fix: reject malformed generated roots

docs: record scoped AC2 and AC8 evidence
fix: certify generated symlink state
2026-07-31 19:25:44 -05:00 · 2026-07-31 19:23:02 -05:00 · 2026-07-31 19:20:39 -05:00 · 2026-07-31 18:30:16 -05:00 · 2026-07-31 18:25:20 -05:00 · 2026-07-31 17:50:58 -05:00
17 changed files with 1506 additions and 86 deletions
@@ -8,6 +8,7 @@ coverage
 .env.local
 *.tsbuildinfo
 .pnpm-store
+__pycache__/
 docs/reports/

 # Step-CA dev password — real file is gitignored; commit only the .example
@@ -1 +1 @@
-pnpm typecheck && pnpm lint && pnpm format:check
+pnpm preflight && pnpm typecheck && pnpm lint && pnpm format:check
@@ -1,5 +1,5 @@
@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
-# Pin the pnpm store to the same path the ci-base image warms (Dockerfile.ci),
-# so the pipeline `pnpm install --prefer-offline` consumes the baked store
-# instead of repopulating a fresh one.
-store-dir=/root/.local/share/pnpm/store
+# HOME resolves to /root in the ci-base image, preserving its warmed-store path.
+# Non-root checkouts use their own HOME. Override without editing this file via
+# NPM_CONFIG_STORE_DIR (pnpm's environment form of the store-dir setting).
+store-dir=${HOME}/.local/share/pnpm/store
@@ -201,8 +201,21 @@ git clone [email protected]:mosaicstack/stack.git
 cd stack

 # Install dependencies. The local tier uses in-process PGlite; leave DATABASE_URL unset.
+# The pnpm store defaults to $HOME/.local/share/pnpm/store. Override it without
+# editing the checkout with NPM_CONFIG_STORE_DIR=$HOME/another-store if needed.
 pnpm install

+# Verify dependencies and generated state before running source-quality gates.
+# Missing dependencies exit 42; stale/foreign apps/web/.next state exits 43.
+# The web build certifies its exact standalone symlink manifest; added, removed,
+# retargeted, or manifest-only-tampered generated links also exit 43. This detects
+# accidental, independent, stale, and foreign-residue mutation—the class exposed by
+# a five-month-stale .next that produced 19 phantom TS2307 errors.
+# It does NOT defend against a same-UID actor that can rewrite both manifest and
+# marker consistently (CWE-345). RM-59 tracks the required executor/spine-side
+# trust anchor outside worktree authority.
+pnpm preflight
+
 # Optional local queue service only. This does not start PostgreSQL.
 docker compose up -d valkey

@@ -230,6 +243,7 @@ Gateway start command until KBN-101-02 makes that state fail closed.
 ### Quality Gates

 ```bash
+pnpm preflight               # Checkout/dependency/generated-state validation
 pnpm typecheck               # TypeScript type checking (all packages)
 pnpm lint                    # ESLint (all packages)
 pnpm test                    # Vitest (all packages)
@@ -3,7 +3,7 @@
  "version": "0.0.2",
  "private": true,
  "scripts": {
-    "build": "next build",
+    "build": "node ../../scripts/build-web.mjs",
    "dev": "next dev",
    "lint": "eslint src",
    "typecheck": "tsc --noEmit",
@@ -0,0 +1,15 @@
+<!-- board-roll: 1 entry rolled from BOARD.md -->
+
+### **D-1 / P-ACTIVATION + hygiene — committed `.npmrc` hard-pins `store-dir=/root/.local/share/pnpm/store`.**
+
+Correct for the CI container (runs as root), fatal for EVERY non-root local checkout: `EACCES` on `/root/.local/share/pnpm/store/v10/server/server.json`. A committed config that only works on one runtime is exactly the activation-skew class. Fix candidate: make store-dir env-overridable, not hardcoded.
+
+<!-- board-roll: 2 entries rolled from BOARD.md -->
+
+### **D-3 / P-FLEET-001 — the seats running this mission are UNMANAGED.** `mos-remediation`, `rev-974`,
+
+`planner-opus`, `planner-sol` appear in NO roster (`~/.config/mosaic/fleet/roster.yaml`, `agents/`). Planners run on socket `default`; the roster declares `mosaic-fleet`. This is the exact "one roster-owned socket/host + quarantine unmanaged + stale GC" failure P-FLEET-001 indicts — observed on the remediation mission's own fleet. Prerequisite for INBOX identity-addressing.
+
+### **D-2 / hygiene — husky `prepare` fails `EPERM` copying into root-owned `.husky/_/`.** Repo working
+
+tree has root-owned dirs (`.husky/`, repo root) under a non-root agent. Worked around with the intended `HUSKY=0` escape hatch (does NOT disable the existing pre-commit/pre-push hooks).
@@ -1,6 +1,6 @@
 # mos-remediation — LIVE BOARD (keep < 8 KB)

-**Phase:** PLANNING COMPLETE — reconciled backlog landed; 3 decisions block dispatch.
+**Phase:** EXECUTING — first PR merged; RM-01 in flight; all 3 decisions ruled.
 **Updated:** 2026-07-31 (mos-remediation orchestrator; seat active on `mosaic-fleet`).

 ## Head
@@ -16,14 +16,14 @@

 ## In-flight

-| Task                                              | Owner           | State                                                 |
-| ------------------------------------------------- | --------------- | ----------------------------------------------------- |
-| PR #1026 `remediation/mission-setup` (docs-only)  | mos-remediation | OPEN, stacked on #1025; retarget to main after merge  |
-| PR #1025 `fix/hygiene-inert-format-gate`          | rev-974         | OPEN; ACs pre-registered 22:12:26Z; review DISPATCHED |
-| DECISION-1 wire-in point (charter change)         | Mos / Jason     | ESCALATED — both planners reject the charter's target |
-| DECISION-2 rollback artifact + availability trade | Jason           | ESCALATED                                             |
-| DECISION-3 RM-03 vs parked PR #1023 ownership     | Mos             | ESCALATED                                             |
-| RM-01 reproducible checkout (unblocks everything) | unassigned      | READY TO DISPATCH                                     |
+| Task                                              | Owner           | State                                                              |
+| ------------------------------------------------- | --------------- | ------------------------------------------------------------------ |
+| PR #1026 docs (mission record + backlog)          | mos-remediation | OPEN, retargeted to main, rebased; diff verified docs-only         |
+| PR #1025 hygiene                                  | —               | **MERGED** 52414605; rev-974 APPROVE + CI #2158 8/8 terminal-green |
+| DECISION-1 wire-in point (charter change)         | Mos / Jason     | ESCALATED — both planners reject the charter's target              |
+| DECISION-2 rollback artifact + availability trade | Jason           | ESCALATED                                                          |
+| DECISION-3 RM-03 vs parked PR #1023 ownership     | Mos             | ESCALATED                                                          |
+| RM-01 reproducible checkout (unblocks everything) | unassigned      | READY TO DISPATCH                                                  |

 ## Fleet seats

@@ -53,37 +53,34 @@
 4. Hygiene + conformance harness
   Cross-cutting retirements: flat-file tracking, 3 MACP islands, silent MOSAIC BYPASS.

-## Dogfood evidence captured this session (live failure classes, not hypotheticals)
+## Dogfood evidence — live failure classes, not hypotheticals

- **D-1 / P-ACTIVATION + hygiene — committed `.npmrc` hard-pins `store-dir=/root/.local/share/pnpm/store`.**
-  Correct for the CI container (runs as root), fatal for EVERY non-root local checkout: `EACCES` on
-  `/root/.local/share/pnpm/store/v10/server/server.json`. A committed config that only works on one
-  runtime is exactly the activation-skew class. Fix candidate: make store-dir env-overridable, not hardcoded.
- **D-2 / hygiene — husky `prepare` fails `EPERM` copying into root-owned `.husky/_/`.** Repo working
-  tree has root-owned dirs (`.husky/`, repo root) under a non-root agent. Worked around with the
-  intended `HUSKY=0` escape hatch (does NOT disable the existing pre-commit/pre-push hooks).
- **D-3 / P-FLEET-001 — the seats running this mission are UNMANAGED.** `mos-remediation`, `rev-974`,
-  `planner-opus`, `planner-sol` appear in NO roster (`~/.config/mosaic/fleet/roster.yaml`, `agents/`).
-  Planners run on socket `default`; the roster declares `mosaic-fleet`. This is the exact
-  "one roster-owned socket/host + quarantine unmanaged + stale GC" failure P-FLEET-001 indicts —
-  observed on the remediation mission's own fleet. Prerequisite for INBOX identity-addressing.
- **D-4 / P-LIFECYCLE + hygiene — a dispatched agent silently IGNORED an in-message context reset.**
-  planner-sol was at 64.3%/372k; the brief asked it to reset first; it began work on dirty context anyway.
-  Only an out-of-band `/new` driven by the orchestrator guaranteed clean state. Confirms the postmortem
-  thesis: **instructions are not enforcement.** Reset must be a mechanical pre-dispatch step, not a request.
+> Newest first. Oldest entries roll to `BOARD-LEDGER.md` via `board-roll.sh` when this file
+> exceeds its 8 KB cap. Keystone detail is duplicated in `TASKS.md` §1a, so rolling loses nothing.

- **D-6 / P-QUEUE-001 — the mandated queue guard returned PASS on an UNKNOWN state, live, today.**
-  Running the required `ci-queue-wait.sh --purpose push` before pushing produced
-  `state=unknown ... exit 0` — the exact defect at `ci-queue-wait.sh:282-288` that PR #1023 is parked
-  on. It also evaluated `branch=main` rather than the branch being pushed. The mission's own required
-  pre-push gate passed me on an indeterminate result. Third independent live instance of the class.
- **D-5 / P-QUEUE-001 + P-CONFORMANCE-001 — KEYSTONE: an inert gate that erased its own evidence.**
-  Merged PR #868 (`b79336a8`) shipped a file that FAILS `pnpm format:check` ⇒ the CI format gate did
-  not block. An unrelated later PR (#872) then reformatted that file via its own `lint-staged`, so
-  `main` went green again and nobody learned the gate had failed to fire. Verified blob-level under the
-  repo's own config. **Detection must be per-merge-commit against that commit's own tree** — a "is main
-  green today" check reports all-clear on this exact defect. Binding on RM-02/RM-55. Full chain in
-  `TASKS.md` §1a. NOT quiet-patched, by Mos's ruling: patching the symptom destroys the signal.
+<!-- BOARD-ROLL:START -->
+
+### **D-8 / P-CONFORMANCE-001 — a PRE-REGISTERED acceptance check that was not runnable as written.**
+
+PR #1025 AC2's fixture `mkdir -p apps/*/venv/lib` creates a literal `apps/*/venv/lib` dir when the glob is unmatched — it did not test what it claimed. rev-974 ran it exactly as written, caught it, re-ran the intended assertion at an explicit path, and **disclosed** rather than silently substituting a working fixture and reporting PASS. **Pre-registration protects a check from being retrofitted to the implementation; it does not make the check correct.** An unverified gate appeared inside the mechanism built to catch unverified gates. Hard requirement on RM-02: the registry must self-verify that every registered case runs AND can fail — presence is not evidence.
+
+### **D-7 / P-FLEET-001 — stale-GC-on-disk: shared 30G /tmp hit 100% ENOSPC, degrading two seats.**
+
+~5.2G was session scratch dead 8-9 days (this session's own footprint: 88K). Same missing capability as orphaned-tmux-session GC, applied to disk — not a quota or discipline problem. Resolved manually by Mos (lead coordinator) after independent verification; `/tmp` now 79%. **The gap IS the finding:** the authority to reap exists, the deterministic reaper does not. Folded into RM-50 with explicit requirements (mechanical liveness, age threshold, dry-run, audit event per reap — never a heuristic sweep). Refusing to unilaterally delete another session's scratch was correct doctrine; the fix is a reaper, not braver agents.
+
+### **D-6 / P-QUEUE-001 — the mandated queue guard returned PASS on an UNKNOWN state, live, today.**
+
+Running the required `ci-queue-wait.sh --purpose push` before pushing produced `state=unknown ... exit 0` — the exact defect at `ci-queue-wait.sh:282-288` that PR #1023 is parked on. It also evaluated `branch=main` rather than the branch being pushed. The mission's own required pre-push gate passed me on an indeterminate result. Third independent live instance of the class.
+
+### **D-5 / P-QUEUE-001 + P-CONFORMANCE-001 — KEYSTONE: an inert gate that erased its own evidence.**
+
+Merged PR #868 (`b79336a8`) shipped a file that FAILS `pnpm format:check` ⇒ the CI format gate did not block. An unrelated later PR (#872) then reformatted that file via its own `lint-staged`, so `main` went green again and nobody learned the gate had failed to fire. Verified blob-level under the repo's own config. **Detection must be per-merge-commit against that commit's own tree** — a "is main green today" check reports all-clear on this exact defect. Binding on RM-02/RM-55. Full chain in `TASKS.md` §1a. NOT quiet-patched, by Mos's ruling: patching the symptom destroys the signal.
+
+### **D-4 / P-LIFECYCLE + hygiene — a dispatched agent silently IGNORED an in-message context reset.**
+
+planner-sol was at 64.3%/372k; the brief asked it to reset first; it began work on dirty context anyway. Only an out-of-band `/new` driven by the orchestrator guaranteed clean state. Confirms the postmortem thesis: **instructions are not enforcement.** Reset must be a mechanical pre-dispatch step, not a request.
+
+<!-- BOARD-ROLL:END -->

 ## Decisions log

@@ -4,8 +4,8 @@
 **Sources:** [`DECOMP-OPUS.md`](./DECOMP-OPUS.md) (robustness, 38 tasks / 8 dissents) and
 [`DECOMP-SOL.md`](./DECOMP-SOL.md) (pragmatic, 25 tasks / 10 defers / 7 dissents), produced
 **independently** — neither planner read the other. Charter: [`MISSION.md`](./MISSION.md).
-**Status:** PLANNING — this backlog is proposed, not yet dispatched. Three items need a Mos/Jason
-ruling before the affected tasks dispatch (§5).
+**Status:** EXECUTING — all three blocking decisions RULED by Mos on 2026-07-31 (§5). **RM-01 is
+dispatched.** RM-03 is held pending Jason's disposition of PR #1023; nothing else is blocked.

 > **Provenance of the inputs (both clean).** `planner-opus` ran in a fresh session throughout.
 > `planner-sol` initially began work at 64.3% dirty context despite a brief instructing it to reset;
@@ -40,7 +40,10 @@ point. Both planners independently rejected it on the same evidence: that contro
 point into a disabled rail produces **a stranded executor — the identical built-but-unwired disease,
 one layer up, that would look "done" in a PR.** The live paths are
 `packages/mosaic/src/commands/launch.ts` and `packages/coord/src/runner.ts`.
-This contradicts the charter and is escalated as **DECISION-1** (§5).
+This contradicted the charter and was escalated as DECISION-1 — **now RULED in the planners' favour by
+Mos (§5)**. The corrected target is a new production Node `TaskExecutor` on the live dispatch path
+(`packages/mosaic` launch + `packages/coord`) that Coord/Forge/live dispatch submit through; the
+Python rail is deleted, not ported.

 ---

@@ -66,6 +69,115 @@ side effect, so `main` went green again **without anyone ever learning the gate
 > present-tense framing was wrong. The hygiene PR therefore carries the `.prettierignore` fix only —
 > the README needs no fix today.

+### Third live instance, same class — the queue guard, hit by this orchestrator
+
+Running the **mandated** pre-push guard during TASK-0:
+
+```
+$ ~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push
+[ci-queue-wait] platform=gitea purpose=push branch=main sha=06e0d403…
+[ci-queue-wait] state=unknown purpose=push branch=main
+$ echo $?   →  0
+```
+
+**Two distinct defects in one tool**, both feeding RM-03:
+
+1. **Wrong exit** — `state=unknown` ⇒ `exit 0`. The defect at `ci-queue-wait.sh:282-288` that OPUS
+   documented and that PR #1023 is parked on. A required gate returned PASS on an indeterminate result.
+2. **Wrong branch** — it evaluated `branch=main`, not the branch actually being pushed. Even a
+   correctly-exiting guard would have been answering the wrong question.
+
+**Standing doctrine (Mos):** until RM-03 lands, a green from this guard carries **zero information**
+and must not be cited as merge evidence. Rely on reviewer clearance + real CI.
+
+Three independent live instances in a single session — format gate, agent context reset, queue guard —
+is the class confirmed, not anecdote.
+
+### D-8 — a PRE-REGISTERED acceptance check that was not runnable as written
+
+On PR #1025 the author (me) pre-registered AC2 with the fixture snippet `mkdir -p apps/*/venv/lib`.
+In bash, when no `venv` exists the glob is unmatched and passes through literally, creating a
+directory named `apps/*/venv/lib` rather than one per workspace. The check as written did not test
+what it claimed to test.
+
+`rev-974` ran it **exactly as written**, observed the wrong behaviour, then re-ran the intended
+assertion at an explicit path — **and said so in the review** rather than silently substituting a
+working fixture and reporting PASS.
+
+Two things this establishes:
+
+1. **The instruction "do not adjust a check to fit the diff; if it is unrunnable, say so explicitly"
+   worked.** A silent substitution here would have produced a green AC2 that proved nothing, on the
+   exact task whose subject is gates that appear to work. The disclosure is what made the PASS
+   meaningful.
+2. **Pre-registration does not confer correctness.** A pre-registered check is protected from being
+   retrofitted to the implementation; it is not protected from being _wrong when written_. This is a
+   small instance of the mission's own class — an unverified gate — occurring inside the mechanism
+   built to catch unverified gates.
+
+**Requirement on RM-02 (non-negotiable, sharpened by Mos).** The registry must **self-verify** that
+every registered case demonstrably **runs** and demonstrably **fails on a known-bad input**.
+Presence in the registry is **not** evidence. **A check is not trusted until it has been shown to
+fail.** This is mutation testing / negative control applied _at the registry level_ — meaning
+**the conformance harness must itself be conformance-tested.** A registered case that cannot fail, or
+cannot run, is exactly as inert as an unregistered one, and the registry check must detect that
+itself rather than assume it.
+
+**Requirement on RM-55.** The same recursion applies to the harness: it must be observed red before
+its green is worth anything (OPUS R-063 AC1 already states this; D-8 is the empirical case for it).
+
+**Second, equally load-bearing lesson — reviewer disclosure is what makes a review trustworthy.**
+rev-974 could have silently swapped in a working fixture and reported `AC2 PASS`. Nothing in the
+process would have caught it, and the resulting green would have certified nothing — on the very task
+whose subject is gates that only appear to work. The brief's instruction — _"do not adjust a check to
+fit the diff; if it is genuinely unrunnable as specified, say so explicitly and explain why rather
+than silently substituting your own"_ — is therefore not boilerplate. It is the clause that makes a
+PASS mean something, and it must appear in **every** reviewer brief this mission issues.
+
+### D-7 — shared-tmpfs contention → cascading ENOSPC (live incident, 2026-07-31)
+
+The shared 30 G `/tmp` hit **100% ENOSPC** mid-session. It broke tool calls in **two different seats**
+(mine and Mos's) — a single full disk degrades every agent on the host at once. Recurring: prior
+incidents 2026-06-18 and 2026-07-17.
+
+Attribution matters, because the wrong owner cleans the wrong thing. Measured:
+
+| path                                           | size      | last modified                | owner                                             |
+| ---------------------------------------------- | --------- | ---------------------------- | ------------------------------------------------- |
+| `…/-src-mosaic-stack/6d2faee6…` (this session) | **88 K**  | live                         | mos-remediation                                   |
+| `…/-src-mosaic-stack/c743185d…`                | **3.6 G** | **2026-07-22** (9 days dead) | abandoned session, same project path              |
+| `…/claude-1001/pnpm-store`                     | **1.6 G** | **2026-07-23** (8 days dead) | abandoned; the live store is correctly on `$HOME` |
+
+So ~5.2 G — the bulk of the pressure — is **dead session scratch that nothing will ever read again**.
+This is not a quota problem; it is **P-FLEET-001's stale-session GC, applied to disk instead of tmux
+sessions.** The same missing capability (nothing owns reaping dead ephemeral state) produces both the
+orphaned-session failure and this one. Reaping dead-session scratch belongs in RM-50 alongside stale
+tmux-session GC.
+
+**Added to RM-01 as acceptance criteria:** heavy build artifacts (node_modules, package stores, build
+output) must land on the main disk in the worktree, never on the shared 30 G `/tmp`.
+
+**Resolution, and the part that is actually the finding.** Mos verified the attribution independently
+(mtimes, no process or `lsof` holding either path, no live session maps) and reaped both as lead
+coordinator: `/tmp` went to 79%, 6.0 G free. But note _how_ it was resolved — **a human-authority seat
+did it by hand, because the authority exists and the reaper does not.** That gap is the finding, not
+the disk usage.
+
+Two doctrine points fall out, both binding on RM-50:
+
+1. **The fix is not "agents should tidy up."** Asking each seat to clean its own scratch is
+   `instructions are not enforcement` (D-4) wearing a different hat. A deterministic reaper must own
+   it — same conclusion the north star reaches for every other class in this mission.
+2. **Refusing to unilaterally delete another session's scratch was correct, and the resolution is not
+   "be braver about deleting."** An agent guessing that someone else's state is garbage is exactly the
+   unreviewed destructive act the Constitution forbids. The resolution is that _ownership and liveness
+   become mechanically decidable_, so reaping is a determination rather than a judgement call.
+
+**Reaper requirements for RM-50:** liveness determined mechanically (process/`lsof`/session-map, not
+mtime alone); an age threshold; a dry-run that reports what it would reap and why; and an audit event
+per reap. Never a heuristic sweep — that would reintroduce the P-WORKFLOW-001 auto-sync failure in a
+more destructive form.
+
 **The self-erasure is the important part.** An inert gate that is masked by unrelated downstream
 commits produces no lasting artifact, which is precisely why this class survives for months. Detection
 cannot rely on "is `main` currently red" — it must be per-merge-commit.
@@ -112,13 +224,13 @@ spread is itself information, and X1 says we calibrate on real merged PRs.

 ⛔ _No gate-introducing task in any later phase may merge before RM-02._

-| id    | task                                                                                         | src | depends_on   | est (S/O)        | tier   |
-| ----- | -------------------------------------------------------------------------------------------- | --- | ------------ | ---------------- | ------ |
-| RM-01 | Reproducible non-root checkout; pre-push gate fails on **code, not env** (banks D-1/D-2/D-5) | O+S | —            | 6K / 60K         | codex  |
-| RM-02 | **Gate registry + negative-control CI check** (anti-inert-gate harness) ★keystone            | O   | RM-01        | — / 120K         | opus   |
-| RM-03 | Queue-guard fail-closed rework (`unknown`/`no-status`/malformed ⇒ ≠0)                        | O+S | RM-02        | 8K / 100K        | sonnet |
-| RM-04 | Activation/version coherence; block launch on skew, fail SAFE; honest `doctor` labels        | O+S | RM-01        | (in S-01) / 140K | sonnet |
-| RM-05 | Break-glass replaces the three silent `MOSAIC BYPASS` fail-opens                             | O   | RM-04, RM-02 | — / 120K         | opus   |
+| id              | task                                                                                                                                          | src      | depends_on   | est (S/O)        | tier   |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | ---------------- | ------ |
+| RM-01           | Reproducible non-root checkout; gate fails on **code, not env**; heavy artifacts OFF shared `/tmp` (banks D-1/D-2/D-5/D-7)                    | O+S+live | —            | 6K / 60K         | codex  |
+| RM-02           | **Gate registry + negative-control CI check** (anti-inert-gate harness) ★keystone                                                             | O        | RM-01        | — / 120K         | opus   |
+| RM-03 ⏸**HOLD** | Queue-guard: **two** defects — (a) `unknown`/`no-status`/malformed ⇒ ≠0, (b) guard evaluates `branch=main` instead of the branch being pushed | O+S+live | RM-02        | 8K / 100K        | sonnet |
+| RM-04           | Activation/version coherence; block launch on skew, fail SAFE; honest `doctor` labels                                                         | O+S      | RM-01        | (in S-01) / 140K | sonnet |
+| RM-05           | Break-glass replaces the three silent `MOSAIC BYPASS` fail-opens                                                                              | O        | RM-04, RM-02 | — / 120K         | opus   |

 > ⚠ **RM-05 must not merge before RM-04.** The bypasses exist because the lease-broker daemon was
 > never _deployed_ on this host — removing the fail-open before deployment coherence is real
@@ -187,7 +299,7 @@ spread is itself information, and X1 says we calibrate on real merged PRs.

 | id    | task                                                                                                                                                 | src                   | depends_on                 | est (S/O)        | tier   |
 | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -------------------------- | ---------------- | ------ |
-| RM-50 | One roster-owned socket/host; quarantine unmanaged; stale-session GC                                                                                 | O+S                   | RM-04                      | 14K / 150K       | sonnet |
+| RM-50 | One roster-owned socket/host; quarantine unmanaged; **deterministic reaper for stale sessions AND dead-session disk scratch** (D-7)                  | O+S+live              | RM-04                      | 14K / 150K       | sonnet |
 | RM-51 | Auto-sync **allowlist** (never auto-stage unknown paths) + worktree/lease isolation                                                                  | O+S                   | RM-02                      | 8K / 110K        | sonnet |
 | RM-52 | Retire the Python controller + duplicate MACP islands (3 → 1)                                                                                        | O+S                   | RM-26, RM-27, RM-25, RM-28 | 14K / 110K       | codex  |
 | RM-53 | Flat-file orchestration → DB hard cutover, with rehearsed rollback artifact                                                                          | O+S                   | RM-27, RM-30, RM-34, RM-29 | (in S-10) / 200K | opus   |
@@ -219,40 +331,49 @@ spread is itself information, and X1 says we calibrate on real merged PRs.

 ---

-## 5. Blocking decisions (need Mos, or Jason via Mos)
+## 5. Decisions — all three ruled by Mos, 2026-07-31

-These are escalated because they change the charter, the accepted directive, or another lane's
-ownership — none is a question I should answer unilaterally.
+**DECISION-1 — the wire-in point. ✅ RULED: accept the planners (Mos, 2026-07-31).**
+The charter's `mosaic_orchestrator.py::run_single_task` target is the **disabled Python controller
+this mission retires**; wiring the new choke point into the rail we are deleting is wrong.

-**DECISION-1 — the wire-in point (changes `MISSION.md`).**
-Both planners independently reject wiring the choke point into
-`mosaic_orchestrator.py::run_single_task`, because that controller is disabled and references a
-non-existent dispatcher. They propose wiring `packages/coord/src/runner.ts` +
-`packages/mosaic/src/commands/launch.ts` and **deleting** the Python rail instead. This makes RM-52 a
-deletion task rather than an integration task, and moves Build 1's acceptance onto a live
-`mosaic yolo` invocation. _My recommendation: accept — wiring a disabled rail reproduces the exact
-disease this mission exists to cure._
+> **Corrected target (authoritative):** a **new production Node `TaskExecutor`** sitting on the
+> **live dispatch path** — `packages/mosaic` launch + `packages/coord` — which Coord, Forge, and live
+> dispatch all **submit through**. This is the MACP scout's _full_ recommendation ("replace the block
+> **with** a Node executor **and** make Coord/Forge submit through it"), not a resurrection of the
+> Python controller. RM-52 is therefore a **deletion** task, and Build 1's acceptance is measured on a
+> live `mosaic yolo` invocation.

-**DECISION-2 — rollback artifact + the availability trade (needs Jason).**
-(a) Does "hard cutover, no flat-file interim" permit a **rehearsed, one-directional, read-as-authority-
-by-nobody** rollback snapshot (OPUS D3)? (b) Do we pre-commit in writing that "no DB ⇒ the fleet
-stops" and "unpersistable event ⇒ the operation fails" (OPUS D8)? That is a real availability
-regression versus today's limping flat-file fleet — correct for a system whose defining failure is
-_silent continuation_, but it should be a decision, not a 2am discovery.
-_My recommendation: yes to both; a rollback snapshot nothing reads is not an interim tracking system._
+Mos ruled this resolvable from the already-accepted retire-the-Python-rail decision — his authority,
+not a Jason escalation. RM-21/RM-26/RM-27/RM-52 all take the corrected target.

-**DECISION-3 — RM-03 ownership vs. parked PR #1023 (needs Mos).**
-P-QUEUE-001 is absorbed into this mission, but PR #1023 is explicitly parked under Mos. Two lanes can
-legitimately claim it. A third recursion on the gate-6 defect — performed by the remediation itself —
-would be the postmortem's own anti-pattern. _Not dispatching RM-03 until Mos rules._
+**DECISION-2 — rollback artifact + availability trade. ⏸ JASON-PENDING — NOT BLOCKING.**
+The DB build is phases away, so this is queued for Jason's next session rather than escalated now.
+**Binding requirement in the meantime (Mos, from P-RECOVERY-001):** the DB spine **must NOT be a
+single-point hard-stop.** Design for a broker-independent / degraded mode **plus** a rollback
+artifact. Jason finalises only the specific availability target. This reverses my earlier reading of
+OPUS D8 ("the fallback is: the fleet stops") — that answer is **not** pre-committed; a degraded mode
+is now a design requirement on RM-12, RM-13, RM-23, RM-36 and RM-53.
+
+**DECISION-3 — RM-03 vs. parked PR #1023. ✅ RULED: HOLD RM-03 (Mos, 2026-07-31).**
+Do **not** open a third gate-6 lane — that is the postmortem's own anti-pattern performed by the
+remediation. PR #1023 sits in Jason's **parked delivery stack**; its disposition (close, or supersede
+by RM-03) is Jason's at his next session.
+
+- **PR #1023 → `SUPERSEDED-PENDING-JASON`.** RM-03 stays `HOLD`; when Jason rules, RM-03 proceeds as
+  the single correct lane.
+- **RM-02 and RM-55 proceed independently and are NOT held.** The per-merge-commit gate-assertion
+  requirement is the _conformance_ capability, not the gate-6 fix itself — different scope, no
+  ownership collision.

 ---

 ## 6. Status

-| phase              | state                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| Decomposition      | DONE — both planners delivered independently                                         |
-| Reconciliation     | DONE — this document                                                                 |
-| Blocking decisions | **OPEN — 3 escalated to Mos (§5)**                                                   |
-| Dispatch           | NOT STARTED — RM-01 is dispatchable now; it depends on nothing and blocks everything |
+| phase              | state                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| Decomposition      | DONE — both planners delivered independently                                                                 |
+| Reconciliation     | DONE — this document                                                                                         |
+| Blocking decisions | **RULED** — all 3 closed by Mos 2026-07-31 (§5); D-2's availability target is Jason-pending but non-blocking |
+| Dispatch           | **RM-01 IN FLIGHT** — f10-coder (codex), worktree-isolated, AC1–AC8 pre-registered                           |
+| Review             | PR #1025 with rev-974; ACs pre-registered 22:12:26Z before diff exposure                                     |
@@ -0,0 +1,58 @@
+# RM-01 — Reproducible checkout
+
+- Task/ref: RM-01 (`docs/remediation/TASKS.md`, internal mission tracking)
+- Objective: make checkout/install/typecheck hooks fail on code rather than environmental residue, for root CI and non-root seats.
+- Scope: pnpm store configuration, transactional Husky installation, dependency/generated-state preflight, checkout regression tests, developer documentation.
+- Constraints: isolated worktree; no skip-switch fixes; no writes under `/root` or `/tmp`; workers do not edit `docs/remediation/TASKS.md`; author does not review or merge.
+- Acceptance: AC1–AC8 from the orchestrator dispatch/addendum.
+- Plan:
+  1. Add RED-first tests for missing dependencies, stale/foreign `.next`, and interrupted hook installation.
+  2. Implement environment-overridable HOME-based pnpm store defaults, deterministic preflight, and transactional hook installation.
+  3. Run focused tests, install/build/baseline gates, and explicit AC negative controls.
+  4. Obtain independent review, push after queue guard, open PR, and send evidence to `mos-remediation`.
+- Budget: orchestrator estimate 6K/60K; no explicit hard token cap. Keep scope to RM-01 and avoid unrelated cleanup.
+- Risks: 97%-full shared `/tmp`; native dependency install size; root-owned fixtures may require Docker for realistic verification.
+
+## Progress / evidence
+
+- Worktree created at `/home/hermes/agent-work/rm-01` from `origin/main` `06e0d403`.
+- `/tmp` baseline: 28G used, 889M available (97%); worktree and planned store are on `/home`.
+- Root causes confirmed from source: committed `.npmrc` pins `/root`; `prepare` invokes Husky directly; web typecheck includes generated `.next` types without validating ownership/freshness.
+
+## Checkpoint evidence (c45e5e19)
+
+- AC1 IN PROGRESS: non-root `pnpm install --frozen-lockfile --store-dir "$HOME/.local/share/pnpm/store"` exited 0; `pnpm exec turbo run typecheck --force` exited 0 (45/45 uncached). Clean CI-container run not performed.
+- AC2 DONE: with `node_modules` absent, `pnpm preflight` exited 42 with `MOSAIC_PREFLIGHT_MISSING_DEPS` and `run pnpm install`; after install it exited 0.
+- AC3 DONE: appending `export const x: number = "s"` to `packages/types/src/index.ts` made `pnpm -w typecheck` exit 2 with TS2322; reverting made it exit 0.
+- AC4 IN PROGRESS: local `pnpm -w build` exited 0 and `git status --porcelain` showed no generated residue beyond the intended RM-01 source changes. Fresh-clone proof not performed.
+- AC5 DONE: non-root install exited 0; `pnpm store path` resolved `/home/hermes/.local/share/pnpm/store/v10`; no `/root` write was attempted.
+- AC6 IN PROGRESS: focused failure/rollback tests passed, but final review found a concurrent-install race. Two installers can both observe `.husky/_` absent; after one installs successfully, the losing install's catch path can quarantine the winner's active hooks and restore stale Git config (`scripts/install-hooks.mjs`, activation/catch transaction). A RED regression is committed after the checkpoint.
+- AC7 DONE: install/store/worktree were on `/home`; full `pnpm -w build` exited 0; `/tmp` usage changed by 4096 bytes during the build (23,805,173,760 → 23,805,177,856 bytes), not materially.
+- AC8 DONE for the implemented path: store resolves under `$HOME`; test/quarantine/build state resolves under the worktree; no implemented component requires a writable path outside `$HOME` or the worktree.
+
+## Continuation evidence
+
+- AC6 DONE: the committed race reproducer was observed RED (`node --test --test-name-pattern='a competing successful installer is not removed by the losing process' scripts/install-hooks.test.mjs`, exit 1/ENOENT), then passed after cleanup became ownership-safe. The losing installer never removes an active hook set or restores Git configuration it did not activate. `pnpm test:checkout` passes 21/21, exit 0, including the original race and a post-rename peer-replacement regression.
+- Generated-state remediation: replaced mtime inference with a source/build-input fingerprint, written only after a serialized successful Next build with unchanged inputs. Failed/interrupted/overlapping builds leave no trusted marker. The fingerprint uses Next's own environment loader, covers resolved `NEXT_PUBLIC_*` values, inherited TypeScript configuration, lock/workspace inputs, and rejects symlink inputs.
+- Baseline: `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` each exit 0. Local `pnpm test` still exits 97 only at the pre-existing Bash `BASH_LINENO` convention guard (#973/#1003), after checkout tests and package tests pass; this is not reported as a green full-suite result.
+- Automated review remediation: resolved findings for peer-hook ownership, stale/failed build markers, build-input changes, expanded environment inputs, inherited TypeScript config, symlink inputs, and overlapping build serialization. Independent PR review remains assigned to rev-974.
+- AC1 DONE at `0f706119`: a clean clone created inside `git.mosaicstack.dev/mosaicstack/stack/ci-base:latest` ran the exact acceptance sequence `pnpm install --frozen-lockfile && pnpm -w typecheck`; exit 0 with 45/45 uncached typecheck tasks successful. An earlier bind-mounted clone attempt exited 1 because root in the container rejected the host-owned Git directory; that failed attempt is not counted as evidence.
+- AC4 DONE at `0f706119`: in that same fresh clone and CI image, `pnpm -w build` completed 25/25 tasks and the immediately following `git status --porcelain` was empty; combined assertion exit 0.
+- Push BLOCKED after the required queue guard: `git push origin fix/rm-01-reproducible-checkout` was rejected by Gitea with `User permission denied for writing` / `pre-receive hook declined`, despite `MOSAIC_GIT_IDENTITY=f10-coder` resolving username `f10-coder` from the provisioned `gitea-mosaicstack-f10-coder.token`.
+
+## Review remediation — restated AC2
+
+- Independent review correctly found that an added symlink under a successfully built `.next` tree passed preflight. The exact reviewer control, `ln -s /etc/hosts apps/web/.next/reviewer-symlink && pnpm preflight`, was observed passing before remediation.
+- The original blanket symlink wording conflicts with AC4 because canonical Next `output: 'standalone'` emits legitimate pnpm dependency symlinks. The coordinator independently verified 42 such links and approved the operative restatement: `.next` itself must not be a symlink; descendant symlinks must exactly match the successful build's certified manifest.
+- RED-first controls were observed failing together against the prior implementation (exit 1): `.next` root, added, removed, retargeted, tampered-manifest, and canonical-style certified-link cases. The build now publishes the manifest atomically before the existing source certification commit marker; that marker binds the manifest SHA-256. Missing/partial/modified manifests remain untrusted.
+- GREEN evidence: the six-case symlink control passes; the exact reviewer-added link exits 43; removing it restores preflight exit 0. The added RED-first build-publication control also proves a symlinked `.next` cannot redirect certification writes outside the checkout. `pnpm test:checkout` passes 23 top-level tests / 29 including subtests. Canonical `pnpm --filter @mosaicstack/web build` and the following `pnpm preflight` both exit 0.
+- Threat-model ruling: the manifest detects accidental, independent, stale, and foreign-residue mutation—the class exposed by the five-month-stale `.next` that produced 19 phantom TS2307 errors. It does not defend against a same-UID actor able to rewrite both manifest and marker consistently (CWE-345); no local worktree construction can without an external trust anchor. RM-59 tracks the residual: executor/spine-side attestation outside worktree authority, dependent on RM-12, RM-21, and RM-25.
+- AC8 concrete proof at `df7530ae`: a clean clone ran in `ci-base:latest` with Docker `--read-only`; its only writable mounts were `/workspace` (the worktree) and `/home/ci` (`HOME`, with `NPM_CONFIG_STORE_DIR=/home/ci/store`). `pnpm install --frozen-lockfile && pnpm -w typecheck` exited 0 with 45/45 uncached tasks. This proves the implemented checkout path requires no writable location outside `$HOME` and the worktree. An initial fixture attempt failed only because Git required `/workspace` safe-directory setup; it is not counted as evidence.
+
+## Handoff
+
+1. Keep the newly committed RED tests red until implementing: (a) source-fingerprint marker support for valid incremental `.next` output, and (b) ownership-safe concurrent hook activation.
+2. The latest automated review rejected oldest-generated-file mtime as a false positive for valid incremental Next output. Use a source-content fingerprint marker written only after successful `next build`; do not continue tuning mtimes.
+3. For Husky, generation in an isolated temporary Git repo avoids mutating real `core.hooksPath` during staging. Preserve that design. Fix the losing concurrent process so it never removes a peer's completed hook set or restores stale config.
+4. Codex review runs in a read-only sandbox, so its attempts to run the fixture-writing Node tests report opaque test-file failures. The same tests run normally in the worktree.
+5. Full `pnpm test` is not green on this host: it exits 97 at the pre-existing Bash `BASH_LINENO` convention guard (#1003), after the changed checkout tests and package tests pass. Do not weaken that gate.
@@ -6,11 +6,14 @@
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
-    "typecheck": "turbo run typecheck",
-    "test": "turbo run test",
+    "preflight": "node scripts/preflight.mjs",
+    "clean:generated": "node scripts/clean-generated.mjs",
+    "typecheck": "pnpm preflight && turbo run typecheck",
+    "test:checkout": "node --test scripts/*.test.mjs",
+    "test": "pnpm test:checkout && turbo run test",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
-    "prepare": "husky"
+    "prepare": "node scripts/install-hooks.mjs"
  },
  "devDependencies": {
    "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+import { generatedSymlinkManifest, sourceFingerprint } from './preflight.mjs';
+
+const scriptRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function run(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, options);
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(signal ? `next build terminated by ${signal}` : `next build exited ${code}`),
+        );
+    });
+  });
+}
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function requireRealDirectory(target, { allowMissing = false } = {}) {
+  try {
+    const stats = await lstat(target);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new Error(`${target} must be a real directory, not a symbolic link.`);
+    }
+  } catch (error) {
+    if (allowMissing && error.code === 'ENOENT') return;
+    throw error;
+  }
+}
+
+async function acquireBuildLock(root) {
+  const workRoot = path.join(root, '.mosaic-test-work');
+  const lock = path.join(workRoot, 'web-build.lock');
+  const nonce = randomUUID();
+  const owner = JSON.stringify({ pid: process.pid, nonce });
+  const deadline = Date.now() + 120_000;
+  await mkdir(workRoot, { recursive: true });
+
+  while (Date.now() < deadline) {
+    try {
+      await mkdir(lock);
+      await writeFile(path.join(lock, 'owner.json'), owner, { mode: 0o600 });
+      return async () => {
+        const current = await readFile(path.join(lock, 'owner.json'), 'utf8');
+        if (current !== owner) throw new Error('Web build lock ownership changed before release.');
+        const released = `${lock}.released-${nonce}`;
+        await rename(lock, released);
+        await rm(released, { recursive: true, force: true });
+      };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let lockOwner;
+      try {
+        lockOwner = JSON.parse(await readFile(path.join(lock, 'owner.json'), 'utf8'));
+      } catch (ownerError) {
+        if (ownerError.code === 'ENOENT') {
+          await delay(25);
+          continue;
+        }
+        throw new Error(`Web build lock is unreadable at ${lock}.`, { cause: ownerError });
+      }
+      try {
+        process.kill(lockOwner.pid, 0);
+      } catch (processError) {
+        if (processError.code !== 'ESRCH') throw processError;
+        const stale = `${lock}.stale-${nonce}`;
+        try {
+          await rename(lock, stale);
+          await rm(stale, { recursive: true, force: true });
+        } catch (renameError) {
+          if (renameError.code !== 'ENOENT') throw renameError;
+        }
+        continue;
+      }
+      await delay(25);
+    }
+  }
+  throw new Error(`Timed out waiting for the web build lock at ${lock}.`);
+}
+
+export async function buildWeb({
+  root = scriptRoot,
+  fingerprint = sourceFingerprint,
+  runBuild = async (webDir) =>
+    run(path.join(webDir, 'node_modules', '.bin', 'next'), ['build'], {
+      cwd: webDir,
+      stdio: 'inherit',
+    }),
+} = {}) {
+  const releaseLock = await acquireBuildLock(root);
+  try {
+    const webDir = path.join(root, 'apps', 'web');
+    const nextDir = path.join(webDir, '.next');
+    const certificationMarker = path.join(nextDir, '.mosaic-source-hash');
+    const symlinkManifest = path.join(nextDir, '.mosaic-symlink-manifest');
+    const certificationTemporary = `${certificationMarker}.${randomUUID()}.tmp`;
+    const manifestTemporary = `${symlinkManifest}.${randomUUID()}.tmp`;
+    const before = await fingerprint(root);
+
+    await requireRealDirectory(nextDir, { allowMissing: true });
+    await Promise.all([
+      rm(certificationMarker, { force: true }),
+      rm(symlinkManifest, { force: true }),
+    ]);
+    await runBuild(webDir);
+    await requireRealDirectory(nextDir);
+
+    const after = await fingerprint(root);
+    if (after !== before) {
+      throw new Error(
+        'Web build inputs changed during next build; generated output was not certified.',
+      );
+    }
+
+    const manifestContents = await generatedSymlinkManifest(nextDir);
+    const certificationContents = `${JSON.stringify({
+      version: 1,
+      sourceFingerprint: before,
+      symlinkManifestHash: createHash('sha256').update(manifestContents).digest('hex'),
+    })}\n`;
+    await Promise.all([
+      writeFile(certificationTemporary, certificationContents, { mode: 0o600 }),
+      writeFile(manifestTemporary, manifestContents, { mode: 0o600 }),
+    ]);
+    // The certification marker is the commit point. Publishing the manifest first
+    // leaves interrupted builds untrusted because the marker remains absent.
+    await rename(manifestTemporary, symlinkManifest);
+    await rename(certificationTemporary, certificationMarker);
+  } finally {
+    await releaseLock();
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await buildWeb();
+}
@@ -0,0 +1,149 @@
+import assert from 'node:assert/strict';
+import { access, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import test from 'node:test';
+
+import { buildWeb } from './build-web.mjs';
+
+const fixtureRoot = path.join(process.cwd(), '.mosaic-test-work', `build-web-${process.pid}`);
+
+async function fixture(name) {
+  const root = path.join(fixtureRoot, name);
+  await mkdir(path.join(root, 'apps', 'web', '.next'), { recursive: true });
+  return root;
+}
+
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test.after(async () => {
+  await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+test('a successful web build atomically publishes its source and symlink certification', async () => {
+  const root = await fixture('success');
+  const marker = path.join(root, 'apps', 'web', '.next', '.mosaic-source-hash');
+  const manifest = path.join(root, 'apps', 'web', '.next', '.mosaic-symlink-manifest');
+
+  await buildWeb({ root, fingerprint: async () => 'certified', runBuild: async () => {} });
+
+  assert.deepEqual(JSON.parse(await readFile(marker, 'utf8')), {
+    version: 1,
+    sourceFingerprint: 'certified',
+    symlinkManifestHash: '8a5a375cea6a55d24bd5f875856da63feba33adbefb15a92a0007719b84bcf11',
+  });
+  assert.equal(await readFile(manifest, 'utf8'), '{"version":1,"links":[]}\n');
+});
+
+test('a failed web build leaves no certification marker', async () => {
+  const root = await fixture('failure');
+  const marker = path.join(root, 'apps', 'web', '.next', '.mosaic-source-hash');
+  const manifest = path.join(root, 'apps', 'web', '.next', '.mosaic-symlink-manifest');
+  await writeFile(marker, 'stale\n');
+  await writeFile(manifest, 'stale\n');
+
+  await assert.rejects(
+    buildWeb({
+      root,
+      fingerprint: async () => 'before',
+      runBuild: async () => {
+        throw new Error('build failed');
+      },
+    }),
+    /build failed/,
+  );
+
+  assert.equal(await exists(marker), false);
+  assert.equal(await exists(manifest), false);
+});
+
+test('overlapping web builds are serialized while the marker remains absent', async () => {
+  const root = await fixture('overlap');
+  const marker = path.join(root, 'apps', 'web', '.next', '.mosaic-source-hash');
+  const manifest = path.join(root, 'apps', 'web', '.next', '.mosaic-symlink-manifest');
+  await writeFile(marker, 'stale\n');
+  await writeFile(manifest, 'stale\n');
+  let releaseFirst;
+  let secondEntered = false;
+  const firstEntered = new Promise((resolve) => {
+    releaseFirst = resolve;
+  });
+  let markFirstEntered;
+  const firstStarted = new Promise((resolve) => {
+    markFirstEntered = resolve;
+  });
+
+  const first = buildWeb({
+    root,
+    fingerprint: async () => 'certified',
+    runBuild: async () => {
+      markFirstEntered();
+      await firstEntered;
+    },
+  });
+  await firstStarted;
+  const second = buildWeb({
+    root,
+    fingerprint: async () => 'certified',
+    runBuild: async () => {
+      secondEntered = true;
+    },
+  });
+  await new Promise((resolve) => setTimeout(resolve, 75));
+  assert.equal(secondEntered, false);
+  assert.equal(await exists(marker), false);
+  assert.equal(await exists(manifest), false);
+
+  releaseFirst();
+  await Promise.all([first, second]);
+  assert.equal(secondEntered, true);
+  assert.equal(JSON.parse(await readFile(marker, 'utf8')).sourceFingerprint, 'certified');
+  assert.equal(await readFile(manifest, 'utf8'), '{"version":1,"links":[]}\n');
+});
+
+test('a build that replaces .next with a symbolic link cannot publish outside the checkout', async () => {
+  const root = await fixture('symbolic-next');
+  const nextDir = path.join(root, 'apps', 'web', '.next');
+  const outside = path.join(root, 'outside-generated');
+  await mkdir(outside);
+
+  await assert.rejects(
+    buildWeb({
+      root,
+      fingerprint: async () => 'certified',
+      runBuild: async () => {
+        await rm(nextDir, { recursive: true });
+        await symlink(outside, nextDir);
+      },
+    }),
+    /must be a real directory/,
+  );
+
+  assert.equal(await exists(path.join(outside, '.mosaic-source-hash')), false);
+  assert.equal(await exists(path.join(outside, '.mosaic-symlink-manifest')), false);
+});
+
+test('inputs changed during a web build are not certified', async () => {
+  const root = await fixture('changed-inputs');
+  const marker = path.join(root, 'apps', 'web', '.next', '.mosaic-source-hash');
+  const manifest = path.join(root, 'apps', 'web', '.next', '.mosaic-symlink-manifest');
+  const fingerprints = ['before', 'after'];
+
+  await assert.rejects(
+    buildWeb({
+      root,
+      fingerprint: async () => fingerprints.shift(),
+      runBuild: async () => {},
+    }),
+    /inputs changed during next build/,
+  );
+
+  assert.equal(await exists(marker), false);
+  assert.equal(await exists(manifest), false);
+});
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { access, mkdir, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+const root = process.cwd();
+const generated = path.join(root, 'apps', 'web', '.next');
+const quarantineRoot = path.join(root, '.mosaic-test-work', 'generated-quarantine');
+
+try {
+  await access(generated);
+} catch (error) {
+  if (error.code === 'ENOENT') process.exit(0);
+  throw error;
+}
+
+await mkdir(quarantineRoot, { recursive: true });
+const quarantine = path.join(quarantineRoot, `web-next-${Date.now()}-${process.pid}`);
+try {
+  await rename(generated, quarantine);
+} catch (error) {
+  console.error(
+    `MOSAIC_GENERATED_CLEAN_FAILED: could not quarantine apps/web/.next. Fix: sudo rm -rf '${generated}', then rerun pnpm preflight`,
+  );
+  throw error;
+}
+
+try {
+  await rm(quarantine, { recursive: true, force: true });
+} catch {
+  console.warn(
+    `Generated state was deactivated but could not be deleted; quarantined at ${quarantine}`,
+  );
+}
@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import { access, lstat, mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+function run(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, options);
+    child.once('error', reject);
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolve();
+      else reject(new Error(signal ? `husky terminated by ${signal}` : `husky exited ${code}`));
+    });
+  });
+}
+
+async function pathExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function directorySnapshot(root) {
+  const snapshot = [];
+  async function walk(current) {
+    const children = await readdir(current, { withFileTypes: true });
+    for (const child of children.sort((left, right) => left.name.localeCompare(right.name))) {
+      const target = path.join(current, child.name);
+      const relative = path.relative(root, target);
+      const stats = await lstat(target);
+      if (child.isDirectory()) {
+        snapshot.push([relative, 'directory', stats.mode & 0o777]);
+        await walk(target);
+      } else {
+        snapshot.push([
+          relative,
+          'file',
+          stats.mode & 0o777,
+          (await readFile(target)).toString('base64'),
+        ]);
+      }
+    }
+  }
+  await walk(root);
+  return JSON.stringify(snapshot);
+}
+
+async function directoriesMatch(left, right) {
+  return (await directorySnapshot(left)) === (await directorySnapshot(right));
+}
+
+export async function installHooks({
+  root = process.cwd(),
+  disabled = process.env.HUSKY === '0',
+  quarantineRoot = path.join(root, '.mosaic-test-work', 'husky-quarantine'),
+  runHusky = async (_stagingHooks, stagingRepo) => {
+    await execFileAsync('git', ['init', '--quiet', stagingRepo]);
+    await run(path.join(root, 'node_modules', '.bin', 'husky'), ['.husky'], {
+      cwd: stagingRepo,
+      stdio: 'inherit',
+    });
+  },
+  activateHooks = async () => {
+    await run('git', ['config', 'core.hooksPath', '.husky/_'], { cwd: root, stdio: 'inherit' });
+  },
+} = {}) {
+  if (disabled) return;
+
+  const huskyDir = path.join(root, '.husky');
+  const active = path.join(huskyDir, '_');
+  const nonce = `${Date.now()}-${process.pid}`;
+  const stagingRepo = path.join(root, '.mosaic-test-work', `husky-stage-${nonce}`);
+  const stagingHooks = path.join(stagingRepo, '.husky');
+  const quarantined = path.join(quarantineRoot, `${path.basename(root)}-${nonce}`);
+  await mkdir(huskyDir, { recursive: true });
+  await mkdir(quarantineRoot, { recursive: true });
+
+  const previousComplete = (await pathExists(active)) && (await pathExists(path.join(active, 'h')));
+  let previousQuarantined = false;
+  try {
+    if ((await pathExists(active)) && !previousComplete) {
+      await rename(active, quarantined);
+      previousQuarantined = true;
+    }
+    await mkdir(stagingRepo, { recursive: true });
+    await runHusky(stagingHooks, stagingRepo);
+    const staged = path.join(stagingHooks, '_');
+    if (!(await pathExists(path.join(staged, 'h')))) {
+      throw new Error('husky did not produce its required h shim');
+    }
+    if (previousComplete) {
+      if (!(await directoriesMatch(active, staged))) {
+        throw new Error('existing complete hook set differs from the installed Husky version');
+      }
+      await rm(stagingRepo, { recursive: true, force: true });
+    } else {
+      await rename(staged, active);
+      await rm(stagingRepo, { recursive: true, force: true });
+    }
+    await activateHooks();
+    if (previousQuarantined) {
+      try {
+        await rm(quarantined, { recursive: true, force: true });
+      } catch {
+        console.warn(
+          `Previous hook state was deactivated but remains quarantined at ${quarantined}`,
+        );
+      }
+    }
+  } catch (error) {
+    const cleanupFailures = [];
+    try {
+      if (await pathExists(stagingRepo)) {
+        await rename(stagingRepo, `${quarantined}-staging`);
+      }
+    } catch (cleanupError) {
+      cleanupFailures.push(`staging hooks: ${cleanupError.message}`);
+    }
+    const cleanup =
+      cleanupFailures.length === 0
+        ? 'No partial hook set was activated.'
+        : `Automatic cleanup was incomplete (${cleanupFailures.join('; ')}).`;
+    throw new Error(
+      `Hook installation failed: ${error.message}. ${cleanup} Fix: rm -rf .husky/_ && git config core.hooksPath .husky/_ && pnpm install --frozen-lockfile`,
+      { cause: error },
+    );
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    await installHooks();
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
@@ -0,0 +1,208 @@
+import assert from 'node:assert/strict';
+import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import test from 'node:test';
+
+import { installHooks } from './install-hooks.mjs';
+
+const fixtureRoot = path.join(process.cwd(), '.mosaic-test-work', `hooks-${process.pid}`);
+const quarantineRoot = path.join(fixtureRoot, 'quarantine');
+
+async function fixture(name) {
+  const root = path.join(fixtureRoot, name);
+  await mkdir(path.join(root, '.husky'), { recursive: true });
+  return root;
+}
+
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+test.after(async () => {
+  await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+test('an interrupted install quarantines the partial active hook set and fails loudly', async () => {
+  const root = await fixture('interrupted');
+  let restoredHooksPath = 'not-called';
+
+  await assert.rejects(
+    installHooks({
+      root,
+      quarantineRoot,
+      runHusky: async (stagingHooks) => {
+        await mkdir(path.join(stagingHooks, '_'), { recursive: true });
+        await writeFile(path.join(stagingHooks, '_', 'h'), 'partial');
+        throw new Error('simulated interruption');
+      },
+      activateHooks: async () => {},
+      readHooksPath: async () => null,
+      restoreHooksPath: async (value) => {
+        restoredHooksPath = value;
+      },
+    }),
+    (error) => {
+      assert.match(error.message, /Hook installation failed/);
+      assert.match(error.message, /pnpm install --frozen-lockfile/);
+      return true;
+    },
+  );
+
+  assert.equal(await exists(path.join(root, '.husky', '_')), false);
+  assert.equal(restoredHooksPath, 'not-called');
+  const quarantined = await readdir(quarantineRoot);
+  assert.equal(quarantined.length, 1);
+});
+
+test('a failed replacement restores a previously complete active hook set', async () => {
+  const root = await fixture('rollback');
+  const activeShim = path.join(root, '.husky', '_', 'h');
+  await mkdir(path.dirname(activeShim), { recursive: true });
+  await writeFile(activeShim, 'previous-complete');
+  let previousRemainedActiveDuringStaging = false;
+
+  await assert.rejects(
+    installHooks({
+      root,
+      quarantineRoot: path.join(fixtureRoot, 'rollback-quarantine'),
+      runHusky: async () => {
+        previousRemainedActiveDuringStaging =
+          (await readFile(activeShim, 'utf8')) === 'previous-complete';
+        throw new Error('simulated replacement failure');
+      },
+      activateHooks: async () => {},
+      readHooksPath: async () => '.husky/_',
+      restoreHooksPath: async () => {},
+    }),
+    /Hook installation failed/,
+  );
+
+  assert.equal(previousRemainedActiveDuringStaging, true);
+  assert.equal(await readFile(activeShim, 'utf8'), 'previous-complete');
+});
+
+test('a mismatched complete hook set fails loudly instead of reporting a stale install as current', async () => {
+  const root = await fixture('mismatch');
+  const activeShim = path.join(root, '.husky', '_', 'h');
+  await mkdir(path.dirname(activeShim), { recursive: true });
+  await writeFile(activeShim, 'old-complete');
+
+  await assert.rejects(
+    installHooks({
+      root,
+      quarantineRoot: path.join(fixtureRoot, 'mismatch-quarantine'),
+      runHusky: async (stagingHooks) => {
+        await mkdir(path.join(stagingHooks, '_'), { recursive: true });
+        await writeFile(path.join(stagingHooks, '_', 'h'), 'new-complete');
+      },
+      activateHooks: async () => {},
+      readHooksPath: async () => '.husky/_',
+      restoreHooksPath: async () => {},
+    }),
+    /Hook installation failed.*pnpm install --frozen-lockfile/,
+  );
+
+  assert.equal(await readFile(activeShim, 'utf8'), 'old-complete');
+});
+
+test('a competing successful installer is not removed by the losing process', async () => {
+  const root = await fixture('concurrent');
+  const activeShim = path.join(root, '.husky', '_', 'h');
+  let restored = false;
+
+  await assert.rejects(
+    installHooks({
+      root,
+      quarantineRoot: path.join(fixtureRoot, 'concurrent-quarantine'),
+      runHusky: async (stagingHooks) => {
+        await mkdir(path.join(stagingHooks, '_'), { recursive: true });
+        await writeFile(path.join(stagingHooks, '_', 'h'), 'ours');
+        await mkdir(path.dirname(activeShim), { recursive: true });
+        await writeFile(activeShim, 'peer');
+      },
+      activateHooks: async () => {},
+      readHooksPath: async () => null,
+      restoreHooksPath: async () => {
+        restored = true;
+      },
+    }),
+    /Hook installation failed/,
+  );
+
+  assert.equal(await readFile(activeShim, 'utf8'), 'peer');
+  assert.equal(restored, false);
+});
+
+test("a competing installer that replaces this installer's active set is preserved", async () => {
+  const root = await fixture('concurrent-after-rename');
+  const active = path.join(root, '.husky', '_');
+  const activeShim = path.join(active, 'h');
+  let restored = false;
+
+  await assert.rejects(
+    installHooks({
+      root,
+      quarantineRoot: path.join(fixtureRoot, 'concurrent-after-rename-quarantine'),
+      runHusky: async (stagingHooks) => {
+        await mkdir(path.join(stagingHooks, '_'), { recursive: true });
+        await writeFile(path.join(stagingHooks, '_', 'h'), 'ours');
+      },
+      activateHooks: async () => {
+        await rm(active, { recursive: true, force: true });
+        await mkdir(active, { recursive: true });
+        await writeFile(activeShim, 'peer');
+        throw new Error('our activation lost to peer');
+      },
+      readHooksPath: async () => null,
+      restoreHooksPath: async () => {
+        restored = true;
+      },
+    }),
+    /Hook installation failed/,
+  );
+
+  assert.equal(await readFile(activeShim, 'utf8'), 'peer');
+  assert.equal(restored, false);
+});
+
+test('an explicit interactive HUSKY=0 opt-out preserves existing hooks without running installer', async () => {
+  const root = await fixture('disabled');
+  const activeShim = path.join(root, '.husky', '_', 'h');
+  await mkdir(path.dirname(activeShim), { recursive: true });
+  await writeFile(activeShim, 'preserved');
+  let ran = false;
+
+  await installHooks({
+    root,
+    disabled: true,
+    runHusky: async () => {
+      ran = true;
+    },
+  });
+
+  assert.equal(ran, false);
+  assert.equal(await readFile(activeShim, 'utf8'), 'preserved');
+});
+
+test('a successful install leaves a complete active hook set', async () => {
+  const root = await fixture('success');
+
+  await installHooks({
+    root,
+    quarantineRoot,
+    runHusky: async (stagingHooks) => {
+      await mkdir(path.join(stagingHooks, '_'), { recursive: true });
+      await writeFile(path.join(stagingHooks, '_', 'h'), 'complete');
+    },
+    activateHooks: async () => {},
+    readHooksPath: async () => null,
+    restoreHooksPath: async () => {},
+  });
+
+  assert.equal(await exists(path.join(root, '.husky', '_', 'h')), true);
+});
@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+import { constants } from 'node:fs';
+import { access, lstat, readFile, readdir, readlink } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+export const MISSING_DEPS_EXIT = 42;
+export const GENERATED_STATE_EXIT = 43;
+
+const scriptRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+async function entries(root) {
+  const result = [];
+  async function walk(current) {
+    let children;
+    try {
+      children = await readdir(current, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT') return;
+      throw error;
+    }
+    for (const child of children) {
+      const target = path.join(current, child.name);
+      result.push(target);
+      if (child.isDirectory() && !child.isSymbolicLink()) await walk(target);
+    }
+  }
+  await walk(root);
+  return result;
+}
+
+export async function generatedSymlinkManifest(nextDir) {
+  const links = [];
+  for (const target of (await entries(nextDir)).sort()) {
+    const stats = await lstat(target);
+    if (!stats.isSymbolicLink()) continue;
+    links.push({
+      path: path.relative(nextDir, target).split(path.sep).join('/'),
+      target: await readlink(target),
+    });
+  }
+  return `${JSON.stringify({ version: 1, links })}\n`;
+}
+
+const webSourceRoots = (root) => [
+  path.join(root, 'apps', 'web', 'src'),
+  path.join(root, 'apps', 'web', 'public'),
+  path.join(root, 'apps', 'web', 'next-env.d.ts'),
+  path.join(root, 'apps', 'web', 'next.config.ts'),
+  path.join(root, 'apps', 'web', 'postcss.config.mjs'),
+  path.join(root, 'apps', 'web', 'package.json'),
+  path.join(root, 'apps', 'web', 'tsconfig.json'),
+  path.join(root, 'packages', 'design-tokens', 'src'),
+  path.join(root, 'packages', 'design-tokens', 'package.json'),
+  path.join(root, 'packages', 'design-tokens', 'tsconfig.json'),
+  path.join(root, 'package.json'),
+  path.join(root, 'tsconfig.base.json'),
+  path.join(root, 'pnpm-lock.yaml'),
+  path.join(root, 'pnpm-workspace.yaml'),
+  path.join(root, 'turbo.json'),
+];
+
+// next.config.ts currently reads no server-only environment. Add any future
+// server-side build inputs here; all resolved NEXT_PUBLIC_* inputs are automatic.
+const serverBuildEnvironmentKeys = [];
+
+function publicBuildEnvironment(root) {
+  const webDir = path.join(root, 'apps', 'web');
+  const requireFromWeb = createRequire(path.join(scriptRoot, 'apps', 'web', 'package.json'));
+  const requireFromNext = createRequire(requireFromWeb.resolve('next/package.json'));
+  const { loadEnvConfig, resetEnv, updateInitialEnv } = requireFromNext('@next/env');
+  const originalEnvironment = { ...process.env };
+  updateInitialEnv(originalEnvironment);
+  try {
+    const { combinedEnv } = loadEnvConfig(webDir, false, { info() {}, error() {} }, true);
+    return Object.fromEntries(
+      Object.entries(combinedEnv).filter(
+        ([key, value]) =>
+          value !== undefined &&
+          (key.startsWith('NEXT_PUBLIC_') || serverBuildEnvironmentKeys.includes(key)),
+      ),
+    );
+  } finally {
+    resetEnv();
+  }
+}
+
+export async function sourceFingerprint(root = process.cwd()) {
+  const files = [];
+  for (const sourceRoot of webSourceRoots(root)) {
+    try {
+      const stats = await lstat(sourceRoot);
+      if (stats.isSymbolicLink()) {
+        throw new Error(
+          `Web build input must not be a symbolic link: ${path.relative(root, sourceRoot)}`,
+        );
+      }
+      if (stats.isFile()) files.push(sourceRoot);
+      if (stats.isDirectory()) {
+        for (const target of await entries(sourceRoot)) {
+          const targetStats = await lstat(target);
+          if (targetStats.isSymbolicLink()) {
+            throw new Error(
+              `Web build input must not be a symbolic link: ${path.relative(root, target)}`,
+            );
+          }
+          if (targetStats.isFile()) files.push(target);
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+
+  const digest = createHash('sha256');
+  for (const [key, value] of Object.entries(publicBuildEnvironment(root)).sort()) {
+    digest.update(`env:${key}\0${value.length}\0${value}\0`);
+  }
+  for (const target of files.sort()) {
+    const contents = await readFile(target);
+    digest.update(path.relative(root, target).split(path.sep).join('/'));
+    digest.update('\0');
+    digest.update(String(contents.length));
+    digest.update('\0');
+    digest.update(contents);
+    digest.update('\0');
+  }
+  return digest.digest('hex');
+}
+
+export async function runPreflight({ root = process.cwd(), uid = process.getuid?.() } = {}) {
+  const binDir = path.join(root, 'node_modules', '.bin');
+  const requiredBinaries = ['eslint', 'husky', 'prettier', 'tsc', 'turbo', 'vitest'];
+  const missingBinaries = [];
+  for (const binary of requiredBinaries) {
+    try {
+      await access(path.join(binDir, binary), constants.X_OK);
+    } catch {
+      missingBinaries.push(binary);
+    }
+  }
+  if (missingBinaries.length > 0) {
+    return {
+      code: MISSING_DEPS_EXIT,
+      message: `MOSAIC_PREFLIGHT_MISSING_DEPS: dependency installation is missing ${missingBinaries.join(', ')}; run pnpm install --frozen-lockfile`,
+    };
+  }
+
+  const buildLock = path.join(root, '.mosaic-test-work', 'web-build.lock');
+  try {
+    await lstat(buildLock);
+    return {
+      code: GENERATED_STATE_EXIT,
+      message: `MOSAIC_PREFLIGHT_GENERATED_STATE: web build is in progress or interrupted at ${buildLock}; wait for it to finish or rerun pnpm build to recover the stale lock`,
+    };
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const nextDir = path.join(root, 'apps', 'web', '.next');
+  let generated = [];
+  try {
+    const nextStats = await lstat(nextDir);
+    if (!nextStats.isDirectory() || nextStats.isSymbolicLink()) {
+      return {
+        code: GENERATED_STATE_EXIT,
+        message:
+          'MOSAIC_PREFLIGHT_GENERATED_STATE: apps/web/.next must be a real directory, not a symbolic link, and is not trustworthy; run pnpm clean:generated, then rerun the gate',
+      };
+    }
+    generated = [nextDir, ...(await entries(nextDir))];
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  if (generated.length > 0) {
+    const foreign = [];
+    for (const target of generated) {
+      const stats = await lstat(target);
+      if (uid !== undefined && stats.uid !== uid) foreign.push(path.relative(root, target));
+    }
+
+    // Detects accidental, independent, stale, and foreign-residue mutation of
+    // generated state: the class this check was born from was a five-month-stale
+    // .next whose validator referenced deleted pages and produced 19 phantom TS2307
+    // errors indistinguishable from real type errors.
+    //
+    // Does NOT defend against an actor with same-UID write access to the generated
+    // tree, which can regenerate both the manifest and marker consistently
+    // (CWE-345). No local construction can, absent a trust anchor outside that
+    // actor's authority. RM-59 tracks executor/spine-side attestation.
+    let certification = null;
+    let certifiedManifest = null;
+    try {
+      const [certificationContents, manifestContents] = await Promise.all([
+        readFile(path.join(nextDir, '.mosaic-source-hash'), 'utf8'),
+        readFile(path.join(nextDir, '.mosaic-symlink-manifest'), 'utf8'),
+      ]);
+      try {
+        const parsed = JSON.parse(certificationContents);
+        if (
+          parsed.version === 1 &&
+          typeof parsed.sourceFingerprint === 'string' &&
+          typeof parsed.symlinkManifestHash === 'string'
+        ) {
+          certification = parsed;
+          certifiedManifest = manifestContents;
+        }
+      } catch {
+        // Invalid certification is handled as untrusted generated state below.
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const stale = certification?.sourceFingerprint !== (await sourceFingerprint(root));
+    const actualManifest = await generatedSymlinkManifest(nextDir);
+    const certifiedManifestHash =
+      certifiedManifest === null
+        ? null
+        : createHash('sha256').update(certifiedManifest).digest('hex');
+    const changedSymlinks =
+      certification?.symlinkManifestHash !== certifiedManifestHash ||
+      certifiedManifest !== actualManifest;
+    if (foreign.length > 0 || stale || changedSymlinks) {
+      const reasons = [
+        foreign.length > 0 ? `foreign-owned paths: ${foreign.slice(0, 3).join(', ')}` : '',
+        stale ? 'generated source fingerprint does not match web source/configuration' : '',
+        changedSymlinks
+          ? 'generated symbolic-link manifest does not match the certified build'
+          : '',
+      ].filter(Boolean);
+      return {
+        code: GENERATED_STATE_EXIT,
+        message: `MOSAIC_PREFLIGHT_GENERATED_STATE: apps/web/.next is not trustworthy (${reasons.join('; ')}); run pnpm clean:generated, then rerun the gate`,
+      };
+    }
+  }
+
+  return { code: 0, message: 'checkout preflight passed' };
+}
+
+async function main() {
+  const result = await runPreflight();
+  const stream = result.code === 0 ? process.stdout : process.stderr;
+  stream.write(`${result.message}\n`);
+  process.exitCode = result.code;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}
@@ -0,0 +1,274 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, rm, symlink, utimes, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import test from 'node:test';
+
+import { runPreflight, sourceFingerprint } from './preflight.mjs';
+
+const fixtureRoot = path.join(process.cwd(), '.mosaic-test-work', `preflight-${process.pid}`);
+
+const requiredBins = ['eslint', 'husky', 'prettier', 'tsc', 'turbo', 'vitest'];
+
+async function fixture(name) {
+  const root = path.join(fixtureRoot, name);
+  await mkdir(path.join(root, 'apps', 'web', 'src', 'app'), { recursive: true });
+  await writeFile(path.join(root, 'apps', 'web', 'src', 'app', 'page.tsx'), 'export default 1;\n');
+  return root;
+}
+
+async function installRequiredBins(root) {
+  const binDir = path.join(root, 'node_modules', '.bin');
+  await mkdir(binDir, { recursive: true });
+  await Promise.all(
+    requiredBins.map(async (name) => {
+      const target = path.join(binDir, name);
+      await writeFile(target, '');
+      await chmod(target, 0o755);
+    }),
+  );
+}
+
+async function certifyGeneratedState(root, links = []) {
+  const nextDir = path.join(root, 'apps', 'web', '.next');
+  await mkdir(nextDir, { recursive: true });
+  const manifest = `${JSON.stringify({ version: 1, links })}\n`;
+  const manifestHash = createHash('sha256').update(manifest).digest('hex');
+  await writeFile(path.join(nextDir, '.mosaic-symlink-manifest'), manifest);
+  await writeFile(
+    path.join(nextDir, '.mosaic-source-hash'),
+    `${JSON.stringify({
+      version: 1,
+      sourceFingerprint: await sourceFingerprint(root),
+      symlinkManifestHash: manifestHash,
+    })}\n`,
+  );
+}
+
+test.after(async () => {
+  await rm(fixtureRoot, { recursive: true, force: true });
+});
+
+test('missing dependencies have a dedicated exit code and install remediation', async () => {
+  const root = await fixture('missing-deps');
+  const result = await runPreflight({ root });
+
+  assert.equal(result.code, 42);
+  assert.match(result.message, /MOSAIC_PREFLIGHT_MISSING_DEPS/);
+  assert.match(result.message, /run pnpm install/i);
+});
+
+test('a partial dependency install keeps the dedicated missing-deps result', async () => {
+  const root = await fixture('partial-deps');
+  await mkdir(path.join(root, 'node_modules', '.bin'), { recursive: true });
+  await writeFile(path.join(root, 'node_modules', '.bin', 'tsc'), '', { mode: 0o755 });
+
+  const result = await runPreflight({ root });
+  assert.equal(result.code, 42);
+  assert.match(result.message, /turbo/);
+});
+
+test('a dangling required dependency shim keeps the dedicated missing-deps result', async () => {
+  const root = await fixture('dangling-deps');
+  await installRequiredBins(root);
+  const turbo = path.join(root, 'node_modules', '.bin', 'turbo');
+  await rm(turbo);
+  await symlink(path.join(root, 'node_modules', 'missing-turbo'), turbo);
+
+  const result = await runPreflight({ root });
+  assert.equal(result.code, 42);
+  assert.match(result.message, /turbo/);
+});
+
+test('installed dependencies pass when generated state is absent', async () => {
+  const root = await fixture('clean');
+  await installRequiredBins(root);
+
+  assert.deepEqual(await runPreflight({ root }), { code: 0, message: 'checkout preflight passed' });
+});
+
+test('foreign-owned generated Next state is identified separately from source errors', async () => {
+  const root = await fixture('foreign-next');
+  await installRequiredBins(root);
+  const generated = path.join(root, 'apps', 'web', '.next', 'types', 'validator.ts');
+  await mkdir(path.dirname(generated), { recursive: true });
+  await writeFile(generated, 'generated output');
+
+  const result = await runPreflight({ root, uid: (process.getuid?.() ?? 0) + 1 });
+  assert.equal(result.code, 43);
+  assert.match(result.message, /MOSAIC_PREFLIGHT_GENERATED_STATE/);
+  assert.match(result.message, /foreign-owned/);
+});
+
+test('a generated marker mismatch is identified separately from source errors', async () => {
+  const root = await fixture('stale-next');
+  await installRequiredBins(root);
+  const generated = path.join(root, 'apps', 'web', '.next', 'types', 'validator.ts');
+  await mkdir(path.dirname(generated), { recursive: true });
+  await writeFile(generated, 'stale generated output');
+  await writeFile(path.join(root, 'apps', 'web', '.next', '.mosaic-source-hash'), 'old-source');
+
+  const result = await runPreflight({ root });
+  assert.equal(result.code, 43);
+  assert.match(result.message, /MOSAIC_PREFLIGHT_GENERATED_STATE/);
+  assert.match(result.message, /apps\/web\/\.next/);
+  assert.match(result.message, /pnpm clean:generated/);
+});
+
+test('generated-state symbolic links are accepted only when exactly build-certified', async (t) => {
+  await t.test('apps/web/.next itself is rejected when it is a symbolic link', async () => {
+    const root = await fixture('symbolic-next-root');
+    await installRequiredBins(root);
+    await writeFile(path.join(root, 'outside-generated'), 'not a Next build\n');
+    await symlink(path.join(root, 'outside-generated'), path.join(root, 'apps', 'web', '.next'));
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /MOSAIC_PREFLIGHT_GENERATED_STATE/);
+    assert.match(result.message, /symbolic link/);
+  });
+
+  await t.test('apps/web/.next is rejected when it is not a directory', async () => {
+    const root = await fixture('non-directory-next-root');
+    await installRequiredBins(root);
+    await writeFile(path.join(root, 'apps', 'web', '.next'), 'not a Next build\n');
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /MOSAIC_PREFLIGHT_GENERATED_STATE/);
+    assert.match(result.message, /real directory/);
+  });
+
+  await t.test('an added descendant symlink is rejected', async () => {
+    const root = await fixture('symbolic-next-added');
+    await installRequiredBins(root);
+    await certifyGeneratedState(root);
+    await symlink('/etc/hosts', path.join(root, 'apps', 'web', '.next', 'reviewer-symlink'));
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /symbolic-link manifest/);
+  });
+
+  await t.test('a removed certified descendant symlink is rejected', async () => {
+    const root = await fixture('symbolic-next-removed');
+    await installRequiredBins(root);
+    const link = path.join(root, 'apps', 'web', '.next', 'dependency-link');
+    await mkdir(path.dirname(link), { recursive: true });
+    await symlink('../dependency-one', link);
+    await certifyGeneratedState(root, [{ path: 'dependency-link', target: '../dependency-one' }]);
+    await rm(link);
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /symbolic-link manifest/);
+  });
+
+  await t.test('a retargeted certified descendant symlink is rejected', async () => {
+    const root = await fixture('symbolic-next-retargeted');
+    await installRequiredBins(root);
+    const link = path.join(root, 'apps', 'web', '.next', 'dependency-link');
+    await mkdir(path.dirname(link), { recursive: true });
+    await symlink('../dependency-one', link);
+    await certifyGeneratedState(root, [{ path: 'dependency-link', target: '../dependency-one' }]);
+    await rm(link);
+    await symlink('../dependency-two', link);
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /symbolic-link manifest/);
+  });
+
+  await t.test('a manifest edited to whitelist a rogue symlink is rejected', async () => {
+    const root = await fixture('symbolic-next-tampered-manifest');
+    await installRequiredBins(root);
+    await certifyGeneratedState(root);
+    const nextDir = path.join(root, 'apps', 'web', '.next');
+    await symlink('/etc/hosts', path.join(nextDir, 'reviewer-symlink'));
+    await writeFile(
+      path.join(nextDir, '.mosaic-symlink-manifest'),
+      `${JSON.stringify({
+        version: 1,
+        links: [{ path: 'reviewer-symlink', target: '/etc/hosts' }],
+      })}\n`,
+    );
+
+    const result = await runPreflight({ root });
+    assert.equal(result.code, 43);
+    assert.match(result.message, /symbolic-link manifest/);
+  });
+
+  await t.test('unchanged canonical-style descendant symlinks are accepted', async () => {
+    const root = await fixture('symbolic-next-certified');
+    await installRequiredBins(root);
+    const link = path.join(
+      root,
+      'apps',
+      'web',
+      '.next',
+      'standalone',
+      'node_modules',
+      'dependency',
+    );
+    await mkdir(path.dirname(link), { recursive: true });
+    await symlink('../.pnpm/dependency', link);
+    await certifyGeneratedState(root, [
+      { path: 'standalone/node_modules/dependency', target: '../.pnpm/dependency' },
+    ]);
+
+    assert.deepEqual(await runPreflight({ root }), {
+      code: 0,
+      message: 'checkout preflight passed',
+    });
+  });
+});
+
+test('the source fingerprint includes inherited TypeScript configuration', async () => {
+  const root = await fixture('inherited-typescript-config');
+  const config = path.join(root, 'tsconfig.base.json');
+  await writeFile(config, '{"compilerOptions":{"strict":true}}\n');
+  const first = await sourceFingerprint(root);
+  await writeFile(config, '{"compilerOptions":{"strict":false}}\n');
+  const second = await sourceFingerprint(root);
+
+  assert.notEqual(first, second);
+});
+
+test('the source fingerprint rejects symbolic-link build inputs', async () => {
+  const root = await fixture('symbolic-source');
+  await writeFile(path.join(root, 'outside.ts'), 'export default 1;\n');
+  await symlink(path.join(root, 'outside.ts'), path.join(root, 'apps', 'web', 'src', 'linked.ts'));
+
+  await assert.rejects(sourceFingerprint(root), /must not be a symbolic link/);
+});
+
+test('the source fingerprint includes expanded public web build environment', async () => {
+  const root = await fixture('public-build-environment');
+  const envFile = path.join(root, 'apps', 'web', '.env.production');
+  await writeFile(
+    envFile,
+    'RM01_GATEWAY_URL=https://one.example\nNEXT_PUBLIC_RM01_URL=$RM01_GATEWAY_URL\n',
+  );
+  const first = await sourceFingerprint(root);
+  await writeFile(
+    envFile,
+    'RM01_GATEWAY_URL=https://two.example\nNEXT_PUBLIC_RM01_URL=$RM01_GATEWAY_URL\n',
+  );
+  const second = await sourceFingerprint(root);
+
+  assert.notEqual(first, second);
+});
+
+test('a matching generation marker accepts incremental output with mixed mtimes', async () => {
+  const root = await fixture('incremental-next');
+  await installRequiredBins(root);
+  const generated = path.join(root, 'apps', 'web', '.next', 'types', 'validator.ts');
+  await mkdir(path.dirname(generated), { recursive: true });
+  await writeFile(generated, 'unchanged generated output');
+  await utimes(generated, new Date('2020-01-01T00:00:00Z'), new Date('2020-01-01T00:00:00Z'));
+  const fresh = path.join(root, 'apps', 'web', '.next', 'types', 'routes.ts');
+  await writeFile(fresh, 'fresh generated output');
+  await certifyGeneratedState(root);
+
+  assert.deepEqual(await runPreflight({ root }), { code: 0, message: 'checkout preflight passed' });
+});
Author	SHA1	Message	Date
f10-coder	98046a76a2	fix: reject malformed generated roots ci/woodpecker/pr/ci Pipeline was successful Details	2026-07-31 19:25:44 -05:00
f10-coder	f710a8d7fb	docs: record scoped AC2 and AC8 evidence	2026-07-31 19:23:02 -05:00
f10-coder	df7530aeac	fix: certify generated symlink state	2026-07-31 19:20:39 -05:00
f10-coder	7ae3f97789	docs: record RM-01 acceptance evidence ci/woodpecker/pr/ci Pipeline was successful Details ci/woodpecker/manual/ci Pipeline was successful Details	2026-07-31 18:30:16 -05:00
f10-coder	0f7061195b	fix: harden reproducible checkout races	2026-07-31 18:25:20 -05:00
mosaic-coder	ece7653ca0	test: capture remaining checkout race regressions ci/woodpecker/pr/ci Pipeline failed Details	2026-07-31 17:50:58 -05:00
mosaic-coder	a0209ee102	fix: make checkout gates environment-aware	2026-07-31 17:50:58 -05:00
mos-dt-0andMos	01e966f36d	docs(remediation): mission charter + reconciled execution backlog (#1026 ) ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: mos-dt-0 <[email protected]>	2026-07-31 22:47:03 +00:00
mos-dt-0andMos	524146055d	fix(hygiene): .prettierignore must exclude Python build/test artifacts (#1025 ) ci/woodpecker/push/publish Pipeline failed Details ci/woodpecker/push/ci Pipeline was successful Details Co-authored-by: mos-dt-0 <[email protected]>	2026-07-31 22:24:49 +00:00