framework tools/git: R3 --body-file across all nine body/comment carriers

--body-file <path> and --body-file - (stdin) load the body/comment from
a file, killing the fragile shell-quoting class for long Markdown
(Jason remediation R3). Contract: mutually exclusive with --body
(rc 2), unreadable file rc 2 naming the path, resolution runs AFTER
parsing and BEFORE the required-value checks. Full arm set on the
issue-comment suite (file, stdin, exclusive, missing); all nine
carrier suites and the readback suite green. Mirrored to brain.

.env.example

@@ -40,9 +40,12 @@ BETTER_AUTH_SECRET=change-me-to-a-random-32-char-string
 BETTER_AUTH_URL=http://localhost:14242
 
 
-# ─── Web App (Next.js) ───────────────────────────────────────────────────────
-# Public gateway URL — accessible from the browser, not just the server.
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
+# ─── Web App (SPA) ───────────────────────────────────────────────────────────
+# Directory holding the built SPA bundle (vite build output). When set, the
+# gateway serves the SPA same-origin; when unset (dev), run the Vite dev
+# server (pnpm --filter @mosaicstack/web dev), which proxies to the gateway.
+# safe-default: unset in dev — SPA serving is an opt-in production concern
+#WEB_DIST_DIR=apps/web/dist
 
 
 # ─── OpenTelemetry ───────────────────────────────────────────────────────────

.gitignore

@@ -23,3 +23,7 @@ infra/step-ca/dev-password
 # traversal error: ... .timestamp-*.mjs: No such file or directory" when the
 # file vanished mid-scan. Ignoring them removes the race.
 *.timestamp-*.mjs
+
+# Playwright run artifacts (#1445, P6 E2E gate)
+apps/web/test-results/
+apps/web/playwright-report/

.mosaic/repo.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 2,
+  "integration_trunk": "next",
+  "release_branch": "main",
+  "flow": "trunk-release",
+  "canonical_remote": "https://git.mosaicstack.dev/mosaicstack/stack",
+  "canonical_clone": "host:/src/mosaic-stack",
+  "worktree_root": "host:/src/mosaic-stack-worktrees",
+  "worktree_policy": "orchestrator-precreated",
+  "notes": "next=development/integration; main=production release. Never branch work off main. worktree_policy is TRANSITIONAL: the wrapper worktree consumer is BLOCKED on the J3/#1174 amendment (checked roots + capacity guard); pre-creation is the interim orchestration choice, not closed policy — it becomes a timing choice only after the wrapper can validate this root."
+}

.woodpecker/ci-image.yml

@@ -22,9 +22,9 @@ steps:
     image: gcr.io/kaniko-project/executor:debug
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}

.woodpecker/ci.yml

@@ -2,24 +2,48 @@
 # node:24-alpine + python3/make/g++/postgresql-client + pnpm + a warm pnpm
 # store. The install step resolves from the baked store (--prefer-offline)
 # instead of paying a ~731s cold fetch + native compile every run.
+#
+# PINNED to an immutable lock-tag (#1328, brain D27): ci-image.yml pushes
+# lock-<sha256(pnpm-lock.yaml)[:12]> atomically with :latest, so the two are
+# byte-identical at push time. A mutable :latest resolves per-pod at pull time
+# on the k8s backend, which made CI verdicts non-reproducible (same tree, same
+# config, different images across runs; see #1324 comment 23382/23386). The pin
+# changes ONLY through reviewed commits; a wrong tag fails loudly at image pull.
+#
+# Bump procedure: when a recipe change (pnpm-lock.yaml / Dockerfile.ci) lands on
+# main, ci-image.yml pushes lock-<new>; a follow-up PR updates this anchor.
+# Until then pipelines keep the old pin: reproducible, with the documented
+# network-fallback lag (frozen-lockfile resolves missing packages from network).
+# Known limitation: lock- addresses the lockfile only, so a Dockerfile-only
+# change re-pushes the same tag with new content (#1328 follow-up: recipe-hash).
 variables:
-  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:lock-9cb7ffcd8828'
   - &enable_pnpm 'corepack enable'
 
 when:
-  # PR + manual CI run on any branch — the pull_request pipeline is the merge gate.
-  # push CI is restricted to protected branches (main) so a feature-branch push no
-  # longer fires a redundant SECOND pipeline alongside its PR pipeline. This ~halves
-  # CI load on the storage-constrained runner with zero loss of gating (branch
-  # protection requires no push/ci status context; main still gets full push CI).
+  # PR + manual CI run on any branch: the pull_request pipeline is the merge
+  # gate (next is protected and the default branch since 2026-08-19).
+  # Push CI runs on main only. next deliberately runs NO push ci: post-merge
+  # verification on next is carried by publish.yml's `verify` step
+  # (pnpm verify:release), which mirrors this pipeline's complete mandatory
+  # set step-for-step, enforced by scripts/verify-release.test.mjs. PR CI
+  # tests the PR HEAD tree (refs/pull/N/head, measured 2026-08-19), not a
+  # merge ref, so if next advances before a merge the landed tree differs
+  # from the tested one; publish verify re-runs the full set on the landed
+  # tree (PGlite path). Measured 2026-08-19: the 21 most recent push events
+  # on next each ran exactly one pipeline (publish), zero ci.
+  # Keeping push ci off next also avoids a redundant second full-suite run
+  # per merge on the storage-constrained runner.
   - event: [pull_request, manual]
   - event: push
     branch: main
 
-# Turbo remote cache (turbo.mosaicstack.dev) is configured via Woodpecker
-# repository-level environment variables (TURBO_API, TURBO_TEAM, TURBO_TOKEN).
-# This avoids from_secret which is blocked on pull_request events.
-# If the env vars aren't set, turbo falls back to local cache only.
+# Turbo remote cache (turbo.mosaicstack.dev) is wired in publish.yml via the
+# org-level Woodpecker secret `turbo_token` (events: push/tag/cron/manual/
+# deployment — never pull_request). This PR pipeline deliberately gets no
+# remote-cache credentials: an untrusted PR must not be able to write to (or
+# poison) the shared cache. Without TURBO_* env vars turbo falls back to
+# local cache only, which is the intended behavior here.
 
 steps:
   install:
@@ -30,6 +54,19 @@ steps:
       # the baked pnpm store.
       - pnpm install --frozen-lockfile --prefer-offline
 
+  # ---------------------------------------------------------------------------
+  # The steps below (sanitization, upgrade-guard, typecheck, lint, format,
+  # test) are the COMPLETE mandatory verification set. SDLC-D-034 mirrors them
+  # one-for-one in the canonical terminal verification command — root
+  # `pnpm verify:release` (scripts/verify-release.mjs) — which the publish
+  # pipeline (.woodpecker/publish.yml `verify` step) runs before ANY publish
+  # effect. These lines stay direct (not routed through the runner) because the
+  # #1017 test-enumeration guard audits framework tool paths through THIS
+  # surface; scripts/verify-release.test.mjs enforces that the runner's stage
+  # table keeps matching these commands exactly, so the two cannot drift.
+  # ---------------------------------------------------------------------------
+
+  # Canonical verify:release stage `sanitization`.
   # Blocking gate: public framework package must contain no operator-specific
   # personal data or private $HOME defaults. Runs early (no node_modules needed).
   sanitization:
@@ -46,7 +83,73 @@ steps:
       # [0] of the pnpm chain, so severing that chain would silence it together
       # with everything it guards; this direct line keeps one instrument running.
       - bash packages/mosaic/framework/tools/quality/scripts/check-test-enumeration.sh
+      # Tool-index gate: a shipped wrapper that appears in no resident index doc
+      # is undiscoverable from inside a session, and an agent that cannot learn a
+      # wrapper exists reaches for raw curl instead — which is how a Gitea review
+      # got filed PENDING three times. Ships-and-documented is one commit, or red.
+      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh --self-test
+      - bash packages/mosaic/framework/tools/quality/scripts/check-tools-index.sh
+      # Hermetic regression for issue-close.sh (#1081): mocks tea/curl onto PATH
+      # and sandboxes a throwaway git repo, so it resolves no real credentials and
+      # joins CI directly rather than the exclusions file.
+      - bash packages/mosaic/framework/tools/git/test-issue-close-fail-closed.sh
+      # Hermetic regression for the git identity ladder (#1356): mock tea on PATH,
+      # sandboxed repo, no real credentials (3/3 green under an empty HOME). Pins
+      # fail-closed: a seat whose login is missing gets a named error, never a
+      # borrowed identity. Joins CI directly; its #1007 exclusion is burned down.
+      - bash packages/mosaic/framework/tools/git/test-gitea-login-resolution.sh
+      # Hermetic regression for issue-view.sh (#1357): mock tea/curl, sandboxed
+      # repo. Pins that comment BODIES render on both paths and that a tea
+      # failure is named as what it was (git-config vs credential).
+      - bash packages/mosaic/framework/tools/git/test-issue-view-comments.sh
+      # Hermetic behavioural regression for the PreToolUse wrapper guard: proves
+      # it still blocks the three mistakes AND still lets reads, unwrapped
+      # endpoints and ordinary commands through. Both directions are asserted —
+      # a guard that over-blocks gets routed around, which fails just as hard.
+      - bash packages/mosaic/framework/tools/git/test-wrapper-guard.sh
+      # Hermetic regression for mosaic-worktree.sh at fleet scale: stubs git onto
+      # PATH so `list` faces ~450 KB of porcelain. The defect it pins is invisible
+      # at small size — `git … | awk '…exit'` gives the producer SIGPIPE, which
+      # under `set -euo pipefail` aborts the caller silently with rc=141 and no
+      # output. A repo only reaches that once it has enough worktrees, so the
+      # stub supplies the scale instead of the host's own checkout.
+      - bash packages/mosaic/framework/tools/git/test-mosaic-worktree-large-repo.sh
 
+  # Canonical repo-structure declaration gate (T51 WP5c, spec §5.4 point 2):
+  # .mosaic/repo.json is the machine-readable structure SSOT consumed by git
+  # wrappers and the T32 gate seat; this is its repo-side CI enforcement.
+  # Path-conditional: runs when the declaration, the vendored validator, or this
+  # pipeline config changes (manual runs always include it). Fails the pipeline
+  # on any VALIDATION_ERROR and enforces the schema_version 2 authoring rule
+  # (--require-v2: edited/new declarations may not stay v1). The validator is
+  # vendored into the framework tree (spec §5.1 final home) — provenance in its
+  # header; the hostile-input suite (101 arms, hermetic) runs alongside so the
+  # gate's own instrument ships in the same commit as the gate.
+  structure-declaration:
+    image: *node_image
+    commands:
+      - apk add --no-cache bash git
+      # MOSAIC_HOST_ROOT is a runtime anchor (spec §1.2a: unset fails closed
+      # for managed validation). CI has no host, so the step provisions an
+      # EXPLICIT fixture root — honest configuration for the resolution path,
+      # never a guess about a real host; the per-host containment checks are
+      # runtime concerns and do not run against a fixture. Grammar, schema,
+      # refs, flow, remote normalization, and path grammar all prove here.
+      - mkdir -p /tmp/t51-ci-hostroot
+      - bash packages/mosaic/framework/tools/structure/validate-repo-json.sh .mosaic/repo.json --require-v2
+      - bash packages/mosaic/framework/tools/structure/test-validate-repo-json.sh
+    environment:
+      MOSAIC_HOST_ROOT: /tmp/t51-ci-hostroot
+    when:
+      - event: pull_request
+        path:
+          include:
+            - '.mosaic/repo.json'
+            - 'packages/mosaic/framework/tools/structure/**'
+            - '.woodpecker/ci.yml'
+      - event: manual
+
+  # Canonical verify:release stage `upgrade-guard`.
   # Blocking gate (#791): a framework upgrade must never write or delete an
   # operator-owned path. The HARD GATE proves an unanticipated operator sentinel
   # survives a keep-mode reseed byte-identical (with rsync present AND absent —
@@ -68,6 +171,8 @@ steps:
       - bash packages/mosaic/framework/tools/quality/scripts/test-upgrade-durable-snapshot.sh
       - bash packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh
 
+  # Canonical verify:release stage `typecheck` — the same `pnpm typecheck`
+  # invocation (which runs the checkout preflight first, then turbo).
   typecheck:
     image: *node_image
     commands:
@@ -78,7 +183,8 @@ steps:
       - sanitization
       - upgrade-guard
 
-  # lint, format, and test are independent — run in parallel after typecheck
+  # lint, format, and test are independent — run in parallel after typecheck.
+  # Each runs exactly its canonical verify:release stage command.
   lint:
     image: *node_image
     commands:
@@ -95,6 +201,12 @@ steps:
     depends_on:
       - typecheck
 
+  # Canonical verify:release stage `test` — the `pnpm test` line below is the
+  # shared command; everything else in this step is PIPELINE-LEVEL
+  # prerequisite the canonical command expects its caller to provide (SDLC-D-034):
+  # the ci-postgres service + pg_isready wait + db:migrate (postgres path),
+  # `apk add openssl`, and the pinned pi install. None of those can move into
+  # the runner (it must also work locally on the PGlite path with no database).
   test:
     image: *node_image
     environment:
@@ -142,6 +254,23 @@ steps:
     depends_on:
       - typecheck
 
+  # Canonical verify:release stage `build` (#1445, P6): every PR proves the
+  # full workspace build — including the SPA `vite build` — before merge,
+  # instead of leaving build breakage to surface post-merge in publish.yml's
+  # verify step. Same canonical command the publish pipeline's build step runs.
+  build:
+    image: *node_image
+    commands:
+      - *enable_pnpm
+      - pnpm build
+    depends_on:
+      # after test, not typecheck: turbo gives `test` a ^build dependency, so
+      # running this step concurrently with test would put two independent
+      # turbo builds on the same shared-workspace dist/ and turbo cache with
+      # no cross-process locking — the same serialization invariant
+      # publish.yml documents for #1411.
+      - test
+
 services:
   ci-postgres:
     image: pgvector/pgvector:pg17

.woodpecker/publish.yml

@@ -1,10 +1,29 @@
 # Build, publish npm packages, and push Docker images
 # Runs on main for stable publishes and on next for integration-line prereleases/images
+#
+# SDLC-D-034 publish gate: every publish effect (publish-npm, publish-next-npm,
+# and every image build/push step) depends DIRECTLY on the `verify` step below.
+# `verify` (a) asserts the provider's commit identity matches the actual
+# checkout (CI_COMMIT_SHA == git rev-parse HEAD, fail closed on mismatch or
+# emptiness) and (b) runs the canonical terminal verification command
+# (`pnpm verify:release`), which mirrors the PR CI pipeline's complete
+# mandatory set (sanitization, upgrade-guard, preflight+typecheck, lint,
+# format:check, test, build) — see scripts/verify-release.mjs. A missing,
+# failed, skipped, cancelled, or inconclusive verification therefore skips the
+# dependent publish effects (fail closed). Path-filtered short-circuits may
+# skip publish EFFECTS (e.g. docs-only merges) but never bypass `verify` for a
+# publish that does run: `verify` itself carries no path filter.
+# scripts/verify-release.test.mjs enforces this DAG invariant at checkout time.
 
 variables:
   # Pre-baked CI base (see .woodpecker/ci-image.yml): node:24-alpine +
   # toolchain + warm pnpm store. Kills the second cold install publish pays.
-  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:latest'
+  # PINNED to the immutable lock-tag, not :latest (#1328, brain D27): a mutable
+  # tag resolves per-pod at pull time on the k8s backend and made CI verdicts
+  # non-reproducible (#1324). Byte-identical to :latest at pin time (pushed
+  # atomically by the same kaniko run, main 712c770, 2026-07-26). Bump only via
+  # reviewed PR, per the procedure in .woodpecker/ci.yml's header comment.
+  - &node_image 'git.mosaicstack.dev/mosaicstack/stack/ci-base:lock-9cb7ffcd8828'
   - &enable_pnpm 'corepack enable'
   # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
   # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
@@ -13,6 +32,11 @@ variables:
   # non-excluded change still builds, so no transitive dep can silently go stale.
   # (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
   # the separate `event: tag` entry.)
+  # #1407: ONE shared anchor for all three image steps. A second main-only
+  # anchor previously gated build-web/build-appservice, so next-lane pushes
+  # published gateway sha images with no web/appservice counterpart — no
+  # sha-parity set existed for next-lane containerized deploys. Every image
+  # step now builds on next too (sha-only destinations, enforced per step).
   - &image_build_when
     - event: tag
     - event: [push, manual]
@@ -25,16 +49,6 @@ variables:
           - '.woodpecker/**'
     - event: [push, manual]
       branch: next
-  - &main_image_build_when
-    - event: tag
-    - event: [push, manual]
-      branch: main
-      path:
-        exclude:
-          - 'packages/mosaic/**'
-          - 'docs/**'
-          - '**/*.md'
-          - '.woodpecker/**'
 
 when:
   - branch: [main, next]
@@ -48,13 +62,67 @@ steps:
       # Resolve from the baked pnpm store instead of a cold network fetch.
       - pnpm install --frozen-lockfile --prefer-offline
 
+  # SDLC-D-034 exact-commit publish gate. No `when`/path filter on purpose: it
+  # runs for every event this pipeline serves so no publish effect can ever
+  # start without it. Fails closed on commit-identity mismatch (or either SHA
+  # being empty) and on any incomplete verification.
+  verify:
+    image: *node_image
+    environment:
+      # Turbo remote cache (see .woodpecker/ci.yml header comment): org-level
+      # secret, exposed only on trusted events (push/tag/cron/manual/deployment).
+      TURBO_API: https://turbo.mosaicstack.dev
+      TURBO_TEAM: mosaic
+      TURBO_TOKEN:
+        from_secret: turbo_token
+    commands:
+      - *enable_pnpm
+      # (a) Commit identity: the provider's claimed SHA must equal the actual
+      # checkout HEAD — verification of anything else must never authorize a
+      # publish of this commit.
+      - |
+        if [ -z "$CI_COMMIT_SHA" ]; then
+          echo "[verify] FATAL: CI_COMMIT_SHA is empty — cannot certify commit identity" >&2
+          exit 1
+        fi
+        CHECKOUT_SHA="$(git rev-parse HEAD 2>/dev/null || true)"
+        if [ -z "$CHECKOUT_SHA" ]; then
+          echo "[verify] FATAL: git rev-parse HEAD returned nothing — cannot certify commit identity" >&2
+          exit 1
+        fi
+        if [ "$CI_COMMIT_SHA" != "$CHECKOUT_SHA" ]; then
+          echo "[verify] FATAL: provider commit ($CI_COMMIT_SHA) != checkout HEAD ($CHECKOUT_SHA)" >&2
+          exit 1
+        fi
+        echo "[verify] commit identity confirmed: $CHECKOUT_SHA"
+      # (b) Canonical terminal verification. Caller-provided prerequisites the
+      # runner expects (see .woodpecker/ci.yml comments): bash/rsync for the
+      # guard stages, openssl + the pinned pi binary for the test stage. git is
+      # baked into ci-base but re-asserted here so the identity check above can
+      # never silently depend on a stale baked image. DATABASE_URL is
+      # deliberately NOT set: the canonical command must hold on the PGlite
+      # path too and never sets or requires a database itself.
+      - apk add --no-cache bash rsync openssl git
+      - npm install -g @earendil-works/[email protected]
+      - pnpm verify:release
+    depends_on:
+      - install
+
   build:
     image: *node_image
+    environment:
+      # Turbo remote cache (see .woodpecker/ci.yml header comment): org-level
+      # secret, exposed only on trusted events (push/tag/cron/manual/deployment).
+      TURBO_API: https://turbo.mosaicstack.dev
+      TURBO_TEAM: mosaic
+      TURBO_TOKEN:
+        from_secret: turbo_token
     commands:
       - *enable_pnpm
       - pnpm build
     depends_on:
       - install
+      - verify
 
   publish-npm:
     image: *node_image
@@ -114,6 +182,7 @@ steps:
         exit 1
     depends_on:
       - build
+      - verify
 
   publish-next-npm:
     image: *node_image
@@ -142,6 +211,20 @@ steps:
         echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
         DIST_TAGS_JSON="$(npm view @mosaicstack/mosaic dist-tags --registry https://git.mosaicstack.dev/api/packages/mosaicstack/npm/ --json)"
         DIST_TAGS_JSON="$DIST_TAGS_JSON" node -e 'const tags = JSON.parse(process.env.DIST_TAGS_JSON || "{}"); if (!tags || typeof tags !== "object" || !Object.hasOwn(tags, "latest")) { throw new Error("Gitea npm registry did not return a usable dist-tags object"); } console.log("[publish-next] registry dist-tags OK: latest=" + tags.latest);'
+        # #1404: snapshot every publishable manifest BEFORE the transform so the
+        # workspace can be restored byte-exact after publish. The transform
+        # rewrites package.json in place (needed: pnpm publish reads the
+        # workspace manifests); without restore, later steps in this pipeline
+        # (build-gateway kaniko COPY + pnpm install --frozen-lockfile) see
+        # manifests that no longer match pnpm-lock.yaml and fail
+        # ERR_PNPM_OUTDATED_LOCKFILE. Snapshot dir is step-local tmp.
+        SNAPSHOT_DIR="$(mktemp -d /tmp/publish-next-manifests.XXXXXX)"
+        export SNAPSHOT_DIR
+        find apps packages plugins -name package.json -not -path "*/node_modules/*" -not -path "*/dist/*" | while read -r mf; do
+          mkdir -p "$SNAPSHOT_DIR/$(dirname "$mf")"
+          cp -p "$mf" "$SNAPSHOT_DIR/$mf"
+        done
+        echo "[publish-next] snapshotted $(find "$SNAPSHOT_DIR" -name package.json | wc -l) manifests to $SNAPSHOT_DIR"
         node <<'NODE'
         const fs = require('node:fs');
         const path = require('node:path');
@@ -149,23 +232,38 @@ steps:
         const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
         const roots = ['apps', 'packages', 'plugins'];
         const updated = [];
+        const exactVersions = new Map(); // name -> bumped next version
 
-        function walk(dir) {
+        function walk(dir, visit) {
           if (!fs.existsSync(dir)) return;
           for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
             if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.turbo') continue;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
               const packagePath = path.join(fullPath, 'package.json');
-              if (fs.existsSync(packagePath)) updatePackage(packagePath);
-              walk(fullPath);
+              if (fs.existsSync(packagePath)) {
+                const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+                if (manifest.name?.startsWith('@mosaicstack/') && !manifest.private) {
+                  visit(manifest, packagePath);
+                }
+              }
+              walk(fullPath, visit);
             }
           }
         }
 
-        function updatePackage(packagePath) {
-          const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
-          if (!manifest.name?.startsWith('@mosaicstack/') || manifest.private) return;
+        // #1389: two passes. Pass 1 bumps every publishable manifest to
+        // <stable+1>-next.<pipeline> exactly as before, recording name ->
+        // bumped version. Pass 2 rewrites every published manifest's
+        // @mosaicstack/* dependency entries (dependencies, devDependencies,
+        // peerDependencies, optionalDependencies) to the EXACT same-pipeline
+        // build. A caret range like ^0.0.3-next.2636 leaves the resolver free
+        // to pick any later build — and on a host with a stale cache, an
+        // installer-side scaffold pinned at stable, or a registry hiccup, that
+        // freedom is how a "next" install ends up executing stable-era code
+        // (web1 evidence: old tier validator, missing migrations). Exact pins
+        // make the defect class unrepresentable regardless of resolver path.
+        function bump(manifest, packagePath) {
           const stableMatch = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(manifest.version);
           if (!stableMatch) {
             throw new Error(manifest.name + " has unsupported semver version '" + manifest.version + "'");
@@ -174,13 +272,40 @@ steps:
           const oldVersion = manifest.version;
           manifest.version = major + '.' + minor + '.' + (Number(patch) + 1) + '-next.' + pipelineNumber;
           fs.writeFileSync(packagePath, JSON.stringify(manifest, null, 2) + '\n');
+          exactVersions.set(manifest.name, manifest.version);
           updated.push(manifest.name + ' ' + oldVersion + ' -> ' + manifest.version);
         }
 
-        for (const root of roots) walk(root);
+        const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+        let pinnedEntries = 0;
+        function pin(manifest, packagePath) {
+          let changed = false;
+          for (const field of DEP_FIELDS) {
+            const deps = manifest[field];
+            if (!deps || typeof deps !== 'object') continue;
+            for (const [name, range] of Object.entries(deps)) {
+              if (!name.startsWith('@mosaicstack/')) continue;
+              const exact = exactVersions.get(name);
+              if (!exact) {
+                throw new Error(
+                  manifest.name + ' depends on ' + name +
+                  ' which has no bumped version in this publish set — cannot pin');
+              }
+              if (range === exact) continue;
+              deps[name] = exact;
+              pinnedEntries++;
+              changed = true;
+            }
+          }
+          if (changed) fs.writeFileSync(packagePath, JSON.stringify(manifest, null, 2) + '\n');
+        }
+
+        for (const root of roots) walk(root, bump);
+        for (const root of roots) walk(root, pin);
         if (updated.length === 0) throw new Error('No publishable @mosaicstack/* packages found');
         console.log('[publish-next] computed prerelease versions for ' + updated.length + ' packages:');
         for (const line of updated) console.log('[publish-next] ' + line);
+        console.log('[publish-next] pinned ' + pinnedEntries + ' @mosaicstack/* dep entries to exact same-pipeline versions across ' + updated.length + ' manifests');
         NODE
         pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" --filter "!@mosaicstack/mosaic-as" publish --no-git-checks --access public --tag next
         EXPECTED_VERSION="$(node -p "require('./packages/mosaic/package.json').version")"
@@ -190,8 +315,187 @@ steps:
           exit 1
         fi
         echo "[publish-next] @mosaicstack/mosaic@next resolves to $RESOLVED_VERSION"
+        # #1389 post-publish guard: every freshly published manifest must carry
+        # EXACT same-pipeline @mosaicstack/* dep pins (no ranges, no stable
+        # fallback). A leak here fails the pipeline instead of shipping.
+        node <<'GUARD'
+        const { execFileSync } = require('node:child_process');
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const pipelineNumber = process.env.CI_PIPELINE_NUMBER;
+        const registry = 'https://git.mosaicstack.dev/api/packages/mosaicstack/npm/';
+        const roots = ['apps', 'packages', 'plugins'];
+        const published = [];
+        function walk(dir) {
+          if (!fs.existsSync(dir)) return;
+          for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.turbo') continue;
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+              const packagePath = path.join(fullPath, 'package.json');
+              if (fs.existsSync(packagePath)) {
+                const m = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+                if (m.name?.startsWith('@mosaicstack/') && !m.private) published.push(m.name);
+              }
+              walk(fullPath);
+            }
+          }
+        }
+        for (const root of roots) walk(root);
+        let failures = 0;
+        for (const name of published) {
+          let manifest;
+          try {
+            const out = execFileSync('npm', ['view', name + '@next', '--json', '--registry', registry],
+                                     { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+            const arr = JSON.parse(out);
+            manifest = Array.isArray(arr) ? arr[arr.length - 1] : arr;
+          } catch (e) {
+            console.error('[publish-next-guard] FAIL ' + name + ': npm view failed: ' + e.message);
+            failures++;
+            continue;
+          }
+          const fields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+          for (const field of fields) {
+            const deps = manifest[field];
+            if (!deps || typeof deps !== 'object') continue;
+            for (const [dep, range] of Object.entries(deps)) {
+              if (!dep.startsWith('@mosaicstack/')) continue;
+              const expected = dep === name ? manifest.version : null;
+              const isExactPin = /^\d+\.\d+\.\d+-next\./.test(range);
+              const samePipeline = range.endsWith('-next.' + pipelineNumber);
+              if (!isExactPin) {
+                console.error('[publish-next-guard] FAIL ' + name + ' -> ' + dep + ' range "' + range + '" is not an exact -next pin (stable-leak class, #1389)');
+                failures++;
+              } else if (!samePipeline) {
+                console.error('[publish-next-guard] FAIL ' + name + ' -> ' + dep + ' pinned "' + range + '" but this pipeline published -next.' + pipelineNumber + ' (cross-pipeline pin)');
+                failures++;
+              }
+            }
+          }
+        }
+        if (failures > 0) {
+          console.error('[publish-next-guard] FATAL: ' + failures + ' dep-pin violation(s) — stable-dep leak into next publish (#1389)');
+          process.exit(1);
+        }
+        console.log('[publish-next-guard] OK: all ' + published.length + ' published manifests carry exact same-pipeline @mosaicstack/* dep pins');
+        GUARD
+        # #1404 restore: put the workspace manifests back byte-exact so later
+        # steps (build-gateway frozen-lockfile install) see the committed tree.
+        RESTORE_FAIL=0
+        while read -r mf; do
+          if [ -f "$SNAPSHOT_DIR/$mf" ]; then
+            cp -p "$SNAPSHOT_DIR/$mf" "$mf"
+          else
+            echo "[publish-next] FATAL: no snapshot for $mf — cannot restore (snapshot incomplete?)" >&2
+            RESTORE_FAIL=1
+          fi
+        done < <(find apps packages plugins -name package.json -not -path "*/node_modules/*" -not -path "*/dist/*")
+        # Pristine guard (#1404 red-first control): the publish step must leave
+        # the workspace byte-identical to the checkout for every manifest.
+        # git diff is the arbiter — any residual mutation fails THIS step
+        # instead of surfacing as ERR_PNPM_OUTDATED_LOCKFILE in build-gateway.
+        if ! git diff --exit-code -- '**/package.json' >/dev/null 2>&1; then
+          echo "[publish-next] FATAL: workspace package.json files still differ from HEAD after restore (#1404 class)" >&2
+          git diff --stat -- '**/package.json' >&2 || true
+          RESTORE_FAIL=1
+        fi
+        rm -rf "$SNAPSHOT_DIR"
+        if [ "$RESTORE_FAIL" -ne 0 ]; then exit 1; fi
+        echo "[publish-next] workspace manifests restored byte-exact (git diff clean); later steps see the committed tree"
     depends_on:
       - build
+      - verify
+
+  # #1445 (P6): headless Playwright E2E gate on every trunk merge. Boots the
+  # real gateway on the embedded PGlite path (no DATABASE_URL, no services)
+  # serving the built SPA bundle via WEB_DIST_DIR — the exact serving path the
+  # gateway image ships (docker/gateway.Dockerfile sets WEB_DIST_DIR to the
+  # baked bundle), which keeps #1407's parity guarantee: the image build steps
+  # below depend on this gate, so a bundle that fails E2E never publishes.
+  #
+  # Image pinned to the @playwright/test version in pnpm-lock.yaml so the
+  # image's bundled browsers match the workspace driver exactly (bump the two
+  # together). The step installs no workspace packages (corepack does fetch
+  # the pinned pnpm itself): it reuses the workspace node_modules
+  # from `install` and the dist outputs from `build` — the gateway's runtime
+  # dependency path is pure JS/WASM (PGlite is WASM, postgres-js is pure JS),
+  # so the alpine-installed modules run unchanged under this glibc image.
+  # depends_on publish-next-npm per the #1411 serialization invariant: this
+  # step reads the workspace and must never run inside the manifest-transform
+  # window.
+  e2e:
+    image: mcr.microsoft.com/playwright:v1.58.2-noble
+    environment:
+      GATEWAY_PORT: '14242'
+      PLAYWRIGHT_BASE_URL: http://localhost:14242
+      # The database is seeded by Playwright's globalSetup in this step, so
+      # login failures are real failures: without this flag the suite's
+      # skip-when-login-fails guards (a live-environment affordance) could
+      # skip every authenticated spec and go green while proving nothing.
+      E2E_REQUIRE_SEEDED_AUTH: '1'
+    commands:
+      - corepack enable
+      - |
+        # Throwaway signing secret for this step's ephemeral embedded database
+        # (the gateway refuses to boot without one). Generated per run so no
+        # usable literal lives in the tree.
+        export BETTER_AUTH_SECRET="$(head -c 32 /dev/urandom | base64)"
+        export WEB_DIST_DIR="$(pwd)/apps/web/dist"
+        if [ ! -f "$WEB_DIST_DIR/index.html" ]; then
+          echo "[e2e] FATAL: $WEB_DIST_DIR/index.html missing — did the build step run?" >&2
+          exit 1
+        fi
+        # Boot the gateway from the built dist, cwd- AND HOME-isolated: the
+        # local-tier PGlite database lives under $HOME/.config/mosaic/gateway/
+        # (database.module.ts), not under cwd, so HOME must point at the
+        # throwaway dir too or the run would share a database with anything
+        # else in the container's home.
+        GATEWAY_RUN_DIR="$(mktemp -d /tmp/e2e-gateway.XXXXXX)"
+        (cd "$GATEWAY_RUN_DIR" && export HOME="$GATEWAY_RUN_DIR" && exec node "$OLDPWD/apps/gateway/dist/main.js") > /tmp/gateway.log 2>&1 &
+        GATEWAY_PID=$!
+        ready=0
+        for i in $(seq 1 90); do
+          if node -e "fetch('http://localhost:' + process.env.GATEWAY_PORT + '/health', { signal: AbortSignal.timeout(2000) }).then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"; then
+            ready=1
+            break
+          fi
+          if ! kill -0 "$GATEWAY_PID" 2>/dev/null; then
+            echo "[e2e] FATAL: gateway process exited during startup" >&2
+            cat /tmp/gateway.log >&2
+            exit 1
+          fi
+          echo "[e2e] waiting for gateway ($i/90)..."
+          sleep 1
+        done
+        if [ "$ready" -ne 1 ]; then
+          echo "[e2e] FATAL: gateway did not become ready in 90s" >&2
+          cat /tmp/gateway.log >&2
+          exit 1
+        fi
+        echo "[e2e] gateway ready; running Playwright suite"
+        set +e
+        pnpm --filter @mosaicstack/web exec playwright test
+        E2E_EXIT=$?
+        set -e
+        kill "$GATEWAY_PID" 2>/dev/null || true
+        if [ "$E2E_EXIT" -ne 0 ]; then
+          echo "[e2e] FATAL: Playwright suite failed (exit $E2E_EXIT); gateway log follows" >&2
+          tail -100 /tmp/gateway.log >&2
+          echo "[e2e] browser-side traces/screenshots are under apps/web/test-results/ in the step workspace (not persisted past the pod)" >&2
+        fi
+        exit "$E2E_EXIT"
+    # Same filter as the image builds it gates: a merge that publishes no
+    # image (docs-only on main) pays no browser suite, and a skipped e2e does
+    # not block anything (skipped-dependency semantics, same as
+    # publish-next-npm on tag events).
+    when: *image_build_when
+    depends_on:
+      - build
+      - verify
+      # #1411: never read the workspace inside publish-next-npm's
+      # manifest-transform window.
+      - publish-next-npm
 
   # TODO: Uncomment when ready to publish to npmjs.org
   # publish-npmjs:
@@ -205,6 +509,7 @@ steps:
   #     - bash scripts/publish-npmjs.sh
   #   depends_on:
   #     - build
+  #     - verify
   #   when:
   #     - event: [tag]
 
@@ -213,9 +518,9 @@ steps:
     when: *image_build_when
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}
@@ -242,15 +547,26 @@ steps:
         /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
     depends_on:
       - build
+      - verify
+      # #1411: publish-next-npm mutates workspace manifests in place during
+      # its transform window and restores them at step end. Any step that
+      # reads the pipeline workspace (kaniko COPY of manifests, later
+      # installs) must run AFTER publish-next-npm, never concurrently —
+      # pipeline 2648 raced a COPY inside the window and failed
+      # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
+      # serialization invariant; add it to every new workspace consumer.
+      - publish-next-npm
+      # #1445 (P6): a bundle that fails the E2E gate never publishes an image.
+      - e2e
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
-    when: *main_image_build_when
+    when: *image_build_when
     environment:
       REGISTRY_USER:
-        from_secret: gitea_username
+        from_secret: REGISTRY_USERNAME
       REGISTRY_PASS:
-        from_secret: gitea_password
+        from_secret: REGISTRY_PASSWORD
       CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
       CI_COMMIT_TAG: ${CI_COMMIT_TAG}
       CI_COMMIT_SHA: ${CI_COMMIT_SHA}
@@ -259,8 +575,17 @@ steps:
       - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
       - |
         DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/appservice:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
+        if [ "$CI_COMMIT_BRANCH" = "next" ]; then
+          if [ -n "$CI_COMMIT_TAG" ]; then
+            echo "[publish] FATAL: next appservice publish must be sha-only; refusing tag '$CI_COMMIT_TAG'" >&2
+            exit 1
+          fi
+          echo "[publish] next appservice publish is sha-only"
+        elif [ "$CI_COMMIT_BRANCH" = "main" ]; then
           DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:latest"
+        elif [ -z "$CI_COMMIT_TAG" ]; then
+          echo "[publish] FATAL: appservice image publish may only run for main, next, or tag events" >&2
+          exit 1
         fi
         if [ -n "$CI_COMMIT_TAG" ]; then
           DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/appservice:$CI_COMMIT_TAG"
@@ -268,29 +593,14 @@ steps:
         /kaniko/executor --context . --dockerfile docker/appservice.Dockerfile $DESTINATIONS
     depends_on:
       - build
-
-  build-web:
-    image: gcr.io/kaniko-project/executor:debug
-    when: *main_image_build_when
-    environment:
-      REGISTRY_USER:
-        from_secret: gitea_username
-      REGISTRY_PASS:
-        from_secret: gitea_password
-      CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
-      CI_COMMIT_TAG: ${CI_COMMIT_TAG}
-      CI_COMMIT_SHA: ${CI_COMMIT_SHA}
-    commands:
-      - mkdir -p /kaniko/.docker
-      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
-      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/stack/web:sha-${CI_COMMIT_SHA:0:7}"
-        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/web:latest"
-        fi
-        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/stack/web:$CI_COMMIT_TAG"
-        fi
-        /kaniko/executor --context . --dockerfile docker/web.Dockerfile $DESTINATIONS
-    depends_on:
-      - build
+      - verify
+      # #1411: publish-next-npm mutates workspace manifests in place during
+      # its transform window and restores them at step end. Any step that
+      # reads the pipeline workspace (kaniko COPY of manifests, later
+      # installs) must run AFTER publish-next-npm, never concurrently —
+      # pipeline 2648 raced a COPY inside the window and failed
+      # ERR_PNPM_OUTDATED_LOCKFILE despite a clean restore. This edge is the
+      # serialization invariant; add it to every new workspace consumer.
+      - publish-next-npm
+      # #1445 (P6): a bundle that fails the E2E gate never publishes an image.
+      - e2e

AGENTS.md

@@ -81,6 +81,73 @@ pnpm format:check  # Prettier check
 pnpm build         # Build all packages and applications
 ```
 
+## Branch Model and Merge Process — `main` and `next` (CANONICAL)
+
+**Every contribution targets `next` first. No exceptions.** Features, fixes, tests,
+docs, and policy changes all take the same route; urgency changes queue priority,
+never the route. Agents never commit to or merge into `main`.
+
+| Branch | Role                                                             | Who merges into it                                                          |
+| ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `next` | Integration trunk — the only PR target for contributions         | The designated merge-gate agent, after all gates pass. Never the PR author. |
+| `main` | Stable/release line — receives promotion merges from `next` only | Jason only (or an agent he explicitly delegates for a named promotion).     |
+
+### Contribution sequencing (in order, no skipping)
+
+1. **Issue first.** Work is tracked in a Gitea issue before a branch exists. The
+   issue number appears in the branch name and the PR body.
+2. **Branch from the current `origin/next` head.** Name it
+   `feat/…`, `fix/…`, `docs/…`, or `test/…` with the issue number
+   (e.g. `docs/1214-branch-process`). Record the base SHA in the PR body.
+3. **Develop with evidence.** Applicable tests accompany the change. Hooks are
+   never bypassed (`--no-verify` is prohibited). Stage explicit paths — never
+   `git add -A`.
+4. **Open the PR against `next`.** The body states: scope, base SHA,
+   verification commands with results, and any known pre-existing failures on
+   the base — documented, not retried to green and not absorbed silently.
+5. **CI must be terminal-green on the exact head.** All bounded Woodpecker
+   steps succeed (`verify-terminal-green` contract). Pipelines for fork PRs
+   start `blocked`; a maintainer approves the run — approving CI is not
+   approving the PR.
+6. **Independent review. Self-merge is prohibited** — for every agent, on every
+   PR, including trivial ones. Where the change touches protected or
+   contract-bearing content, the reviewer verifies the exact head
+   (exact-byte/exact-blob comparison), not a description of it. An `AMEND`
+   verdict returns the PR to its author; the reviewer's gate stays held until
+   a fresh exact head passes.
+7. **Merge into `next`** happens only after CI green + review pass, pinned to
+   the reviewed head SHA (a post-review push voids the review).
+8. **Promotion `next` → `main`** is a deliberate, Jason-owned reconciliation
+   merge — not part of any contribution's lifecycle. Contributors are done at
+   step 7.
+
+### Responsibilities
+
+- **Contributor** — base pinning, green CI, evidence in the PR body,
+  responding to AMEND verdicts, never merging own work.
+- **Reviewer / merge gate** — independent verification on the exact head;
+  holds and lifts gates; executes the merge into `next`.
+- **Orchestrator / adjudicator** — cross-PR sequencing, disposition when PRs
+  collide, conflict adjudication.
+- **Jason** — `next` → `main` promotions, merge-authority grants, collaborator
+  and token provisioning. Agents cannot grant themselves or each other any of
+  these.
+
+### Hotfixes and divergence
+
+- A hotfix follows the same path: branch from `next`, PR to `next`, gates,
+  merge, then an expedited Jason-owned promotion if `main` needs it urgently.
+  Committing the fix to `main` directly is prohibited even under pressure.
+- **Never land work on `main` that is not on `next`.** This has happened
+  (issue #1152's goal controller reached `main` without reaching `next`) and
+  every later PR paid for it. If it happens anyway: transplant the work onto
+  a `next`-based branch with provenance-preserving commits
+  (`git cherry-pick -x` or explicit SHA references in the messages), PR it
+  through the normal gates, and let promotion re-align `main`. Do not
+  hand-patch `main` to compensate.
+- Force-pushing a branch you do not own is prohibited; rebasing your own PR
+  branch is fine before review, and voids any review already given.
+
 ## Database and Local Runtime Safety
 
 - Current local data-layer work uses in-process PGlite; leave `DATABASE_URL` unset.

README.md

@@ -74,6 +74,14 @@ The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md
 
 Pi launches default to a token-lean skill posture: `mosaic pi` passes `--no-skills` so Pi does not preload every global skill description into the system prompt. Use `MOSAIC_PI_SKILL_MODE=all mosaic pi` for the legacy all-skills catalog, or `MOSAIC_PI_SKILL_MODE=discover mosaic pi` to let Pi use its native settings/project skill discovery.
 
+Mosaic also loads its Pi extensions from `~/.config/mosaic/runtime/pi/`. Inside Pi,
+`/goal set <statement>` starts a bounded persistent loop that checks every turn and successful
+compaction, requires two evidence-bearing completion reports, and can be inspected or stopped with
+`/goal status`, `/goal pause`, `/goal resume`, and `/goal cancel`. Controller-owned goal-state
+entries redact common credential shapes, but Pi's model/tool-call history is separate, so goals and
+evidence must never contain secrets or raw sensitive output. Mosaic does not install this extension
+into `~/.pi/agent/extensions/`.
+
 ### TUI & Gateway
 
 ```bash
@@ -138,9 +146,9 @@ mosaic brain tasks
 mosaic brain conversations
 
 # Agent forge pipeline
-mosaic forge run
+mosaic forge run [--simulate]        # fails closed (FORGE_NO_EXECUTOR) with no executor wired; --simulate for typed simulated runs
 mosaic forge status
-mosaic forge resume
+mosaic forge resume [--simulate]     # same fail-closed rule as forge run
 mosaic forge personas
 
 # Structured logging
@@ -331,7 +339,7 @@ The framework is the bash-based standards layer installed to every developer mac
 ├── bin/mosaic             ← Unified launcher (claude, codex, opencode, pi, yolo)
 ├── guides/                ← E2E delivery, orchestrator protocol, PRD, etc.
 ├── runtime/               ← Per-runtime configs (claude/, codex/, opencode/, pi/)
-├── skills/                ← Universal skills (synced from agent-skills repo)
+├── skills/                ← Universal skills (shipped with the framework package)
 ├── tools/                 ← Tool suites (orchestrator, git, quality, prdy, etc.)
 └── memory/                ← Persistent agent memory (preserved across upgrades)
 ```

apps/gateway/package.json

@@ -28,6 +28,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
     "@fastify/helmet": "^13.0.2",
+    "@fastify/static": "^8.3.0",
     "@mariozechner/pi-ai": "^0.65.0",
     "@mariozechner/pi-coding-agent": "^0.65.0",
     "@modelcontextprotocol/sdk": "^1.27.1",

apps/gateway/src/__tests__/cross-user-isolation.test.ts

@@ -190,7 +190,13 @@ beforeEach((ctx) => {
 });
 
 afterAll(async () => {
-  if (!handle) return;
+  // Cleanup only when the fixture actually installed rows. `handle` is set
+  // before the first query (createDb connects lazily), so on an unreachable
+  // database `handle` is truthy while nothing was inserted — cleanup must
+  // honor `dbAvailable` or the skip path fails the file with ECONNREFUSED in
+  // afterAll (caught live by the publish pipeline's no-DATABASE_URL verify
+  // step, pipeline 2486).
+  if (!handle || !dbAvailable) return;
   const db = handle.db;
 
   // Delete in dependency order (FK constraints)

apps/gateway/src/__tests__/hierarchy-route-inventory.test.ts

@@ -0,0 +1,106 @@
+import { RequestMethod, type Type } from '@nestjs/common';
+import { describe, expect, it } from 'vitest';
+import { AppModule } from '../app.module.js';
+import { HierarchyModule } from '../hierarchy/hierarchy.module.js';
+
+/**
+ * Hierarchy route-inventory baseline (contract 1 §6.3(a)).
+ *
+ * M4-1b-i ships the audit event + outbox machinery with NO mutation routes:
+ * the hierarchy command family (controllers + DTOs) lands in M4-1b-ii once
+ * contract 2 merges. This witness enumerates every route the AppModule graph
+ * declares and pins that baseline, so a hierarchy route appearing before its
+ * command-family witnesses exist fails here first. When M4-1b-ii lands, this
+ * baseline is replaced by an exact inventory of the command family.
+ */
+
+interface RouteEntry {
+  method: string;
+  path: string;
+  controller: string;
+}
+
+/** Module-metadata entry: a module class or a DynamicModule-shaped object. */
+type ModuleEntry =
+  | Type<unknown>
+  | { module: Type<unknown>; imports?: unknown[]; controllers?: Type<unknown>[] };
+
+function collectControllers(root: ModuleEntry): Type<unknown>[] {
+  const visited = new Set<unknown>();
+  const controllers: Type<unknown>[] = [];
+  const walk = (entry: ModuleEntry | undefined | null): void => {
+    if (!entry || visited.has(entry)) return;
+    visited.add(entry);
+    const moduleClass = typeof entry === 'function' ? entry : entry.module;
+    // Entries with no resolvable class (forwardRef wrappers, async dynamic
+    // modules) carry no decorator metadata to read here.
+    if (typeof moduleClass !== 'function') return;
+    if (visited.has(moduleClass) && typeof entry !== 'function') return;
+    visited.add(moduleClass);
+    // 'controllers' / 'imports' are the metadata keys the @Module decorator writes.
+    const declared = (Reflect.getMetadata('controllers', moduleClass) ?? []) as Type<unknown>[];
+    controllers.push(...declared);
+    if (typeof entry !== 'function' && entry.controllers) controllers.push(...entry.controllers);
+    const imports = [
+      ...((Reflect.getMetadata('imports', moduleClass) ?? []) as ModuleEntry[]),
+      ...(typeof entry !== 'function' ? ((entry.imports ?? []) as ModuleEntry[]) : []),
+    ];
+    for (const imported of imports) walk(imported);
+  };
+  walk(root);
+  return controllers;
+}
+
+function routesOf(controller: Type<unknown>): RouteEntry[] {
+  // 'path' on the class is the @Controller prefix; 'path'/'method' on a
+  // handler are written by the @Get/@Post/... route decorators.
+  const base = (Reflect.getMetadata('path', controller) ?? '') as string | string[];
+  const bases = Array.isArray(base) ? base : [base];
+  const routes: RouteEntry[] = [];
+  const prototype = controller.prototype as Record<string, unknown>;
+  for (const name of Object.getOwnPropertyNames(prototype)) {
+    if (name === 'constructor') continue;
+    const handler = Object.getOwnPropertyDescriptor(prototype, name)?.value;
+    if (typeof handler !== 'function') continue;
+    const method = Reflect.getMetadata('method', handler) as number | undefined;
+    if (method === undefined) continue;
+    const sub = (Reflect.getMetadata('path', handler) ?? '/') as string;
+    for (const prefix of bases) {
+      const path = `/${prefix}/${sub}`.replace(/\/+/g, '/').replace(/(.)\/$/, '$1');
+      routes.push({
+        method: RequestMethod[method] ?? String(method),
+        path,
+        controller: controller.name,
+      });
+    }
+  }
+  return routes;
+}
+
+describe('hierarchy route-inventory baseline (§6.3(a))', () => {
+  const inventory = collectControllers(AppModule).flatMap(routesOf);
+
+  it('control: the enumeration sees the known route surface', () => {
+    const paths = inventory.map((r) => `${r.method} ${r.path}`);
+    expect(paths).toContain('GET /health');
+    expect(paths).toContain('POST /api/workspaces');
+    expect(paths).toContain('GET /api/teams');
+    expect(inventory.length).toBeGreaterThan(20);
+  });
+
+  it('declares zero hierarchy mutation routes before M4-1b-ii', () => {
+    const hierarchyRoutes = inventory.filter((r) =>
+      /hierarch|compan|estate|platform[-_]?project/i.test(r.path),
+    );
+    expect(
+      hierarchyRoutes,
+      'a hierarchy route landed without replacing the §6.3(a) baseline with a command-family inventory',
+    ).toEqual([]);
+  });
+
+  it('HierarchyModule itself declares no controllers', () => {
+    expect((Reflect.getMetadata('controllers', HierarchyModule) ?? []) as unknown[]).toEqual([]);
+    const hierarchyControllers = collectControllers(HierarchyModule);
+    expect(hierarchyControllers).toEqual([]);
+  });
+});

apps/gateway/src/__tests__/required-security-wiring.test.ts

@@ -0,0 +1,332 @@
+import { type Type } from '@nestjs/common';
+import { Test, type TestingModule } from '@nestjs/testing';
+import type { SlashCommandPayload } from '@mosaicstack/types';
+import { describe, expect, it, vi } from 'vitest';
+import { AgentService, type AgentSession } from '../agent/agent.service.js';
+import { ProviderService } from '../agent/provider.service.js';
+import { AppModule } from '../app.module.js';
+import { CommandAuthorizationService } from '../commands/command-authorization.service.js';
+import { CommandExecutorService } from '../commands/command-executor.service.js';
+import { CommandsModule } from '../commands/commands.module.js';
+import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
+import { PreferencesModule } from '../preferences/preferences.module.js';
+import { SystemOverrideService } from '../preferences/system-override.service.js';
+
+const fakeDb = {
+  $client: { exec: async (): Promise<void> => {} },
+  execute: async (): Promise<{ rows: unknown[] }> => ({ rows: [] }),
+  select: () => ({
+    from: () => ({
+      where: async (): Promise<Array<{ count: number }>> => [{ count: 1 }],
+    }),
+  }),
+  insert: () => ({ values: async (): Promise<void> => {} }),
+};
+
+const fakeProviderService = {
+  onModuleInit: async (): Promise<void> => {},
+  onModuleDestroy: (): void => {},
+  getRegistry: () => ({ getAvailable: () => [], getAll: () => [], find: () => undefined }),
+  getDefaultModel: () => undefined,
+  listAvailableModels: () => [],
+  listProviders: () => [],
+  getAdapter: () => undefined,
+  getProvidersHealth: () => [],
+};
+
+function compileRealAppGraph(): Promise<TestingModule> {
+  return Test.createTestingModule({ imports: [AppModule] })
+    .overrideProvider('DB_HANDLE')
+    .useValue({ db: fakeDb, close: async (): Promise<void> => {} })
+    .overrideProvider('DB')
+    .useValue(fakeDb)
+    .overrideProvider('STORAGE_ADAPTER')
+    .useValue({
+      name: 'required-security-wiring-test',
+      migrate: async (): Promise<void> => {},
+      close: async (): Promise<void> => {},
+    })
+    .overrideProvider('AUTH')
+    .useValue({})
+    .overrideProvider('BRAIN')
+    .useValue({ conversations: {}, agents: {} })
+    .overrideProvider('LOG_SERVICE')
+    .useValue({})
+    .overrideProvider('MEMORY')
+    .useValue({})
+    .overrideProvider('MEMORY_ADAPTER')
+    .useValue({})
+    .overrideProvider(ProviderService)
+    .useValue(fakeProviderService)
+    .compile();
+}
+
+function providerToken(provider: unknown): unknown {
+  return typeof provider === 'function' ? provider : (provider as { provide?: unknown })?.provide;
+}
+
+interface MaskingConsumer {
+  moduleType: Type<unknown>;
+  token: Type<unknown>;
+  useValue: object;
+}
+
+async function compileWithoutProvider(
+  moduleType: Type<unknown>,
+  missingToken: Type<unknown>,
+  maskingConsumer: MaskingConsumer,
+): Promise<{ error: unknown; moduleRef: TestingModule | undefined }> {
+  const touchedModules = new Set([moduleType, maskingConsumer.moduleType]);
+  const originals = Array.from(touchedModules, (touchedModule: Type<unknown>) => ({
+    moduleType: touchedModule,
+    providers: (Reflect.getMetadata('providers', touchedModule) ?? []) as unknown[],
+    exports: (Reflect.getMetadata('exports', touchedModule) ?? []) as unknown[],
+  }));
+
+  for (const original of originals) {
+    const providers = original.providers.flatMap((provider: unknown): unknown[] => {
+      const token = providerToken(provider);
+      if (original.moduleType === moduleType && token === missingToken) return [];
+      if (original.moduleType === maskingConsumer.moduleType && token === maskingConsumer.token) {
+        return [{ provide: maskingConsumer.token, useValue: maskingConsumer.useValue }];
+      }
+      return [provider];
+    });
+    const exports = original.exports.filter(
+      (exported: unknown): boolean =>
+        original.moduleType !== moduleType || providerToken(exported) !== missingToken,
+    );
+    Reflect.defineMetadata('providers', providers, original.moduleType);
+    Reflect.defineMetadata('exports', exports, original.moduleType);
+  }
+
+  let moduleRef: TestingModule | undefined;
+  let error: unknown;
+  try {
+    moduleRef = await compileRealAppGraph();
+  } catch (caught: unknown) {
+    error = caught;
+  } finally {
+    for (const original of originals) {
+      Reflect.defineMetadata('providers', original.providers, original.moduleType);
+      Reflect.defineMetadata('exports', original.exports, original.moduleType);
+    }
+  }
+  return { error, moduleRef };
+}
+
+async function closeIfCompiled(moduleRef: TestingModule | undefined): Promise<void> {
+  if (moduleRef) await moduleRef.close();
+}
+
+describe('required security wiring — real AppModule startup refusal', () => {
+  it('FL-01 positive control: the real graph compiles when CommandAuthorizationService is bound', async () => {
+    const moduleRef = await compileRealAppGraph();
+    try {
+      expect(moduleRef.get(CommandAuthorizationService, { strict: false })).toBeInstanceOf(
+        CommandAuthorizationService,
+      );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('FL-01 negative control: absence read as permission is refused at module compilation', async () => {
+    const { error, moduleRef } = await compileWithoutProvider(
+      CommandsModule,
+      CommandAuthorizationService,
+      {
+        moduleType: CommandsModule,
+        token: CommandRuntimeApprovalVerifier,
+        useValue: {},
+      },
+    );
+    await closeIfCompiled(moduleRef);
+
+    expect(
+      error,
+      'absence read as permission: AppModule compilation accepted a missing CommandAuthorizationService binding',
+    ).toBeInstanceOf(Error);
+    if (!(error instanceof Error)) return;
+    expect(error.message).toContain('CommandExecutorService');
+    expect(error.message).toContain('CommandAuthorizationService');
+  });
+
+  it('FL-11 positive control: the real graph compiles when SystemOverrideService is bound', async () => {
+    const moduleRef = await compileRealAppGraph();
+    try {
+      expect(moduleRef.get(SystemOverrideService, { strict: false })).toBeInstanceOf(
+        SystemOverrideService,
+      );
+    } finally {
+      await moduleRef.close();
+    }
+  });
+
+  it('FL-11 negative control: absence read as permission is refused at module compilation', async () => {
+    const { error, moduleRef } = await compileWithoutProvider(
+      PreferencesModule,
+      SystemOverrideService,
+      {
+        moduleType: CommandsModule,
+        token: CommandExecutorService,
+        useValue: {},
+      },
+    );
+    await closeIfCompiled(moduleRef);
+
+    expect(
+      error,
+      'absence read as permission: AppModule compilation accepted a missing SystemOverrideService binding',
+    ).toBeInstanceOf(Error);
+    if (!(error instanceof Error)) return;
+    expect(error.message).toContain('AgentService');
+    expect(error.message).toContain('SystemOverrideService');
+  });
+});
+
+const actorScope = { userId: 'security-user', tenantId: 'security-tenant' };
+const conversationId = 'security-conversation';
+
+function directExecutorWithoutAuthorization(systemOverrideSet: ReturnType<typeof vi.fn>) {
+  const registry = {
+    getManifest: vi.fn(() => ({
+      version: 1,
+      commands: [
+        {
+          name: 'system',
+          aliases: [],
+          description: 'Set instruction authority',
+          scope: 'agent' as const,
+          execution: 'socket' as const,
+          available: true,
+        },
+      ],
+      skills: [],
+    })),
+  };
+  return new CommandExecutorService(
+    registry as never,
+    { getSession: vi.fn() } as never,
+    { set: systemOverrideSet, clear: vi.fn() } as never,
+    { collect: vi.fn() } as never,
+    null,
+    { agents: {} } as never,
+    null,
+    null,
+    { getServerStatuses: vi.fn(() => []), getToolDefinitions: vi.fn(() => []) } as never,
+    undefined as never,
+  );
+}
+
+function directAgentWithoutSystemOverride(piPrompt: ReturnType<typeof vi.fn>): {
+  service: AgentService;
+  session: AgentSession;
+} {
+  const service = new AgentService(
+    {
+      getDefaultModel: vi.fn(() => null),
+      getRegistry: vi.fn(() => ({})),
+      findModel: vi.fn(),
+      listAvailableModels: vi.fn(() => []),
+    } as never,
+    {} as never,
+    {} as never,
+    { available: false } as never,
+    {} as never,
+    { getToolDefinitions: vi.fn(() => []) } as never,
+    { loadForSession: vi.fn(async () => ({ metaTools: [], promptAdditions: [] })) } as never,
+    undefined as never,
+    null,
+    { collect: vi.fn().mockResolvedValue(undefined) } as never,
+    null,
+  );
+  const session = {
+    id: conversationId,
+    provider: 'test-provider',
+    modelId: 'test-model',
+    piSession: { prompt: piPrompt },
+    listeners: new Set(),
+    unsubscribe: vi.fn(),
+    createdAt: Date.now(),
+    promptCount: 0,
+    channels: new Set(),
+    skillPromptAdditions: [],
+    sandboxDir: process.cwd(),
+    allowedTools: null,
+    userId: actorScope.userId,
+    tenantId: actorScope.tenantId,
+    metrics: {
+      tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+      modelSwitches: 0,
+      messageCount: 0,
+      lastActivityAt: new Date(0).toISOString(),
+    },
+  } as unknown as AgentSession;
+  const internals = service as unknown as { sessions: Map<string, AgentSession> };
+  internals.sessions.set(conversationId, session);
+  return { service, session };
+}
+
+describe('required security wiring — malformed direct absence has zero effects', () => {
+  it('FL-01 refuses command execution before any command effect when authorization is absent', async () => {
+    const systemOverrideSet = vi.fn().mockResolvedValue(undefined);
+    const executor = directExecutorWithoutAuthorization(systemOverrideSet);
+    const payload: SlashCommandPayload = {
+      command: 'system',
+      args: 'authority that must not be stored',
+      conversationId,
+    };
+    let error: unknown;
+
+    try {
+      await executor.execute(payload, actorScope);
+    } catch (caught: unknown) {
+      error = caught;
+    }
+
+    expect
+      .soft(
+        error,
+        'absence read as permission: direct executor accepted missing command authorization',
+      )
+      .toBeInstanceOf(Error);
+    expect
+      .soft(
+        systemOverrideSet,
+        'absence read as permission: command effect occurred without command authorization',
+      )
+      .not.toHaveBeenCalled();
+  });
+
+  it('FL-11 refuses prompt execution before any provider or session effect when system override authority is absent', async () => {
+    const piPrompt = vi.fn().mockResolvedValue(undefined);
+    const { service, session } = directAgentWithoutSystemOverride(piPrompt);
+    let error: unknown;
+
+    try {
+      await service.prompt(conversationId, 'must not reach provider', actorScope);
+    } catch (caught: unknown) {
+      error = caught;
+    }
+
+    expect
+      .soft(
+        error,
+        'absence read as permission: direct session accepted missing system override authority',
+      )
+      .toBeInstanceOf(Error);
+    expect
+      .soft(
+        piPrompt,
+        'absence read as permission: provider prompt occurred without system override authority',
+      )
+      .not.toHaveBeenCalled();
+    expect
+      .soft(
+        session.promptCount,
+        'absence read as permission: session state changed without system override authority',
+      )
+      .toBe(0);
+  });
+});

apps/gateway/src/agent/__tests__/agent-service-ownership.test.ts

@@ -26,7 +26,7 @@ function makeService(operatorMemory: unknown = null): AgentService {
     {} as never,
     { getToolDefinitions: vi.fn(() => []) } as never,
     { loadForSession: vi.fn(async () => ({ metaTools: [], promptAdditions: [] })) } as never,
-    null,
+    { get: vi.fn().mockResolvedValue(null), renew: vi.fn().mockResolvedValue(undefined) } as never,
     null,
     { collect: vi.fn().mockResolvedValue(undefined) } as never,
     operatorMemory as never,

apps/gateway/src/agent/agent.service.ts

@@ -132,9 +132,8 @@ export class AgentService implements OnModuleDestroy {
     @Inject(CoordService) private readonly coordService: CoordService,
     @Inject(McpClientService) private readonly mcpClientService: McpClientService,
     @Inject(SkillLoaderService) private readonly skillLoaderService: SkillLoaderService,
-    @Optional()
     @Inject(SystemOverrideService)
-    private readonly systemOverride: SystemOverrideService | null,
+    private readonly systemOverride: SystemOverrideService,
     @Optional()
     @Inject(PreferencesService)
     private readonly preferencesService: PreferencesService | null,
@@ -709,23 +708,22 @@ export class AgentService implements OnModuleDestroy {
       throw new Error(`No agent session found: ${sessionId}`);
     }
     this.assertSessionScope(session, scope);
-    session.promptCount += 1;
 
     // Channel attachments are untrusted URI references. Preserve exact,
     // authenticated metadata for the agent without treating it as authority.
     const attachmentContext = this.attachmentContext(attachments);
 
-    // Prepend session-scoped system override if present (renew TTL on each turn)
+    // Prepend session-scoped system override if present (renew TTL on each turn).
+    // Required instruction-authority wiring is consulted before session/provider effects.
     let effectiveMessage = `${message}${attachmentContext}`;
-    if (this.systemOverride) {
-      const override = await this.systemOverride.get(sessionId, scope);
-      if (override) {
-        effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
-        await this.systemOverride.renew(sessionId, scope);
-        this.logger.debug(`Applied system override for session ${sessionId}`);
-      }
+    const override = await this.systemOverride.get(sessionId, scope);
+    if (override) {
+      effectiveMessage = `[System Override]\n${override}\n\n${effectiveMessage}`;
+      await this.systemOverride.renew(sessionId, scope);
+      this.logger.debug(`Applied system override for session ${sessionId}`);
     }
 
+    session.promptCount += 1;
     try {
       await session.piSession.prompt(effectiveMessage);
     } catch (err) {

apps/gateway/src/app.module.ts

@@ -24,6 +24,7 @@ import { GCModule } from './gc/gc.module.js';
 import { HarnessModule } from './harness/harness.module.js';
 import { ReloadModule } from './reload/reload.module.js';
 import { WorkspaceModule } from './workspace/workspace.module.js';
+import { HierarchyModule } from './hierarchy/hierarchy.module.js';
 import { QueueModule } from './queue/queue.module.js';
 import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
@@ -65,6 +66,7 @@ const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'feder
     QueueModule,
     ReloadModule,
     WorkspaceModule,
+    HierarchyModule,
     ...(federationEnabled ? [FederationModule] : []),
   ],
   controllers: [HealthController],

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -80,6 +80,10 @@ const mockMcpClient = {
   getToolDefinitions: vi.fn(() => []),
 };
 
+const allowAuthorization = {
+  authorize: vi.fn().mockResolvedValue({ allowed: true }),
+};
+
 function buildService(
   redis: typeof mockRedis | null = mockRedis,
   mcpClient: {
@@ -98,6 +102,7 @@ function buildService(
     null,
     mockChatGateway as never,
     mcpClient as never,
+    allowAuthorization as never,
   );
 }
 

apps/gateway/src/commands/command-executor.service.ts

@@ -35,9 +35,8 @@ export class CommandExecutorService {
     @Inject(forwardRef(() => ChatGateway))
     private readonly chatGateway: ChatGateway | null,
     @Inject(McpClientService) private readonly mcpClient: McpClientService,
-    @Optional()
     @Inject(CommandAuthorizationService)
-    private readonly authorization: CommandAuthorizationService | null = null,
+    private readonly authorization: CommandAuthorizationService,
   ) {}
 
   async execute(
@@ -57,13 +56,13 @@ export class CommandExecutorService {
       };
     }
 
-    const authorization = await this.authorization?.authorize(
+    const authorization = await this.authorization.authorize(
       def,
       payload,
       userId,
       payload.approvalId,
     );
-    if (authorization && !authorization.allowed) {
+    if (!authorization.allowed) {
       return { command, conversationId, success: false, message: authorization.reason };
     }
 
@@ -171,7 +170,7 @@ export class CommandExecutorService {
     const def = this.registry
       .getManifest()
       .commands.find((command) => command.name === payload.command);
-    if (!def || !this.authorization) return null;
+    if (!def) return null;
     return this.authorization.createApproval(def, payload, scope.userId);
   }
 

apps/gateway/src/commands/commands.integration.spec.ts

@@ -55,6 +55,10 @@ const mockMcpClient = {
   reconnectServer: vi.fn().mockResolvedValue(undefined),
 };
 
+const allowAuthorization = {
+  authorize: vi.fn().mockResolvedValue({ allowed: true }),
+};
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function buildRegistry(): CommandRegistryService {
@@ -74,6 +78,7 @@ function buildExecutor(registry: CommandRegistryService): CommandExecutorService
     null, // reloadService (optional)
     null, // chatGateway (optional)
     mockMcpClient as never,
+    allowAuthorization as never,
   );
 }
 

apps/gateway/src/database/database.module.1392.spec.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// The module under test imports @mosaicstack/db at module scope; we replace only the
+// pieces DatabaseModule uses (partial mock — the real module also exports the
+// schema the storage adapter's import chain needs) so the test pins the #1392
+// contract (refuse to start on an incomplete schema) without a live database.
+vi.mock('@mosaicstack/db', async (importOriginal) => {
+  const actual: object = await importOriginal();
+  return {
+    ...actual,
+    createDb: vi.fn(),
+    createPgliteDb: vi.fn(),
+    getMigrationStatus: vi.fn(),
+    runPgliteMigrations: vi.fn(),
+  };
+});
+
+import { DatabaseModule } from './database.module.js';
+import { getMigrationStatus } from '@mosaicstack/db';
+import type { DbHandle } from '@mosaicstack/db';
+import type { StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
+
+function makeModule(storageType: 'postgres' | 'pglite', tier: string) {
+  const storageAdapter = {
+    name: storageType,
+    migrate: vi.fn(),
+    close: vi.fn(),
+  } as unknown as StorageAdapter;
+  const handle = { close: vi.fn() } as unknown as DbHandle;
+  const config = {
+    tier,
+    storage: { type: storageType, url: 'postgresql://x' },
+  } as unknown as MosaicConfig;
+  return {
+    mod: new DatabaseModule(handle, storageAdapter, config),
+    storageAdapter,
+  };
+}
+
+describe('DatabaseModule.onModuleInit — #1392 schema verification', () => {
+  it('refuses to start when the postgres schema is incomplete', async () => {
+    const { mod, storageAdapter } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 15,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: false,
+    });
+    await expect(mod.onModuleInit()).rejects.toThrow('Database schema incomplete: 15/17');
+    expect(storageAdapter.migrate).toHaveBeenCalled(); // migrations attempted first
+  });
+
+  it('starts normally when the schema is complete', async () => {
+    const { mod } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 17,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: true,
+    });
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+  });
+
+  it('does not verify postgres status for the local tier (PGlite migrates itself)', async () => {
+    const { mod } = makeModule('pglite', 'local');
+    vi.mocked(getMigrationStatus).mockClear();
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+    expect(getMigrationStatus).not.toHaveBeenCalled();
+  });
+});

apps/gateway/src/database/database.module.ts

@@ -12,6 +12,7 @@ import {
 import {
   createDb,
   createPgliteDb,
+  getMigrationStatus,
   runPgliteMigrations,
   type Db,
   type DbHandle,
@@ -74,6 +75,11 @@ export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
   // the same DATABASE_URL, so a single call covers both the gateway DB and
   // the storage tables. We deliberately do NOT call runMigrations() here to
   // avoid opening a second short-lived connection and doubling startup cost.
+  //
+  // #1392: we DO verify afterwards (getMigrationStatus opens one short-lived
+  // connection) and refuse to start on an incomplete schema. A gateway that
+  // boots "healthy" on an empty or partial database is precisely the failure
+  // that shipped in the T63 batch: silent at startup, catastrophic later.
   async onModuleInit(): Promise<void> {
     if (this.config.tier === 'local') {
       this.logger.log('Applying PGlite schema migrations...');
@@ -81,6 +87,24 @@ export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
     }
     this.logger.log(`Initializing storage adapter (${this.storageAdapter.name})...`);
     await this.storageAdapter.migrate();
+
+    if (this.config.storage.type === 'postgres') {
+      const status = await getMigrationStatus(this.config.storage.url);
+      if (!status.complete) {
+        this.logger.error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied ` +
+            `(last expected: ${status.expectedLastTag}). ` +
+            'Refusing to start on a partial schema — see issues #1392/#1402. ' +
+            "Remediation: re-run 'mosaic gateway install' (it now verifies), or apply migrations manually.",
+        );
+        throw new Error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied`,
+        );
+      }
+      this.logger.log(
+        `Database schema verified: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied.`,
+      );
+    }
   }
 
   async onApplicationShutdown(): Promise<void> {

apps/gateway/src/federation/__tests__/enrollment.service.spec.ts

@@ -245,9 +245,21 @@ describe('EnrollmentService.createToken', () => {
     const after = Date.now();
 
     const expiresMs = new Date(result.expiresAt).getTime();
-    // Should be at most 900s from now
-    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + 100);
+
+    // The property under test is CLAMPING: a 9999s request must come back as 900s.
+    // The gap between clamped and unclamped is 9_099_000 ms, so the tolerance below
+    // only has to exceed CI scheduling jitter — it does not need to be tight to keep
+    // the assertion discriminating. A 5s allowance consumes 0.05% of that margin and
+    // an unclamped result still misses by three orders of magnitude.
+    //
+    // It was 100ms and failed on a loaded agent at 900_106 — 6ms over (#1090). A
+    // wall-clock budget sized to a fast machine is a flake, not a tighter test.
+    const CI_JITTER_MS = 5_000;
+    expect(expiresMs - before).toBeLessThanOrEqual(900_000 + CI_JITTER_MS);
     expect(expiresMs - after).toBeGreaterThanOrEqual(0);
+    // Explicitly pin the clamp itself, independent of any timing allowance:
+    // unclamped (9999s) would exceed this by ~9_099_000 ms.
+    expect(expiresMs - before).toBeLessThan(1_000_000);
   });
 });
 

apps/gateway/src/hierarchy/hierarchy-audit.integration.test.ts

@@ -0,0 +1,247 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { Test, type TestingModule } from '@nestjs/testing';
+import {
+  companies,
+  createPgliteDb,
+  eq,
+  estates,
+  hierarchyAuditEvents,
+  hierarchyOutbox,
+  platformProjects,
+  runPgliteMigrations,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+import {
+  HierarchyAuditIdempotencyConflictError,
+  HierarchyAuditRepository,
+  HierarchyNodeNotFoundError,
+  type AppendHierarchyEventInput,
+} from './hierarchy-audit.repository.js';
+
+/**
+ * Repository-level §6.4 witnesses for the hierarchy audit machinery
+ * (contract 1 §5.2, REQ-AUD-001): same-transaction atomicity of state +
+ * event + outbox, rollback leaving no residue, idempotent replay, snapshot
+ * parent chains, events surviving target deletion, per-target ordering, and
+ * the outbox claim/complete/release CAS. The schema-level constraints are
+ * witnessed in packages/db/src/hierarchy-audit.witness.test.ts.
+ */
+describe('hierarchy audit repository integration', (): void => {
+  let dataDir: string;
+  let handle: DbHandle;
+  let moduleRef: TestingModule;
+  let repo: HierarchyAuditRepository;
+
+  const input = (
+    overrides: Partial<AppendHierarchyEventInput> = {},
+  ): AppendHierarchyEventInput => ({
+    actorId: 'user-actor',
+    verb: 'create',
+    targetKind: 'company',
+    targetId: randomUUID(),
+    targetSnapshot: { id: 'x', slug: 'x', name: 'x', parentChain: [] },
+    correlationId: 'corr-1',
+    idempotencyKey: `key-${randomUUID()}`,
+    ...overrides,
+  });
+
+  beforeAll(async (): Promise<void> => {
+    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-hierarchy-audit-'));
+    handle = createPgliteDb(dataDir);
+    await runPgliteMigrations(handle);
+    moduleRef = await Test.createTestingModule({
+      providers: [HierarchyAuditRepository, { provide: DB, useValue: handle.db }],
+    }).compile();
+    repo = moduleRef.get(HierarchyAuditRepository);
+  });
+
+  afterAll(async (): Promise<void> => {
+    await moduleRef.close();
+    await handle.close();
+    await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('commits state, event, and outbox record atomically in one transaction', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Atomic Co', slug: 'atomic-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      const result = await repo.append(tx, {
+        ...input({ targetId: companyId, idempotencyKey: key }),
+        targetSnapshot: { ...snapshot },
+      });
+      expect(result.replayed).toBe(false);
+      expect(result.event.idempotencyKey).toBe(key);
+    });
+    const events = await handle.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.idempotencyKey, key));
+    expect(events).toHaveLength(1);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, events[0]!.id));
+    expect(outbox).toHaveLength(1);
+    expect(outbox[0]).toMatchObject({
+      status: 'pending',
+      idempotencyKey: key,
+      correlationId: 'corr-1',
+    });
+  });
+
+  it('a rolled-back transaction leaves no state, no event, and no outbox record', async () => {
+    const companyId = randomUUID();
+    const key = `key-${randomUUID()}`;
+    await expect(
+      handle.db.transaction(async (tx) => {
+        await tx.insert(companies).values({ id: companyId, name: 'Doomed Co', slug: 'doomed-co' });
+        await repo.append(tx, input({ targetId: companyId, idempotencyKey: key }));
+        throw new Error('deliberate rollback');
+      }),
+    ).rejects.toThrow('deliberate rollback');
+    const [companyRows, eventRows, outboxRows] = await Promise.all([
+      handle.db.select().from(companies).where(eq(companies.id, companyId)),
+      handle.db
+        .select()
+        .from(hierarchyAuditEvents)
+        .where(eq(hierarchyAuditEvents.idempotencyKey, key)),
+      handle.db.select().from(hierarchyOutbox).where(eq(hierarchyOutbox.idempotencyKey, key)),
+    ]);
+    expect(companyRows).toHaveLength(0);
+    expect(eventRows).toHaveLength(0);
+    expect(outboxRows).toHaveLength(0);
+  });
+
+  it('replays a duplicate idempotency key without inserting a second event or outbox record', async () => {
+    const first = input();
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    expect(replay.replayed).toBe(true);
+    expect(replay.event.id).toBe(original.event.id);
+    const outbox = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.eventId, original.event.id));
+    expect(outbox).toHaveLength(1);
+  });
+
+  it('throws on a duplicate idempotency key carrying different event content', async () => {
+    const first = input();
+    await handle.db.transaction(async (tx) => repo.append(tx, first));
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, verb: 'rename', targetId: randomUUID() }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('throws on a duplicate idempotency key whose transfer destination differs', async () => {
+    const from = { kind: 'company' as const, id: randomUUID(), slug: 'src-co' };
+    const to = { kind: 'company' as const, id: randomUUID(), slug: 'dst-co' };
+    const first = input({
+      verb: 'transfer',
+      targetKind: 'estate',
+      transferFrom: from,
+      transferTo: to,
+    });
+    const original = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(original.replayed).toBe(false);
+    // Identical retry replays; a retry re-routed to a different destination must conflict.
+    const replay = await handle.db.transaction(async (tx) => repo.append(tx, first));
+    expect(replay.replayed).toBe(true);
+    await expect(
+      handle.db.transaction(async (tx) =>
+        repo.append(tx, { ...first, transferTo: { ...to, id: randomUUID() } }),
+      ),
+    ).rejects.toThrow(HierarchyAuditIdempotencyConflictError);
+  });
+
+  it('builds root-first parent chains and rejects unknown nodes', async () => {
+    const companyId = randomUUID();
+    const estateId = randomUUID();
+    const projectId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Chain Co', slug: 'chain-co' });
+      await tx
+        .insert(estates)
+        .values({ id: estateId, name: 'Chain Estate', slug: 'chain-estate', companyId });
+      await tx
+        .insert(platformProjects)
+        .values({ id: projectId, name: 'Chain Project', slug: 'chain-project', estateId });
+    });
+    const snapshot = await repo.snapshot(handle.db, 'platform_project', projectId);
+    expect(snapshot).toMatchObject({ id: projectId, slug: 'chain-project', name: 'Chain Project' });
+    expect(snapshot.parentChain).toEqual([
+      { kind: 'company', id: companyId, slug: 'chain-co' },
+      { kind: 'estate', id: estateId, slug: 'chain-estate' },
+    ]);
+    await expect(repo.snapshot(handle.db, 'estate', randomUUID())).rejects.toThrow(
+      HierarchyNodeNotFoundError,
+    );
+  });
+
+  it('keeps events readable, in per-target seq order, after the target row is deleted', async () => {
+    const companyId = randomUUID();
+    await handle.db.transaction(async (tx) => {
+      await tx.insert(companies).values({ id: companyId, name: 'Mortal Co', slug: 'mortal-co' });
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, input({ targetId: companyId, targetSnapshot: { ...snapshot } }));
+    });
+    await handle.db.transaction(async (tx) => {
+      const snapshot = await repo.snapshot(tx, 'company', companyId);
+      await repo.append(tx, {
+        ...input({ verb: 'delete', targetId: companyId }),
+        targetSnapshot: { ...snapshot },
+      });
+      await tx.delete(companies).where(eq(companies.id, companyId));
+    });
+    const events = await repo.eventsForTarget(companyId);
+    expect(events.map((e) => e.verb)).toEqual(['create', 'delete']);
+    expect(events[1]!.seq).toBeGreaterThan(events[0]!.seq);
+    expect((events[1]!.targetSnapshot as { id: string }).id).toBe(companyId);
+  });
+
+  it('claims the oldest pending outbox record exactly once, completes and releases by CAS', async () => {
+    // Drain records left pending by earlier cases so ordering is deterministic.
+    for (;;) {
+      const drained = await repo.claimPendingOutbox();
+      if (!drained) break;
+      await repo.completeOutbox(drained.id);
+    }
+    const older = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+    const newer = await handle.db.transaction(async (tx) => repo.append(tx, input()));
+
+    const claimed = await repo.claimPendingOutbox();
+    expect(claimed).not.toBeNull();
+    expect(claimed!.eventId).toBe(older.event.id);
+    expect(claimed!.status).toBe('processing');
+
+    // Delivery fails: release returns it to pending and it is claimable again.
+    await repo.releaseOutbox(claimed!.id);
+    const reclaimed = await repo.claimPendingOutbox();
+    expect(reclaimed!.id).toBe(claimed!.id);
+
+    await repo.completeOutbox(reclaimed!.id);
+    const done = await handle.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.id, reclaimed!.id));
+    expect(done[0]!.status).toBe('delivered');
+    expect(done[0]!.deliveredAt).not.toBeNull();
+    // completeOutbox is CAS-guarded on 'processing': completing again is a no-op.
+    await repo.completeOutbox(reclaimed!.id);
+
+    const second = await repo.claimPendingOutbox();
+    expect(second!.eventId).toBe(newer.event.id);
+    await repo.completeOutbox(second!.id);
+    expect(await repo.claimPendingOutbox()).toBeNull();
+  });
+});

apps/gateway/src/hierarchy/hierarchy-audit.repository.ts

@@ -0,0 +1,274 @@
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  asc,
+  companies,
+  eq,
+  estates,
+  hierarchyAuditEvents,
+  hierarchyOutbox,
+  platformProjects,
+  type Db,
+  type HIERARCHY_AUDIT_TARGET_KINDS,
+  type HIERARCHY_AUDIT_VERBS,
+} from '@mosaicstack/db';
+import { DB } from '../database/database.module.js';
+
+/**
+ * Hierarchy audit event + outbox machinery (contract 1 §5.2).
+ *
+ * Every hierarchy mutation writes its semantic audit event AND the event's
+ * outbox record on the caller's transaction, so state, event, and outbox
+ * commit or roll back together. Events reference their target by an
+ * immutable snapshot (id, slug, parent chain at event time), never by a
+ * foreign key into the class tables — append-only events survive the
+ * deletion of their target. This module exposes no update or delete path
+ * for events: append-only is a property of the code surface, witnessed by
+ * the integration tests.
+ *
+ * This is NOT a class-table writer: it touches only the audit/outbox
+ * tables, so it does not appear on the writer-coverage allowlist. The
+ * hierarchy command repositories (M4-1b-ii) are the allowlisted writers and
+ * call into this on their own transactions.
+ */
+
+export type HierarchyAuditVerb = (typeof HIERARCHY_AUDIT_VERBS)[number];
+export type HierarchyTargetKind = (typeof HIERARCHY_AUDIT_TARGET_KINDS)[number];
+export type HierarchyNodeKind = Exclude<HierarchyTargetKind, 'grant'>;
+
+export interface ParentChainEntry {
+  readonly kind: HierarchyNodeKind;
+  readonly id: string;
+  readonly slug: string;
+}
+
+/** Immutable node snapshot at event time; parentChain is root-first. */
+export interface HierarchyNodeSnapshot {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+  readonly parentChain: readonly ParentChainEntry[];
+}
+
+export interface AppendHierarchyEventInput {
+  readonly actorId: string;
+  readonly verb: HierarchyAuditVerb;
+  readonly targetKind: HierarchyTargetKind;
+  readonly targetId: string;
+  /** Node events: HierarchyNodeSnapshot. Grant events: subject/target/role snapshot (contract 2 §4.4). */
+  readonly targetSnapshot: Record<string, unknown>;
+  /** Present exactly on transfers (CHECK-enforced): source/destination parent { kind, id, slug }. */
+  readonly transferFrom?: ParentChainEntry;
+  readonly transferTo?: ParentChainEntry;
+  readonly correlationId: string;
+  /** Prior event in the causal chain (e.g. the delete event causing cascaded grant_revoke events). */
+  readonly causationId?: string;
+  readonly idempotencyKey: string;
+}
+
+export type HierarchyAuditEventRow = typeof hierarchyAuditEvents.$inferSelect;
+export type HierarchyOutboxRow = typeof hierarchyOutbox.$inferSelect;
+
+export interface AppendHierarchyEventResult {
+  readonly event: HierarchyAuditEventRow;
+  /** True when the idempotency key had already committed an identical event (REQ-AUD-001 duplicate suppression). */
+  readonly replayed: boolean;
+}
+
+type Tx = Pick<Db, 'insert' | 'select'>;
+
+export class HierarchyAuditIdempotencyConflictError extends Error {
+  constructor(idempotencyKey: string) {
+    super(
+      `hierarchy audit idempotency key ${idempotencyKey} already exists with different event content`,
+    );
+    this.name = 'HierarchyAuditIdempotencyConflictError';
+  }
+}
+
+export class HierarchyNodeNotFoundError extends Error {
+  constructor(kind: HierarchyNodeKind, id: string) {
+    super(`hierarchy node not found: ${kind} ${id}`);
+    this.name = 'HierarchyNodeNotFoundError';
+  }
+}
+
+/**
+ * Append one audit event and its outbox record on the caller's transaction.
+ * A duplicate idempotency key with identical semantic content returns the
+ * prior event (replayed: true) without inserting anything; a duplicate key
+ * with different content throws.
+ */
+export async function appendHierarchyEvent(
+  tx: Tx,
+  input: AppendHierarchyEventInput,
+): Promise<AppendHierarchyEventResult> {
+  const inserted = await tx
+    .insert(hierarchyAuditEvents)
+    .values({
+      actorId: input.actorId,
+      verb: input.verb,
+      targetKind: input.targetKind,
+      targetId: input.targetId,
+      targetSnapshot: input.targetSnapshot,
+      transferFrom: input.transferFrom ?? null,
+      transferTo: input.transferTo ?? null,
+      correlationId: input.correlationId,
+      causationId: input.causationId ?? null,
+      idempotencyKey: input.idempotencyKey,
+    })
+    .onConflictDoNothing()
+    .returning();
+  const event = inserted[0];
+  if (event) {
+    await tx.insert(hierarchyOutbox).values({
+      eventId: event.id,
+      idempotencyKey: input.idempotencyKey,
+      correlationId: input.correlationId,
+    });
+    return { event, replayed: false };
+  }
+
+  const prior = await tx
+    .select()
+    .from(hierarchyAuditEvents)
+    .where(eq(hierarchyAuditEvents.idempotencyKey, input.idempotencyKey))
+    .limit(1);
+  const existing = prior[0];
+  if (!existing || !sameEvent(existing, input)) {
+    throw new HierarchyAuditIdempotencyConflictError(input.idempotencyKey);
+  }
+  // Event and outbox committed atomically the first time, so the outbox
+  // record already exists; a replay inserts nothing.
+  return { event: existing, replayed: true };
+}
+
+/** Key-order-independent serialization: jsonb does not preserve key order. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    const body = Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+      .join(',');
+    return `{${body}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sameEvent(row: HierarchyAuditEventRow, input: AppendHierarchyEventInput): boolean {
+  return (
+    row.actorId === input.actorId &&
+    row.verb === input.verb &&
+    row.targetKind === input.targetKind &&
+    row.targetId === input.targetId &&
+    row.correlationId === input.correlationId &&
+    (row.causationId ?? null) === (input.causationId ?? null) &&
+    canonicalJson(row.targetSnapshot) === canonicalJson(input.targetSnapshot) &&
+    // Transfer source/destination are semantic content (§5.2): a retry with a
+    // different destination must conflict, never silently replay.
+    canonicalJson(row.transferFrom ?? null) === canonicalJson(input.transferFrom ?? null) &&
+    canonicalJson(row.transferTo ?? null) === canonicalJson(input.transferTo ?? null)
+  );
+}
+
+/**
+ * Build the immutable snapshot for a node: its row plus the parent chain up
+ * to the company root, root-first, read on the caller's transaction so the
+ * snapshot is consistent with the mutation it audits.
+ */
+export async function buildNodeSnapshot(
+  tx: Tx,
+  kind: HierarchyNodeKind,
+  id: string,
+): Promise<HierarchyNodeSnapshot> {
+  if (kind === 'company') {
+    const rows = await tx.select().from(companies).where(eq(companies.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    return { id: row.id, slug: row.slug, name: row.name, parentChain: [] };
+  }
+  if (kind === 'estate') {
+    const rows = await tx.select().from(estates).where(eq(estates.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+    const parent = await buildNodeSnapshot(tx, 'company', row.companyId);
+    return {
+      id: row.id,
+      slug: row.slug,
+      name: row.name,
+      parentChain: [...parent.parentChain, { kind: 'company', id: parent.id, slug: parent.slug }],
+    };
+  }
+  const rows = await tx.select().from(platformProjects).where(eq(platformProjects.id, id)).limit(1);
+  const row = rows[0];
+  if (!row) throw new HierarchyNodeNotFoundError(kind, id);
+  const parent = await buildNodeSnapshot(tx, 'estate', row.estateId);
+  return {
+    id: row.id,
+    slug: row.slug,
+    name: row.name,
+    parentChain: [...parent.parentChain, { kind: 'estate', id: parent.id, slug: parent.slug }],
+  };
+}
+
+@Injectable()
+export class HierarchyAuditRepository {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  /** Compose an event+outbox append into a caller-owned transaction. */
+  append(tx: Tx, input: AppendHierarchyEventInput): Promise<AppendHierarchyEventResult> {
+    return appendHierarchyEvent(tx, input);
+  }
+
+  snapshot(tx: Tx, kind: HierarchyNodeKind, id: string): Promise<HierarchyNodeSnapshot> {
+    return buildNodeSnapshot(tx, kind, id);
+  }
+
+  /** Per-target ordered event history (REQ-AUD-001 per-target ordering; read-only). */
+  async eventsForTarget(targetId: string): Promise<HierarchyAuditEventRow[]> {
+    return this.db
+      .select()
+      .from(hierarchyAuditEvents)
+      .where(eq(hierarchyAuditEvents.targetId, targetId))
+      .orderBy(asc(hierarchyAuditEvents.seq));
+  }
+
+  /**
+   * Claim the oldest pending outbox record (claim-by-CAS: the UPDATE is
+   * guarded on status so a lost race returns null and the caller retries).
+   */
+  async claimPendingOutbox(): Promise<HierarchyOutboxRow | null> {
+    const candidates = await this.db
+      .select()
+      .from(hierarchyOutbox)
+      .where(eq(hierarchyOutbox.status, 'pending'))
+      .orderBy(asc(hierarchyOutbox.createdAt))
+      .limit(1);
+    const candidate = candidates[0];
+    if (!candidate) return null;
+    const claimed = await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'processing', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, candidate.id), eq(hierarchyOutbox.status, 'pending')))
+      .returning();
+    return claimed[0] ?? null;
+  }
+
+  async completeOutbox(id: string): Promise<void> {
+    const now = new Date();
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'delivered', deliveredAt: now, updatedAt: now })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+
+  /** Return a claimed record to pending (delivery failed; it stays replayable). */
+  async releaseOutbox(id: string): Promise<void> {
+    await this.db
+      .update(hierarchyOutbox)
+      .set({ status: 'pending', updatedAt: new Date() })
+      .where(and(eq(hierarchyOutbox.id, id), eq(hierarchyOutbox.status, 'processing')));
+  }
+}

apps/gateway/src/hierarchy/hierarchy.module.ts

@@ -0,0 +1,17 @@
+import { Module } from '@nestjs/common';
+import { HierarchyAuditRepository } from './hierarchy-audit.repository.js';
+
+/**
+ * Hierarchy (tenancy/authorization structure) feature module.
+ *
+ * M4-1b-i ships the audit event + outbox machinery only (contract 1 §5.2).
+ * The hierarchy command family — controllers, DTOs, and the allowlisted
+ * class-table repositories — lands in M4-1b-ii once contract 2 (RBAC grant
+ * model) merges; until then this module exposes no routes, which the
+ * route-inventory witness asserts.
+ */
+@Module({
+  providers: [HierarchyAuditRepository],
+  exports: [HierarchyAuditRepository],
+})
+export class HierarchyModule {}

apps/gateway/src/main.ts

@@ -12,12 +12,19 @@ import { AppModule } from './app.module.js';
 import { mountAuthHandler } from './auth/auth.controller.js';
 import { mountMcpHandler } from './mcp/mcp.controller.js';
 import { McpService } from './mcp/mcp.service.js';
+import { mountSpaStatic } from './spa/serve-spa.js';
 import { detectAndAssertTier, TierDetectionError } from '@mosaicstack/storage';
 import { resolveGatewayConfigPath } from './env.js';
+import { assertValidationPipeSeesDtoDecorators } from './validation-pipe-check.js';
 
 async function bootstrap(): Promise<void> {
   const logger = new Logger('Bootstrap');
 
+  // Fail loud BEFORE anything else if the global ValidationPipe cannot see
+  // the guarded DTOs' decorated properties (#1391): a broken metatype turns
+  // every request body into a 400 at first use; this surfaces it at boot.
+  assertValidationPipeSeesDtoDecorators();
+
   if (!process.env['BETTER_AUTH_SECRET']) {
     throw new Error('BETTER_AUTH_SECRET is required');
   }
@@ -62,6 +69,7 @@ async function bootstrap(): Promise<void> {
 
   mountAuthHandler(app);
   mountMcpHandler(app, app.get(McpService));
+  await mountSpaStatic(app);
 
   const port = Number(process.env['GATEWAY_PORT'] ?? 14242);
   await app.listen(port, '0.0.0.0');

apps/gateway/src/reload/reload.service.spec.ts

@@ -159,6 +159,7 @@ describe('ReloadService — /reload command sanitizes plugin errors', () => {
       reloadService,
       mockChatGateway as never,
       mockMcpClient as never,
+      { authorize: vi.fn().mockResolvedValue({ allowed: true }) } as never,
     );
 
     const payload: SlashCommandPayload = { command: 'reload', conversationId: 'conv-1' };

apps/gateway/src/spa/serve-spa.e2e.spec.ts

@@ -0,0 +1,192 @@
+/**
+ * E2E integration test — SPA static serving (Phase P5 cutover, #1444; tests
+ * added in P6, #1445, review follow-up SF1 on PR #1453).
+ *
+ * Boots a real Nest+Fastify app the way main.ts does (mountSpaStatic after the
+ * controllers) against a fixture dist directory, and pins the serving
+ * contract:
+ *
+ *   1. `/` and client-side deep links fall back to index.html.
+ *   2. Declared API routes win over the catch-all.
+ *   3. Unknown backend paths (/api, /mcp, /socket.io) are JSON 404s, never the
+ *      SPA page — including with a query string (`/api?x=1`).
+ *   4. Static files are served exactly; hashed /assets/ files get immutable
+ *      cache headers, everything else revalidates (max-age=0), and a missing
+ *      /assets/ file is a 404 — never the SPA fallback.
+ *   5. WEB_DIST_DIR unset disables SPA serving entirely.
+ *   6. WEB_DIST_DIR pointing at a directory without index.html fails at boot.
+ */
+
+import 'reflect-metadata';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it, expect, afterAll, beforeAll } from 'vitest';
+import { Test } from '@nestjs/testing';
+import { Controller, Get, type INestApplication } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import request from 'supertest';
+import { mountSpaStatic } from './serve-spa.js';
+
+const INDEX_HTML = '<!doctype html><html><body>mosaic spa fixture</body></html>\n';
+const ASSET_JS = 'console.log("hashed asset");\n';
+
+@Controller('api/spa-test')
+class SpaTestController {
+  @Get('ping')
+  ping(): { ok: boolean } {
+    return { ok: true };
+  }
+}
+
+async function createApp(): Promise<INestApplication> {
+  const moduleRef = await Test.createTestingModule({
+    controllers: [SpaTestController],
+  }).compile();
+
+  const app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+  await app.init();
+  // Mirror main.ts ordering: SPA mounting happens after the app (and its
+  // controllers) exist, before listen.
+  await mountSpaStatic(app as NestFastifyApplication);
+  await (app as NestFastifyApplication).getHttpAdapter().getInstance().ready();
+  return app;
+}
+
+describe('SPA static serving — fixture dist dir', () => {
+  let app: INestApplication;
+  let distDir: string;
+  let previousWebDistDir: string | undefined;
+
+  beforeAll(async () => {
+    distDir = await mkdtemp(path.join(tmpdir(), 'serve-spa-fixture-'));
+    await writeFile(path.join(distDir, 'index.html'), INDEX_HTML);
+    await writeFile(path.join(distDir, 'favicon.svg'), '<svg></svg>\n');
+    await mkdir(path.join(distDir, 'assets'), { recursive: true });
+    await writeFile(path.join(distDir, 'assets', 'app-abc123.js'), ASSET_JS);
+
+    previousWebDistDir = process.env['WEB_DIST_DIR'];
+    process.env['WEB_DIST_DIR'] = distDir;
+    app = await createApp();
+  });
+
+  afterAll(async () => {
+    if (previousWebDistDir === undefined) {
+      delete process.env['WEB_DIST_DIR'];
+    } else {
+      process.env['WEB_DIST_DIR'] = previousWebDistDir;
+    }
+    await app.close();
+    await rm(distDir, { recursive: true, force: true });
+  });
+
+  it('serves index.html at /', async () => {
+    const res = await request(app.getHttpServer()).get('/');
+    expect(res.status).toBe(200);
+    expect(res.text).toBe(INDEX_HTML);
+    expect(res.headers['content-type']).toContain('text/html');
+  });
+
+  it('falls back to index.html for client-side deep links', async () => {
+    for (const deepLink of ['/chat', '/projects/42', '/settings']) {
+      const res = await request(app.getHttpServer()).get(deepLink);
+      expect(res.status, deepLink).toBe(200);
+      expect(res.text, deepLink).toBe(INDEX_HTML);
+    }
+  });
+
+  it('declared API routes win over the SPA catch-all', async () => {
+    const res = await request(app.getHttpServer()).get('/api/spa-test/ping');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+  });
+
+  it('unknown backend paths are JSON 404s, never the SPA page', async () => {
+    for (const backendPath of ['/api/nope', '/api', '/mcp/nope', '/socket.io/nope']) {
+      const res = await request(app.getHttpServer()).get(backendPath);
+      expect(res.status, backendPath).toBe(404);
+      expect(res.headers['content-type'], backendPath).toContain('application/json');
+      expect(res.body, backendPath).toMatchObject({ error: 'Not Found', statusCode: 404 });
+    }
+  });
+
+  it('a backend path with a query string is still a backend 404 (/api?x=1)', async () => {
+    const res = await request(app.getHttpServer()).get('/api?x=1');
+    expect(res.status).toBe(404);
+    expect(res.headers['content-type']).toContain('application/json');
+  });
+
+  it('serves static files exactly', async () => {
+    const res = await request(app.getHttpServer()).get('/favicon.svg');
+    expect(res.status).toBe(200);
+    // supertest buffers image/svg+xml as a Buffer body, not res.text.
+    const body = res.text || (res.body as Buffer).toString('utf8');
+    expect(body).toBe('<svg></svg>\n');
+  });
+
+  it('hashed /assets/ files get immutable cache headers', async () => {
+    const res = await request(app.getHttpServer()).get('/assets/app-abc123.js');
+    expect(res.status).toBe(200);
+    expect(res.text).toBe(ASSET_JS);
+    expect(res.headers['cache-control']).toBe('public, max-age=31536000, immutable');
+  });
+
+  it('missing /assets/ files are 404s, never the SPA page with an immutable header', async () => {
+    // The exact request a browser with a stale index.html makes after a
+    // deploy: the old hashed filename. Serving index.html here would poison
+    // caches with a year-long immutable entry whose body is HTML.
+    for (const missingAsset of ['/assets/app-old999.js', '/assets/app-old999.js?v=1']) {
+      const res = await request(app.getHttpServer()).get(missingAsset);
+      expect(res.status, missingAsset).toBe(404);
+      expect(res.text, missingAsset).not.toContain('mosaic spa fixture');
+      // The 404 carries no cache-control at all; ?? '' keeps the assertion valid.
+      expect(res.headers['cache-control'] ?? '', missingAsset).not.toContain('immutable');
+    }
+  });
+
+  it('index.html and non-asset files revalidate (no immutable caching)', async () => {
+    for (const revalidating of ['/', '/chat', '/favicon.svg']) {
+      const res = await request(app.getHttpServer()).get(revalidating);
+      expect(res.headers['cache-control'], revalidating).not.toContain('immutable');
+    }
+  });
+
+  it('non-GET unmatched requests keep the stock 404 (catch-all is GET/HEAD only)', async () => {
+    const res = await request(app.getHttpServer()).post('/chat');
+    expect(res.status).toBe(404);
+    expect(res.text).not.toContain('mosaic spa fixture');
+  });
+});
+
+describe('SPA static serving — configuration edges', () => {
+  it('WEB_DIST_DIR unset disables SPA serving', async () => {
+    const previous = process.env['WEB_DIST_DIR'];
+    delete process.env['WEB_DIST_DIR'];
+    try {
+      const app = await createApp();
+      const res = await request(app.getHttpServer()).get('/chat');
+      expect(res.status).toBe(404);
+      await app.close();
+    } finally {
+      if (previous !== undefined) {
+        process.env['WEB_DIST_DIR'] = previous;
+      }
+    }
+  });
+
+  it('WEB_DIST_DIR without index.html fails at boot', async () => {
+    const emptyDir = await mkdtemp(path.join(tmpdir(), 'serve-spa-empty-'));
+    const previous = process.env['WEB_DIST_DIR'];
+    process.env['WEB_DIST_DIR'] = emptyDir;
+    try {
+      await expect(createApp()).rejects.toThrow(/index\.html.*does not exist/);
+    } finally {
+      if (previous === undefined) {
+        delete process.env['WEB_DIST_DIR'];
+      } else {
+        process.env['WEB_DIST_DIR'] = previous;
+      }
+      await rm(emptyDir, { recursive: true, force: true });
+    }
+  });
+});

apps/gateway/src/spa/serve-spa.ts

@@ -0,0 +1,106 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { Logger } from '@nestjs/common';
+import fastifyStatic from '@fastify/static';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+
+/** Request paths that belong to the backend, never to the SPA fallback. */
+const BACKEND_PREFIXES = ['/api', '/mcp', '/socket.io'] as const;
+
+function isBackendPath(url: string): boolean {
+  // Match on the path only: `/api?x=1` is a backend request, and the query
+  // string must never turn it into an SPA fallback.
+  const pathOnly = url.split('?', 1)[0] ?? url;
+  return BACKEND_PREFIXES.some(
+    (prefix) => pathOnly === prefix || pathOnly.startsWith(`${prefix}/`),
+  );
+}
+
+/**
+ * Serve the built web SPA bundle (Phase P5 cutover, #1444).
+ *
+ * WEB_DIST_DIR unset: SPA serving is disabled — dev runs the Vite dev server,
+ * which proxies /api and /socket.io here. WEB_DIST_DIR set but not holding a
+ * built bundle: fail at boot, because a gateway configured to serve the UI
+ * silently serving 404s is an outage, not a degraded mode.
+ *
+ * Static files get exact routes (wildcard: false, so nothing shadows the API
+ * routes); every other GET/HEAD outside the backend prefixes falls back to
+ * index.html so client-side routes deep-link correctly.
+ */
+export async function mountSpaStatic(app: NestFastifyApplication): Promise<void> {
+  const logger = new Logger('SpaStatic');
+  const distDir = process.env['WEB_DIST_DIR'];
+  if (!distDir) {
+    logger.log('WEB_DIST_DIR not set; SPA serving disabled (dev mode uses the Vite dev server)');
+    return;
+  }
+
+  const root = path.resolve(distDir);
+  const indexFile = path.join(root, 'index.html');
+  if (!existsSync(indexFile)) {
+    throw new Error(`WEB_DIST_DIR is '${distDir}' but '${indexFile}' does not exist`);
+  }
+
+  // Default cache semantics: public, max-age=0 with ETag/Last-Modified, so
+  // every response revalidates (304 when unchanged). Always correct, including
+  // for index.html after a deploy.
+  await app.register(
+    fastifyStatic as never,
+    {
+      root,
+      wildcard: false,
+      index: false,
+    } as never,
+  );
+
+  const fastify = app.getHttpAdapter().getInstance();
+
+  // Files under /assets/ carry a content hash in their name (Vite emits them
+  // that way), so they get long-lived immutable caching: a changed file is a
+  // new URL, never a stale cache hit. An onSend hook rather than the plugin's
+  // `setHeaders` option, because @fastify/static applies its own computed
+  // cache-control (reply.headers) after calling setHeaders, overriding it.
+  fastify.addHook('onSend', (req, reply, payload, done) => {
+    const pathOnly = (req.raw.url ?? '').split('?', 1)[0] ?? '';
+    if (reply.statusCode === 200 && pathOnly.startsWith('/assets/')) {
+      void reply.header('cache-control', 'public, max-age=31536000, immutable');
+    }
+    done(null, payload);
+  });
+
+  // A wildcard route, not setNotFoundHandler: Nest installs its own not-found
+  // handler during init and Fastify allows only one. find-my-way matches
+  // most-specific-first, so every declared route (API, static files) wins over
+  // this catch-all; non-GET unmatched requests keep Fastify's stock 404.
+  fastify.get('/*', (req, reply) => {
+    const url = req.raw.url ?? '';
+    const pathOnly = url.split('?', 1)[0] ?? url;
+    if (isBackendPath(url)) {
+      // An unknown backend path is an API 404, never the SPA page.
+      void reply.code(404).send({
+        message: `Route ${req.raw.method ?? 'GET'}:${url} not found`,
+        error: 'Not Found',
+        statusCode: 404,
+      });
+      return;
+    }
+    if (pathOnly === '/assets' || pathOnly.startsWith('/assets/')) {
+      // A missing hashed asset — typically a browser holding a stale
+      // index.html after a deploy — must 404. Falling through to the SPA
+      // fallback would return index.html as the asset body, and the onSend
+      // hook above would stamp it with a year-long immutable cache-control.
+      void reply.code(404).send({
+        message: `Asset ${pathOnly} not found`,
+        error: 'Not Found',
+        statusCode: 404,
+      });
+      return;
+    }
+    // sendFile is decorated by @fastify/static; its type augmentation targets
+    // a different fastify copy in the pnpm tree than the Nest adapter's.
+    (reply as unknown as { sendFile: (file: string) => unknown }).sendFile('index.html');
+  });
+
+  logger.log(`Serving SPA bundle from ${root}`);
+}

apps/gateway/src/validation-pipe-check.spec.ts

@@ -0,0 +1,104 @@
+/**
+ * Boot-time ValidationPipe metatype self-check (#1391).
+ *
+ * The check exists to fail loud at boot when the global pipe cannot see a
+ * guarded DTO's decorated properties — the #436 class-erasure signature and
+ * its dependency-graph cousins. Red/green arms:
+ *
+ *   GREEN  real module state: BootstrapSetupDto's three properties are
+ *          decorated and visible through the globalThis-shared storage.
+ *   RED    a control class with NO decorators (the erasure shape): the
+ *          check throws PipeMetatypeCheckError naming every property.
+ *   RED-2  a control where one property is decorated and two are not: the
+ *          error names exactly the missing two — the miss list is precise,
+ *          not a blanket failure.
+ */
+import { describe, expect, it } from 'vitest';
+import { IsString } from 'class-validator';
+import {
+  assertValidationPipeSeesDtoDecorators,
+  PipeMetatypeCheckError,
+} from './validation-pipe-check.js';
+
+describe('assertValidationPipeSeesDtoDecorators (#1391 boot check)', () => {
+  it('GREEN: passes on real module state (decorated DTO visible to the pipe)', () => {
+    expect(() => assertValidationPipeSeesDtoDecorators()).not.toThrow();
+  });
+
+  it('RED control: a class whose properties lost their decorators throws, naming them', async () => {
+    // Simulate metatype erasure: an undecorated class standing where a
+    // decorated DTO should be. Redefine the guard table for the test by
+    // importing the module and pointing its table at the eroded class —
+    // the check reads the table at call time, so a fresh module instance
+    // with a swapped table reproduces the boot failure deterministically.
+    const { PIPE_GUARDED_DTOS } = await import('./validation-pipe-check.js');
+
+    class ErodedDto {
+      name?: string;
+      email?: string;
+      password?: string;
+    }
+
+    const original = PIPE_GUARDED_DTOS[0];
+    expect(original).toBeDefined();
+    // Swap in the eroded target (same declared properties, zero decorators).
+    (
+      PIPE_GUARDED_DTOS as unknown as Array<{ name: string; target: object; properties: string[] }>
+    ).splice(0, PIPE_GUARDED_DTOS.length, {
+      name: 'ErodedDto',
+      target: ErodedDto,
+      properties: ['name', 'email', 'password'],
+    });
+
+    try {
+      expect(() => assertValidationPipeSeesDtoDecorators()).toThrow(PipeMetatypeCheckError);
+      try {
+        assertValidationPipeSeesDtoDecorators();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : '';
+        expect(message).toContain('ErodedDto.name');
+        expect(message).toContain('ErodedDto.email');
+        expect(message).toContain('ErodedDto.password');
+      }
+    } finally {
+      // Restore real module state for any later test in this file.
+      (PIPE_GUARDED_DTOS as unknown as unknown[]).splice(0, PIPE_GUARDED_DTOS.length, original);
+    }
+    // And confirm the restore is real.
+    expect(() => assertValidationPipeSeesDtoDecorators()).not.toThrow();
+  });
+
+  it('RED-2 control: a partially decorated class names exactly the missing properties', async () => {
+    const { PIPE_GUARDED_DTOS } = await import('./validation-pipe-check.js');
+
+    class HalfErodedDto {
+      @IsString()
+      name?: string;
+      email?: string;
+      password?: string;
+    }
+
+    const original = PIPE_GUARDED_DTOS[0];
+    (
+      PIPE_GUARDED_DTOS as unknown as Array<{ name: string; target: object; properties: string[] }>
+    ).splice(0, PIPE_GUARDED_DTOS.length, {
+      name: 'HalfErodedDto',
+      target: HalfErodedDto,
+      properties: ['name', 'email', 'password'],
+    });
+
+    try {
+      try {
+        assertValidationPipeSeesDtoDecorators();
+        expect.unreachable('partially decorated DTO must fail the boot check');
+      } catch (err) {
+        const message = err instanceof Error ? err.message : '';
+        expect(message).toContain('HalfErodedDto.email');
+        expect(message).toContain('HalfErodedDto.password');
+        expect(message).not.toContain('HalfErodedDto.name has no');
+      }
+    } finally {
+      (PIPE_GUARDED_DTOS as unknown as unknown[]).splice(0, PIPE_GUARDED_DTOS.length, original);
+    }
+  });
+});

apps/gateway/src/validation-pipe-check.ts

@@ -0,0 +1,94 @@
+import 'reflect-metadata';
+import { getMetadataStorage } from 'class-validator';
+import { BootstrapSetupDto } from './admin/bootstrap.dto.js';
+
+/**
+ * Boot-time self-check: the global ValidationPipe must be able to SEE the
+ * decorated properties of the DTOs it guards (#1391, #436 class).
+ *
+ * WHY THIS EXISTS. When Nest resolves a @Body() metatype to Object — via
+ * `import type` class erasure (#436), or a dependency graph where the
+ * controller's decorators and the application's route enhancers disagree
+ * (#1391's hypothesized dual-@nestjs/common on a mixed install) — the
+ * ValidationPipe's whitelist treats every property as forbidden. The first
+ * symptom is a 400 on the FIRST bootstrap attempt of a fresh install, the
+ * worst place to discover wiring damage: the operator cannot tell a broken
+ * payload from a broken daemon.
+ *
+ * This check fails LOUD at boot instead: if the pipe cannot see the DTO's
+ * decorated properties, the gateway refuses to start with a named cause.
+ * It catches the whole class — erasure, decorator metadata loss — on every
+ * host, at the moment the damage exists rather than at first use.
+ *
+ * Storage sharing note: class-validator keys its metadata storage on
+ * globalThis, so duplicate package copies do NOT hide metadata (measured,
+ * #1391 diagnosis). What hides it is losing the metatype itself, which is
+ * what this asserts against.
+ */
+
+/**
+ * DTOs the global pipe guards, mapped to the properties the whitelist must
+ * admit. Target is the CONSTRUCTOR (the object class itself): class-validator
+ * decorators register metadata keyed on the constructor, and its executor
+ * looks up `object.constructor` (ValidationExecutor.js:50) — the probe
+ * through `prototype` returns zero. Extend when adding DTOs to the app.
+ */
+export const PIPE_GUARDED_DTOS: Array<{
+  name: string;
+  target: abstract new (...args: never[]) => unknown;
+  properties: string[];
+}> = [
+  {
+    name: 'BootstrapSetupDto',
+    target: BootstrapSetupDto,
+    properties: ['name', 'email', 'password'],
+  },
+];
+
+export class PipeMetatypeCheckError extends Error {
+  constructor(missing: string[]) {
+    super(
+      'ValidationPipe metatype check failed: ' +
+        missing.join('; ') +
+        '. The global ValidationPipe cannot see decorated DTO properties — ' +
+        'every request body would be rejected as non-whitelisted. ' +
+        'Check for import-type erasure or decorator metadata loss in the ' +
+        'dependency graph (see issues #436, #1391).',
+    );
+    this.name = 'PipeMetatypeCheckError';
+  }
+}
+
+/**
+ * Assert the pipe's whitelist can see every guarded DTO's decorated
+ * properties. Throws PipeMetatypeCheckError (fail-loud at boot) listing
+ * each miss. Pure function of module state: no I/O, safe to call twice.
+ */
+export function assertValidationPipeSeesDtoDecorators(): void {
+  const storage = getMetadataStorage();
+  const missing: string[] = [];
+
+  for (const dto of PIPE_GUARDED_DTOS) {
+    // class-validator records constraints keyed on the DTO's constructor
+    // (decorators run on the class), and its executor resolves them via
+    // object.constructor. A property with no recorded metadata is invisible
+    // to the whitelist — whatever the cause — and fails here.
+    // Signature mirrors ValidationExecutor.js:50 — (constructor, schema, always,
+    // strictGroups, groups?). No schema, always=true, no groups: every
+    // constraint regardless of grouping, which is what the whitelist sees.
+    const metadatas = storage.getTargetValidationMetadatas(dto.target, '', true, false);
+    const decorated = new Set(metadatas.map((m) => m.propertyName));
+
+    for (const property of dto.properties) {
+      if (!decorated.has(property)) {
+        missing.push(
+          `${dto.name}.${property} has no class-validator constraints visible to the pipe`,
+        );
+      }
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new PipeMetatypeCheckError(missing);
+  }
+}

apps/gateway/src/workspace/teams.controller.spec.ts

@@ -0,0 +1,123 @@
+import 'reflect-metadata';
+import { type CanActivate, type ExecutionContext, type INestApplication } from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { TeamsController } from './teams.controller.js';
+import { TeamsService } from './teams.service.js';
+
+const teamAlpha = { id: 'team-alpha', name: 'Alpha' };
+const teamBeta = { id: 'team-beta', name: 'Beta' };
+
+// user-1 is a member of team-alpha only; admin-1 has role admin.
+let currentUser: { id: string; role?: string } = { id: 'user-1' };
+
+const teamsServiceMock = {
+  findAll: vi.fn(() => Promise.resolve([teamAlpha, teamBeta])),
+  findAllForUser: vi.fn((userId: string) =>
+    Promise.resolve(userId === 'user-1' ? [teamAlpha] : []),
+  ),
+  findById: vi.fn((id: string) => Promise.resolve([teamAlpha, teamBeta].find((t) => t.id === id))),
+  listMembers: vi.fn(() => Promise.resolve([{ teamId: 'team-alpha', userId: 'user-1' }])),
+  isMember: vi.fn((teamId: string, userId: string) =>
+    Promise.resolve(teamId === 'team-alpha' && userId === 'user-1'),
+  ),
+};
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context
+      .switchToHttp()
+      .getRequest<{ user?: { id: string; role?: string } }>();
+    requestContext.user = currentUser;
+    return true;
+  },
+};
+
+describe('teams endpoints are scoped to membership', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [TeamsController],
+      providers: [{ provide: TeamsService, useValue: teamsServiceMock }],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  beforeEach(() => {
+    currentUser = { id: 'user-1' };
+    vi.clearAllMocks();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('GET /api/teams returns only the teams the user belongs to', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual([teamAlpha]);
+    expect(teamsServiceMock.findAll).not.toHaveBeenCalled();
+  });
+
+  it('GET /api/teams returns every team for an admin', async () => {
+    currentUser = { id: 'admin-1', role: 'admin' };
+    const response = await request(app.getHttpServer()).get('/api/teams');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual([teamAlpha, teamBeta]);
+    expect(teamsServiceMock.findAllForUser).not.toHaveBeenCalled();
+  });
+
+  it('GET /api/teams/:teamId returns 403 for a non-member', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams/team-beta');
+    expect(response.status).toBe(403);
+  });
+
+  it('GET /api/teams/:teamId returns 404 for a missing team', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams/team-missing');
+    expect(response.status).toBe(404);
+  });
+
+  it('GET /api/teams/:teamId returns the team for a member', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams/team-alpha');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual(teamAlpha);
+  });
+
+  it('GET /api/teams/:teamId/members returns 403 for a non-member and members for a member', async () => {
+    const denied = await request(app.getHttpServer()).get('/api/teams/team-beta/members');
+    expect(denied.status).toBe(403);
+    expect(teamsServiceMock.listMembers).not.toHaveBeenCalled();
+
+    const allowed = await request(app.getHttpServer()).get('/api/teams/team-alpha/members');
+    expect(allowed.status).toBe(200);
+    expect(allowed.body).toEqual([{ teamId: 'team-alpha', userId: 'user-1' }]);
+  });
+
+  it('GET /api/teams/:teamId/members/:userId allows a self-lookup on any team', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams/team-beta/members/user-1');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ isMember: false });
+  });
+
+  it('GET /api/teams/:teamId/members/:userId denies looking up another user on a foreign team', async () => {
+    const response = await request(app.getHttpServer()).get('/api/teams/team-beta/members/user-2');
+    expect(response.status).toBe(403);
+  });
+
+  it('an admin can look up any membership', async () => {
+    currentUser = { id: 'admin-1', role: 'admin' };
+    const response = await request(app.getHttpServer()).get('/api/teams/team-alpha/members/user-1');
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ isMember: true });
+  });
+});

apps/gateway/src/workspace/teams.controller.ts

@@ -1,30 +1,68 @@
-import { Controller, Get, Param, UseGuards } from '@nestjs/common';
+import {
+  Controller,
+  ForbiddenException,
+  Get,
+  NotFoundException,
+  Param,
+  UseGuards,
+} from '@nestjs/common';
 import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
 import { TeamsService } from './teams.service.js';
 
+type RequestUser = { id: string; role?: string };
+
 @Controller('api/teams')
 @UseGuards(AuthGuard)
 export class TeamsController {
   constructor(private readonly teams: TeamsService) {}
 
   @Get()
-  async list() {
-    return this.teams.findAll();
+  async list(@CurrentUser() user: RequestUser) {
+    if (user.role === 'admin') {
+      return this.teams.findAll();
+    }
+    return this.teams.findAllForUser(user.id);
   }
 
   @Get(':teamId')
-  async findOne(@Param('teamId') teamId: string) {
-    return this.teams.findById(teamId);
+  async findOne(@Param('teamId') teamId: string, @CurrentUser() user: RequestUser) {
+    return this.getAccessibleTeam(teamId, user);
   }
 
   @Get(':teamId/members')
-  async listMembers(@Param('teamId') teamId: string) {
+  async listMembers(@Param('teamId') teamId: string, @CurrentUser() user: RequestUser) {
+    await this.getAccessibleTeam(teamId, user);
     return this.teams.listMembers(teamId);
   }
 
   @Get(':teamId/members/:userId')
-  async checkMembership(@Param('teamId') teamId: string, @Param('userId') userId: string) {
+  async checkMembership(
+    @Param('teamId') teamId: string,
+    @Param('userId') userId: string,
+    @CurrentUser() user: RequestUser,
+  ) {
+    // A user may always ask about their own membership; anything else is
+    // team-scoped like the other routes.
+    if (userId !== user.id) {
+      await this.getAccessibleTeam(teamId, user);
+    }
     const isMember = await this.teams.isMember(teamId, userId);
     return { isMember };
   }
+
+  /**
+   * Team-scoped access: admins see any team; everyone else only teams they
+   * are a member of. NotFoundException when the team does not exist and
+   * ForbiddenException when the user lacks access (same convention as the
+   * projects controller).
+   */
+  private async getAccessibleTeam(teamId: string, user: RequestUser) {
+    const team = await this.teams.findById(teamId);
+    if (!team) throw new NotFoundException('Team not found');
+    if (user.role === 'admin') return team;
+    const isMember = await this.teams.isMember(teamId, user.id);
+    if (!isMember) throw new ForbiddenException('Not a member of this team');
+    return team;
+  }
 }

apps/gateway/src/workspace/teams.service.ts

@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { eq, and, type Db, teams, teamMembers, projects } from '@mosaicstack/db';
+import { eq, and, inArray, type Db, teams, teamMembers, projects } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 
 @Injectable()
@@ -56,6 +56,21 @@ export class TeamsService {
     return this.db.select().from(teams);
   }
 
+  /**
+   * List only the teams the user is a member of.
+   */
+  async findAllForUser(userId: string) {
+    const memberRows = await this.db
+      .select({ teamId: teamMembers.teamId })
+      .from(teamMembers)
+      .where(eq(teamMembers.userId, userId));
+
+    const teamIds = memberRows.map((r) => r.teamId);
+    if (teamIds.length === 0) return [];
+
+    return this.db.select().from(teams).where(inArray(teams.id, teamIds));
+  }
+
   /**
    * Find a team by ID.
    */

apps/web/e2e/admin.spec.ts

@@ -1,11 +1,14 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, ADMIN_USER, TEST_USER } from './helpers/auth.js';
+import { loginAs, ADMIN_USER, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Admin page — admin user', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, ADMIN_USER.email, ADMIN_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded admin user — skipping admin tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded admin user — skipping admin tests',
+    );
   });
 
   test('admin page loads with the Admin Panel heading', async ({ page }) => {
@@ -31,15 +34,11 @@ test.describe('Admin page — admin user', () => {
     await page.goto('/admin');
     await page.getByRole('button', { name: /system health/i }).click();
     // Health cards or loading indicator should appear
-    const hasLoading = await page
+    const loadingOrCard = page
       .getByText(/loading health/i)
-      .isVisible()
-      .catch(() => false);
-    const hasCard = await page
-      .getByText(/database/i)
-      .isVisible()
-      .catch(() => false);
-    expect(hasLoading || hasCard).toBe(true);
+      .or(page.getByText(/database/i))
+      .first();
+    await expect(loadingOrCard).toBeVisible({ timeout: 10_000 });
   });
 });
 
@@ -47,26 +46,19 @@ test.describe('Admin page — non-admin user', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping non-admin tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping non-admin tests',
+    );
   });
 
-  test('non-admin visiting /admin sees access denied or is redirected', async ({ page }) => {
+  test('non-admin visiting /admin never sees the admin panel', async ({ page }) => {
     await page.goto('/admin');
-    // Either redirected away or shown an access-denied message
-    const onAdmin = page.url().includes('/admin');
-    if (onAdmin) {
-      // Should show some access-denied content rather than the full admin panel
-      const hasPanel = await page
-        .getByRole('heading', { name: /admin panel/i })
-        .isVisible()
-        .catch(() => false);
-      // If heading is visible, the guard allowed access (user may have admin role in this env)
-      // — not a failure, just informational
-      if (!hasPanel) {
-        // access denied message, redirect, or guard placeholder
-        const url = page.url();
-        expect(url).toBeTruthy(); // environment-dependent — no hard assertion
-      }
-    }
+    // Wait for the app shell to render (redirect and access-denied views both
+    // keep the sidebar), then assert the panel itself is absent. globalSetup
+    // seeds TEST_USER with role 'member', so this is a real authorization
+    // assertion, not environment-dependent.
+    await expect(page.getByRole('img', { name: /mosaic logo/i })).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByRole('heading', { name: /admin panel/i })).not.toBeVisible();
   });
 });

apps/web/e2e/auth.spec.ts

@@ -1,5 +1,5 @@
 import { test, expect } from '@playwright/test';
-import { TEST_USER } from './helpers/auth.js';
+import { REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 // ── Login page ────────────────────────────────────────────────────────────────
 
@@ -49,18 +49,14 @@ test.describe('Login page', () => {
   });
 
   test('redirects to /chat after successful login', async ({ page }) => {
+    // Only meaningful with known-good credentials; against a live environment
+    // this would just probe someone else's user table.
+    test.skip(!REQUIRE_SEEDED_AUTH, 'needs seeded credentials (E2E_REQUIRE_SEEDED_AUTH=1)');
     await page.goto('/login');
     await page.getByLabel('Email').fill(TEST_USER.email);
     await page.getByLabel('Password').fill(TEST_USER.password);
     await page.getByRole('button', { name: /sign in/i }).click();
-    // Either reaches /chat or shows an error (if credentials are wrong in this env).
-    // We assert a navigation away from /login, or the alert is shown.
-    await Promise.race([
-      expect(page).toHaveURL(/\/chat/, { timeout: 10_000 }),
-      expect(page.getByRole('alert')).toBeVisible({ timeout: 10_000 }),
-    ]).catch(() => {
-      // Acceptable — environment may not have seeded credentials
-    });
+    await expect(page).toHaveURL(/\/chat/, { timeout: 10_000 });
   });
 });
 

apps/web/e2e/chat.spec.ts

@@ -1,45 +1,38 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Chat page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     // If login failed (no seeded user in env) we may be on /login — skip
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
-  test('chat page loads and shows the welcome message or conversation list', async ({ page }) => {
+  test('chat page loads and shows the conversation area', async ({ page }) => {
     await page.goto('/chat');
-    // Either there are conversations listed or the welcome empty-state is shown
-    const hasWelcome = await page
-      .getByRole('heading', { name: /welcome to mosaic chat/i })
-      .isVisible()
-      .catch(() => false);
-    const hasConversationPanel = await page
-      .locator('[data-testid="conversation-list"], nav, aside')
-      .first()
-      .isVisible()
-      .catch(() => false);
-
-    expect(hasWelcome || hasConversationPanel).toBe(true);
+    await expect(page.getByRole('heading', { level: 1, name: /chat/i })).toBeVisible({
+      timeout: 10_000,
+    });
+    await expect(page.getByRole('log', { name: /conversation/i })).toBeVisible();
   });
 
-  test('new conversation button is visible', async ({ page }) => {
+  test('message composer input is visible', async ({ page }) => {
     await page.goto('/chat');
-    // "Start new conversation" button or a "+" button in the sidebar
-    const newConvButton = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await expect(newConvButton).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByLabel('Message')).toBeVisible({ timeout: 10_000 });
   });
 
-  test('clicking new conversation shows a chat input area', async ({ page }) => {
+  test('command panel lists /new and exposes the run controls', async ({ page }) => {
     await page.goto('/chat');
-    // Find any button that creates a new conversation
-    const newBtn = page.getByRole('button', { name: /new conversation|start new/i }).first();
-    await newBtn.click();
-    // After creating, a text input for sending messages should appear
-    const chatInput = page.getByRole('textbox').or(page.locator('textarea')).first();
-    await expect(chatInput).toBeVisible({ timeout: 10_000 });
+    // Conversations are command-driven: /new starts one via the commands panel.
+    const commandList = page.getByRole('list', { name: /available commands/i });
+    await expect(commandList).toBeVisible({ timeout: 10_000 });
+    await expect(commandList.getByText('/new', { exact: true })).toBeVisible();
+    await expect(page.getByLabel('Command name')).toBeVisible();
+    await expect(page.getByRole('button', { name: /run command/i })).toBeVisible();
   });
 
   test('sidebar navigation is present on chat page', async ({ page }) => {

apps/web/e2e/global-setup.ts

@@ -0,0 +1,95 @@
+import type { FullConfig } from '@playwright/test';
+import { ADMIN_USER, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
+
+/**
+ * Seed the E2E users through the gateway's real APIs (#1445, P6).
+ *
+ * On a fresh database (CI boots the gateway on the embedded PGlite path):
+ *   1. POST /api/bootstrap/setup creates ADMIN_USER as the first admin.
+ *   2. The admin signs in and creates TEST_USER via the better-auth admin API.
+ *
+ * Against an environment that already has users (needsSetup=false), seeding is
+ * skipped entirely: the specs keep their own skip-when-login-fails guards, so
+ * a live environment stays usable as a test target without mutation. Under
+ * E2E_REQUIRE_SEEDED_AUTH=1 (CI) that state is instead a hard failure and the
+ * guards are disabled — see helpers/auth.ts.
+ *
+ * On a fresh database, any seeding failure throws and fails the whole run: an
+ * E2E gate whose authenticated suites silently skip would pass while proving
+ * nothing.
+ */
+export default async function globalSetup(config: FullConfig): Promise<void> {
+  const baseURL = config.projects[0]?.use?.baseURL ?? 'http://localhost:14242';
+
+  const statusRes = await fetch(`${baseURL}/api/bootstrap/status`);
+  if (!statusRes.ok) {
+    throw new Error(`GET /api/bootstrap/status returned ${statusRes.status} — is the gateway up?`);
+  }
+  const status = (await statusRes.json()) as { needsSetup: boolean };
+  if (!status.needsSetup) {
+    if (REQUIRE_SEEDED_AUTH) {
+      // CI boots the gateway on a fresh HOME-isolated database, so an
+      // already-populated one means the isolation regressed — refuse to run
+      // against unknown data rather than skip-and-pass.
+      throw new Error(
+        'E2E_REQUIRE_SEEDED_AUTH=1 but the database already has users — gateway HOME isolation regressed?',
+      );
+    }
+    console.info('[e2e setup] users already exist; skipping seed');
+    return;
+  }
+
+  const setupRes = await fetch(`${baseURL}/api/bootstrap/setup`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      name: ADMIN_USER.name,
+      email: ADMIN_USER.email,
+      password: ADMIN_USER.password,
+    }),
+  });
+  if (!setupRes.ok) {
+    throw new Error(
+      `POST /api/bootstrap/setup failed (${setupRes.status}): ${await setupRes.text()}`,
+    );
+  }
+  console.info(`[e2e setup] bootstrap admin created: ${ADMIN_USER.email}`);
+
+  // better-auth's CSRF protection rejects requests without an Origin header
+  // (403 MISSING_OR_NULL_ORIGIN), so the server-side fetches here send the
+  // gateway's own origin — the same value a browser tab on the SPA would send.
+  const authHeaders = { 'content-type': 'application/json', origin: baseURL };
+
+  const signInRes = await fetch(`${baseURL}/api/auth/sign-in/email`, {
+    method: 'POST',
+    headers: authHeaders,
+    body: JSON.stringify({ email: ADMIN_USER.email, password: ADMIN_USER.password }),
+  });
+  if (!signInRes.ok) {
+    throw new Error(`admin sign-in failed (${signInRes.status}): ${await signInRes.text()}`);
+  }
+  const cookies = signInRes.headers
+    .getSetCookie()
+    .map((cookie) => cookie.split(';', 1)[0])
+    .join('; ');
+  if (!cookies) {
+    throw new Error('admin sign-in returned no session cookie');
+  }
+
+  const createRes = await fetch(`${baseURL}/api/auth/admin/create-user`, {
+    method: 'POST',
+    headers: { ...authHeaders, cookie: cookies },
+    body: JSON.stringify({
+      name: TEST_USER.name,
+      email: TEST_USER.email,
+      password: TEST_USER.password,
+      role: 'member',
+    }),
+  });
+  if (!createRes.ok) {
+    throw new Error(
+      `POST /api/auth/admin/create-user failed (${createRes.status}): ${await createRes.text()}`,
+    );
+  }
+  console.info(`[e2e setup] test user created: ${TEST_USER.email}`);
+}

apps/web/e2e/helpers/auth.ts

@@ -13,11 +13,28 @@ export const ADMIN_USER = {
 };
 
 /**
- * Fill the login form and submit. Waits for navigation after success.
+ * Set when the database was seeded by global-setup (CI sets it in the
+ * publish.yml e2e step). Seeded credentials MUST work, so login failures are
+ * hard failures and the skip-when-login-fails guards are disabled — otherwise
+ * a login regression would skip every authenticated suite and the gate would
+ * pass while proving nothing. Unset (a live environment used as a test
+ * target), the guards stay on and unseeded credentials skip their suites.
+ */
+export const REQUIRE_SEEDED_AUTH = process.env['E2E_REQUIRE_SEEDED_AUTH'] === '1';
+
+/**
+ * Fill the login form and submit, then wait for the post-login redirect to
+ * /chat. Under REQUIRE_SEEDED_AUTH a missed redirect throws (failing the
+ * test). Otherwise the timeout is swallowed: the page stays on /login and the
+ * callers' `test.skip(...)` guards see that. Without this wait, every guard
+ * read page.url() before the redirect happened and skipped its suite even
+ * when login succeeded (#1445).
  */
 export async function loginAs(page: Page, email: string, password: string): Promise<void> {
   await page.goto('/login');
   await page.getByLabel('Email').fill(email);
   await page.getByLabel('Password').fill(password);
   await page.getByRole('button', { name: /sign in/i }).click();
+  const redirect = page.waitForURL(/\/chat/, { timeout: 10_000 });
+  await (REQUIRE_SEEDED_AUTH ? redirect : redirect.catch(() => {}));
 }

apps/web/e2e/navigation.spec.ts

@@ -1,16 +1,22 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Sidebar navigation', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
-  test('sidebar shows Mosaic brand link', async ({ page }) => {
+  test('sidebar shows the Mosaic brand', async ({ page }) => {
     await page.goto('/chat');
-    await expect(page.getByRole('link', { name: /mosaic/i }).first()).toBeVisible();
+    // The brand block is a logo image plus "Mosaic / Mission Control" text,
+    // not a link.
+    await expect(page.getByRole('img', { name: /mosaic logo/i })).toBeVisible();
+    await expect(page.getByText('Mission Control')).toBeVisible();
   });
 
   test('Chat nav link navigates to /chat', async ({ page }) => {
@@ -48,11 +54,12 @@ test.describe('Sidebar navigation', () => {
 
   test('active link is visually highlighted', async ({ page }) => {
     await page.goto('/chat');
-    // The active link should have a distinct class — check that the Chat link
-    // has the active style class (bg-blue-600/20 text-blue-400)
+    // The sidebar marks the active item with `font-medium` (plus an inline
+    // primary-color style); inactive items get the hover class instead.
     const chatLink = page.getByRole('link', { name: /^chat$/i }).first();
-    const cls = await chatLink.getAttribute('class');
-    expect(cls).toContain('blue');
+    const projectsLink = page.getByRole('link', { name: /^projects$/i }).first();
+    await expect(chatLink).toHaveClass(/font-medium/);
+    await expect(projectsLink).not.toHaveClass(/font-medium/);
   });
 });
 
@@ -60,18 +67,23 @@ test.describe('Route transitions', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('navigating chat → projects → settings → chat works without errors', async ({ page }) => {
     await page.goto('/chat');
     await expect(page).toHaveURL(/\/chat/);
 
+    // level: 1 — empty-state h2s ("No projects yet") also match the loose
+    // patterns, and a two-element match is a strict-mode violation.
     await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /projects/i })).toBeVisible();
+    await expect(page.getByRole('heading', { level: 1, name: /projects/i })).toBeVisible();
 
     await page.goto('/settings');
-    await expect(page.getByRole('heading', { name: /settings/i })).toBeVisible();
+    await expect(page.getByRole('heading', { level: 1, name: /settings/i })).toBeVisible();
 
     await page.goto('/chat');
     await expect(page).toHaveURL(/\/chat/);

apps/web/e2e/projects.spec.ts

@@ -1,16 +1,23 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Projects page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('projects page loads with heading', async ({ page }) => {
     await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /projects/i })).toBeVisible({ timeout: 10_000 });
+    // level: 1 — the "No projects yet" empty-state h2 also matches /projects/i
+    // and a two-element match is a strict-mode violation.
+    await expect(page.getByRole('heading', { level: 1, name: /projects/i })).toBeVisible({
+      timeout: 10_000,
+    });
   });
 
   test('shows empty state or project cards when loaded', async ({ page }) => {
@@ -18,23 +25,11 @@ test.describe('Projects page', () => {
     // Wait for loading state to clear
     await expect(page.getByText(/loading projects/i)).not.toBeVisible({ timeout: 10_000 });
 
-    const hasProjects = await page
+    const cardsOrEmpty = page
       .locator('[class*="grid"]')
-      .isVisible()
-      .catch(() => false);
-    const hasEmpty = await page
-      .getByText(/no projects yet/i)
-      .isVisible()
-      .catch(() => false);
-
-    expect(hasProjects || hasEmpty).toBe(true);
-  });
-
-  test('shows Active Mission section', async ({ page }) => {
-    await page.goto('/projects');
-    await expect(page.getByRole('heading', { name: /active mission/i })).toBeVisible({
-      timeout: 10_000,
-    });
+      .or(page.getByText(/no projects yet/i))
+      .first();
+    await expect(cardsOrEmpty).toBeVisible({ timeout: 10_000 });
   });
 
   test('sidebar navigation is present', async ({ page }) => {

apps/web/e2e/settings.spec.ts

@@ -1,11 +1,14 @@
 import { test, expect } from '@playwright/test';
-import { loginAs, TEST_USER } from './helpers/auth.js';
+import { loginAs, REQUIRE_SEEDED_AUTH, TEST_USER } from './helpers/auth.js';
 
 test.describe('Settings page', () => {
   test.beforeEach(async ({ page }) => {
     await loginAs(page, TEST_USER.email, TEST_USER.password);
     const url = page.url();
-    test.skip(!url.includes('/chat'), 'No seeded test user — skipping authenticated tests');
+    test.skip(
+      !REQUIRE_SEEDED_AUTH && !url.includes('/chat'),
+      'No seeded test user — skipping authenticated tests',
+    );
   });
 
   test('settings page loads with heading', async ({ page }) => {

apps/web/next-env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/web/next.config.ts

@@ -1,32 +0,0 @@
-import type { NextConfig } from 'next';
-
-const nextConfig: NextConfig = {
-  output: 'standalone',
-  transpilePackages: ['@mosaicstack/design-tokens'],
-
-  // Enable gzip/brotli compression for all responses.
-  compress: true,
-
-  // Reduce bundle size: disable source maps in production builds.
-  productionBrowserSourceMaps: false,
-
-  // Image optimisation: allow the gateway origin as an external image source.
-  images: {
-    formats: ['image/avif', 'image/webp'],
-    remotePatterns: [
-      {
-        protocol: 'https',
-        hostname: '**',
-      },
-    ],
-  },
-
-  // Experimental: enable React compiler for automatic memoisation (Next 15+).
-  // Falls back gracefully if the compiler plugin is not installed.
-  experimental: {
-    // Turbopack is the default in dev for Next 15; keep it opt-in for now.
-    // turbo: {},
-  },
-};
-
-export default nextConfig;

apps/web/package.json

@@ -3,22 +3,19 @@
   "version": "0.0.2",
   "private": true,
   "scripts": {
-    "build": "node ../../scripts/build-web.mjs",
-    "build:vite": "vite build",
-    "dev": "next dev -p 3101",
-    "dev:vite": "vite",
+    "build": "vite build",
+    "dev": "vite",
+    "preview": "vite preview",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
-    "test:e2e": "playwright test",
-    "start": "next start -p 3101"
+    "test:e2e": "playwright test"
   },
   "dependencies": {
     "@mosaicstack/design-tokens": "workspace:^",
     "@mosaicstack/types": "workspace:^",
     "better-auth": "^1.5.5",
     "clsx": "^2.1.0",
-    "next": "^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",

apps/web/playwright.config.ts

@@ -1,23 +1,30 @@
 import { defineConfig, devices } from '@playwright/test';
 
 /**
- * Playwright E2E configuration for Mosaic web app.
+ * Playwright E2E configuration for the Mosaic web SPA.
  *
- * Assumes:
- *   - Next.js web app running on http://localhost:3000
- *   - NestJS gateway running on http://localhost:14242
+ * Assumes the NestJS gateway is already running on http://localhost:14242 and
+ * serving the built SPA bundle (WEB_DIST_DIR pointing at apps/web/dist) — the
+ * same serving path production uses (Phase P5, #1444). Override the target
+ * with PLAYWRIGHT_BASE_URL.
+ *
+ * global-setup seeds the E2E users through the real bootstrap and admin APIs
+ * when the database is empty; against an already-populated environment it
+ * seeds nothing.
  *
  * Run with:   pnpm --filter @mosaicstack/web test:e2e
  */
 export default defineConfig({
   testDir: './e2e',
+  globalSetup: './e2e/global-setup.ts',
   fullyParallel: true,
   forbidOnly: !!process.env['CI'],
   retries: process.env['CI'] ? 2 : 0,
   workers: process.env['CI'] ? 1 : undefined,
-  reporter: 'html',
+  // CI needs the verdict in the step log; the html report is a local tool.
+  reporter: process.env['CI'] ? 'list' : 'html',
   use: {
-    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000',
+    baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:14242',
     trace: 'on-first-retry',
     screenshot: 'only-on-failure',
   },
@@ -27,6 +34,6 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
   ],
-  // Do NOT auto-start the dev server — tests assume it is already running.
+  // Do NOT auto-start a server — tests assume the gateway is already running.
   // webServer is intentionally omitted so tests can run against a live env.
 });

apps/web/src/app/(auth)/layout.tsx

@@ -1,14 +0,0 @@
-import type { ReactNode } from 'react';
-import { GuestGuard } from '@/components/guest-guard';
-
-export default function AuthLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <GuestGuard>
-      <div className="flex min-h-screen items-center justify-center bg-surface-bg">
-        <div className="w-full max-w-md rounded-xl border border-surface-border bg-surface-card p-8 shadow-lg">
-          {children}
-        </div>
-      </div>
-    </GuestGuard>
-  );
-}

apps/web/src/app/(auth)/login/page.tsx

@@ -1,139 +0,0 @@
-'use client';
-
-import { useEffect, useState } from 'react';
-import { useRouter } from 'next/navigation';
-import Link from 'next/link';
-import { api } from '@/lib/api';
-import { authClient, signIn } from '@/lib/auth-client';
-import type { SsoProviderDiscovery } from '@/lib/sso';
-import { SsoProviderButtons } from '@/components/auth/sso-provider-buttons';
-
-export default function LoginPage(): React.ReactElement {
-  const router = useRouter();
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
-  const [ssoLoadingProviderId, setSsoLoadingProviderId] = useState<
-    SsoProviderDiscovery['id'] | null
-  >(null);
-
-  useEffect(() => {
-    api<SsoProviderDiscovery[]>('/api/sso/providers')
-      .catch(() => [] as SsoProviderDiscovery[])
-      .then((providers) => setSsoProviders(providers.filter((provider) => provider.configured)));
-  }, []);
-
-  async function handleSubmit(e: React.FormEvent<HTMLFormElement>): Promise<void> {
-    e.preventDefault();
-    setError(null);
-    setLoading(true);
-
-    const form = new FormData(e.currentTarget);
-    const email = form.get('email') as string;
-    const password = form.get('password') as string;
-
-    const result = await signIn.email({ email, password });
-
-    if (result.error) {
-      setError(result.error.message ?? 'Sign in failed');
-      setLoading(false);
-      return;
-    }
-
-    router.push('/chat');
-  }
-
-  async function handleSsoSignIn(providerId: SsoProviderDiscovery['id']): Promise<void> {
-    setError(null);
-    setSsoLoadingProviderId(providerId);
-
-    try {
-      const result = await authClient.signIn.oauth2({
-        providerId,
-        callbackURL: '/chat',
-        newUserCallbackURL: '/chat',
-      });
-
-      if (result.error) {
-        setError(result.error.message ?? `Sign in with ${providerId} failed`);
-        setSsoLoadingProviderId(null);
-      }
-    } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : `Sign in with ${providerId} failed`);
-      setSsoLoadingProviderId(null);
-    }
-  }
-
-  return (
-    <div>
-      <h1 className="text-2xl font-semibold">Sign in</h1>
-      <p className="mt-1 text-sm text-text-secondary">Sign in to your Mosaic account</p>
-
-      {error && (
-        <div
-          role="alert"
-          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
-        >
-          {error}
-        </div>
-      )}
-
-      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
-        <div>
-          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
-            Email
-          </label>
-          <input
-            id="email"
-            name="email"
-            type="email"
-            autoComplete="email"
-            required
-            disabled={loading}
-            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
-            placeholder="[email protected]"
-          />
-        </div>
-
-        <div>
-          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
-            Password
-          </label>
-          <input
-            id="password"
-            name="password"
-            type="password"
-            autoComplete="current-password"
-            required
-            disabled={loading}
-            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
-            placeholder="••••••••"
-          />
-        </div>
-
-        <button
-          type="submit"
-          disabled={loading}
-          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
-        >
-          {loading ? 'Signing in...' : 'Sign in'}
-        </button>
-      </form>
-
-      <SsoProviderButtons
-        providers={ssoProviders}
-        loadingProviderId={ssoLoadingProviderId}
-        onOidcSignIn={(providerId) => {
-          void handleSsoSignIn(providerId);
-        }}
-      />
-
-      <p className="mt-4 text-center text-sm text-text-muted">
-        Don&apos;t have an account?{' '}
-        <Link href="/register" className="text-blue-400 hover:text-blue-300">
-          Sign up
-        </Link>
-      </p>
-    </div>
-  );
-}

apps/web/src/app/(auth)/register/page.tsx

@@ -1,114 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-import { useRouter } from 'next/navigation';
-import Link from 'next/link';
-import { signUp } from '@/lib/auth-client';
-
-export default function RegisterPage(): React.ReactElement {
-  const router = useRouter();
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-
-  async function handleSubmit(e: React.FormEvent<HTMLFormElement>): Promise<void> {
-    e.preventDefault();
-    setError(null);
-    setLoading(true);
-
-    const form = new FormData(e.currentTarget);
-    const name = form.get('name') as string;
-    const email = form.get('email') as string;
-    const password = form.get('password') as string;
-
-    const result = await signUp.email({ name, email, password });
-
-    if (result.error) {
-      setError(result.error.message ?? 'Registration failed');
-      setLoading(false);
-      return;
-    }
-
-    router.push('/chat');
-  }
-
-  return (
-    <div>
-      <h1 className="text-2xl font-semibold">Create account</h1>
-      <p className="mt-1 text-sm text-text-secondary">Get started with Mosaic</p>
-
-      {error && (
-        <div
-          role="alert"
-          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
-        >
-          {error}
-        </div>
-      )}
-
-      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
-        <div>
-          <label htmlFor="name" className="block text-sm font-medium text-text-secondary">
-            Name
-          </label>
-          <input
-            id="name"
-            name="name"
-            type="text"
-            autoComplete="name"
-            required
-            disabled={loading}
-            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
-            placeholder="Your name"
-          />
-        </div>
-
-        <div>
-          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
-            Email
-          </label>
-          <input
-            id="email"
-            name="email"
-            type="email"
-            autoComplete="email"
-            required
-            disabled={loading}
-            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
-            placeholder="[email protected]"
-          />
-        </div>
-
-        <div>
-          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
-            Password
-          </label>
-          <input
-            id="password"
-            name="password"
-            type="password"
-            autoComplete="new-password"
-            required
-            disabled={loading}
-            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
-            placeholder="••••••••"
-          />
-        </div>
-
-        <button
-          type="submit"
-          disabled={loading}
-          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
-        >
-          {loading ? 'Creating account...' : 'Create account'}
-        </button>
-      </form>
-
-      <p className="mt-4 text-center text-sm text-text-muted">
-        Already have an account?{' '}
-        <Link href="/login" className="text-blue-400 hover:text-blue-300">
-          Sign in
-        </Link>
-      </p>
-    </div>
-  );
-}

apps/web/src/app/(dashboard)/chat/page.tsx

@@ -1,365 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { api } from '@/lib/api';
-import { destroySocket, getSocket } from '@/lib/socket';
-import type { Conversation, Message } from '@/lib/types';
-import {
-  ConversationSidebar,
-  type ConversationSidebarRef,
-} from '@/components/chat/conversation-sidebar';
-import { MessageBubble } from '@/components/chat/message-bubble';
-import { ChatInput } from '@/components/chat/chat-input';
-import { StreamingMessage } from '@/components/chat/streaming-message';
-
-interface ModelInfo {
-  id: string;
-  provider: string;
-  name: string;
-  reasoning: boolean;
-  contextWindow: number;
-  maxTokens: number;
-  inputTypes: ('text' | 'image')[];
-  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
-}
-
-interface ProviderInfo {
-  id: string;
-  name: string;
-  available: boolean;
-  models: ModelInfo[];
-}
-
-export default function ChatPage(): React.ReactElement {
-  const [activeId, setActiveId] = useState<string | null>(null);
-  const [messages, setMessages] = useState<Message[]>([]);
-  const [streamingText, setStreamingText] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [isSidebarOpen, setIsSidebarOpen] = useState(true);
-  const [models, setModels] = useState<ModelInfo[]>([]);
-  const [selectedModelId, setSelectedModelId] = useState('');
-  const messagesEndRef = useRef<HTMLDivElement>(null);
-  const sidebarRef = useRef<ConversationSidebarRef>(null);
-
-  // Track the active conversation ID in a ref so socket event handlers always
-  // see the current value without needing to be re-registered.
-  const activeIdRef = useRef<string | null>(null);
-  activeIdRef.current = activeId;
-
-  // Accumulate streamed text in a ref so agent:end can read the full content
-  // without stale-closure issues.
-  const streamingTextRef = useRef('');
-
-  useEffect(() => {
-    const savedState = window.localStorage.getItem('mosaic-sidebar-open');
-    if (savedState !== null) {
-      setIsSidebarOpen(savedState === 'true');
-    }
-  }, []);
-
-  useEffect(() => {
-    window.localStorage.setItem('mosaic-sidebar-open', String(isSidebarOpen));
-  }, [isSidebarOpen]);
-
-  useEffect(() => {
-    api<ProviderInfo[]>('/api/providers')
-      .then((providers) => {
-        const availableModels = providers
-          .filter((provider) => provider.available)
-          .flatMap((provider) => provider.models);
-        setModels(availableModels);
-        setSelectedModelId((current) => current || availableModels[0]?.id || '');
-      })
-      .catch(() => {
-        setModels([]);
-        setSelectedModelId('');
-      });
-  }, []);
-
-  // Load messages when active conversation changes
-  useEffect(() => {
-    if (!activeId) {
-      setMessages([]);
-      return;
-    }
-    // Clear streaming state when switching conversations
-    setIsStreaming(false);
-    setStreamingText('');
-    streamingTextRef.current = '';
-    api<Message[]>(`/api/conversations/${activeId}/messages`)
-      .then(setMessages)
-      .catch(() => {});
-  }, [activeId]);
-
-  // Auto-scroll to bottom
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
-  }, [messages, streamingText]);
-
-  // Socket.io setup — connect once for the page lifetime
-  useEffect(() => {
-    const socket = getSocket();
-
-    function onAgentStart(data: { conversationId: string }): void {
-      // Only update state if the event belongs to the currently viewed conversation
-      if (activeIdRef.current !== data.conversationId) return;
-      setIsStreaming(true);
-      setStreamingText('');
-      streamingTextRef.current = '';
-    }
-
-    function onAgentText(data: { conversationId: string; text: string }): void {
-      if (activeIdRef.current !== data.conversationId) return;
-      streamingTextRef.current += data.text;
-      setStreamingText((prev) => prev + data.text);
-    }
-
-    function onAgentEnd(data: { conversationId: string }): void {
-      if (activeIdRef.current !== data.conversationId) return;
-      const finalText = streamingTextRef.current;
-      setIsStreaming(false);
-      setStreamingText('');
-      streamingTextRef.current = '';
-      // Append the completed assistant message to the local message list.
-      // The Pi agent session is in-memory so the assistant response is not
-      // persisted to the DB — we build the local UI state instead.
-      if (finalText) {
-        setMessages((prev) => [
-          ...prev,
-          {
-            id: `assistant-${Date.now()}`,
-            conversationId: data.conversationId,
-            role: 'assistant' as const,
-            content: finalText,
-            createdAt: new Date().toISOString(),
-          },
-        ]);
-        sidebarRef.current?.refresh();
-      }
-    }
-
-    function onError(data: { error: string; conversationId?: string }): void {
-      setIsStreaming(false);
-      setStreamingText('');
-      streamingTextRef.current = '';
-      setMessages((prev) => [
-        ...prev,
-        {
-          id: `error-${Date.now()}`,
-          conversationId: data.conversationId ?? '',
-          role: 'system' as const,
-          content: `Error: ${data.error}`,
-          createdAt: new Date().toISOString(),
-        },
-      ]);
-    }
-
-    socket.on('agent:start', onAgentStart);
-    socket.on('agent:text', onAgentText);
-    socket.on('agent:end', onAgentEnd);
-    socket.on('error', onError);
-
-    // Connect if not already connected
-    if (!socket.connected) {
-      socket.connect();
-    }
-
-    return () => {
-      socket.off('agent:start', onAgentStart);
-      socket.off('agent:text', onAgentText);
-      socket.off('agent:end', onAgentEnd);
-      socket.off('error', onError);
-      // Fully tear down the socket when the chat page unmounts so we get a
-      // fresh authenticated connection next time the page is visited.
-      destroySocket();
-    };
-  }, []);
-
-  const handleNewConversation = useCallback(async (projectId?: string | null) => {
-    const conv = await api<Conversation>('/api/conversations', {
-      method: 'POST',
-      body: { title: 'New conversation', projectId: projectId ?? null },
-    });
-
-    sidebarRef.current?.addConversation({
-      id: conv.id,
-      title: conv.title,
-      projectId: conv.projectId,
-      updatedAt: conv.updatedAt,
-      archived: conv.archived,
-    });
-
-    setActiveId(conv.id);
-    setMessages([]);
-    setIsSidebarOpen(true);
-  }, []);
-
-  const handleSend = useCallback(
-    async (content: string, options?: { modelId?: string }) => {
-      let convId = activeId;
-
-      // Auto-create conversation if none selected
-      if (!convId) {
-        const autoTitle = content.slice(0, 60);
-        const conv = await api<Conversation>('/api/conversations', {
-          method: 'POST',
-          body: { title: autoTitle },
-        });
-        sidebarRef.current?.addConversation({
-          id: conv.id,
-          title: conv.title,
-          projectId: conv.projectId,
-          updatedAt: conv.updatedAt,
-          archived: conv.archived,
-        });
-        setActiveId(conv.id);
-        convId = conv.id;
-      } else if (messages.length === 0) {
-        // Auto-title the initial placeholder conversation from the first user message.
-        const autoTitle = content.slice(0, 60);
-        api<Conversation>(`/api/conversations/${convId}`, {
-          method: 'PATCH',
-          body: { title: autoTitle },
-        })
-          .then(() => sidebarRef.current?.refresh())
-          .catch(() => {});
-      }
-
-      // Optimistic user message in local UI state
-      setMessages((prev) => [
-        ...prev,
-        {
-          id: `user-${Date.now()}`,
-          conversationId: convId,
-          role: 'user' as const,
-          content,
-          createdAt: new Date().toISOString(),
-        },
-      ]);
-
-      // Persist the user message to the DB so conversation history is
-      // available when the page is reloaded or a new session starts.
-      api<Message>(`/api/conversations/${convId}/messages`, {
-        method: 'POST',
-        body: { role: 'user', content },
-      }).catch(() => {
-        // Non-fatal: the agent can still process the message even if
-        // REST persistence fails.
-      });
-
-      // Send to WebSocket — gateway creates/resumes the agent session and
-      // streams the response back via agent:start / agent:text / agent:end.
-      const socket = getSocket();
-      if (!socket.connected) {
-        socket.connect();
-      }
-      socket.emit('message', {
-        conversationId: convId,
-        content,
-        modelId: (options?.modelId ?? selectedModelId) || undefined,
-      });
-    },
-    [activeId, messages, selectedModelId],
-  );
-
-  return (
-    <div
-      className="-m-6 flex h-[calc(100vh-3.5rem)] overflow-hidden"
-      style={{ background: 'var(--bg-deep, var(--color-surface-bg, #0a0f1a))' }}
-    >
-      <ConversationSidebar
-        ref={sidebarRef}
-        isOpen={isSidebarOpen}
-        onClose={() => setIsSidebarOpen(false)}
-        currentConversationId={activeId}
-        onSelectConversation={(conversationId) => {
-          setActiveId(conversationId);
-          setMessages([]);
-          if (conversationId && window.innerWidth < 768) {
-            setIsSidebarOpen(false);
-          }
-        }}
-        onNewConversation={(projectId) => {
-          void handleNewConversation(projectId);
-        }}
-      />
-
-      <div className="flex min-w-0 flex-1 flex-col">
-        <div
-          className="flex items-center gap-3 border-b px-4 py-3"
-          style={{ borderColor: 'var(--border)' }}
-        >
-          <button
-            type="button"
-            onClick={() => setIsSidebarOpen((open) => !open)}
-            className="rounded-lg border p-2 transition-colors"
-            style={{
-              borderColor: 'var(--border)',
-              background: 'var(--surface)',
-              color: 'var(--text)',
-            }}
-            aria-label={isSidebarOpen ? 'Close conversation sidebar' : 'Open conversation sidebar'}
-          >
-            <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor">
-              <path strokeWidth="2" strokeLinecap="round" d="M4 7h16M4 12h16M4 17h16" />
-            </svg>
-          </button>
-          <div>
-            <h1 className="text-sm font-semibold" style={{ color: 'var(--text)' }}>
-              Mosaic Chat
-            </h1>
-            <p className="text-xs" style={{ color: 'var(--muted)' }}>
-              {activeId ? 'Active conversation selected' : 'Choose or start a conversation'}
-            </p>
-          </div>
-        </div>
-
-        {activeId ? (
-          <>
-            <div className="flex-1 space-y-4 overflow-y-auto p-6">
-              {messages.map((msg) => (
-                <MessageBubble key={msg.id} message={msg} />
-              ))}
-              {isStreaming && <StreamingMessage text={streamingText} />}
-              <div ref={messagesEndRef} />
-            </div>
-            <ChatInput
-              onSend={handleSend}
-              isStreaming={isStreaming}
-              models={models}
-              selectedModelId={selectedModelId}
-              onModelChange={setSelectedModelId}
-            />
-          </>
-        ) : (
-          <div className="flex flex-1 items-center justify-center px-6">
-            <div
-              className="max-w-md rounded-2xl border px-8 py-10 text-center"
-              style={{
-                borderColor: 'var(--border)',
-                background: 'var(--surface)',
-              }}
-            >
-              <h2 className="text-lg font-medium" style={{ color: 'var(--text)' }}>
-                Welcome to Mosaic Chat
-              </h2>
-              <p className="mt-1 text-sm" style={{ color: 'var(--muted)' }}>
-                Select a conversation or start a new one
-              </p>
-              <button
-                type="button"
-                onClick={() => {
-                  void handleNewConversation();
-                }}
-                className="mt-4 rounded-lg px-4 py-2 text-sm font-medium text-white transition-colors"
-                style={{ background: 'var(--primary)' }}
-              >
-                Start new conversation
-              </button>
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}

apps/web/src/app/(dashboard)/layout.tsx

@@ -1,11 +0,0 @@
-import type { ReactNode } from 'react';
-import { AppShell } from '@/components/layout/app-shell';
-import { AuthGuard } from '@/components/auth-guard';
-
-export default function DashboardLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <AuthGuard>
-      <AppShell>{children}</AppShell>
-    </AuthGuard>
-  );
-}

apps/web/src/app/(dashboard)/projects/[id]/page.tsx

@@ -1,338 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useParams, useRouter } from 'next/navigation';
-import { api } from '@/lib/api';
-import { cn } from '@/lib/cn';
-import type { Mission, Project, Task, TaskStatus } from '@/lib/types';
-import { MissionTimeline } from '@/components/projects/mission-timeline';
-import { PrdViewer } from '@/components/projects/prd-viewer';
-import { TaskDetailModal } from '@/components/tasks/task-detail-modal';
-import { TaskListView } from '@/components/tasks/task-list-view';
-import { TaskStatusSummary } from '@/components/tasks/task-status-summary';
-
-type Tab = 'overview' | 'tasks' | 'missions' | 'prd';
-
-const statusColors: Record<string, string> = {
-  active: 'bg-success/20 text-success',
-  paused: 'bg-warning/20 text-warning',
-  completed: 'bg-blue-600/20 text-blue-400',
-  archived: 'bg-gray-600/20 text-gray-400',
-};
-
-interface TabButtonProps {
-  id: Tab;
-  label: string;
-  activeTab: Tab;
-  onClick: (tab: Tab) => void;
-}
-
-function TabButton({ id, label, activeTab, onClick }: TabButtonProps): React.ReactElement {
-  return (
-    <button
-      type="button"
-      onClick={() => onClick(id)}
-      className={cn(
-        'border-b-2 px-4 py-2 text-sm transition-colors',
-        activeTab === id
-          ? 'border-text-primary text-text-primary'
-          : 'border-transparent text-text-muted hover:text-text-secondary',
-      )}
-    >
-      {label}
-    </button>
-  );
-}
-
-export default function ProjectDetailPage(): React.ReactElement {
-  const params = useParams();
-  const router = useRouter();
-  const id = typeof params['id'] === 'string' ? params['id'] : '';
-
-  const [project, setProject] = useState<Project | null>(null);
-  const [missions, setMissions] = useState<Mission[]>([]);
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const [activeTab, setActiveTab] = useState<Tab>('overview');
-  const [taskFilter, setTaskFilter] = useState<TaskStatus | 'all'>('all');
-  const [selectedTask, setSelectedTask] = useState<Task | null>(null);
-
-  useEffect(() => {
-    if (!id) return;
-
-    setLoading(true);
-    setError(null);
-
-    Promise.all([
-      api<Project>(`/api/projects/${id}`),
-      api<Mission[]>('/api/missions').catch(() => [] as Mission[]),
-      api<Task[]>(`/api/tasks?projectId=${id}`).catch(() => [] as Task[]),
-    ])
-      .then(([proj, allMissions, tks]) => {
-        setProject(proj);
-        setMissions(allMissions.filter((m) => m.projectId === id));
-        setTasks(tks);
-      })
-      .catch((err: Error) => {
-        setError(err.message ?? 'Failed to load project');
-      })
-      .finally(() => setLoading(false));
-  }, [id]);
-
-  const handleTaskClick = useCallback((task: Task) => {
-    setSelectedTask(task);
-  }, []);
-
-  const handleCloseTaskModal = useCallback(() => {
-    setSelectedTask(null);
-  }, []);
-
-  if (loading) {
-    return (
-      <div className="py-16 text-center">
-        <p className="text-sm text-text-muted">Loading project...</p>
-      </div>
-    );
-  }
-
-  if (error || !project) {
-    return (
-      <div className="py-16 text-center">
-        <p className="text-sm text-error">{error ?? 'Project not found'}</p>
-        <button
-          type="button"
-          onClick={() => router.push('/projects')}
-          className="mt-4 text-sm text-text-muted underline hover:text-text-secondary"
-        >
-          Back to projects
-        </button>
-      </div>
-    );
-  }
-
-  const filteredTasks = taskFilter === 'all' ? tasks : tasks.filter((t) => t.status === taskFilter);
-
-  const prdContent = getPrdContent(project);
-  const hasPrd = Boolean(prdContent);
-
-  const tabs: { id: Tab; label: string }[] = [
-    { id: 'overview', label: 'Overview' },
-    { id: 'tasks', label: `Tasks (${tasks.length})` },
-    { id: 'missions', label: `Missions (${missions.length})` },
-    ...(hasPrd ? [{ id: 'prd' as Tab, label: 'PRD' }] : []),
-  ];
-
-  return (
-    <div>
-      {/* Breadcrumb */}
-      <nav className="mb-4 flex items-center gap-2 text-sm text-text-muted">
-        <button
-          type="button"
-          onClick={() => router.push('/projects')}
-          className="hover:text-text-secondary"
-        >
-          Projects
-        </button>
-        <span>/</span>
-        <span className="text-text-primary">{project.name}</span>
-      </nav>
-
-      {/* Project header */}
-      <div className="mb-6 flex items-start justify-between gap-4">
-        <div>
-          <div className="flex items-center gap-3">
-            <h1 className="text-2xl font-semibold text-text-primary">{project.name}</h1>
-            <span
-              className={cn(
-                'rounded-full px-2 py-0.5 text-xs',
-                statusColors[project.status] ?? 'bg-gray-600/20 text-gray-400',
-              )}
-            >
-              {project.status}
-            </span>
-          </div>
-          {project.description && (
-            <p className="mt-1 text-sm text-text-muted">{project.description}</p>
-          )}
-          <p className="mt-2 text-xs text-text-muted">
-            Created {new Date(project.createdAt).toLocaleDateString()} · Updated{' '}
-            {new Date(project.updatedAt).toLocaleDateString()}
-          </p>
-        </div>
-      </div>
-
-      {/* Stats bar */}
-      <div className="mb-6 grid grid-cols-2 gap-3 sm:grid-cols-4">
-        <StatCard label="Tasks" value={String(tasks.length)} />
-        <StatCard
-          label="Done"
-          value={String(tasks.filter((t) => t.status === 'done').length)}
-          valueClass="text-success"
-        />
-        <StatCard
-          label="In Progress"
-          value={String(tasks.filter((t) => t.status === 'in-progress').length)}
-          valueClass="text-blue-400"
-        />
-        <StatCard
-          label="Blocked"
-          value={String(tasks.filter((t) => t.status === 'blocked').length)}
-          valueClass={tasks.some((t) => t.status === 'blocked') ? 'text-error' : undefined}
-        />
-      </div>
-
-      {/* Tabs */}
-      <div className="mb-6 flex gap-0 border-b border-surface-border">
-        {tabs.map((tab) => (
-          <TabButton
-            key={tab.id}
-            id={tab.id}
-            label={tab.label}
-            activeTab={activeTab}
-            onClick={setActiveTab}
-          />
-        ))}
-      </div>
-
-      {/* Tab content */}
-      {activeTab === 'overview' && (
-        <OverviewTab project={project} missions={missions} tasks={tasks} />
-      )}
-
-      {activeTab === 'tasks' && (
-        <div>
-          <div className="mb-4">
-            <TaskStatusSummary
-              tasks={tasks}
-              activeFilter={taskFilter}
-              onFilterChange={setTaskFilter}
-            />
-          </div>
-          <TaskListView tasks={filteredTasks} onTaskClick={handleTaskClick} />
-        </div>
-      )}
-
-      {activeTab === 'missions' && <MissionTimeline missions={missions} />}
-
-      {activeTab === 'prd' && prdContent && (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-6">
-          <PrdViewer content={prdContent} />
-        </div>
-      )}
-
-      {/* Task detail modal */}
-      {selectedTask && <TaskDetailModal task={selectedTask} onClose={handleCloseTaskModal} />}
-    </div>
-  );
-}
-
-interface OverviewTabProps {
-  project: Project;
-  missions: Mission[];
-  tasks: Task[];
-}
-
-function OverviewTab({ project, missions, tasks }: OverviewTabProps): React.ReactElement {
-  const recentTasks = [...tasks]
-    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
-    .slice(0, 5);
-
-  return (
-    <div className="grid gap-6 lg:grid-cols-2">
-      {/* Recent tasks */}
-      <section>
-        <h2 className="mb-3 text-sm font-semibold text-text-secondary">Recent Tasks</h2>
-        {recentTasks.length === 0 ? (
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
-            <p className="text-sm text-text-muted">No tasks yet</p>
-          </div>
-        ) : (
-          <div className="space-y-2">
-            {recentTasks.map((task) => (
-              <TaskSummaryRow key={task.id} task={task} />
-            ))}
-          </div>
-        )}
-      </section>
-
-      {/* Mission summary */}
-      <section>
-        <h2 className="mb-3 text-sm font-semibold text-text-secondary">Missions</h2>
-        {missions.length === 0 ? (
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
-            <p className="text-sm text-text-muted">No missions yet</p>
-          </div>
-        ) : (
-          <MissionTimeline missions={missions.slice(0, 4)} />
-        )}
-      </section>
-
-      {/* Metadata */}
-      {project.metadata && Object.keys(project.metadata).length > 0 && (
-        <section className="lg:col-span-2">
-          <h2 className="mb-3 text-sm font-semibold text-text-secondary">Project Metadata</h2>
-          <div className="rounded-lg border border-surface-border bg-surface-card p-4">
-            <pre className="overflow-x-auto text-xs text-text-muted">
-              {JSON.stringify(project.metadata, null, 2)}
-            </pre>
-          </div>
-        </section>
-      )}
-    </div>
-  );
-}
-
-const taskStatusColors: Record<string, string> = {
-  'not-started': 'bg-gray-600/20 text-gray-300',
-  'in-progress': 'bg-blue-600/20 text-blue-400',
-  blocked: 'bg-error/20 text-error',
-  done: 'bg-success/20 text-success',
-  cancelled: 'bg-gray-600/20 text-gray-500',
-};
-
-function TaskSummaryRow({ task }: { task: Task }): React.ReactElement {
-  return (
-    <div className="flex items-center justify-between gap-2 rounded-lg border border-surface-border bg-surface-card px-3 py-2">
-      <span className="truncate text-sm text-text-primary">{task.title}</span>
-      <span
-        className={cn(
-          'shrink-0 rounded-full px-2 py-0.5 text-xs',
-          taskStatusColors[task.status] ?? 'bg-gray-600/20 text-gray-400',
-        )}
-      >
-        {task.status}
-      </span>
-    </div>
-  );
-}
-
-function StatCard({
-  label,
-  value,
-  valueClass,
-}: {
-  label: string;
-  value: string;
-  valueClass?: string;
-}): React.ReactElement {
-  return (
-    <div className="rounded-lg border border-surface-border bg-surface-card p-3">
-      <p className="text-xs text-text-muted">{label}</p>
-      <p className={cn('mt-1 text-lg font-semibold', valueClass ?? 'text-text-primary')}>{value}</p>
-    </div>
-  );
-}
-
-function getPrdContent(project: Project): string | null {
-  if (!project.metadata) return null;
-
-  const prd = project.metadata['prd'];
-  if (typeof prd === 'string' && prd.trim().length > 0) return prd;
-
-  const prdContent = project.metadata['prdContent'];
-  if (typeof prdContent === 'string' && prdContent.trim().length > 0) return prdContent;
-
-  return null;
-}

apps/web/src/app/(dashboard)/projects/page.tsx

@@ -1,101 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { useRouter } from 'next/navigation';
-import { api } from '@/lib/api';
-import type { Project } from '@/lib/types';
-import { ProjectCard } from '@/components/projects/project-card';
-
-export default function ProjectsPage(): React.ReactElement {
-  const [projects, setProjects] = useState<Project[]>([]);
-  const [loading, setLoading] = useState(true);
-  const router = useRouter();
-
-  useEffect(() => {
-    api<Project[]>('/api/projects')
-      .then(setProjects)
-      .catch(() => {})
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleProjectClick = useCallback(
-    (project: Project) => {
-      router.push(`/projects/${project.id}`);
-    },
-    [router],
-  );
-
-  return (
-    <div>
-      <div className="mb-6 flex items-center justify-between">
-        <h1 className="text-2xl font-semibold">Projects</h1>
-      </div>
-
-      {loading ? (
-        <p className="py-8 text-center text-sm text-text-muted">Loading projects...</p>
-      ) : projects.length === 0 ? (
-        <div className="py-12 text-center">
-          <h2 className="text-lg font-medium text-text-secondary">No projects yet</h2>
-          <p className="mt-1 text-sm text-text-muted">
-            Projects will appear here when created via the gateway API
-          </p>
-        </div>
-      ) : (
-        <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {projects.map((project) => (
-            <ProjectCard key={project.id} project={project} onClick={handleProjectClick} />
-          ))}
-        </div>
-      )}
-
-      {/* Mission status section */}
-      <MissionStatus />
-    </div>
-  );
-}
-
-function MissionStatus(): React.ReactElement {
-  const [mission, setMission] = useState<Record<string, unknown> | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    api<Record<string, unknown>>('/api/coord/status')
-      .then(setMission)
-      .catch(() => setMission(null))
-      .finally(() => setLoading(false));
-  }, []);
-
-  return (
-    <section className="mt-8">
-      <h2 className="mb-4 text-lg font-semibold">Active Mission</h2>
-      {loading ? (
-        <p className="text-sm text-text-muted">Loading mission status...</p>
-      ) : !mission ? (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-6 text-center">
-          <p className="text-sm text-text-muted">No active mission detected</p>
-        </div>
-      ) : (
-        <div className="rounded-lg border border-surface-border bg-surface-card p-4">
-          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
-            <StatCard label="Mission" value={String(mission['missionId'] ?? 'Unknown')} />
-            <StatCard label="Phase" value={String(mission['currentPhase'] ?? '—')} />
-            <StatCard
-              label="Tasks"
-              value={`${mission['completedTasks'] ?? 0} / ${mission['totalTasks'] ?? 0}`}
-            />
-            <StatCard label="Status" value={String(mission['status'] ?? '—')} />
-          </div>
-        </div>
-      )}
-    </section>
-  );
-}
-
-function StatCard({ label, value }: { label: string; value: string }): React.ReactElement {
-  return (
-    <div className="rounded-lg bg-surface-elevated p-3">
-      <p className="text-xs text-text-muted">{label}</p>
-      <p className="mt-1 text-sm font-medium text-text-primary">{value}</p>
-    </div>
-  );
-}

apps/web/src/app/(dashboard)/tasks/page.tsx

@@ -1,72 +0,0 @@
-'use client';
-
-import { useCallback, useEffect, useState } from 'react';
-import { api } from '@/lib/api';
-import { cn } from '@/lib/cn';
-import type { Task } from '@/lib/types';
-import { KanbanBoard } from '@/components/tasks/kanban-board';
-import { TaskListView } from '@/components/tasks/task-list-view';
-
-type ViewMode = 'list' | 'kanban';
-
-export default function TasksPage(): React.ReactElement {
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [view, setView] = useState<ViewMode>('kanban');
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    api<Task[]>('/api/tasks')
-      .then(setTasks)
-      .catch(() => {})
-      .finally(() => setLoading(false));
-  }, []);
-
-  const handleTaskClick = useCallback((task: Task) => {
-    // Task detail view will be added in future iteration
-    console.log('Task clicked:', task.id);
-  }, []);
-
-  return (
-    <div>
-      <div className="mb-6 flex items-center justify-between">
-        <h1 className="text-2xl font-semibold">Tasks</h1>
-        <div className="flex items-center gap-2">
-          <div className="flex rounded-lg border border-surface-border">
-            <button
-              type="button"
-              onClick={() => setView('list')}
-              className={cn(
-                'px-3 py-1.5 text-xs transition-colors',
-                view === 'list'
-                  ? 'bg-surface-elevated text-text-primary'
-                  : 'text-text-muted hover:text-text-secondary',
-              )}
-            >
-              List
-            </button>
-            <button
-              type="button"
-              onClick={() => setView('kanban')}
-              className={cn(
-                'px-3 py-1.5 text-xs transition-colors',
-                view === 'kanban'
-                  ? 'bg-surface-elevated text-text-primary'
-                  : 'text-text-muted hover:text-text-secondary',
-              )}
-            >
-              Kanban
-            </button>
-          </div>
-        </div>
-      </div>
-
-      {loading ? (
-        <p className="py-8 text-center text-sm text-text-muted">Loading tasks...</p>
-      ) : view === 'kanban' ? (
-        <KanbanBoard tasks={tasks} onTaskClick={handleTaskClick} />
-      ) : (
-        <TaskListView tasks={tasks} onTaskClick={handleTaskClick} />
-      )}
-    </div>
-  );
-}

apps/web/src/app/auth/provider/[provider]/page.tsx

@@ -1,95 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { useEffect, useState } from 'react';
-import { useParams, useSearchParams } from 'next/navigation';
-import { api } from '@/lib/api';
-import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
-import { signIn } from '@/lib/auth-client';
-import type { SsoProviderDiscovery } from '@/lib/sso';
-
-export default function AuthProviderRedirectPage(): React.ReactElement {
-  const params = useParams<{ provider: string }>();
-  const searchParams = useSearchParams();
-  const providerId = typeof params.provider === 'string' ? params.provider : '';
-  const requestedCallbackURL = searchParams.get('callbackURL');
-  const [providerName, setProviderName] = useState<string | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    async function redirectToProvider(): Promise<void> {
-      try {
-        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
-        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
-        if (cancelled) return;
-
-        const provider = providers.find((candidate) => candidate.id === providerId);
-        if (!provider) {
-          setError('Unknown SSO provider.');
-          return;
-        }
-
-        setProviderName(provider.name);
-        if (!provider.configured) {
-          setError(`${provider.name} is not enabled in this deployment.`);
-          return;
-        }
-        if (provider.loginMode !== 'oidc') {
-          setError(`${provider.name} is not available for OIDC sign in.`);
-          return;
-        }
-
-        const result = await signIn.oauth2({
-          providerId: provider.id,
-          callbackURL,
-        });
-
-        if (!cancelled && result?.error) {
-          setError(result.error.message ?? `${provider.name} sign in failed.`);
-        }
-      } catch (caught: unknown) {
-        if (!cancelled) {
-          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
-        }
-      }
-    }
-
-    void redirectToProvider();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [providerId, requestedCallbackURL]);
-
-  return (
-    <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
-      <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
-      <p className="mt-2 text-sm text-text-secondary">
-        {providerName
-          ? `Redirecting you to ${providerName}...`
-          : 'Preparing your sign-in request...'}
-      </p>
-
-      {error ? (
-        <div
-          role="alert"
-          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
-        >
-          <p>{error}</p>
-          <Link
-            href="/login"
-            className="mt-3 inline-block font-medium text-blue-400 hover:text-blue-300"
-          >
-            Return to login
-          </Link>
-        </div>
-      ) : (
-        <div className="mt-6 rounded-lg border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-secondary">
-          If the redirect does not start automatically, return to the login page and try again.
-        </div>
-      )}
-    </div>
-  );
-}

apps/web/src/app/layout.tsx

@@ -1,41 +0,0 @@
-import type { Metadata } from 'next';
-import type { ReactNode } from 'react';
-import { ThemeProvider } from '@/providers/theme-provider';
-import './globals.css';
-
-export const metadata: Metadata = {
-  title: 'Mosaic',
-  description: 'Mosaic Stack Dashboard',
-};
-
-function themeScript(): string {
-  return `
-    (function () {
-      try {
-        var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
-        document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
-      } catch (error) {
-        document.documentElement.setAttribute('data-theme', 'dark');
-      }
-    })();
-  `;
-}
-
-export default function RootLayout({ children }: { children: ReactNode }): React.ReactElement {
-  return (
-    <html lang="en" suppressHydrationWarning>
-      <head>
-        <link rel="preconnect" href="https://fonts.googleapis.com" />
-        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
-        <link
-          rel="stylesheet"
-          href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
-        />
-        <script dangerouslySetInnerHTML={{ __html: themeScript() }} />
-      </head>
-      <body>
-        <ThemeProvider>{children}</ThemeProvider>
-      </body>
-    </html>
-  );
-}

apps/web/src/app/page.tsx

@@ -1,5 +0,0 @@
-import { redirect } from 'next/navigation';
-
-export default function HomePage(): never {
-  redirect('/chat');
-}

apps/web/src/components/admin-role-guard.tsx

@@ -1,40 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface AdminRoleGuardProps {
-  children: React.ReactNode;
-}
-
-export function AdminRoleGuard({ children }: AdminRoleGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  const user = session?.user as
-    | (NonNullable<typeof session>['user'] & { role?: string })
-    | undefined;
-
-  useEffect(() => {
-    if (!isPending && !session) {
-      router.replace('/login');
-    } else if (!isPending && session && user?.role !== 'admin') {
-      router.replace('/');
-    }
-  }, [isPending, session, user?.role, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (!session || user?.role !== 'admin') {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/auth-guard.tsx

@@ -1,34 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface AuthGuardProps {
-  children: React.ReactNode;
-}
-
-export function AuthGuard({ children }: AuthGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!isPending && !session) {
-      router.replace('/login');
-    }
-  }, [isPending, session, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (!session) {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/chat/chat-input.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useEffect, useMemo, useRef, useState } from 'react';
 import type { ModelInfo } from '@/lib/types';
 

apps/web/src/components/chat/conversation-list.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useCallback, useRef, useState } from 'react';
 import { cn } from '@/lib/cn';
 import type { Conversation } from '@/lib/types';

apps/web/src/components/chat/conversation-sidebar.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import {
   forwardRef,
   useCallback,

apps/web/src/components/chat/message-bubble.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useCallback, useMemo, useState } from 'react';
 import ReactMarkdown from 'react-markdown';
 import { cn } from '@/lib/cn';

apps/web/src/components/chat/streaming-message.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useEffect, useMemo, useState } from 'react';
 
 interface StreamingMessageProps {

apps/web/src/components/freshness/freshness-notices.tsx

@@ -0,0 +1,108 @@
+import type { ReactElement } from 'react';
+import { formatAge, type FreshnessLabel } from '@/lib/freshness/model';
+
+/**
+ * Rendering rules for non-current freshness states (RI-5-001).
+ *
+ * - `unavailable` renders an explicit failure panel — never an empty
+ *   healthy collection.
+ * - `stale` may render last-known data, but only under a visible label
+ *   carrying source identity, snapshot version, and age.
+ * - `partial` renders the verified parts plus an explicit list of what is
+ *   missing.
+ */
+
+interface RetryableNoticeProps {
+  readonly onRetry?: () => void;
+  readonly retryLabel?: string;
+}
+
+function RetryButton({ onRetry, retryLabel }: RetryableNoticeProps): ReactElement | null {
+  if (!onRetry) return null;
+  return (
+    <button
+      type="button"
+      onClick={onRetry}
+      className="mt-2 rounded-lg border border-surface-border px-3 py-1.5 text-xs transition-colors hover:border-gray-500"
+    >
+      {retryLabel ?? 'Retry'}
+    </button>
+  );
+}
+
+export interface UnavailableDataNoticeProps extends RetryableNoticeProps {
+  /** What is unavailable, e.g. "Tasks". */
+  readonly title: string;
+  /** Optional underlying failure detail (network message, invalidation reason). */
+  readonly detail?: string | null;
+}
+
+/** Explicit `unavailable` state. Never renders as an empty healthy collection. */
+export function UnavailableDataNotice({
+  title,
+  detail,
+  onRetry,
+  retryLabel,
+}: UnavailableDataNoticeProps): ReactElement {
+  return (
+    <div role="alert" className="rounded-lg border border-error/40 px-4 py-3 text-sm">
+      <p className="font-medium text-text-primary">{title} are unavailable</p>
+      <p className="mt-1 text-text-muted">
+        This is not an empty result — the data could not be verified from the gateway.
+        {detail ? ` ${detail}` : ''}
+      </p>
+      <RetryButton onRetry={onRetry} retryLabel={retryLabel} />
+    </div>
+  );
+}
+
+export interface StaleDataNoticeProps extends RetryableNoticeProps {
+  /** Provenance of the last-known snapshot being displayed. */
+  readonly label: FreshnessLabel;
+}
+
+/**
+ * Situational-awareness banner for `stale` data: last-known data may render,
+ * but visibly labeled with source identity, snapshot version, and age.
+ */
+export function StaleDataNotice({
+  label,
+  onRetry,
+  retryLabel,
+}: StaleDataNoticeProps): ReactElement {
+  return (
+    <div role="status" className="rounded-lg border border-warning/40 px-4 py-3 text-sm">
+      <p className="font-medium text-warning">Showing last-known data — it may be out of date</p>
+      <p className="mt-1 text-xs text-text-muted">
+        Source {label.source} · snapshot v{label.version} · fetched{' '}
+        {formatAge(label.fetchedAt, Date.now())}. Verdicts derived from this data are unknown and
+        changes are disabled until it is revalidated.
+      </p>
+      <RetryButton onRetry={onRetry} retryLabel={retryLabel ?? 'Revalidate'} />
+    </div>
+  );
+}
+
+export interface PartialDataNoticeProps extends RetryableNoticeProps {
+  /** Display names of the sections whose collections are unavailable. */
+  readonly missing: readonly string[];
+}
+
+/** `partial` surface banner: verified parts render, missing parts are explicit. */
+export function PartialDataNotice({
+  missing,
+  onRetry,
+  retryLabel,
+}: PartialDataNoticeProps): ReactElement {
+  return (
+    <div role="status" className="rounded-lg border border-warning/40 px-4 py-3 text-sm">
+      <p className="font-medium text-warning">Some data could not be loaded</p>
+      <p className="mt-1 text-xs text-text-muted">
+        {missing.join(', ')} {missing.length === 1 ? 'is' : 'are'} unavailable — sections below show
+        an explicit unavailable state instead of an empty list. Derived verdicts remain unknown
+        until every collection is revalidated.
+      </p>
+      <RetryButton onRetry={onRetry} retryLabel={retryLabel ?? 'Revalidate'} />
+    </div>
+  );
+}

apps/web/src/components/guest-guard.tsx

@@ -1,35 +0,0 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
-import { useEffect } from 'react';
-import { useSession } from '@/lib/auth-client';
-
-interface GuestGuardProps {
-  children: React.ReactNode;
-}
-
-/** Redirects authenticated users away from auth pages. */
-export function GuestGuard({ children }: GuestGuardProps): React.ReactElement | null {
-  const { data: session, isPending } = useSession();
-  const router = useRouter();
-
-  useEffect(() => {
-    if (!isPending && session) {
-      router.replace('/chat');
-    }
-  }, [isPending, session, router]);
-
-  if (isPending) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <div className="text-sm text-text-muted">Loading...</div>
-      </div>
-    );
-  }
-
-  if (session) {
-    return null;
-  }
-
-  return <>{children}</>;
-}

apps/web/src/components/layout/app-header.tsx

@@ -1,239 +0,0 @@
-'use client';
-
-import Link from 'next/link';
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { signOut, useSession } from '@/lib/auth-client';
-
-interface AppHeaderProps {
-  conversationTitle?: string | null;
-  isSidebarOpen: boolean;
-  onToggleSidebar: () => void;
-}
-
-type ThemeMode = 'dark' | 'light';
-
-const THEME_STORAGE_KEY = 'mosaic-chat-theme';
-
-export function AppHeader({
-  conversationTitle,
-  isSidebarOpen,
-  onToggleSidebar,
-}: AppHeaderProps): React.ReactElement {
-  const { data: session } = useSession();
-  const [currentTime, setCurrentTime] = useState('');
-  const [version, setVersion] = useState<string | null>(null);
-  const [menuOpen, setMenuOpen] = useState(false);
-  const [theme, setTheme] = useState<ThemeMode>('dark');
-
-  useEffect(() => {
-    function updateTime(): void {
-      setCurrentTime(
-        new Date().toLocaleTimeString([], {
-          hour: '2-digit',
-          minute: '2-digit',
-        }),
-      );
-    }
-
-    updateTime();
-    const interval = window.setInterval(updateTime, 60_000);
-    return () => window.clearInterval(interval);
-  }, []);
-
-  useEffect(() => {
-    fetch('/version.json')
-      .then(async (res) => res.json() as Promise<{ version?: string; commit?: string }>)
-      .then((data) => {
-        if (data.version) {
-          setVersion(data.commit ? `${data.version}+${data.commit}` : data.version);
-        }
-      })
-      .catch(() => setVersion(null));
-  }, []);
-
-  useEffect(() => {
-    const storedTheme = window.localStorage.getItem(THEME_STORAGE_KEY);
-    const nextTheme = storedTheme === 'light' ? 'light' : 'dark';
-    applyTheme(nextTheme);
-    setTheme(nextTheme);
-  }, []);
-
-  const handleThemeToggle = useCallback(() => {
-    const nextTheme = theme === 'dark' ? 'light' : 'dark';
-    applyTheme(nextTheme);
-    window.localStorage.setItem(THEME_STORAGE_KEY, nextTheme);
-    setTheme(nextTheme);
-  }, [theme]);
-
-  const handleSignOut = useCallback(async (): Promise<void> => {
-    await signOut();
-    window.location.href = '/login';
-  }, []);
-
-  const userLabel = session?.user.name ?? session?.user.email ?? 'Mosaic User';
-  const initials = useMemo(() => getInitials(userLabel), [userLabel]);
-
-  return (
-    <header
-      className="sticky top-0 z-20 border-b backdrop-blur-xl"
-      style={{
-        backgroundColor: 'color-mix(in srgb, var(--color-surface) 82%, transparent)',
-        borderColor: 'var(--color-border)',
-      }}
-    >
-      <div className="flex items-center justify-between gap-3 px-4 py-3 md:px-6">
-        <div className="flex min-w-0 items-center gap-3">
-          <button
-            type="button"
-            onClick={onToggleSidebar}
-            className="inline-flex h-10 w-10 items-center justify-center rounded-2xl border transition-colors hover:bg-white/5"
-            style={{ borderColor: 'var(--color-border)', color: 'var(--color-text)' }}
-            aria-label="Toggle conversation sidebar"
-            aria-expanded={isSidebarOpen}
-          >
-            ☰
-          </button>
-
-          <Link href="/chat" className="flex min-w-0 items-center gap-3">
-            <div
-              className="flex h-10 w-10 items-center justify-center rounded-2xl text-sm font-semibold text-white shadow-[var(--shadow-ms-md)]"
-              style={{
-                background:
-                  'linear-gradient(135deg, var(--color-ms-blue-500), var(--color-ms-teal-500))',
-              }}
-            >
-              M
-            </div>
-            <div className="flex min-w-0 items-center gap-3">
-              <div className="text-sm font-semibold text-[var(--color-text)]">Mosaic</div>
-              <div className="hidden h-5 w-px bg-[var(--color-border)] md:block" />
-              <div className="hidden items-center gap-2 md:flex">
-                <span className="relative flex h-2.5 w-2.5">
-                  <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-[var(--color-ms-teal-500)] opacity-60" />
-                  <span className="relative inline-flex h-2.5 w-2.5 rounded-full bg-[var(--color-ms-teal-500)]" />
-                </span>
-                <span className="text-xs uppercase tracking-[0.18em] text-[var(--color-muted)]">
-                  Online
-                </span>
-              </div>
-            </div>
-          </Link>
-        </div>
-
-        <div className="hidden min-w-0 items-center gap-3 md:flex">
-          <div className="rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-text-2)]">
-            {currentTime || '--:--'}
-          </div>
-          <div className="max-w-[24rem] truncate text-sm font-medium text-[var(--color-text)]">
-            {conversationTitle?.trim() || 'New Session'}
-          </div>
-          {version ? (
-            <div className="rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-muted)]">
-              v{version}
-            </div>
-          ) : null}
-        </div>
-
-        <div className="flex items-center gap-2">
-          <div className="hidden items-center gap-2 lg:flex">
-            <ShortcutHint label="⌘/" text="focus" />
-            <ShortcutHint label="⌘K" text="focus" />
-          </div>
-
-          <button
-            type="button"
-            onClick={handleThemeToggle}
-            className="inline-flex h-10 items-center justify-center rounded-2xl border px-3 text-sm transition-colors hover:bg-white/5"
-            style={{ borderColor: 'var(--color-border)', color: 'var(--color-text)' }}
-            aria-label="Toggle theme"
-          >
-            {theme === 'dark' ? '☀︎' : '☾'}
-          </button>
-
-          <div className="relative">
-            <button
-              type="button"
-              onClick={() => setMenuOpen((prev) => !prev)}
-              className="inline-flex h-10 w-10 items-center justify-center rounded-full border text-sm font-semibold transition-colors hover:bg-white/5"
-              style={{
-                backgroundColor: 'var(--color-surface-2)',
-                borderColor: 'var(--color-border)',
-                color: 'var(--color-text)',
-              }}
-              aria-expanded={menuOpen}
-              aria-label="Open user menu"
-            >
-              {session?.user.image ? (
-                <img
-                  src={session.user.image}
-                  alt={userLabel}
-                  className="h-full w-full rounded-full object-cover"
-                />
-              ) : (
-                initials
-              )}
-            </button>
-            {menuOpen ? (
-              <div
-                className="absolute right-0 top-12 min-w-56 rounded-3xl border p-2 shadow-[var(--shadow-ms-lg)]"
-                style={{
-                  backgroundColor: 'var(--color-surface)',
-                  borderColor: 'var(--color-border)',
-                }}
-              >
-                <div className="border-b px-3 py-2" style={{ borderColor: 'var(--color-border)' }}>
-                  <div className="text-sm font-medium text-[var(--color-text)]">{userLabel}</div>
-                  {session?.user.email ? (
-                    <div className="text-xs text-[var(--color-muted)]">{session.user.email}</div>
-                  ) : null}
-                </div>
-                <div className="p-1">
-                  <Link
-                    href="/settings"
-                    className="flex rounded-2xl px-3 py-2 text-sm text-[var(--color-text-2)] transition-colors hover:bg-white/5"
-                    onClick={() => setMenuOpen(false)}
-                  >
-                    Settings
-                  </Link>
-                  <button
-                    type="button"
-                    onClick={() => void handleSignOut()}
-                    className="flex w-full rounded-2xl px-3 py-2 text-left text-sm text-[var(--color-text-2)] transition-colors hover:bg-white/5"
-                  >
-                    Sign out
-                  </button>
-                </div>
-              </div>
-            ) : null}
-          </div>
-        </div>
-      </div>
-    </header>
-  );
-}
-
-function ShortcutHint({ label, text }: { label: string; text: string }): React.ReactElement {
-  return (
-    <span className="inline-flex items-center gap-2 rounded-full border border-[var(--color-border)] px-3 py-1.5 text-xs text-[var(--color-muted)]">
-      <span className="font-medium text-[var(--color-text-2)]">{label}</span>
-      <span>{text}</span>
-    </span>
-  );
-}
-
-function getInitials(label: string): string {
-  const words = label.split(/\s+/).filter(Boolean).slice(0, 2);
-  if (words.length === 0) return 'M';
-  return words.map((word) => word.charAt(0).toUpperCase()).join('');
-}
-
-function applyTheme(theme: ThemeMode): void {
-  const root = document.documentElement;
-  if (theme === 'light') {
-    root.setAttribute('data-theme', 'light');
-    root.classList.remove('dark');
-  } else {
-    root.removeAttribute('data-theme');
-    root.classList.add('dark');
-  }
-}

apps/web/src/components/layout/app-shell.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import type { ReactNode } from 'react';
 import { SidebarProvider, useSidebar } from './sidebar-context';
 import { Sidebar } from './sidebar';

apps/web/src/components/layout/sidebar-context.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 
 interface SidebarContextValue {

apps/web/src/components/layout/sidebar.tsx

@@ -1,7 +1,4 @@
-'use client';
-
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
+import { Link, useLocation } from 'react-router-dom';
 import { cn } from '@/lib/cn';
 import { MosaicLogo } from '@/components/ui/mosaic-logo';
 import { useSidebar } from './sidebar-context';
@@ -99,7 +96,7 @@ const navItems: NavItem[] = [
 ];
 
 export function Sidebar(): React.ReactElement {
-  const pathname = usePathname();
+  const { pathname } = useLocation();
   const { mobileOpen, setMobileOpen } = useSidebar();
 
   return (
@@ -137,7 +134,7 @@ export function Sidebar(): React.ReactElement {
               return (
                 <Link
                   key={item.href}
-                  href={item.href}
+                  to={item.href}
                   onClick={() => setMobileOpen(false)}
                   className={cn(
                     'group flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm transition-all duration-150',

apps/web/src/components/layout/theme-toggle.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useTheme } from '@/providers/theme-provider';
 
 interface ThemeToggleProps {

apps/web/src/components/layout/topbar.tsx

@@ -1,6 +1,4 @@
-'use client';
-
-import { useRouter } from 'next/navigation';
+import { useNavigate } from 'react-router-dom';
 import { signOut, useSession } from '@/lib/auth-client';
 import { ThemeToggle } from './theme-toggle';
 import { useSidebar } from './sidebar-context';
@@ -22,12 +20,12 @@ function MenuIcon(): React.JSX.Element {
 
 export function Topbar(): React.ReactElement {
   const { data: session } = useSession();
-  const router = useRouter();
+  const navigate = useNavigate();
   const { isMobile, mobileOpen, setMobileOpen, toggleCollapsed } = useSidebar();
 
   async function handleSignOut(): Promise<void> {
     await signOut();
-    router.replace('/login');
+    navigate('/login', { replace: true });
   }
 
   function handleSidebarToggle(): void {

apps/web/src/components/projects/mission-timeline.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { cn } from '@/lib/cn';
 import type { Mission, MissionStatus } from '@/lib/types';
 

apps/web/src/components/projects/prd-viewer.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 interface PrdViewerProps {
   content: string;
 }

apps/web/src/components/projects/project-card.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { cn } from '@/lib/cn';
 import type { Project } from '@/lib/types';
 

apps/web/src/components/tasks/kanban-board.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import type { Task, TaskStatus } from '@/lib/types';
 import { TaskCard } from './task-card';
 

apps/web/src/components/tasks/task-card.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { cn } from '@/lib/cn';
 import type { Task } from '@/lib/types';
 

apps/web/src/components/tasks/task-detail-modal.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { useEffect, useRef } from 'react';
 import type { ReactNode } from 'react';
 import { cn } from '@/lib/cn';

apps/web/src/components/tasks/task-list-view.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { cn } from '@/lib/cn';
 import type { Task } from '@/lib/types';
 

apps/web/src/components/tasks/task-status-summary.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { cn } from '@/lib/cn';
 import type { Task, TaskStatus } from '@/lib/types';
 

apps/web/src/components/ui/mosaic-logo.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import type { CSSProperties } from 'react';
 
 export interface MosaicLogoProps {

apps/web/src/lib/freshness/model.spec.ts

@@ -0,0 +1,324 @@
+import { describe, expect, it } from 'vitest';
+import type { Task } from '@/lib/types';
+import {
+  acceptSnapshot,
+  assertMutable,
+  canMutate,
+  combineFreshness,
+  computeDigest,
+  computeFreshness,
+  DEFAULT_FRESHNESS_POLICY,
+  formatAge,
+  type FreshSnapshot,
+  invalidationReasonLabels,
+  StaleMutationError,
+  UNKNOWN_VERDICT,
+  verdictValue,
+} from './model';
+import { validateProjectCollection, validateTaskCollection } from './validators';
+
+const NOW = 1_800_000_000_000;
+
+const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 };
+
+const taskPayload: Task[] = [
+  {
+    id: 'task-1',
+    title: 'T1',
+    description: null,
+    status: 'not-started',
+    priority: 'high',
+    projectId: 'project-1',
+    missionId: null,
+    assignee: null,
+    tags: null,
+    dueDate: null,
+    metadata: null,
+    createdAt: '2026-08-01T00:00:00.000Z',
+    updatedAt: '2026-08-01T00:00:00.000Z',
+  },
+];
+
+function acceptedTaskSnapshot(
+  overrides: Partial<FreshSnapshot<typeof taskPayload>> = {},
+): FreshSnapshot<typeof taskPayload> {
+  const result = acceptSnapshot({
+    value: taskPayload,
+    validate: validateTaskCollection,
+    previous: null,
+    policy,
+    source: 'gateway:/api/tasks',
+    now: NOW,
+  });
+  if (result.outcome !== 'accepted') {
+    throw new Error(`fixture setup failed: ${result.reason}`);
+  }
+  return { ...result.snapshot, ...overrides };
+}
+
+describe('computeFreshness', () => {
+  it('treats a missing snapshot as unavailable, never as an empty healthy collection', () => {
+    expect(computeFreshness({ snapshot: null, policy, now: NOW })).toBe('unavailable');
+  });
+
+  it('returns current for a fresh verified snapshot regardless of data emptiness', () => {
+    const empty = acceptSnapshot({
+      value: [],
+      validate: validateTaskCollection,
+      previous: null,
+      policy,
+      source: 'gateway:/api/tasks',
+      now: NOW,
+    });
+    if (empty.outcome !== 'accepted') throw new Error('expected acceptance');
+    expect(computeFreshness({ snapshot: empty.snapshot, policy, now: NOW })).toBe('current');
+  });
+
+  it('degrades to stale once the snapshot ages past staleAfterMs', () => {
+    const snapshot = acceptedTaskSnapshot();
+    expect(computeFreshness({ snapshot, policy, now: NOW + 60_001 })).toBe('stale');
+    expect(computeFreshness({ snapshot, policy, now: NOW + 59_999 })).toBe('current');
+  });
+
+  it('degrades to stale when the latest revalidation failed', () => {
+    const snapshot = acceptedTaskSnapshot();
+    expect(computeFreshness({ snapshot, policy, now: NOW, degraded: true })).toBe('stale');
+  });
+});
+
+describe('mutation guard', () => {
+  it('permits mutations only on current data', () => {
+    expect(canMutate('current')).toBe(true);
+    for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) {
+      expect(canMutate(state)).toBe(false);
+    }
+  });
+
+  it('refuses mutations on non-current data via assertMutable', () => {
+    expect(() => assertMutable('current')).not.toThrow();
+    for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) {
+      let thrown: unknown;
+      try {
+        assertMutable(state);
+      } catch (caught) {
+        thrown = caught;
+      }
+      expect(thrown).toBeInstanceOf(StaleMutationError);
+      expect(thrown).toBeInstanceOf(Error);
+      if (thrown instanceof StaleMutationError) {
+        expect(thrown.name).toBe('StaleMutationError');
+        expect(thrown.freshness).toBe(state);
+        expect(thrown.message).toContain(state);
+        expect(thrown.message).toContain('revalidat');
+      }
+    }
+  });
+});
+
+describe('acceptSnapshot', () => {
+  it('accepts a valid payload with provenance', () => {
+    const result = acceptSnapshot({
+      value: taskPayload,
+      validate: validateTaskCollection,
+      previous: null,
+      policy,
+      source: 'gateway:/api/tasks',
+      now: NOW,
+    });
+    expect(result.outcome).toBe('accepted');
+    if (result.outcome !== 'accepted') return;
+    expect(result.snapshot.source).toBe('gateway:/api/tasks');
+    expect(result.snapshot.version).toBe(1);
+    expect(result.snapshot.fetchedAt).toBe(NOW);
+    expect(result.snapshot.data).toEqual(taskPayload);
+  });
+
+  it('invalidates a schema-mismatched payload instead of rendering it', () => {
+    const result = acceptSnapshot({
+      value: { not: 'an array' },
+      validate: validateTaskCollection,
+      previous: acceptedTaskSnapshot(),
+      policy,
+      source: 'gateway:/api/tasks',
+      now: NOW,
+    });
+    expect(result).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' });
+    expect(invalidationReasonLabels['schema-mismatch']).toContain('schema');
+  });
+
+  it('invalidates cross-workspace payloads', () => {
+    const userOne = acceptSnapshot({
+      value: [
+        {
+          id: 'p1',
+          name: 'P1',
+          description: null,
+          status: 'active',
+          userId: 'user-1',
+          metadata: null,
+          createdAt: '2026-08-01T00:00:00.000Z',
+          updatedAt: '2026-08-01T00:00:00.000Z',
+        },
+      ],
+      validate: validateProjectCollection,
+      previous: null,
+      policy,
+      source: 'gateway:/api/projects',
+      now: NOW,
+    });
+    if (userOne.outcome !== 'accepted') throw new Error('expected acceptance');
+
+    const switched = acceptSnapshot({
+      value: [
+        {
+          id: 'p9',
+          name: 'P9',
+          description: null,
+          status: 'active',
+          userId: 'user-2',
+          metadata: null,
+          createdAt: '2026-08-01T00:00:00.000Z',
+          updatedAt: '2026-08-01T00:00:00.000Z',
+        },
+      ],
+      validate: validateProjectCollection,
+      previous: userOne.snapshot,
+      policy,
+      source: 'gateway:/api/projects',
+      now: NOW,
+    });
+    expect(switched).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
+  });
+
+  it('keeps the previous workspace for collections with no intrinsic identity', () => {
+    const userOne = acceptSnapshot({
+      value: [
+        {
+          id: 'p1',
+          name: 'P1',
+          description: null,
+          status: 'active',
+          userId: 'user-1',
+          metadata: null,
+          createdAt: '2026-08-01T00:00:00.000Z',
+          updatedAt: '2026-08-01T00:00:00.000Z',
+        },
+      ],
+      validate: validateProjectCollection,
+      previous: null,
+      policy,
+      source: 'gateway:/api/projects',
+      now: NOW,
+    });
+    if (userOne.outcome !== 'accepted') throw new Error('expected acceptance');
+
+    // Empty list after the user deleted every project: no identity to check,
+    // so the verified scope is retained and the empty state stays healthy.
+    const emptied = acceptSnapshot({
+      value: [],
+      validate: validateProjectCollection,
+      previous: userOne.snapshot,
+      policy,
+      source: 'gateway:/api/projects',
+      now: NOW,
+    });
+    expect(emptied.outcome).toBe('accepted');
+    if (emptied.outcome === 'accepted') {
+      expect(emptied.snapshot.data).toEqual([]);
+      expect(emptied.snapshot.workspace).toBe('user-1');
+    }
+  });
+
+  it('invalidates version regressions', () => {
+    const previous = acceptedTaskSnapshot({ version: 7 });
+    const regressed = acceptSnapshot({
+      value: taskPayload,
+      validate: validateTaskCollection,
+      previous,
+      policy,
+      source: 'gateway:/api/tasks',
+      now: NOW,
+      incomingVersion: 3,
+    });
+    expect(regressed).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
+
+    const newerSchema = acceptedTaskSnapshot({ schemaVersion: 4 });
+    const downgradedClient = acceptSnapshot({
+      value: taskPayload,
+      validate: validateTaskCollection,
+      previous: newerSchema,
+      policy: { ...policy, schemaVersion: 2 },
+      source: 'gateway:/api/tasks',
+      now: NOW,
+    });
+    expect(downgradedClient).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
+  });
+
+  it('increments the version monotonically across accepted snapshots', () => {
+    const first = acceptedTaskSnapshot();
+    const second = acceptSnapshot({
+      value: taskPayload,
+      validate: validateTaskCollection,
+      previous: first,
+      policy,
+      source: 'gateway:/api/tasks',
+      now: NOW,
+    });
+    expect(second.outcome).toBe('accepted');
+    if (second.outcome === 'accepted') {
+      expect(second.snapshot.version).toBe(first.version + 1);
+    }
+  });
+});
+
+describe('combineFreshness', () => {
+  it('gates the surface on the primary collection', () => {
+    expect(combineFreshness('unavailable', ['current'])).toBe('unavailable');
+    expect(combineFreshness('unknown', ['current'])).toBe('unknown');
+    expect(combineFreshness('current', [])).toBe('current');
+  });
+
+  it('degrades to partial when a secondary is unavailable', () => {
+    expect(combineFreshness('current', ['current', 'unavailable'])).toBe('partial');
+  });
+
+  it('degrades to unknown while a secondary is still loading', () => {
+    expect(combineFreshness('current', ['unknown'])).toBe('unknown');
+  });
+
+  it('degrades to stale when any collection is stale', () => {
+    expect(combineFreshness('current', ['stale'])).toBe('stale');
+    expect(combineFreshness('stale', ['current'])).toBe('stale');
+  });
+
+  it('propagates partial secondaries', () => {
+    expect(combineFreshness('current', ['partial'])).toBe('partial');
+  });
+});
+
+describe('computeDigest', () => {
+  it('is stable across key order and changes with data', () => {
+    const a = computeDigest({ x: 1, y: [1, 2] });
+    const b = computeDigest({ y: [1, 2], x: 1 });
+    expect(a).toBe(b);
+    expect(computeDigest({ x: 1, y: [1, 3] })).not.toBe(a);
+  });
+});
+
+describe('verdictValue', () => {
+  it('returns the value only for verified inputs', () => {
+    expect(verdictValue(true, '5')).toBe('5');
+    expect(verdictValue(false, '5')).toBe(UNKNOWN_VERDICT);
+    expect(verdictValue(false, '5')).not.toBe('5');
+  });
+});
+
+describe('formatAge', () => {
+  it('labels age in human terms', () => {
+    expect(formatAge(NOW, NOW)).toBe('just now');
+    expect(formatAge(NOW, NOW + 15_000)).toBe('under a minute ago');
+    expect(formatAge(NOW, NOW + 120_000)).toBe('2m ago');
+    expect(formatAge(NOW, NOW + 3 * 3_600_000)).toBe('3h ago');
+    expect(formatAge(NOW, NOW + 2 * 86_400_000)).toBe('2d ago');
+  });
+});

apps/web/src/lib/freshness/model.ts

@@ -0,0 +1,261 @@
+/**
+ * Typed freshness model for gateway-fetched collections (RI-5-001).
+ *
+ * A failed or stale fetch must never be indistinguishable from an empty
+ * healthy collection. Every fetched surface carries an explicit freshness
+ * state, a verified snapshot identity (source, workspace, version, age), and
+ * a mutation guard that refuses state-changing operations unless the data is
+ * verified current.
+ */
+
+/** Freshness states for fetched data. Never inferred from emptiness. */
+export type FreshnessState = 'current' | 'stale' | 'partial' | 'unknown' | 'unavailable';
+
+/**
+ * Reasons a snapshot is invalidated. An invalidated snapshot is treated as
+ * unavailable and is never rendered as current.
+ */
+export type InvalidationReason =
+  | 'cache-corruption'
+  | 'cross-workspace'
+  | 'schema-mismatch'
+  | 'version-regression';
+
+/** Human-readable labels for invalidation reasons (UI + error messages). */
+export const invalidationReasonLabels: Record<InvalidationReason, string> = {
+  'cache-corruption': 'cached snapshot failed integrity checks',
+  'cross-workspace': 'data belongs to a different workspace',
+  'schema-mismatch': 'response did not match the expected schema',
+  'version-regression': 'snapshot version regressed below the accepted version',
+};
+
+/** A verified snapshot of fetched data with full provenance. */
+export interface FreshSnapshot<T> {
+  readonly data: T;
+  /** Source identity of the fetch, e.g. `gateway:/api/tasks`. */
+  readonly source: string;
+  /** Workspace scope the data belongs to. */
+  readonly workspace: string;
+  /** Monotonic snapshot sequence number for this surface. */
+  readonly version: number;
+  /** Schema version of the validator that accepted this snapshot. */
+  readonly schemaVersion: number;
+  /** Epoch ms at which the data was verified. */
+  readonly fetchedAt: number;
+  /** Integrity digest of `data`, used to detect cache corruption. */
+  readonly digest: string;
+}
+
+/** Provenance label rendered next to last-known data. */
+export interface FreshnessLabel {
+  readonly source: string;
+  readonly version: number;
+  readonly fetchedAt: number;
+}
+
+/** Policy governing freshness for a surface. */
+export interface FreshnessPolicy {
+  /** Active workspace scope. Snapshots from other scopes are invalidated. */
+  readonly workspace: string;
+  /** Schema version of the current validator. */
+  readonly schemaVersion: number;
+  /** Age after which a verified snapshot degrades from current to stale. */
+  readonly staleAfterMs: number;
+}
+
+export const DEFAULT_FRESHNESS_POLICY: FreshnessPolicy = {
+  workspace: 'default',
+  schemaVersion: 1,
+  staleAfterMs: 60_000,
+};
+
+/** Payload returned by a successful schema validation. */
+export interface FreshPayload<T> {
+  readonly data: T;
+  /**
+   * Workspace identity extracted from the payload itself when the collection
+   * carries one (e.g. a uniform `userId` on projects). `null` when the
+   * collection has no intrinsic workspace identity.
+   */
+  readonly workspace: string | null;
+}
+
+/** Error thrown when a mutation is attempted on non-current data. */
+export class StaleMutationError extends Error {
+  readonly freshness: FreshnessState;
+
+  constructor(freshness: FreshnessState) {
+    super(`Refused mutation on ${freshness} data: revalidation is required before mutating.`);
+    this.name = 'StaleMutationError';
+    this.freshness = freshness;
+  }
+}
+
+/** Stable JSON digest used for snapshot integrity checks. */
+export function computeDigest(value: unknown): string {
+  // FNV-1a 32-bit over the stable JSON serialization. This is an integrity
+  // check against corruption, not a cryptographic guarantee.
+  let hash = 0x811c9dc5;
+  for (const byte of stableStringify(value)) {
+    hash ^= byte.charCodeAt(0);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function stableStringify(value: unknown): string {
+  return serialize(value);
+}
+
+function serialize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(serialize).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, item]) => item !== undefined)
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([key, item]) => `${JSON.stringify(key)}:${serialize(item)}`);
+  return `{${entries.join(',')}}`;
+}
+
+export type AcceptSnapshotResult<T> =
+  | { readonly outcome: 'accepted'; readonly snapshot: FreshSnapshot<T> }
+  | { readonly outcome: 'invalidated'; readonly reason: InvalidationReason };
+
+export interface AcceptSnapshotOptions<T> {
+  /** Raw fetched value (untrusted JSON). */
+  readonly value: unknown;
+  /** Schema validator; returns `null` when the value does not match. */
+  readonly validate: (value: unknown) => FreshPayload<T> | null;
+  /** Previously accepted snapshot for this surface, if any. */
+  readonly previous: FreshSnapshot<T> | null;
+  readonly policy: FreshnessPolicy;
+  readonly source: string;
+  /**
+   * Version carried by the incoming payload when the transport exposes one.
+   * Must not regress below the accepted snapshot's version.
+   */
+  readonly incomingVersion?: number;
+  readonly now: number;
+}
+
+/**
+ * Validate and accept a fetched value as a snapshot, or invalidate it.
+ *
+ * Invalidation rules (each treated as unavailable, never rendered current):
+ * - schema mismatch: the payload fails validation
+ * - cross-workspace: the payload's workspace differs from the verified one
+ * - version regression: payload/schema version is below the accepted one
+ */
+export function acceptSnapshot<T>(options: AcceptSnapshotOptions<T>): AcceptSnapshotResult<T> {
+  const payload = options.validate(options.value);
+  if (payload === null) {
+    return { outcome: 'invalidated', reason: 'schema-mismatch' };
+  }
+
+  // Workspace identity: the payload's own scope wins; a collection with no
+  // intrinsic identity (e.g. an empty list after every project was deleted)
+  // keeps the previously verified scope rather than resetting to the policy
+  // default, so a legitimately empty response is not mistaken for a scope
+  // change.
+  const workspace = payload.workspace ?? options.previous?.workspace ?? options.policy.workspace;
+  if (options.previous !== null && options.previous.workspace !== workspace) {
+    return { outcome: 'invalidated', reason: 'cross-workspace' };
+  }
+  if (options.previous !== null && options.policy.schemaVersion < options.previous.schemaVersion) {
+    return { outcome: 'invalidated', reason: 'version-regression' };
+  }
+  if (
+    options.incomingVersion !== undefined &&
+    options.previous !== null &&
+    options.incomingVersion < options.previous.version
+  ) {
+    return { outcome: 'invalidated', reason: 'version-regression' };
+  }
+
+  const snapshot: FreshSnapshot<T> = {
+    data: payload.data,
+    source: options.source,
+    workspace,
+    version: options.incomingVersion ?? (options.previous?.version ?? 0) + 1,
+    schemaVersion: options.policy.schemaVersion,
+    fetchedAt: options.now,
+    digest: computeDigest(payload.data),
+  };
+  return { outcome: 'accepted', snapshot };
+}
+
+export interface ComputeFreshnessOptions {
+  readonly snapshot: FreshSnapshot<unknown> | null;
+  readonly policy: FreshnessPolicy;
+  readonly now: number;
+  /**
+   * True when the snapshot cannot be trusted as current regardless of age:
+   * the latest revalidation failed, or the snapshot was restored from cache
+   * and has not been verified by a fetch in this session.
+   */
+  readonly degraded?: boolean;
+}
+
+/**
+ * Compute the freshness state of a snapshot. A missing snapshot is
+ * `unavailable` (never "empty and healthy"); a degraded or aged snapshot is
+ * `stale` (situational awareness only).
+ */
+export function computeFreshness(options: ComputeFreshnessOptions): FreshnessState {
+  const { snapshot, policy, now, degraded = false } = options;
+  if (snapshot === null) return 'unavailable';
+  if (degraded) return 'stale';
+  if (now - snapshot.fetchedAt > policy.staleAfterMs) return 'stale';
+  return 'current';
+}
+
+/** Only verified-current data may back a state-changing action. */
+export function canMutate(state: FreshnessState): boolean {
+  return state === 'current';
+}
+
+/** Defense in depth: reject the mutation call itself on non-current data. */
+export function assertMutable(state: FreshnessState): void {
+  if (!canMutate(state)) {
+    throw new StaleMutationError(state);
+  }
+}
+
+/**
+ * Combine freshness across a multi-collection surface (primary + secondaries).
+ * The primary collection gates the surface: unknown while it loads,
+ * unavailable when it fails. Missing secondaries degrade the surface to
+ * `partial`; aged collections degrade it to `stale`.
+ */
+export function combineFreshness(
+  primary: FreshnessState,
+  secondaries: readonly FreshnessState[],
+): FreshnessState {
+  if (primary === 'unavailable') return 'unavailable';
+  if (primary === 'unknown') return 'unknown';
+  if (secondaries.includes('unavailable')) return 'partial';
+  if (secondaries.includes('unknown')) return 'unknown';
+  if (secondaries.includes('stale') || primary === 'stale') return 'stale';
+  if (secondaries.includes('partial')) return 'partial';
+  return 'current';
+}
+
+/** Render-safe age label for snapshot provenance. */
+export function formatAge(fetchedAt: number, now: number): string {
+  const ageMs = Math.max(0, now - fetchedAt);
+  if (ageMs < 10_000) return 'just now';
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 1) return 'under a minute ago';
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+/** Derived verdict placeholder for non-current inputs — never a green value. */
+export const UNKNOWN_VERDICT = '?';
+
+export function verdictValue(verified: boolean, value: string): string {
+  return verified ? value : UNKNOWN_VERDICT;
+}

apps/web/src/lib/freshness/snapshot-cache.spec.ts

@@ -0,0 +1,197 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { acceptSnapshot, DEFAULT_FRESHNESS_POLICY } from './model';
+import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache';
+import { validateProjectCollection, validateTaskCollection } from './validators';
+import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
+import type { Project, Task } from '@/lib/types';
+
+const KEY = 'test:tasks';
+const NOW = 1_800_000_000_000;
+const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 };
+
+function storedTaskSnapshot() {
+  const result = acceptSnapshot({
+    value: taskFixtures,
+    validate: validateTaskCollection,
+    previous: null,
+    policy,
+    source: 'gateway:/api/tasks',
+    now: NOW,
+  });
+  if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
+  return result.snapshot;
+}
+
+function storedProjectSnapshot() {
+  const result = acceptSnapshot({
+    value: projectFixtures,
+    validate: validateProjectCollection,
+    previous: null,
+    policy,
+    source: 'gateway:/api/projects',
+    now: NOW,
+  });
+  if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
+  return result.snapshot;
+}
+
+function readTasks() {
+  return readSnapshotCache({
+    key: KEY,
+    workspace: policy.workspace,
+    policy,
+    validate: validateTaskCollection,
+  });
+}
+
+/** Write an arbitrary value directly at the raw cache slot. */
+function writeRaw(key: string, value: unknown): void {
+  sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify(value));
+}
+
+/** Parse and re-write the stored entry (for tampering with internals). */
+function tamperStored<T>(key: string, mutate: (stored: T) => void): void {
+  const parsed = JSON.parse(sessionStorage.getItem(`mosaic:freshness:v1:${key}`) ?? '{}') as T;
+  mutate(parsed);
+  writeRaw(key, parsed);
+}
+
+beforeEach(() => {
+  sessionStorage.clear();
+});
+
+afterEach(() => {
+  sessionStorage.clear();
+});
+
+describe('readSnapshotCache', () => {
+  it('misses when nothing is stored', () => {
+    expect(readTasks()).toEqual({ outcome: 'miss' });
+  });
+
+  it('hits for a well-formed entry and preserves provenance', () => {
+    const snapshot = storedTaskSnapshot();
+    writeSnapshotCache(KEY, snapshot);
+
+    const result = readTasks();
+    expect(result.outcome).toBe('hit');
+    if (result.outcome === 'hit') {
+      expect(result.snapshot.data).toEqual(taskFixtures);
+      expect(result.snapshot.source).toBe('gateway:/api/tasks');
+      expect(result.snapshot.version).toBe(snapshot.version);
+      expect(result.snapshot.fetchedAt).toBe(snapshot.fetchedAt);
+      expect(result.snapshot.workspace).toBe(snapshot.workspace);
+    }
+  });
+
+  it('invalidates unparsable entries as cache corruption', () => {
+    sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, '{not json');
+    expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
+  });
+
+  it('invalidates structurally wrong entries as cache corruption', () => {
+    const malformed: unknown[] = [
+      'nested but not a snapshot',
+      { data: taskFixtures }, // missing provenance fields
+      {
+        data: taskFixtures,
+        source: 1,
+        workspace: 'w',
+        version: 1,
+        schemaVersion: 1,
+        fetchedAt: 1,
+        digest: 'x',
+      },
+      null,
+      17,
+    ];
+    for (const entry of malformed) {
+      writeRaw(KEY, entry);
+      expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
+    }
+  });
+
+  it('invalidates digest mismatches as cache corruption (tampered data)', () => {
+    writeSnapshotCache(KEY, storedTaskSnapshot());
+    tamperStored<{ data: Task[] }>(KEY, (stored) => {
+      stored.data = [...stored.data, { ...stored.data[0]!, id: 'injected-task' }];
+    });
+    expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' });
+  });
+
+  it('invalidates entries scoped to another workspace', () => {
+    const snapshot = storedTaskSnapshot();
+    writeSnapshotCache(KEY, { ...snapshot, workspace: 'someone-else' });
+    expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
+  });
+
+  it('invalidates entries written by a newer schema as a version regression', () => {
+    const snapshot = storedTaskSnapshot();
+    writeSnapshotCache(KEY, { ...snapshot, schemaVersion: policy.schemaVersion + 1 });
+    expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'version-regression' });
+  });
+
+  it('invalidates entries whose data no longer validates (schema mismatch)', () => {
+    writeSnapshotCache(KEY, storedTaskSnapshot());
+    tamperStored<{ data: unknown }>(KEY, (stored) => {
+      stored.data = { malformed: true };
+    });
+    expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' });
+  });
+
+  it('never reports a corrupted raw entry as a hit (negative control)', () => {
+    for (const raw of ['{oops', 'null', '"string"', '[]', '12']) {
+      sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, raw);
+      const result = readTasks();
+      expect(result.outcome).not.toBe('hit');
+      expect(result.outcome).toBe('invalidated');
+    }
+  });
+
+  it('scopes project collections by their workspace identity', () => {
+    const snapshot = storedProjectSnapshot();
+    writeSnapshotCache('test:projects', snapshot);
+
+    const sameScope = readSnapshotCache({
+      key: 'test:projects',
+      workspace: 'user-1',
+      policy,
+      validate: validateProjectCollection,
+    });
+    expect(sameScope.outcome).toBe('hit');
+
+    const foreignScope = readSnapshotCache({
+      key: 'test:projects',
+      workspace: 'user-2',
+      policy,
+      validate: validateProjectCollection,
+    });
+    expect(foreignScope).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' });
+  });
+});
+
+describe('writeSnapshotCache round-trip', () => {
+  it('round-trips an accepted project snapshot', () => {
+    const snapshot = storedProjectSnapshot();
+    writeSnapshotCache('test:projects', snapshot);
+    const result = readSnapshotCache({
+      key: 'test:projects',
+      workspace: snapshot.workspace,
+      policy,
+      validate: validateProjectCollection,
+    });
+    expect(result.outcome).toBe('hit');
+    if (result.outcome === 'hit') {
+      expect(result.snapshot.data).toEqual(projectFixtures as Project[]);
+    }
+  });
+});
+
+describe('clearSnapshotCache', () => {
+  it('drops the entry so the next read misses', () => {
+    writeSnapshotCache(KEY, storedTaskSnapshot());
+    expect(readTasks().outcome).toBe('hit');
+    clearSnapshotCache(KEY);
+    expect(readTasks()).toEqual({ outcome: 'miss' });
+  });
+});

apps/web/src/lib/freshness/snapshot-cache.ts

@@ -0,0 +1,154 @@
+import {
+  computeDigest,
+  type FreshPayload,
+  type FreshSnapshot,
+  type FreshnessPolicy,
+  type InvalidationReason,
+} from './model';
+
+/**
+ * Session-scoped last-known snapshot cache (RI-5-001).
+ *
+ * Restored snapshots are situational awareness only: they surface as `stale`
+ * until a fetch re-verifies them. A cache entry that is corrupted, belongs to
+ * another workspace, was written by a newer schema, or no longer validates is
+ * invalidated (treated as unavailable, never rendered as current).
+ */
+
+const CACHE_PREFIX = 'mosaic:freshness:v1';
+
+interface StoredSnapshot {
+  data: unknown;
+  source: string;
+  workspace: string;
+  version: number;
+  schemaVersion: number;
+  fetchedAt: number;
+  digest: string;
+}
+
+export type SnapshotCacheRead<T> =
+  | { readonly outcome: 'hit'; readonly snapshot: FreshSnapshot<T> }
+  | { readonly outcome: 'miss' }
+  | { readonly outcome: 'invalidated'; readonly reason: InvalidationReason };
+
+export interface ReadSnapshotCacheOptions<T> {
+  readonly key: string;
+  readonly workspace: string;
+  readonly policy: FreshnessPolicy;
+  readonly validate: (value: unknown) => FreshPayload<T> | null;
+}
+
+function cacheKey(key: string): string {
+  return `${CACHE_PREFIX}:${key}`;
+}
+
+function isStoredSnapshot(value: unknown): value is StoredSnapshot {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate['data'] === 'object' &&
+    candidate['data'] !== null &&
+    typeof candidate['source'] === 'string' &&
+    typeof candidate['workspace'] === 'string' &&
+    typeof candidate['version'] === 'number' &&
+    typeof candidate['schemaVersion'] === 'number' &&
+    typeof candidate['fetchedAt'] === 'number' &&
+    typeof candidate['digest'] === 'string'
+  );
+}
+
+function getStorage(): Storage | null {
+  try {
+    return globalThis.sessionStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Restore a cached snapshot under the active workspace scope. Every failure
+ * mode maps to an explicit invalidation reason or a miss — never to data
+ * that renders as current.
+ */
+export function readSnapshotCache<T>(options: ReadSnapshotCacheOptions<T>): SnapshotCacheRead<T> {
+  const storage = getStorage();
+  if (storage === null) return { outcome: 'miss' };
+
+  let raw: string | null;
+  try {
+    raw = storage.getItem(cacheKey(options.key));
+  } catch {
+    return { outcome: 'miss' };
+  }
+  if (raw === null) return { outcome: 'miss' };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { outcome: 'invalidated', reason: 'cache-corruption' };
+  }
+  if (!isStoredSnapshot(parsed)) {
+    return { outcome: 'invalidated', reason: 'cache-corruption' };
+  }
+  if (parsed.workspace !== options.workspace) {
+    return { outcome: 'invalidated', reason: 'cross-workspace' };
+  }
+  if (parsed.schemaVersion > options.policy.schemaVersion) {
+    // Written by a newer build than the running client: version regression.
+    return { outcome: 'invalidated', reason: 'version-regression' };
+  }
+
+  const payload = options.validate(parsed.data);
+  if (payload === null) {
+    return { outcome: 'invalidated', reason: 'schema-mismatch' };
+  }
+  if (computeDigest(payload.data) !== parsed.digest) {
+    return { outcome: 'invalidated', reason: 'cache-corruption' };
+  }
+
+  return {
+    outcome: 'hit',
+    snapshot: {
+      data: payload.data,
+      source: parsed.source,
+      workspace: parsed.workspace,
+      version: parsed.version,
+      schemaVersion: parsed.schemaVersion,
+      fetchedAt: parsed.fetchedAt,
+      digest: parsed.digest,
+    },
+  };
+}
+
+/** Persist a verified snapshot. Failures are non-fatal (cache is best-effort). */
+export function writeSnapshotCache<T>(key: string, snapshot: FreshSnapshot<T>): void {
+  const storage = getStorage();
+  if (storage === null) return;
+  const stored: StoredSnapshot = {
+    data: snapshot.data,
+    source: snapshot.source,
+    workspace: snapshot.workspace,
+    version: snapshot.version,
+    schemaVersion: snapshot.schemaVersion,
+    fetchedAt: snapshot.fetchedAt,
+    digest: snapshot.digest,
+  };
+  try {
+    storage.setItem(cacheKey(key), JSON.stringify(stored));
+  } catch {
+    // Quota or serialization failures simply skip caching.
+  }
+}
+
+/** Drop a cached snapshot (used when a surface invalidates its cache entry). */
+export function clearSnapshotCache(key: string): void {
+  const storage = getStorage();
+  if (storage === null) return;
+  try {
+    storage.removeItem(cacheKey(key));
+  } catch {
+    // Ignorable: a wedged storage entry is detected as corruption on read.
+  }
+}

apps/web/src/lib/freshness/use-fresh-collection.spec.tsx

@@ -0,0 +1,372 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Task } from '@/lib/types';
+import { acceptSnapshot, StaleMutationError, DEFAULT_FRESHNESS_POLICY } from './model';
+import type { FreshnessFailure } from './use-fresh-collection';
+import {
+  describeFailure,
+  useFreshCollection,
+  type FreshCollection,
+  type UseFreshCollectionOptions,
+} from './use-fresh-collection';
+import { validateProjectCollection, validateTaskCollection } from './validators';
+import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
+
+/**
+ * Failure-matrix coverage for the freshness seam (RI-5-001): network failure,
+ * auth failure, malformed response, cache corruption, stale age, schema
+ * mismatch, cross-workspace, recovery, and stale-action rejection — with
+ * negative controls proving no case yields current data or an enabled
+ * mutation.
+ */
+
+const NOW = 1_800_000_000_000;
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+}
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement;
+let latest: FreshCollection<Task[]> | null = null;
+
+function Probe({
+  options,
+}: {
+  options: UseFreshCollectionOptions<Task[]>;
+}): React.ReactElement | null {
+  latest = useFreshCollection<Task[]>(options);
+  return null;
+}
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+beforeEach(() => {
+  sessionStorage.clear();
+});
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  latest = null;
+  sessionStorage.clear();
+  vi.restoreAllMocks();
+});
+
+async function renderCollection(
+  options: UseFreshCollectionOptions<Task[]>,
+): Promise<FreshCollection<Task[]>> {
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(<Probe options={options} />);
+  });
+  if (latest === null) throw new Error('hook did not run');
+  return latest;
+}
+
+function taskOptions(
+  overrides: Partial<UseFreshCollectionOptions<Task[]>> = {},
+): UseFreshCollectionOptions<Task[]> {
+  return {
+    source: 'gateway:/api/tasks',
+    fetcher: () => Promise.resolve(taskFixtures),
+    validate: validateTaskCollection,
+    cacheKey: 'tasks',
+    clock: () => NOW,
+    ...overrides,
+  };
+}
+
+function authError(statusCode: number): Error & { statusCode: number } {
+  return Object.assign(new Error(`Request failed with ${statusCode}`), { statusCode });
+}
+
+function seedCache(key: string): number {
+  const result = acceptSnapshot({
+    value: taskFixtures,
+    validate: validateTaskCollection,
+    previous: null,
+    policy: DEFAULT_FRESHNESS_POLICY,
+    source: 'gateway:/api/tasks',
+    now: NOW,
+  });
+  if (result.outcome !== 'accepted') throw new Error('fixture setup failed');
+  sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify({ ...result.snapshot }));
+  return result.snapshot.version;
+}
+
+describe('useFreshCollection failure matrix', () => {
+  it('is unknown (not empty) while the first validation is in flight', async () => {
+    const deferred = createDeferred<Task[]>();
+    const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
+
+    expect(collection.freshness).toBe('unknown');
+    expect(collection.validating).toBe(true);
+    expect(collection.data).toBeNull();
+    expect(collection.canMutate).toBe(false);
+
+    await act(async () => {
+      deferred.resolve(taskFixtures);
+      await deferred.promise;
+    });
+  });
+
+  it('becomes current with provenance after a verified fetch', async () => {
+    const collection = await renderCollection(taskOptions());
+
+    expect(collection.freshness).toBe('current');
+    expect(collection.data).toEqual(taskFixtures);
+    expect(collection.snapshot?.source).toBe('gateway:/api/tasks');
+    expect(collection.snapshot?.version).toBe(1);
+    expect(collection.failure).toBeNull();
+    expect(collection.canMutate).toBe(true);
+    // Verified snapshot is persisted for last-known restore.
+    expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeTruthy();
+  });
+
+  it('treats a network failure as unavailable — never an empty healthy collection', async () => {
+    const collection = await renderCollection(
+      taskOptions({ fetcher: () => Promise.reject(new Error('network down')) }),
+    );
+
+    expect(collection.freshness).toBe('unavailable');
+    expect(collection.data).toBeNull();
+    expect(collection.failure).toEqual({ kind: 'fetch', message: 'network down' });
+    expect(collection.canMutate).toBe(false);
+    expect(describeFailure(collection.failure)).toBe('network down');
+  });
+
+  it('treats an auth failure as unavailable and drops the last-known snapshot', async () => {
+    let call = 0;
+    const collection = await renderCollection(
+      taskOptions({
+        fetcher: () => {
+          call += 1;
+          return call === 1 ? Promise.resolve(taskFixtures) : Promise.reject(authError(401));
+        },
+      }),
+    );
+    expect(collection.freshness).toBe('current');
+
+    await act(async () => {
+      await collection.revalidate();
+    });
+
+    expect(latest?.freshness).toBe('unavailable');
+    expect(latest?.data).toBeNull();
+    expect(latest?.failure?.kind).toBe('fetch');
+    // The previous user's data must not linger in the session cache.
+    expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull();
+  });
+
+  it('invalidates a malformed response as a schema mismatch', async () => {
+    const collection = await renderCollection(
+      taskOptions({ fetcher: () => Promise.resolve({ malformed: true }) }),
+    );
+
+    expect(collection.freshness).toBe('unavailable');
+    expect(collection.data).toBeNull();
+    expect(collection.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' });
+    expect(collection.canMutate).toBe(false);
+  });
+
+  it('keeps the previous snapshot as labeled stale when a later payload mismatches', async () => {
+    let call = 0;
+    const collection = await renderCollection(
+      taskOptions({
+        fetcher: () => {
+          call += 1;
+          return call === 1 ? Promise.resolve(taskFixtures) : Promise.resolve('garbage');
+        },
+      }),
+    );
+    expect(collection.freshness).toBe('current');
+
+    await act(async () => {
+      await collection.revalidate();
+    });
+
+    expect(latest?.freshness).toBe('stale');
+    expect(latest?.data).toEqual(taskFixtures);
+    expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' });
+    expect(latest?.canMutate).toBe(false);
+  });
+
+  it('drops the snapshot when the workspace changes under it (cross-workspace)', async () => {
+    let call = 0;
+    const collection = await renderCollection(
+      taskOptions({
+        fetcher: () => {
+          call += 1;
+          return Promise.resolve(
+            call === 1 ? projectFixtures : [{ ...projectFixtures[0], userId: 'user-2' }],
+          );
+        },
+        validate: validateProjectCollection as unknown as (value: unknown) => {
+          data: Task[];
+          workspace: string | null;
+        },
+        source: 'gateway:/api/projects',
+      }),
+    );
+    expect(collection.freshness).toBe('current');
+
+    await act(async () => {
+      await collection.revalidate();
+    });
+
+    expect(latest?.freshness).toBe('unavailable');
+    expect(latest?.data).toBeNull();
+    expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'cross-workspace' });
+  });
+
+  it('ages from current to stale and refuses mutations on stale data', async () => {
+    let fakeNow = NOW;
+    const collection = await renderCollection(
+      taskOptions({
+        clock: () => fakeNow,
+        policy: { staleAfterMs: 40 },
+        tickMs: 10,
+      }),
+    );
+    expect(collection.freshness).toBe('current');
+
+    // Age the snapshot past the policy and let the tick recompute.
+    fakeNow = NOW + 60;
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    });
+
+    expect(latest?.freshness).toBe('stale');
+    expect(latest?.data).toEqual(taskFixtures);
+    expect(latest?.canMutate).toBe(false);
+
+    const operation = vi.fn(async () => 'result');
+    await expect(latest?.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
+    expect(operation).not.toHaveBeenCalled();
+  });
+
+  it('recovers to current after a successful revalidation', async () => {
+    let call = 0;
+    const collection = await renderCollection(
+      taskOptions({
+        fetcher: () => {
+          call += 1;
+          return call === 1
+            ? Promise.reject(new Error('first attempt failed'))
+            : Promise.resolve(taskFixtures);
+        },
+      }),
+    );
+    expect(collection.freshness).toBe('unavailable');
+
+    await act(async () => {
+      await collection.revalidate();
+    });
+
+    expect(latest?.freshness).toBe('current');
+    expect(latest?.failure).toBeNull();
+
+    const operation = vi.fn(async (data: Task[]) => data.length);
+    await expect(latest?.mutate(operation)).resolves.toBe(taskFixtures.length);
+    expect(operation).toHaveBeenCalledOnce();
+  });
+
+  it('restores a cached snapshot as unverified stale data, then verifies it', async () => {
+    const seededVersion = seedCache('tasks');
+    const deferred = createDeferred<Task[]>();
+    const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
+
+    // Restored data is situational awareness only: labeled stale, never
+    // current, and mutations are refused before verification.
+    expect(collection.freshness).toBe('stale');
+    expect(collection.data).toEqual(taskFixtures);
+    expect(collection.canMutate).toBe(false);
+    await expect(collection.mutate(vi.fn())).rejects.toBeInstanceOf(StaleMutationError);
+
+    await act(async () => {
+      deferred.resolve(taskFixtures);
+      await deferred.promise;
+    });
+
+    expect(latest?.freshness).toBe('current');
+    expect(latest?.snapshot?.version).toBe(seededVersion + 1);
+  });
+
+  it('never promotes corrupted cache data to current (cache corruption)', async () => {
+    sessionStorage.setItem('mosaic:freshness:v1:tasks', '{"data":');
+    const collection = await renderCollection(
+      taskOptions({ fetcher: () => Promise.reject(new Error('still down')) }),
+    );
+
+    expect(collection.freshness).toBe('unavailable');
+    expect(collection.data).toBeNull();
+    expect(collection.canMutate).toBe(false);
+    // The corrupted entry is dropped so it cannot come back.
+    expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull();
+  });
+
+  it('refuses mutations while unknown or unavailable — the call itself, not just the button', async () => {
+    const deferred = createDeferred<Task[]>();
+    const unknown = await renderCollection(taskOptions({ fetcher: () => deferred.promise }));
+    const operation = vi.fn(async () => 'result');
+    await expect(unknown.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
+    expect(operation).not.toHaveBeenCalled();
+    await act(async () => {
+      deferred.reject(new Error('failed'));
+      await deferred.promise.catch(() => undefined);
+    });
+
+    const unavailable = latest!;
+    await expect(unavailable.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError);
+    expect(operation).not.toHaveBeenCalled();
+    expect(unavailable.canMutate).toBe(false);
+  });
+
+  it('degrades to stale with last-known data when a revalidation fails after success', async () => {
+    let call = 0;
+    const collection = await renderCollection(
+      taskOptions({
+        fetcher: () => {
+          call += 1;
+          return call === 1
+            ? Promise.resolve(taskFixtures)
+            : Promise.reject(new Error('connection lost'));
+        },
+      }),
+    );
+    expect(collection.freshness).toBe('current');
+
+    await act(async () => {
+      await collection.revalidate();
+    });
+
+    expect(latest?.freshness).toBe('stale');
+    expect(latest?.data).toEqual(taskFixtures);
+    const failure: FreshnessFailure | null = latest?.failure ?? null;
+    expect(failure).toEqual({ kind: 'fetch', message: 'connection lost' });
+  });
+});

apps/web/src/lib/freshness/use-fresh-collection.ts

@@ -0,0 +1,281 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  acceptSnapshot,
+  assertMutable,
+  computeFreshness,
+  DEFAULT_FRESHNESS_POLICY,
+  invalidationReasonLabels,
+  type FreshPayload,
+  type FreshSnapshot,
+  type FreshnessPolicy,
+  type FreshnessState,
+  type InvalidationReason,
+  StaleMutationError,
+} from './model';
+import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache';
+
+/**
+ * Freshness-aware collection fetch hook (RI-5-001).
+ *
+ * One hook owns one gateway collection end to end: fetch, schema validation,
+ * snapshot acceptance with provenance, session-scoped last-known caching,
+ * aging, and the mutation guard. Pages consume `freshness` and never infer
+ * health from emptiness.
+ */
+
+/** Why the latest validation did not produce a current snapshot. */
+export type FreshnessFailure =
+  | { readonly kind: 'fetch'; readonly message: string }
+  | { readonly kind: 'invalidated'; readonly reason: InvalidationReason };
+
+export interface UseFreshCollectionOptions<T> {
+  /** Source identity for provenance labels, e.g. `gateway:/api/tasks`. */
+  readonly source: string;
+  /** Performs the unvalidated fetch. The hook owns abort and verification. */
+  readonly fetcher: (signal: AbortSignal) => Promise<unknown>;
+  /**
+   * Runtime schema validator. Returning `null` invalidates the payload
+   * (`schema-mismatch`) instead of letting malformed JSON flow into render.
+   */
+  readonly validate: (value: unknown) => FreshPayload<T> | null;
+  /** Overrides of the default freshness policy. */
+  readonly policy?: Partial<FreshnessPolicy>;
+  /**
+   * Session cache key for last-known snapshots. `null`/omitted disables
+   * restore. Restored snapshots are unverified: they render only as
+   * labeled `stale` data until a fetch re-verifies them.
+   */
+  readonly cacheKey?: string | null;
+  /** Injectable clock for deterministic age transitions in tests. */
+  readonly clock?: () => number;
+  /** Aging tick interval override (default derived from `staleAfterMs`). */
+  readonly tickMs?: number;
+  /** When false, no fetch runs (surfaces stay `unavailable`/`unknown`). */
+  readonly enabled?: boolean;
+}
+
+export interface FreshCollection<T> {
+  /** Last verified (or restored-unverified) snapshot, or `null`. */
+  readonly snapshot: FreshSnapshot<T> | null;
+  /** Snapshot data or `null` — never a fabricated empty collection. */
+  readonly data: T | null;
+  readonly freshness: FreshnessState;
+  /** True while a validation request is in flight. */
+  readonly validating: boolean;
+  /** Outcome of the latest failed validation, `null` when healthy. */
+  readonly failure: FreshnessFailure | null;
+  /** False unless freshness is `current`; drives disabled UI affordances. */
+  readonly canMutate: boolean;
+  /** Re-run the fetch and re-verify. Always allowed (it is a read). */
+  readonly revalidate: () => Promise<void>;
+  /**
+   * Run a state-changing operation against verified-current data only.
+   * Rejects with `StaleMutationError` on any other state — the guard fires
+   * even if a disabled button was bypassed (defense in depth).
+   */
+  readonly mutate: <R>(operation: (data: T) => Promise<R>) => Promise<R>;
+}
+
+const defaultClock = (): number => Date.now();
+
+function resolveTickMs(policy: FreshnessPolicy, override?: number): number {
+  if (override !== undefined && override > 0) return override;
+  return Math.min(5_000, Math.max(250, Math.floor(policy.staleAfterMs / 4)));
+}
+
+function isAuthFailure(caught: unknown): boolean {
+  return (
+    typeof caught === 'object' &&
+    caught !== null &&
+    'statusCode' in caught &&
+    ((caught as { statusCode?: unknown }).statusCode === 401 ||
+      (caught as { statusCode?: unknown }).statusCode === 403)
+  );
+}
+
+function fetchFailureMessage(caught: unknown): string {
+  if (caught instanceof Error && caught.message.trim().length > 0) return caught.message;
+  return 'The request failed.';
+}
+
+/** Human-readable summary of a failure for unavailable/stale notices. */
+export function describeFailure(failure: FreshnessFailure | null): string | null {
+  if (failure === null) return null;
+  if (failure.kind === 'fetch') return failure.message;
+  return `The snapshot was invalidated: ${invalidationReasonLabels[failure.reason]}.`;
+}
+
+export function useFreshCollection<T>(options: UseFreshCollectionOptions<T>): FreshCollection<T> {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const policy = useMemo<FreshnessPolicy>(
+    () => ({ ...DEFAULT_FRESHNESS_POLICY, ...options.policy }),
+    [options.policy],
+  );
+  const policyRef = useRef(policy);
+  policyRef.current = policy;
+
+  const clockRef = useRef(options.clock ?? defaultClock);
+  clockRef.current = options.clock ?? defaultClock;
+
+  const [snapshot, setSnapshot] = useState<FreshSnapshot<T> | null>(null);
+  const [failure, setFailure] = useState<FreshnessFailure | null>(null);
+  const [unverified, setUnverified] = useState(false);
+  const [validating, setValidating] = useState(options.enabled !== false);
+  const [now, setNow] = useState(() => (options.clock ?? defaultClock)());
+
+  const snapshotRef = useRef(snapshot);
+  snapshotRef.current = snapshot;
+  const failureRef = useRef(failure);
+  failureRef.current = failure;
+  const unverifiedRef = useRef(unverified);
+  unverifiedRef.current = unverified;
+
+  const runRef = useRef(0);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const revalidate = useCallback(async (): Promise<void> => {
+    const current = optionsRef.current;
+    if (current.enabled === false) {
+      setValidating(false);
+      return;
+    }
+
+    const runId = ++runRef.current;
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    setValidating(true);
+
+    let value: unknown;
+    try {
+      value = await current.fetcher(controller.signal);
+    } catch (caught) {
+      if (runRef.current !== runId || controller.signal.aborted) return;
+      if (isAuthFailure(caught)) {
+        // An unauthenticated viewer must not keep (or be served) the
+        // previous user's last-known data.
+        setSnapshot(null);
+        setUnverified(false);
+        if (current.cacheKey) clearSnapshotCache(current.cacheKey);
+      }
+      setFailure({ kind: 'fetch', message: fetchFailureMessage(caught) });
+      setValidating(false);
+      return;
+    }
+
+    if (runRef.current !== runId) return;
+
+    const result = acceptSnapshot({
+      value,
+      validate: current.validate,
+      previous: snapshotRef.current,
+      policy: policyRef.current,
+      source: current.source,
+      now: clockRef.current(),
+    });
+
+    if (result.outcome === 'accepted') {
+      setSnapshot(result.snapshot);
+      setUnverified(false);
+      setFailure(null);
+      if (current.cacheKey) writeSnapshotCache(current.cacheKey, result.snapshot);
+    } else {
+      if (result.reason === 'cross-workspace') {
+        // Data verified for a different workspace must not linger as
+        // last-known situational awareness either.
+        setSnapshot(null);
+        setUnverified(false);
+      }
+      if (current.cacheKey) clearSnapshotCache(current.cacheKey);
+      setFailure({ kind: 'invalidated', reason: result.reason });
+    }
+    setValidating(false);
+  }, []);
+
+  // Restore the last-known snapshot (unverified) and run the first fetch.
+  useEffect(() => {
+    if (optionsRef.current.enabled === false) {
+      setValidating(false);
+      return;
+    }
+
+    const cacheKey = optionsRef.current.cacheKey;
+    if (cacheKey) {
+      const restored = readSnapshotCache<T>({
+        key: cacheKey,
+        workspace: policyRef.current.workspace,
+        policy: policyRef.current,
+        validate: optionsRef.current.validate,
+      });
+      if (restored.outcome === 'hit') {
+        setSnapshot(restored.snapshot);
+        setUnverified(true);
+      } else if (restored.outcome === 'invalidated') {
+        // A corrupted/foreign/regressed entry is dropped immediately; it must
+        // never surface as data. The fetch decides the visible state.
+        clearSnapshotCache(cacheKey);
+      }
+    }
+
+    void revalidate();
+
+    return () => {
+      abortRef.current?.abort();
+    };
+    // Mount-once by design: `revalidate` is stable and reads live options
+    // through refs, so it never needs to re-run when options change.
+    // Route-param pages remount this hook via an identity `key` instead.
+  }, [revalidate]);
+
+  // Aging tick: recomputes freshness as the snapshot ages past the policy.
+  useEffect(() => {
+    const interval = setInterval(
+      () => {
+        setNow(clockRef.current());
+      },
+      resolveTickMs(policyRef.current, optionsRef.current.tickMs),
+    );
+    return () => clearInterval(interval);
+  }, []);
+
+  const freshness = useMemo<FreshnessState>(() => {
+    if (snapshot === null) return validating ? 'unknown' : 'unavailable';
+    return computeFreshness({
+      snapshot,
+      policy,
+      now,
+      degraded: failure !== null || unverified,
+    });
+    // `now` from state covers age; refs inside computeFreshness are pure.
+  }, [snapshot, validating, failure, unverified, now, policy]);
+
+  const canMutate = freshness === 'current';
+
+  const mutate = useCallback(async <R>(operation: (data: T) => Promise<R>): Promise<R> => {
+    const currentSnapshot = snapshotRef.current;
+    // No verified snapshot at all: with nothing verified there is nothing
+    // current to mutate, regardless of the recorded failure.
+    if (currentSnapshot === null) throw new StaleMutationError('unavailable');
+    const state = computeFreshness({
+      snapshot: currentSnapshot,
+      policy: policyRef.current,
+      now: clockRef.current(),
+      degraded: failureRef.current !== null || unverifiedRef.current,
+    });
+    assertMutable(state);
+    return operation(currentSnapshot.data);
+  }, []);
+
+  return {
+    snapshot,
+    data: snapshot === null ? null : snapshot.data,
+    freshness,
+    validating,
+    failure,
+    canMutate,
+    revalidate,
+    mutate,
+  };
+}

apps/web/src/lib/freshness/validators.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import type { Mission, Project, Task } from '@/lib/types';
+import {
+  validateMissionCollection,
+  validateProjectCollection,
+  validateProjectEntity,
+  validateTaskCollection,
+} from './validators';
+import { missionFixtures, projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures';
+
+describe('validateTaskCollection', () => {
+  it('accepts a well-formed task collection', () => {
+    expect(validateTaskCollection(taskFixtures)).toEqual({
+      data: taskFixtures,
+      workspace: null,
+    });
+  });
+
+  it('accepts an empty collection (a healthy empty state is a valid payload)', () => {
+    expect(validateTaskCollection([])).toEqual({ data: [], workspace: null });
+  });
+
+  it.each([
+    ['not an array', { items: [] }],
+    ['item is not an object', ['nope']],
+    ['missing id', [{ ...(taskFixtures[0] as Task), id: undefined }]],
+    ['missing title', [{ ...(taskFixtures[0] as Task), title: undefined }]],
+    ['unknown status enum', [{ ...(taskFixtures[0] as Task), status: 'finished' }]],
+    ['unknown priority enum', [{ ...(taskFixtures[0] as Task), priority: 'urgent' }]],
+    ['tags of the wrong type', [{ ...(taskFixtures[0] as Task), tags: 'spa' }]],
+    ['metadata of the wrong type', [{ ...(taskFixtures[0] as Task), metadata: 'notes' }]],
+    ['createdAt of the wrong type', [{ ...(taskFixtures[0] as Task), createdAt: 1234 }]],
+    ['null sneaks past a required string', [{ ...(taskFixtures[0] as Task), title: null }]],
+  ])('rejects a malformed payload: %s', (_label, value) => {
+    expect(validateTaskCollection(value)).toBeNull();
+  });
+});
+
+describe('validateMissionCollection', () => {
+  it('accepts a well-formed mission collection', () => {
+    expect(validateMissionCollection(missionFixtures)).toEqual({
+      data: missionFixtures,
+      workspace: null,
+    });
+  });
+
+  it.each([
+    ['not an array', null],
+    ['item missing name', [{ ...(missionFixtures[0] as Mission), name: 42 }]],
+    ['unknown status enum', [{ ...(missionFixtures[0] as Mission), status: 'canceled' }]],
+    ['projectId of the wrong type', [{ ...(missionFixtures[0] as Mission), projectId: 7 }]],
+  ])('rejects a malformed payload: %s', (_label, value) => {
+    expect(validateMissionCollection(value)).toBeNull();
+  });
+});
+
+describe('validateProjectCollection', () => {
+  it('accepts a uniform workspace-scoped collection and reports its workspace', () => {
+    expect(validateProjectCollection(projectFixtures)).toEqual({
+      data: projectFixtures,
+      workspace: 'user-1',
+    });
+  });
+
+  it('accepts an empty collection with no workspace identity', () => {
+    expect(validateProjectCollection([])).toEqual({ data: [], workspace: null });
+  });
+
+  it.each([
+    ['not an array', 42],
+    ['item missing userId', [{ ...(projectFixtures[0] as Project), userId: undefined }]],
+    ['unknown status enum', [{ ...(projectFixtures[0] as Project), status: 'live' }]],
+    ['description of the wrong type', [{ ...(projectFixtures[0] as Project), description: 1 }]],
+  ])('rejects a malformed payload: %s', (_label, value) => {
+    expect(validateProjectCollection(value)).toBeNull();
+  });
+
+  it('rejects a collection mixing workspace identities (cross-workspace leak)', () => {
+    const mixed = [
+      projectFixtures[0] as Project,
+      { ...(projectFixtures[1] as Project), userId: 'user-2' },
+    ];
+    expect(validateProjectCollection(mixed)).toBeNull();
+  });
+});
+
+describe('validateProjectEntity', () => {
+  it('accepts a well-formed project and reports its workspace', () => {
+    expect(validateProjectEntity(projectFixtures[0])).toEqual({
+      data: projectFixtures[0],
+      workspace: 'user-1',
+    });
+  });
+
+  it.each([
+    ['not an object', 'project-1'],
+    ['null', null],
+    ['array', [projectFixtures[0]]],
+    ['missing userId', [{ ...(projectFixtures[0] as Project), userId: null }]],
+  ])('rejects a malformed entity: %s', (_label, value) => {
+    expect(validateProjectEntity(value)).toBeNull();
+  });
+});

apps/web/src/lib/freshness/validators.ts

@@ -0,0 +1,135 @@
+import type { Mission, Project, Task, MissionStatus, TaskPriority, TaskStatus } from '@/lib/types';
+import type { FreshPayload } from './model';
+
+/**
+ * Runtime schema validators for gateway collections (RI-5-001).
+ *
+ * `api<T>()` returns untrusted JSON cast to `T`; these validators are the
+ * seam where a malformed response becomes an explicit schema mismatch
+ * instead of flowing into the render path as if it were healthy data.
+ */
+
+const taskStatuses: readonly TaskStatus[] = [
+  'not-started',
+  'in-progress',
+  'blocked',
+  'done',
+  'cancelled',
+];
+const taskPriorities: readonly TaskPriority[] = ['critical', 'high', 'medium', 'low'];
+const missionStatuses: readonly MissionStatus[] = [
+  'planning',
+  'active',
+  'paused',
+  'completed',
+  'failed',
+];
+const projectStatuses: readonly Project['status'][] = ['active', 'paused', 'completed', 'archived'];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === 'string';
+}
+
+function isOneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value);
+}
+
+function isNullableRecord(value: unknown): value is Record<string, unknown> | null {
+  return value === null || isRecord(value);
+}
+
+function isNullableStringArray(value: unknown): value is string[] | null {
+  if (value === null) return true;
+  if (!Array.isArray(value)) return false;
+  return value.every((item) => typeof item === 'string');
+}
+
+function isIsoLike(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isTask(value: unknown): value is Task {
+  if (!isRecord(value)) return false;
+  return (
+    isString(value['id']) &&
+    isString(value['title']) &&
+    isOneOf(value['status'], taskStatuses) &&
+    isOneOf(value['priority'], taskPriorities) &&
+    isNullableString(value['projectId']) &&
+    isNullableString(value['missionId']) &&
+    isNullableString(value['assignee']) &&
+    isNullableStringArray(value['tags']) &&
+    isNullableRecord(value['metadata']) &&
+    isNullableString(value['dueDate']) &&
+    isIsoLike(value['createdAt']) &&
+    isIsoLike(value['updatedAt'])
+  );
+}
+
+/** Tasks carry no workspace identity; scope falls back to the policy. */
+export function validateTaskCollection(value: unknown): FreshPayload<Task[]> | null {
+  if (!Array.isArray(value) || !value.every(isTask)) return null;
+  return { data: value as Task[], workspace: null };
+}
+
+function isMission(value: unknown): value is Mission {
+  if (!isRecord(value)) return false;
+  return (
+    isString(value['id']) &&
+    isString(value['name']) &&
+    isOneOf(value['status'], missionStatuses) &&
+    isNullableString(value['projectId']) &&
+    isNullableString(value['description']) &&
+    isNullableRecord(value['metadata']) &&
+    isIsoLike(value['createdAt']) &&
+    isIsoLike(value['updatedAt'])
+  );
+}
+
+/** Missions carry no workspace identity; scope falls back to the policy. */
+export function validateMissionCollection(value: unknown): FreshPayload<Mission[]> | null {
+  if (!Array.isArray(value) || !value.every(isMission)) return null;
+  return { data: value as Mission[], workspace: null };
+}
+
+function isProject(value: unknown): value is Project {
+  if (!isRecord(value)) return false;
+  return (
+    isString(value['id']) &&
+    isString(value['name']) &&
+    isOneOf(value['status'], projectStatuses) &&
+    isString(value['userId']) &&
+    isNullableString(value['description']) &&
+    isNullableRecord(value['metadata']) &&
+    isIsoLike(value['createdAt']) &&
+    isIsoLike(value['updatedAt'])
+  );
+}
+
+/**
+ * Projects are workspace-scoped: every item must carry the same `userId`.
+ * A collection mixing identities (cross-workspace leak) is a schema
+ * mismatch; the uniform `userId` becomes the snapshot workspace.
+ */
+export function validateProjectCollection(value: unknown): FreshPayload<Project[]> | null {
+  if (!Array.isArray(value) || !value.every(isProject)) return null;
+  const projects = value as Project[];
+  const workspaces = new Set(projects.map((project) => project.userId));
+  if (workspaces.size > 1) return null;
+  return { data: projects, workspace: projects.length > 0 ? projects[0]!.userId : null };
+}
+
+/** Single project entity (project detail primary collection). */
+export function validateProjectEntity(value: unknown): FreshPayload<Project> | null {
+  if (!isProject(value)) return null;
+  const project = value as Project;
+  return { data: project, workspace: project.userId };
+}

apps/web/src/main.tsx

@@ -3,7 +3,7 @@ import { createRoot } from 'react-dom/client';
 import { RouterProvider } from 'react-router-dom';
 import { ThemeProvider } from '@/providers/theme-provider';
 import { createAppRouter } from '@/routes';
-import '@/app/globals.css';
+import '@/globals.css';
 
 const container = document.getElementById('root');
 if (!container) {

apps/web/src/providers/theme-provider.tsx

@@ -1,5 +1,3 @@
-'use client';
-
 import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
 
 export type Theme = 'dark' | 'light';

apps/web/src/routes.tsx

@@ -13,8 +13,18 @@ import {
   TasksRouteErrorBoundary,
 } from '@/spa/pages/resource-route-error-boundaries';
 import { TasksPage } from '@/spa/pages/tasks';
-import { AuthGuard, GuestGuard } from '@/spa/guards';
-import { Placeholder } from '@/spa/placeholder';
+import { SettingsPage } from '@/spa/pages/settings';
+import { AdminPage } from '@/spa/pages/admin';
+import { AdminGuard, AuthGuard, GuestGuard } from '@/spa/guards';
+import { AppShell } from '@/components/layout/app-shell';
+
+function DashboardLayout(): ReactElement {
+  return (
+    <AppShell>
+      <Outlet />
+    </AppShell>
+  );
+}
 
 function GuestLayout(): ReactElement {
   return (
@@ -43,21 +53,29 @@ export const routes: RouteObject[] = [
   {
     element: <AuthGuard />,
     children: [
-      { path: '/', element: <Navigate to="/chat" replace /> },
-      { path: '/chat', element: <ChatPage />, errorElement: <ChatRouteErrorBoundary /> },
       {
-        path: '/projects',
-        element: <ProjectsPage />,
-        errorElement: <ProjectsRouteErrorBoundary />,
+        element: <DashboardLayout />,
+        children: [
+          { path: '/', element: <Navigate to="/chat" replace /> },
+          { path: '/chat', element: <ChatPage />, errorElement: <ChatRouteErrorBoundary /> },
+          {
+            path: '/projects',
+            element: <ProjectsPage />,
+            errorElement: <ProjectsRouteErrorBoundary />,
+          },
+          {
+            path: '/projects/:id',
+            element: <ProjectDetailPage />,
+            errorElement: <ProjectDetailRouteErrorBoundary />,
+          },
+          { path: '/tasks', element: <TasksPage />, errorElement: <TasksRouteErrorBoundary /> },
+          { path: '/settings', element: <SettingsPage /> },
+          {
+            element: <AdminGuard />,
+            children: [{ path: '/admin', element: <AdminPage /> }],
+          },
+        ],
       },
-      {
-        path: '/projects/:id',
-        element: <ProjectDetailPage />,
-        errorElement: <ProjectDetailRouteErrorBoundary />,
-      },
-      { path: '/tasks', element: <TasksPage />, errorElement: <TasksRouteErrorBoundary /> },
-      { path: '/settings', element: <Placeholder title="Settings" /> },
-      { path: '/admin', element: <Placeholder title="Admin" /> },
     ],
   },
 ];

apps/web/src/spa/guards.tsx

@@ -21,3 +21,23 @@ export function AuthGuard(): ReactElement {
 
   return session ? <Outlet /> : <Navigate to="/login" replace />;
 }
+
+export function AdminGuard(): ReactElement {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="text-sm text-text-muted">Loading...</div>
+      </div>
+    );
+  }
+
+  if (!session) {
+    return <Navigate to="/login" replace />;
+  }
+
+  const user = session.user as typeof session.user & { role?: string };
+
+  return user.role === 'admin' ? <Outlet /> : <Navigate to="/" replace />;
+}

apps/web/src/spa/pages/admin.spec.tsx

@@ -0,0 +1,206 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { apiMock, useSessionMock } = vi.hoisted(() => ({
+  apiMock: vi.fn(),
+  useSessionMock: vi.fn(),
+}));
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  useSession: useSessionMock,
+  authClient: {},
+}));
+
+import { AdminPage } from './admin';
+import { AdminGuard } from '@/spa/guards';
+
+const userFixtures = {
+  users: [
+    {
+      id: 'u-admin',
+      name: 'Ada Admin',
+      email: '[email protected]',
+      role: 'admin',
+      banned: false,
+      banReason: null,
+      createdAt: '2026-08-01T00:00:00.000Z',
+      updatedAt: '2026-08-01T00:00:00.000Z',
+    },
+    {
+      id: 'u-member',
+      name: 'Mel Member',
+      email: '[email protected]',
+      role: 'member',
+      banned: true,
+      banReason: 'spam',
+      createdAt: '2026-08-02T00:00:00.000Z',
+      updatedAt: '2026-08-02T00:00:00.000Z',
+    },
+  ],
+  total: 2,
+};
+
+let root: Root | null = null;
+let container: HTMLDivElement;
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+afterEach(async () => {
+  await act(async () => {
+    root?.unmount();
+  });
+  document.body.replaceChildren();
+  root = null;
+  apiMock.mockReset();
+  useSessionMock.mockReset();
+});
+
+async function renderAdminRoute(): Promise<void> {
+  const routes: RouteObject[] = [
+    {
+      element: <AdminGuard />,
+      children: [{ path: '/admin', element: <AdminPage /> }],
+    },
+    { path: '/', element: <div>home page</div> },
+    { path: '/login', element: <div>login page</div> },
+  ];
+  const router = createMemoryRouter(routes, { initialEntries: ['/admin'] });
+  container = document.createElement('div');
+  document.body.append(container);
+  root = createRoot(container);
+
+  await act(async () => {
+    root?.render(<RouterProvider router={router} />);
+  });
+}
+
+function sessionWithRole(role: string | undefined): { data: unknown; isPending: boolean } {
+  return {
+    data: { user: { id: 'u-1', name: 'Test', email: '[email protected]', role } },
+    isPending: false,
+  };
+}
+
+describe('AdminGuard', () => {
+  it('redirects unauthenticated visitors to /login', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('login page');
+    expect(apiMock).not.toHaveBeenCalled();
+  });
+
+  it('redirects non-admin users to /', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('member'));
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('home page');
+    expect(apiMock).not.toHaveBeenCalled();
+  });
+
+  it('renders the admin page for admin users', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures);
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('Admin Panel');
+  });
+});
+
+describe('AdminPage users tab', () => {
+  it('lists users with role and ban status after load', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures);
+
+    await renderAdminRoute();
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/users');
+    expect(container.textContent).toContain('Ada Admin');
+    expect(container.textContent).toContain('Mel Member');
+    expect(container.textContent).toContain('Banned');
+    expect(container.textContent).toContain('2 user(s)');
+  });
+
+  it('shows the load error with a retry control', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockRejectedValueOnce(new Error('gateway unavailable'));
+
+    await renderAdminRoute();
+
+    expect(container.textContent).toContain('gateway unavailable');
+
+    apiMock.mockResolvedValueOnce(userFixtures);
+    const retry = [...container.querySelectorAll('button')].find((b) =>
+      b.textContent?.includes('Retry'),
+    );
+    expect(retry).toBeTruthy();
+    await act(async () => {
+      retry?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(container.textContent).toContain('Ada Admin');
+  });
+
+  it('posts to the ban endpoint and reloads on Ban', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValue(userFixtures);
+
+    await renderAdminRoute();
+
+    const banButton = [...container.querySelectorAll('button')].find(
+      (b) => b.textContent === 'Ban',
+    );
+    expect(banButton).toBeTruthy();
+    await act(async () => {
+      banButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/users/u-admin/ban', { method: 'POST' });
+  });
+});
+
+describe('AdminPage health tab', () => {
+  it('loads health status when the tab is opened', async () => {
+    useSessionMock.mockReturnValue(sessionWithRole('admin'));
+    apiMock.mockResolvedValueOnce(userFixtures).mockResolvedValueOnce({
+      status: 'ok',
+      database: { status: 'ok', latencyMs: 3 },
+      cache: { status: 'ok', latencyMs: 1 },
+      agentPool: { activeSessions: 2 },
+      providers: [{ id: 'ollama', name: 'Ollama', available: true, modelCount: 4 }],
+      checkedAt: '2026-08-26T00:00:00.000Z',
+    });
+
+    await renderAdminRoute();
+
+    const healthTab = [...container.querySelectorAll('button')].find((b) =>
+      b.textContent?.includes('System Health'),
+    );
+    await act(async () => {
+      healthTab?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(apiMock).toHaveBeenCalledWith('/api/admin/health');
+    expect(container.textContent).toContain('Database (PostgreSQL)');
+    expect(container.textContent).toContain('Active sessions: 2');
+    expect(container.textContent).toContain('4 models');
+  });
+});

apps/web/src/spa/pages/admin.tsx

@@ -1,7 +1,4 @@
-'use client';
-
 import { useEffect, useState, useCallback } from 'react';
-import { AdminRoleGuard } from '@/components/admin-role-guard';
 import { api } from '@/lib/api';
 import { cn } from '@/lib/cn';
 
@@ -47,15 +44,9 @@ interface HealthStatusDto {
 
 // ── Admin Page ─────────────────────────────────────────────────────────────────
 
-export default function AdminPage(): React.ReactElement {
-  return (
-    <AdminRoleGuard>
-      <AdminContent />
-    </AdminRoleGuard>
-  );
-}
-
-function AdminContent(): React.ReactElement {
+// Route-level access control lives in AdminGuard (spa/guards.tsx); this page
+// assumes an authenticated admin session.
+export function AdminPage(): React.ReactElement {
   const [activeTab, setActiveTab] = useState<'users' | 'health'>('users');
 
   return (

apps/web/src/spa/pages/chat-error-boundary.spec.tsx

@@ -11,6 +11,7 @@ vi.mock('@/lib/auth-client', () => ({
   useSession: useSessionMock,
 }));
 
+import { ThemeProvider } from '@/providers/theme-provider';
 import { routes } from '@/routes';
 
 beforeAll(() => {
@@ -73,7 +74,11 @@ describe('ChatRouteErrorBoundary', () => {
     const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     try {
       await act(async () => {
-        root?.render(<RouterProvider router={router} />);
+        root?.render(
+          <ThemeProvider>
+            <RouterProvider router={router} />
+          </ThemeProvider>,
+        );
       });
 
       expect(consoleErrorSpy).toHaveBeenCalled();

apps/web/src/spa/pages/project-detail.spec.tsx

@@ -35,6 +35,7 @@ afterEach(async () => {
   document.body.replaceChildren();
   root = null;
   apiMock.mockReset();
+  sessionStorage.clear();
 });
 
 async function renderProjectDetailPage(): Promise<ReturnType<typeof createMemoryRouter>> {
@@ -64,21 +65,49 @@ function clickButtonByText(text: string): void {
   button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
 }
 
+async function flushAct(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+}
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+const projectOneTasks = taskFixtures.filter((task) => task.projectId === 'project-1');
+
+function mockHealthyLoad(): void {
+  apiMock
+    .mockResolvedValueOnce(projectFixtures[0])
+    .mockResolvedValueOnce(missionFixtures)
+    .mockResolvedValueOnce(projectOneTasks);
+}
+
 describe('ProjectDetailPage', () => {
   it('loads the project, tasks, missions, and optional PRD content for the active project', async () => {
-    apiMock
-      .mockResolvedValueOnce(projectFixtures[0])
-      .mockResolvedValueOnce(missionFixtures)
-      .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
+    mockHealthyLoad();
 
     await renderProjectDetailPage();
 
-    expect(apiMock.mock.calls).toEqual([
-      ['/api/projects/project-1'],
-      ['/api/missions'],
-      ['/api/tasks?projectId=project-1'],
+    expect(apiMock.mock.calls.map((call) => call[0])).toEqual([
+      '/api/projects/project-1',
+      '/api/missions',
+      '/api/tasks?projectId=project-1',
     ]);
 
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'current',
+    );
     expect(container.textContent).toContain('Mosaic Stack');
     expect(container.textContent).toContain('Route /projects/:id');
     expect(container.textContent).toContain('Tasks');
@@ -101,10 +130,7 @@ describe('ProjectDetailPage', () => {
   });
 
   it('opens and closes the existing read-only task modal from the tasks tab', async () => {
-    apiMock
-      .mockResolvedValueOnce(projectFixtures[0])
-      .mockResolvedValueOnce(missionFixtures)
-      .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
+    mockHealthyLoad();
 
     await renderProjectDetailPage();
 
@@ -134,35 +160,153 @@ describe('ProjectDetailPage', () => {
     expect(container.querySelector('[role="dialog"]')).toBeNull();
   });
 
-  it('renders the project with an empty missions tab when the missions request fails', async () => {
-    apiMock
-      .mockResolvedValueOnce(projectFixtures[0])
-      .mockRejectedValueOnce(new Error('Missions request failed'))
-      .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
+  it('shows verified completion verdicts when the task collection is current', async () => {
+    mockHealthyLoad();
 
     await renderProjectDetailPage();
 
-    expect(container.textContent).toContain('Mosaic Stack');
-    expect(container.querySelector('[role="alert"]')).toBeNull();
-
-    await act(async () => {
-      clickButtonByText('Missions (0)');
-    });
-
-    expect(container.textContent).toContain('No missions for this project');
+    const doneCard = [...container.querySelectorAll('div')].find(
+      (candidate) => candidate.textContent === 'Done1',
+    );
+    expect(doneCard).toBeTruthy();
+    const inProgressCard = [...container.querySelectorAll('div')].find(
+      (candidate) => candidate.textContent === 'In Progress1',
+    );
+    expect(inProgressCard).toBeTruthy();
   });
 
-  it('renders a visible alert when the project request fails and lets the user navigate back', async () => {
+  it('renders an explicit unavailable missions tab when the missions request fails (partial, not empty)', async () => {
+    apiMock
+      .mockResolvedValueOnce(projectFixtures[0])
+      .mockRejectedValueOnce(new Error('Missions request failed'))
+      .mockResolvedValueOnce(projectOneTasks);
+
+    await renderProjectDetailPage();
+
+    // Secondary failure degrades the surface to partial; the project itself
+    // still renders.
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'partial',
+    );
+    expect(container.textContent).toContain('Mosaic Stack');
+    const partial = container.querySelector('[role="status"]');
+    expect(partial?.textContent).toContain('Missions');
+    expect(partial?.textContent).toContain('unavailable');
+
+    await act(async () => {
+      clickButtonByText('Missions (?)');
+    });
+
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('Missions request failed');
+    // Negative control: a failed fetch must not look like an empty list.
+    expect(container.textContent).not.toContain('No missions for this project');
+  });
+
+  it('marks derived verdicts unknown when the tasks collection is unavailable', async () => {
+    apiMock
+      .mockResolvedValueOnce(projectFixtures[0])
+      .mockResolvedValueOnce(missionFixtures)
+      .mockRejectedValueOnce(new Error('Tasks request failed'));
+
+    await renderProjectDetailPage();
+
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'partial',
+    );
+
+    // Completion verdicts become unknown ('?') — never green counts.
+    for (const label of ['Done', 'In Progress', 'Blocked', 'Tasks']) {
+      const unknownCard = [...container.querySelectorAll('div')].find(
+        (candidate) => candidate.textContent === `${label}?`,
+      );
+      expect(unknownCard, `expected ${label} card to render ?`).toBeTruthy();
+    }
+    // Negative control: no green "Done 1" verdict anywhere.
+    expect(
+      [...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'),
+    ).toBe(false);
+
+    await act(async () => {
+      clickButtonByText('Tasks (?)');
+    });
+
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('Tasks request failed');
+    // Negative control: no healthy empty task list from a failed fetch.
+    expect(container.textContent).not.toContain('No tasks found');
+    expect(container.querySelector('table')).toBeNull();
+  });
+
+  it('recovers a partial surface to current after revalidation', async () => {
+    apiMock
+      .mockResolvedValueOnce(projectFixtures[0])
+      .mockResolvedValueOnce(missionFixtures)
+      .mockRejectedValueOnce(new Error('Tasks request failed'))
+      .mockResolvedValueOnce(projectFixtures[0])
+      .mockResolvedValueOnce(missionFixtures)
+      .mockResolvedValueOnce(projectOneTasks);
+
+    await renderProjectDetailPage();
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'partial',
+    );
+
+    await act(async () => {
+      clickButtonByText('Revalidate');
+    });
+    await flushAct();
+
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'current',
+    );
+    expect(
+      [...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'),
+    ).toBe(true);
+  });
+
+  it("never shows one project's data on another project's route after navigation", async () => {
+    mockHealthyLoad();
+
+    const router = await renderProjectDetailPage();
+    expect(container.textContent).toContain('Mosaic Stack');
+
+    const deferred = createDeferred<(typeof projectFixtures)[number]>();
+    apiMock
+      .mockResolvedValueOnce(deferred.promise)
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([]);
+
+    await act(async () => {
+      await router.navigate('/projects/project-2');
+    });
+
+    // While project-2 loads, nothing from project-1 may render on its route.
+    expect(container.textContent).toContain('Loading project...');
+    expect(container.textContent).not.toContain('Mosaic Stack');
+    expect(container.textContent).not.toContain('Route /projects/:id');
+
+    await act(async () => {
+      deferred.resolve(projectFixtures[1]!);
+      await deferred.promise;
+    });
+
+    expect(container.textContent).toContain('Agent Runtime');
+    expect(apiMock.mock.calls[3]?.[0]).toBe('/api/projects/project-2');
+  });
+
+  it('renders a visible unavailable state when the project request fails and lets the user navigate back', async () => {
     apiMock
       .mockRejectedValueOnce(new Error('Project request failed'))
       .mockResolvedValueOnce(missionFixtures)
-      .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1'));
+      .mockResolvedValueOnce(projectOneTasks);
 
     const router = await renderProjectDetailPage();
 
     const alert = container.querySelector('[role="alert"]');
     expect(alert).toBeTruthy();
     expect(alert?.textContent).toContain('Project request failed');
+    expect(alert?.textContent).toContain('not an empty result');
     expect(container.textContent).not.toContain('Mosaic Stack');
 
     await act(async () => {

apps/web/src/spa/pages/project-detail.tsx

@@ -1,14 +1,30 @@
-import { useEffect, useState, type ReactElement } from 'react';
+import { useState, type ReactElement } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { MissionTimeline } from '@/components/projects/mission-timeline';
 import { PrdViewer } from '@/components/projects/prd-viewer';
 import { TaskDetailModal } from '@/components/tasks/task-detail-modal';
 import { TaskListView } from '@/components/tasks/task-list-view';
 import { TaskStatusSummary } from '@/components/tasks/task-status-summary';
+import {
+  PartialDataNotice,
+  StaleDataNotice,
+  UnavailableDataNotice,
+} from '@/components/freshness/freshness-notices';
 import { api } from '@/lib/api';
 import { cn } from '@/lib/cn';
 import type { Mission, Project, Task, TaskStatus } from '@/lib/types';
-import { getErrorMessage } from './page-errors';
+import {
+  combineFreshness,
+  UNKNOWN_VERDICT,
+  verdictValue,
+  type FreshSnapshot,
+} from '@/lib/freshness/model';
+import { describeFailure, useFreshCollection } from '@/lib/freshness/use-fresh-collection';
+import {
+  validateMissionCollection,
+  validateProjectEntity,
+  validateTaskCollection,
+} from '@/lib/freshness/validators';
 
 type Tab = 'overview' | 'tasks' | 'missions' | 'prd';
 
@@ -51,73 +67,62 @@ function TabButton({ id, label, activeTab, onClick }: TabButtonProps): ReactElem
   );
 }
 
+/** Remounts per project id so no state from one project renders for another. */
 export function ProjectDetailPage(): ReactElement {
   const { id = '' } = useParams();
+  return <ProjectDetail id={id} key={id} />;
+}
+
+function ProjectDetail({ id }: { id: string }): ReactElement {
   const navigate = useNavigate();
-  const [project, setProject] = useState<Project | null>(null);
-  const [missions, setMissions] = useState<Mission[]>([]);
-  const [tasks, setTasks] = useState<Task[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const enabled = id.length > 0;
+
+  // Primary collection gates the surface; missions and tasks are secondaries
+  // whose failures degrade the surface to `partial` instead of rendering
+  // empty healthy lists.
+  const project = useFreshCollection<Project>({
+    source: `gateway:/api/projects/${id}`,
+    fetcher: (signal) => api<unknown>(`/api/projects/${id}`, { signal }),
+    validate: validateProjectEntity,
+    // No last-known restore: the entity carries workspace identity that
+    // cannot be scope-checked before display (see ProjectsPage note).
+    enabled,
+  });
+  const missions = useFreshCollection<Mission[]>({
+    source: 'gateway:/api/missions',
+    fetcher: (signal) => api<unknown>('/api/missions', { signal }),
+    validate: validateMissionCollection,
+    cacheKey: enabled ? 'missions' : null,
+    enabled,
+  });
+  const tasks = useFreshCollection<Task[]>({
+    source: `gateway:/api/tasks?projectId=${id}`,
+    fetcher: (signal) => api<unknown>(`/api/tasks?projectId=${id}`, { signal }),
+    validate: validateTaskCollection,
+    cacheKey: enabled ? `project-tasks:${id}` : null,
+    enabled,
+  });
+
   const [activeTab, setActiveTab] = useState<Tab>('overview');
   const [taskFilter, setTaskFilter] = useState<TaskStatus | 'all'>('all');
   const [selectedTask, setSelectedTask] = useState<Task | null>(null);
 
-  useEffect(() => {
-    if (!id) {
-      setError('Project id is missing.');
-      setLoading(false);
-      return;
-    }
+  const surface = combineFreshness(project.freshness, [missions.freshness, tasks.freshness]);
+  const tasksVerified = tasks.freshness === 'current';
+  const projectMissions = missions.data?.filter((mission) => mission.projectId === id) ?? null;
 
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
+  const retryAll = (): void => {
+    void Promise.all([project.revalidate(), missions.revalidate(), tasks.revalidate()]);
+  };
 
-    void Promise.all([
-      api<Project>('/api/projects/' + id),
-      api<Mission[]>('/api/missions').catch(() => [] as Mission[]),
-      api<Task[]>('/api/tasks?projectId=' + id).catch(() => [] as Task[]),
-    ])
-      .then(([loadedProject, allMissions, loadedTasks]) => {
-        if (cancelled) return;
-        setProject(loadedProject);
-        setMissions(allMissions.filter((mission) => mission.projectId === id));
-        setTasks(loadedTasks);
-      })
-      .catch((caught: unknown) => {
-        if (cancelled) return;
-        setError(getErrorMessage(caught, 'Failed to load project.'));
-      })
-      .finally(() => {
-        if (cancelled) return;
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [id]);
-
-  if (loading) {
-    return (
-      <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
-        <header className="mb-6 border-b px-1 pb-3">
-          <h1 className="text-2xl font-semibold">Project</h1>
-        </header>
-        <p className="py-16 text-center text-sm text-text-muted">Loading project...</p>
-      </div>
-    );
-  }
-
-  if (error || !project) {
+  if (!enabled) {
     return (
       <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
         <header className="mb-6 border-b px-1 pb-3">
           <h1 className="text-2xl font-semibold">Project</h1>
         </header>
         <div role="alert" className="rounded-lg border border-error/40 px-4 py-3 text-sm">
-          {error ?? 'Project not found.'}
+          Project id is missing.
         </div>
         <button
           type="button"
@@ -130,18 +135,81 @@ export function ProjectDetailPage(): ReactElement {
     );
   }
 
+  if (project.freshness === 'unknown') {
+    return (
+      <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
+        <header className="mb-6 border-b px-1 pb-3">
+          <h1 className="text-2xl font-semibold">Project</h1>
+        </header>
+        <p className="py-16 text-center text-sm text-text-muted">Loading project...</p>
+      </div>
+    );
+  }
+
+  if (project.freshness === 'unavailable' || project.data === null) {
+    return (
+      <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
+        <header className="mb-6 border-b px-1 pb-3">
+          <h1 className="text-2xl font-semibold">Project</h1>
+        </header>
+        <UnavailableDataNotice
+          title="This project"
+          detail={describeFailure(project.failure)}
+          onRetry={retryAll}
+        />
+        <button
+          type="button"
+          onClick={() => navigate('/projects')}
+          className="mt-4 w-fit text-sm underline"
+        >
+          Back to projects
+        </button>
+      </div>
+    );
+  }
+
+  const projectTasks = tasks.data ?? null;
   const filteredTasks =
-    taskFilter === 'all' ? tasks : tasks.filter((task) => task.status === taskFilter);
-  const prdContent = getPrdContent(project);
+    projectTasks === null
+      ? []
+      : taskFilter === 'all'
+        ? projectTasks
+        : projectTasks.filter((task) => task.status === taskFilter);
+
+  // Derived completion verdicts: unknown (never green) unless the task
+  // collection is verified current.
+  const doneCount = projectTasks?.filter((task) => task.status === 'done').length ?? 0;
+  const inProgressCount = projectTasks?.filter((task) => task.status === 'in-progress').length ?? 0;
+  const blockedCount = projectTasks?.filter((task) => task.status === 'blocked').length ?? 0;
+
+  const prdContent = getPrdContent(project.data);
   const tabs: Array<{ id: Tab; label: string }> = [
     { id: 'overview', label: 'Overview' },
-    { id: 'tasks', label: `Tasks (${tasks.length})` },
-    { id: 'missions', label: `Missions (${missions.length})` },
+    {
+      id: 'tasks',
+      label: `Tasks (${projectTasks === null ? UNKNOWN_VERDICT : projectTasks.length})`,
+    },
+    {
+      id: 'missions',
+      label: `Missions (${projectMissions === null ? UNKNOWN_VERDICT : projectMissions.length})`,
+    },
     ...(prdContent ? [{ id: 'prd' as const, label: 'PRD' }] : []),
   ];
 
+  const staleSnapshot: FreshSnapshot<unknown> | null =
+    project.freshness === 'stale'
+      ? project.snapshot
+      : missions.freshness === 'stale'
+        ? missions.snapshot
+        : tasks.freshness === 'stale'
+          ? tasks.snapshot
+          : null;
+  const missingSections: string[] = [];
+  if (missions.freshness === 'unavailable') missingSections.push('Missions');
+  if (tasks.freshness === 'unavailable') missingSections.push('Tasks');
+
   return (
-    <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
+    <div data-freshness={surface} className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
       <header className="mb-6 border-b px-1 pb-3">
         <nav className="mb-4 flex items-center gap-2 text-sm text-text-muted">
           <button
@@ -152,49 +220,64 @@ export function ProjectDetailPage(): ReactElement {
             Projects
           </button>
           <span>/</span>
-          <span className="text-text-primary">{project.name}</span>
+          <span className="text-text-primary">{project.data.name}</span>
         </nav>
 
         <div className="flex items-start justify-between gap-4">
           <div>
             <div className="flex items-center gap-3">
-              <h1 className="text-2xl font-semibold text-text-primary">{project.name}</h1>
+              <h1 className="text-2xl font-semibold text-text-primary">{project.data.name}</h1>
               <span
                 className={cn(
                   'rounded-full px-2 py-0.5 text-xs',
-                  projectStatusColors[project.status] ?? 'bg-gray-600/20 text-gray-400',
+                  projectStatusColors[project.data.status] ?? 'bg-gray-600/20 text-gray-400',
                 )}
               >
-                {project.status}
+                {project.data.status}
               </span>
             </div>
-            {project.description ? (
-              <p className="mt-1 text-sm text-text-muted">{project.description}</p>
+            {project.data.description ? (
+              <p className="mt-1 text-sm text-text-muted">{project.data.description}</p>
             ) : null}
             <p className="mt-2 text-xs text-text-muted">
-              Created {new Date(project.createdAt).toLocaleDateString()} · Updated{' '}
-              {new Date(project.updatedAt).toLocaleDateString()}
+              Created {new Date(project.data.createdAt).toLocaleDateString()} · Updated{' '}
+              {new Date(project.data.updatedAt).toLocaleDateString()}
             </p>
           </div>
         </div>
       </header>
 
+      {staleSnapshot !== null ? (
+        <div className="mb-6">
+          <StaleDataNotice label={staleSnapshot} onRetry={retryAll} />
+        </div>
+      ) : null}
+
+      {missingSections.length > 0 ? (
+        <div className="mb-6">
+          <PartialDataNotice missing={missingSections} onRetry={retryAll} />
+        </div>
+      ) : null}
+
       <div className="mb-6 grid grid-cols-2 gap-3 sm:grid-cols-4">
-        <StatCard label="Tasks" value={String(tasks.length)} />
+        <StatCard
+          label="Tasks"
+          value={projectTasks === null ? UNKNOWN_VERDICT : String(projectTasks.length)}
+        />
         <StatCard
           label="Done"
-          value={String(tasks.filter((task) => task.status === 'done').length)}
-          valueClass="text-success"
+          value={verdictValue(tasksVerified, String(doneCount))}
+          valueClass={tasksVerified ? 'text-success' : undefined}
         />
         <StatCard
           label="In Progress"
-          value={String(tasks.filter((task) => task.status === 'in-progress').length)}
-          valueClass="text-blue-400"
+          value={verdictValue(tasksVerified, String(inProgressCount))}
+          valueClass={tasksVerified ? 'text-blue-400' : undefined}
         />
         <StatCard
           label="Blocked"
-          value={String(tasks.filter((task) => task.status === 'blocked').length)}
-          valueClass={tasks.some((task) => task.status === 'blocked') ? 'text-error' : undefined}
+          value={verdictValue(tasksVerified, String(blockedCount))}
+          valueClass={tasksVerified && blockedCount > 0 ? 'text-error' : undefined}
         />
       </div>
 
@@ -211,23 +294,43 @@ export function ProjectDetailPage(): ReactElement {
       </div>
 
       {activeTab === 'overview' ? (
-        <OverviewTab project={project} missions={missions} tasks={tasks} />
+        <OverviewTab project={project.data} missions={projectMissions} tasks={projectTasks} />
       ) : null}
 
       {activeTab === 'tasks' ? (
         <div>
-          <div className="mb-4">
-            <TaskStatusSummary
-              tasks={tasks}
-              activeFilter={taskFilter}
-              onFilterChange={setTaskFilter}
+          {projectTasks === null ? (
+            <UnavailableDataNotice
+              title="Tasks"
+              detail={describeFailure(tasks.failure)}
+              onRetry={retryAll}
             />
-          </div>
-          <TaskListView tasks={filteredTasks} onTaskClick={setSelectedTask} />
+          ) : (
+            <>
+              <div className="mb-4">
+                <TaskStatusSummary
+                  tasks={projectTasks}
+                  activeFilter={taskFilter}
+                  onFilterChange={setTaskFilter}
+                />
+              </div>
+              <TaskListView tasks={filteredTasks} onTaskClick={setSelectedTask} />
+            </>
+          )}
         </div>
       ) : null}
 
-      {activeTab === 'missions' ? <MissionTimeline missions={missions} /> : null}
+      {activeTab === 'missions' ? (
+        projectMissions === null ? (
+          <UnavailableDataNotice
+            title="Missions"
+            detail={describeFailure(missions.failure)}
+            onRetry={retryAll}
+          />
+        ) : (
+          <MissionTimeline missions={projectMissions} />
+        )
+      ) : null}
 
       {activeTab === 'prd' && prdContent ? (
         <div className="rounded-lg border border-surface-border bg-surface-card p-6">
@@ -248,18 +351,26 @@ function OverviewTab({
   tasks,
 }: {
   project: Project;
-  missions: Mission[];
-  tasks: Task[];
+  missions: Mission[] | null;
+  tasks: Task[] | null;
 }): ReactElement {
-  const recentTasks = [...tasks]
-    .sort((left, right) => new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime())
-    .slice(0, 5);
+  const recentTasks =
+    tasks === null
+      ? null
+      : [...tasks]
+          .sort(
+            (left, right) =>
+              new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime(),
+          )
+          .slice(0, 5);
 
   return (
     <div className="grid gap-6 lg:grid-cols-2">
       <section>
         <h2 className="mb-3 text-sm font-semibold text-text-secondary">Recent Tasks</h2>
-        {recentTasks.length === 0 ? (
+        {recentTasks === null ? (
+          <UnavailableDataNotice title="Tasks" />
+        ) : recentTasks.length === 0 ? (
           <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
             <p className="text-sm text-text-muted">No tasks yet</p>
           </div>
@@ -287,7 +398,9 @@ function OverviewTab({
 
       <section>
         <h2 className="mb-3 text-sm font-semibold text-text-secondary">Missions</h2>
-        {missions.length === 0 ? (
+        {missions === null ? (
+          <UnavailableDataNotice title="Missions" />
+        ) : missions.length === 0 ? (
           <div className="rounded-lg border border-surface-border bg-surface-card p-4 text-center">
             <p className="text-sm text-text-muted">No missions yet</p>
           </div>

apps/web/src/spa/pages/projects.spec.tsx

@@ -51,6 +51,7 @@ afterEach(async () => {
   document.body.replaceChildren();
   root = null;
   apiMock.mockReset();
+  sessionStorage.clear();
 });
 
 async function renderProjectsPage(): Promise<ReturnType<typeof createMemoryRouter>> {
@@ -71,6 +72,22 @@ async function renderProjectsPage(): Promise<ReturnType<typeof createMemoryRoute
   return router;
 }
 
+function clickButtonByText(text: string): void {
+  const button = [...container.querySelectorAll('button')].find((candidate) =>
+    candidate.textContent?.includes(text),
+  );
+  if (!button) {
+    throw new Error(`Button containing "${text}" not found`);
+  }
+  button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+}
+
+async function flushAct(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
 describe('ProjectsPage', () => {
   it('shows a visible loading state while the project request is in flight', async () => {
     const deferred = createDeferred<typeof projectFixtures>();
@@ -91,7 +108,7 @@ describe('ProjectsPage', () => {
 
     const router = await renderProjectsPage();
 
-    expect(apiMock).toHaveBeenCalledWith('/api/projects');
+    expect(apiMock.mock.calls[0]?.[0]).toBe('/api/projects');
     expect(container.textContent).toContain('Mosaic Stack');
     expect(container.textContent).toContain('Agent Runtime');
 
@@ -108,7 +125,7 @@ describe('ProjectsPage', () => {
     expect(container.textContent).toContain('Project detail target');
   });
 
-  it('renders the empty state when the API returns no projects', async () => {
+  it('renders the empty state only for a verified empty collection', async () => {
     apiMock.mockResolvedValueOnce([]);
 
     await renderProjectsPage();
@@ -117,9 +134,12 @@ describe('ProjectsPage', () => {
     expect(container.textContent).toContain(
       'Projects will appear here when created via the gateway API',
     );
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'current',
+    );
   });
 
-  it('renders a visible alert when the projects request fails', async () => {
+  it('renders a failed fetch as an explicit unavailable state, never an empty collection', async () => {
     apiMock.mockRejectedValueOnce(new Error('Projects are unavailable'));
 
     await renderProjectsPage();
@@ -127,5 +147,51 @@ describe('ProjectsPage', () => {
     const alert = container.querySelector('[role="alert"]');
     expect(alert).toBeTruthy();
     expect(alert?.textContent).toContain('Projects are unavailable');
+    expect(alert?.textContent).toContain('not an empty result');
+
+    // Negative controls: no healthy empty state and no project cards render
+    // from a failed fetch.
+    expect(container.textContent).not.toContain('No projects yet');
+    expect(container.textContent).not.toContain('Mosaic Stack');
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'unavailable',
+    );
+  });
+
+  it('renders an auth failure as unavailable and recovers after retry', async () => {
+    apiMock
+      .mockRejectedValueOnce(Object.assign(new Error('Unauthorized'), { statusCode: 401 }))
+      .mockResolvedValueOnce(projectFixtures);
+
+    await renderProjectsPage();
+
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('Unauthorized');
+    expect(container.textContent).not.toContain('No projects yet');
+
+    await act(async () => {
+      clickButtonByText('Retry');
+    });
+    await flushAct();
+
+    expect(container.querySelector('[role="alert"]')).toBeNull();
+    expect(container.textContent).toContain('Mosaic Stack');
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'current',
+    );
+  });
+
+  it('renders a schema-mismatched response as unavailable, never as data', async () => {
+    apiMock.mockResolvedValueOnce({ results: projectFixtures });
+
+    await renderProjectsPage();
+
+    const alert = container.querySelector('[role="alert"]');
+    expect(alert?.textContent).toContain('not an empty result');
+    expect(container.textContent).not.toContain('Mosaic Stack');
+    expect(container.textContent).not.toContain('No projects yet');
+    expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe(
+      'unavailable',
+    );
   });
 });

apps/web/src/spa/pages/projects.tsx

@@ -1,53 +1,51 @@
-import { useEffect, useState, type ReactElement } from 'react';
+import { type ReactElement } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { ProjectCard } from '@/components/projects/project-card';
+import { StaleDataNotice, UnavailableDataNotice } from '@/components/freshness/freshness-notices';
 import { api } from '@/lib/api';
 import type { Project } from '@/lib/types';
-import { getErrorMessage } from './page-errors';
+import { useFreshCollection, describeFailure } from '@/lib/freshness/use-fresh-collection';
+import { validateProjectCollection } from '@/lib/freshness/validators';
 
 export function ProjectsPage(): ReactElement {
   const navigate = useNavigate();
-  const [projects, setProjects] = useState<Project[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    void api<Project[]>('/api/projects')
-      .then((response) => {
-        if (cancelled) return;
-        setProjects(response);
-      })
-      .catch((caught: unknown) => {
-        if (cancelled) return;
-        setError(getErrorMessage(caught, 'Failed to load projects.'));
-      })
-      .finally(() => {
-        if (cancelled) return;
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, []);
+  const projects = useFreshCollection<Project[]>({
+    source: 'gateway:/api/projects',
+    fetcher: (signal) => api<unknown>('/api/projects', { signal }),
+    validate: validateProjectCollection,
+    // Projects carry workspace identity (userId) that is only knowable from
+    // the payload itself, so a restored entry cannot be scope-checked before
+    // display. Conservative choice: no last-known restore for this surface;
+    // cross-workspace switching is still invalidated at verification time.
+  });
+  const retry = (): void => {
+    void projects.revalidate();
+  };
 
   return (
-    <div className="flex min-h-screen flex-col px-4 py-6 sm:px-6">
+    <div
+      data-freshness={projects.freshness}
+      className="flex min-h-screen flex-col px-4 py-6 sm:px-6"
+    >
       <header className="mb-6 border-b px-1 pb-3">
         <h1 className="text-2xl font-semibold">Projects</h1>
       </header>
 
-      {error ? (
-        <div role="alert" className="mb-6 rounded-lg border border-error/40 px-4 py-3 text-sm">
-          {error}
+      {projects.freshness === 'stale' && projects.snapshot ? (
+        <div className="mb-6">
+          <StaleDataNotice label={projects.snapshot} onRetry={retry} />
         </div>
       ) : null}
 
-      {loading ? (
+      {projects.freshness === 'unknown' ? (
         <p className="py-8 text-center text-sm text-text-muted">Loading projects...</p>
-      ) : projects.length === 0 ? (
+      ) : projects.freshness === 'unavailable' ? (
+        <UnavailableDataNotice
+          title="Projects"
+          detail={describeFailure(projects.failure)}
+          onRetry={retry}
+        />
+      ) : projects.data !== null && projects.data.length === 0 ? (
         <div className="py-12 text-center">
           <h2 className="text-lg font-medium text-text-secondary">No projects yet</h2>
           <p className="mt-1 text-sm text-text-muted">
@@ -56,7 +54,7 @@ export function ProjectsPage(): ReactElement {
         </div>
       ) : (
         <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-          {projects.map((project) => (
+          {(projects.data ?? []).map((project) => (
             <ProjectCard
               key={project.id}
               project={project}