fix(mosaic): enforce private brain checkout

fix(mosaic): reject unapproved brain skeleton state
fix(mosaic): preserve measurable brain git state
2026-08-05 17:19:51 -05:00 · 2026-08-05 17:19:51 -05:00 · 2026-08-05 17:19:50 -05:00 · 2026-08-05 17:19:50 -05:00 · 2026-08-05 17:19:50 -05:00 · 2026-08-05 17:19:50 -05:00
50 changed files with 7939 additions and 259 deletions
@@ -79,6 +79,49 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and

 ---

+## Per-estate durable agent working memory (#1051)
+
+### Problem and objective
+
+Agent and lane continuity currently accumulates as plain local files with no repository backing. The installer must make a private, per-estate `mosaic-brain` clone at `~/.mosaic` reproducible without authorizing cross-estate access or introducing an independent credential path.
+
+### Normative requirements
+
+1. `MB-REQ-01` (R1): Ensure the target estate's existing `mosaic-brain` can be cloned to `~/.mosaic`; repository creation and live access granting remain broker-mediated.
+2. `MB-REQ-02` (R2/Q1): Derive estate and brain target from the configured target git host through the credential broker's estate registry. A second `brain_repo` authority and host-machine inference are forbidden; an unknown host fails closed with a named diagnosis.
+3. `MB-REQ-03` (R3): Seat access is granted only through `mosaic cred`; callers must never resolve or read a token independently. Live grant verification is gated on MC-CRED-01 implementation.
+4. `MB-REQ-04` (R4): The eventual live postcondition requires `~/.mosaic` to be a `main`-branch git repo with the expected remote and a seat-owned read/write round-trip. This live validation is gated on MC-CRED-01 implementation and cannot be replaced by a clone exit code.
+5. `MB-REQ-05` (R5): The out-of-estate refusal control covers both Git and API resolver axes. Axis disagreement is `indeterminate` failure, never permission; contract tests bind to the broker's four terminal classes and stable reason codes.
+6. `MB-REQ-06` (R6): The brain skeleton excludes `*.token`, `*.key`, `*.pem`, `.env`, and `credentials.json`; credentials remain broker-owned and no error path may print secret material. Arbitrary legacy content is never auto-published from a heuristic denylist: an approved content scanner must bind approval to the exact source snapshot, otherwise the item is retained and reported.
+7. `MB-REQ-07` (R7): Detect existing local lane directories and seat state files, publish approved snapshots into the durable layout without overwrite or deletion, and explicitly report every detected item that cannot be migrated. Automatic source deletion is parked until command-scoped identity propagation and the required clean audit; retained sources are always reported. Lane findings are append-only; `board/` has a named single writer; writes push immediately rather than on a timer.
+8. `MB-REQ-08` (R8): `mosaic doctor` reports missing clone, wrong remote, incomplete write-access evidence, and uncommitted local state. `--fix` repairs the first three only through the approved installer/broker path; it never hand-rolls credential resolution.
+9. `MB-REQ-09`: Retention is ownership-first and archive-only. Every retained artifact requires a named durable owner; absent or non-durable ownership leaves the gate open and blocking. Age and size never authorize deletion.
+10. `MB-REQ-10`: Brain provisioning occupies canonical installer P7 only after the applicable P5 credential postcondition commits; canonical phase numbers are unchanged.
+
+### Current delivery slice
+
+In scope now: estate derivation, secret exclusion, non-destructive migration, doctor reporting/repair orchestration, and red-first tests over all four credential-contract terminal classes. Live grant and live read/write round-trip evidence remain explicitly gated on the working MC-CRED-01 broker and must not be mocked or replaced by independent token lookup.
+
+### Acceptance criteria
+
+1. `AC-MB-01`: Contract tests observe RED before implementation and then distinguish `ok/0`, `refused/10`, `error/20`, and `indeterminate/30`, preserving v1.5 diagnoses including refused `provider-identity-mismatch`/`credential-rejected` and indeterminate `identity-not-measured`/`provider-unavailable`. A scope-forbidden `/user` result with confirmed in-scope repository capability is never represented as a dead credential. `identity-not-found` remains reserved for a future visibility-authorized inventory operation and is not an expected `validate` result.
+2. `AC-MB-02`: Estate resolution uses the configured target git host and one registry; unknown, mismatched, and host-machine-derived inputs fail closed.
+3. `AC-MB-03`: A clean fixture contains the required layout and exact secret exclusions; filename-, content-, binary-, and size-based secret controls remain outside Git without their values appearing in output. Without an approved scanner, even benign legacy content is retained and reported rather than auto-published.
+4. `AC-MB-04`: Migration publishes approved lane-durable and seat-state snapshots into collision-safe archive/ledger paths, retains and reports every source, never overwrites an existing finding, and never deletes by age/size.
+5. `AC-MB-05`: Doctor detects all four R8 defect classes; `--fix` repairs eligible classes through the approved P7/broker seam and leaves unresolved credential-dependent states visible.
+6. `AC-MB-06`: Git-axis and API-axis refusal must both be authoritative `refused` outcomes with matching stable reason codes; any disagreement yields `indeterminate`.
+7. `AC-MB-07`: Independent code review and security review pass at the exact head, and HOMELAB Woodpecker instance `mosaic` is terminal green before integration.
+8. `AC-MB-08`: After reviewed merge to `main`, report only **believed-fixed, pending jarvis validation**; issue #1051 remains open until W-jarvis validates the installed result.
+
+### Constraints and risks
+
+- MC-CRED-01 contract v1.5 is the caller boundary; no independent credential/token lookup is permitted. Identity is established from governed mint-time binding and provider evidence when measurable, never a credential filename. Runtime validation does not widen a least-privilege token merely to make `/user` observable.
+- C1 owns installer phase sequencing. This slice consumes P5/P7 ordering without renumbering or duplicating the phase machine.
+- Lane content is findings, so last-writer-wins is data loss. Append-only names and explicit collision handling are mandatory.
+- A created-but-empty brain beside unbacked local doctrine fails the objective; migration is a primary acceptance gate.
+
+---
+
 ## Compaction Refresh Trust Lifecycle (M1, #827–#830)

 ### Problem and objective
@@ -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,105 @@
+# #1051 — per-estate mosaic-brain installer
+
+Last updated: 2026-08-05
+
+## Objective
+
+Codify estate-derived, repository-backed `~/.mosaic` support with secret exclusions, non-destructive migration, doctor diagnostics/fixes, and credential-contract terminal-class handling. Live broker grants and live read/write round-trips remain gated on MC-CRED-01.
+
+## Sources and bindings
+
+- Provider issue: HOMELAB `git.mosaicstack.dev`, `GET /api/v1/repos/mosaicstack/stack/issues/1051`, `application/json;charset=utf-8`.
+- Issue requirements: R1–R8 read directly on 2026-08-05.
+- MC-CRED caller contract: v1.5, SHA-256 `4cecba3386b37431d4a075205c6dfe43555c7673922fed61b84f43cac1a6ae92` at the 2026-08-05 re-derivation. Earlier moving bindings were v1.5 `710d22d61a93a4b9c70fc55506a023a675a110417fa7a6e72dc051c0d9fe8237`, v1.4 `27f20158561ae8292f3bfc926b5e97f398de93db6a1cf65fcc215d08811d39af`/`d12ad4595b7aef078e392988a07ab5cb00244440775c9c733dc825746d7ac67b`, and v1.3 `8cfa4853d2b0b0e8cc9e792fa8411310e16d7704c06e0af9d9a57155131d8086`.
+- Fleet doctrine: SHA-256 `026b43322e0551ef15b646a9f30d3a6aef58c662a810b732be2a03b1ecf7d36e` at intake.
+- Intake base was HOMELAB provider `next` = `4df478cdd150fdf8d52ea109f02ade5d85017acd`; `main` = `5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc`. On 2026-08-05 `mos-claude` ruled that L0 trunk-based gate 15 requires all three lanes to retarget to `main`; `next` remains a non-merging integration branch. Never weaken or patch `pr-merge.sh`.
+
+## Scope
+
+### In now
+
+- R2/Q1 target-host estate derivation using one registry.
+- R5 both-axis refusal parity and disagreement failure.
+- R6 exact secret exclusions and no secret-bearing diagnostics.
+- R7 detection plus non-destructive, collision-safe migration/reporting.
+- R8 doctor checks and approved-seam fix orchestration.
+- Red-first tests over all four contract terminal classes and stable reason codes.
+
+### Gated / excluded
+
+- R3 live grant: waits for working MC-CRED-01.
+- R4 live seat-owned read/write round-trip: waits for working MC-CRED-01.
+- No independent token lookup, grant helper, or shared-credential fallback.
+- No phase renumbering; C1 owns the phase machine and provides the P5→P7 seam.
+- No age/size reaping or deletion.
+
+## Owner authority ruling and resolver seam
+
+- Binding addendum: `/home/hermes/agent-work/tl-mosaic/CHARTER-MB-BRAIN-01-ADDENDUM.md`; re-read after compaction.
+- HOMELAB durable lane-archive owner and user-namespace brain owner are the human provider account selected by local estate policy (operator ruling: `jason.woltje`) with a required GLPI queue as the standing remediation process. The brain target is therefore `<policy-owner>/mosaic-brain` on the estate host, not `<installer-source-org>/mosaic-brain`. Framework source remains operator-agnostic: the actual login and queue are local policy, not hardcoded open-source context.
+- Provider lookup is anonymous because the ruled owner is public. It requires exact allowlisted login plus a same-invocation public known-good control, private 404 control, and generated absent 404 control. It sends no Authorization header and never widens token scope.
+- Provider `active` is deliberately ignored: non-admin reads return false for demonstrably active accounts. Resolvability + exact login + public visibility are the gate.
+- Private and absent principals both return anonymous 404. The fail-closed reason is `owner-not-resolvable`, never owner-not-found.
+- Caller `owner` strings and `validated=true` are ignored. Migration consumes only an injected source-of-truth resolver result. Owner grammar is NFKC-stable, ASCII allowlisted, exact-policy matched, and mission-seat class is excluded.
+
+## Plan
+
+1. Pre-register acceptance tests and observe each requirement RED for its own missing behavior.
+2. Commit the red tests before implementation.
+3. Implement a narrow brain provisioning/doctor helper that consumes broker JSON outcomes and the shared estate registry without credential resolution.
+4. Implement safe migration and exact brain skeleton/ignore policy.
+5. Integrate the helper into C1's P7 seam and `mosaic doctor` after C1 lands/rebase.
+6. Run focused, package, installer, lint, typecheck, format, and situational security tests.
+7. Run independent code and security reviews in parallel; remediate and re-review.
+8. Push after HOMELAB queue guard, open the reviewed PR to `main`, and preserve merge order C1 → MC-CRED → MB-BRAIN. Do not modify the merge guard; `next` is non-merging integration only.
+9. Re-take CI measurement at the rebased exact head; do not rework code solely because base evidence moved.
+
+## Acceptance interpretation registered before results
+
+- `ok/0`: complete authoritative evidence only.
+- `refused/10`: complete authoritative denial only.
+- `error/20`: local contract/control failure; never reinterpret as denial.
+- `indeterminate/30`: incomplete/disagreeing evidence; fail closed, never resolve permissively.
+- Both Git and API axes must return authoritative `refused` with the same stable reason code for R5. Any axis disagreement is `indeterminate`. A provider `/user` login mismatch is first-class `provider-identity-mismatch`; credential filenames never establish principal identity.
+- Migration publication requires the durable object to contain the approved snapshot and no overwrite. Automatic path-based source deletion is parked; every source is retained and reported.
+- Secret exclusion is tested through exact ignore rules, nested secret-shaped paths, bounded UTF-8 content controls, and an approved-scanner gate bound to the exact source snapshot. Without an approved scanner, even benign content is retained and reported rather than committed.
+
+## Budget
+
+No explicit token ceiling was supplied. Working cap: 55K tokens for implementation/review and 3 focused remediation attempts per failure class. Reduce optional refactoring and documentation breadth before touching required acceptance scope.
+
+## Risks
+
+- C1 and MC-CRED branches have not merged into `main`; integration edits must wait for their exact interfaces or be confined to stable contract seams.
+- A broker runtime test before MC-CRED lands would either fail for an irrelevant reason or pressure a hand-rolled workaround; contract fixtures are allowed, live capability claims are not.
+- Migration can lose data through overwrite, cross-device move failure, or partial copy. Implementation must stage, verify resulting bytes, and retain/report source on incomplete transfer.
+- `~/.mosaic` is a git repo, while current working state may live under multiple local roots; detection must be explicit and cannot treat age/size as ownership.
+
+## Progress / evidence
+
+- [x] Charter receipt accepted by `tl-mosaic`.
+- [x] Issue #1051 R1–R8 read directly from provider.
+- [x] Contract re-derived through v1.3, moving v1.4, and v1.5 before R5 integration. v1.5 separates in-scope repository capability from `/user` identity measurement: 401 is `credential-rejected`/refused, 403/404 may become `identity-not-measured` only after in-scope capability succeeds, and 200 login mismatch is refused. `identity-not-found` is not reachable from `validate`.
+- [x] C1 P5→P7 seam receipt read; no brain implementation is in C1.
+- [x] RED acceptance set committed at `cf11c6c86abae073d8b02b4014cd5447ba67f12a`; author and committer read back as `be-coder-07` and branch reachability was independently verified by `tl-mosaic`.
+- [x] Moving-contract REDs observed independently for v1.4 mismatch, R8 prerequisite ordering, owner resolver seam/allowlist, tracked skeleton/no-follow behavior, runtime observation/publication, and provider owner resolution.
+- [x] Focused implementation includes secure migration, v1.5 write-differential/subject binding, production Git+API refusal parity, provider-backed durable owner resolution that ignores non-admin `active`, required GLPI standing-process policy, P7 provision orchestration, an internal installer command, and installed `mosaic doctor` wiring. Latest focused result: 97/97 (secure config 4, store 45, runtime 19, owner resolver 16, provision 5, provision command 3, installed doctor 5).
+- [x] MC-CRED added the required canonical reverse registry seam `ParsedCredentialEstateRegistry.resolveByHost()` at dependency head `6ca8758f`; current local copies are temporary until dependency integration and the 32-line permissive shim has been removed.
+- [x] Identity gotcha measured: inline `MOSAIC_GIT_IDENTITY=be-coder-07` controls credential resolution but does not override `user.name`/`user.email` inherited from the linked worktree common-dir config (`coder-mos1`). The first local P7 RED commit was immediately amended before push with command-scoped `GIT_AUTHOR_*` + `GIT_COMMITTER_*`; resulting author and committer both read back as `be-coder-07`. Every subsequent authoring command must carry both identity sets and be verified.
+- [x] R6 migration reports filename- or content-secret-shaped files without copying them; arbitrary legacy content requires an approved scanner bound to the exact source snapshot, and production currently retains/reports when no approved scanner is configured. `.gitignore` is canonical allowlisted content only: an existing noncanonical regular file fails closed and is never merged into publication. Symlinked `.gitignore`, layout directories, and nested migration destinations fail closed; a dirty checkout blocks provisioning before skeleton publication. The brain root is principal-owned mode `0700` before clone and after clone, all memory-bearing layout directories are mode `0700` even under umask `0022`, and doctor reports owner-accessible roots as hard unsafe findings.
+- [x] Provider owner lookup uses manual redirect handling, a five-second abort signal, strict JSON content type/shape, and an incrementally enforced 256 KiB response ceiling.
+- [x] Security-critical owner policy/registry reads have direct controls for principal UID ownership, file/ancestor permissions, and descriptor-safe regular-file reads.
+- [x] Automatic source deletion is parked per the shared-Git-identity governance ruling; remotely reachable snapshots still leave and report every source.
+- [x] Multi-host push-on-write uses an isolated temporary Git index populated from approved in-memory blobs rather than pathname re-reads, verifies each committed blob ID, the exact changed-path allowlist, and both author/committer trailers before push, then reconciles only approved paths into the real checkout index. Real-repository controls prove a clean checkout remains clean, a concurrent non-fast-forward fetch/rebase/push remains clean and preserves both findings, destination-path substitution cannot change committed bytes, and unrelated pre-staged secret-shaped content remains staged but never enters the published commit.
+- [x] Doctor Git observations preserve three states: `clean`, `dirty`, and `unmeasurable`; failed remote, branch, or status measurements emit hard `brain-git-state-indeterminate` findings rather than mismatch or ready. The boolean-literal guard sweep covered all MB-BRAIN production files in the 20-file PR population: its only remaining `=== false` guard is the non-nullable `isAbsolute()` predicate; no nullable boolean measurement guards remain.
+- [x] Author-run Review 10 and focused 88/88 evidence were declared void when blocker fixes changed the head; neither is an independent gate pass.
+- [ ] Installer shell P7 invocation after C1 + MC-CRED integration; production command is registered but the C1 shell has not yet called it.
+- [ ] Implementation green on merged dependency base.
+- [ ] Independent code review.
+- [ ] Independent security review.
+- [ ] HOMELAB CI terminal green at exact head.
+- [ ] Reviewed PR retargeted to `main` after C1 and MC-CRED; `next` remains non-merging integration only.
+
+## Completion language
+
+After reviewed merge to `main`, only: **believed-fixed, pending jarvis validation**. Issue #1051 remains open until W-jarvis validates the installed result.
@@ -0,0 +1,120 @@
+# RM-03 — CI Queue Guard Repair
+
+- **Task:** RM-03
+- **Issue:** #1019
+- **Branch:** `fix/rm-03-queue-guard`
+- **Owner:** coder-mos1
+- **Reviewer:** rev-974 (independent; author != reviewer)
+- **Started:** 2026-08-01
+
+## Objective
+
+Repair the mandatory CI queue guard so it reads provider payloads, blocks asserted non-green CI, distinguishes provider unavailability from a real non-green result, and inspects the branch actually being pushed or merged.
+
+## Constraints
+
+- Worktree only: `/home/hermes/agent-work/rm-03`; never mutate `/src/mosaic-stack`.
+- JSON payload travels through stdin; never argv. Large payload must remain below no ARG_MAX dependency.
+- TDD is mandatory. Every behavior case must be observed red before implementation.
+- No bypass flags or hook suppression.
+- Do not cite the existing guard's green as evidence; D-23 establishes it is zero-information.
+- Gate-ready is a frozen exact head. Any push after a merge-gate verdict voids that verdict.
+- No merge: coordinator holds the merge hand pending Jason.
+
+## Design
+
+1. Feed JSON to `python3 -c` on stdin, including pending-context rendering.
+2. Classify valid green as `READY`; pending/failure/no-status/malformed/mixed as `ASSERTED_NOT_READY`; provider/credential/transport inability as `CANNOT_ASSERT`.
+3. `ASSERTED_NOT_READY` exits nonzero. `CANNOT_ASSERT` emits a loud diagnostic and appends a local JSONL audit record. Push degrades to exit 0; merge holds with distinct retryable exit 75 until provider recovery, then self-clears without manual reset. Inability to write the audit exits nonzero.
+4. Derive the current branch when `-B` is omitted. The merge wrapper passes the exact PR head branch, repository, and full commit SHA—not its `main` base—so fork PRs cannot resolve against an adjacent base-repository branch.
+
+## Test matrix
+
+| Case | Required outcome |
+| --- | --- |
+| success | exit 0; terminal-success |
+| pending | nonzero after bounded timeout |
+| failure | nonzero |
+| no-status | nonzero |
+| malformed | nonzero |
+| >=150 KiB payload | unchanged classification; never rc126 |
+| provider unreachable on push | loud audited CANNOT_ASSERT; degraded exit 0 |
+| provider unreachable on merge | loud audited CANNOT_ASSERT; retryable exit 75/HOLD |
+| audit unavailable | nonzero |
+| implicit push branch | provider URL uses checked-out feature branch |
+| merge wrapper | queue guard receives exact PR head branch/repository/full SHA |
+
+## RED-first evidence
+
+Observed against the unmodified `origin/main` implementation before source edits:
+
+- `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` → rc 1 with 15 failed assertions.
+- Success payload was reported `state=unknown`.
+- Pending, failure, no-status, and malformed payloads each exited 0 and omitted `ASSERTED_NOT_READY`.
+- The 160 KiB payload produced rc 141 because Python never consumed the pipe; it did not classify success.
+- Provider-unreachable exited 7 with no `CANNOT_ASSERT` audit record.
+- Implicit push queried `/branches/main`, not `/branches/fix/rm-03-fixture`.
+- Audit-unavailable emitted no audit diagnostic.
+- A credential-resolution hard-block mutant was then run before trusting that added case: `credential-unresolvable` returned rc 1 and omitted `CANNOT_ASSERT`; the matrix returned rc 1 with two named assertion failures.
+- Review-blocker controls were observed red: structurally invalid `statuses` string and null-entry payloads each exited 0 as `terminal-success`; unsupported-platform discovery exited 1 without diagnostic or audit (seven named assertion failures total).
+- After the push/merge asymmetry ruling, merge-side provider unavailability was observed red at rc 0; its registered case required distinct retryable rc 75.
+- Aggregate `state=success` with zero contexts was observed red: it exited 0 as `terminal-success`; the registered case requires `no-status`/nonzero.
+- Fork/exact-head controls were observed red: `pr-merge.sh` omitted the fork repository and full SHA, and an ignored-arguments mutant re-resolved through `/branches/` instead of the exact fork commit (two named failures).
+- GitHub check-run-only success/pending/failure were each misclassified as `no-status`; the RED run had five named failures and proved the Checks API was never queried.
+- The first merge-pin control was unrunnable because one `local` declaration referenced a variable before assignment under `set -u`; this was disclosed and corrected rather than counted. The runnable RED then showed Gitea payload `{"Do":"squash"}` lacked `head_commit_id`; a separate GitHub run showed `gh pr merge 123 --squash` lacked `--match-head-commit`.
+- A stale-verdict mutant removed the `--expect-head` comparison and was observed red because a moved head reached the provider merge call.
+- `bash packages/mosaic/framework/tools/git/test-pr-merge-queue-branch.sh` initially returned rc 1; captured call was `--purpose merge -B main -t 900 -i 15`.
+
+Logs remain untracked under the worktree as `.mosaic-test-work-red-*.log` and will not be committed.
+
+## Progress
+
+- [x] Mission, remediation charter, task evidence, board, issue #1019, and superseded PR #1023 read.
+- [x] Isolated worktree created and identity configured coherently.
+- [x] Mutant tests authored and observed red.
+- [x] Implementation green.
+- [x] Baseline and focused situational gates green; full package suite has an unrelated framework-shell environment abort recorded below.
+- [ ] Independent review clean (rev-974 requested changes at `44ffa99a`; bypass remediation committed and awaiting re-review).
+- [ ] PR CI terminal-green at exact head by full step scan.
+- [ ] Merge-gate verdict issued against frozen head.
+
+## Scope disposition
+
+- The five framework guides are consequential documentation: they define the purpose-aware tri-state contract, including audited push degradation and merge HOLD.
+- The agent templates are consequential because they ship the same queue-guard instructions into newly seeded agent contracts; leaving them binary/stale would contradict the repaired tool.
+- `pr-merge.sh` is consequential: it must inspect the PR's exact head branch/repository/SHA and enforce the exact-head merge pin.
+- `pr-metadata.sh` is consequential only as the normalized source of that head branch/repository/SHA. Its diff is limited to exposing those fields on GitHub and Gitea.
+- `test-pr-merge-gitea-empty-uid.sh` changes because exact-head Gitea merges now always use the API path (the only path that can send `head_commit_id`), superseding the prior tea-empty-identity fallback behavior.
+
+## Review remediation
+
+- rev-974 independently proved that the documented `--skip-queue-guard` merge option bypassed an exit-99 guard stub, reached the provider merge payload, printed success, and exited 0 at head `44ffa99a`.
+- RED-first reproduction was added to `test-pr-merge-head-pin.sh` before the production fix: `FAIL merge-bypass: --skip-queue-guard reached the provider merge path`, suite rc 1. The test-only commit is `241113e6`.
+- Production remediation `37aae650` removes the option from parsing, usage, help, and examples. Every merge-capable path now invokes the queue guard; `--dry-run` alone omits it and has a regression proving that it exits before provider dispatch and creates no merge payload.
+- Existing Gitea merge tests now exercise a successful guard response rather than bypassing the guard.
+
+## Risks / boundaries
+
+- The local JSONL audit is durable operational evidence but not tamper-resistant against the same UID. RM-03 does not claim otherwise.
+- Push-side audited exit 0 is an explicit owner ruling (Option B), accepted to avoid bricking recovery work; merge-side CANNOT_ASSERT remains retryable exit 75/HOLD. The automated security reviewer continues to flag the deliberate push availability tradeoff.
+- Source/deployed-copy equality is owned by RM-02/D-22; this branch changes repository source and its tests only.
+
+## Test evidence
+
+Fresh after rescue checkpoint `b7175012`:
+
+- Focused situational matrix: tri-state, GitHub checks pagination, branch-absent, merge head branch/repository/SHA, exact-head pin, and Gitea exact-head API regressions all passed.
+- `bash -n` on the three production shell scripts passed.
+- `shellcheck -x -P packages/mosaic/framework/tools/git ...` on all changed shell scripts passed.
+- `pnpm typecheck` passed (45/45 Turbo tasks).
+- `pnpm lint` passed (25/25 Turbo tasks).
+- `pnpm format:check` passed.
+- `pnpm --filter @mosaicstack/mosaic test`: Vitest passed 1508/1508 on the confirmation run; framework-shell then aborted at the pre-existing wake coordinate assertion with exit 97: `BASH_LINENO ... probe reported [3 5], expected [3 4] ... (#973)`. This is outside the RM-03 diff and is disclosed rather than substituted or called green.
+- The prior package-suite attempt had one transient, out-of-diff `install-ordering-guard.spec.ts` failure (1/1508); its isolated rerun passed 19/19 and the confirmation full Vitest run passed 1508/1508.
+- After bypass remediation: all six focused RM-03 queue/merge regressions passed, including bypass refusal and dry-run non-dispatch; shell syntax and source-aware ShellCheck passed; `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` passed.
+- Fresh `test:framework-shell` reached and passed every RM-03 test, then again aborted at the unrelated wake coordinate assertion with exit 97; it remains explicitly non-green rather than substituted.
+- An ad hoc raw Prettier invocation over `.template` and `.sh` files was unrunnable because no parser is registered for those extensions; it was not used as a substitute for canonical `pnpm format:check`.
+
+## Final evidence
+
+Pending.
@@ -925,14 +925,16 @@ Woodpecker note:
 Before pushing a branch or merging a PR, guard against overlapping project pipelines:

 ```bash
-~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main
-~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main
+~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push
+~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>
 ```

 Behavior:

- If pipeline state is running/queued/pending, wait until queue clears.
- If timeout or API/auth failure occurs, treat as `blocked`, report exact failed wrapper command, and stop.
+- If pipeline state is running/queued/pending, wait until queue clears; timeout is `ASSERTED_NOT_READY` and exits nonzero.
+- Failure, missing status, malformed status, or any other provider-asserted non-green state is `ASSERTED_NOT_READY` and exits nonzero.
+- Credential, transport, or provider unavailability is `CANNOT_ASSERT`: the guard emits a loud diagnostic and durable JSONL audit record. For push it exits 0 so recovery work is not bricked. For merge it returns distinct retryable exit 75 and holds until provider recovery; rerunning then self-clears without manual reset. This result is never evidence that CI was clear. If the audit cannot be written, the guard exits nonzero.
+- `pr-merge.sh` resolves and guards the exact PR head repository and full SHA automatically, including fork PRs.

 ## Gitea as Unified Platform

@@ -13,7 +13,7 @@ Merge strategy enforcement (HARD RULE):
 - PR target for delivery is `main`.
 - Direct pushes to `main` are prohibited.
 - Merge to `main` MUST be squash-only.
- Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash` (or PowerShell equivalent).
+- Use `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}` (or PowerShell equivalent).

 ## Review Checklist

@@ -79,7 +79,7 @@ For implementation work, you MUST run this cycle in order:
 8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. `push` - push immediately after queue guard passes.
 10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
-11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge`.
+11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines on the exact PR head to clear: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/tools/git/pr-ci-wait.sh` for PR-based workflow).
 13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
 14. `greenfield situational test` - validate required user flows in a clean environment/startup path (post-merge for trunk workflow changes).
@@ -93,8 +93,8 @@ For implementation work, you MUST run this cycle in order:
 > the gate (AGENTS.md hard gate "Merge authority"). Solo delivery proceeds
 > without asking.

-1. `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`
-2. `~/.config/mosaic/tools/git/pr-merge.sh -n <PR_NUMBER> -m squash`
+1. `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
+2. `~/.config/mosaic/tools/git/pr-merge.sh -n <PR_NUMBER> -m squash --expect-head <APPROVED_FULL_SHA>`
 3. `~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>`
 4. `~/.config/mosaic/tools/git/issue-close.sh -i <ISSUE_NUMBER>` (or close internal `docs/TASKS.md` ref when no provider exists)
 5. If any step fails: set status `blocked`, report the exact failed wrapper command, and stop.
@@ -425,11 +425,11 @@ git push
    and checklist completed (`~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`) when applicable.
 13. **PR + CI + Issue Closure Gate** (HARD RULE for source-code tasks):
    - Before merging, run queue guard:
-      `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`
+      `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`
    - Ensure PR exists for the task branch (create/update via wrappers if needed):
      `~/.config/mosaic/tools/git/pr-create.sh ... -B main`
    - Merge via wrapper:
-      `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash`
+      `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
    - Wait for terminal CI status:
      `~/.config/mosaic/tools/git/pr-ci-wait.sh -n {PR_NUMBER}`
    - Close linked issue after merge + green CI:
@@ -630,7 +630,7 @@ Construct this from the task row and pass to worker via Task tool:

 **MANDATORY:** This ALWAYS includes linting. If the project has a linter configured
 (ESLint, Biome, ruff, etc.), you MUST run it and fix ALL violations in files you touched.
-Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIRED situational tests based on changed surfaces (see `~/.config/mosaic/guides/E2E-DELIVERY.md` and `~/.config/mosaic/guides/QA-TESTING.md`). 7. If task is bug fix/security/auth/critical business logic, apply REQUIRED TDD discipline per `~/.config/mosaic/guides/QA-TESTING.md`. 8. If gates or required situational tests fail: Fix and retry. Do NOT report success with failures. 9. Commit: `git commit -m "fix({finding_id}): brief description"` 10. Before push, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main` 11. Push: `git push origin {branch}` 12. Report result as JSON (see format below)
+Do NOT leave lint warnings or errors for someone else to clean up. 6. Run REQUIRED situational tests based on changed surfaces (see `~/.config/mosaic/guides/E2E-DELIVERY.md` and `~/.config/mosaic/guides/QA-TESTING.md`). 7. If task is bug fix/security/auth/critical business logic, apply REQUIRED TDD discipline per `~/.config/mosaic/guides/QA-TESTING.md`. 8. If gates or required situational tests fail: Fix and retry. Do NOT report success with failures. 9. Commit: `git commit -m "fix({finding_id}): brief description"` 10. Before push, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {branch}` 11. Push: `git push origin {branch}` 12. Report result as JSON (see format below)

 ## Git Scripts

@@ -638,8 +638,9 @@ For issue/PR/milestone operations, use scripts (NOT raw tea/gh):

 - `~/.config/mosaic/tools/git/issue-view.sh -i {N}`
 - `~/.config/mosaic/tools/git/pr-create.sh -t "Title" -b "Desc" -B main`
- `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`
- `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash`
+- Push: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B {task_branch}`
+- Merge: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B {pr_head_branch} -R {pr_head_owner/repo} --sha {pr_head_full_sha}`
+- `~/.config/mosaic/tools/git/pr-merge.sh -n {PR_NUMBER} -m squash --expect-head {approved_full_sha}`
 - `~/.config/mosaic/tools/git/pr-ci-wait.sh -n {PR_NUMBER}`
 - `~/.config/mosaic/tools/git/issue-close.sh -i {N}`

@@ -23,10 +23,12 @@ Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection a
 # Milestones
 ~/.config/mosaic/tools/git/milestone-create.sh

-# CI queue guard (required before push/merge)
+# CI queue guard (required before push/merge; defaults to the checked-out branch)
 ~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
 ```

+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)

 ```bash
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -88,7 +88,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.

 ## Container Release Strategy (When Applicable)

@@ -147,9 +147,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -97,7 +97,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.


 ## Container Release Strategy (When Applicable)
@@ -198,9 +198,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -101,7 +101,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.


 ## Container Release Strategy (When Applicable)
@@ -230,9 +230,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -87,7 +87,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.

 ## Container Release Strategy (When Applicable)

@@ -146,9 +146,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -84,7 +84,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.

 ## Container Release Strategy (When Applicable)

@@ -136,9 +136,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -9,7 +9,7 @@
 2. Do NOT ask for routine confirmation before required push/merge/issue-close/release/tag actions.
 3. Completion is forbidden at PR-open stage.
 4. Completion requires merged PR to `main` + terminal green CI + linked issue/internal task closed.
-5. Before push or merge, run queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+5. Before push or merge, run the queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.
 6. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/tools/git/*.sh`).
 7. If any required wrapper command fails: report `blocked` with the exact failed wrapper command and stop.
 8. Do NOT stop at "PR created" and do NOT ask "should I merge?" for routine flow.
@@ -85,7 +85,7 @@ Reference:
 5. Do not mark implementation complete until PR is merged.
 6. Do not mark implementation complete until CI/pipeline status is terminal green.
 7. Close linked issues/tasks only after merge + green CI.
-8. Before push or merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge -B main`.
+8. Before push or merge, run the CI queue guard against the push branch or the merge PR's exact head repository/SHA (`ci-queue-wait.sh --help`); `pr-merge.sh` supplies exact merge metadata automatically.

 ## Container Release Strategy (When Applicable)

@@ -133,9 +133,9 @@ Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close
 5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
 6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
 7. Update `docs/TASKS.md` status + issue/internal ref before coding.
-8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B main`.
+8. Before push, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push`.
 9. Open PR to `main` for delivery changes (no direct push to `main`).
-10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`.
+10. Before merge, run CI queue guard: `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B <PR_HEAD_BRANCH> -R <PR_HEAD_OWNER/REPO> --sha <PR_HEAD_FULL_SHA>`.
 11. Merge PRs that pass required checks and review gates with squash strategy only.
 12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
 13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
@@ -7,7 +7,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/detect-platform.sh"

-BRANCH="main"
+BRANCH=""
+TARGET_REPO=""
+HEAD_SHA=""
 TIMEOUT_SEC=900
 INTERVAL_SEC=15
 PURPOSE="merge"
@@ -15,10 +17,12 @@ REQUIRE_STATUS=0

 usage() {
    cat <<EOF
-Usage: $(basename "$0") [-B branch] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status]
+Usage: $(basename "$0") [-B branch] [-R owner/repo] [--sha full-40] [-t timeout_sec] [-i interval_sec] [--purpose push|merge] [--require-status]

 Options:
-  -B, --branch BRANCH      Branch head to inspect (default: main)
+  -B, --branch BRANCH      Branch head to inspect (default: current branch)
+  -R, --repo OWNER/REPO    Repository containing the branch (default: origin repo)
+      --sha FULL_SHA       Inspect this exact 40-character commit instead of resolving the branch
  -t, --timeout SECONDS    Max wait time in seconds (default: 900)
  -i, --interval SECONDS   Poll interval in seconds (default: 15)
      --purpose VALUE      Log context: push|merge (default: merge)
@@ -27,63 +31,65 @@ Options:

 Examples:
  $(basename "$0")
-  $(basename "$0") --purpose push -B main -t 600 -i 10
+  $(basename "$0") --purpose push -t 600 -i 10
 EOF
 }

 # get_remote_host and get_gitea_token are provided by detect-platform.sh

 get_state_from_status_json() {
-    python3 - <<'PY'
+    # Python source comes from -c so the provider payload remains on stdin.
+    # Never move the payload to argv: commit-status responses can exceed ARG_MAX.
+    python3 -c '
 import json
 import sys

 try:
    payload = json.load(sys.stdin)
+    if not isinstance(payload, dict):
+        raise ValueError("status payload is not an object")
 except Exception:
-    print("unknown")
+    print("malformed")
    raise SystemExit(0)

-statuses = payload.get("statuses") or []
-state = (payload.get("state") or "").lower()
+raw_statuses = payload.get("statuses", [])
+raw_state = payload.get("state", "")
+if not isinstance(raw_statuses, list) or not isinstance(raw_state, str):
+    print("malformed")
+    raise SystemExit(0)
+statuses = raw_statuses
+state = raw_state.lower()

 pending_values = {"pending", "queued", "running", "waiting"}
 failure_values = {"failure", "error", "failed"}
 success_values = {"success"}

-if state in pending_values:
-    print("pending")
-    raise SystemExit(0)
-if state in failure_values:
-    print("terminal-failure")
-    raise SystemExit(0)
-if state in success_values:
-    print("terminal-success")
-    raise SystemExit(0)
-
 values = []
 for item in statuses:
    if not isinstance(item, dict):
-        continue
-    value = (item.get("status") or item.get("state") or "").lower()
-    if value:
-        values.append(value)
+        print("malformed")
+        raise SystemExit(0)
+    raw_value = item.get("status") or item.get("state")
+    if not isinstance(raw_value, str) or not raw_value:
+        print("malformed")
+        raise SystemExit(0)
+    values.append(raw_value.lower())

-if not values and not state:
-    print("no-status")
-elif any(v in pending_values for v in values):
+if any(value in pending_values for value in values) or state in pending_values:
    print("pending")
-elif any(v in failure_values for v in values):
+elif any(value in failure_values for value in values) or state in failure_values:
    print("terminal-failure")
-elif values and all(v in success_values for v in values):
+elif values and all(value in success_values for value in values) and state in {"", "success"}:
    print("terminal-success")
+elif not values:
+    print("no-status")
 else:
    print("unknown")
-PY
+'
 }

 print_pending_contexts() {
-    python3 - <<'PY'
+    python3 -c '
 import json
 import sys

@@ -104,17 +110,61 @@ for item in statuses:
    if not isinstance(item, dict):
        continue
    name = item.get("context") or item.get("name") or "unknown-context"
-    value = (item.get("status") or item.get("state") or "unknown").lower()
+    value = str(item.get("status") or item.get("state") or "unknown").lower()
    target = item.get("target_url") or item.get("url") or ""
    if value in pending_values:
        found = True
-        if target:
-            print(f"[ci-queue-wait] pending: {name}={value} ({target})")
-        else:
-            print(f"[ci-queue-wait] pending: {name}={value}")
+        suffix = f" ({target})" if target else ""
+        print(f"[ci-queue-wait] pending: {name}={value}{suffix}")
 if not found:
    print("[ci-queue-wait] no pending contexts")
+'
+}
+
+record_cannot_assert() {
+    local reason="$1"
+    local audit_log="${MOSAIC_CI_QUEUE_AUDIT_LOG:-${XDG_STATE_HOME:-${HOME:-}/.local/state}/mosaic/audit/ci-queue-wait.jsonl}"
+
+    if [[ -z "$audit_log" ]] || ! mkdir -p "$(dirname "$audit_log")"; then
+        echo "Error: CANNOT_ASSERT and audit directory is unavailable; refusing degraded pass." >&2
+        return 70
+    fi
+
+    if ! python3 - "$audit_log" "$reason" "${PLATFORM:-unknown}" "$PURPOSE" "${BRANCH:-unknown}" "${OWNER:-unknown}/${REPO:-unknown}" <<'PY'
+import datetime
+import json
+import os
+import sys
+
+path, reason, platform, purpose, branch, repo = sys.argv[1:]
+record = {
+    "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+    "outcome": "CANNOT_ASSERT",
+    "reason": reason,
+    "platform": platform,
+    "purpose": purpose,
+    "disposition": "hold" if purpose == "merge" else "degraded-pass",
+    "branch": branch,
+    "repo": repo,
+}
+fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+try:
+    os.write(fd, (json.dumps(record, separators=(",", ":")) + "\n").encode())
+finally:
+    os.close(fd)
 PY
+    then
+        echo "Error: CANNOT_ASSERT and audit write failed at ${audit_log}; refusing degraded pass." >&2
+        return 70
+    fi
+
+    if [[ "$PURPOSE" == "merge" ]]; then
+        echo "[ci-queue-wait] CANNOT_ASSERT reason=${reason} purpose=merge branch=${BRANCH:-unknown}; audited=${audit_log}; HOLD (exit 75). Retry after provider recovery; no manual reset is required." >&2
+        return 75
+    fi
+
+    echo "[ci-queue-wait] CANNOT_ASSERT reason=${reason} purpose=push branch=${BRANCH:-unknown}; audited=${audit_log}; push may proceed in degraded mode." >&2
+    return 0
 }

 github_get_branch_head_sha() {
@@ -128,7 +178,87 @@ github_get_commit_status_json() {
    local owner="$1"
    local repo="$2"
    local sha="$3"
-    gh api "repos/${owner}/${repo}/commits/${sha}/status"
+    local work_root status_file checks_file
+    work_root="${AGENT_WORK_ROOT:-${HOME:-}/.cache/mosaic/ci-queue-wait}"
+    mkdir -p "$work_root" || return 1
+    status_file=$(mktemp "$work_root/github-status.XXXXXX") || return 1
+    checks_file=$(mktemp "$work_root/github-checks.XXXXXX") || {
+        rm -f "$status_file"
+        return 1
+    }
+
+    if ! gh api --paginate --slurp "repos/${owner}/${repo}/commits/${sha}/statuses?per_page=100" > "$status_file" ||
+       ! gh api --paginate --slurp "repos/${owner}/${repo}/commits/${sha}/check-runs?per_page=100&filter=latest" > "$checks_file"; then
+        rm -f "$status_file" "$checks_file"
+        return 1
+    fi
+
+    python3 - "$status_file" "$checks_file" <<'PY'
+import json
+import sys
+
+with open(sys.argv[1], encoding="utf-8") as handle:
+    status_pages = json.load(handle)
+with open(sys.argv[2], encoding="utf-8") as handle:
+    check_pages = json.load(handle)
+
+if not isinstance(status_pages, list) or not isinstance(check_pages, list):
+    raise SystemExit(1)
+
+# The statuses endpoint is newest-first and can contain retries for one context.
+# Keep only the newest entry per context after flattening every page.
+combined = []
+seen_contexts = set()
+for page in status_pages:
+    if not isinstance(page, list):
+        raise SystemExit(1)
+    for status in page:
+        if not isinstance(status, dict):
+            raise SystemExit(1)
+        context = status.get("context")
+        if not isinstance(context, str) or not context or context in seen_contexts:
+            continue
+        seen_contexts.add(context)
+        combined.append(status)
+
+check_runs = []
+reported_total = 0
+for page in check_pages:
+    if not isinstance(page, dict):
+        raise SystemExit(1)
+    page_runs = page.get("check_runs") or []
+    total_count = page.get("total_count")
+    if not isinstance(page_runs, list) or not isinstance(total_count, int):
+        raise SystemExit(1)
+    reported_total = max(reported_total, total_count)
+    check_runs.extend(page_runs)
+if len(check_runs) < reported_total:
+    raise SystemExit(1)
+
+for run in check_runs:
+    if not isinstance(run, dict):
+        raise SystemExit(1)
+    status = run.get("status")
+    conclusion = run.get("conclusion")
+    if status != "completed":
+        value = "pending"
+    elif conclusion == "success":
+        value = "success"
+    elif conclusion in {"failure", "cancelled", "timed_out", "action_required", "startup_failure", "stale"}:
+        value = "failure"
+    else:
+        value = "unknown"
+    combined.append({
+        "context": run.get("name") or "github-check",
+        "status": value,
+        "target_url": run.get("html_url") or run.get("details_url") or "",
+    })
+
+json.dump({"state": "", "statuses": combined}, sys.stdout)
+PY
+    local status=$?
+    rm -f "$status_file" "$checks_file"
+    return "$status"
 }

 gitea_get_branch_head_sha() {
@@ -174,6 +304,14 @@ while [[ $# -gt 0 ]]; do
            BRANCH="$2"
            shift 2
            ;;
+        -R|--repo)
+            TARGET_REPO="$2"
+            shift 2
+            ;;
+        --sha)
+            HEAD_SHA="$2"
+            shift 2
+            ;;
        -t|--timeout)
            TIMEOUT_SEC="$2"
            shift 2
@@ -206,45 +344,89 @@ if ! [[ "$TIMEOUT_SEC" =~ ^[0-9]+$ ]] || ! [[ "$INTERVAL_SEC" =~ ^[0-9]+$ ]]; th
    echo "Error: timeout and interval must be integer seconds." >&2
    exit 1
 fi
+if [[ -n "$HEAD_SHA" && ! "$HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
+    echo "Error: --sha must be a full 40-character hexadecimal commit SHA." >&2
+    exit 1
+fi
+if [[ -n "$TARGET_REPO" && ! "$TARGET_REPO" =~ ^[^/[:space:]]+/[^/[:space:]]+$ ]]; then
+    echo "Error: --repo must be OWNER/REPO." >&2
+    exit 1
+fi

-OWNER=$(get_repo_owner)
-REPO=$(get_repo_name)
-detect_platform > /dev/null
+if [[ "$PURPOSE" != "push" && "$PURPOSE" != "merge" ]]; then
+    echo "Error: --purpose must be push or merge." >&2
+    exit 1
+fi
+
+OWNER="unknown"
+REPO="unknown"
+PLATFORM="unknown"
+if ! OWNER=$(get_repo_owner) || [[ -z "$OWNER" ]]; then
+    record_cannot_assert "repository-owner-unresolvable"
+    exit $?
+fi
+if ! REPO=$(get_repo_name) || [[ -z "$REPO" ]]; then
+    record_cannot_assert "repository-name-unresolvable"
+    exit $?
+fi
+if ! detect_platform > /dev/null; then
+    PLATFORM="${PLATFORM:-unknown}"
+    record_cannot_assert "unsupported-platform"
+    exit $?
+fi
 PLATFORM="${PLATFORM:-unknown}"

+if [[ -n "$TARGET_REPO" ]]; then
+    OWNER="${TARGET_REPO%%/*}"
+    REPO="${TARGET_REPO##*/}"
+fi
+
+if [[ -z "$BRANCH" ]]; then
+    if ! BRANCH=$(git symbolic-ref --quiet --short HEAD) || [[ -z "$BRANCH" ]]; then
+        record_cannot_assert "current-branch-unresolvable"
+        exit $?
+    fi
+fi
+
 if [[ "$PLATFORM" == "github" ]]; then
    if ! command -v gh >/dev/null 2>&1; then
-        echo "Error: gh CLI is required for GitHub CI queue guard." >&2
-        exit 1
+        record_cannot_assert "github-cli-unavailable"
+        exit $?
    fi
-    HEAD_SHA=$(github_get_branch_head_sha "$OWNER" "$REPO" "$BRANCH")
    if [[ -z "$HEAD_SHA" ]]; then
-        echo "Error: Could not resolve ${BRANCH} head SHA." >&2
-        exit 1
+        if ! HEAD_SHA=$(github_get_branch_head_sha "$OWNER" "$REPO" "$BRANCH") || [[ -z "$HEAD_SHA" ]]; then
+            record_cannot_assert "branch-head-unavailable"
+            exit $?
+        fi
    fi
    echo "[ci-queue-wait] platform=github purpose=${PURPOSE} branch=${BRANCH} sha=${HEAD_SHA}"
 elif [[ "$PLATFORM" == "gitea" ]]; then
-    HOST=$(get_remote_host) || {
-        echo "Error: Could not determine remote host." >&2
-        exit 1
-    }
-    TOKEN=$(get_gitea_token "$HOST") || {
-        echo "Error: Gitea token not found. Set GITEA_TOKEN or configure ~/.git-credentials." >&2
-        exit 1
-    }
-    HEAD_SHA=$(gitea_get_branch_head_sha "$HOST" "$OWNER/$REPO" "$BRANCH" "$TOKEN")
-    if [[ "$HEAD_SHA" == "__BRANCH_ABSENT__" ]]; then
-        echo "[ci-queue-wait] branch ${BRANCH} not yet on remote — no in-flight pipeline; queue clear."
-        exit 0
+    if ! HOST=$(get_remote_host) || [[ -z "$HOST" ]]; then
+        record_cannot_assert "remote-host-unresolvable"
+        exit $?
+    fi
+    if ! TOKEN=$(get_gitea_token "$HOST") || [[ -z "$TOKEN" ]]; then
+        record_cannot_assert "credential-unresolvable"
+        exit $?
    fi
    if [[ -z "$HEAD_SHA" ]]; then
-        echo "Error: Could not resolve ${BRANCH} head SHA." >&2
-        exit 1
+        if ! HEAD_SHA=$(gitea_get_branch_head_sha "$HOST" "$OWNER/$REPO" "$BRANCH" "$TOKEN"); then
+            record_cannot_assert "branch-head-unavailable"
+            exit $?
+        fi
+        if [[ "$HEAD_SHA" == "__BRANCH_ABSENT__" ]]; then
+            echo "[ci-queue-wait] branch ${BRANCH} not yet on remote — no in-flight pipeline; queue clear."
+            exit 0
+        fi
+        if [[ -z "$HEAD_SHA" ]]; then
+            record_cannot_assert "branch-head-unavailable"
+            exit $?
+        fi
    fi
    echo "[ci-queue-wait] platform=gitea purpose=${PURPOSE} branch=${BRANCH} sha=${HEAD_SHA}"
 else
-    echo "Error: Unsupported platform '${PLATFORM}'." >&2
-    exit 1
+    record_cannot_assert "unsupported-platform"
+    exit $?
 fi

 START_TS=$(date +%s)
@@ -253,14 +435,20 @@ DEADLINE_TS=$((START_TS + TIMEOUT_SEC))
 while true; do
    NOW_TS=$(date +%s)
    if (( NOW_TS > DEADLINE_TS )); then
-        echo "Error: Timed out waiting for CI queue to clear on ${BRANCH} after ${TIMEOUT_SEC}s." >&2
+        echo "Error: ASSERTED_NOT_READY state=pending; timed out waiting for CI queue to clear on ${BRANCH} after ${TIMEOUT_SEC}s." >&2
        exit 124
    fi

    if [[ "$PLATFORM" == "github" ]]; then
-        STATUS_JSON=$(github_get_commit_status_json "$OWNER" "$REPO" "$HEAD_SHA")
+        if ! STATUS_JSON=$(github_get_commit_status_json "$OWNER" "$REPO" "$HEAD_SHA"); then
+            record_cannot_assert "status-provider-unreachable"
+            exit $?
+        fi
    else
-        STATUS_JSON=$(gitea_get_commit_status_json "$HOST" "$OWNER/$REPO" "$HEAD_SHA" "$TOKEN")
+        if ! STATUS_JSON=$(gitea_get_commit_status_json "$HOST" "$OWNER/$REPO" "$HEAD_SHA" "$TOKEN"); then
+            record_cannot_assert "status-provider-unreachable"
+            exit $?
+        fi
    fi

    STATE=$(printf '%s' "$STATUS_JSON" | get_state_from_status_json)
@@ -271,21 +459,24 @@ while true; do
            printf '%s' "$STATUS_JSON" | print_pending_contexts
            sleep "$INTERVAL_SEC"
            ;;
+        terminal-success)
+            exit 0
+            ;;
        no-status)
            if [[ "$REQUIRE_STATUS" -eq 1 ]]; then
-                echo "Error: No CI status contexts found for ${BRANCH} while --require-status is set." >&2
-                exit 1
+                echo "Error: ASSERTED_NOT_READY state=no-status; --require-status was set for ${BRANCH}." >&2
+            else
+                echo "Error: ASSERTED_NOT_READY state=no-status purpose=${PURPOSE} branch=${BRANCH}." >&2
            fi
-            echo "[ci-queue-wait] no status contexts present; proceeding."
-            exit 0
+            exit 3
            ;;
-        terminal-success|terminal-failure|unknown)
-            # Queue guard only blocks on pending/running/queued states.
-            exit 0
+        terminal-failure|malformed|unknown)
+            echo "Error: ASSERTED_NOT_READY state=${STATE} purpose=${PURPOSE} branch=${BRANCH}." >&2
+            exit 3
            ;;
        *)
-            echo "[ci-queue-wait] unrecognized state '${STATE}', proceeding conservatively."
-            exit 0
+            echo "Error: ASSERTED_NOT_READY unrecognized-state=${STATE} purpose=${PURPOSE} branch=${BRANCH}." >&2
+            exit 3
            ;;
    esac
 done
@@ -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] [--skip-queue-guard]
+# Usage: pr-merge.sh -n PR_NUMBER [-m squash] [-d]

 set -euo pipefail

@@ -12,8 +12,8 @@ source "$SCRIPT_DIR/detect-platform.sh"
 PR_NUMBER=""
 MERGE_METHOD="squash"
 DELETE_BRANCH=false
-SKIP_QUEUE_GUARD=false
 DRY_RUN=false
+EXPECT_HEAD=""

 usage() {
    cat <<EOF
@@ -25,15 +25,14 @@ Options:
    -n, --number NUMBER     PR number to merge (required)
    -m, --method METHOD     Merge method: squash only (default: squash)
    -d, --delete-branch     Delete the head branch after merge
-        --skip-queue-guard  Skip CI queue guard wait before merge
        --dry-run           Run metadata/login preflight without merging
+        --expect-head SHA   Refuse unless the PR head matches this full commit SHA
    -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 --skip-queue-guard # Skip queue guard wait
 EOF
    exit "${1:-1}"
 }
@@ -53,15 +52,14 @@ while [[ $# -gt 0 ]]; do
            DELETE_BRANCH=true
            shift
            ;;
-        --skip-queue-guard)
-            SKIP_QUEUE_GUARD=true
-            shift
-            ;;
        --dry-run)
            DRY_RUN=true
-            SKIP_QUEUE_GUARD=true
            shift
            ;;
+        --expect-head)
+            EXPECT_HEAD="$2"
+            shift 2
+            ;;
        -h|--help)
            usage 0
            ;;
@@ -86,18 +84,36 @@ if [[ "$MERGE_METHOD" != "squash" ]]; then
    echo "Error: Mosaic policy enforces squash merge only. Received '$MERGE_METHOD'." >&2
    exit 1
 fi
+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

 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())')"
 if [[ "$BASE_BRANCH" != "main" ]]; then
    echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
    exit 1
 fi

-if [[ "$SKIP_QUEUE_GUARD" != true ]]; then
+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
+fi
+if [[ -n "$EXPECT_HEAD" && "$HEAD_SHA" != "$EXPECT_HEAD" ]]; then
+    echo "Error: PR head moved: expected $EXPECT_HEAD, found $HEAD_SHA." >&2
+    exit 1
+fi
+
+if [[ "$DRY_RUN" != true ]]; then
    "$SCRIPT_DIR/ci-queue-wait.sh" \
        --purpose merge \
-        -B "$BASE_BRANCH" \
+        -B "$HEAD_BRANCH" \
+        -R "$HEAD_REPO" \
+        --sha "$HEAD_SHA" \
        -t "${MOSAIC_CI_QUEUE_TIMEOUT_SEC:-900}" \
        -i "${MOSAIC_CI_QUEUE_POLL_SEC:-15}"
 fi
@@ -106,31 +122,22 @@ PLATFORM=$(detect_platform)
 OWNER=$(get_repo_owner)
 REPO=$(get_repo_name)

-is_known_tea_empty_identity_failure() {
-    local error_file="$1"
-
-    python3 - "$error_file" <<'PY'
-import re
-import sys
-
-with open(sys.argv[1], encoding="utf-8", errors="replace") as handle:
-    error = handle.read()
-
-known_empty_identity = re.search(
-    r"user does not exist.*\[.*uid:\s*0,\s*name:\s*\]",
-    error,
-    flags=re.IGNORECASE | re.DOTALL,
-)
-raise SystemExit(0 if known_empty_identity else 1)
-PY
-}
-
 merge_gitea_with_api() {
    local host="$1" api_url token basic_auth body_file raw_code payload
    api_url="https://${host}/api/v1/repos/${OWNER}/${REPO}/pulls/${PR_NUMBER}/merge"
    mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
    body_file=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-api-response.XXXXXX")
-    payload='{"Do":"squash"}'
+    payload=$(python3 - "$HEAD_SHA" "$DELETE_BRANCH" <<'PY'
+import json
+import sys
+
+head_sha, delete_branch = sys.argv[1:]
+payload = {"Do": "squash", "head_commit_id": head_sha}
+if delete_branch == "true":
+    payload["delete_branch_after_merge"] = True
+print(json.dumps(payload, separators=(",", ":")))
+PY
+)

    token=$(get_gitea_token "$host" || true)
    if [[ -n "$token" ]]; then
@@ -202,7 +209,7 @@ fi

 case "$PLATFORM" in
    github)
-        cmd=(gh pr merge "$PR_NUMBER" --squash)
+        cmd=(gh pr merge "$PR_NUMBER" --squash --match-head-commit "$HEAD_SHA")
        [[ "$DELETE_BRANCH" == true ]] && cmd+=(--delete-branch)
        "${cmd[@]}"
        ;;
@@ -211,32 +218,9 @@ case "$PLATFORM" in
            echo "Error: Cannot determine host from origin remote URL" >&2
            exit 1
        }
-        TEA_LOGIN="$(get_gitea_login_for_host "$HOST" || true)"
-
-        if [[ -n "$TEA_LOGIN" ]]; then
-            mkdir -p "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}"
-            TEA_ERROR_FILE=$(mktemp "${AGENT_WORK_ROOT:-${HOME:-/tmp}/mosaic/agent-work}/pr-merge-tea-error.XXXXXX")
-            if tea pr merge "$PR_NUMBER" --style squash --repo "$OWNER/$REPO" --login "$TEA_LOGIN" 2> "$TEA_ERROR_FILE"; then
-                rm -f "$TEA_ERROR_FILE"
-            elif is_known_tea_empty_identity_failure "$TEA_ERROR_FILE"; then
-                cat "$TEA_ERROR_FILE" >&2
-                echo "Known tea empty identity failure detected; using authenticated Gitea API merge fallback." >&2
-                rm -f "$TEA_ERROR_FILE"
-                merge_gitea_with_api "$HOST"
-            else
-                cat "$TEA_ERROR_FILE" >&2
-                rm -f "$TEA_ERROR_FILE"
-                exit 1
-            fi
-        else
-            echo "No tea login configured for $HOST; using authenticated Gitea API merge fallback." >&2
-            merge_gitea_with_api "$HOST"
-        fi
-
-        # Delete branch after merge if requested
-        if [[ "$DELETE_BRANCH" == true ]]; then
-            echo "Note: Branch deletion after merge may need to be done separately with tea" >&2
-        fi
+        # 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.
+        merge_gitea_with_api "$HOST"
        ;;
    *)
        echo "Error: Could not detect git platform" >&2
@@ -109,7 +109,7 @@ PY
 detect_platform > /dev/null

 if [[ "$PLATFORM" == "github" ]]; then
-    METADATA=$(gh pr view "$PR_NUMBER" --json number,title,body,state,author,headRefName,baseRefName,files,labels,assignees,milestone,createdAt,updatedAt,url,isDraft)
+    METADATA=$(gh pr view "$PR_NUMBER" --json number,title,body,state,author,headRefName,headRefOid,headRepository,baseRefName,files,labels,assignees,milestone,createdAt,updatedAt,url,isDraft)
    write_metadata "$METADATA"
 elif [[ "$PLATFORM" == "gitea" ]]; then
    OWNER=$(get_repo_owner)
@@ -182,6 +182,25 @@ if isinstance(head_ref, str) and head_ref.startswith('refs/pull/'):
        data.get('head_ref'),
        head_ref,
    )
+head_sha = first_non_empty(
+    nested(data, 'head', 'sha'),
+    nested(data, 'head', 'id'),
+    data.get('head_sha'),
+)
+head_repo = first_non_empty(
+    nested(data, 'head', 'repo', 'full_name'),
+    nested(data, 'head', 'repo', 'name_with_owner'),
+)
+if not head_repo:
+    head_repo_owner = first_non_empty(
+        nested(data, 'head', 'repo', 'owner', 'login'),
+        nested(data, 'head', 'repo', 'owner', 'username'),
+        nested(data, 'head', 'repo', 'owner_name'),
+    )
+    head_repo_name = first_non_empty(nested(data, 'head', 'repo', 'name'))
+    if head_repo_owner and head_repo_name:
+        head_repo = f'{head_repo_owner}/{head_repo_name}'
+
 base_ref = first_non_empty(
    nested(data, 'base', 'ref'),
    nested(data, 'base', 'name'),
@@ -207,6 +226,8 @@ normalized = {
    'state': data.get('state'),
    'author': nested(data, 'user', 'login') or '',
    'headRefName': head_ref,
+    'headRefOid': head_sha,
+    'headRepository': head_repo,
    'baseRefName': base_ref,
    'labels': [l.get('name', '') for l in data.get('labels', []) if isinstance(l, dict)],
    'assignees': [a.get('login', '') for a in data.get('assignees', []) if isinstance(a, dict)],
@@ -13,7 +13,7 @@
 # Covers:
 #   (a) 404 branch-absent          -> exit 0, "queue clear" message.
 #   (b) 200 existing branch + a terminal CI state -> unchanged behavior.
-#   (c) genuine API error (500)    -> still fail-closed (nonzero exit).
+#   (c) genuine API error (500)    -> loud, audited CANNOT_ASSERT; degraded exit 0.

 set -euo pipefail

@@ -62,7 +62,7 @@ case "$mode" in
    200)  code=200; body='{"commit":{"id":"deadbeefcafef00d0123456789abcdef01234567"}}' ;;
    500)  code=500; body='{"message":"internal server error"}' ;;
    no-status)         code=200; body='{}' ;;
-    terminal-success)  code=200; body='{"state":"success"}' ;;
+    terminal-success)  code=200; body='{"state":"success","statuses":[{"status":"success"}]}' ;;
    *)
        echo "curl stub: unknown mode=$mode" >&2
        exit 2
@@ -91,6 +91,7 @@ run_ci_queue_wait() {
        export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
        export GITEA_TOKEN="stub-token"
        export GITEA_URL="https://git.example.test"
+        export MOSAIC_CI_QUEUE_AUDIT_LOG="$WORK_DIR/audit/ci-queue-wait.jsonl"
        "$SCRIPT_DIR/ci-queue-wait.sh" -B "$branch" --purpose push -t 5 -i 1
    )
 }
@@ -131,19 +132,26 @@ elif [[ "$out_b" == *"queue clear"* ]]; then
    fail=1
 fi

-# (c) genuine API error (500) -> still fail-closed, exit nonzero.
+# (c) genuine API error (500) -> CANNOT_ASSERT is loud and audited, but does not brick delivery.
 set +e
 out_c=$(MOSAIC_STUB_BRANCH_MODE=500 run_ci_queue_wait "feat/some-branch" 2>&1)
 status_c=$?
 set -e
-if [[ "$status_c" -eq 0 ]]; then
-    echo "FAIL(c): expected a nonzero exit for a genuine 500 API error, got 0" >&2
+if [[ "$status_c" -ne 0 ]]; then
+    echo "FAIL(c): expected degraded exit 0 for provider unavailability, got $status_c" >&2
+    echo "$out_c" >&2
+    fail=1
+elif [[ "$out_c" != *"CANNOT_ASSERT"* ]]; then
+    echo "FAIL(c): expected a loud CANNOT_ASSERT diagnostic" >&2
    echo "$out_c" >&2
    fail=1
 elif [[ "$out_c" == *"queue clear"* ]]; then
    echo "FAIL(c): a genuine API error must not be reported as queue-clear" >&2
    echo "$out_c" >&2
    fail=1
+elif [[ ! -s "$WORK_DIR/audit/ci-queue-wait.jsonl" ]]; then
+    echo "FAIL(c): expected a durable CANNOT_ASSERT audit record" >&2
+    fail=1
 fi

 if [[ "$fail" -eq 0 ]]; then
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# GitHub Actions uses Checks API check-runs, not only legacy commit statuses.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/ci-queue-wait-github-checks}"
+REPO_DIR="$WORK_DIR/repo"
+STUB_DIR="$WORK_DIR/stubs"
+rm -rf "$WORK_DIR"
+mkdir -p "$REPO_DIR" "$STUB_DIR"
+git -C "$REPO_DIR" init -q
+git -C "$REPO_DIR" checkout -q -b fix/github-checks
+git -C "$REPO_DIR" remote add origin https://github.com/acme/widgets.git
+
+cat > "$STUB_DIR/gh" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+endpoint=""
+for arg in "$@"; do
+    [[ "$arg" == repos/* ]] && endpoint="$arg"
+done
+printf '%s\n' "$*" >> "${MOSAIC_GH_CALL_LOG:?}"
+case "$endpoint" in
+    repos/acme/widgets/branches/fix/github-checks)
+        printf '%s\n' '0123456789abcdef0123456789abcdef01234567'
+        ;;
+    repos/acme/widgets/commits/*/statuses?per_page=100)
+        printf '%s\n' '[[]]'
+        ;;
+    repos/acme/widgets/commits/*/check-runs?per_page=100\&filter=latest)
+        case "${MOSAIC_GH_CHECK_MODE:?}" in
+            success) printf '%s\n' '[{"total_count":1,"check_runs":[{"name":"ci","status":"completed","conclusion":"success"}]}]' ;;
+            pending) printf '%s\n' '[{"total_count":1,"check_runs":[{"name":"ci","status":"in_progress","conclusion":null}]}]' ;;
+            failure) printf '%s\n' '[{"total_count":1,"check_runs":[{"name":"ci","status":"completed","conclusion":"failure"}]}]' ;;
+            late-failure) printf '%s\n' '[{"total_count":2,"check_runs":[{"name":"first-page","status":"completed","conclusion":"success"}]},{"total_count":2,"check_runs":[{"name":"later-page","status":"completed","conclusion":"failure"}]}]' ;;
+            *) exit 2 ;;
+        esac
+        ;;
+    *) echo "unexpected gh endpoint: $endpoint" >&2; exit 2 ;;
+esac
+SH
+chmod +x "$STUB_DIR/gh"
+
+run_guard() {
+    local mode="$1"
+    (
+        cd "$REPO_DIR" || exit
+        export PATH="$STUB_DIR:$PATH"
+        export MOSAIC_GH_CHECK_MODE="$mode"
+        export MOSAIC_GH_CALL_LOG="$WORK_DIR/gh-calls.log"
+        export MOSAIC_CI_QUEUE_AUDIT_LOG="$WORK_DIR/audit.jsonl"
+        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose push -t 0 -i 0
+    )
+}
+
+failures=0
+assert_case() {
+    local mode="$1" expected_rc="$2" expected_state="$3" output rc
+    set +e
+    output=$(run_guard "$mode" 2>&1)
+    rc=$?
+    set -e
+    if [[ "$expected_rc" == zero && "$rc" -ne 0 ]]; then
+        echo "FAIL github-$mode: expected rc=0, got $rc" >&2
+        failures=$((failures + 1))
+    elif [[ "$expected_rc" == nonzero && "$rc" -eq 0 ]]; then
+        echo "FAIL github-$mode: expected rc!=0, got 0" >&2
+        failures=$((failures + 1))
+    fi
+    if [[ "$output" != *"state=$expected_state"* ]]; then
+        echo "FAIL github-$mode: expected state=$expected_state, got:" >&2
+        printf '%s\n' "$output" >&2
+        failures=$((failures + 1))
+    fi
+}
+
+set -e
+: > "$WORK_DIR/gh-calls.log"
+assert_case success zero terminal-success
+assert_case pending nonzero pending
+assert_case failure nonzero terminal-failure
+assert_case late-failure nonzero terminal-failure
+
+if [[ $(grep -c 'check-runs?per_page=100&filter=latest' "$WORK_DIR/gh-calls.log") -lt 4 ]]; then
+    echo "FAIL: expected every case to query all Checks API pages" >&2
+    failures=$((failures + 1))
+fi
+
+if [[ "$failures" -ne 0 ]]; then
+    echo "GitHub check-runs regression failed ($failures assertions)" >&2
+    exit 1
+fi
+
+echo "GitHub check-runs regression passed (4/4 cases, including later-page failure)"
@@ -0,0 +1,364 @@
+#!/usr/bin/env bash
+# Exit-asserting RM-03 regression harness for ci-queue-wait.sh.
+# Every case is a process-level assertion: a classifier-only green cannot satisfy it.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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
+
+cat > "$STUB_DIR/curl" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+url=""
+has_write_out=0
+for arg in "$@"; do
+    case "$arg" in
+        -w) has_write_out=1 ;;
+        http://*|https://*) url="$arg" ;;
+    esac
+done
+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
+        body='{"commit":{"id":"deadbeefcafef00d0123456789abcdef01234567"}}'
+        if [[ "$has_write_out" -eq 1 ]]; then
+            printf '%s\n200' "$body"
+        else
+            printf '%s' "$body"
+        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"}]}' ;;
+            failure)   printf '%s' '{"state":"failure","statuses":[{"status":"failure"}]}' ;;
+            no-status) printf '%s' '{"state":"","statuses":[]}' ;;
+            aggregate-success-no-status) printf '%s' '{"state":"success","statuses":[]}' ;;
+            malformed) printf '%s' 'not-json' ;;
+            malformed-statuses-type) printf '%s' '{"state":"success","statuses":"corrupt"}' ;;
+            malformed-status-entry) printf '%s' '{"state":"success","statuses":[null]}' ;;
+            large-success)
+                python3 -c 'import json; print(json.dumps({"state":"success", "statuses":[{"status":"success"}], "padding":"x" * (160 * 1024)}), end="")'
+                ;;
+            unreachable) exit 7 ;;
+            *) echo "unknown status mode" >&2; exit 2 ;;
+        esac
+        ;;
+    *) echo "unexpected curl URL: $url" >&2; exit 2 ;;
+esac
+SH
+
+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"
+    local audit_log="${2:-$AUDIT_LOG}"
+    shift 2 || true
+    (
+        cd "$REPO_DIR" || exit
+        export PATH="$STUB_DIR:$PATH"
+        export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+        if [[ "$status_mode" == "credential-unresolvable" ]]; then
+            export HOME="$WORK_DIR/empty-home"
+            mkdir -p "$HOME"
+            unset GITEA_TOKEN GITEA_URL MOSAIC_GIT_IDENTITY
+            export MOSAIC_STUB_STATUS_MODE=success
+        else
+            export GITEA_TOKEN=stub-token
+            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"
+        # 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
+    shift 4
+    set +e
+    output=$(run_guard "$status_mode" "$AUDIT_LOG" "$@" 2>&1)
+    rc=$?
+    set -e
+
+    case "$expected_rc" in
+        zero)
+            if [[ "$rc" -ne 0 ]]; then
+                echo "FAIL $name: expected rc=0, got rc=$rc" >&2
+                failures=$((failures + 1))
+            fi
+            ;;
+        nonzero)
+            if [[ "$rc" -eq 0 ]]; then
+                echo "FAIL $name: expected rc!=0, got rc=0" >&2
+                failures=$((failures + 1))
+            fi
+            ;;
+        not126)
+            if [[ "$rc" -eq 126 ]]; then
+                echo "FAIL $name: payload transport hit ARG_MAX (rc=126)" >&2
+                failures=$((failures + 1))
+            fi
+            ;;
+    esac
+    if [[ "$output" != *"$required_text"* ]]; then
+        echo "FAIL $name: output missing '$required_text' (rc=$rc)" >&2
+        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
+: > "$WORK_DIR/urls.log"
+run_assertion success zero success 'state=terminal-success'
+run_assertion pending nonzero pending 'ASSERTED_NOT_READY'
+run_assertion failure nonzero failure 'ASSERTED_NOT_READY'
+run_assertion no-status nonzero no-status 'ASSERTED_NOT_READY'
+run_assertion aggregate-success-no-status nonzero aggregate-success-no-status 'ASSERTED_NOT_READY'
+run_assertion malformed nonzero malformed 'ASSERTED_NOT_READY'
+run_assertion malformed-statuses-type nonzero malformed-statuses-type 'ASSERTED_NOT_READY'
+run_assertion malformed-status-entry nonzero malformed-status-entry 'ASSERTED_NOT_READY'
+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))
+fi
+
+# Merge cannot proceed without exact-head evidence. CANNOT_ASSERT is retryable exit 75,
+# distinct from ASSERTED_NOT_READY (3/124), and still writes its audit record.
+merge_audit_lines_before=$(wc -l < "$AUDIT_LOG")
+set +e
+merge_unreachable_output=$(MOSAIC_TEST_PURPOSE=merge run_guard unreachable "$AUDIT_LOG" 2>&1)
+merge_unreachable_rc=$?
+set -e
+if [[ "$merge_unreachable_rc" -ne 75 ]]; then
+    echo "FAIL merge-provider-unreachable: expected rc=75, got rc=$merge_unreachable_rc" >&2
+    failures=$((failures + 1))
+fi
+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
+    failures=$((failures + 1))
+fi
+
+# A feature-branch push with no -B must inspect the checked-out feature branch.
+if ! grep -q "/branches/$FEATURE_BRANCH" "$WORK_DIR/urls.log"; then
+    echo "FAIL implicit-branch: provider was not queried for $FEATURE_BRANCH" >&2
+    failures=$((failures + 1))
+fi
+
+# Merge callers can pin both a fork repository and the exact reviewed head SHA.
+exact_sha=0123456789abcdef0123456789abcdef01234567
+: > "$WORK_DIR/urls.log"
+run_assertion exact-fork-head zero success 'state=terminal-success' \
+    -B fix/rm-03-fixture -R contributor/widgets-fork --sha "$exact_sha"
+if ! grep -q "/repos/contributor/widgets-fork/commits/$exact_sha/status" "$WORK_DIR/urls.log"; then
+    echo "FAIL exact-fork-head: status URL did not bind fork repository and exact SHA" >&2
+    failures=$((failures + 1))
+fi
+if grep -q '/branches/' "$WORK_DIR/urls.log"; then
+    echo "FAIL exact-fork-head: explicit SHA must not be re-resolved through a branch" >&2
+    failures=$((failures + 1))
+fi
+
+# Platform/repository discovery failures use the same audited CANNOT_ASSERT path.
+audit_lines_before=$(wc -l < "$AUDIT_LOG")
+git -C "$REPO_DIR" remote set-url origin https://gitlab.com/acme/widgets.git
+set +e
+unsupported_output=$(run_guard success "$AUDIT_LOG" 2>&1)
+unsupported_rc=$?
+set -e
+git -C "$REPO_DIR" remote set-url origin https://git.example.test/acme/widgets.git
+if [[ "$unsupported_rc" -ne 0 ]]; then
+    echo "FAIL unsupported-platform: expected degraded rc=0, got rc=$unsupported_rc" >&2
+    failures=$((failures + 1))
+fi
+if [[ "$unsupported_output" != *"CANNOT_ASSERT"* ]]; then
+    echo "FAIL unsupported-platform: expected loud CANNOT_ASSERT diagnostic" >&2
+    failures=$((failures + 1))
+fi
+audit_lines_after=$(wc -l < "$AUDIT_LOG")
+if [[ "$audit_lines_after" -le "$audit_lines_before" ]]; then
+    echo "FAIL unsupported-platform: expected an additional audit record" >&2
+    failures=$((failures + 1))
+fi
+
+# A degraded pass is forbidden if the audit receipt cannot be written.
+mkdir -p "$WORK_DIR/not-a-directory"
+printf 'file' > "$WORK_DIR/not-a-directory/parent"
+set +e
+audit_failure_output=$(run_guard unreachable "$WORK_DIR/not-a-directory/parent/audit.jsonl" 2>&1)
+audit_failure_rc=$?
+set -e
+if [[ "$audit_failure_rc" -eq 0 ]]; then
+    echo "FAIL audit-unavailable: expected rc!=0, got rc=0" >&2
+    failures=$((failures + 1))
+fi
+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
+    exit 1
+fi
+
+echo "ci-queue-wait tri-state regression passed (all outcome classes)"
@@ -1,5 +1,5 @@
 #!/bin/bash
-# Regression harness for pr-merge.sh Gitea non-interactive tea empty identity fallback.
+# Regression harness for pr-merge.sh Gitea exact-head API path and input safety.

 set -euo pipefail

@@ -79,15 +79,24 @@ emit_response() {
        printf '200'
    fi
 }
+if [[ "$args" == *"/api/v1/repos/mosaicstack/stack/commits/0123456789abcdef0123456789abcdef01234567/status"* ]]; then
+    emit_response '{"state":"success","statuses":[{"context":"ci/test","status":"success"}]}'
+    exit 0
+fi
 if [[ "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123"* && "$args" != *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
-    emit_response '{"number":123,"title":"mock","state":"open","user":{"login":"tester"},"head":{"ref":"feature/mock"},"base":{"ref":"main"},"labels":[],"assignees":[],"html_url":"https://git.mosaicstack.dev/mosaicstack/stack/pulls/123","mergeable":true}'
+    emit_response '{"number":123,"title":"mock","state":"open","user":{"login":"tester"},"head":{"ref":"feature/mock","sha":"0123456789abcdef0123456789abcdef01234567","repo":{"full_name":"mosaicstack/stack"}},"base":{"ref":"main"},"labels":[],"assignees":[],"html_url":"https://git.mosaicstack.dev/mosaicstack/stack/pulls/123","mergeable":true}'
    exit 0
 fi
 if [[ "$args" == *"-X POST"* && "$args" == *"/api/v1/repos/mosaicstack/stack/pulls/123/merge"* ]]; then
-    if [[ "$post_data" != '{"Do":"squash"}' ]]; then
-        echo "unexpected merge payload: $post_data" >&2
-        exit 96
-    fi
+    POST_DATA="$post_data" python3 - <<'PY'
+import json
+import os
+payload = json.loads(os.environ["POST_DATA"])
+assert payload == {
+    "Do": "squash",
+    "head_commit_id": "0123456789abcdef0123456789abcdef01234567",
+}, payload
+PY
    emit_response '{"merged":true,"message":"mock merge complete"}'
    exit 0
 fi
@@ -107,8 +116,8 @@ export GITEA_URL="https://git.mosaicstack.dev"
 export GITEA_TOKEN="redacted-test-token"

 OUTPUT="$SANDBOX/output.log"
-if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected pr-merge.sh to recover via Gitea API fallback." >&2
+if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash > "$OUTPUT" 2>&1; then
+    echo "Expected pr-merge.sh to use the exact-head Gitea API path." >&2
    echo "--- output ---" >&2
    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
    echo "--- mock log ---" >&2
@@ -127,38 +136,6 @@ if grep -q 'redacted-test-token' "$OUTPUT"; then
    exit 1
 fi

-cat > "$MOCK_BIN/tea" <<'EOF'
-#!/bin/bash
-set -euo pipefail
-printf 'tea %q ' "$@" >> "$PR_MERGE_TEST_LOG"
-printf '\n' >> "$PR_MERGE_TEST_LOG"
-if [[ "$*" == *"login list"* ]]; then
-    echo '[{"name":"git.mosaicstack.dev","url":"https://git.mosaicstack.dev"}]'
-    exit 0
-fi
-if [[ "$*" == *"pr merge"* ]]; then
-    echo 'tea network timeout' >&2
-    exit 2
-fi
-exit 0
-EOF
-chmod +x "$MOCK_BIN/tea"
-: > "$LOG_FILE"
-if "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected arbitrary tea failure to remain blocking." >&2
-    exit 1
-fi
-if grep -q '/api/v1/repos/mosaicstack/stack/pulls/123/merge' "$LOG_FILE"; then
-    echo "Arbitrary tea failure unexpectedly used Gitea API merge fallback." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
-    exit 1
-fi
-if ! grep -q 'tea network timeout' "$OUTPUT"; then
-    echo "Expected arbitrary tea error to be preserved in output." >&2
-    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
-    exit 1
-fi
-
 cat > "$MOCK_BIN/tea" <<'EOF'
 #!/bin/bash
 set -euo pipefail
@@ -177,8 +154,8 @@ EOF
 chmod +x "$MOCK_BIN/tea"
 unset GITEA_LOGIN
 : > "$LOG_FILE"
-if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
-    echo "Expected missing tea login to use authenticated Gitea API fallback." >&2
+if ! "$SCRIPT_DIR/pr-merge.sh" -n 123 -m squash > "$OUTPUT" 2>&1; then
+    echo "Expected the exact-head API path not to depend on a tea login." >&2
    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
    sed 's/redacted-test-token/***REDACTED***/g' "$LOG_FILE" >&2
    exit 1
@@ -215,7 +192,7 @@ cd "$REPO_DIR"
 git remote set-url origin https://github.com/mosaicstack/stack.git
 : > "$LOG_FILE"
 rm -f "$SENTINEL"
-if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash > "$OUTPUT" 2>&1; then
    echo "Expected GitHub metacharacter PR number to be rejected." >&2
    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
    exit 1
@@ -240,7 +217,7 @@ git remote set-url origin https://git.mosaicstack.dev/mosaicstack/stack.git
 export GITEA_LOGIN="git.mosaicstack.dev"
 : > "$LOG_FILE"
 rm -f "$SENTINEL"
-if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash --skip-queue-guard > "$OUTPUT" 2>&1; then
+if "$SCRIPT_DIR/pr-merge.sh" -n "$INJECTION" -m squash > "$OUTPUT" 2>&1; then
    echo "Expected Gitea metacharacter PR number to be rejected." >&2
    sed 's/redacted-test-token/***REDACTED***/g' "$OUTPUT" >&2
    exit 1
@@ -260,4 +237,4 @@ if ! grep -q 'Invalid PR number' "$OUTPUT"; then
    exit 1
 fi

-echo "pr-merge.sh Gitea fallback regression passed"
+echo "pr-merge.sh Gitea exact-head API regression passed"
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# shellcheck disable=SC2030,SC2031 # Provider arms isolate PATH/credentials in subshells.
+# The commit whose CI was guarded must be the commit the provider atomically merges.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-head-pin}"
+SHA=0123456789abcdef0123456789abcdef01234567
+
+make_fixture() {
+    local name="$1" remote="$2"
+    local root="$WORK_DIR/$name"
+    local tools="$root/tools/git"
+    mkdir -p "$tools" "$root/repo"
+    cp "$SCRIPT_DIR/pr-merge.sh" "$tools/pr-merge.sh"
+    cp "$SCRIPT_DIR/detect-platform.sh" "$tools/detect-platform.sh"
+    git -C "$root/repo" init -q
+    git -C "$root/repo" remote add origin "$remote"
+    cat > "$tools/pr-metadata.sh" <<SH
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"main","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"contributor/widgets-fork"}'
+SH
+    cat > "$tools/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+    chmod +x "$tools"/*.sh
+}
+
+rm -rf "$WORK_DIR"
+make_fixture gitea https://git.example.test/acme/widgets.git
+make_fixture github https://github.com/acme/widgets.git
+
+cat > "$WORK_DIR/gitea/curl" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+payload=""
+for ((i=1; i<=$#; i++)); do
+    if [[ "${!i}" == "-d" ]]; then
+        j=$((i + 1))
+        payload="${!j}"
+    fi
+done
+printf '%s' "$payload" > "${MOSAIC_MERGE_PAYLOAD_LOG:?}"
+printf '200'
+SH
+chmod +x "$WORK_DIR/gitea/curl"
+
+set +e
+(
+    cd "$WORK_DIR/gitea/repo"
+    export PATH="$WORK_DIR/gitea:$PATH"
+    export GITEA_TOKEN=stub-token
+    export GITEA_URL=https://git.example.test
+    export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+    export MOSAIC_MERGE_PAYLOAD_LOG="$WORK_DIR/gitea-payload.json"
+    env -u MOSAIC_GIT_IDENTITY "$WORK_DIR/gitea/tools/git/pr-merge.sh" -n 123
+) >"$WORK_DIR/gitea.out" 2>&1
+gitea_rc=$?
+set -e
+if [[ "$gitea_rc" -ne 0 ]]; then
+    echo "FAIL gitea-pin: merge fixture returned $gitea_rc" >&2
+    cat "$WORK_DIR/gitea.out" >&2
+    exit 1
+fi
+python3 - "$WORK_DIR/gitea-payload.json" "$SHA" <<'PY'
+import json
+import sys
+payload = json.load(open(sys.argv[1], encoding="utf-8"))
+assert set(payload) <= {"Do", "head_commit_id", "delete_branch_after_merge"}, payload
+assert payload.get("Do") == "squash", payload
+assert payload.get("head_commit_id") == sys.argv[2], payload
+PY
+
+# A merge-gate verdict is commit-bound. A stale expected head must fail before merge.
+wrong_sha=ffffffffffffffffffffffffffffffffffffffff
+rm -f "$WORK_DIR/gitea-payload-stale.json"
+set +e
+(
+    cd "$WORK_DIR/gitea/repo"
+    export PATH="$WORK_DIR/gitea:$PATH"
+    export GITEA_TOKEN=stub-token
+    export GITEA_URL=https://git.example.test
+    export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+    export MOSAIC_MERGE_PAYLOAD_LOG="$WORK_DIR/gitea-payload-stale.json"
+    env -u MOSAIC_GIT_IDENTITY "$WORK_DIR/gitea/tools/git/pr-merge.sh" -n 123 --expect-head "$wrong_sha"
+) >"$WORK_DIR/gitea-stale.out" 2>&1
+stale_rc=$?
+set -e
+if [[ "$stale_rc" -eq 0 ]] || [[ -e "$WORK_DIR/gitea-payload-stale.json" ]]; then
+    echo "FAIL stale-verdict: moved head was not refused before provider merge" >&2
+    exit 1
+fi
+
+# A merge-capable path cannot bypass the mandatory queue guard. The legacy
+# --skip-queue-guard option must be rejected before any provider merge call.
+cat > "$WORK_DIR/gitea/tools/git/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+exit 99
+SH
+chmod +x "$WORK_DIR/gitea/tools/git/ci-queue-wait.sh"
+rm -f "$WORK_DIR/gitea-payload-bypass.json"
+set +e
+(
+    cd "$WORK_DIR/gitea/repo"
+    export PATH="$WORK_DIR/gitea:$PATH"
+    export GITEA_TOKEN=stub-token
+    export GITEA_URL=https://git.example.test
+    export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+    export MOSAIC_MERGE_PAYLOAD_LOG="$WORK_DIR/gitea-payload-bypass.json"
+    env -u MOSAIC_GIT_IDENTITY "$WORK_DIR/gitea/tools/git/pr-merge.sh" -n 123 --skip-queue-guard
+) >"$WORK_DIR/gitea-bypass.out" 2>&1
+bypass_rc=$?
+set -e
+if [[ "$bypass_rc" -eq 0 ]] || [[ -e "$WORK_DIR/gitea-payload-bypass.json" ]]; then
+    echo "FAIL merge-bypass: --skip-queue-guard reached the provider merge path" >&2
+    exit 1
+fi
+
+# Dry-run is the only path that may omit the guard because it exits before the
+# provider merge dispatch. Prove the exit and absence of a merge payload.
+rm -f "$WORK_DIR/gitea-payload-dry-run.json"
+(
+    cd "$WORK_DIR/gitea/repo"
+    export PATH="$WORK_DIR/gitea:$PATH"
+    export GITEA_TOKEN=stub-token
+    export GITEA_URL=https://git.example.test
+    export MOSAIC_CREDENTIALS_FILE="$WORK_DIR/no-credentials.json"
+    export MOSAIC_MERGE_PAYLOAD_LOG="$WORK_DIR/gitea-payload-dry-run.json"
+    env -u MOSAIC_GIT_IDENTITY "$WORK_DIR/gitea/tools/git/pr-merge.sh" -n 123 --dry-run
+) >"$WORK_DIR/gitea-dry-run.out" 2>&1
+if [[ -e "$WORK_DIR/gitea-payload-dry-run.json" ]]; then
+    echo "FAIL dry-run: non-merging preflight reached the provider merge path" >&2
+    exit 1
+fi
+
+cat > "$WORK_DIR/github/gh" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' "$*" > "${MOSAIC_GH_MERGE_LOG:?}"
+SH
+chmod +x "$WORK_DIR/github/gh"
+(
+    cd "$WORK_DIR/github/repo"
+    export PATH="$WORK_DIR/github:$PATH"
+    export MOSAIC_GH_MERGE_LOG="$WORK_DIR/github-call.log"
+    "$WORK_DIR/github/tools/git/pr-merge.sh" -n 123
+) >"$WORK_DIR/github.out" 2>&1
+if ! grep -q -- "--match-head-commit $SHA" "$WORK_DIR/github-call.log"; then
+    echo "FAIL github-pin: merge command omitted --match-head-commit $SHA" >&2
+    cat "$WORK_DIR/github-call.log" >&2
+    exit 1
+fi
+
+echo "PR merge exact-head pin regression passed (Gitea + GitHub)"
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# RM-03: pr-merge must guard the PR head branch, not its main base branch.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORK_DIR="${MOSAIC_TEST_WORK_DIR:-$PWD/.mosaic-test-work/pr-merge-queue-branch}"
+FIXTURE_DIR="$WORK_DIR/tools/git"
+CALL_LOG="$WORK_DIR/queue-call.log"
+
+rm -rf "$WORK_DIR"
+mkdir -p "$FIXTURE_DIR"
+cp "$SCRIPT_DIR/pr-merge.sh" "$FIXTURE_DIR/pr-merge.sh"
+cp "$SCRIPT_DIR/detect-platform.sh" "$FIXTURE_DIR/detect-platform.sh"
+
+cat > "$FIXTURE_DIR/pr-metadata.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' '{"baseRefName":"main","headRefName":"fix/rm-03-fixture","headRefOid":"0123456789abcdef0123456789abcdef01234567","headRepository":"contributor/widgets-fork"}'
+SH
+
+cat > "$FIXTURE_DIR/ci-queue-wait.sh" <<'SH'
+#!/usr/bin/env bash
+printf '%s\n' "$*" > "${MOSAIC_QUEUE_CALL_LOG:?}"
+exit 42
+SH
+chmod +x "$FIXTURE_DIR"/*.sh
+
+set +e
+(
+    cd "$WORK_DIR"
+    export MOSAIC_QUEUE_CALL_LOG="$CALL_LOG"
+    "$FIXTURE_DIR/pr-merge.sh" -n 123
+) >/dev/null 2>&1
+rc=$?
+set -e
+
+if [[ "$rc" -ne 42 ]]; then
+    echo "FAIL: expected queue stub rc=42 to propagate, got $rc" >&2
+    exit 1
+fi
+if [[ ! -s "$CALL_LOG" ]]; then
+    echo "FAIL: merge wrapper did not invoke the queue guard" >&2
+    exit 1
+fi
+if ! grep -q -- '-B fix/rm-03-fixture' "$CALL_LOG"; then
+    echo "FAIL: merge queue guard did not receive PR head branch" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if grep -q -- '-B main' "$CALL_LOG"; then
+    echo "FAIL: merge queue guard still received the main base branch" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if ! grep -q -- '-R contributor/widgets-fork' "$CALL_LOG"; then
+    echo "FAIL: merge queue guard did not receive the fork head repository" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+if ! grep -q -- '--sha 0123456789abcdef0123456789abcdef01234567' "$CALL_LOG"; then
+    echo "FAIL: merge queue guard did not receive the exact PR head SHA" >&2
+    cat "$CALL_LOG" >&2
+    exit 1
+fi
+
+echo "pr-merge queue branch/repository/SHA regression passed"
@@ -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"
-trap 'rm -f "$STRIPPED" "$NOEXIT" "$D1CTRL" "$D2CTRL"' EXIT
+rm -f "$STRIPPED" "$SIGNALED" "$NOEXIT" "$D1CTRL" "$D2CTRL"
+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
-# fires and ONLY the signal path governs), and assert the shipped installer
-# restores AND exits without reporting success. The control strips `exit 1` from
-# the trap and shows the buggy resume-to-success.
-make_term_shim() {
-  local dir="$1"
-  cat > "$dir/cp" <<SHIM
-#!/usr/bin/env bash
-dest="\${@: -1}"
-case "\$dest" in
-  */$POISON_REL)
-    kill -TERM "\$PPID" 2>/dev/null   # signal install.sh; the copy still succeeds
-    exec env PATH="$ORIG_PATH" cp "\$@" ;;
-esac
-exec env PATH="$ORIG_PATH" cp "\$@"
-SHIM
-  chmod +x "$dir/cp"
+# success. The earlier test used a child cp shim to signal its parent, making
+# child completion race Bash's interrupted wait. Concurrency is not part of the
+# guarded property: sync_framework_keep() runs in the installer's own Bash
+# process, and `kill` is a builtin. Generate two installer fixtures that signal
+# themselves at the same known mid-sync point. Their TERM handlers emit the same
+# observable before diverging, so missing signal delivery fails BOTH arms rather
+# than manufacturing a pass. The only semantic difference between fixtures is
+# the explicit `exit 1` whose load-bearing behavior this control proves.
+TERM_MARKER='[test-control] TERM handler entered'
+HANDLER_WITH_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot; exit 1' TERM  # TEST-TERM-HANDLER"
+HANDLER_WITHOUT_EXIT="trap 'echo \"$TERM_MARKER\" >&2; restore_snapshot' TERM  # TEST-TERM-HANDLER"
+
+make_signal_installer() {
+  local output="$1" handler="$2"
+  local target_trap="trap 'restore_snapshot; exit 1' ERR INT TERM"
+  local target_cp='    cp "$abs" "$dst/$rel"'
+  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
-  H=$(mktemp -d); OUT=$(mktemp); SHIM=$(mktemp -d)
+  local installer="$1" H OUT rc
+  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
-# resumes past the interrupt and wrongly reports success. In $FW so SOURCE_DIR resolves.
-sed "s/trap 'restore_snapshot; exit 1' ERR INT TERM/trap 'restore_snapshot' ERR INT TERM/" \
-  "$INSTALL" > "$NOEXIT"
-chk "[control] the exit-strip actually changed the installer" \
-  "! cmp -s '$INSTALL' '$NOEXIT'"
-IFS=$'\t' read -r _rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
+IFS=$'\t' read -r rcD OUTD HD < <(run_signal_upgrade "$NOEXIT")
+chk "[control] TERM handler observable fires exactly once" \
+  "[ \"\$(grep -cF '$TERM_MARKER' '$OUTD')\" -eq 1 ]"
+chk "[control] without 'exit 1' the handler restores before returning" \
+  "grep -q 'restoring previous state from snapshot' '$OUTD'"
+chk "[control] without 'exit 1' the installer exits zero after resuming" \
+  "[ '$rcD' -eq 0 ]"
 chk "[control] without 'exit 1' the trap resumes and reports sync success (the bug)" \
  "grep -q 'file phase complete' '$OUTD'"

@@ -309,10 +355,10 @@ chk "[control] without the D2 recovery line the operator gets no snapshot pointe
 # 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

-# 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"
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.48",
+  "version": "0.0.49",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
@@ -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-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 && 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"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -23,6 +23,7 @@ import { registerSkillCommand } from './commands/skill.js';
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerLeaseCapabilityProbe } from './commands/lease-activation-probe.js';
 import { registerInstallOrderingGuardCommand } from './commands/install-ordering-guard.js';
+import { registerBrainProvisionCommand } from './commands/brain-provision-command.js';
 import { registerAuthCommand } from './commands/auth.js';
 import { registerFederationCommand } from './commands/federation.js';
 import { registerGatewayCommand } from './commands/gateway.js';
@@ -85,6 +86,10 @@ registerLeaseCapabilityProbe(program);

 registerInstallOrderingGuardCommand(program);

+// ─── durable brain P7 provisioner (hidden; #1051) ───────────────────────
+
+registerBrainProvisionCommand(program);
+
 // ─── login ──────────────────────────────────────────────────────────────

 program
@@ -0,0 +1,272 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface InstalledDoctorResult {
+  readonly status: 'ok' | 'warn' | 'error';
+  readonly findings: readonly {
+    readonly code: string;
+    readonly reasonCode: string | null;
+  }[];
+  readonly lines: readonly string[];
+}
+
+interface BrainDoctorModule {
+  runInstalledBrainDoctorCheck(
+    options: {
+      readonly mosaicHome: string;
+      readonly home: string;
+      readonly identity?: string;
+      readonly fix: boolean;
+    },
+    run: (request: CommandRequest) => CommandResult,
+  ): InstalledDoctorResult;
+}
+
+const MODULE_PATH = './brain-doctor-check.js';
+const roots: string[] = [];
+
+async function loadDoctor(requirement: string): Promise<BrainDoctorModule> {
+  try {
+    return (await import(MODULE_PATH)) as BrainDoctorModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: installed brain doctor check is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-doctor-'));
+  roots.push(root);
+  return root;
+}
+
+function installConfig(root: string): { readonly home: string; readonly mosaicHome: string } {
+  const home = join(root, 'home');
+  const mosaicHome = join(home, '.config', 'mosaic');
+  mkdirSync(join(mosaicHome, 'cred'), { recursive: true });
+  mkdirSync(join(mosaicHome, 'brain'), { recursive: true });
+  writeFileSync(
+    join(mosaicHome, 'cred', 'estates.json'),
+    JSON.stringify({
+      version: 1,
+      estates: [
+        {
+          name: 'homelab',
+          readOnlyControlIdentity: 'read-control',
+          hosts: [
+            {
+              host: 'git.example.invalid',
+              provider: 'gitea',
+              apiBaseUrl: 'https://git.example.invalid',
+              tokenPrefix: 'gitea-example',
+            },
+          ],
+        },
+      ],
+    }),
+    { mode: 0o600 },
+  );
+  writeFileSync(
+    join(mosaicHome, 'brain', 'owners.json'),
+    JSON.stringify({
+      version: 1,
+      estates: [
+        {
+          estate: 'homelab',
+          laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+          standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+          controls: { publicIdentity: 'public-control', privateIdentity: 'private-control' },
+        },
+      ],
+    }),
+    { mode: 0o600 },
+  );
+  writeFileSync(
+    join(mosaicHome, '.install-manifest.json'),
+    JSON.stringify({
+      version: 2,
+      status: 'committed',
+      sourceRepo: 'https://git.example.invalid/example/stack.git',
+    }),
+    { mode: 0o600 },
+  );
+  return { home, mosaicHome };
+}
+
+function validateResult(outcome: 'ok' | 'refused' | 'indeterminate', reasonCode: string): string {
+  const exitCode = outcome === 'ok' ? 0 : outcome === 'refused' ? 10 : 30;
+  return JSON.stringify({
+    schemaVersion: 1,
+    operation: 'validate',
+    outcome,
+    exitCode,
+    retryable: false,
+    subject: {
+      identity: 'seat-a',
+      estate: 'homelab',
+      host: 'git.example.invalid',
+      repo: 'durable-owner/mosaic-brain',
+    },
+    mutation: 'none',
+    reason: { code: reasonCode, message: 'non-secret' },
+    evidence: {
+      providerIdentity:
+        outcome === 'ok'
+          ? {
+              login: 'seat-a',
+              endpoint: 'GET /api/v1/user',
+              contentType: 'application/json',
+            }
+          : null,
+      repositoryPermission:
+        outcome === 'ok'
+          ? {
+              requested: 'write',
+              effective: 'write',
+              endpoint: 'GET /api/v1/repos/durable-owner/mosaic-brain',
+              contentType: 'application/json',
+            }
+          : null,
+      writeDifferential:
+        outcome === 'ok'
+          ? {
+              state: 'can-write',
+              credentialBinding: 'same-resolution',
+              transportPrincipal: 'seat-a',
+              authenticatedReceivePack: 'advertised',
+              readOnlyControl: {
+                identity: 'read-control',
+                providerPermission: 'read',
+                receivePack: 'refused',
+              },
+              unauthenticatedReceivePack: 'refused',
+              artifactCreated: false,
+              proves: 'non-secret evidence',
+              doesNotProve: 'branch update acceptance',
+            }
+          : null,
+    },
+    audit: { journalId: 'opaque', state: 'sealed' },
+  });
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('installed mosaic doctor brain checks', (): void => {
+  it('derives the target from the committed install manifest and surfaces a missing clone plus refusal', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 installed doctor missing clone');
+    const config = installConfig(tempRoot());
+    const requests: CommandRequest[] = [];
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, identity: 'seat-a', fix: false },
+      (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 10,
+          stdout: validateResult('refused', 'no-token-for-identity'),
+          stderr: 'refused reason=no-token-for-identity',
+        };
+      },
+    );
+
+    expect(result.status).toBe('warn');
+    expect(result.findings.map((finding) => finding.code)).toEqual(
+      expect.arrayContaining(['brain-clone-missing', 'brain-write-access-refused']),
+    );
+    expect(result.lines.join('\n')).toMatch(/brain-clone-missing/);
+    expect(result.lines.join('\n')).toMatch(/no-token-for-identity/);
+    expect(requests[0]?.args).toContain('durable-owner/mosaic-brain');
+  });
+
+  it('fails closed without an explicit identity and performs no command', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 explicit identity');
+    const config = installConfig(tempRoot());
+    let calls = 0;
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, fix: false },
+      (): CommandResult => {
+        calls += 1;
+        return { status: 0, stdout: '', stderr: '' };
+      },
+    );
+
+    expect(result).toMatchObject({
+      status: 'error',
+      findings: [{ code: 'brain-identity-required', reasonCode: 'identity-required' }],
+    });
+    expect(calls).toBe(0);
+  });
+
+  it('treats identity-not-measured as an error, not no-write refusal and not a repairable grant case', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-08 identity measurement axis');
+    const config = installConfig(tempRoot());
+    const requests: CommandRequest[] = [];
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { ...config, identity: 'seat-a', fix: true },
+      (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 30,
+          stdout: validateResult('indeterminate', 'identity-not-measured'),
+          stderr: 'identity not measured',
+        };
+      },
+    );
+
+    expect(result.status).toBe('error');
+    expect(result.findings).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'brain-write-access-indeterminate',
+          reasonCode: 'identity-not-measured',
+        }),
+      ]),
+    );
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('is wired into the top-level mosaic doctor path before the shell audit runs', (): void => {
+    const launch = readFileSync(join(process.cwd(), 'src', 'commands', 'launch.ts'), 'utf8');
+
+    expect(launch).toContain('runInstalledBrainDoctorCheck');
+    expect(launch).toContain('defaultInstalledBrainDoctorOptions');
+    expect(launch).toContain('systemCommandRunner');
+    expect(launch).toMatch(/brainCheckFailed[\s\S]*runDoctorScriptAndExit/);
+  });
+
+  it('reports a missing or unsafe registry/manifest as configuration error rather than defaulting estate', async (): Promise<void> => {
+    const doctor = await loadDoctor('MB-REQ-02 missing mapping fail-closed');
+    const root = tempRoot();
+    const home = join(root, 'home');
+    const mosaicHome = join(home, '.config', 'mosaic');
+    mkdirSync(mosaicHome, { recursive: true });
+
+    const result = doctor.runInstalledBrainDoctorCheck(
+      { home, mosaicHome, identity: 'seat-a', fix: false },
+      (): CommandResult => ({ status: 0, stdout: '', stderr: '' }),
+    );
+
+    expect(result.status).toBe('error');
+    expect(result.findings[0]?.code).toMatch(/brain-(estate-registry|install-manifest)-/);
+    expect(result.lines.join('\n')).not.toMatch(/homelab|usc/);
+  });
+});
@@ -0,0 +1,152 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readBrainConfigSecure } from './brain-secure-config.js';
+import { resolveBrainOwnerPolicy } from './brain-owner-resolver.js';
+import { deriveBrainTarget } from './brain-store.js';
+import {
+  collectBrainDoctorReport,
+  repairBrainDoctor,
+  type CommandRunner,
+  type DoctorRuntimeReport,
+} from './brain-store-runtime.js';
+
+const IDENTITY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const manifestSchema = z
+  .object({
+    version: z.literal(2),
+    status: z.literal('committed'),
+    sourceRepo: z.string().min(1),
+  })
+  .passthrough();
+
+export interface InstalledDoctorFinding {
+  readonly code: string;
+  readonly reasonCode: string | null;
+}
+
+export interface InstalledDoctorResult {
+  readonly status: 'ok' | 'warn' | 'error';
+  readonly findings: readonly InstalledDoctorFinding[];
+  readonly lines: readonly string[];
+}
+
+function configurationError(code: string, reasonCode = code): InstalledDoctorResult {
+  return {
+    status: 'error',
+    findings: [{ code, reasonCode }],
+    lines: [`[mosaic-doctor] [ERROR] ${code}`],
+  };
+}
+
+function renderReport(report: DoctorRuntimeReport): InstalledDoctorResult {
+  const findings = report.findings.map(
+    (finding): InstalledDoctorFinding => ({
+      code: finding.code,
+      reasonCode: finding.reasonCode,
+    }),
+  );
+  const hard = findings.some(
+    (finding): boolean =>
+      finding.code.endsWith('-error') ||
+      finding.code.endsWith('-indeterminate') ||
+      finding.code === 'brain-not-git-repository' ||
+      finding.code === 'brain-root-permissions-unsafe',
+  );
+  const status: InstalledDoctorResult['status'] =
+    findings.length === 0 ? 'ok' : hard ? 'error' : 'warn';
+  const severity = status === 'error' ? 'ERROR' : status === 'warn' ? 'WARN' : 'OK';
+  const lines =
+    findings.length === 0
+      ? ['[mosaic-doctor] [OK] mosaic-brain ready']
+      : findings.map(
+          (finding): string =>
+            `[mosaic-doctor] [${severity}] ${finding.code}${
+              finding.reasonCode === null ? '' : ` reason=${finding.reasonCode}`
+            }`,
+        );
+  return { status, findings, lines };
+}
+
+export function runInstalledBrainDoctorCheck(
+  options: {
+    readonly mosaicHome: string;
+    readonly home: string;
+    readonly identity?: string;
+    readonly fix: boolean;
+  },
+  run: CommandRunner,
+): InstalledDoctorResult {
+  if (options.identity === undefined || !IDENTITY.test(options.identity)) {
+    return configurationError('brain-identity-required', 'identity-required');
+  }
+
+  const registryPath = join(options.mosaicHome, 'cred', 'estates.json');
+  const manifestPath = join(options.mosaicHome, '.install-manifest.json');
+  const ownerPolicyPath = join(options.mosaicHome, 'brain', 'owners.json');
+  let registrySource: string;
+  try {
+    registrySource = readBrainConfigSecure(registryPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-estate-registry-unavailable');
+  }
+  let manifestSource: string;
+  try {
+    manifestSource = readBrainConfigSecure(manifestPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-install-manifest-unavailable');
+  }
+  let manifestRaw: unknown;
+  try {
+    manifestRaw = JSON.parse(manifestSource);
+  } catch {
+    return configurationError('brain-install-manifest-invalid');
+  }
+  const manifest = manifestSchema.safeParse(manifestRaw);
+  if (!manifest.success) return configurationError('brain-install-manifest-invalid');
+  let ownerPolicySource: string;
+  try {
+    ownerPolicySource = readBrainConfigSecure(ownerPolicyPath, options.mosaicHome);
+  } catch {
+    return configurationError('brain-owner-policy-unavailable');
+  }
+  let preliminaryTarget: ReturnType<typeof deriveBrainTarget>;
+  try {
+    preliminaryTarget = deriveBrainTarget(registrySource, manifest.data.sourceRepo, 'policy-probe');
+  } catch {
+    return configurationError('brain-estate-registry-invalid');
+  }
+  const ownerPolicy = resolveBrainOwnerPolicy(ownerPolicySource, preliminaryTarget.estate);
+  if (ownerPolicy === undefined) return configurationError('brain-owner-policy-invalid');
+
+  const input = {
+    registrySource,
+    targetGitUrl: manifest.data.sourceRepo,
+    brainNamespace: ownerPolicy.brainNamespace,
+    identity: options.identity,
+    root: join(options.home, '.mosaic'),
+  };
+  try {
+    return renderReport(
+      options.fix ? repairBrainDoctor(input, run) : collectBrainDoctorReport(input, run),
+    );
+  } catch {
+    return configurationError('brain-estate-registry-invalid');
+  }
+}
+
+export function defaultInstalledBrainDoctorOptions(fix: boolean): {
+  readonly mosaicHome: string;
+  readonly home: string;
+  readonly identity?: string;
+  readonly fix: boolean;
+} {
+  const home = homedir();
+  const identity = process.env['MOSAIC_GIT_IDENTITY'];
+  return {
+    mosaicHome: process.env['MOSAIC_HOME'] ?? join(home, '.config', 'mosaic'),
+    home,
+    ...(identity === undefined ? {} : { identity }),
+    fix,
+  };
+}
@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function installerSource(): string {
+  return readFileSync(join(process.cwd(), '..', '..', 'tools', 'install.sh'), 'utf8');
+}
+
+describe('root installer P7 durable-brain integration', (): void => {
+  it('records the configured source repository in the committed manifest for doctor derivation', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toContain('sourceRepo:');
+    expect(installer).toMatch(/sourceRepo:\s*process\.argv\[/);
+    expect(installer).toMatch(/MANIFEST_SOURCE_REPO/);
+  });
+
+  it('invokes the broker-only provision command in P7 with explicit owner and refusal controls', (): void => {
+    const installer = installerSource();
+    const provision = installer.indexOf('__brain-provision');
+    const p7 = installer.indexOf('state_phase_begin P7');
+
+    expect(provision).toBeGreaterThan(-1);
+    expect(p7).toBeGreaterThan(-1);
+    expect(provision).toBeGreaterThan(p7);
+    for (const flag of [
+      '--identity',
+      '--target-url',
+      '--owner',
+      '--refusal-identity',
+      '--lane',
+      '--owner-policy',
+    ]) {
+      expect(installer).toContain(flag);
+    }
+    expect(installer).not.toMatch(/__brain-provision[^\n]*(?:token|password|authorization)/i);
+  });
+
+  it('journals ~/.mosaic and the owner policy as P7 mutations and checks the resulting object', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toContain('state_record_mutation P7 "$HOME/.mosaic"');
+    expect(installer).toContain('state_record_mutation P7 "$MOSAIC_HOME/brain/owners.json"');
+    expect(installer).toMatch(/P7\)[\s\S]*\.mosaic[\s\S]*(?:remote|get-url)[\s\S]*main/);
+  });
+
+  it('discovers every legacy lane directory rather than silently migrating only one lane', (): void => {
+    const installer = installerSource();
+
+    expect(installer).toMatch(/memory\/lanes/);
+    expect(installer).toMatch(/for\s+[^\n]*lane/);
+    expect(installer).toMatch(/__brain-provision[\s\S]*--lane/);
+  });
+});
@@ -0,0 +1,373 @@
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Red-first owner-authority resolver contract for #1051.
+ *
+ * Fixtures are operator-agnostic. The HOMELAB owner name belongs in the local
+ * estate policy, never in framework source. Anonymous lookup is intentional:
+ * the ruled owner class is PUBLIC and least-privilege seats may lack read:user.
+ */
+
+interface MigrationOwnerResolution {
+  readonly verdict: 'resolved' | 'refused' | 'not-measured';
+  readonly reasonCode: string;
+  readonly principal: {
+    readonly name: string;
+    readonly kind: 'durable-human';
+  } | null;
+  readonly authority: {
+    readonly system: 'gitea';
+    readonly endpoint: string;
+    readonly contentType: 'application/json';
+  } | null;
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+interface OwnerResolverModule {
+  resolveProviderDurableOwner(
+    input: {
+      readonly estateRegistrySource: string;
+      readonly ownerPolicySource: string;
+      readonly host: string;
+      readonly requestedOwner: string;
+    },
+    dependencies: {
+      readonly fetch: FetchLike;
+      readonly absentControlName: () => string;
+    },
+  ): Promise<MigrationOwnerResolution>;
+}
+
+const MODULE_PATH = './brain-owner-resolver.js';
+
+async function loadResolver(requirement: string): Promise<OwnerResolverModule> {
+  try {
+    return (await import(MODULE_PATH)) as OwnerResolverModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain owner resolver is absent (${detail})`);
+  }
+}
+
+function estateRegistry(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        name: 'homelab',
+        readOnlyControlIdentity: 'read-control',
+        hosts: [
+          {
+            host: 'git.example.invalid',
+            provider: 'gitea',
+            apiBaseUrl: 'https://git.example.invalid',
+            tokenPrefix: 'gitea-example',
+          },
+        ],
+      },
+    ],
+  });
+}
+
+function ownerPolicy(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        estate: 'homelab',
+        laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+        standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+        controls: {
+          publicIdentity: 'public-control',
+          privateIdentity: 'private-control',
+        },
+      },
+    ],
+  });
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8' },
+  });
+}
+
+function publicUser(login: string, active = false): Response {
+  return jsonResponse(200, {
+    id: 42,
+    login,
+    visibility: 'public',
+    active,
+  });
+}
+
+function identityFromUrl(input: string | URL | Request): string {
+  const value = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+  return decodeURIComponent(new URL(value).pathname.split('/').at(-1) ?? '');
+}
+
+function controlledFetch(
+  overrides: Readonly<Record<string, Response>> = {},
+  calls: Array<{ identity: string; authorization: string | null }> = [],
+): FetchLike {
+  return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const identity = identityFromUrl(input);
+    const headers = new Headers(init?.headers);
+    calls.push({ identity, authorization: headers.get('authorization') });
+    const override = overrides[identity];
+    if (override !== undefined) return override.clone();
+    if (identity === 'public-control') return publicUser('public-control');
+    if (identity === 'private-control' || identity === 'generated-absent-control') {
+      return jsonResponse(404, { message: 'not found' });
+    }
+    if (identity === 'durable-owner') return publicUser('durable-owner', false);
+    return jsonResponse(404, { message: 'not found' });
+  };
+}
+
+describe('provider-backed durable owner resolver', (): void => {
+  it('resolves an allowlisted PUBLIC owner by exact login with public/private/absent controls and ignores active=false', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 provider owner resolution');
+    const calls: Array<{ identity: string; authorization: string | null }> = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: controlledFetch({}, calls),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toEqual({
+      verdict: 'resolved',
+      reasonCode: 'owner-verified',
+      principal: { name: 'user:durable-owner', kind: 'durable-human' },
+      authority: {
+        system: 'gitea',
+        endpoint: 'GET /api/v1/users/durable-owner',
+        contentType: 'application/json',
+      },
+    });
+    expect(calls.map((call) => call.identity)).toEqual([
+      'public-control',
+      'private-control',
+      'generated-absent-control',
+      'durable-owner',
+    ]);
+    expect(calls.every((call) => call.authorization === null)).toBe(true);
+  });
+
+  it('refuses provider redirects and configures a bounded no-redirect request', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 owner lookup SSRF boundary');
+    const requests: RequestInit[] = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (_input, init): Promise<Response> => {
+          requests.push(init ?? {});
+          return new Response(JSON.stringify({ message: 'redirect' }), {
+            status: 302,
+            headers: {
+              'content-type': 'application/json',
+              location: 'http://127.0.0.1/internal',
+            },
+          });
+        },
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'not-measured', reasonCode: 'owner-control-invalid' });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.redirect).toBe('manual');
+    expect(requests[0]?.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it('cancels a chunked provider body as soon as it exceeds the byte ceiling', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 bounded owner response stream');
+    let cancelled = false;
+    const oversized = new ReadableStream<Uint8Array>({
+      start(controller): void {
+        controller.enqueue(new Uint8Array(200_000));
+        controller.enqueue(new Uint8Array(100_000));
+      },
+      cancel(): void {
+        cancelled = true;
+      },
+    });
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (): Promise<Response> =>
+          new Response(oversized, {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+          }),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({
+      verdict: 'not-measured',
+      reasonCode: 'owner-unexpected-provider-shape',
+    });
+    expect(cancelled).toBe(true);
+  });
+
+  it('requires the GLPI standing remediation queue in the local estate policy', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 standing process policy');
+    const raw = JSON.parse(ownerPolicy()) as { estates: Array<Record<string, unknown>> };
+    delete raw.estates[0]?.['standingProcess'];
+    let fetchCalls = 0;
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: JSON.stringify(raw),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: async (): Promise<Response> => {
+          fetchCalls += 1;
+          return publicUser('durable-owner');
+        },
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'refused', reasonCode: 'owner-policy-invalid' });
+    expect(fetchCalls).toBe(0);
+  });
+
+  it('rejects a provider-valid but unlisted principal before provider lookup', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 provider-valid unlisted owner refusal');
+    const calls: Array<{ identity: string; authorization: string | null }> = [];
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:other-public-user',
+      },
+      {
+        fetch: controlledFetch({ 'other-public-user': publicUser('other-public-user') }, calls),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ verdict: 'refused', reasonCode: 'owner-not-allowlisted' });
+    expect(calls).toHaveLength(0);
+  });
+
+  it.each([
+    ['user:durable–owner', 'owner-name-invalid'],
+    [' user:durable-owner ', 'owner-name-invalid'],
+    ['user:durable.owner', 'owner-not-allowlisted'],
+    ['user:durable owner', 'owner-name-invalid'],
+    ['user:ｄurable-owner', 'owner-name-invalid'],
+    ['user:be-coder-07@mission-seat', 'owner-name-invalid'],
+  ] as const)(
+    'rejects non-canonical, unlisted, or transient-seat presentation %s before lookup',
+    async (name, reasonCode): Promise<void> => {
+      const resolver = await loadResolver('MB-REQ-09 owner allowlist grammar');
+      let fetchCalls = 0;
+
+      const result = await resolver.resolveProviderDurableOwner(
+        {
+          estateRegistrySource: estateRegistry(),
+          ownerPolicySource: ownerPolicy(),
+          host: 'git.example.invalid',
+          requestedOwner: name,
+        },
+        {
+          fetch: async (): Promise<Response> => {
+            fetchCalls += 1;
+            return publicUser('durable-owner');
+          },
+          absentControlName: (): string => 'generated-absent-control',
+        },
+      );
+
+      expect(result).toMatchObject({ verdict: 'refused', reasonCode });
+      expect(fetchCalls).toBe(0);
+    },
+  );
+
+  it('fails closed as not-resolvable rather than claiming a private-or-absent owner does not exist', async (): Promise<void> => {
+    const resolver = await loadResolver('MB-REQ-09 private/absent ambiguity');
+
+    const result = await resolver.resolveProviderDurableOwner(
+      {
+        estateRegistrySource: estateRegistry(),
+        ownerPolicySource: ownerPolicy(),
+        host: 'git.example.invalid',
+        requestedOwner: 'user:durable-owner',
+      },
+      {
+        fetch: controlledFetch({ 'durable-owner': jsonResponse(404, { message: 'hidden' }) }),
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({
+      verdict: 'not-measured',
+      reasonCode: 'owner-not-resolvable',
+      principal: null,
+    });
+    expect(JSON.stringify(result)).not.toMatch(/owner-not-found|does-not-exist/);
+  });
+
+  it.each([
+    ['public control hidden', { 'public-control': jsonResponse(404, {}) }],
+    ['public control login mismatch', { 'public-control': publicUser('other') }],
+    ['private control unexpectedly public', { 'private-control': publicUser('private-control') }],
+    [
+      'generated absent control unexpectedly resolves',
+      { 'generated-absent-control': publicUser('generated-absent-control') },
+    ],
+  ] as const)(
+    'makes the whole result not-measured when %s',
+    async (_caseName, overrides): Promise<void> => {
+      const resolver = await loadResolver('MB-REQ-09 owner resolver controls');
+
+      const result = await resolver.resolveProviderDurableOwner(
+        {
+          estateRegistrySource: estateRegistry(),
+          ownerPolicySource: ownerPolicy(),
+          host: 'git.example.invalid',
+          requestedOwner: 'user:durable-owner',
+        },
+        {
+          fetch: controlledFetch(overrides),
+          absentControlName: (): string => 'generated-absent-control',
+        },
+      );
+
+      expect(result).toMatchObject({
+        verdict: 'not-measured',
+        reasonCode: 'owner-control-invalid',
+      });
+    },
+  );
+});
@@ -0,0 +1,280 @@
+import { z } from 'zod';
+import { parseCredentialEstateRegistry } from '../credentials/estate-registry.js';
+import type { MigrationOwnerResolution } from './brain-store.js';
+
+const MAX_BODY_BYTES = 256 * 1024;
+const LOGIN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/;
+const REQUESTED_OWNER = /^user:(.+)$/;
+
+const ownerPolicySchema = z
+  .object({
+    version: z.literal(1),
+    estates: z
+      .array(
+        z
+          .object({
+            estate: z.string().min(1),
+            laneArchiveOwners: z
+              .array(
+                z
+                  .object({
+                    kind: z.literal('provider-user'),
+                    login: z.string().min(1),
+                  })
+                  .strict(),
+              )
+              .min(1),
+            standingProcess: z
+              .object({
+                kind: z.literal('glpi-queue'),
+                queue: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+              })
+              .strict(),
+            controls: z
+              .object({
+                publicIdentity: z.string().min(1),
+                privateIdentity: z.string().min(1),
+              })
+              .strict(),
+          })
+          .strict(),
+      )
+      .min(1),
+  })
+  .strict();
+
+const providerUserSchema = z
+  .object({
+    id: z.number().int(),
+    login: z.string().min(1),
+    visibility: z.literal('public'),
+  })
+  .passthrough();
+
+export type OwnerFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+function unresolved(reasonCode: string): MigrationOwnerResolution {
+  return {
+    verdict: 'not-measured',
+    reasonCode,
+    principal: null,
+    authority: null,
+  };
+}
+
+function refused(reasonCode: string): MigrationOwnerResolution {
+  return {
+    verdict: 'refused',
+    reasonCode,
+    principal: null,
+    authority: null,
+  };
+}
+
+function exactCanonicalLogin(value: string): boolean {
+  return value.normalize('NFKC') === value && LOGIN.test(value);
+}
+
+async function boundedJson(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.toLowerCase().startsWith('application/json')) {
+    throw new Error('owner-unexpected-content-type');
+  }
+  const declared = response.headers.get('content-length');
+  let declaredSize: number | null = null;
+  if (declared !== null) {
+    if (!/^\d+$/.test(declared)) throw new Error('owner-unexpected-provider-shape');
+    declaredSize = Number.parseInt(declared, 10);
+    if (!Number.isSafeInteger(declaredSize) || declaredSize > MAX_BODY_BYTES) {
+      throw new Error('owner-unexpected-provider-shape');
+    }
+  }
+  if (response.body === null) throw new Error('owner-unexpected-provider-shape');
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const next = await reader.read();
+    if (next.done) break;
+    total += next.value.byteLength;
+    if (total > MAX_BODY_BYTES) {
+      await reader.cancel('owner response exceeds byte ceiling');
+      throw new Error('owner-unexpected-provider-shape');
+    }
+    chunks.push(next.value);
+  }
+  if (declaredSize !== null && declaredSize !== total) {
+    throw new Error('owner-unexpected-provider-shape');
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
+  } catch {
+    throw new Error('owner-unexpected-provider-shape');
+  }
+}
+
+async function readPublicIdentity(
+  origin: string,
+  identity: string,
+  fetchImpl: OwnerFetch,
+): Promise<{ readonly status: number; readonly user: unknown }> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${origin}/api/v1/users/${encodeURIComponent(identity)}`, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'mosaic-brain-owner/1',
+      },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    throw new Error('owner-provider-unavailable');
+  }
+  return { status: response.status, user: await boundedJson(response) };
+}
+
+function publicIdentityMatches(value: unknown, identity: string): boolean {
+  const parsed = providerUserSchema.safeParse(value);
+  return parsed.success && parsed.data.login === identity;
+}
+
+export interface BrainOwnerPolicyBinding {
+  readonly brainNamespace: string;
+  readonly publicControl: string;
+  readonly privateControl: string;
+  readonly standingQueue: string;
+}
+
+export function resolveBrainOwnerPolicy(
+  ownerPolicySource: string,
+  estate: string,
+): BrainOwnerPolicyBinding | undefined {
+  let rawPolicy: unknown;
+  try {
+    rawPolicy = JSON.parse(ownerPolicySource);
+  } catch {
+    return undefined;
+  }
+  const policy = ownerPolicySchema.safeParse(rawPolicy);
+  if (!policy.success) return undefined;
+  const estatePolicies = policy.data.estates.filter(
+    (candidate): boolean => candidate.estate === estate,
+  );
+  if (estatePolicies.length !== 1) return undefined;
+  const estatePolicy = estatePolicies[0];
+  if (estatePolicy === undefined || estatePolicy.laneArchiveOwners.length !== 1) return undefined;
+  const brainNamespace = estatePolicy.laneArchiveOwners[0]?.login;
+  if (brainNamespace === undefined || !exactCanonicalLogin(brainNamespace)) return undefined;
+  return {
+    brainNamespace,
+    publicControl: estatePolicy.controls.publicIdentity,
+    privateControl: estatePolicy.controls.privateIdentity,
+    standingQueue: estatePolicy.standingProcess.queue,
+  };
+}
+
+export function parseRequestedOwner(requestedOwner: string): string | null {
+  if (requestedOwner.normalize('NFKC') !== requestedOwner) return null;
+  const match = REQUESTED_OWNER.exec(requestedOwner);
+  const login = match?.[1];
+  if (login === undefined || !exactCanonicalLogin(login)) return null;
+  return login;
+}
+
+export async function resolveProviderDurableOwner(
+  input: {
+    readonly estateRegistrySource: string;
+    readonly ownerPolicySource: string;
+    readonly host: string;
+    readonly requestedOwner: string;
+  },
+  dependencies: {
+    readonly fetch: OwnerFetch;
+    readonly absentControlName: () => string;
+  },
+): Promise<MigrationOwnerResolution> {
+  const requestedLogin = parseRequestedOwner(input.requestedOwner);
+  if (requestedLogin === null) return refused('owner-name-invalid');
+
+  const target = parseCredentialEstateRegistry(input.estateRegistrySource).resolveByHost(
+    input.host,
+  );
+  if (target === undefined) return refused('estate-host-unmapped');
+
+  const policy = resolveBrainOwnerPolicy(input.ownerPolicySource, target.estate);
+  if (policy === undefined) return refused('owner-policy-invalid');
+  if (policy.brainNamespace !== requestedLogin) return refused('owner-not-allowlisted');
+
+  const publicControl = policy.publicControl;
+  const privateControl = policy.privateControl;
+  const absentControl = dependencies.absentControlName();
+  if (
+    !exactCanonicalLogin(publicControl) ||
+    !exactCanonicalLogin(privateControl) ||
+    !exactCanonicalLogin(absentControl) ||
+    new Set([publicControl, privateControl, absentControl, requestedLogin]).size !== 4
+  ) {
+    return refused('owner-policy-invalid');
+  }
+
+  try {
+    const publicResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      publicControl,
+      dependencies.fetch,
+    );
+    if (publicResult.status !== 200 || !publicIdentityMatches(publicResult.user, publicControl)) {
+      return unresolved('owner-control-invalid');
+    }
+
+    const privateResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      privateControl,
+      dependencies.fetch,
+    );
+    if (privateResult.status !== 404) return unresolved('owner-control-invalid');
+
+    const absentResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      absentControl,
+      dependencies.fetch,
+    );
+    if (absentResult.status !== 404) return unresolved('owner-control-invalid');
+
+    const ownerResult = await readPublicIdentity(
+      target.host.apiBaseUrl,
+      requestedLogin,
+      dependencies.fetch,
+    );
+    if (ownerResult.status === 401 || ownerResult.status === 403 || ownerResult.status === 404) {
+      return unresolved('owner-not-resolvable');
+    }
+    if (ownerResult.status !== 200) return unresolved('owner-provider-unavailable');
+    if (!publicIdentityMatches(ownerResult.user, requestedLogin)) {
+      return unresolved('owner-provider-identity-mismatch');
+    }
+    return {
+      verdict: 'resolved',
+      reasonCode: 'owner-verified',
+      principal: { name: `user:${requestedLogin}`, kind: 'durable-human' },
+      authority: {
+        system: 'gitea',
+        endpoint: `GET /api/v1/users/${requestedLogin}`,
+        contentType: 'application/json',
+      },
+    };
+  } catch (error: unknown) {
+    const reason = error instanceof Error ? error.message : 'owner-provider-unavailable';
+    if (reason === 'owner-unexpected-content-type') return unresolved(reason);
+    if (reason === 'owner-unexpected-provider-shape') return unresolved(reason);
+    return unresolved('owner-provider-unavailable');
+  }
+}
@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface BrainProvisionCommandModule {
+  readonly BRAIN_PROVISION_COMMAND: string;
+  registerBrainProvisionCommand(program: Command): void;
+  executeBrainProvisionCommand(
+    options: {
+      readonly mosaicHome: string;
+      readonly home: string;
+      readonly identity: string;
+      readonly refusalIdentity: string;
+      readonly targetUrl: string;
+      readonly owner: string;
+      readonly lane: string;
+      readonly sourceRoot?: string;
+      readonly brainRoot?: string;
+      readonly ownerPolicy?: string;
+      readonly registry?: string;
+    },
+    dependencies: {
+      readonly run: () => never;
+      readonly fetch: typeof fetch;
+      readonly absentControlName: () => string;
+    },
+  ): Promise<{
+    readonly status: 'provisioned' | 'blocked' | 'failed';
+    readonly reasonCode: string;
+  }>;
+}
+
+const MODULE_PATH = './brain-provision-command.js';
+const roots: string[] = [];
+
+async function loadCommand(requirement: string): Promise<BrainProvisionCommandModule> {
+  try {
+    return (await import(MODULE_PATH)) as BrainProvisionCommandModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain provision command is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-command-'));
+  roots.push(root);
+  return root;
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('internal P7 brain provision command', (): void => {
+  it('registers only explicit non-secret contract inputs and no credential/token lookup switches', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-03 broker-only provision command');
+    const program = new Command();
+    module.registerBrainProvisionCommand(program);
+    const command = program.commands.find(
+      (candidate) => candidate.name() === module.BRAIN_PROVISION_COMMAND,
+    );
+
+    expect(command).toBeDefined();
+    const flags = command?.options.map((option) => option.flags) ?? [];
+    expect(flags.join(' ')).toContain('--identity');
+    expect(flags.join(' ')).toContain('--target-url');
+    expect(flags.join(' ')).toContain('--refusal-identity');
+    expect(flags.join(' ')).toContain('--owner-policy');
+    expect(flags.join(' ')).toContain('--owner');
+    expect(flags.join(' ')).toContain('--lane');
+    expect(flags.join(' ')).not.toMatch(/token|password|authorization|grant-authority/i);
+  });
+
+  it('is registered by the shipped CLI', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-10 shipped P7 command');
+    const cli = readFileSync(join(process.cwd(), 'src', 'cli.ts'), 'utf8');
+
+    expect(cli).toContain('registerBrainProvisionCommand');
+    expect(cli).toContain(`registerBrainProvisionCommand(program)`);
+    expect(module.BRAIN_PROVISION_COMMAND).toBe('__brain-provision');
+  });
+
+  it('fails closed before commands when the local owner policy is absent', async (): Promise<void> => {
+    const module = await loadCommand('MB-REQ-09 owner policy required');
+    const root = tempRoot();
+    const home = join(root, 'home');
+    const mosaicHome = join(home, '.config', 'mosaic');
+    mkdirSync(join(mosaicHome, 'cred'), { recursive: true });
+    writeFileSync(
+      join(mosaicHome, 'cred', 'estates.json'),
+      JSON.stringify({ version: 1, estates: [] }),
+      { mode: 0o600 },
+    );
+    let commands = 0;
+
+    const result = await module.executeBrainProvisionCommand(
+      {
+        mosaicHome,
+        home,
+        identity: 'seat-a',
+        refusalIdentity: 'outside-seat',
+        targetUrl: 'https://git.example.invalid/example/stack.git',
+        owner: 'user:durable-owner',
+        lane: 'lane-a',
+      },
+      {
+        run: (): never => {
+          commands += 1;
+          throw new Error('must not run');
+        },
+        fetch,
+        absentControlName: (): string => 'generated-absent-control',
+      },
+    );
+
+    expect(result).toMatchObject({ status: 'failed', reasonCode: 'owner-policy-unavailable' });
+    expect(commands).toBe(0);
+  });
+});
@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import { readBrainConfigSecure } from './brain-secure-config.js';
+import { provisionBrain, type ProvisionResult } from './brain-provision.js';
+import { systemCommandRunner, type CommandRunner } from './brain-store-runtime.js';
+import type { OwnerFetch } from './brain-owner-resolver.js';
+
+export const BRAIN_PROVISION_COMMAND = '__brain-provision';
+
+interface BrainProvisionCommandOptions {
+  readonly mosaicHome: string;
+  readonly home: string;
+  readonly identity: string;
+  readonly refusalIdentity: string;
+  readonly targetUrl: string;
+  readonly owner: string;
+  readonly lane: string;
+  readonly sourceRoot?: string;
+  readonly brainRoot?: string;
+  readonly ownerPolicy?: string;
+  readonly registry?: string;
+}
+
+interface BrainProvisionCommandDependencies {
+  readonly run: CommandRunner;
+  readonly fetch: OwnerFetch;
+  readonly absentControlName: () => string;
+}
+
+function configFailure(reasonCode: string): ProvisionResult {
+  return {
+    status: 'failed',
+    reasonCode,
+    findings: [{ code: `brain-${reasonCode}`, reasonCode }],
+    owner: null,
+    migration: null,
+  };
+}
+
+export async function executeBrainProvisionCommand(
+  options: BrainProvisionCommandOptions,
+  dependencies: BrainProvisionCommandDependencies,
+): Promise<ProvisionResult> {
+  const registry = options.registry ?? join(options.mosaicHome, 'cred', 'estates.json');
+  const ownerPolicy = options.ownerPolicy ?? join(options.mosaicHome, 'brain', 'owners.json');
+  let estateRegistrySource: string;
+  try {
+    estateRegistrySource = readBrainConfigSecure(registry, options.mosaicHome);
+  } catch {
+    return configFailure('estate-registry-unavailable');
+  }
+  let ownerPolicySource: string;
+  try {
+    ownerPolicySource = readBrainConfigSecure(ownerPolicy, options.mosaicHome);
+  } catch {
+    return configFailure('owner-policy-unavailable');
+  }
+
+  try {
+    return await provisionBrain(
+      {
+        estateRegistrySource,
+        ownerPolicySource,
+        targetGitUrl: options.targetUrl,
+        requestedOwner: options.owner,
+        identity: options.identity,
+        refusalIdentity: options.refusalIdentity,
+        root: options.brainRoot ?? join(options.home, '.mosaic'),
+        sourceRoot: options.sourceRoot ?? join(options.mosaicHome, 'memory'),
+        seat: options.identity,
+        lane: options.lane,
+        laneActive: false,
+      },
+      dependencies,
+    );
+  } catch {
+    return configFailure('brain-provision-exception');
+  }
+}
+
+export function registerBrainProvisionCommand(program: Command): void {
+  program
+    .command(BRAIN_PROVISION_COMMAND, { hidden: true })
+    .description('Internal installer P7 durable-brain provisioner')
+    .requiredOption('--identity <name>', 'explicit fleet identity')
+    .requiredOption('--target-url <url>', 'configured target git URL')
+    .requiredOption('--refusal-identity <name>', 'explicit out-of-estate negative control')
+    .requiredOption('--owner <owner>', 'policy-bound durable owner candidate')
+    .requiredOption('--lane <name>', 'source lane to migrate')
+    .option('--mosaic-home <path>', 'installed Mosaic home')
+    .option('--home <path>', 'principal home')
+    .option('--source-root <path>', 'legacy memory root')
+    .option('--brain-root <path>', 'per-estate brain checkout root')
+    .option('--owner-policy <path>', 'durable-owner allowlist policy')
+    .option('--registry <path>', 'estate registry path')
+    .action(async (raw: Record<string, string | undefined>): Promise<void> => {
+      const home = raw['home'] ?? homedir();
+      const mosaicHome =
+        raw['mosaicHome'] ?? process.env['MOSAIC_HOME'] ?? join(home, '.config', 'mosaic');
+      const result = await executeBrainProvisionCommand(
+        {
+          mosaicHome,
+          home,
+          identity: raw['identity']!,
+          targetUrl: raw['targetUrl']!,
+          refusalIdentity: raw['refusalIdentity']!,
+          owner: raw['owner']!,
+          lane: raw['lane']!,
+          ...(raw['sourceRoot'] === undefined ? {} : { sourceRoot: raw['sourceRoot'] }),
+          ...(raw['brainRoot'] === undefined ? {} : { brainRoot: raw['brainRoot'] }),
+          ...(raw['ownerPolicy'] === undefined ? {} : { ownerPolicy: raw['ownerPolicy'] }),
+          ...(raw['registry'] === undefined ? {} : { registry: raw['registry'] }),
+        },
+        {
+          run: systemCommandRunner,
+          fetch,
+          absentControlName: (): string => `mosaic-absent-${randomUUID()}`,
+        },
+      );
+      process.stdout.write(
+        `${JSON.stringify({
+          status: result.status,
+          reasonCode: result.reasonCode,
+          findings: result.findings,
+          owner: result.owner,
+          migration: result.migration,
+        })}\n`,
+      );
+      if (result.status !== 'provisioned') process.exitCode = result.status === 'blocked' ? 30 : 20;
+    });
+}
@@ -0,0 +1,561 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+type CommandRunner = (request: CommandRequest) => CommandResult;
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+interface ProvisionResult {
+  readonly status: 'provisioned' | 'blocked' | 'failed';
+  readonly reasonCode: string;
+  readonly findings: readonly { code: string; reasonCode: string | null }[];
+  readonly owner: {
+    readonly verdict: 'resolved' | 'refused' | 'not-measured';
+    readonly reasonCode: string;
+  } | null;
+  readonly migration: {
+    readonly status: 'migrated' | 'reported' | 'failed';
+    readonly reported: readonly { path: string; reason: string }[];
+  } | null;
+}
+
+interface ProvisionModule {
+  provisionBrain(
+    input: {
+      readonly estateRegistrySource: string;
+      readonly ownerPolicySource: string;
+      readonly targetGitUrl: string;
+      readonly requestedOwner: string;
+      readonly identity: string;
+      readonly refusalIdentity: string;
+      readonly root: string;
+      readonly sourceRoot: string;
+      readonly seat: string;
+      readonly lane: string;
+      readonly laneActive: boolean;
+    },
+    dependencies: {
+      readonly run: CommandRunner;
+      readonly fetch: FetchLike;
+      readonly absentControlName: () => string;
+      readonly approveMigrationContent?: (path: string, content: Uint8Array) => boolean;
+    },
+  ): Promise<ProvisionResult>;
+}
+
+const MODULE_PATH = './brain-provision.js';
+const roots: string[] = [];
+
+async function loadProvisioner(requirement: string): Promise<ProvisionModule> {
+  try {
+    return (await import(MODULE_PATH)) as ProvisionModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`${requirement}: brain provisioner is absent (${detail})`);
+  }
+}
+
+function tempRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'mosaic-brain-provision-'));
+  roots.push(root);
+  return root;
+}
+
+function estateRegistry(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        name: 'homelab',
+        readOnlyControlIdentity: 'read-control',
+        hosts: [
+          {
+            host: 'git.example.invalid',
+            provider: 'gitea',
+            apiBaseUrl: 'https://git.example.invalid',
+            tokenPrefix: 'gitea-example',
+          },
+        ],
+      },
+    ],
+  });
+}
+
+function ownerPolicy(): string {
+  return JSON.stringify({
+    version: 1,
+    estates: [
+      {
+        estate: 'homelab',
+        laneArchiveOwners: [{ kind: 'provider-user', login: 'durable-owner' }],
+        standingProcess: { kind: 'glpi-queue', queue: 'mosaic-brain-remediation' },
+        controls: { publicIdentity: 'public-control', privateIdentity: 'private-control' },
+      },
+    ],
+  });
+}
+
+function validateResult(
+  outcome: 'ok' | 'refused' | 'indeterminate',
+  reasonCode: string,
+  identity = 'seat-a',
+): string {
+  const exitCode = outcome === 'ok' ? 0 : outcome === 'refused' ? 10 : 30;
+  return JSON.stringify({
+    schemaVersion: 1,
+    operation: 'validate',
+    outcome,
+    exitCode,
+    retryable: false,
+    subject: {
+      identity,
+      estate: 'homelab',
+      host: 'git.example.invalid',
+      repo: 'durable-owner/mosaic-brain',
+    },
+    mutation: 'none',
+    reason: { code: reasonCode, message: 'non-secret' },
+    evidence: {
+      providerIdentity:
+        outcome === 'ok'
+          ? {
+              login: identity,
+              endpoint: 'GET /api/v1/user',
+              contentType: 'application/json',
+            }
+          : null,
+      repositoryPermission:
+        outcome === 'ok'
+          ? {
+              requested: 'write',
+              effective: 'write',
+              endpoint: 'GET /api/v1/repos/durable-owner/mosaic-brain',
+              contentType: 'application/json',
+            }
+          : null,
+      writeDifferential:
+        outcome === 'ok'
+          ? {
+              state: 'can-write',
+              credentialBinding: 'same-resolution',
+              transportPrincipal: identity,
+              authenticatedReceivePack: 'advertised',
+              readOnlyControl: {
+                identity: 'read-control',
+                providerPermission: 'read',
+                receivePack: 'refused',
+              },
+              unauthenticatedReceivePack: 'refused',
+              artifactCreated: false,
+              proves: 'non-secret evidence',
+              doesNotProve: 'branch update acceptance',
+            }
+          : null,
+    },
+    audit: { journalId: 'opaque', state: 'sealed' },
+  });
+}
+
+function publicUser(login: string): Response {
+  return new Response(JSON.stringify({ id: 1, login, visibility: 'public', active: false }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function ownerFetch(ownerStatus = 200): FetchLike {
+  return async (input): Promise<Response> => {
+    const raw = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    const identity = decodeURIComponent(new URL(raw).pathname.split('/').at(-1) ?? '');
+    if (identity === 'public-control') return publicUser(identity);
+    if (identity === 'private-control' || identity === 'generated-absent-control') {
+      return new Response(JSON.stringify({ message: 'hidden or absent' }), {
+        status: 404,
+        headers: { 'content-type': 'application/json' },
+      });
+    }
+    if (identity === 'durable-owner' && ownerStatus === 200) return publicUser(identity);
+    return new Response(JSON.stringify({ message: 'hidden or absent' }), {
+      status: ownerStatus,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+}
+
+function baseInput(root: string): {
+  readonly estateRegistrySource: string;
+  readonly ownerPolicySource: string;
+  readonly targetGitUrl: string;
+  readonly requestedOwner: string;
+  readonly identity: string;
+  readonly refusalIdentity: string;
+  readonly root: string;
+  readonly sourceRoot: string;
+  readonly seat: string;
+  readonly lane: string;
+  readonly laneActive: boolean;
+} {
+  return {
+    estateRegistrySource: estateRegistry(),
+    ownerPolicySource: ownerPolicy(),
+    targetGitUrl: 'https://git.example.invalid/example/stack.git',
+    requestedOwner: 'user:durable-owner',
+    identity: 'seat-a',
+    refusalIdentity: 'outside-seat',
+    root: join(root, 'brain'),
+    sourceRoot: join(root, 'local-memory'),
+    seat: 'seat-a',
+    lane: 'lane-a',
+    laneActive: false,
+  };
+}
+
+afterEach((): void => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('P7 brain provisioning orchestration', (): void => {
+  it('requires the P5 write-capability postcondition and never grants or clones on refusal', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-10 P5 before P7');
+    const root = tempRoot();
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(baseInput(root), {
+      run: (request): CommandResult => {
+        requests.push(request);
+        return {
+          status: 10,
+          stdout: validateResult('refused', 'no-token-for-identity'),
+          stderr: 'refused reason=no-token-for-identity',
+        };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'credential-postcondition-failed',
+    });
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.program).toBe('mosaic');
+    expect(requests[0]?.args.slice(0, 3)).toEqual(['cred', 'validate', 'seat-a']);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('clone'))).toBe(false);
+  });
+
+  it('blocks before clone when the out-of-estate Git and API axes disagree', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-05 P7 refusal control gate');
+    const root = tempRoot();
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(baseInput(root), {
+      run: (request): CommandResult => {
+        requests.push(request);
+        if (request.program === 'mosaic' && request.args[2] === 'outside-seat') {
+          return {
+            status: 10,
+            stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+            stderr: 'refused reason=no-token-for-identity',
+          };
+        }
+        if (request.program === 'mosaic') {
+          return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        if (request.args.includes('ls-remote')) {
+          return { status: 0, stdout: 'refs are visible', stderr: '' };
+        }
+        return { status: 99, stdout: '', stderr: 'unexpected command' };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'refusal-control-failed',
+    });
+    expect(requests.some((request) => request.args.includes('clone'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('blocks before skeleton publication when the existing checkout is dirty', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-06 dirty checkout publication gate');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(join(input.root, '.git'), { recursive: true });
+    const requests: CommandRequest[] = [];
+
+    const result = await provisioner.provisionBrain(input, {
+      run: (request): CommandResult => {
+        requests.push(request);
+        if (request.program === 'mosaic') {
+          return request.args[2] === 'outside-seat'
+            ? {
+                status: 10,
+                stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+                stderr: 'refused reason=no-token-for-identity',
+              }
+            : { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        const command = request.args.join(' ');
+        if (command.includes('ls-remote')) {
+          return {
+            status: 128,
+            stdout: '',
+            stderr: 'credential helper refused reason=no-token-for-identity',
+          };
+        }
+        if (command.includes('rev-parse --is-inside-work-tree')) {
+          return { status: 0, stdout: 'true\n', stderr: '' };
+        }
+        if (command.includes('remote get-url origin')) {
+          return {
+            status: 0,
+            stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+            stderr: '',
+          };
+        }
+        if (command.includes('branch --show-current')) {
+          return { status: 0, stdout: 'main\n', stderr: '' };
+        }
+        if (command.includes('status --porcelain')) {
+          return { status: 0, stdout: '?? .gitignore\n', stderr: '' };
+        }
+        return { status: 99, stdout: '', stderr: 'unexpected publication command' };
+      },
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'brain-postcondition-failed',
+    });
+    expect(requests.some((request) => request.args.includes('commit'))).toBe(false);
+    expect(requests.some((request) => request.args.includes('push'))).toBe(false);
+  });
+
+  it('clones, seeds, resolves owner, migrates, pushes on each write, and archives source only after reachability', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-07 complete migration transaction');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(join(input.sourceRoot, 'lanes', 'lane-a'), { recursive: true });
+    const source = join(input.sourceRoot, 'lanes', 'lane-a', 'finding.md');
+    writeFileSync(source, 'durable finding\n');
+    const requests: CommandRequest[] = [];
+    let commitOrdinal = 0;
+    let approvedPaths: string[] = [];
+    let privateAtClone = false;
+    const runner: CommandRunner = (request): CommandResult => {
+      requests.push(request);
+      if (request.program === 'mosaic') {
+        if (request.args[2] === 'outside-seat') {
+          return {
+            status: 10,
+            stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+            stderr: 'refused reason=no-token-for-identity',
+          };
+        }
+        return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+      }
+      const command = request.args.join(' ');
+      if (command.includes('ls-remote')) {
+        return {
+          status: 128,
+          stdout: '',
+          stderr: 'credential helper refused reason=no-token-for-identity',
+        };
+      }
+      if (request.args[0] === 'clone') {
+        privateAtClone = existsSync(input.root) && (lstatSync(input.root).mode & 0o077) === 0;
+        mkdirSync(join(input.root, '.git'), { recursive: true });
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('read-tree')) {
+        approvedPaths = [];
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('hash-object')) {
+        return { status: 0, stdout: `${'f'.repeat(40)}\n`, stderr: '' };
+      }
+      if (command.includes('update-index')) {
+        const path = request.args.at(-1);
+        if (path !== undefined) approvedPaths.push(path);
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('rev-parse') && request.args.at(-1)?.includes(':')) {
+        return { status: 0, stdout: `${'f'.repeat(40)}\n`, stderr: '' };
+      }
+      if (command.includes('diff --cached --quiet')) {
+        return { status: 1, stdout: '', stderr: '' };
+      }
+      if (command.includes('diff-tree')) {
+        return { status: 0, stdout: `${approvedPaths.join('\0')}\0`, stderr: '' };
+      }
+      if (command.includes('show -s')) {
+        return {
+          status: 0,
+          stdout: 'seat-a\[email protected]\0seat-a\[email protected]\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('rev-parse --is-inside-work-tree')) {
+        return { status: 0, stdout: 'true\n', stderr: '' };
+      }
+      if (command.includes('remote get-url origin')) {
+        return {
+          status: 0,
+          stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('branch --show-current')) {
+        return { status: 0, stdout: 'main\n', stderr: '' };
+      }
+      if (command.includes('status --porcelain')) {
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (command.includes('rev-parse HEAD')) {
+        commitOrdinal += 1;
+        return {
+          status: 0,
+          stdout: `${commitOrdinal === 1 ? 'a' : 'c'.repeat(1)}`.repeat(40) + '\n',
+          stderr: '',
+        };
+      }
+      if (command.includes('rev-parse origin/main')) {
+        const value = commitOrdinal === 1 ? 'b' : 'd';
+        return { status: 0, stdout: `${value.repeat(40)}\n`, stderr: '' };
+      }
+      return { status: 0, stdout: '', stderr: '' };
+    };
+
+    const result = await provisioner.provisionBrain(input, {
+      run: runner,
+      fetch: ownerFetch(),
+      absentControlName: (): string => 'generated-absent-control',
+      approveMigrationContent: (): boolean => true,
+    });
+
+    expect(result).toMatchObject({
+      status: 'provisioned',
+      reasonCode: 'brain-provisioned',
+      owner: { verdict: 'resolved', reasonCode: 'owner-verified' },
+      migration: { status: 'reported' },
+    });
+    expect(privateAtClone).toBe(true);
+    expect(existsSync(source)).toBe(true);
+    const imported = result.migration?.reported ?? [];
+    expect(imported).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: source, reason: expect.stringMatching(/retained/i) }),
+      ]),
+    );
+    const laneImports = join(input.root, 'lanes', 'lane-a', 'findings', 'imports');
+    const archiveImports = join(input.root, 'archives', 'imports', 'lane');
+    expect(existsSync(laneImports)).toBe(true);
+    expect(existsSync(archiveImports)).toBe(true);
+    expect(
+      requests.filter((request) => request.program === 'git' && request.args.includes('push')),
+    ).toHaveLength(2);
+    expect(requests.some((request) => request.args.includes('grant'))).toBe(false);
+  });
+
+  it('keeps every source and reports the owner ambiguity when the public owner cannot be resolved', async (): Promise<void> => {
+    const provisioner = await loadProvisioner('MB-REQ-07 owner-blocked detection/reporting');
+    const root = tempRoot();
+    const input = baseInput(root);
+    mkdirSync(input.root, { recursive: true });
+    mkdirSync(join(input.root, '.git'), { recursive: true });
+    mkdirSync(join(input.sourceRoot, 'lanes', 'lane-a'), { recursive: true });
+    const source = join(input.sourceRoot, 'lanes', 'lane-a', 'finding.md');
+    writeFileSync(source, 'retain me\n');
+    let commitOrdinal = 0;
+
+    const result = await provisioner.provisionBrain(input, {
+      run: (request): CommandResult => {
+        if (request.program === 'mosaic') {
+          if (request.args[2] === 'outside-seat') {
+            return {
+              status: 10,
+              stdout: validateResult('refused', 'no-token-for-identity', 'outside-seat'),
+              stderr: 'refused reason=no-token-for-identity',
+            };
+          }
+          return { status: 0, stdout: validateResult('ok', 'validation-verified'), stderr: '' };
+        }
+        const command = request.args.join(' ');
+        if (command.includes('ls-remote')) {
+          return {
+            status: 128,
+            stdout: '',
+            stderr: 'credential helper refused reason=no-token-for-identity',
+          };
+        }
+        if (command.includes('rev-parse --is-inside-work-tree')) {
+          return { status: 0, stdout: 'true\n', stderr: '' };
+        }
+        if (command.includes('remote get-url origin')) {
+          return {
+            status: 0,
+            stdout: 'https://git.example.invalid/durable-owner/mosaic-brain.git\n',
+            stderr: '',
+          };
+        }
+        if (command.includes('branch --show-current')) {
+          return { status: 0, stdout: 'main\n', stderr: '' };
+        }
+        if (command.includes('status --porcelain')) {
+          return { status: 0, stdout: '', stderr: '' };
+        }
+        if (command.includes('rev-parse HEAD')) {
+          commitOrdinal += 1;
+          return { status: 0, stdout: `${'a'.repeat(40)}\n`, stderr: '' };
+        }
+        if (command.includes('rev-parse origin/main')) {
+          return { status: 0, stdout: `${'b'.repeat(40)}\n`, stderr: '' };
+        }
+        return { status: 0, stdout: '', stderr: '' };
+      },
+      fetch: ownerFetch(404),
+      absentControlName: (): string => 'generated-absent-control',
+    });
+
+    expect(result).toMatchObject({
+      status: 'blocked',
+      reasonCode: 'owner-not-resolvable',
+      owner: { verdict: 'not-measured', reasonCode: 'owner-not-resolvable' },
+      migration: { status: 'reported' },
+    });
+    expect(readFileSync(source, 'utf8')).toBe('retain me\n');
+    expect(result.migration?.reported).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: source, reason: expect.stringMatching(/owner/i) }),
+      ]),
+    );
+    expect(JSON.stringify(result)).not.toMatch(/owner-not-found|does-not-exist/);
+    expect(commitOrdinal).toBe(0);
+  });
+});
@@ -0,0 +1,271 @@
+import { existsSync } from 'node:fs';
+import { parseRequestedOwner, resolveProviderDurableOwner } from './brain-owner-resolver.js';
+import {
+  createBrainSkeleton,
+  deriveBrainTarget,
+  discoverBrainMigration,
+  ensureBrainRootPrivate,
+  migrateBrainState,
+  type MigrationResult,
+  type MigrationOwnerResolution,
+  type MigrationPublishEntry,
+} from './brain-store.js';
+import {
+  collectBrainDoctorReport,
+  collectBrainRefusalControl,
+  publishBrainPaths,
+  type CommandRequest,
+  type CommandResult,
+  type CommandRunner,
+} from './brain-store-runtime.js';
+import type { OwnerFetch } from './brain-owner-resolver.js';
+
+export interface ProvisionResult {
+  readonly status: 'provisioned' | 'blocked' | 'failed';
+  readonly reasonCode: string;
+  readonly findings: readonly {
+    readonly code: string;
+    readonly reasonCode: string | null;
+  }[];
+  readonly owner: Pick<MigrationOwnerResolution, 'verdict' | 'reasonCode'> | null;
+  readonly migration: Pick<MigrationResult, 'status' | 'reported'> | null;
+}
+
+function commandEnv(identity: string): Readonly<Record<string, string>> {
+  return { MOSAIC_GIT_IDENTITY: identity, GIT_TERMINAL_PROMPT: '0' };
+}
+
+function findingView(
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+): readonly { readonly code: string; readonly reasonCode: string | null }[] {
+  return findings.map((finding): { readonly code: string; readonly reasonCode: string | null } => ({
+    code: finding.code,
+    reasonCode: finding.reasonCode,
+  }));
+}
+
+function blocked(
+  reasonCode: string,
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+  owner: MigrationOwnerResolution | null = null,
+  migration: MigrationResult | null = null,
+): ProvisionResult {
+  return {
+    status: 'blocked',
+    reasonCode,
+    findings: findingView(findings),
+    owner: owner === null ? null : { verdict: owner.verdict, reasonCode: owner.reasonCode },
+    migration:
+      migration === null ? null : { status: migration.status, reported: migration.reported },
+  };
+}
+
+function failed(
+  reasonCode: string,
+  findings: readonly { readonly code: string; readonly reasonCode: string | null }[],
+  owner: MigrationOwnerResolution | null = null,
+  migration: MigrationResult | null = null,
+): ProvisionResult {
+  return {
+    ...blocked(reasonCode, findings, owner, migration),
+    status: 'failed',
+  };
+}
+
+export async function provisionBrain(
+  input: {
+    readonly estateRegistrySource: string;
+    readonly ownerPolicySource: string;
+    readonly targetGitUrl: string;
+    readonly requestedOwner: string;
+    readonly identity: string;
+    readonly refusalIdentity: string;
+    readonly root: string;
+    readonly sourceRoot: string;
+    readonly seat: string;
+    readonly lane: string;
+    readonly laneActive: boolean;
+  },
+  dependencies: {
+    readonly run: CommandRunner;
+    readonly fetch: OwnerFetch;
+    readonly absentControlName: () => string;
+    readonly approveMigrationContent?: (path: string, content: Uint8Array) => boolean;
+  },
+): Promise<ProvisionResult> {
+  const brainNamespace = parseRequestedOwner(input.requestedOwner);
+  if (brainNamespace === null) return blocked('owner-name-invalid', []);
+  const target = deriveBrainTarget(input.estateRegistrySource, input.targetGitUrl, brainNamespace);
+  if (existsSync(input.root)) {
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return blocked('brain-root-permissions-unsafe', []);
+    }
+  }
+  const doctorInput = {
+    registrySource: input.estateRegistrySource,
+    targetGitUrl: input.targetGitUrl,
+    brainNamespace,
+    identity: input.identity,
+    root: input.root,
+  };
+  let report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  if (report.access.outcome !== 'ok') {
+    return blocked('credential-postcondition-failed', report.findings);
+  }
+
+  const refusalControl = collectBrainRefusalControl(
+    {
+      registrySource: input.estateRegistrySource,
+      targetGitUrl: input.targetGitUrl,
+      brainNamespace,
+      refusalIdentity: input.refusalIdentity,
+    },
+    dependencies.run,
+  );
+  if (!refusalControl.observed) {
+    return blocked('refusal-control-failed', [
+      ...report.findings,
+      {
+        code: 'brain-refusal-control-indeterminate',
+        reasonCode: refusalControl.reasonCode,
+      },
+    ]);
+  }
+
+  const owner = await resolveProviderDurableOwner(
+    {
+      estateRegistrySource: input.estateRegistrySource,
+      ownerPolicySource: input.ownerPolicySource,
+      host: target.host,
+      requestedOwner: input.requestedOwner,
+    },
+    {
+      fetch: dependencies.fetch,
+      absentControlName: dependencies.absentControlName,
+    },
+  );
+  if (owner.verdict !== 'resolved') {
+    const plan = discoverBrainMigration(
+      {
+        sourceRoot: input.sourceRoot,
+        brainRoot: input.root,
+        seat: input.seat,
+        lane: input.lane,
+        laneActive: input.laneActive,
+      },
+      (): MigrationOwnerResolution => owner,
+    );
+    const migration = migrateBrainState(
+      plan,
+      (): never => {
+        throw new Error('blocked owner cannot publish');
+      },
+      input.root,
+    );
+    return blocked(owner.reasonCode, report.findings, owner, migration);
+  }
+
+  if (report.findings.some((finding): boolean => finding.code === 'brain-clone-missing')) {
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return failed('brain-root-permissions-unsafe', report.findings);
+    }
+    const clone: CommandRequest = {
+      program: 'git',
+      args: ['clone', '--branch', 'main', '--single-branch', target.cloneUrl, input.root],
+      env: commandEnv(input.identity),
+    };
+    const cloneResult: CommandResult = dependencies.run(clone);
+    if (cloneResult.status !== 0) return failed('brain-clone-failed', report.findings);
+    try {
+      ensureBrainRootPrivate(input.root);
+    } catch {
+      return failed('brain-root-permissions-unsafe', report.findings);
+    }
+    report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  }
+
+  const blockingCloneFindings = report.findings.filter(
+    (finding): boolean =>
+      finding.code === 'brain-clone-missing' ||
+      finding.code === 'brain-not-git-repository' ||
+      finding.code === 'brain-remote-mismatch' ||
+      finding.code === 'brain-branch-mismatch' ||
+      finding.code === 'brain-uncommitted-state' ||
+      finding.code === 'brain-git-state-indeterminate' ||
+      finding.code === 'brain-root-permissions-unsafe' ||
+      finding.code.startsWith('brain-write-access-'),
+  );
+  if (blockingCloneFindings.length > 0) {
+    return blocked('brain-postcondition-failed', report.findings);
+  }
+
+  let skeletonEntries: readonly MigrationPublishEntry[];
+  try {
+    const skeleton = createBrainSkeleton(input.root);
+    skeletonEntries = skeleton.publicationEntries;
+  } catch {
+    return failed('brain-skeleton-failed', report.findings);
+  }
+  if (skeletonEntries.length > 0) {
+    try {
+      const evidence = publishBrainPaths(
+        {
+          root: input.root,
+          identity: input.identity,
+          entries: skeletonEntries,
+          message: 'chore: seed durable brain layout',
+        },
+        dependencies.run,
+      );
+      if (!evidence.reachable) return failed('brain-skeleton-not-reachable', report.findings);
+    } catch {
+      return failed('brain-skeleton-publish-failed', report.findings);
+    }
+  }
+
+  const plan = discoverBrainMigration(
+    {
+      sourceRoot: input.sourceRoot,
+      brainRoot: input.root,
+      seat: input.seat,
+      lane: input.lane,
+      laneActive: input.laneActive,
+    },
+    (): MigrationOwnerResolution => owner,
+    dependencies.approveMigrationContent,
+  );
+  const migration = migrateBrainState(
+    plan,
+    (brainRoot: string, entries: readonly MigrationPublishEntry[]) =>
+      publishBrainPaths(
+        {
+          root: brainRoot,
+          identity: input.identity,
+          entries,
+          message: `migrate: archive ${input.lane} working memory`,
+        },
+        dependencies.run,
+      ),
+    input.root,
+  );
+
+  if (migration.status === 'failed') {
+    return failed('brain-migration-publish-failed', report.findings, owner, migration);
+  }
+
+  report = collectBrainDoctorReport(doctorInput, dependencies.run);
+  if (report.findings.length > 0) {
+    return blocked('brain-final-postcondition-failed', report.findings, owner, migration);
+  }
+  return {
+    status: 'provisioned',
+    reasonCode: 'brain-provisioned',
+    findings: [],
+    owner: { verdict: owner.verdict, reasonCode: owner.reasonCode },
+    migration: { status: migration.status, reported: migration.reported },
+  };
+}
@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+interface SecureConfigModule {
+  readBrainConfigSecure(path: string, root: string): string;
+}
+
+const roots: string[] = [];
+
+async function loadSecureConfig(): Promise<SecureConfigModule> {
+  try {
+    return (await import('./brain-secure-config.js')) as SecureConfigModule;
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`MB-REQ-06 secure brain config reader is absent (${detail})`);
+  }
+}
+
+function fixture(): { readonly root: string; readonly directory: string; readonly file: string } {
+  const outer = mkdtempSync(join(tmpdir(), 'mosaic-brain-secure-config-'));
+  roots.push(outer);
+  const root = join(outer, 'mosaic');
+  const directory = join(root, 'brain');
+  const file = join(directory, 'owners.json');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  writeFileSync(file, '{"version":1}\n', { mode: 0o600 });
+  return { root, directory, file };
+}
+
+afterEach((): void => {
+  vi.restoreAllMocks();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('security-critical brain configuration reads', (): void => {
+  it('reads a principal-owned non-writable regular file through the secure descriptor path', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+
+    expect(secure.readBrainConfigSecure(config.file, config.root)).toBe('{"version":1}\n');
+  });
+
+  it('rejects a managed root owned by a UID other than the running principal', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    if (typeof process.getuid !== 'function') throw new Error('test requires POSIX getuid');
+    const processWithUid = process as typeof process & { getuid: () => number };
+    const actualUid = processWithUid.getuid();
+    vi.spyOn(processWithUid, 'getuid').mockReturnValue(actualUid + 1);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-ancestor-owner-unsafe/,
+    );
+  });
+
+  it('rejects a group/world-writable policy file', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    chmodSync(config.file, 0o666);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-file-permissions-unsafe/,
+    );
+  });
+
+  it('rejects a group/world-writable managed ancestor', async (): Promise<void> => {
+    const secure = await loadSecureConfig();
+    const config = fixture();
+    chmodSync(config.directory, 0o777);
+
+    expect(() => secure.readBrainConfigSecure(config.file, config.root)).toThrow(
+      /config-ancestor-permissions-unsafe/,
+    );
+  });
+});
@@ -0,0 +1,52 @@
+import { lstatSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { assertCanonicalContainment, readRegularFileSecure } from '../fleet/secure-file.js';
+
+const MAX_CONFIG_BYTES = 256 * 1024;
+const GROUP_OR_OTHER_WRITE = 0o022;
+
+function currentUid(): number {
+  if (typeof process.getuid !== 'function') {
+    throw new Error('config-owner-check-unsupported');
+  }
+  return process.getuid();
+}
+
+function assertOwnedNonWritableDirectory(path: string, uid: number): void {
+  const status = lstatSync(path);
+  if (!status.isDirectory() || status.isSymbolicLink() || status.uid !== uid) {
+    throw new Error('config-ancestor-owner-unsafe');
+  }
+  if ((status.mode & GROUP_OR_OTHER_WRITE) !== 0) {
+    throw new Error('config-ancestor-permissions-unsafe');
+  }
+}
+
+export function readBrainConfigSecure(path: string, root: string): string {
+  const canonicalRoot = resolve(root);
+  const canonicalPath = resolve(path);
+  assertCanonicalContainment(canonicalRoot, canonicalPath);
+  const uid = currentUid();
+  assertOwnedNonWritableDirectory(canonicalRoot, uid);
+  let cursor = canonicalRoot;
+  for (const component of relative(canonicalRoot, dirname(canonicalPath))
+    .split(sep)
+    .filter(Boolean)) {
+    cursor = resolve(cursor, component);
+    assertOwnedNonWritableDirectory(cursor, uid);
+  }
+
+  const snapshot = readRegularFileSecure(canonicalPath, {
+    root: canonicalRoot,
+    maxBytes: MAX_CONFIG_BYTES,
+  });
+  if (snapshot.uid !== uid) throw new Error('config-file-owner-unsafe');
+  if ((snapshot.mode & GROUP_OR_OTHER_WRITE) !== 0) {
+    throw new Error('config-file-permissions-unsafe');
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(snapshot.content);
+  } catch {
+    throw new Error('config-file-not-utf8');
+  }
+}
@@ -0,0 +1,569 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import {
+  assessCredentialResult,
+  brainRootIsPrivate,
+  deriveBrainTarget,
+  ensureBrainRootPrivate,
+  evaluateBrainDoctor,
+  planBrainDoctorFix,
+  type BrainDoctorFinding,
+  type BrainDoctorObservation,
+  type CredentialAssessment,
+} from './brain-store.js';
+
+const COMMIT = /^[0-9a-f]{40}$/;
+const GIT_OBJECT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_PUBLISH_ENTRY_BYTES = 1024 * 1024;
+
+export interface CommandRequest {
+  readonly program: 'git' | 'mosaic';
+  readonly args: readonly string[];
+  readonly cwd?: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly stdin?: Uint8Array;
+}
+
+export interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export type CommandRunner = (request: CommandRequest) => CommandResult;
+
+export const systemCommandRunner: CommandRunner = (request: CommandRequest): CommandResult => {
+  const result = spawnSync(request.program, request.args, {
+    cwd: request.cwd,
+    env: { ...process.env, ...request.env },
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024,
+    input: request.stdin,
+  });
+  return {
+    status: result.status ?? 127,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? result.error?.message ?? '',
+  };
+};
+
+export interface DoctorRuntimeReport {
+  readonly findings: readonly BrainDoctorFinding[];
+  readonly access: CredentialAssessment;
+  readonly refusalControl: {
+    readonly observed: boolean;
+    readonly reasonCode: string | null;
+  };
+}
+
+export interface BrainRefusalControlResult {
+  readonly observed: boolean;
+  readonly reasonCode: string | null;
+  readonly gitReasonCode: string;
+  readonly apiReasonCode: string;
+}
+
+export interface PublishEvidence {
+  readonly commit: string;
+  readonly remoteHead: string;
+  readonly reachable: boolean;
+}
+
+function commandEnv(identity: string): Readonly<Record<string, string>> {
+  return {
+    MOSAIC_GIT_IDENTITY: identity,
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
+function integrationFailure(): CredentialAssessment {
+  return {
+    outcome: 'indeterminate',
+    exitCode: 30,
+    reasonCode: 'unexpected-provider-shape',
+    diagnostic: 'indeterminate: unexpected-provider-shape',
+  };
+}
+
+function runGit(run: CommandRunner, identity: string, args: readonly string[]): CommandResult {
+  return run({ program: 'git', args, env: commandEnv(identity) });
+}
+
+function runGitWithEnv(
+  run: CommandRunner,
+  identity: string,
+  args: readonly string[],
+  env: Readonly<Record<string, string>>,
+  stdin?: Uint8Array,
+): CommandResult {
+  return run({ program: 'git', args, env: { ...commandEnv(identity), ...env }, stdin });
+}
+
+export function collectBrainDoctorReport(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly identity: string;
+    readonly root: string;
+  },
+  run: CommandRunner,
+): DoctorRuntimeReport {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  const validation = run({
+    program: 'mosaic',
+    args: [
+      'cred',
+      'validate',
+      input.identity,
+      '--estate',
+      target.estate,
+      '--host',
+      target.host,
+      '--repo',
+      target.repo,
+      '--require',
+      'write',
+      '--json',
+    ],
+    env: commandEnv(input.identity),
+  });
+  let access = assessCredentialResult(validation.stdout, {
+    identity: input.identity,
+    estate: target.estate,
+    host: target.host,
+    repo: target.repo,
+  });
+  if (validation.status !== access.exitCode) access = integrationFailure();
+
+  const rootExists = existsSync(input.root);
+  let gitRepository = false;
+  let remote: string | null = null;
+  let branch: string | null = null;
+  let worktreeState: BrainDoctorObservation['worktreeState'] = 'unmeasurable';
+  if (rootExists) {
+    const repository = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'rev-parse',
+      '--is-inside-work-tree',
+    ]);
+    gitRepository = repository.status === 0 && repository.stdout.trim() === 'true';
+    if (gitRepository) {
+      const remoteResult = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'remote',
+        'get-url',
+        'origin',
+      ]);
+      const branchResult = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'branch',
+        '--show-current',
+      ]);
+      const statusResult = runGit(run, input.identity, ['-C', input.root, 'status', '--porcelain']);
+      if (remoteResult.status === 0) remote = remoteResult.stdout.trim();
+      if (branchResult.status === 0) branch = branchResult.stdout.trim();
+      if (statusResult.status === 0) {
+        worktreeState = statusResult.stdout.trim().length > 0 ? 'dirty' : 'clean';
+      }
+    }
+  }
+
+  const observation: BrainDoctorObservation = {
+    rootExists,
+    rootPrivate: rootExists && brainRootIsPrivate(input.root),
+    gitRepository,
+    remote,
+    branch,
+    worktreeState,
+    access,
+  };
+  const refusalMarker = `refused reason=${access.reasonCode}`;
+  const refusalObserved =
+    validation.status === 10 &&
+    access.outcome === 'refused' &&
+    access.reasonCode === 'no-token-for-identity' &&
+    validation.stderr.includes(refusalMarker);
+  return {
+    findings: evaluateBrainDoctor(observation, target.cloneUrl),
+    access,
+    refusalControl: {
+      observed: refusalObserved,
+      reasonCode: refusalObserved ? access.reasonCode : null,
+    },
+  };
+}
+
+export function collectBrainRefusalControl(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly refusalIdentity: string;
+  },
+  run: CommandRunner,
+): BrainRefusalControlResult {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(input.refusalIdentity)) {
+    return {
+      observed: false,
+      reasonCode: 'permission-evidence-disagrees',
+      gitReasonCode: 'invalid-control-identity',
+      apiReasonCode: 'invalid-control-identity',
+    };
+  }
+  const apiResult = run({
+    program: 'mosaic',
+    args: [
+      'cred',
+      'validate',
+      input.refusalIdentity,
+      '--estate',
+      target.estate,
+      '--host',
+      target.host,
+      '--repo',
+      target.repo,
+      '--require',
+      'write',
+      '--json',
+    ],
+    env: commandEnv(input.refusalIdentity),
+  });
+  let api = assessCredentialResult(apiResult.stdout, {
+    identity: input.refusalIdentity,
+    estate: target.estate,
+    host: target.host,
+    repo: target.repo,
+  });
+  if (apiResult.status !== api.exitCode) api = integrationFailure();
+
+  const gitResult = runGit(run, input.refusalIdentity, ['ls-remote', target.cloneUrl, 'HEAD']);
+  const marker = /(?:^|\s)reason=([a-z0-9-]+)(?:\s|$)/.exec(gitResult.stderr)?.[1];
+  const stableRefusals = new Set([
+    'identity-required',
+    'estate-required',
+    'estate-host-mismatch',
+    'cross-estate-resolution',
+    'no-token-for-identity',
+    'tea-login-missing',
+    'tea-login-host-mismatch',
+    'provider-identity-mismatch',
+    'credential-rejected',
+    'permission-denied',
+    'organization-membership-required',
+    'team-membership-required',
+  ]);
+  const gitReasonCode =
+    gitResult.status === 0
+      ? 'transport-accepted'
+      : marker !== undefined && stableRefusals.has(marker) && gitResult.stdout.length === 0
+        ? marker
+        : 'transport-indeterminate';
+  const observed =
+    api.outcome === 'refused' &&
+    gitReasonCode !== 'transport-accepted' &&
+    gitReasonCode !== 'transport-indeterminate' &&
+    gitReasonCode === api.reasonCode;
+  return {
+    observed,
+    reasonCode: observed ? api.reasonCode : 'permission-evidence-disagrees',
+    gitReasonCode,
+    apiReasonCode: api.reasonCode,
+  };
+}
+
+export function repairBrainDoctor(
+  input: {
+    readonly registrySource: string;
+    readonly targetGitUrl: string;
+    readonly brainNamespace: string;
+    readonly identity: string;
+    readonly root: string;
+  },
+  run: CommandRunner,
+): DoctorRuntimeReport {
+  const target = deriveBrainTarget(input.registrySource, input.targetGitUrl, input.brainNamespace);
+  let report = collectBrainDoctorReport(input, run);
+  const actions = planBrainDoctorFix({
+    findings: report.findings,
+    target,
+    identity: input.identity,
+    root: input.root,
+  });
+  for (const action of actions) {
+    if (action.program === 'mosaic') {
+      run({ program: 'mosaic', args: action.args, env: commandEnv(input.identity) });
+      report = collectBrainDoctorReport(input, run);
+      if (report.access.outcome !== 'ok') return report;
+      continue;
+    }
+    if (action.findingCode === 'brain-clone-missing') {
+      try {
+        ensureBrainRootPrivate(input.root);
+      } catch {
+        return collectBrainDoctorReport(input, run);
+      }
+    }
+    const result = runGit(run, input.identity, action.args);
+    if (result.status !== 0) return collectBrainDoctorReport(input, run);
+  }
+  return collectBrainDoctorReport(input, run);
+}
+
+function requireSuccess(result: CommandResult, operation: string): void {
+  if (result.status !== 0) throw new Error(`${operation}-failed`);
+}
+
+function containedRelative(root: string, path: string): string {
+  if (isAbsolute(path) === false) throw new Error('brain-publish-path-must-be-absolute');
+  const absoluteRoot = resolve(root);
+  const absolutePath = resolve(path);
+  if (absolutePath === absoluteRoot || !absolutePath.startsWith(`${absoluteRoot}${sep}`)) {
+    throw new Error('brain-publish-path-escaped-root');
+  }
+  return relative(absoluteRoot, absolutePath).split(sep).join('/');
+}
+
+export function publishBrainPaths(
+  input: {
+    readonly root: string;
+    readonly identity: string;
+    readonly entries: readonly {
+      readonly path: string;
+      readonly content: Uint8Array;
+    }[];
+    readonly message: string;
+  },
+  run: CommandRunner,
+): PublishEvidence {
+  if (input.entries.length === 0) throw new Error('brain-publish-paths-empty');
+  if (input.message.trim().length === 0) throw new Error('brain-publish-message-empty');
+  const entries = input.entries.map((entry) => {
+    if (entry.content.byteLength > MAX_PUBLISH_ENTRY_BYTES) {
+      throw new Error('brain-publish-entry-too-large');
+    }
+    return {
+      path: containedRelative(input.root, entry.path),
+      content: Uint8Array.from(entry.content),
+    };
+  });
+  const paths = entries.map((entry): string => entry.path);
+  if (new Set(paths).size !== paths.length) throw new Error('brain-publish-path-duplicate');
+
+  const readHead = (): string => {
+    const result = runGit(run, input.identity, ['-C', input.root, 'rev-parse', 'HEAD']);
+    requireSuccess(result, 'brain-git-read-commit');
+    const value = result.stdout.trim();
+    if (!COMMIT.test(value)) throw new Error('brain-git-commit-shape-invalid');
+    return value;
+  };
+  const verifyCommitIdentity = (commit: string): void => {
+    const result = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'show',
+      '-s',
+      '--format=%an%x00%ae%x00%cn%x00%ce',
+      commit,
+    ]);
+    requireSuccess(result, 'brain-git-read-commit-identity');
+    const expectedEmail = `${input.identity}@fleet.mosaicstack.dev`;
+    const [author, authorEmail, committer, committerEmail] = result.stdout.trimEnd().split('\0');
+    if (
+      author !== input.identity ||
+      authorEmail !== expectedEmail ||
+      committer !== input.identity ||
+      committerEmail !== expectedEmail
+    ) {
+      throw new Error('brain-git-commit-identity-mismatch');
+    }
+  };
+  const expectedObjects = new Map<string, string>();
+  const verifyCommitObjects = (commit: string): void => {
+    for (const [path, expected] of expectedObjects) {
+      const result = runGit(run, input.identity, [
+        '-C',
+        input.root,
+        'rev-parse',
+        `${commit}:${path}`,
+      ]);
+      requireSuccess(result, 'brain-git-read-commit-object');
+      if (result.stdout.trim() !== expected) throw new Error('brain-git-commit-content-mismatch');
+    }
+  };
+  const reconcileRealIndex = (): void => {
+    for (const [path, objectId] of expectedObjects) {
+      requireSuccess(
+        runGit(run, input.identity, [
+          '-C',
+          input.root,
+          'update-index',
+          '--add',
+          '--cacheinfo',
+          '100644',
+          objectId,
+          path,
+        ]),
+        'brain-git-reconcile-checkout-index',
+      );
+    }
+  };
+  const verifyCommitPaths = (commit: string): void => {
+    const changed = runGit(run, input.identity, [
+      '-C',
+      input.root,
+      'diff-tree',
+      '--root',
+      '--no-commit-id',
+      '--name-only',
+      '-r',
+      '-z',
+      commit,
+    ]);
+    requireSuccess(changed, 'brain-git-read-commit-paths');
+    const names = changed.stdout.split('\0').filter(Boolean);
+    const approved = new Set(paths);
+    if (names.length === 0 || names.some((name: string): boolean => !approved.has(name))) {
+      throw new Error('brain-git-commit-paths-unapproved');
+    }
+  };
+
+  const base = readHead();
+  const indexRoot = mkdtempSync(join(tmpdir(), 'mosaic-brain-index-'));
+  const isolatedEnv = { GIT_INDEX_FILE: join(indexRoot, 'index') };
+  let commit = base;
+  let createdCommit = false;
+  try {
+    requireSuccess(
+      runGitWithEnv(run, input.identity, ['-C', input.root, 'read-tree', base], isolatedEnv),
+      'brain-git-isolated-index-init',
+    );
+    for (const entry of entries) {
+      const object = runGitWithEnv(
+        run,
+        input.identity,
+        ['-C', input.root, 'hash-object', '-w', '--stdin'],
+        isolatedEnv,
+        entry.content,
+      );
+      requireSuccess(object, 'brain-git-write-approved-object');
+      const objectId = object.stdout.trim();
+      if (!GIT_OBJECT.test(objectId)) throw new Error('brain-git-object-shape-invalid');
+      expectedObjects.set(entry.path, objectId);
+      requireSuccess(
+        runGitWithEnv(
+          run,
+          input.identity,
+          [
+            '-C',
+            input.root,
+            'update-index',
+            '--add',
+            '--cacheinfo',
+            '100644',
+            objectId,
+            entry.path,
+          ],
+          isolatedEnv,
+        ),
+        'brain-git-stage-approved-object',
+      );
+    }
+    const difference = runGitWithEnv(
+      run,
+      input.identity,
+      ['-C', input.root, 'diff', '--cached', '--quiet', '--exit-code', base, '--', ...paths],
+      isolatedEnv,
+    );
+    if (difference.status === 1) {
+      requireSuccess(
+        runGitWithEnv(
+          run,
+          input.identity,
+          [
+            '-C',
+            input.root,
+            '-c',
+            `user.name=${input.identity}`,
+            '-c',
+            `user.email=${input.identity}@fleet.mosaicstack.dev`,
+            'commit',
+            '-m',
+            input.message,
+          ],
+          isolatedEnv,
+        ),
+        'brain-git-commit',
+      );
+      commit = readHead();
+      verifyCommitPaths(commit);
+      verifyCommitObjects(commit);
+      verifyCommitIdentity(commit);
+      reconcileRealIndex();
+      createdCommit = true;
+    } else if (difference.status !== 0) {
+      throw new Error('brain-git-isolated-diff-failed');
+    }
+  } finally {
+    rmSync(indexRoot, { recursive: true, force: true });
+  }
+
+  let pushed = !createdCommit;
+  for (let attempt = 0; createdCommit && attempt < 3; attempt += 1) {
+    const push = runGit(run, input.identity, ['-C', input.root, 'push', 'origin', 'HEAD:main']);
+    if (push.status === 0) {
+      pushed = true;
+      break;
+    }
+    const concurrentUpdate = /non-fast-forward|fetch first|\[rejected\]/i.test(push.stderr);
+    if (!concurrentUpdate || attempt === 2) throw new Error('brain-git-push-failed');
+    requireSuccess(
+      runGit(run, input.identity, ['-C', input.root, 'fetch', 'origin', 'main']),
+      'brain-git-fetch-concurrent',
+    );
+    requireSuccess(
+      runGit(run, input.identity, [
+        '-C',
+        input.root,
+        '-c',
+        `user.name=${input.identity}`,
+        '-c',
+        `user.email=${input.identity}@fleet.mosaicstack.dev`,
+        'rebase',
+        'origin/main',
+      ]),
+      'brain-git-rebase-concurrent',
+    );
+    commit = readHead();
+    verifyCommitPaths(commit);
+    verifyCommitObjects(commit);
+    verifyCommitIdentity(commit);
+  }
+  if (!pushed) throw new Error('brain-git-push-failed');
+  requireSuccess(
+    runGit(run, input.identity, ['-C', input.root, 'fetch', 'origin', 'main']),
+    'brain-git-fetch-readback',
+  );
+  const reachableResult = runGit(run, input.identity, [
+    '-C',
+    input.root,
+    'merge-base',
+    '--is-ancestor',
+    commit,
+    'origin/main',
+  ]);
+  if (reachableResult.status !== 0 && reachableResult.status !== 1) {
+    throw new Error('brain-git-reachability-check-failed');
+  }
+  const remoteResult = runGit(run, input.identity, ['-C', input.root, 'rev-parse', 'origin/main']);
+  requireSuccess(remoteResult, 'brain-git-read-remote-head');
+  const remoteHead = remoteResult.stdout.trim();
+  if (!COMMIT.test(remoteHead)) throw new Error('brain-git-remote-head-shape-invalid');
+  return { commit, remoteHead, reachable: reachableResult.status === 0 };
+}
@@ -29,6 +29,11 @@ import { readPersonaContractBlock } from '../fleet/persona-contract.js';
 import { canonicalizeRoleClass } from './fleet-personas.js';
 import { launchClaudex, type ClaudexHarnessAdapter } from './claudex.js';
 import { runLeaseEnforcementDoctorCheck } from './lease-doctor-check.js';
+import {
+  defaultInstalledBrainDoctorOptions,
+  runInstalledBrainDoctorCheck,
+} from './brain-doctor-check.js';
+import { systemCommandRunner } from './brain-store-runtime.js';

 const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
 const MAX_INSTALLED_TOOLS_BYTES = 256 * 1024;
@@ -1257,8 +1262,11 @@ export function registerLaunchCommands(program: Command): void {
      });
  }

-  // `doctor` — the framework drift audit (bash script) PLUS the #869
-  // Point-1 C5 lease-enforcement activation check (TS, reusing C1's
+  // `doctor` — the framework drift audit (bash script), the #869
+  // Point-1 C5 lease-enforcement activation check, and the #1051 per-estate
+  // durable brain check. Both TS checks run before the bash audit and can
+  // force a non-zero result for hard/indeterminate failures.
+  // The lease check reuses C1's
  // `leaseEnforcementActivatable()` and C3's `checkBrokerSupervisorHealth()`).
  // Kept out of the generic `directCommands` loop above because this check
  // must run and report BEFORE the bash script's own exit, and must be able
@@ -1267,14 +1275,29 @@ export function registerLaunchCommands(program: Command): void {
  // undiagnosed (see lease-doctor-check.ts docstring).
  program
    .command('doctor')
-    .description('Health audit — detect drift, missing files, and #869 lease-activation gaps')
+    .description('Health audit — detect drift, lease gaps, and per-estate brain defects')
    .allowUnknownOption(true)
    .allowExcessArguments(true)
    .action(async (_opts: unknown, cmd: Command) => {
      checkMosaicHome();
      const leaseCheck = await runLeaseEnforcementDoctorCheck();
      const leaseCheckFailed = printLeaseDoctorCheck(leaseCheck);
-      runDoctorScriptAndExit(fwScript('mosaic-doctor'), cmd.args, leaseCheckFailed);
+      const fix = cmd.args.includes('--fix');
+      const brainCheck = runInstalledBrainDoctorCheck(
+        defaultInstalledBrainDoctorOptions(fix),
+        systemCommandRunner,
+      );
+      for (const line of brainCheck.lines) {
+        (brainCheck.status === 'ok' ? console.log : console.error)(line);
+      }
+      const brainCheckFailed =
+        brainCheck.status === 'error' ||
+        (brainCheck.status === 'warn' && cmd.args.includes('--fail-on-warn'));
+      runDoctorScriptAndExit(
+        fwScript('mosaic-doctor'),
+        cmd.args,
+        leaseCheckFailed || brainCheckFailed,
+      );
    });
 }

@@ -22,6 +22,8 @@ export interface SecureFileSnapshot {
  mode: number;
  dev: number | bigint;
  ino: number | bigint;
+  uid: number;
+  gid: number;
 }

 function sameIdentity(
@@ -235,6 +237,8 @@ export function readRegularFileSecure(
      mode: Number(opened.mode),
      dev: opened.dev,
      ino: opened.ino,
+      uid: opened.uid,
+      gid: opened.gid,
    };
  } finally {
    closeDescriptors(openedFile.descriptors);
Author	SHA1	Message	Date
be-coder-07	a50b5a6b4d	fix(mosaic): enforce private brain checkout ci/woodpecker/pr/ci Pipeline failed Details	2026-08-05 17:19:51 -05:00
be-coder-07	22cedbb506	fix(mosaic): reject unapproved brain skeleton state	2026-08-05 17:19:51 -05:00
be-coder-07	bad53564ed	fix(mosaic): preserve measurable brain git state	2026-08-05 17:19:50 -05:00
be-coder-07	518c4185ee	test(mosaic): control brain config owner binding	2026-08-05 17:19:50 -05:00
be-coder-07	877473c244	fix(mosaic): bind brain commits to approved blobs	2026-08-05 17:19:50 -05:00
be-coder-07	f0555016f4	fix(mosaic): isolate brain publication index	2026-08-05 17:19:50 -05:00
be-coder-07	fb7087b3eb	fix(mosaic): quarantine unscanned brain state	2026-08-05 17:19:50 -05:00
be-coder-07	836aab1ab5	fix(mosaic): bound brain migration and owner lookups	2026-08-05 17:19:50 -05:00
be-coder-07	656fa9ceb7	fix(mosaic): fail closed on unsafe brain cleanup and config	2026-08-05 17:19:50 -05:00
be-coder-07	6afb3cb5b3	fix(mosaic): hold brain migration destinations by descriptor	2026-08-05 17:19:50 -05:00
be-coder-07	351cb67cec	fix(mosaic): exclude nested secret migration paths	2026-08-05 17:19:50 -05:00
be-coder-07	fcfc1b08f9	fix(mosaic): harden brain migration snapshots	2026-08-05 17:19:50 -05:00
be-coder-07	2451c2f21a	feat(mosaic): provision per-estate durable brain	2026-08-05 17:19:50 -05:00
be-coder-07	c6329ec91e	test(installer): preregister durable brain P7 integration	2026-08-05 17:19:50 -05:00
be-coder-07	01694f3f98	test(#1051 ): preregister mosaic-brain acceptance contract	2026-08-05 17:19:50 -05:00
be-coder-08andMos	85d2108e4e	fix(ci): remove upgrade rollback signal race (#1060 ) ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: be-coder-08 <[email protected]>	2026-08-05 22:14:15 +00:00
be-coder-08andMos	16f91157a1	test(ci): make queue guard harness deterministic (#1062 ) ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: be-coder-08 <[email protected]>	2026-08-05 21:49:44 +00:00
coder-mos1andmos-dt-0	5916aeefd6	chore(release): @mosaicstack/mosaic 0.0.49 — ship RM-03 guard fix to release channel (#1036 ) ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline failed Details Co-authored-by: coder-mos1 <[email protected]>	2026-08-02 20:09:11 +00:00
coder-mos1andmos-dt-0	58b971aba3	fix(rm-03): make CI queue guard fail on asserted non-readiness (#1032 ) ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: coder-mos1 <[email protected]>	2026-08-01 18:55:26 +00:00