wrapper-guard: name the marker every forge API shares, not one dialect's

The scope gate asked for a scheme URL, a `/api/v[0-9]` path, or a provider-CLI `api` subcommand. `/api/v[0-9]` is Gitea's spelling. GitHub's API carries no version segment at all -- `api.github.com/repos/a/b/issues` -- so the schemeless Gitea write was in scope and the schemeless GitHub one was not: curl -X POST -d x api.github.com/repos/a/b/issues rc 0 curl -X POST -d x api.github.com/repos/a/b/issues/1/comments rc 0 host=api.github.com; curl -X POST -d x ${host}/repos/a/b/issues rc 0 A gate calibrated to one provider's spelling rather than to what identifies a provider API. `/repos/` is the marker both dialects share -- every forge API addresses a repository through it -- so the gate now names both. This is SPAN a third time, and the third layer it has appeared on. Round 8: a block message named a wrapper that could not make the call. Round 9: a map claimed a span its wrapper did not cover. Round 10: a control claimed a surface it did not measure. Here the scope gate itself claimed a class of API and recognised one member of it. Same question each time -- does this thing SPAN what it claims -- and it has now been the answer four rounds running, which is the argument for asking it of every arm rather than of the reported one. Widening a scope gate can only make the guard stricter. Downstream a block still requires a body flag AND either a mapped endpoint or an unreadable one, so this widens what is CONSIDERED, not what is refused. The three fixtures asserting that -- a schemeless GitHub read, an unwrapped GitHub endpoint, and a read past `--` -- exist to hold that claim to account rather than state it. Also: the provider-CLI arm's option scanner required a letter after the dashes, so `gh api -X POST -- ${p}${q} -f title=x` walked its endpoint straight past. The end-of-options marker is the one option not spelled like one, and a scanner that skips options had to be told so. Because the new endpoints are READABLE, each blocked fixture asserts the wrapper its message must name. A rc-only fixture here would have passed on the unreadable arm and proved nothing -- which is the failure mode this suite caught in itself last round. Evidence: 110/110 fixtures (was 101) locally and in ci-base. Negative-controlled per change, not in aggregate: dropping `/repos/` from the gate fails exactly the five GitHub fixtures; dropping the `--` alternative fails exactly one; neither disturbs a pre-existing fixture. 18-command sweep unchanged (same three round-6 flips, nothing new); 12-command ordinary-work sweep 0 blocked. shellcheck clean at warning+. CI 2374 on the previous head was green across all nine steps. Residual, stated rather than implied: a caller who splits `/repos/` itself in a schemeless GitHub URL leaves no literal marker anywhere and is out of scope -- the same boundary as splitting the hostname, and no longer a mistake anyone makes by accident. Round 11, addressing rev0 review 154.
wrapper-guard: fail closed on an unreadable endpoint in every shape the scope gate admits
2026-08-12 19:07:44 -05:00 · 2026-08-12 18:53:25 -05:00 · 2026-08-12 18:36:23 -05:00 · 2026-08-12 18:25:13 -05:00 · 2026-08-12 18:10:19 -05:00 · 2026-08-12 17:59:14 -05:00
100 changed files with 7202 additions and 314 deletions
@@ -46,6 +46,21 @@ steps:
      # [0] of the pnpm chain, so severing that chain would silence it together
      # with everything it guards; this direct line keeps one instrument running.
      - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
      # Tool-index gate: a shipped wrapper that appears in no resident index doc
      # is undiscoverable from inside a session, and an agent that cannot learn a
      # wrapper exists reaches for raw curl instead — which is how a Gitea review
      # got filed PENDING three times. Ships-and-documented is one commit, or red.
      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh --self-test
      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh
      # Hermetic regression for issue-close.sh (#1081): mocks tea/curl onto PATH
      # and sandboxes a throwaway git repo, so it resolves no real credentials and
      # joins CI directly rather than the exclusions file.
      - bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh
      # Hermetic behavioural regression for the PreToolUse wrapper guard: proves
      # it still blocks the three mistakes AND still lets reads, unwrapped
      # endpoints and ordinary commands through. Both directions are asserted —
      # a guard that over-blocks gets routed around, which fails just as hard.
      - bash packages/mosaic/framework/tools/git/test-wrapper-guard.sh
  # Blocking gate (#791): a framework upgrade must never write or delete an
  # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
@@ -60,6 +60,14 @@ The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md
 Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
 Mosaic also loads its Pi extensions from `~/.config/mosaic/runtime/pi/`. Inside Pi,
 `/goal set <statement>` starts a bounded persistent loop that checks every turn and successful
 compaction, requires two evidence-bearing completion reports, and can be inspected or stopped with
 `/goal status`, `/goal pause`, `/goal resume`, and `/goal cancel`. Controller-owned goal-state
 entries redact common credential shapes, but Pi's model/tool-call history is separate, so goals and
 evidence must never contain secrets or raw sensitive output. Mosaic does not install this extension
 into `~/.pi/agent/extensions/`.
 ### TUI & Gateway
 ```bash
@@ -245,9 +245,21 @@ describe('EnrollmentService.createToken', () => {
    const after = Date.now();
    const expiresMs = new Date(result.expiresAt).getTime();
-    // Should be at most 900s from now
+
-    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);
+    // The property under test is CLAMPING: a 9999s request must come back as 900s.
    // The gap between clamped and unclamped is 9_099_000 ms, so the tolerance below
    // only has to exceed CI scheduling jitter — it does not need to be tight to keep
    // the assertion discriminating. A 5s allowance consumes 0.05% of that margin and
    // an unclamped result still misses by three orders of magnitude.
    //
    // It was 100ms and failed on a loaded agent at 900_106 — 6ms over (#1090). A
    // wall-clock budget sized to a fast machine is a flake, not a tighter test.
    const CI_JITTER_MS = 5_000;
    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + CI_JITTER_MS);
    expect(expiresMs - after).toBeGreaterThanOrEqual(0);
    // Explicitly pin the clamp itself, independent of any timing allowance:
    // unclamped (9999s) would exceed this by ~9_099_000 ms.
    expect(expiresMs - before).toBeLessThan(1_000_000);
  });
 });
@@ -102,6 +102,128 @@ Context compaction, session replacement, and same-PID runtime reloads can leave
 ---
 ## Pi Persistent Goal Loop (#1150)
 ### Problem and objective
 A Pi agent can stop after a plausible-looking answer even when the operator's broader objective is
 not complete, and ordinary compaction can weaken or omit the original objective. Mosaic needs an
 optional, operator-controlled goal loop that keeps a Pi session oriented, checks progress at native
 lifecycle boundaries, and resumes work until completion is verified or a bounded safety state is
 reached.
 The objective is a Mosaic-owned Pi extension deployed from the framework into
 `~/.config/mosaic/runtime/pi/`. It must not install into or depend on `~/.pi/agent/extensions/`.
 ### Scope
 #### In scope
 1. `PGL-REQ-01`: The framework SHALL ship a dedicated Pi goal extension under
   `packages/mosaic/framework/runtime/pi/`, seed it under `$MOSAIC_HOME/runtime/pi/`, and make
   `mosaic pi` load it alongside the core Mosaic extension when present.
 2. `PGL-REQ-02`: `/goal` SHALL support setting a goal plus status, pause, resume, cancel, and help
   operations without silently replacing an active goal.
 3. `PGL-REQ-03`: Active branch-specific goal state SHALL be persisted in Pi custom session entries,
   restored on session start and tree navigation, and never rely on a compaction summary as its
   source of truth.
 4. `PGL-REQ-04`: A hidden goal contract SHALL be injected through Pi's `context` event before every
   model request so it remains effective across tool turns, retries, and post-compaction requests.
 5. `PGL-REQ-05`: The harness SHALL inspect every `turn_end` and successful `session_compact` event.
   A structured terminating goal-report tool SHALL capture `continue`, evidence-bearing `achieved`,
   or `blocked` status without requiring a redundant model turn.
 6. `PGL-REQ-06`: An achievement claim SHALL remain provisional until a second consecutive
   evidence-bearing verification report. Any continuation report or successful compaction during
   verification SHALL reset the verification sequence.
 7. `PGL-REQ-07`: Continuation SHALL be initiated at safe lifecycle boundaries, primarily
   `agent_settled`; manual compaction and restored active sessions may schedule a deferred idle
   continuation without re-entering compaction handlers.
 8. `PGL-REQ-08`: The loop SHALL have operator cancellation plus bounded turn and repeated-no-progress
   limits. Exhausted or blocked goals pause rather than continuing indefinitely.
 9. `PGL-REQ-09`: Framework installation and update SHALL preserve normal manifest ownership: the
   goal extension is framework-owned under `runtime/**`, while no goal extension or configuration
   asset is created or modified under the operator's main Pi configuration. Pi remains the owner of
   its native session files used by `appendEntry()`.
 #### Out of scope
 1. A mathematical guarantee that an arbitrary natural-language goal is semantically complete.
 2. Automatically executing user-supplied shell predicates or accepting executable validation code in
   `/goal` arguments.
 3. Restarting Pi after process, host, or supervisor failure; the existing Mosaic fleet/runtime
   supervisor owns process durability.
 4. Gateway, database, web UI, Discord, or cross-harness goal orchestration in this slice.
 ### User and stakeholder requirements
 - An operator can start a goal from Pi and see its current phase, evidence, limits, and latest report.
 - The agent remains oriented after each turn and compaction until verified, paused, blocked,
  exhausted, or cancelled.
 - Local testing uses a file under `~/.config/mosaic/runtime/pi/`; the feature never writes an
  extension asset to `~/.pi/agent/extensions/`.
 - Framework updates deploy the same reviewed extension source through Mosaic's existing manifest
  sync path.
 ### Non-functional requirements
 1. **Safety:** bounded continuation, explicit cancellation, no arbitrary command execution, and no
   completion without non-empty reported evidence.
 2. **Reliability:** serialized continuation scheduling, branch-aware restoration, compaction-safe
   context injection, and stale-timer cancellation on session shutdown.
 3. **Performance:** no extra nested judge-model request on every turn; structured reporting uses the
   active agent's final terminating tool call.
 4. **Observability:** Pi status/notifications expose phase and bounded counters without recording
   credentials or hidden model reasoning.
 5. **Maintainability:** the state machine is deterministic and behavior-tested independently from Pi
   provider/network access.
 ### Acceptance criteria
 1. `AC-PGL-01`: A framework-sync fixture installs the extension at
   `$MOSAIC_HOME/runtime/pi/goal-extension.ts`, and launcher tests prove both Mosaic Pi extensions are
   emitted in deterministic order while absent optional files remain backward-compatible.
 2. `AC-PGL-02`: Command tests prove set/status/pause/resume/cancel behavior, active-goal replacement
   refusal, and bounded input handling.
 3. `AC-PGL-03`: Lifecycle tests prove every turn is recorded, active context is injected on every
   request, two evidence-bearing achievement reports are required, and `agent_settled` continues an
   unmet goal without duplicate scheduling.
 4. `AC-PGL-04`: Compaction and restoration tests prove goal state survives, verification is reset and
   rechecked after compaction, manual compaction continuation is deferred until idle, and tree/session
   branch state is reconstructed correctly.
 5. `AC-PGL-05`: Limit tests prove max-turn and repeated-no-progress exhaustion stop autonomous
   continuation, while pause/cancel/blocked states do not restart.
 6. `AC-PGL-06`: Focused tests, package typecheck/lint/test, repository quality gates, a local Pi load
   smoke test from `~/.config/mosaic/runtime/pi/`, independent review, and terminal-green CI pass before
   issue #1150 closes.
 ### Constraints, risks, and assumptions
 - Dependency: Pi's extension API must continue to provide `registerCommand`, `registerTool`,
  `context`, `turn_end`, `agent_settled`, `session_compact`, session custom entries, and terminating
  tool results.
 - Risk: the working agent can overstate completion. Mitigation: structured evidence, a mandatory
  second verification pass, explicit semantic limitations, and operator-visible reports.
 - Risk: an impossible goal can consume unbounded resources. Mitigation: hard turn/no-progress bounds
  and paused terminal states.
 - Risk: automatic continuation can race compaction or session replacement. Mitigation: drive from
  `agent_settled`, defer idle restarts, generation-check timers, and clear timers on shutdown.
 - `ASSUMPTION:` Two consecutive evidence-bearing reports are the initial local verification policy;
  rationale: it provides a real recheck without doubling every turn's model cost. Future policy may
  add independent or deterministic validators.
 - `ASSUMPTION:` Default limits are 40 turns and 6 repeated no-progress reports, configurable only by
  bounded Mosaic environment settings; rationale: useful persistence with a finite autonomous budget.
 - `ASSUMPTION:` Documentation remains canonical in-repo for this slice; no external docs publication
  is requested.
 ### Testing and delivery intent
 Use TDD for the deterministic controller and lifecycle invariants. Test with fake Pi lifecycle
 objects first, then run a local load/smoke test from the deployed Mosaic path. Deliver source, tests,
 launcher wiring, framework/runtime documentation, user/developer guides, and sitemap updates in one
 reviewed squash PR to `main` with terminal-green CI.
 ---
 ## Fleet Declarative Configuration Management Workstream (FCM, #758)
 ### Problem and objective
@@ -146,6 +268,68 @@ lands. M0 consists only of these normative requirements, the complete task DAG,
 documentation IA checklist, and the legacy example/profile disposition inventory. Subsequent cards
 are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 ### Fleet git identity launch propagation (#1043)
 #### Problem and objective
 A fleet seat can have a registered per-agent Git credential while its launched runtime process lacks
 `MOSAIC_GIT_IDENTITY`. The credential resolver then cannot select the seat identity reliably, which
 blocks repository operations on fail-closed estates and can fall through to an unrelated identity on
 estates where that refusal is not active. The objective is to make Git identity a deterministic,
 roster-derived part of the generated launch projection and prove it reaches the launched process.
 #### Normative requirements
 1. `FGI-REQ-01`: Every generated fleet agent projection SHALL declare
   `MOSAIC_GIT_IDENTITY=<MOSAIC_AGENT_NAME>`; a differing or unsafe identity SHALL fail closed before
   tmux launch.
 2. `FGI-REQ-02`: The clean `/usr/bin/env -i` pane boundary SHALL pass every variable declared by the
   generated projection, including `MOSAIC_GIT_IDENTITY`, to the launched runtime process.
 3. `FGI-REQ-03`: A behavioral integration test SHALL set-compare the complete generated projection
   against the launched process environment. Source-text/string-presence assertions are insufficient.
 4. `FGI-REQ-04`: Verification SHALL include RED-first evidence and a delete-the-subject mutation that
   removes Git-identity pane propagation and makes the behavioral test fail.
 #### Acceptance criteria
 1. `AC-FGI-01`: A launched seat process contains every key/value pair declared by its generated
   environment projection, including the roster-derived Git identity.
 2. `AC-FGI-02`: Missing, unsafe, or split Git identity is rejected before a tmux session is created.
 3. `AC-FGI-03`: Focused launcher and generated-environment tests, repository quality gates,
   independent review, and the required RED/green/R7 evidence are recorded before push.
 ### Framework shell assertion portability (#1098)
 #### Problem and objective
 The blocking framework-shell chain can report that a pane command omitted `/usr/bin/env -i` even when
 `-i` matched successfully. A short-circuiting `grep -q` under `set -o pipefail` may close its pipe after
 the match and cause an upstream producer to exit with SIGPIPE, turning a valid semantic result into a
 nonzero aggregate pipeline. The objective is to inspect the captured NUL-delimited argv directly and
 make failures carry the observed records needed for diagnosis.
 #### Normative requirements
 1. `FSP-REQ-01`: The pane-boundary test SHALL validate an adjacent `/usr/bin/env`, `-i` argv pair from
   the authoritative NUL-delimited tmux capture without a short-circuit pipeline whose upstream status
   can override a successful match.
 2. `FSP-REQ-02`: Missing, reversed, or non-adjacent boundary tokens SHALL fail, while valid boundaries
   SHALL remain valid regardless of trailing argv size, pipe capacity, process scheduling, or host/CI
   utility implementation.
 3. `FSP-REQ-03`: A failed boundary check SHALL print stable indexed, shell-escaped observed argv records
   before exiting nonzero; the fixture SHALL continue to contain generated non-secret launch data only.
 4. `FSP-REQ-04`: Verification SHALL include RED-first large-payload evidence, negative token-order
   controls, the complete focused launcher suite, canonical Woodpecker CI, and independent review.
 #### Acceptance criteria
 1. `AC-FSP-01`: A large captured argv with adjacent `/usr/bin/env`, `-i` passes even when the former
   `grep -q` pipeline returns nonzero from an upstream SIGPIPE.
 2. `AC-FSP-02`: Missing executable, missing flag, and detached/reversed flag fixtures return nonzero and
   emit the indexed observed argv.
 3. `AC-FSP-03`: The focused suite passes on the development host and CI image, and the merged-main
   Woodpecker pipeline is terminal green before #1098 closes.
 ---
 ## Exact Cross-Harness Fleet Communications Contract (#766)
@@ -14,6 +14,13 @@
 - [Skill registration user guide](guides/user-guide.md#claude-code-skill-registration) — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
 - [Skill bridge developer guide](guides/dev-guide.md#claude-code-skill-bridge) — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.
 ## Pi persistent goals
 - [Persistent goal user guide](guides/user-guide.md#pi-persistent-goals) — `/goal` commands, verification behavior, limits, compaction/resume semantics, and limitations.
 - [Goal extension developer guide](guides/dev-guide.md#pi-persistent-goal-extension) — framework ownership, launcher ordering, lifecycle design, tests, and local Mosaic-path smoke workflow.
 - [Goal loop operations](guides/admin-guide.md#pi-goal-loop-operations) — deployment ownership, bounded settings, pause/resume procedures, and supervisor boundary.
 - [Pi runtime reference](../packages/mosaic/framework/runtime/pi/RUNTIME.md#extensions) — deployed paths, command summary, and bounded environment settings.
 ## Fleet configuration management
 - [Fleet configuration entry point](fleet/README.md) — desired-versus-observed decision tree and complete operator link map.
@@ -5,14 +5,14 @@ Generated environment files are rebuildable projections, not an operator-editabl
 ## Launch chain
-| Layer               | Responsibility                                                                                                                  |
+| Layer               | Responsibility                                                                                                                                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket. |
+| Roster              | `fleet/roster.yaml` supplies the agent name, class, supported runtime, model, reasoning, tool policy, workdir, and tmux socket; Git identity is derived from the exact agent name. |
-| Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                        |
+| Projection writer   | Renders deterministic fleet/agents/<name>.env.generated from the roster.                                                                                                           |
-| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                       |
+| Optional local data | Reads a strict, data-only fleet/agents/<name>.env.local; it cannot shadow generated keys.                                                                                          |
-| systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                          |
+| systemd             | Starts the launcher with env -i and fixed bootstrap data. It does not preload either environment file.                                                                             |
-| session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                  |
+| session launcher    | Validates generated and local data before it queries, creates, or stops an exact tmux session.                                                                                     |
-| runtime launch      | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract.             |
+| runtime launch      | Derives the fixed mosaic yolo <runtime> argument array from validated roster data, then seeds the runtime contract.                                                                |
 The launcher never `source`s or `eval`s an environment file and never accepts an environment-supplied
 command. `MOSAIC_AGENT_COMMAND`, command/channel overrides, unknown keys, generated-key shadowing,
@@ -24,6 +24,7 @@ secret-like key names, duplicate keys, comments, quoted/export syntax, and unsaf
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
 MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -33,8 +34,10 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
-The generated launch contract supports `claude`, `codex`, `opencode`, and `pi`. mosaic fleet add
+`MOSAIC_GIT_IDENTITY` is not independently configurable: it must equal `MOSAIC_AGENT_NAME`, preventing
-rejects another runtime before it writes the roster or modifies generated, local, or quarantine state.
+split runtime and repository identity authority. The generated launch contract supports `claude`,
 `codex`, `opencode`, and `pi`. mosaic fleet add rejects another runtime before it writes the roster or
 modifies generated, local, or quarantine state.
 The legacy dogfood stub remains an observability-only canary on its separate `mosaic-factory` socket;
 it has no generated-launch adapter and cannot be added through this path.
@@ -3,11 +3,12 @@
 The launcher consumes validated data, not shell configuration.
 1. Read and validate the canonical roster.
-2. Render deterministic <name>.env.generated data from that roster.
+2. Render deterministic <name>.env.generated data from that roster, including `MOSAIC_GIT_IDENTITY` derived exactly from the roster agent name.
 3. Parse optional <name>.env.local through a strict allowlist.
 4. Reject generated-key shadowing, unknown or sensitive-looking keys, unsafe paths/values, duplicates, malformed lines, shell syntax, and command overrides.
-5. Derive the runtime command from validated runtime/model/reasoning data.
+5. Reject a Git identity that is unsafe or differs from the generated agent name.
-6. Target only the exact configured tmux socket and roster session after ownership checks.
+6. Derive the runtime command from validated runtime/model/reasoning data and pass every generated projection entry through the clean process environment boundary.
 7. Target only the exact configured tmux socket and roster session after ownership checks.
 ## File precedence and ownership
@@ -35,6 +35,7 @@ values, credential material, or command text.
 ```dotenv
 MOSAIC_AGENT_NAME=<roster name>
 MOSAIC_GIT_IDENTITY=<roster name>
 MOSAIC_AGENT_CLASS=<roster class>
 MOSAIC_AGENT_RUNTIME=<roster runtime>
 MOSAIC_AGENT_MODEL=<roster model hint>
@@ -44,8 +45,9 @@ MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
 MOSAIC_TMUX_SOCKET=<roster socket or empty>
 ```
-The generated launch contract supports only `claude`, `codex`, `opencode`, and `pi`. fleet add
+`MOSAIC_GIT_IDENTITY` is derived from and must equal `MOSAIC_AGENT_NAME`; it is not a separate
-uses that same runtime authority and rejects any other runtime before it writes the roster or changes
+operator-controlled identity authority. The generated launch contract supports only `claude`, `codex`,
 `opencode`, and `pi`. fleet add uses that same runtime authority and rejects any other runtime before it writes the roster or changes
 projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
 socket remains an observability canary; it has no generated-launch adapter and cannot be added through
 this projection path.
@@ -7,7 +7,8 @@
 3. [Provider Configuration](#provider-configuration)
 4. [MCP Server Configuration](#mcp-server-configuration)
 5. [Environment Variables Reference](#environment-variables-reference)
-6. [Local Fleet Canary](./fleet-local-canary.md)
+6. [Pi Goal Loop Operations](#pi-goal-loop-operations)
 7. [Local Fleet Canary](./fleet-local-canary.md)
 ---
@@ -264,6 +265,16 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
 | `AGENT_SYSTEM_PROMPT`    | —               | Platform-level system prompt injected into all sessions |
 | `AGENT_USER_TOOLS`       | all tools       | Comma-separated allowlist of tools for non-admin users  |
 ### Mosaic Pi goal loop
 | Variable                      | Default | Description                                                          |
 | ----------------------------- | ------- | -------------------------------------------------------------------- |
 | `MOSAIC_GOAL_MAX_TURNS`       | `40`    | Per-goal autonomous turn limit; accepted range `1..500`              |
 | `MOSAIC_GOAL_MAX_NO_PROGRESS` | `6`     | Consecutive identical progress-report limit; accepted range `1..100` |
 These variables are consumed by the framework-owned Pi goal extension at goal creation. Invalid or
 out-of-range values fall back to the defaults; they do not disable the bounds.
 ### Providers
 | Variable                  | Default                      | Description                                      |
@@ -374,3 +385,29 @@ Session cleanup is scoped to one session identifier and only removes that sessio
 | Variable                | Default                       | Description                                |
 | ----------------------- | ----------------------------- | ------------------------------------------ |
 | `MOSAIC_WORKSPACE_ROOT` | monorepo root (auto-detected) | Root path for mission workspace operations |
 ---
 ## Pi Goal Loop Operations
 The reviewed runtime asset is deployed at
 `~/.config/mosaic/runtime/pi/goal-extension.ts` by framework install/update. Do not install another
 copy under `~/.pi/agent/extensions/`; duplicate registration can create suffixed commands and two
 competing lifecycle controllers.
 Operational checks:
 1. Run `mosaic pi` and verify `/goal help` is available.
 2. Use `/goal status` to inspect phase, turn/no-progress limits, compaction checks, and evidence.
   Reports persist in Pi session data; controller-owned state redacts common credential shapes, but
   Pi's model/tool-call history is separate. Operators must not place secrets or raw sensitive output
   in goals, pause reasons, or evidence.
 3. Use `/goal pause <reason>` before planned maintenance or manual investigation. Pause and cancel
   abort the current goal-driven run when Pi is busy.
 4. Use `/goal resume` only after addressing a blocker; counters restart with the configured bounds.
 5. Use `/goal cancel` before replacing an unfinished goal.
 A blocked or exhausted goal remains stopped and visible; Mosaic does not automatically raise its
 limits or restart the process. Framework sync owns file deployment, while Pi's native session file
 owns branch replay. Process/host restart remains the responsibility of the existing runtime or fleet
 supervisor.
@@ -9,8 +9,9 @@
 5. [Adding New MCP Tools](#adding-new-mcp-tools)
 6. [Database Schema and Migrations](#database-schema-and-migrations)
 7. [Claude Code Skill Bridge](#claude-code-skill-bridge)
-8. [API Endpoint Reference](#api-endpoint-reference)
+8. [Pi Persistent Goal Extension](#pi-persistent-goal-extension)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+9. [API Endpoint Reference](#api-endpoint-reference)
 10. [Local Fleet Canary](./fleet-local-canary.md)
 ---
@@ -385,6 +386,85 @@ M1 intentionally manages Claude Code only. Pi's Mosaic launcher can discover the
 canonical root directly. Codex still relies on the existing full skill-sync
 linker and needs separate parity analysis before this lifecycle API is extended.
 ## Pi Persistent Goal Extension
 The source of the Mosaic-owned Pi goal controller is:
 ```text
 packages/mosaic/framework/runtime/pi/goal-extension.ts
 ```
 The framework manifest classifies `runtime/**` as framework-owned. Both the bash installer and the
 TypeScript file adapter therefore deploy the same reviewed source to:
 ```text
 $MOSAIC_HOME/runtime/pi/goal-extension.ts
 # default: ~/.config/mosaic/runtime/pi/goal-extension.ts
 ```
 Do not copy or link this extension into `~/.pi/agent/extensions/`. The launcher function
 `discoverPiExtensionArgs()` emits the core `mosaic-extension.ts` first and the optional
 `goal-extension.ts` second, preserving compatibility with an older installed framework that does
 not have the goal file yet.
 ### Lifecycle design
 | Pi API                         | Goal-controller responsibility                                                    |
 | ------------------------------ | --------------------------------------------------------------------------------- |
 | `registerCommand('goal')`      | Set, inspect, pause, resume, or cancel one branch-specific goal                   |
 | `registerTool(...)`            | Record a terminating structured progress report with evidence                     |
 | `context`                      | Inject the active goal contract before every provider request                     |
 | `turn_end`                     | Record every turn, reject mixed final reports, and enforce the turn bound         |
 | `agent_settled`                | Start one deduplicated continuation only after Pi has no retry/compact/queue work |
 | `session_compact`              | Record the compact check, reset provisional verification, and defer idle work     |
 | `session_start`/`session_tree` | Rebuild state from custom entries on the active branch                            |
 | `session_shutdown`             | Invalidate deferred callbacks and clear UI state                                  |
 State is appended as `mosaic-goal-state` custom entries, which do not enter model context. The
 `context` hook creates a fresh hidden `mosaic-goal-context` message for each request instead of
 trusting compaction summaries. The `mosaic_goal_report` result uses `terminate: true`; when it is the
 sole final tool call, Pi avoids an unnecessary model response before the controller decides whether
 to verify, continue, or stop.
 Before state is appended or displayed, the controller applies bounded credential-pattern redaction
 to the goal statement, report summary/evidence/next step, and stop reason. Fingerprints are computed
 over redacted report content. Pi session entries are append-only, so a credential-bearing legacy
 entry cannot honestly be erased by the extension: restoration fails closed, emits a warning, and
 requires removal of the affected session before setting a new goal. This is defense-in-depth rather
 than a secret-storage contract, and it does not rewrite Pi's separate model-message/tool-call
 history. Goal prompts tell the agent not to submit credentials or raw sensitive output, and tests use
 canaries to prove known forms do not reach new custom entries, status text, context, or tool details
 while ordinary typed fields such as `token: string` remain intact.
 Completion remains evidence-gated but semantic: two consecutive `achieved` reports are required,
 and the second run is explicitly a verification pass. This avoids an extra judge-model request after
 every turn. Deterministic validator commands are intentionally not accepted as `/goal` input in this
 slice, so never describe this mechanism as proof of arbitrary natural-language completion.
 ### Tests and local smoke workflow
 ```bash
 pnpm --filter @mosaicstack/mosaic exec vitest run \
  src/runtime/pi-goal-extension.spec.ts \
  src/commands/launch.spec.ts \
  src/config/file-adapter.test.ts
 bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
 ```
 For an additive local smoke test without reseeding unrelated live framework files:
 ```bash
 install -D -m 0644 \
  packages/mosaic/framework/runtime/pi/goal-extension.ts \
  ~/.config/mosaic/runtime/pi/goal-extension.ts
 pi --extension ~/.config/mosaic/runtime/pi/goal-extension.ts
 ```
 Use `/goal help`, `/goal set ...`, and `/goal status` in that test session. A released framework
 sync installs the file, and a released Mosaic CLI loads it automatically through `mosaic pi`.
 ## API Endpoint Reference
 All endpoints are served by the gateway at `http://localhost:14242` by default.
@@ -8,9 +8,10 @@
 4. [Tasks](#tasks)
 5. [Settings](#settings)
 6. [CLI Usage](#cli-usage)
-7. [Sub-package Commands](#sub-package-commands)
+7. [Pi Persistent Goals](#pi-persistent-goals)
-8. [Telemetry](#telemetry)
+8. [Sub-package Commands](#sub-package-commands)
-9. [Local Fleet Canary](./fleet-local-canary.md)
+9. [Telemetry](#telemetry)
 10. [Local Fleet Canary](./fleet-local-canary.md)
 ---
@@ -307,6 +308,57 @@ mosaic prdy
 mosaic quality-rails
 ```
 ## Pi Persistent Goals
 `mosaic pi` loads a Mosaic-owned goal extension from
 `~/.config/mosaic/runtime/pi/goal-extension.ts`. It is deliberately not installed in
 `~/.pi/agent/extensions/`; framework installation and updates manage it with the rest of the Mosaic
 runtime assets.
 Start Pi, then set a goal:
 ```text
 /goal set Deliver the feature, tests, documentation, and verification evidence
 # Shorthand:
 /goal Deliver the feature, tests, documentation, and verification evidence
 ```
 Control and inspect the loop with:
 | Command                | Behavior                                                           |
 | ---------------------- | ------------------------------------------------------------------ |
 | `/goal status`         | Show phase, limits, compaction checks, latest report, and evidence |
 | `/goal pause [reason]` | Stop autonomous continuation while preserving the goal             |
 | `/goal resume`         | Resume with fresh turn and no-progress counters                    |
 | `/goal cancel`         | Cancel the goal and remove its active status                       |
 | `/goal help`           | Show command help                                                  |
 While a goal is active, Mosaic injects its contract before every Pi model request and checks every
 completed model/tool turn. The agent ends each work cycle with the structured
 `mosaic_goal_report` tool. `achieved` is provisional until a second consecutive report rechecks the
 whole goal with evidence. A continuation report or a successful compaction resets provisional
 verification.
 Goal statements and reports are stored in Pi session data. Mosaic redacts common credential shapes
 before appending its goal-state entries and before goal tool output or `/goal status`, but
 pattern-based redaction is not a secret store. Pi's own model-message and tool-call records are
 outside that redactor. Never put tokens, passwords, private keys, connection strings, or raw
 sensitive output in a goal or report; cite the command, artifact, and pass/fail result instead.
 The loop stops instead of running forever when it is paused, blocked, cancelled, verified, reaches
 its turn limit, or repeats the same no-progress report too many times. Defaults are 40 turns and 6
 repeated no-progress reports. Operators may lower or raise them within enforced bounds before
 launching Pi:
 ```bash
 MOSAIC_GOAL_MAX_TURNS=60 MOSAIC_GOAL_MAX_NO_PROGRESS=8 mosaic pi
 ```
 Goal state is branch-specific Pi session data. It survives compaction and session resume, but Pi's
 process still must be relaunched or supervised after a process/host failure. This initial verifier
 checks structured evidence twice; it cannot mathematically prove every arbitrary natural-language
 goal. Use explicit acceptance criteria and inspect `/goal status` for consequential work.
 ---
 ### Claude Code Skill Registration
@@ -0,0 +1,83 @@
 # #1099 pipefail + early-exit sweep
 Baseline: `df4c591ab42aa1ae62c12935fdc0e772684864a0`
 This is a site inventory, not a risk count. `FIXED` means the early-exiting consumer no longer has a piped upstream process whose SIGPIPE can become the result under `pipefail`. `NOT-LOAD-BEARING` means the pipeline status is explicitly discarded. `UNREACHABLE-AND-WHY` describes designed input, not a payload-size safety claim.
 ## Tranche 1 — runtime and general scripts
 | Baseline site | Verdict | Construction / reason |
 | --- | --- | --- |
 | `tools/matrix-presence-harness/run.sh:38` | FIXED | nullglob array selects the first path; no pipeline |
 | `tools/e2e-install-test.sh:139` | FIXED | capture help completely, then grep via redirection |
 | `tools/install.sh:312` | FIXED | NUL `mapfile` reads all roots; count != 1 reaches the named malformed-archive diagnostic |
 | `scripts/analysis/reflect-board-history.sh:76` | FIXED | capture Git history completely, then grep via redirection |
 | `scripts/analysis/reflect-git-history.sh:67` | FIXED | grep reads from a here-string |
 | `scripts/analysis/reflect-git-history.sh:69` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/authentik/user-create.sh:72` | FIXED | jq `first(...)` reads the response directly |
 | `packages/mosaic/framework/tools/git/mutate-push-guard.sh:87` | FIXED | grep `-m1` reads the file directly; downstream `cut` consumes its complete scalar output |
 | `packages/mosaic/framework/tools/orchestrator/session-resume.sh:94` | FIXED | `mapfile` plus bounded indexed loop replaces `head` pipeline |
 | `packages/mosaic/framework/tools/prdy/prdy-status.sh:69` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:172` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:173` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:174` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:175` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:176` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:177` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:178` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/qa/typecheck-hook.sh:16` | FIXED | Bash regex extracts the first field without a pipeline |
 | `packages/mosaic/framework/tools/qa/typecheck-hook.sh:56` | FIXED | grep and bounded sed each read from a here-string |
 | `packages/mosaic/framework/tools/tmux/send-message.sh:113` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/tmux/send-message.sh:124` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/wake/detector.sh:126` | FIXED | one awk reads the manifest directly and exits after the first exact key |
 | `packages/mosaic/framework/tools/wake/detector.sh:270` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/wake/detector.sh:278` | FIXED | grep reads from a here-string |
 | `packages/mosaic/framework/tools/wake/digest.sh:647` | FIXED | capture complete locator output, then select first line by parameter expansion |
 | `packages/mosaic/framework/tools/wake/reconcile.sh:149` | FIXED | one awk reads the manifest directly and exits after the first exact key |
 ## Explicit withdrawn / non-load-bearing sites
 | Baseline site | Verdict | Reason |
 | --- | --- | --- |
 | `tools/install.sh:182` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
 | `tools/install.sh:356` | UNREACHABLE-AND-WHY | `pnpm pack` writes one matching CLI tarball into a fresh directory immediately before lookup; citation withdrawn in #1099 |
 | `tools/install.sh:357` | UNREACHABLE-AND-WHY | same fresh-directory invariant for gateway tarball; citation withdrawn in #1099 |
 | `tools/install.sh:627` | NOT-LOAD-BEARING | `|| true` explicitly discards lookup status |
 | `scripts/agent/session-start.sh:70` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
 | `packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh:58` | NOT-LOAD-BEARING | optional scratchpad lookup has `|| true` |
 | `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:25` | UNREACHABLE-AND-WHY | withdrawn in #1099 after designed-input reachability measurement; preserved without re-litigation |
 | `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:27` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
 | `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:30` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
 | `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:32` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
 | `packages/mosaic/framework/tools/qa/qa-hook-stdin.sh:34` | UNREACHABLE-AND-WHY | same withdrawn designed-input finding |
 ## Tranche 2 — non-wake test harnesses
 All 22 baseline sites below are `FIXED`; the checked-in tranche fixture is passed through the same scanner and asserts all 22 occurrences and 21 normalized identities (the same response-split line occurs twice).
 | Baseline site(s) | Verdict | Construction |
 | --- | --- | --- |
 | `systemd/user/test-fleet-units.sh:148` | FIXED | capture tmux output, then grep via redirection |
 | `git/test-issue-comment-readback.sh:283,302` | FIXED | parameter expansion splits status/body without `head` |
 | `git/test-pr-review-gitea-comment.sh:228` | FIXED | parameter expansion splits status/body |
 | `git/test-lane-brief-pr-linkage.sh:72` | FIXED | grep reads from a here-string |
 | `git/test-pr-review-repo-host-override.sh:225-226` | FIXED | grep reads from a here-string |
 | `orchestrator/smoke-test.sh:67,72` | FIXED | parameter expansion selects first line |
 | `orchestrator/test-board-roll.sh:99-100` | FIXED | grep reads from a here-string |
 | `quality/scripts/test-upgrade-durable-snapshot.sh:180` | FIXED | complete sorted output is read with `mapfile`, then indexed |
 | `quality/scripts/test-upgrade-rollback.sh:339,356` | FIXED | direct `grep -m1` file reads; cleanup captures before testing |
 | `tmux/test-send-message-socket.sh:37,38,44-46,68,72` | FIXED | capture commands complete before redirected grep assertions |
 | `tmux/test-send-message-verdict.sh:34` | FIXED | grep reads from a here-string |
 ## Tranche 3 — wake validation harnesses
 All 26 baseline occurrences (25 normalized identities; one preimage selector occurs twice) are `FIXED` and mechanically bound through the wake fixture and shared scanner.
 | Baseline site(s) | Verdict | Construction |
 | --- | --- | --- |
 | `wake/test-wake-digest-quarantine.sh:567` | FIXED | complete match populations are captured, then first line selected by parameter expansion |
 | `wake/test-wake-preimage.sh:182-183,346-347` | FIXED | jq `first(...)` reads each JSONL file directly |
 | `wake/validate-973/microtest-wake-assert.sh:153,170-171,176,204-209,233-234,251-252,286-287` | FIXED | scalar assertions use here-strings; diagnostics use non-early sed ranges; source line captured before matching |
 | `wake/validate-973/validate-973.sh:110,119,180,182,187` | FIXED | scalar assertions use here-strings; diagnostic truncation uses consuming sed ranges |
 The scoped inventory is complete: 26 runtime/general + 22 non-wake tests + 26 wake tests fixed; 11 explicitly withdrawn or non-load-bearing sites retain their documented verdicts.
@@ -0,0 +1,71 @@
 # #1019 — Zero-timeout queue-guard harness race
 - **Issue:** #1019 (parent status remains `believed-fixed, pending jarvis validation`; do not close)
 - **Branch:** `fix/1019-ci-queue-timeout-harness`
 - **Owner:** `be-coder-08`
 - **Base:** `origin/main` at `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`
 - **Charter:** `/home/hermes/agent-work/tl-mosaic/CHARTER-1019-HARNESS-FIX.md`
 ## Objective
 Make `test-ci-queue-wait-tristate.sh` deterministic without changing any asserted outcome. Remove the indiscriminate zero-timeout race, require every status-classification case to prove the provider was observed, and prove the harness-controlled virtual clock is active.
 ## Scope
 - In scope: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` only, plus this evidence scratchpad.
 - Out of scope: guard parsers, D2/D3 behavior, installer/reseed staleness, PR #1060, and issue closure.
 ## Acceptance criteria
 1. RED deterministically reproduces deadline pre-emption before the provider call.
 2. Every case that intends status classification positively proves provider observation.
 3. Pending observes `pending` before deterministic virtual-time expiration.
 4. The virtual clock has a positive interception control; a broken-clock mutant makes the suite red.
 5. The exact CI-base image passes the final harness repeatedly with zero failures.
 6. Baseline gates, independent code/security review, exact-head CI, and coordinator-authorized squash merge pass.
 ## Plan
 1. Add deterministic RED instrumentation for the known merge/provider-unreachable pre-emption.
 2. Replace global `-t 0` with a nonzero timeout interpreted under an event-driven virtual clock; stub sleep without wall waiting.
 3. Add provider-observation and virtual-clock positive controls without changing outcome assertions.
 4. Run focused shell checks, repeat in exact CI-base image, baseline gates, and independent reviews.
 5. Commit with both identity layers, queue-guard plus direct Woodpecker terminal-state verification, push, self-post PR, verify poster/head/CI, obtain coordinator merge authorization, then squash merge without closing #1019.
 ## Budget
 - No explicit token cap supplied. Keep scope to one harness file and one scratchpad; stop/report at the charter's 60% context gate.
 ## Evidence
 - RED, deterministic pre-provider expiry: `evidence/1019-harness-fix/red-pre-provider-expiry.log` — rc 1; merge/provider-unreachable got rc 124 instead of 75, omitted CANNOT_ASSERT, did not observe the status provider, and wrote no additional audit record (four named failures).
 - GREEN host focused harness: `evidence/1019-harness-fix/green-host.log` — rc 0, all outcome classes passed.
 - Load-bearing clock negative control: a temporary same-directory mutant replaced the virtual `date` body with `/bin/date`; `evidence/1019-harness-fix/red-clock-not-intercepted.log` — rc 1 with named `virtual clock interception did not run` failures. The mutant file was removed after the run.
 - Exact CI-base repeat: `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`, repository mounted read-only, harness work under container `/tmp`; `evidence/1019-harness-fix/ci-image-repeat/summary.log` — **100 pass / 0 fail / 100 total**.
 - Synchronization design: provider-status observation creates the event marker; virtual time is 1000 before the event and 1002 afterward. Pending alone reaches the stubbed no-op sleep and a post-observation deadline check. `-t 1` is uniquely load-bearing because removing it restores the 900-second default deadline at virtual time 1900, which 1002 does not cross. The numeric timeout is subject semantics under virtual time, not a wall-clock synchronization duration.
 ## Review remediation — semantic timeout vs. liveness bound
 Security review found that virtual time remained at 1000 forever before provider observation and stubbed sleep never waited. A regression looping before the status endpoint—or blocking in the first provider call—therefore could prevent `run_guard` from returning, so the post-return provider assertion could never fire.
 **General rule:** A timeout usually serves two purposes: semantics and liveness. Removing wall time from semantic synchronization can silently remove the only independent hang bound. Preserve deterministic virtual time for subject semantics, but provide a separately implemented real-clock liveness watchdog and prove that watchdog fires.
 Remediation:
 - Every guard subject invocation is launched by absolute `/usr/bin/python3` in a new session. Python's internal monotonic `wait(timeout=...)` provides real-clock liveness independently of PATH; expiry kills the entire isolated process group, so neither PATH-front shims nor a blocked provider descendant can retain the capture pipe.
 - Watchdog expiry returns distinct harness rc 90 plus `FAIL HANG watchdog`, separate from subject timeout rc 124.
 - A first attempt using absolute `/usr/bin/timeout -s KILL` passed on GNU coreutils but failed in the exact Alpine CI-base image: BusyBox killed the immediate wrapper while the guard/provider descendants survived and retained the command-substitution pipe. The process-group kill is therefore required behavior, not portability polish.
 - A committed positive control hangs the branch-provider stub before the status endpoint. It must terminate through the watchdog, emit the hang-specific diagnostic, return rc 90, and prove the status provider was never reached.
 - RED before remediation: a temporary ordinary-success mutant hung before provider observation; only an external control could kill the suite (rc 137), and there was no internal hang-specific diagnostic (`red-watchdog-absent.log`).
 - The watchdog mutant/control is load-bearing: removing the internal watchdog leaves the control unable to produce its required rc 90 and diagnostic.
 Post-review evidence:
 - Host focused harness with process-group watchdog: rc 0 (`green-watchdog-process-group-host.log`).
 - Exact Alpine CI-base focused harness with process-group watchdog: rc 0 (`green-watchdog-ci-image.log`).
 - Hanging ordinary-success mutant: suite rc 1; success returned rc 90, emitted `FAIL HANG watchdog`, and loudly reported that provider/clock observation did not occur (`red-watchdog-fires.log`).
 - Removed-`-t 1` mutant: suite rc 1; pending was terminated by the watchdog instead of producing `ASSERTED_NOT_READY`, proving the explicit timeout is load-bearing (`red-timeout-argument-removed.log`).
 ## 60% context hold
 Stopped before baseline/review/commit as required by the charter. Remaining: inspect final diff, shell/static/baseline gates, independent code/security review, remediation if any, identity-bound commit/trailer verification, mandatory queue guard plus direct terminal Woodpecker `mosaic` enumeration, push, self-posted PR/provider poster read-back, exact-head terminal-green CI, coordinator merge authorization, squash merge, main CI verification, and leave #1019 unclosed as `believed-fixed, pending jarvis validation`.
@@ -0,0 +1,229 @@
 # #1043 — Fleet pane git-identity propagation
 ## Objective
 Ensure a fleet seat's launched runtime process receives its roster-derived `MOSAIC_GIT_IDENTITY`, and lock the complete generated-environment propagation boundary with an enumerated set comparison.
 ## Tracking
 - External issue: `mosaicstack/stack#1043`
 - Branch: `fix/1043-pane-git-identity`
 - Coordinator: `tl-mosaic`
 - `docs/TASKS.md`: read-only by project worker contract; not modified.
 ## Constraints
 - RED-first bug reproducer is mandatory.
 - R7 delete-the-subject mutation must turn the behavioral test red.
 - Assert launched-process environment, not source text.
 - One push only; do not poll CI after push.
 - Run the CI queue guard immediately before push and report its `state=` line as state, not evidence.
 - Do not modify a live host launcher or obtain/copy another credential.
 - Self-post the PR, verify provider attribution, then stop.
 - Final status wording: `believed-fixed, pending jarvis validation`.
 ## Scope inventory
 Re-derived against `origin/main` at `85d2108e`:
 - Launch consumer: `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
 - Behavioral launch test: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
 - Generated-environment contract/parser: `packages/mosaic/src/fleet/generated-env-boundary.ts`
 - Roster projection producers:
  - `packages/mosaic/src/commands/fleet.ts`
  - `packages/mosaic/src/fleet/fleet-reconciler.ts`
  - `packages/mosaic/src/fleet/fleet-agent-crud.ts`
  - `packages/mosaic/src/fleet/v1-v2-migration.ts`
 - Contract and producer tests discovered by repository search.
 - Generated-environment operator/developer docs and their executable documentation contract test.
 Discrepancy sent to `tl-mosaic`: current main no longer contains the charter's `PANE_SHELL_SNIPPET`; #772 replaced it with an `/usr/bin/env -i` argv launch boundary, and current generated projections do not declare git identity. Code-read inventory is **NOT MEASURED** behavior.
 ## Plan
 1. Add the process-environment set-comparison regression first and record RED.
 2. Add roster-derived `MOSAIC_GIT_IDENTITY=<agent name>` to the complete generated projection contract.
 3. Validate identity syntax and equality with `MOSAIC_AGENT_NAME`; pass it through the clean pane environment.
 4. Update affected projection tests and generated-environment docs.
 5. Run focused and baseline gates.
 6. Perform R7 by deleting the pane propagation entry, prove RED, restore, and prove GREEN.
 7. Run independent review, remediate, commit, queue guard, one push, self-post PR, verify provider attribution, and stop without CI polling.
 ## Budget
 No explicit token cap was provided. Working cap: one narrow logical unit, no dependency installation unless existing tooling requires it, no unrelated refactor.
 ## Evidence log
 ### TDD and mutation evidence
 - RED-first, repository launcher: `bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh` exited 64 on pre-fix source with `code=unknown-key key=MOSAIC_GIT_IDENTITY`. The generated seat could not launch with the required declared identity.
 - GREEN: the same repository launcher test emitted `ok - start-agent-session generated environment boundary`.
 - R7 delete-the-subject: removed only `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"` from the repository launch array; the same test exited 1 with `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
 - R7 restoration: restored that launch entry; the same test returned green.
 - Launcher under test is explicitly `packages/mosaic/framework/tools/fleet/start-agent-session.sh` through the test's `$START`, **not** the stale installed host copy.
 ### Situational and focused tests
 - Repository launcher boundary: green, including set comparison of all nine generated projection entries and fail-before-tmux cases for missing, unsafe, mismatched, and local-shadow Git identity.
 - Fleet systemd launcher integration: `bash packages/mosaic/framework/systemd/user/test-fleet-units.sh` — green.
 - Focused Mosaic Vitest set: 6 files, 311 tests — green.
 - `bash -n` on changed shell files — green.
 - `git diff --check` — green.
 ### Baseline gates
 - `pnpm typecheck` — 45/45 tasks green.
 - `pnpm lint` — 25/25 tasks green.
 - `pnpm format:check` — green.
 - `pnpm test:checkout` — green.
 - Repository-wide Vitest under a hermetic current-version npm prefix: Mosaic 81/81 files and 1510/1510 tests green; other workspace test tasks shown green before the framework-shell phase.
 - Canonical `pnpm test` is not fully green on this host for unrelated environment-sensitive gates:
  1. the first two runs exposed the globally installed Mosaic 0.0.48 update banner in three CLI smoke tests expecting empty stderr;
  2. after isolating that global-version input, the framework wake assertion aborted at the known `#973` Bash `BASH_LINENO` convention check (exit 97; observed `[3 5]`, expected `[3 4]`).
  No tests were weakened or bypassed; focused changed-surface tests are green. CI remains the canonical clean-environment result and is intentionally not polled after push per charter.
 ### Independent review
 - Codex code review first pass: request changes for missing shell rejection-path coverage.
 - Remediation: added table-driven missing/unsafe/mismatch/local-shadow launcher cases, each asserting no tmux call.
 - Codex code re-review: **approve**, no findings, confidence 0.88.
 - Codex security review: risk `none`, no findings, confidence 0.97.
 ### Acceptance criteria mapping
 | Acceptance criterion | Evidence |
 | --- | --- |
 | AC-FGI-01: launched process receives every generated key/value | Repository launcher process-environment `comm -23` set comparison; GREEN and R7 RED evidence above |
 | AC-FGI-02: missing, unsafe, or split identity fails before tmux | Table-driven shell cases plus TypeScript generated-boundary tests |
 | AC-FGI-03: focused/baseline/review evidence recorded | Commands and review outcomes above; host-sensitive full-suite limitations stated explicitly |
 ### Documentation checklist
 - PRD updated with #1043 requirements and acceptance criteria.
 - Fleet launch runbook, generated-env concept, and generated-env reference updated.
 - No API/OpenAPI, sitemap, user publishing target, deployment, or external docs publication change applies.
 - `docs/TASKS.md` remains unmodified per its single-writer project contract.
 ## Round 2 — PR #1073 review 97 remediation
 ### Review blocker
 The launched-process suite was signed-excluded from CI enumeration. Manual GREEN/R7 evidence therefore did not prove a PR workflow could detect regression.
 ### RED-first and canonical wiring
 1. Removed the suite's signed exclusion before adding a CI execution path.
 2. `check-test-enumeration.sh` went RED with exact `UNENUMERATED` output for `test-start-agent-session.sh`: population 49, enumerated 30, excluded 18.
 3. Added both `framework/tools/fleet/test-start-agent-session.sh` and `framework/systemd/user/test-fleet-units.sh` to `@mosaicstack/mosaic`'s canonical `test:framework-shell` chain.
 4. The guard returned GREEN: population 49, enumerated 32, excluded 18, surfaces 45. The systemd suite is outside the guard's tools-only population but now has the same explicit canonical execution disposition.
 ### Workflow-level R7
 - Deleted only the pane launch entry `"MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"`.
 - Ran the exact `.woodpecker/ci.yml` test-step command, `pnpm test`, with only a temporary PATH-scoped npm shim reporting the checkout's current 0.0.49 version so the unrelated global 0.0.48 banner could not preempt the shell chain.
 - Result: exit 1 at `@mosaicstack/mosaic#test`, with the enumeration guard GREEN followed by `FAIL: runtime pane omitted or changed generated environment keys: MOSAIC_GIT_IDENTITY`.
 - Restored the launch entry. The canonical `test:framework-shell` chain then reached both newly wired suites and printed both GREEN markers before the known unrelated #973 host-only `BASH_LINENO` abort.
 - An actual provider PR workflow on the intentionally broken mutant is **NOT MEASURED**: the one-push constraint forbids pushing a red mutant and then a repaired head. Local execution proves the exact PR workflow command and dependency chain go RED on the subject deletion; CI on the repaired pushed head remains canonical.
 ### Workflow population
 - **DEFINED:** 3 workflows (`ci.yml`, `ci-image.yml`, `publish.yml`).
 - **ELIGIBLE for `pull_request`:** 1/3 (`ci.yml`), based on top-level `when:` clauses.
 - **REPORTED:** Round-1 exact-head provider read reported 1/1 eligible context (`ci/woodpecker/pr/ci`). Post-remediation-head reported count is **NOT MEASURED** by this seat because CI polling is prohibited; workflow definitions and eligibility did not change.
 ### Independent remediation review
 - First Round-2 review identified a CI-image blocker: the newly wired launcher suite used Perl, which the Alpine CI base does not install.
 - Replaced the suite's three Perl-only fixture mutations with POSIX/BusyBox-compatible `sed -i` substitutions; production behavior and assertions are unchanged.
 - Codex re-review: **APPROVE**, confidence 0.93, no findings.
 ### Vitest denominator reconciliation
 The PR's `311/311` is correct for its explicitly named six-file command at both the original and remediation worktrees:
 - generated environment boundary: 24
 - fleet documentation: 23
 - Tess service profile: 6
 - fleet regen command: 27
 - fleet agent CRUD command: 22
 - fleet command: 209
 - total: **311**
 Review 97 reported 312/312 without naming its six files. That is a different or miscounted population and cannot replace the command-scoped 311 denominator; the PR follow-up will name the exact files and arithmetic.
 ## Round 3 — Alpine stale-marker portability
 ### Objective and plan
 - Replace the GNU-only relative-date fixture with a deterministic POSIX/BusyBox timestamp while preserving the required stale-marker assertion.
 - Re-run the launcher suite in the canonical `ci-base:latest` Alpine image, then run applicable repository gates and independent review.
 - Update the PR body to name the repeated GNU-host/Alpine-CI portability pattern, run the mandatory queue guard, push once, verify provider attribution, and stop without CI polling.
 - Working budget: 8K tokens; scope is one fixture line plus delivery evidence. No production behavior changes.
 ### RED-first evidence
 Before the fix, the canonical CI image command
 `docker run --rm -v "$PWD:/work" -w /work git.mosaicstack.dev/mosaicstack/stack/ci-base:latest bash packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
 exited 1 at the stale-marker setup with exact BusyBox output
 `touch: invalid date '10 seconds ago'`. The prior fresh-marker assertions had already executed, matching pipeline 2233's failure location.
 ### Root cause and fix
 The test used GNU `touch -d` relative-date parsing although the PR workflow runs on Alpine/BusyBox. The fixture now uses POSIX `touch -t 200001010000.00`, a fixed timestamp that is unconditionally stale; the stale assertion remains mandatory and was not made tolerant of missing timestamp metadata.
 ### Structural pattern
 This is the third GNU-host/Alpine-CI portability defect in the lane: GNU `grep` multi-match counting, Perl-only fixture mutation, and GNU `touch -d` date parsing. The repeated cause is shell suites authored on a GNU host but executed in an Alpine CI image; durable prevention belongs in CI-image execution or portability lint, not assertion weakening.
 ### GREEN and quality evidence
 - Focused launcher suite in `ci-base:latest`: exit 0, `ok - start-agent-session generated environment boundary`.
 - Canonical test step in `ci-base:latest` with the pipeline's `pgvector/pgvector:pg17` service, readiness check, migration, and `pnpm test`: exit 0; 46/46 Turbo tasks; Mosaic 81/81 files and 1510/1510 tests; Gateway 57 passed/5 skipped files and 629 passed/11 skipped tests; enumeration 49 population / 32 enumerated / 18 signed exclusions / 45 named surfaces.
 - The first image-only `pnpm test` attempt lacked the pipeline PostgreSQL service and failed only on connection refusal after the launcher suite was GREEN. The rerun supplied the canonical service precondition and passed.
 - Canonical-image baseline: typecheck 45/45 tasks, lint 25/25 tasks, format check GREEN; `git diff --check` GREEN.
 - Independent Codex code review: APPROVE, confidence 0.96, 2/2 Round-3 files, no findings.
 - Independent Codex security review: risk none, confidence 0.99, 2/2 Round-3 files, no findings.
 ### Re-derived inventory and denominators
 - Round-3 git delta: **2/2 files** — launcher suite and task scratchpad; 25 insertions / 1 deletion before evidence finalization.
 - Full PR path inventory against `origin/main` at `85d2108e`: **19/19 changed paths**; Round 3 adds no new PR path.
 - Workflow definition population: **1/3 pull-request-eligible** (`ci.yml` of `ci.yml`, `ci-image.yml`, `publish.yml`).
 - Do not re-litigate the settled 311/312 populations; both are valid for their separately named Tess6 and CRUD-core7 sets.
 ## Round 4 — bound stale-marker observation
 ### Objective and plan
 - Make the heartbeat assertion discriminate an initially stale native marker from a fresh marker without changing the production staleness threshold or shortening the polling window.
 - Freeze only the sidecar's numeric observation clock during the stale-fixture arm so elapsed assertion time cannot turn a fresh mutant stale.
 - Prove two independent mutants RED: disable production stale-marker detection while retaining the stale fixture; replace the stale fixture with a fresh marker. Restore the tree and prove GREEN in the canonical Alpine image.
 - Re-derive the changed-path inventory, run applicable quality and independent review gates, commit with environment-only author/committer identity, queue-guard, push once, verify provider attribution using curl stdin config, and stop without CI polling.
 - Working budget: 8K tokens. Scope is the launcher test and its scratchpad evidence; production launcher behavior remains unchanged.
 ### Root cause and bounded observation
 The 30 × 0.1-second assertion window overlaps the production `now - marker > interval * 2 + 1` threshold at interval 1. Depending on second boundaries and load, a fresh marker can age past the threshold before the assertion ends. A focused pre-fix fresh-mutant attempt returned RED while Review 101's full-suite run returned GREEN; the differing result is itself timing dependence, not a discriminating assertion.
 The test now supplies a fixed numeric epoch only to the stale-fixture sidecar. Its real marker mtime is still read from the filesystem, but assertion runtime cannot advance `now`. Date formatting still delegates to the image's real `/bin/date`. Neither the production threshold nor the 30 × 0.1-second polling window changed.
 ### Two-mutant RED / restored GREEN
 All three runs used `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest`:
 1. **Stale-detection mutant RED:** replaced only the production stale-age predicate with `false` while retaining the fixed stale marker; suite exit 1 with `FAIL: heartbeat sidecar did not resume after native marker became stale or absent`.
 2. **Fresh-marker mutant RED:** replaced only `touch -t 200001010000.00` with fresh `touch`; suite exit 1 with the same failed stale-resumption assertion. The fixed observation epoch kept the mutant fresh throughout all 30 polls.
 3. **Restored tree GREEN:** suite exit 0 with `ok - start-agent-session generated environment boundary`.
 ### Re-derived inventory
 - Round-4 delta: **2/2 files** — launcher test plus task scratchpad; production launcher delta is empty.
 - Full PR inventory against `origin/main`: **19/19 paths**; Round 4 adds no path.
 - Production stale threshold remains `now - marker > iv * 2 + 1`; assertion polling remains 30 × 0.1 seconds.
 - Review 101's confirmed enumeration/workflow/CI and attribution evidence is accepted without re-polling or re-derivation.
 ## Residual risk
 - Landing on `main` does not update the currently installed host launcher. Host framework installation/reseed and Jarvis live-seat validation are separate downstream events.
 - Canonical CI result is pending and will not be polled by this seat.
@@ -0,0 +1,97 @@
 # #1098 — Framework shell portability / red main
 ## Objective
 Restore terminal-green `main` by making the `test-start-agent-session.sh` clean-environment assertion semantic and portable without removing either newly enumerated framework-shell suite.
 ## Scope
 - Tracking issue: `mosaicstack/stack#1098`
 - Branch: `fix/framework-shell-portability`
 - Base: `origin/main` at `4fa2768962702d53e16e8b67ee6ad52ebcb0910e`
 - Primary file: `packages/mosaic/framework/tools/fleet/test-start-agent-session.sh`
 - Requirements source: `docs/PRD.md` § Framework shell assertion portability (#1098)
 - Out of scope: deployed files under `~/.config/mosaic`, pnpm-store cleanup, checkout deletion, and changes to the launcher’s `/usr/bin/env -i` behavior.
 ## Acceptance criteria
 1. The test inspects the captured NUL-delimited tmux argv semantically and accepts an adjacent `/usr/bin/env`, `-i` pair regardless of trailing payload size or pipe scheduling.
 2. Missing `/usr/bin/env`, missing `-i`, and non-adjacent `-i` remain failures.
 3. Failure output includes the observed argv records with stable indexes and shell escaping; it exposes no credentials because this fixture supplies only generated non-secret launch data.
 4. The focused suite passes on the dev host and in the repository CI image; the blocking PR/main pipeline returns terminal green.
 5. Independent review passes; PR is squash-merged and #1098 is closed only after merged-main CI is terminal green.
 ## Budget
 - ASSUMPTION: 30K-token working budget; rationale: one shell-test defect plus full PR/CI lifecycle.
 - Auto-reduction: focused shell and package gates first; rely on canonical Woodpecker for the full monorepo suite rather than duplicating a dependency install under constrained `/home`.
 - Disk baseline before clone/build: `/home` 7.1G free (99% used), `/tmp` 2.4G free (92% used).
 ## Investigation
 ### First-hand CI evidence
 - Public log: `GET https://ci.mosaicstack.dev/api/repos/47/logs/2269/53041`
 - Decoded 1,436 entries (11 null `data` entries treated as empty log rows), 190,756 bytes.
 - Failure: `FAIL: pane command did not clear its environment` immediately after the expected pane-PID warning.
 - BusyBox primitives, complete assertion pipeline, real CI image, stale/current image digests, Turbo cache masking, gateway failure, and heartbeat-sidecar concurrent writing were independently excluded.
 ### Root cause
 The assertion ends in:
 ```bash
 printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i'
 ```
 The script has `set -o pipefail`. `grep -q` exits as soon as it finds the valid `-i` record. Upstream `tail`/`printf` can then receive SIGPIPE, making the aggregate pipeline nonzero even though grep returned 0 and the semantic property is true. This depends on payload size, pipe capacity, and scheduling, explaining a local/image pass with a CI failure.
 Discriminating stress control with `/usr/bin/env` followed immediately by `-i`:
 - 8,192-byte trailing payload: `printf=0 tail=0 grep=0`, aggregate 0.
 - 16,384-byte trailing payload: `printf=0 tail=141 grep=0`, aggregate 141.
 - 32,768+ bytes: `printf=141 tail=141 grep=0`, aggregate 141.
 - A full-reading `grep -xF` control remained 0 for every payload.
 This is a third branch omitted by the earlier present-vs-corrupted split: the pair can be present and intact while `pipefail` reports an upstream SIGPIPE.
 ## TDD plan
 1. RED: preserve the one-off stress reproducer above and add an automated large-argv semantic regression that fails under the current pipeline implementation.
 2. GREEN: parse the authoritative NUL-delimited capture into a Bash array and search for an adjacent `/usr/bin/env`, `-i` pair without a short-circuit pipeline.
 3. Add negative controls for missing, detached, and reversed tokens.
 4. On failure, print indexed `%q` argv records before returning nonzero.
 5. Run focused suite, mutation controls, shell syntax/format checks, then repository baseline gates feasible without dependency installation.
 6. Independent review, queue guard, push, PR, CI, coordinator merge authorization, squash merge, merged-main CI, issue close.
 ## Progress
 - [x] Checkout created and based on `origin/main` `4fa27689`.
 - [x] CI log decoded directly.
 - [x] Root-cause stress control reproduced semantic match + aggregate pipeline failure.
 - [x] RED evidence: intact `/usr/bin/env`, `-i` fixture produced component statuses `0/141/0` and aggregate 141 under the former `grep -q` pipeline; full-reading semantic control stayed 0.
 - [x] GREEN implementation: direct NUL-argv adjacency parser, indexed diagnostics, and full-reading scalar predicates replace all load-bearing early-exit pipelines in this test.
 - [x] Baseline/situational tests:
  - focused launcher suite: PASS on GNU host and cached Alpine CI image;
  - paired `test-fleet-units.sh`: PASS;
  - enumeration guard: PASS (`population=53`, `enumerated=36`, `excluded=18`), 14/14 mutation needles;
  - `bash -n`, ShellCheck, `git diff --check`: PASS;
  - static denominator after change: zero load-bearing `grep -q`/`head`/`-m1` pipeline candidates in `test-start-agent-session.sh`;
  - delete-the-subject mutation removing production `-i`: RED with 78 indexed argv records, byte count, and explicit boundary failure.
 - [x] Independent review:
  - first Codex review: request changes — negative fixtures did not each assert diagnostics;
  - remediation: centralized predicate + diagnostic wrapper and exercised all four negative fixtures;
  - second Codex review: APPROVE, 0 blockers/should-fix/suggestions;
  - Codex security review: risk none, 0 findings.
 - [ ] PR CI, formal fleet review, merge, merged-main CI, issue closure.
 ## Documentation disposition
 - Updated canonical `docs/PRD.md` with FSP requirements and acceptance criteria.
 - This is an internal test/reliability change with no API, user workflow, deployment, navigation, or publishing-surface change; no user/admin/API/sitemap update is required.
 - `docs/TASKS.md` remains unchanged because the project contract makes it orchestrator-only.
 ## Risks
 - The CI failure did not print its captured argv, so the exact CI payload is unavailable. The stress control proves the assertion is non-portable and can emit the exact false verdict; branch CI is the canonical confirmation that replacing it resolves pipeline 2269’s failure class.
 - Printing fixture argv is safe only while this test’s projection remains non-secret. The diagnostic must stay scoped to the test capture and shell-escaped.
@@ -0,0 +1,41 @@
 # #1099 — pipefail + early-exit sweep
 ## Scope and decisions
 - Baseline `df4c591ab42aa1ae62c12935fdc0e772684864a0`, after #1100 removed its 35 sites.
 - Split into review-sized non-closing tranches: runtime/general; tmux/git/quality tests; wake validation/tests.
 - Do not equate class membership with demonstrated risk. Do not use payload size or pipeline stage count as a safety proxy.
 - Preserve the issue's withdrawn findings for `qa-hook-stdin.sh` and the two fresh-directory `pnpm pack` lookups. Fix `install.sh:312` because malformed multi-root input must reach its named handler.
 ## Tranche 1 TDD
 RED-first control: `node --test scripts/pipefail-early-exit.test.mjs` reported exactly 26 non-accepted runtime/general sites, including `install.sh:312`, and exited 1. A checked-in fixture generated from immutable baseline `df4c591a` records all 26 normalized sites; the control passes every fixture entry through the same scanner, asserts exact identity/count/uniqueness, and separately requires zero findings in the current tree. It also inventories accepted sites rather than silently excluding whole files.
 Construction choices:
 - here-string/file redirection for scalar grep assertions;
 - full capture then parameter expansion for first-line selection;
 - arrays/`mapfile` for complete populations;
 - direct jq/awk/grep selection where one tool can express the property;
 - no `|| true` added to a load-bearing assertion.
 Site-by-site verdicts: `docs/reports/quality/1099-pipefail-sweep.md`.
 ## Tranche 2 TDD
 Expanded the unconditional scanner over 11 non-wake test harnesses. RED named exactly 22 source lines; a second immutable-baseline fixture now asserts those 22 entries through the same scanner. Rewrites preserve command status by capturing producers before redirected assertions, use parameter expansion for line selection, and use complete `mapfile` populations where ordering matters. Current-tree finding count is zero for tranches 1 and 2.
 ## Tranche 3 TDD
 Expanded the shared scanner over four wake validation harnesses. RED named 26 occurrences. The wake fixture asserts 26 occurrences / 25 normalized identities through the same scanner; all scalar assertions now use redirection, direct jq selection, complete capture, or consuming diagnostic ranges. Current-tree finding count is zero across the full scoped population.
 ## Verification so far
 - `bash -n` on every changed shell script: pass.
 - structural Node control: pass.
 - `test-mutate-push-guard.sh`: 8/8 pass.
 - `test-send-message-verdict.sh`: 3/3 pass.
 - `test-send-message-socket.sh`: pass.
 - Independent review 143 found two semantic regressions: a help-probe `|| true` changed the failure truth table, and an unguarded Git capture changed non-Git data-dir behavior from rc 0 + JSON to silent rc 128. Both received RED-first regressions before correction; help status is now separate and required, and Git status remains condition-guarded.
 - Wake static inventory remains aligned at 261/261 after line-neutral rewrites; no static-set mismatch. Wake detector/reconcile/digest/preimage suites terminate at their existing fail-closed #973 `BASH_LINENO` environment probe (exit 97, observed `[3 5]`, expected `[3 4]`) before subject tests. No bypass or skip was used; canonical CI remains required.
 - ShellCheck reports only pre-existing source-following, unused-variable, and untouched `ls | head` findings; no new diagnostic was introduced.
@@ -0,0 +1,156 @@
 # #1150 — Pi persistent goal extension
 - **Task ID:** ISSUE-1150 (no `docs/TASKS.md` row; that file is orchestrator-only)
 - **Issue:** #1150 — `pi: add persistent /goal controller extension to Mosaic framework`
 - **Branch:** `feat/1150-pi-goal-extension`
 - **Mode:** Delivery
 - **Status:** in progress
 ## Objective
 Build and locally validate a Mosaic-owned Pi `/goal` extension. Source must ship from
 `packages/mosaic/framework/runtime/pi/`, framework sync must deploy it under
 `~/.config/mosaic/runtime/pi/`, and no extension/configuration asset may be written into `~/.pi`.
 Pi's native session manager remains the owner of session entries.
 ## Scope and acceptance source
 - Canonical requirements: `docs/PRD.md`, section **Pi Persistent Goal Loop (#1150)**.
 - User intent: continuous goal orientation and status checking after each Pi turn and compaction,
  tested locally before framework delivery.
 - Documentation target: canonical in-repo user/developer/runtime docs; no external publication.
 ## Assumptions
 - `ASSUMPTION:` Initial semantic verification uses two consecutive structured, evidence-bearing
  reports from the working agent rather than a second model request after every turn. This keeps the
  loop testable and avoids doubling model cost while making the limitation explicit.
 - `ASSUMPTION:` Default autonomous bounds are 40 turns and 6 repeated no-progress reports, with only
  bounded numeric environment overrides.
 - `ASSUMPTION:` A local smoke copy to `~/.config/mosaic/runtime/pi/goal-extension.ts` is authorized by
  the user's explicit request. Full framework reseed into the live home is not required for the smoke
  test and would touch unrelated framework-owned files.
 ## Budget
 - Working estimate: 30K implementation/review tokens.
 - Hard user cap: none stated.
 - Cost control: deterministic fake-Pi tests; no nested evaluator calls; only bounded arithmetic/load
  smoke workflows against the installed runtime.
 ## Plan
 1. Update PRD and create tracking/scratchpad artifacts.
 2. Read launcher, installer ownership, Pi extension, and documentation surfaces.
 3. TDD: add fake-Pi behavior tests for commands, state restoration, turn checks, compaction, limits,
   verification, and continuation deduplication.
 4. Implement `runtime/pi/goal-extension.ts` and deterministic launcher discovery.
 5. Add framework-sync/deployment acceptance coverage.
 6. Update user, developer, runtime, framework README, and sitemap documentation.
 7. Run focused tests, local Mosaic-path smoke test, then baseline repository gates.
 8. Run independent review, remediate, commit, push/PR/CI/merge/issue closure per delivery gates.
 ## TDD decision
 Applied. The continuation state machine and lifecycle scheduling are control-path logic where a race
 or false terminal state can cause unbounded work or premature completion.
 ## Progress checkpoints
 - [x] Issue #1150 created through Mosaic wrapper.
 - [x] Isolated worktree created from `origin/main`.
 - [x] PRD requirements and acceptance criteria added.
 - [x] Task scratchpad created.
 - [x] RED controller and security-regression tests written and observed failing before implementation.
 - [x] Goal controller, launcher discovery, framework deployment coverage, and bounded state machine
      implemented.
 - [x] User, admin, developer, runtime, adapter, README, and sitemap documentation updated.
 - [x] Final source copied additively to `~/.config/mosaic/runtime/pi/goal-extension.ts`; source and
      deployed SHA-256 are identical.
 - [x] Live Pi RPC smoke from the exact Mosaic path reached `achieved` with two verification passes and
      no extension errors.
 - [x] Baseline and situational checks completed, except the explicitly documented unavailable
      PostgreSQL-only root integration case.
 - [x] Independent code and OWASP/security reviews completed; all findings remediated and re-reviewed.
 - [ ] Commit, push, PR, terminal-green CI, squash merge, and issue closure complete.
 ## Tests and evidence
 ### Situational
 - `pnpm --filter @mosaicstack/mosaic exec vitest run src/runtime/pi-goal-extension.spec.ts`
  - final: 25 passed.
  - Covers commands, per-turn checks, context injection, two-pass verification, mixed-report
    rejection, bounded limits, compaction, branch restore, stale timers, credential redaction,
    typed-field false-positive protection, and append-only legacy-state fail-closed behavior.
 - Final focused launcher/controller/file-adapter run: 3 files / 67 tests passed.
 - Final V8 coverage for `framework/runtime/pi/goal-extension.ts`:
  - 99.17% statements/lines, 93.78% branches, 100% functions.
 - Installer migration fixture: 24 passed and byte-compared the deployed framework asset.
 - Standalone extension TypeScript check against installed Pi 0.84.1 types passed:
  `pnpm --filter @mosaicstack/mosaic exec tsc --noEmit --pretty false --module NodeNext
  --moduleResolution NodeNext --target ES2022 --skipLibCheck framework/runtime/pi/goal-extension.ts`.
 - Live deployment/load evidence:
  - source/deployed SHA-256:
    `1f0a3806e0948ad5f49684273a7e535e9880c148f7fd16d13ee487fcd601f637`.
  - `get_commands` identified `/goal` as an extension command sourced from
    `~/.config/mosaic/runtime/pi/goal-extension.ts`; `/goal help` succeeded; zero extension errors.
  - live arithmetic goal ended `achieved`, verification `2/2`, with 3 goal reports / 3 agent starts
    and zero extension errors.
  - no goal extension exists under `~/.pi` extension paths.
 ### Baseline
 - `pnpm build`: passed before the final framework-only redaction remediation; the extension is not a
  package build input and its final source passed the standalone Pi type check.
 - `pnpm typecheck`: 45/45 tasks passed.
 - `pnpm lint`: 25/25 tasks passed.
 - `pnpm format:check`: passed.
 - Final Mosaic package components:
  - Vitest: 82 files / 1,539 tests passed.
  - full `test:framework-shell` harness passed.
  - the discovered pre-existing tmux loader-marker race was reproduced with constructor PID
    evidence, fixed with a pane readiness/FIFO barrier, passed 3 consecutive focused runs, and passed
    in the full shell harness.
  - one combined rerun encountered the separate existing real-lease probe TOCTOU in
    `install-ordering-guard.spec.ts`; an earlier final Vitest run was fully green and the changed
    focused suites remained green.
 - Gateway safe baseline excluding the prohibited PostgreSQL-only fixture: 55 files / 600 tests passed
  (6 files / 12 tests skipped by their existing environment gates).
 - Root `pnpm test` reached 43 successful workspace tasks and all changed-package Vitest tests, but
  the unchanged `apps/gateway/src/__tests__/cross-user-isolation.test.ts` afterAll hook retried a
  PostgreSQL connection and failed authentication (`28P01`). This checkout explicitly forbids local
  PostgreSQL startup/access; the failure is unrelated to #1150 and cannot be remediated by starting
  the database. The gateway suite excluding that PostgreSQL-only file and required CI are used as
  the safe verification paths.
 ### Independent review
 - Codex code review: approved, 0 findings across 15 files.
 - Initial Codex security review: one medium CWE-532/A09 finding for raw report persistence.
 - Remediation added central credential-pattern redaction, prompt/docs guidance, canary tests, typed
  field false-positive guards, and sticky fail-closed restore for credential-bearing append-only
  history.
 - Codex security re-review: risk `none`, 0 findings, confidence 0.87.
 - Focused remediation review findings were fixed; final focused re-review verdict: `APPROVE`.
 - Focused independent review of the tmux readiness barrier: `APPROVE`, no actionable findings.
 ## Risks and blockers
 - Live `~/.config/mosaic` is shared by active Pi/fleet processes. Local deployment remained a single
  additive framework file and did not reload or restart unrelated sessions.
 - Completion verification is semantic, not mathematical: the active agent supplies structured
  evidence twice. Operators must still inspect consequential outcomes.
 - Credential redaction is pattern-based defense-in-depth, not a secret store. It covers
  controller-owned state/status/tool details, not Pi's separate model-message/tool-call history.
  Goals and reports must never contain real secrets or raw sensitive output. Because Pi session
  entries are append-only, a detected credential-bearing legacy branch fails closed and the affected
  session must be removed.
 - Current installed Pi is newer than the repository's historical gateway Pi dependency. The
  extension was checked and smoke-tested against installed Pi 0.84.1 using stable documented APIs.
 - Local root testing cannot safely execute the unchanged PostgreSQL-only integration fixture under
  the checkout's explicit database safety constraints. Terminal-green PR CI remains mandatory before
  merge.
 - The unchanged real-lease default-probe test can observe different broker availability across its two
  sequential probes; one combined package rerun hit that existing TOCTOU. The same final Vitest suite
  passed in a separate run, and CI remains the merge authority.
@@ -0,0 +1,99 @@
 # PR merge squash message field
 - **Charter:** `/home/hermes/agent-work/CHARTER-PRMERGE-MESSAGE-FIELD.md`
 - **Owner:** `be-coder-08`
 - **Branch:** `fix/pr-merge-message-field`
 - **Base:** remote `main` / local `origin/main` at `85d2108e4ed15c744ad3b87a5b629e7b2d39405a`
 - **Estate:** HOMELAB tooling shared by HOMELAB and USC
 ## Objective
 Add an optional, identity-checked Gitea squash message to `pr-merge.sh` so genuine multi-author PRs retain non-poster branch authors without weakening hardcoded squash behavior.
 ## Binding requirements
 1. `Do` remains hardcoded to `squash`; no provider/repository default may select merge style.
 2. A verified trailer uses a PR commit's linked `author.login` and that same commit's author email. No `/users/{login}` primary-email lookup occurs. Recorded rationale: this asks only what the provider can answer.
 3. A commit with `author.login` null blocks before merge, prints both the null provider fact and commit email fact, and names the escalation principal.
 4. The BLOCK arm must be observed firing; a normal canonical single-author API payload remains explicit squash plus its reviewed `head_commit_id`.
 5. Every provider mutation is read back from the provider; no real PR is merged during tests.
 ## Derived interface decisions
 - Add `--co-author-trailers` rather than accepting arbitrary message text. The wrapper enumerates PR commits and constructs trailers, making an unchecked `Co-authored-by` line unexpressible.
 - Require `--escalate-to PRINCIPAL` with `--co-author-trailers`, so the BLOCK diagnostic always names a principal rather than a generic role.
 - Do not expose `MergeTitleField` separately. When trailers exist, set it from the provider PR title and set `MergeMessageField` only to construction-generated trailers. This preserves one provider source for the title and avoids an unrelated caller-controlled degree of freedom.
 - Preserve first-commit order and emit one trailer per distinct non-poster `author.login`, using that first linked commit's own email.
 ## Canonical delivery plan
 1. Port the capability into the installed source of truth, `packages/mosaic/framework/tools/git/pr-merge.sh`; do not retain `infra/fleet/tools/git` as a second copy.
 2. Preserve canonical `--expect-head`, exact head branch/repository/SHA queue inspection, Gitea atomic head pinning, GitHub `--match-head-commit`, and delete-after-merge semantics.
 3. Do not port the deployed-only `--skip-queue-guard` bypass. Add the focused harness to the canonical framework-shell suite and re-establish RED/GREEN on the packaged baseline.
 4. Deliver through a reviewed package release followed by `mosaic update` with its default framework reseed. The installer snapshots, manifest-syncs framework-owned `tools/**`, and rolls back on failure.
 5. Before either estate relies on the change, require installed/package hash equality, `MergeMessageField` presence, and a green focused harness. Release/reseed ownership is currently unassigned and blocks activation after source merge.
 ## Evidence
 - RED against the byte-identical deployed baseline (`sha256 08a65e8584c5…`): rc 1 with eight named failures. The wrapper rejected `--co-author-trailers`; the null-login path emitted none of the required BLOCK facts/principal; and both verified/ordinary API paths failed the stdin-config credential assertion (ordinary path exposed the fixture token through curl argv). Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-red.log`.
 - GREEN on the deployed-baseline candidate: verified linked multi-author payload, null-login BLOCK, required named principal, explicit squash, stdin-config token transport, and absence of `/users` lookup all passed. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-message-field-green.log`.
 - RED against canonical packaged baseline `c581ef48…`: rc 1 with 32 assertions. It rejects the new option, and the first harness version did not satisfy canonical head branch/repository/SHA metadata. Log: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-packaged-baseline-red.log`. The port adapts the fixture rather than weakening canonical head controls.
 - Provider capability probe against `git.mosaicstack.dev`: authenticated `be-coder-08` POST to deliberately nonexistent PR `2147483647` with both message fields returned JSON HTTP 404; the unauthenticated same request returned JSON HTTP 401 (not the charter's predicted 403). The authenticated-vs-unauthenticated differential proves write authorization resolved while no mergeable subject existed. `tl-mosaic` ruled the literal non-load-bearing: preserve the observed 404/401 pair and do not manufacture a 403 case. No cause was inferred and no real PR was targeted.
 - Provider-generated trailer behavior is not treated as exclusive or absent. The wrapper's VERIFIED/BLOCK decision binds each requested non-poster trailer to commit `author.login` plus that commit's email; it does not assume `MergeMessageField` is the squash's only trailer source. The poster is omitted from the constructed list because the resulting squash author already records the poster; any additional provider-generated trailer is outside this change's unmeasured mechanism.
 - An early candidate SHA-256 `5de32876990e4f26920448cb3220cc7f1146d558b4dd2bc1ee1a2abee2f2cbe6` passed the initial harness, then author-side review found credential-fallback and argv-exposure defects. The live deployed wrapper was atomically restored to baseline SHA-256 `08a65e8584c52c6d41ea1c686f8b95585c21e4b37320a2447eba09359a0e02c1`; the remediated candidate remains only in the worktree.
 ## Remediation and current review state
 1. Token and Basic Auth now use stdin curl configuration, not argv. PR title, contributor email, and the JSON payload also remain out of child argv.
 2. Each credential attempt binds commit inspection and merge. A token failure during either inspection or mutation causes Basic fallback to repeat inspection before mutation; the payload pins the inspected `head_commit_id`.
 3. Focused tests cover token-resolution fail-closed behavior, both HTTP-401 fallback seams, metadata/credential argv absence, null-login BLOCK, explicit squash, canonical reviewed-head binding, unchanged ordinary payload, and retained log-safe provider diagnostics. Token-resolution RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-token-resolution-red.log`.
 4. Codex review rounds 3–5 requested retained provider error text, log-safe provider diagnostics, fail-closed credential fallback, stable value-option parsing, and PR-title trailer-injection prevention. These are remediated with regression assertions. A post-remediation independent review is still required.
 5. **Accepted linkage limitation:** `author.login` resolution proves that the commit address maps to a registered provider account. It does not prove that the named principal authored the commit because Git author metadata is self-asserted. This gate checks attribution linkage, not authorship; commit signing is out of scope and currently unadopted. Coordinators explicitly ruled that this does not add a third state.
 6. Codex's sandbox could not execute the harness because its checkout was read-only; that environmental limitation is recorded separately from host-side test results.
 ## Disposable provider fixture acceptance
 - Use a retained scratch repository only, with two branch authors and `author != committer` on at least one commit.
 - Arm A supplies a message-field trailer for one non-poster; record whether that value lands without forcing the partial-pair result into under-specified `APPENDS`/`REPLACES` labels. Demonstrate an absence control.
 - Arm B includes a registered trailer for a different non-poster on a branch commit; record whether it survives or drops. Verify identity through an existing commit whose `author.login` resolves and demonstrate an absence control.
 - Parse landed trailers key-agnostically with `^[A-Za-z-]+-[Bb]y:` and record generated poster pair presence/absence plus resulting poster attribution.
 - Record `/users/<login>` status and raw email only as non-gating estate telemetry. Never read `active`, `visibility`, or any profile field as an identity gate.
 - Use distinct principals: poster `be-coder-08`, merger `Mos`, Arm A `be-coder-07`, and Arm B `be-coder-06`. Capture every trailer-shaped line verbatim and in order. Zero trailer lines means the generator did not fire and the run is `VOID`, not evidence that either arm dropped.
 - Report the same read-back evidence to `mos-claude` on socket `default` and `tl-mosaic` on socket `mosaic-fleet`. Report values rather than mechanism inferences and stop on any poster-attribution regression.
 ## Fixture preflight
 - Retained public repository: `mosaicstack/prmerge-trailer-fixture`; PR `#1`, posted by `be-coder-08` and reserved for merge by `Mos`.
 - Existing `mosaicstack/stack` commits resolve `be-coder-07` and `be-coder-06` through `author.login`; exact addresses are `[email protected]` and `[email protected]`.
 - Non-gating HOMELAB telemetry for authenticated reader `be-coder-08`: `/api/v1/users/be-coder-06` returned HTTP 200 with raw `email` value `[email protected]`.
 - Provider preflight showed PR commit enumeration is newest-first. A new RED test proved that deriving `head_commit_id` from the final array element selected the wrong commit. The candidate now reads `.head.sha` from the authenticated PR endpoint before enumeration, verifies it appears in the commit set, and atomically pins that SHA in the explicit squash payload. RED: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-head-order-red.log`.
 - Fixture PR head `f6ba6e5105031fa21f5ff7bd8e4379d99c16e1de` has `author.login=be-coder-07`, `committer.login=be-coder-08`, and branch-message trailer `Co-authored-by: be-coder-06 <[email protected]>`.
 ## Fixture result
 - `Mos` merged retained fixture PR `#1` through staged candidate SHA-256 `60e779a85fd13b729d859ea7c986d1e9b1641b97991611329226c1b3113ffb6e`; resulting squash commit: `3f550715d9bc716426fd355a65fe997b3a90fa7d` with one parent.
 - Provider read-back: poster/commit author `be-coder-08`, committer/merger `Mos`. The run is non-void.
 - Trailer-shaped lines, verbatim and in order:
  1. `Co-authored-by: be-coder-07 <[email protected]>`
  2. `Co-authored-by: be-coder-08 <[email protected]>`
 - Arm A supplied field value (`be-coder-07`) landed. Arm B branch trailer (`be-coder-06`) dropped. Both fabricated absence controls remained absent. No `Co-committed-by:` line landed.
 - The candidate payload construction explicitly excludes the poster and supplied only the Arm A `be-coder-07` line. Therefore the landed poster line was provider-generated, not candidate-composed. The raw result supports `FIELD LANDS`, `BRANCH DROPS`, and `POSTER GENERATED`; it does not support a claim that candidate code supplied the poster. Evidence: `/home/hermes/agent-work/be-coder-08/evidence/prmerge-fixture-readback.log` and the retained provider object.
 - Retained fixture PR `#2` measured the N=2 shape needed by `#1030`: supplied `be-coder-07` then `be-coder-06`; both landed in that order, followed by the provider-generated poster line. No truncation or dedup occurred at N=2. Resulting squash: `39db9d13aed0…`.
 ## Current hold point
 PR `mosaicstack/stack#1066` is open. Its first frozen head `f4b162fa…` was terminal-green in Woodpecker `mosaic` pipeline `#2225`, but that evidence becomes stale when the canonical port moves the head. The deployed wrapper remains baseline `08a65e85…`; no manual copy will occur. Canonical port tests, commit amendment, rebase, one guarded force-with-lease, exact-head CI, and new independent review remain. Even after source merge, activation remains blocked on an assigned package-release/reseed owner and installed-byte read-back.
 ## Security review 96 remediation
 Exact reviewed predecessor head: `1ceb11058f64dd7f4a817ceb2124f980a1c4dd23`.
 RED-first focused harness produced 10 named failures: all curl calls lacked size/time/connect bounds; raw ESC email reached mutation; oversized and stalled curl failures were discarded and reached mutation; nonempty Basic output with resolver rc 91 authorized mutation.
 Security remediation:
 - Removed the cross-principal HTTP-401 Basic fallback. Both inspection-401 and merge-401 paths now refuse without Basic resolution or mutation; `get_gitea_basic_auth` references in the merge subject are 0.
 - Applied `--max-filesize`, `--max-time`, and `--connect-timeout` to all 3/3 provider curl sites and fail closed on curl transport rc at all 3/3 sites.
 - Required linked email bytes to be ASCII and printable before constructing `MergeMessageField`; guarded construction sites 1/1.
 GREEN: message-field, exact-head, empty-UID/API, queue branch/repository/SHA, bash syntax, ShellCheck, and diff check pass. R7 total-removal mutants went RED: email guard 3 rows; bound switches 1 row; transport-rc guards 4 rows; HTTP-401 refusal 3 rows. R7 bound: mutants prove total removal only; explicit denominators above prove site coverage.
@@ -13,7 +13,8 @@ Pi is the native Mosaic agent runtime. The `mosaic pi` launcher:
 1. Injects the full runtime contract via `--append-system-prompt`
 2. Loads Mosaic skills via `--skill` flags
-3. Loads the Mosaic extension via `--extension` for lifecycle hooks
+3. Loads framework-owned `mosaic-extension.ts` and `goal-extension.ts` from
   `~/.config/mosaic/runtime/pi/` via ordered `--extension` flags
 4. Detects active missions and injects initial prompts
 ## Capabilities vs Other Runtimes
@@ -22,6 +23,7 @@ Pi is the native Mosaic agent runtime. The `mosaic pi` launcher:
 - Native thinking levels replace sequential-thinking MCP
 - Native skill discovery compatible with Mosaic SKILL.md format
 - Native extension system for lifecycle hooks (TypeScript, not bash shims)
 - Bounded persistent `/goal` loop with per-turn, post-compaction, and two-pass evidence checks
 - Native session persistence and resume
 - Model-agnostic (Anthropic, OpenAI, Google, Ollama, custom providers)
@@ -94,7 +94,14 @@ The launcher:
 1. Verifies `~/.config/mosaic` exists
 2. Verifies `SOUL.md` exists (auto-runs `mosaic init` if missing)
 3. Injects `AGENTS.md` into the runtime
-4. Forwards all arguments to the runtime CLI
+4. For Pi, loads the framework-owned core and persistent-goal extensions from
   `~/.config/mosaic/runtime/pi/`
 5. Forwards all arguments to the runtime CLI
 Inside `mosaic pi`, `/goal set <statement>` starts a bounded persistent goal loop. Use `/goal status`,
 `/goal pause`, `/goal resume`, or `/goal cancel` to control it. The extension remains part of Mosaic
 under `~/.config/mosaic/runtime/pi/goal-extension.ts`; it is not installed in Pi's main extension
 directory.
 You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtime adapters will tell the agent to read `~/.config/mosaic/AGENTS.md`.
@@ -114,7 +121,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 │   ├── claude/            ← CLAUDE.md, RUNTIME.md, settings.json, hooks
 │   ├── codex/             ← instructions.md, RUNTIME.md
 │   ├── opencode/          ← AGENTS.md, RUNTIME.md
-│   ├── pi/                ← RUNTIME.md, mosaic-extension.ts
+│   ├── pi/                ← RUNTIME.md, mosaic-extension.ts, goal-extension.ts
 │   └── mcp/               ← MCP server configs
 ├── skills/                ← Universal skills (synced from mosaic/agent-skills)
 ├── skills-local/          ← Local cross-runtime skills
@@ -126,7 +133,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 | Launch method       | Injection mechanism                                                                       |
 | ------------------- | ----------------------------------------------------------------------------------------- |
-| `mosaic pi`         | `--append-system-prompt` with composed runtime contract + skills + extension              |
+| `mosaic pi`         | `--append-system-prompt` with composed runtime contract + skills + Mosaic extensions      |
 | `mosaic claude`     | `--append-system-prompt` with composed runtime contract (`AGENTS.md` + runtime reference) |
 | `mosaic codex`      | Writes composed runtime contract to `~/.codex/instructions.md` before launch              |
 | `mosaic opencode`   | Writes composed runtime contract to `~/.config/opencode/AGENTS.md` before launch          |
@@ -52,6 +52,52 @@ If a repo does not expose these scripts, run equivalent local workflow commands
 - Do not auto-resolve data conflicts in shared state files.
 - Keep commits scoped to a single logical change set.
 ## Model Tiering
 Model choice is a standard, not a preference. Delegating a mechanical grep to a
 frontier reasoning model wastes budget; sending a security review to a cheap tier
 produces a review that passes and proves nothing. Both are defects.
 Tiers are named by **capability class**, so the standard survives a model
 generation. An operator binds each class to a concrete model id.
 | Class         | Use for                                                                                   |
 | ------------- | ----------------------------------------------------------------------------------------- |
 | `search`      | grep/glob, file location, status and health checks, one-line mechanical edits             |
 | `build`       | feature implementation, test writing, bugfixes, routine refactors                         |
 | `judge`       | code review, planning, API/compat-sensitive changes                                       |
 | `adversarial` | security review, ambiguous architecture, anything where a wrong "looks fine" is expensive |
 Rules:
 1. **Start at the cheapest class that can do the task; escalate on evidence, not
   on nerves.** Omitting a tier is not neutral — it inherits the caller's model,
   which is usually the most expensive one.
 2. **Compat-sensitive work escalates one class.** A change that must interoperate
   with an existing contract is judged, not just built.
 3. **A tier assignment is benchmarked, not asserted.** Move a task class to a
   cheaper tier only against a blind A/B on real work from this codebase, ranked
   by someone other than the author. "It seemed fine" is not evidence.
 4. **Reviewer independence beats reviewer size.** An `adversarial` verdict from
   the model that wrote the code is not a second opinion (see Constitution gate 16).
 ### Where the binding lives
 The class→model map is operator configuration, never framework source: model
 availability, cost, and quotas differ per operator and per host.
 Resolution order, first hit wins:
 1. the config service (DB-backed, surfaced and editable in the Mosaic webUI)
 2. a local operator file (`STANDARDS.local.md`, or `policy/` where the runtime
   injects it)
 3. the framework default — the class names above, with no binding
 Only layer 1 is auditable across a fleet, so it is the target end state; layers 2
 and 3 exist so a host with no config service still runs. A local override that
 silently disagrees with the config service is drift — the same failure class the
 tool-index gate exists to catch, and it belongs in `mosaic doctor`.
 ## Prompting Contract
 All runtime adapters should inject:
@@ -11,22 +11,105 @@ All tool suites are located at `~/.config/mosaic/tools/`.
 Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
 This index is complete and is kept complete mechanically: `tools/quality/scripts/check-tools-index.sh`
 fails CI when a wrapper ships without an entry here, or when an entry here names a wrapper that no
 longer exists. A wrapper missing from this list is, from inside an agent session, indistinguishable
 from a wrapper that was never written — which is how the APPROVE/APPROVED incident below happened.
 Every command takes `--help`. All of them accept `--login <account>` to pin the acting identity;
 supply it explicitly on any host where the provider CLI's default account is an admin.
 | Issues             |                                   |
 | ------------------ | --------------------------------- |
 | `issue-create.sh`  | Create an issue (Gitea or GitHub) |
 | `issue-view.sh`    | Show one issue                    |
 | `issue-list.sh`    | List issues                       |
 | `issue-edit.sh`    | Edit title/body/labels/milestone  |
 | `issue-comment.sh` | Add a comment                     |
 | `issue-assign.sh`  | Assign or unassign                |
 | `issue-close.sh`   | Close an issue                    |
 | `issue-reopen.sh`  | Reopen a closed issue             |
 | Pull requests    |                                                           |
 | ---------------- | --------------------------------------------------------- |
 | `pr-create.sh`   | Open a pull request                                       |
 | `pr-view.sh`     | Show one PR                                               |
 | `pr-list.sh`     | List PRs                                                  |
 | `pr-diff.sh`     | Fetch a PR's diff                                         |
 | `pr-metadata.sh` | PR metadata as JSON (head SHA, base, state, mergeability) |
 | `pr-review.sh`   | **Place a review verdict — see the dialect note below**   |
 | `pr-ci-wait.sh`  | Block until the PR's CI reaches a terminal state          |
 | `pr-merge.sh`    | Merge a PR                                                |
 | `pr-close.sh`    | Close a PR without merging                                |
 | Milestones            |                    |
 | --------------------- | ------------------ |
 | `milestone-create.sh` | Create a milestone |
 | `milestone-list.sh`   | List milestones    |
 | `milestone-close.sh`  | Close a milestone  |
 | Gates and guards        |                                                                                                           |
 | ----------------------- | --------------------------------------------------------------------------------------------------------- |
 | `ci-queue-wait.sh`      | CI queue guard — required before push/merge (see below)                                                   |
 | `push-guard.sh`         | Refuse verifications that pass for the wrong reason (e.g. green against an unpushed tree)                 |
 | `mutate-push-guard.sh`  | Regenerate the guard's mutation-coverage table from measurement, so the table cannot drift from the guard |
 | `verify-clean-clone.sh` | Prove the **committed** artifact runs, from a clean clone — not the working tree                          |
 | Context              |                                                                                          |
 | -------------------- | ---------------------------------------------------------------------------------------- |
 | `detect-platform.sh` | Resolve the provider (Gitea vs GitHub) for the current repo; every other wrapper uses it |
 | `lane-brief.sh`      | Live dispatch brief for a repo "lane" (milestone/label) straight from the provider       |
 | Workspace            |                                                                          |
 | -------------------- | ------------------------------------------------------------------------ |
 | `mosaic-worktree.sh` | Create/list/remove git worktrees — **the only supported way**; see below |
 | `wrapper-guard.sh`   | PreToolUse hook that enforces the two rules above; not called by hand    |
 **Workspace placement is derived, not chosen.** `mosaic-worktree.sh new <branch>` takes a branch
 name and nothing else. Every path comes out of `git worktree list --porcelain` — main worktree,
 repo name, parent dir, then `<parent>/<repo>-worktrees/<branch-slug>`. There is no placement flag
 because a decision an agent has to make is a decision that drifts: the rule "big work goes on a work
 filesystem" already existed in prose and 255 GB accumulated in `$HOME` across 842 directories
 anyway, under five simultaneous conventions on a single host.
 ```bash
-# Issues
+~/.config/mosaic/tools/git/mosaic-worktree.sh new <branch> [--from <base>]
-~/.config/mosaic/tools/git/issue-create.sh
+~/.config/mosaic/tools/git/mosaic-worktree.sh path <branch>   # derived path, no side effect
-~/.config/mosaic/tools/git/issue-close.sh
+~/.config/mosaic/tools/git/mosaic-worktree.sh list            # this repo's worktrees + state
 ~/.config/mosaic/tools/git/mosaic-worktree.sh rm <branch>     # removal is part of the task
 ~/.config/mosaic/tools/git/mosaic-worktree.sh gc [--apply]    # reclaim clean + fully-pushed ones
 ```
-# PRs
+Worktrees rather than clones, because `git worktree list` makes every checkout enumerable — a bare
-~/.config/mosaic/tools/git/pr-create.sh
+clone dropped somewhere on disk can never be safely reclaimed, so it is never reclaimed. `rm` and
-~/.config/mosaic/tools/git/pr-merge.sh
+`gc` decide by **evidence, never by size or age**: a worktree is reclaimable only when
 `git status --porcelain` is empty _and_ `git rev-list --count HEAD --not --remotes` is 0. Anything
 else is preserved and reported. `--force` exists and is yours to type deliberately.
-# Milestones
+`wrapper-guard.sh` is registered as a Claude Code `PreToolUse` hook on `Bash` (see
-~/.config/mosaic/tools/git/milestone-create.sh
+`runtime/claude/settings.json`). It blocks exactly three things and lets everything else through:
 a `git clone`/`git worktree add` targeting `$HOME`; a raw provider-API **write** to an endpoint that
 already has a wrapper above (reads are untouched — they are how you gather evidence); and the
 literal `"event": "APPROVE"`. For a genuine gap no wrapper can express, prefix
 `MOSAIC_WRAPPER_OVERRIDE=1`. Reaching for the override twice for the same call means the wrapper has
 a missing flag — extend the wrapper.
 ```bash
 ~/.config/mosaic/tools/git/issue-create.sh --help
 ~/.config/mosaic/tools/git/pr-review.sh --pr 42 --event APPROVED --body "..."
 # CI queue guard (required before push/merge; defaults to the checked-out branch)
 ~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
 ```
 **Review dialect — the reason `pr-review.sh` is not optional.** Gitea's approve event is
 `APPROVED`; GitHub's is `APPROVE`. Send GitHub's spelling to a Gitea host and it answers **HTTP
 200**, files the review as PENDING, and then rejects the submit with `422 review stay pending` — the
 verdict looks placed and is not. (`REQUEST_CHANGES` is spelled identically on both, so only the
 approve path carries the trap.) `pr-review.sh` sends the correct token for the detected provider.
 Whatever you use, re-read `GET /pulls/{n}/reviews` and assert the state before reporting a verdict
 placed.
 The guard exits nonzero for any provider-asserted non-green, missing, or malformed CI state. If credentials or the provider are unavailable, it emits `CANNOT_ASSERT` and writes a JSONL audit record. Push degrades to exit 0 so recovery work is not bricked; merge holds with retryable exit 75 until the provider recovers, then self-clears without manual reset. Neither outcome is evidence that CI was clear. `pr-merge.sh` automatically inspects the exact PR head repository and full commit SHA rather than its `main` base; this also handles fork PRs without branch-name ambiguity. Pass `--expect-head <approved-full-sha>` to bind a commit-specific review or merge-gate verdict; Gitea uses atomic `head_commit_id` and GitHub uses `--match-head-commit`.
 ### Code Review (Codex)
@@ -52,6 +52,16 @@
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.config/mosaic/tools/git/wrapper-guard.sh",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
@@ -51,12 +51,26 @@ Skills are discovered from:
 ### Extensions
-The Mosaic Pi extension (`~/.config/mosaic/runtime/pi/mosaic-extension.ts`) handles:
+`mosaic pi` loads framework-owned extensions directly from `~/.config/mosaic/runtime/pi/` in this
 order:
- Session start/end lifecycle hooks
+1. `mosaic-extension.ts` — session lifecycle, mission context, memory routing, lease/mutator gates,
- Active mission detection and context injection
+   and fleet heartbeat reporting.
- Memory routing to `~/.config/mosaic/memory/`
+2. `goal-extension.ts` — optional persistent `/goal` controller with per-turn and post-compaction
- MACP queue status reporting
+   checks.
 The goal extension is deployed by Mosaic and MUST NOT be copied into `~/.pi/agent/extensions/`.
 Use `/goal set <statement>` (or `/goal <statement>`) to start, then `/goal status`, `/goal pause`,
 `/goal resume`, or `/goal cancel` to control it. An active goal is injected before every model
 request, restored from branch-specific session entries, and considered achieved only after two
 consecutive evidence-bearing reports. Common credential shapes are redacted before controller-owned
 goal-state entries are persisted or
 displayed; Pi's own model/tool-call history is separate. Goals and reports must contain references
 and pass/fail summaries rather than secrets or raw sensitive output.
 - `MOSAIC_GOAL_MAX_TURNS` — autonomous turn limit, default `40`, accepted range `1..500`.
 - `MOSAIC_GOAL_MAX_NO_PROGRESS` — identical no-progress report limit, default `6`, accepted range
  `1..100`.
 ### Sessions
@@ -66,7 +66,10 @@ if command -v tmux >/dev/null 2>&1 && command -v cc >/dev/null 2>&1; then
  trap 'tmux -L "$TEST_SOCKET" kill-server >/dev/null 2>&1 || true; rm -rf "$TEST_ROOT"' EXIT
  MARKER="$TEST_ROOT/loader-marker"
  LIBRARY="$TEST_ROOT/marker.so"
  FIXTURE_READY="$TEST_ROOT/loader-ready"
  FIXTURE_FIFO="$TEST_ROOT/loader-block"
  HOLDER_HOME="$TEST_ROOT/holder-home"
  mkfifo "$FIXTURE_FIFO"
  mkdir -p "$HOLDER_HOME/.config/mosaic/fleet/run"
  chmod 700 "$HOLDER_HOME/.config" "$HOLDER_HOME/.config/mosaic" \
    "$HOLDER_HOME/.config/mosaic/fleet" "$HOLDER_HOME/.config/mosaic/fleet/run"
@@ -87,7 +90,17 @@ __attribute__((constructor)) static void mark_loader(void) {
 EOF
  cc -shared -fPIC -o "$LIBRARY" "$TEST_ROOT/marker.c"
  MOSAIC_LOADER_MARKER="$MARKER" LD_PRELOAD="$LIBRARY" \
-    tmux -L "$TEST_SOCKET" new-session -d -s _holder 'sleep 60'
+    tmux -L "$TEST_SOCKET" new-session -d -s _holder \
      "touch '$FIXTURE_READY'; read _ < '$FIXTURE_FIFO'"
  # tmux starts the pane asynchronously. Wait until its contaminated shell has
  # loaded the constructor and reached a builtin-only FIFO barrier before
  # clearing the marker; otherwise that expected constructor can race with the
  # clean holder assertion below and create a false failure.
  for _attempt in {1..100}; do
    [ -e "$FIXTURE_READY" ] && break
    sleep 0.01
  done
  [ -e "$FIXTURE_READY" ] || fail "contaminated fixture pane did not become ready"
  [ -s "$MARKER" ] || fail "contaminated fixture did not execute loader constructor"
  server_pid=$(tmux -L "$TEST_SOCKET" display-message -p '#{pid}')
  : > "$MARKER"
@@ -112,6 +125,7 @@ EOF
  chmod 700 "$AGENT_HOME/fleet/agents"
  cat > "$AGENT_HOME/fleet/agents/$AGENT_NAME.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$AGENT_NAME
 MOSAIC_GIT_IDENTITY=$AGENT_NAME
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=
@@ -144,7 +158,8 @@ EOF
  /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin \
    MOSAIC_TMUX_SOCKET="$TEST_SOCKET" MOSAIC_TMUX_HOLDER=_holder "$HOLDER_START"
  tmux -L "$TEST_SOCKET" has-session -t '=_holder:0.0' || fail "fresh holder was not created"
-  if tmux -L "$TEST_SOCKET" show-environment -g LD_PRELOAD 2>/dev/null | grep -q '^LD_PRELOAD='; then
+  ld_preload_env="$(tmux -L "$TEST_SOCKET" show-environment -g LD_PRELOAD 2>/dev/null)" || true
  if grep -q '^LD_PRELOAD=' <<<"$ld_preload_env"; then
    fail "fresh holder retained LD_PRELOAD"
  fi
  /usr/bin/env -i HOME="$HOLDER_HOME" PATH=/usr/bin:/bin MOSAIC_HOME="$AGENT_HOME" \
@@ -69,7 +69,7 @@ if [[ -n "$GROUP" ]]; then
  group_response=$(curl -sk \
    -H "Authorization: Bearer $TOKEN" \
    "${AUTHENTIK_URL}/api/v3/core/groups/?search=${GROUP}")
-  group_pk=$(echo "$group_response" | jq -r ".results[] | select(.name == \"$GROUP\") | .pk" | head -1)
+  group_pk=$(jq -r "first(.results[] | select(.name == \"$GROUP\") | .pk) // empty" <<<"$group_response")
  if [[ -n "$group_pk" ]]; then
    payload=$(echo "$payload" | jq --arg gk "$group_pk" '. + {groups: [$gk]}')
  else
@@ -97,7 +97,7 @@ is_sensitive_key() {
 is_generated_key() {
  case "$1" in
-    MOSAIC_AGENT_NAME|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
+    MOSAIC_AGENT_NAME|MOSAIC_GIT_IDENTITY|MOSAIC_AGENT_CLASS|MOSAIC_AGENT_RUNTIME|MOSAIC_AGENT_MODEL|MOSAIC_AGENT_REASONING|MOSAIC_AGENT_TOOL_POLICY|MOSAIC_AGENT_WORKDIR|MOSAIC_TMUX_SOCKET) return 0 ;;
    *) return 1 ;;
  esac
 }
@@ -114,6 +114,7 @@ validate_generated_value() {
  local value="$2"
  case "$key" in
    MOSAIC_AGENT_NAME) safe_agent_name "$value" || fail_env unsafe-agent-name "$key" "$value" ;;
    MOSAIC_GIT_IDENTITY) safe_agent_name "$value" || fail_env unsafe-git-identity "$key" "$value" ;;
    MOSAIC_AGENT_CLASS) safe_policy_name "$value" || fail_env unsafe-class "$key" "$value" ;;
    MOSAIC_AGENT_RUNTIME)
      case "$value" in claude|codex|opencode|pi) ;; *) fail_env unsupported-runtime "$key" "$value" ;; esac
@@ -175,7 +176,7 @@ load_environment_file() {
 load_environment_file "$GENERATED_ENV" generated
 for required_key in \
-  MOSAIC_AGENT_NAME MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
+  MOSAIC_AGENT_NAME MOSAIC_GIT_IDENTITY MOSAIC_AGENT_CLASS MOSAIC_AGENT_RUNTIME MOSAIC_AGENT_MODEL \
  MOSAIC_AGENT_REASONING MOSAIC_AGENT_TOOL_POLICY MOSAIC_AGENT_WORKDIR MOSAIC_TMUX_SOCKET; do
  [ -n "${GENERATED_VALUES[$required_key]+set}" ] || fail_env missing-key "$required_key" ''
 done
@@ -183,12 +184,15 @@ load_environment_file "$LOCAL_ENV" local
 [ "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}" = "$AGENT_NAME" ] || \
  fail_env agent-name-mismatch MOSAIC_AGENT_NAME "${GENERATED_VALUES[MOSAIC_AGENT_NAME]}"
 [ "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}" = "$AGENT_NAME" ] || \
  fail_env git-identity-mismatch MOSAIC_GIT_IDENTITY "${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}"
 MOSAIC_TMUX_SOCKET=${GENERATED_VALUES[MOSAIC_TMUX_SOCKET]}
 MOSAIC_AGENT_RUNTIME=${GENERATED_VALUES[MOSAIC_AGENT_RUNTIME]}
 MOSAIC_AGENT_MODEL=${GENERATED_VALUES[MOSAIC_AGENT_MODEL]}
 MOSAIC_AGENT_REASONING=${GENERATED_VALUES[MOSAIC_AGENT_REASONING]}
 MOSAIC_AGENT_WORKDIR=${GENERATED_VALUES[MOSAIC_AGENT_WORKDIR]}
 MOSAIC_GIT_IDENTITY=${GENERATED_VALUES[MOSAIC_GIT_IDENTITY]}
 MOSAIC_AGENT_CLASS=${GENERATED_VALUES[MOSAIC_AGENT_CLASS]}
 MOSAIC_AGENT_TOOL_POLICY=${GENERATED_VALUES[MOSAIC_AGENT_TOOL_POLICY]}
 MOSAIC_RUNTIME_BIN=${LOCAL_VALUES[MOSAIC_RUNTIME_BIN]:-}
@@ -343,6 +347,7 @@ LAUNCH_ENV=(
  "PATH=$PANE_PATH"
  "MOSAIC_HOME=$MOSAIC_HOME"
  "MOSAIC_AGENT_NAME=$AGENT_NAME"
  "MOSAIC_GIT_IDENTITY=$MOSAIC_GIT_IDENTITY"
  "MOSAIC_AGENT_CLASS=$MOSAIC_AGENT_CLASS"
  "MOSAIC_AGENT_RUNTIME=$MOSAIC_AGENT_RUNTIME"
  "MOSAIC_AGENT_MODEL=$MOSAIC_AGENT_MODEL"
@@ -14,6 +14,82 @@ fail() {
  exit 1
 }
 pane_command_clears_environment() {
  local calls_file="$1"
  local -a argv=()
  local index
  mapfile -d '' -t argv < "$calls_file"
  for ((index = 0; index + 1 < ${#argv[@]}; index++)); do
    if [ "${argv[$index]}" = /usr/bin/env ] && [ "${argv[$((index + 1))]}" = -i ]; then
      return 0
    fi
  done
  return 1
 }
 print_pane_argv() {
  local calls_file="$1"
  local -a argv=()
  local bytes index
  mapfile -d '' -t argv < "$calls_file"
  bytes=$(wc -c < "$calls_file")
  printf 'observed pane argv: records=%s bytes=%s\n' "${#argv[@]}" "$bytes" >&2
  for ((index = 0; index < ${#argv[@]}; index++)); do
    printf '  [%03d] %q\n' "$index" "${argv[$index]}" >&2
  done
 }
 check_pane_environment_boundary() {
  local calls_file="$1"
  if pane_command_clears_environment "$calls_file"; then
    return 0
  fi
  print_pane_argv "$calls_file"
  return 1
 }
 contains_literal() {
  grep -F -- "$2" <<< "$1" >/dev/null
 }
 contains_line() {
  grep -xF -- "$2" <<< "$1" >/dev/null
 }
 # Portability regression: inspect the authoritative NUL-delimited argv instead
 # of piping a newline reconstruction through `grep -q` under pipefail. The old
 # pipeline could report failure after a successful match when an upstream
 # producer received SIGPIPE. A large trailing argument keeps that failure class
 # covered without making stream size part of the semantic contract.
 PORTABILITY_CALLS="$ROOT/portability-calls"
 printf -v PORTABILITY_PADDING '%*s' 32768 ''
 PORTABILITY_PADDING=${PORTABILITY_PADDING// /x}
 printf '%s\0' /usr/bin/env -i "$PORTABILITY_PADDING" > "$PORTABILITY_CALLS"
 pane_command_clears_environment "$PORTABILITY_CALLS" || \
  fail "valid large pane argv was rejected by the environment-boundary assertion"
 assert_pane_boundary_rejected() {
  local case_name="$1"
  local expected_records="$2"
  local diagnostic
  if diagnostic=$(check_pane_environment_boundary "$PORTABILITY_CALLS" 2>&1); then
    fail "pane boundary accepted invalid $case_name fixture"
  fi
  contains_literal "$diagnostic" "records=$expected_records bytes=" || \
    fail "pane argv diagnostic omitted counts for $case_name fixture"
  contains_literal "$diagnostic" '[000]' || \
    fail "pane argv diagnostic omitted indexed arguments for $case_name fixture"
 }
 printf '%s\0' tmux -i > "$PORTABILITY_CALLS"
 assert_pane_boundary_rejected missing-env 2
 printf '%s\0' /usr/bin/env HOME=/untrusted > "$PORTABILITY_CALLS"
 assert_pane_boundary_rejected missing-i 2
 printf '%s\0' /usr/bin/env HOME=/untrusted -i > "$PORTABILITY_CALLS"
 assert_pane_boundary_rejected non-adjacent-i 3
 printf '%s\0' -i /usr/bin/env > "$PORTABILITY_CALLS"
 assert_pane_boundary_rejected reversed-boundary 2
 cat > "$FAKE_BIN/tmux" <<'SHIM'
 #!/usr/bin/env bash
 set -euo pipefail
@@ -62,6 +138,19 @@ env -0 > "${MOSAIC_HOME:?}/fleet/pane-environment"
 SHIM
 chmod +x "$FAKE_BIN/mosaic"
 # Freeze numeric epoch reads only when a test arm supplies an observation bound.
 # Formatting reads still use the real BusyBox/POSIX date implementation.
 cat > "$FAKE_BIN/date" <<'SHIM'
 #!/usr/bin/env bash
 set -euo pipefail
 if [ -n "${MOSAIC_TEST_FIXED_EPOCH:-}" ] && [ "${1:-}" = '+%s' ]; then
  printf '%s\n' "$MOSAIC_TEST_FIXED_EPOCH"
  exit 0
 fi
 exec /bin/date "$@"
 SHIM
 chmod +x "$FAKE_BIN/date"
 write_generated() {
  local home="$1"
  local agent="$2"
@@ -71,6 +160,7 @@ write_generated() {
  chmod 600 "$home/fleet/run/holder-owner"
  cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
 MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=code
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol
@@ -88,6 +178,7 @@ run_start() {
  local agent="$2"
  HOME="$home" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
    MOSAIC_TEST_PANE_PID="${MOSAIC_TEST_PANE_PID:-}" \
    MOSAIC_TEST_FIXED_EPOCH="${MOSAIC_TEST_FIXED_EPOCH:-}" \
    MOSAIC_TEST_HOME="$home" \
    MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
    MOSAIC_HOME="$home" "$START" "$agent"
@@ -100,19 +191,55 @@ AGENT_VALID="coder0"
 write_generated "$HOME_VALID" "$AGENT_VALID"
 run_start "$HOME_VALID" "$AGENT_VALID"
 valid_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$valid_args" | grep -qF new-session || fail "valid generated projection did not reach tmux"
+contains_literal "$valid_args" new-session || fail "valid generated projection did not reach tmux"
-echo "$valid_args" | grep -qF 'mosaic' || fail "fixed mosaic launcher command missing"
+contains_literal "$valid_args" mosaic || fail "fixed mosaic launcher command missing"
-echo "$valid_args" | grep -qF 'yolo' || fail "fixed yolo launcher command missing"
+contains_literal "$valid_args" yolo || fail "fixed yolo launcher command missing"
-echo "$valid_args" | grep -qF 'pi' || fail "roster runtime missing"
+contains_literal "$valid_args" pi || fail "roster runtime missing"
-if echo "$valid_args" | grep -qF 'bash -c'; then
+if contains_literal "$valid_args" 'bash -c'; then
  fail "launcher constructed a shell command payload"
 fi
 # The pane must start through an absolute clean-environment boundary. Its
 # runtime command remains an argv vector, but no holder/session environment
 # control variable can pass through the pane command.
-echo "$valid_args" | grep -qxF '/usr/bin/env' || fail "pane does not use absolute env"
+check_pane_environment_boundary "$TMUX_CALLS" || \
-echo "$valid_args" | grep -qxF -- '-i' || fail "pane environment is not cleared"
+  fail "pane command did not use an adjacent /usr/bin/env -i boundary"
 # Git identity is generated authority, not an optional or independently mutable
 # local value. Each invalid form must fail before fake tmux receives a call.
 assert_git_identity_rejected() {
  local case_name="$1"
  local expected_code="$2"
  local home="$ROOT/git-identity-$case_name"
  local agent="coder-git-identity-$case_name"
  local generated="$home/fleet/agents/$agent.env.generated"
  write_generated "$home" "$agent"
  case "$case_name" in
    missing) grep -v '^MOSAIC_GIT_IDENTITY=' "$generated" > "$generated.next" && mv "$generated.next" "$generated" ;;
    unsafe) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=bad/identity|' "$generated" ;;
    mismatch) sed -i 's|^MOSAIC_GIT_IDENTITY=.*$|MOSAIC_GIT_IDENTITY=other-agent|' "$generated" ;;
    local-shadow)
      printf 'MOSAIC_GIT_IDENTITY=%s\n' "$agent" > "$home/fleet/agents/$agent.env.local"
      chmod 600 "$home/fleet/agents/$agent.env.local"
      ;;
    *) fail "unknown Git identity rejection case: $case_name" ;;
  esac
  chmod 600 "$generated"
  : > "$TMUX_CALLS"
  if output=$(run_start "$home" "$agent" 2>&1); then
    fail "Git identity case $case_name was accepted"
  fi
  [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before Git identity $case_name rejection"
  contains_literal "$output" "code=$expected_code" || \
    fail "Git identity $case_name diagnostic omitted code $expected_code"
 }
 assert_git_identity_rejected missing missing-key
 assert_git_identity_rejected unsafe unsafe-git-identity
 assert_git_identity_rejected mismatch git-identity-mismatch
 assert_git_identity_rejected local-shadow generated-key-shadow
 # The generated-file parent is a security boundary too: even a private regular
 # file is untrusted if its parent can be replaced or written by another user.
@@ -125,7 +252,7 @@ if output=$(run_start "$HOME_UNSAFE_PARENT" coder-parent 2>&1); then
  fail "generated file under a world-writable parent was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before unsafe parent rejection"
-echo "$output" | grep -qF 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
+contains_literal "$output" 'code=unsafe-permissions' || fail "unsafe parent diagnostic missing"
 : > "$TMUX_CALLS"
 HOME_SYMLINK_PARENT="$ROOT/symlink-parent"
@@ -136,7 +263,7 @@ if output=$(run_start "$HOME_SYMLINK_PARENT" coder-symlink-parent 2>&1); then
  fail "generated file under a symlinked parent was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before symlinked parent rejection"
-echo "$output" | grep -qF 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
+contains_literal "$output" 'code=unsafe-directory' || fail "symlinked parent diagnostic missing"
 # Every managed ancestor is a boundary: MOSAIC_HOME, fleet, and agents. A
 # symlink or group/world-writable ancestor must fail before environment parsing,
@@ -174,8 +301,8 @@ assert_managed_ancestor_rejected() {
  fi
  [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before $hazard $ancestor rejection"
  [ ! -e "$home/work" ] || fail "workdir was created before $hazard $ancestor rejection"
-  echo "$output" | grep -qF "code=unsafe-" || fail "managed ancestor diagnostic missing"
+  contains_literal "$output" 'code=unsafe-' || fail "managed ancestor diagnostic missing"
-  if echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND'; then
+  if contains_literal "$output" 'key=MOSAIC_AGENT_COMMAND'; then
    fail "environment parsing ran before $hazard $ancestor rejection"
  fi
 }
@@ -196,9 +323,9 @@ if output=$(run_start "$HOME_SHADOW" coder1 2>&1); then
  fail "generated-key shadow was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before generated-key shadow rejection"
-echo "$output" | grep -qF 'key=MOSAIC_AGENT_RUNTIME' || fail "shadow diagnostic omitted key"
+contains_literal "$output" 'key=MOSAIC_AGENT_RUNTIME' || fail "shadow diagnostic omitted key"
-echo "$output" | grep -qF 'sha256=' || fail "shadow diagnostic omitted hash"
+contains_literal "$output" 'sha256=' || fail "shadow diagnostic omitted hash"
-if echo "$output" | grep -qF 'codex'; then
+if contains_literal "$output" codex; then
  fail "shadow diagnostic leaked value"
 fi
@@ -214,9 +341,9 @@ if output=$(run_start "$HOME_COMMAND" coder2 2>&1); then
  fail "arbitrary command override was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before command rejection"
-echo "$output" | grep -qF 'key=MOSAIC_AGENT_COMMAND' || fail "command diagnostic omitted key"
+contains_literal "$output" 'key=MOSAIC_AGENT_COMMAND' || fail "command diagnostic omitted key"
-echo "$output" | grep -qF 'sha256=' || fail "command diagnostic omitted hash"
+contains_literal "$output" 'sha256=' || fail "command diagnostic omitted hash"
-if echo "$output" | grep -qF "$COMMAND_VALUE"; then
+if contains_literal "$output" "$COMMAND_VALUE"; then
  fail "command diagnostic leaked command value"
 fi
@@ -230,7 +357,7 @@ if output=$(run_start "$HOME_PERMS" coder3 2>&1); then
  fail "world-readable local input was accepted"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before permissions rejection"
-echo "$output" | grep -qF 'code=unsafe-permissions' || fail "permission diagnostic missing"
+contains_literal "$output" 'code=unsafe-permissions' || fail "permission diagnostic missing"
 # A unit/holder-like clean bootstrap must yield a pane with trusted HOME and
 # computed PATH only. The pane command itself must not carry loader, shell
@@ -260,25 +387,35 @@ PATH="$PANE_STALE_PATH" \
    MOSAIC_TEST_EXECUTE_PANE=1 \
    "$START" coder-pane-boundary
 pane_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$pane_args" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
+contains_line "$pane_args" "HOME=$PANE_TRUSTED_HOME" || \
  fail "pane did not restore trusted HOME"
-echo "$pane_args" | grep -qF "HOME=$PANE_STALE_HOME" && \
+contains_literal "$pane_args" "HOME=$PANE_STALE_HOME" && \
  fail "pane inherited stale HOME"
-echo "$pane_args" | grep -qF "$PANE_STALE_PATH" && fail "pane inherited stale PATH"
+contains_literal "$pane_args" "$PANE_STALE_PATH" && fail "pane inherited stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
-  echo "$pane_args" | grep -qF "$blocked" && fail "pane inherited $blocked"
+  contains_literal "$pane_args" "$blocked" && fail "pane inherited $blocked"
 done
-after_pane_env=$(printf '%s\n' "$pane_args" | grep -n -m1 -F '/usr/bin/env' | cut -d: -f1)
+check_pane_environment_boundary "$TMUX_CALLS" || \
-[ -n "$after_pane_env" ] || fail "pane command did not use absolute env"
+  fail "pane command did not use an adjacent /usr/bin/env -i boundary"
 printf '%s\n' "$pane_args" | tail -n +"$after_pane_env" | grep -qxF -- '-i' || \
  fail "pane command did not clear its environment"
 pane_environment=$(tr '\0' '\n' < "$HOME_PANE_BOUNDARY/fleet/pane-environment")
-echo "$pane_environment" | grep -qxF "HOME=$PANE_TRUSTED_HOME" || \
+# Exercise the repository launcher at $START, not the independently installed
 # host copy. Set-compare every declared generated projection entry with the
 # launched process environment so a newly declared identity cannot be omitted
 # by a hand-maintained per-variable assertion.
 declared_generated_environment=$(sort "$HOME_PANE_BOUNDARY/fleet/agents/coder-pane-boundary.env.generated")
 missing_or_changed_generated_environment=$(comm -23 \
  <(printf '%s\n' "$declared_generated_environment") \
  <(printf '%s\n' "$pane_environment" | sort))
 if [ -n "$missing_or_changed_generated_environment" ]; then
  missing_or_changed_keys=$(printf '%s\n' "$missing_or_changed_generated_environment" | cut -d= -f1 | paste -sd, -)
  fail "runtime pane omitted or changed generated environment keys: $missing_or_changed_keys"
 fi
 contains_line "$pane_environment" "HOME=$PANE_TRUSTED_HOME" || \
  fail "runtime pane did not receive trusted HOME"
-echo "$pane_environment" | grep -qF "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
+contains_literal "$pane_environment" "$PANE_STALE_PATH" && fail "runtime pane received stale PATH"
 for blocked in LD_PRELOAD= BASH_ENV= MOSAIC_UNTRUSTED_SENTINEL=; do
-  echo "$pane_environment" | grep -qF "$blocked" && fail "runtime pane received $blocked"
+  contains_literal "$pane_environment" "$blocked" && fail "runtime pane received $blocked"
 done
 write_interaction_generated() {
@@ -290,6 +427,7 @@ write_interaction_generated() {
  chmod 600 "$home/fleet/run/holder-owner"
  cat > "$home/fleet/agents/$agent.env.generated" <<EOF
 MOSAIC_AGENT_NAME=$agent
 MOSAIC_GIT_IDENTITY=$agent
 MOSAIC_AGENT_CLASS=operator-interaction
 MOSAIC_AGENT_RUNTIME=pi
 MOSAIC_AGENT_MODEL=openai/gpt-5.6-sol
@@ -352,8 +490,12 @@ write_generated "$HOME_NATIVE_STALE" "coder-native-stale"
 write_heartbeat_local "$HOME_NATIVE_STALE" "coder-native-stale"
 STALE_HB="$HOME_NATIVE_STALE/run/coder-native-stale.hb"
 printf 'ts=native\npid=1\nstatus=busy\nmodel=stale-model\n' > "$STALE_HB"
-touch -d '10 seconds ago' "$STALE_HB.native"
+touch -t 200001010000.00 "$STALE_HB.native"
-MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
+# Hold the sidecar's observation epoch constant: assertion runtime must not age
 # a fresh-marker mutant into the stale state that this fixture must distinguish.
 STALE_OBSERVATION_EPOCH=$(date +%s)
 MOSAIC_TEST_FIXED_EPOCH="$STALE_OBSERVATION_EPOCH" \
  MOSAIC_TEST_PANE_PID=$$ run_start "$HOME_NATIVE_STALE" coder-native-stale
 wait_for_sidecar_status "$STALE_HB"
 HOME_NATIVE_ABSENT="$ROOT/native-absent"
@@ -374,22 +516,22 @@ if output=$(run_interaction "$HOME_INTERACTION_MALFORMED" interaction-malformed
  fail "interaction wrapper accepted malformed generated data"
 fi
 [ ! -s "$TMUX_CALLS" ] || fail "tmux ran before interaction strict-parser rejection"
-echo "$output" | grep -qF 'code=unknown-key' || fail "interaction did not use shared strict parser first"
+contains_literal "$output" 'code=unknown-key' || fail "interaction did not use shared strict parser first"
 # A syntactically valid but policy-incompatible projection reaches the pinned
 # interaction policy check only after strict parsing and never starts tmux.
 : > "$TMUX_CALLS"
 HOME_INTERACTION_POLICY="$ROOT/interaction-policy"
 write_interaction_generated "$HOME_INTERACTION_POLICY" "interaction-policy"
-perl -0pi -e 's/MOSAIC_AGENT_RUNTIME=pi/MOSAIC_AGENT_RUNTIME=codex/' \
+sed -i 's|^MOSAIC_AGENT_RUNTIME=pi$|MOSAIC_AGENT_RUNTIME=codex|' \
  "$HOME_INTERACTION_POLICY/fleet/agents/interaction-policy.env.generated"
 if output=$(run_interaction "$HOME_INTERACTION_POLICY" interaction-policy 2>&1); then
  fail "interaction wrapper accepted a policy-incompatible projection"
 fi
 interaction_policy_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$interaction_policy_args" | grep -qF 'new-session' && \
+contains_literal "$interaction_policy_args" new-session && \
  fail "interaction pinned-policy rejection created a tmux session"
-echo "$output" | grep -qF 'operator interaction service requires runtime pi' || \
+contains_literal "$output" 'operator interaction service requires runtime pi' || \
  fail "interaction pinned-policy check did not follow strict parsing"
 # Exact stop derives the socket exclusively from the validated generated
@@ -402,10 +544,10 @@ HOME="$HOME_STOP" PATH="$FAKE_BIN:$PATH" MOSAIC_TEST_TMUX_CALLS="$TMUX_CALLS" \
  MOSAIC_TEST_FLEET_OWNER=123e4567-e89b-12d3-a456-426614174000 \
  MOSAIC_HOME="$HOME_STOP" MOSAIC_TMUX_SOCKET=ambient-socket "$START" --stop coder-stop
 stop_args=$(tr '\0' '\n' < "$TMUX_CALLS")
-echo "$stop_args" | grep -qxF 'mosaic-test' || fail "exact stop did not use the validated generated socket"
+contains_line "$stop_args" mosaic-test || fail "exact stop did not use the validated generated socket"
-echo "$stop_args" | grep -qxF 'kill-session' || fail "exact stop did not request session termination"
+contains_line "$stop_args" kill-session || fail "exact stop did not request session termination"
-echo "$stop_args" | grep -qxF '=coder-stop' || fail "exact stop did not exact-match the generated agent name"
+contains_line "$stop_args" '=coder-stop' || fail "exact stop did not exact-match the generated agent name"
-if echo "$stop_args" | grep -qF 'ambient-socket'; then
+if contains_literal "$stop_args" ambient-socket; then
  fail "exact stop trusted an ambient socket"
 fi
@@ -5,7 +5,10 @@
 detect_platform() {
    local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
    # kills the CALLER before the -z check below can run, so the error message that is
    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
    remote_url=$(git remote get-url origin 2>/dev/null) || true
    if [[ -z "$remote_url" ]]; then
        echo "error: not a git repository or no origin remote" >&2
@@ -39,7 +42,10 @@ detect_platform() {
 get_repo_info() {
    local remote_url
-    remote_url=$(git remote get-url origin 2>/dev/null)
+    # `|| true` is load-bearing under `set -e`: outside a git repo this returns 128 and
    # kills the CALLER before the -z check below can run, so the error message that is
    # already written here was unreachable. Same idiom as get_gitea_repo_args() below.
    remote_url=$(git remote get-url origin 2>/dev/null) || true
    if [[ -z "$remote_url" ]]; then
        echo "error: not a git repository or no origin remote" >&2
@@ -240,6 +246,21 @@ PY
    } >&2
 }
 # Explain tea's most misleading failure. `user does not exist [uid: 0, name: ]` reads
 # as a missing account; it almost always means a REVOKED OR STALE TOKEN. `tea login`
 # keeps its OWN COPY of the token, so rotating the credential store does not update it.
 # Diagnostic only -- stderr, no control flow, no exit.
 explain_tea_user_does_not_exist() {
    cat >&2 <<'MSG'
 NOTE: `user does not exist [uid: 0, name: ]` from tea usually means a REVOKED OR STALE TOKEN,
      not a missing account. A `tea login` stores its OWN COPY of the token; rotating the
      credential store does NOT update it.
      CHECK: the login's cached copy (`tea login list` -- read the FULL table, never `| head`),
             then re-register that login against the current token.
      DO NOT probe capability with a mutating request; a POST is the action, not a check.
 MSG
 }
 get_gitea_login_for_host() {
    local host="${1:-}"
    local login
@@ -91,13 +91,32 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
    GITEA_LOGIN_NAME=$(get_gitea_login || true)
    if [[ -n "$GITEA_LOGIN_NAME" ]]; then
        if [[ -n "$COMMENT" ]]; then
-            tea issue comment "$ISSUE_NUMBER" "$COMMENT" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
+            # `tea issue comment` is NOT a subcommand -- tea 0.11.x lists only
            # list/create/edit/reopen/close under `tea issue`. Comments are the
            # TOP-LEVEL `tea comment`, which takes the same --repo/--login flags.
            # The old call therefore always failed, was unchecked, and the script
            # closed the issue anyway, losing the record of WHY.
            #
            # Use `tea comment` rather than the API helper so the comment and the
            # close are made by the SAME principal ($GITEA_LOGIN_NAME). Routing the
            # comment through the token-authenticated helper here would attribute the
            # comment to the token holder and the close to the tea login -- two
            # principals for one operation.
            tea comment "$ISSUE_NUMBER" "$COMMENT" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME" || {
                echo "Error: failed to post comment on #$ISSUE_NUMBER -- NOT closing (fail closed)." >&2
                exit 1
            }
        fi
        tea issue close "$ISSUE_NUMBER" --repo "$OWNER/$REPO" --login "$GITEA_LOGIN_NAME"
    else
        echo "No tea login configured for $(get_remote_host); using authenticated Gitea API fallback." >&2
        if [[ -n "$COMMENT" ]]; then
-            gitea_issue_comment_api
+            # Fail closed here too: an unchecked comment lets the issue close without its
            # audit trail, which is the same defect as the tea path above.
            gitea_issue_comment_api || {
                echo "Error: failed to post comment on #$ISSUE_NUMBER -- NOT closing (fail closed)." >&2
                exit 1
            }
        fi
        gitea_issue_close_api
    fi
@@ -254,15 +254,32 @@ from urllib.parse import urlparse
 def _origin_and_path(url):
-    # Normalize a URL to (scheme, host, effective-port) + comment path. The port
+    # Normalize a URL to (scheme-class, host, distinguishing-port) + comment path.
-    # defaults to the scheme's default (80 http / 443 otherwise) so an implicit
+    #
-    # port and its explicit default form compare equal.
+    # #991: http and https collapse into ONE scheme class ("web"). A Gitea whose
    # ROOT_URL is configured http:// returns http:// object URLs even when every
    # client reaches it over https://, so a scheme-strict comparison rejects the
    # provider's own correct answer about a write that landed — a deterministic
    # false negative on every comment posted against such a deployment. The
    # scheme is also not what this check defends: the forgeries it exists to
    # catch (look-alike host, decoy path prefix, wrong owner/repo/number) all
    # vary the HOST or the PATH, both of which stay strict below. Any OTHER
    # scheme (file:, ftp:, javascript:) remains distinguishing and is rejected.
    #
    # Port: an implicit port and its own scheme's default compare equal, so
    # http://h == https://h. An EXPLICIT non-default port still distinguishes,
    # because a different port is a different service on the same host.
    parsed = urlparse(url or "")
    scheme = (parsed.scheme or "").lower()
    host = (parsed.hostname or "").lower()
-    default_port = 80 if scheme == "http" else 443
+    if scheme in ("http", "https"):
-    port = parsed.port if parsed.port is not None else default_port
+        scheme_class = "web"
-    return (scheme, host, port), parsed.path.rstrip("/")
+        default_port = 80 if scheme == "http" else 443
        port = None if parsed.port in (None, default_port) else parsed.port
    else:
        scheme_class = scheme
        port = parsed.port
    return (scheme_class, host, port), parsed.path.rstrip("/")
 try:
@@ -156,6 +156,7 @@ case "$PLATFORM" in
                exit 0
            fi
            echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
            { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
        fi
        gitea_issue_create_api
        ;;
@@ -71,6 +71,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
            exit 0
        fi
        echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
    fi
    gitea_issue_view_api
 else
@@ -0,0 +1,289 @@
 #!/usr/bin/env bash
 # mosaic-worktree.sh — the only supported way to create and dispose of a git
 # worktree on a fleet host.
 #
 # Why this exists as a helper and not as a rule: the rule already existed, in
 # the framework's own words ("Big work → /var/tmp"), and 255 GB accumulated in
 # $HOME across 842 directories anyway. Five placement conventions were live on
 # one fleet host simultaneously. Every one was a decision an agent had to make,
 # and a decision an agent has to make is a decision that drifts.
 #
 # So this script makes NO placement decision available. The caller supplies a
 # branch name. Every path is DERIVED:
 #
 #   main worktree   <- git worktree list --porcelain (never cwd, which may
 #                      itself already be a worktree)
 #   REPO_NAME       <- basename of the main worktree
 #   REPO_PARENT     <- dirname  of the main worktree
 #   WT_ROOT         <- $REPO_PARENT/$REPO_NAME-worktrees
 #   SLUG            <- branch with '/' replaced by '-'
 #   WT_PATH         <- $WT_ROOT/$SLUG
 #
 # The derivation puts the worktree on the same filesystem as the object store
 # it shares, as a sibling of the repo, under one root per repo. Those are the
 # properties that make the checkout cheap and — via `git worktree list` —
 # enumerable, which is the only reason automated cleanup can ever be safe.
 #
 # Usage:
 #   mosaic-worktree.sh new <branch> [--from <base>]   create (branch may exist)
 #   mosaic-worktree.sh path <branch>                  print derived path, no side effect
 #   mosaic-worktree.sh list                           this repo's worktrees + state
 #   mosaic-worktree.sh rm <branch> [--force]          remove; refuses to lose work
 #   mosaic-worktree.sh gc [--apply]                   report/remove clean+pushed worktrees
 #
 # `rm` and `gc` refuse to delete a worktree with uncommitted changes, with
 # commits absent from every remote, or holding ignored files that are not of the
 # well-known regenerable kind (a `.env` is ignored so it is never committed,
 # which is also why nothing else holds a copy). That check is by EVIDENCE, never
 # by size or age. --force overrides it and is yours to type deliberately.
 #
 # Run from anywhere inside the repo, or pass --repo <path>.
 set -euo pipefail
 die() { printf 'mosaic-worktree: %s\n' "$*" >&2; exit 1; }
 REPO_HINT=""
 ARGS=()
 while [ $# -gt 0 ]; do
  case "$1" in
    --repo) REPO_HINT="${2:-}"; shift 2 ;;
    *) ARGS+=("$1"); shift ;;
  esac
 done
 set -- "${ARGS[@]+"${ARGS[@]}"}"
 CMD="${1:-}"
 [ -n "$CMD" ] || die "no command. Try: new | path | list | rm | gc"
 shift || true
 # ---- mechanical derivation -------------------------------------------------
 # The FIRST entry of `git worktree list --porcelain` is always the main
 # worktree, regardless of which worktree we are standing in. Deriving from cwd
 # would nest worktrees inside worktrees.
 resolve_repo() {
  local start="${REPO_HINT:-$PWD}"
  git -C "$start" rev-parse --git-dir >/dev/null 2>&1 \
    || die "not inside a git repository: $start"
  MAIN_WT="$(git -C "$start" worktree list --porcelain | awk '/^worktree /{print substr($0,10); exit}')"
  [ -n "$MAIN_WT" ] || die "could not resolve the main worktree"
  REPO_NAME="$(basename -- "$MAIN_WT")"
  REPO_PARENT="$(dirname -- "$MAIN_WT")"
  WT_ROOT="$REPO_PARENT/$REPO_NAME-worktrees"
 }
 slugify() { printf '%s' "$1" | tr '/' '-'; }
 derive_path() {
  local branch="$1"
  [ -n "$branch" ] || die "branch name required"
  printf '%s/%s' "$WT_ROOT" "$(slugify "$branch")"
 }
 # A worktree root under $HOME defeats the entire point: wrong filesystem, and
 # $HOME is for configuration and state, not work products. Refuse rather than
 # silently produce the layout we are trying to eliminate.
 assert_not_home() {
  local p="$1" home_real repo_real
  home_real="$(cd "$HOME" && pwd -P)"
  repo_real="$(cd "$(dirname -- "$p")" 2>/dev/null && pwd -P || dirname -- "$p")"
  case "$repo_real/" in
    "$home_real"/*)
      die "refusing: derived path is under \$HOME ($p).
 The repo itself lives under \$HOME, so its worktrees would too. Move the repo
 to a work filesystem (e.g. /src/$REPO_NAME) and re-run. \$HOME holds
 configuration, credentials, state and caches — not checkouts." ;;
  esac
 }
 # ---- work-loss evidence ----------------------------------------------------
 # Two independent questions, both answered from git, neither from size or age:
 #   dirty    — anything uncommitted in the tree
 #   unpushed — commits reachable from HEAD that no remote ref contains
 #   precious — IGNORED files git will not mention and will not miss
 #
 # The third question is not obvious and was missed on the first pass. An
 # independent reviewer demonstrated it in four commands: a pushed, clean
 # worktree whose .gitignore covers `*.secret`, holding one `local.secret`.
 # `git status --porcelain` is empty, `rev-list --count HEAD --not --remotes` is
 # 0 — the evidence reads SAFE — and `git worktree remove` deletes the file. The
 # same shape covers `.env`, credentials, scratch notes, downloaded fixtures:
 # precisely the files that are ignored BECAUSE they must not be committed, which
 # is also why nothing else is holding a copy.
 #
 # So ignored files count as work unless they are the well-known regenerable
 # kind. Getting that set wrong is asymmetric: an over-broad list preserves a
 # worktree that could have been reclaimed (cheap, visible, fixable by --force),
 # an over-narrow one deletes the only copy of a secret (silent, permanent).
 # The list stays short and conservative for that reason.
 DISPOSABLE_RE='(^|/)(node_modules|\.venv|venv|__pycache__|\.mypy_cache|\.pytest_cache|\.ruff_cache|\.turbo|\.cache|\.parcel-cache|\.gradle|dist|build|out|target|coverage|\.next|\.nuxt|\.svelte-kit)(/|$)|\.(pyc|pyo|o|class)$'
 # These three run under `set -euo pipefail` inside command substitution, which
 # makes any nonzero exit ANYWHERE in the pipeline abort the calling function
 # silently. Two ways that bites, one of which shipped:
 #
 #   * `grep -v` exits 1 when it filters everything out. A worktree whose only
 #     ignored entry is `node_modules/` is exactly the SAFE case, and it made
 #     `rm` exit 1 with no message and no removal — found by review.
 #   * `head -200` closes the pipe, SIGPIPEs the producer, and turns a worktree
 #     with 201 dirty files into the same silent abort. Not reported; it is the
 #     same defect one step upstream, so the cap is gone. Counting is cheap;
 #     the cap only ever protected output that is now never printed.
 #
 # Every one of them therefore ends in a total, and every stage that can
 # legitimately exit nonzero says so explicitly.
 wt_dirty() {
  local out
  out="$(git -C "$1" status --porcelain 2>/dev/null || true)"
  if [ -n "$out" ]; then printf '%s\n' "$out" | wc -l; else printf '0'; fi
 }
 wt_unpushed() { git -C "$1" rev-list --count HEAD --not --remotes 2>/dev/null || printf '?'; }
 # Default --ignored (not =matching) so a 40k-file node_modules collapses to one
 # directory entry instead of being enumerated and then discarded.
 wt_precious() {
  local ignored
  ignored="$(git -C "$1" status --porcelain --ignored 2>/dev/null \
             | awk '/^!! /{print substr($0,4)}' || true)"
  [ -n "$ignored" ] || { printf '0'; return 0; }
  printf '%s\n' "$ignored" | grep -Ecv "$DISPOSABLE_RE" || true
 }
 wt_state() {
  local wt="$1" d u p
  d="$(wt_dirty "$wt")"; u="$(wt_unpushed "$wt")"; p="$(wt_precious "$wt")"
  if [ "$d" -eq 0 ] && [ "$u" = "0" ] && [ "$p" -eq 0 ]; then
    printf 'SAFE\tclean; 0 unpushed; no ignored files worth keeping'
  else
    printf 'PRESERVE\t%s uncommitted; %s unpushed; %s ignored-but-not-disposable' "$d" "$u" "$p"
  fi
 }
 # ---- commands --------------------------------------------------------------
 cmd_path() { resolve_repo; derive_path "${1:-}"; echo; }
 cmd_new() {
  local branch="${1:-}" base=""
  shift || true
  while [ $# -gt 0 ]; do
    case "$1" in --from) base="${2:-}"; shift 2 ;; *) die "unknown flag: $1" ;; esac
  done
  [ -n "$branch" ] || die "usage: mosaic-worktree.sh new <branch> [--from <base>]"
  resolve_repo
  local path; path="$(derive_path "$branch")"
  assert_not_home "$path"
  if [ -e "$path" ]; then
    echo "exists: $path"
    echo "(already checked out — reuse it, or 'rm' it first)"
    return 0
  fi
  mkdir -p "$WT_ROOT"
  # Existing branch -> check it out. New branch -> create from base (default:
  # the remote's default branch if resolvable, else current HEAD).
  if git -C "$MAIN_WT" show-ref --verify --quiet "refs/heads/$branch" \
     || git -C "$MAIN_WT" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
    git -C "$MAIN_WT" worktree add "$path" "$branch"
  else
    if [ -z "$base" ]; then
      base="$(git -C "$MAIN_WT" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)"
      [ -n "$base" ] || base="HEAD"
    fi
    git -C "$MAIN_WT" worktree add -b "$branch" "$path" "$base"
  fi
  cat <<EOF
 worktree: $path
 branch:   $branch
 Removal is part of this task, not a later chore. When the work is pushed:
  mosaic-worktree.sh rm $branch
 EOF
 }
 cmd_list() {
  resolve_repo
  printf 'repo: %s\nroot: %s\n\n' "$MAIN_WT" "$WT_ROOT"
  git -C "$MAIN_WT" worktree list --porcelain \
    | awk '/^worktree /{print substr($0,10)}' \
    | while read -r wt; do
        [ "$wt" = "$MAIN_WT" ] && { printf '%-10s %s (main)\n' "-" "$wt"; continue; }
        printf '%-10s %s\t%s\n' "$(wt_state "$wt" | cut -f1)" "$wt" "$(wt_state "$wt" | cut -f2)"
      done
 }
 cmd_rm() {
  local branch="${1:-}" force=0
  shift || true
  while [ $# -gt 0 ]; do
    case "$1" in --force) force=1; shift ;; *) die "unknown flag: $1" ;; esac
  done
  [ -n "$branch" ] || die "usage: mosaic-worktree.sh rm <branch> [--force]"
  resolve_repo
  local path; path="$(derive_path "$branch")"
  [ -d "$path" ] || die "no worktree at $path"
  local d u p
  d="$(wt_dirty "$path")"; u="$(wt_unpushed "$path")"; p="$(wt_precious "$path")"
  if [ "$force" -eq 0 ] && { [ "$d" -ne 0 ] || [ "$u" != "0" ] || [ "$p" -ne 0 ]; }; then
    die "refusing to remove $path
  uncommitted files:            $d
  unpushed commits:             $u
  ignored, not disposable:      $p
 Commit and push first — that is the contract. Ignored files are counted because
 git will neither report them nor miss them: a .env or a *.secret is ignored
 precisely so it is never committed, which is also why nothing else holds a copy.
 List them with:  git -C $path status --porcelain --ignored | grep '^!!'
 If this work is genuinely disposable, re-run with --force."
  fi
  # NB: ${force:+--force} would expand for force=0 too ("0" is non-empty).
  if [ "$force" -eq 1 ]; then
    git -C "$MAIN_WT" worktree remove --force "$path"
  else
    git -C "$MAIN_WT" worktree remove "$path"
  fi
  git -C "$MAIN_WT" worktree prune
  echo "removed: $path"
  rmdir "$WT_ROOT" 2>/dev/null || true
 }
 cmd_gc() {
  local apply=0
  [ "${1:-}" = "--apply" ] && apply=1
  resolve_repo
  git -C "$MAIN_WT" worktree prune
  git -C "$MAIN_WT" worktree list --porcelain \
    | awk '/^worktree /{print substr($0,10)}' \
    | while read -r wt; do
        [ "$wt" = "$MAIN_WT" ] && continue
        local_state="$(wt_state "$wt")"
        case "$local_state" in
          SAFE*)
            if [ "$apply" -eq 1 ]; then
              git -C "$MAIN_WT" worktree remove "$wt" && echo "removed: $wt"
            else
              echo "reclaimable (clean + fully pushed): $wt"
            fi ;;
          *) echo "preserved: $wt  [$(printf '%s' "$local_state" | cut -f2)]" ;;
        esac
      done
  git -C "$MAIN_WT" worktree prune
  [ "$apply" -eq 1 ] || echo $'\n(report only — re-run with --apply to remove the reclaimable ones)'
 }
 case "$CMD" in
  new)  cmd_new  "$@" ;;
  path) cmd_path "$@" ;;
  list) cmd_list "$@" ;;
  rm)   cmd_rm   "$@" ;;
  gc)   cmd_gc   "$@" ;;
  -h|--help|help) sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//' ;;
  *) die "unknown command: $CMD (new | path | list | rm | gc)" ;;
 esac
@@ -84,7 +84,7 @@ cp "$TARGET" "$BAK"
 export MOSAIC_TEST_WORK_DIR="$WORK/.work"
 # --- where the prose lives: usage() { ... EOF ---------------------------------
-PROSE_LO="$(grep -n '^usage() {' "$BAK" | head -1 | cut -d: -f1)"
+PROSE_LO="$(grep -n -m1 '^usage() {' "$BAK" | cut -d: -f1)"
 PROSE_HI="$(awk -v lo="$PROSE_LO" 'NR > lo && /^EOF$/ { print NR; exit }' "$BAK")"
 if [[ -z "$PROSE_LO" || -z "$PROSE_HI" ]]; then
    echo "!! cannot locate the usage() heredoc -- the prose guard would be inert; refusing" >&2
@@ -219,6 +219,7 @@ case "$PLATFORM" in
            exit 0
        fi
        echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
        { declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true
        gitea_pr_create_api
        ;;
    *)
@@ -1,6 +1,6 @@
 #!/bin/bash
 # pr-merge.sh - Merge pull requests on Gitea or GitHub
-# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d] [--expect-head SHA] [--co-author-trailers --escalate-to PRINCIPAL]
 set -euo pipefail
@@ -14,6 +14,8 @@ MERGE_METHOD="squash"
 DELETE_BRANCH=false
 DRY_RUN=false
 EXPECT_HEAD=""
 CO_AUTHOR_TRAILERS=false
 ESCALATE_TO=""
 usage() {
    cat <<EOF
@@ -27,12 +29,16 @@ Options:
    -d, --delete-branch     Delete the head branch after merge
        --dry-run           Run metadata/login preflight without merging
        --expect-head SHA   Refuse unless the PR head matches this full commit SHA
        --co-author-trailers Build verified trailers from linked PR commit authors
        --escalate-to NAME  Named principal for an unresolved-author BLOCK
    -h, --help              Show this help message
 Examples:
    $(basename "$0") -n 42                    # Merge PR #42
    $(basename "$0") -n 42 -m squash          # Squash merge
    $(basename "$0") -n 42 -d                 # Squash merge and delete branch
    $(basename "$0") -n 42 --expect-head 0123456789abcdef0123456789abcdef01234567
    $(basename "$0") -n 42 --co-author-trailers --escalate-to tl-mosaic
 EOF
    exit "${1:-1}"
 }
@@ -57,9 +63,25 @@ while [[ $# -gt 0 ]]; do
            shift
            ;;
        --expect-head)
            if [[ $# -lt 2 ]]; then
                echo "Error: --expect-head requires one full commit SHA." >&2
                exit 1
            fi
            EXPECT_HEAD="$2"
            shift 2
            ;;
        --co-author-trailers)
            CO_AUTHOR_TRAILERS=true
            shift
            ;;
        --escalate-to)
            if [[ $# -lt 2 ]]; then
                echo "Error: --escalate-to requires one principal name." >&2
                exit 1
            fi
            ESCALATE_TO="$2"
            shift 2
            ;;
        -h|--help)
            usage 0
            ;;
@@ -88,17 +110,30 @@ if [[ -n "$EXPECT_HEAD" && ! "$EXPECT_HEAD" =~ ^[0-9a-fA-F]{40}$ ]]; then
    echo "Error: --expect-head must be a full 40-character hexadecimal commit SHA." >&2
    exit 1
 fi
 if [[ "$CO_AUTHOR_TRAILERS" == true && -z "$ESCALATE_TO" ]]; then
    echo "Error: --co-author-trailers requires --escalate-to with a named principal." >&2
    exit 1
 fi
 if [[ -n "$ESCALATE_TO" && ! "$ESCALATE_TO" =~ ^[A-Za-z0-9_.-]+$ ]]; then
    echo "Error: --escalate-to must be one exact principal name." >&2
    exit 1
 fi
 if [[ "$CO_AUTHOR_TRAILERS" != true && -n "$ESCALATE_TO" ]]; then
    echo "Error: --escalate-to is valid only with --co-author-trailers." >&2
    exit 1
 fi
 PR_METADATA="$("$SCRIPT_DIR/pr-metadata.sh" -n "$PR_NUMBER")"
 BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("baseRefName") or "").strip())')"
 HEAD_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefName") or "").strip())')"
 HEAD_SHA="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefOid") or "").strip())')"
 HEAD_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("headRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
 PR_TITLE="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("title") or "").strip())')"
 PR_AUTHOR="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("author") or ""; print((value.get("login") or "").strip() if isinstance(value, dict) else str(value).strip())')"
 if [[ "$BASE_BRANCH" != "main" ]]; then
    echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
    exit 1
 fi
 if [[ -z "$HEAD_BRANCH" || -z "$HEAD_REPO" || ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
    echo "Error: Could not resolve the PR head branch, repository, and full commit SHA for queue inspection." >&2
    exit 1
@@ -122,70 +157,442 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 REPO=$(get_repo_name)
-merge_gitea_with_api() {
+write_curl_auth_config() {
-    local host="$1" api_url token basic_auth body_file raw_code payload
+    local mode="$1" credential="$2"
-    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
+    printf '%s' "$credential" | python3 -c '
-    mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
+import sys
-    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
+mode = sys.argv[1]
-    payload=$(python3 - "$HEAD_SHA" "$DELETE_BRANCH" <<'PY'
+credential = sys.stdin.read()
 if not credential or any(char in credential for char in "\r\n"):
    raise SystemExit(1)
 escaped = credential.replace("\\", "\\\\").replace("\"", "\\\"")
 if mode == "token":
    print(f"header = \"Authorization: token {escaped}\"")
 elif mode == "basic":
    print(f"user = \"{escaped}\"")
 else:
    raise SystemExit(1)
 ' "$mode"
 }
 LAST_GITEA_HTTP_CODE="000"
 LAST_GITEA_ERROR=""
 MERGE_TEMP_DIRS=()
 GITEA_CURL_MAX_BYTES="${MOSAIC_GITEA_CURL_MAX_BYTES:-1048576}"
 GITEA_CURL_MAX_TIME="${MOSAIC_GITEA_CURL_MAX_TIME_SEC:-30}"
 GITEA_CURL_CONNECT_TIMEOUT="${MOSAIC_GITEA_CURL_CONNECT_TIMEOUT_SEC:-10}"
 for bound in "$GITEA_CURL_MAX_BYTES" "$GITEA_CURL_MAX_TIME" "$GITEA_CURL_CONNECT_TIMEOUT"; do
    if [[ ! "$bound" =~ ^[1-9][0-9]*$ ]]; then
        echo "Error: Gitea curl bounds must be positive integers; refusing request." >&2
        exit 1
    fi
 done
 GITEA_CURL_BOUNDS=(
    --max-filesize "$GITEA_CURL_MAX_BYTES"
    --max-time "$GITEA_CURL_MAX_TIME"
    --connect-timeout "$GITEA_CURL_CONNECT_TIMEOUT"
 )
 format_gitea_error_response() {
    local response_file="$1"
    python3 - "$response_file" <<'PY'
 import json
 import sys
-head_sha, delete_branch = sys.argv[1:]
+with open(sys.argv[1], "rb") as handle:
    raw = handle.read(65536)
 try:
    response = json.loads(raw.decode("utf-8", errors="replace"))
 except (UnicodeDecodeError, json.JSONDecodeError):
    message = "non-JSON response omitted"
 else:
    if isinstance(response, dict):
        message = response.get("message") or response.get("error")
        if not message and response.get("errors") is not None:
            message = json.dumps(response["errors"], separators=(",", ":"))
    else:
        message = None
    if not message:
        message = "JSON response contained no error message"
 message = str(message)
 if len(message) > 500:
    message = message[:500] + "..."
 print(ascii(message))
 PY
 }
 cleanup_merge_temp_dirs() {
    local path
    for path in "${MERGE_TEMP_DIRS[@]}"; do
        [[ -n "$path" ]] && rm -rf -- "$path"
    done
 }
 trap cleanup_merge_temp_dirs EXIT
 trap 'exit 130' INT
 trap 'exit 143' TERM
 fetch_gitea_pr_head() {
    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
    local response_file raw_code api_url auth_config curl_rc
    response_file=$(mktemp "$work_root/pr-merge-pr.XXXXXX")
    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}"
    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
        rm -f "$response_file"
        return 1
    fi
    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$response_file" \
        -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
    curl_rc=$?
    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
    if [[ "$curl_rc" -ne 0 ]]; then
        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
        rm -f "$response_file"
        return 1
    fi
    if [[ ! "$raw_code" =~ ^2 ]]; then
        LAST_GITEA_ERROR=$(format_gitea_error_response "$response_file")
        rm -f "$response_file"
        return 1
    fi
    if ! python3 - "$response_file" <<'PY'
 import json
 import re
 import sys
 with open(sys.argv[1], encoding="utf-8") as handle:
    pull = json.load(handle)
 head = pull.get("head") if isinstance(pull, dict) else None
 sha = str(head.get("sha") or "") if isinstance(head, dict) else ""
 if not re.fullmatch(r"[0-9a-fA-F]{40}", sha):
    raise SystemExit(1)
 print(sha)
 PY
    then
        echo "Error: Gitea PR response has no valid head SHA; refusing merge." >&2
        rm -f "$response_file"
        return 1
    fi
    rm -f "$response_file"
 }
 fetch_gitea_pr_commits() {
    local host="$1" auth_mode="$2" credential="$3" work_root="$4"
    local page page_file combined_file merged_file raw_code page_count api_url auth_config curl_rc
    mkdir -p "$work_root"
    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
        return 1
    fi
    combined_file=$(mktemp "$work_root/pr-merge-commits.XXXXXX")
    printf '[]' > "$combined_file"
    page=1
    while true; do
        page_file=$(mktemp "$work_root/pr-merge-commits-page.XXXXXX")
        api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/commits?limit=50&page=${page}"
        raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$page_file" \
            -H "User-Agent: curl/8" "$api_url" <<<"$auth_config")
        curl_rc=$?
        LAST_GITEA_HTTP_CODE="${raw_code:-000}"
        if [[ "$curl_rc" -ne 0 ]]; then
            LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
            rm -f "$page_file" "$combined_file"
            return 1
        fi
        if [[ ! "$raw_code" =~ ^2 ]]; then
            LAST_GITEA_ERROR=$(format_gitea_error_response "$page_file")
            rm -f "$page_file" "$combined_file"
            return 1
        fi
        if ! page_count=$(python3 - "$page_file" <<'PY'
 import json
 import sys
 with open(sys.argv[1], encoding="utf-8") as handle:
    page = json.load(handle)
 if not isinstance(page, list):
    raise SystemExit(1)
 print(len(page))
 PY
        ); then
            echo "Error: Gitea PR commits response is not a JSON array; refusing merge." >&2
            rm -f "$page_file" "$combined_file"
            return 1
        fi
        merged_file=$(mktemp "$work_root/pr-merge-commits-merged.XXXXXX")
        if ! python3 - "$combined_file" "$page_file" > "$merged_file" <<'PY'
 import json
 import sys
 with open(sys.argv[1], encoding="utf-8") as handle:
    combined = json.load(handle)
 with open(sys.argv[2], encoding="utf-8") as handle:
    page = json.load(handle)
 json.dump(combined + page, sys.stdout, separators=(",", ":"))
 PY
        then
            echo "Error: Could not combine paginated PR commit metadata; refusing merge." >&2
            rm -f "$page_file" "$combined_file" "$merged_file"
            return 1
        fi
        mv "$merged_file" "$combined_file"
        rm -f "$page_file"
        if [[ "$page_count" -lt 50 ]]; then
            break
        fi
        page=$((page + 1))
        if [[ "$page" -gt 1000 ]]; then
            echo "Error: PR commit pagination exceeded 1000 pages; refusing merge." >&2
            rm -f "$combined_file"
            return 1
        fi
    done
    cat "$combined_file"
    rm -f "$combined_file"
 }
 # LIMITATION: author.login resolution proves the commit address maps to a registered account.
 # It does NOT prove the named principal authored the commit — git author metadata is self-asserted.
 # This gate checks ATTRIBUTION LINKAGE, not AUTHORSHIP. Commit signing is out of scope and unadopted.
 build_coauthor_message_fields() {
    local commits_file="$1" context_file="$2" head_file="$3"
    python3 - "$commits_file" "$context_file" "$head_file" <<'PY'
 import json
 import re
 import sys
 commits_path, context_path, head_path = sys.argv[1:]
 with open(commits_path, encoding="utf-8") as handle:
    commits = json.load(handle)
 head_sha = open(head_path, encoding="utf-8").read().strip()
 context_parts = open(context_path, "rb").read().split(b"\0")
 if len(context_parts) != 4 or context_parts[-1] != b"":
    raise SystemExit(1)
 poster, title, principal = (part.decode("utf-8") for part in context_parts[:3])
 if not isinstance(commits, list) or not commits:
    print(
        f"BLOCK: provider returned no PR commits; author identity is unmeasurable. "
        f"Refusing merge; escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 if not poster:
    print(
        f"BLOCK: PR poster login is empty; refusing merge; "
        f"escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 if not re.fullmatch(r"[0-9a-fA-F]{40}", head_sha):
    print(
        f"BLOCK: inspected PR head SHA is invalid; refusing merge; "
        f"escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 seen = set()
 trailers = []
 head_seen = False
 for item in commits:
    if not isinstance(item, dict):
        print(f"BLOCK: malformed PR commit metadata; escalate to named principal '{principal}'.", file=sys.stderr)
        raise SystemExit(75)
    sha = str(item.get("sha") or "<unknown>")
    if sha == head_sha:
        head_seen = True
    commit = item.get("commit") if isinstance(item.get("commit"), dict) else {}
    commit_author = commit.get("author") if isinstance(commit.get("author"), dict) else {}
    email = str(commit_author.get("email") or "").strip()
    provider_author = item.get("author") if isinstance(item.get("author"), dict) else {}
    login = str(provider_author.get("login") or "").strip()
    if not login:
        diagnostic_email = email or "<missing>"
        print(
            f"BLOCK: commit {sha!r} has author.login=NULL while "
            f"commit.author.email={diagnostic_email!r}; refusing merge; "
            f"escalate to named principal '{principal}'.",
            file=sys.stderr,
        )
        raise SystemExit(75)
    if (
        not email.isascii()
        or not email.isprintable()
        or not re.fullmatch(r"[A-Za-z0-9_.-]+", login)
        or not re.fullmatch(r"[^<>\s]+@[^<>\s]+", email)
    ):
        print(
            f"BLOCK: commit {sha!r} has unusable linked identity "
            f"author.login={login!r}, commit.author.email={email!r}; refusing merge; "
            f"escalate to named principal '{principal}'.",
            file=sys.stderr,
        )
        raise SystemExit(75)
    if login == poster or login in seen:
        continue
    seen.add(login)
    trailers.append(f"Co-authored-by: {login} <{email}>")
 if not head_seen:
    print(
        f"BLOCK: inspected PR head is absent from commit enumeration; refusing merge; "
        f"escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 if not trailers:
    print("{}")
    raise SystemExit(0)
 if not title:
    print(
        f"BLOCK: PR title is empty; refusing merge; escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 if not title.isprintable() or re.match(r"^[A-Za-z-]+-[Bb]y:", title):
    print(
        f"BLOCK: PR title is not one printable, non-trailer line; refusing merge; "
        f"escalate to named principal '{principal}'.",
        file=sys.stderr,
    )
    raise SystemExit(75)
 print(json.dumps({
    "MergeTitleField": title,
    "MergeMessageField": "\n".join(trailers),
 }, separators=(",", ":")))
 PY
 }
 merge_gitea_api_attempt() {
    local host="$1" auth_mode="$2" credential="$3"
    local api_url attempt_dir body_file raw_code commits_file fields_file context_file head_file payload_file work_root attempt_rc auth_config curl_rc
    LAST_GITEA_HTTP_CODE="000"
    LAST_GITEA_ERROR=""
    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
    work_root="${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
    mkdir -p "$work_root"
    attempt_dir=$(mktemp -d "$work_root/pr-merge-attempt.XXXXXX")
    chmod 0700 "$attempt_dir"
    MERGE_TEMP_DIRS+=("$attempt_dir")
    body_file=$(mktemp "$attempt_dir/api-response.XXXXXX")
    fields_file=$(mktemp "$attempt_dir/message-fields.XXXXXX")
    payload_file=$(mktemp "$attempt_dir/payload.XXXXXX")
    printf '{}' > "$fields_file"
    if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
        commits_file=$(mktemp "$attempt_dir/pr-merge-commits-input.XXXXXX")
        context_file=$(mktemp "$attempt_dir/pr-merge-message-context.XXXXXX")
        head_file=$(mktemp "$attempt_dir/pr-merge-head-input.XXXXXX")
        printf '%s\0%s\0%s\0' "$PR_AUTHOR" "$PR_TITLE" "$ESCALATE_TO" > "$context_file"
        if fetch_gitea_pr_head "$host" "$auth_mode" "$credential" "$attempt_dir" > "$head_file"; then
            :
        else
            attempt_rc=$?
            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
            return "$attempt_rc"
        fi
        if [[ "$(<"$head_file")" != "$HEAD_SHA" ]]; then
            echo "BLOCK: authenticated PR head moved from reviewed $HEAD_SHA to $(<"$head_file"); refusing merge; escalate to named principal '$ESCALATE_TO'." >&2
            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
            return 75
        fi
        if fetch_gitea_pr_commits "$host" "$auth_mode" "$credential" "$attempt_dir" > "$commits_file"; then
            :
        else
            attempt_rc=$?
            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
            return "$attempt_rc"
        fi
        if build_coauthor_message_fields "$commits_file" "$context_file" "$head_file" > "$fields_file"; then
            :
        else
            attempt_rc=$?
            rm -f "$body_file" "$fields_file" "$payload_file" "$commits_file" "$context_file" "$head_file"
            return "$attempt_rc"
        fi
        rm -f "$commits_file" "$context_file" "$head_file"
    fi
    if ! python3 - "$fields_file" "$HEAD_SHA" "$DELETE_BRANCH" > "$payload_file" <<'PY'
 import json
 import sys
 with open(sys.argv[1], encoding="utf-8") as handle:
    fields = json.load(handle)
 head_sha, delete_branch = sys.argv[2:]
 payload = {"Do": "squash", "head_commit_id": head_sha}
 if delete_branch == "true":
    payload["delete_branch_after_merge"] = True
 payload.update(fields)
 allowed = {"Do", "head_commit_id", "delete_branch_after_merge", "MergeTitleField", "MergeMessageField"}
 if payload.get("Do") != "squash" or set(payload) - allowed:
    raise SystemExit(1)
 print(json.dumps(payload, separators=(",", ":")))
 PY
-)
+    then
-
+        rm -f "$body_file" "$fields_file" "$payload_file"
-    token=$(get_gitea_token "$host" || true)
+        return 1
    if [[ -n "$token" ]]; then
        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
            -X POST \
            -H "User-Agent: curl/8" \
            -H "Authorization: token $token" \
            -H 'Content-Type: application/json' \
            -d "$payload" \
            "$api_url" || true)
        if [[ "$raw_code" =~ ^2 ]]; then
            rm -f "$body_file"
            return 0
        fi
    fi
    rm -f "$fields_file"
-    basic_auth=$(get_gitea_basic_auth "$host" || true)
+    if ! auth_config=$(write_curl_auth_config "$auth_mode" "$credential"); then
-    if [[ -n "$basic_auth" ]]; then
+        echo "Error: Could not construct Gitea authentication config; refusing request." >&2
-        raw_code=$(curl -sS -w '%{http_code}' -o "$body_file" \
+        rm -f "$body_file" "$payload_file"
-            -X POST \
+        return 1
            -u "$basic_auth" \
            -H "User-Agent: curl/8" \
            -H 'Content-Type: application/json' \
            -d "$payload" \
            "$api_url" || true)
        if [[ "$raw_code" =~ ^2 ]]; then
            rm -f "$body_file"
            return 0
        fi
    fi
    raw_code=$(curl -sS -K - "${GITEA_CURL_BOUNDS[@]}" -w '%{http_code}' -o "$body_file" \
        -X POST -H "User-Agent: curl/8" \
        -H 'Content-Type: application/json' \
        --data-binary "@$payload_file" "$api_url" <<<"$auth_config")
    curl_rc=$?
    LAST_GITEA_HTTP_CODE="${raw_code:-000}"
    if [[ "$curl_rc" -ne 0 ]]; then
        LAST_GITEA_ERROR="curl transport failed (rc=$curl_rc)"
        rm -f "$body_file" "$payload_file"
        rm -rf -- "$attempt_dir"
        return 1
    fi
    if [[ ! "$raw_code" =~ ^2 ]]; then
        LAST_GITEA_ERROR=$(format_gitea_error_response "$body_file")
    fi
    rm -f "$body_file" "$payload_file"
    rm -rf -- "$attempt_dir"
    [[ "$raw_code" =~ ^2 ]]
 }
-    python3 - "${raw_code:-000}" "$body_file" <<'PY' >&2
+merge_gitea_with_api() {
-import json
+    local host="$1" token attempt_rc
-import sys
+
-code, path = sys.argv[1], sys.argv[2]
+    if ! token=$(get_gitea_token "$host"); then
-try:
+        echo "Error: Could not resolve the required Gitea token; refusing merge without changing principals." >&2
-    with open(path, encoding="utf-8", errors="replace") as handle:
+        return 1
-        raw = handle.read(500)
+    fi
-    data = json.loads(raw) if raw else {}
+    if [[ -z "$token" ]]; then
-    message = data.get("message") or data.get("error") or raw or "empty response"
+        echo "Error: Required Gitea token resolved empty; refusing merge without changing principals." >&2
-except Exception:
+        return 1
-    try:
+    fi
-        message = open(path, encoding="utf-8", errors="replace").read(500) or "empty response"
+    if merge_gitea_api_attempt "$host" token "$token"; then
-    except Exception:
+        return 0
-        message = "unreadable response"
+    else
-print(f"Error: Gitea API merge failed with HTTP {code}: {message}")
+        attempt_rc=$?
-PY
+    fi
-    rm -f "$body_file"
+    if [[ "$attempt_rc" -eq 75 ]]; then
        return 75
    fi
    if [[ "$LAST_GITEA_HTTP_CODE" != "401" ]]; then
        echo "Error: Gitea API merge failed with the identity-bound token (HTTP ${LAST_GITEA_HTTP_CODE:-000}).${LAST_GITEA_ERROR:+ Provider response: $LAST_GITEA_ERROR}" >&2
        return 1
    fi
    echo "Error: Gitea API rejected the identity-bound token with HTTP 401; refusing cross-principal credential fallback." >&2
    return 1
 }
@@ -195,11 +602,10 @@ if [[ "$DRY_RUN" == true ]]; then
            echo "Error: Cannot determine host from origin remote URL" >&2
            exit 1
        }
-        TEA_LOGIN="$(get_gitea_login_for_host "$HOST" || true)"
+        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
-        if [[ -n "$TEA_LOGIN" ]]; then
+            echo "Dry run: would verify PR commit authors and merge PR #$PR_NUMBER on $HOST with authenticated Gitea API message fields (base=$BASE_BRANCH, method=squash)."
            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with tea login '$TEA_LOGIN' (base=$BASE_BRANCH, method=squash)."
        else
-            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with authenticated Gitea API fallback (base=$BASE_BRANCH, method=squash)."
+            echo "Dry run: would merge PR #$PR_NUMBER on $HOST with the authenticated exact-head Gitea API path (base=$BASE_BRANCH, method=squash)."
        fi
    else
        echo "Dry run: would merge PR #$PR_NUMBER on $PLATFORM (base=$BASE_BRANCH, method=squash)."
@@ -209,6 +615,10 @@ fi
 case "$PLATFORM" in
    github)
        if [[ "$CO_AUTHOR_TRAILERS" == true ]]; then
            echo "Error: --co-author-trailers currently requires the Gitea REST message-field contract." >&2
            exit 1
        fi
        cmd=(gh pr merge "$PR_NUMBER" --squash --match-head-commit "$HEAD_SHA")
        [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
        "${cmd[@]}"
@@ -219,7 +629,7 @@ case "$PLATFORM" in
            exit 1
        }
        # Gitea's API head_commit_id is an atomic compare-and-merge precondition.
-        # tea cannot express it, so exact-head merges use the authenticated API path.
+        # tea cannot express it, so every Gitea merge uses the authenticated API path.
        merge_gitea_with_api "$HOST"
        ;;
    *)
@@ -243,15 +243,35 @@ from urllib.parse import urlparse
 def _origin_and_path(url):
-    # Normalize a URL to (scheme, host, effective-port) + comment path. The port
+    # Normalize a URL to (scheme-class, host, distinguishing-port) + comment path.
-    # defaults to the scheme's default (80 http / 443 otherwise) so an implicit
+    #
-    # port and its explicit default form compare equal.
+    # #991: http and https collapse into ONE scheme class ("web"). A Gitea whose
    # ROOT_URL is configured http:// returns http:// object URLs even when every
    # client reaches it over https://, so a scheme-strict comparison rejects the
    # provider's own correct answer about a comment that landed — a deterministic
    # false negative on EVERY review comment posted against such a deployment.
    # That matters more here than anywhere else: on a host where no seat can
    # create a review OBJECT, the comment-form review record this path produces
    # is the only gate-16 evidence available, and this check refuses all of it.
    # The scheme is also not what the check defends: the forgeries it exists to
    # catch (look-alike host, decoy path prefix, wrong owner/repo/kind/number)
    # all vary the HOST or the PATH, both of which stay strict below. Any OTHER
    # scheme (file:, ftp:, javascript:) remains distinguishing and is rejected.
    #
    # Port: an implicit port and its own scheme's default compare equal, so
    # http://h == https://h. An EXPLICIT non-default port still distinguishes,
    # because a different port is a different service on the same host.
    parsed = urlparse(url or "")
    scheme = (parsed.scheme or "").lower()
    host = (parsed.hostname or "").lower()
-    default_port = 80 if scheme == "http" else 443
+    if scheme in ("http", "https"):
-    port = parsed.port if parsed.port is not None else default_port
+        scheme_class = "web"
-    return (scheme, host, port), parsed.path.rstrip("/")
+        default_port = 80 if scheme == "http" else 443
        port = None if parsed.port in (None, default_port) else parsed.port
    else:
        scheme_class = scheme
        port = parsed.port
    return (scheme_class, host, port), parsed.path.rstrip("/")
 try:
@@ -9,10 +9,51 @@ WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-tristate}
 REPO_DIR="$WORK_DIR/repo"
 STUB_DIR="$WORK_DIR/stubs"
 AUDIT_LOG="$WORK_DIR/audit/ci-queue-wait.jsonl"
 STATUS_OBSERVED="$WORK_DIR/status-observed"
 CLOCK_LOG="$WORK_DIR/clock.log"
 WATCHDOG_PYTHON="/usr/bin/python3"
 WATCHDOG_SCRIPT="$WORK_DIR/real-clock-watchdog.py"
 WATCHDOG_TIMEOUT_SEC=5
 WATCHDOG_EXIT=90
 FEATURE_BRANCH="fix/rm-03-fixture"
 if [[ ! -x "$WATCHDOG_PYTHON" ]]; then
    echo "FAIL setup: required real-clock watchdog runtime is unavailable at $WATCHDOG_PYTHON" >&2
    exit 1
 fi
 rm -rf "$WORK_DIR"
 mkdir -p "$REPO_DIR" "$STUB_DIR"
 cat > "$WATCHDOG_SCRIPT" <<'PY'
 import os
 import signal
 import subprocess
 import sys
 if len(sys.argv) < 3:
    raise SystemExit(2)
 timeout_seconds = float(sys.argv[1])
 process = subprocess.Popen(sys.argv[2:], start_new_session=True)
 try:
    return_code = process.wait(timeout=timeout_seconds)
 except subprocess.TimeoutExpired:
    try:
        os.killpg(process.pid, signal.SIGKILL)
    except ProcessLookupError:
        pass
    process.wait()
    print(
        f"FAIL HANG watchdog: subject exceeded {timeout_seconds:g}s "
        "before completing its intended path",
        file=sys.stderr,
    )
    raise SystemExit(90)
 if return_code < 0:
    raise SystemExit(128 - return_code)
 raise SystemExit(return_code)
 PY
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" checkout -q -b "$FEATURE_BRANCH"
 git -C "$REPO_DIR" remote add origin https://git.example.test/acme/widgets.git
@@ -33,6 +74,9 @@ printf '%s\n' "$url" >> "${MOSAIC_STUB_URL_LOG:?}"
 case "$url" in
    */branches/*)
        if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "hang-before-provider" ]]; then
            while :; do :; done
        fi
        if [[ "${MOSAIC_STUB_BRANCH_MODE:-ok}" == "unreachable" ]]; then
            exit 7
        fi
@@ -44,6 +88,7 @@ case "$url" in
        fi
        ;;
    */status)
        : > "${MOSAIC_STUB_STATUS_OBSERVED:?}"
        case "${MOSAIC_STUB_STATUS_MODE:?}" in
            success)   printf '%s' '{"state":"success","statuses":[{"status":"success"}]}' ;;
            pending)   printf '%s' '{"state":"pending","statuses":[{"status":"pending","context":"ci/test"}]}' ;;
@@ -63,7 +108,31 @@ case "$url" in
    *) echo "unexpected curl URL: $url" >&2; exit 2 ;;
 esac
 SH
-chmod +x "$STUB_DIR/curl"
+
 cat > "$STUB_DIR/date" <<'SH'
 #!/usr/bin/env bash
 set -euo pipefail
 if [[ "$#" -ne 1 || "$1" != "+%s" ]]; then
    echo "unexpected date invocation: $*" >&2
    exit 2
 fi
 if [[ -e "${MOSAIC_STUB_STATUS_OBSERVED:?}" ]]; then
    printf 'date-phase=after-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
    printf '1002\n'
 else
    printf 'date-phase=before-status\n' >> "${MOSAIC_STUB_CLOCK_LOG:?}"
    printf '1000\n'
 fi
 SH
 cat > "$STUB_DIR/sleep" <<'SH'
 #!/usr/bin/env bash
 set -euo pipefail
 printf 'sleep-after-status=%s\n' "$*" >> "${MOSAIC_STUB_CLOCK_LOG:?}"
 SH
 chmod +x "$STUB_DIR/curl" "$STUB_DIR/date" "$STUB_DIR/sleep"
 run_guard() {
    local status_mode="$1"
@@ -83,13 +152,46 @@ run_guard() {
            export GITEA_URL=https://git.example.test
            export MOSAIC_STUB_STATUS_MODE="$status_mode"
        fi
        rm -f "$STATUS_OBSERVED" "$CLOCK_LOG"
        export MOSAIC_STUB_URL_LOG="$WORK_DIR/urls.log"
        export MOSAIC_STUB_STATUS_OBSERVED="$STATUS_OBSERVED"
        export MOSAIC_STUB_CLOCK_LOG="$CLOCK_LOG"
        export MOSAIC_CI_QUEUE_AUDIT_LOG="$audit_log"
-        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 0 -i 0 "$@"
+        # Provider observation is the synchronization event. The one-second
        # timeout is subject semantics under virtual time, never a wall wait.
        # The absolute Python runtime uses an internal monotonic wait and kills
        # the subject's isolated process group. Neither operation can resolve
        # to the virtual date/sleep stubs at the front of PATH.
        local subject_rc
        if "$WATCHDOG_PYTHON" "$WATCHDOG_SCRIPT" "$WATCHDOG_TIMEOUT_SEC" \
            "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "${MOSAIC_TEST_PURPOSE:-push}" -t 1 -i 1 "$@"; then
            subject_rc=0
        else
            subject_rc=$?
        fi
        return "$subject_rc"
    )
 }
 failures=0
 assert_provider_observed() {
    local name="$1" require_expiration="${2:-0}"
    if [[ ! -e "$STATUS_OBSERVED" ]]; then
        echo "FAIL $name: status provider was not observed" >&2
        failures=$((failures + 1))
    fi
    if [[ ! -s "$CLOCK_LOG" ]] || ! grep -q '^date-phase=before-status$' "$CLOCK_LOG"; then
        echo "FAIL $name: virtual clock interception did not run before provider observation" >&2
        failures=$((failures + 1))
    fi
    if [[ "$require_expiration" -eq 1 ]]; then
        if ! grep -q '^sleep-after-status=' "$CLOCK_LOG" || ! grep -q '^date-phase=after-status$' "$CLOCK_LOG"; then
            echo "FAIL $name: pending path did not expire after provider observation" >&2
            failures=$((failures + 1))
        fi
    fi
 }
 run_assertion() {
    local name="$1" expected_rc="$2" status_mode="$3" required_text="$4"
    local output rc
@@ -124,6 +226,13 @@ run_assertion() {
        printf '%s\n' "$output" >&2
        failures=$((failures + 1))
    fi
    if [[ "$status_mode" != "credential-unresolvable" ]]; then
        if [[ "$status_mode" == "pending" ]]; then
            assert_provider_observed "$name" 1
        else
            assert_provider_observed "$name"
        fi
    fi
 }
 set -e
@@ -140,6 +249,27 @@ run_assertion large-payload not126 large-success 'state=terminal-success'
 run_assertion credential-unresolvable zero credential-unresolvable 'CANNOT_ASSERT'
 run_assertion provider-unreachable zero unreachable 'CANNOT_ASSERT'
 # Positive liveness control: a subject mutant hangs before the branch lookup
 # can reach the status provider. Only the independent real-clock watchdog may
 # terminate it, and its failure must be distinct from subject timeout rc=124.
 set +e
 watchdog_output=$(MOSAIC_STUB_BRANCH_MODE=hang-before-provider run_guard success "$AUDIT_LOG" 2>&1)
 watchdog_rc=$?
 set -e
 if [[ "$watchdog_rc" -ne "$WATCHDOG_EXIT" ]]; then
    echo "FAIL watchdog-control: expected hang-specific rc=$WATCHDOG_EXIT, got rc=$watchdog_rc" >&2
    failures=$((failures + 1))
 fi
 if [[ "$watchdog_output" != *"FAIL HANG watchdog:"* ]]; then
    echo "FAIL watchdog-control: expected distinct hang-specific diagnostic" >&2
    printf '%s\n' "$watchdog_output" >&2
    failures=$((failures + 1))
 fi
 if [[ -e "$STATUS_OBSERVED" ]]; then
    echo "FAIL watchdog-control: hanging mutant unexpectedly reached the status provider" >&2
    failures=$((failures + 1))
 fi
 if [[ ! -s "$AUDIT_LOG" ]] || ! grep -q '"outcome":"CANNOT_ASSERT"' "$AUDIT_LOG"; then
    echo "FAIL provider-unreachable-audit: expected durable CANNOT_ASSERT JSONL record" >&2
    failures=$((failures + 1))
@@ -160,6 +290,7 @@ if [[ "$merge_unreachable_output" != *"CANNOT_ASSERT"* ]]; then
    echo "FAIL merge-provider-unreachable: expected loud CANNOT_ASSERT diagnostic" >&2
    failures=$((failures + 1))
 fi
 assert_provider_observed merge-provider-unreachable
 merge_audit_lines_after=$(wc -l < "$AUDIT_LOG")
 if [[ "$merge_audit_lines_after" -le "$merge_audit_lines_before" ]]; then
    echo "FAIL merge-provider-unreachable: expected an additional audit record" >&2
@@ -223,6 +354,7 @@ if [[ "$audit_failure_output" != *"audit"* ]]; then
    echo "FAIL audit-unavailable: expected loud audit failure diagnostic" >&2
    failures=$((failures + 1))
 fi
 assert_provider_observed audit-unavailable
 if [[ "$failures" -ne 0 ]]; then
    echo "ci-queue-wait tri-state regression failed ($failures assertions)" >&2
@@ -0,0 +1,58 @@
 #!/bin/bash
 # Regression: detect_platform / get_repo_info must FAIL LOUDLY outside a git repo,
 # not kill the caller silently.
 #
 # Both functions already contained the right error path:
 #     if [[ -z "$remote_url" ]]; then echo "error: not a git repository..." >&2; return 1; fi
 # but under `set -e` -- which every wrapper in this directory uses -- the preceding
 # assignment `remote_url=$(git remote get-url origin 2>/dev/null)` returns git's 128
 # outside a repo and terminates the CALLER first. The message was unreachable.
 #
 # Observed cost: pr-review.sh invoked from a non-repo cwd exits 128 with NO stdout and
 # NO stderr, even when -r/--repo and -H/--host are supplied -- the flags documented as
 # "skips git-remote inference". Two reviewer seats hit this and correctly reported
 # `blocked` with no diagnostic to report.
 #
 # The control that matters is the LOUD one: asserting "rc != 0" passes on the broken
 # build too, because 128 is also non-zero. The test must assert the MESSAGE.
 set -uo pipefail
 fail=0
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
 run_outside() { # $1=function name -> "rc:sawmessage"
    local fn="$1" out rc
    out=$( cd "$TMP" && bash -c "set -e; source '$HERE/detect-platform.sh'; $fn" 2>&1 ); rc=$?
    printf '%s:%s' "$rc" "$(grep -qi 'not a git repository' <<<"$out" && echo yes || echo no)"
 }
 check() { if [ "$2" = "$3" ]; then echo "  PASS  $1 ($2)"; else echo "  FAIL  $1: got $2, want $3"; fail=1; fi; }
 # $TMP must not be inside a git repo. Do not SKIP on failure: be-coder-07 showed the
 # original SKIP exited 0, so pointing TMPDIR beneath a git worktree made this test PASS
 # against unchanged main. A skip that exits 0 is indistinguishable from a pass.
 # GIT_CEILING_DIRECTORIES stops git walking above $TMP, making the condition hold
 # regardless of where TMPDIR lives, rather than merely detecting when it does not.
 # GIT_CEILING_DIRECTORIES is matched against the PHYSICAL path -- a symlinked TMPDIR
 # (/tmp is commonly one) makes the logical path never match, and the ceiling silently
 # does nothing. Resolve it before exporting.
 TMP="$(cd "$TMP" && pwd -P)"
 export GIT_CEILING_DIRECTORIES="$TMP"
 if ( cd "$TMP" && git rev-parse --git-dir >/dev/null 2>&1 ); then
    echo "  FAIL  scratch dir is inside a git repo even with GIT_CEILING_DIRECTORIES set;"
    echo "        the outside-a-repo precondition cannot be established -- refusing to report a result"
    exit 1
 fi
 echo "== outside a git repo: rc=1 AND the diagnostic is emitted =="
 check "detect_platform" "$(run_outside detect_platform)" "1:yes"
 check "get_repo_info"   "$(run_outside get_repo_info)"   "1:yes"
 echo "== inside a git repo the functions still work =="
 git init -q "$TMP/repo" 2>/dev/null
 git -C "$TMP/repo" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git 2>/dev/null
 out=$( cd "$TMP/repo" && bash -c "set -e; source '$HERE/detect-platform.sh'; detect_platform" 2>&1 ); rc=$?
 if [ "$rc" -eq 0 ] && grep -qi 'gitea' <<<"$out"; then echo "  PASS  detect_platform in-repo (rc=0, $out)"
 else echo "  FAIL  detect_platform in-repo: rc=$rc out=$out"; fail=1; fi
 [ "$fail" -eq 0 ] && echo "OK  detect-platform fails loudly outside a repo" || echo "FAILED"
 exit "$fail"
@@ -0,0 +1,64 @@
 #!/bin/bash
 # Regression: the tea-failure diagnostic must be STATUS-NEUTRAL.
 #
 # Found by be-coder-08 reviewing PR #1086. At all three call sites the diagnostic is emitted
 # immediately BEFORE the Gitea API fallback. Written as the last command of an && list:
 #     declare -F explain_... >/dev/null && explain_...
 # under `set -e` a FAILING diagnostic exits and the fallback never runs -- a diagnostic that
 # suppresses the recovery path it exists to explain. It misbehaves ONLY when the helper is
 # PRESENT, so the helper-absent path (pre-#1086 behaviour) keeps working and reads as a
 # passing control.
 #
 # TWO DEFECTS IN THE FIRST VERSION OF THIS TEST, both found by be-coder-08:
 #   1. `out=$( ... ) 2>"$errto"` applies the redirection to the ASSIGNMENT, not to the
 #      command substitution, so the probe's stderr was never actually pointed at /dev/full
 #      and the /dev/full rows proved nothing. Verified: `out=$(echo x >&2) 2>/dev/full`
 #      leaks to the terminal and returns 0; the redirect must be INSIDE the substitution.
 #   2. `eval "$CONSTRUCT"` changes `set -e` semantics for a bare && list, so the probe did
 #      not exercise the construct as the shipped file executes it. It now writes the line
 #      into a real script and runs it -- same parse, same set -e rules, no eval.
 # The construct is still LIFTED FROM THE SHIPPED FILE: retyping the fixed form makes the
 # probe pass on a build whose real call sites still carry the bare && form.
 set -uo pipefail
 fail=0
 GIT_DIR_UNDER_TEST="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
 probe() { # $1=present|absent  $2=stderr target  $3=source file  -> "rc:fallback"
    local helper="$1" errto="$2" src="$3" construct script out rc
    construct=$(grep -m1 'explain_tea_user_does_not_exist' "$GIT_DIR_UNDER_TEST/$src" | sed 's/^[[:space:]]*//')
    [ -n "$construct" ] || { printf 'no-construct:no'; return; }
    script="$TMP/probe.sh"
    {
        echo '#!/bin/bash'
        echo 'set -e'
        echo 'explain_tea_user_does_not_exist() { echo "diagnostic" >&2; }'
        [ "$helper" = absent ] && echo 'unset -f explain_tea_user_does_not_exist'
        echo "$construct"                # the shipped line, parsed by a real shell
        echo 'echo FALLBACK_REACHED'
    } > "$script"
    # redirect INSIDE the substitution so the subshell's stderr really is $errto
    out=$( bash "$script" 2>"$errto" ); rc=$?
    printf '%s:%s' "$rc" "$(grep -q FALLBACK_REACHED <<<"$out" && echo yes || echo no)"
 }
 check() { if [ "$2" = "$3" ]; then echo "  PASS  $1 ($2)"; else echo "  FAIL  $1: got $2, want $3"; fail=1; fi; }
 echo "== diagnostic must not alter exit status or skip the fallback =="
 # /dev/full makes every stderr write fail -- the real-world shape is a closed or full fd.
 for src in pr-create.sh issue-view.sh issue-create.sh; do
    check "$src stderr OK      / helper present" "$(probe present /dev/null "$src")" "0:yes"
    check "$src stderr OK      / helper absent " "$(probe absent  /dev/null "$src")" "0:yes"
    check "$src stderr FAILING / helper present" "$(probe present /dev/full "$src")" "0:yes"
    check "$src stderr FAILING / helper absent " "$(probe absent  /dev/full "$src")" "0:yes"
 done
 echo "== all three call sites use the status-neutral form =="
 for f in pr-create.sh issue-view.sh issue-create.sh; do
    p="$GIT_DIR_UNDER_TEST/$f"
    grep -q '{ declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist; } || true' "$p" \
        && echo "  PASS  $f guarded" || { echo "  FAIL  $f: diagnostic is not status-neutral"; fail=1; }
 done
 [ "$fail" -eq 0 ] && echo "OK  diagnostic is status-neutral" || echo "FAILED"
 exit "$fail"
@@ -7,14 +7,40 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/gitea-login-resolution}"
 REPO_DIR="$WORK_DIR/repo"
 BIN_DIR="$WORK_DIR/bin"
 HOME_DIR="$WORK_DIR/home"
 LOG_FILE="$WORK_DIR/calls.log"
 CREDENTIALS_FILE="$WORK_DIR/credentials.json"
 rm -rf "$WORK_DIR"
-mkdir -p "$REPO_DIR" "$BIN_DIR"
+mkdir -p "$REPO_DIR" "$BIN_DIR" "$HOME_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.uscllc.com/USC/uconnect.git
 # HERMETICITY (#1007) — TWO mechanisms with DIFFERENT jobs; do not conflate them.
 #
 # OPERATIVE: the empty repo-local `mosaic.gitIdentity` below. get_gitea_token()
 # step 0 resolves a per-agent identity from `git config --get mosaic.gitIdentity`,
 # which on a provisioned agent seat is set GLOBALLY and so leaks into this fresh
 # repo. It then reads a REAL per-slot token from $HOME and returns it WITHOUT ever
 # consulting MOSAIC_CREDENTIALS_FILE, so the fixture credentials below are silently
 # ignored. This suite is the one where the consequence is not subtle: it FAILS
 # outright on a provisioned seat (rc=1 bare, rc=0 with $HOME sandboxed, one
 # variable changed) and passes everywhere else, including CI, which has no
 # per-agent token to leak.
 #
 # CONTAINMENT: the sandboxed HOME in the four run helpers below. It only has to
 # bound a failure that the pin should already have prevented.
 #
 # NOTE FOR ANYONE AUDITING THIS SUITE: the sandboxed HOME is containment, NOT an
 # assay. Running a suite under a decoy HOME to test for this defect REMOVES the
 # trigger — ~/.gitconfig is where the global identity lives, so step 0 is skipped
 # by construction and every suite reads clean however vulnerable it is. To measure,
 # REPLICATE a seat (a decoy HOME whose .gitconfig sets mosaic.gitIdentity, with no
 # per-slot token) so step 0 reaches its fail-loud branch.
 #
 # Note the env-var route does NOT work: detect-platform.sh reads
 # "${MOSAIC_GIT_IDENTITY:-}", and `:-` treats set-but-empty identically to unset.
 git -C "$REPO_DIR" config mosaic.gitIdentity ""
 cat > "$CREDENTIALS_FILE" <<'JSON'
 {
@@ -86,6 +112,7 @@ run_in_repo() {
    (
        cd "$REPO_DIR"
        PATH="$BIN_DIR:$PATH" \
        HOME="$HOME_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        MOSAIC_TEST_LOG="$LOG_FILE" \
        "$@"
@@ -283,6 +310,7 @@ run_in_repo2() {
    (
        cd "$REPO_DIR"
        PATH="$BIN_DIR2:$PATH" \
        HOME="$HOME_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        MOSAIC_TEST_LOG="$LOG_FILE" \
        "$@"
@@ -343,7 +371,7 @@ write_fixture() { printf '%s' "$1" > "$FIXTURE_XDG/tea/config.yml"; }
 token_fallback() {
    (
        cd "$REPO_DIR"
-        XDG_CONFIG_HOME="$FIXTURE_XDG" PYTHONPATH="$NOYAML_DIR" bash -c '
+        HOME="$HOME_DIR" XDG_CONFIG_HOME="$FIXTURE_XDG" PYTHONPATH="$NOYAML_DIR" bash -c '
            source "'"$SCRIPT_DIR"'/detect-platform.sh"
            get_gitea_token_for_login "$1" "$2"
        ' _ "$1" "$2"
@@ -354,7 +382,7 @@ token_fallback() {
 token_pyyaml() {
    (
        cd "$REPO_DIR"
-        XDG_CONFIG_HOME="$FIXTURE_XDG" bash -c '
+        HOME="$HOME_DIR" XDG_CONFIG_HOME="$FIXTURE_XDG" bash -c '
            source "'"$SCRIPT_DIR"'/detect-platform.sh"
            get_gitea_token_for_login "$1" "$2"
        ' _ "$1" "$2"
@@ -0,0 +1,150 @@
 #!/usr/bin/env bash
 # Regression: issue-close.sh must NOT close an issue when the closing comment could not
 # be posted, and comment+close must be made by ONE principal.
 #
 # Guards two defects fixed together (see #1081):
 #   1. `tea issue comment` is not a subcommand -- tea exposes comments as the TOP-LEVEL
 #      `tea comment`. The old call always failed, was unchecked, and the issue closed
 #      anyway, losing the record of WHY it was closed.
 #   2. Routing the comment through the token-authenticated API helper while the close
 #      used --login would attribute one operation to two principals.
 #
 # SAFETY (rev-974, #1085 review 130): this test previously ran under `set -uo pipefail`
 # with unchecked mkdir/redirect/cd, then prepended a possibly-nonexistent $MOCK_BIN to
 # PATH -- while `git remote add origin` names the REAL repository. Forcing setup failure
 # with an unwritable AGENT_WORK_ROOT made it `git init` in its CALLER's directory and
 # invoke the real, provider-mutating issue-close.sh. Setup now fails closed, and both
 # `tea` and `curl` are asserted to resolve INSIDE $MOCK_BIN before any target run.
 set -euo pipefail
 # NOTE: with `set -e`, `grep -q X && fail "..."` is a trap -- the ABSENT case (grep rc=1,
 # which is the PASSING case for a must-not-appear assertion) is the last command of an &&
 # list and silently terminates the script with no message. Every must-not-appear check
 # below is therefore an if-block. This is the same set -e + &&-list defect be-coder-08
 # found in #1086, reintroduced here by adding `set -e` for the sandbox-safety fix.
 WORK_ROOT="${AGENT_WORK_ROOT:-${TMPDIR:-/tmp}}"
 SANDBOX="$WORK_ROOT/issue-close-fail-closed-test-$$"
 MOCK_BIN="$SANDBOX/bin"; REPO_DIR="$SANDBOX/repo"; CALLS="$SANDBOX/calls.log"
 cleanup() { rm -rf "$SANDBOX"; }
 trap cleanup EXIT
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET="$SCRIPT_DIR/issue-close.sh"
 [ -f "$TARGET" ] || { echo "FAIL: issue-close.sh not found beside this test"; exit 1; }
 fail() { echo "FAIL: $*"; exit 1; }
 # Every setup step is checked. Under `set -e` these abort; the explicit || fail keeps the
 # reason legible instead of a bare non-zero exit.
 mkdir -p "$MOCK_BIN" "$REPO_DIR" || fail "setup: cannot create sandbox under $WORK_ROOT"
 : > "$CALLS"                     || fail "setup: cannot write calls log at $CALLS"
 cd "$REPO_DIR"                   || fail "setup: cannot cd into $REPO_DIR"
 git init -q                      || fail "setup: git init failed"
 git remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git || fail "setup: git remote add failed"
 export PATH="$MOCK_BIN:$PATH" CALLS
 export GITEA_URL="https://git.mosaicstack.dev"
 export GITEA_TOKEN="redacted-test-token"
 cat > "$MOCK_BIN/curl" <<'EOF'
 #!/bin/bash
 method=GET; url=""
 while [ $# -gt 0 ]; do
    case "$1" in
        -X) method="$2"; shift 2 ;;
        http*|https*) url="$1"; shift ;;
        *) shift ;;
    esac
 done
 printf 'curl %s %s\n' "$method" "$url" >> "$CALLS"
 [ "${MOCK_CURL_FAIL:-}" = "1" ] && [ "$method" = "POST" ] && exit 22
 exit 0
 EOF
 chmod +x "$MOCK_BIN/curl"
 mk_tea() {  # $1 = exit code for a comment attempt; $2 = login list (empty => no login)
    local rc="$1" login="${2-}"
    cat > "$MOCK_BIN/tea" <<EOF
 #!/bin/bash
 printf 'tea %s\n' "\$*" >> "$CALLS"
 if [[ "\$*" == *"login list"* ]]; then
    printf '%s\n' '${login}'; exit 0
 fi
 # Fail ANY comment attempt -- both the correct top-level \`tea comment\` and the broken
 # \`tea issue comment\` -- so an unfixed script exercises the DEFECT rather than tripping
 # a setup assertion.
 if [[ "\$1" == "comment" || ( "\$1" == "issue" && "\$2" == "comment" ) ]]; then exit $rc; fi
 exit 0
 EOF
    chmod +x "$MOCK_BIN/tea"
 }
 LOGIN_JSON='[{"name":"git.mosaicstack.dev","url":"https://git.mosaicstack.dev"}]'
 # The mocks must be the ones that run. Without this, a failed setup silently falls through
 # to the real tea/curl and the "test" mutates the real provider.
 assert_mocked() {
    local w
    for w in tea curl; do
        p=$(command -v "$w" || true)
        [ -n "$p" ] || fail "SAFETY: $w does not resolve at all"
        case "$p" in
            "$MOCK_BIN"/*) : ;;
            *) fail "SAFETY: $w resolves to $p, OUTSIDE the sandbox -- refusing to invoke the target" ;;
        esac
    done
 }
 run_target() {  # never let a target failure abort the test; we assert on rc
    # Call sites MUST use `rc=0; run_target ... || rc=$?` -- a bare `run_target ...; rc=$?`
    # lets the non-zero RETURN trip set -e in the CALLER before rc is ever read.
    set +e; bash "$TARGET" "$@" >/dev/null 2>&1; local rc=$?; set -e; return $rc
 }
 # ── tea path ────────────────────────────────────────────────────────────────────────
 # 1. NEGATIVE (the regression): comment fails => must NOT close, must exit non-zero
 mk_tea 1 "$LOGIN_JSON"; : > "$CALLS"; assert_mocked
 rc=0; run_target -i 42 -c "closing note" || rc=$?
 grep -qE 'tea (issue )?comment' "$CALLS" || fail "no comment attempt -- setup did not reach the tea branch"
 if grep -q 'tea issue close' "$CALLS"; then fail "ISSUE CLOSED AFTER THE COMMENT FAILED -- the regression"; fi
 [ "$rc" -ne 0 ] || fail "comment failed but issue-close exited 0 -- FAIL-OPEN"
 # 2. POSITIVE: comment succeeds => close proceeds, exit 0
 mk_tea 0 "$LOGIN_JSON"; : > "$CALLS"; assert_mocked
 rc=0; run_target -i 42 -c "closing note" || rc=$?
 [ "$rc" -eq 0 ] || fail "comment succeeded but issue-close exited $rc"
 grep -q 'tea issue close' "$CALLS" || fail "issue not closed even though the comment succeeded"
 # 3. must use top-level `tea comment`, never `tea issue comment`
 if grep -q 'tea issue comment' "$CALLS"; then fail "used 'tea issue comment' -- not a valid subcommand"; fi
 # 4. ONE PRINCIPAL: comment and close must carry the SAME --login
 c=$(grep -m1 '^tea comment'     "$CALLS" | grep -o -- '--login [^ ]*' | awk '{print $2}')
 k=$(grep -m1 '^tea issue close' "$CALLS" | grep -o -- '--login [^ ]*' | awk '{print $2}')
 [ -n "$c" ] || fail "comment carried no --login"
 [ "$c" = "$k" ] || fail "MIXED PRINCIPALS: comment=$c close=$k"
 # ── no-login / API fallback path ────────────────────────────────────────────────────
 # rev-974: the delta also adds fail-closed behaviour to this branch, and the suite never
 # reached it -- replacing the whole fallback contract with an unconditional close still
 # passed. These assert the POSTCONDITION (which HTTP calls happened, in what order),
 # not merely that a command ran.
 # 5. no login + comment FAILS => POST attempted, NO PATCH, non-zero
 mk_tea 0 ""; : > "$CALLS"; assert_mocked
 rc=0; MOCK_CURL_FAIL=1 run_target -i 42 -c "closing note" || rc=$?
 grep -q 'curl POST' "$CALLS" || fail "API path: no comment POST attempted"
 if grep -q 'curl PATCH' "$CALLS"; then fail "API path: ISSUE CLOSED (PATCH) AFTER THE COMMENT POST FAILED"; fi
 [ "$rc" -ne 0 ] || fail "API path: comment failed but exited 0 -- FAIL-OPEN"
 # 6. no login + comment SUCCEEDS => POST strictly BEFORE PATCH, exit 0
 mk_tea 0 ""; : > "$CALLS"; assert_mocked
 rc=0; run_target -i 42 -c "closing note" || rc=$?
 [ "$rc" -eq 0 ] || fail "API path: comment succeeded but exited $rc"
 order=$(grep -oE 'curl (POST|PATCH)' "$CALLS" | awk '{print $2}' | paste -sd, -)
 [ "$order" = "POST,PATCH" ] || fail "API path: expected POST,PATCH -- got '${order:-<none>}'"
 # 7. no login + NO comment => PATCH only, never a POST
 mk_tea 0 ""; : > "$CALLS"; assert_mocked
 rc=0; run_target -i 42 || rc=$?
 [ "$rc" -eq 0 ] || fail "API path: no-comment close exited $rc"
 if grep -q 'curl POST' "$CALLS"; then fail "API path: posted a comment when none was requested"; fi
 grep -q 'curl PATCH' "$CALLS" || fail "API path: issue not closed when no comment was requested"
 echo "issue-close.sh fail-closed + single-principal regression passed"
@@ -61,15 +61,54 @@ STATE_FILE="$WORK_DIR/comments.json"
 # A dedicated scratch dir the wrapper is pointed at via TMPDIR, so the leak
 # check can assert every POST/GET body + metadata temp file is cleaned up.
 TMP_SCRATCH="$WORK_DIR/scratch"
 HOME_DIR="$WORK_DIR/home"
 cleanup() {
    rm -rf "$WORK_DIR"
 }
 trap cleanup EXIT
-mkdir -p "$REPO_DIR" "$BIN_DIR" "$XDG_DIR" "$TMP_SCRATCH"
+mkdir -p "$REPO_DIR" "$BIN_DIR" "$XDG_DIR" "$TMP_SCRATCH" "$HOME_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
 # HERMETICITY (#1007) — TWO mechanisms with DIFFERENT jobs; do not conflate them.
 #
 # OPERATIVE: the empty repo-local `mosaic.gitIdentity` below. get_gitea_token()
 # step 0 resolves a per-agent identity from `git config --get mosaic.gitIdentity`,
 # which on a provisioned agent seat is set GLOBALLY and so leaks into this fresh
 # repo. It then reads a REAL per-slot token from $HOME and returns it WITHOUT ever
 # consulting MOSAIC_CREDENTIALS_FILE, so the fixture credential below is silently
 # ignored. The stub curl then rejects the unrecognised bearer, and this suite
 # fails at its FIRST case with `Gitea authenticated-identity read failed with
 # HTTP 401`. An empty repo-local value shadows the global one and reads back
 # empty at rc=0. Measured: without this pin the suite is RED on every seat.
 #
 # CONTAINMENT: the sandboxed HOME in run_comment(). It only has to bound a
 # failure that the pin should already have prevented.
 #
 # THIS SUITE WAS THE HARDEST OF THE FIVE TO SEE, and the reason is worth stating
 # because it generalises: run_comment() sends the wrapper's stdout AND stderr to
 # $OUTPUT_FILE, and the EXIT trap above deletes $WORK_DIR. So the 401 — the only
 # thing that says what went wrong — exists only inside a directory that is gone
 # by the time anyone looks. The suite exits 1 with ZERO bytes on stdout and
 # stderr. A suite that discards or deletes its own evidence turns any post-hoc
 # assay into a non-measurement: "nothing found" there means "no surviving
 # trace", never "clean". It was found by intercepting the identity read at its
 # SOURCE (a PATH shim over `git` logging every `mosaic.gitIdentity` read to a
 # file outside $WORK_DIR), which is deletion-proof by construction, rather than
 # by grepping for the symptom.
 #
 # NOTE FOR ANYONE AUDITING THIS SUITE: the sandboxed HOME is containment, NOT an
 # assay. Running a suite under a decoy HOME to test for this defect REMOVES the
 # trigger — ~/.gitconfig is where the global identity lives, so step 0 is skipped
 # by construction and every suite reads clean however vulnerable it is. To
 # measure, REPLICATE a seat (a decoy HOME whose .gitconfig sets
 # mosaic.gitIdentity, with no per-slot token) so step 0 reaches its fail-loud
 # branch — or intercept the read as described above.
 #
 # Note the env-var route does NOT work: detect-platform.sh reads
 # "${MOSAIC_GIT_IDENTITY:-}", and `:-` treats set-but-empty identically to unset.
 git -C "$REPO_DIR" config mosaic.gitIdentity ""
 ISSUE_NUMBER=7
 REPO_SLUG="mosaicstack/stack"
@@ -280,7 +319,10 @@ print("201")
 print(json.dumps(record))
 PY
 )
-    write_response "$(printf '%s' "$result" | head -n1)" "$(printf '%s' "$result" | tail -n +2)"
+    response_status="${result%%$'\n'*}"
    response_body=""
    [[ "$result" == *$'\n'* ]] && response_body="${result#*$'\n'}"
    write_response "$response_status" "$response_body"
 elif [[ "$method" == "GET" && "$path" == "$ISSUE_COMMENT_API_BASE"/issues/comments/* ]]; then
    result=$(ISSUE_COMMENT_GET_ID="${path##*/}" python3 - <<'PY'
 import json
@@ -299,7 +341,10 @@ else:
    print(json.dumps(match))
 PY
 )
-    write_response "$(printf '%s' "$result" | head -n1)" "$(printf '%s' "$result" | tail -n +2)"
+    response_status="${result%%$'\n'*}"
    response_body=""
    [[ "$result" == *$'\n'* ]] && response_body="${result#*$'\n'}"
    write_response "$response_status" "$response_body"
 else
    echo "Unexpected curl request: $method $url" >&2
    exit 97
@@ -366,6 +411,7 @@ run_comment() {
        cd "$REPO_DIR"
        PATH="$BIN_DIR:$PATH" \
        TMPDIR="$TMP_SCRATCH" \
        HOME="$HOME_DIR" \
        XDG_CONFIG_HOME="$XDG_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        ISSUE_COMMENT_TEA_LOG="$TEA_LOG" \
@@ -7,13 +7,38 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/issue-create-interactive-auth}"
 REPO_DIR="$WORK_DIR/repo"
 BIN_DIR="$WORK_DIR/bin"
 HOME_DIR="$WORK_DIR/home"
 LOG_FILE="$WORK_DIR/calls.log"
 CREDENTIALS_FILE="$WORK_DIR/credentials.json"
 rm -rf "$WORK_DIR"
-mkdir -p "$REPO_DIR" "$BIN_DIR"
+mkdir -p "$REPO_DIR" "$BIN_DIR" "$HOME_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
 # HERMETICITY (#1007) — TWO mechanisms with DIFFERENT jobs; do not conflate them.
 #
 # OPERATIVE: the empty repo-local `mosaic.gitIdentity` below. get_gitea_token()
 # step 0 resolves a per-agent identity from `git config --get mosaic.gitIdentity`,
 # which on a provisioned agent seat is set GLOBALLY and so leaks into this fresh
 # repo. It then reads a REAL per-slot token from $HOME and returns it WITHOUT ever
 # consulting MOSAIC_CREDENTIALS_FILE, so the fixture credential below is silently
 # ignored and the suite runs against a production credential. An empty repo-local
 # value shadows the global one and reads back empty at rc=0. Measured: this suite
 # resolves a per-slot token without it.
 #
 # CONTAINMENT: the sandboxed HOME in run_wrapper(). It only has to bound a failure
 # that the pin should already have prevented.
 #
 # NOTE FOR ANYONE AUDITING THIS SUITE: the sandboxed HOME is containment, NOT an
 # assay. Running a suite under a decoy HOME to test for this defect REMOVES the
 # trigger — ~/.gitconfig is where the global identity lives, so step 0 is skipped
 # by construction and every suite reads clean however vulnerable it is. To measure,
 # REPLICATE a seat (a decoy HOME whose .gitconfig sets mosaic.gitIdentity, with no
 # per-slot token) so step 0 reaches its fail-loud branch.
 #
 # Note the env-var route does NOT work: detect-platform.sh reads
 # "${MOSAIC_GIT_IDENTITY:-}", and `:-` treats set-but-empty identically to unset.
 git -C "$REPO_DIR" config mosaic.gitIdentity ""
 cat > "$CREDENTIALS_FILE" <<'JSON'
 {"gitea":{"mosaicstack":{"url":"https://git.mosaicstack.dev","token":"test-token"}}}
@@ -50,6 +75,7 @@ run_wrapper() {
  (
    cd "$REPO_DIR"
    PATH="$BIN_DIR:$PATH" \
    HOME="$HOME_DIR" \
    MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
    MOSAIC_TEST_LOG="$LOG_FILE" \
    "$@"
@@ -69,7 +69,7 @@ section_nums() { # $1 = output  $2 = header-prefix
 }
 fail() { echo "FAIL: $1" >&2; exit 1; }
-contains() { printf '%s\n' "$1" | grep -qx "$2"; }
+contains() { grep -qx "$2" <<<"$1"; }
 # ---------------------------------------------------------------------------
 # Fixed (current) script behavior
@@ -8,6 +8,7 @@ WORK_ROOT="${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
 SANDBOX="$WORK_ROOT/pr-merge-empty-uid-test-$$"
 MOCK_BIN="$SANDBOX/bin"
 REPO_DIR="$SANDBOX/repo"
 HOME_DIR="$SANDBOX/home"
 LOG_FILE="$SANDBOX/mock.log"
 cleanup() {
@@ -15,7 +16,7 @@ cleanup() {
 }
 trap cleanup EXIT
-mkdir -p "$MOCK_BIN" "$REPO_DIR"
+mkdir -p "$MOCK_BIN" "$REPO_DIR" "$HOME_DIR"
 : > "$LOG_FILE"
 cat > "$MOCK_BIN/tea" <<'EOF'
@@ -51,22 +52,23 @@ for arg in "$@"; do
        prev=""
        continue
    fi
-    if [[ "$prev" == "-d" ]]; then
+    if [[ "$prev" == "data" ]]; then
        post_data="$arg"
        [[ "$post_data" == @* ]] && post_data=$(<"${post_data#@}")
        prev=""
        continue
    fi
-    if [[ "$arg" == "-o" ]]; then
+    if [[ "$prev" == "config" ]]; then
-        prev="-o"
+        [[ "$arg" == "-" ]] && cat >/dev/null
        prev=""
        continue
    fi
-    if [[ "$arg" == "-d" ]]; then
+    case "$arg" in
-        prev="-d"
+        -o) prev="-o" ;;
-        continue
+        -d|--data|--data-binary) prev="data" ;;
-    fi
+        -K|--config) prev="config" ;;
-    if [[ "$arg" == "-w" ]]; then
+        -w) write_code=true ;;
-        write_code=true
+    esac
    fi
 done
 emit_response() {
    local body="$1"
@@ -108,7 +110,48 @@ chmod +x "$MOCK_BIN/curl"
 cd "$REPO_DIR"
 git init -q
 git remote add origin https://git.mosaicstack.dev/mosaicstack/stack.git
 # HERMETICITY (#1007) — TWO mechanisms with DIFFERENT jobs; do not conflate them.
 #
 # OPERATIVE: the empty repo-local `mosaic.gitIdentity` below. get_gitea_token()
 # step 0 resolves a per-agent identity from `git config --get mosaic.gitIdentity`,
 # which on a provisioned agent seat is set GLOBALLY and so leaks into this fresh
 # repo. Step 0 runs BEFORE the credential loader AND before the GITEA_TOKEN env
 # check, so the `GITEA_TOKEN=redacted-test-token` exported below is silently
 # overridden and a REAL per-slot token from $HOME is what flows through the
 # wrapper. Measured on a provisioned seat before this pin: all 5 mock-curl calls
 # carried the real per-slot token in argv and the fixture token was never used at
 # ALL. Three consequences specific to this suite:
 #   1. pr-merge.sh passes the token as `-H "Authorization: token $token"` and the
 #      mock curl logs full argv, so the real credential is written to $LOG_FILE
 #      on disk — transiently: the suite truncates that file between phases and
 #      the EXIT trap removes $SANDBOX, so it leaves NO post-hoc trace. That is
 #      why this suite was the hardest of the three to detect; observing it needs
 #      an instrument that captures argv while the run is live.
 #   2. Every failure path dumps $OUTPUT/$LOG_FILE to stderr through
 #      `sed 's/redacted-test-token/***REDACTED***/g'` — a redaction pattern that
 #      is the literal fixture string and therefore CANNOT match the token
 #      actually in use.
 #   3. The leak assertion at "Token leaked to pr-merge.sh output" greps for that
 #      same fixture string, so on a provisioned seat it passes vacuously: it is
 #      searching for a value the run never used.
 # An empty repo-local value shadows the global one and reads back empty at rc=0.
 #
 # CONTAINMENT: the sandboxed HOME exported below. It only has to bound a failure
 # that the pin should already have prevented.
 #
 # NOTE FOR ANYONE AUDITING THIS SUITE: the sandboxed HOME is containment, NOT an
 # assay. Running a suite under a decoy HOME to test for this defect REMOVES the
 # trigger — ~/.gitconfig is where the global identity lives, so step 0 is skipped
 # by construction and every suite reads clean however vulnerable it is. To measure,
 # REPLICATE a seat (a decoy HOME whose .gitconfig sets mosaic.gitIdentity, with no
 # per-slot token) so step 0 reaches its fail-loud branch.
 #
 # Note the env-var route does NOT work: detect-platform.sh reads
 # "${MOSAIC_GIT_IDENTITY:-}", and `:-` treats set-but-empty identically to unset.
 git -C "$REPO_DIR" config mosaic.gitIdentity ""
 # $SANDBOX/$HOME_DIR were derived from the real $HOME above, before this export.
 export HOME="$HOME_DIR"
 export PATH="$MOCK_BIN:$PATH"
 export PR_MERGE_TEST_LOG="$LOG_FILE"
 export GITEA_LOGIN="git.mosaicstack.dev"
@@ -36,13 +36,30 @@ cat > "$WORK_DIR/gitea/curl" <<'SH'
 #!/usr/bin/env bash
 set -euo pipefail
 payload=""
-for ((i=1; i<=$#; i++)); do
+out_file=""
-    if [[ "${!i}" == "-d" ]]; then
+while [[ $# -gt 0 ]]; do
-        j=$((i + 1))
+    case "$1" in
-        payload="${!j}"
+        -d|--data|--data-binary)
-    fi
+            payload="$2"
            [[ "$payload" == @* ]] && payload=$(<"${payload#@}")
            shift 2
            ;;
        -o)
            out_file="$2"
            shift 2
            ;;
        -K|--config)
            [[ "$2" == "-" ]] && cat >/dev/null
            shift 2
            ;;
        -w|-X|-H)
            shift 2
            ;;
        *) shift ;;
    esac
 done
 printf '%s' "$payload" > "${MOSAIC_MERGE_PAYLOAD_LOG:?}"
 [[ -n "$out_file" ]] && printf '{}' > "$out_file"
 printf '200'
 SH
 chmod +x "$WORK_DIR/gitea/curl"
@@ -0,0 +1,541 @@
 #!/usr/bin/env bash
 # Regression harness for the optional, identity-checked Gitea squash message.
 set -u
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SUBJECT="${MOSAIC_TEST_SUBJECT:-$SCRIPT_DIR/pr-merge.sh}"
 WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-message-field}"
 ORIG_PATH="$PATH"
 failures=0
 rm -rf "$WORK_DIR"
 mkdir -p "$WORK_DIR"
 fail() {
    echo "FAIL $1" >&2
    failures=$((failures + 1))
 }
 make_case() {
    local name="$1" case_dir
    case_dir="$WORK_DIR/$name"
    mkdir -p "$case_dir/bin" "$case_dir/agent"
    cp "$SUBJECT" "$case_dir/pr-merge.sh"
    chmod +x "$case_dir/pr-merge.sh"
    cat > "$case_dir/detect-platform.sh" <<'SH'
 #!/usr/bin/env bash
 detect_platform() { PLATFORM=gitea; printf 'gitea\n'; }
 get_repo_owner() { printf 'acme\n'; }
 get_repo_name() { printf 'widgets\n'; }
 get_remote_host() { printf 'git.example.test\n'; }
 get_gitea_token() {
    printf 'resolved\n' >> "${MOSAIC_TEST_TOKEN_RESOLUTION_LOG:?}"
    if [[ "${MOSAIC_TEST_TOKEN_AVAILABLE:-true}" != "true" ]]; then
        return 1
    fi
    printf 'fixture-token\n'
 }
 get_gitea_basic_auth() {
    printf 'resolved\n' >> "${MOSAIC_TEST_BASIC_RESOLUTION_LOG:?}"
    if [[ "${MOSAIC_TEST_BASIC_AVAILABLE:-false}" == "true" ]]; then
        printf 'fixture-user:fixture-password\n'
        return "${MOSAIC_TEST_BASIC_RC:-0}"
    fi
    return 1
 }
 get_gitea_login_for_host() { return 1; }
 SH
    cat > "$case_dir/pr-metadata.sh" <<'SH'
 #!/usr/bin/env bash
 if [[ "${MOSAIC_TEST_TITLE_MODE:-safe}" == "injection" ]]; then
    title='Preserve authors\n\nCo-authored-by: victim <[email protected]>'
 else
    title='Preserve both branch authors'
 fi
 case "${MOSAIC_TEST_COMMITS_MODE:?}" in
    verified) head_sha=2222222222222222222222222222222222222222 ;;
    null-login|unsafe-identity) head_sha=3333333333333333333333333333333333333333 ;;
    single) head_sha=1111111111111111111111111111111111111111 ;;
    *) echo "unknown commits mode" >&2; exit 2 ;;
 esac
 printf '{"number":42,"title":"%s","author":"poster","baseRefName":"main","headRefName":"feature/fixture","headRefOid":"%s","headRepository":"acme/widgets"}\n' "$title" "$head_sha"
 SH
    cat > "$case_dir/ci-queue-wait.sh" <<'SH'
 #!/usr/bin/env bash
 exit 0
 SH
    cat > "$case_dir/bin/python3" <<'SH'
 #!/usr/bin/env bash
 for arg in "$@"; do
    case "$arg" in
        *"Preserve both branch authors"*|*"[email protected]"*)
            : > "${MOSAIC_TEST_METADATA_ARGV_MARKER:?}"
            ;;
    esac
 done
 exec "${MOSAIC_TEST_REAL_PYTHON:?}" "$@"
 SH
    cat > "$case_dir/bin/curl" <<'SH'
 #!/usr/bin/env bash
 set -eu
 for arg in "$@"; do
    case "$arg" in
        *"Preserve both branch authors"*|*"[email protected]"*)
            : > "${MOSAIC_TEST_METADATA_ARGV_MARKER:?}"
            ;;
    esac
 done
 url=""
 method="GET"
 out_file=""
 data=""
 config=""
 auth_mode="none"
 has_max_filesize=0
 has_max_time=0
 has_connect_timeout=0
 while [[ $# -gt 0 ]]; do
    case "$1" in
        -o)
            out_file="$2"
            shift 2
            ;;
        -w)
            shift 2
            ;;
        -X)
            method="$2"
            shift 2
            ;;
        -d|--data|--data-binary)
            data="$2"
            if [[ "$data" == @* ]]; then
                data=$(<"${data#@}")
            fi
            shift 2
            ;;
        -K|--config)
            if [[ "$2" == "-" ]]; then
                config=$(cat)
            fi
            shift 2
            ;;
        --max-filesize)
            has_max_filesize=1
            shift 2
            ;;
        --max-time)
            has_max_time=1
            shift 2
            ;;
        --connect-timeout)
            has_connect_timeout=1
            shift 2
            ;;
        -H|--header|-u|--user)
            if [[ "$2" == *"fixture-token"* ]]; then
                : > "${MOSAIC_TEST_TOKEN_ARGV_MARKER:?}"
            fi
            if [[ "$2" == *"fixture-password"* ]]; then
                : > "${MOSAIC_TEST_BASIC_ARGV_MARKER:?}"
            fi
            shift 2
            ;;
        http://*|https://*)
            url="$1"
            shift
            ;;
        *)
            shift
            ;;
    esac
 done
 if [[ "$config" == *"Authorization: token fixture-token"* ]]; then
    auth_mode="token"
    : > "${MOSAIC_TEST_AUTH_CONFIG_MARKER:?}"
 elif [[ "$config" == *"user = \"fixture-user:fixture-password\""* ]]; then
    auth_mode="basic"
    : > "${MOSAIC_TEST_BASIC_CONFIG_MARKER:?}"
 fi
 printf '%s %s %s\n' "$method" "$auth_mode" "$url" >> "${MOSAIC_TEST_CURL_LOG:?}"
 printf '%s:%s:%s\n' "$has_max_filesize" "$has_max_time" "$has_connect_timeout" >> "${MOSAIC_TEST_CURL_BOUNDS_LOG:?}"
 case "$url" in
    */pulls/42)
        case "${MOSAIC_TEST_COMMITS_MODE:?}" in
            verified) head_sha=2222222222222222222222222222222222222222 ;;
            null-login|unsafe-identity) head_sha=3333333333333333333333333333333333333333 ;;
            single) head_sha=1111111111111111111111111111111111111111 ;;
            *) echo "unknown commits mode" >&2; exit 2 ;;
        esac
        if [[ "${MOSAIC_TEST_HEAD_MODE:-stable}" == "moved" ]]; then
            head_sha=4444444444444444444444444444444444444444
        fi
        body="{\"head\":{\"sha\":\"$head_sha\"}}"
        code=200
        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "inspection" && "$auth_mode" == "token" ]]; then
            body='{"message":"token rejected"}'
            code=401
        fi
        ;;
    */pulls/42/commits*)
        case "${MOSAIC_TEST_COMMITS_MODE:?}" in
            verified)
                if [[ "${MOSAIC_TEST_EMAIL_MODE:-safe}" == "escape" ]]; then
                    body='[{"sha":"2222222222222222222222222222222222222222","commit":{"author":{"name":"Alice","email":"alice+\u001b[[email protected]"}},"author":{"login":"alice"}},{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
                else
                    body='[{"sha":"2222222222222222222222222222222222222222","commit":{"author":{"name":"Alice","email":"[email protected]"}},"author":{"login":"alice"}},{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
                fi
                ;;
            null-login)
                body='[{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}},{"sha":"3333333333333333333333333333333333333333","commit":{"author":{"name":"Unresolved Author","email":"[email protected]\n\u001b[31m"}},"author":null}]'
                ;;
            unsafe-identity)
                body='[{"sha":"unsafe\n\u001b[31m","commit":{"author":{"name":"Unsafe","email":"not-an-email"}},"author":{"login":"unsafe"}},{"sha":"3333333333333333333333333333333333333333","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
                ;;
            single)
                body='[{"sha":"1111111111111111111111111111111111111111","commit":{"author":{"name":"Poster","email":"[email protected]"}},"author":{"login":"poster"}}]'
                ;;
            *)
                echo "unknown commits mode" >&2
                exit 2
                ;;
        esac
        code=200
        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "inspection" && "$auth_mode" == "token" ]]; then
            body='{"message":"token rejected"}'
            code=401
        fi
        ;;
    */pulls/42/merge)
        body='{}'
        code=200
        if [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "merge" && "$auth_mode" == "token" ]]; then
            body='{"message":"token rejected"}'
            code=401
        elif [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "provider-error" ]]; then
            body='{"message":"branch policy rejected\n\u001b[31m"}'
            code=409
        elif [[ "${MOSAIC_TEST_FALLBACK_MODE:-none}" == "forbidden" ]]; then
            body='{"message":"permission denied"}'
            code=403
        else
            printf '%s' "$data" > "${MOSAIC_TEST_MERGE_PAYLOAD:?}"
        fi
        ;;
    */users/*)
        body='{"message":"not found"}'
        code=404
        ;;
    *)
        body='{"message":"unexpected URL"}'
        code=500
        ;;
 esac
 if [[ -n "$out_file" ]]; then
    printf '%s' "$body" > "$out_file"
 else
    printf '%s' "$body"
 fi
 printf '%s' "$code"
 case "${MOSAIC_TEST_CURL_FAILURE:-none}" in
    oversize) exit 63 ;;
    stalled) exit 28 ;;
 esac
 SH
    chmod +x "$case_dir/detect-platform.sh" "$case_dir/pr-metadata.sh" \
        "$case_dir/ci-queue-wait.sh" "$case_dir/bin/curl" "$case_dir/bin/python3"
    printf '%s\n' "$case_dir"
 }
 run_case() {
    local case_dir="$1" mode="$2"
    shift 2
    MOSAIC_TEST_COMMITS_MODE="$mode" \
    MOSAIC_TEST_CURL_LOG="$case_dir/curl.log" \
    MOSAIC_TEST_CURL_BOUNDS_LOG="$case_dir/curl-bounds.log" \
    MOSAIC_TEST_MERGE_PAYLOAD="$case_dir/merge-payload.json" \
    MOSAIC_TEST_TOKEN_ARGV_MARKER="$case_dir/token-in-argv" \
    MOSAIC_TEST_BASIC_ARGV_MARKER="$case_dir/basic-in-argv" \
    MOSAIC_TEST_AUTH_CONFIG_MARKER="$case_dir/auth-via-config" \
    MOSAIC_TEST_BASIC_CONFIG_MARKER="$case_dir/basic-via-config" \
    MOSAIC_TEST_TOKEN_RESOLUTION_LOG="$case_dir/token-resolution.log" \
    MOSAIC_TEST_BASIC_RESOLUTION_LOG="$case_dir/basic-resolution.log" \
    MOSAIC_TEST_METADATA_ARGV_MARKER="$case_dir/metadata-in-argv" \
    MOSAIC_TEST_REAL_PYTHON="$(command -v python3)" \
    AGENT_WORK_ROOT="$case_dir/agent" \
    PATH="$case_dir/bin:$ORIG_PATH" \
        "$case_dir/pr-merge.sh" -n 42 "$@"
 }
 # Verified multi-author path: the non-poster trailer is built from one commit's
 # linked author.login and that same commit's author email. No /users lookup.
 verified_dir=$(make_case verified)
 set +e
 verified_output=$(run_case "$verified_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 verified_rc=$?
 set -e
 if [[ "$verified_rc" -ne 0 ]]; then
    fail "verified multi-author merge expected rc=0, got rc=$verified_rc: $verified_output"
 elif [[ ! -s "$verified_dir/merge-payload.json" ]]; then
    fail "verified multi-author merge did not reach the API payload"
 else
    python3 - "$verified_dir/merge-payload.json" <<'PY' || fail "verified payload did not preserve squash and exact message fields"
 import json
 import sys
 payload = json.load(open(sys.argv[1], encoding="utf-8"))
 assert payload == {
    "Do": "squash",
    "head_commit_id": "2222222222222222222222222222222222222222",
    "MergeTitleField": "Preserve both branch authors",
    "MergeMessageField": "Co-authored-by: alice <[email protected]>",
 }, payload
 PY
 fi
 [[ -e "$verified_dir/auth-via-config" ]] || fail "verified path did not authenticate curl through stdin config"
 [[ ! -e "$verified_dir/token-in-argv" ]] || fail "verified path placed the Gitea token in curl argv"
 [[ ! -e "$verified_dir/metadata-in-argv" ]] || fail "verified path placed PR title or contributor email in child argv"
 [[ "$(wc -l < "$verified_dir/token-resolution.log")" -eq 1 ]] || fail "verified path did not bind inspection and merge to one credential resolution"
 if grep -q '/users/' "$verified_dir/curl.log" 2>/dev/null; then
    fail "verified path performed a forbidden second /users lookup"
 fi
 if grep -qv '^1:1:1$' "$verified_dir/curl-bounds.log"; then
    fail "verified path did not apply size/max-time/connect-time bounds to every provider download"
 fi
 # A linked email containing a terminal escape must block before mutation.
 escape_email_dir=$(make_case escape-email)
 set +e
 escape_email_output=$(MOSAIC_TEST_EMAIL_MODE=escape run_case "$escape_email_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 escape_email_rc=$?
 set -e
 [[ "$escape_email_rc" -ne 0 ]] || fail "control-byte email unexpectedly passed"
 [[ "$escape_email_output" == *"unusable linked identity"* ]] || fail "control-byte email refusal lost its diagnostic"
 [[ ! -e "$escape_email_dir/merge-payload.json" ]] || fail "control-byte email reached the merge API"
 # Curl transfer and duration failures must remain failures even with HTTP 200.
 for failure_mode in oversize stalled; do
    failure_dir=$(make_case "curl-$failure_mode")
    set +e
    failure_output=$(MOSAIC_TEST_CURL_FAILURE="$failure_mode" run_case "$failure_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
    failure_rc=$?
    set -e
    [[ "$failure_rc" -ne 0 ]] || fail "curl $failure_mode failure was discarded: $failure_output"
    [[ ! -e "$failure_dir/merge-payload.json" ]] || fail "curl $failure_mode failure reached the merge API"
 done
 # The authenticated head is re-read under the mutation credential but cannot
 # replace the canonical preflight/review head. A move blocks before enumeration
 # or mutation even though the provider returned a valid new SHA.
 moved_dir=$(make_case moved-head)
 set +e
 moved_output=$(MOSAIC_TEST_HEAD_MODE=moved \
    run_case "$moved_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 moved_rc=$?
 set -e
 [[ "$moved_rc" -ne 0 ]] || fail "moved authenticated head unexpectedly passed"
 [[ "$moved_output" == *"authenticated PR head moved from reviewed"* ]] || fail "moved head refusal lost its diagnostic"
 [[ "$moved_output" == *"tl-mosaic"* ]] || fail "moved head refusal omitted the named escalation principal"
 [[ ! -e "$moved_dir/merge-payload.json" ]] || fail "moved head refusal reached the merge API"
 moved_sequence=$(awk '{print $1 ":" $2}' "$moved_dir/curl.log" | paste -sd, -)
 [[ "$moved_sequence" == "GET:token" ]] || fail "moved head refusal performed post-move inspection/mutation (calls=$moved_sequence)"
 # Token resolution failure is not an authentication response. It must fail
 # closed instead of borrowing a Basic credential under a different principal.
 token_missing_dir=$(make_case token-missing)
 set +e
 token_missing_output=$(MOSAIC_TEST_TOKEN_AVAILABLE=false MOSAIC_TEST_BASIC_AVAILABLE=true \
    run_case "$token_missing_dir" single 2>&1)
 token_missing_rc=$?
 set -e
 [[ "$token_missing_rc" -ne 0 ]] || fail "missing token unexpectedly borrowed Basic Auth"
 [[ "$token_missing_output" == *"required Gitea token"* ]] || fail "missing token refusal lost its diagnostic"
 [[ ! -e "$token_missing_dir/basic-resolution.log" ]] || fail "missing token resolved Basic Auth after identity failure"
 [[ ! -e "$token_missing_dir/curl.log" ]] || fail "missing token reached a provider request"
 # A failed Basic resolver must never use its nonempty output or reach mutation.
 basic_rc_dir=$(make_case basic-resolver-rc)
 set +e
 basic_rc_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_BASIC_RC=91 MOSAIC_TEST_FALLBACK_MODE=inspection \
    run_case "$basic_rc_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 basic_rc_rc=$?
 set -e
 [[ "$basic_rc_rc" -ne 0 ]] || fail "failed Basic resolver output unexpectedly authorized a merge: $basic_rc_output"
 [[ ! -e "$basic_rc_dir/merge-payload.json" ]] || fail "failed Basic resolver reached the merge API"
 # HTTP 401 never changes principals: inspection rejection fails closed without
 # resolving or attempting Basic Auth.
 fallback_inspect_dir=$(make_case fallback-inspection)
 set +e
 fallback_inspect_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=inspection \
    run_case "$fallback_inspect_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 fallback_inspect_rc=$?
 set -e
 [[ "$fallback_inspect_rc" -ne 0 ]] || fail "inspection token rejection unexpectedly changed principals"
 [[ "$fallback_inspect_output" == *"refusing cross-principal credential fallback"* ]] || fail "inspection token rejection lost its refusal diagnostic"
 [[ ! -e "$fallback_inspect_dir/basic-resolution.log" ]] || fail "inspection token rejection resolved Basic Auth"
 [[ ! -e "$fallback_inspect_dir/merge-payload.json" ]] || fail "inspection token rejection reached merge mutation"
 inspect_sequence=$(awk '{print $1 ":" $2}' "$fallback_inspect_dir/curl.log" | paste -sd, -)
 [[ "$inspect_sequence" == "GET:token" ]] || fail "inspection rejection made unexpected provider calls (calls=$inspect_sequence)"
 # Token rejection at merge likewise fails closed without cross-principal retry.
 fallback_merge_dir=$(make_case fallback-merge)
 set +e
 fallback_merge_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=merge \
    run_case "$fallback_merge_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 fallback_merge_rc=$?
 set -e
 [[ "$fallback_merge_rc" -ne 0 ]] || fail "merge token rejection unexpectedly changed principals"
 [[ "$fallback_merge_output" == *"refusing cross-principal credential fallback"* ]] || fail "merge token rejection lost its refusal diagnostic"
 [[ ! -e "$fallback_merge_dir/basic-resolution.log" ]] || fail "merge token rejection resolved Basic Auth"
 [[ ! -e "$fallback_merge_dir/merge-payload.json" ]] || fail "merge token rejection recorded a successful payload"
 merge_sequence=$(awk '{print $1 ":" $2}' "$fallback_merge_dir/curl.log" | paste -sd, -)
 [[ "$merge_sequence" == "GET:token,GET:token,POST:token" ]] || fail "merge rejection made unexpected provider calls (calls=$merge_sequence)"
 # BLOCK path: a commit email exists but author.login is null. It must name both
 # facts, name the escalation principal, and never reach the merge endpoint.
 null_dir=$(make_case null-login)
 set +e
 null_output=$(run_case "$null_dir" null-login --co-author-trailers --escalate-to tl-mosaic 2>&1)
 null_rc=$?
 set -e
 [[ "$null_rc" -ne 0 ]] || fail "null-login author expected a non-zero BLOCK"
 [[ "$null_output" == *"BLOCK"* ]] || fail "null-login author omitted BLOCK diagnostic"
 [[ "$null_output" == *"author.login=NULL"* ]] || fail "null-login author omitted the null provider fact"
 [[ "$null_output" == *"[email protected]"* ]] || fail "null-login author omitted the commit email fact"
 [[ "$null_output" == *'\n\x1b[31m'* ]] || fail "null-login author diagnostic did not escape control characters"
 [[ "$null_output" != *$'\033'* ]] || fail "null-login author diagnostic emitted a raw terminal escape"
 [[ "$(printf '%s\n' "$null_output" | wc -l)" -eq 1 ]] || fail "null-login author diagnostic permitted newline injection"
 [[ "$null_output" == *"tl-mosaic"* ]] || fail "null-login author omitted the named escalation principal"
 [[ ! -e "$null_dir/merge-payload.json" ]] || fail "null-login BLOCK still reached the merge API"
 # Every provider-derived field in alternate BLOCK diagnostics is log-safe too,
 # including an invalid non-head SHA that contains control characters.
 unsafe_dir=$(make_case unsafe-identity)
 set +e
 unsafe_output=$(run_case "$unsafe_dir" unsafe-identity --co-author-trailers --escalate-to tl-mosaic 2>&1)
 unsafe_rc=$?
 set -e
 [[ "$unsafe_rc" -ne 0 ]] || fail "unsafe identity expected a non-zero BLOCK"
 [[ "$unsafe_output" == *"unusable linked identity"* ]] || fail "unsafe identity omitted its BLOCK reason"
 [[ "$unsafe_output" == *'\n\x1b[31m'* ]] || fail "unsafe identity SHA did not escape control characters"
 [[ "$unsafe_output" != *$'\033'* ]] || fail "unsafe identity diagnostic emitted a raw terminal escape"
 [[ "$(printf '%s\n' "$unsafe_output" | wc -l)" -eq 1 ]] || fail "unsafe identity diagnostic permitted newline injection"
 [[ ! -e "$unsafe_dir/merge-payload.json" ]] || fail "unsafe identity BLOCK still reached the merge API"
 # The provider PR title cannot add an unchecked trailer outside the constructed
 # message field: multi-line and trailer-shaped titles block before mutation.
 title_dir=$(make_case title-injection)
 set +e
 title_output=$(MOSAIC_TEST_TITLE_MODE=injection \
    run_case "$title_dir" verified --co-author-trailers --escalate-to tl-mosaic 2>&1)
 title_rc=$?
 set -e
 [[ "$title_rc" -ne 0 ]] || fail "title trailer injection unexpectedly passed"
 [[ "$title_output" == *"not one printable, non-trailer line"* ]] || fail "title injection refusal lost its diagnostic"
 [[ ! -e "$title_dir/merge-payload.json" ]] || fail "title injection reached the merge API"
 # Provider failures remain diagnosable after their temporary response file is
 # removed, but provider-controlled control characters stay log-safe.
 error_dir=$(make_case provider-error)
 set +e
 error_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=provider-error \
    run_case "$error_dir" single 2>&1)
 error_rc=$?
 set -e
 [[ "$error_rc" -ne 0 ]] || fail "provider error unexpectedly passed"
 [[ "$error_output" == *"HTTP 409"* ]] || fail "provider error omitted the HTTP status"
 [[ "$error_output" == *"branch policy rejected"* ]] || fail "provider error response was discarded"
 [[ "$error_output" == *'\n\x1b[31m'* ]] || fail "provider error response did not escape control characters"
 [[ "$error_output" != *$'\033'* ]] || fail "provider error response emitted a raw terminal escape"
 [[ "$error_output" != *"Basic Auth fallback"* ]] || fail "provider error advertised removed Basic Auth fallback"
 [[ ! -e "$error_dir/basic-resolution.log" ]] || fail "HTTP 409 policy denial incorrectly triggered Basic Auth fallback"
 # Authorization denials likewise fail closed instead of changing principals.
 forbidden_dir=$(make_case forbidden)
 set +e
 forbidden_output=$(MOSAIC_TEST_BASIC_AVAILABLE=true MOSAIC_TEST_FALLBACK_MODE=forbidden \
    run_case "$forbidden_dir" single 2>&1)
 forbidden_rc=$?
 set -e
 [[ "$forbidden_rc" -ne 0 ]] || fail "HTTP 403 authorization denial unexpectedly passed"
 [[ "$forbidden_output" == *"HTTP 403"* ]] || fail "authorization denial omitted the HTTP status"
 [[ "$forbidden_output" != *"Basic Auth fallback"* ]] || fail "authorization denial advertised removed Basic Auth fallback"
 [[ ! -e "$forbidden_dir/basic-resolution.log" ]] || fail "HTTP 403 authorization denial incorrectly triggered Basic Auth fallback"
 # The BLOCK destination cannot be generic or inferred after failure: opting in
 # without a named principal is refused before any provider operation.
 principal_dir=$(make_case missing-principal)
 set +e
 principal_output=$(run_case "$principal_dir" verified --co-author-trailers 2>&1)
 principal_rc=$?
 set -e
 [[ "$principal_rc" -ne 0 ]] || fail "co-author mode without a named principal unexpectedly passed"
 [[ "$principal_output" == *"requires --escalate-to with a named principal"* ]] || fail "missing-principal refusal lost its diagnostic"
 [[ ! -e "$principal_dir/merge-payload.json" ]] || fail "missing-principal refusal reached the merge API"
 # A trailing value-taking option receives a stable CLI diagnostic instead of a
 # set -u unbound-variable crash.
 value_dir=$(make_case missing-principal-value)
 set +e
 value_output=$(run_case "$value_dir" verified --co-author-trailers --escalate-to 2>&1)
 value_rc=$?
 set -e
 [[ "$value_rc" -ne 0 ]] || fail "missing --escalate-to value unexpectedly passed"
 [[ "$value_output" == *"--escalate-to requires one principal name"* ]] || fail "missing --escalate-to value lost its diagnostic"
 [[ "$value_output" != *"unbound variable"* ]] || fail "missing --escalate-to value crashed under set -u"
 [[ ! -e "$value_dir/merge-payload.json" ]] || fail "missing --escalate-to value reached the merge API"
 # Negative control: ordinary single-author merge remains byte-for-byte payload
 # compatible and hardcoded to squash, with no optional message fields.
 single_dir=$(make_case single)
 set +e
 single_output=$(run_case "$single_dir" single 2>&1)
 single_rc=$?
 set -e
 if [[ "$single_rc" -ne 0 ]]; then
    fail "ordinary single-author merge expected rc=0, got rc=$single_rc: $single_output"
 elif [[ ! -s "$single_dir/merge-payload.json" ]]; then
    fail "ordinary single-author merge did not reach the API payload"
 else
    python3 - "$single_dir/merge-payload.json" <<'PY' || fail "ordinary single-author payload changed"
 import json
 import sys
 payload = json.load(open(sys.argv[1], encoding="utf-8"))
 assert payload == {
    "Do": "squash",
    "head_commit_id": "1111111111111111111111111111111111111111",
 }, payload
 PY
 fi
 [[ -e "$single_dir/auth-via-config" ]] || fail "ordinary path did not authenticate curl through stdin config"
 [[ ! -e "$single_dir/token-in-argv" ]] || fail "ordinary path placed the Gitea token in curl argv"
 [[ "$(wc -l < "$single_dir/token-resolution.log")" -eq 1 ]] || fail "ordinary path did not use exactly one credential resolution"
 # Squash is not defaultable: an explicit non-squash method must remain refused.
 method_dir=$(make_case method-refusal)
 set +e
 method_output=$(run_case "$method_dir" single -m merge 2>&1)
 method_rc=$?
 set -e
 [[ "$method_rc" -ne 0 ]] || fail "non-squash method unexpectedly passed"
 [[ "$method_output" == *"enforces squash merge only"* ]] || fail "non-squash refusal lost its policy diagnostic"
 [[ ! -e "$method_dir/merge-payload.json" ]] || fail "non-squash refusal reached the merge API"
 if [[ "$failures" -ne 0 ]]; then
    echo "pr-merge message-field regression failed ($failures assertions)" >&2
    exit 1
 fi
 echo "pr-merge message-field regression passed (verified, BLOCK, and unchanged squash control)"
@@ -8,12 +8,68 @@ WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-metadata-gitea}"
 REPO_DIR="$WORK_DIR/repo"
 FIXTURE_DIR="$WORK_DIR/fixtures"
 STUB_DIR="$WORK_DIR/stubs"
 HOME_DIR="$WORK_DIR/home"
 CREDENTIALS_FILE="$WORK_DIR/credentials.json"
 rm -rf "$WORK_DIR"
-mkdir -p "$REPO_DIR" "$FIXTURE_DIR" "$STUB_DIR"
+mkdir -p "$REPO_DIR" "$FIXTURE_DIR" "$STUB_DIR" "$HOME_DIR"
 git -C "$REPO_DIR" init -q
 git -C "$REPO_DIR" remote add origin https://git.uscllc.com/USC/uconnect.git
 # HERMETICITY (#1007) — TWO mechanisms with DIFFERENT jobs; do not conflate them.
 #
 # OPERATIVE: the empty repo-local `mosaic.gitIdentity` below. get_gitea_token()
 # step 0 resolves a per-agent identity from `git config --get mosaic.gitIdentity`,
 # which on a provisioned agent seat is set GLOBALLY and so leaks into this fresh
 # repo. Step 0 runs BEFORE the credential loader AND before the GITEA_TOKEN env
 # check, so the `GITEA_TOKEN="stub-token"` set in the run helpers below is
 # silently overridden and a REAL per-slot token from $HOME is what reaches curl.
 # Measured on a provisioned seat before this pin: both stub-curl calls carried
 # the real token in argv. An empty repo-local value shadows the global one and
 # reads back empty at rc=0.
 #
 # CONTAINMENT: the sandboxed HOME in the three run helpers below. It only has to
 # bound a failure that the pin should already have prevented.
 #
 # NOTE FOR ANYONE AUDITING THIS SUITE: the sandboxed HOME is containment, NOT an
 # assay. Running a suite under a decoy HOME to test for this defect REMOVES the
 # trigger — ~/.gitconfig is where the global identity lives, so step 0 is skipped
 # by construction and every suite reads clean however vulnerable it is. To measure,
 # REPLICATE a seat (a decoy HOME whose .gitconfig sets mosaic.gitIdentity, with no
 # per-slot token) so step 0 reaches its fail-loud branch. See
 # test-gitea-token-identity.sh for the stronger `env -i HOME=…` form used where a
 # suite's whole subject IS identity resolution.
 #
 # Note the env-var route does NOT work: detect-platform.sh reads
 # "${MOSAIC_GIT_IDENTITY:-}", and `:-` treats set-but-empty identically to unset.
 git -C "$REPO_DIR" config mosaic.gitIdentity ""
 # The pin above removes step 0, but this suite has a SECOND, independent
 # dependency on operator state, and closing only the first would leave the suite
 # red on any hermetic environment. The `GITEA_TOKEN="stub-token"` /
 # `GITEA_URL="https://git.example.test"` pair the run helpers set is INERT: step 2
 # of get_gitea_token accepts GITEA_TOKEN only when GITEA_URL matches the remote
 # host, and this repo's origin is git.uscllc.com, so that pair can never satisfy
 # it. Before this fixture the only credential that could reach the authenticated
 # curl branch was a REAL one — from step 0 on an agent seat, or from step 1
 # reading the operator's own ~/.config/mosaic/credentials.json. That is why the
 # "curl success path" case passed: not because the stub credential worked, but
 # because a production credential was available.
 #
 # A fixture is used rather than relying on the sandboxed HOME making step 1 find
 # nothing: a test that passes because production configuration is ABSENT fails
 # the moment it is present. Step 1 now resolves deterministically to a value that
 # is a fixture on every machine.
 cat > "$CREDENTIALS_FILE" <<'JSON'
 {
  "gitea": {
    "usc": {
      "url": "https://git.uscllc.com",
      "token": "stub-token"
    }
  }
 }
 JSON
 cat > "$FIXTURE_DIR/gitea-standard.json" <<'JSON'
 {
@@ -131,6 +187,8 @@ run_curl_success_case() {
    set +e
    output=$(cd "$REPO_DIR" && \
        PATH="$STUB_DIR:$PATH" \
        HOME="$HOME_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        TMPDIR="$tmpdir" \
        GITEA_TOKEN="stub-token" \
        GITEA_URL="https://git.example.test" \
@@ -170,6 +228,8 @@ run_curl_early_exit_cleanup_case() {
    set +e
    output=$(cd "$REPO_DIR" && \
        PATH="$STUB_DIR:$PATH" \
        HOME="$HOME_DIR" \
        MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        TMPDIR="$tmpdir" \
        GITEA_TOKEN="stub-token" \
        GITEA_URL="https://git.example.test" \
@@ -204,7 +264,8 @@ run_curl_early_exit_cleanup_case() {
 run_case() {
    local fixture="$1" expected_number="$2" expected_head="$3"
    local output
-    output=$(cd "$REPO_DIR" && MOSAIC_GITEA_PR_METADATA_RAW_FILE="$fixture" "$SCRIPT_DIR/pr-metadata.sh" -n "$expected_number")
+    output=$(cd "$REPO_DIR" && HOME="$HOME_DIR" MOSAIC_CREDENTIALS_FILE="$CREDENTIALS_FILE" \
        MOSAIC_GITEA_PR_METADATA_RAW_FILE="$fixture" "$SCRIPT_DIR/pr-metadata.sh" -n "$expected_number")
    PR_METADATA_OUTPUT="$output" python3 - "$expected_number" "$expected_head" <<'PY'
 import json
 import os
@@ -225,7 +225,10 @@ write_response() {
 emit() {
    # Split a two-line "status\n<json body>" python result into the response.
    local result="$1"
-    write_response "$(printf '%s' "$result" | head -n1)" "$(printf '%s' "$result" | tail -n +2)"
+    response_status="${result%%$'\n'*}"
    response_body=""
    [[ "$result" == *$'\n'* ]] && response_body="${result#*$'\n'}"
    write_response "$response_status" "$response_body"
 }
 mode="${PR_REVIEW_TEST_MODE:-}"
@@ -436,6 +439,19 @@ elif mode == "comment-url-wrong-repo":
 elif mode == "comment-url-suffix-injection":
    # Prefix-injected: a bare endswith("/<slug>/pulls/123") test would ACCEPT it.
    pr_url = f"{_origin}/deceptive{_slug}/pulls/123"
 elif mode == "comment-url-wrong-port":
    # #991 bound: an EXPLICIT non-default port is a different service on the same
    # host. Relaxing http-vs-https must NOT relax this.
    pr_url = f"{_p.scheme}://{_p.hostname}:8443{_slug}/pulls/123"
 elif mode == "comment-url-non-web-scheme":
    # #991 bound: ONLY http/https collapse; any other scheme stays distinguishing.
    pr_url = f"ftp://{_p.netloc}{_slug}/pulls/123"
 elif mode == "comment-url-scheme-downgrade":
    # #991, and the only URL mode here that must be ACCEPTED. A Gitea whose
    # ROOT_URL is http:// returns http:// object URLs for a repo reached over
    # https://. Same host, same path, correct record — a truthful provider
    # answer about a comment that landed, not a forgery.
    pr_url = f"http://{_p.netloc}{_slug}/pulls/123"
 elif mode == "comment-mixed-case-slug":
    # #875: EXPECTED_REPO_SLUG is taken verbatim from GITEA_API_BASE and can be
    # mixed-case (e.g. "USC/uconnect"), but Gitea canonicalizes the returned
@@ -890,11 +906,16 @@ fi
 assert_no_temp_leak "review-body-reuse"
 # Cases 12-15 (#865 Blocker 3): a PR comment whose id/author/body are all correct
-# but whose provider-returned pull_request_url is forged must FAIL CLOSED.
+# but whose provider-returned pull_request_url does not belong to this PR must
-# Verification pins the URL's ORIGIN (scheme+host+effective-port) and FULL path
+# FAIL CLOSED. Verification pins the URL's ORIGIN (scheme-class + host + explicit
-# (deployment prefix + exact owner/repo + kind + number); a bare endswith/suffix
+# non-default port) and FULL path (deployment prefix + exact owner/repo + kind +
-# test would wrongly accept the look-alike-host and prefix-injection variants.
+# number); a bare endswith/suffix test would wrongly accept the look-alike-host
-for bad_mode in comment-url-wrong-host comment-url-wrong-owner comment-url-wrong-repo comment-url-suffix-injection; do
+# and prefix-injection variants. comment-url-wrong-port and
 # comment-url-non-web-scheme (#991) bound the scheme relaxation from the other
 # side: collapsing http/https must not also collapse a different port or a
 # different scheme family.
 for bad_mode in comment-url-wrong-host comment-url-wrong-owner comment-url-wrong-repo \
                comment-url-suffix-injection comment-url-wrong-port comment-url-non-web-scheme; do
    if run_review "$bad_mode" comment durable-body; then
        echo "FAIL: forged comment URL ($bad_mode) was accepted" >&2
        cat "$OUTPUT_FILE" >&2
@@ -920,6 +941,19 @@ run_review comment-mixed-case-slug comment durable-body https://git.mosaicstack.
 grep -q 'Added and verified comment on Gitea PR #123' "$OUTPUT_FILE"
 assert_no_temp_leak "comment-mixed-case-slug"
 # Case 15c (#991): the deployment's Gitea ROOT_URL is http:// while every client
 # reaches it over https://, so the provider returns an http:// pull_request_url
 # for a comment that is otherwise entirely correct. Same class as 15b — a
 # legitimate provider response, not a spoof — and a scheme-strict compare
 # rejects it on EVERY comment, deterministically. That is not a cosmetic false
 # negative here: on a host where no seat can create a review OBJECT, this
 # comment-form record is the only gate-16 evidence obtainable, and the wrapper
 # refuses all of it while the comment sits durably on the PR. Host, path, owner,
 # repo, kind and number stay strict; only http-vs-https is relaxed.
 run_review comment-url-scheme-downgrade comment durable-body
 grep -q 'Added and verified comment on Gitea PR #123' "$OUTPUT_FILE"
 assert_no_temp_leak "comment-url-scheme-downgrade"
 # Case 16 (#865 ITEM 1, current-head TOCTOU): the PR head advances between the
 # pre-submit head read (which pins the review) and the post-verify re-read. The
 # review is genuinely created and verified as pinned to the OLD head, but the
@@ -222,8 +222,8 @@ grep -q 'Unknown action: bogus-action' "$OUTPUT_FILE"
 # --- Case 2: -h/--help documents both overrides.
 HELP_TEXT="$("$SCRIPT_DIR/pr-review.sh" -h)"
-echo "$HELP_TEXT" | grep -q -- '-r, --repo'
+grep -q -- '-r, --repo' <<<"$HELP_TEXT"
-echo "$HELP_TEXT" | grep -q -- '-H, --host'
+grep -q -- '-H, --host' <<<"$HELP_TEXT"
 # --- Case 3 (comment): a TRUE no-git-origin dir + -r/-H must not silently die
 # and must not fail with "not a git repository or no origin remote" either.
@@ -0,0 +1,275 @@
 #!/usr/bin/env bash
 # test-wrapper-guard.sh — hermetic behavioural regression for wrapper-guard.sh.
 #
 # Resolves no credentials, touches no network, and creates no repository: the
 # guard reads a hook payload on stdin and answers with an exit code, so the whole
 # contract is testable from fixtures.
 #
 # The fixtures are written to a temp file rather than passed inline, and this is
 # not stylistic. The guard inspects the literal text of the Bash command it is
 # handed. A test that embeds `git clone ... $HOME` inside its own command line
 # trips the guard on the harness instead of on the fixture — which is exactly
 # what happened the first time this was checked by hand. Substring matching over
 # whole command text is the guard's deliberate fail-closed posture; a test that
 # does not account for it silently measures the wrong thing.
 #
 # Exit: 0 = every fixture behaved as specified · 1 = at least one did not
 set -uo pipefail
 HERE="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 GUARD="${1:-$HERE/wrapper-guard.sh}"
 [ -x "$GUARD" ] || { printf 'test-wrapper-guard: not executable: %s\n' "$GUARD" >&2; exit 2; }
 TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
 FIXTURES="$TMP/fixtures.tsv"
 # Each line: <expected-exit> TAB <hook payload> TAB <what it proves>
 #            [ TAB <substring the block message must contain> ]
 # 0 = allowed, 2 = blocked. The optional fourth field is how the remediation
 # itself gets checked; without it a block is only asserted to have happened,
 # not to have been useful.
 {
  printf '2\t{"tool_input":{"command":"git clone https://example.invalid/x ~/wt"}}\tcheckout into $HOME is refused\n'
  printf '2\t{"tool_input":{"command":"git worktree add ~/wt topic"}}\tworktree into $HOME is refused\n'
  printf '0\t{"tool_input":{"command":"git clone https://example.invalid/x /src/wt"}}\tcheckout onto a work filesystem is fine\n'
  printf '0\t{"tool_input":{"command":"curl -s -X GET https://git.example.invalid/api/v1/repos/a/b/pulls/1"}}\treads are never blocked\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\treview write has a wrapper\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge"}}\tmerge write has a wrapper\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://api.github.com/repos/a/b/issues"}}\tGitHub host is covered too\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/releases"}}\tan endpoint with no wrapper passes\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d {\\"event\\":\\"APPROVE\\"} https://example.invalid/x"}}\tthe APPROVE token is caught anywhere\n'
  printf '0\t{"tool_input":{"command":"ls -la /src"}}\tordinary commands are untouched\n'
  printf '0\t{"tool_input":{"command":"MOSAIC_WRAPPER_OVERRIDE=1 curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls"}}\tbreak-glass works\n'
  printf '0\t{"tool_input":{}}\tan empty payload does not block the session\n'
  # --- bypasses an independent reviewer demonstrated against the first version.
  # Each of these returned 0 (allowed) and each is a real write. They are pinned
  # as fixtures rather than fixed-and-forgotten because the class is recurring:
  # the guard reads text, so every spelling it does not know is a hole.
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\t-d@body with no space is still a body\n'
  printf '2\t{"tool_input":{"command":"curl --request=POST -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\t--request=POST equals-form is still a method\n'
  printf '2\t{"tool_input":{"command":"p=/api/v1/repo; q=s/a/b/pulls/1/reviews; curl -d@b https://git.example.invalid${p}${q}"}}\ta path split across variables is still that path\n'
  printf '2\t{"tool_input":{"command":"curl --data-binary @b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\t--data-binary is a body\n'
  printf '2\t{"tool_input":{"command":"curl -F f=@b https://git.example.invalid/api/v1/repos/a/b/issues"}}\t-F multipart is a body\n'
  # Reads must survive every one of those broadenings, or the guard gets disabled.
  printf '0\t{"tool_input":{"command":"curl -s https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\tno body and no verb is a read\n'
  printf '0\t{"tool_input":{"command":"grep -rn /pulls/ src/ | head -20"}}\ta path fragment in a grep is not an API call\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://registry.example.invalid/v2/x/manifests/latest"}}\tan unwrapped API is not this guard'"'"'s business\n'
  # --- round two of the same review. Splitting the ENDPOINT TOKEN defeats any
  # amount of fragment matching, because the endpoint does not exist until the
  # shell expands it. The guard now refuses to clear a write whose URL it cannot
  # read, rather than pretending it read one.
  printf '2\t{"tool_input":{"command":"a=/api/v1/repos/a/b/iss; b=ues/1/comments; curl -d@body https://git.example.invalid${a}${b}"}}\tan endpoint token split across variables is unreadable, not absent\n'
  printf '2\t{"tool_input":{"command":"a=/api/v1/repos/a/b/pu; b=lls/1/reviews; curl -d@body https://git.example.invalid${a}${b}"}}\tsame split, review endpoint\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @payload https://hooks.example.invalid/services/${WEBHOOK_ID}"}}\tan opaque URL that is not forge-shaped stays allowed\n'
  # --- round six changed the contract in this direction, and these fixtures are
  # where it shows. They used to assert that discussing a call is not making one.
  # Five rounds proved there is no textual way to tell a quoted example from a
  # quoted command, so the guard stopped trying: it judges the payload, and a
  # payload inside quotes is still a payload. Quoting one of these on a Bash
  # command line is now refused, and the way to write the example is a
  # file-writing tool. This is the deliberate cost of the mechanism change.
  printf '2\t{"tool_input":{"command":"grep -R \\"curl -d https://git.example.invalid/api/v1/repos/a/b/issues\\" docs/"}}\tquoting a wrapped write is refused even in a grep\n'
  printf '2\t{"tool_input":{"command":"echo \\"curl -d https://git.example.invalid/api/v1/repos/a/b/pulls\\" > note.txt"}}\t...and when written into a file\n'
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'print(\\"curl -d https://git.example.invalid/api/v1/repos/a/b/issues\\")'"'"'"}}\t...and when printed from another language\n'
  # The boundary that keeps this from being "block everything": what is refused
  # is a WRITE to a WRAPPED endpoint. Mentioning either alone still passes, and
  # these are asserted as hard as the blocks above.
  printf '0\t{"tool_input":{"command":"grep -R \\"curl -s https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" docs/"}}\tquoting a READ example is untouched\n'
  printf '0\t{"tool_input":{"command":"echo \\"the wrapped endpoint is https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" >> notes.md"}}\tnaming the endpoint without a body flag is untouched\n'
  printf '0\t{"tool_input":{"command":"grep -R \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/releases\\" docs/"}}\tquoting a write to an UNWRAPPED endpoint is untouched\n'
  printf '0\t{"tool_input":{"command":"issue-comment.sh --repo a/b --issue 1 --body @msg.md"}}\tthe wrapper itself carries a body flag and must never trip its own guard\n'
  # Command position must still catch the real thing behind operators and env.
  printf '2\t{"tool_input":{"command":"cd /tmp && GITEA_TOKEN=$T curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge"}}\ta real call behind && and an assignment is still a call\n'
  # --- the case the AUTHOR hit twice while chasing the above: sending a message
  # that QUOTED one of these fixtures. Under the old contract that was a defect
  # to be parsed away; under this one it is the documented cost, and the message
  # gets composed with a file-writing tool instead.
  printf '2\t{"tool_input":{"command":"send.sh -m \\"repro was: cd /tmp && curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge\\""}}\tquoting the repro in a message is refused too\n'
  printf '2\t{"tool_input":{"command":"cat >> notes.md <<EOF\\nwe ran: curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues\\nEOF"}}\ta heredoc body carrying the payload is refused with it\n'
  # ...but quotes stop being data the moment something executes them.
  printf '2\t{"tool_input":{"command":"bash -c \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pulls/1/merge\\""}}\tbash -c makes the quoted text code again\n'
  # --- round three. Each of these four is a real write that a bare-name match
  # for the client could not see, because an ordinary word sat in front of it.
  # They are kept as fixtures after the mechanism change even though the guard no
  # longer looks for a client at all: they are the evidence for WHY it stopped,
  # and a future re-narrowing that reintroduced position would fail here first.
  printf '2\t{"tool_input":{"command":"env GITEA_TOKEN=$T curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tenv VAR=... in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"command curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tcommand in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"timeout 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\ttimeout N in front of the client is still the client\n'
  printf '2\t{"tool_input":{"command":"/usr/bin/curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan absolute path to the client is still the client\n'
  printf '2\t{"tool_input":{"command":"echo timeout 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments >> notes.md"}}\tnaming the call after echo carries the payload, so it is refused\n'
  # A shell standing between quoted data and execution makes that data code,
  # and the pipe is the form agents actually use. Filing it as data allowed the
  # call to vanish from the skeleton while still running.
  printf '2\t{"tool_input":{"command":"printf '"'"'%%s\\\\n'"'"' '"'"'curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments'"'"' | sh"}}\tquoted code piped to a shell is code\n'
  printf '2\t{"tool_input":{"command":"cat <<EOF | sh\\ncurl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\nEOF"}}\ta heredoc piped to a shell is code\n'
  printf '2\t{"tool_input":{"command":"sh -s <<EOF\\ncurl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\nEOF"}}\tsh -s reads its script from the heredoc\n'
  # ...and the questions that used to follow — is the pipe target a shell, does a
  # shell on one line execute a string on another — no longer have to be answered
  # at all. Both of these carry the payload, both are refused, and neither
  # outcome depends on parsing what the pipe or the other line does.
  printf '2\t{"tool_input":{"command":"grep -R \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" docs/ | wc -l"}}\tpiping the payload to wc is refused without asking what wc is\n'
  printf '2\t{"tool_input":{"command":"docker run --rm alpine sh -c '"'"'echo hi'"'"'\\necho \\"example: curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\" >> notes.md"}}\tan unrelated shell on another line no longer changes the answer either way\n'
  # --- round four. The guard was still reading the command as typed rather than
  # as the shell will run it: a backslash before a newline is removed before
  # anything else happens, so the endpoint token can be split across the join.
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/iss\\\\\\nues/1/comments"}}\ta line continuation inside the endpoint token is still that endpoint\n'
  printf '2\t{"tool_input":{"command":"curl -d@b https://git.example.invalid/api/v1/repos/a/b/pu\\\\\\nlls/1/reviews"}}\tsame join, review endpoint\n'
  printf '2\t{"tool_input":{"command":"cat >> notes.md <<EOF\\nwe ran: curl -d@b https://git.example.invalid/api/v1/repos/a/b/iss\\\\\\nues/1/comments\\nEOF"}}\tthe join still runs first, and the joined payload is refused in a document too\n'
  # Transparent prefixes take option VALUES, and the value was a word the list
  # did not know — so the client went missing again behind an ordinary `sudo -u`.
  printf '2\t{"tool_input":{"command":"sudo -u root curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan option value after a prefix does not hide the client\n'
  printf '2\t{"tool_input":{"command":"timeout --signal TERM 10 curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tan option pair plus a duration does not hide the client\n'
  printf '2\t{"tool_input":{"command":"xargs echo curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tthe payload behind xargs echo is refused rather than adjudicated\n'
  printf '0\t{"tool_input":{"command":"sudo apt-get install curl"}}\tinstalling the client is not calling it\n'
  # Execution through another command needed its own case under the old design.
  printf '2\t{"tool_input":{"command":"find . -maxdepth 0 -exec curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments ;"}}\tfind -exec runs the client\n'
  # --- round five, and the finding that ended the parser. Command substitution
  # inside a double-quoted span EXECUTES, while the skeleton was discarding that
  # span as inert prose. The unquoted and process-substitution forms already
  # blocked, which is what made it a classification defect rather than a spelling
  # one: the same call was refused or allowed depending on a quote character.
  printf '2\t{"tool_input":{"command":"echo \\"$(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)\\""}}\tcommand substitution inside double quotes executes\n'
  printf '2\t{"tool_input":{"command":"echo \\"`curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments`\\""}}\tso does the backtick form\n'
  printf '2\t{"tool_input":{"command":"msg=\\"$(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)\\""}}\tand an assignment RHS is not data either\n'
  printf '2\t{"tool_input":{"command":"echo $(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)"}}\tthe unquoted form, which blocked before and must keep blocking\n'
  printf '2\t{"tool_input":{"command":"cat <(curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments)"}}\tprocess substitution, same\n'
  printf '2\t{"tool_input":{"command":"bash --command \\"curl -d@b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\""}}\tthe long-option spelling of bash -c needs no entry in any list now\n'
  # A client the guard was never taught is the point of dropping client
  # detection: neither of these names curl at all.
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'import requests; requests.post(\\"https://git.example.invalid/api/v1/repos/a/b/issues/1/comments\\", json={})'"'"'"}}\ta library call is a write with no flag and no curl\n'
  printf '2\t{"tool_input":{"command":"wget --post-data=x https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\twget spells its body differently and is still a write\n'
  # Round six scoped the guard on `https?://`, and review found the absence shape
  # had simply moved to that new boundary: a raw provider CLI carries no scheme,
  # so the guard never reached the write question. These are the reported repros.
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues -f title=x -f body=y"}}\tgh api is a raw write with no URL scheme at all\n'
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/pulls/1/reviews -f event=APPROVE"}}\tand it reaches the endpoint the review wrapper owns\n'
  printf '2\t{"tool_input":{"command":"tea api -X POST repos/a/b/issues/1/comments -f body=x"}}\ttea api, same shape, different CLI\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x git.example.invalid/api/v1/repos/a/b/issues"}}\ta scheme-less host path is still an API write\n'
  printf '2\t{"tool_input":{"command":"gh api repos/a/b/issues -f title=x"}}\tgh POSTs implicitly when handed a field, exactly as curl does with -d\n'
  # ...and the boundary that stops a broader scope gate becoming block-everything.
  printf '0\t{"tool_input":{"command":"gh api repos/a/b/pulls/1"}}\treading through a provider CLI stays untouched\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/releases -f tag_name=v1"}}\tno wrapper owns releases, whoever calls it\n'
  printf '0\t{"tool_input":{"command":"tea pulls create --title x --repo a/b"}}\tprovider PORCELAIN is out of scope by decision, not by accident\n'
  printf '0\t{"tool_input":{"command":"rm -f /var/tmp/api/v1-issues-notes.txt"}}\t-f is only a body when it carries key=value\n'
  printf '0\t{"tool_input":{"command":"grep -f patterns.txt /src/api/v1/repos/a/b/issues.log"}}\tsame, on the flag agents actually collide with\n'
  # Wrong remediation is its own defect: /issues/1/labels used to block with
  # "use issue-create.sh", which is not the wrapper for that call. Round seven
  # answered that by letting EVERY path under a numbered issue or PR through,
  # and review showed the reasoning ("no wrapper owns these") was false in this
  # tree. These are the reported repros, all rc 0 before round eight, and each
  # asserts the wrapper the advice must name — not merely that a block happened.
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f title=x"}}\tan issue edit is issue-edit.sh, not a wrapper gap\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1"}}\tsame call through curl, same wrapper\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1/labels -f labels[]=bug"}}\tlabels are wrapped, and the advice says by which\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/assignees -f assignees[]=u"}}\tassignees are issue-assign.sh\tissue-assign.sh\n'
  printf '2\t{"tool_input":{"command":"gh api repos/a/b/issues/1/assignees -f assignees[]=u"}}\tthe array field spelling is a body with no -X at all\tissue-assign.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/labels"}}\ta PR is an issue where labels live, so the issue wrapper owns them\tissue-edit.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1"}}\tPR state is pr-close.sh, and the gap in that arm is stated\tpr-close.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/milestones/4"}}\ta milestone state change is milestone-close.sh, not the create wrapper\tmilestone-close.sh\n'
  # SPAN. A wrapper that owns a slice of an endpoint must not be advertised as
  # owning the endpoint. milestone-close.sh takes only -t <title> and sends
  # state=closed, so a title/description/due-date edit is a gap and the message
  # has to say so — round eight named the wrapper and stopped there.
  printf '2\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/milestones/1"}}\ta milestone edit blocks, but the advice states the close-only span\towns the CLOSE only\n'
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f assignee=u"}}\tissue-edit.sh cannot set an assignee, so the message names the one that can\tissue-assign.sh owns the assignee\n'
  # The residue: still genuinely owned by nothing, and still flowing through.
  # Requesting a reviewer is not submitting one; pr-review.sh files verdicts and
  # nothing in the tree adds a requested reviewer.
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/pulls/1/requested_reviewers -f reviewers[]=u"}}\tno wrapper requests a reviewer, so it is not refused with pr-review.sh\n'
  # SPAN, applied to the guard's OWN fail-closed rule rather than to a wrapper.
  # The scope gate admits three shapes; the unreadable-endpoint rule asked only
  # for `https?://`, so a split endpoint in the other two was in scope to block,
  # produced no readable endpoint, and fell through to allow. Same defect class
  # as the milestone arm, one layer up. Each shape gets its own fixture, because
  # a single one would have passed on the arm that already worked.
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; gh api -X POST ${p}${q} -f title=x"}}\ta split endpoint in a provider-CLI api call is unreadable, not absent\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/issues/1/comm; q=ents; gh api -X POST ${p}${q} -f body=x"}}\tsame, comments\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/pulls/1/rev; q=iews; gh api -X POST ${p}${q} -f event=APPROVED"}}\tsame, and a verdict is the costliest one to lose\n'
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; tea api -X POST ${p}${q} -f title=x"}}\tevery CLI the scope gate admits, not just gh\n'
  printf '2\t{"tool_input":{"command":"p=/api/v1/repos/a/b/iss; q=ues; curl -X POST -d x git.example.invalid${p}${q}"}}\ta schemeless forge host with a split path is unreadable too\n'
  printf '2\t{"tool_input":{"command":"h=git.example.invalid; q=ues; curl -X POST -d x ${h}/api/v1/repos/a/b/iss${q}"}}\tthe expansion may come first; the token is what matters\n'
  # And the reason this is not "any variable blocks a write": a payload in a
  # variable is the SAFE way to pass one and leaves the endpoint fully legible.
  printf '0\t{"tool_input":{"command":"gh api repos/a/b/git/refs -f sha=$SHA"}}\tan expansion in a body value leaves the endpoint readable\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d \\"$BODY\\" https://git.example.invalid/api/v1/repos/a/b/git/refs"}}\tsame for a quoted body on an unwrapped endpoint\n'
  printf '0\t{"tool_input":{"command":"gh api repos/${OWNER}/${REPO}/git/refs"}}\ta read with a split endpoint is still a read\n'
  printf '0\t{"tool_input":{"command":"curl -X PATCH -d @b https://git.example.invalid/api/v1/repos/a/b/issues/comments/5"}}\tediting a comment has no wrapper; only creating one does\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1/stopwatch/start"}}\tno wrapper owns a stopwatch, and none is invented for it\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/times -f time=60"}}\tnor time tracking\n'
  printf '0\t{"tool_input":{"command":"gh api -X POST repos/a/b/issues/1/reactions -f content=+1"}}\tnor reactions\n'
  # ...and the residue must be decided by the SEGMENT, never by a stray slash.
  printf '2\t{"tool_input":{"command":"gh api -X PATCH repos/a/b/issues/1 -f body=see-/docs/x"}}\ta slash inside the body is not a subresource\tissue-edit.sh\n'
  # The arms above the numbered ones must keep blocking, with their own wrappers.
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues/1/comments"}}\tthe wrapped subresource must not fall through\tissue-comment.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/issues"}}\tnor may issue creation\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls"}}\tPR creation is wrapped and must not fall through with them\tpr-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d @b https://git.example.invalid/api/v1/repos/a/b/pulls/1/reviews"}}\tand a review still names the review wrapper\tpr-review.sh\n'
  # SPAN a third time, now in the scope gate itself: it asked for `/api/v[0-9]`,
  # which is Gitea's spelling. GitHub's API carries no version segment at all
  # (`api.github.com/repos/...`), so the schemeless Gitea write was in scope and
  # the schemeless GitHub one was not — a gate calibrated to one dialect rather
  # than to what identifies a provider API. `/repos/` is the marker both share.
  # These endpoints are READABLE, so each asserts the wrapper it must name; a
  # rc-only fixture here would pass on the unreadable arm and prove nothing.
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/issues"}}\ta schemeless GitHub host is a provider API even with no version segment\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/issues/1/comments"}}\tsame, and the subresource still names its own wrapper\tissue-comment.sh\n'
  printf '2\t{"tool_input":{"command":"host=api.github.com; curl -X POST -d x ${host}/repos/a/b/issues"}}\tthe host may be a variable; the path is what the guard reads\tissue-create.sh\n'
  printf '2\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/pulls/1/reviews"}}\ta verdict is the costliest call to lose to a spelling\tpr-review.sh\n'
  printf '2\t{"tool_input":{"command":"p=/repos/a/b/iss; q=ues; curl -X POST -d x api.github.com${p}${q}"}}\tand the split form of it is unreadable, not absent\n'
  # The end-of-options marker, which is the one option not spelled like one.
  printf '2\t{"tool_input":{"command":"p=repos/a/b/iss; q=ues; gh api -X POST -- ${p}${q} -f title=x"}}\ta bare -- must not walk the endpoint past the scanner\n'
  # Widening a scope gate may not create a block. Reads and unwrapped endpoints
  # in the newly admitted shape have to stay allowed, or this is a regression
  # wearing a fix'"'"'s clothes.
  printf '0\t{"tool_input":{"command":"curl api.github.com/repos/a/b/issues"}}\tadmitting a shape to the gate does not make a read a write\n'
  printf '0\t{"tool_input":{"command":"curl -X POST -d x api.github.com/repos/a/b/git/refs"}}\tno wrapper owns git refs, on GitHub'"'"'s spelling either\n'
  printf '0\t{"tool_input":{"command":"gh api -- repos/a/b/issues"}}\tthe marker in a read is still a read\n'
  # The APPROVE trap, in the spelling a provider CLI uses, and the value that
  # must never trip it.
  printf '0\t{"tool_input":{"command":"curl -X POST -d {\\"event\\":\\"APPROVED\\"} https://git.example.invalid/api/v1/repos/a/b/releases"}}\tAPPROVED is the correct value and is never the trap\n'
  # Documented over-block, pinned so it is a known boundary and not a surprise.
  printf '2\t{"tool_input":{"command":"python3 -c '"'"'print(\\"https://git.example.invalid/api/v1/repos/a/b/issues/1/comments .post(\\")'"'"'"}}\tprose carrying .post( near a wrapped URL is refused, by the same payload rule\n'
 } > "$FIXTURES"
 fail=0 n=0
 while IFS=$'\t' read -r want payload why remedy; do
  [ -n "${want:-}" ] || continue
  n=$((n + 1))
  out="$(printf '%s' "$payload" | "$GUARD" 2>&1)"
  got=$?
  if [ "$got" != "$want" ]; then
    printf 'FAIL  %s (want exit %s, got %s)\n' "$why" "$want" "$got"
    fail=1
    continue
  fi
  # A block that names the wrong wrapper is a defect in its own right, and until
  # now it was invisible here: the harness read the exit code and nothing else,
  # so /issues/1/labels blocking with "use issue-create.sh" passed every run for
  # six rounds. Where a fixture states the remediation it expects, assert it.
  if [ -n "${remedy:-}" ] && ! printf '%s' "$out" | grep -Fq -- "$remedy"; then
    printf 'FAIL  %s (blocked, but the advice does not name %s)\n' "$why" "$remedy"
    fail=1
    continue
  fi
  printf 'ok    %s\n' "$why"
 done < "$FIXTURES"
 printf '\n'
 if [ "$fail" -eq 0 ]; then
  printf 'wrapper-guard: %d/%d fixtures behaved as specified.\n' "$n" "$n"
 else
  cat <<'EOF'
 wrapper-guard drifted from its contract.
 A guard that blocks too much gets routed around, and a guard that blocks too
 little is decoration. Both directions are failures here, which is why the
 allowed cases are asserted as hard as the blocked ones.
 EOF
 fi
 exit "$fail"
@@ -0,0 +1,484 @@
 #!/usr/bin/env bash
 # wrapper-guard.sh — PreToolUse hook on Bash.
 #
 # Blocks three specific, mechanically-detectable mistakes that prose has
 # repeatedly failed to prevent:
 #
 #   1. A checkout (git clone / git worktree add) targeting $HOME.
 #      Root cause of a fleet host's /home filling to 100% — 255 GB, 842 dirs.
 #
 #   2. A raw provider API WRITE against an endpoint that already has a Mosaic
 #      wrapper. Constitution gate 7 requires the wrapper; the wrapper knows
 #      provider dialect, identity, and queue-guard ordering that raw curl does
 #      not. Reads are untouched — they are how you gather evidence.
 #
 #   3. The literal review event "APPROVE". Gitea's vocabulary is APPROVED;
 #      it accepts APPROVE with HTTP 200, silently files the review PENDING,
 #      and then 422s on submit. This one is unconditionally wrong on Gitea and
 #      is what a verdict silently failing to land looks like.
 #
 # Design constraint: this hook must not become something agents route around.
 # It blocks WRITES to endpoints with a known wrapper, and nothing else. Raw
 # curl for reads, for registry/manifest calls, and for endpoints with no
 # wrapper (there are many) all pass untouched.
 #
 # One consequence is worth knowing before it surprises you: it judges the
 # payload, not the caller, so a command that merely QUOTES such a write is
 # refused as well. See the long note at section 2 for why that trade was made.
 #
 # Break-glass, for a genuine gap where no wrapper can express the call:
 #   MOSAIC_WRAPPER_OVERRIDE=1 <command>
 # Using it means "no wrapper covers this" — if that is wrong, the fix is to
 # extend the wrapper, not to keep typing the override.
 #
 # Exit codes (Claude Code PreToolUse): 0 = allow, 2 = block with message.
 set -euo pipefail
 INPUT="$(cat)"
 CMD="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)"
 [ -z "$CMD" ] && exit 0
 # Read the command the SHELL will run, not the text as typed. A backslash before
 # a newline is removed before anything else happens, so
 #   curl -d@b https://host/api/v1/repos/a/b/iss\
 #   ues/1/comments
 # executes the comments endpoint while the literal token `issues` never appears
 # in the text. Every check below — position, URL, body, endpoint — reads the
 # joined form, because that is the command.
 CMD="$(printf '%s' "$CMD" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\\\n//g')"
 # Honour the override only when it is set in the command itself or the env.
 case "$CMD" in *MOSAIC_WRAPPER_OVERRIDE=1*) exit 0 ;; esac
 [ "${MOSAIC_WRAPPER_OVERRIDE:-0}" = "1" ] && exit 0
 # The wrappers this guard points at are its own siblings. Resolving relative to
 # this file — rather than to a hardcoded $HOME/.config/mosaic — means the guard
 # names the wrappers from the same install it was launched from, and that it
 # still works from a repo checkout with no installed mosaic home (which is how it
 # is exercised in CI). $HOME remains the fallback for a guard invoked by an
 # absolute path from somewhere unusual.
 W="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 [ -x "$W/pr-review.sh" ] || W="$HOME/.config/mosaic/tools/git"
 # ---- 1. checkout into $HOME ------------------------------------------------
 if printf '%s' "$CMD" | grep -Eq 'git[^|;&]*(clone|worktree[[:space:]]+add)'; then
  # Any argument that resolves under $HOME and is not under a work filesystem.
  if printf '%s' "$CMD" | grep -Eq "(^|[[:space:]=\"'])(~|\\\$HOME|$HOME)/"; then
    cat <<EOF
 BLOCKED: this checks a repository out under \$HOME.
 \$HOME holds configuration, credentials, state and caches. It does not hold
 checkouts, worktrees, scratch files, or build output. One fleet host's /home hit
 100% (394 G) with 255 GB of agent workspaces accumulated exactly this way.
 Use the helper, which derives the path so you do not have to choose one:
  ~/.config/mosaic/tools/git/mosaic-worktree.sh new <branch>     # /src/<repo>-worktrees/<slug>
  ~/.config/mosaic/tools/git/mosaic-worktree.sh path <branch>    # show where it would go
  ~/.config/mosaic/tools/git/mosaic-worktree.sh rm <branch>      # removal is part of the task
 Worktrees, not clones: they share the object store, and \`git worktree list\`
 makes every one of them enumerable — which is the only reason cleanup can
 ever be safe.
 EOF
    exit 2
  fi
 fi
 # ---- 2/3. provider API writes ---------------------------------------------
 # A raw provider write this guard cares about is two things: a WRITE, and a URL
 # naming an endpoint a Mosaic wrapper already owns. Reads are untouched — they
 # are how you gather evidence — and the many endpoints with no wrapper flow
 # through.
 #
 # It deliberately does NOT ask which program makes the call, or whether that
 # program sits at shell command position. It used to, and that is the whole
 # history of this file. Answering "is this code or is this data" from the text
 # of a shell command required a skeleton with quoted spans and heredoc bodies
 # removed, an invoker list for the forms where a shell executes quoted text, a
 # prefix list for `env`/`sudo`/`timeout`, option-value skipping, and
 # backslash-newline joining. Five rounds of adversarial review put nineteen
 # writes straight through it, and every one had the same shape: the client was
 # ABSENT from the skeleton, so the guard allowed. Variables, line continuations,
 # command prefixes, option values, pipes into a shell, and finally command
 # substitution inside the very quotes the skeleton was discarding:
 #   echo "$(curl -d@b .../issues/1/comments)"
 #   msg="$(curl -d@b .../issues/1/comments)"
 # Classifying code against data in shell text with sed and awk is not a hard
 # problem, it is the wrong problem. It was not even portable: under CI's busybox
 # awk the quote-stripping silently failed, the skeleton kept every quoted span,
 # and the guard started refusing ordinary prose instead — which is the other way
 # a control like this dies.
 #
 # So the client detection is gone, and with it that entire failure class: what
 # is left cannot fail open by hiding the caller, because it never looks for one.
 # It looks for the payload. Something that names a wrapped endpoint and carries
 # a body is refused however it is spelled — curl, wget, `python -c`, or a form
 # nobody has thought of yet.
 #
 # The cost is real and belongs in the open, because over-blocking is how a hook
 # gets switched off: QUOTING one of these calls on a Bash command line now
 # blocks too. `grep -R "curl -d .../issues" docs/` is refused, and so is echoing
 # an example into a file. There is no textual way to tell a quoted example from
 # a quoted command — that is exactly the finding above — so the rule is the one
 # an agent can hold in mind without a parser:
 #
 #   do not put a raw write to a wrapped forge endpoint on a Bash command line,
 #   not even inside quotes.
 #
 # Write the example with a file-writing tool, or leave the body flag out of it.
 # That is a deliberate narrowing of scope, not an oversight. This hook stops
 # mistakes; it is not a sandbox, and pretending otherwise is how you get a
 # control nobody can trust the boundaries of.
 #
 # Scoped to commands that are provider-API-shaped, so nothing else is even
 # considered. The first version of this scope gate asked only for `https?://`,
 # and review found the absence shape had simply moved to the new boundary:
 #   gh api -X POST repos/a/b/pulls/1/reviews -f event=APPROVE
 #   tea api -X POST repos/a/b/issues/1/comments -f body=x
 #   curl -X POST -d x git.example.invalid/api/v1/repos/a/b/issues
 # all carry a real write to a wrapped endpoint and none carries a scheme, so the
 # guard never asked the write question at all. Gate 7 covers raw provider CLIs,
 # so these are in scope and the gate now names the shapes they come in.
 #
 # Then review found the same absence at the same boundary a second time, in the
 # one provider whose paths carry no version marker at all:
 #   curl -X POST -d x api.github.com/repos/a/b/issues
 # GitHub's API is `api.github.com/repos/...`; Gitea's is `/api/v1/repos/...`.
 # Asking for `/api/v[0-9]` therefore admitted the schemeless Gitea write and
 # excluded the schemeless GitHub one — a gate calibrated to one dialect's
 # spelling rather than to what identifies a provider API. So the gate names both
 # markers: a version segment, and the `/repos/` path that every forge API uses
 # to address a repository.
 #
 # Adding alternatives to a scope gate can only make it stricter — it cannot
 # create a new allow — which is why this is a list of triggers rather than a
 # model of any one caller. Downstream, a block still requires a body flag AND
 # either a mapped endpoint or an unreadable one, so widening the gate widens
 # what is CONSIDERED, not what is refused.
 #
 # Residual, stated rather than implied: a caller who splits `/repos/` itself in
 # a schemeless GitHub URL (`h=api.github.com/rep; q=os/a/b/issues`) leaves no
 # literal marker anywhere and is out of scope. That is the same boundary as
 # splitting the hostname — no longer a mistake anyone makes by accident.
 #
 # Boundary, deliberate and worth stating: this covers the `api` subcommand,
 # which is a raw API call wearing a CLI. Provider PORCELAIN (`tea pulls create`,
 # `gh pr merge`) is NOT covered — catching that means modelling every CLI's verb
 # grammar, which is the parser mistake again in a new costume. Porcelain is a
 # gate-7 gap for prose and review to hold, not this hook.
 API_SHAPED='https?://|/api/v[0-9]|/repos/'
 API_SHAPED="$API_SHAPED"'|(^|[[:space:]|;&(])(gh|tea|glab|hub)[[:space:]]+api([[:space:]]|$)'
 if printf '%s' "$CMD" | grep -Eq "$API_SHAPED"; then
  # Write detection, now client-agnostic. Every spelling curl accepts, because
  # the guard is defeated by the one spelling it does not know: `-d@body` (no
  # space) and `--request=POST` (equals form) both slipped past the first
  # version. Plus wget's forms and a library call, which a client-shaped test
  # could not have seen at all.
  #
  # A body flag is read as a body flag wherever it appears. `ls -d */ && curl -s
  # .../issues/1/comments` is therefore refused, which is a read wearing a
  # write's flag. That direction is the acceptable one: it costs an override on
  # a rare command, where the reverse costs a silent raw write.
  is_write=0
  printf '%s' "$CMD" | grep -Eq -- \
    '-X[[:space:]]*(POST|PATCH|PUT|DELETE)|--(request|method)[[:space:]=]*(POST|PATCH|PUT|DELETE)' && is_write=1
  # curl sends POST implicitly when handed a body, in any of these forms.
  printf '%s' "$CMD" | grep -Eq -- \
    '(^|[[:space:]])(-d|-F|-T)|--data([-a-z]*)?[[:space:]=]|--json[[:space:]=]|--form|--upload-file|--post-(data|file)[[:space:]=]' && is_write=1
  # The provider CLIs POST implicitly the same way curl does, when handed a
  # field. Matched only in `-f key=value` shape, so the far more common `rm -f`
  # and `grep -f` cannot be read as a body. The trailing `[]` is the array
  # spelling the provider CLIs use for repeated fields (`-f labels[]=bug`), and
  # without it the key class stopped at the bracket and the field was not seen
  # as a body at all — found while pinning the labels/assignees repros, both of
  # which carry it.
  printf '%s' "$CMD" | grep -Eq -- \
    '(^|[[:space:]])(-f|--field|--raw-field)[[:space:]]+[A-Za-z_][A-Za-z0-9_.-]*(\[\])?=|--input[[:space:]=]' && is_write=1
  # ...and a library call is a write without any flag at all.
  #
  # Second documented over-block, and broader than the body flags because it
  # needs no flag: any text carrying `.post(` near a wrapped URL is refused,
  # including prose that merely quotes it. That follows from the same rule as
  # the quoted-curl cost above — the payload is judged, not the caller — and it
  # is stated here so it is a known boundary rather than a surprise.
  printf '%s' "$CMD" | grep -Eq -- \
    '\.(post|put|patch|delete)\(' && is_write=1
  if [ "$is_write" -eq 1 ]; then
    # The endpoint map, and the rule that keeps it honest: an arm exists here
    # ONLY because a wrapper in this directory owns that call. It is an
    # inventory, not a model — read off `ls tools/git/*.sh` and the flags each
    # script accepts, so it can be re-derived and checked rather than believed.
    # Second column is what the wrapper SPANS; a partial span must be stated in
    # the block message, never rounded up to ownership of the whole endpoint.
    #
    #   /pulls/{n}/reviews          pr-review.sh          full
    #   /pulls/{n}/merge            pr-merge.sh           full (-m method, -d)
    #   /issues/{n}/comments        issue-comment.sh      create only (POST)
    #   /issues|pulls/{n}/assignees issue-assign.sh       full (-a, -r)
    #   /issues|pulls/{n}/labels    issue-edit.sh         sets the whole list;
    #                               issue-assign.sh -l    same
    #   /milestones/{n}             milestone-close.sh    CLOSE ONLY — title,
    #                                                     description, due date
    #                                                     are a wrapper gap
    #   /issues/{n}                 issue-edit.sh         title/body/labels/
    #                                                     milestone; close/reopen
    #                                                     for state; assignee is
    #                                                     issue-assign.sh
    #   /pulls/{n}                  pr-close.sh           state only — title and
    #                                                     body are a wrapper gap
    #   /pulls, /issues,            the create wrappers   full
    #   /milestones
    #
    # Owned by nothing, so they flow through: /issues/comments/{id} (a comment
    # EDIT), /pulls/{n}/requested_reviewers, and the residue caught by
    # subtraction below.
    #
    # Round seven had a single arm allowing EVERY path under a numbered issue or
    # PR, on the reasoning that no wrapper owned any of them. Review showed that
    # was false in this tree — issue-edit.sh takes --title/--body/--labels/
    # --milestone and issue-assign.sh takes assignee/labels/milestone — so the
    # guard was answering "allow" because wrapper ownership had been ASSUMED
    # absent instead of looked up. That is the same absence-driven allow the
    # whole file exists to remove, committed inside the fix for it. The lesson
    # is not "block more"; it is that ownership is an inventory question and an
    # inventory has to be read.
    #
    # Wrong advice remains its own defect — a block an agent cannot comply with
    # teaches that the hook is broken and the override is routine, and a routine
    # override is a guard that is off. So the fix is precision in BOTH
    # directions: every arm names the wrapper that actually owns the call, and
    # anything genuinely unowned still flows through (below).
    #
    # Round eight got the inventory right and the SPAN wrong, which review caught
    # on /milestones/{n}: milestone-close.sh takes only -t <title> and hardcodes
    # state=closed, so it cannot express a title, description or due-date edit,
    # and naming it there told an agent to use a wrapper that cannot make the
    # call. "Which wrapper touches this endpoint" is the wrong question; "does
    # the wrapper SPAN this endpoint" is the right one. Where a wrapper owns only
    # a slice, `alsoown` must say which slice and name the rest as a gap — the
    # treatment /pulls/{n} already had, and that two other arms did not, so this
    # was a consistency failure rather than a missing idea. Auditing every arm
    # for span (not just the reported one) is what found requested_reviewers.
    endpoint=""; wrapper=""; alsoown=""
    case "$CMD" in
      # Requesting a reviewer is not submitting one. pr-review.sh takes
      # -a <action> -c <comment> and files a verdict; nothing in the tree adds a
      # requested reviewer. Unowned, so it flows through — placed above the
      # reviews arm so it cannot be refused with "use pr-review.sh".
      *"/pulls/"*"/requested_reviewers"*) : ;;
      *"/pulls/"*"/reviews"*) endpoint="pull-request review"; wrapper="pr-review.sh" ;;
      *"/pulls/"*"/merge"*)   endpoint="pull-request merge";  wrapper="pr-merge.sh"  ;;
      # A comment EDIT/DELETE lives at /issues/comments/{id} — a sibling of the
      # numbered issue, not a child of it. issue-comment.sh only creates, so
      # nothing owns this one. Placed above the create arm so it cannot be
      # refused with "use issue-comment.sh", which would be the wrong call.
      *"/issues/comments/"*)  : ;;
      *"/issues/"*"/comments"*) endpoint="issue comment";     wrapper="issue-comment.sh" ;;
      *"/issues/"*"/assignees"*|*"/pulls/"*"/assignees"*)
                              endpoint="issue assignee";      wrapper="issue-assign.sh" ;;
      *"/issues/"*"/labels"*|*"/pulls/"*"/labels"*)
                              endpoint="issue label";         wrapper="issue-edit.sh"
                              alsoown="issue-assign.sh -l sets labels too (and the milestone)." ;;
      *"/milestones/"[0-9]*)  endpoint="milestone";            wrapper="milestone-close.sh"
                              alsoown="milestone-close.sh owns the CLOSE only — it takes -t <title>
 and sends state=closed. A milestone's title, description or due date is a real
 wrapper gap: no tool in this tree edits them, and the override exists for it." ;;
      # The numbered object itself. These two arms are the fuzzy ones — they
      # match a number and then anything — so they are refined immediately
      # below rather than trusted as written.
      *"/issues/"[0-9]*)      endpoint="issue edit";          wrapper="issue-edit.sh"
                              alsoown="issue-close.sh and issue-reopen.sh own the state change, and
 issue-assign.sh owns the assignee, labels and milestone fields at this same
 number — issue-edit.sh does not set an assignee." ;;
      *"/pulls/"[0-9]*)       endpoint="pull-request edit";   wrapper="pr-close.sh"
                              alsoown="pr-close.sh owns state=closed. A PR's labels, assignee and
 milestone are the ISSUE object on both providers, so issue-edit.sh and
 issue-assign.sh own those at the same number. Nothing wraps a PR title/body
 edit — that one is a real wrapper gap, and the override exists for it." ;;
      *"/pulls"*)             endpoint="pull request";        wrapper="pr-create.sh" ;;
      *"/issues"*)            endpoint="issue";               wrapper="issue-create.sh" ;;
      *"/milestones"*)        endpoint="milestone";           wrapper="milestone-create.sh" ;;
    esac
    # Refine the two fuzzy arms, and note WHY this is a regex and not another
    # case arm: `case` globs cannot express a path SEGMENT, so an allow arm
    # written as *"/issues/"[0-9]*"/"* would clear
    #   gh api -X PATCH repos/a/b/issues/1 -f body="see /docs"
    # on the strength of a slash inside the body. An allow decided by a glob
    # over the whole command is exactly the fail-open shape this file keeps
    # finding; the regex pins the segment to the number.
    #
    # The residue is defined by SUBTRACTION rather than by listing provider API
    # surface: every subresource a wrapper owns was consumed by an arm above, so
    # whatever still carries /issues|pulls/{n}/<segment> here is owned by
    # nothing — times, stopwatch, reactions, subscriptions, dependencies, a PR's
    # files or commits. Listing them instead would rot the moment a provider
    # adds one, and rot in the blocking direction with wrong advice.
    case "$endpoint" in
      "issue edit"|"pull-request edit")
        if printf '%s' "$CMD" | grep -Eq '/(issues|pulls)/[0-9]+/[A-Za-z_]'; then
          endpoint=""; wrapper=""; alsoown=""
        fi ;;
    esac
    # An endpoint the guard cannot READ is an endpoint the guard must not CLEAR.
    #
    # Round one fixed one spelling of this and review immediately produced the
    # general form: split the endpoint token itself across two variables —
    #   a=/api/v1/repos/o/r/iss; b=ues/1/comments
    #   curl -d@body "https://host${a}${b}"
    # — and no fragment above ever appears contiguously. Chasing that with more
    # fragments is unwinnable: the endpoint does not exist until the shell
    # expands it, and this hook runs before that.
    #
    # So stop pretending to read it. If a write's endpoint contains an expansion,
    # the guard has no endpoint to judge, and "no endpoint" must not mean
    # "allowed" — that is the same absence-driven allow as the missing-wrapper
    # case, wearing different clothes.
    #
    # SPAN, and the defect review found here: a fail-closed rule must cover the
    # same surface as the block it guards. This test asked only for `https?://`
    # while the scope gate above had already been widened to three shapes, so
    #   p=repos/a/b/iss; q=ues; gh api -X POST ${p}${q} -f title=x
    #   p=/api/v1/repos/a/b/iss; q=ues; curl -X POST -d x git.example.invalid${p}${q}
    # were in scope to be blocked, produced no readable endpoint, and then fell
    # through to ALLOW — while the identical split behind a literal `https://`
    # blocked. Same shape as the milestone arm one round earlier: the correct
    # treatment already existed and was applied to one of the surfaces it
    # covered. A control is only as wide as its narrowest arm.
    #
    # Three arms, one per shape the scope gate admits:
    #   A  a scheme-bearing URL token carrying an expansion
    #   B  a schemeless token carrying BOTH a forge fragment and an expansion
    #   C  the endpoint argument of a provider-CLI `api` call carrying one
    #
    # Stated limits, because a control may not claim more than it measures. B
    # requires the fragment and the expansion in the SAME shell token, so a
    # caller who splits the hostname and `/api/` as well gets through. C reads
    # the endpoint positionally — the first bare token after `api` and its option
    # run — so an endpoint pushed past an option whose value itself contains
    # whitespace is not seen. Both are deliberate: this hook stops mistakes, it
    # is not a sandbox, and pretending otherwise is how you get a control nobody
    # can trust the boundaries of.
    #
    # C's option run also accepts the bare `--` end-of-options marker, because
    # review found that `gh api -X POST -- ${p}${q} -f title=x` walked straight
    # past an option class that required a letter after the dashes. The marker is
    # the one "option" that is not spelled like one, and a scanner that skips
    # options had to be told that.
    #
    # Note what is NOT unreadable: an expansion in a BODY (`-d "$BODY"`,
    # `-f sha=$SHA`) leaves the endpoint perfectly legible, and blocking it would
    # punish the safest way to pass a payload. Only the endpoint region counts.
    URLTOK='[^[:space:]"'"'"'|;&)]*'
    FORGE='(/api/v[0-9]|/repos/|git\.|gitea|github\.com|gitlab|forgejo)'
    unreadable=0
    if printf '%s' "$CMD" | grep -Eq "https?://$URLTOK"'[$`]' \
       && printf '%s' "$CMD" | grep -Eq "$FORGE"; then unreadable=1; fi
    printf '%s' "$CMD" | grep -Eq \
      "$URLTOK($FORGE$URLTOK"'[$`]'"|"'[$`]'"$URLTOK$FORGE)" && unreadable=1
    printf '%s' "$CMD" | grep -Eq \
      '(^|[[:space:]|;&(])(gh|tea|glab|hub)[[:space:]]+api([[:space:]]+(--|--?[A-Za-z][A-Za-z-]*)([[:space:]]+[^-[:space:]][^[:space:]]*)?)*[[:space:]]+[^-[:space:]][^[:space:]]*[$`]' \
      && unreadable=1
    if [ -z "$endpoint" ] && [ "$unreadable" -eq 1 ]; then
      cat <<EOF
 BLOCKED: raw provider API write whose endpoint this guard cannot read.
 The endpoint is assembled from shell expansions, so the path it names does not
 exist until the shell builds it — after this check runs. The guard cannot tell
 whether it is a wrapped endpoint, and an unreadable endpoint is not a cleared
 one.
  $W/  <- the wrappers; use the one for the endpoint you are calling
 If you are calling a wrapped endpoint (reviews, merges, comments, pulls,
 issues, milestones), use the wrapper — it also resolves identity explicitly,
 which matters on a host whose default provider login is an admin account.
 If this is genuinely not a provider endpoint, either write the endpoint
 literally so the guard can see what it is, or prefix MOSAIC_WRAPPER_OVERRIDE=1.
 A variable in the BODY is fine and does not trigger this; only the endpoint
 itself has to be legible.
 EOF
      exit 2
    fi
    # Block on the ENDPOINT, never on whether the wrapper file happens to exist.
    # The previous version required `[ -x "$W/$wrapper" ]`, which meant a host
    # with a broken or absent install allowed exactly the raw writes the guard
    # exists to stop — an absence-driven allow, and the second one found in this
    # file. A missing wrapper is a broken install; it is not a licence to bypass
    # gate 7. Say so, and say which is which.
    if [ -n "$endpoint" ]; then
      if [ -x "$W/$wrapper" ]; then
        remedy="Use the wrapper the Constitution (gate 7) requires:
  $W/$wrapper
 Run \`$wrapper --help\` for the flags."
        # Several wrappers can own one endpoint (labels are settable from both
        # issue-edit.sh and issue-assign.sh; state has its own pair). Naming
        # only one of them is how a correct block still ends up reading as
        # wrong advice, so say which wrapper owns which part of the call.
        [ -n "$alsoown" ] && remedy="$remedy
 $alsoown"
      else
        remedy="The wrapper that covers this endpoint is \`$wrapper\`, and it is NOT
 present or not executable at:
  $W/$wrapper
 That is a broken or incomplete install, not permission to send the call raw.
 Repair the install (\`mosaic doctor\`) and use the wrapper."
        [ -n "$alsoown" ] && remedy="$remedy
 $alsoown"
      fi
      cat <<EOF
 BLOCKED: raw provider API write to the $endpoint endpoint.
 $remedy
 The wrappers are not a formality. They carry provider-dialect differences that
 raw curl silently gets wrong — Gitea's review event is APPROVED, GitHub's is
 APPROVE, and Gitea accepts the wrong one with HTTP 200 while filing the review
 as PENDING. They also resolve identity explicitly, which matters on a host
 where the default login is an admin account.
 If no wrapper flag can express this call, that is a wrapper gap: extend the
 wrapper. To proceed anyway for a genuine gap, prefix MOSAIC_WRAPPER_OVERRIDE=1.
 EOF
      exit 2
    fi
  fi
 fi
 # ---- 3. the APPROVE/APPROVED trap, wherever it appears ---------------------
 # Both spellings the trap arrives in: the JSON body `"event": "APPROVE"` and the
 # provider-CLI field `-f event=APPROVE`. The trailing [^A-Z] is what keeps the
 # correct value out of it — APPROVED must never match.
 if printf '%s' "$CMD" | grep -Eq 'event"?[[:space:]]*[=:][[:space:]]*"?APPROVE([^A-Z]|$)'; then
  cat <<EOF
 BLOCKED: review event "APPROVE" is not valid on Gitea.
 Gitea's vocabulary is "APPROVED". It accepts "APPROVE" with HTTP 200, silently
 files the review as PENDING, and then fails the submit endpoint with
 422 "review stay pending" — so the verdict looks placed and is not.
 ("REQUEST_CHANGES" is spelled identically on both providers; only the approve
 path carries this trap.)
 Use $W/pr-review.sh, which sends the correct token for the detected provider.
 Whatever you use, re-read GET /pulls/{n}/reviews and assert state==APPROVED
 before reporting a verdict placed.
 EOF
  exit 2
 fi
 exit 0
@@ -91,10 +91,12 @@ fi
 if [[ -n "$dirty_files" ]]; then
  echo "  Modified files:"
-  echo "$dirty_files" | head -20 | while IFS= read -r line; do
+  mapfile -t dirty_lines <<<"$dirty_files"
-    echo "    $line"
+  file_count="${#dirty_lines[@]}"
  display_count=$((file_count < 20 ? file_count : 20))
  for ((i = 0; i < display_count; i++)); do
    echo "    ${dirty_lines[$i]}"
  done
  file_count="$(echo "$dirty_files" | wc -l)"
  if (( file_count > 20 )); then
    echo "    ... and $(( file_count - 20 )) more"
  fi
@@ -64,12 +64,12 @@ if jq -e '.next_task == "T-001"' "$capsule_file" >/dev/null 2>&1; then pass_case
 if grep -Fq 'Target runtime:** codex' <<< "$codex_continue_output"; then pass_case "continue prompt contains target runtime codex"; else fail_case "continue prompt contains target runtime codex"; fi
 codex_run_prompt="$(MOSAIC_COORD_RUNTIME=codex bash "$SCRIPT_DIR/session-run.sh" --project "$tmp_project" --print)"
-if [[ "$(printf '%s\n' "$codex_run_prompt" | head -n1)" == "Now initiating Orchestrator mode..." ]]; then pass_case "codex run prompt first line is mode declaration"; else fail_case "codex run prompt first line is mode declaration"; fi
+if [[ "${codex_run_prompt%%$'\n'*}" == "Now initiating Orchestrator mode..." ]]; then pass_case "codex run prompt first line is mode declaration"; else fail_case "codex run prompt first line is mode declaration"; fi
 if grep -Fq 'Do NOT ask clarifying questions before your first tool actions' <<< "$codex_run_prompt"; then pass_case "codex run prompt includes no-questions hard gate"; else fail_case "codex run prompt includes no-questions hard gate"; fi
 if grep -Fq '"next_task": "T-001"' <<< "$codex_run_prompt"; then pass_case "codex run prompt embeds capsule json"; else fail_case "codex run prompt embeds capsule json"; fi
 claude_run_prompt="$(MOSAIC_COORD_RUNTIME=claude bash "$SCRIPT_DIR/session-run.sh" --project "$tmp_project" --print)"
-if [[ "$(printf '%s\n' "$claude_run_prompt" | head -n1)" == "## Continuation Mission" ]]; then pass_case "claude run prompt remains continuation prompt format"; else fail_case "claude run prompt remains continuation prompt format"; fi
+if [[ "${claude_run_prompt%%$'\n'*}" == "## Continuation Mission" ]]; then pass_case "claude run prompt remains continuation prompt format"; else fail_case "claude run prompt remains continuation prompt format"; fi
 echo ""
 echo "Smoke test summary: pass=$PASS fail=$FAIL"
@@ -96,8 +96,8 @@ L="$WORK/live5.md"; G="$WORK/ledger5.md"; echo "# LEDGER" > "$G"
 make_board "$L" 6 1 400
 before_l=$(cat "$L"); before_g=$(cat "$G")
 out=$(bash "$SUT" --live "$L" --ledger "$G" --cap 2000 --dry-run 2>&1) || note "dry-run exited nonzero: $out"
-echo "$out" | grep -qi "dry run" || note "dry-run did not announce itself"
+grep -qi "dry run" <<<"$out" || note "dry-run did not announce itself"
-echo "$out" | grep -q "would roll" || note "dry-run did not report a plan"
+grep -q "would roll" <<<"$out" || note "dry-run did not report a plan"
 [[ "$(cat "$L")" == "$before_l" ]] || note "dry-run modified LIVE"
 [[ "$(cat "$G")" == "$before_g" ]] || note "dry-run modified LEDGER"
@@ -66,7 +66,7 @@ present=0
 for entry in "${PRDY_REQUIRED_SECTIONS[@]}"; do
  pattern="${entry#*|}"
-  if echo "$PRD_CONTENT" | grep -qiE "$pattern"; then
+  if grep -qiE "$pattern" <<<"$PRD_CONTENT"; then
    present=$((present + 1))
  fi
 done
@@ -169,13 +169,13 @@ main() {
 # classify_surface PATH → surface name (highest-risk match wins, mirrors TS)
 classify_surface() {
  local p="$1"
-  if printf '%s' "$p" | grep -qiE 'auth|login|session|token|permission|rbac|credential|secret'; then echo auth; return; fi
+  if grep -qiE 'auth|login|session|token|permission|rbac|credential|secret' <<<"$p"; then echo auth; return; fi
-  if printf '%s' "$p" | grep -qiE 'migration|prisma|schema|\.sql|entity|repository|seed'; then echo data; return; fi
+  if grep -qiE 'migration|prisma|schema|\.sql|entity|repository|seed' <<<"$p"; then echo data; return; fi
-  if printf '%s' "$p" | grep -qiE 'docker|\.woodpecker|compose|traefik|deploy|helm|k8s|terraform'; then echo infra; return; fi
+  if grep -qiE 'docker|\.woodpecker|compose|traefik|deploy|helm|k8s|terraform' <<<"$p"; then echo infra; return; fi
-  if printf '%s' "$p" | grep -qiE 'package\.json|tsconfig|turbo\.json|pnpm-|\.config\.|eslint|vite'; then echo build; return; fi
+  if grep -qiE 'package\.json|tsconfig|turbo\.json|pnpm-|\.config\.|eslint|vite' <<<"$p"; then echo build; return; fi
-  if printf '%s' "$p" | grep -qE '\.tsx|\.css|components/|apps/web/'; then echo ui; return; fi
+  if grep -qE '\.tsx|\.css|components/|apps/web/' <<<"$p"; then echo ui; return; fi
-  if printf '%s' "$p" | grep -qE '\.spec\.|\.test\.|__tests__/'; then echo test; return; fi
+  if grep -qE '\.spec\.|\.test\.|__tests__/' <<<"$p"; then echo test; return; fi
-  if printf '%s' "$p" | grep -qE '\.md$|docs/'; then echo docs; return; fi
+  if grep -qE '\.md$|docs/' <<<"$p"; then echo docs; return; fi
  echo none
 }
@@ -13,7 +13,12 @@ JSON_INPUT=$(cat)
 if command -v jq &>/dev/null; then
  FILE_PATH=$(echo "$JSON_INPUT" | jq -r '.tool_input.file_path // .tool_response.filePath // .file_path // empty' 2>/dev/null || echo "")
 else
-  FILE_PATH=$(echo "$JSON_INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*"\([^"]*\)"$/\1/' | head -1)
+  file_path_pattern='"file_path"[[:space:]]*:[[:space:]]*"([^"]*)"'
  if [[ "$JSON_INPUT" =~ $file_path_pattern ]]; then
    FILE_PATH="${BASH_REMATCH[1]}"
  else
    FILE_PATH=""
  fi
 fi
 # Only check TypeScript files
@@ -53,7 +58,7 @@ OUTPUT=$(npx tsc --noEmit --pretty --maxNodeModuleJsDepth 0 2>&1) || STATUS=$?
 if [ "${STATUS:-0}" -ne 0 ]; then
  # Filter output to only show errors related to the edited file (if possible)
  BASENAME=$(basename "$FILE_PATH")
-  RELEVANT=$(echo "$OUTPUT" | grep -A2 "$BASENAME" 2>/dev/null || echo "$OUTPUT" | head -20)
+  RELEVANT=$(grep -A2 "$BASENAME" <<<"$OUTPUT" 2>/dev/null || sed -n '1,20p' <<<"$OUTPUT")
  echo "TypeScript type errors detected after editing $FILE_PATH:"
  echo "$RELEVANT"
@@ -0,0 +1,293 @@
 #!/usr/bin/env bash
 # check-tools-index.sh — assert every shipped tool is discoverable from the
 # resident documentation an agent actually has in context.
 #
 # WHY THIS GATE EXISTS
 # --------------------
 # The framework ships 26 git wrappers. Before this gate, 20 of them were named
 # in neither `defaults/TOOLS.md` nor `guides/TOOLS-REFERENCE.md`. One of the
 # undocumented ones was `pr-review.sh` — the wrapper that carries the
 # APPROVED/APPROVE provider-dialect split.
 #
 # The observable consequence, on a live fleet host: an agent needing to place a
 # review verdict reached for raw `curl`, sent GitHub's `APPROVE` to a Gitea
 # host, and got HTTP 200 with the review silently filed PENDING — three times,
 # because nothing about the failure pointed at the wrapper that already handled
 # it correctly. The agent was not ignoring Constitution gate 7. It was obeying
 # an index that said the tool did not exist.
 #
 # That is not a discipline problem and no amount of prose fixes it. A wrapper
 # that is not in the resident index is, from inside a session, indistinguishable
 # from a wrapper that was never written. So the invariant is mechanical:
 #
 #     shipping a tool and documenting it are the same commit, or CI fails.
 #
 # WHAT IT CHECKS
 # --------------
 #   forward  every non-excluded tool in an ENFORCED suite is named in at least
 #            one index document (missing tool -> undiscoverable -> FAIL)
 #   reverse  every `<name>.sh` an index document attributes to an enforced
 #            suite exists on disk (stale reference -> agent runs a ghost -> FAIL)
 #
 # Suites outside the enforced set are reported with a coverage percentage but do
 # not fail the build, so the ratchet can be tightened one suite per PR instead of
 # landing as one unreviewable sweep. `--strict` fails on those too.
 #
 # WHY THE ENFORCED LIST LIVES HERE AND NOT IN A MARKER INSIDE THE DOC
 # -------------------------------------------------------------------
 # `TOOLS.md` is operator-owned (see framework-manifest.txt). A marker inside it
 # would let an operator silence this gate by editing their own copy — the gate
 # would then be strongest exactly where it is least needed and absent where it
 # is needed most. The list is framework-owned and changes only through a
 # reviewed PR.
 #
 # Usage:
 #   check-tools-index.sh [--tools-dir DIR] [--doc FILE]... [--strict] [--self-test]
 #
 # Exit: 0 = every enforced suite fully discoverable · 1 = drift · 2 = bad usage
 set -euo pipefail
 # Suites whose coverage is a HARD requirement. Add a suite here only together
 # with the doc changes that make it pass.
 #
 # `git` is first because it is the suite Constitution gates 6-8 make mandatory:
 # an undiscoverable git wrapper converts a hard gate into a coin flip.
 ENFORCED_SUITES=(git)
 # Files that are not agent-callable tools and must not be required in an index.
 EXCLUDE_GLOBS=(
  'test-*'        # hermetic regression scripts, invoked by CI not by agents
  '_*'            # private helpers (_lib, _scripts internals)
  '*.bak'         # editor/installer debris
  '*.pre-*'       # pre-change backups (e.g. ci-queue-wait.sh.pre-404fix-bak)
  'README.md'
 )
 STRICT=0
 SELF_TEST=0
 TOOLS_DIR=""
 DOCS=()
 die() { printf 'check-tools-index: %s\n' "$*" >&2; exit 2; }
 while [ $# -gt 0 ]; do
  case "$1" in
    --tools-dir) TOOLS_DIR="${2:-}"; shift 2 ;;
    --doc)       DOCS+=("${2:-}");   shift 2 ;;
    --strict)    STRICT=1; shift ;;
    --self-test) SELF_TEST=1; shift ;;
    -h|--help)   sed -n '2,48p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
    *)           die "unknown argument: $1" ;;
  esac
 done
 # ---- location resolution ---------------------------------------------------
 # Runs from two places with different layouts, and must not silently check the
 # wrong tree: a CI checkout (repo-relative) and an installed host ($MOSAIC_HOME).
 resolve_locations() {
  local here framework
  here="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
  # .../framework/tools/quality/scripts -> .../framework
  framework="$(cd -- "$here/../../.." && pwd)"
  if [ -z "$TOOLS_DIR" ]; then
    if [ -d "$framework/tools" ]; then
      TOOLS_DIR="$framework/tools"
    else
      TOOLS_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}/tools"
    fi
  fi
  if [ ${#DOCS[@]} -eq 0 ]; then
    # The two layouts are mutually exclusive on purpose. Unioning them would let
    # a well-maintained operator TOOLS.md on the developer's own machine mask a
    # gap in the shipped defaults — the check would pass locally and the defect
    # would still install on every other host. Repo layout wins when present.
    if [ -f "$framework/defaults/TOOLS.md" ]; then
      DOCS+=("$framework/defaults/TOOLS.md")
      [ -f "$framework/guides/TOOLS-REFERENCE.md" ] && DOCS+=("$framework/guides/TOOLS-REFERENCE.md")
    else
      local mosaic_home="${MOSAIC_HOME:-$HOME/.config/mosaic}"
      [ -f "$mosaic_home/TOOLS.md" ]                  && DOCS+=("$mosaic_home/TOOLS.md")
      [ -f "$mosaic_home/guides/TOOLS-REFERENCE.md" ] && DOCS+=("$mosaic_home/guides/TOOLS-REFERENCE.md")
    fi
  fi
  [ -d "$TOOLS_DIR" ] || die "tools dir not found: $TOOLS_DIR"
  [ ${#DOCS[@]} -gt 0 ] || die "no index documents found (pass --doc FILE)"
 }
 is_excluded() {
  local name="$1" glob
  for glob in "${EXCLUDE_GLOBS[@]}"; do
    # shellcheck disable=SC2254  # glob is intentionally a pattern
    case "$name" in $glob) return 0 ;; esac
  done
  return 1
 }
 # A tool counts as documented when its basename appears anywhere in the corpus.
 # Deliberately permissive about *form* (table cell, code fence, prose) and strict
 # about *presence*: the gate's job is "an agent can find it", not house style.
 documented() { grep -qF -- "$1" "$CORPUS"; }
 # ---- the check -------------------------------------------------------------
 run_check() {
  local rc=0 suite dir tool base enforced
  CORPUS="$(mktemp)"; trap 'rm -f "$CORPUS"' RETURN
  cat "${DOCS[@]}" > "$CORPUS"
  printf 'tools:  %s\n' "$TOOLS_DIR"
  for d in "${DOCS[@]}"; do printf 'index:  %s\n' "$d"; done
  printf '\n'
  for dir in "$TOOLS_DIR"/*/; do
    [ -d "$dir" ] || continue
    suite="$(basename -- "$dir")"
    case " ${ENFORCED_SUITES[*]} " in *" $suite "*) enforced=1 ;; *) enforced=0 ;; esac
    [ "$STRICT" -eq 1 ] && enforced=1
    case "$suite" in _*) continue ;; esac
    local total=0 found=0
    local -a suite_missing=() suite_noexec=()
    for tool in "$dir"*.sh; do
      [ -e "$tool" ] || continue
      base="$(basename -- "$tool")"
      is_excluded "$base" && continue
      total=$((total + 1))
      if documented "$base"; then
        found=$((found + 1))
        # Documented AND present is not enough. The index presents these as
        # commands to run, and every caller — the wrapper guard included —
        # decides "is this tool here?" with `[ -x ]`. A 0644 wrapper is
        # documented, present, and dead: it reads as absent to every check that
        # matters while scoring 100% here. That is a false green, which is worse
        # than a red, so it fails rather than warns.
        [ -x "$tool" ] || suite_noexec+=("$base")
      else
        suite_missing+=("$base")
      fi
    done
    [ "$total" -eq 0 ] && continue
    local pct=$(( found * 100 / total ))
    if [ "$enforced" -eq 1 ] && [ ${#suite_noexec[@]} -gt 0 ]; then
      printf 'FAIL  %-12s %3d%% (%d/%d)  documented but not executable: %s\n' \
        "$suite" "$pct" "$found" "$total" "${suite_noexec[*]}"
      rc=1
    fi
    if [ "$enforced" -eq 1 ] && [ ${#suite_missing[@]} -gt 0 ]; then
      printf 'FAIL  %-12s %3d%% (%d/%d)  undocumented: %s\n' \
        "$suite" "$pct" "$found" "$total" "${suite_missing[*]}"
      rc=1
    elif [ "$enforced" -eq 1 ] && [ ${#suite_noexec[@]} -eq 0 ]; then
      printf 'ok    %-12s %3d%% (%d/%d)  [enforced]\n' "$suite" "$pct" "$found" "$total"
    else
      printf 'info  %-12s %3d%% (%d/%d)  not yet enforced\n' "$suite" "$pct" "$found" "$total"
    fi
    # Reverse: an index that names a tool this suite does not have sends agents
    # after something that cannot run. Only checked for enforced suites, where
    # the naming is unambiguous enough to attribute.
    if [ "$enforced" -eq 1 ]; then
      local -a stale=()
      local ref
      while read -r ref; do
        [ -n "$ref" ] || continue
        is_excluded "$ref" && continue
        [ -e "$dir$ref" ] || stale+=("$ref")
      done < <(grep -oE "$suite/[a-z0-9][a-z0-9._-]*\.sh" "$CORPUS" \
                 | sed "s|^$suite/||" | sort -u)
      if [ ${#stale[@]} -gt 0 ]; then
        printf 'FAIL  %-12s stale index references (no such file): %s\n' \
          "$suite" "${stale[*]}"
        rc=1
      fi
    fi
  done
  printf '\n'
  if [ "$rc" -ne 0 ]; then
    cat <<EOF
 Undocumented tools are undiscoverable. An agent cannot obey a hard gate that
 tells it to use a wrapper it has no way to learn exists — it will reach for raw
 curl/gh/tea instead, and the wrapper's provider-dialect handling will be lost.
 Fix by naming each tool above in one of the index documents listed at the top,
 in the same commit that ships it.
 EOF
  else
    printf 'every enforced suite is fully discoverable.\n'
  fi
  return "$rc"
 }
 # ---- self-test -------------------------------------------------------------
 # Proves the gate can actually fail. A checker that only ever passes is
 # indistinguishable from one that is not running, which is the failure mode this
 # whole file exists to prevent — so it must demonstrate a red on demand.
 self_test() {
  local tmp rc
  tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' RETURN
  mkdir -p "$tmp/tools/git"
  printf '#!/bin/sh\n' > "$tmp/tools/git/documented-tool.sh"
  printf '#!/bin/sh\n' > "$tmp/tools/git/test-ignored.sh"
  chmod +x "$tmp/tools/git/documented-tool.sh" "$tmp/tools/git/test-ignored.sh"
  # run_check reads the TOOLS_DIR / DOCS globals; an array cannot ride in a
  # command-prefix assignment, so point the globals at the fixture directly.
  TOOLS_DIR="$tmp/tools"
  DOCS=("$tmp/doc.md")
  # Case 1: fully documented -> pass.
  printf 'see tools/git/documented-tool.sh for details\n' > "$tmp/doc.md"
  if run_check >/dev/null; then
    printf 'self-test 1/4 ok  (complete index passes)\n'
  else
    printf 'self-test 1/4 FAIL (complete index should pass)\n'; return 1
  fi
  # Case 2: an undocumented tool -> fail.
  printf '#!/bin/sh\n' > "$tmp/tools/git/undocumented-tool.sh"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 2/4 ok  (undocumented tool fails the gate)\n'
  else
    printf 'self-test 2/4 FAIL (undocumented tool should fail, got rc=%s)\n' "$rc"; return 1
  fi
  # Case 3: a stale index reference -> fail.
  rm "$tmp/tools/git/undocumented-tool.sh"
  printf 'also tools/git/deleted-tool.sh\n' >> "$tmp/doc.md"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 3/4 ok  (stale index reference fails the gate)\n'
  else
    printf 'self-test 3/4 FAIL (stale reference should fail, got rc=%s)\n' "$rc"; return 1
  fi
  # Case 4: documented, present, and NOT executable -> fail. Found by an
  # independent reviewer: a 0644 wrapper scored 100% here while reading as
  # absent to every `[ -x ]` in the fleet, including the wrapper guard's.
  sed -i '/deleted-tool/d' "$tmp/doc.md"
  printf '#!/bin/sh\n' > "$tmp/tools/git/noexec-tool.sh"
  chmod 0644 "$tmp/tools/git/noexec-tool.sh"
  printf 'and tools/git/noexec-tool.sh\n' >> "$tmp/doc.md"
  rc=0; run_check >/dev/null || rc=$?
  if [ "$rc" -eq 1 ]; then
    printf 'self-test 4/4 ok  (documented but non-executable tool fails the gate)\n'
  else
    printf 'self-test 4/4 FAIL (non-executable tool should fail, got rc=%s)\n' "$rc"; return 1
  fi
  printf '\nself-test passed: the gate demonstrably reds on every drift direction.\n'
 }
 if [ "$SELF_TEST" -eq 1 ]; then
  self_test
 else
  resolve_locations
  run_check
 fi
@@ -26,6 +26,9 @@ chk "F1 fresh: CONSTITUTION/AGENTS/STANDARDS/TOOLS seeded" \
  "[ -f '$T1/CONSTITUTION.md' ] && [ -f '$T1/AGENTS.md' ] && [ -f '$T1/STANDARDS.md' ] && [ -f '$T1/TOOLS.md' ]"
 chk "F1 fresh: AGENTS == shipped default" "cmp -s '$T1/AGENTS.md' '$DEFA/AGENTS.md'"
 chk "F1 fresh: framework-version stamped 3" "[ \"\$(cat '$T1/.framework-version' 2>/dev/null)\" = 3 ]"
 chk "F1 fresh: Pi goal extension deploys under Mosaic runtime" \
  "cmp -s '$T1/runtime/pi/goal-extension.ts' '$FW/runtime/pi/goal-extension.ts'"
 chk "F1 fresh: installer creates no nested main Pi config" "[ ! -e '$T1/.pi' ]"
 # F2 — legacy install with a user-edited AGENTS.md (the sanctioned pre-constitution customization)
 T2=$(mktemp -d); mkdir -p "$T2/credentials"
@@ -89,6 +92,8 @@ chk "F6 reseed: per-agent env bytes survive" "cmp -s '$T6/fleet/agents/coder0.en
 chk "F6 reseed: heartbeat bytes survive" "cmp -s '$T6/fleet/run/coder0.hb' '$E6/run.expected'"
 chk "F6 reseed: framework examples are refreshed" "grep -q orchestrator '$T6/fleet/examples/general.yaml'"
 chk "F6 reseed: framework roster schema is refreshed" "cmp -s '$T6/fleet/roster.schema.json' '$FW/fleet/roster.schema.json'"
 chk "F6 reseed: Pi goal extension is refreshed from framework source" \
  "cmp -s '$T6/runtime/pi/goal-extension.ts' '$FW/runtime/pi/goal-extension.ts'"
 rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" "$T6" "$E6"
 echo
@@ -176,8 +176,12 @@ run_snap() {
 # Resolve the single pre-update-* snapshot dir under a state dir (newest if many).
 snap_dir() {
-  find "$1/mosaic/backups" -maxdepth 1 -type d -name 'pre-update-*' 2>/dev/null \
+  local -a snapshots=()
-    | LC_ALL=C sort -r | head -1
+  mapfile -t snapshots < <(
    find "$1/mosaic/backups" -maxdepth 1 -type d -name 'pre-update-*' 2>/dev/null \
      | LC_ALL=C sort -r
  )
  printf '%s\n' "${snapshots[0]:-}"
 }
 echo "── Part 1/2/3: durable snapshot scope, perms, no-leak ──────────────────"
@@ -39,11 +39,12 @@ ORIG_PATH="$PATH"
 # loop — which would make the control a false negative. A root dotfile is
 # operator-owned (unknown→operator), so the sync loop skips it. Clean up on exit.
 STRIPPED="$FW/.install-rollback-control.tmp.sh"
 SIGNALED="$FW/.install-signal-control.tmp.sh"
 NOEXIT="$FW/.install-noexit-control.tmp.sh"
 D1CTRL="$FW/.install-d1guard-control.tmp.sh"
 D2CTRL="$FW/.install-d2guard-control.tmp.sh"
-rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+rm -f "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
-trap 'rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
+trap 'rm -f "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
 pass=0; fail=0
 chk() { if eval "$2"; then echo "  ✓ $1"; pass=$((pass + 1)); else echo "  ✗ $1"; fail=$((fail + 1)); fi; }
@@ -180,41 +181,86 @@ chk "[control] without -E the mid-sync corruption survives (no rollback)" \
 # ── Part C: an INT/TERM interrupt must terminate, not resume (blocker-A) ──────
 # A bash signal trap that merely returns lets the script continue past the
 # interrupt — restoring the snapshot, then resuming the sync and reporting
-# success. We inject a SIGTERM mid-sync with a cp that SUCCEEDS (so set -e never
+# success. The earlier test used a child cp shim to signal its parent, making
-# fires and ONLY the signal path governs), and assert the shipped installer
+# child completion race Bash's interrupted wait. Concurrency is not part of the
-# restores AND exits without reporting success. The control strips `exit 1` from
+# guarded property: sync_framework_keep() runs in the installer's own Bash
-# the trap and shows the buggy resume-to-success.
+# process, and `kill` is a builtin. Generate two installer fixtures that signal
-make_term_shim() {
+# themselves at the same known mid-sync point. Their TERM handlers emit the same
-  local dir="$1"
+# observable before diverging, so missing signal delivery fails BOTH arms rather
-  cat > "$dir/cp" <<SHIM
+# than manufacturing a pass. The only semantic difference between fixtures is
-#!/usr/bin/env bash
+# the explicit `exit 1` whose load-bearing behavior this control proves.
-dest="\${@: -1}"
+TERM_MARKER='[test-control] TERM handler entered'
-case "\$dest" in
+HANDLER_WITH_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot; exit 1' TERM  # TEST-TERM-HANDLER"
-  */$POISON_REL)
+HANDLER_WITHOUT_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot' TERM  # TEST-TERM-HANDLER"
-    kill -TERM "\$PPID" 2>/dev/null   # signal install.sh; the copy still succeeds
+
-    exec env PATH="$ORIG_PATH" cp "\$@" ;;
+make_signal_installer() {
-esac
+  local output="$1" handler="$2"
-exec env PATH="$ORIG_PATH" cp "\$@"
+  local target_trap="trap 'restore_snapshot; exit 1' ERR INT TERM"
-SHIM
+  local target_cp='    cp "$abs" "$dst/$rel"'
-  chmod +x "$dir/cp"
+  local inject_open="    if [[ \"\$rel\" == \"$POISON_REL\" ]]; then"
  local inject_kill='      kill -TERM "$$"  # TEST-TERM-INJECTION'
  local inject_close='    fi'
  if ! awk \
    -v target_trap="$target_trap" -v target_cp="$target_cp" \
    -v handler="$handler" -v inject_open="$inject_open" \
    -v inject_kill="$inject_kill" -v inject_close="$inject_close" '
      $0 == target_cp {
        print inject_open
        print inject_kill
        print inject_close
        injection_sites++
      }
      { print }
      $0 == target_trap {
        print handler
        handler_sites++
      }
      END {
        if (handler_sites != 1 || injection_sites != 1) exit 42
      }
    ' "$INSTALL" > "$output"; then
    rm -f "$output"
    fail "Could not construct the self-TERM control installer at the exact trap/copy sites"
    exit 1
  fi
  chmod +x "$output"
 }
-# Run one keep-mode upgrade with the SIGTERM shim. Echoes "<exit>\t<out>\t<home>".
+make_signal_installer "$SIGNALED" "$HANDLER_WITH_EXIT"
 make_signal_installer "$NOEXIT" "$HANDLER_WITHOUT_EXIT"
 signal_fixture_ready() {
  local fixture="$1" expected_handler="$2"
  [[ "$(grep -cF '# TEST-TERM-INJECTION' "$fixture")" -eq 1 ]] \
    && [[ "$(grep -cF '# TEST-TERM-HANDLER' "$fixture")" -eq 1 ]] \
    && grep -Fqx "$expected_handler" "$fixture"
 }
 signaled_fixture_ready() { signal_fixture_ready "$SIGNALED" "$HANDLER_WITH_EXIT"; }
 noexit_fixture_ready() { signal_fixture_ready "$NOEXIT" "$HANDLER_WITHOUT_EXIT"; }
 chk "[signal] shipped fixture has exactly one self-TERM injection and marked handler" \
  "signaled_fixture_ready"
 chk "[control] no-exit fixture has exactly one self-TERM injection and marked handler" \
  "noexit_fixture_ready"
 chk "[control] removing the explicit TERM exit changes the fixture" \
  "! cmp -s '$SIGNALED' '$NOEXIT'"
 # Run one keep-mode upgrade whose own shell delivers SIGTERM synchronously at
 # the selected copy. Echoes "<exit>\t<out>\t<home>".
 run_signal_upgrade() {
-  local installer="$1" H OUT SHIM rc
+  local installer="$1" H OUT rc
-  H=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
+  H=$(mktemp -d); OUT=$(mktemp)
  seed_home "$H"
  make_term_shim "$SHIM"
  set +e
-  PATH="$SHIM:$ORIG_PATH" \
+  PATH="$ORIG_PATH" \
    MOSAIC_HOME="$H" MOSAIC_INSTALL_MODE=keep MOSAIC_SYNC_ONLY=1 bash "$installer" >"$OUT" 2>&1
  rc=$?
  set -e 2>/dev/null || true
  rm -rf "$SHIM"
  printf '%s\t%s\t%s\n' "$rc" "$OUT" "$H"
 }
-IFS=$'\t' read -r rcC OUTC HC < <(run_signal_upgrade "$INSTALL")
+IFS=$'\t' read -r rcC OUTC HC < <(run_signal_upgrade "$SIGNALED")
 chk "[signal] TERM handler observable fires exactly once" \
  "[ \"\$(grep -cF '$TERM_MARKER' '$OUTC')\" -eq 1 ]"
 chk "[signal] SIGTERM mid-sync aborts non-zero (trap exits, does not resume)" \
  "[ '$rcC' -ne 0 ]"
 chk "[signal] restore_snapshot fires on the interrupt" \
@@ -222,13 +268,13 @@ chk "[signal] restore_snapshot fires on the interrupt" \
 chk "[signal] does NOT resume to report sync success after the interrupt" \
  "! grep -q 'file phase complete' '$OUTC'"
-# Control: strip `exit 1` from the signal trap → the handler returns, the script
+IFS=$'\t' read -r rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
-# resumes past the interrupt and wrongly reports success. In $FW so SOURCE_DIR resolves.
+chk "[control] TERM handler observable fires exactly once" \
-sed "s/trap 'restore_snapshot; exit 1' ERR INT TERM/trap 'restore_snapshot' ERR INT TERM/" \
+  "[ \"\$(grep -cF '$TERM_MARKER' '$OUTD')\" -eq 1 ]"
-  "$INSTALL" > "$NOEXIT"
+chk "[control] without 'exit 1' the handler restores before returning" \
-chk "[control] the exit-strip actually changed the installer" \
+  "grep -q 'restoring previous state from snapshot' '$OUTD'"
-  "! cmp -s '$INSTALL' '$NOEXIT'"
+chk "[control] without 'exit 1' the installer exits zero after resuming" \
-IFS=$'\t' read -r _rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
+  "[ '$rcD' -eq 0 ]"
 chk "[control] without 'exit 1' the trap resumes and reports sync success (the bug)" \
  "grep -q 'file phase complete' '$OUTD'"
@@ -290,7 +336,7 @@ chk "[reset-fail] the manual-recovery pointer is emitted (not a silent set -e ex
  "grep -q 'Snapshot restore could not reset' '$OUTG'"
 chk "[reset-fail] the recovery message points at a preserved snapshot dir" \
  "grep -q 'preserved at: .*mosaic-snapshot' '$OUTG'"
-SNAP_E="$(grep -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTG" | head -1)"
+SNAP_E="$(grep -m1 -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTG")"
 chk "[reset-fail] the named snapshot directory actually survives for recovery" \
  "[ -n '$SNAP_E' ] && [ -d '$SNAP_E' ]"
 chk "[reset-fail] operator secret value never appears in installer output" \
@@ -307,12 +353,13 @@ chk "[control] without the D2 recovery line the operator gets no snapshot pointe
  "! grep -q 'Snapshot restore could not reset' '$OUTH'"
 [ -n "${SNAP_E:-}" ] && rm -rf "$SNAP_E"
 # Reap any snapshot the reset-fail runs left in /tmp (reset failed → never cleaned).
-grep -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTH" 2>/dev/null | head -1 | while read -r s; do rm -rf "$s"; done
+orphan_snapshot="$(grep -m1 -o '/[^ ]*mosaic-snapshot[^ ]*' "$OUTH" 2>/dev/null || true)"
 [ -n "$orphan_snapshot" ] && rm -rf "$orphan_snapshot"
-# Cleanup ($STRIPPED / $NOEXIT / $D1CTRL / $D2CTRL are also removed by the EXIT trap).
+# Cleanup (generated installer controls are also removed by the EXIT trap).
 for d in "$HA" "$REFA" "$HB" "$REFB" "$HC" "$HD" "$HE" "$REFE" "$HF" "$REFF" "$HG" "$HH"; do rm -rf "$d"; done
 rm -f "$OUTA" "$OUTB" "$OUTC" "$OUTD" "$OUTE" "$OUTF" "$OUTG" "$OUTH" \
-  "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+  "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
 echo
 echo "RESULT: $pass passed, $fail failed"
@@ -32,7 +32,6 @@ packages/mosaic/framework/tools/tmux/test-send-message-socket.sh | requires a re
 packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires real tmux-pane fixtures on a throwaway socket; CI image ships no tmux; #1017 burndown (same condition as its sibling)
 # --- single-suite directories: unmeasured in CI ---
 packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | unmeasured in CI image; stubs tmux via a fake bin dir, likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/glpi/test-list-http-status.sh | unmeasured in CI image; stub-based (#807 regression harness), likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/orchestrator/test-board-roll.sh | unmeasured in CI image; file-fixture based, likely CI-fit; #1017 burndown
 packages/mosaic/framework/tools/woodpecker/test-ci-wait-exit-matrix.sh | unmeasured in CI image; drives ci-wait.sh against a stub pipeline-status.sh, likely CI-fit; #1017 burndown
@@ -110,7 +110,7 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
  sleep 1.2
  pane=$("${tmux_cmd[@]}" capture-pane -t "$EFFECTIVE_TARGET" -p 2>/dev/null)
-  if printf '%s' "$pane" | grep -qF "$QUEUED_RE"; then
+  if grep -qF "$QUEUED_RE" <<<"$pane"; then
    status="queued"; break
  fi
  # Locate the REPL input box (prompt glyph). If we cannot see it, we have NO
@@ -121,7 +121,7 @@ for attempt in $(seq 1 $((RETRIES + 1))); do
  fi
  # Input box located AND still carrying our tail => unsubmitted draft. Flush + retry.
  # (Submitted messages scroll up into history; a draft stays on the ❯ line.)
-  if [ -n "$snippet" ] && printf '%s' "$promptline" | grep -qF "$snippet"; then
+  if [ -n "$snippet" ] && grep -qF "$snippet" <<<"$promptline"; then
    status="draft"; continue
  fi
  # Input box located AND clear of our tail => positively submitted. This is the
@@ -34,16 +34,20 @@ tmux new-session -d -s "$DEFAULT_TARGET" -c "$TMPDIR" 'PS1="❯ " exec bash --no
 "$SEND_MESSAGE" -L "$SOCKET" -t "=$TARGET" -m "named socket hello" >/tmp/send-message-named.out
 sleep 0.2
-capture_named | grep -qF "named socket hello" || fail "send-message.sh did not deliver to named socket"
+named_pane="$(capture_named)" || fail "could not capture named socket pane"
-if capture_default | grep -qF "named socket hello"; then
+grep -qF "named socket hello" <<<"$named_pane" || fail "send-message.sh did not deliver to named socket"
 default_pane="$(capture_default)" || fail "could not capture default socket pane"
 if grep -qF "named socket hello" <<<"$default_pane"; then
  fail "send-message.sh leaked named-socket message to default tmux server"
 fi
 "$AGENT_SEND" -L "$SOCKET" -S "tester:source" -s "=$TARGET" -m "agent socket hello" >/tmp/agent-send-named.out
 sleep 0.2
-capture_named | grep -qF "[tester:source ->" || fail "agent-send.sh did not include preamble"
+named_pane="$(capture_named)" || fail "could not capture named socket pane"
-capture_named | grep -qF "agent socket hello" || fail "agent-send.sh did not deliver to named socket"
+grep -qF "[tester:source ->" <<<"$named_pane" || fail "agent-send.sh did not include preamble"
-if capture_default | grep -qF "agent socket hello"; then
+grep -qF "agent socket hello" <<<"$named_pane" || fail "agent-send.sh did not deliver to named socket"
 default_pane="$(capture_default)" || fail "could not capture default socket pane"
 if grep -qF "agent socket hello" <<<"$default_pane"; then
  fail "agent-send.sh leaked named-socket message to default tmux server"
 fi
@@ -65,11 +69,11 @@ done
 sleep 0.2
 for i in $(seq 1 "$CONC_N"); do
  pane=$(tmux -L "$SOCKET" capture-pane -t "=conc-$i:0.0" -p)
-  printf '%s' "$pane" | grep -qF "CONCPAYLOAD-${i}-END" \
+  grep -qF "CONCPAYLOAD-${i}-END" <<<"$pane" \
    || fail "concurrent send dropped payload for pane conc-$i"
  for j in $(seq 1 "$CONC_N"); do
    [ "$j" = "$i" ] && continue
-    if printf '%s' "$pane" | grep -qF "CONCPAYLOAD-${j}-END"; then
+    if grep -qF "CONCPAYLOAD-${j}-END" <<<"$pane"; then
      fail "concurrent send cross-delivered payload $j to pane conc-$i"
    fi
  done
@@ -31,7 +31,7 @@ tmux -L "$SOCKET" new-session -d -s repl -c "$TMP" \
  'PS1="❯ " exec bash --noprofile --norc -i'
 sleep 0.3
 out=$("$SEND" -L "$SOCKET" -t "=repl" -m "verdict fixture one delivered ok" 2>"$TMP/e1"); rc=$?
-if [ "$rc" -eq 0 ] && printf '%s' "$out" | grep -qF "✓ delivered"; then
+if [ "$rc" -eq 0 ] && grep -qF "✓ delivered" <<<"$out"; then
  ok "delivered: ❯-prompt REPL that submits => exit 0 ✓ delivered"
 else
  no "delivered: ❯-prompt REPL that submits => exit 0 ✓ delivered" "rc=$rc out=[$out] err=[$(cat "$TMP/e1")]"
@@ -123,7 +123,7 @@ _manifest_val() {
  # _manifest_val KEY — echo VALUE for KEY=VALUE in the manifest (blank if none).
  local key="$1"
  [ -f "$MANIFEST" ] || return 0
-  sed -n "s/^${key}=//p" "$MANIFEST" | head -n1 | tr -d '[:space:]'
+  awk -v key="$key" 'index($0, key "=") == 1 { sub(/^[^=]*=/, ""); gsub(/[[:space:]]/, ""); print; exit }' "$MANIFEST"
 }
 # _load_watchlist — validate the watch-list path + JSON + schema_version range.
@@ -267,7 +267,7 @@ _poll_source() {
    if snap_json="$(jq -ce '.' <<<"$rawmeta" 2>/dev/null)"; then
      snap_sha="$(jq -r 'if (.snapshot_sha|type) == "string" then .snapshot_sha else "" end' <<<"$snap_json")"
      snap_ts="$(jq -r 'if (.snapshot_ts|type) == "number" then (.snapshot_ts|floor|tostring) else "" end' <<<"$snap_json")"
-      if [ -n "$snap_sha" ] && ! printf '%s' "$snap_sha" | grep -Eq '^[0-9a-f]{7,64}$'; then
+      if [ -n "$snap_sha" ] && ! grep -Eq '^[0-9a-f]{7,64}$' <<<"$snap_sha"; then
        echo "detector.sh: source '$kind/$id' snapshot_sha rejected (not a 7-64 char lowercase-hex git sha) — snapshot metadata DROPPED, poll continues (#940)." >&2
        snap_sha=""
        snap_ts=""
@@ -275,7 +275,7 @@ _poll_source() {
      # A ts must be a sane positive epoch BEFORE any arithmetic touches it: a
      # negative or absurdly large value would make the shell integer comparison
      # below error out and silently KEEP the bad ts — validate first, compare after.
-      if [ -n "$snap_ts" ] && ! printf '%s' "$snap_ts" | grep -Eq '^[0-9]{1,12}$'; then
+      if [ -n "$snap_ts" ] && ! grep -Eq '^[0-9]{1,12}$' <<<"$snap_ts"; then
        echo "detector.sh: source '$kind/$id' snapshot_ts rejected (not a sane positive epoch) — snapshot_ts DROPPED, poll continues (#940)." >&2
        snap_ts=""
      fi
@@ -644,7 +644,8 @@ cmd_render() {
        oseq="$(jq -r '.observed_seq // "?"' <<<"$line")"
        oclass="$(jq -r '.class // "actionable"' <<<"$line")"
        oloc="$(jq -c '.locators // {}' <<<"$line")"
-        olabel="$(_locator_line "$oloc" | head -n1)"
+        olabel="$(_locator_line "$oloc")"
        olabel="${olabel%%$'\n'*}"
        printf '  * seq %s [%s] %s\n' "$oseq" "$(_scrub_inline "$oclass")" "$olabel"
      done <<<"$pending"
    fi
@@ -146,7 +146,7 @@ EOF
 _manifest_val() {
  local key="$1"
  [ -f "$MANIFEST" ] || return 0
-  sed -n "s/^${key}=//p" "$MANIFEST" | head -n1 | tr -d '[:space:]'
+  awk -v key="$key" 'index($0, key "=") == 1 { sub(/^[^=]*=/, ""); gsub(/[[:space:]]/, ""); print; exit }' "$MANIFEST"
 }
 # _load_watchlist — validate path + JSON + shape + Gate B schema range (mirrors
@@ -564,7 +564,7 @@ echo "== Q16 (guard): Q2's ENUM-B fixture must STAY address-free — the reconci
  # Token concatenated so THIS guard's own source lines never contain the
  # literal fixture id and cannot self-match.
  enum_id='ENUM''-B'
-  fixture_line="$(has_match -F "\"id\":\"$enum_id\"" "$self" | has_match -F '"observed_seq":5' | head -n1)"
+  fixture_lines="$(has_match -F "\"id\":\"$enum_id\"" "$self")"; fixture_matches="$(has_match -F '"observed_seq":5' <<<"$fixture_lines")"; fixture_line="${fixture_matches%%$'\n'*}"
  [ -n "$fixture_line" ] || fail_msg "Q16: could not locate Q2's $enum_id fixture line (renamed/renumbered? update this guard)"
  fixture_json="$(printf '%s' "$fixture_line" | sed "s/.*'\({.*}\)'.*/\1/")"
  # Positive controls FIRST (blind-instrument rule): the extraction must yield
@@ -179,8 +179,8 @@ echo "== P3: detector orders the cause line BEFORE the delta it explains =="
  printf 'r1 state v2\n' >"$fx/repo_r1"
  "$DET" poll-once >/dev/null 2>&1 || fail_msg "P3: second poll failed"
  sd="$(state_dir)"
-  pre_seq="$(jq -r 'select(.locators.kind == "preimage") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  pre_seq="$(jq -nr 'first(inputs | select(.locators.kind == "preimage") | .observed_seq) // empty' "$sd/pending.jsonl")"
-  src_seq="$(jq -r 'select(.locators.kind == "repo") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  src_seq="$(jq -nr 'first(inputs | select(.locators.kind == "repo") | .observed_seq) // empty' "$sd/pending.jsonl")"
  [ -n "$pre_seq" ] || fail_msg "P3: no preimage cause entry enqueued"
  [ -n "$src_seq" ] || fail_msg "P3: no source delta entry enqueued"
  if [ -n "$pre_seq" ] && [ -n "$src_seq" ]; then
@@ -343,8 +343,8 @@ echo "== P11: reconcile surfaces the cause line before its enumerations =="
  printf '# adapter changed while detector down\n' >>"$fx/adapter.sh"
  "$RECON" reconcile >/dev/null 2>&1 # rc 1 expected (unaccounted enumerated)
  sd="$(state_dir)"
-  pre_seq="$(jq -r 'select(.locators.kind == "preimage") | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  pre_seq="$(jq -nr 'first(inputs | select(.locators.kind == "preimage") | .observed_seq) // empty' "$sd/pending.jsonl")"
-  enum_seq="$(jq -r 'select(.locators.reconciled == true) | .observed_seq' "$sd/pending.jsonl" | head -n1)"
+  enum_seq="$(jq -nr 'first(inputs | select(.locators.reconciled == true) | .observed_seq) // empty' "$sd/pending.jsonl")"
  [ -n "$pre_seq" ] || fail_msg "P11: reconcile must enqueue the preimage cause line"
  [ -n "$enum_seq" ] || fail_msg "P11: reconcile must still enumerate the unaccounted source"
  if [ -n "$pre_seq" ] && [ -n "$enum_seq" ]; then
@@ -150,7 +150,7 @@ site_line() { # site_line FILE MARKER -> first physical line of that call
  local f="$1" marker="$2" ln
  ln="$(grep -n "# SITE:${marker}\$" "$f" | cut -d: -f1)"
  # continuation marker sits on the tail line; the call starts one line up
-  if ! sed -n "${ln}p" "$f" | grep -Eq 'has_match|count_lines'; then
+  source_line="$(sed -n "${ln}p" "$f")"; if ! grep -Eq 'has_match|count_lines' <<<"$source_line"; then
    ln=$((ln - 1))
  fi
  printf '%s' "$ln"
@@ -167,13 +167,13 @@ rcB=$?
 sort "$LEDGER" >"$TMP/got-c1"
 n_expected="$(grep -c . "$TMP/expected-c1")"
 if [ "$rcA" -eq 0 ] && [ "$rcB" -eq 0 ] &&
-  printf '%s' "$outA" | grep -q 'mini-a: OK' &&
+  grep -q 'mini-a: OK'  <<<"$outA"&&
-  printf '%s' "$outB" | grep -q 'mini-b: OK' &&
+  grep -q 'mini-b: OK'  <<<"$outB"&&
  [ "$n_expected" -gt 1 ] &&
  cmp -s "$TMP/expected-c1" "$TMP/got-c1"; then
  check C1 0 ""
 else
-  check C1 1 "rcA=$rcA rcB=$rcB expected($n_expected)/got diff: $(diff "$TMP/expected-c1" "$TMP/got-c1" 2>&1 | head -n 10 | tr '\n' ' ')"
+  check C1 1 "rcA=$rcA rcB=$rcB expected($n_expected)/got diff: $(diff "$TMP/expected-c1" "$TMP/got-c1" 2>&1 | sed -n '1,10p' | tr '\n' ' ')"
 fi
 # --- C2: early exit -> short ledger, comparison catches it -----------------
@@ -201,12 +201,12 @@ abort_case() { # abort_case NAME MARKER HELPER
    bash "$TMP/mini-a.sh" "$TMP" 2>&1)"
  rc=$?
  if [ "$rc" -ne 0 ] &&
-    ! printf '%s' "$out" | grep -q 'mini-a: OK' &&
+    ! grep -q 'mini-a: OK'  <<<"$out"&&
-    ! printf '%s' "$out" | grep -q 'mini-a: FAILED' &&
+    ! grep -q 'mini-a: FAILED'  <<<"$out"&&
-    printf '%s' "$out" | grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site" &&
+    grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site"  <<<"$out"&&
-    printf '%s' "$out" | grep -q "WAKE-ASSERT ABORT" &&
+    grep -q "WAKE-ASSERT ABORT"  <<<"$out"&&
-    printf '%s' "$out" | grep -q "$site" &&
+    grep -q "$site"  <<<"$out"&&
-    printf '%s' "$out" | grep -q "grep exit 2" &&
+    grep -q "grep exit 2"  <<<"$out"&&
    grep -q "^${helper} ${site}\$" "$ledger"; then
    check "$name" 0 ""
  else
@@ -230,8 +230,8 @@ if [ "$got" = "1" ]; then check C8 0 ""; else check C8 1 "env-prefix did not rea
 out="$(WAKE_ASSERT_FORCE_GREP_ERROR_AT="mini-a.sh:9999" bash "$TMP/mini-a.sh" "$TMP" 2>&1)"
 rc=$?
 if [ "$rc" -eq 0 ] &&
-  printf '%s' "$out" | grep -q 'mini-a: OK' &&
+  grep -q 'mini-a: OK'  <<<"$out"&&
-  ! printf '%s' "$out" | grep -q 'WAKE-ASSERT ARMED'; then
+  ! grep -q 'WAKE-ASSERT ARMED' <<<"$out"; then
  check C9 0 ""
 else
  check C9 1 "rc=$rc out=$(printf '%s' "$out" | tail -n 3 | tr '\n' ' ')"
@@ -248,8 +248,8 @@ chmod +x "$TMP/fake-bash"
 out="$(WAKE_ASSERT_PIN_BASH="$TMP/fake-bash" bash -c '. "$WAKE_COMMON" && wake_assert_init && echo REACHED-PAST-INIT' 2>&1)"
 rc=$?
 if [ "$rc" -ne 0 ] &&
-  ! printf '%s' "$out" | grep -q 'REACHED-PAST-INIT' &&
+  ! grep -q 'REACHED-PAST-INIT'  <<<"$out"&&
-  printf '%s' "$out" | grep -q 'WAKE-ASSERT INIT ABORT: BASH_LINENO convention violated'; then
+  grep -q 'WAKE-ASSERT INIT ABORT: BASH_LINENO convention violated' <<<"$out"; then
  check C10 0 ""
 else
  check C10 1 "rc=$rc out=$(printf '%s' "$out" | tail -n 2 | tr '\n' ' ')"
@@ -283,8 +283,8 @@ out="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$TMP/mini-c.sh" "$TMP" 2>&1)"
 rc=$?
 summary_ln="$(site_line "$TMP/mini-c.sh" c-summary)"
 if [ "$rc" -eq 1 ] &&
-  printf '%s' "$out" | grep -q 'wake mini-c harness: FAILED (1 assertion(s))' &&
+  grep -q 'wake mini-c harness: FAILED (1 assertion(s))'  <<<"$out"&&
-  ! printf '%s' "$out" | grep -q 'all invariants passed' &&
+  ! grep -q 'all invariants passed'  <<<"$out"&&
  grep -q "^count_lines mini-c.sh:${summary_ln}\$" "$LEDGER"; then
  check C11 0 ""
 else
@@ -107,7 +107,7 @@ if cmp -s "$TMP/expected.txt" "$TMP/static.txt"; then
  echo "STATIC-INVENTORY equals expected set ($(grep -c . "$TMP/static.txt") rows from source text)"
 else
  flag "static inventory (source text) differs from expected set (artifact):"
-  diff "$TMP/expected.txt" "$TMP/static.txt" | head -n 20 | sed 's/^/  /'
+  diff "$TMP/expected.txt" "$TMP/static.txt" | sed -n '1,20p' | sed 's/^/  /'
 fi
 # --- 3: green instrumented run ----------------------------------------------
@@ -116,7 +116,7 @@ LEDGER="$TMP/ledger"
 for s in "${SUITES[@]}"; do
  out="$(WAKE_ASSERT_LEDGER="$LEDGER" bash "$WAKE/$s" 2>&1)"
  rc=$?
-  if printf '%s\n' "$out" | grep -Eq "$(sentinel_for "$s")"; then
+  if grep -Eq "$(sentinel_for "$s")" <<<"$out"; then
    sent="present"
  else
    sent="ABSENT"
@@ -177,14 +177,14 @@ while read -r helper site form; do
  rc=$?
  bad=""
  [ "$rc" -ne 0 ] || bad="$bad exit=0"
-  printf '%s\n' "$out" | grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site" ||
+  grep -q "WAKE-ASSERT ARMED: forcing real grep error at $site"  <<<"$out"||
    bad="$bad no-ARMED-line"
-  printf '%s\n' "$out" | grep -q "WAKE-ASSERT ABORT: ${helper} at ${site}: grep exit" ||
+  grep -q "WAKE-ASSERT ABORT: ${helper} at ${site}: grep exit"  <<<"$out"||
    bad="$bad no-ABORT-line"
  # AND-polarity check (a match is the defect): a grep error (rc>=2) must be
  # its own loud arm — it cannot fall through as "no sentinel = pass".
  rc_sent=0
-  printf '%s\n' "$out" | grep -Eq "$(sentinel_for "$f")" || rc_sent=$?
+  grep -Eq "$(sentinel_for "$f")"  <<<"$out"|| rc_sent=$?
  case "$rc_sent" in
  0) bad="$bad sentinel-emitted" ;;
  1) : ;;
@@ -25,7 +25,7 @@
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
    "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/systemd/user/test-fleet-units.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/git/test-explain-diagnostic-status-neutral.sh && bash framework/tools/git/test-detect-platform-outside-repo.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -131,13 +131,14 @@ async function exists(path: string): Promise<boolean> {
 }
 describe('projectRosterV2AgentGeneratedEnv', (): void => {
-  it('maps a roster-v2 agent to exactly the eight generated projection keys', (): void => {
+  it('maps a roster-v2 agent to exactly the nine generated projection keys', (): void => {
    const roster = parseRosterV2(rosterYaml, 'yaml');
    const agent = roster.agents.find((candidate) => candidate.name === 'coder0');
    expect(agent).toBeDefined();
    const values = projectRosterV2AgentGeneratedEnv(roster, agent!);
    expect(values).toEqual({
      MOSAIC_AGENT_NAME: 'coder0',
      MOSAIC_GIT_IDENTITY: 'coder0',
      MOSAIC_AGENT_CLASS: 'code',
      MOSAIC_AGENT_RUNTIME: 'pi',
      MOSAIC_AGENT_MODEL: 'gpt-5.6-sol',
@@ -422,6 +422,7 @@ describe('fleet roster parsing', () => {
    expect(generateAgentEnv(roster, getRosterAgent(roster, 'coder0'))).toBe(
      [
        'MOSAIC_AGENT_NAME=coder0',
        'MOSAIC_GIT_IDENTITY=coder0',
        // Reflects the roster's canonicalized compatibility class (A3a).
        'MOSAIC_AGENT_CLASS=code',
        'MOSAIC_AGENT_RUNTIME=codex',
@@ -3799,6 +3800,7 @@ describe('fleet add command', () => {
      'utf8',
    );
    expect(envContent).toContain('MOSAIC_AGENT_NAME=coder0');
    expect(envContent).toContain('MOSAIC_GIT_IDENTITY=coder0');
    expect(envContent).toContain('MOSAIC_AGENT_RUNTIME=codex');
  });
@@ -484,6 +484,7 @@ function generateAgentEnvValues(
  const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
  return {
    MOSAIC_AGENT_NAME: agent.name,
    MOSAIC_GIT_IDENTITY: agent.name,
    MOSAIC_AGENT_CLASS: agent.className,
    MOSAIC_AGENT_RUNTIME: agent.runtime,
    MOSAIC_AGENT_MODEL: agent.modelHint ?? '',
@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
  buildPiSkillArgs,
  discoverPiExtensionArgs,
  enumerateSkillDirs,
  piForceSkillNames,
  registerRuntimeLaunchers,
@@ -178,6 +179,52 @@ describe('buildPiSkillArgs', () => {
  });
 });
 describe('discoverPiExtensionArgs', () => {
  it('loads the core and goal extensions in deterministic order from Mosaic home', () => {
    const root = mkdtempSync(join(tmpdir(), 'mosaic-pi-extensions-'));
    const runtimeDir = join(root, 'runtime', 'pi');
    mkdirSync(runtimeDir, { recursive: true });
    writeFileSync(join(runtimeDir, 'goal-extension.ts'), '// goal\n');
    writeFileSync(join(runtimeDir, 'mosaic-extension.ts'), '// core\n');
    try {
      expect(discoverPiExtensionArgs(root)).toEqual([
        '--extension',
        join(runtimeDir, 'mosaic-extension.ts'),
        '--extension',
        join(runtimeDir, 'goal-extension.ts'),
      ]);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });
  it('remains backward-compatible when the optional goal extension is absent', () => {
    const root = mkdtempSync(join(tmpdir(), 'mosaic-pi-extensions-'));
    const runtimeDir = join(root, 'runtime', 'pi');
    mkdirSync(runtimeDir, { recursive: true });
    writeFileSync(join(runtimeDir, 'mosaic-extension.ts'), '// core\n');
    try {
      expect(discoverPiExtensionArgs(root)).toEqual([
        '--extension',
        join(runtimeDir, 'mosaic-extension.ts'),
      ]);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });
  it('emits no extension arguments when Mosaic runtime assets are absent', () => {
    const root = mkdtempSync(join(tmpdir(), 'mosaic-pi-extensions-'));
    try {
      expect(discoverPiExtensionArgs(root)).toEqual([]);
    } finally {
      rmSync(root, { recursive: true, force: true });
    }
  });
 });
 describe('enumerateSkillDirs (real FS)', () => {
  let root: string;
@@ -715,9 +715,15 @@ export function buildPiSkillArgs(
  return ['--no-skills', ...forcedSkillArgs];
 }
-function discoverPiExtension(): string[] {
+const PI_EXTENSION_FILES = ['mosaic-extension.ts', 'goal-extension.ts'] as const;
-  const ext = join(MOSAIC_HOME, 'runtime', 'pi', 'mosaic-extension.ts');
+
-  return existsSync(ext) ? ['--extension', ext] : [];
+export function discoverPiExtensionArgs(mosaicHome: string = MOSAIC_HOME): string[] {
  const args: string[] = [];
  for (const fileName of PI_EXTENSION_FILES) {
    const extensionPath = join(mosaicHome, 'runtime', 'pi', fileName);
    if (existsSync(extensionPath)) args.push('--extension', extensionPath);
  }
  return args;
 }
 // ─── Launch functions ────────────────────────────────────────────────────────
@@ -792,7 +798,7 @@ function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): nev
      const prompt = buildRuntimePrompt('pi');
      const cliArgs = ['--append-system-prompt', prompt];
      cliArgs.push(...buildPiSkillArgs(args));
-      cliArgs.push(...discoverPiExtension());
+      cliArgs.push(...discoverPiExtensionArgs());
      if (hasMissionNoArgs) {
        cliArgs.push(missionPrompt);
      } else {
@@ -209,6 +209,20 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
    );
  });
  it('deploys the Mosaic-owned Pi goal extension only inside the Mosaic runtime tree', async () => {
    const sourceRuntime = join(fixture.sourceDir, 'runtime', 'pi');
    mkdirSync(sourceRuntime, { recursive: true });
    writeFileSync(join(sourceRuntime, 'goal-extension.ts'), '// persistent goal extension\n');
    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
    await adapter.syncFramework('fresh');
    expect(
      readFileSync(join(fixture.mosaicHome, 'runtime', 'pi', 'goal-extension.ts'), 'utf-8'),
    ).toBe('// persistent goal extension\n');
    expect(existsSync(join(fixture.mosaicHome, '.pi'))).toBe(false);
  });
  it('is a no-op for seeding when defaults/ dir does not exist', async () => {
    rmSync(fixture.defaultsDir, { recursive: true });
@@ -358,6 +358,7 @@ function generatedValues(
 ): Readonly<Record<string, string>> {
  return {
    MOSAIC_AGENT_NAME: agent.name,
    MOSAIC_GIT_IDENTITY: agent.name,
    MOSAIC_AGENT_CLASS: agent.className,
    MOSAIC_AGENT_RUNTIME: agent.runtime,
    MOSAIC_AGENT_MODEL: agent.model,
@@ -380,7 +380,7 @@ const COMMAND_RECORDS: Readonly<Record<string, RegExp>> = {
 const DATA_PROFILE_BODIES: Readonly<Record<string, string>> = {
  'DATA.DOTENV.FLEET_LAUNCH':
-    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
+    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_GIT_IDENTITY=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
  'DATA.TEXT_TABLE.FLEET_TASKS':
    '| W-FLEET | in-progress | Fleet (agent-session execution layer) | Phase 2/5 | docs/fleet/TASKS.md | observability dogfooded on live stub fleet; control plane rides federation (W1) |',
  'DATA.TEXT_DIAGRAM.BACKLOG_FLOW':
@@ -406,7 +406,7 @@ const DATA_PROFILE_BODIES: Readonly<Record<string, string>> = {
  'DATA.JSON.MUTATION_RESULT':
    '{\n  "applied": false,\n  "authoritativeRoster": "committed",\n  "projections": "incomplete",\n  "recovery": {\n    "code": "projection-apply-failed",\n    "action": "regenerate-projections-from-roster"\n  }\n}',
  'DATA.DOTENV.GENERATED_ENV':
-    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
+    'MOSAIC_AGENT_NAME=<roster name>\nMOSAIC_GIT_IDENTITY=<roster name>\nMOSAIC_AGENT_CLASS=<roster class>\nMOSAIC_AGENT_RUNTIME=<roster runtime>\nMOSAIC_AGENT_MODEL=<roster model hint>\nMOSAIC_AGENT_REASONING=<roster reasoning>\nMOSAIC_AGENT_TOOL_POLICY=<roster tool policy>\nMOSAIC_AGENT_WORKDIR=<absolute roster work directory>\nMOSAIC_TMUX_SOCKET=<roster socket or empty>',
  'DATA.YAML.ROSTER_FIELDS':
    'version: 2\ngeneration: 1\ntransport: tmux\ntmux:\n  socket_name: mosaic-fleet\n  holder_session: _holder\ndefaults:\n  working_directory: ~/src\n  runtime: pi\nruntimes:\n  pi:\n    reset_command: /new\nagents:\n  - name: coder0\n    alias: Coder 0\n    class: code\n    runtime: pi\n    provider: openai\n    model: gpt-5.6-sol\n    reasoning: high\n    tool_policy: code\n    working_directory: ~/src\n    persistent_persona: false\n    reset_between_tasks: true\n    lifecycle:\n      enabled: true\n      desired_state: stopped\n    launch:\n      yolo: true',
 };
@@ -922,8 +922,8 @@ describe('fleet operator documentation', (): void => {
    );
    expect(
      surfaces.filter((surface): boolean => surface.category === 'InlineLiteral'),
-    ).toHaveLength(858);
+    ).toHaveLength(863);
-    expect(surfaces).toHaveLength(882);
+    expect(surfaces).toHaveLength(887);
    const rosterSource = await readFile(join(fleetDocs, 'examples', 'roster-v2.yaml'), 'utf8');
    const auxiliary: CodeSurface = {
@@ -597,6 +597,7 @@ export function projectRosterV2AgentGeneratedEnv(
 ): Readonly<Record<string, string>> {
  return {
    MOSAIC_AGENT_NAME: agent.name,
    MOSAIC_GIT_IDENTITY: agent.name,
    MOSAIC_AGENT_CLASS: agent.className,
    MOSAIC_AGENT_RUNTIME: agent.runtime,
    MOSAIC_AGENT_MODEL: agent.model,
@@ -22,6 +22,7 @@ import {
 const generatedValues = {
  MOSAIC_AGENT_NAME: 'coder0',
  MOSAIC_GIT_IDENTITY: 'coder0',
  MOSAIC_AGENT_CLASS: 'code',
  MOSAIC_AGENT_RUNTIME: 'pi',
  MOSAIC_AGENT_MODEL: 'openai-codex/gpt-5.6-sol',
@@ -45,6 +46,7 @@ describe('generated fleet agent environment boundary', (): void => {
    expect(renderGeneratedAgentEnvironment(generatedValues)).toBe(
      [
        'MOSAIC_AGENT_NAME=coder0',
        'MOSAIC_GIT_IDENTITY=coder0',
        'MOSAIC_AGENT_CLASS=code',
        'MOSAIC_AGENT_RUNTIME=pi',
        'MOSAIC_AGENT_MODEL=openai-codex/gpt-5.6-sol',
@@ -78,6 +80,22 @@ describe('generated fleet agent environment boundary', (): void => {
    expect(String(error)).toMatch(/key=.*sha256=/);
  });
  it.each([
    ['unsafe-git-identity', 'other/identity'],
    ['git-identity-mismatch', 'reviewer0'],
  ])('rejects %s before any launch consumer can use it', (code: string, identity: string): void => {
    expect((): void => {
      renderGeneratedAgentEnvironment({
        ...generatedValues,
        MOSAIC_GIT_IDENTITY: identity,
      });
    }).toThrow(
      expect.objectContaining({
        diagnostic: expect.objectContaining({ code, key: 'MOSAIC_GIT_IDENTITY' }),
      }),
    );
  });
  it('rejects unsafe generated paths before any launch consumer can use them', (): void => {
    expect((): void => {
      renderGeneratedAgentEnvironment({
@@ -73,6 +73,7 @@ export class AgentEnvBoundaryError extends Error {
 export const GENERATED_AGENT_ENV_KEYS = [
  'MOSAIC_AGENT_NAME',
  'MOSAIC_GIT_IDENTITY',
  'MOSAIC_AGENT_CLASS',
  'MOSAIC_AGENT_RUNTIME',
  'MOSAIC_AGENT_MODEL',
@@ -402,6 +403,7 @@ function assertGeneratedValues(values: Readonly<Record<string, string>>): void {
    if (value === undefined) throw new AgentEnvBoundaryError('missing-key', key, '');
  }
  const name = requiredGeneratedValue(values, 'MOSAIC_AGENT_NAME');
  const gitIdentity = requiredGeneratedValue(values, 'MOSAIC_GIT_IDENTITY');
  const className = requiredGeneratedValue(values, 'MOSAIC_AGENT_CLASS');
  const runtime = requiredGeneratedValue(values, 'MOSAIC_AGENT_RUNTIME');
  const model = requiredGeneratedValue(values, 'MOSAIC_AGENT_MODEL');
@@ -412,6 +414,12 @@ function assertGeneratedValues(values: Readonly<Record<string, string>>): void {
  if (!AGENT_NAME.test(name))
    throw new AgentEnvBoundaryError('unsafe-agent-name', 'MOSAIC_AGENT_NAME', name);
  if (!AGENT_NAME.test(gitIdentity)) {
    throw new AgentEnvBoundaryError('unsafe-git-identity', 'MOSAIC_GIT_IDENTITY', gitIdentity);
  }
  if (gitIdentity !== name) {
    throw new AgentEnvBoundaryError('git-identity-mismatch', 'MOSAIC_GIT_IDENTITY', gitIdentity);
  }
  if (!POLICY_NAME.test(className)) {
    throw new AgentEnvBoundaryError('unsafe-class', 'MOSAIC_AGENT_CLASS', className);
  }
@@ -1405,6 +1405,7 @@ function generatedValues(
 ): Readonly<Record<string, string>> {
  return {
    MOSAIC_AGENT_NAME: agent.name,
    MOSAIC_GIT_IDENTITY: agent.name,
    MOSAIC_AGENT_CLASS: agent.className,
    MOSAIC_AGENT_RUNTIME: agent.runtime,
    MOSAIC_AGENT_MODEL: agent.model,
@@ -0,0 +1,796 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 interface FakeEntry {
  type: string;
  customType?: string;
  data?: unknown;
 }
 interface SentMessage {
  message: {
    customType: string;
    content: string;
    display: boolean;
  };
  options?: {
    triggerTurn?: boolean;
    deliverAs?: 'steer' | 'followUp' | 'nextTurn';
  };
 }
 interface FakeContext {
  cwd: string;
  ui: {
    notifications: Array<{ message: string; level?: string }>;
    statuses: Map<string, string | undefined>;
    notify(message: string, level?: string): void;
    setStatus(key: string, value: string | undefined): void;
  };
  sessionManager: {
    getBranch(): FakeEntry[];
  };
  isIdle(): boolean;
  hasPendingMessages(): boolean;
  abort(): void;
 }
 type EventHandler = (
  event: Record<string, unknown>,
  context: FakeContext,
 ) => unknown | Promise<unknown>;
 type CommandHandler = (args: string, context: FakeContext) => unknown | Promise<unknown>;
 interface FakeToolResult {
  content: Array<{ type: string; text: string }>;
  details?: unknown;
  terminate?: boolean;
 }
 interface FakeTool {
  name: string;
  execute(
    toolCallId: string,
    params: Record<string, unknown>,
    signal: AbortSignal | undefined,
    onUpdate: undefined,
    context: FakeContext,
  ): Promise<FakeToolResult>;
 }
 interface GoalExtensionFactory {
  (api: FakePiApi): void;
 }
 interface GoalExtensionModule {
  default: GoalExtensionFactory;
 }
 interface FakePiApi {
  on(event: string, handler: EventHandler): void;
  registerCommand(name: string, options: { description: string; handler: CommandHandler }): void;
  registerTool(tool: FakeTool): void;
  appendEntry(customType: string, data?: unknown): void;
  sendMessage(message: SentMessage['message'], options?: SentMessage['options']): void;
 }
 function isGoalExtensionModule(value: unknown): value is GoalExtensionModule {
  if (typeof value !== 'object' || value === null) return false;
  return typeof Reflect.get(value, 'default') === 'function';
 }
 const goalExtensionUrl = new URL('../../framework/runtime/pi/goal-extension.ts', import.meta.url)
  .href;
 const importedGoalExtension: unknown = await import(goalExtensionUrl);
 if (!isGoalExtensionModule(importedGoalExtension)) {
  throw new Error('Pi goal extension must export a default registration function');
 }
 const registerGoalExtension = importedGoalExtension.default;
 function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 class FakePi {
  readonly handlers = new Map<string, EventHandler[]>();
  readonly commands = new Map<string, CommandHandler>();
  readonly tools = new Map<string, FakeTool>();
  readonly entries: FakeEntry[] = [];
  readonly sentMessages: SentMessage[] = [];
  readonly notifications: Array<{ message: string; level?: string }> = [];
  readonly statuses = new Map<string, string | undefined>();
  branch: FakeEntry[] = [];
  idle = true;
  pending = false;
  abortCount = 0;
  readonly context: FakeContext = {
    cwd: '/tmp/project',
    ui: {
      notifications: this.notifications,
      statuses: this.statuses,
      notify: (message: string, level?: string): void => {
        this.notifications.push({ message, level });
      },
      setStatus: (key: string, value: string | undefined): void => {
        this.statuses.set(key, value);
      },
    },
    sessionManager: {
      getBranch: (): FakeEntry[] => [...this.branch],
    },
    isIdle: (): boolean => this.idle,
    hasPendingMessages: (): boolean => this.pending,
    abort: (): void => {
      this.abortCount += 1;
    },
  };
  readonly api: FakePiApi = {
    on: (event: string, handler: EventHandler): void => {
      this.handlers.set(event, [...(this.handlers.get(event) ?? []), handler]);
    },
    registerCommand: (
      name: string,
      options: { description: string; handler: CommandHandler },
    ): void => {
      this.commands.set(name, options.handler);
    },
    registerTool: (tool: FakeTool): void => {
      this.tools.set(tool.name, tool);
    },
    appendEntry: (customType: string, data?: unknown): void => {
      const entry: FakeEntry = { type: 'custom', customType, data };
      this.entries.push(entry);
      this.branch.push(entry);
    },
    sendMessage: (message: SentMessage['message'], options?: SentMessage['options']): void => {
      this.sentMessages.push({ message, options });
    },
  };
  constructor(initialBranch: FakeEntry[] = []) {
    this.branch = [...initialBranch];
    registerGoalExtension(this.api);
  }
  async emit(event: string, value: Record<string, unknown> = {}): Promise<unknown[]> {
    const results: unknown[] = [];
    for (const handler of this.handlers.get(event) ?? []) {
      results.push(await handler(value, this.context));
    }
    return results;
  }
  async goal(args: string): Promise<void> {
    const handler = this.commands.get('goal');
    if (handler === undefined) throw new Error('/goal was not registered');
    await handler(args, this.context);
  }
  async report(params: Record<string, unknown>): Promise<FakeToolResult> {
    const tool = this.tools.get('mosaic_goal_report');
    if (tool === undefined) throw new Error('mosaic_goal_report was not registered');
    return await tool.execute('goal-report-1', params, undefined, undefined, this.context);
  }
 }
 function latestGoalStateData(pi: FakePi): Record<string, unknown> {
  for (let index = pi.entries.length - 1; index >= 0; index -= 1) {
    const entry = pi.entries[index];
    if (entry?.customType === 'mosaic-goal-state' && isRecord(entry.data)) return entry.data;
  }
  throw new Error('No persisted Mosaic goal state found');
 }
 function stateField(pi: FakePi, field: string): unknown {
  return latestGoalStateData(pi)[field];
 }
 function activeGoalStatementFromContext(result: unknown): string {
  if (!isRecord(result)) throw new Error('Context handler did not return an object');
  const messages = result['messages'];
  if (!Array.isArray(messages)) throw new Error('Context result did not include messages');
  const goalMessage = messages.find(
    (message: unknown): boolean =>
      isRecord(message) && message['customType'] === 'mosaic-goal-context',
  );
  if (!isRecord(goalMessage) || typeof goalMessage['content'] !== 'string') {
    throw new Error('Goal context message was not injected');
  }
  return goalMessage['content'];
 }
 afterEach(() => {
  vi.useRealTimers();
  vi.unstubAllEnvs();
 });
 describe('Mosaic Pi goal extension commands', () => {
  it('shows help and handles controls safely when no goal exists', async () => {
    const pi = new FakePi();
    await pi.goal('');
    expect(pi.notifications.at(-1)?.message).toContain('/goal set');
    await pi.goal('status');
    expect(pi.notifications.at(-1)?.message).toContain('No Mosaic goal is set');
    for (const command of ['pause', 'resume', 'cancel']) {
      await pi.goal(command);
      expect(pi.notifications.at(-1)?.level).toBe('warning');
    }
    expect(pi.entries).toHaveLength(0);
    expect(pi.sentMessages).toHaveLength(0);
  });
  it('sets, reports, pauses, resumes, and cancels a bounded goal', async () => {
    const pi = new FakePi();
    await pi.goal('set Deliver the local goal extension with tests');
    expect(stateField(pi, 'phase')).toBe('active');
    expect(stateField(pi, 'statement')).toBe('Deliver the local goal extension with tests');
    expect(pi.sentMessages).toHaveLength(1);
    expect(pi.sentMessages[0]?.options?.triggerTurn).toBe(true);
    await pi.goal('status');
    expect(pi.notifications.at(-1)?.message).toContain('Deliver the local goal extension');
    expect(pi.notifications.at(-1)?.message).toContain('active');
    await pi.goal('pause');
    expect(stateField(pi, 'phase')).toBe('paused');
    pi.sentMessages.length = 0;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
    await pi.goal('resume');
    expect(stateField(pi, 'phase')).toBe('active');
    expect(pi.sentMessages).toHaveLength(1);
    await pi.goal('cancel');
    expect(stateField(pi, 'phase')).toBe('cancelled');
    pi.sentMessages.length = 0;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
  });
  it('accepts /goal <statement> shorthand but refuses to replace an active goal', async () => {
    const pi = new FakePi();
    await pi.goal('First goal');
    const firstGoalId = stateField(pi, 'goalId');
    await pi.goal('set Second goal');
    expect(stateField(pi, 'goalId')).toBe(firstGoalId);
    expect(stateField(pi, 'statement')).toBe('First goal');
    expect(pi.notifications.at(-1)?.level).toBe('warning');
    expect(pi.notifications.at(-1)?.message).toContain('/goal cancel');
  });
  it('rejects invalid phase transitions, aborts busy work, and supports clear as cancel', async () => {
    const pi = new FakePi();
    await pi.goal('set Preserve transition safety');
    await pi.goal('resume');
    expect(pi.notifications.at(-1)?.message).toContain('cannot be resumed');
    pi.idle = false;
    await pi.goal('pause maintenance window');
    expect(stateField(pi, 'stopReason')).toBe('maintenance window');
    expect(pi.abortCount).toBe(1);
    await pi.goal('pause');
    expect(pi.notifications.at(-1)?.message).toContain('cannot be paused');
    await pi.goal('clear');
    expect(stateField(pi, 'phase')).toBe('cancelled');
    expect(pi.abortCount).toBe(2);
  });
  it('rejects empty and oversized goal statements without starting a run', async () => {
    const pi = new FakePi();
    await pi.goal('set');
    await pi.goal(`set ${'x'.repeat(8_001)}`);
    expect(pi.entries).toHaveLength(0);
    expect(pi.sentMessages).toHaveLength(0);
    expect(pi.notifications.at(-1)?.level).toBe('warning');
  });
 });
 describe('Mosaic Pi goal lifecycle', () => {
  it('injects one fresh active contract before every model context', async () => {
    const pi = new FakePi();
    await pi.goal('set Keep the agent oriented');
    const existingGoalContext = {
      role: 'custom',
      customType: 'mosaic-goal-context',
      content: 'stale',
    };
    const existingContinuation = {
      role: 'custom',
      customType: 'mosaic-goal-continuation',
      content: 'stale continuation',
    };
    const first = await pi.emit('context', {
      messages: [existingGoalContext, existingContinuation],
    });
    const second = await pi.emit('context', { messages: [] });
    expect(activeGoalStatementFromContext(first[0])).toContain('Keep the agent oriented');
    expect(activeGoalStatementFromContext(first[0])).toContain('mosaic_goal_report');
    expect(activeGoalStatementFromContext(first[0])).not.toContain('stale');
    if (!isRecord(first[0]) || !Array.isArray(first[0]['messages'])) {
      throw new Error('Expected filtered context messages');
    }
    expect(first[0]['messages']).toHaveLength(1);
    expect(activeGoalStatementFromContext(second[0])).toContain('Keep the agent oriented');
    await pi.goal('cancel');
    expect(
      await pi.emit('context', {
        messages: [existingGoalContext, existingContinuation],
      }),
    ).toEqual([{ messages: [] }]);
  });
  it('lets an existing busy run adopt the goal and waits behind a pending message', async () => {
    const busy = new FakePi();
    busy.idle = false;
    await busy.goal('set Join the current run safely');
    expect(busy.sentMessages).toHaveLength(0);
    busy.pending = true;
    await busy.emit('agent_settled');
    expect(busy.sentMessages).toHaveLength(0);
    busy.pending = false;
    busy.idle = true;
    await busy.emit('agent_settled');
    expect(busy.sentMessages).toHaveLength(1);
  });
  it('records every turn and continues once when an active run settles', async () => {
    const pi = new FakePi();
    await pi.goal('set Finish all acceptance criteria');
    pi.sentMessages.length = 0;
    await pi.emit('turn_end', { turnIndex: 0, message: {}, toolResults: [] });
    expect(stateField(pi, 'turnCount')).toBe(1);
    expect(stateField(pi, 'lastCheckSource')).toBe('turn');
    await pi.emit('agent_settled');
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(1);
    expect(pi.sentMessages[0]?.message.content).toContain('Goal remains active');
    await pi.emit('agent_start');
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(2);
  });
  it('requires two consecutive evidence-bearing achievement reports', async () => {
    const pi = new FakePi();
    await pi.goal('set Prove the feature works');
    pi.sentMessages.length = 0;
    const first = await pi.report({
      status: 'achieved',
      summary: 'Focused tests pass',
      evidence: ['pnpm test: 12 passed'],
    });
    expect(first.terminate).toBe(true);
    expect(stateField(pi, 'phase')).toBe('verifying');
    expect(stateField(pi, 'verificationPasses')).toBe(1);
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(1);
    expect(pi.sentMessages[0]?.message.content).toContain('verification pass');
    await pi.emit('agent_start');
    const second = await pi.report({
      status: 'achieved',
      summary: 'Independent recheck confirms completion',
      evidence: ['rerun: 12 passed', 'framework path verified'],
    });
    expect(second.terminate).toBe(true);
    expect(stateField(pi, 'phase')).toBe('achieved');
    expect(stateField(pi, 'verificationPasses')).toBe(2);
    pi.sentMessages.length = 0;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
  });
  it('rejects malformed progress reports and reports submitted without an active goal', async () => {
    const noGoal = new FakePi();
    await expect(
      noGoal.report({ status: 'continue', summary: 'work', evidence: [] }),
    ).rejects.toThrow(/No active Mosaic goal/);
    const pi = new FakePi();
    await pi.goal('set Validate report boundaries');
    const invalidReports: Record<string, unknown>[] = [
      {},
      { status: 'invalid', summary: 'work', evidence: [] },
      { status: 'continue', evidence: [] },
      { status: 'continue', summary: '   ', evidence: [] },
      { status: 'continue', summary: 'x'.repeat(2_001), evidence: [] },
      { status: 'continue', summary: 'work', evidence: 'not-an-array' },
      { status: 'continue', summary: 'work', evidence: Array.from({ length: 21 }, () => 'x') },
      { status: 'continue', summary: 'work', evidence: [4] },
      { status: 'continue', summary: 'work', evidence: [''] },
      { status: 'continue', summary: 'work', evidence: ['x'.repeat(1_001)] },
      { status: 'continue', summary: 'work', evidence: [], nextStep: 4 },
      { status: 'continue', summary: 'work', evidence: [], nextStep: '   ' },
      { status: 'continue', summary: 'work', evidence: [], nextStep: 'x'.repeat(2_001) },
    ];
    for (const report of invalidReports) {
      await expect(pi.report(report)).rejects.toThrow();
    }
    expect(stateField(pi, 'phase')).toBe('active');
  });
  it('rejects an achievement claim without evidence', async () => {
    const pi = new FakePi();
    await pi.goal('set Require evidence');
    await expect(
      pi.report({ status: 'achieved', summary: 'Trust me', evidence: [] }),
    ).rejects.toThrow(/evidence/i);
    expect(stateField(pi, 'phase')).toBe('active');
  });
  it('redacts credential-shaped goal and report text before persistence or display', async () => {
    const githubToken = `ghp_${'a'.repeat(32)}`;
    const anthropicKey = `sk-ant-api03-${'b'.repeat(40)}`;
    const bearerToken = 'header.payload.signature-canary';
    const databaseUrl = 'postgresql://mosaic:[email protected]/mosaic';
    const password = 'password-canary';
    const pi = new FakePi();
    await pi.goal(`set Rotate ${githubToken} without retaining it`);
    const context = await pi.emit('context', { messages: [] });
    expect(activeGoalStatementFromContext(context[0])).not.toContain(githubToken);
    const result = await pi.report({
      status: 'achieved',
      summary: `Validated ${anthropicKey}`,
      evidence: [`Authorization: Bearer ${bearerToken}`, `DATABASE_URL=${databaseUrl}`],
      nextStep: `password=${password}`,
    });
    await pi.goal('status');
    const persisted = JSON.stringify(latestGoalStateData(pi));
    const displayed = pi.notifications.at(-1)?.message ?? '';
    const toolOutput = JSON.stringify(result);
    for (const secret of [githubToken, anthropicKey, bearerToken, databaseUrl, password]) {
      expect(persisted).not.toContain(secret);
      expect(displayed).not.toContain(secret);
      expect(toolOutput).not.toContain(secret);
    }
    expect(persisted).toContain('[REDACTED-SECRET]');
  });
  it('preserves ordinary typed fields that resemble sensitive assignment names', async () => {
    const typedFields = 'token: string, password: boolean, secret: false';
    const pi = new FakePi();
    await pi.goal(`set Preserve TypeScript fields: ${typedFields}`);
    await pi.report({
      status: 'continue',
      summary: `Schema still contains ${typedFields}`,
      evidence: [`interface Config { ${typedFields} }`],
      nextStep: `Keep ${typedFields} unchanged`,
    });
    expect(stateField(pi, 'statement')).toContain(typedFields);
    expect(JSON.stringify(stateField(pi, 'lastReport'))).toContain(typedFields);
    expect(JSON.stringify(latestGoalStateData(pi))).not.toContain('[REDACTED-SECRET]');
  });
  it('stops autonomous continuation when the max-turn limit is reached', async () => {
    vi.stubEnv('MOSAIC_GOAL_MAX_TURNS', '2');
    const pi = new FakePi();
    await pi.goal('set Bound this run');
    pi.sentMessages.length = 0;
    await pi.emit('turn_end', { turnIndex: 0, message: {}, toolResults: [] });
    await pi.emit('turn_end', { turnIndex: 1, message: {}, toolResults: [] });
    expect(stateField(pi, 'phase')).toBe('exhausted');
    expect(pi.abortCount).toBe(1);
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
  });
  it('resets the no-progress sequence when a continuation report changes', async () => {
    const pi = new FakePi();
    await pi.goal('set Track changing progress');
    await pi.report({
      status: 'continue',
      summary: 'First checkpoint',
      evidence: ['file A changed'],
      nextStep: 'Run focused tests',
    });
    await pi.report({
      status: 'continue',
      summary: 'Second checkpoint',
      evidence: ['focused tests passed'],
      nextStep: 'Review the diff',
    });
    expect(stateField(pi, 'phase')).toBe('active');
    expect(stateField(pi, 'noProgressReports')).toBe(1);
    await pi.goal('status');
    expect(pi.notifications.at(-1)?.message).toContain('Next step: Review the diff');
    expect(pi.notifications.at(-1)?.message).toContain('focused tests passed');
  });
  it('stops after a bounded number of identical no-progress reports', async () => {
    vi.stubEnv('MOSAIC_GOAL_MAX_NO_PROGRESS', '2');
    const pi = new FakePi();
    await pi.goal('set Detect stalled work');
    const report = {
      status: 'continue',
      summary: 'No change yet',
      evidence: ['same observation'],
      nextStep: 'Try again',
    };
    await pi.report(report);
    await pi.report(report);
    expect(stateField(pi, 'phase')).toBe('exhausted');
    expect(stateField(pi, 'noProgressReports')).toBe(2);
    pi.sentMessages.length = 0;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
  });
  it('rejects a goal report mixed with another tool result in the same turn', async () => {
    const pi = new FakePi();
    await pi.goal('set Require a sole final report');
    await pi.report({
      status: 'achieved',
      summary: 'Premature mixed claim',
      evidence: ['one observation'],
    });
    await pi.emit('turn_end', {
      turnIndex: 0,
      message: {},
      toolResults: [{ toolName: 'mosaic_goal_report' }, { toolName: 'read' }],
    });
    expect(stateField(pi, 'phase')).toBe('active');
    expect(stateField(pi, 'verificationPasses')).toBe(0);
    expect(stateField(pi, 'lastCheckOutcome')).toBe('mixed-goal-report-rejected');
    expect(pi.notifications.at(-1)?.level).toBe('warning');
  });
  it('marks blocked reports terminal until the operator resumes', async () => {
    const pi = new FakePi();
    await pi.goal('set Stop on a real blocker');
    await pi.report({
      status: 'blocked',
      summary: 'Missing required access',
      evidence: ['provider returned 403'],
    });
    expect(stateField(pi, 'phase')).toBe('blocked');
    pi.sentMessages.length = 0;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(0);
    await pi.goal('resume');
    expect(stateField(pi, 'phase')).toBe('active');
    expect(stateField(pi, 'turnCount')).toBe(0);
    expect(pi.sentMessages).toHaveLength(1);
  });
 });
 describe('Mosaic Pi goal compaction and restoration', () => {
  it('resets provisional verification and defers manual-compaction continuation until idle', async () => {
    vi.useFakeTimers();
    const pi = new FakePi();
    await pi.goal('set Survive compaction');
    await pi.report({
      status: 'achieved',
      summary: 'Initial claim',
      evidence: ['focused test passed'],
    });
    expect(stateField(pi, 'phase')).toBe('verifying');
    pi.sentMessages.length = 0;
    await pi.emit('session_compact', { reason: 'manual', willRetry: false });
    expect(stateField(pi, 'phase')).toBe('active');
    expect(stateField(pi, 'verificationPasses')).toBe(0);
    expect(stateField(pi, 'compactionCount')).toBe(1);
    expect(stateField(pi, 'lastCheckSource')).toBe('compact');
    expect(pi.sentMessages).toHaveLength(0);
    await vi.runAllTimersAsync();
    expect(pi.sentMessages).toHaveLength(1);
    expect(pi.sentMessages[0]?.message.content).toContain('compaction');
  });
  it('does not re-enter an active automatic compaction and relies on the settled backstop', async () => {
    vi.useFakeTimers();
    const pi = new FakePi();
    await pi.goal('set Avoid compaction races');
    pi.sentMessages.length = 0;
    pi.idle = false;
    await pi.emit('session_compact', { reason: 'threshold', willRetry: false });
    await vi.runAllTimersAsync();
    expect(pi.sentMessages).toHaveLength(0);
    pi.idle = true;
    await pi.emit('agent_settled');
    expect(pi.sentMessages).toHaveLength(1);
  });
  it('restores branch-specific state on session start and tree navigation', async () => {
    vi.useFakeTimers();
    const source = new FakePi();
    await source.goal('set Restore this exact branch goal');
    const activeState = latestGoalStateData(source);
    const restored = new FakePi([
      { type: 'custom', customType: 'mosaic-goal-state', data: activeState },
    ]);
    await restored.emit('session_start', { reason: 'resume' });
    expect(restored.statuses.get('mosaic-goal')).toContain('active');
    const context = await restored.emit('context', { messages: [] });
    expect(activeGoalStatementFromContext(context[0])).toContain('Restore this exact branch goal');
    await restored.goal('pause');
    const pausedState = latestGoalStateData(restored);
    restored.branch = [{ type: 'custom', customType: 'mosaic-goal-state', data: pausedState }];
    await restored.emit('session_tree', {});
    await vi.runAllTimersAsync();
    expect(stateField(restored, 'phase')).toBe('paused');
    expect(restored.sentMessages).toHaveLength(0);
  });
  it('restores only fully valid persisted states and ignores malformed entries', async () => {
    vi.useFakeTimers();
    const source = new FakePi();
    await source.goal('set Validate persisted branch state');
    await source.report({
      status: 'continue',
      summary: 'Valid report',
      evidence: ['valid evidence'],
      nextStep: 'Continue validation',
    });
    const valid = latestGoalStateData(source);
    const validRestore = new FakePi([
      { type: 'custom', customType: 'mosaic-goal-state', data: valid },
    ]);
    await validRestore.emit('session_start', { reason: 'resume' });
    expect(stateField(validRestore, 'statement')).toBe('Validate persisted branch state');
    await validRestore.emit('session_shutdown', { reason: 'reload' });
    const validReport = latestGoalStateData(source)['lastReport'];
    if (!isRecord(validReport)) throw new Error('Expected a valid persisted report fixture');
    const integerFields = [
      'turnCount',
      'reportCount',
      'verificationPasses',
      'requiredVerificationPasses',
      'noProgressReports',
      'maxTurns',
      'maxNoProgressReports',
      'compactionCount',
    ];
    const corruptions: Array<(state: Record<string, unknown>) => unknown> = [
      (): unknown => null,
      (state): unknown => ({ ...state, version: 99 }),
      (state): unknown => ({ ...state, goalId: '' }),
      (state): unknown => ({ ...state, statement: '' }),
      (state): unknown => ({ ...state, statement: 'x'.repeat(8_001) }),
      (state): unknown => ({ ...state, phase: 'unknown' }),
      (state): unknown => ({ ...state, lastCheckSource: 'unknown' }),
      (state): unknown => ({ ...state, startedAt: 4 }),
      (state): unknown => ({ ...state, lastCheckAt: 4 }),
      (state): unknown => ({ ...state, lastReport: null }),
      (state): unknown => ({ ...state, lastProgressFingerprint: 4 }),
      (state): unknown => ({ ...state, stopReason: 4 }),
      ...integerFields.map((field: string) => (state: Record<string, unknown>): unknown => ({
        ...state,
        [field]: -1,
      })),
    ];
    corruptions.push(
      (state: Record<string, unknown>): unknown => ({ ...state, maxTurns: 501 }),
      (state: Record<string, unknown>): unknown => ({ ...state, maxNoProgressReports: 101 }),
      (state: Record<string, unknown>): unknown => ({ ...state, requiredVerificationPasses: 3 }),
    );
    const reportCorruptions: Array<Record<string, unknown>> = [
      { ...validReport, status: 'bad' },
      { ...validReport, summary: '' },
      { ...validReport, evidence: 'bad' },
      { ...validReport, evidence: [4] },
      { ...validReport, fingerprint: '' },
      { ...validReport, reportedAt: '' },
      { ...validReport, nextStep: 4 },
    ];
    for (const corruptReport of reportCorruptions) {
      corruptions.push((state: Record<string, unknown>): unknown => ({
        ...state,
        lastReport: corruptReport,
      }));
    }
    for (const corrupt of corruptions) {
      const candidate = corrupt(structuredClone(valid));
      const restored = new FakePi([
        { type: 'custom', customType: 'mosaic-goal-state', data: candidate },
      ]);
      await restored.emit('session_start', { reason: 'resume' });
      expect(restored.statuses.get('mosaic-goal')).toBeUndefined();
      expect(await restored.emit('context', { messages: [] })).toEqual([undefined]);
    }
    const failClosed = new FakePi([
      { type: 'custom', customType: 'mosaic-goal-state', data: valid },
      { type: 'custom', customType: 'mosaic-goal-state', data: { ...valid, version: 99 } },
    ]);
    await failClosed.emit('session_start', { reason: 'resume' });
    expect(failClosed.statuses.get('mosaic-goal')).toBeUndefined();
  });
  it('fails closed instead of reusing credential-bearing legacy branch state', async () => {
    const source = new FakePi();
    await source.goal('set Build a valid restore fixture');
    const cleanState = latestGoalStateData(source);
    const legacyState = structuredClone(cleanState);
    legacyState['statement'] = `Legacy secret ghp_${'z'.repeat(32)}`;
    const restored = new FakePi([
      { type: 'custom', customType: 'mosaic-goal-state', data: legacyState },
      { type: 'custom', customType: 'mosaic-goal-state', data: cleanState },
    ]);
    await restored.emit('session_start', { reason: 'resume' });
    expect(restored.statuses.get('mosaic-goal')).toBeUndefined();
    expect(await restored.emit('context', { messages: [] })).toEqual([undefined]);
    expect(restored.notifications.at(-1)?.level).toBe('warning');
    expect(restored.notifications.at(-1)?.message).toContain('was not restored');
    expect(restored.entries).toHaveLength(0);
  });
  it('schedules an active tree-restored goal and preserves terminal state through compaction', async () => {
    vi.useFakeTimers();
    const source = new FakePi();
    await source.goal('set Restore active tree work');
    const active = latestGoalStateData(source);
    const restored = new FakePi();
    restored.branch = [{ type: 'custom', customType: 'mosaic-goal-state', data: active }];
    await restored.emit('session_tree', {});
    await vi.runAllTimersAsync();
    expect(restored.sentMessages).toHaveLength(1);
    expect(restored.sentMessages[0]?.message.content).toContain('tree navigation');
    await restored.goal('cancel');
    await restored.emit('session_compact', { reason: 'manual', willRetry: false });
    expect(stateField(restored, 'phase')).toBe('cancelled');
    expect(stateField(restored, 'compactionCount')).toBe(1);
  });
  it('cancels deferred continuation when the session shuts down', async () => {
    vi.useFakeTimers();
    const pi = new FakePi();
    await pi.goal('set Do not leak a stale timer');
    pi.sentMessages.length = 0;
    await pi.emit('session_compact', { reason: 'manual', willRetry: false });
    await pi.emit('session_shutdown', { reason: 'reload' });
    await vi.runAllTimersAsync();
    expect(pi.sentMessages).toHaveLength(0);
  });
 });
@@ -72,8 +72,9 @@ elif [[ -n "$DATA_DIR" ]]; then
  while IFS= read -r file; do
    [[ -z "$file" ]] && continue
    done_total=$((done_total + 1))
-    if git -C "$DATA_DIR" log --since="${WINDOW_DAYS} days ago" --pretty='%s' -- "$file" 2>/dev/null \
+    history_rc=0
-         | grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo'; then
+    history="$(git -C "$DATA_DIR" log --since="${WINDOW_DAYS} days ago" --pretty='%s' -- "$file" 2>/dev/null)" || history_rc=$?
    if [[ "$history_rc" -eq 0 ]] && grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo' <<<"$history"; then
      detectable=$((detectable + 1))
    fi
  done < <(find "$DATA_DIR" -type f -name '*.json' 2>/dev/null)
@@ -64,9 +64,9 @@ for line in "${LINES[@]}"; do
  #   - build/test/lint/type/ci signals → CI would have caught it
  #   - security/auth/permission/data/migration → human review would flag it
  #   - everything else (logic/UX/assumption/edge) → only-self-reflection bucket
-  if printf '%s' "$subj" | grep -qiE 'test|lint|type|build|ci|compile|typo'; then
+  if grep -qiE 'test|lint|type|build|ci|compile|typo' <<<"$subj"; then
    ci=$((ci + 1))
-  elif printf '%s' "$subj" | grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection'; then
+  elif grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection' <<<"$subj"; then
    human=$((human + 1))
  else
    selfonly=$((selfonly + 1))
@@ -0,0 +1,28 @@
 [
  "tools/matrix-presence-harness/run.sh:TSX_CLI=\"$(ls -d \"${REPO}\"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs 2>/dev/null | head -1)\"",
  "tools/e2e-install-test.sh:if ! mosaic gateway --help 2>&1 | grep -q 'verify'; then",
  "tools/install.sh:EXTRACTED_DIR=\"$(find \"$WORK_DIR\" -maxdepth 1 -mindepth 1 -type d | head -1)\"",
  "scripts/analysis/reflect-board-history.sh:if git -C \"$DATA_DIR\" log --since=\"${WINDOW_DAYS} days ago\" --pretty='%s' -- \"$file\" 2>/dev/null  | grep -qiE 'reopen|revert|fix|regression|wrong|incorrect|redo'; then",
  "scripts/analysis/reflect-git-history.sh:if printf '%s' \"$subj\" | grep -qiE 'test|lint|type|build|ci|compile|typo'; then",
  "scripts/analysis/reflect-git-history.sh:elif printf '%s' \"$subj\" | grep -qiE 'security|auth|permission|rbac|secret|migration|data|sql|injection'; then",
  "packages/mosaic/framework/tools/authentik/user-create.sh:group_pk=$(echo \"$group_response\" | jq -r \".results[] | select(.name == \\\"$GROUP\\\") | .pk\" | head -1)",
  "packages/mosaic/framework/tools/git/mutate-push-guard.sh:PROSE_LO=\"$(grep -n '^usage() {' \"$BAK\" | head -1 | cut -d: -f1)\"",
  "packages/mosaic/framework/tools/orchestrator/session-resume.sh:echo \"$dirty_files\" | head -20 | while IFS= read -r line; do",
  "packages/mosaic/framework/tools/prdy/prdy-status.sh:if echo \"$PRD_CONTENT\" | grep -qiE \"$pattern\"; then",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'auth|login|session|token|permission|rbac|credential|secret'; then echo auth; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'migration|prisma|schema|\\.sql|entity|repository|seed'; then echo data; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'docker|\\.woodpecker|compose|traefik|deploy|helm|k8s|terraform'; then echo infra; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qiE 'package\\.json|tsconfig|turbo\\.json|pnpm-|\\.config\\.|eslint|vite'; then echo build; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.tsx|\\.css|components/|apps/web/'; then echo ui; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.spec\\.|\\.test\\.|__tests__/'; then echo test; return; fi",
  "packages/mosaic/framework/tools/qa/reflect-stop-hook.sh:if printf '%s' \"$p\" | grep -qE '\\.md$|docs/'; then echo docs; return; fi",
  "packages/mosaic/framework/tools/qa/typecheck-hook.sh:FILE_PATH=$(echo \"$JSON_INPUT\" | grep -o '\"file_path\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | sed 's/.*\"\\([^\"]*\\)\"$/\\1/' | head -1)",
  "packages/mosaic/framework/tools/qa/typecheck-hook.sh:RELEVANT=$(echo \"$OUTPUT\" | grep -A2 \"$BASENAME\" 2>/dev/null || echo \"$OUTPUT\" | head -20)",
  "packages/mosaic/framework/tools/tmux/send-message.sh:if printf '%s' \"$pane\" | grep -qF \"$QUEUED_RE\"; then",
  "packages/mosaic/framework/tools/tmux/send-message.sh:if [ -n \"$snippet\" ] && printf '%s' \"$promptline\" | grep -qF \"$snippet\"; then",
  "packages/mosaic/framework/tools/wake/detector.sh:sed -n \"s/^${key}=//p\" \"$MANIFEST\" | head -n1 | tr -d '[:space:]'",
  "packages/mosaic/framework/tools/wake/detector.sh:if [ -n \"$snap_sha\" ] && ! printf '%s' \"$snap_sha\" | grep -Eq '^[0-9a-f]{7,64}$'; then",
  "packages/mosaic/framework/tools/wake/detector.sh:if [ -n \"$snap_ts\" ] && ! printf '%s' \"$snap_ts\" | grep -Eq '^[0-9]{1,12}$'; then",
  "packages/mosaic/framework/tools/wake/digest.sh:olabel=\"$(_locator_line \"$oloc\" | head -n1)\"",
  "packages/mosaic/framework/tools/wake/reconcile.sh:sed -n \"s/^${key}=//p\" \"$MANIFEST\" | head -n1 | tr -d '[:space:]'"
 ]
@@ -0,0 +1,24 @@
 [
  "packages/mosaic/framework/systemd/user/test-fleet-units.sh:if tmux -L \"$TEST_SOCKET\" show-environment -g LD_PRELOAD 2>/dev/null | grep -q '^LD_PRELOAD='; then",
  "packages/mosaic/framework/tools/git/test-issue-comment-readback.sh:write_response \"$(printf '%s' \"$result\" | head -n1)\" \"$(printf '%s' \"$result\" | tail -n +2)\"",
  "packages/mosaic/framework/tools/git/test-issue-comment-readback.sh:write_response \"$(printf '%s' \"$result\" | head -n1)\" \"$(printf '%s' \"$result\" | tail -n +2)\"",
  "packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh:contains() { printf '%s\\n' \"$1\" | grep -qx \"$2\"; }",
  "packages/mosaic/framework/tools/git/test-pr-review-gitea-comment.sh:write_response \"$(printf '%s' \"$result\" | head -n1)\" \"$(printf '%s' \"$result\" | tail -n +2)\"",
  "packages/mosaic/framework/tools/git/test-pr-review-repo-host-override.sh:echo \"$HELP_TEXT\" | grep -q -- '-r, --repo'",
  "packages/mosaic/framework/tools/git/test-pr-review-repo-host-override.sh:echo \"$HELP_TEXT\" | grep -q -- '-H, --host'",
  "packages/mosaic/framework/tools/orchestrator/smoke-test.sh:if [[ \"$(printf '%s\\n' \"$codex_run_prompt\" | head -n1)\" == \"Now initiating Orchestrator mode...\" ]]; then pass_case \"codex run prompt first line is mode declaration\"; else fail_case \"codex run prompt first line is mode declaration\"; fi",
  "packages/mosaic/framework/tools/orchestrator/smoke-test.sh:if [[ \"$(printf '%s\\n' \"$claude_run_prompt\" | head -n1)\" == \"## Continuation Mission\" ]]; then pass_case \"claude run prompt remains continuation prompt format\"; else fail_case \"claude run prompt remains continuation prompt format\"; fi",
  "packages/mosaic/framework/tools/orchestrator/test-board-roll.sh:echo \"$out\" | grep -qi \"dry run\" || note \"dry-run did not announce itself\"",
  "packages/mosaic/framework/tools/orchestrator/test-board-roll.sh:echo \"$out\" | grep -q \"would roll\" || note \"dry-run did not report a plan\"",
  "packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh:find \"$1/mosaic/backups\" -maxdepth 1 -type d -name 'pre-update-*' 2>/dev/null  | LC_ALL=C sort -r | head -1",
  "packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh:SNAP_E=\"$(grep -o '/[^ ]*mosaic-snapshot[^ ]*' \"$OUTG\" | head -1)\"",
  "packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh:grep -o '/[^ ]*mosaic-snapshot[^ ]*' \"$OUTH\" 2>/dev/null | head -1 | while read -r s; do rm -rf \"$s\"; done",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:capture_named | grep -qF \"named socket hello\" || fail \"send-message.sh did not deliver to named socket\"",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:if capture_default | grep -qF \"named socket hello\"; then",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:capture_named | grep -qF \"[tester:source ->\" || fail \"agent-send.sh did not include preamble\"",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:capture_named | grep -qF \"agent socket hello\" || fail \"agent-send.sh did not deliver to named socket\"",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:if capture_default | grep -qF \"agent socket hello\"; then",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:printf '%s' \"$pane\" | grep -qF \"CONCPAYLOAD-${i}-END\"  || fail \"concurrent send dropped payload for pane conc-$i\"",
  "packages/mosaic/framework/tools/tmux/test-send-message-socket.sh:if printf '%s' \"$pane\" | grep -qF \"CONCPAYLOAD-${j}-END\"; then",
  "packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh:if [ \"$rc\" -eq 0 ] && printf '%s' \"$out\" | grep -qF \"✓ delivered\"; then"
 ]
@@ -0,0 +1,28 @@
 [
  "packages/mosaic/framework/tools/wake/test-wake-digest-quarantine.sh:fixture_line=\"$(has_match -F \"\\\"id\\\":\\\"$enum_id\\\"\" \"$self\" | has_match -F '\"observed_seq\":5' | head -n1)\"",
  "packages/mosaic/framework/tools/wake/test-wake-preimage.sh:pre_seq=\"$(jq -r 'select(.locators.kind == \"preimage\") | .observed_seq' \"$sd/pending.jsonl\" | head -n1)\"",
  "packages/mosaic/framework/tools/wake/test-wake-preimage.sh:src_seq=\"$(jq -r 'select(.locators.kind == \"repo\") | .observed_seq' \"$sd/pending.jsonl\" | head -n1)\"",
  "packages/mosaic/framework/tools/wake/test-wake-preimage.sh:pre_seq=\"$(jq -r 'select(.locators.kind == \"preimage\") | .observed_seq' \"$sd/pending.jsonl\" | head -n1)\"",
  "packages/mosaic/framework/tools/wake/test-wake-preimage.sh:enum_seq=\"$(jq -r 'select(.locators.reconciled == true) | .observed_seq' \"$sd/pending.jsonl\" | head -n1)\"",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:if ! sed -n \"${ln}p\" \"$f\" | grep -Eq 'has_match|count_lines'; then",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$outA\" | grep -q 'mini-a: OK' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$outB\" | grep -q 'mini-b: OK' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:check C1 1 \"rcA=$rcA rcB=$rcB expected($n_expected)/got diff: $(diff \"$TMP/expected-c1\" \"$TMP/got-c1\" 2>&1 | head -n 10 | tr '\\n' ' ')\"",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:! printf '%s' \"$out\" | grep -q 'mini-a: OK' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:! printf '%s' \"$out\" | grep -q 'mini-a: FAILED' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q \"WAKE-ASSERT ARMED: forcing real grep error at $site\" &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q \"WAKE-ASSERT ABORT\" &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q \"$site\" &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q \"grep exit 2\" &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q 'mini-a: OK' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:! printf '%s' \"$out\" | grep -q 'WAKE-ASSERT ARMED'; then",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:! printf '%s' \"$out\" | grep -q 'REACHED-PAST-INIT' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q 'WAKE-ASSERT INIT ABORT: BASH_LINENO convention violated'; then",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:printf '%s' \"$out\" | grep -q 'wake mini-c harness: FAILED (1 assertion(s))' &&",
  "packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh:! printf '%s' \"$out\" | grep -q 'all invariants passed' &&",
  "packages/mosaic/framework/tools/wake/validate-973/validate-973.sh:diff \"$TMP/expected.txt\" \"$TMP/static.txt\" | head -n 20 | sed 's/^/  /'",
  "packages/mosaic/framework/tools/wake/validate-973/validate-973.sh:if printf '%s\\n' \"$out\" | grep -Eq \"$(sentinel_for \"$s\")\"; then",
  "packages/mosaic/framework/tools/wake/validate-973/validate-973.sh:printf '%s\\n' \"$out\" | grep -q \"WAKE-ASSERT ARMED: forcing real grep error at $site\" ||",
  "packages/mosaic/framework/tools/wake/validate-973/validate-973.sh:printf '%s\\n' \"$out\" | grep -q \"WAKE-ASSERT ABORT: ${helper} at ${site}: grep exit\" ||",
  "packages/mosaic/framework/tools/wake/validate-973/validate-973.sh:printf '%s\\n' \"$out\" | grep -Eq \"$(sentinel_for \"$f\")\" || rc_sent=$?"
 ]
@@ -0,0 +1,207 @@
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
 const ROOT = new URL('../', import.meta.url);
 const EXPECTED_BASELINE_SITES = 26;
 const EXPECTED_TEST_BASELINE_SITES = 22;
 const EXPECTED_WAKE_BASELINE_SITES = 26;
 const TARGETS = [
  'tools/matrix-presence-harness/run.sh',
  'tools/e2e-install-test.sh',
  'tools/install.sh',
  'scripts/agent/session-start.sh',
  'scripts/analysis/reflect-board-history.sh',
  'scripts/analysis/reflect-git-history.sh',
  'packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh',
  'packages/mosaic/framework/tools/authentik/user-create.sh',
  'packages/mosaic/framework/tools/git/mutate-push-guard.sh',
  'packages/mosaic/framework/tools/orchestrator/session-resume.sh',
  'packages/mosaic/framework/tools/prdy/prdy-status.sh',
  'packages/mosaic/framework/tools/qa/reflect-stop-hook.sh',
  'packages/mosaic/framework/tools/qa/typecheck-hook.sh',
  'packages/mosaic/framework/tools/tmux/send-message.sh',
  'packages/mosaic/framework/tools/wake/detector.sh',
  'packages/mosaic/framework/tools/wake/digest.sh',
  'packages/mosaic/framework/tools/wake/reconcile.sh',
  'packages/mosaic/framework/systemd/user/test-fleet-units.sh',
  'packages/mosaic/framework/tools/git/test-issue-comment-readback.sh',
  'packages/mosaic/framework/tools/git/test-lane-brief-pr-linkage.sh',
  'packages/mosaic/framework/tools/git/test-pr-review-gitea-comment.sh',
  'packages/mosaic/framework/tools/git/test-pr-review-repo-host-override.sh',
  'packages/mosaic/framework/tools/orchestrator/smoke-test.sh',
  'packages/mosaic/framework/tools/orchestrator/test-board-roll.sh',
  'packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh',
  'packages/mosaic/framework/tools/quality/scripts/test-upgrade-rollback.sh',
  'packages/mosaic/framework/tools/tmux/test-send-message-socket.sh',
  'packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh',
  'packages/mosaic/framework/tools/wake/test-wake-digest-quarantine.sh',
  'packages/mosaic/framework/tools/wake/test-wake-preimage.sh',
  'packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh',
  'packages/mosaic/framework/tools/wake/validate-973/validate-973.sh',
 ];
 // These statuses are explicitly non-load-bearing or unreachable at designed input.
 // They remain inventoried until the final #1099 tranche records every verdict.
 const ACCEPTED = [
  ['tools/install.sh', 'mosaic-bak-', '|| true'],
  ['tools/install.sh', 'mosaicstack-mosaic-*.tgz', 'head -1'],
  ['tools/install.sh', 'mosaicstack-gateway-*.tgz', 'head -1'],
  ['scripts/agent/session-start.sh', 'docs/scratchpads/*.md', '|| true'],
  [
    'packages/mosaic/framework/templates/repo/scripts/agent/session-start.sh',
    'docs/scratchpads/*.md',
    '|| true',
  ],
 ];
 const earlyExit =
  /(?<!\|)\|(?!\|)[^;\n]*(?:grep\b[^;\n]*(?:-[A-Za-z]*q|--quiet|-m\s*1)|head\b(?:\s|$))/;
 function scan(sources) {
  const found = [];
  for (const [file, rawSource] of sources) {
    const source = rawSource.replace(/\\\n\s*/g, ' ');
    for (const rawLine of source.split('\n')) {
      const line = rawLine.trim();
      if (!earlyExit.test(line)) continue;
      const accepted = ACCEPTED.some(
        ([acceptedFile, ...fragments]) =>
          acceptedFile === file && fragments.every((item) => line.includes(item)),
      );
      if (!accepted) found.push(`${file}:${line}`);
    }
  }
  return found;
 }
 async function currentSources() {
  return Promise.all(
    TARGETS.map(async (file) => [file, await readFile(new URL(file, ROOT), 'utf8')]),
  );
 }
 async function assertBaselineFixture(file, expectedCount, expectedUnique = expectedCount) {
  const baseline = JSON.parse(await readFile(new URL(file, ROOT), 'utf8'));
  assert.equal(baseline.length, expectedCount);
  assert.equal(new Set(baseline).size, expectedUnique);
  const fixtureSources = baseline.map((site) => {
    const separator = site.indexOf(':');
    assert.ok(separator > 0, `invalid baseline site: ${site}`);
    return [site.slice(0, separator), site.slice(separator + 1)];
  });
  assert.deepEqual(scan(fixtureSources), baseline);
 }
 test('the registered runtime baseline denominator is exactly 26 unsafe sites', async () => {
  await assertBaselineFixture(
    'scripts/fixtures/pipefail-early-exit-baseline.json',
    EXPECTED_BASELINE_SITES,
  );
 });
 test('the registered test baseline denominator is exactly 22 unsafe sites', async () => {
  await assertBaselineFixture(
    'scripts/fixtures/pipefail-early-exit-test-baseline.json',
    EXPECTED_TEST_BASELINE_SITES,
    21,
  );
 });
 test('the registered wake baseline denominator is exactly 26 unsafe sites', async () => {
  await assertBaselineFixture(
    'scripts/fixtures/pipefail-early-exit-wake-baseline.json',
    EXPECTED_WAKE_BASELINE_SITES,
    25,
  );
 });
 test('load-bearing pipefail paths do not pipe into early-exiting consumers', async () => {
  assert.deepEqual(scan(await currentSources()), []);
 });
 test('gateway verify capability preserves the complete help-probe truth table', async () => {
  const directory = await mkdtemp(path.join(tmpdir(), 'gateway-help-probe-'));
  const mosaic = path.join(directory, 'mosaic');
  const probe = new URL('tools/e2e-gateway-verify-supported.sh', ROOT).pathname;
  try {
    await writeFile(
      mosaic,
      '#!/usr/bin/env bash\nprintf \'%s\\n\' "${MOCK_HELP_OUTPUT:-}"\nexit "${MOCK_HELP_RC:-0}"\n',
    );
    await chmod(mosaic, 0o755);
    const run = (rc, output) =>
      spawnSync('bash', [probe], {
        env: {
          ...process.env,
          PATH: `${directory}:${process.env.PATH}`,
          MOCK_HELP_RC: String(rc),
          MOCK_HELP_OUTPUT: output,
        },
      }).status;
    assert.equal(run(0, 'commands: verify'), 0);
    assert.equal(run(0, 'commands: install'), 1);
    assert.equal(run(1, 'commands: verify'), 1);
  } finally {
    await rm(directory, { recursive: true, force: true });
  }
 });
 test('wake JSONL selectors take the first match across the complete input stream', async () => {
  const source = await readFile(
    new URL('packages/mosaic/framework/tools/wake/test-wake-preimage.sh', ROOT),
    'utf8',
  );
  assert.equal((source.match(/jq -nr 'first\(inputs \| select\(/g) ?? []).length, 4);
  const directory = await mkdtemp(path.join(tmpdir(), 'wake-jsonl-first-'));
  const input = path.join(directory, 'pending.jsonl');
  const filter = 'first(inputs | select(.locators.kind == "preimage") | .observed_seq) // empty';
  try {
    await writeFile(
      input,
      '{"locators":{"kind":"repo"},"observed_seq":1}\n' +
        '{"locators":{"kind":"preimage"},"observed_seq":4}\n' +
        '{"locators":{"kind":"preimage"},"observed_seq":9}\n',
    );
    let result = spawnSync('jq', ['-nr', filter, input], { encoding: 'utf8' });
    assert.equal(result.status, 0, result.stderr);
    assert.equal(result.stdout, '4\n');
    await writeFile(input, '{"locators":{"kind":"repo"},"observed_seq":1}\n');
    result = spawnSync('jq', ['-nr', filter, input], { encoding: 'utf8' });
    assert.equal(result.status, 0, result.stderr);
    assert.equal(result.stdout, '');
    await writeFile(input, '{invalid json}\n');
    result = spawnSync('jq', ['-nr', filter, input], { encoding: 'utf8' });
    assert.notEqual(result.status, 0);
  } finally {
    await rm(directory, { recursive: true, force: true });
  }
 });
 test('board-history preserves non-git data-dir as a non-detectable result', async () => {
  const directory = await mkdtemp(path.join(tmpdir(), 'reflect-board-non-git-'));
  try {
    await writeFile(path.join(directory, 'task.json'), '{}\n');
    const result = spawnSync(
      'bash',
      [
        new URL('scripts/analysis/reflect-board-history.sh', ROOT).pathname,
        '--data-dir',
        directory,
      ],
      { encoding: 'utf8' },
    );
    assert.equal(result.status, 0, result.stderr);
    assert.match(result.stdout, /"done_tasks": 1/);
    assert.match(result.stdout, /"detectable_outcomes": 0/);
  } finally {
    await rm(directory, { recursive: true, force: true });
  }
 });
@@ -0,0 +1,10 @@
 #!/usr/bin/env bash
 # Exit 0 only when the capability probe itself succeeds and advertises verify.
 # A failed help command and a successful response without verify are both
 # unsupported, matching the historical e2e-install-test.sh conditional.
 set -uo pipefail
 gateway_help_rc=0
 gateway_help="$(mosaic gateway --help 2>&1)" || gateway_help_rc=$?
 [[ "$gateway_help_rc" -eq 0 ]] || exit 1
 grep -q 'verify' <<<"$gateway_help"
@@ -136,7 +136,7 @@ fi
 echo "=== [inner] Running mosaic gateway verify ==="
 # `gateway verify` was added in feat/mosaic-first-run-ux.
 # If the installed version pre-dates this, skip gracefully.
-if ! mosaic gateway --help 2>&1 | grep -q 'verify'; then
+if ! bash /repo/tools/e2e-gateway-verify-supported.sh; then
  echo "[SKIP] 'mosaic gateway verify' not available in installed version ${INSTALLED_VERSION}."
  echo "[SKIP] This command was added in the feat/mosaic-first-run-ux release."
  echo "[SKIP] Re-run after the new version is published to validate this step."
@@ -308,13 +308,17 @@ ensure_monorepo() {
    exit 1
  fi
-  # Gitea archives extract to <repo-name>/ inside the work dir
+  # Gitea archives extract to exactly one <repo-name>/ inside the work dir.
-  EXTRACTED_DIR="$(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d | head -1)"
+  # Read the complete population so a malformed multi-root archive reaches the
-  if [[ -z "$EXTRACTED_DIR" ]] || [[ ! -d "$EXTRACTED_DIR" ]]; then
+  # named diagnostic instead of aborting on an upstream SIGPIPE under pipefail.
-    fail "Could not locate extracted source in archive."
+  local -a extracted_dirs=()
  mapfile -d '' -t extracted_dirs < <(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d -print0)
  if [[ "${#extracted_dirs[@]}" -ne 1 ]] || [[ ! -d "${extracted_dirs[0]:-}" ]]; then
    fail "Could not locate exactly one extracted source directory in archive."
    ls -la "$WORK_DIR" >&2
    exit 1
  fi
  EXTRACTED_DIR="${extracted_dirs[0]}"
 }
 # Build @mosaicstack/mosaic + @mosaicstack/gateway from source and install both
@@ -35,7 +35,10 @@ export DARK_THRESHOLD_MS="${DARK_THRESHOLD_MS:-6000}"
 export AGENT_SLUGS="${AGENT_SLUGS:-alpha,bravo,charlie}"
 export VICTIM_SLUG="${VICTIM_SLUG:-charlie}"
-TSX_CLI="$(ls -d "${REPO}"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs 2>/dev/null | head -1)"
+shopt -s nullglob
 TSX_CANDIDATES=("${REPO}"/node_modules/.pnpm/tsx@*/node_modules/tsx/dist/cli.mjs)
 shopt -u nullglob
 TSX_CLI="${TSX_CANDIDATES[0]:-}"
 if [[ -z "${TSX_CLI}" ]]; then
  echo "run.sh: tsx not found under node_modules — run pnpm install first" >&2
  exit 1