From 5c34e6c77b0dde124a90a8979e706bfc6788d5d8 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 22:29:51 +0200
Subject: [PATCH 01/47] docs(plan): audit remediation implementation plan

---
 .../plans/2026-07-20-audit-remediation.md     | 382 ++++++++++++++++++
 1 file changed, 382 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-20-audit-remediation.md

diff --git a/docs/superpowers/plans/2026-07-20-audit-remediation.md b/docs/superpowers/plans/2026-07-20-audit-remediation.md
new file mode 100644
index 00000000..9ce1fe85
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-20-audit-remediation.md
@@ -0,0 +1,382 @@
+# Audit Remediation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Close every fixable gap found in the 2026-07-20 whole-project audit: wrong/stale docs, dead config knobs, unrun CI lanes, and four "looks wired but silently does nothing" code paths, plus missing trust-layer surfaces and docs.
+
+**Architecture:** Four phases. Phase 1 makes docs/config tell the truth (independent file sets, parallel-safe). Phase 2 makes CI actually gate what exists. Phase 3 wires the silent-failure code paths. Phase 4 completes the trust-layer surfaces (REST/UI). Each task is independently reviewable and committed separately.
+
+**Tech Stack:** Python 3.12 + uv workspace (FastAPI, Celery, SQLAlchemy/Alembic, pydantic), Next.js 16/React 19 + vitest (`apps/web`), GitHub Actions, docker compose, Caddy/nginx.
+
+## Global Constraints
+
+- Branch: all work lands on `audit-remediation` (branched from `main` @ `24832c7`). One conventional commit per task — `cz check` gates PR commits, so messages MUST match `type(scope): subject` (feat/fix/docs/ci/chore/test/refactor).
+- NEVER run whole-repo `pytest` in a task (db migration tests alone take ~20 min). Run targeted paths only, e.g. `uv run pytest apps/worker/tests -q`.
+- New Python test files MUST either have a repo-unique basename or live in a directory containing `__init__.py` — whole-repo collection breaks on duplicate bare basenames (until Task 9 lands importlib mode).
+- Python: `uv run <cmd>` (pytest, mypy, ruff). Web: `pnpm --filter @forge/web <script>` (lint, typecheck, test, build).
+- Follow existing layout patterns exactly: API routers in `apps/api/forge_api/routers/`, pydantic schemas in `apps/api/forge_api/schemas/`, services in `apps/api/forge_api/services/`, worker tasks in `apps/worker/forge_worker/tasks/`, web components in `apps/web/src/components/<area>/` with colocated `.test.tsx`.
+- Do not touch `security/waivers.yaml`, `.semgrep/forge.yml`, or anything under `docs/security/evidence/`.
+- Honesty rule (house style): never fake a capability. If something can't work yet, the UI/docs must say so plainly (see existing `dev-banner.tsx` pattern).
+- Out of scope (do NOT attempt): creds-gated live gates/runbooks, pentest/soak human gates, learned-reranker eval numbers, `infra/` apply, Self-Eval Phase B, object-storage (MinIO) client subsystem, frontend workspace routing (F02), coverage-floor expansion beyond current 2 modules, multi-process SSO replay stores, SSO deprovision run-cancel.
+
+## Model assignment
+
+| Task | Title | Model |
+|---|---|---|
+| 1 | BYOK env truth + scripted-fallback warning | opus |
+| 2 | Doc-drift sweep (secret var, shipped features, package maps) | sonnet |
+| 3 | CHANGELOG + RELEASE_READINESS regeneration | sonnet |
+| 4 | Trust-layer + realtime + orchestration docs | opus |
+| 5 | Nginx reverse-proxy config + doc | sonnet |
+| 6 | FORGE_SPEC realignment | sonnet |
+| 7 | Web CI lanes (vitest + tsc) | opus |
+| 8 | mypy full package coverage | opus |
+| 9 | pytest basename-collision guard + importlib | opus |
+| 10 | CI/config hygiene (ui-kit excludes, board_v1, release draft input) | sonnet |
+| 11 | Schema-drift gate | opus |
+| 12 | Slack `/forge status` wiring | opus |
+| 13 | Legacy in-memory approval router retirement | opus |
+| 14 | Deployment worker task registration | opus |
+| 15 | SAML SLO honest UI | sonnet |
+| 16 | Spec review reject/request-changes persistence | fable |
+| 17 | Supervised multi-agent dispatch | fable |
+| 18 | PM sync board-write path | fable |
+| 19 | Attested Changesets REST + web UI | fable |
+| 20 | Red-Team Gate trigger endpoint + V1 worker path | fable |
+| 21 | Self-Eval Gate web UI | fable |
+
+---
+
+## Phase 1 — Truth in docs & config
+
+### Task 1: BYOK env truth + scripted-fallback warning
+
+**Files:**
+- Modify: `.env.example` (lines ~88-105 model/rerank/embedding block)
+- Modify: `docs/integrations/byok-and-boards.md:46,51`
+- Modify: `docs/getting-started.md`, `docs/architecture.md` (every `MODEL_PROVIDER`/`MODEL_PROVIDER_KEY` mention)
+- Modify: `apps/worker/forge_worker/agent_runner.py:118-130` (`_resolve_model_client`)
+- Test: `apps/worker/tests/` (existing test file for agent_runner; add warning assertions there)
+
+**Interfaces:**
+- Consumes: `forge_agent.providers.config.ModelClientConfig.from_env()` — returns `None` when `FORGE_MODEL_PROVIDER` unset (`packages/agent-runtime/forge_agent/providers/config.py:65-79`).
+- Produces: no API change; a `logging` warning emitted exactly once per `_resolve_model_client` fallback.
+
+**Background (verified):** `.env.example:90-91` ships `MODEL_PROVIDER=anthropic` / `MODEL_PROVIDER_KEY=` but NOTHING reads those names. Real knobs: `FORGE_MODEL_PROVIDER` (`anthropic|openai`), `FORGE_MODEL_NAME`, key resolution order `FORGE_MODEL_API_KEY` → `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`. When unset the worker silently uses the offline `ScriptedModelClient`.
+
+- [ ] **Step 1:** Read `packages/agent-runtime/forge_agent/providers/config.py` fully; list every env var it reads (also `EMBEDDING_MODEL`, `EMBEDDING_BASE_URL`, `EMBEDDING_DIM` readers in `packages/knowledge-core`, and `FORGE_RERANK_*` readers in `packages/knowledge-core/forge_knowledge/reranker.py`).
+- [ ] **Step 2:** Rewrite the `.env.example` model block: replace `MODEL_PROVIDER`/`MODEL_PROVIDER_KEY` with commented, documented `FORGE_MODEL_PROVIDER=anthropic`, `FORGE_MODEL_NAME=`, `FORGE_MODEL_API_KEY=` (+ note about `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` fallback). Delete dead knobs `EMBEDDING_PROVIDER`, `FORGE_RERANK_MODEL`, `RERANKER_URL`, `RERANKER_MODEL`. Add missing real knobs `EMBEDDING_BASE_URL`, `EMBEDDING_DIM`. Keep `MINIO_ROOT_USER`/`MINIO_ROOT_PASSWORD` ONLY if `grep MINIO deploy/docker-compose*.yml` shows compose consumes them (it does for the minio service); delete `MINIO_ENDPOINT`, `MINIO_BUCKET`, `FORGE_POSTMORTEMS_BUCKET` if nothing reads them, with a one-line comment pointing to the parked object-storage scope.
+- [ ] **Step 3:** Fix the same var names in `docs/getting-started.md`, `docs/architecture.md`, and `docs/integrations/byok-and-boards.md` (drop `EMBEDDING_PROVIDER` and `FORGE_RERANK_MODEL` rows; the real rerank knobs are `FORGE_RERANK_{ENABLED,PROVIDER,BASE_URL,TIMEOUT_MS,ALLOW_INSECURE_URL}`).
+- [ ] **Step 4:** Write failing test: when `FORGE_MODEL_PROVIDER` is unset, `_resolve_model_client` logs a WARNING containing `ScriptedModelClient` and `FORGE_MODEL_PROVIDER` (use `caplog`). Run it; expect FAIL (no warning today).
+- [ ] **Step 5:** Add the warning in `_resolve_model_client` fallback branch. Run the worker test file; expect PASS.
+- [ ] **Step 6:** Verify no stale references remain: `grep -rn "MODEL_PROVIDER_KEY\|EMBEDDING_PROVIDER=\|FORGE_RERANK_MODEL" --include="*.md" docs README.md .env.example` → 0 hits (except historical CHANGELOG).
+- [ ] **Step 7:** Commit: `fix(config): document real FORGE_MODEL_* env vars and warn on scripted-client fallback`
+
+### Task 2: Doc-drift sweep
+
+**Files:**
+- Modify: `docs/self-hosting/quickstart.md:28` (`SECRET_KEY` → `FORGE_SECRET_KEY`)
+- Modify: `README.md:39-44,57-58,69,74,130-149`
+- Modify: `docs/concepts.md:134-145` (+ new OIDC bullet, orchestration mention)
+- Modify: `docs/architecture.md:53-73` (package map)
+- Modify: `docs/self-hosting/docker-compose.md:18-41`
+- Modify: `apps/web/src/lib/api/client.ts:1-8` (stale "Phase-0 stub" docstring)
+
+**Interfaces:** none (docs only).
+
+Fixes, each with verified reality:
+1. quickstart: set `FORGE_SECRET_KEY` (deprecated alias `SECRET_KEY` warned at `apps/api/forge_api/cli_secrets.py:41`).
+2. README:69 + concepts:143 — marketplace in-app publish SHIPPED (`apps/api/forge_api/routers/marketplace.py:293`, `apps/web/src/components/marketplace/publish-dialog.tsx`). Remove "offline author CLI only / UI in progress".
+3. README:74 + concepts:145 — leaderboard UI SHIPPED (`apps/web/src/app/(board)/leaderboard/page.tsx`).
+4. README:44,71 — OIDC SHIPPED (`apps/api/forge_api/routers/oidc.py`); add OIDC to concepts SSO section (concepts currently SAML/SCIM only).
+5. README:57 — default sandbox is `worktree` (`.env.example` `FORGE_SANDBOX_KIND=worktree`), container optional.
+6. README:39-42 — replace the named 15-screen list with the actual `(board)` routes: approvals, audit, board, deployments, depth, incidents, leaderboard, marketplace, observability, runs, settings, specs, sprints, walkthrough, workflow.
+7. README repo layout + architecture package map — add `packages/orchestration-policy/` (Adaptive Orchestration, `forge_orchestration_policy`); both maps currently list 19 of 20.
+8. docker-compose.md — add `docker-proxy` (`deploy/docker-compose.yml:472`) and `sandbox-proxy` (`:523`) to the service table; list all 7 networks (edge, backend, data, mcp, sandbox_ctl, sandbox_egress, observability), noting profile-gated ones.
+9. client.ts header comment — routes are implemented; describe the 501 handler as a residual safety net.
+
+- [ ] **Step 1:** Apply all nine edits (evidence lines above; re-verify each against current code before editing).
+- [ ] **Step 2:** `grep -n "UI in progress\|still landing\|offline author CLI" README.md docs/concepts.md` → 0 hits.
+- [ ] **Step 3:** `pnpm --filter @forge/web lint` (client.ts comment change) → clean.
+- [ ] **Step 4:** Commit: `docs: fix stale feature status, secret var name, package maps, compose tables`
+
+### Task 3: CHANGELOG + RELEASE_READINESS regeneration
+
+**Files:**
+- Modify: `CHANGELOG.md`, `RELEASE_READINESS.md`, `Makefile` (release-readiness target)
+
+**Interfaces:** none.
+
+- [ ] **Step 1:** `uv run cz changelog --dry-run` (per CHANGELOG.md:6-8 header). If output includes the trust-layer PRs (#61-#66, #57, #36), regenerate the file with `uv run cz changelog`; otherwise append an Unreleased section manually covering: Attested Changesets (#61), Time-Travel Runs (#62), Red-Team Gate (#63), Self-Eval Gate (#64-#66), OIDC SSO + marketplace publish + leaderboard (#57), realtime co-editing (#36). Keep existing entries.
+- [ ] **Step 2:** Verify: `grep -in "attested\|time-travel\|red-team\|self-eval\|oidc" CHANGELOG.md` → all present.
+- [ ] **Step 3:** Makefile `release-readiness` target currently forces `--bar production` while the committed artifact and `docs/README.md:51` describe the beta bar. Parameterize: `BAR ?= beta` and use `--bar $(BAR)`.
+- [ ] **Step 4:** Regenerate: `uv run forge-release-readiness --bar beta > RELEASE_READINESS.md` (or the Make target's exact invocation — read `packages/evaluation/forge_eval/release/readiness.py` first for the real CLI shape; it writes the markdown itself). Expect: updated timestamp/commit, G-ATTEST row now present, no-creds gates still SKIPPED_NO_CREDS. This may take minutes; that's fine. Never let it run whole-repo pytest — if the render shells out to long gates, use its evidence/skip mode (read the module to confirm flags).
+- [ ] **Step 5:** Sanity: `head -40 RELEASE_READINESS.md` shows HEAD commit hash and today's date.
+- [ ] **Step 6:** Commit: `docs(release): regenerate changelog and readiness snapshot at current HEAD`
+
+### Task 4: Trust-layer + realtime + orchestration docs
+
+**Files:**
+- Create: `docs/trust-layer.md`
+- Modify: `docs/concepts.md` (new "Trust layer" section + realtime co-editing subsection + Adaptive Orchestration para)
+- Modify: `docs/architecture.md` (cross-link trust-layer components)
+- Modify: `docs/README.md` (index entry)
+
+**Interfaces:** none (docs); MUST be written from code, not imagination.
+
+- [ ] **Step 1:** Read, then document, each feature (one section each in `docs/trust-layer.md`, ~1 page per feature: what it is, data model, API/CLI surface, current limitations):
+  - Attested Changesets: `packages/contracts/forge_contracts/attestation.py`, `packages/observability/forge_obs/attest/signing.py`, `apps/api/forge_api/services/attestation_service.py`, CLI `forge-verify` (`apps/api/forge_api/cli_verify.py`), migration `0036`. Limitation: minted as approval side-effect; REST/UI arrive in Task 19.
+  - Time-Travel Runs: `apps/api/forge_api/routers/agent.py:259` (replay), `:316` (fork), `apps/worker/forge_worker/agent_runner.py` recording, `forge-replay` CLI, migration `0037`, web `run-trace/time-travel-replay.tsx`.
+  - Red-Team Gate: `packages/workflow-engine/forge_workflow/temporal/workflows.py:141`, `packages/multi-agent-coordinator/forge_coordinator/red_team.py`, `GET /workflow/runs/{id}/red-team` (`routers/workflow.py:227`), migration `0038`. Limitation (state plainly): defaults to a recorded "parked-pass" verdict when no adversary model/sandbox is wired (`temporal/activities.py:128-134`); Temporal path only until Task 20.
+  - Self-Eval Gate: `apps/api/forge_api/services/self_eval_gate.py`, `self_eval_service.py`, `routers/ao_settings.py`, worker `tasks/self_eval_{mint,run}.py`, migrations `0039`/`0040`. Limitation: Phase A; API-layer gate no-ops without a baseline scorecard.
+- [ ] **Step 2:** Add concepts.md subsections: trust layer summary (link to docs/trust-layer.md), realtime co-editing (yjs/y-websocket, `apps/api/forge_api/routers/realtime.py`), Adaptive Orchestration (`packages/orchestration-policy/README.md` is the source).
+- [ ] **Step 3:** Link check: every relative link added resolves (`ls` each target).
+- [ ] **Step 4:** Commit: `docs: document trust layer, realtime co-editing, and adaptive orchestration`
+
+### Task 5: Nginx reverse-proxy config + doc
+
+**Files:**
+- Create: `deploy/nginx/forge.conf`
+- Create: `docs/self-hosting/reverse-proxy.md`
+- Modify: `docs/self-hosting/quickstart.md` (one line linking the new doc)
+
+**Interfaces:** mirrors `deploy/caddy/Caddyfile` routing exactly (same upstreams/ports/paths, incl. websocket upgrade for realtime + MCP SSE if present).
+
+- [ ] **Step 1:** Read `deploy/caddy/Caddyfile` and `deploy/docker-compose.yml` service ports. Write `forge.conf` as a full `server` block equivalent: TLS notes as comments, `proxy_pass` per route, `proxy_set_header Upgrade/Connection` for websocket paths, sane timeouts matching Caddy's.
+- [ ] **Step 2:** Validate syntax: `docker run --rm -v "$PWD/deploy/nginx/forge.conf:/etc/nginx/conf.d/forge.conf:ro" nginx:alpine nginx -t` (if the sandbox lacks docker, state so in the report and have the reviewer run it; do not claim validated).
+- [ ] **Step 3:** Write `reverse-proxy.md`: Caddy (default, auto-TLS) vs nginx (this file), header/websocket requirements, health-check paths.
+- [ ] **Step 4:** Commit: `feat(deploy): add nginx reverse-proxy config and reverse-proxy doc`
+
+### Task 6: FORGE_SPEC realignment
+
+**Files:**
+- Modify: `docs/FORGE_SPEC.md` (structure list ~L190/L211, SDD CLI section L279-285, launch-docs list L889, roadmap L978-1022)
+
+- [ ] **Step 1:** Structure list: remove `packages/ui-kit/` (UI lives in `apps/web`), keep `deploy/nginx/forge.conf` (exists after Task 5), add the 9 unlisted real packages (approval-sdk, auth-sdk, authz-sdk, contracts, db, deploy-core, marketplace-sdk, observability, orchestration-policy).
+- [ ] **Step 2:** SDD CLI section: state the shipped reality — lifecycle is API/web-first (`routers/spec.py`), console scripts shipped are `forge-verify`/`forge-replay`; `forge bench|marketplace` remain parked stubs. Move the full `forge` CLI to the roadmap section explicitly.
+- [ ] **Step 3:** Roadmap: add a shipped "Trust layer" entry (4 features, PR refs) and mark early-shipped Phase-3 items (OIDC/SAML/SCIM, marketplace, leaderboard, Firecracker) as done.
+- [ ] **Step 4:** Commit: `docs(spec): realign FORGE_SPEC with shipped reality`
+
+---
+
+## Phase 2 — CI gates what exists
+
+### Task 7: Web CI lanes
+
+**Files:**
+- Modify: `.github/workflows/ci.yml` (web job, ~lines 243-278)
+
+- [ ] **Step 1:** Run locally first: `pnpm --filter @forge/web typecheck` and `pnpm --filter @forge/web test`. If either fails, fix trivial breakage (type errors, snapshot drift) as part of this task; if failures are deep/product bugs, report them and gate only what passes (do not disable tests to go green).
+- [ ] **Step 2:** Add two steps to the `web` job after lint: `pnpm --filter @forge/web typecheck` and `pnpm --filter @forge/web test` (before build). No `continue-on-error`.
+- [ ] **Step 3:** `actionlint` if available, else YAML sanity via `python -c "import yaml,sys; yaml.safe_load(open('.github/workflows/ci.yml'))"`.
+- [ ] **Step 4:** Commit: `ci(web): run vitest suite and tsc typecheck on every PR`
+
+### Task 8: mypy full package coverage
+
+**Files:**
+- Modify: `Makefile:13-17` (`MYPY_PACKAGES`) — add `forge_deploy`, `forge_auth`, `forge_marketplace`, `forge_obs`
+- Modify: whatever those packages need to type-check clean
+
+- [ ] **Step 1:** Add the 4 modules to `MYPY_PACKAGES`. Run `make typecheck`.
+- [ ] **Step 2:** Fix every surfaced error properly (annotations, narrowing) — no blanket `# type: ignore`, no ignore_errors config. If a package has >30 errors, report the count before proceeding.
+- [ ] **Step 3:** `make typecheck` → exit 0. Run the 4 packages' test dirs targeted (`uv run pytest packages/deploy-core/tests packages/auth-sdk/tests packages/marketplace-sdk/tests packages/observability/tests -q`) → green.
+- [ ] **Step 4:** Commit: `ci(types): bring deploy-core, auth-sdk, marketplace-sdk, observability under mypy`
+
+### Task 9: pytest basename-collision guard + importlib
+
+**Files:**
+- Modify: `pyproject.toml:90-94` (pytest addopts)
+- Modify: `tests/test_test_infra.py` (add guard test — file already exists, correct home)
+
+- [ ] **Step 1:** Write the guard test in `tests/test_test_infra.py`: walk the repo for `test_*.py` (exclude node_modules/.git/__pycache__), group by basename; for any duplicated basename assert every copy resolves to a unique dotted module (i.e. sits under a chain of `__init__.py` dirs). Fail message must name the colliding paths and cite this plan.
+- [ ] **Step 2:** Run it: `uv run pytest tests/test_test_infra.py -q` → PASS (current 7 collision sets are all disambiguated today; if not, fix by adding `__init__.py`).
+- [ ] **Step 3:** Add `--import-mode=importlib` to addopts. Verify collection of the WHOLE repo (collection only — fast, and it's where exit-2 lives): `uv run pytest --collect-only -q > /dev/null; echo $?` → 0. Then run two targeted suites that use fixtures/conftest heavily (`apps/api/tests/pm_api`, `packages/workflow-engine/tests/editor`) → green.
+- [ ] **Step 4:** If importlib breaks collection or those suites, revert the addopts change (keep the guard test) and record why in the commit body.
+- [ ] **Step 5:** Commit: `test(infra): guard against test-basename collisions; adopt importlib import mode`
+
+### Task 10: CI/config hygiene
+
+**Files:**
+- Modify: `ruff.toml:10`, `mypy.ini:15`, `pyproject.toml:63` (drop nonexistent `packages/ui-kit` excludes)
+- Delete: `apps/api/forge_api/routers/board_v1/` (contains only `__pycache__`; `git rm -r` won't see it — remove from disk, confirm untracked)
+- Modify: `.github/workflows/release.yml` (wire dead `draft` input: `release.yml:22-25` vs hardcoded `--draft` at `:200`)
+- Modify: `.github/workflows/security.yml` (top-of-file comment noting intentional overlap with ci.yml security job)
+
+- [ ] **Step 1:** Apply the four edits. For release.yml: `--draft` becomes conditional on `${{ inputs.draft }}` with default true for tag pushes.
+- [ ] **Step 2:** `uv run ruff check . -q` and `make typecheck` still clean; YAML sanity-parse both workflows.
+- [ ] **Step 3:** Commit: `chore(ci): remove dead ui-kit excludes, orphaned board_v1 dir, wire release draft input`
+
+### Task 11: Schema-drift gate
+
+**Files:**
+- Create: `packages/db/tests/test_schema_drift.py` (basename unique — verified no existing file by this name)
+
+**Interfaces:**
+- Consumes: `packages/db/alembic.ini`, `forge_db` metadata (find the canonical `Base.metadata` export in `packages/db/forge_db/models/__init__.py`), existing PG fixture pattern from `packages/db/tests/test_migration.py` (`@pytest.mark.postgres`, `FORGE_TEST_DATABASE_URL`).
+
+- [ ] **Step 1:** Write failing-by-construction check: upgrade a fresh PG database to `head`, then run `alembic.autogenerate.compare_metadata(migration_context, Base.metadata)` and assert the diff list is empty. Copy the engine/env setup verbatim from `test_migration.py`'s postgres tests.
+- [ ] **Step 2:** `uv run pytest packages/db/tests/test_schema_drift.py -q` with a local PG if available (`docker compose` pg service or skip-if-no `FORGE_TEST_DATABASE_URL` exactly like test_migration.py does). If it FAILS with real drift, list the diffs in the report — do NOT auto-generate a migration without review.
+- [ ] **Step 3:** Commit: `test(db): gate model/migration schema drift via autogenerate compare`
+
+---
+
+## Phase 3 — Silent-failure wiring
+
+### Task 12: Slack `/forge status` wiring
+
+**Files:**
+- Modify: `apps/api/forge_api/routers/integration.py:496` (stub) and its service layer
+- Test: extend the existing integration router test file (same dir/tests package as current slash-command tests)
+
+**Interfaces:**
+- Consumes: agent-run lookup — find the existing service the `runs` UI uses (grep `routers/agent.py` for the run-detail dependency) and reuse it; do not open a new DB session pattern.
+- Produces: slash response text `run <id>: <status> (<phase/step>)` or a not-found message.
+
+- [ ] **Step 1:** Failing test: posting the slash payload `/forge status <known-run-id>` returns 200 with the run's real status string; unknown id returns the not-found copy. Seed a run via the same fixture the runs API tests use.
+- [ ] **Step 2:** Implement lookup + response; keep Slack signature verification untouched.
+- [ ] **Step 3:** Targeted tests green; commit: `feat(slack): wire /forge status to live run lookup`
+
+### Task 13: Legacy in-memory approval router retirement
+
+**Files:**
+- Modify: `apps/api/forge_api/routers/__init__.py` or wherever `FEATURE_ROUTERS` lists `approval` (grep `FEATURE_ROUTERS`)
+- Delete: `apps/api/forge_api/routers/approval.py` + its dedicated tests
+- Check: `grep -rn "\"/approval/\|'/approval/" apps/web/src apps/api` for consumers first
+
+- [ ] **Step 1:** Prove no consumer: grep web + api + tests for `/approval/` (singular, not `/approvals/`). If a consumer exists, STOP and report instead of deleting.
+- [ ] **Step 2:** Remove router from registry, delete module + its tests, run `uv run pytest apps/api/tests -q -k "approval"` → remaining (DB-backed) approval tests green.
+- [ ] **Step 3:** Commit: `refactor(api): retire legacy in-memory /approval router in favor of DB-backed /approvals`
+
+### Task 14: Deployment worker task registration
+
+**Files:**
+- Modify: `apps/worker/forge_worker/celery_app.py:29-48` (add `forge_worker.tasks.deployments` to include)
+- Modify: `apps/api/forge_api/services/deployment_service.py` ONLY if enqueueing is added (see Step 2 decision rule)
+- Test: `apps/worker/tests/` (extend existing deployments task tests if present; else add to an existing worker test module)
+
+- [ ] **Step 1:** Register the module in celery include. Failing test: `celery_app.tasks` contains `forge.deployments.advance` and `forge.deployments.request`.
+- [ ] **Step 2:** Decision rule (record which branch in the commit body): if `forge.deployments.request` duplicates what `deployment_service` already does synchronously with no retry/backoff benefit surfaced anywhere (no beat schedule, no caller), keep the sync path as-is and just register + test the tasks execute `DeploymentOrchestrator.advance()` correctly. Do NOT rip out the sync path.
+- [ ] **Step 3:** Targeted worker tests green; commit: `fix(worker): register deployment tasks with celery`
+
+### Task 15: SAML SLO honest UI
+
+**Files:**
+- Modify: `apps/web/src/components/sso/sso-settings-view.tsx:590` (SLO URL field)
+- Test: `apps/web/src/components/sso/sso-settings-view.test.tsx`
+
+- [ ] **Step 1:** Failing test: SLO field renders disabled with helper text stating Single Logout is not yet supported (server returns 501) — align copy with the honest-status house style; the existing test at `:359` asserts no "coming soon" copy, so use plain "not yet supported" phrasing consistent with that assertion.
+- [ ] **Step 2:** Implement; `pnpm --filter @forge/web test -- sso-settings-view` → green.
+- [ ] **Step 3:** Commit: `fix(web): mark SAML single logout as not yet supported in SSO settings`
+
+### Task 16: Spec review reject/request-changes persistence — model: fable
+
+**Files:**
+- Modify: `packages/spec-engine/forge_spec/` (engine: add `reject_spec` / `request_changes` transitions; find `approve_spec` and mirror its shape; extend the status enum — it is file-based, no DB migration)
+- Modify: `apps/api/forge_api/routers/spec.py` (two new POST endpoints beside the approve endpoint at `:339`)
+- Modify: `apps/api/forge_api/schemas/` (request body: `{note: str}`)
+- Modify: `apps/web/src/components/spec-studio/read-mode.tsx:28-34,256` (replace local-only recording with real API calls; keep optimistic UI)
+- Tests: spec-engine tests (existing files), `apps/api/tests` spec router tests, `read-mode.test.tsx`
+
+**Interfaces:**
+- Consumes: `FileSpecEngine.approve_spec` signature (read it; mirror exactly for the two new transitions).
+- Produces: `POST /spec/{id}/reject` and `POST /spec/{id}/request-changes`, both accepting `{note}`, returning the updated spec payload the approve endpoint returns; new statuses must round-trip through `load_manifest`.
+
+- [ ] **Step 1 (TDD, engine):** failing tests for both transitions incl. illegal-state transitions (e.g. rejecting an already-approved spec → domain error mirroring approve's guards). Implement. Targeted spec-engine tests green.
+- [ ] **Step 2 (TDD, API):** failing router tests (status codes, body echo, 409 on illegal transition — mirror approve endpoint's error mapping). Implement. Green.
+- [ ] **Step 3 (TDD, web):** failing read-mode tests: clicking Reject calls the endpoint and renders returned status; server error surfaces (no silent local state). Implement. Green.
+- [ ] **Step 4:** Commit: `feat(spec): persist reject and request-changes review decisions end-to-end`
+
+### Task 17: Supervised multi-agent dispatch — model: fable
+
+**Files:**
+- Modify: `apps/worker/forge_worker/agent_runner.py:292-312` (the `forge.agent.run` task — branch on the run's `execution_mode`)
+- Consumes: `packages/multi-agent-coordinator/forge_coordinator/` (supervisor entrypoint — read `forge_coordinator/__init__.py` exports and its own tests to find the canonical run API), `ExecutionMode.SUPERVISED_MULTI_AGENT` enum, migration `0009_f27_multi_agent.py` tables (persistence via `forge_coordinator.persistence`)
+- Test: `apps/worker/tests/` (new cases in the existing agent_runner test module; scripted model clients — the coordinator's own tests show how it runs offline)
+
+**Interfaces:**
+- Produces: when `execution_mode == supervised_multi_agent`, `forge.agent.run` drives the coordinator supervisor instead of a single `AgentRunner`; run status/artifacts land in the same tables the single path writes (same observable contract for the API/UI).
+
+- [ ] **Step 1:** Read the coordinator package tests end-to-end to extract the intended integration surface (this package was built with tests but never wired — its tests ARE the spec).
+- [ ] **Step 2 (TDD):** failing worker test: enqueue `forge.agent.run` for a run whose spec sets supervised mode with a scripted client → coordinator persistence rows exist and run completes; single-agent path untouched (regression test asserting default mode still builds one `AgentRunner`).
+- [ ] **Step 3:** Implement the branch + adapter glue (model client construction reuses `_resolve_model_client`). Keep the diff inside `agent_runner.py` + a small `apps/worker/forge_worker/multi_agent.py` adapter if glue exceeds ~60 lines.
+- [ ] **Step 4:** Targeted tests green (`apps/worker/tests` + `packages/multi-agent-coordinator/tests`). Commit: `feat(worker): dispatch supervised multi-agent runs through forge_coordinator`
+
+### Task 18: PM sync board-write path — model: fable
+
+**Files:**
+- Create: `apps/worker/forge_worker/tasks/pm_sync.py` (task `forge.pm.process_webhook`)
+- Modify: `apps/worker/forge_worker/celery_app.py` include list
+- Modify: `apps/api/forge_api/services/pm_service.py:322-372` (enqueue after persist, replacing the parked NOTE at `:371`)
+- Test: `apps/worker/tests/` (new module in an `__init__.py`-marked dir or unique basename `test_pm_sync_task.py`)
+
+**Interfaces:**
+- Consumes: persisted webhook row (id) from `pm_service`; provider adapters `packages/integration-sdk/forge_integrations/pm/registry.py` (9 providers, each with issue fetch + mapping — read the adapter conformance tests `packages/integration-sdk/tests/test_conformance.py` + `tests/pm/` for the fetch/map API); board write surface in `packages/board-core` (find the `sync_in` / upsert entrypoint the parked docstring names — `grep -rn "sync_in" packages/board-core apps`).
+- Produces: webhook → task enqueue → adapter re-fetch → board item upsert, idempotent on redelivery (dedup key already persisted by pm_service).
+
+- [ ] **Step 0 (gate):** Verify the substrate exists NOW: locate a concrete board upsert path in `packages/board-core` usable from the worker (the parked note predates board-core maturity). If genuinely absent, STOP after Step 0, implement the honest fallback instead — webhook response/UI surface a `sync: parked` status (`pm-integrations-view.tsx` health panel) — and report the blocker precisely.
+- [ ] **Step 1 (TDD):** failing worker test with a fake adapter registered in the registry: task fetches the issue, upserts a board item, second delivery of same event is a no-op.
+- [ ] **Step 2:** Implement task + enqueue in `pm_service` (post-persist, post-audit; keep 202 semantics). Signature verification untouched.
+- [ ] **Step 3:** Targeted tests: new module + `apps/api/tests/pm_api` + `packages/integration-sdk/tests/pm` → green.
+- [ ] **Step 4:** Update the parked docstrings (`pm.py:7-10`, `pm_service.py:9-14`) to reflect what now works vs. what remains parked (OAuth exchange, backfill, conflict resolve — leave parked unless trivially unlocked by the same substrate; do not scope-creep).
+- [ ] **Step 5:** Commit: `feat(pm): wire webhook intake to board-write sync task`
+
+---
+
+## Phase 4 — Trust-layer completion
+
+### Task 19: Attested Changesets REST + web UI — model: fable
+
+**Files:**
+- Create: `apps/api/forge_api/routers/attestations.py` (`GET /attestations`, `GET /attestations/{id}`, `GET /approvals/{id}/attestation`)
+- Create: `apps/api/forge_api/schemas/attestation.py`
+- Modify: router registry (same list Task 13 touches — coordinate: land after Task 13)
+- Create: `apps/web/src/components/attestations/attestation-panel.tsx` (+ `.test.tsx`) rendered inside the approvals review surface (`apps/web/src/components/approvals/review-panel.tsx` — same slot pattern as `red-team-badge.tsx`)
+- Tests: `apps/api/tests/attest/` (dir already exists with `__init__.py`)
+
+**Interfaces:**
+- Consumes: `attestation_service` read paths + `forge_db/models/attestation.py`; verification via the same seam `forge-verify` CLI uses (`cli_verify.py` — reuse its service call, not its parked stub printout).
+- Produces: JSON: `{id, changeset_hash, signer, created_at, verified: bool, provenance: {...}}`; UI badge/panel: signed/verified/missing states, no fake states.
+
+- [ ] **Step 1 (TDD, API):** failing router tests: list/detail/by-approval incl. 404, using fixtures from `apps/api/tests/attest/` (existing service tests show how records are minted). Implement. Green.
+- [ ] **Step 2 (TDD, web):** failing panel tests: renders verified/unverified/absent from API payload; wire into review-panel next to red-team badge. Implement. `pnpm --filter @forge/web test -- attestation` green.
+- [ ] **Step 3:** Append an API section to `docs/trust-layer.md` (Task 4 created it) and remove its "REST/UI pending" limitation line.
+- [ ] **Step 4:** Commit: `feat(attest): expose attested changesets over REST with approvals UI panel`
+
+### Task 20: Red-Team Gate trigger + V1 worker path — model: fable
+
+**Files:**
+- Modify: `apps/api/forge_api/routers/workflow.py` (add `POST /workflow/runs/{id}/red-team` beside the GET at `:227`)
+- Modify: the V1 (Celery/FSM) approval-gate path in `apps/worker/` — locate where the V1 workflow FSM evaluates gates before the human approval step (grep `apps/worker` + `packages/workflow-engine` for the non-temporal gate evaluation; mirror `temporal/workflows.py:141`)
+- Consumes: `packages/db/forge_db/redteam/repository.py`, `forge_coordinator/red_team.py`, verdict schema `apps/api/forge_api/schemas/red_team.py`
+- Tests: worker V1-path test module + `apps/api/tests` workflow router tests
+
+**Interfaces:**
+- Produces: POST returns 202 + verdict record id; V1 path records a verdict (real adversary when a model is configured, explicit `parked` verdict otherwise — identical contract to the Temporal activity) before the approval gate resolves.
+
+- [ ] **Step 1:** Map the V1 gate evaluation point; write it down in the task report before coding.
+- [ ] **Step 2 (TDD, worker):** failing test: V1 run reaching approval gate persists a red-team verdict row (parked kind when no adversary configured — same shape as `temporal/activities.py:128-134`). Implement by extracting the Temporal activity's verdict-building into a shared helper both paths call (DRY — helper lives in `forge_workflow`, not copy-paste).
+- [ ] **Step 3 (TDD, API):** failing test: POST triggers evaluation for a run, GET then returns the verdict; 409 when run not in a gateable state. Implement. Green.
+- [ ] **Step 4:** Update `docs/trust-layer.md` Red-Team limitations (Temporal-only line goes away; parked-pass default stays documented).
+- [ ] **Step 5:** Commit: `feat(red-team): trigger endpoint and V1 worker gate parity`
+
+### Task 21: Self-Eval Gate web UI — model: fable
+
+**Files:**
+- Create: `apps/web/src/components/self-eval/self-eval-panel.tsx` (+ `.test.tsx`), surfaced in settings (same page family as `ao_settings` backend — find where AO settings render: `grep -rn "ao" apps/web/src/app/(board)/settings`)
+- Consumes: existing endpoints from `routers/ao_settings.py` (suite scoping, baseline, run trigger `POST /ao/self-eval/runs`, gate verdicts) — read the router to enumerate the exact contract first; do NOT invent endpoints.
+
+**Interfaces:**
+- Produces: panel showing configured suite, current baseline (score + minted at), last run result, gate status for pending config changes; a "run self-eval" action calling the existing run endpoint; Phase-A limitation copy (API-layer gate requires a baseline) stated inline.
+
+- [ ] **Step 1:** Enumerate the real API contract from `routers/ao_settings.py` + `schemas/` and paste it into the task report.
+- [ ] **Step 2 (TDD):** failing tests: renders baseline/last-run from mocked API; run button posts and renders accepted state; no-baseline state shows the honest Phase-A copy. Implement. `pnpm --filter @forge/web test -- self-eval` green; `pnpm --filter @forge/web typecheck` clean.
+- [ ] **Step 3:** Update `docs/trust-layer.md` Self-Eval section (UI now exists; Phase B still out of scope).
+- [ ] **Step 4:** Commit: `feat(self-eval): settings panel for suite, baseline, runs, and gate status`
+
+---
+
+## Execution notes
+
+- Phase 1 tasks 1-6 are file-disjoint → may run as parallel subagents in isolated worktrees, merged serially by the orchestrator. Phases 2-4 run sequentially (shared files: ci.yml, celery_app.py, router registry).
+- Task 19 depends on Task 13 (router registry churn) and Task 4 (docs file exists). Task 20/21 depend on Task 4 (docs file).
+- Every task ends green on its targeted tests before commit; final gate before PR: `uv run ruff check . -q`, `make typecheck`, `uv run pytest --collect-only -q`, `pnpm --filter @forge/web lint && pnpm --filter @forge/web typecheck && pnpm --filter @forge/web test && pnpm --filter @forge/web build`.

From c92ad6242e4f9ec67c687a19128e6d69836229d8 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 22:34:35 +0200
Subject: [PATCH 02/47] =?UTF-8?q?docs(plan):=20keep=20FORGE=5FRERANK=5FMOD?=
 =?UTF-8?q?EL=20=E2=80=94=20live=20via=20pydantic=20FORGE=5F=20prefix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/superpowers/plans/2026-07-20-audit-remediation.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-20-audit-remediation.md b/docs/superpowers/plans/2026-07-20-audit-remediation.md
index 9ce1fe85..f0e3671d 100644
--- a/docs/superpowers/plans/2026-07-20-audit-remediation.md
+++ b/docs/superpowers/plans/2026-07-20-audit-remediation.md
@@ -65,11 +65,11 @@
 **Background (verified):** `.env.example:90-91` ships `MODEL_PROVIDER=anthropic` / `MODEL_PROVIDER_KEY=` but NOTHING reads those names. Real knobs: `FORGE_MODEL_PROVIDER` (`anthropic|openai`), `FORGE_MODEL_NAME`, key resolution order `FORGE_MODEL_API_KEY` → `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`. When unset the worker silently uses the offline `ScriptedModelClient`.
 
 - [ ] **Step 1:** Read `packages/agent-runtime/forge_agent/providers/config.py` fully; list every env var it reads (also `EMBEDDING_MODEL`, `EMBEDDING_BASE_URL`, `EMBEDDING_DIM` readers in `packages/knowledge-core`, and `FORGE_RERANK_*` readers in `packages/knowledge-core/forge_knowledge/reranker.py`).
-- [ ] **Step 2:** Rewrite the `.env.example` model block: replace `MODEL_PROVIDER`/`MODEL_PROVIDER_KEY` with commented, documented `FORGE_MODEL_PROVIDER=anthropic`, `FORGE_MODEL_NAME=`, `FORGE_MODEL_API_KEY=` (+ note about `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` fallback). Delete dead knobs `EMBEDDING_PROVIDER`, `FORGE_RERANK_MODEL`, `RERANKER_URL`, `RERANKER_MODEL`. Add missing real knobs `EMBEDDING_BASE_URL`, `EMBEDDING_DIM`. Keep `MINIO_ROOT_USER`/`MINIO_ROOT_PASSWORD` ONLY if `grep MINIO deploy/docker-compose*.yml` shows compose consumes them (it does for the minio service); delete `MINIO_ENDPOINT`, `MINIO_BUCKET`, `FORGE_POSTMORTEMS_BUCKET` if nothing reads them, with a one-line comment pointing to the parked object-storage scope.
-- [ ] **Step 3:** Fix the same var names in `docs/getting-started.md`, `docs/architecture.md`, and `docs/integrations/byok-and-boards.md` (drop `EMBEDDING_PROVIDER` and `FORGE_RERANK_MODEL` rows; the real rerank knobs are `FORGE_RERANK_{ENABLED,PROVIDER,BASE_URL,TIMEOUT_MS,ALLOW_INSECURE_URL}`).
+- [ ] **Step 2:** Rewrite the `.env.example` model block: replace `MODEL_PROVIDER`/`MODEL_PROVIDER_KEY` with commented, documented `FORGE_MODEL_PROVIDER=anthropic`, `FORGE_MODEL_NAME=`, `FORGE_MODEL_API_KEY=` (+ note about `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` fallback). Delete dead knobs `EMBEDDING_PROVIDER`, `RERANKER_URL`, `RERANKER_MODEL`. KEEP `FORGE_RERANK_MODEL` — it is live via pydantic `env_prefix="FORGE_"` → `Settings.rerank_model` (settings.py:298, reranker.py:518). Add missing real knobs `EMBEDDING_BASE_URL`, `EMBEDDING_DIM`. Keep `MINIO_ROOT_USER`/`MINIO_ROOT_PASSWORD` ONLY if `grep MINIO deploy/docker-compose*.yml` shows compose consumes them (it does for the minio service); delete `MINIO_ENDPOINT`, `MINIO_BUCKET`, `FORGE_POSTMORTEMS_BUCKET` if nothing reads them, with a one-line comment pointing to the parked object-storage scope.
+- [ ] **Step 3:** Fix the same var names in `docs/getting-started.md`, `docs/architecture.md`, and `docs/integrations/byok-and-boards.md` (drop `EMBEDDING_PROVIDER` rows; the real rerank knobs are `FORGE_RERANK_{ENABLED,PROVIDER,MODEL,BASE_URL,TIMEOUT_MS,ALLOW_INSECURE_URL}` — `FORGE_RERANK_MODEL` is live via the pydantic `FORGE_` prefix).
 - [ ] **Step 4:** Write failing test: when `FORGE_MODEL_PROVIDER` is unset, `_resolve_model_client` logs a WARNING containing `ScriptedModelClient` and `FORGE_MODEL_PROVIDER` (use `caplog`). Run it; expect FAIL (no warning today).
 - [ ] **Step 5:** Add the warning in `_resolve_model_client` fallback branch. Run the worker test file; expect PASS.
-- [ ] **Step 6:** Verify no stale references remain: `grep -rn "MODEL_PROVIDER_KEY\|EMBEDDING_PROVIDER=\|FORGE_RERANK_MODEL" --include="*.md" docs README.md .env.example` → 0 hits (except historical CHANGELOG).
+- [ ] **Step 6:** Verify no stale references remain: `grep -rn "MODEL_PROVIDER_KEY\|EMBEDDING_PROVIDER=\|RERANKER_URL\|RERANKER_MODEL" --include="*.md" docs README.md .env.example | grep -v FORGE_RERANK` → 0 hits (except historical CHANGELOG).
 - [ ] **Step 7:** Commit: `fix(config): document real FORGE_MODEL_* env vars and warn on scripted-client fallback`
 
 ### Task 2: Doc-drift sweep

From be54bb3f4c547d23f9a2be67657db07bfc25f4ec Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 22:42:27 +0200
Subject: [PATCH 03/47] fix(config): document real FORGE_MODEL_* env vars and
 warn on scripted-client fallback

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .env.example                             | 37 ++++++++++++++++--------
 apps/worker/forge_worker/agent_runner.py |  9 ++++++
 apps/worker/tests/test_agent_runner.py   | 22 ++++++++++++++
 docs/getting-started.md                  |  7 +++--
 docs/integrations/byok-and-boards.md     |  5 ++--
 5 files changed, 62 insertions(+), 18 deletions(-)

diff --git a/.env.example b/.env.example
index 06661bb6..97031a0b 100644
--- a/.env.example
+++ b/.env.example
@@ -65,11 +65,12 @@ DATABASE_URL=postgresql+psycopg://forge:change-me@localhost:5432/forge
 # Redis (queue, cache, sessions)
 REDIS_URL=redis://localhost:6379/0
 
-# Object storage (MinIO / S3-compatible)
+# Object storage (MinIO / S3-compatible). Only the root credentials are consumed
+# today — by the compose `minio` service (`${MINIO_ROOT_USER}`/`${MINIO_ROOT_PASSWORD}`).
+# Endpoint/bucket wiring is PARKED with the object-storage scope: no code reads
+# MINIO_ENDPOINT / MINIO_BUCKET yet, so they are omitted until they are wired.
 MINIO_ROOT_USER=forge
 MINIO_ROOT_PASSWORD=change-me
-MINIO_ENDPOINT=http://localhost:9000
-MINIO_BUCKET=forge-artifacts
 
 # Auth (Better Auth / Auth.js)
 AUTH_SECRET=change-me-generate-a-long-random-string
@@ -86,13 +87,26 @@ API_KEY_PEPPER=
 # Beat cadence for the expired platform-key purge (seconds; default 15m).
 FORGE_AUTH_PURGE_KEYS_INTERVAL_SECONDS=900
 
-# BYOK model provider (provider-agnostic; Anthropic reference impl)
-MODEL_PROVIDER=anthropic
-MODEL_PROVIDER_KEY=
-EMBEDDING_PROVIDER=anthropic
-EMBEDDING_MODEL=
-RERANKER_URL=http://localhost:8080
-RERANKER_MODEL=jina-reranker-v2-base-multilingual
+# ---------------------------------------------------------------------------
+# BYOK model provider (provider-agnostic; Anthropic reference impl). UNSET by
+# default: with no FORGE_MODEL_PROVIDER the worker runs the offline, deterministic
+# ScriptedModelClient (canned output, no network) and logs a WARNING each run.
+# Uncomment + fill these in to drive a real provider.
+# ---------------------------------------------------------------------------
+# Master switch: anthropic | openai. Absent -> offline scripted fallback.
+# FORGE_MODEL_PROVIDER=anthropic
+# Model name. Optional for anthropic (a reference default is applied); REQUIRED
+# for openai.
+# FORGE_MODEL_NAME=
+# BYOK key. The provider-native ANTHROPIC_API_KEY / OPENAI_API_KEY takes
+# precedence; FORGE_MODEL_API_KEY is the provider-agnostic fallback.
+# FORGE_MODEL_API_KEY=
+
+# Embeddings for hybrid-retrieval evaluation (OpenAI-compatible embedder), shown
+# with the built-in defaults; override to point at another endpoint.
+# EMBEDDING_MODEL=text-embedding-3-small
+# EMBEDDING_BASE_URL=https://api.openai.com/v1
+# EMBEDDING_DIM=1536
 
 # HARD-03 live cross-encoder reranker (BYOK). Provider `fixture` (default) keeps
 # the offline deterministic reranker; `jina`/`cohere`/`selfhosted` build a
@@ -131,8 +145,7 @@ FORGE_GRAFANA_WEBHOOK_SECRET=
 # in the bundled incident.yaml, not an env var).
 FORGE_INCIDENT_RECOVERY_WINDOW_SECONDS=300
 FORGE_INCIDENT_RECOVERY_MAX_WINDOWS=6
-# MinIO bucket for versioned postmortem snapshots.
-FORGE_POSTMORTEMS_BUCKET=forge-postmortems
+# Postmortem-snapshot bucket: PARKED with the object-storage scope (no reader yet).
 
 # External PM adapters (F18 — Jira, Linear). OAuth client creds are optional
 # (api_token auth works without them). Webhook bodies for these routes MUST reach
diff --git a/apps/worker/forge_worker/agent_runner.py b/apps/worker/forge_worker/agent_runner.py
index b822cb2a..62ead82e 100644
--- a/apps/worker/forge_worker/agent_runner.py
+++ b/apps/worker/forge_worker/agent_runner.py
@@ -127,6 +127,15 @@ def _resolve_model_client(model_client: ModelClient | None) -> ModelClient:
             # Provider SDK/extra absent — never silently fake on a configured
             # lane failure; degrade to the offline client and keep running.
             pass
+    # Reached once per run when no live provider resolved: make the degrade loud
+    # so a self-hoster does not mistake canned scripted output for a real run.
+    logger.warning(
+        "No live model provider resolved; falling back to the offline "
+        "ScriptedModelClient (canned, deterministic output — not a real agent "
+        "run). Set FORGE_MODEL_PROVIDER (anthropic|openai) and a BYOK key "
+        "(ANTHROPIC_API_KEY / OPENAI_API_KEY, or FORGE_MODEL_API_KEY) to run a "
+        "real provider."
+    )
     return _scripted_client()
 
 
diff --git a/apps/worker/tests/test_agent_runner.py b/apps/worker/tests/test_agent_runner.py
index 91ab235a..a85a029d 100644
--- a/apps/worker/tests/test_agent_runner.py
+++ b/apps/worker/tests/test_agent_runner.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import importlib.util
+import logging
 
 import pytest
 
@@ -44,6 +45,27 @@ def test_build_agent_runner_no_creds_uses_scripted(monkeypatch: pytest.MonkeyPat
     assert isinstance(runner._model, ScriptedModelClient)
 
 
+def test_build_agent_runner_warns_on_scripted_fallback(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    """No provider configured -> a single loud WARNING that output is canned.
+
+    A self-hoster who never set ``FORGE_MODEL_PROVIDER`` gets ``ScriptedModelClient``
+    (offline, deterministic) instead of a real agent run; the fallback must not be
+    silent. The warning fires once per resolve (once per run), not per-call spam.
+    """
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    with caplog.at_level(logging.WARNING, logger="forge.agent_runner"):
+        build_agent_runner()
+    fallback_warnings = [
+        r for r in caplog.records if r.name == "forge.agent_runner" and r.levelno == logging.WARNING
+    ]
+    assert len(fallback_warnings) == 1, "expected exactly one scripted-fallback WARNING"
+    message = fallback_warnings[0].getMessage()
+    assert "ScriptedModelClient" in message
+    assert "FORGE_MODEL_PROVIDER" in message
+
+
 def test_build_agent_runner_uses_injected_client(monkeypatch: pytest.MonkeyPatch) -> None:
     """HARD-02 AC8: an injected real ``ModelClient`` is used verbatim."""
     monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
diff --git a/docs/getting-started.md b/docs/getting-started.md
index a820e572..ae76ada5 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -46,9 +46,10 @@ Edit `.env` and set, at minimum:
 
 To run agent work, also set your model provider:
 
-- `MODEL_PROVIDER=anthropic` and `MODEL_PROVIDER_KEY=<your key>` (or configure it
-  later through the encrypted vault — see
-  [BYOK](./integrations/byok-and-boards.md)).
+- `FORGE_MODEL_PROVIDER=anthropic` and a BYOK key (`ANTHROPIC_API_KEY` /
+  `OPENAI_API_KEY`, or `FORGE_MODEL_API_KEY`) — or configure it later through the
+  encrypted vault (see [BYOK](./integrations/byok-and-boards.md)). Left unset, the
+  worker runs an offline scripted model and logs a warning.
 
 Never commit `.env`; it is git-ignored.
 
diff --git a/docs/integrations/byok-and-boards.md b/docs/integrations/byok-and-boards.md
index c2afb4a0..2f94166e 100644
--- a/docs/integrations/byok-and-boards.md
+++ b/docs/integrations/byok-and-boards.md
@@ -25,8 +25,8 @@ text.
 Set the provider and key in `.env` for a quick local run:
 
 ```bash
-MODEL_PROVIDER=anthropic          # anthropic (default) or openai
-MODEL_PROVIDER_KEY=<your-api-key> # e.g. sk-ant-... or sk-...
+FORGE_MODEL_PROVIDER=anthropic     # anthropic or openai (unset -> offline scripted model)
+FORGE_MODEL_API_KEY=<your-api-key> # e.g. sk-ant-... or sk-...; or set ANTHROPIC_API_KEY / OPENAI_API_KEY
 # For OpenAI also set the model name:
 # FORGE_MODEL_NAME=gpt-4.1
 ```
@@ -43,7 +43,6 @@ secret under `MODEL_PROVIDER`, then the `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` /
 Hybrid retrieval can use a hosted embedding model and an optional reranker:
 
 ```bash
-EMBEDDING_PROVIDER=<provider>
 EMBEDDING_MODEL=<model>
 # Optional reranker (Jina / Cohere / a self-hosted endpoint):
 FORGE_RERANK_ENABLED=true

From 7faae271fb8fa78d85b50de96644f01d91e8632d Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 22:55:55 +0200
Subject: [PATCH 04/47] docs: fix stale feature status, secret var name,
 package maps, compose tables

---
 README.md                           | 36 ++++++++++++++++-------------
 apps/web/src/lib/api/client.ts      | 11 +++++----
 docs/architecture.md                |  1 +
 docs/concepts.md                    | 19 ++++++++++-----
 docs/self-hosting/docker-compose.md | 14 +++++++++--
 docs/self-hosting/quickstart.md     |  5 ++--
 6 files changed, 55 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index b2afc77a..cda58790 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 > ⚠️ **Under active development — pre-1.0, not production-ready.** Forge is shared
 > openly for **evaluation and testing**, not for production use yet. Expect rough
 > edges, changing APIs, and features that are API/CLI-first with their UI or live
-> integrations still landing. Read **[Status](#status)** for the honest per-area
+> integrations pending. Read **[Status](#status)** for the honest per-area
 > state before you rely on it, and please contribute via pull request.
 
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
@@ -36,12 +36,13 @@ Forge is **pre-1.0 and under active development** — usable for evaluation and
 self-host testing, **not yet for production**. The backend platform, HTTP API,
 CLI, workflow/agent runtime, and self-hosting substrate are the mature surface,
 exercised by a large test suite (~3,700 tests on real pgvector Postgres, green
-in CI). The **web UI ships 15 feature screens** (board, approvals, run-trace
-viewer, spec dashboard, marketplace, incidents, observability, sprints, audit,
-deployment gates, SSO/SCIM, RBAC admin, PM integrations, workflow editor, and a
-guided walkthrough) on the Forge design system. Some screens carry **honestly
-marked gaps** where a backend projection or live credential is still landing
-(e.g. a couple of dashboard projections, OIDC), and the
+in CI). The **web UI ships 15 feature screens** — `approvals`, `audit`,
+`board`, `deployments`, `depth`, `incidents`, `leaderboard`, `marketplace`,
+`observability`, `runs`, `settings` (SSO/OIDC/SCIM, RBAC, PM integrations,
+model BYOK), `specs`, `sprints`, `walkthrough`, and `workflow` — on the Forge
+design system. Some screens carry **honestly marked gaps** where a backend
+projection or live credential is pending (e.g. a couple of dashboard
+projections), and the
 third-party integrations (GitHub App, model BYOK, reranker, MCP, Slack) are
 code-complete with tests + runbooks but need **your keys** to verify live. We
 try hard not to advertise anything that is only parked — the pre-1.0 notice at
@@ -54,9 +55,10 @@ individual screens mark in-progress areas inline.
 - **Spec-driven development** — author a `manifest.yaml` spec; the spec engine
   validates it and drives the work. Includes a spec-validation dashboard.
 - **Agent runtime** — a LangGraph agent loop that runs work inside sandboxed
-  execution (Docker today; gVisor / Firecracker isolation classes are modelled
-  and mapped, with the real-runtime tiers gated behind a virtualization-enabled
-  CI job).
+  execution (`worktree` git-worktree isolation by default, a per-task Docker
+  `container` sandbox also available; gVisor / Firecracker isolation classes
+  are modelled and mapped, with the real-runtime tiers gated behind a
+  virtualization-enabled CI job).
 - **Multi-agent coordination** — a coordinator for fanning work across agents.
 - **Workflow engine** — a Postgres finite-state-machine workflow layer, with
   Temporal available in the production stack for durable orchestration.
@@ -65,13 +67,14 @@ individual screens mark in-progress areas inline.
 - **Native project board** — a board core for tracking runs and work items.
 - **Policy, skill, integration & MCP SDKs** — declarative `.forge/policy.yaml`,
   skill profiles, integration definitions, and an MCP gateway for tool sources.
-- **Integration marketplace** — browse and install integrations (UI shipped;
-  publishing still via the offline author CLI).
-- **Enterprise SSO / SCIM** — SAML SSO and SCIM provisioning with an admin UI
-  (OIDC and live IdP verification still landing).
+- **Integration marketplace** — browse, install, and publish integrations
+  from the in-app UI (the offline `forge marketplace package` CLI works too).
+- **Enterprise SSO / SCIM** — SAML SSO and OIDC, plus SCIM provisioning, with
+  an admin UI (live IdP verification needs your own IdP, like the third-party
+  integrations above).
 - **Human approval system** — gated approvals for sensitive agent actions.
-- **Benchmark leaderboard** — submit, verify, and rank agent benchmark runs
-  (backend; **UI in progress**).
+- **Benchmark leaderboard** — submit, verify, and rank agent benchmark runs,
+  with a public leaderboard UI.
 - **Auth, secrets & BYOK** — envelope-encrypted secrets, a key vault, and
   bring-your-own-key model-provider credentials.
 - **Observability & cost metrics + audit log** — structured, redaction-aware
@@ -133,6 +136,7 @@ forge/
 │   ├── workflow-engine/         # forge_workflow
 │   ├── agent-runtime/           # forge_agent
 │   ├── multi-agent-coordinator/ # forge_coordinator
+│   ├── orchestration-policy/    # forge_orchestration_policy
 │   ├── spec-engine/             # forge_spec
 │   ├── board-core/              # forge_board
 │   ├── knowledge-core/          # forge_knowledge
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index 1aec3754..f7041ee3 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -1,10 +1,11 @@
 /**
- * Typed Forge API client (Phase-0 stub).
+ * Typed Forge API client.
  *
- * A thin `fetch` wrapper that knows the Forge API surface. The backend routes are
- * still Phase-0 stubs returning HTTP 501; this client therefore surfaces a typed
- * {@link ApiError} (with `notImplemented` set for 501s) so Task 1.6 can build
- * against a stable shape and progressively light up real handlers.
+ * A thin `fetch` wrapper that knows the Forge API surface. The backend routes
+ * below are implemented; this client still surfaces a typed {@link ApiError}
+ * (with `notImplemented` set for HTTP 501) as a residual safety net for any
+ * route a given deployment has feature-flagged off or not yet enabled, so
+ * callers can degrade gracefully instead of choking on an unexpected shape.
  */
 
 import { deriveOnboardingProgress } from "./onboarding-progress";
diff --git a/docs/architecture.md b/docs/architecture.md
index 6bed546f..2816cc89 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -57,6 +57,7 @@ packages/
   workflow-engine/forge_workflow       Postgres FSM workflow layer
   agent-runtime/  forge_agent          LangGraph plan/execute/verify + sandboxes
   multi-agent-coordinator/ forge_coordinator  Fan-out / supervision
+  orchestration-policy/ forge_orchestration_policy  Adaptive Orchestration: complexity sizing + role→tier/model routing
   board-core/     forge_board          Native project board
   knowledge-core/ forge_knowledge      Hybrid retrieval (pgvector + FTS + RRF + rerank)
   integration-sdk/forge_integrations   Integrations incl. PM adapters
diff --git a/docs/concepts.md b/docs/concepts.md
index 13128dfc..60137188 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -133,16 +133,23 @@ See [BYOK](./integrations/byok-and-boards.md).
 
 ## Access control: SSO, SCIM & RBAC
 
-For teams, Forge provides **SAML SSO** and **SCIM** user provisioning
-(`forge_api`, on `forge_authz` roles) plus **multi-team RBAC** (`forge_authz`) — role-based access
+For teams, Forge provides **SAML SSO** and **OIDC** single sign-on plus
+**SCIM** user provisioning (`forge_api`, on `forge_authz` roles) — configured
+from an admin UI — and **multi-team RBAC** (`forge_authz`) — role-based access
 scoped per team and workspace.
 
-## Marketplace, benchmarks & deployment gates
+## Marketplace, benchmarks, orchestration policy & deployment gates
 
 - **Integration marketplace** (`forge_marketplace`) — publish and install
-  integrations (backend + an offline author CLI today; UI in progress).
-- **Benchmark leaderboard** — submit, verify, and rank agent benchmark runs
-  (backend + offline `forge bench` CLI today; leaderboard UI in progress).
+  integrations, from the in-app UI or the offline `forge marketplace package`
+  CLI.
+- **Benchmark leaderboard** — submit, verify, and rank agent benchmark runs,
+  with a public leaderboard UI (backed by an offline `forge bench` CLI for
+  submission).
+- **Adaptive Orchestration** (`forge_orchestration_policy`) — deterministically
+  sizes a spec or task's complexity (tier: junior/medior/senior, strategy:
+  single/swarm) and resolves the effective model/tier routing per agent role,
+  configurable from a workspace settings screen.
 - **Deployment gates** (`forge_deploy`) — policy-gated promotion of changes
   through environments.
 
diff --git a/docs/self-hosting/docker-compose.md b/docs/self-hosting/docker-compose.md
index 01952f02..cb635698 100644
--- a/docs/self-hosting/docker-compose.md
+++ b/docs/self-hosting/docker-compose.md
@@ -26,6 +26,8 @@ the hardening applied, and how to operate it. To get running quickly first, see
 | `web` | built from `deploy/docker/web.Dockerfile` | Next.js frontend |
 | `caddy` | `caddy:2.8-alpine` | TLS termination and reverse proxy |
 | `autoheal` | `willfarrell/autoheal` | Restarts containers that fail their healthcheck |
+| `docker-proxy` | `tecnativa/docker-socket-proxy:0.3.0` | Read-only-socket, verb-restricted Docker API proxy — the only component near the raw Docker socket, used by `worker` to create/exec/inspect per-task sandbox containers |
+| `sandbox-proxy` | `ubuntu/squid:6.6-24.04_edge` | Allow-listing forward proxy (squid) — the only egress route for sandboxed agent containers on the `network: egress` sandbox mode |
 
 ## Hardening applied
 
@@ -38,8 +40,16 @@ The production file follows the spec's "Production Docker Compose Requirements":
 - **Resource limits** — CPU and memory limits on every container.
 - **Named volumes** for all stateful data (`db-data`, `redis-data`,
   `minio-data`, `caddy-data`, `caddy-config`) — never bind mounts.
-- **Segmented networks** — `edge`, `backend`, `data`, `mcp`; the `data` network
-  is marked `internal`, so the database is unreachable from the edge.
+- **Segmented networks** — seven networks: `edge`, `backend`, `data`, `mcp`,
+  `sandbox_ctl`, `sandbox_egress`, and `observability`. `data`, `sandbox_ctl`,
+  `sandbox_egress`, and `observability` are marked `internal` (no route to the
+  public internet): `data` isolates the database from the edge; `sandbox_ctl`
+  is `worker`'s private route to `docker-proxy`; `sandbox_egress` is the only
+  route out for sandboxed agent containers, bridged by `sandbox-proxy`.
+  `observability` is only populated when the `observability` Compose profile
+  is enabled (`otel-collector`, `prometheus`, `grafana`, `loki`, `tempo`,
+  `alertmanager`); `temporal`, `temporal-ui`, and `temporal-worker` similarly
+  only start under the `temporal` profile.
 - **Non-root** app containers (`user: "1000:1000"`).
 - **Log rotation** — `json-file` driver capped at `max-size: 100m`,
   `max-file: 5` per container.
diff --git a/docs/self-hosting/quickstart.md b/docs/self-hosting/quickstart.md
index 60896eb7..fa93b317 100644
--- a/docs/self-hosting/quickstart.md
+++ b/docs/self-hosting/quickstart.md
@@ -25,8 +25,9 @@ cp .env.example .env
 
 Edit `.env` and set, at minimum:
 
-- `SECRET_KEY` and `AUTH_SECRET` — long random strings (e.g.
-  `openssl rand -hex 32`).
+- `FORGE_SECRET_KEY` and `AUTH_SECRET` — long random strings (e.g.
+  `openssl rand -hex 32`). (`SECRET_KEY` is a deprecated alias that is
+  detected and warned about — see `apps/api/forge_api/cli_secrets.py`.)
 - `POSTGRES_PASSWORD` and `MINIO_ROOT_PASSWORD` — strong unique secrets.
 - `DOMAIN` — the hostname Caddy will serve (use `localhost` for a local trial).
 - `MODEL_PROVIDER_KEY` — your BYOK model provider key (Forge is provider

From a06ad55b4491697126b048ce5a56f545bfeae6d4 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:01:14 +0200
Subject: [PATCH 05/47] docs(web): align notImplemented docstring with
 implemented-routes reality

---
 apps/web/src/lib/api/client.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index f7041ee3..d45a40e4 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -142,7 +142,7 @@ export const DEFAULT_API_TOKEN = process.env.NEXT_PUBLIC_API_TOKEN;
 export class ApiError extends Error {
   readonly status: number;
   readonly body: unknown;
-  /** True when the endpoint exists but is a Phase-0 stub (HTTP 501). */
+  /** True when the server answered 501 — a residual safety net for disabled or not-yet-enabled routes. */
   readonly notImplemented: boolean;
 
   constructor(status: number, message: string, body: unknown) {

From 2ba502f6c13b9072e82f727476cf30f9e1f2c9f0 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:05:59 +0200
Subject: [PATCH 06/47] docs(release): regenerate changelog and readiness
 snapshot at current HEAD

---
 CHANGELOG.md         | 40 ++++++++++++++++++++++++++++++++++++++++
 Makefile             |  6 ++++--
 RELEASE_READINESS.md | 24 ++++++++++++------------
 3 files changed, 56 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 551ddf0a..c070f840 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,42 @@ sections by hand; write a well-formed commit instead.
 
 ### Added
 
+- **self-eval**: enforce the gate on config changes + worker-driven run (Phase A wiring) (#66)
+- **self-eval**: baseline persistence + live agent-backed eval runner (Phase A substrate) (#65)
+- Self-Eval Gate — block config changes that regress a workspace's private per-repo suite (trust-layer 4/4) (#64)
+- Red-Team Gate (trust layer, phase 3) — adversary must break the change in-sandbox before the human gate (#63)
+- Time-Travel Runs (trust layer, phase 2) — deterministic record-replay of agent runs (#62)
+- Attested Changesets (trust layer, phase 1) — signed provenance chained into the tamper-evident audit log (#61)
+- OIDC SSO + marketplace publish + benchmark leaderboard + under-dev banner (#57)
+- frontend UX pass — clearer IA/nav, one primary action, progressive disclosure, empty/loading/error states, a11y (#39)
+- IaC — OpenTofu infra/ (Hetzner control-plane + Cloudflare + Fly agents), dev/staging/prod, remote state, runbook (#38)
+- F40 deferred-scope deltas — PM adapters (BYO board), MCP, policy, automations, sprint depth, observability (#37)
+- realtime co-editing (WS server + CRDT spec co-editing + live push) (#36)
+- Spec Studio — dual-format spec authoring (Guided/Markdown/YAML/Read), BYOK AI draft, lifecycle, versioning (#33)
+- adaptive orchestration (auto model routing + per-role effort + settings + cost-by-tier) (#32)
+- public-readiness — under-dev banner, honest status, live spec dashboard (#30)
+- **web/walkthrough**: In-app guided walkthrough
+- **web/workflow-editor**: Workflow visual editor
+- **web/pm-integrations**: PM integrations
+- **web/rbac-admin**: Multi-team & RBAC admin
+- **web/sso-settings**: SSO / SCIM settings
+- **web/deployment-gates**: Deployment gates
+- **web/audit-log**: Audit viewer
+- **web/sprints**: Sprints & velocity
+- **web/observability**: Observability & cost
+- **web/incidents**: Incidents
+- **web/marketplace**: Marketplace
+- **web/spec-dashboard**: Spec-validation dashboard
+- **web/run-trace-viewer**: Run-trace viewer
+- **web/approval-inbox**: Approval inbox
+- **web/board-depth**: Board depth
+- **HARD-06**: live-slack
+- **HARD-05**: live-mcp-server
+- **HARD-03**: live-reranker
+- **HARD-02**: live-model-byok
+- **HARD-01**: live-github-app
+- **HARD-08**: kubernetes-helm-deploy
+- **HARD-12**: release-engineering
 - **HARD-10**: observability-cost-prod
 - **HARD-04**: real-eval-corpus
 - **HARD-11**: reliability-maturity
@@ -62,3 +98,7 @@ sections by hand; write a well-formed commit instead.
 - **phase0**: 0.3 contracts (packages/contracts)
 - **phase0**: 0.2 data-model (packages/db)
 - **phase0**: 0.1 workspace+tooling
+
+### Fixed
+
+- **config**: document real FORGE_MODEL_* env vars and warn on scripted-client fallback
diff --git a/Makefile b/Makefile
index 75a59b29..5a1e4ede 100644
--- a/Makefile
+++ b/Makefile
@@ -125,8 +125,10 @@ hooks: ## Install the commit-msg hook that enforces Conventional Commits (cz che
 	@chmod +x .git/hooks/commit-msg
 	@echo "Installed .git/hooks/commit-msg (uv run cz check)."
 
-release-readiness: ## Run the automated RELEASE_READINESS gate at the PRODUCTION bar
-	uv run forge-release-readiness --bar production
+BAR ?= beta
+
+release-readiness: ## Run the automated RELEASE_READINESS gate at BAR (default: beta; override with BAR=production)
+	uv run forge-release-readiness --bar $(BAR)
 
 source-sbom: ## Generate the source-tree CycloneDX SBOM (release/sbom/forge-source.cdx.json)
 	release/scripts/source-sbom.sh
diff --git a/RELEASE_READINESS.md b/RELEASE_READINESS.md
index 0d4b1e09..8c249d35 100644
--- a/RELEASE_READINESS.md
+++ b/RELEASE_READINESS.md
@@ -2,8 +2,8 @@
 
 - **Target bar:** Beta
 - **Overall verdict:** ❌ **NOT MET**
-- **Generated (UTC):** 2026-07-10T16:14:12Z
-- **Commit:** `34d48693fe97ca9c29845949573b0a9da29ea897`
+- **Generated (UTC):** 2026-07-20T21:04:04Z
+- **Commit:** `a06ad55b4491697126b048ce5a56f545bfeae6d4`
 - **Version (cz):** `0.1.0`
 
 > A bar is **MET** only when every gate at-or-below it is `GREEN` or `MANUAL_ATTESTED`. `SKIPPED_NO_CREDS`, `MISSING_EVIDENCE`, `STALE`, `MANUAL_PENDING`, and `RED` all mean **NOT MET** — the engine never infers a pass.
@@ -12,16 +12,16 @@
 
 | Gate | Blocker | Workstream | Status | Evidence (cmd/artifact) | Last-checked |
 |---|---|---|---|---|---|
-| `G-DB` | #6 | HARD-01 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m postgres -q packages/db | 2026-07-10T16:14:12Z |
-| `G-MODEL` | #1 | HARD-02 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q apps/api -k model_provider | 2026-07-10T16:14:12Z |
-| `G-RAG-REAL` | #2 | HARD-04 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m realeval -q | 2026-07-10T16:14:12Z |
-| `G-GH` | #1 | HARD-05 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k github_app | 2026-07-10T16:14:12Z |
-| `G-MCP` | #1 | HARD-06 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k mcp_live | 2026-07-10T16:14:12Z |
-| `G-SLACK` | #1 | HARD-07 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k slack_live | 2026-07-10T16:14:12Z |
-| `G-BUILD` | #3 | HARD-08 | 🟢 GREEN | deploy/build-manifest.json | 2026-07-10T16:14:12Z |
-| `G-TYPES` | #6 | HARD-12 | 🟢 GREEN | make typecheck | 2026-07-10T16:14:12Z |
-| `G-SEC-AUTOMATED` | #4 | HARD-09 | 🟢 GREEN | uv run pytest -m security -q | 2026-07-10T16:14:12Z |
-| `G-CRYPTO` | #5 | HARD-10 | 🟢 GREEN | uv run pytest -q apps/api/tests/test_auth_crypto_envelope.py apps/api/tests/test_cli_secrets.py | 2026-07-10T16:14:12Z |
+| `G-DB` | #6 | HARD-01 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m postgres -q packages/db | 2026-07-20T21:04:04Z |
+| `G-MODEL` | #1 | HARD-02 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q apps/api -k model_provider | 2026-07-20T21:04:04Z |
+| `G-RAG-REAL` | #2 | HARD-04 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m realeval -q | 2026-07-20T21:04:04Z |
+| `G-GH` | #1 | HARD-05 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k github_app | 2026-07-20T21:04:04Z |
+| `G-MCP` | #1 | HARD-06 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k mcp_live | 2026-07-20T21:04:04Z |
+| `G-SLACK` | #1 | HARD-07 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k slack_live | 2026-07-20T21:04:04Z |
+| `G-BUILD` | #3 | HARD-08 | 🟢 GREEN | deploy/build-manifest.json | 2026-07-20T21:04:04Z |
+| `G-TYPES` | #6 | HARD-12 | 🟢 GREEN | make typecheck | 2026-07-20T21:04:04Z |
+| `G-SEC-AUTOMATED` | #4 | HARD-09 | 🟢 GREEN | uv run pytest -m security -q | 2026-07-20T21:04:04Z |
+| `G-CRYPTO` | #5 | HARD-10 | 🟢 GREEN | uv run pytest -q apps/api/tests/test_auth_crypto_envelope.py apps/api/tests/test_cli_secrets.py | 2026-07-20T21:04:04Z |
 
 ## Verdict
 

From 9aeea0772956c9bd792d721e430a46bf36db5916 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:10:38 +0200
Subject: [PATCH 07/47] =?UTF-8?q?docs(plan):=20correct=20G-ATTEST=20expect?=
 =?UTF-8?q?ation=20=E2=80=94=20production-bar-only=20gate?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/superpowers/plans/2026-07-20-audit-remediation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/superpowers/plans/2026-07-20-audit-remediation.md b/docs/superpowers/plans/2026-07-20-audit-remediation.md
index f0e3671d..a38968e1 100644
--- a/docs/superpowers/plans/2026-07-20-audit-remediation.md
+++ b/docs/superpowers/plans/2026-07-20-audit-remediation.md
@@ -110,7 +110,7 @@ Fixes, each with verified reality:
 - [ ] **Step 1:** `uv run cz changelog --dry-run` (per CHANGELOG.md:6-8 header). If output includes the trust-layer PRs (#61-#66, #57, #36), regenerate the file with `uv run cz changelog`; otherwise append an Unreleased section manually covering: Attested Changesets (#61), Time-Travel Runs (#62), Red-Team Gate (#63), Self-Eval Gate (#64-#66), OIDC SSO + marketplace publish + leaderboard (#57), realtime co-editing (#36). Keep existing entries.
 - [ ] **Step 2:** Verify: `grep -in "attested\|time-travel\|red-team\|self-eval\|oidc" CHANGELOG.md` → all present.
 - [ ] **Step 3:** Makefile `release-readiness` target currently forces `--bar production` while the committed artifact and `docs/README.md:51` describe the beta bar. Parameterize: `BAR ?= beta` and use `--bar $(BAR)`.
-- [ ] **Step 4:** Regenerate: `uv run forge-release-readiness --bar beta > RELEASE_READINESS.md` (or the Make target's exact invocation — read `packages/evaluation/forge_eval/release/readiness.py` first for the real CLI shape; it writes the markdown itself). Expect: updated timestamp/commit, G-ATTEST row now present, no-creds gates still SKIPPED_NO_CREDS. This may take minutes; that's fine. Never let it run whole-repo pytest — if the render shells out to long gates, use its evidence/skip mode (read the module to confirm flags).
+- [ ] **Step 4:** Regenerate: `uv run forge-release-readiness --bar beta > RELEASE_READINESS.md` (or the Make target's exact invocation — read `packages/evaluation/forge_eval/release/readiness.py` first for the real CLI shape; it writes the markdown itself). Expect: updated timestamp/commit, no-creds gates still SKIPPED_NO_CREDS. (G-ATTEST is `bar: production` in release/gates.yaml and correctly does NOT appear in a beta render — confirmed during execution.) This may take minutes; that's fine. Never let it run whole-repo pytest — if the render shells out to long gates, use its evidence/skip mode (read the module to confirm flags).
 - [ ] **Step 5:** Sanity: `head -40 RELEASE_READINESS.md` shows HEAD commit hash and today's date.
 - [ ] **Step 6:** Commit: `docs(release): regenerate changelog and readiness snapshot at current HEAD`
 

From 128350a7941045193b8586cffc507cb4f75dfca5 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:19:04 +0200
Subject: [PATCH 08/47] docs: document trust layer, realtime co-editing, and
 adaptive orchestration

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/README.md       |   1 +
 docs/architecture.md |  19 +++
 docs/concepts.md     |  69 ++++++++-
 docs/trust-layer.md  | 330 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 415 insertions(+), 4 deletions(-)
 create mode 100644 docs/trust-layer.md

diff --git a/docs/README.md b/docs/README.md
index a39a9bc5..fc3dccc0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,6 +14,7 @@ Start here and follow the path that fits you.
 | **[Getting started](./getting-started.md)** | From a clone to your first orchestrated run in ~15 minutes |
 | **[Concepts](./concepts.md)** | The mental model: specs, workflows, agents, runs, knowledge, approvals, policies + a glossary |
 | **[Architecture](./architecture.md)** | Services, package map, and how a change flows through the platform |
+| **[Trust layer](./trust-layer.md)** | Attested Changesets, Time-Travel Runs, Red-Team Gate, and the Self-Eval Gate — verifiable autonomous change |
 
 ## Connect your tools
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 2816cc89..39336bbd 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -114,6 +114,25 @@ in steps 4–6.
   [threat model](./security/threat-model.md) and
   [security policy](../SECURITY.md).
 
+## Trust layer & provenance
+
+The trust-layer features are not a new service — each is a self-contained,
+append-only record spread across the existing packages, hooked into the flow
+above. Full detail (data models, API/CLI, and the parked/Phase-A limitations)
+lives in **[Trust layer](./trust-layer.md)**.
+
+| Feature | Where it lives | Hooks into |
+|---------|----------------|------------|
+| **Attested Changesets** | `forge_contracts.attestation` (DSSE + in-toto contract), `forge_obs.attest.signing` (Ed25519 signer/verifier), `forge_api` `attestation_service` + `forge-verify` CLI, `attestation` table (`forge_db`) | Minted on `pr` approval (step 5); chained into the audit log (step 6) |
+| **Time-Travel Runs** | `forge_agent.replay` (record/replay), `forge_worker.agent_runner` (recorder sink), `forge_api` replay/fork endpoints + `forge-replay` CLI, `run_recording` table | Records the agent run (step 3) behind `FORGE_RECORD_RUNS=1` |
+| **Red-Team Gate** | `forge_coordinator.red_team` (adversary harness), `forge_workflow` Temporal workflow + activity, `red_team_record` table | Runs inside the workflow (step 2), before the human spec-approval gate |
+| **Self-Eval Gate** | `forge_eval.sweval` (gate + scorer), `forge_api` `self_eval_gate`/`self_eval_service` + `/ao` config API, `forge_worker` mint/run tasks, `self_eval_baseline` table | Gates Adaptive Orchestration config changes; baselines minted from merged PRs |
+
+The two realtime WebSocket channels (`forge_api.routers.realtime`) — the board
+push (`/ws`) and CRDT spec co-editing (`/ws/spec/{spec_id}`, `pycrdt` server doc
+over the Yjs sync protocol) — mount at the app root rather than under the API
+prefix, matching the URLs the web client opens.
+
 ## Deployment options
 
 | Path | Use | Reference |
diff --git a/docs/concepts.md b/docs/concepts.md
index 60137188..b4b65df3 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -73,6 +73,21 @@ For work that fans out, the **coordinator** (`forge_coordinator`) supervises
 multiple agents — dividing a spec across agents and reconciling their results —
 rather than driving a single execution agent.
 
+## Adaptive Orchestration
+
+**Adaptive Orchestration** (`forge_orchestration_policy`) sizes a task or spec
+before an agent runs it. A **pure, deterministic** scoring function reads
+normalized signals — kind, priority, blast radius, file/repo counts, requirement
+and acceptance-criteria counts, whether it touches contracts or security,
+dependency count, and ambiguity — and returns a `ComplexitySizing`: a **tier**
+(`junior` / `medior` / `senior`), a **strategy** (`single` / `swarm`), a score,
+and the reasons behind it. The scorer picks neither a model nor an agent itself;
+its `tier`/`strategy` output is what the model router and per-role config consume
+to resolve the effective model and effort per agent role. It is configurable from
+a workspace settings screen (the `/ao` API), and you can preview what a sample
+task would be routed to via `POST /ao/routing-preview`. See
+[`packages/orchestration-policy/README.md`](../packages/orchestration-policy/README.md).
+
 ## Runs & the run-trace viewer
 
 A **run** is one execution of agent work. Every step, tool call, model
@@ -102,6 +117,49 @@ a human decision. When an agent reaches a gated action it pauses and enqueues an
 approval; a human approves or rejects before the action proceeds. Human-in-the-
 loop where it matters, autonomous everywhere else.
 
+## Trust layer
+
+Four features make an autonomous change *verifiable*, not merely recorded — each
+an append-only, single-table record:
+
+- **Attested Changesets** — a DSSE-signed, in-toto provenance record of what
+  actually ran (agent, model, sandbox tier, policy hash, tools, approver, spec
+  revision), minted when a PR gate is approved and chained into the audit log.
+- **Time-Travel Runs** — deterministic record-replay of an agent run from a
+  redacted cassette, plus a counterfactual **fork** that diverges onto a
+  different model from a chosen point.
+- **Red-Team Gate** — a heterogeneous adversary must fail to break a candidate
+  change (with an *executed* failing test or a real spec-violation) before the
+  change reaches the human implementation gate.
+- **Self-Eval Gate** — blocks a model/prompt/router config change that regresses
+  a workspace's private per-repo regression suite below a frozen baseline.
+
+Some of these ship with parked or Phase-A limits (the Red-Team Gate records a
+parked-pass when no adversary is wired; the Self-Eval Gate no-ops at the API
+layer without an injected runner) — each is stated plainly in
+**[Trust layer](./trust-layer.md)**.
+
+## Realtime co-editing
+
+Two WebSocket channels (`forge_api.routers.realtime`), both authenticated
+per-workspace, back the live surfaces. `/ws` is a one-way, server→client **board
+push**: the server pushes JSON envelopes as board entities change and the web
+board hook maps them onto query keys to invalidate.
+
+`/ws/spec/{spec_id}` is **collaborative spec editing** over the **Yjs** binary
+sync protocol (the web client uses `yjs` + `y-websocket`). The server owns an
+*authoritative* CRDT document (a `pycrdt` `Doc` holding a `Text` for `spec.md`
+and `manifest.yaml`), seeded from the canonical spec engine; connected peers
+converge against it. Presence and cursors ride the same socket as ephemeral Yjs
+*awareness* frames, but identity (display name and colour) is **stamped
+server-side** from the authenticated principal, so no peer can spoof another.
+Write gating lives at the router — a read-only principal may observe, but a
+doc-mutating frame from one is a policy violation and closes the socket. The Y
+document is ephemeral: on quiesce (a short idle gap, or the last editor leaving)
+the room materialises `spec.md` back through the engine and records exactly
+**one** `SpecVersion` checkpoint (not one per keystroke), attributed to the most
+recent editor.
+
 ## Policies, skills, integrations & MCP
 
 Forge is configured declaratively through SDKs:
@@ -146,10 +204,9 @@ scoped per team and workspace.
 - **Benchmark leaderboard** — submit, verify, and rank agent benchmark runs,
   with a public leaderboard UI (backed by an offline `forge bench` CLI for
   submission).
-- **Adaptive Orchestration** (`forge_orchestration_policy`) — deterministically
-  sizes a spec or task's complexity (tier: junior/medior/senior, strategy:
-  single/swarm) and resolves the effective model/tier routing per agent role,
-  configurable from a workspace settings screen.
+- **Adaptive Orchestration** (`forge_orchestration_policy`) — deterministic
+  complexity sizing and per-role model/tier routing; see
+  [Adaptive Orchestration](#adaptive-orchestration) above.
 - **Deployment gates** (`forge_deploy`) — policy-gated promotion of changes
   through environments.
 
@@ -168,6 +225,10 @@ scoped per team and workspace.
 | **BYOK** | Bring-your-own-key model-provider credentials |
 | **MCP** | Model Context Protocol — tool-source gateway for agents |
 | **Approval** | Human decision gating a sensitive agent action |
+| **Attested Changeset** | DSSE-signed in-toto provenance record of what actually ran ([trust layer](./trust-layer.md)) |
+| **Cassette** | Redacted record of a run's LLM + tool calls, replayed by substitution ([Time-Travel Runs](./trust-layer.md#time-travel-runs)) |
+| **Red-Team Gate** | Heterogeneous adversary that must fail to break a change before the human gate |
+| **Self-Eval Gate** | Blocks a config change that regresses a workspace's private per-repo suite |
 
 Next: **[Architecture](./architecture.md)** for how these run together, or
 **[Getting started](./getting-started.md)** to try them.
diff --git a/docs/trust-layer.md b/docs/trust-layer.md
new file mode 100644
index 00000000..52ed8a5c
--- /dev/null
+++ b/docs/trust-layer.md
@@ -0,0 +1,330 @@
+# Trust layer
+
+Four features that make autonomous change *verifiable* rather than merely
+recorded. Where the [run-trace viewer](./concepts.md) answers *what did the
+agent do*, the trust layer answers *can I prove it, could I replay it, did
+anything adversarial catch it, and did this config change quietly make the
+system worse*. Each feature is a self-contained, append-only record backed by
+one Postgres table; none of them can mutate existing behaviour (every migration
+is purely additive).
+
+This document is written from the code. Where a capability is parked or
+Phase-A, that is stated plainly in the feature's **Current limitations** — a
+parked stand-in that looks like a pass is a trust hazard, so it is named.
+
+For where these sit in the platform, see [Architecture](./architecture.md); for
+the mental model, see [Concepts](./concepts.md).
+
+| Feature | One line | Table | Migration |
+|---------|----------|-------|-----------|
+| [Attested Changesets](#attested-changesets) | DSSE-signed in-toto provenance over a changeset | `attestation` | `0036` |
+| [Time-Travel Runs](#time-travel-runs) | Deterministic record-replay (and counterfactual fork) of an agent run | `run_recording` | `0037` |
+| [Red-Team Gate](#red-team-gate) | A heterogeneous adversary must fail to break the change before the human gate | `red_team_record` | `0038` |
+| [Self-Eval Gate](#self-eval-gate) | Block a config change that regresses a workspace's private per-repo suite | `benchmark_suite` (+cols), `self_eval_baseline` | `0039`, `0040` |
+
+---
+
+## Attested Changesets
+
+### What it is
+
+An **Attested Changeset** is a cryptographically signed, tamper-evident record
+of the *truthful runtime provenance* of the agent run that produced a change —
+what actually ran, never a planned or intended value. It is a
+[DSSE](https://github.com/secure-systems-lab/dsse) (Dead Simple Signing
+Envelope) wrapping an [in-toto v1 Statement](https://github.com/in-toto/attestation),
+whose predicate (`ChangesetProvenance`) records the agent role and model, the
+model version the provider reported, the spec revision the prompt was built
+against, the sandbox isolation tier the commands executed under, a content hash
+of the policy in effect, the ordered tool names invoked (names only — no
+arguments, since an attestation may be exported outside the trust boundary the
+raw step log lives in), the human approver, the linked workflow/agent run, the
+PR numbers, and the spec key/version.
+
+The contract lives in
+`packages/contracts/forge_contracts/attestation.py`. The signer/verifier
+(`packages/observability/forge_obs/attest/signing.py`) uses raw **Ed25519** keys
+and signs over the DSSE **PAE** (Pre-Authentication Encoding) of
+`(payloadType, payload)`, so relabeling the payload type invalidates the
+signature. Signing and verifying are pure and total — malformed input is "not
+verified", never an exception.
+
+The signing key comes from `FORGE_ATTEST_SIGNING_KEY` (a base64 32-byte Ed25519
+seed). Signing an attestation is a provenance convenience, not a confidentiality
+boundary, so an **unset** key fails *open* to a loudly-warned, process-ephemeral
+key (a real deployment must set a stable key or verification fails after a
+restart); a key that *is* set but malformed fails *closed*. The `keyid` is the
+sha256 of the raw public key bytes — a content-derived id a verifier looks up
+rather than trusting a signer-asserted one.
+
+### Data model
+
+`AttestationService` (`apps/api/forge_api/services/attestation_service.py`)
+reads the strongly-linked rows for a workflow run (`AgentRun`,
+`TraceabilityCriterionLink`, `SpecVersion`), assembles the `ChangesetProvenance`
+predicate inside an in-toto `Statement`, signs it, inserts one append-only
+`Attestation` row, and emits a `changeset.attested` event through the F39 audit
+hash chain — whose `detail_ref` points back at the attestation row, and whose
+returned `seq` is recorded on the row (`audit_seq`). Because the table is
+append-only, the id is pre-generated so the audit event can reference it and
+`audit_seq` lands in the single INSERT.
+
+The `attestation` table (migration `0036`,
+`packages/db/forge_db/models/attestation.py`) is append-only, hardened by the
+shared Postgres BEFORE UPDATE/DELETE immutability trigger. Columns:
+`subject_digest`, `predicate_type`, `envelope` (the full DSSE JSON),
+`payload_hash` (sha256 of the PAE-encoded payload the signature covers),
+`keyid`, nullable `workflow_run_id`/`agent_run_id`, `pr_numbers`, `spec_key`,
+`spec_version`, `audit_seq`, and `merkle_leaf_hash` (reserved for a future
+batch-Merkle anchoring scheme, unused today).
+
+### API / CLI surface
+
+Attestations are minted as a **side effect of approval**:
+`PrAttestationResolutionHook` is registered against the F36 approval system, so
+approving a `pr` gate that carries a `workflow_run_id` attests the changeset
+(recording the approving user as `human_approver`). There is no dedicated REST
+endpoint or UI yet.
+
+Verification is offline-first via the `forge-verify` CLI (`python -m
+forge_api.cli_verify`, `apps/api/forge_api/cli_verify.py`). Three
+mutually-exclusive modes, all exiting **non-zero on any verification failure** so
+they can gate a release:
+
+| Mode | Does | Needs a DB? |
+|------|------|-------------|
+| `--attestation <file\|->` | Offline DSSE-verify an envelope's Ed25519 signature against `--public-key` (or the public half of `FORGE_ATTEST_SIGNING_KEY`) | No |
+| `--run <id>` | Load the stored `Attestation`, re-derive `payload_hash` from the envelope's PAE and confirm it matches the recorded column, then verify the signature | Yes |
+| `--audit-export <ndjson>` | Re-walk an F39 audit-chain export offline: recompute each row's `payload_hash`/`entry_hash` and re-check the per-workspace `prev_hash` linkage | No |
+
+Exit codes: `0` verified / chain intact, `1` rejected or tampered, `3` no
+database configured (a "can't check" distinguished from a "checked and it's
+tampered").
+
+### Current limitations
+
+- **Minted only as an approval side effect.** An attestation is produced when a
+  `pr` approval gate carrying a `workflow_run_id` is approved. There is **no
+  REST endpoint and no UI** to list, fetch, or trigger attestations — those
+  arrive in a later task (Attested Changesets REST endpoints + UI, Task 19).
+- **Default signing key is process-ephemeral.** If `FORGE_ATTEST_SIGNING_KEY`
+  is unset, signatures are made with a warned-about ephemeral key and will fail
+  verification after a restart or from another process. Set a stable key in any
+  real deployment.
+- `merkle_leaf_hash` is reserved and unused; there is no batch-Merkle-root
+  anchoring yet.
+
+---
+
+## Time-Travel Runs
+
+### What it is
+
+**Time-Travel Runs** is deterministic record-replay of an agent run. The two
+nondeterministic boundaries — LLM completions and tool calls — are recorded into
+a redacted **cassette** (`RunCassette`) keyed by call-order. Replay does **not**
+re-seed the model (the target providers 400 on `seed`/`temperature`); it
+substitutes the recorded response/result back in by call-index, so no live model
+or tool is ever touched during a replay. A per-call divergence canary reports
+the first point where a re-run stops matching the tape.
+
+Recording is opt-in behind `FORGE_RECORD_RUNS=1` (default **off**). When
+enabled, `build_agent_runner`
+(`apps/worker/forge_worker/agent_runner.py`) wraps the model and tools with
+`RecordingModelClient` / `RecordingToolRegistry` bound to a fresh cassette;
+`persist_run_recording` then redacts the cassette, offloads oversized tool
+outputs to the artifact store, and inserts an append-only `RunRecording` row.
+
+### Data model
+
+The `run_recording` table (migration `0037`,
+`packages/db/forge_db/models/run_recording.py`) is append-only via the shared
+immutability trigger. Columns: nullable `agent_run_id`/`workflow_run_id`, the
+redacted `cassette` snapshot (LLM calls, tool calls, and the redacted env, keyed
+by call-index), `model` (the id the run was driven under — nullable, since a
+tool-only run has no model to report), and `content_hash` (sha256 of the
+cassette's canonical JSON — a whole-tape fingerprint).
+
+### API / CLI surface
+
+Two endpoints on the agent router (`apps/api/forge_api/routers/agent.py`), both
+loading the workspace-scoped recording (404 for a missing or foreign-tenant
+one):
+
+| Endpoint | Permission | Behaviour |
+|----------|-----------|-----------|
+| `POST /agent/runs/{run_id}/replay` | `READ` | Re-run the objective by substitution and return a per-step diff plus any divergence. Read-only — never mutates the recording or produces a new persisted run. |
+| `POST /agent/runs/{run_id}/fork` | `RUN_AGENT` | Counterfactual fork: replay up to `fork_index`, then from the fork on, LLM completions run against a **different** model (`model`, optionally with a `prompt_override` appended to the system prompt) and tool dispatches run **live**. If the pre-fork prefix no longer reproduces the tape, the fork aborts and the divergence is reported. |
+
+The `forge-replay` CLI (`python -m forge_api.cli_replay`,
+`apps/api/forge_api/cli_replay.py`) loads a persisted cassette by id, replays a
+supplied objective by substitution, and prints a step-by-step diff. Exit codes:
+`0` reproduced, `1` diverged or error, `3` no database configured.
+
+A web surface exists at
+`apps/web/src/components/run-trace/time-travel-replay.tsx`.
+
+### Current limitations
+
+- **Recording is opt-in and off by default** (`FORGE_RECORD_RUNS=1`). A run not
+  recorded has no cassette to replay or fork.
+- Replay is **by call-index substitution**, not model re-seeding — a structural
+  change to the run (different tool order) diverges rather than silently
+  re-running.
+- A tool-only run (zero LLM calls) records `model=None`.
+
+---
+
+## Red-Team Gate
+
+### What it is
+
+The **Red-Team Gate** puts a distinct **adversary** agent between a candidate
+change and the human implementation gate. The adversary runs a **heterogeneous**
+model — a different provider than the coder used — and is scoped to the
+`ADVERSARY` role tools: it may read the repo, author a candidate failing test,
+and run SAST, but it can **never edit product code**. It attacks the candidate
+diff, and a change is **BLOCKED** only when:
+
+- the adversary's authored test **actually fails when executed in a sandbox**
+  (non-zero exit) — an *executed* failing test, never the adversary's own
+  self-reported pass; or
+- the adversary reports a structured spec-violation that references a **real**
+  `AcceptanceCriterion` of the spec.
+
+Otherwise the change earns a `survived` verdict — the "survived adversarial
+review" signal that feeds the Attested Changeset. Heterogeneity is enforced up
+front: a homogeneous adversary (same provider as the coder) is rejected with
+`HomogeneousAdversaryError` before any model or sandbox work. The harness lives
+in `packages/multi-agent-coordinator/forge_coordinator/red_team.py`
+(`run_red_team`).
+
+### Data model
+
+The `red_team_record` table (migration `0038`,
+`packages/db/forge_db/models/red_team.py`) is append-only via the shared
+immutability trigger. Columns: nullable `workflow_run_id`, `verdict`
+(`blocked`/`survived`), `kind` (`failing_test`, `spec_violation`, or `parked`),
+`evidence` (the structured attack result), and the heterogeneous
+`adversary_model` / `coder_model` pair (both nullable — a parked-pass has no
+adversary model).
+
+### API / CLI surface
+
+The gate is driven inside the **Temporal** workflow
+(`packages/workflow-engine/forge_workflow/temporal/workflows.py`): after the spec
+is drafted and clarified but **before** the human spec-approval gate, the
+workflow runs a red-team scan. A `blocked` verdict routes the change back for
+changes (→ clarification → spec review) so a human must address the finding; a
+`survived` verdict proceeds unchanged and the recorder writes the
+`RedTeamRecord` plus a `redteam.survived` audit event.
+
+The verdict is surfaced read-only at `GET /workflow/runs/{run_id}/red-team`
+(`apps/api/forge_api/routers/workflow.py`), returning the latest verdict plus the
+full scan history (a `blocked` scan followed by a re-submitted `survived` one is
+common). It reads the append-only table scoped to the caller's workspace on the
+row itself; an unscanned or foreign run reads as `latest=None` with an empty
+history — never a 404, so the endpoint never leaks cross-tenant existence.
+
+### Current limitations
+
+- **Parked-pass when no adversary is wired.** The Temporal activity's default
+  `red_team_fn`
+  (`packages/workflow-engine/forge_workflow/temporal/activities.py`,
+  `_default_red_team`) records a **parked-pass**: `verdict=survived`,
+  `kind=parked`, `evidence={"parked": true, "reason": "no adversary model/sandbox
+  wired"}`. This is a *park-don't-fake* stand-in so the durable spine runs and
+  the human gate is still reached — it is **not** a real adversarial review, and
+  a `survived`/`parked` record must not be read as "an adversary tried and
+  failed to break this". A real deployment must inject a `red_team_fn` that runs
+  the heterogeneous, sandboxed adversary (`run_red_team`).
+- **Temporal path only.** The scan runs today only inside the Temporal workflow.
+  A trigger endpoint and a non-Temporal worker path arrive in a later task
+  (Red-Team trigger endpoint + non-Temporal worker path, Task 20).
+
+---
+
+## Self-Eval Gate
+
+### What it is
+
+The **Self-Eval Gate** refuses a model / prompt / router **config change** if,
+re-evaluated on a workspace's **private per-repo regression suite**, its
+resolution rate drops below a frozen baseline. The private suite is a *living
+accumulator* minted from the org's own merged PRs: each merge can mint one hidden
+regression case, and those minted test ids live only on disk in the suite dir —
+they never enter a model prompt.
+
+The gate itself (`packages/evaluation/forge_eval/sweval/gate.py`,
+`SelfEvalGate.check_config`) is small and injectable: it looks up the baseline,
+runs the eval runner over the proposed config, and raises
+`SelfEvalRegressionError` when the new resolution rate is below the baseline. It
+is a **no-op on cold start** (no baseline, or no private suite) so existing
+config flows stay green until a suite exists, and a `force=True` override skips
+the check (audited).
+
+### Data model
+
+Two migrations:
+
+- **`0039`** extends `benchmark_suite` with three additive columns:
+  `workspace_id` (nullable FK), `repo_id` (nullable, free-form), and `private`
+  (`NOT NULL`, default `false`). A NULL `workspace_id` / `private=false`
+  preserves today's shared/community-suite semantics for every pre-existing row;
+  only a newly-minted self-eval suite opts into `private=true`.
+- **`0040`** adds the `self_eval_baseline` table
+  (`packages/db/forge_db/models/benchmark.py`, `SelfEvalBaseline`): exactly one
+  baseline per `(workspace, suite)` (unique constraint), carrying
+  `baseline_rate`, `resolved`, `total`, a **redacted** `config` snapshot (no
+  secrets ever land in this table), and `recorded_by`. A run upserts the row.
+
+`SelfEvalService`
+(`apps/api/forge_api/services/self_eval_service.py`) is the storage layer:
+`workspace_baseline` is the gate's baseline lookup (most-recently-updated wins;
+`None` on cold start), and `record_baseline` upserts — with `overwrite=False`, an
+existing baseline is left untouched so a regressing run can never silently
+*lower* the bar it defends.
+
+### API / CLI surface
+
+The gate is consulted at the Adaptive Orchestration config-change API
+(`apps/api/forge_api/routers/ao_settings.py`) on `PUT /ao/role-config/{role}`
+and `PUT /ao/settings`. Enforcement is behind the `self_eval_enforce` app
+setting (a no-op unless set). On a regression the block is **audited**
+(`ao.config.self_eval_blocked`, its own committed row) and a `409` is raised
+*before* the mutation is applied; a `force=true` override is audited
+(`ao.config.self_eval_forced`) and allowed through.
+
+Two worker tasks own the offline, agent-driven halves (they run in the worker,
+never a request path, because a real run is minutes-long):
+
+- `forge.self_eval.mint` (`apps/worker/forge_worker/tasks/self_eval_mint.py`) —
+  mints a hidden regression case from each merged PR and appends it to the
+  private suite, re-freezing the manifest with a fresh `content_hash`.
+- `forge.self_eval.run` (`apps/worker/forge_worker/tasks/self_eval_run.py`) —
+  drives the `ProductionEvalRunner` over the private suite and records the
+  baseline the gate blocks against. It is an honest **no-op** until an operator
+  provisions the prerequisites (a published private suite, `FORGE_BENCHMARK_DIR`,
+  a local clone under `FORGE_SELF_EVAL_REPO_ROOT/<repo_id>`, and a BYOK model) —
+  every missing piece resolves to a `scored: false` reason rather than
+  fabricating a score.
+
+### Current limitations
+
+- **Phase A: the API-layer gate no-ops without an injected runner.** The default
+  eval runner at the API layer (`_unavailable_runner` in
+  `apps/api/forge_api/services/self_eval_gate.py`) returns `None`, because
+  running a workspace's private suite is a minutes-long worker job and
+  `apps/api` cannot import `forge_worker` without an import cycle. So at
+  config-change time the API gate has **no fresh scorecard for the proposed
+  config and no-ops** — the gate *mechanism* (baseline lookup, regression block,
+  force override, audit) is fully wired and exercised in tests by injecting a
+  runner, but a stock API deployment does not evaluate the proposed config
+  inline.
+- **Enforcement is off by default** (`self_eval_enforce`).
+- **Baseline establishment/refresh is worker-driven only.** It is the
+  `forge.self_eval.run` Celery task. (Some in-code docstrings refer to this as
+  "the worker-owned `POST /ao/self-eval/runs` path" — that HTTP endpoint does
+  **not** exist today; `benchmarks.py` states there is no inline `POST /runs`,
+  and the baseline run is the Celery task.)
+- **No web UI yet** (Self-Eval web UI, Task 21).

From f36edadcdead5e0a608aea51202165cd650e346a Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:20:17 +0200
Subject: [PATCH 09/47] =?UTF-8?q?docs(plan):=20Task=2021=20=E2=80=94=20no?=
 =?UTF-8?q?=20/ao/self-eval/runs=20endpoint=20exists;=20prefer=20thin=20tr?=
 =?UTF-8?q?igger=20endpoint?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/superpowers/plans/2026-07-20-audit-remediation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/superpowers/plans/2026-07-20-audit-remediation.md b/docs/superpowers/plans/2026-07-20-audit-remediation.md
index a38968e1..58167e6a 100644
--- a/docs/superpowers/plans/2026-07-20-audit-remediation.md
+++ b/docs/superpowers/plans/2026-07-20-audit-remediation.md
@@ -363,7 +363,7 @@ Fixes, each with verified reality:
 
 **Files:**
 - Create: `apps/web/src/components/self-eval/self-eval-panel.tsx` (+ `.test.tsx`), surfaced in settings (same page family as `ao_settings` backend — find where AO settings render: `grep -rn "ao" apps/web/src/app/(board)/settings`)
-- Consumes: existing endpoints from `routers/ao_settings.py` (suite scoping, baseline, run trigger `POST /ao/self-eval/runs`, gate verdicts) — read the router to enumerate the exact contract first; do NOT invent endpoints.
+- Consumes: existing endpoints from `routers/ao_settings.py` (suite scoping, baseline, gate verdicts) — read the router to enumerate the exact contract first; do NOT invent endpoints. NOTE (found during Task 4): there is NO `POST /ao/self-eval/runs` endpoint — runs are minted via the Celery task `forge.self_eval.run`. For the panel's "run self-eval" action, prefer adding a thin authenticated POST endpoint in `routers/ao_settings.py` that enqueues that existing task (consistent with #66's worker-driven design); if that proves non-trivial, ship the read-only panel and state the run path plainly in the UI copy.
 
 **Interfaces:**
 - Produces: panel showing configured suite, current baseline (score + minted at), last run result, gate status for pending config changes; a "run self-eval" action calling the existing run endpoint; Phase-A limitation copy (API-layer gate requires a baseline) stated inline.

From a36691d9283e32d95bb83f3c40cb9f4b5bc85e29 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:40:49 +0200
Subject: [PATCH 10/47] feat(deploy): add nginx reverse-proxy config and
 reverse-proxy doc

---
 deploy/nginx/forge.conf            | 256 +++++++++++++++++++++++++++++
 docs/self-hosting/quickstart.md    |   8 +-
 docs/self-hosting/reverse-proxy.md | 155 +++++++++++++++++
 3 files changed, 416 insertions(+), 3 deletions(-)
 create mode 100644 deploy/nginx/forge.conf
 create mode 100644 docs/self-hosting/reverse-proxy.md

diff --git a/deploy/nginx/forge.conf b/deploy/nginx/forge.conf
new file mode 100644
index 00000000..267da0ec
--- /dev/null
+++ b/deploy/nginx/forge.conf
@@ -0,0 +1,256 @@
+# Forge — nginx reverse-proxy alternative to deploy/caddy/Caddyfile (Task 5).
+#
+# This is a faithful routing equivalent of the default Caddy edge
+# (deploy/caddy/Caddyfile): same upstreams (service:port pairs come straight
+# from deploy/docker-compose.yml), same paths, same websocket handling. Use it
+# in place of Caddy when an operator wants a config surface they already know,
+# or needs nginx-specific features (an existing nginx-based LB/WAF, etc.). See
+# docs/self-hosting/reverse-proxy.md for how to wire this in and the concrete
+# differences from the Caddy default — most importantly, nginx does not
+# auto-provision TLS the way Caddy does (see the commented-out TLS block
+# below).
+#
+# Validation performed in the authoring environment (docker was available):
+#   docker run --rm -v "$PWD/deploy/nginx/forge.conf:/etc/nginx/conf.d/forge.conf:ro" nginx:alpine nginx -t
+# passed ("syntax is ok" / "test is successful"), plus a manual functional
+# smoke test (real nginx:alpine container + traefik/whoami stand-ins named
+# api/mcp-gateway/web/grafana/temporal-ui) confirming each route below reaches
+# the right upstream with the right path (stripped or not) and that
+# basic-auth-gated routes 401 without credentials. This is config-syntax +
+# routing-logic validation only — it was NOT run against the real Forge
+# services or the actual docker-compose.yml network topology. See
+# docs/self-hosting/reverse-proxy.md and .superpowers/sdd/task-5-report.md for
+# the full account.
+#
+# Mount this file at /etc/nginx/conf.d/forge.conf. The stock nginx:alpine image
+# also ships /etc/nginx/conf.d/default.conf; remove or override that mount too
+# (see the doc) or you will get two `listen 80` server blocks.
+
+# Caddy's `reverse_proxy` autodetects the `Upgrade` header and proxies
+# websockets with no extra config. nginx needs this map (standard recipe) plus
+# the two proxy_set_header lines below on every websocket location.
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 80;
+    # Caddyfile: `{$DOMAIN:localhost} { ... }`. nginx config files have no
+    # runtime env-var substitution; set this to your real DOMAIN, or render
+    # this file through `envsubst` (or a templating step) at container start.
+    server_name _;
+
+    # Caddy resolves each upstream's DNS name lazily, per-request, so it
+    # never cares what order Compose starts services in. Static nginx
+    # `upstream {}` blocks resolve once at startup and fail hard
+    # ("host not found in upstream") if that name isn't up yet — a real
+    # regression vs. Caddy's behavior with Compose's non-deterministic start
+    # order. Using a variable in `proxy_pass` (below, on every location) plus
+    # this `resolver` defers resolution to request time instead, matching
+    # Caddy. 127.0.0.11 is Docker's embedded DNS server, present in every
+    # container on a user-defined network (i.e. any Compose network here).
+    resolver 127.0.0.11 valid=10s;
+
+    # --- TLS (commented out; see docs/self-hosting/reverse-proxy.md) --------
+    # Caddyfile's top-level `{ email {$ACME_EMAIL:admin@localhost} }` block
+    # plus the `{$DOMAIN:localhost} { ... }` site block get Caddy automatic
+    # ACME certificate issuance and renewal for free. nginx has no built-in
+    # ACME client: run certbot/acme.sh alongside it (or terminate TLS
+    # upstream of nginx) and uncomment something like:
+    #
+    # listen 443 ssl;
+    # ssl_certificate     /etc/nginx/certs/fullchain.pem;
+    # ssl_certificate_key /etc/nginx/certs/privkey.pem;
+    # ssl_protocols       TLSv1.2 TLSv1.3;
+    # # then, on this :80 server, redirect instead of serving directly:
+    # # return 301 https://$host$request_uri;
+    # -------------------------------------------------------------------------
+
+    # Caddyfile: `encode gzip zstd`. Stock nginx ships gzip only — no zstd
+    # module — so this is a partial parity gap; see the doc.
+    gzip on;
+    gzip_types text/plain application/json application/javascript text/css application/x-ndjson;
+
+    # Caddyfile: `header { Strict-Transport-Security ...; X-Content-Type-Options
+    # nosniff; Referrer-Policy ...; -Server }` applied to every route.
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    # Caddy's `-Server` strips the Server header outright. Stock nginx has no
+    # directive to remove it entirely (that needs the third-party
+    # headers-more module); `server_tokens off` is the closest built-in
+    # equivalent — it drops the version string but the bare "nginx" token
+    # remains. Noted as a gap in the doc.
+    server_tokens off;
+
+    # Caddyfile: `log { output stdout; format console }`. The official nginx
+    # image already symlinks its default access/error logs to stdout/stderr;
+    # these are explicit for clarity.
+    access_log /dev/stdout;
+    error_log  /dev/stderr;
+
+    # Caddyfile lines 24-34: alert-provider (PagerDuty/Datadog/Sentry/Grafana)
+    # and PM (Jira/Linear) webhook signatures are HMAC'd over the EXACT raw
+    # request body, so these paths MUST reach the API byte-for-byte. Caddy
+    # never buffers request bodies by default; nginx does, so
+    # `proxy_request_buffering off` is load-bearing here, not decorative.
+    location ~ ^/api/v1/integrations/alerts/[^/]+/webhook$ {
+        # No URI segment on proxy_pass: forwards the path verbatim, matching
+        # Caddy's `handle` (as opposed to the prefix-stripping `handle_path`
+        # used for the general /api/* surface below).
+        set $upstream_api http://api:8000;
+        proxy_pass $upstream_api;
+        proxy_request_buffering off;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    location ^~ /api/v1/integrations/pm/webhooks/ {
+        set $upstream_api http://api:8000;
+        proxy_pass $upstream_api;
+        proxy_request_buffering off;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Caddyfile: `handle /public/*` (F35 public leaderboard) — no prefix
+    # stripping; the API mounts this router at its own root path.
+    location /public/ {
+        set $upstream_api http://api:8000;
+        proxy_pass $upstream_api;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Realtime WebSockets (forge_api.routers.realtime): board push (`/ws`) and
+    # CRDT spec co-editing (`/ws/spec/{spec_id}`). Per docs/architecture.md
+    # ("Trust layer & provenance"), these mount at the API app ROOT, not under
+    # /api. The Caddyfile has no dedicated handle block for either path today
+    # — absent one, both would fall through to the catch-all `web:3000` route
+    # below, which is wrong (the socket only exists on `api`). Added here
+    # explicitly per this task's brief; flagged in the task report as a gap
+    # worth also closing in the Caddyfile.
+    location = /ws {
+        set $upstream_api http://api:8000;
+        proxy_pass $upstream_api;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        # A long-lived socket: nginx's 60s default proxy_read_timeout would
+        # kill an idle connection. 3600s matches the read/send timeout this
+        # repo already uses for its nginx-ingress ws/SSE routes (see
+        # deploy/helm/forge/values.yaml `ingress.sseReadTimeout`).
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+
+    location /ws/spec/ {
+        set $upstream_api http://api:8000;
+        proxy_pass $upstream_api;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+
+    # Caddyfile: `handle_path /api/*` — strips the `/api` prefix before
+    # forwarding. A variable in proxy_pass (needed for deferred DNS
+    # resolution, see the `resolver` comment above) disables nginx's usual
+    # "trailing slash on proxy_pass" prefix-stripping trick, so the `rewrite
+    # ... break` does the strip explicitly instead — same net effect. Also
+    # carries the NDJSON audit-export stream (forge_api.routers.audit
+    # `/audit/export`); buffering is disabled so it flushes the way Caddy's
+    # unbuffered default does.
+    location /api/ {
+        # `set` must run before `rewrite ... break` — `break` halts all
+        # further rewrite-module directives (including a later `set`) for
+        # this request, which would otherwise leave $upstream_api empty.
+        set $upstream_api http://api:8000;
+        rewrite ^/api/(.*)$ /$1 break;
+        proxy_pass $upstream_api;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+
+    # Caddyfile: `handle_path /mcp/*` — strips the `/mcp` prefix (see the
+    # `rewrite` note on the /api/ location above for why this uses `rewrite`
+    # instead of a trailing-slash proxy_pass).
+    location /mcp/ {
+        set $upstream_mcp http://mcp-gateway:8001;
+        rewrite ^/mcp/(.*)$ /$1 break;
+        proxy_pass $upstream_mcp;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Caddyfile: `handle /_temporal*` — admin-gated Temporal Web UI (`temporal`
+    # profile), basic-auth locked by default. Caddy's default is a dummy
+    # bcrypt hash that accepts no credentials until TEMPORAL_UI_BASIC_AUTH is
+    # set; the nginx equivalent is an htpasswd file that does not exist until
+    # an operator creates one, so this route 401s for everyone out of the box
+    # (fails closed the same way). Generate credentials with:
+    #   htpasswd -c /etc/nginx/secrets/temporal.htpasswd admin
+    location /_temporal {
+        auth_basic "Forge Temporal UI";
+        auth_basic_user_file /etc/nginx/secrets/temporal.htpasswd;
+        set $upstream_temporal_ui http://temporal-ui:8080;
+        proxy_pass $upstream_temporal_ui;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Caddyfile: `handle /grafana/*` (`observability` profile) — deliberately
+    # `handle`, not `handle_path`: Grafana runs with
+    # GF_SERVER_SERVE_FROM_SUB_PATH, so it must see the /grafana prefix; do
+    # not strip it here either. Basic-auth locked by default, same pattern as
+    # /_temporal above (in addition to Grafana's own admin login).
+    location /grafana/ {
+        auth_basic "Forge Grafana";
+        auth_basic_user_file /etc/nginx/secrets/grafana.htpasswd;
+        set $upstream_grafana http://grafana:3000;
+        proxy_pass $upstream_grafana;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Caddyfile: `handle { reverse_proxy web:3000 }` — catch-all; must stay
+    # last so every more-specific location above is tried first.
+    location / {
+        set $upstream_web http://web:3000;
+        proxy_pass $upstream_web;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
diff --git a/docs/self-hosting/quickstart.md b/docs/self-hosting/quickstart.md
index fa93b317..079aa287 100644
--- a/docs/self-hosting/quickstart.md
+++ b/docs/self-hosting/quickstart.md
@@ -3,9 +3,11 @@
 Stand up a complete Forge instance on a single machine with Docker Compose. This
 is the fastest path from a clone to a running board, knowledge pipeline, and
 API. For the production hardening details see
-[docker-compose.md](docker-compose.md); for day-2 operations see
-[backup.md](backup.md), [restore.md](restore.md), [upgrade.md](upgrade.md),
-[security.md](security.md), and [troubleshooting.md](troubleshooting.md).
+[docker-compose.md](docker-compose.md); for the edge proxy (Caddy by default,
+nginx alternative) see [reverse-proxy.md](reverse-proxy.md); for day-2
+operations see [backup.md](backup.md), [restore.md](restore.md),
+[upgrade.md](upgrade.md), [security.md](security.md), and
+[troubleshooting.md](troubleshooting.md).
 
 ## Prerequisites
 
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
new file mode 100644
index 00000000..509836c9
--- /dev/null
+++ b/docs/self-hosting/reverse-proxy.md
@@ -0,0 +1,155 @@
+# Reverse proxy: Caddy (default) vs. nginx (alternative)
+
+Forge's edge — the single TLS-terminating entrypoint in front of the API, web
+UI, MCP gateway, and the admin-gated Temporal/Grafana UIs — is
+[Caddy](https://caddyserver.com/) by default. This guide explains why, what it
+routes, and how to swap in the nginx alternative this repo also ships if you'd
+rather run a proxy you already operate.
+
+## Caddy (default)
+
+[`deploy/caddy/Caddyfile`](../../deploy/caddy/Caddyfile) is the config the
+`caddy` service in [`deploy/docker-compose.yml`](../../deploy/docker-compose.yml)
+mounts. It's the default for one reason: **automatic TLS**. Point `DOMAIN` at
+a real hostname with a public A/AAAA record and Caddy obtains and renews a
+Let's Encrypt certificate with zero extra config; for local trials
+(`DOMAIN=localhost`, the default) it serves over Caddy's internal CA instead.
+It also reverse-proxies websockets with no special configuration — Caddy
+detects the `Upgrade` header on any route automatically.
+
+Nothing else about this guide changes Caddy's behavior. Use it unless you have
+a specific reason not to.
+
+## nginx (alternative)
+
+[`deploy/nginx/forge.conf`](../../deploy/nginx/forge.conf) is a route-for-route
+equivalent of the Caddyfile, for operators who'd rather run nginx — an
+existing nginx-based load balancer/WAF in front, more familiar config syntax,
+or an nginx-specific module you need. It is **not** a generic reverse-proxy
+template: every `location` in it traces back to a `handle`/`handle_path` block
+in the Caddyfile (cited in comments), using the same service:port upstreams
+from `docker-compose.yml`.
+
+### Routes
+
+| Path | Caddyfile directive | Upstream | Prefix stripped? |
+|---|---|---|---|
+| `/api/v1/integrations/alerts/*/webhook` | `handle` | `api:8000` | No (HMAC'd raw body) |
+| `/api/v1/integrations/pm/webhooks/*` | `handle` | `api:8000` | No (HMAC'd raw body) |
+| `/public/*` | `handle` | `api:8000` | No |
+| `/ws`, `/ws/spec/*` | *(none — see below)* | `api:8000` | No |
+| `/api/*` | `handle_path` | `api:8000` | Yes (`/api` stripped) |
+| `/mcp/*` | `handle_path` | `mcp-gateway:8001` | Yes (`/mcp` stripped) |
+| `/_temporal*` | `handle` + `basic_auth` | `temporal-ui:8080` | No |
+| `/grafana/*` | `handle` + `basic_auth` | `grafana:3000` | No |
+| everything else | `handle` (catch-all) | `web:3000` | No |
+
+The one deliberate addition: **`/ws` and `/ws/spec/{spec_id}`** (the board-push
+and CRDT spec-co-editing websocket channels, `forge_api.routers.realtime`)
+mount at the API app root, not under `/api` (see
+[architecture.md](../architecture.md#trust-layer--provenance)). The Caddyfile
+has no dedicated `handle` block for either path today, so without one both
+would silently fall through to the catch-all `web:3000` route — wrong, since
+neither socket exists on the frontend. `forge.conf` routes them to `api:8000`
+explicitly; the same gap is worth closing in the Caddyfile too (flagged, not
+fixed here — out of this change's scope).
+
+### Websocket and streaming requirements
+
+- **Upgrade headers.** `/ws` and `/ws/spec/*` set `proxy_http_version 1.1`,
+  `Upgrade`, and `Connection: upgrade` (via the standard `map $http_upgrade
+  $connection_upgrade` recipe) — Caddy does this automatically, nginx does not.
+- **Timeouts.** nginx's default `proxy_read_timeout`/`proxy_send_timeout` is
+  60s, which would kill an idle websocket or a slow-trickling stream; Caddy
+  has no such default. `forge.conf` sets both to `3600s` on the websocket and
+  `/api/` locations — matching the `sseReadTimeout` this repo's Kubernetes
+  ingress already uses for the same reason (`deploy/helm/forge/values.yaml`).
+- **Buffering.** nginx buffers proxied responses (and, separately, request
+  bodies) by default; Caddy streams both by default. `forge.conf` sets
+  `proxy_buffering off` on `/api/` (it carries the NDJSON audit-export stream,
+  `forge_api.routers.audit`) and `proxy_request_buffering off` on the two
+  webhook routes, where request-body buffering would be actively harmful:
+  alert/PM webhook signatures are HMAC'd over the exact raw body, and a
+  buffering proxy that rewrites or re-chunks it breaks verification.
+- **DNS.** Caddy resolves each upstream hostname lazily, per request, so
+  Compose's non-deterministic service start order never matters. A static
+  nginx `upstream {}` block resolves once at startup and fails hard
+  (`nginx: [emerg] host not found in upstream`) if that name isn't up yet.
+  `forge.conf` works around this with `resolver 127.0.0.11` (Docker's embedded
+  DNS, present on every container on a user-defined/Compose network) plus a
+  `set $upstream_x http://service:port;` + variable `proxy_pass` on every
+  location, which defers resolution to request time.
+
+### Known gaps vs. Caddy
+
+- **TLS is not automatic.** Caddy's ACME integration has no nginx equivalent
+  in this file. Run certbot/acme.sh alongside nginx, or terminate TLS
+  upstream of it, and uncomment the `listen 443 ssl; ssl_certificate ...;`
+  block in `forge.conf`.
+- **`zstd` compression.** The Caddyfile does `encode gzip zstd`; stock nginx
+  ships gzip only (no zstd module compiled in), so `forge.conf` only does
+  gzip.
+- **Removing the `Server` header.** Caddy's `-Server` in its `header` block
+  strips the header outright. Stock nginx has no directive to do that (it
+  needs the third-party `headers-more` module); `server_tokens off` is the
+  closest built-in equivalent — it hides the version but the bare `nginx`
+  token stays.
+- **Basic-auth credentials aren't environment-driven.** Caddy reads
+  `TEMPORAL_UI_BASIC_AUTH`/`GRAFANA_BASIC_AUTH` bcrypt hashes from env vars,
+  defaulting to a hash that accepts nothing. nginx's `auth_basic_user_file`
+  needs a real htpasswd file on disk; `forge.conf` points at
+  `/etc/nginx/secrets/{temporal,grafana}.htpasswd`, which don't exist until
+  you create them, so both routes fail closed (401 for everyone) the same way
+  Caddy's dummy hash does. Generate one with:
+
+  ```bash
+  htpasswd -c /etc/nginx/secrets/grafana.htpasswd admin
+  ```
+
+- **Network reachability (pre-existing, not introduced by this file):**
+  `docker-compose.yml`'s `mcp-gateway` service is only on the `backend` and
+  `mcp` networks — not `edge`, the network the `caddy` service (and any
+  drop-in nginx replacement) is on. As shipped, neither proxy can actually
+  reach `mcp-gateway:8001` for the `/mcp/*` route without also adding the edge
+  proxy container to the `mcp` network. This is a `docker-compose.yml`
+  topology question, out of scope for this doc/config (only `forge.conf`,
+  this file, and a `quickstart.md` link were in scope) — flag it before
+  relying on `/mcp/*` in production with either proxy.
+
+### Health checks
+
+The edge proxy itself doesn't need a dedicated health-check route: Docker
+Compose's `api`/`mcp-gateway`/`web` healthchecks all probe each container
+directly (`/health/ready`, `/health`, `/` respectively — see
+[docker-compose.md](docker-compose.md)), bypassing the proxy entirely. The
+API's own liveness/readiness endpoints (`/health`, `/healthz`, `/readyz`,
+`/health/ready`) are mounted at the API app root, same as `/ws`; reachable
+through either proxy only via `/api/health` etc. (under the `/api/*` surface),
+not bare `/health` — the Caddyfile doesn't expose the bare paths externally
+either, so `forge.conf` doesn't add that.
+
+### Switching to it
+
+```yaml
+# deploy/docker-compose.yml — replace the `caddy` service's image/volumes
+caddy:
+  image: nginx:1.27-alpine
+  volumes:
+    - ./nginx/forge.conf:/etc/nginx/conf.d/forge.conf:ro
+    - ./nginx/secrets:/etc/nginx/secrets:ro   # htpasswd files, see above
+    # Remove or override the image's own conf.d/default.conf too — it also
+    # `listen`s on 80 and will otherwise shadow forge.conf as the default
+    # server for that port.
+```
+
+Validate the syntax before rolling it out:
+
+```bash
+docker run --rm -v "$PWD/deploy/nginx/forge.conf:/etc/nginx/conf.d/forge.conf:ro" nginx:alpine nginx -t
+```
+
+This checks config syntax and routing logic only (see `forge.conf`'s header
+comment for exactly what was and wasn't exercised) — it does not stand up the
+real Forge services, so it can't catch things like the network-reachability
+gap noted above. Confirm end-to-end behavior against a running stack before
+trusting either proxy in production.

From 30e9b56e72ee5f4482be1e7892bc5d44890e51f0 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:51:50 +0200
Subject: [PATCH 11/47] fix(deploy): nginx body-size and websocket-upgrade
 parity with Caddy

---
 deploy/nginx/forge.conf            | 26 ++++++++++++++++++++++++++
 docs/self-hosting/reverse-proxy.md | 18 +++++++++++++++---
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/deploy/nginx/forge.conf b/deploy/nginx/forge.conf
index 267da0ec..98e9ffa2 100644
--- a/deploy/nginx/forge.conf
+++ b/deploy/nginx/forge.conf
@@ -52,6 +52,14 @@ server {
     # container on a user-defined network (i.e. any Compose network here).
     resolver 127.0.0.11 valid=10s;
 
+    # Caddy's `reverse_proxy` imposes no request body size cap at all. Stock
+    # nginx defaults `client_max_body_size` to 1m, which would silently 413
+    # any >1 MB webhook/API payload Caddy would otherwise have passed through
+    # untouched. Set an explicit, generous cap here instead of relying on the
+    # default; tune this for your actual max payload (largest legitimate
+    # request this edge should ever see).
+    client_max_body_size 50m;
+
     # --- TLS (commented out; see docs/self-hosting/reverse-proxy.md) --------
     # Caddyfile's top-level `{ email {$ACME_EMAIL:admin@localhost} }` block
     # plus the `{$DOMAIN:localhost} { ... }` site block get Caddy automatic
@@ -101,6 +109,7 @@ server {
         # used for the general /api/* surface below).
         set $upstream_api http://api:8000;
         proxy_pass $upstream_api;
+        proxy_http_version 1.1;
         proxy_request_buffering off;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -111,6 +120,7 @@ server {
     location ^~ /api/v1/integrations/pm/webhooks/ {
         set $upstream_api http://api:8000;
         proxy_pass $upstream_api;
+        proxy_http_version 1.1;
         proxy_request_buffering off;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
@@ -123,6 +133,7 @@ server {
     location /public/ {
         set $upstream_api http://api:8000;
         proxy_pass $upstream_api;
+        proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -215,11 +226,19 @@ server {
     # an operator creates one, so this route 401s for everyone out of the box
     # (fails closed the same way). Generate credentials with:
     #   htpasswd -c /etc/nginx/secrets/temporal.htpasswd admin
+    #
+    # Caddy auto-detects the `Upgrade` header on every route, including this
+    # one, so it never needed a separate websocket carve-out here. nginx
+    # doesn't, so this location gets the same `proxy_http_version 1.1` +
+    # `map $connection_upgrade` recipe used on the /ws locations above.
     location /_temporal {
         auth_basic "Forge Temporal UI";
         auth_basic_user_file /etc/nginx/secrets/temporal.htpasswd;
         set $upstream_temporal_ui http://temporal-ui:8080;
         proxy_pass $upstream_temporal_ui;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -231,11 +250,18 @@ server {
     # GF_SERVER_SERVE_FROM_SUB_PATH, so it must see the /grafana prefix; do
     # not strip it here either. Basic-auth locked by default, same pattern as
     # /_temporal above (in addition to Grafana's own admin login).
+    #
+    # Grafana Live (`/grafana/api/live/ws`) needs a real websocket upgrade,
+    # same as /_temporal above: Caddy auto-detects `Upgrade` on any route,
+    # nginx needs it spelled out per-location.
     location /grafana/ {
         auth_basic "Forge Grafana";
         auth_basic_user_file /etc/nginx/secrets/grafana.htpasswd;
         set $upstream_grafana http://grafana:3000;
         proxy_pass $upstream_grafana;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
index 509836c9..67fed453 100644
--- a/docs/self-hosting/reverse-proxy.md
+++ b/docs/self-hosting/reverse-proxy.md
@@ -56,9 +56,15 @@ fixed here — out of this change's scope).
 
 ### Websocket and streaming requirements
 
-- **Upgrade headers.** `/ws` and `/ws/spec/*` set `proxy_http_version 1.1`,
-  `Upgrade`, and `Connection: upgrade` (via the standard `map $http_upgrade
-  $connection_upgrade` recipe) — Caddy does this automatically, nginx does not.
+- **Upgrade headers.** `/ws`, `/ws/spec/*`, `/_temporal`, and `/grafana/` all
+  set `proxy_http_version 1.1`, `Upgrade`, and `Connection: upgrade` (via the
+  standard `map $http_upgrade $connection_upgrade` recipe) — Caddy does this
+  automatically on every route (including Grafana Live's `/grafana/api/live/ws`),
+  nginx does not, so each location that might carry a websocket needs it
+  spelled out explicitly. The remaining locations (`/public/`, the two webhook
+  routes, `/api/`, `/mcp/`, the catch-all) also set `proxy_http_version 1.1`
+  for consistency, even though none of them carry an upgradeable connection
+  today.
 - **Timeouts.** nginx's default `proxy_read_timeout`/`proxy_send_timeout` is
   60s, which would kill an idle websocket or a slow-trickling stream; Caddy
   has no such default. `forge.conf` sets both to `3600s` on the websocket and
@@ -82,6 +88,12 @@ fixed here — out of this change's scope).
 
 ### Known gaps vs. Caddy
 
+- **Request body size cap.** Caddy's `reverse_proxy` imposes no `client_max_body_size`
+  equivalent — request bodies of any size pass through uncapped. Stock nginx
+  defaults `client_max_body_size` to 1m, which would silently 413 any >1 MB
+  webhook/API payload Caddy would have let through. `forge.conf` sets an
+  explicit `client_max_body_size 50m;` at the `server` level instead of
+  relying on the 1m default; tune it for your actual max payload.
 - **TLS is not automatic.** Caddy's ACME integration has no nginx equivalent
   in this file. Run certbot/acme.sh alongside nginx, or terminate TLS
   upstream of it, and uncomment the `listen 443 ssl; ssl_certificate ...;`

From 7f70154aaa3db082fa95ce8fe5f95485db289e5e Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Mon, 20 Jul 2026 23:58:17 +0200
Subject: [PATCH 12/47] docs(spec): realign FORGE_SPEC with shipped reality

---
 docs/FORGE_SPEC.md | 72 +++++++++++++++++++++++++++++++++++++---------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/docs/FORGE_SPEC.md b/docs/FORGE_SPEC.md
index 65cd0bae..87bb8113 100644
--- a/docs/FORGE_SPEC.md
+++ b/docs/FORGE_SPEC.md
@@ -187,7 +187,15 @@ forge/
 │   ├── policy-sdk/               # Repo policy loading, permission evaluation
 │   ├── skill-sdk/                # Skill profiles, workflow behavior injection
 │   ├── evaluation/               # Golden test set, RAGAS metrics, quality harness
-│   └── ui-kit/                   # Shared React components, design tokens
+│   ├── contracts/                # Shared DTOs/schemas used across services
+│   ├── db/                       # SQLAlchemy models, migrations, repositories
+│   ├── auth-sdk/                 # Auth/session primitives (BYOK, OAuth, API keys)
+│   ├── authz-sdk/                # RBAC/permission evaluation
+│   ├── approval-sdk/             # Human approval gate primitives
+│   ├── orchestration-policy/     # Workflow/orchestration policy evaluation
+│   ├── deploy-core/              # Deployment/environment-promotion domain logic
+│   ├── observability/            # Run traces, audit log, attestations, metrics
+│   └── marketplace-sdk/          # Integration/skill-profile marketplace primitives
 ├── docs/
 │   ├── self-hosting/             # quickstart, docker-compose, kubernetes, backup, upgrade
 │   ├── architecture/             # ADRs, service boundaries, data model
@@ -274,15 +282,35 @@ WorkflowRun
 
 ### SDD Lifecycle
 
-| Phase | CLI Action | Output | Gate |
-|---|---|---|---|
-| Constitution | `forge constitution init` | Engineering principles, arch guardrails | Human review |
-| Specify | `forge spec create` | Requirements, user journeys, acceptance criteria | Human approval |
-| Clarify | `forge spec clarify` | Resolved open questions | Human sign-off |
-| Plan | `forge spec plan` | Architecture, data model, interfaces, ADRs | Human approval |
-| Tasks | `forge spec tasks` | Phased implementation units | Auto-generated; human editable |
-| Implement | `forge run <task-id>` | Code, tests, PRs | Spec-gated |
-| Validate | `forge validate <task-id>` | Requirement-to-test traceability | Required before merge |
+> **Shipped reality:** the `forge` command surface in the table below
+> (`forge constitution init`, `forge spec create`, etc.) is a **roadmap**
+> command-line wrapper — it does not exist yet (see
+> [Phased Roadmap](#phased-roadmap)). Today the lifecycle ships **API/web-first**:
+> every phase is a live endpoint on the spec router
+> (`apps/api/forge_api/routers/spec.py`) driven from the web UI, plus an agent
+> run endpoint (`apps/api/forge_api/routers/agent.py`) for Implement. The
+> "CLI Action" column names the logical action; the "Shipped As" column is
+> what actually runs it today.
+>
+> Two SDD-adjacent console scripts do ship as real CLI entry points from
+> `apps/api/pyproject.toml`: `forge-verify` (offline attestation/audit-chain
+> verification) and `forge-replay` (Time-Travel Runs replay-and-diff) — see
+> [trust layer](./trust-layer.md). `forge bench` and `forge marketplace` also
+> exist as installed CLIs, but only their offline subcommands work standalone
+> (`bench freeze/hash/verify`, `marketplace package`); their `run`/`submit`/
+> `leaderboard` and `search`/`show`/`list`/`install`/`update` subcommands are
+> **parked stubs** that print `PARKED ... use the HTTP API or web UI` and exit
+> non-zero (`apps/api/forge_api/cli_bench.py`, `cli_marketplace.py`).
+
+| Phase | CLI Action (roadmap) | Shipped As | Output | Gate |
+|---|---|---|---|---|
+| Constitution | `forge constitution init` | `POST /spec/constitution` | Engineering principles, arch guardrails | Human review |
+| Specify | `forge spec create` | `POST /spec/specs` | Requirements, user journeys, acceptance criteria | Human approval |
+| Clarify | `forge spec clarify` | `POST /spec/specs/{id}/clarify` | Resolved open questions | Human sign-off |
+| Plan | `forge spec plan` | `POST /spec/specs/{id}/plan` | Architecture, data model, interfaces, ADRs | Human approval |
+| Tasks | `forge spec tasks` | `POST /spec/specs/{id}/tasks` | Phased implementation units | Auto-generated; human editable |
+| Implement | `forge run <task-id>` | `POST /agent/runs` | Code, tests, PRs | Spec-gated |
+| Validate | `forge validate <task-id>` | `POST /spec/tasks/{id}/validate` | Requirement-to-test traceability | Required before merge |
 
 ### Spec Folder Layout
 
@@ -893,6 +921,10 @@ docs/self-hosting/ must include:
 - security.md (hardening, credential rotation, network policies)
 - troubleshooting.md (common errors and fixes)
 
+**Shipped:** all nine files above exist in `docs/self-hosting/`.
+`reverse-proxy.md` documents both Caddy and the nginx alternative
+(`deploy/nginx/forge.conf`) side by side.
+
 ---
 
 ## Integrations
@@ -1008,6 +1040,7 @@ Cost: token cost per task, per workflow phase, per model provider.
 - [ ] Kubernetes Helm chart
 - [ ] Temporal workflow engine integration
 - [ ] Sprint management and velocity dashboards
+- [ ] Full `forge` CLI (`forge constitution init`, `forge spec create/clarify/plan/tasks`, `forge run`, `forge validate`) as a local command-line wrapper over the already-shipped API/web SDD lifecycle (see [SDD Lifecycle](#sdd-lifecycle))
 
 ### Phase 3 — Scale (V3)
 
@@ -1016,10 +1049,21 @@ Cost: token cost per task, per workflow phase, per model provider.
 - [ ] Advanced policy engine with conditional rules
 - [ ] Multi-team workspace controls and full RBAC hierarchy
 - [ ] Deployment gates and environment promotion workflows
-- [ ] Integration marketplace for community MCP connectors and skill profiles
-- [ ] Enterprise SSO (SAML, SCIM)
-- [ ] Firecracker / gVisor sandbox isolation
-- [ ] Benchmark suite and public evaluation leaderboard
+- [x] Integration marketplace for community MCP connectors and skill profiles — **shipped early** (PR #57; `packages/marketplace-sdk/`, `apps/web` marketplace screens); `forge marketplace search/show/list/install/update` remain parked CLI stubs pending a live registry
+- [x] Enterprise SSO (SAML, SCIM) — **shipped early**, plus OIDC (PR #57; `apps/api/forge_api/sso/`, `routers/oidc.py`, `routers/saml.py`, `routers/scim.py`)
+- [x] Firecracker / gVisor sandbox isolation — **shipped early** (F34; `packages/agent-runtime/forge_agent/sandbox/microvm.py`, `sandbox/gvisor.py`, Helm `runtimeclass-kata-fc`/`runtimeclass-gvisor` templates)
+- [x] Benchmark suite and public evaluation leaderboard — **shipped early** (PR #57/F35; `apps/web` leaderboard screen, benchmarks API); `forge bench run/submit/leaderboard` remain parked CLI stubs
+
+### Trust Layer — Shipped Ahead of Roadmap
+
+Not scoped in any phase above when this spec was first written; shipped as
+the platform's category-defining differentiator (PRs #61-#64). See
+[docs/trust-layer.md](./trust-layer.md) for the full write-up.
+
+- [x] Attested Changesets — DSSE-signed in-toto provenance over every changeset (PR #61)
+- [x] Time-Travel Runs — deterministic record-replay (and counterfactual fork) of an agent run (PR #62)
+- [x] Red-Team Gate — a heterogeneous adversary must fail to break the change in-sandbox before the human gate (PR #63)
+- [x] Self-Eval Gate — blocks a config change that regresses a workspace's private per-repo evaluation suite (PR #64)
 
 ---
 

From 6a7c820a1f1cb491a8e65806366023aed8e0e0f3 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:02:32 +0200
Subject: [PATCH 13/47] docs(spec): correct F32/F33 shipping attributions in
 roadmap

---
 docs/FORGE_SPEC.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/FORGE_SPEC.md b/docs/FORGE_SPEC.md
index 87bb8113..182fae30 100644
--- a/docs/FORGE_SPEC.md
+++ b/docs/FORGE_SPEC.md
@@ -1049,8 +1049,8 @@ Cost: token cost per task, per workflow phase, per model provider.
 - [ ] Advanced policy engine with conditional rules
 - [ ] Multi-team workspace controls and full RBAC hierarchy
 - [ ] Deployment gates and environment promotion workflows
-- [x] Integration marketplace for community MCP connectors and skill profiles — **shipped early** (PR #57; `packages/marketplace-sdk/`, `apps/web` marketplace screens); `forge marketplace search/show/list/install/update` remain parked CLI stubs pending a live registry
-- [x] Enterprise SSO (SAML, SCIM) — **shipped early**, plus OIDC (PR #57; `apps/api/forge_api/sso/`, `routers/oidc.py`, `routers/saml.py`, `routers/scim.py`)
+- [x] Integration marketplace for community MCP connectors and skill profiles — **shipped early** (F32; `packages/marketplace-sdk/`, `apps/web` marketplace screens), in-app publish flow (PR #57); `forge marketplace search/show/list/install/update` remain parked CLI stubs pending a live registry
+- [x] Enterprise SSO (SAML, SCIM) — **shipped early** (F33; `apps/api/forge_api/sso/`, `routers/saml.py`, `routers/scim.py`), plus OIDC (PR #57; `routers/oidc.py`)
 - [x] Firecracker / gVisor sandbox isolation — **shipped early** (F34; `packages/agent-runtime/forge_agent/sandbox/microvm.py`, `sandbox/gvisor.py`, Helm `runtimeclass-kata-fc`/`runtimeclass-gvisor` templates)
 - [x] Benchmark suite and public evaluation leaderboard — **shipped early** (PR #57/F35; `apps/web` leaderboard screen, benchmarks API); `forge bench run/submit/leaderboard` remain parked CLI stubs
 

From 4bf2478593ef1d967557c98c4d2c8c3a5adf66b5 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:06:25 +0200
Subject: [PATCH 14/47] ci(web): run vitest suite and tsc typecheck on every PR

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 66d2a1e5..bdf15c89 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -241,7 +241,7 @@ jobs:
         run: uv run pytest -m live_slack -q
 
   web:
-    name: web (lint + build)
+    name: web (lint + types + tests + build)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -263,6 +263,16 @@ jobs:
       - name: Lint
         run: pnpm -r lint
 
+      # The web package ships 89 vitest files and a `tsc --noEmit` typecheck that
+      # previously only ran in the (unreachable) release workflow. Gate both on
+      # every PR/push, after lint and before build, so a type error or a broken
+      # component test blocks the merge instead of shipping.
+      - name: Type-check (tsc)
+        run: pnpm --filter @forge/web typecheck
+
+      - name: Test (vitest)
+        run: pnpm --filter @forge/web test
+
       - name: Build
         run: pnpm -r build
 

From 73676f6b1a79e3080be4a0ef8adb6066427c421e Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:23:46 +0200
Subject: [PATCH 15/47] ci(types): bring deploy-core, auth-sdk,
 marketplace-sdk, observability under mypy

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 Makefile                                      |  3 +-
 packages/auth-sdk/forge_auth/py.typed         |  0
 .../deploy-core/forge_deploy/orchestrator.py  |  4 ++-
 .../deploy-core/forge_deploy/providers.py     |  4 +--
 packages/deploy-core/forge_deploy/schemas.py  |  7 +++-
 .../forge_marketplace/catalog.py              |  6 +++-
 .../forge_obs/analytics/budgets.py            | 10 ++++--
 .../forge_obs/analytics/coverage.py           | 10 ++++--
 .../observability/forge_obs/analytics/dora.py | 34 ++++++++++++++-----
 .../observability/forge_obs/analytics/fx.py   |  7 ++--
 .../forge_obs/analytics/incidents.py          |  7 ++--
 .../forge_obs/analytics/skill_snapshot.py     | 13 ++++---
 .../observability/forge_obs/cost/meter.py     |  3 +-
 .../observability/forge_obs/cost/models.py    | 10 +++++-
 .../observability/forge_obs/cost/pricing.py   |  7 ++--
 .../forge_obs/cost/repository.py              | 14 +++++---
 packages/observability/forge_obs/metrics.py   |  7 ++--
 17 files changed, 107 insertions(+), 39 deletions(-)
 create mode 100644 packages/auth-sdk/forge_auth/py.typed

diff --git a/Makefile b/Makefile
index 5a1e4ede..e595ad4b 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,8 @@ MYPY_PACKAGES := \
 	forge_contracts forge_db forge_workflow forge_agent forge_coordinator \
 	forge_spec forge_board forge_knowledge forge_integrations forge_mcp \
 	forge_policy forge_authz forge_skill forge_eval forge_approval forge_api \
-	forge_worker forge_mcp_gateway forge_orchestration_policy
+	forge_worker forge_mcp_gateway forge_orchestration_policy \
+	forge_deploy forge_auth forge_marketplace forge_obs
 
 help: ## Show available targets
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
diff --git a/packages/auth-sdk/forge_auth/py.typed b/packages/auth-sdk/forge_auth/py.typed
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/deploy-core/forge_deploy/orchestrator.py b/packages/deploy-core/forge_deploy/orchestrator.py
index 4d7e2323..f871470c 100644
--- a/packages/deploy-core/forge_deploy/orchestrator.py
+++ b/packages/deploy-core/forge_deploy/orchestrator.py
@@ -12,6 +12,8 @@
 import uuid
 from collections.abc import Callable
 
+from sqlalchemy.orm import Session
+
 from forge_db.models.deployment import Deployment, Environment
 from forge_deploy.engine import DeploymentStateMachine
 from forge_deploy.freeze import Clock, SystemClock
@@ -53,7 +55,7 @@ def _default_health_resolver(config: dict) -> HealthChecker:
 class DeploymentOrchestrator:
     def __init__(
         self,
-        session,
+        session: Session,
         *,
         workspace_id: uuid.UUID,
         engine: DeploymentStateMachine | None = None,
diff --git a/packages/deploy-core/forge_deploy/providers.py b/packages/deploy-core/forge_deploy/providers.py
index 0a9a8c34..ecd1b0f2 100644
--- a/packages/deploy-core/forge_deploy/providers.py
+++ b/packages/deploy-core/forge_deploy/providers.py
@@ -14,7 +14,7 @@
 from typing import Any, Protocol, runtime_checkable
 
 from forge_deploy.errors import ProviderError
-from forge_deploy.schemas import DeployHandle, DeployRequest, DeployStatus
+from forge_deploy.schemas import DeployHandle, DeployRequest, DeployState, DeployStatus
 
 
 @runtime_checkable
@@ -51,7 +51,7 @@ def post(
     ) -> dict[str, Any]: ...
 
 
-_GITHUB_STATE_MAP = {
+_GITHUB_STATE_MAP: dict[str, DeployState] = {
     "queued": "pending",
     "pending": "pending",
     "in_progress": "in_progress",
diff --git a/packages/deploy-core/forge_deploy/schemas.py b/packages/deploy-core/forge_deploy/schemas.py
index cccbd863..92eb23ca 100644
--- a/packages/deploy-core/forge_deploy/schemas.py
+++ b/packages/deploy-core/forge_deploy/schemas.py
@@ -137,8 +137,12 @@ class DeployHandle(BaseModel):
     url: str | None = None
 
 
+#: The lifecycle states a provider can report for a deployment.
+DeployState = Literal["pending", "in_progress", "success", "failure", "error"]
+
+
 class DeployStatus(BaseModel):
-    state: Literal["pending", "in_progress", "success", "failure", "error"]
+    state: DeployState
     detail: str | None = None
     finished: bool = False
 
@@ -154,6 +158,7 @@ class HealthCheckResult(BaseModel):
     "DeployHandle",
     "DeployProviderConfig",
     "DeployRequest",
+    "DeployState",
     "DeployStatus",
     "EnvironmentSpec",
     "FreezeWindow",
diff --git a/packages/marketplace-sdk/forge_marketplace/catalog.py b/packages/marketplace-sdk/forge_marketplace/catalog.py
index 5459bd5c..b2a713f6 100644
--- a/packages/marketplace-sdk/forge_marketplace/catalog.py
+++ b/packages/marketplace-sdk/forge_marketplace/catalog.py
@@ -100,7 +100,11 @@ def compatible_versions(
 
 def sort_versions(versions: list[RegistryIndexVersion]) -> list[RegistryIndexVersion]:
     """Return ``versions`` sorted ascending by semver precedence."""
-    return sorted(versions, key=cmp_to_key(lambda a, b: compare_semver(a.version, b.version)))
+
+    def _by_precedence(a: RegistryIndexVersion, b: RegistryIndexVersion) -> int:
+        return compare_semver(a.version, b.version)
+
+    return sorted(versions, key=cmp_to_key(_by_precedence))
 
 
 def latest_compatible(
diff --git a/packages/observability/forge_obs/analytics/budgets.py b/packages/observability/forge_obs/analytics/budgets.py
index 80138466..a520b70e 100644
--- a/packages/observability/forge_obs/analytics/budgets.py
+++ b/packages/observability/forge_obs/analytics/budgets.py
@@ -12,12 +12,18 @@
 
 from datetime import datetime
 from decimal import Decimal
+from typing import TYPE_CHECKING
 from uuid import UUID
 
 from pydantic import BaseModel
 
 from forge_obs.analytics.fx import FxRateBook, convert
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
+    from forge_db.models.obs_analytics import Budget as BudgetRow
+
 __all__ = ["Budget", "BudgetStatus", "SqlBudgetReader", "evaluate_budget"]
 
 
@@ -95,10 +101,10 @@ def evaluate_budget(
 class SqlBudgetReader:
     """List/get ``budget`` rows for a workspace."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
-    def _dto(self, row) -> Budget:
+    def _dto(self, row: BudgetRow) -> Budget:
         return Budget(
             id=row.id,
             workspace_id=row.workspace_id,
diff --git a/packages/observability/forge_obs/analytics/coverage.py b/packages/observability/forge_obs/analytics/coverage.py
index 1115c4b8..2e87eb15 100644
--- a/packages/observability/forge_obs/analytics/coverage.py
+++ b/packages/observability/forge_obs/analytics/coverage.py
@@ -10,10 +10,16 @@
 
 from collections.abc import Sequence
 from datetime import date
+from typing import TYPE_CHECKING
 from uuid import UUID
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
+    from forge_db.models.obs_analytics import CoverageSnapshot
+
 __all__ = [
     "CoverageSnapshotDTO",
     "CoverageTrendPoint",
@@ -53,11 +59,11 @@ class CoverageTrendPoint(BaseModel):
 class SqlCoverageRepository:
     """Recompute-and-upsert + trend/rollup reads over ``coverage_snapshot``."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     @staticmethod
-    def _dto(row) -> CoverageSnapshotDTO:
+    def _dto(row: CoverageSnapshot) -> CoverageSnapshotDTO:
         return CoverageSnapshotDTO(
             id=row.id,
             project_id=row.project_id,
diff --git a/packages/observability/forge_obs/analytics/dora.py b/packages/observability/forge_obs/analytics/dora.py
index 4d19be35..93ccfcc9 100644
--- a/packages/observability/forge_obs/analytics/dora.py
+++ b/packages/observability/forge_obs/analytics/dora.py
@@ -14,11 +14,14 @@
 
 from collections.abc import Iterable, Sequence
 from datetime import datetime
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from uuid import UUID
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
 __all__ = ["DeploymentLike", "DoraMetrics", "SqlDoraReader", "compute_dora_metrics"]
 
 #: Deployment states counted as a completed (terminal) promotion attempt.
@@ -31,14 +34,27 @@
 
 @runtime_checkable
 class DeploymentLike(Protocol):
-    """The subset of ``deployment`` columns the DORA aggregation reads."""
+    """The subset of ``deployment`` columns the DORA aggregation reads.
+
+    Members are read-only (properties) rather than settable attributes: the ORM
+    ``deployment`` row types ``state``/``kind`` as ``StrEnum`` (a subclass of
+    ``str``), and a settable ``str`` protocol attribute is invariant and would
+    reject them. The aggregation only ever reads these fields, so a covariant
+    read-only view is both correct and accepts the enum-typed columns.
+    """
 
-    environment_name: str
-    state: str
-    kind: str
-    requested_at: datetime | None
-    started_at: datetime | None
-    finished_at: datetime | None
+    @property
+    def environment_name(self) -> str: ...
+    @property
+    def state(self) -> str: ...
+    @property
+    def kind(self) -> str: ...
+    @property
+    def requested_at(self) -> datetime | None: ...
+    @property
+    def started_at(self) -> datetime | None: ...
+    @property
+    def finished_at(self) -> datetime | None: ...
 
 
 class DoraMetrics(BaseModel):
@@ -114,7 +130,7 @@ def compute_dora_metrics(
 class SqlDoraReader:
     """Workspace-scoped DORA rollup over the real ``deployment`` table."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     def dora_metrics(
diff --git a/packages/observability/forge_obs/analytics/fx.py b/packages/observability/forge_obs/analytics/fx.py
index c7cdf4c7..2192b197 100644
--- a/packages/observability/forge_obs/analytics/fx.py
+++ b/packages/observability/forge_obs/analytics/fx.py
@@ -11,11 +11,14 @@
 
 from datetime import datetime
 from decimal import Decimal
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from uuid import UUID
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
 __all__ = ["DbFxRateBook", "FxRate", "FxRateBook", "InMemoryFxRateBook", "convert"]
 
 
@@ -78,7 +81,7 @@ def resolve(self, *, base: str, quote: str, at: datetime) -> Decimal | None:
 class DbFxRateBook:
     """FX rate book over the real ``fx_rate`` table."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     def resolve(self, *, base: str, quote: str, at: datetime) -> Decimal | None:
diff --git a/packages/observability/forge_obs/analytics/incidents.py b/packages/observability/forge_obs/analytics/incidents.py
index 9195b13a..df8d531b 100644
--- a/packages/observability/forge_obs/analytics/incidents.py
+++ b/packages/observability/forge_obs/analytics/incidents.py
@@ -15,11 +15,14 @@
 
 from collections.abc import Iterable, Sequence
 from datetime import datetime
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from uuid import UUID
 
 from pydantic import BaseModel
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
 __all__ = [
     "IncidentLike",
     "IncidentReliabilityMetrics",
@@ -103,7 +106,7 @@ def compute_incident_reliability(
 class SqlIncidentReliabilityReader:
     """Workspace-scoped reliability rollup over ``incident``/``remediation_plan``."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     def reliability(
diff --git a/packages/observability/forge_obs/analytics/skill_snapshot.py b/packages/observability/forge_obs/analytics/skill_snapshot.py
index f5cd5091..2c0c922c 100644
--- a/packages/observability/forge_obs/analytics/skill_snapshot.py
+++ b/packages/observability/forge_obs/analytics/skill_snapshot.py
@@ -11,13 +11,18 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
 from pydantic import BaseModel
 
 from forge_contracts import SkillProfile
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
+    from forge_db.models.obs_analytics import SkillProfileSnapshot
+
 __all__ = [
     "SkillProfileSnapshotDTO",
     "SqlSkillProfileSnapshotRepository",
@@ -62,11 +67,11 @@ class SqlSkillProfileSnapshotRepository:
     "record the snapshot for this run" call must be a safe no-op, not a crash.
     """
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     @staticmethod
-    def _dto(row) -> SkillProfileSnapshotDTO:
+    def _dto(row: SkillProfileSnapshot) -> SkillProfileSnapshotDTO:
         return SkillProfileSnapshotDTO(
             id=row.id,
             workspace_id=row.workspace_id,
@@ -85,7 +90,7 @@ def record(
 
         from forge_db.models.obs_analytics import SkillProfileSnapshot
 
-        def _existing(session) -> SkillProfileSnapshotDTO | None:
+        def _existing(session: Session) -> SkillProfileSnapshotDTO | None:
             row = session.scalars(
                 select(SkillProfileSnapshot).where(
                     SkillProfileSnapshot.agent_run_id == agent_run_id
diff --git a/packages/observability/forge_obs/cost/meter.py b/packages/observability/forge_obs/cost/meter.py
index 63d037b6..ec960d2f 100644
--- a/packages/observability/forge_obs/cost/meter.py
+++ b/packages/observability/forge_obs/cost/meter.py
@@ -14,6 +14,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Callable
 
 from forge_obs.cost.models import COST_KINDS, CostRecord, ModelUsage
 from forge_obs.cost.pricing import PriceBook, compute_cost
@@ -90,7 +91,7 @@ def record(self, usage: ModelUsage) -> CostRecord:
             )
         return record
 
-    def _safe(self, emit) -> None:
+    def _safe(self, emit: Callable[[ForgeMetrics], object]) -> None:
         """Metric export must never break cost emission (spec AC7)."""
         try:
             emit(self._facade)
diff --git a/packages/observability/forge_obs/cost/models.py b/packages/observability/forge_obs/cost/models.py
index 319cef64..422392f0 100644
--- a/packages/observability/forge_obs/cost/models.py
+++ b/packages/observability/forge_obs/cost/models.py
@@ -101,7 +101,15 @@ class CostSummary(BaseModel):
     total_completion_tokens: int = 0
     group_by: str = "none"  # phase | provider | model | none
     buckets: list[CostBucket] = Field(default_factory=list)
-    from_: datetime | None = Field(default=None, alias="from")
+    # ``from`` is a Python keyword, so the attribute is ``from_``. Using
+    # ``validation_alias``/``serialization_alias`` (rather than ``alias``) keeps
+    # the wire key ``from`` on both read and write while letting the synthesized
+    # ``__init__`` use the real field name — so ``CostSummary(from_=...)`` is
+    # both valid Python and type-checks. ``populate_by_name`` still accepts the
+    # ``from`` key on validation, so behaviour is unchanged.
+    from_: datetime | None = Field(
+        default=None, validation_alias="from", serialization_alias="from"
+    )
     to: datetime | None = None
 
 
diff --git a/packages/observability/forge_obs/cost/pricing.py b/packages/observability/forge_obs/cost/pricing.py
index f3c1dbff..6bb3721f 100644
--- a/packages/observability/forge_obs/cost/pricing.py
+++ b/packages/observability/forge_obs/cost/pricing.py
@@ -12,11 +12,14 @@
 
 from datetime import datetime
 from decimal import ROUND_HALF_UP, Decimal
-from typing import Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from uuid import UUID
 
 from forge_obs.cost.models import ModelPrice, ModelUsage
 
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
 __all__ = ["DbPriceBook", "InMemoryPriceBook", "PriceBook", "compute_cost"]
 
 _ONE_K = Decimal(1000)
@@ -89,7 +92,7 @@ def resolve(
 class DbPriceBook:
     """Price book over the durable ``model_price`` table (forge_db)."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     def resolve(
diff --git a/packages/observability/forge_obs/cost/repository.py b/packages/observability/forge_obs/cost/repository.py
index 41a2344d..979798e8 100644
--- a/packages/observability/forge_obs/cost/repository.py
+++ b/packages/observability/forge_obs/cost/repository.py
@@ -18,7 +18,7 @@
 
 from datetime import datetime, timedelta
 from decimal import Decimal
-from typing import Any, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 from uuid import UUID, uuid4
 
 from forge_obs.cost.models import (
@@ -30,6 +30,10 @@
 )
 from forge_obs.cost.pricing import PriceBook, compute_cost
 
+if TYPE_CHECKING:
+    from sqlalchemy import ColumnElement
+    from sqlalchemy.orm import Session, sessionmaker
+
 __all__ = [
     "CostLedger",
     "CostReader",
@@ -331,7 +335,7 @@ def _usage_from_row(row: Any) -> ModelUsage:
 class SqlCostLedger:
     """Durable ledger over ``cost_event`` (idempotent on the unique index)."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     def upsert_event(
@@ -342,7 +346,7 @@ def upsert_event(
 
         from forge_db.models.cost import CostEvent, CostEventKind
 
-        def _dedup(session) -> CostRecord | None:
+        def _dedup(session: Session) -> CostRecord | None:
             row = session.scalars(
                 select(CostEvent).where(
                     CostEvent.workspace_id == usage.workspace_id,
@@ -445,11 +449,11 @@ def reprice(
 class SqlCostReader:
     """Workspace-scoped rollups over ``cost_event`` for the Cost API."""
 
-    def __init__(self, session_factory) -> None:
+    def __init__(self, session_factory: sessionmaker[Session]) -> None:
         self._session_factory = session_factory
 
     @staticmethod
-    def _scope_clause(scope: str, scope_id: UUID):
+    def _scope_clause(scope: str, scope_id: UUID) -> ColumnElement[bool]:
         from forge_db.models.cost import CostEvent
 
         return {
diff --git a/packages/observability/forge_obs/metrics.py b/packages/observability/forge_obs/metrics.py
index cfcb8fc8..39329df8 100644
--- a/packages/observability/forge_obs/metrics.py
+++ b/packages/observability/forge_obs/metrics.py
@@ -23,7 +23,7 @@
 from __future__ import annotations
 
 import threading
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from typing import Protocol, runtime_checkable
 
 __all__ = [
@@ -178,7 +178,7 @@ class NoopMetrics:
     forward-compat with facade methods added later.
     """
 
-    def _noop(self, **_kwargs) -> None:
+    def _noop(self, **_kwargs: object) -> None:
         return None
 
     record_model_cost = _noop
@@ -195,7 +195,8 @@ def _noop(self, **_kwargs) -> None:
     record_mcp_call = _noop
     set_mcp_freshness_lag = _noop
 
-    def __getattr__(self, name: str):  # uniform no-op surface for new methods
+    def __getattr__(self, name: str) -> Callable[..., None]:
+        # Uniform no-op surface for facade methods added later.
         if name.startswith(("record_", "observe_", "set_")):
             return self._noop
         raise AttributeError(name)

From 69c2aaf9476cb08d0f864b79452bc55bb2e43b6f Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:33:18 +0200
Subject: [PATCH 16/47] test(infra): guard against test-basename collisions
 (importlib evaluated, reverted)

--import-mode=importlib breaks whole-repo collection (exit 2, 51 errors):
importlib mode does not put each test dir on sys.path, so bare sibling
imports fail (41x conftest, _provider_fakes, _sandbox_fakes, mcp_fakes,
cost_support, helm_chart_lib, _helpers, _mp_helpers). Guard test ships
with prepend-mode semantics matching CI. Full importlib migration needs
repackaging ~50 sibling-helper imports first.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tests/test_test_infra.py | 96 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/tests/test_test_infra.py b/tests/test_test_infra.py
index e5b70fc2..5ad0d6c6 100644
--- a/tests/test_test_infra.py
+++ b/tests/test_test_infra.py
@@ -8,6 +8,10 @@
 
 from __future__ import annotations
 
+import os
+from collections import defaultdict
+from pathlib import Path
+
 import conftest
 import pytest
 
@@ -39,3 +43,95 @@ def test_postgres_and_integration_markers_registered(
 def test_postgres_fixture_yields_url(postgres_url: str) -> None:
     # Runs only when Postgres is configured; otherwise skipped (parked).
     assert postgres_url
+
+
+# --------------------------------------------------------------------------- #
+# Guard: test-basename collisions (Task 9).
+#
+# Whole-repo pytest collection imports every ``test_*.py`` into one process.
+# Python caches modules by their *dotted name*, not by file path, so two test
+# files that share a basename AND derive the same dotted module name abort
+# collection with ``exit 2`` ("import file mismatch") — silently redding the
+# entire ``python`` CI lane. Today's duplicate basenames are each disambiguated
+# by a chain of ``__init__.py`` package dirs (or the lack of one); this guard
+# fails the moment a new copy is not, before it can red the lane.
+#
+# The guard stays strict (unique dotted-module per duplicated basename) even
+# after adopting ``--import-mode=importlib`` — importlib tolerates such
+# collisions, but keeping the tree collision-free keeps the suite portable and
+# greppable regardless of import mode.
+#
+# See .superpowers/sdd/task-9-brief.md (Task 9).
+# --------------------------------------------------------------------------- #
+
+_EXCLUDED_DIRS = frozenset({"node_modules", ".git", "__pycache__", ".venv"})
+
+
+def _repo_root() -> Path:
+    """Anchor the walk at the repo root (nearest ancestor with pyproject.toml)."""
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "pyproject.toml").exists():
+            return parent
+    return here.parent.parent
+
+
+def _dotted_module(path: Path) -> str:
+    """Module name pytest's ``prepend`` import mode derives for *path*.
+
+    Walk upward accumulating package names while an ``__init__.py`` is present;
+    the first ancestor without one is the sys.path root. Two test files that
+    derive the *same* dotted name collide at import time (``exit 2``).
+    """
+    parts = [path.stem]
+    parent = path.parent
+    while (parent / "__init__.py").exists():
+        parts.append(parent.name)
+        parent = parent.parent
+    return ".".join(reversed(parts))
+
+
+def _iter_test_files(root: Path):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _EXCLUDED_DIRS]
+        for filename in filenames:
+            if filename.startswith("test_") and filename.endswith(".py"):
+                yield Path(dirpath) / filename
+
+
+def test_no_ambiguous_test_basename_collisions() -> None:
+    """Duplicate test-file basenames must each resolve to a unique module.
+
+    Fix a reported collision by either adding ``__init__.py`` package dirs so
+    each copy sits under a *unique* dotted package path, or renaming the
+    offending ``test_*.py`` to a unique basename. See Task 9 brief.
+    """
+    root = _repo_root()
+
+    by_basename: dict[str, list[Path]] = defaultdict(list)
+    for path in _iter_test_files(root):
+        by_basename[path.name].append(path)
+
+    collisions: list[str] = []
+    for _basename, paths in sorted(by_basename.items()):
+        if len(paths) < 2:
+            continue
+        by_module: dict[str, list[Path]] = defaultdict(list)
+        for path in paths:
+            by_module[_dotted_module(path)].append(path)
+        for module, module_paths in sorted(by_module.items()):
+            if len(module_paths) > 1:
+                rels = ", ".join(
+                    str(p.relative_to(root)) for p in sorted(module_paths)
+                )
+                collisions.append(f"  module {module!r} <- {rels}")
+
+    assert not collisions, (
+        "Ambiguous test-basename collision(s): the following test files share a "
+        "basename AND resolve to the SAME dotted module, which aborts whole-repo "
+        "pytest collection with exit 2 (import file mismatch):\n"
+        + "\n".join(collisions)
+        + "\n\nFix: add __init__.py package dirs to give each copy a unique dotted "
+        "module path, or rename one file to a unique basename. "
+        "See .superpowers/sdd/task-9-brief.md (Task 9)."
+    )

From f21e9495e192cf21a09528f89b2d3392dd36bcee Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:39:00 +0200
Subject: [PATCH 17/47] chore(ci): remove dead ui-kit excludes, orphaned
 board_v1 dir, wire release draft input

---
 .github/workflows/release.yml  | 11 ++++++++++-
 .github/workflows/security.yml |  9 +++++++++
 mypy.ini                       |  1 -
 pyproject.toml                 |  2 +-
 ruff.toml                      |  1 -
 5 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 08a0a42e..f301d7c7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -189,15 +189,24 @@ jobs:
              cp CHANGELOG.md RELEASE_NOTES.md
 
       # --- Publish the GitHub Release (gh CLI, GITHUB_TOKEN) --- #
+      # Draft by default: a tag push always creates a draft (the `inputs`
+      # context is empty on a non-workflow_dispatch trigger, so the first
+      # disjunct short-circuits `true`); only an explicit `workflow_dispatch`
+      # run with draft=false produces a published (non-draft) release.
       - name: Create GitHub Release
         if: startsWith(github.ref, 'refs/tags/v')
         env:
           GH_TOKEN: ${{ github.token }}
+          RELEASE_IS_DRAFT: ${{ (github.event_name != 'workflow_dispatch') || inputs.draft }}
         run: |
+          DRAFT_FLAG=""
+          if [ "$RELEASE_IS_DRAFT" = "true" ]; then
+            DRAFT_FLAG="--draft"
+          fi
           gh release create "${GITHUB_REF_NAME}" \
             --title "${GITHUB_REF_NAME}" \
             --notes-file RELEASE_NOTES.md \
-            --draft \
+            $DRAFT_FLAG \
             release/sbom/forge-source.cdx.json \
             deploy/sbom/*.cdx.json \
             deploy/build-manifest.json \
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index 7f58c157..43829b81 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -5,6 +5,15 @@
 #
 # Third-party (and official actions/*) actions are pinned to a full commit SHA
 # with a human-readable version comment, so a moved tag cannot alter what runs.
+#
+# NOTE — intentional overlap with ci.yml's `security` job: that job runs the
+# same scanners (bandit, pip-audit, gitleaks) plus semgrep + SBOM + the
+# enforcement-matrix suite as part of the full green gate. This workflow is
+# kept as a separate, minimal-permission (contents: read only), fast-to-review
+# check so the core secret/SAST/dependency gate can be reasoned about (and
+# required in branch protection) independently of the rest of CI. Do not
+# de-duplicate one into the other without checking branch-protection required
+# status checks first.
 name: security
 
 on:
diff --git a/mypy.ini b/mypy.ini
index d772c0e5..38715a28 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -12,6 +12,5 @@ no_implicit_optional = True
 ignore_missing_imports = True
 exclude = (?x)(
     ^apps/web/
-    | ^packages/ui-kit/
     | /migrations/versions/
     )
diff --git a/pyproject.toml b/pyproject.toml
index a2d2bd23..eda156af 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -60,7 +60,7 @@ package = false
 
 [tool.uv.workspace]
 members = ["packages/*", "apps/*"]
-exclude = ["packages/ui-kit", "apps/web"]
+exclude = ["apps/web"]
 
 [tool.uv.sources]
 forge-contracts = { workspace = true }
diff --git a/ruff.toml b/ruff.toml
index 1128e47f..4ac7b772 100644
--- a/ruff.toml
+++ b/ruff.toml
@@ -7,7 +7,6 @@ extend-exclude = [
     ".venv",
     "node_modules",
     "apps/web",
-    "packages/ui-kit",
     "**/migrations/versions",
     # HARD-09 SAST fixtures deliberately contain rule-triggering constructs.
     "tests/security/fixtures",

From c7ef1612ad39f2fc2f4fe2f92792c54fcc9a7624 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 00:55:26 +0200
Subject: [PATCH 18/47] test(db): gate model/migration schema drift via
 autogenerate compare

Add packages/db/tests/test_schema_drift.py: upgrade a fresh Postgres to
head and assert alembic.autogenerate.compare_metadata() returns an empty
diff against Base.metadata, using the exact autogenerate settings env.py
configures (compare_type=True; compare_server_default unset; no
include_object). Mirrors test_migration.py's @pytest.mark.postgres
fixture/skip conventions (scratch throwaway DB, FORGE_TEST_DATABASE_URL).
A second sanity test proves the comparison is drift-sensitive by diffing
against an empty MetaData().

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/db/tests/test_schema_drift.py | 196 +++++++++++++++++++++++++
 1 file changed, 196 insertions(+)
 create mode 100644 packages/db/tests/test_schema_drift.py

diff --git a/packages/db/tests/test_schema_drift.py b/packages/db/tests/test_schema_drift.py
new file mode 100644
index 00000000..e93d7a21
--- /dev/null
+++ b/packages/db/tests/test_schema_drift.py
@@ -0,0 +1,196 @@
+"""Schema-drift gate (Task 11).
+
+Upgrades a throwaway Postgres database to ``head`` and asserts Alembic's
+:func:`alembic.autogenerate.compare_metadata` finds an *empty* diff between the
+migrated schema and the ORM ``Base.metadata``. In other words: every model
+change must be backed by a matching Alembic migration (and vice versa). This
+closes the audit gap where a SQLAlchemy model change *without* a corresponding
+migration passed CI and shipped — the drift only surfaces at runtime as a
+missing column/table.
+
+Contract — this test asserts *exactly* the diff a real ``alembic revision
+--autogenerate`` would emit, by reusing the same autogenerate settings
+``packages/db/migrations/env.py`` configures and nothing more:
+
+* ``compare_type=True`` — mirrored from ``env.py``'s ``context.configure(...)``.
+* ``compare_server_default`` — *not* set, exactly as in ``env.py`` (Alembic
+  defaults it off), so ``server_default`` text is never compared. This is the
+  documented reason the ``server_default`` false positives the brief warns about
+  do not appear.
+* No ``include_object`` / ``include_name`` filter — ``env.py`` defines none, so
+  none is added here. Alembic's own version table (``alembic_version``) is
+  excluded internally by ``compare_metadata``; pgvector's ``VECTOR`` /
+  ``TSVECTOR`` types round-trip through reflection (pgvector registers them in
+  the Postgres dialect ``ischema_names``), so neither needs a filter.
+
+Keeping the settings identical to ``env.py`` means the gate can never disagree
+with the tool that generates the migrations: if this test is green, autogenerate
+is quiescent; if it is red, autogenerate would produce a non-empty revision.
+
+Runs only against a real pgvector Postgres (the baseline's ``CREATE EXTENSION
+vector`` + ``VECTOR(1536)`` / ``tsvector`` columns cannot be represented on
+SQLite) and skips cleanly when no ``FORGE_TEST_DATABASE_URL`` (or a
+``testcontainers`` pgvector) is available — mirroring the ``@pytest.mark.postgres``
+tests in ``test_migration.py``. CI's ``python`` job provisions the database and
+sets ``FORGE_TEST_DATABASE_URL``, so the gate is live there.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator
+
+import pytest
+from alembic import command
+from alembic.autogenerate import compare_metadata
+from alembic.config import Config
+from alembic.migration import MigrationContext
+from sqlalchemy import MetaData, create_engine, text
+from sqlalchemy.engine import make_url
+
+import forge_db.models  # noqa: F401  (registers every model on Base.metadata)
+from forge_db.base import Base
+from forge_db.migration_utils import build_alembic_config
+
+
+def _diff_lines(diffs: list) -> str:
+    """Render a ``compare_metadata`` diff list as one human-readable line each.
+
+    Each element is either a single ``(op, ...)`` tuple or a list of such tuples
+    (Alembic groups per-column ops, e.g. ``modify_type``); flatten so every drift
+    item prints verbatim in the failure message / CI log.
+    """
+    lines: list[str] = []
+    for entry in diffs:
+        group = entry if isinstance(entry, list) else [entry]
+        for op in group:
+            lines.append(f"  - {op!r}")
+    return "\n".join(lines)
+
+
+@pytest.fixture
+def scratch_pg_config(postgres_url: str, monkeypatch: pytest.MonkeyPatch) -> Iterator[Config]:
+    """Provision a throwaway Postgres database and yield an Alembic ``Config``.
+
+    A fresh, empty database (public schema, no Forge tables) is created on the
+    same server the ``postgres_url`` fixture resolves, so ``alembic upgrade``
+    runs against a clean slate and the baseline's ``CREATE EXTENSION vector`` +
+    every table is provisioned end-to-end without touching any other test's data.
+    The database is dropped on teardown. ``FORGE_DATABASE_URL`` is pointed at the
+    scratch DB for the duration so Alembic's ``env.py`` targets it.
+
+    (Copied from ``test_migration.py``'s live-Postgres tests so the drift gate
+    shares their engine/env/isolation conventions verbatim.)
+    """
+    base_url = make_url(postgres_url)
+    scratch_name = f"forge_drift_{uuid.uuid4().hex[:12]}"
+
+    admin = create_engine(base_url, isolation_level="AUTOCOMMIT", future=True)
+    try:
+        with admin.connect() as conn:
+            conn.execute(text(f'CREATE DATABASE "{scratch_name}"'))
+    finally:
+        admin.dispose()
+
+    scratch_url = base_url.set(database=scratch_name)
+    url_str = scratch_url.render_as_string(hide_password=False)
+    # env.py reads FORGE_DATABASE_URL first, then the config's sqlalchemy.url;
+    # set both to the scratch DB so nothing external can redirect the migration.
+    monkeypatch.setenv("FORGE_DATABASE_URL", url_str)
+    cfg = build_alembic_config(url_str)
+    try:
+        yield cfg
+    finally:
+        teardown = create_engine(base_url, isolation_level="AUTOCOMMIT", future=True)
+        try:
+            with teardown.connect() as conn:
+                conn.execute(
+                    text(
+                        "SELECT pg_terminate_backend(pid) FROM pg_stat_activity "
+                        "WHERE datname = :n AND pid <> pg_backend_pid()"
+                    ),
+                    {"n": scratch_name},
+                )
+                conn.execute(text(f'DROP DATABASE IF EXISTS "{scratch_name}"'))
+        finally:
+            teardown.dispose()
+
+
+@pytest.mark.postgres
+def test_no_schema_drift_between_models_and_migrations(scratch_pg_config: Config) -> None:
+    """The migrated ``head`` schema must equal the ORM metadata (no drift).
+
+    Upgrades a fresh Postgres to ``head`` then runs ``compare_metadata`` with the
+    exact autogenerate settings ``env.py`` uses. A non-empty diff means a model
+    was changed without a matching migration (or a migration diverged from the
+    models) — the gate the audit found missing. Every diff item is listed in the
+    failure so the fix (add/adjust a migration, or align the model) is obvious.
+    """
+    url = scratch_pg_config.get_main_option("sqlalchemy.url")
+    assert url is not None
+
+    command.upgrade(scratch_pg_config, "head")
+
+    engine = create_engine(url, future=True)
+    try:
+        with engine.connect() as conn:
+            # Mirror env.py's online autogenerate contract exactly:
+            #   context.configure(connection=..., target_metadata=Base.metadata,
+            #                     compare_type=True)
+            context = MigrationContext.configure(
+                connection=conn,
+                opts={"compare_type": True, "target_metadata": Base.metadata},
+            )
+            diffs = compare_metadata(context, Base.metadata)
+    finally:
+        engine.dispose()
+
+    assert not diffs, (
+        "Schema drift detected: the ORM models and the Alembic migrations "
+        "disagree. `alembic revision --autogenerate` against a fresh Postgres "
+        f"would emit {sum(len(d) if isinstance(d, list) else 1 for d in diffs)} "
+        "operation(s):\n"
+        + _diff_lines(diffs)
+        + "\n\nResolve by adding/adjusting an Alembic migration under "
+        "packages/db/migrations/versions so the schema matches the models "
+        "(do NOT silence this by editing the test). If a divergence is "
+        "intentional and cannot be represented in metadata, document it here "
+        "with a narrow, explicit exclusion."
+    )
+
+
+@pytest.mark.postgres
+def test_compare_metadata_is_drift_sensitive(scratch_pg_config: Config) -> None:
+    """Sensitivity guard: the comparison actually detects a missing schema.
+
+    Proves the gate above can fail — without mutating any real model. Comparing
+    the migrated ``head`` database against an empty ``MetaData()`` must yield a
+    non-empty diff containing ``remove_table`` operations (Alembic's signal that
+    the database has tables the compared metadata lacks). This is the same
+    machinery, exercised in its failing direction, so a green
+    ``test_no_schema_drift_*`` is a meaningful assertion rather than a
+    vacuously-empty one.
+    """
+    url = scratch_pg_config.get_main_option("sqlalchemy.url")
+    assert url is not None
+
+    command.upgrade(scratch_pg_config, "head")
+
+    empty_metadata = MetaData()
+    engine = create_engine(url, future=True)
+    try:
+        with engine.connect() as conn:
+            context = MigrationContext.configure(
+                connection=conn,
+                opts={"compare_type": True, "target_metadata": empty_metadata},
+            )
+            diffs = compare_metadata(context, empty_metadata)
+    finally:
+        engine.dispose()
+
+    assert diffs, "compare_metadata found no diff against empty metadata — gate is blind"
+    ops = {op[0] for entry in diffs for op in (entry if isinstance(entry, list) else [entry])}
+    assert "remove_table" in ops, (
+        "expected 'remove_table' ops when comparing a populated database against "
+        f"empty metadata; got op kinds: {sorted(ops)}"
+    )

From 1ec53171a205168e683c1c77d7f6aac5d7de3b21 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:05:34 +0200
Subject: [PATCH 19/47] fix(db): align model with migrations and scope
 drift-gate exclusions

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/db/forge_db/base.py              |   9 +-
 packages/db/forge_db/models/automation.py |  10 ++-
 packages/db/forge_db/models/workspace.py  |   2 +-
 packages/db/tests/test_schema_drift.py    | 102 +++++++++++++++++++++-
 4 files changed, 114 insertions(+), 9 deletions(-)

diff --git a/packages/db/forge_db/base.py b/packages/db/forge_db/base.py
index 1cc42904..74b57c6a 100644
--- a/packages/db/forge_db/base.py
+++ b/packages/db/forge_db/base.py
@@ -49,18 +49,25 @@ def json_type() -> TypeEngine[Any]:
     return JSON().with_variant(JSONB(), "postgresql")
 
 
-def enum_type[E: enum.Enum](enum_cls: type[E]) -> SAEnum:
+def enum_type[E: enum.Enum](enum_cls: type[E], *, length: int | None = None) -> SAEnum:
     """String-backed enum column storing the member ``value`` (cross-dialect).
 
     ``native_enum=False`` renders as VARCHAR + CHECK (no Postgres native ENUM,
     keeping migrations simple); ``values_callable`` persists ``member.value`` so
     stored strings match the spec verbatim (e.g. ``agent-runner``).
+
+    ``length`` pins the rendered ``VARCHAR`` width. Left ``None`` (the default),
+    SQLAlchemy sizes the column to the longest enum value; pass an explicit width
+    when a migration has deliberately widened the DB column beyond the current
+    vocabulary (e.g. F40's ``VARCHAR(32)`` headroom on the automation trigger
+    columns) so the ORM metadata renders the same width and no drift is reported.
     """
     return SAEnum(
         enum_cls,
         native_enum=False,
         validate_strings=True,
         values_callable=lambda e: [member.value for member in e],
+        length=length,
     )
 
 
diff --git a/packages/db/forge_db/models/automation.py b/packages/db/forge_db/models/automation.py
index ee69a22d..8f693ae3 100644
--- a/packages/db/forge_db/models/automation.py
+++ b/packages/db/forge_db/models/automation.py
@@ -59,8 +59,10 @@ class AutomationRule(WorkspaceScopedModel):
     name: Mapped[str] = mapped_column(String(200), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     enabled: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    # F40 (migration 0033) widened this VARCHAR to 32 for headroom; pin the same
+    # width on the model so the ORM metadata matches the DB (no schema drift).
     trigger_type: Mapped[AutomationTriggerType] = mapped_column(
-        enum_type(AutomationTriggerType), nullable=False
+        enum_type(AutomationTriggerType, length=32), nullable=False
     )
     trigger_config: Mapped[dict[str, Any]] = mapped_column(
         json_type(), default=dict, nullable=False
@@ -91,12 +93,14 @@ class AutomationExecution(WorkspaceScopedModel):
     # ``SET NULL`` to honor the stronger append-only guarantee.)
     rule_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True), nullable=True)
     rule_version: Mapped[int] = mapped_column(Integer, nullable=False)
+    # F40 (migration 0033) widened trigger_type/trigger_source to VARCHAR(32) for
+    # headroom; pin the same width here so the ORM matches the DB (no drift).
     trigger_type: Mapped[AutomationTriggerType] = mapped_column(
-        enum_type(AutomationTriggerType), nullable=False
+        enum_type(AutomationTriggerType, length=32), nullable=False
     )
     trigger_event_id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), nullable=False)
     trigger_source: Mapped[AutomationTriggerSource] = mapped_column(
-        enum_type(AutomationTriggerSource), nullable=False
+        enum_type(AutomationTriggerSource, length=32), nullable=False
     )
     entity_type: Mapped[AutomationEntityType] = mapped_column(
         enum_type(AutomationEntityType), nullable=False
diff --git a/packages/db/forge_db/models/workspace.py b/packages/db/forge_db/models/workspace.py
index 728751c8..78b23c74 100644
--- a/packages/db/forge_db/models/workspace.py
+++ b/packages/db/forge_db/models/workspace.py
@@ -88,7 +88,7 @@ class APIKey(WorkspaceScopedModel):
     # and when the DEK was last re-wrapped (rotation audit). The wrapped DEK
     # itself travels inside ``encrypted_secret`` (self-describing envelope blob).
     key_version: Mapped[int] = mapped_column(
-        SmallInteger, default=1, server_default=text("1"), nullable=False
+        SmallInteger, default=1, server_default=text("1"), nullable=False, index=True
     )
     rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
 
diff --git a/packages/db/tests/test_schema_drift.py b/packages/db/tests/test_schema_drift.py
index e93d7a21..71ea3100 100644
--- a/packages/db/tests/test_schema_drift.py
+++ b/packages/db/tests/test_schema_drift.py
@@ -27,6 +27,16 @@
 with the tool that generates the migrations: if this test is green, autogenerate
 is quiescent; if it is red, autogenerate would produce a non-empty revision.
 
+The one post-processing step is a narrow, exact-name exclusion allowlist
+(``KNOWN_UNREPRESENTABLE``) applied to the *result* diff — never via
+``include_object`` — for the handful of Postgres objects that exist in the
+migrated schema but genuinely cannot be represented in ORM metadata (raw-DDL
+expression/GIN indexes and Postgres-only FKs the models deliberately omit for
+SQLite portability). It matches by exact object name only, drops only ``remove_*``
+ops, and leaves the ``add_*`` direction completely unfiltered so real "model grew
+something without a migration" drift still fails. Each excluded name cites the
+migration/DDL that owns it (see the allowlist below).
+
 Runs only against a real pgvector Postgres (the baseline's ``CREATE EXTENSION
 vector`` + ``VECTOR(1536)`` / ``tsvector`` columns cannot be represented on
 SQLite) and skips cleanly when no ``FORGE_TEST_DATABASE_URL`` (or a
@@ -68,6 +78,84 @@ def _diff_lines(diffs: list) -> str:
     return "\n".join(lines)
 
 
+# --------------------------------------------------------------------------- #
+# Structurally-unrepresentable schema objects — exact-name exclusion allowlist. #
+#                                                                               #
+# Each object below genuinely exists in the migrated Postgres schema but CANNOT #
+# be expressed in the SQLAlchemy ORM ``Base.metadata`` (raw-DDL expression/GIN  #
+# indexes, or Postgres-only FKs the models deliberately omit so SQLite          #
+# ``create_all`` stays portable). ``compare_metadata`` therefore emits a        #
+# perpetual, un-actionable ``remove_*`` op for each — a false positive the gate #
+# must tolerate WITHOUT weakening its real job.                                 #
+#                                                                               #
+# The exclusion below is deliberately narrow: it matches by EXACT object name   #
+# only (no wildcard, no prefix), it never suppresses a whole diff kind, and it  #
+# only ever drops ``remove_*`` ops. The ``add_*`` direction is left completely  #
+# unfiltered — a model that *grows* one of these names without a migration must #
+# still fail the gate, because that is real, dangerous drift. Every name cites  #
+# the migration / DDL that owns it and why Alembic cannot round-trip it:        #
+KNOWN_UNREPRESENTABLE: frozenset[str] = frozenset(
+    {
+        # Raw-DDL GIN index over a ``jsonb_path_ops`` expression, created by
+        # ``marketplace.py``'s ``_pg_ddl(...)`` (Postgres-only; mirrored by
+        # migration ``0015_f32_integration_marketplace``). Alembic metadata
+        # cannot represent a functional / opclass GIN index, so it round-trips
+        # as a phantom removal.
+        "ix_marketplace_listing_tags_gin",
+        # Raw-DDL full-text GIN index over ``to_tsvector('english', name || ' '
+        # || summary)``, created by ``marketplace.py``'s ``_pg_ddl(...)``
+        # (Postgres-only; mirrored by ``0015``). Expression indexes are not
+        # expressible in ORM metadata.
+        "ix_marketplace_listing_fts",
+        # Postgres-only FK ``project.owner_team_id -> team.id`` (ON DELETE SET
+        # NULL) added by migration ``0012_f30_multi_team_rbac``. The model keeps
+        # a plain, FK-less column so SQLite ``create_all`` can drop it on
+        # downgrade; the FK lives only in the migration and reflects as a phantom
+        # removal.
+        "fk_project_owner_team_id_team",
+        # Postgres-only FK ``sub_agent_run.agent_run_id -> agent_run.id`` (ON
+        # DELETE SET NULL) added by migration ``0009_f27_multi_agent`` (the
+        # child-run FK pattern ``project.owner_team_id`` mirrors). The model omits
+        # the ORM FK, so it reflects as a phantom removal.
+        "fk_sub_agent_run_child",
+    }
+)
+
+
+def _removal_object_name(op: tuple) -> str | None:
+    """Exact schema-object name a ``remove_*`` diff op targets, else ``None``.
+
+    Defined only for ``remove_*`` ops whose payload is a named schema construct
+    (``Index`` / ``ForeignKeyConstraint`` and other constraints expose ``.name``).
+    Returns ``None`` for every other op — crucially every ``add_*`` op — so the
+    exclusion below can never match anything but an exact-named removal.
+    """
+    kind = op[0]
+    if not kind.startswith("remove_") or len(op) < 2:
+        return None
+    return getattr(op[1], "name", None)
+
+
+def _filter_known_unrepresentable(diffs: list) -> list:
+    """Drop only exact-named ``remove_*`` ops listed in ``KNOWN_UNREPRESENTABLE``.
+
+    Everything else is preserved verbatim: grouped ops (lists, e.g. ``modify_*``),
+    every ``add_*`` op, and any ``remove_*`` op whose name is not in the frozen
+    set. This keeps the gate live for all real drift while tolerating the handful
+    of structurally-unrepresentable Postgres objects documented above.
+    """
+    kept: list = []
+    for entry in diffs:
+        if isinstance(entry, list):
+            kept.append(entry)
+            continue
+        name = _removal_object_name(entry)
+        if name is not None and name in KNOWN_UNREPRESENTABLE:
+            continue
+        kept.append(entry)
+    return kept
+
+
 @pytest.fixture
 def scratch_pg_config(postgres_url: str, monkeypatch: pytest.MonkeyPatch) -> Iterator[Config]:
     """Provision a throwaway Postgres database and yield an Alembic ``Config``.
@@ -141,10 +229,15 @@ def test_no_schema_drift_between_models_and_migrations(scratch_pg_config: Config
                 connection=conn,
                 opts={"compare_type": True, "target_metadata": Base.metadata},
             )
-            diffs = compare_metadata(context, Base.metadata)
+            raw_diffs = compare_metadata(context, Base.metadata)
     finally:
         engine.dispose()
 
+    # Drop only the exact-named, structurally-unrepresentable Postgres objects
+    # documented in KNOWN_UNREPRESENTABLE (raw-DDL expression/GIN indexes +
+    # Postgres-only FKs). The add_* direction and every other object stay live.
+    diffs = _filter_known_unrepresentable(raw_diffs)
+
     assert not diffs, (
         "Schema drift detected: the ORM models and the Alembic migrations "
         "disagree. `alembic revision --autogenerate` against a fresh Postgres "
@@ -153,9 +246,10 @@ def test_no_schema_drift_between_models_and_migrations(scratch_pg_config: Config
         + _diff_lines(diffs)
         + "\n\nResolve by adding/adjusting an Alembic migration under "
         "packages/db/migrations/versions so the schema matches the models "
-        "(do NOT silence this by editing the test). If a divergence is "
-        "intentional and cannot be represented in metadata, document it here "
-        "with a narrow, explicit exclusion."
+        "(do NOT silence this by editing the test). If a divergence is genuinely "
+        "intentional and cannot be represented in metadata, add its exact name to "
+        "KNOWN_UNREPRESENTABLE above with a comment citing the migration/DDL "
+        "source (never a wildcard, never a whole diff kind, never an add_* op)."
     )
 
 

From 81068d892db8c7aa61721563e362d07349d7f5f8 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:12:44 +0200
Subject: [PATCH 20/47] test(db): unit-test drift-gate exclusion filter without
 postgres

---
 packages/db/tests/test_schema_drift.py | 147 ++++++++++++++++++++++++-
 1 file changed, 146 insertions(+), 1 deletion(-)

diff --git a/packages/db/tests/test_schema_drift.py b/packages/db/tests/test_schema_drift.py
index 71ea3100..c6cc3765 100644
--- a/packages/db/tests/test_schema_drift.py
+++ b/packages/db/tests/test_schema_drift.py
@@ -55,7 +55,16 @@
 from alembic.autogenerate import compare_metadata
 from alembic.config import Config
 from alembic.migration import MigrationContext
-from sqlalchemy import MetaData, create_engine, text
+from sqlalchemy import (
+    Column,
+    ForeignKeyConstraint,
+    Index,
+    Integer,
+    MetaData,
+    Table,
+    create_engine,
+    text,
+)
 from sqlalchemy.engine import make_url
 
 import forge_db.models  # noqa: F401  (registers every model on Base.metadata)
@@ -156,6 +165,142 @@ def _filter_known_unrepresentable(diffs: list) -> list:
     return kept
 
 
+# --------------------------------------------------------------------------- #
+# Unit tests for the exclusion filter itself — no Postgres required.          #
+#                                                                               #
+# `_filter_known_unrepresentable` / `_removal_object_name` were previously     #
+# exercised only indirectly, inside `test_no_schema_drift_between_models_and_  #
+# migrations` (``@pytest.mark.postgres``), which skips with no live DB. These  #
+# table-driven cases pin the filter's actual decision logic — using real       #
+# ``sqlalchemy.Index`` / ``ForeignKeyConstraint`` objects so ``.name`` behaves  #
+# exactly as it does on a genuine ``compare_metadata`` diff — and run          #
+# unconditionally (unmarked; the module has no module-level ``pytestmark``,    #
+# each Postgres test opts in individually via ``@pytest.mark.postgres``).      #
+# --------------------------------------------------------------------------- #
+
+
+def _named_index(name: str) -> Index:
+    """A real, standalone ``Index`` with the given ``.name`` (no DB needed)."""
+    metadata = MetaData()
+    table = Table(f"_t_{name}", metadata, Column("id", Integer))
+    return Index(name, table.c.id)
+
+
+def _named_fk(name: str) -> ForeignKeyConstraint:
+    """A real, standalone ``ForeignKeyConstraint`` with the given ``.name``."""
+    return ForeignKeyConstraint(["parent_id"], ["parent.id"], name=name)
+
+
+_ALLOWLISTED_INDEX = _named_index("ix_marketplace_listing_fts")
+_OTHER_INDEX = _named_index("ix_other_random")
+_ALLOWLISTED_FK = _named_fk("fk_sub_agent_run_child")
+_MODIFY_TYPE_GROUP = [("modify_type", None, "some_table", "some_column", {}, "OLD", "NEW")]
+_REMOVE_COLUMN_NO_SCHEMA = ("remove_column", None, "sub_agent_run", Column("agent_run_id", Integer))
+_REMOVE_COLUMN_WITH_SCHEMA = (
+    "remove_column",
+    "public",
+    "sub_agent_run",
+    Column("agent_run_id", Integer),
+)
+
+
+@pytest.mark.parametrize(
+    ("diffs", "expected"),
+    [
+        pytest.param(
+            [("remove_index", _ALLOWLISTED_INDEX)],
+            [],
+            id="remove_index-allowlisted-name-filtered",
+        ),
+        pytest.param(
+            [("add_index", _ALLOWLISTED_INDEX)],
+            [("add_index", _ALLOWLISTED_INDEX)],
+            id="add_index-allowlisted-name-kept-add-star-never-filtered",
+        ),
+        pytest.param(
+            [("remove_index", _OTHER_INDEX)],
+            [("remove_index", _OTHER_INDEX)],
+            id="remove_index-non-allowlisted-name-kept",
+        ),
+        pytest.param(
+            [_MODIFY_TYPE_GROUP],
+            [_MODIFY_TYPE_GROUP],
+            id="grouped-op-list-kept-unconditionally",
+        ),
+        pytest.param(
+            [("remove_fk", _ALLOWLISTED_FK)],
+            [],
+            id="remove_fk-allowlisted-name-filtered",
+        ),
+        pytest.param(
+            [_REMOVE_COLUMN_NO_SCHEMA],
+            [_REMOVE_COLUMN_NO_SCHEMA],
+            id="remove_column-schema-is-None-no-name-attr-kept-no-raise",
+        ),
+        pytest.param(
+            [_REMOVE_COLUMN_WITH_SCHEMA],
+            [_REMOVE_COLUMN_WITH_SCHEMA],
+            id="remove_column-schema-is-str-no-name-attr-kept-no-raise",
+        ),
+    ],
+)
+def test_filter_known_unrepresentable_cases(diffs: list, expected: list) -> None:
+    """Table-driven pin of the exclusion filter's decision logic (no Postgres).
+
+    Each case is a synthetic ``compare_metadata``-shaped diff entry:
+
+    * ``remove_index`` / ``remove_fk`` on an allowlisted name -> dropped.
+    * ``add_index`` on the *same* allowlisted name -> kept: only ``remove_*``
+      is ever eligible for filtering, per ``_removal_object_name``'s
+      ``kind.startswith("remove_")`` guard.
+    * ``remove_index`` on a non-allowlisted name -> kept.
+    * A grouped op (a ``list``, e.g. Alembic's per-column ``modify_*`` bundle)
+      -> kept unconditionally; ``_filter_known_unrepresentable`` never
+      recurses into grouped entries.
+    * ``remove_column`` -> kept and does not raise: its diff shape is
+      ``("remove_column", schema, tablename, column)``, so ``op[1]`` is the
+      *schema* (a ``str`` or ``None``), not the column. ``getattr(op[1],
+      "name", None)`` safely returns ``None`` for both, so remove_column ops
+      are never filterable by this function regardless of the column's name.
+    """
+    assert _filter_known_unrepresentable(diffs) == expected
+
+
+def test_compare_metadata_detects_add_table_without_postgres() -> None:
+    """Sensitivity guard, add_* direction — proven hermetically (no Postgres).
+
+    Folded-in minor: the existing ``test_compare_metadata_is_drift_sensitive``
+    (``@pytest.mark.postgres``) only proves the *remove* direction (comparing a
+    populated DB against empty metadata). This proves the *add* direction —
+    metadata carrying a table the database lacks yields an ``add_table`` op —
+    without needing Postgres or any of ``env.py``'s pgvector-specific baseline:
+    an in-memory SQLite connection is enough to drive a real
+    ``MigrationContext``/``compare_metadata`` round-trip, so this direction is
+    on watch even in the hermetic, no-network default lane.
+    """
+    baseline_metadata = MetaData()
+    grown_metadata = MetaData()
+    Table("throwaway_extra_table", grown_metadata, Column("id", Integer, primary_key=True))
+
+    engine = create_engine("sqlite://", future=True)
+    try:
+        with engine.connect() as conn:
+            baseline_metadata.create_all(conn)  # the "existing" DB: no tables
+            context = MigrationContext.configure(
+                connection=conn,
+                opts={"compare_type": True, "target_metadata": grown_metadata},
+            )
+            diffs = compare_metadata(context, grown_metadata)
+    finally:
+        engine.dispose()
+
+    ops = {op[0] for entry in diffs for op in (entry if isinstance(entry, list) else [entry])}
+    assert "add_table" in ops, (
+        "expected an 'add_table' op when comparing metadata that grew a table "
+        f"the database lacks; got op kinds: {sorted(ops)}"
+    )
+
+
 @pytest.fixture
 def scratch_pg_config(postgres_url: str, monkeypatch: pytest.MonkeyPatch) -> Iterator[Config]:
     """Provision a throwaway Postgres database and yield an Alembic ``Config``.

From 9266106cb83322b5426d852d36985df2ccb93cd6 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:23:50 +0200
Subject: [PATCH 21/47] fix(helm): wire real FORGE_MODEL_* env contract, drop
 dead MinIO knobs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/helm/forge/README.md                   |  7 +++++-
 deploy/helm/forge/templates/_helpers.tpl      | 16 ++++++-------
 .../helm/forge/templates/configmap-env.yaml   | 23 +++++++++++--------
 .../tests/secret_config_separation_test.yaml  |  4 ++--
 deploy/helm/forge/values-production.yaml      |  5 ++--
 deploy/helm/forge/values.schema.json          |  3 ++-
 deploy/helm/forge/values.yaml                 | 19 +++++++++++++--
 docs/FORGE_SPEC.md                            |  2 +-
 docs/self-hosting/kubernetes.md               | 18 +++++++++++----
 docs/self-hosting/quickstart.md               |  6 +++--
 docs/self-hosting/troubleshooting.md          |  6 +++--
 11 files changed, 74 insertions(+), 35 deletions(-)

diff --git a/deploy/helm/forge/README.md b/deploy/helm/forge/README.md
index 7d02f071..081c99a1 100644
--- a/deploy/helm/forge/README.md
+++ b/deploy/helm/forge/README.md
@@ -16,9 +16,14 @@ helm install forge deploy/helm/forge -n forge --create-namespace \
   --set-string secrets.data.AUTH_SECRET="$(openssl rand -hex 32)" \
   --set-string secrets.data.API_KEY_PEPPER="$(openssl rand -hex 32)" \
   --set-string secrets.data.INTERNAL_SERVICE_TOKEN="$(openssl rand -hex 32)" \
-  --set-string secrets.data.MODEL_PROVIDER_KEY="$MODEL_KEY"
+  --set-string secrets.data.FORGE_MODEL_API_KEY="$MODEL_KEY"   # optional; omit for offline scripted model
 ```
 
+`forge.modelProvider` (default `anthropic`) sets the master switch
+`FORGE_MODEL_PROVIDER`; leave `secrets.data.FORGE_MODEL_API_KEY` blank to run the
+offline deterministic model, or set it (plus `forge.modelName` for openai) to
+drive a real provider.
+
 ## Source / dependencies
 
 | Repository | Name | Version |
diff --git a/deploy/helm/forge/templates/_helpers.tpl b/deploy/helm/forge/templates/_helpers.tpl
index 5d2ebb39..e98bfc76 100644
--- a/deploy/helm/forge/templates/_helpers.tpl
+++ b/deploy/helm/forge/templates/_helpers.tpl
@@ -164,7 +164,10 @@ its name is required (and the same keys are the operator's responsibility).
 {{- define "forge.validateSecrets" -}}
 {{- if .Values.secrets.create -}}
 {{- $data := .Values.secrets.data | default dict -}}
-{{- range $key := (list "SECRET_KEY" "AUTH_SECRET" "FORGE_VAULT_KEYS" "API_KEY_PEPPER" "INTERNAL_SERVICE_TOKEN" "MODEL_PROVIDER_KEY") -}}
+{{- /* The BYOK model key (FORGE_MODEL_API_KEY) is intentionally NOT here: the
+       worker/api boot fine without it (offline scripted fallback), so it is
+       optional, not fail-closed. */ -}}
+{{- range $key := (list "SECRET_KEY" "AUTH_SECRET" "FORGE_VAULT_KEYS" "API_KEY_PEPPER" "INTERNAL_SERVICE_TOKEN") -}}
 {{- if not (get $data $key) -}}
 {{- fail (printf "secrets.data.%s is required (api/worker fail closed without it — F37). Generate one (e.g. openssl rand -hex 32) and pass it via --set or a values file." $key) -}}
 {{- end -}}
@@ -211,13 +214,10 @@ secret name.
 {{- end -}}
 {{- end -}}
 
-{{- define "forge.minioEndpoint" -}}
-{{- if .Values.minio.enabled -}}
-{{- printf "http://%s-minio:9000" (include "forge.fullname" .) -}}
-{{- else -}}
-{{- .Values.externalObjectStore.endpoint -}}
-{{- end -}}
-{{- end -}}
+{{/* NOTE: no forge.minioEndpoint helper — object-store endpoint/bucket env is
+     PARKED with the object-storage scope (no reader yet). Bundled/external
+     object-store CREDS still flow via the Secret + the minio subchart /
+     externalObjectStore config. */}}
 
 {{- define "forge.publicUrl" -}}
 {{- default (printf "https://%s" .Values.forge.domain) .Values.forge.publicUrl -}}
diff --git a/deploy/helm/forge/templates/configmap-env.yaml b/deploy/helm/forge/templates/configmap-env.yaml
index 1c8fa033..5acceadc 100644
--- a/deploy/helm/forge/templates/configmap-env.yaml
+++ b/deploy/helm/forge/templates/configmap-env.yaml
@@ -18,7 +18,14 @@ data:
   FORGE_ENV: "production"
   LOG_LEVEL: {{ .Values.forge.logLevel | quote }}
   FORGE_PUBLIC_URL: {{ include "forge.publicUrl" . | quote }}
-  MODEL_PROVIDER: {{ .Values.forge.modelProvider | quote }}
+  # --- BYOK model provider. FORGE_MODEL_PROVIDER is the master switch; the key
+  #     itself is in the Secret (FORGE_MODEL_API_KEY). With the key blank the
+  #     worker runs the offline scripted model. FORGE_MODEL_NAME is optional for
+  #     anthropic (a reference default is applied) and required for openai. ---
+  FORGE_MODEL_PROVIDER: {{ .Values.forge.modelProvider | quote }}
+  {{- with .Values.forge.modelName }}
+  FORGE_MODEL_NAME: {{ . | quote }}
+  {{- end }}
   MCP_GATEWAY_URL: {{ printf "http://%s-mcp-gateway:%d" (include "forge.fullname" .) (int .Values.mcpGateway.service.port) | quote }}
   # --- BYOK vault: the ACTIVE key VERSION is non-secret; the key MATERIAL
   #     (FORGE_VAULT_KEYS) is in the Secret only (F37). ---
@@ -49,15 +56,11 @@ data:
   {{- else }}
   REDIS_PORT: {{ .Values.externalRedis.port | quote }}
   {{- end }}
-  # --- Object store (credentials are in the Secret) ---
-  MINIO_ENDPOINT: {{ include "forge.minioEndpoint" . | quote }}
-  {{- if .Values.minio.enabled }}
-  MINIO_BUCKET: {{ .Values.minio.defaultBuckets | quote }}
-  MINIO_REGION: "us-east-1"
-  {{- else }}
-  MINIO_BUCKET: {{ .Values.externalObjectStore.bucket | quote }}
-  MINIO_REGION: {{ .Values.externalObjectStore.region | quote }}
-  {{- end }}
+  # --- Object store: endpoint/bucket/region env is PARKED with the object-storage
+  #     scope. No code reads MINIO_ENDPOINT / MINIO_BUCKET / MINIO_REGION yet, so
+  #     they are omitted until wired. Object-store CREDENTIALS still flow via the
+  #     Secret (MINIO_ROOT_USER/PASSWORD) + the minio subchart / externalObjectStore
+  #     config; only the dead app-facing knobs are dropped here. ---
   # --- retrieval / reranker (F05) ---
   RERANK_ENABLED: {{ .Values.config.rerankEnabled | quote }}
   {{- with include "forge.rerankerUrl" . }}
diff --git a/deploy/helm/forge/tests/secret_config_separation_test.yaml b/deploy/helm/forge/tests/secret_config_separation_test.yaml
index 7d86a8b4..d7df9d08 100644
--- a/deploy/helm/forge/tests/secret_config_separation_test.yaml
+++ b/deploy/helm/forge/tests/secret_config_separation_test.yaml
@@ -13,8 +13,8 @@ tests:
           path: stringData.API_KEY_PEPPER
       - isNotNull:
           path: stringData.INTERNAL_SERVICE_TOKEN
-      - isNotNull:
-          path: stringData.MODEL_PROVIDER_KEY
+      # NOTE: the BYOK model key (FORGE_MODEL_API_KEY) is NOT boot-critical — it is
+      # optional (blank -> offline scripted model) so it is not asserted here.
       - isNotNull:
           path: stringData.FORGE_DATABASE_URL
       - isNull:
diff --git a/deploy/helm/forge/values-production.yaml b/deploy/helm/forge/values-production.yaml
index caf08e37..2c67ee4f 100644
--- a/deploy/helm/forge/values-production.yaml
+++ b/deploy/helm/forge/values-production.yaml
@@ -19,8 +19,9 @@ image:
 
 # Operator-managed Secret carrying every boot-critical + integration key
 # (SECRET_KEY, AUTH_SECRET, FORGE_VAULT_KEYS, API_KEY_PEPPER,
-# INTERNAL_SERVICE_TOKEN, MODEL_PROVIDER_KEY, FORGE_DATABASE_URL, FORGE_REDIS_URL,
-# object-store creds, GITHUB_*/SLACK_*). The chart renders NO Secret of its own.
+# INTERNAL_SERVICE_TOKEN, FORGE_DATABASE_URL, FORGE_REDIS_URL, object-store creds,
+# GITHUB_*/SLACK_*, plus the OPTIONAL BYOK FORGE_MODEL_API_KEY — blank runs the
+# offline scripted model). The chart renders NO Secret of its own.
 secrets:
   create: false
   existingSecret: forge-external
diff --git a/deploy/helm/forge/values.schema.json b/deploy/helm/forge/values.schema.json
index 8d2e055a..805b1171 100644
--- a/deploy/helm/forge/values.schema.json
+++ b/deploy/helm/forge/values.schema.json
@@ -90,7 +90,8 @@
         "domain": {"type": "string", "minLength": 3},
         "publicUrl": {"type": "string"},
         "logLevel": {"enum": ["debug", "info", "warning", "error"]},
-        "modelProvider": {"type": "string"}
+        "modelProvider": {"type": "string"},
+        "modelName": {"type": "string"}
       }
     },
     "image": {
diff --git a/deploy/helm/forge/values.yaml b/deploy/helm/forge/values.yaml
index 6d11d6c5..4d868396 100644
--- a/deploy/helm/forge/values.yaml
+++ b/deploy/helm/forge/values.yaml
@@ -28,8 +28,20 @@ forge:
   # Public base URL; defaults to https://{domain} when empty.
   publicUrl: ""
   logLevel: info
-  # Default model provider name (the API key itself is a Secret: MODEL_PROVIDER_KEY).
+  # BYOK model provider. `modelProvider` (anthropic|openai) is the master switch,
+  # rendered as FORGE_MODEL_PROVIDER. The key itself is a Secret
+  # (secrets.data.FORGE_MODEL_API_KEY); with that key BLANK the worker runs the
+  # offline deterministic ScriptedModelClient (canned output, no network) and logs
+  # a WARNING each run — set the key to drive a real provider. `modelName` is
+  # optional for anthropic (a reference default is applied) and REQUIRED for openai.
+  #
+  # UPGRADE NOTE (pre-1.0): earlier charts shipped the DEAD keys `MODEL_PROVIDER`
+  # (ConfigMap) and `secrets.data.MODEL_PROVIDER_KEY` — nothing read them, so a
+  # deploy silently fell back to the scripted client. They are replaced by
+  # FORGE_MODEL_PROVIDER / FORGE_MODEL_NAME (env) and secrets.data.FORGE_MODEL_API_KEY.
+  # Rename any --set secrets.data.MODEL_PROVIDER_KEY=... to FORGE_MODEL_API_KEY.
   modelProvider: anthropic
+  modelName: ""
 
 # Image defaults shared by all four workloads. Per-workload image.repository/tag/
 # digest live under each workload block below.
@@ -227,7 +239,10 @@ secrets:
     FORGE_VAULT_KEYS: "1:ZGV2LWNoYW5nZS1tZS0zMi1ieXRlLXZhdWx0LWtleS0xMjM="
     API_KEY_PEPPER: "dev-change-me-API_KEY_PEPPER"
     INTERNAL_SERVICE_TOKEN: "dev-change-me-INTERNAL_SERVICE_TOKEN"
-    MODEL_PROVIDER_KEY: "dev-change-me-MODEL_PROVIDER_KEY"
+    # BYOK model key (OPTIONAL — not boot-critical). Blank -> the worker runs the
+    # offline scripted model (see forge.modelProvider). Provider-agnostic fallback:
+    # ANTHROPIC_API_KEY / OPENAI_API_KEY take precedence if you set them instead.
+    FORGE_MODEL_API_KEY: ""
     # Bundled datastore credentials (used to build FORGE_DATABASE_URL / _REDIS_URL).
     POSTGRES_PASSWORD: "forge"
     REDIS_PASSWORD: ""
diff --git a/docs/FORGE_SPEC.md b/docs/FORGE_SPEC.md
index 182fae30..e155b001 100644
--- a/docs/FORGE_SPEC.md
+++ b/docs/FORGE_SPEC.md
@@ -867,7 +867,7 @@ sudo usermod -aG docker $USER && newgrp docker
 git clone https://github.com/QuintinBotes/forge
 cd forge
 cp .env.production.example .env.production
-# Fill in: SECRET_KEY, DB_PASSWORD, GITHUB_APP_*, MODEL_PROVIDER_KEY, DOMAIN
+# Fill in: SECRET_KEY, DB_PASSWORD, GITHUB_APP_*, FORGE_MODEL_PROVIDER + FORGE_MODEL_API_KEY (optional), DOMAIN
 
 docker compose -f docker-compose.yml --env-file .env.production up -d
 docker compose exec api forge-cli db migrate
diff --git a/docs/self-hosting/kubernetes.md b/docs/self-hosting/kubernetes.md
index 631d2c82..89715e44 100644
--- a/docs/self-hosting/kubernetes.md
+++ b/docs/self-hosting/kubernetes.md
@@ -55,10 +55,18 @@ helm install forge deploy/helm/forge -n forge \
   --set-string secrets.data.AUTH_SECRET="$(openssl rand -hex 32)" \
   --set-string secrets.data.API_KEY_PEPPER="$(openssl rand -hex 32)" \
   --set-string secrets.data.INTERNAL_SERVICE_TOKEN="$(openssl rand -hex 32)" \
-  --set-string secrets.data.MODEL_PROVIDER_KEY="$MODEL_KEY"
+  --set-string secrets.data.FORGE_MODEL_API_KEY="$MODEL_KEY"   # optional (see below)
 kubectl -n forge rollout status deploy/forge-api
 ```
 
+The BYOK model key is **optional**: `forge.modelProvider` (default `anthropic`)
+sets the master switch `FORGE_MODEL_PROVIDER`, and with
+`secrets.data.FORGE_MODEL_API_KEY` blank the worker runs the offline
+deterministic scripted model (canned output) and logs a warning each run. Set the
+key — and `forge.modelName` (required for `openai`) — to drive a real provider.
+`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` take precedence over `FORGE_MODEL_API_KEY`
+if you set them instead.
+
 The pre-install hook runs the Alembic chain (`alembic -c packages/db/alembic.ini
 upgrade head`, the same command as `make migrate`) to completion before any app
 pod serves traffic; readiness is gated on `/readyz`. Override `migrations.command`
@@ -147,9 +155,11 @@ sandbox:
 
 No secret value is ever rendered into a `ConfigMap`. The boot-critical keys
 (`SECRET_KEY`, `AUTH_SECRET`, `FORGE_VAULT_KEYS`, `API_KEY_PEPPER`,
-`INTERNAL_SERVICE_TOKEN`, `MODEL_PROVIDER_KEY`) are required — the chart fails
-fast at template time if any is missing, mirroring the application's fail-closed
-startup. `FORGE_VAULT_KEYS` is the AES-256-GCM envelope-vault master key (KEK)
+`INTERNAL_SERVICE_TOKEN`) are required — the chart fails fast at template time if
+any is missing, mirroring the application's fail-closed startup. The BYOK model
+key (`FORGE_MODEL_API_KEY`) is **not** boot-critical: the worker/api boot without
+it and fall back to the offline scripted model, so it is optional. `FORGE_VAULT_KEYS`
+is the AES-256-GCM envelope-vault master key (KEK)
 and is distinct from `SECRET_KEY`; store it in a managed secret store and rotate
 it with `forge-cli secrets rotate-key`. A Postgres restore of encrypted rows is
 useless without the same `FORGE_VAULT_KEYS` material. See
diff --git a/docs/self-hosting/quickstart.md b/docs/self-hosting/quickstart.md
index 079aa287..e4afbbc3 100644
--- a/docs/self-hosting/quickstart.md
+++ b/docs/self-hosting/quickstart.md
@@ -32,8 +32,10 @@ Edit `.env` and set, at minimum:
   detected and warned about — see `apps/api/forge_api/cli_secrets.py`.)
 - `POSTGRES_PASSWORD` and `MINIO_ROOT_PASSWORD` — strong unique secrets.
 - `DOMAIN` — the hostname Caddy will serve (use `localhost` for a local trial).
-- `MODEL_PROVIDER_KEY` — your BYOK model provider key (Forge is provider
-  agnostic; leave blank to run the platform without live model calls).
+- `FORGE_MODEL_PROVIDER` (`anthropic`|`openai`) plus a BYOK key
+  (`FORGE_MODEL_API_KEY`, or `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`) — Forge is
+  provider agnostic; leave `FORGE_MODEL_PROVIDER` unset to run the platform on the
+  offline scripted model (no live model calls).
 
 The full set of variables is documented inline in
 [../../.env.example](../../.env.example).
diff --git a/docs/self-hosting/troubleshooting.md b/docs/self-hosting/troubleshooting.md
index e9ab1643..1fbccdf5 100644
--- a/docs/self-hosting/troubleshooting.md
+++ b/docs/self-hosting/troubleshooting.md
@@ -103,8 +103,10 @@ often shows repeated restarts rather than a clean `exited`.
 - Confirm the indexer worker ran: `docker compose -f deploy/docker-compose.yml logs worker`.
 - Confirm chunks exist:
   `psql -U forge -d forge -c "select count(*) from retrieval_chunks;"`.
-- A blank `MODEL_PROVIDER_KEY`/`EMBEDDING_*` means no live embeddings are
-  produced; set BYOK keys to enable real retrieval.
+- Blank `EMBEDDING_*` config means no live embeddings are produced; set it to
+  enable real retrieval. Separately, with no `FORGE_MODEL_PROVIDER` + BYOK key
+  (`FORGE_MODEL_API_KEY`, or `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`) the worker runs
+  the offline scripted model — set those to enable live agent runs.
 
 ## Resource pressure
 

From 981522174889b71df2b026f9fbeac0e849e50c2d Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:36:07 +0200
Subject: [PATCH 22/47] fix(helm): render-contract test, blank-key install
 warning, provider enum

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/helm/forge/templates/NOTES.txt         |  8 +++++++
 .../tests/secret_config_separation_test.yaml  | 24 +++++++++++++++++++
 deploy/helm/forge/values.schema.json          |  2 +-
 deploy/helm/tests/test_render_contract.py     |  5 +++-
 docs/self-hosting/kubernetes.md               |  6 +++++
 5 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/deploy/helm/forge/templates/NOTES.txt b/deploy/helm/forge/templates/NOTES.txt
index b7fad0b2..9cb0e387 100644
--- a/deploy/helm/forge/templates/NOTES.txt
+++ b/deploy/helm/forge/templates/NOTES.txt
@@ -31,6 +31,14 @@ the application pods started.
 WARNING: this release rendered an in-chart Secret (secrets.create=true). For
 production, store secrets in an operator-managed Secret and set
 secrets.existingSecret instead. Never commit populated secret values to git.
+{{- $modelData := .Values.secrets.data | default dict }}
+{{- if not (or (get $modelData "FORGE_MODEL_API_KEY") (get $modelData "ANTHROPIC_API_KEY") (get $modelData "OPENAI_API_KEY")) }}
+
+WARNING: no model provider key configured — agent runs will use the
+offline scripted model (canned output, no network). Set the key via
+secrets.data.FORGE_MODEL_API_KEY, or point secrets.existingSecret at a
+Secret that carries it, to drive the real "{{ .Values.forge.modelProvider }}" provider.
+{{- end }}
 {{- end }}
 
 Datastores:
diff --git a/deploy/helm/forge/tests/secret_config_separation_test.yaml b/deploy/helm/forge/tests/secret_config_separation_test.yaml
index d7df9d08..2a920256 100644
--- a/deploy/helm/forge/tests/secret_config_separation_test.yaml
+++ b/deploy/helm/forge/tests/secret_config_separation_test.yaml
@@ -30,6 +30,30 @@ tests:
           path: data.FORGE_VAULT_KEYS
       - isNull:
           path: data.FORGE_DATABASE_URL
+  - it: the model-provider master switch renders in the ConfigMap (non-secret)
+    template: templates/configmap-env.yaml
+    asserts:
+      - isNotNull:
+          path: data.FORGE_MODEL_PROVIDER
+      - equal:
+          path: data.FORGE_MODEL_PROVIDER
+          value: anthropic
+      # The key MATERIAL never leaks into the ConfigMap (it is Secret-only).
+      - isNull:
+          path: data.FORGE_MODEL_API_KEY
+  - it: templates cleanly when the optional model key is blank (offline fallback)
+    template: templates/configmap-env.yaml
+    set:
+      secrets.data.FORGE_MODEL_API_KEY: ""
+    asserts:
+      # A blank model key is NOT boot-critical: rendering must NOT fail closed.
+      # A rendered ConfigMap (isKind) + a reachable key both prove the template
+      # rendered successfully — the fail-closed guard runs from this template, so
+      # any regression that treated the model key as boot-critical would error here.
+      - isKind:
+          of: ConfigMap
+      - isNotNull:
+          path: data.FORGE_MODEL_PROVIDER
   - it: fails closed when secrets.create=false and existingSecret is empty
     template: templates/worker/deployment.yaml
     set:
diff --git a/deploy/helm/forge/values.schema.json b/deploy/helm/forge/values.schema.json
index 805b1171..e130d658 100644
--- a/deploy/helm/forge/values.schema.json
+++ b/deploy/helm/forge/values.schema.json
@@ -90,7 +90,7 @@
         "domain": {"type": "string", "minLength": 3},
         "publicUrl": {"type": "string"},
         "logLevel": {"enum": ["debug", "info", "warning", "error"]},
-        "modelProvider": {"type": "string"},
+        "modelProvider": {"type": "string", "enum": ["anthropic", "openai"]},
         "modelName": {"type": "string"}
       }
     },
diff --git a/deploy/helm/tests/test_render_contract.py b/deploy/helm/tests/test_render_contract.py
index 3e15a5c9..68ee6ed8 100644
--- a/deploy/helm/tests/test_render_contract.py
+++ b/deploy/helm/tests/test_render_contract.py
@@ -101,9 +101,12 @@ def test_secret_and_config_keys_are_disjoint() -> None:
         "FORGE_VAULT_KEYS",
         "API_KEY_PEPPER",
         "INTERNAL_SERVICE_TOKEN",
-        "MODEL_PROVIDER_KEY",
     }
     assert boot <= sec_keys
+    # The BYOK model key lives in the Secret but is OPTIONAL (blank -> offline
+    # scripted model), so it is present-not-required: assert it renders as a key,
+    # but do NOT require a non-blank value (that would break the offline default).
+    assert "FORGE_MODEL_API_KEY" in sec_keys
     assert "FORGE_VAULT_ACTIVE_KEY_VERSION" in cm_keys
 
 
diff --git a/docs/self-hosting/kubernetes.md b/docs/self-hosting/kubernetes.md
index 89715e44..94ab341d 100644
--- a/docs/self-hosting/kubernetes.md
+++ b/docs/self-hosting/kubernetes.md
@@ -196,6 +196,12 @@ after it succeeds do the workloads roll. If the hook fails, the release does not
 roll — run `helm rollback forge <rev>`. Verify and bump image digests against the
 release notes before upgrading; see [upgrade.md](upgrade.md).
 
+> **Values rename (pre-1.0):** the dead `MODEL_PROVIDER` / `secrets.data.MODEL_PROVIDER_KEY`
+> values were replaced by `forge.modelProvider` (→ `FORGE_MODEL_PROVIDER`) and
+> `secrets.data.FORGE_MODEL_API_KEY`. Rename any `--set secrets.data.MODEL_PROVIDER_KEY=…`
+> to `FORGE_MODEL_API_KEY` before upgrading; a blank key falls back to the offline
+> scripted model (see the BYOK note above).
+
 ## Verification
 
 ```bash

From a8fcc5f67b22d0d24d5acf288e54c2a0ac19e5c1 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:46:16 +0200
Subject: [PATCH 23/47] fix(deploy): mcp-gateway edge network membership and
 websocket route parity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Item 1 (websocket routing through Caddy) — INVESTIGATED, real gap, fixed.
Outcome: the web client opens a BARE /ws (never /api/ws). The WS URL is built
purely from NEXT_PUBLIC_WS_URL (default ws://localhost:8000/ws) with no /api
prefix and no same-origin/window.location derivation
(apps/web/src/lib/realtime/use-board-realtime.ts:55-56,
use-spec-collab.ts:133-136); the API mounts them rootless
(apps/api/forge_api/main.py:138-140 -> routers/realtime.py:75,109). NEXT_PUBLIC_WS_URL
is set in no compose/env/Dockerfile/doc, so a same-origin operator value is
wss://<domain>/ws. The pre-fix Caddyfile had no /ws route, so bare /ws fell
through to the web:3000 catch-all -> realtime silently dead behind Caddy. Added
`handle /ws` + `handle /ws/spec/*` -> api:8000, mirroring deploy/nginx/forge.conf;
documented the canonical route + NEXT_PUBLIC_WS_URL contract in
docs/self-hosting/reverse-proxy.md.

Item 2 (mcp-gateway unreachable via proxies) — verified, fixed. mcp-gateway was
on [backend, mcp] while caddy is on [edge] only: no shared network, so /mcp/*
would 502. Added `edge` to mcp-gateway (now [edge, backend, mcp]; mcp/backend
preserved). docker-compose.dev.yml has no networks block (single default net),
so no gap there. `docker compose config -q` passes for both files; deploy/tests
green (103 passed, 2 pre-existing skips), incl. two new regression tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/caddy/Caddyfile                | 24 ++++++++++++++
 deploy/docker-compose.yml             |  6 ++++
 deploy/tests/test_compose_contract.py | 32 ++++++++++++++++++
 docs/self-hosting/reverse-proxy.md    | 48 +++++++++++++++------------
 4 files changed, 88 insertions(+), 22 deletions(-)

diff --git a/deploy/caddy/Caddyfile b/deploy/caddy/Caddyfile
index e1aa8193..d8d6ceca 100644
--- a/deploy/caddy/Caddyfile
+++ b/deploy/caddy/Caddyfile
@@ -46,6 +46,30 @@
 		reverse_proxy api:8000
 	}
 
+	# Realtime WebSockets (forge_api.routers.realtime): board push (`/ws`) and
+	# CRDT spec co-editing (`/ws/spec/{spec_id}`). These mount at the API app
+	# ROOT — `app.include_router(realtime_router)` with no prefix (see
+	# apps/api/forge_api/main.py) — so their path is a bare `/ws`, NOT `/api/ws`.
+	# The web client builds the URL from NEXT_PUBLIC_WS_URL (default
+	# `ws://localhost:8000/ws`, apps/web/src/lib/realtime/use-board-realtime.ts),
+	# a same-origin `/ws` path with no `/api` prefix and no window.location
+	# rewrite — so behind this edge an operator sets NEXT_PUBLIC_WS_URL to
+	# `wss://<DOMAIN>/ws`. Without these two blocks, `/ws` and `/ws/spec/*` fall
+	# through to the `web:3000` catch-all below and the socket hits Next.js
+	# instead of the API — realtime silently dead behind Caddy. `handle` (not
+	# `handle_path`) preserves the `/ws` prefix, which is where the API serves
+	# them. Caddy's reverse_proxy auto-detects the `Upgrade` header, so
+	# websockets need no extra directives here; the nginx equivalent
+	# (deploy/nginx/forge.conf `location = /ws` + `location /ws/spec/`) has to
+	# spell the upgrade + long-idle timeouts out by hand. These two are the
+	# canonical realtime routes for BOTH proxies (edge routing parity).
+	handle /ws {
+		reverse_proxy api:8000
+	}
+	handle /ws/spec/* {
+		reverse_proxy api:8000
+	}
+
 	# MCP gateway surface.
 	handle_path /mcp/* {
 		reverse_proxy mcp-gateway:8001
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 776766ed..56c94d03 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -338,6 +338,12 @@ services:
       db:
         condition: service_healthy
     networks:
+      # `edge` is load-bearing: the Caddy edge proxy (and the drop-in nginx
+      # alternative, deploy/nginx/forge.conf) sits ONLY on `edge` and routes
+      # /mcp/* -> mcp-gateway:8001. Without membership here the proxy and the
+      # gateway share no network, so /mcp/* resolves nowhere and 502s. `mcp`
+      # keeps the api/worker <-> gateway path; `backend` its other peers.
+      - edge
       - backend
       - mcp
     healthcheck:
diff --git a/deploy/tests/test_compose_contract.py b/deploy/tests/test_compose_contract.py
index 76e116ed..50d54ae7 100644
--- a/deploy/tests/test_compose_contract.py
+++ b/deploy/tests/test_compose_contract.py
@@ -194,6 +194,38 @@ def test_caddy_exposes_admin_gated_temporal_route() -> None:
     assert "temporal-ui:8080" in caddy
 
 
+# --------------------------------------------------------------------------- #
+# Task 24 — edge routing parity (mcp-gateway reachability + websocket routes)  #
+# --------------------------------------------------------------------------- #
+
+
+def test_mcp_gateway_on_edge_network_with_proxy() -> None:
+    """The edge proxy can reach mcp-gateway for /mcp/*.
+
+    Caddy (and the drop-in nginx alternative) sit only on `edge` and route
+    /mcp/* -> mcp-gateway:8001. If mcp-gateway is not also on `edge`, proxy and
+    gateway share no network and the route resolves nowhere (502). The mcp +
+    backend memberships (in-cluster api/worker paths) must be preserved.
+    """
+    mcp = _service("mcp-gateway")
+    caddy = _service("caddy")
+    assert "edge" in caddy["networks"], "caddy edge proxy must be on `edge`"
+    assert "edge" in mcp["networks"], "mcp-gateway must share `edge` with the proxy"
+    # Existing in-cluster networks preserved (not clobbered by the edge add).
+    assert "mcp" in mcp["networks"]
+    assert "backend" in mcp["networks"]
+
+
+def test_caddy_routes_realtime_websockets() -> None:
+    """The realtime board (/ws) and spec co-editing (/ws/spec/*) sockets mount at
+    the API app root (no /api prefix); the client opens a bare same-origin /ws,
+    so Caddy must route both to the API or they fall through to the web catch-all.
+    """
+    caddy = (DEPLOY / "caddy" / "Caddyfile").read_text(encoding="utf-8")
+    assert "handle /ws {" in caddy, "missing bare /ws board-push route"
+    assert "handle /ws/spec/* {" in caddy, "missing /ws/spec/* co-editing route"
+
+
 @pytest.mark.skipif(shutil.which("bash") is None, reason="bash not available")
 def test_preflight_rejects_old_engine(tmp_path: Path) -> None:
     """AC17 — preflight.sh fails on Docker Engine < 26.1 (stubbed version)."""
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
index 67fed453..c5684b05 100644
--- a/docs/self-hosting/reverse-proxy.md
+++ b/docs/self-hosting/reverse-proxy.md
@@ -37,22 +37,27 @@ from `docker-compose.yml`.
 | `/api/v1/integrations/alerts/*/webhook` | `handle` | `api:8000` | No (HMAC'd raw body) |
 | `/api/v1/integrations/pm/webhooks/*` | `handle` | `api:8000` | No (HMAC'd raw body) |
 | `/public/*` | `handle` | `api:8000` | No |
-| `/ws`, `/ws/spec/*` | *(none — see below)* | `api:8000` | No |
+| `/ws`, `/ws/spec/*` | `handle` | `api:8000` | No |
 | `/api/*` | `handle_path` | `api:8000` | Yes (`/api` stripped) |
 | `/mcp/*` | `handle_path` | `mcp-gateway:8001` | Yes (`/mcp` stripped) |
 | `/_temporal*` | `handle` + `basic_auth` | `temporal-ui:8080` | No |
 | `/grafana/*` | `handle` + `basic_auth` | `grafana:3000` | No |
 | everything else | `handle` (catch-all) | `web:3000` | No |
 
-The one deliberate addition: **`/ws` and `/ws/spec/{spec_id}`** (the board-push
-and CRDT spec-co-editing websocket channels, `forge_api.routers.realtime`)
-mount at the API app root, not under `/api` (see
-[architecture.md](../architecture.md#trust-layer--provenance)). The Caddyfile
-has no dedicated `handle` block for either path today, so without one both
-would silently fall through to the catch-all `web:3000` route — wrong, since
-neither socket exists on the frontend. `forge.conf` routes them to `api:8000`
-explicitly; the same gap is worth closing in the Caddyfile too (flagged, not
-fixed here — out of this change's scope).
+**`/ws` and `/ws/spec/{spec_id}`** (the board-push and CRDT spec-co-editing
+websocket channels, `forge_api.routers.realtime`) mount at the API app **root**,
+not under `/api` — `app.include_router(realtime_router)` with no prefix (see
+`apps/api/forge_api/main.py`). The web client builds the socket URL from
+`NEXT_PUBLIC_WS_URL` (default `ws://localhost:8000/ws`, see
+`apps/web/src/lib/realtime/use-board-realtime.ts`): a same-origin **`/ws`** path
+with no `/api` prefix and no `window.location` rewrite. So behind either proxy
+you set `NEXT_PUBLIC_WS_URL=wss://<your-domain>/ws` (the same-origin analogue of
+`NEXT_PUBLIC_API_URL=/api`), and the edge must route that bare `/ws` to the API.
+Both proxies now do: the Caddyfile has explicit `handle /ws` + `handle /ws/spec/*`
+blocks and `forge.conf` has `location = /ws` + `location /ws/spec/`, each
+proxying to `api:8000`. Without them, `/ws` falls through to the catch-all
+`web:3000` route — wrong, since neither socket exists on the frontend — and
+realtime is silently dead behind the proxy.
 
 ### Websocket and streaming requirements
 
@@ -118,15 +123,14 @@ fixed here — out of this change's scope).
   htpasswd -c /etc/nginx/secrets/grafana.htpasswd admin
   ```
 
-- **Network reachability (pre-existing, not introduced by this file):**
-  `docker-compose.yml`'s `mcp-gateway` service is only on the `backend` and
-  `mcp` networks — not `edge`, the network the `caddy` service (and any
-  drop-in nginx replacement) is on. As shipped, neither proxy can actually
-  reach `mcp-gateway:8001` for the `/mcp/*` route without also adding the edge
-  proxy container to the `mcp` network. This is a `docker-compose.yml`
-  topology question, out of scope for this doc/config (only `forge.conf`,
-  this file, and a `quickstart.md` link were in scope) — flag it before
-  relying on `/mcp/*` in production with either proxy.
+- **Network reachability:** the edge proxy reaches `mcp-gateway:8001` for the
+  `/mcp/*` route because `docker-compose.yml`'s `mcp-gateway` service is on the
+  `edge` network alongside the `caddy` service (and any drop-in nginx
+  replacement, which is also on `edge`). It keeps its `backend` + `mcp`
+  membership for the in-cluster api/worker paths. If you swap in your own edge
+  network topology, make sure the proxy container and `mcp-gateway` still share
+  a network, or `/mcp/*` will 502 (the gateway resolves nowhere from the
+  proxy's networks).
 
 ### Health checks
 
@@ -162,6 +166,6 @@ docker run --rm -v "$PWD/deploy/nginx/forge.conf:/etc/nginx/conf.d/forge.conf:ro
 
 This checks config syntax and routing logic only (see `forge.conf`'s header
 comment for exactly what was and wasn't exercised) — it does not stand up the
-real Forge services, so it can't catch things like the network-reachability
-gap noted above. Confirm end-to-end behavior against a running stack before
-trusting either proxy in production.
+real Forge services, so it can't catch a runtime issue like a proxy and an
+upstream landing on different networks. Confirm end-to-end behavior against a
+running stack before trusting either proxy in production.

From 9322dc78af0fc4bfb486b518cf675cbb6a2eb50e Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 01:55:29 +0200
Subject: [PATCH 24/47] fix(deploy): assert ws proxy upstream in tests;
 document proxied github webhook url

---
 deploy/tests/test_compose_contract.py | 26 ++++++++++++++++++++++++++
 docs/runbooks/live-github.md          | 14 ++++++++++++++
 docs/self-hosting/reverse-proxy.md    | 10 ++++++++++
 3 files changed, 50 insertions(+)

diff --git a/deploy/tests/test_compose_contract.py b/deploy/tests/test_compose_contract.py
index 50d54ae7..c8429c8a 100644
--- a/deploy/tests/test_compose_contract.py
+++ b/deploy/tests/test_compose_contract.py
@@ -216,6 +216,28 @@ def test_mcp_gateway_on_edge_network_with_proxy() -> None:
     assert "backend" in mcp["networks"]
 
 
+def _caddy_block(caddy: str, header: str) -> str:
+    """Return the text span of a Caddyfile block, from ``header`` (e.g.
+    ``"handle /ws {"``) through its matching closing brace.
+
+    ``api:8000`` (unlike ``temporal-ui:8080`` in the sibling test above) appears
+    as the upstream of several unrelated blocks in this file (``/api/*``,
+    ``/public/*``, the webhook routes, ...), so a bare file-wide substring check
+    would pass even if these specific blocks proxied somewhere else entirely.
+    Scoping the assertion to the block's own text span keeps it meaningful.
+    """
+    start = caddy.index(header)
+    depth = 0
+    for i in range(start, len(caddy)):
+        if caddy[i] == "{":
+            depth += 1
+        elif caddy[i] == "}":
+            depth -= 1
+            if depth == 0:
+                return caddy[start : i + 1]
+    raise AssertionError(f"unterminated block for {header!r}")
+
+
 def test_caddy_routes_realtime_websockets() -> None:
     """The realtime board (/ws) and spec co-editing (/ws/spec/*) sockets mount at
     the API app root (no /api prefix); the client opens a bare same-origin /ws,
@@ -224,6 +246,10 @@ def test_caddy_routes_realtime_websockets() -> None:
     caddy = (DEPLOY / "caddy" / "Caddyfile").read_text(encoding="utf-8")
     assert "handle /ws {" in caddy, "missing bare /ws board-push route"
     assert "handle /ws/spec/* {" in caddy, "missing /ws/spec/* co-editing route"
+    assert "api:8000" in _caddy_block(caddy, "handle /ws {"), "/ws must proxy to api:8000"
+    assert "api:8000" in _caddy_block(
+        caddy, "handle /ws/spec/* {"
+    ), "/ws/spec/* must proxy to api:8000"
 
 
 @pytest.mark.skipif(shutil.which("bash") is None, reason="bash not available")
diff --git a/docs/runbooks/live-github.md b/docs/runbooks/live-github.md
index 405d921d..05ca4888 100644
--- a/docs/runbooks/live-github.md
+++ b/docs/runbooks/live-github.md
@@ -96,6 +96,20 @@ behaviour (200 on a valid signature, 401 on a tamper) with a signed envelope, an
 proves the **HMAC primitive** on the actual delivered bytes. Raw-payload
 ingestion is an F03 concern, out of scope for HARD-01.
 
+**Webhook delivery URL (configure this in the GitHub App):** the path above is
+the API's *internal* route — `api_prefix` defaults to empty, so the router
+serves it bare. Behind the edge proxy (Caddy's `handle_path /api/*` /
+`forge.conf`'s `location /api/`, see
+[docs/self-hosting/reverse-proxy.md](../self-hosting/reverse-proxy.md)), only
+the `/api`-prefixed path is externally reachable — the bare path falls through
+to the web frontend's catch-all route. Set the GitHub App's **Webhook URL** to:
+
+```
+https://<DOMAIN>/api/integration/github/webhooks
+```
+
+(internally the API serves this at `POST /integration/github/webhooks`).
+
 ## 6. Docker Compose (production wiring)
 
 `deploy/docker-compose.yml` mounts the key **read-only** and passes the
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
index c5684b05..d23c77af 100644
--- a/docs/self-hosting/reverse-proxy.md
+++ b/docs/self-hosting/reverse-proxy.md
@@ -36,6 +36,7 @@ from `docker-compose.yml`.
 |---|---|---|---|
 | `/api/v1/integrations/alerts/*/webhook` | `handle` | `api:8000` | No (HMAC'd raw body) |
 | `/api/v1/integrations/pm/webhooks/*` | `handle` | `api:8000` | No (HMAC'd raw body) |
+| `/api/integration/github/webhooks` | `handle_path` (via `/api/*`) | `api:8000` | Yes (`/api` stripped; see below) |
 | `/public/*` | `handle` | `api:8000` | No |
 | `/ws`, `/ws/spec/*` | `handle` | `api:8000` | No |
 | `/api/*` | `handle_path` | `api:8000` | Yes (`/api` stripped) |
@@ -44,6 +45,15 @@ from `docker-compose.yml`.
 | `/grafana/*` | `handle` + `basic_auth` | `grafana:3000` | No |
 | everything else | `handle` (catch-all) | `web:3000` | No |
 
+**`/api/integration/github/webhooks`** (the GitHub App webhook ingress,
+`forge_api.routers.integration`) is not a dedicated `handle` block like the
+alerts/PM webhook rows above — it rides the generic `/api/*` prefix-stripped
+route, because `api_prefix` defaults to empty and the router already mounts
+the path at `/integration/github/webhooks` internally. Configure the GitHub
+App's Webhook URL as `https://<domain>/api/integration/github/webhooks` (see
+[docs/runbooks/live-github.md](../runbooks/live-github.md)) — the bare,
+un-prefixed path is not externally reachable behind either proxy.
+
 **`/ws` and `/ws/spec/{spec_id}`** (the board-push and CRDT spec-co-editing
 websocket channels, `forge_api.routers.realtime`) mount at the API app **root**,
 not under `/api` — `app.include_router(realtime_router)` with no prefix (see

From 1fb5c2e88ee43c4c2e9145d9e1f9cb804fd40789 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 02:07:54 +0200
Subject: [PATCH 25/47] fix(web): derive same-origin websocket url when
 NEXT_PUBLIC_WS_URL unset

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .env.example                                  |   8 ++
 .../src/lib/realtime/use-board-realtime.ts    |   7 +-
 apps/web/src/lib/realtime/use-spec-collab.ts  |  15 +-
 apps/web/src/lib/realtime/ws-url.test.ts      | 134 ++++++++++++++++++
 apps/web/src/lib/realtime/ws-url.ts           |  90 ++++++++++++
 docs/self-hosting/reverse-proxy.md            |  19 ++-
 6 files changed, 255 insertions(+), 18 deletions(-)
 create mode 100644 apps/web/src/lib/realtime/ws-url.test.ts
 create mode 100644 apps/web/src/lib/realtime/ws-url.ts

diff --git a/.env.example b/.env.example
index 97031a0b..30f2612a 100644
--- a/.env.example
+++ b/.env.example
@@ -191,6 +191,14 @@ FORGE_SANDBOX_MAX_TTL_SECONDS=21600
 API_URL=http://localhost:8000
 MCP_GATEWAY_URL=http://localhost:8001
 NEXT_PUBLIC_API_URL=http://localhost:8000
+# Realtime (board push + spec co-editing) WebSocket endpoint. Inlined into the
+# web bundle at BUILD time (NEXT_PUBLIC_*). Leave UNSET for the common cases:
+# the client auto-derives a same-origin `wss://<page-host>/ws` in the browser
+# (which the edge routes to the API — see docs/self-hosting/reverse-proxy.md),
+# and keeps `ws://localhost:8000/ws` on the local `next dev` server (:3000).
+# Set it ONLY when the WS endpoint is NOT same-origin (e.g. a dedicated realtime
+# host), and set it as a BUILD arg — a runtime env var alone is too late.
+# NEXT_PUBLIC_WS_URL=wss://forge.example.com/ws
 
 # MCP sync-and-index (F20) — periodic ingestion of MCP resources into the index.
 MCP_INDEX_POLL_SECONDS=300
diff --git a/apps/web/src/lib/realtime/use-board-realtime.ts b/apps/web/src/lib/realtime/use-board-realtime.ts
index 3ada290c..94918f0a 100644
--- a/apps/web/src/lib/realtime/use-board-realtime.ts
+++ b/apps/web/src/lib/realtime/use-board-realtime.ts
@@ -14,6 +14,8 @@ import { useEffect, useState } from "react";
 
 import { apiClient } from "@/lib/api/client";
 
+import { resolveBoardWsUrl } from "./ws-url";
+
 /** Minimal structural type for the bits of `WebSocket` this hook uses. */
 export interface WebSocketLike {
   readyState: number;
@@ -52,9 +54,6 @@ export interface BoardRealtimeState {
   connected: boolean;
 }
 
-export const DEFAULT_WS_URL =
-  process.env.NEXT_PUBLIC_WS_URL ?? "ws://localhost:8000/ws";
-
 /**
  * Append `?token=` to a WS URL for the server's WS auth dependency (query
  * param, since WS upgrade requests can't carry an `Authorization` header).
@@ -110,7 +109,7 @@ export function useBoardRealtime(
   options: UseBoardRealtimeOptions = {},
 ): BoardRealtimeState {
   const {
-    url = DEFAULT_WS_URL,
+    url = resolveBoardWsUrl(),
     enabled = true,
     token = apiClient.token,
     socketFactory,
diff --git a/apps/web/src/lib/realtime/use-spec-collab.ts b/apps/web/src/lib/realtime/use-spec-collab.ts
index 5e357879..a34c6a19 100644
--- a/apps/web/src/lib/realtime/use-spec-collab.ts
+++ b/apps/web/src/lib/realtime/use-spec-collab.ts
@@ -23,6 +23,8 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { WebsocketProvider } from "y-websocket";
 import * as Y from "yjs";
 
+import { resolveSpecWsBaseUrl } from "./ws-url";
+
 /** The two CRDT-synced spec surfaces; each is a named `Y.Text` in the doc. */
 export type SpecCollabField = "markdown" | "yaml";
 
@@ -98,7 +100,11 @@ export interface UseSpecCollabOptions {
   enabled?: boolean;
   /** Bearer token forwarded as the `?token=` query param (WS auth). */
   token?: string;
-  /** Base WS URL; defaults to `NEXT_PUBLIC_SPEC_WS_URL` → `/ws/spec`. */
+  /**
+   * Base WS URL. Defaults to `NEXT_PUBLIC_SPEC_WS_URL` → `NEXT_PUBLIC_WS_URL`
+   * (`/ws`→`/ws/spec`) → the same-origin `/ws/spec` derived from the page's
+   * `window.location` (see `resolveSpecWsBaseUrl`).
+   */
   baseUrl?: string;
   /** Local editor identity for presence. */
   user?: CollabUser;
@@ -130,11 +136,6 @@ export interface SpecCollabState {
   peers: CollabPeer[];
 }
 
-export const DEFAULT_SPEC_WS_URL =
-  process.env.NEXT_PUBLIC_SPEC_WS_URL ??
-  process.env.NEXT_PUBLIC_WS_URL?.replace(/\/ws$/, "/ws/spec") ??
-  "ws://localhost:8000/ws/spec";
-
 /** Number of slots in the categorical chart ramp (`--chart-1..6`). */
 const CHART_SLOTS = 6;
 
@@ -212,7 +213,7 @@ export function useSpecCollab(
     field,
     enabled = true,
     token,
-    baseUrl = DEFAULT_SPEC_WS_URL,
+    baseUrl = resolveSpecWsBaseUrl(),
     user,
     seedText,
     providerFactory,
diff --git a/apps/web/src/lib/realtime/ws-url.test.ts b/apps/web/src/lib/realtime/ws-url.test.ts
new file mode 100644
index 00000000..ffdb4a17
--- /dev/null
+++ b/apps/web/src/lib/realtime/ws-url.test.ts
@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  resolveBoardWsUrl,
+  resolveSpecWsBaseUrl,
+  sameOriginWsUrl,
+} from "./ws-url";
+
+/** Point `window.location` at a fake origin for the duration of one test. */
+function stubLocation(loc: {
+  protocol: string;
+  host: string;
+  hostname: string;
+  port: string;
+}) {
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    writable: true,
+    value: loc,
+  });
+}
+
+const ORIGINAL_LOCATION = window.location;
+
+afterEach(() => {
+  // Restore the real global bindings first (an SSR test may have unset
+  // `window`), *then* restore the original jsdom location on it.
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    writable: true,
+    value: ORIGINAL_LOCATION,
+  });
+});
+
+describe("sameOriginWsUrl", () => {
+  it("derives a wss same-origin URL on an https page", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+    });
+    expect(sameOriginWsUrl("/ws")).toBe("wss://forge.example.com/ws");
+  });
+
+  it("derives a ws same-origin URL on an http non-localhost page", () => {
+    stubLocation({
+      protocol: "http:",
+      host: "forge.internal:8080",
+      hostname: "forge.internal",
+      port: "8080",
+    });
+    expect(sameOriginWsUrl("/ws")).toBe("ws://forge.internal:8080/ws");
+  });
+
+  it("keeps the legacy dev default on the Next dev server (localhost:3000)", () => {
+    stubLocation({
+      protocol: "http:",
+      host: "localhost:3000",
+      hostname: "localhost",
+      port: "3000",
+    });
+    expect(sameOriginWsUrl("/ws")).toBe("ws://localhost:8000/ws");
+  });
+
+  it("still derives same-origin for a full stack served on localhost via the proxy (port 80)", () => {
+    // The full compose stack fronts the app with Caddy on :80/:443, where
+    // same-origin /ws IS routed to the API — only the :3000 dev web server is
+    // the exception.
+    stubLocation({
+      protocol: "http:",
+      host: "localhost",
+      hostname: "localhost",
+      port: "",
+    });
+    expect(sameOriginWsUrl("/ws")).toBe("ws://localhost/ws");
+  });
+
+  it("returns the static default in SSR / non-browser contexts", () => {
+    vi.stubGlobal("window", undefined);
+    expect(sameOriginWsUrl("/ws")).toBe("ws://localhost:8000/ws");
+  });
+});
+
+describe("resolveBoardWsUrl", () => {
+  it("uses NEXT_PUBLIC_WS_URL verbatim when set (operator override wins)", () => {
+    vi.stubEnv("NEXT_PUBLIC_WS_URL", "wss://ws.example.com/custom/ws");
+    expect(resolveBoardWsUrl()).toBe("wss://ws.example.com/custom/ws");
+  });
+
+  it("derives same-origin /ws when NEXT_PUBLIC_WS_URL is unset", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+    });
+    expect(resolveBoardWsUrl()).toBe("wss://forge.example.com/ws");
+  });
+});
+
+describe("resolveSpecWsBaseUrl", () => {
+  it("uses NEXT_PUBLIC_SPEC_WS_URL verbatim when set", () => {
+    vi.stubEnv("NEXT_PUBLIC_SPEC_WS_URL", "wss://ws.example.com/spec-base");
+    expect(resolveSpecWsBaseUrl()).toBe("wss://ws.example.com/spec-base");
+  });
+
+  it("derives /ws/spec from NEXT_PUBLIC_WS_URL when only it is set (byte-identical to legacy)", () => {
+    vi.stubEnv("NEXT_PUBLIC_WS_URL", "wss://forge.example.com/ws");
+    expect(resolveSpecWsBaseUrl()).toBe("wss://forge.example.com/ws/spec");
+  });
+
+  it("derives a same-origin /ws/spec base on an https page when no override is set", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+    });
+    expect(resolveSpecWsBaseUrl()).toBe("wss://forge.example.com/ws/spec");
+  });
+
+  it("keeps the legacy dev base on the Next dev server (localhost:3000)", () => {
+    stubLocation({
+      protocol: "http:",
+      host: "localhost:3000",
+      hostname: "localhost",
+      port: "3000",
+    });
+    expect(resolveSpecWsBaseUrl()).toBe("ws://localhost:8000/ws/spec");
+  });
+});
diff --git a/apps/web/src/lib/realtime/ws-url.ts b/apps/web/src/lib/realtime/ws-url.ts
new file mode 100644
index 00000000..b5e903b2
--- /dev/null
+++ b/apps/web/src/lib/realtime/ws-url.ts
@@ -0,0 +1,90 @@
+/**
+ * Runtime resolution of the Forge realtime WebSocket URL(s).
+ *
+ * Next.js inlines `NEXT_PUBLIC_*` at **build** time, and nothing plumbs
+ * `NEXT_PUBLIC_WS_URL` (the `web` image takes no such build arg — see
+ * `deploy/docker/web.Dockerfile`). A deployed instance behind Caddy/nginx would
+ * therefore fall back to the hardcoded `ws://localhost:8000/ws`, which is dead in
+ * a browser hitting `https://forge.example.com`. These helpers instead derive the
+ * socket URL from `window.location` at **runtime**, so realtime targets the same
+ * origin the page was served from — which the edge routes to the API (see
+ * `docs/self-hosting/reverse-proxy.md`). An explicit `NEXT_PUBLIC_WS_URL` set at
+ * build time still wins verbatim.
+ *
+ * This follows `apps/web/src/lib/api/client.ts`'s precedence (operator env wins,
+ * else a safe default) but goes one step further: `client.ts` does no
+ * `window.location` derivation — it leans on a relative `NEXT_PUBLIC_API_URL=/api`
+ * being present at build time. The WS endpoint has no such build-time value, so
+ * it must be derived from the live origin instead.
+ */
+
+/**
+ * Static default origin (scheme + host) used in SSR / non-browser contexts and
+ * on the local Next dev server (see below). Matches the legacy hardcoded default
+ * and `client.ts`'s `http://localhost:8000` fallback: in dev the API listens on
+ * :8000 while the web dev server runs on :3000.
+ */
+const LEGACY_WS_ORIGIN = "ws://localhost:8000";
+
+/** Loopback hosts that identify a local origin. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/**
+ * Port the local Next web server listens on (`next dev` / standalone `next
+ * start`, `deploy/docker/web*.Dockerfile`, `.env.dev` `WEB_PORT`). The full
+ * compose stack, by contrast, fronts the app with Caddy on :80/:443, where
+ * same-origin `/ws` IS routed to the API — so only the dev web server is the
+ * exception below.
+ */
+const DEV_WEB_PORT = "3000";
+
+/**
+ * True when the page is served by the local Next web server (loopback host on
+ * :3000), whose same-origin has no `/ws` route — so we keep the legacy API
+ * origin (`ws://localhost:8000`) rather than pointing the socket at the dead
+ * `ws://localhost:3000/ws`.
+ */
+function isLocalDevWebServer(hostname: string, port: string): boolean {
+  return LOOPBACK_HOSTS.has(hostname) && port === DEV_WEB_PORT;
+}
+
+/**
+ * Derive the WebSocket URL for a root `path` (e.g. `/ws`, `/ws/spec`) when no
+ * operator override is set:
+ *   - Browser: same-origin — `wss://` on an https page, `ws://` otherwise —
+ *     EXCEPT on the local Next dev server, which keeps the legacy dev origin.
+ *   - SSR / non-browser: the legacy static default (current behavior).
+ */
+export function sameOriginWsUrl(path: string): string {
+  if (typeof window === "undefined") {
+    return `${LEGACY_WS_ORIGIN}${path}`;
+  }
+  const { protocol, host, hostname, port } = window.location;
+  if (isLocalDevWebServer(hostname, port)) {
+    return `${LEGACY_WS_ORIGIN}${path}`;
+  }
+  const scheme = protocol === "https:" ? "wss:" : "ws:";
+  return `${scheme}//${host}${path}`;
+}
+
+/**
+ * Board-push socket URL (`/ws`). `NEXT_PUBLIC_WS_URL` (build-time inlined) wins
+ * verbatim — byte-identical to the legacy behavior for anyone who set it.
+ */
+export function resolveBoardWsUrl(): string {
+  return process.env.NEXT_PUBLIC_WS_URL ?? sameOriginWsUrl("/ws");
+}
+
+/**
+ * Spec co-editing base URL (`/ws/spec`; the room = spec id is appended by the
+ * provider). Preserves the hook's existing env precedence exactly:
+ * `NEXT_PUBLIC_SPEC_WS_URL` → `NEXT_PUBLIC_WS_URL` with `/ws`→`/ws/spec` →
+ * same-origin derivation.
+ */
+export function resolveSpecWsBaseUrl(): string {
+  return (
+    process.env.NEXT_PUBLIC_SPEC_WS_URL ??
+    process.env.NEXT_PUBLIC_WS_URL?.replace(/\/ws$/, "/ws/spec") ??
+    sameOriginWsUrl("/ws/spec")
+  );
+}
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
index d23c77af..f6c8ba46 100644
--- a/docs/self-hosting/reverse-proxy.md
+++ b/docs/self-hosting/reverse-proxy.md
@@ -57,13 +57,18 @@ un-prefixed path is not externally reachable behind either proxy.
 **`/ws` and `/ws/spec/{spec_id}`** (the board-push and CRDT spec-co-editing
 websocket channels, `forge_api.routers.realtime`) mount at the API app **root**,
 not under `/api` — `app.include_router(realtime_router)` with no prefix (see
-`apps/api/forge_api/main.py`). The web client builds the socket URL from
-`NEXT_PUBLIC_WS_URL` (default `ws://localhost:8000/ws`, see
-`apps/web/src/lib/realtime/use-board-realtime.ts`): a same-origin **`/ws`** path
-with no `/api` prefix and no `window.location` rewrite. So behind either proxy
-you set `NEXT_PUBLIC_WS_URL=wss://<your-domain>/ws` (the same-origin analogue of
-`NEXT_PUBLIC_API_URL=/api`), and the edge must route that bare `/ws` to the API.
-Both proxies now do: the Caddyfile has explicit `handle /ws` + `handle /ws/spec/*`
+`apps/api/forge_api/main.py`). The web client opens a bare same-origin **`/ws`**
+path — no `/api` prefix. It **auto-derives** the URL from the page's
+`window.location` at runtime (`wss://<page-host>/ws` on an https page, `ws://`
+otherwise; see `apps/web/src/lib/realtime/ws-url.ts`), so behind either proxy
+realtime works over the same origin as the page with no configuration — the edge
+only has to route that bare `/ws` to the API. To point realtime at a
+non-same-origin endpoint, override with `NEXT_PUBLIC_WS_URL=wss://<host>/ws` as a
+**build** arg (it is inlined into the web bundle at build time, like
+`NEXT_PUBLIC_API_URL`); leave it unset for the same-origin default. (The local
+`next dev` server on :3000 serves no `/ws`, so the client keeps
+`ws://localhost:8000/ws` there.) The edge must still route bare `/ws` to the API,
+and both proxies now do: the Caddyfile has explicit `handle /ws` + `handle /ws/spec/*`
 blocks and `forge.conf` has `location = /ws` + `location /ws/spec/`, each
 proxying to `api:8000`. Without them, `/ws` falls through to the catch-all
 `web:3000` route — wrong, since neither socket exists on the frontend — and

From a964e95f51621634244e69516cde117bcfab8b44 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 02:28:03 +0200
Subject: [PATCH 26/47] fix(web): resolve api base url same-origin when
 NEXT_PUBLIC_API_URL is unset or relative

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .env.example                         |  11 +-
 apps/web/next.config.mjs             |  14 +-
 apps/web/src/lib/api/api-url.test.ts | 204 +++++++++++++++++++++++++++
 apps/web/src/lib/api/api-url.ts      | 126 +++++++++++++++++
 apps/web/src/lib/api/client.ts       |  27 +++-
 deploy/docker-compose.yml            |   8 +-
 docs/self-hosting/reverse-proxy.md   |   9 ++
 7 files changed, 389 insertions(+), 10 deletions(-)
 create mode 100644 apps/web/src/lib/api/api-url.test.ts
 create mode 100644 apps/web/src/lib/api/api-url.ts

diff --git a/.env.example b/.env.example
index 30f2612a..79b1c2cc 100644
--- a/.env.example
+++ b/.env.example
@@ -190,7 +190,16 @@ FORGE_SANDBOX_MAX_TTL_SECONDS=21600
 # Service URLs (used by web / inter-service calls)
 API_URL=http://localhost:8000
 MCP_GATEWAY_URL=http://localhost:8001
-NEXT_PUBLIC_API_URL=http://localhost:8000
+# Browser REST API base. Inlined into the web bundle at BUILD time (NEXT_PUBLIC_*),
+# so a runtime env var is too late for the client. Leave UNSET for the common
+# cases: the client auto-derives a same-origin `https://<page-host>/api` in the
+# browser (the edge strips `/api` and routes it to the API — see
+# docs/self-hosting/reverse-proxy.md), and keeps `http://localhost:8000` on the
+# local `next dev` server (:3000). Set it ONLY when the API is NOT same-origin —
+# an absolute value (e.g. `https://api.example.com`) is used verbatim, a relative
+# value (e.g. `/api`) resolves against the page origin — and set it as a BUILD
+# arg; a runtime env var alone is too late.
+# NEXT_PUBLIC_API_URL=http://localhost:8000
 # Realtime (board push + spec co-editing) WebSocket endpoint. Inlined into the
 # web bundle at BUILD time (NEXT_PUBLIC_*). Leave UNSET for the common cases:
 # the client auto-derives a same-origin `wss://<page-host>/ws` in the browser
diff --git a/apps/web/next.config.mjs b/apps/web/next.config.mjs
index 7d3432fb..50ebfadb 100644
--- a/apps/web/next.config.mjs
+++ b/apps/web/next.config.mjs
@@ -30,10 +30,16 @@ const nextConfig = {
   output: "standalone",
   // Note: Next.js 16 removed the built-in ESLint integration (`next lint` and the
   // `eslint` config key). Linting now runs via `pnpm lint` (eslint.config.mjs).
-  // Surface the API base URL to the typed client at build time when provided.
-  env: {
-    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000",
-  },
+  //
+  // `NEXT_PUBLIC_API_URL` is intentionally NOT declared in an `env:` block. Next
+  // already inlines any `process.env.NEXT_PUBLIC_*` reference at build time from
+  // the build environment (a build arg wins; unset → `undefined`), exactly like
+  // `NEXT_PUBLIC_WS_URL`. Forcing a `?? "http://localhost:8000"` default here (as
+  // this block used to) would inline that literal into every bundle — a truthy,
+  // absolute value — so the client could never tell "unset" from "localhost", and
+  // the same-origin fallback in src/lib/api/api-url.ts would be dead code. Leaving
+  // it unset lets an un-configured build derive a same-origin `/api` base at
+  // runtime in the browser (see api-url.ts + docs/self-hosting/reverse-proxy.md).
   // HARD-09: apply the hardening headers to every route.
   async headers() {
     return [{ source: "/:path*", headers: securityHeaders }];
diff --git a/apps/web/src/lib/api/api-url.test.ts b/apps/web/src/lib/api/api-url.test.ts
new file mode 100644
index 00000000..e84c9ed8
--- /dev/null
+++ b/apps/web/src/lib/api/api-url.test.ts
@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { ForgeApiClient } from "./client";
+import {
+  resolveApiBaseUrl,
+  sameOriginApiBaseUrl,
+  toAbsoluteApiBase,
+} from "./api-url";
+
+/** Point `window.location` at a fake origin for the duration of one test. */
+function stubLocation(loc: {
+  protocol: string;
+  host: string;
+  hostname: string;
+  port: string;
+  origin: string;
+}) {
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    writable: true,
+    value: loc,
+  });
+}
+
+const ORIGINAL_LOCATION = window.location;
+
+afterEach(() => {
+  // Restore the real global bindings first (an SSR test may have unset
+  // `window`), *then* restore the original jsdom location on it.
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    writable: true,
+    value: ORIGINAL_LOCATION,
+  });
+});
+
+describe("sameOriginApiBaseUrl", () => {
+  it("derives a same-origin /api base on an https page", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    expect(sameOriginApiBaseUrl()).toBe("https://forge.example.com/api");
+  });
+
+  it("derives a same-origin /api base on an http non-localhost page", () => {
+    stubLocation({
+      protocol: "http:",
+      host: "forge.internal:8080",
+      hostname: "forge.internal",
+      port: "8080",
+      origin: "http://forge.internal:8080",
+    });
+    expect(sameOriginApiBaseUrl()).toBe("http://forge.internal:8080/api");
+  });
+
+  it("keeps the legacy dev default on the Next dev server (localhost:3000)", () => {
+    // The :3000 dev web server serves no /api route — the API listens on :8000.
+    stubLocation({
+      protocol: "http:",
+      host: "localhost:3000",
+      hostname: "localhost",
+      port: "3000",
+      origin: "http://localhost:3000",
+    });
+    expect(sameOriginApiBaseUrl()).toBe("http://localhost:8000");
+  });
+
+  it("still derives same-origin /api for a full stack served on localhost via the proxy (port 80)", () => {
+    // The full compose stack fronts the app with Caddy on :80/:443, where
+    // same-origin /api IS routed to the API — only the :3000 dev web server is
+    // the exception.
+    stubLocation({
+      protocol: "http:",
+      host: "localhost",
+      hostname: "localhost",
+      port: "",
+      origin: "http://localhost",
+    });
+    expect(sameOriginApiBaseUrl()).toBe("http://localhost/api");
+  });
+
+  it("returns the static default in SSR / non-browser contexts", () => {
+    vi.stubGlobal("window", undefined);
+    expect(sameOriginApiBaseUrl()).toBe("http://localhost:8000");
+  });
+});
+
+describe("resolveApiBaseUrl", () => {
+  it("uses an ABSOLUTE NEXT_PUBLIC_API_URL verbatim (operator override wins, byte-identical)", () => {
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.example.com");
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    expect(resolveApiBaseUrl()).toBe("https://api.example.com");
+  });
+
+  it("resolves a RELATIVE NEXT_PUBLIC_API_URL against the page origin in the browser", () => {
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "/api");
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    expect(resolveApiBaseUrl()).toBe("https://forge.example.com/api");
+  });
+
+  it("resolves a RELATIVE NEXT_PUBLIC_API_URL against the static origin in SSR (no throw)", () => {
+    vi.stubGlobal("window", undefined);
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "/api");
+    expect(resolveApiBaseUrl()).toBe("http://localhost:8000/api");
+  });
+
+  it("derives same-origin /api when NEXT_PUBLIC_API_URL is unset (browser https)", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    expect(resolveApiBaseUrl()).toBe("https://forge.example.com/api");
+  });
+
+  it("keeps the legacy dev default when unset on the Next dev server (localhost:3000)", () => {
+    stubLocation({
+      protocol: "http:",
+      host: "localhost:3000",
+      hostname: "localhost",
+      port: "3000",
+      origin: "http://localhost:3000",
+    });
+    expect(resolveApiBaseUrl()).toBe("http://localhost:8000");
+  });
+
+  it("returns the static default when unset in SSR / non-browser contexts", () => {
+    vi.stubGlobal("window", undefined);
+    expect(resolveApiBaseUrl()).toBe("http://localhost:8000");
+  });
+});
+
+describe("toAbsoluteApiBase", () => {
+  it("returns an absolute base verbatim", () => {
+    expect(toAbsoluteApiBase("https://api.example.com/v1")).toBe(
+      "https://api.example.com/v1",
+    );
+  });
+
+  it("resolves a relative base against the page origin in the browser", () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    expect(toAbsoluteApiBase("/api")).toBe("https://forge.example.com/api");
+  });
+
+  it("resolves a relative base against the static origin in SSR", () => {
+    vi.stubGlobal("window", undefined);
+    expect(toAbsoluteApiBase("/api")).toBe("http://localhost:8000/api");
+  });
+});
+
+describe("ForgeApiClient with a relative base URL", () => {
+  it("does not throw and issues requests to an absolute same-origin URL", async () => {
+    stubLocation({
+      protocol: "https:",
+      host: "forge.example.com",
+      hostname: "forge.example.com",
+      port: "",
+      origin: "https://forge.example.com",
+    });
+    const fetchImpl = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) =>
+      Promise.resolve(
+        new Response(JSON.stringify({ status: "ok" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        }),
+      ),
+    );
+    const client = new ForgeApiClient({
+      baseUrl: "/api",
+      fetch: fetchImpl as unknown as typeof fetch,
+    });
+
+    await client.health();
+
+    const [url] = fetchImpl.mock.calls[0];
+    expect(String(url)).toBe("https://forge.example.com/api/health");
+  });
+});
diff --git a/apps/web/src/lib/api/api-url.ts b/apps/web/src/lib/api/api-url.ts
new file mode 100644
index 00000000..8bf874e8
--- /dev/null
+++ b/apps/web/src/lib/api/api-url.ts
@@ -0,0 +1,126 @@
+/**
+ * Runtime resolution of the Forge REST API base URL for the typed client.
+ *
+ * Next.js inlines `NEXT_PUBLIC_*` at **build** time, and the `web` image takes no
+ * `NEXT_PUBLIC_API_URL` build arg (see `deploy/docker/web.Dockerfile`) — so a
+ * compose-deployed instance bakes the static default into the client bundle, and
+ * the runtime `environment: NEXT_PUBLIC_API_URL` on the `web` service is too late
+ * to reach it. Left unresolved, a browser on `https://forge.example.com` would
+ * send REST to the baked-in `http://localhost:8000` (wrong host + mixed content).
+ *
+ * These helpers instead derive the base from `window.location` at **runtime** so
+ * REST targets the same origin the page was served from — which the edge routes
+ * to the API under `/api` (Caddy/nginx strip the prefix; see
+ * `docs/self-hosting/reverse-proxy.md`). This mirrors
+ * `apps/web/src/lib/realtime/ws-url.ts` (board/spec WebSocket same-origin
+ * derivation); the local-dev exception below is the same invariant expressed for
+ * HTTP — kept self-contained here rather than shared, so the freshly-shipped WS
+ * helper is not disturbed.
+ *
+ * Resolution precedence (see {@link resolveApiBaseUrl}):
+ *   1. `NEXT_PUBLIC_API_URL` set (build-time inlined) →
+ *      - absolute (`https://api.example.com`) → used **verbatim** (byte-identical
+ *        to the legacy behavior for anyone who set an absolute value);
+ *      - relative (`/api`) → resolved against the page origin in the browser
+ *        (`https://<page-host>/api`); against the static default origin in SSR
+ *        (so `new URL(path, base)` never throws on a relative base — see 3).
+ *   2. Unset + browser → same-origin `/api` (the edge strips `/api` → API),
+ *      EXCEPT the local `next dev` server (loopback:3000), which serves no `/api`
+ *      route and keeps the legacy `http://localhost:8000` API origin.
+ *   3. Unset + SSR / non-browser → the legacy static default
+ *      (`http://localhost:8000`). Any server-side fetch inside the container
+ *      legitimately reaches the API this way; nothing changes for it.
+ */
+
+/**
+ * Static default origin (scheme + host) used in SSR / non-browser contexts and on
+ * the local Next dev server. Matches `client.ts`'s legacy `http://localhost:8000`
+ * default: in dev the API listens on :8000 while the web dev server runs on :3000.
+ */
+const LEGACY_API_ORIGIN = "http://localhost:8000";
+
+/**
+ * Path prefix the edge routes to the API. Caddy/nginx strip `/api` before
+ * forwarding to `api:8000` (see `docs/self-hosting/reverse-proxy.md`), so a
+ * same-origin `/api` base reaches the API's un-prefixed routes.
+ */
+const SAME_ORIGIN_API_PREFIX = "/api";
+
+/** Loopback hosts that identify a local origin (mirrors `ws-url.ts`). */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/**
+ * Port the local Next web server listens on (`next dev` / standalone `next
+ * start`, `deploy/docker/web.Dockerfile`, `.env.dev` `WEB_PORT`). The full
+ * compose stack, by contrast, fronts the app with Caddy on :80/:443, where
+ * same-origin `/api` IS routed to the API — so only the dev web server is the
+ * exception below (mirrors `ws-url.ts`).
+ */
+const DEV_WEB_PORT = "3000";
+
+/**
+ * True when the page is served by the local Next web server (loopback host on
+ * :3000), whose same-origin has no `/api` route — so we keep the legacy API
+ * origin (`http://localhost:8000`) rather than the dead `http://localhost:3000/api`.
+ */
+function isLocalDevWebServer(hostname: string, port: string): boolean {
+  return LOOPBACK_HOSTS.has(hostname) && port === DEV_WEB_PORT;
+}
+
+/** True for an absolute URL bearing a scheme (`http://`, `https://`, …). */
+function isAbsoluteUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+/** Join a relative base path (e.g. `/api`) onto an absolute origin. */
+function joinOrigin(origin: string, path: string): string {
+  return `${origin}${path.startsWith("/") ? "" : "/"}${path}`;
+}
+
+/**
+ * Ensure `baseUrl` is absolute before it is handed to `new URL(path, base)`,
+ * which throws on a relative base. A relative base (e.g. `/api`, whether derived
+ * or from an explicit `new ForgeApiClient({ baseUrl: "/api" })`) is resolved
+ * against the live page origin, or the static default origin in SSR — so requests
+ * are always built against an absolute base and never throw.
+ */
+export function toAbsoluteApiBase(baseUrl: string): string {
+  if (isAbsoluteUrl(baseUrl)) {
+    return baseUrl;
+  }
+  const origin =
+    typeof window === "undefined" ? LEGACY_API_ORIGIN : window.location.origin;
+  return joinOrigin(origin, baseUrl);
+}
+
+/**
+ * Derive the API base URL when no operator override is set:
+ *   - Browser: same-origin `/api` (`https://host/api` / `http://host/api`) —
+ *     EXCEPT the local Next dev server, which keeps the legacy dev origin.
+ *   - SSR / non-browser: the legacy static default (current behavior).
+ */
+export function sameOriginApiBaseUrl(): string {
+  if (typeof window === "undefined") {
+    return LEGACY_API_ORIGIN;
+  }
+  const { protocol, host, hostname, port } = window.location;
+  if (isLocalDevWebServer(hostname, port)) {
+    return LEGACY_API_ORIGIN;
+  }
+  return `${protocol}//${host}${SAME_ORIGIN_API_PREFIX}`;
+}
+
+/**
+ * Resolve the client-side API base URL. `NEXT_PUBLIC_API_URL` (build-time
+ * inlined) wins: an absolute value is used verbatim; a relative value (e.g.
+ * `/api`) is resolved against the page origin in the browser (or the static
+ * default origin in SSR). When unset, the base is derived same-origin (see
+ * {@link sameOriginApiBaseUrl}).
+ */
+export function resolveApiBaseUrl(): string {
+  const configured = process.env.NEXT_PUBLIC_API_URL;
+  if (configured) {
+    return toAbsoluteApiBase(configured);
+  }
+  return sameOriginApiBaseUrl();
+}
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index d45a40e4..b5f4cd30 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -8,6 +8,7 @@
  * callers can degrade gracefully instead of choking on an unexpected shape.
  */
 
+import { resolveApiBaseUrl, toAbsoluteApiBase } from "./api-url";
 import { deriveOnboardingProgress } from "./onboarding-progress";
 import type {
   AgentRole,
@@ -133,8 +134,18 @@ import type {
   WorkflowValidationIssue,
 } from "./types";
 
-export const DEFAULT_API_BASE_URL =
-  process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000";
+/**
+ * The base URL the client targets when none is passed to the constructor.
+ *
+ * Resolved at runtime (see {@link resolveApiBaseUrl}): an absolute
+ * `NEXT_PUBLIC_API_URL` is used verbatim (byte-identical to the legacy default);
+ * a relative one (e.g. `/api`) or an unset one derives the same origin the page
+ * was served from in the browser, and keeps the static `http://localhost:8000`
+ * default in SSR / on the local `next dev` server. This fixes browser REST calls
+ * from a compose-deployed app, which the build-time `NEXT_PUBLIC_*` inlining
+ * otherwise baked to `http://localhost:8000` (wrong host + mixed content).
+ */
+export const DEFAULT_API_BASE_URL = resolveApiBaseUrl();
 
 /** Default bearer token for the shared `apiClient` singleton (REST + WS auth). */
 export const DEFAULT_API_TOKEN = process.env.NEXT_PUBLIC_API_TOKEN;
@@ -176,7 +187,13 @@ function buildUrl(
   path: string,
   query?: RequestOptions["query"],
 ): string {
-  const url = new URL(path.replace(/^\//, ""), baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  // `new URL(path, base)` throws on a relative base (e.g. `/api`); normalise to
+  // an absolute base first so a same-origin/relative base is joined safely.
+  const absoluteBase = toAbsoluteApiBase(baseUrl);
+  const url = new URL(
+    path.replace(/^\//, ""),
+    absoluteBase.endsWith("/") ? absoluteBase : `${absoluteBase}/`,
+  );
   if (query) {
     for (const [key, value] of Object.entries(query)) {
       if (value !== undefined) {
@@ -193,7 +210,9 @@ export class ForgeApiClient {
   private readonly fetchImpl: typeof fetch;
 
   constructor(config: ApiClientConfig = {}) {
-    this.baseUrl = config.baseUrl ?? DEFAULT_API_BASE_URL;
+    // Resolve fresh per instance (not the module-load `DEFAULT_API_BASE_URL`) so
+    // the browser-constructed singleton derives the live same-origin base.
+    this.baseUrl = config.baseUrl ?? resolveApiBaseUrl();
     this.authToken = config.token ?? DEFAULT_API_TOKEN;
     this.fetchImpl = config.fetch ?? globalThis.fetch;
   }
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 56c94d03..22651a74 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -377,7 +377,13 @@ services:
     user: "1000:1000"
     environment:
       NODE_ENV: production
-      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-/api}
+      # NOTE: NEXT_PUBLIC_API_URL is deliberately NOT set here. `NEXT_PUBLIC_*`
+      # is inlined into the web bundle at BUILD time (see web.Dockerfile /
+      # apps/web/next.config.mjs), so a runtime env var is too late to reach the
+      # client — it was dead config. The browser client now derives a same-origin
+      # `/api` base at runtime, which the edge routes to the API (see
+      # apps/web/src/lib/api/api-url.ts + docs/self-hosting/reverse-proxy.md).
+      # To target a non-same-origin API, pass NEXT_PUBLIC_API_URL as a BUILD arg.
     depends_on:
       api:
         condition: service_healthy
diff --git a/docs/self-hosting/reverse-proxy.md b/docs/self-hosting/reverse-proxy.md
index f6c8ba46..606f9e5d 100644
--- a/docs/self-hosting/reverse-proxy.md
+++ b/docs/self-hosting/reverse-proxy.md
@@ -74,6 +74,15 @@ proxying to `api:8000`. Without them, `/ws` falls through to the catch-all
 `web:3000` route — wrong, since neither socket exists on the frontend — and
 realtime is silently dead behind the proxy.
 
+The **REST** client derives its base the same way: with `NEXT_PUBLIC_API_URL`
+unset it targets a same-origin **`https://<page-host>/api`** in the browser (the
+`/api` prefix the edge strips and routes to the API; `apps/web/src/lib/api/api-url.ts`),
+keeping `http://localhost:8000` on the local `next dev` server (:3000) and in
+SSR — so behind either proxy REST works over the page's own origin with no build
+arg. Set `NEXT_PUBLIC_API_URL` (as a **build** arg) only for a non-same-origin
+API: an absolute value is used verbatim, a relative one resolves against the page
+origin.
+
 ### Websocket and streaming requirements
 
 - **Upgrade headers.** `/ws`, `/ws/spec/*`, `/_temporal`, and `/grafana/` all

From 0c0a58f819a4472c87c131c0e527798a1d070550 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 02:39:27 +0200
Subject: [PATCH 27/47] feat(slack): wire /forge status to live run lookup

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/agent.py       |  12 +++
 apps/api/forge_api/routers/integration.py |  43 +++++++--
 apps/api/tests/test_slack_inbound.py      | 112 ++++++++++++++++++++++
 3 files changed, 161 insertions(+), 6 deletions(-)

diff --git a/apps/api/forge_api/routers/agent.py b/apps/api/forge_api/routers/agent.py
index 1c502724..9665e19c 100644
--- a/apps/api/forge_api/routers/agent.py
+++ b/apps/api/forge_api/routers/agent.py
@@ -105,6 +105,18 @@ def get(self, run_id: uuid.UUID, *, workspace_id: uuid.UUID) -> AgentRunResult |
             return None
         return self._runs.get(run_id)
 
+    def owner_of(self, run_id: uuid.UUID) -> uuid.UUID | None:
+        """Return the workspace that owns ``run_id``, or ``None`` if unknown.
+
+        Read-only, cross-tenant-safe resolution mirroring
+        :meth:`ApprovalStore.owner_of`: the Slack ``/forge status`` slash command
+        is unauthenticated untrusted intake (it carries no Forge principal), so
+        the handler resolves the owning workspace from the run id and then reads
+        the run back through the normal workspace-scoped :meth:`get`. An unknown
+        id yields ``None`` -> the handler returns its not-found copy.
+        """
+        return self._owner.get(run_id)
+
 
 # --------------------------------------------------------------------------- #
 # Runner + store dependencies (overridable for tests / BYOK swap)             #
diff --git a/apps/api/forge_api/routers/integration.py b/apps/api/forge_api/routers/integration.py
index d3b7226c..55a1bbee 100644
--- a/apps/api/forge_api/routers/integration.py
+++ b/apps/api/forge_api/routers/integration.py
@@ -32,6 +32,7 @@
 from forge_api.observability.audit import AuditCategory, AuditLog
 from forge_api.observability.redaction import redact_mapping, redact_text
 from forge_api.routers._rbac import require_permission
+from forge_api.routers.agent import AgentRunStore, get_agent_store
 from forge_api.routers.approval import ApprovalStore, get_approval_store
 from forge_api.settings import Settings, get_settings
 from forge_contracts import (
@@ -280,6 +281,7 @@ def get_slack_signing_secret() -> str | None:
 SlackSigningSecretDep = Annotated[str | None, Depends(get_slack_signing_secret)]
 ApprovalStoreDep = Annotated[ApprovalStore, Depends(get_approval_store)]
 SlackRefStoreDep = Annotated[SlackApprovalRefStore, Depends(get_slack_ref_store)]
+AgentRunStoreDep = Annotated[AgentRunStore, Depends(get_agent_store)]
 
 
 # --------------------------------------------------------------------------- #
@@ -488,17 +490,43 @@ def _slack_actor(payload: dict[str, object]) -> str:
     return "slack:unknown"
 
 
-def _command_blocks(text: str) -> dict[str, object]:
+def _run_status_body(store: AgentRunStore, raw_run_id: str) -> str:
+    """Resolve ``/forge status <run>`` against the live agent-run store.
+
+    Mirrors the interactivity handler's ``owner_of`` pattern: the slash command is
+    unauthenticated untrusted intake (no Forge principal), so the owning workspace
+    is resolved from the run id and the run is then read back through the normal
+    workspace-scoped :meth:`AgentRunStore.get`. A malformed or unknown id yields
+    the not-found copy (never fabricated). The response reports the run's real
+    :class:`~forge_contracts.enums.RunStatus`, plus the number of recorded steps
+    when the run carries any (the only step/phase detail the run model holds).
+    """
+    try:
+        run_id = uuid.UUID(raw_run_id)
+    except ValueError:
+        return f"*Forge* — no run `{raw_run_id}` found."
+    owner = store.owner_of(run_id)
+    result = store.get(run_id, workspace_id=owner) if owner is not None else None
+    if result is None:
+        return f"*Forge* — no run `{raw_run_id}` found."
+    detail = ""
+    if result.steps:
+        count = len(result.steps)
+        detail = f" ({count} step{'s' if count != 1 else ''})"
+    return f"run {run_id}: {result.status.value}{detail}"
+
+
+def _command_blocks(text: str, store: AgentRunStore) -> dict[str, object]:
     """Build the ephemeral Block Kit response for a ``/forge`` sub-command."""
     parts = text.strip().split()
     sub = parts[0].lower() if parts else "help"
     if sub == "status" and len(parts) > 1:
-        body = f"*Forge* — status for `{parts[1]}` is not wired to a live task yet."
+        body = _run_status_body(store, parts[1])
     else:
         body = (
             "*Forge* commands:\n"
             "• `/forge help` — show this help\n"
-            "• `/forge status <task-id>` — task status"
+            "• `/forge status <run-id>` — live run status"
         )
     return {
         "response_type": "ephemeral",
@@ -511,20 +539,23 @@ async def slack_slash_command(
     request: Request,
     secret: SlackSigningSecretDep,
     settings: SettingsDep,
+    store: AgentRunStoreDep,
     x_slack_signature: Annotated[str | None, Header()] = None,
     x_slack_request_timestamp: Annotated[str | None, Header()] = None,
 ) -> JSONResponse:
     """Handle a signed ``/forge`` slash command (``x-www-form-urlencoded``).
 
     Verifies the Slack v0 signature over the raw body, then returns an ephemeral
-    Block Kit response within Slack's 3-second budget. Fail-closed: 501 when no
-    signing secret is configured, 401 on a bad/missing/stale signature.
+    Block Kit response within Slack's 3-second budget. ``/forge status <run>`` is
+    resolved live against the shared :class:`~forge_api.routers.agent.AgentRunStore`
+    (the same store the runs API serves ``GET /agent/runs/{id}`` from). Fail-closed:
+    501 when no signing secret is configured, 401 on a bad/missing/stale signature.
     """
     body = await request.body()
     _verify_slack_request(secret, settings, body, x_slack_request_timestamp, x_slack_signature)
     form = parse_qs(body.decode("utf-8", errors="replace"))
     text = (form.get("text") or [""])[0]
-    return JSONResponse(content=_command_blocks(text))
+    return JSONResponse(content=_command_blocks(text, store))
 
 
 @router.post("/slack/interactions")
diff --git a/apps/api/tests/test_slack_inbound.py b/apps/api/tests/test_slack_inbound.py
index dc456505..b7de48df 100644
--- a/apps/api/tests/test_slack_inbound.py
+++ b/apps/api/tests/test_slack_inbound.py
@@ -336,3 +336,115 @@ def test_interaction_unrecognised_action_is_ignored_200(
         )
     assert resp.status_code == 200, resp.text
     assert store.get(req.id, workspace_id=WS_ID).status is ApprovalStatus.PENDING  # type: ignore[union-attr, arg-type]
+
+
+# --------------------------------------------------------------------------- #
+# /forge status <run> — wired to the live agent-run store (Task 12)            #
+#                                                                             #
+# The slash command is unauthenticated untrusted intake (no Forge principal),  #
+# so — mirroring the interactivity handler's ``owner_of`` resolution — it       #
+# resolves the owning workspace from the run id, then reads the run back        #
+# through the normal workspace-scoped ``AgentRunStore.get`` path. Seeds via the #
+# same store the runs API tests (test_agent_router.py) drive.                   #
+# --------------------------------------------------------------------------- #
+
+
+def _seeded_run_store(*, status: object | None = None, n_steps: int = 2) -> tuple[object, object]:
+    """A run store seeded with one WS_ID-owned run (mirrors test_agent_router)."""
+    from forge_api.routers.agent import AgentRunStore
+    from forge_contracts import AgentRunResult, Step
+    from forge_contracts.enums import RunStatus
+
+    store = AgentRunStore()
+    result = AgentRunResult(
+        run_id=uuid.uuid4(),
+        status=status if status is not None else RunStatus.SUCCEEDED,
+        steps=[Step(index=i) for i in range(n_steps)],
+    )
+    store.put(result, workspace_id=WS_ID)
+    return store, result
+
+
+def _status_command(text: str) -> bytes:
+    return urlencode({"command": "/forge", "text": text}).encode()
+
+
+def test_status_command_returns_live_run_status(
+    authenticate_app: Callable[..., FastAPI],
+) -> None:
+    from forge_api.routers.agent import get_agent_store
+
+    store, result = _seeded_run_store(n_steps=2)
+    app = _build_app(authenticate_app)
+    app.dependency_overrides[get_agent_store] = lambda: store
+    body = _status_command(f"status {result.run_id}")  # type: ignore[attr-defined]
+    with TestClient(app) as c:
+        resp = c.post(
+            "/integration/slack/commands", content=body, headers=_signed(SIGNING_SECRET, body)
+        )
+    assert resp.status_code == 200, resp.text
+    text = json.dumps(resp.json())
+    assert f"run {result.run_id}" in text  # type: ignore[attr-defined]
+    assert "succeeded" in text  # the run's real status string, not the old stub
+    assert "2 steps" in text  # step detail carried by the run record
+    assert "not wired" not in text  # the stub is gone
+
+
+def test_status_command_unknown_run_returns_not_found(
+    authenticate_app: Callable[..., FastAPI],
+) -> None:
+    from forge_api.routers.agent import get_agent_store
+
+    store, _ = _seeded_run_store()
+    app = _build_app(authenticate_app)
+    app.dependency_overrides[get_agent_store] = lambda: store
+    unknown = uuid.uuid4()
+    body = _status_command(f"status {unknown}")
+    with TestClient(app) as c:
+        resp = c.post(
+            "/integration/slack/commands", content=body, headers=_signed(SIGNING_SECRET, body)
+        )
+    assert resp.status_code == 200, resp.text
+    text = json.dumps(resp.json()).lower()
+    assert "no run" in text and "found" in text  # the not-found copy
+    assert "succeeded" not in text  # never leaks another run's status
+
+
+def test_status_command_cross_tenant_run_is_not_found(
+    authenticate_app: Callable[..., FastAPI],
+) -> None:
+    """A run owned by another workspace resolves via owner_of but the scoped
+    get returns it consistently: still reachable read-only by id (unguessable
+    UUID), never fabricated. Guards the owner_of -> scoped-get round trip."""
+    from forge_api.routers.agent import get_agent_store
+
+    store, result = _seeded_run_store(n_steps=0)
+    app = _build_app(authenticate_app)
+    app.dependency_overrides[get_agent_store] = lambda: store
+    body = _status_command(f"status {result.run_id}")  # type: ignore[attr-defined]
+    with TestClient(app) as c:
+        resp = c.post(
+            "/integration/slack/commands", content=body, headers=_signed(SIGNING_SECRET, body)
+        )
+    assert resp.status_code == 200, resp.text
+    text = json.dumps(resp.json())
+    assert f"run {result.run_id}: succeeded" in text  # type: ignore[attr-defined]
+    assert "steps" not in text  # no step detail when the run carries no steps
+
+
+def test_status_command_malformed_id_returns_not_found(
+    authenticate_app: Callable[..., FastAPI],
+) -> None:
+    from forge_api.routers.agent import get_agent_store
+
+    store, _ = _seeded_run_store()
+    app = _build_app(authenticate_app)
+    app.dependency_overrides[get_agent_store] = lambda: store
+    body = _status_command("status not-a-uuid")
+    with TestClient(app) as c:
+        resp = c.post(
+            "/integration/slack/commands", content=body, headers=_signed(SIGNING_SECRET, body)
+        )
+    assert resp.status_code == 200, resp.text
+    text = json.dumps(resp.json()).lower()
+    assert "no run" in text and "found" in text

From c6f51afaa97a42bec39636ee5430ee14cde82fd1 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 02:46:18 +0200
Subject: [PATCH 28/47] test(slack): real cross-tenant coverage and
 threat-model residual for slash surfaces

---
 apps/api/tests/test_slack_inbound.py | 52 ++++++++++++++++++++++++----
 docs/security/threat-model.md        |  6 +++-
 2 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/apps/api/tests/test_slack_inbound.py b/apps/api/tests/test_slack_inbound.py
index b7de48df..c577ad80 100644
--- a/apps/api/tests/test_slack_inbound.py
+++ b/apps/api/tests/test_slack_inbound.py
@@ -43,6 +43,9 @@
 # across the full-suite run, where a nested tests/sso/conftest.py collides).
 WS_ID = uuid.UUID("00000000-0000-0000-0000-0000000000c6")
 USER_ID = uuid.UUID("00000000-0000-0000-0000-0000000000d7")
+# A second, distinct workspace used only by the genuine cross-tenant test below —
+# never the authenticated test principal's own workspace (WS_ID).
+WS_ID_OTHER = uuid.UUID("00000000-0000-0000-0000-0000000000c7")
 
 
 def _principal() -> Principal:
@@ -349,8 +352,11 @@ def test_interaction_unrecognised_action_is_ignored_200(
 # --------------------------------------------------------------------------- #
 
 
-def _seeded_run_store(*, status: object | None = None, n_steps: int = 2) -> tuple[object, object]:
-    """A run store seeded with one WS_ID-owned run (mirrors test_agent_router)."""
+def _seeded_run_store(
+    *, status: object | None = None, n_steps: int = 2, workspace_id: uuid.UUID = WS_ID
+) -> tuple[object, object]:
+    """A run store seeded with one ``workspace_id``-owned run (defaults to
+    WS_ID; mirrors test_agent_router)."""
     from forge_api.routers.agent import AgentRunStore
     from forge_contracts import AgentRunResult, Step
     from forge_contracts.enums import RunStatus
@@ -361,7 +367,7 @@ def _seeded_run_store(*, status: object | None = None, n_steps: int = 2) -> tupl
         status=status if status is not None else RunStatus.SUCCEEDED,
         steps=[Step(index=i) for i in range(n_steps)],
     )
-    store.put(result, workspace_id=WS_ID)
+    store.put(result, workspace_id=workspace_id)
     return store, result
 
 
@@ -410,12 +416,16 @@ def test_status_command_unknown_run_returns_not_found(
     assert "succeeded" not in text  # never leaks another run's status
 
 
-def test_status_command_cross_tenant_run_is_not_found(
+def test_status_command_run_without_steps_omits_step_detail(
     authenticate_app: Callable[..., FastAPI],
 ) -> None:
-    """A run owned by another workspace resolves via owner_of but the scoped
-    get returns it consistently: still reachable read-only by id (unguessable
-    UUID), never fabricated. Guards the owner_of -> scoped-get round trip."""
+    """A run with zero recorded steps renders its status with no step-count
+    suffix: ``_run_status_body`` only appends ``(N steps)`` when the run
+    actually carries any. (Previously misnamed
+    ``test_status_command_cross_tenant_run_is_not_found`` — it seeded and read
+    back a single workspace's own run, so it never exercised a second tenant;
+    see ``test_status_command_cross_tenant_run_is_found_by_uuid`` below for the
+    genuine cross-tenant case.)"""
     from forge_api.routers.agent import get_agent_store
 
     store, result = _seeded_run_store(n_steps=0)
@@ -432,6 +442,34 @@ def test_status_command_cross_tenant_run_is_not_found(
     assert "steps" not in text  # no step detail when the run carries no steps
 
 
+def test_status_command_cross_tenant_run_is_found_by_uuid(
+    authenticate_app: Callable[..., FastAPI],
+) -> None:
+    """The slash command carries no Forge tenant principal, so a run seeded
+    under a different workspace (WS_ID_OTHER — never the authenticated test
+    principal's own WS_ID) is still resolved and returned by UUID: ``owner_of``
+    finds the true owning workspace and ``get`` reads the run back through
+    that workspace's own scope, regardless of who is asking. This is the
+    accepted residual posture recorded in the threat model
+    (docs/security/threat-model.md, S5): after signature verification,
+    object-UUID unguessability — not tenant matching — is the sole
+    cross-tenant secrecy control on this surface."""
+    from forge_api.routers.agent import get_agent_store
+
+    store, result = _seeded_run_store(n_steps=1, workspace_id=WS_ID_OTHER)
+    app = _build_app(authenticate_app)
+    app.dependency_overrides[get_agent_store] = lambda: store
+    body = _status_command(f"status {result.run_id}")  # type: ignore[attr-defined]
+    with TestClient(app) as c:
+        resp = c.post(
+            "/integration/slack/commands", content=body, headers=_signed(SIGNING_SECRET, body)
+        )
+    assert resp.status_code == 200, resp.text
+    text = json.dumps(resp.json())
+    assert f"run {result.run_id}: succeeded" in text  # type: ignore[attr-defined]
+    assert "no run" not in text.lower()  # genuinely found, not the not-found copy
+
+
 def test_status_command_malformed_id_returns_not_found(
     authenticate_app: Callable[..., FastAPI],
 ) -> None:
diff --git a/docs/security/threat-model.md b/docs/security/threat-model.md
index eed9f9de..6c103bfc 100644
--- a/docs/security/threat-model.md
+++ b/docs/security/threat-model.md
@@ -89,7 +89,11 @@ registry client is **PT-07**. Pentest: SSRF via redirect + rebind (**PT-05**).
 | **R** | Replay | Slack timestamp window; providers' nonces where available. |
 
 **Residual:** replay window tuning per provider; pentest: signature-bypass and
-timing (**PT-06**).
+timing (**PT-06**). After signature verification, Slack interaction/command
+payloads carry no Forge tenant principal; approval-decide and run-status
+resolve tenancy via an `owner_of(id)` lookup, so object-UUID unguessability is
+the sole cross-tenant secrecy control on these surfaces (status/step-count
+exposure for runs; decide for approvals).
 
 ## S6 — Agent git-worktree sandbox (worker)
 

From 7ddc2c8ca450e9baed821b7090523f9cd0bb92b1 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 02:58:38 +0200
Subject: [PATCH 29/47] refactor(api): retire legacy in-memory /approval router
 in favor of DB-backed /approvals

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/__init__.py    |   3 -
 apps/api/forge_api/routers/agent.py       |   3 +-
 apps/api/forge_api/routers/approval.py    | 214 ----------------------
 apps/api/forge_api/routers/integration.py | 111 ++++++++++-
 apps/api/tests/test_api_skeleton.py       |   2 +-
 apps/api/tests/test_approval_router.py    |  79 --------
 apps/api/tests/test_integration_router.py |  10 +-
 apps/api/tests/test_rbac_tenant_r2.py     |  95 +++-------
 apps/api/tests/test_slack_inbound.py      |   3 +-
 9 files changed, 139 insertions(+), 381 deletions(-)
 delete mode 100644 apps/api/forge_api/routers/approval.py
 delete mode 100644 apps/api/tests/test_approval_router.py

diff --git a/apps/api/forge_api/routers/__init__.py b/apps/api/forge_api/routers/__init__.py
index 0fd847b0..e631d766 100644
--- a/apps/api/forge_api/routers/__init__.py
+++ b/apps/api/forge_api/routers/__init__.py
@@ -15,7 +15,6 @@
     agent,
     alerts,
     ao_settings,
-    approval,
     approvals,
     audit,
     auth,
@@ -64,7 +63,6 @@
     marketplace.router,
     benchmarks.router,
     integration.router,
-    approval.router,
     approvals.router,
     audit.router,
     cost.router,
@@ -91,7 +89,6 @@
     "agent",
     "alerts",
     "ao_settings",
-    "approval",
     "approvals",
     "audit",
     "auth",
diff --git a/apps/api/forge_api/routers/agent.py b/apps/api/forge_api/routers/agent.py
index 9665e19c..e496ad2c 100644
--- a/apps/api/forge_api/routers/agent.py
+++ b/apps/api/forge_api/routers/agent.py
@@ -109,7 +109,8 @@ def owner_of(self, run_id: uuid.UUID) -> uuid.UUID | None:
         """Return the workspace that owns ``run_id``, or ``None`` if unknown.
 
         Read-only, cross-tenant-safe resolution mirroring
-        :meth:`ApprovalStore.owner_of`: the Slack ``/forge status`` slash command
+        :meth:`~forge_api.routers.integration.ApprovalStore.owner_of`: the Slack
+        ``/forge status`` slash command
         is unauthenticated untrusted intake (it carries no Forge principal), so
         the handler resolves the owning workspace from the run id and then reads
         the run back through the normal workspace-scoped :meth:`get`. An unknown
diff --git a/apps/api/forge_api/routers/approval.py b/apps/api/forge_api/routers/approval.py
deleted file mode 100644
index 000899d6..00000000
--- a/apps/api/forge_api/routers/approval.py
+++ /dev/null
@@ -1,214 +0,0 @@
-"""Approval router — the human-in-the-loop gate surface (wired in Phase 2 Task 2.1).
-
-Serves the approval queue over HTTP:
-
-* ``POST /approval/requests``                 — open an approval request (a gate
-  raised by the workflow/agent layer when a task needs human sign-off).
-* ``GET  /approval/requests``                 — list pending/decided requests.
-* ``GET  /approval/requests/{approval_id}``   — fetch one request (full context).
-* ``POST /approval/requests/{approval_id}/decision`` — approve / reject /
-  request changes.
-
-Handlers delegate to a process-wide in-memory :class:`ApprovalStore` (the
-DB-backed store is swapped in behind the same dependency via
-``app.dependency_overrides`` / config). Unknown ids map to HTTP 404.
-"""
-
-from __future__ import annotations
-
-import uuid
-from datetime import UTC, datetime
-from functools import lru_cache
-from typing import Annotated
-
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel
-
-from forge_api.auth.rbac import Permission
-from forge_api.deps import Principal, get_current_principal
-from forge_api.routers._rbac import require_permission
-from forge_contracts import ApprovalRequest
-from forge_contracts.enums import ApprovalStatus
-
-router = APIRouter(
-    prefix="/approval",
-    tags=["approval"],
-    dependencies=[Depends(get_current_principal)],
-)
-
-# Permission-gated principals (authenticate + authorize, returning the principal
-# so handlers can scope by workspace and record the decider identity). Opening
-# and deciding a gate are WRITE operations — a read-only ``viewer`` and the
-# ``agent-runner`` (which lacks WRITE) are therefore denied, preserving the
-# human-in-the-loop guarantee that an agent cannot approve its own gate.
-ReaderDep = Annotated[Principal, Depends(require_permission(Permission.READ))]
-WriterDep = Annotated[Principal, Depends(require_permission(Permission.WRITE))]
-
-
-# --------------------------------------------------------------------------- #
-# In-memory approval store                                                     #
-# --------------------------------------------------------------------------- #
-
-
-class ApprovalStore:
-    """A tiny in-memory store of approval requests (keyed by id).
-
-    Each request is tagged with the ``workspace_id`` that created it; every read
-    and decision is scoped to a workspace so one tenant can never see, fetch, or
-    decide another tenant's gates. ``ApprovalRequest`` carries no ``workspace_id``
-    field (it is a frozen contract), so ownership is tracked alongside the items.
-    """
-
-    def __init__(self) -> None:
-        self._items: dict[uuid.UUID, ApprovalRequest] = {}
-        self._owner: dict[uuid.UUID, uuid.UUID] = {}
-
-    def create(self, request: ApprovalRequest, *, workspace_id: uuid.UUID) -> ApprovalRequest:
-        if request.id is None:
-            request.id = uuid.uuid4()
-        if request.created_at is None:
-            request.created_at = datetime.now(UTC)
-        self._items[request.id] = request
-        self._owner[request.id] = workspace_id
-        return request
-
-    def list(
-        self, *, workspace_id: uuid.UUID, status: ApprovalStatus | None = None
-    ) -> list[ApprovalRequest]:
-        items = [req for key, req in self._items.items() if self._owner.get(key) == workspace_id]
-        if status is not None:
-            items = [i for i in items if i.status == status]
-        return items
-
-    def get(self, approval_id: uuid.UUID, *, workspace_id: uuid.UUID) -> ApprovalRequest | None:
-        if self._owner.get(approval_id) != workspace_id:
-            return None
-        return self._items.get(approval_id)
-
-    def owner_of(self, approval_id: uuid.UUID) -> uuid.UUID | None:
-        """Return the workspace that owns ``approval_id``, or ``None`` if unknown.
-
-        Read-only, cross-tenant-safe resolution used by the Slack interactivity
-        handler: a Slack ``block_actions`` callback is unauthenticated (it carries
-        no Forge principal) and embeds only the approval id, so the handler must
-        resolve the owning workspace before applying the decision through the
-        normal workspace-scoped :meth:`decide` path. An unknown id yields
-        ``None`` -> the handler no-ops (never leaks another tenant's gate).
-        """
-        return self._owner.get(approval_id)
-
-    def decide(
-        self,
-        approval_id: uuid.UUID,
-        *,
-        workspace_id: uuid.UUID,
-        status: ApprovalStatus,
-        decided_by: str | None,
-        reason: str | None,
-    ) -> ApprovalRequest | None:
-        request = self.get(approval_id, workspace_id=workspace_id)
-        if request is None:
-            return None
-        request.status = status
-        request.decided_by = decided_by
-        request.decision_reason = reason
-        request.decided_at = datetime.now(UTC)
-        return request
-
-
-@lru_cache(maxsize=1)
-def _approval_store_singleton() -> ApprovalStore:
-    return ApprovalStore()
-
-
-def get_approval_store() -> ApprovalStore:
-    """Return the process-wide approval store (override in tests via DI)."""
-    return _approval_store_singleton()
-
-
-StoreDep = Annotated[ApprovalStore, Depends(get_approval_store)]
-
-
-# --------------------------------------------------------------------------- #
-# Request bodies                                                              #
-# --------------------------------------------------------------------------- #
-
-
-class DecisionRequest(BaseModel):
-    """Body for ``POST /approval/requests/{approval_id}/decision``.
-
-    There is deliberately **no** ``decided_by`` field: the decider identity is
-    taken from the authenticated principal, never from the request body, so the
-    gate's accountability record cannot be forged.
-    """
-
-    status: ApprovalStatus
-    reason: str | None = None
-
-
-def _decider_identity(principal: Principal) -> str:
-    """Stable, human-readable identity for the authenticated decider."""
-    return principal.email or str(principal.user_id)
-
-
-def _require(request: ApprovalRequest | None, approval_id: uuid.UUID) -> ApprovalRequest:
-    if request is None:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND, detail=f"no approval request {approval_id}"
-        )
-    return request
-
-
-# --------------------------------------------------------------------------- #
-# Routes                                                                      #
-# --------------------------------------------------------------------------- #
-
-
-@router.post("/requests", response_model=ApprovalRequest, status_code=status.HTTP_201_CREATED)
-def create_request(
-    store: StoreDep, principal: WriterDep, request: ApprovalRequest
-) -> ApprovalRequest:
-    """Open an approval request in the caller's workspace."""
-    return store.create(request, workspace_id=principal.workspace_id)
-
-
-@router.get("/requests", response_model=list[ApprovalRequest])
-def list_requests(
-    store: StoreDep,
-    principal: ReaderDep,
-    status: Annotated[ApprovalStatus | None, Query()] = None,
-) -> list[ApprovalRequest]:
-    """List the caller workspace's approval requests (optionally by status)."""
-    return store.list(workspace_id=principal.workspace_id, status=status)
-
-
-@router.get("/requests/{approval_id}", response_model=ApprovalRequest)
-def get_request(store: StoreDep, principal: ReaderDep, approval_id: uuid.UUID) -> ApprovalRequest:
-    """Fetch one approval request (only within the caller's workspace)."""
-    return _require(store.get(approval_id, workspace_id=principal.workspace_id), approval_id)
-
-
-@router.post("/requests/{approval_id}/decision", response_model=ApprovalRequest)
-def decide(
-    store: StoreDep,
-    principal: WriterDep,
-    approval_id: uuid.UUID,
-    payload: DecisionRequest,
-) -> ApprovalRequest:
-    """Approve / reject / request changes on an approval request.
-
-    The decider identity is the authenticated principal (WRITE-capable: a human
-    ``member``/``admin``); the read-only ``viewer`` and the ``agent-runner`` are
-    rejected upstream by the WRITE gate, so an agent cannot decide its own gate.
-    """
-    decided = store.decide(
-        approval_id,
-        workspace_id=principal.workspace_id,
-        status=payload.status,
-        decided_by=_decider_identity(principal),
-        reason=payload.reason,
-    )
-    return _require(decided, approval_id)
-
-
-__all__ = ["ApprovalStore", "DecisionRequest", "get_approval_store", "router"]
diff --git a/apps/api/forge_api/routers/integration.py b/apps/api/forge_api/routers/integration.py
index 55a1bbee..8a7dbe91 100644
--- a/apps/api/forge_api/routers/integration.py
+++ b/apps/api/forge_api/routers/integration.py
@@ -19,6 +19,7 @@
 
 import contextlib
 import uuid
+from datetime import UTC, datetime
 from functools import lru_cache
 from typing import Annotated
 from urllib.parse import parse_qs
@@ -33,9 +34,9 @@
 from forge_api.observability.redaction import redact_mapping, redact_text
 from forge_api.routers._rbac import require_permission
 from forge_api.routers.agent import AgentRunStore, get_agent_store
-from forge_api.routers.approval import ApprovalStore, get_approval_store
 from forge_api.settings import Settings, get_settings
 from forge_contracts import (
+    ApprovalRequest,
     CIStatus,
     HealthResult,
     PullRequest,
@@ -203,15 +204,111 @@ def _slack_notifier_singleton() -> SlackNotifier:
     )
 
 
+class ApprovalStore:
+    """In-memory approval queue that backs **only** the Slack integration.
+
+    This is the Phase-2 in-memory approval store. Its HTTP surface (the legacy
+    ``/approval/*`` router) was retired in favour of the DB-backed F36
+    ``/approvals/*`` surface (``routers/approvals.py`` +
+    ``forge_approval.ApprovalService``). The store itself survives here because
+    the Slack integration is still wired to it and **cannot** be migrated to the
+    F36 service within a bounded diff:
+
+    * a Slack ``block_actions`` / ``chat.update`` callback is *unauthenticated*
+      untrusted intake — it carries no Forge principal, only an approval id — so
+      it needs :meth:`owner_of` to resolve the owning workspace from the id
+      alone; ``ApprovalService`` deliberately exposes no such id-only lookup
+      (every read demands a ``workspace_id``, and a cross-workspace id maps to
+      not-found);
+    * ``ApprovalService.resolve`` requires a domain ``Principal`` of
+      ``kind="user"`` with a real Forge user UUID and a ``member``/``admin``
+      role, and records that UUID as the decision's ``approver_user_id``; a Slack
+      actor is a ``slack:<handle>`` string with no Forge-user mapping anywhere in
+      the codebase, so it cannot satisfy the authorizer without forging identity;
+    * :meth:`slack_notify_approval` hands the resolved request to
+      :meth:`SlackNotifier.notify_approval`, which is typed to the frozen
+      :class:`~forge_contracts.ApprovalRequest` contract — a different type than
+      the F36 ``forge_approval.models.ApprovalRequest`` the service returns.
+
+    Consumers (both in this module): :func:`slack_notify_approval`
+    (``POST /integration/slack/approvals/{id}/notify``) reads via :meth:`get`;
+    :func:`slack_interaction` (``POST /integration/slack/interactions``) resolves
+    via :meth:`owner_of` then applies :meth:`decide`.
+
+    Each request is tagged with the ``workspace_id`` that created it; every read
+    and decision is scoped to a workspace so one tenant can never see, fetch, or
+    decide another tenant's gates. ``ApprovalRequest`` carries no ``workspace_id``
+    field (it is a frozen contract), so ownership is tracked alongside the items.
+    """
+
+    def __init__(self) -> None:
+        self._items: dict[uuid.UUID, ApprovalRequest] = {}
+        self._owner: dict[uuid.UUID, uuid.UUID] = {}
+
+    def create(self, request: ApprovalRequest, *, workspace_id: uuid.UUID) -> ApprovalRequest:
+        if request.id is None:
+            request.id = uuid.uuid4()
+        if request.created_at is None:
+            request.created_at = datetime.now(UTC)
+        self._items[request.id] = request
+        self._owner[request.id] = workspace_id
+        return request
+
+    def get(self, approval_id: uuid.UUID, *, workspace_id: uuid.UUID) -> ApprovalRequest | None:
+        if self._owner.get(approval_id) != workspace_id:
+            return None
+        return self._items.get(approval_id)
+
+    def owner_of(self, approval_id: uuid.UUID) -> uuid.UUID | None:
+        """Return the workspace that owns ``approval_id``, or ``None`` if unknown.
+
+        Read-only, cross-tenant-safe resolution used by the Slack interactivity
+        handler: a Slack ``block_actions`` callback is unauthenticated (it carries
+        no Forge principal) and embeds only the approval id, so the handler must
+        resolve the owning workspace before applying the decision through the
+        normal workspace-scoped :meth:`decide` path. An unknown id yields
+        ``None`` -> the handler no-ops (never leaks another tenant's gate).
+        """
+        return self._owner.get(approval_id)
+
+    def decide(
+        self,
+        approval_id: uuid.UUID,
+        *,
+        workspace_id: uuid.UUID,
+        status: ApprovalStatus,
+        decided_by: str | None,
+        reason: str | None,
+    ) -> ApprovalRequest | None:
+        request = self.get(approval_id, workspace_id=workspace_id)
+        if request is None:
+            return None
+        request.status = status
+        request.decided_by = decided_by
+        request.decision_reason = reason
+        request.decided_at = datetime.now(UTC)
+        return request
+
+
+@lru_cache(maxsize=1)
+def _approval_store_singleton() -> ApprovalStore:
+    return ApprovalStore()
+
+
+def get_approval_store() -> ApprovalStore:
+    """Return the process-wide Slack-integration approval store (override in tests)."""
+    return _approval_store_singleton()
+
+
 class SlackApprovalRefStore:
     """In-memory ``approval_id -> (channel, ts)`` back-reference for Slack posts.
 
     ``ApprovalRequest`` is a frozen contract (no ``slack_ts`` field), so — exactly
-    as :class:`~forge_api.routers.approval.ApprovalStore` tracks workspace
-    ownership *beside* the item rather than mutating the DTO — the resolved
-    channel + message timestamp of an approval's Slack post are tracked here. The
-    interactivity handler reads them to edit the original message in place
-    (``chat.update``). The DB-backed store swaps in behind the same dependency.
+    as :class:`ApprovalStore` tracks workspace ownership *beside* the item rather
+    than mutating the DTO — the resolved channel + message timestamp of an
+    approval's Slack post are tracked here. The interactivity handler reads them
+    to edit the original message in place (``chat.update``). The DB-backed store
+    swaps in behind the same dependency.
     """
 
     def __init__(self) -> None:
@@ -661,8 +758,10 @@ async def slack_interaction(
 
 
 __all__ = [
+    "ApprovalStore",
     "RepoConnectionStore",
     "SlackApprovalRefStore",
+    "get_approval_store",
     "get_github_client",
     "get_github_client_optional",
     "get_github_webhook_secret",
diff --git a/apps/api/tests/test_api_skeleton.py b/apps/api/tests/test_api_skeleton.py
index c159a157..538d6e7a 100644
--- a/apps/api/tests/test_api_skeleton.py
+++ b/apps/api/tests/test_api_skeleton.py
@@ -40,7 +40,7 @@
     "/policy",
     "/mcp",
     "/integration",
-    "/approval",
+    "/approvals",
     "/observability",
     "/auth",
 ]
diff --git a/apps/api/tests/test_approval_router.py b/apps/api/tests/test_approval_router.py
deleted file mode 100644
index 88b88bb5..00000000
--- a/apps/api/tests/test_approval_router.py
+++ /dev/null
@@ -1,79 +0,0 @@
-"""Integration tests for the approval router (Phase 2 Task 2.1 wires ``/approval/*``).
-
-Exercises the real handlers wired to a fresh in-memory :class:`ApprovalStore`:
-create a request, list/get it, and record a decision; unknown ids -> 404.
-"""
-
-from __future__ import annotations
-
-import uuid
-from collections.abc import Callable, Iterator
-
-import pytest
-from fastapi import FastAPI
-from fastapi.testclient import TestClient
-
-from forge_api.main import create_app
-from forge_api.routers.approval import ApprovalStore, get_approval_store
-
-
-@pytest.fixture
-def client(authenticate_app: Callable[..., FastAPI]) -> Iterator[TestClient]:
-    app = create_app()
-    authenticate_app(app)
-    store = ApprovalStore()
-    app.dependency_overrides[get_approval_store] = lambda: store
-    with TestClient(app) as c:
-        yield c
-
-
-def _create(client: TestClient) -> dict:
-    resp = client.post(
-        "/approval/requests",
-        json={"gate": "pr", "title": "Approve PR for TASK-1", "confidence": 0.8},
-    )
-    assert resp.status_code == 201, resp.text
-    return resp.json()
-
-
-def test_create_and_get(client: TestClient) -> None:
-    created = _create(client)
-    assert created["id"]
-    assert created["status"] == "pending"
-    fetched = client.get(f"/approval/requests/{created['id']}")
-    assert fetched.status_code == 200
-    assert fetched.json()["title"] == "Approve PR for TASK-1"
-
-
-def test_list_requests(client: TestClient) -> None:
-    _create(client)
-    resp = client.get("/approval/requests")
-    assert resp.status_code == 200
-    assert len(resp.json()) == 1
-    pending = client.get("/approval/requests", params={"status": "pending"})
-    assert len(pending.json()) == 1
-
-
-def test_decide_approves(client: TestClient) -> None:
-    created = _create(client)
-    resp = client.post(
-        f"/approval/requests/{created['id']}/decision",
-        # A forged ``decided_by`` in the body must be ignored: the decider is the
-        # authenticated principal, not whatever the caller claims.
-        json={"status": "approved", "decided_by": "alice", "reason": "looks good"},
-    )
-    assert resp.status_code == 200, resp.text
-    body = resp.json()
-    assert body["status"] == "approved"
-    assert body["decided_by"] == "test-principal@forge.local"
-    assert body["decided_at"]
-
-
-def test_get_unknown_is_404(client: TestClient) -> None:
-    resp = client.get(f"/approval/requests/{uuid.uuid4()}")
-    assert resp.status_code == 404
-
-
-def test_decide_unknown_is_404(client: TestClient) -> None:
-    resp = client.post(f"/approval/requests/{uuid.uuid4()}/decision", json={"status": "approved"})
-    assert resp.status_code == 404
diff --git a/apps/api/tests/test_integration_router.py b/apps/api/tests/test_integration_router.py
index 04b188df..f1e0570f 100644
--- a/apps/api/tests/test_integration_router.py
+++ b/apps/api/tests/test_integration_router.py
@@ -101,9 +101,10 @@ def test_slack_notify_approval_records_ts(authenticate_app: Callable[..., FastAP
     """POST /slack/approvals/{id}/notify posts the gate + stashes channel/ts (AC)."""
     import uuid
 
-    from forge_api.routers.approval import ApprovalStore, get_approval_store
     from forge_api.routers.integration import (
+        ApprovalStore,
         SlackApprovalRefStore,
+        get_approval_store,
         get_slack_notifier,
         get_slack_ref_store,
     )
@@ -137,8 +138,11 @@ def test_slack_notify_approval_404_for_unknown_gate(
 ) -> None:
     import uuid
 
-    from forge_api.routers.approval import ApprovalStore, get_approval_store
-    from forge_api.routers.integration import get_slack_notifier
+    from forge_api.routers.integration import (
+        ApprovalStore,
+        get_approval_store,
+        get_slack_notifier,
+    )
 
     store = ApprovalStore()
     slack = SlackNotifier(
diff --git a/apps/api/tests/test_rbac_tenant_r2.py b/apps/api/tests/test_rbac_tenant_r2.py
index 591f12d3..ba0d4f66 100644
--- a/apps/api/tests/test_rbac_tenant_r2.py
+++ b/apps/api/tests/test_rbac_tenant_r2.py
@@ -1,17 +1,24 @@
 """Reproduction + regression tests for the Phase-2 round-2 security fixes (2.3-fix-r2).
 
-Four real defects in the wired feature routers:
+Four real defects were found in the wired feature routers. The legacy in-memory
+``/approval/*`` router has since been retired in favour of the DB-backed F36
+``/approvals/*`` surface, so this file keeps the agent / workflow / spec / repo
+coverage below; the approval-gate embodiment of defects #1-#3 now lives with the
+DB-backed surface's own tests (``test_approvals.py``:
+``test_decision_authz_matrix`` for RBAC + the ``agent-runner`` refusal,
+``test_decision_body_cannot_forge_decider`` for decider identity,
+``test_cross_workspace_404`` for tenant isolation).
 
 1. **RBAC never enforced** — a read-only ``viewer`` (and the ``agent-runner``
    identity) could perform writes / runs / approvals. Every write/run/approve
    route must now authorize, not just authenticate.
-2. **HITL decider spoofing** — ``POST /approval/.../decision`` recorded
-   ``decided_by`` from the request body, and any role could decide. The decider
-   identity must come from the authenticated principal, and the ``agent-runner``
-   must not be able to decide its own gate.
-3. **Cross-workspace tenant isolation** — approval / agent / workflow / spec
-   stores were process-wide and unscoped; workspace B could read/decide/overwrite
-   workspace A's data. Foreign ids must surface as 404.
+2. **HITL decider spoofing** — a decision recorded ``decided_by`` from the
+   request body, and any role could decide. The decider identity must come from
+   the authenticated principal, and the ``agent-runner`` must not be able to
+   decide its own gate.
+3. **Cross-workspace tenant isolation** — agent / workflow / spec stores were
+   process-wide and unscoped; workspace B could read/decide/overwrite workspace
+   A's data. Foreign ids must surface as 404.
 4. **sync_repo confused-deputy** — the route ignored ``connection_id`` and synced
    a caller-supplied repo with the server's privileged token. The connection must
    be resolved server-side, scoped to the caller's workspace.
@@ -108,90 +115,32 @@ def test_viewer_cannot_write_or_run_across_routers() -> None:
     rid = uuid.uuid4()
     with TestClient(app) as client:
         cases = [
-            client.post(f"/approval/requests/{rid}/decision", json={"status": "approved"}),
             client.post(f"/spec/specs/{rid}/approve"),
             client.post(f"/workflow/runs/{rid}/transition", json={"event": "x"}),
             client.post(
                 "/integration/github/pull-requests",
                 json={"repo": "org/api", "title": "t", "head": "f", "base": "main"},
             ),
-            client.post(
-                "/approval/requests",
-                json={"gate": "pr", "title": "t", "confidence": 0.5},
-            ),
         ]
     for resp in cases:
         assert resp.status_code == 403, resp.text
 
 
-def test_viewer_may_still_read() -> None:
-    app = create_app()
-    _as(app, make_test_principal(role=UserRole.VIEWER))
-    with TestClient(app) as client:
-        resp = client.get("/approval/requests")
-    assert resp.status_code == 200, resp.text
-
-
 # --------------------------------------------------------------------------- #
-# 2. HITL decider identity                                                     #
+# 2. HITL decider identity + 3. approval tenant isolation                      #
+#                                                                             #
+# The approval-gate embodiment of these fixes moved to the DB-backed F36       #
+# ``/approvals/*`` surface when the legacy in-memory ``/approval/*`` router was #
+# retired; see ``test_approvals.py`` (``test_decision_body_cannot_forge_decider``,#
+# ``test_decision_authz_matrix``, ``test_cross_workspace_404``).               #
 # --------------------------------------------------------------------------- #
 
 
-def _open_request(client: TestClient) -> str:
-    resp = client.post(
-        "/approval/requests",
-        json={"gate": "pr", "title": "Approve PR", "confidence": 0.8},
-    )
-    assert resp.status_code == 201, resp.text
-    return resp.json()["id"]
-
-
-def test_decider_identity_comes_from_principal_not_body() -> None:
-    app = create_app()
-    member = make_test_principal(role=UserRole.MEMBER)
-    _as(app, member)
-    with TestClient(app) as client:
-        rid = _open_request(client)
-        resp = client.post(
-            f"/approval/requests/{rid}/decision",
-            json={"status": "approved", "decided_by": "attacker", "reason": "ok"},
-        )
-    assert resp.status_code == 200, resp.text
-    body = resp.json()
-    # The forged body identity is ignored; the authenticated principal is recorded.
-    assert body["decided_by"] != "attacker"
-    assert body["decided_by"] == member.email
-
-
-def test_agent_runner_cannot_decide_its_own_gate() -> None:
-    app = create_app()
-    # Member opens the gate, then the agent-runner attempts to approve it.
-    _as(app, make_test_principal(role=UserRole.MEMBER))
-    with TestClient(app) as client:
-        rid = _open_request(client)
-        _as(app, make_test_principal(role=UserRole.AGENT_RUNNER))
-        resp = client.post(f"/approval/requests/{rid}/decision", json={"status": "approved"})
-    assert resp.status_code == 403, resp.text
-
-
 # --------------------------------------------------------------------------- #
-# 3. Cross-workspace tenant isolation                                          #
+# 3. Cross-workspace tenant isolation (agent / workflow / spec)                #
 # --------------------------------------------------------------------------- #
 
 
-def test_approval_is_workspace_scoped() -> None:
-    app = create_app()
-    _as(app, make_test_principal(role=UserRole.MEMBER, workspace_id=TEST_WORKSPACE_ID))
-    with TestClient(app) as client:
-        rid = _open_request(client)
-        # Switch to a different tenant.
-        _as(app, make_test_principal(role=UserRole.MEMBER, workspace_id=OTHER_WORKSPACE_ID))
-        assert client.get(f"/approval/requests/{rid}").status_code == 404
-        assert client.get("/approval/requests").json() == []
-        decide = client.post(f"/approval/requests/{rid}/decision", json={"status": "approved"})
-        assert decide.status_code == 404
-
-
 def test_agent_run_is_workspace_scoped() -> None:
     from forge_api.routers.agent import (
         AgentRunStore,
diff --git a/apps/api/tests/test_slack_inbound.py b/apps/api/tests/test_slack_inbound.py
index c577ad80..c691a2aa 100644
--- a/apps/api/tests/test_slack_inbound.py
+++ b/apps/api/tests/test_slack_inbound.py
@@ -26,9 +26,10 @@
 from forge_api.deps import Principal
 from forge_api.main import create_app
 from forge_api.observability.audit import AuditCategory, AuditLog
-from forge_api.routers.approval import ApprovalStore, get_approval_store
 from forge_api.routers.integration import (
+    ApprovalStore,
     SlackApprovalRefStore,
+    get_approval_store,
     get_integration_audit_log,
     get_slack_notifier,
     get_slack_ref_store,

From cd6d3acf983d6864adb0a9c5f8623b19b474377b Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 03:03:45 +0200
Subject: [PATCH 30/47] docs(api): state dead-writer status in relocated
 ApprovalStore docstring

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/integration.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/apps/api/forge_api/routers/integration.py b/apps/api/forge_api/routers/integration.py
index 8a7dbe91..71e23ba5 100644
--- a/apps/api/forge_api/routers/integration.py
+++ b/apps/api/forge_api/routers/integration.py
@@ -239,6 +239,12 @@ class ApprovalStore:
     and decision is scoped to a workspace so one tenant can never see, fetch, or
     decide another tenant's gates. ``ApprovalRequest`` carries no ``workspace_id``
     field (it is a frozen contract), so ownership is tracked alongside the items.
+
+    Note: since the legacy ``POST /approval/requests`` route was removed, nothing
+    populates this store in production — the Slack notify/decide flow below
+    operates on an empty store until a writer is reintroduced (tests seed it
+    directly). Kept pending migration of Slack interactivity to the DB-backed
+    ``/approvals`` surface.
     """
 
     def __init__(self) -> None:

From ef0778560359bcf0067a6fa45a1bd95a38ed8ebf Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 03:10:36 +0200
Subject: [PATCH 31/47] fix(worker): register deployment tasks with celery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The deployment task module defined `forge.deployments.advance` and
`forge.deployments.request` but was absent from `celery_app`'s `include`
list, so nothing imported it at worker boot — the tasks were unregistered
dead code. Add `forge_worker.tasks.deployments` to `include`.

Decision rule (kept the sync path — no enqueue wired): `forge.deployments.request`
merely duplicates what `DeploymentService.request_deployment` already does
synchronously in-process (create + `DeploymentOrchestrator.advance()`). Evidence
of no surfaced retry/backoff benefit: no `.delay`/`.apply_async` call-site for
these tasks anywhere, no beat-schedule entry references them, and no code
references the task-name constants outside the task module. So we register +
test the tasks so they drive `DeploymentOrchestrator.advance()` correctly when
invoked, and leave the synchronous API path untouched.

TDD: RED — the module was not in `celery_app.conf.include`, so the tasks did
not resolve via the worker's boot path (`loader.import_default_modules()`).
GREEN after registration. Added behaviour tests that invoking
`request_deployment_task` / `advance_deployment` drives
`DeploymentOrchestrator.advance()` on the target deployment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/worker/forge_worker/celery_app.py |  1 +
 apps/worker/tests/test_deployments.py  | 90 ++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)

diff --git a/apps/worker/forge_worker/celery_app.py b/apps/worker/forge_worker/celery_app.py
index 8f5d5b0e..b73e409d 100644
--- a/apps/worker/forge_worker/celery_app.py
+++ b/apps/worker/forge_worker/celery_app.py
@@ -44,6 +44,7 @@ def get_broker_url() -> str:
         "forge_worker.tasks.audit",
         "forge_worker.tasks.self_eval_mint",
         "forge_worker.tasks.self_eval_run",
+        "forge_worker.tasks.deployments",
         "forge_worker.beat",
     ],
 )
diff --git a/apps/worker/tests/test_deployments.py b/apps/worker/tests/test_deployments.py
index bc0effb9..a95e5a14 100644
--- a/apps/worker/tests/test_deployments.py
+++ b/apps/worker/tests/test_deployments.py
@@ -13,7 +13,11 @@
 from forge_db.base import Base
 from forge_db.models import Project, User, Workspace
 from forge_db.models.deployment import Environment, EnvironmentPipeline
+from forge_deploy.orchestrator import DeploymentOrchestrator
+from forge_deploy.repository import DeploymentRepository
 from forge_deploy.schemas import GateConfig
+from forge_worker.celery_app import celery_app
+from forge_worker.tasks import deployments as deployments_task
 from forge_worker.tasks.deployments import (
     CeleryDeploymentRequester,
     request_deployment_sync,
@@ -107,3 +111,89 @@ def test_unknown_pipeline_returns_none(seeded) -> None:
         initiated_by="x",
     )
     assert dto is None
+
+
+# --------------------------------------------------------------- registration
+def test_deployment_tasks_registered_with_celery() -> None:
+    """The task module must be in the celery ``include`` list so the tasks
+    register at worker boot — independent of any test-time side-effect import.
+
+    ``loader.import_default_modules()`` is exactly what a real worker calls on
+    startup to import ``conf.include``; asserting through it proves the tasks
+    resolve from the include list rather than from this file's own import."""
+    assert "forge_worker.tasks.deployments" in (celery_app.conf.include or [])
+    celery_app.loader.import_default_modules()
+    assert "forge.deployments.advance" in celery_app.tasks
+    assert "forge.deployments.request" in celery_app.tasks
+
+
+# ------------------------------------------------------------- task behaviour
+def _seed_requested_deployment(
+    factory: sessionmaker[Session], project_id: uuid.UUID
+) -> uuid.UUID:
+    """Persist a bare REQUESTED deployment (no advance) and return its id."""
+    with factory() as s:
+        repo = DeploymentRepository(s, workspace_id=WS_ID)
+        pipeline = repo.get_pipeline_for_project(project_id)
+        assert pipeline is not None
+        env = repo.get_environment(pipeline.id, "dev")
+        assert env is not None
+        dep = repo.create_deployment(
+            project_id=project_id,
+            pipeline_id=pipeline.id,
+            environment_id=env.id,
+            environment_name=env.name,
+            repo_id=pipeline.repo_id,
+            commit_sha="abc123",
+            initiated_by="system:test",
+            state=DeploymentState.REQUESTED,
+        )
+        s.commit()
+        return dep.id
+
+
+def _spy_on_advance(monkeypatch) -> list[uuid.UUID]:
+    calls: list[uuid.UUID] = []
+    original = DeploymentOrchestrator.advance
+
+    def _spy(self: DeploymentOrchestrator, deployment_id: uuid.UUID) -> DeploymentState:
+        calls.append(deployment_id)
+        return original(self, deployment_id)
+
+    monkeypatch.setattr(DeploymentOrchestrator, "advance", _spy)
+    return calls
+
+
+def test_request_task_drives_orchestrator_advance(seeded, monkeypatch) -> None:
+    factory, project_id = seeded
+    monkeypatch.setattr(deployments_task, "_session_factory", lambda: factory)
+    advanced = _spy_on_advance(monkeypatch)
+
+    dep_id = deployments_task.request_deployment_task(
+        str(WS_ID),
+        str(project_id),
+        DeploymentRequest(environment="dev", commit_sha="abc123").model_dump(mode="json"),
+        "system:test",
+    )
+
+    assert dep_id is not None
+    # The task created the deployment and drove it through the orchestrator.
+    assert uuid.UUID(dep_id) in advanced
+    # No CI reader wired -> ci_green gate fails closed -> terminal GATE_REJECTED.
+    with factory() as s:
+        state = DeploymentRepository(s, workspace_id=WS_ID).get_or_404(uuid.UUID(dep_id)).state
+    assert state == DeploymentState.GATE_REJECTED
+
+
+def test_advance_task_drives_orchestrator_advance(seeded, monkeypatch) -> None:
+    factory, project_id = seeded
+    dep_id = _seed_requested_deployment(factory, project_id)
+    monkeypatch.setattr(deployments_task, "_session_factory", lambda: factory)
+    advanced = _spy_on_advance(monkeypatch)
+
+    result = deployments_task.advance_deployment(str(dep_id), str(WS_ID))
+
+    # The task resumed the FSM via DeploymentOrchestrator.advance() on that id.
+    assert dep_id in advanced
+    # REQUESTED -> gate-evaluate -> no CI -> GATE_REJECTED (fail-closed).
+    assert result == DeploymentState.GATE_REJECTED.value

From e619b7b968cc2123ecd34fbc986377b6175f0db1 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 03:19:43 +0200
Subject: [PATCH 32/47] fix(web): mark SAML single logout as not yet supported
 in SSO settings

---
 .../components/sso/sso-settings-view.test.tsx | 68 +++++++++++++++++++
 .../src/components/sso/sso-settings-view.tsx  | 16 ++++-
 2 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/sso/sso-settings-view.test.tsx b/apps/web/src/components/sso/sso-settings-view.test.tsx
index 9ac11333..bdd7d22a 100644
--- a/apps/web/src/components/sso/sso-settings-view.test.tsx
+++ b/apps/web/src/components/sso/sso-settings-view.test.tsx
@@ -255,6 +255,74 @@ describe("SsoSettingsView", () => {
     );
   });
 
+  it("renders the SLO URL field disabled with a not-yet-supported hint, but still shows a previously saved value", async () => {
+    const client = makeClient({
+      getSsoConfig: vi.fn(() =>
+        Promise.resolve(
+          makeConfig({
+            idp: {
+              entity_id: "https://idp.acme.com/saml/metadata",
+              sso_url: "https://idp.acme.com/sso",
+              slo_url: "https://idp.acme.com/slo",
+              x509_certs: [
+                "-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----",
+              ],
+              name_id_format:
+                "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+            },
+          }),
+        ),
+      ),
+    });
+    renderView(client);
+
+    const sloField = await screen.findByLabelText(/IdP SLO URL/i);
+    expect(sloField).toBeDisabled();
+    // Disabled != hidden: an admin who previously saved a value should still see it.
+    expect(sloField).toHaveValue("https://idp.acme.com/slo");
+    expect(
+      screen.getByText(/single logout is not yet supported/i),
+    ).toBeInTheDocument();
+    // House style bans "coming soon" phrasing everywhere in this view.
+    expect(screen.queryByText(/coming soon/i)).not.toBeInTheDocument();
+  });
+
+  it("keeps the saved SLO URL in the save payload even though the field is disabled", async () => {
+    const client = makeClient({
+      getSsoConfig: vi.fn(() =>
+        Promise.resolve(
+          makeConfig({
+            idp: {
+              entity_id: "https://idp.acme.com/saml/metadata",
+              sso_url: "https://idp.acme.com/sso",
+              slo_url: "https://idp.acme.com/slo",
+              x509_certs: [
+                "-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----",
+              ],
+              name_id_format:
+                "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
+            },
+          }),
+        ),
+      ),
+    });
+    renderView(client);
+    await screen.findByLabelText(/IdP SLO URL/i);
+
+    fireEvent.click(screen.getByTestId("sso-save"));
+
+    await waitFor(() =>
+      expect(client.putSsoConfig).toHaveBeenCalledWith(
+        WORKSPACE,
+        expect.objectContaining({
+          idp: expect.objectContaining({
+            slo_url: "https://idp.acme.com/slo",
+          }),
+        }),
+      ),
+    );
+  });
+
   it("adds a login domain to the verified list", async () => {
     renderView(makeClient());
     const input = await screen.findByLabelText("Add domain");
diff --git a/apps/web/src/components/sso/sso-settings-view.tsx b/apps/web/src/components/sso/sso-settings-view.tsx
index fb1ad9fc..aa4fbcd8 100644
--- a/apps/web/src/components/sso/sso-settings-view.tsx
+++ b/apps/web/src/components/sso/sso-settings-view.tsx
@@ -583,13 +583,25 @@ export function SsoSettingsView({
                   className={cn(FIELD, "font-mono text-xs")}
                 />
               </Field>
-              <Field label="IdP SLO URL" hint="optional">
+              <Field label="IdP SLO URL" hint="not yet supported">
                 <input
                   value={form.idpSloUrl}
+                  disabled
+                  aria-describedby="idp-slo-help"
                   onChange={(e) => patch("idpSloUrl", e.target.value)}
                   placeholder="https://idp.example.com/slo"
-                  className={cn(FIELD, "font-mono text-xs")}
+                  className={cn(
+                    FIELD,
+                    "font-mono text-xs disabled:cursor-not-allowed disabled:opacity-60",
+                  )}
                 />
+                <p
+                  id="idp-slo-help"
+                  className="text-xs text-muted-foreground"
+                >
+                  Single Logout is not yet supported. Forge keeps any saved
+                  value but can&apos;t yet act on it during sign-out.
+                </p>
               </Field>
             </div>
   

From f0a647b0a13bd681333a5696bbd1a7c156bfea28 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 03:25:41 +0200
Subject: [PATCH 33/47] fix(web): separate slo helper from label for clean
 name/description a11y

---
 .../components/sso/sso-settings-view.test.tsx | 13 +++++++
 .../src/components/sso/sso-settings-view.tsx  | 35 ++++++++++++-------
 2 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/apps/web/src/components/sso/sso-settings-view.test.tsx b/apps/web/src/components/sso/sso-settings-view.test.tsx
index bdd7d22a..cf8467ca 100644
--- a/apps/web/src/components/sso/sso-settings-view.test.tsx
+++ b/apps/web/src/components/sso/sso-settings-view.test.tsx
@@ -285,6 +285,19 @@ describe("SsoSettingsView", () => {
     ).toBeInTheDocument();
     // House style bans "coming soon" phrasing everywhere in this view.
     expect(screen.queryByText(/coming soon/i)).not.toBeInTheDocument();
+
+    // The helper sentence is a sibling of the <label>, not nested inside it, so
+    // it must NOT be folded into the input's accessible name — it should only
+    // reach assistive tech via aria-describedby, exactly like SsoSwitch's
+    // separate label/description elements.
+    expect(sloField).toHaveAccessibleName("IdP SLO URL");
+    const describedbyId = sloField.getAttribute("aria-describedby");
+    expect(describedbyId).toBeTruthy();
+    const describedbyEl = document.getElementById(describedbyId as string);
+    expect(describedbyEl).not.toBeNull();
+    expect(describedbyEl).toHaveTextContent(
+      /single logout is not yet supported/i,
+    );
   });
 
   it("keeps the saved SLO URL in the save payload even though the field is disabled", async () => {
diff --git a/apps/web/src/components/sso/sso-settings-view.tsx b/apps/web/src/components/sso/sso-settings-view.tsx
index aa4fbcd8..ca339934 100644
--- a/apps/web/src/components/sso/sso-settings-view.tsx
+++ b/apps/web/src/components/sso/sso-settings-view.tsx
@@ -583,18 +583,27 @@ export function SsoSettingsView({
                   className={cn(FIELD, "font-mono text-xs")}
                 />
               </Field>
-              <Field label="IdP SLO URL" hint="not yet supported">
-                <input
-                  value={form.idpSloUrl}
-                  disabled
-                  aria-describedby="idp-slo-help"
-                  onChange={(e) => patch("idpSloUrl", e.target.value)}
-                  placeholder="https://idp.example.com/slo"
-                  className={cn(
-                    FIELD,
-                    "font-mono text-xs disabled:cursor-not-allowed disabled:opacity-60",
-                  )}
-                />
+              <div className="flex flex-col gap-1.5">
+                <Field label="IdP SLO URL">
+                  <input
+                    value={form.idpSloUrl}
+                    disabled
+                    aria-describedby="idp-slo-help"
+                    onChange={(e) => patch("idpSloUrl", e.target.value)}
+                    placeholder="https://idp.example.com/slo"
+                    className={cn(
+                      FIELD,
+                      "font-mono text-xs disabled:cursor-not-allowed disabled:opacity-60",
+                    )}
+                  />
+                </Field>
+                {/*
+                 * Sibling of the label, not nested inside it: the input's accessible
+                 * NAME comes only from the <label> above, and its accessible
+                 * DESCRIPTION comes only from this paragraph via aria-describedby.
+                 * Keeping them as non-overlapping elements (see SsoSwitch) avoids
+                 * screen readers announcing this sentence twice.
+                 */}
                 <p
                   id="idp-slo-help"
                   className="text-xs text-muted-foreground"
@@ -602,7 +611,7 @@ export function SsoSettingsView({
                   Single Logout is not yet supported. Forge keeps any saved
                   value but can&apos;t yet act on it during sign-out.
                 </p>
-              </Field>
+              </div>
             </div>
   
             <Field

From 22e8fa1a1f50e73e42cb7461e510c76f847ed6d7 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 03:47:53 +0200
Subject: [PATCH 34/47] feat(spec): persist reject and request-changes review
 decisions end-to-end

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/spec.py            |  32 +++++
 apps/api/tests/test_spec_router.py            |  75 +++++++++++
 .../components/spec-studio/read-mode.test.tsx |  47 +++++--
 .../src/components/spec-studio/read-mode.tsx  |  57 ++++-----
 .../spec-studio/spec-studio.test.tsx          |  82 ++++++++++++
 .../components/spec-studio/spec-studio.tsx    |  30 ++++-
 .../web/src/components/spec/spec-meta.test.ts |  22 ++++
 apps/web/src/components/spec/spec-meta.ts     |  18 ++-
 apps/web/src/lib/api/client-spec.test.tsx     |  34 +++++
 apps/web/src/lib/api/client.ts                |  16 +++
 apps/web/src/lib/api/spec.test.tsx            |  98 +++++++++++++++
 apps/web/src/lib/api/spec.ts                  |  71 +++++++++++
 apps/web/src/lib/api/types.ts                 |  11 +-
 .../web/src/lib/spec-studio/markdown-parse.ts |   2 +-
 apps/web/src/lib/spec-studio/yaml-schema.ts   |   2 +-
 packages/contracts/forge_contracts/dtos.py    |   3 +
 packages/contracts/forge_contracts/enums.py   |   9 +-
 packages/contracts/tests/test_contracts.py    |   2 +
 packages/spec-engine/forge_spec/engine.py     |  38 +++++-
 packages/spec-engine/forge_spec/gates.py      |  36 +++++-
 packages/spec-engine/forge_spec/markdown.py   |   2 +
 .../spec-engine/tests/test_spec_lifecycle.py  | 117 ++++++++++++++++++
 .../spec-engine/tests/test_spec_manifest.py   |  20 +++
 .../spec-engine/tests/test_spec_markdown.py   |  16 +++
 24 files changed, 785 insertions(+), 55 deletions(-)

diff --git a/apps/api/forge_api/routers/spec.py b/apps/api/forge_api/routers/spec.py
index 56533678..8ef0c555 100644
--- a/apps/api/forge_api/routers/spec.py
+++ b/apps/api/forge_api/routers/spec.py
@@ -178,6 +178,12 @@ class TextContent(BaseModel):
     content: str
 
 
+class SpecReviewRequest(BaseModel):
+    """Body for the reject / request-changes review endpoints."""
+
+    note: str = ""
+
+
 class DraftSpecRequest(BaseModel):
     """Body for ``POST /spec/draft`` (BYOK AI spec drafting; draft-only)."""
 
@@ -343,6 +349,32 @@ def approve_spec(engine: EngineDep, spec_id: uuid.UUID) -> SpecManifest:
         return engine.approve_spec(spec_id)
 
 
+@router.post("/specs/{spec_id}/reject", response_model=SpecManifest, dependencies=[WriteGate])
+def reject_spec(engine: EngineDep, spec_id: uuid.UUID, request: SpecReviewRequest) -> SpecManifest:
+    """Reject a spec at the human gate; moves it to ``rejected``.
+
+    Persists the reviewer's note in the manifest. 409 when the spec is already
+    past the gate (``approved`` and beyond), mirroring the tasks gate.
+    """
+    with _spec_errors():
+        return engine.reject_spec(spec_id, request.note)
+
+
+@router.post(
+    "/specs/{spec_id}/request-changes", response_model=SpecManifest, dependencies=[WriteGate]
+)
+def request_changes(
+    engine: EngineDep, spec_id: uuid.UUID, request: SpecReviewRequest
+) -> SpecManifest:
+    """Request changes on a spec at the human gate; moves it to ``changes_requested``.
+
+    The counterpart of the reject endpoint for the softer review outcome; same
+    persistence and 409 gating semantics.
+    """
+    with _spec_errors():
+        return engine.request_changes(spec_id, request.note)
+
+
 @router.post("/specs/{spec_id}/tasks", response_model=list[TaskDTO], dependencies=[WriteGate])
 def spec_tasks(engine: EngineDep, spec_id: uuid.UUID) -> list[TaskDTO]:
     """Generate implementation tasks from an approved spec (gated)."""
diff --git a/apps/api/tests/test_spec_router.py b/apps/api/tests/test_spec_router.py
index 0c787bd6..100a3b35 100644
--- a/apps/api/tests/test_spec_router.py
+++ b/apps/api/tests/test_spec_router.py
@@ -221,6 +221,81 @@ def test_read_missing_spec_manifest_yaml_is_404(client: TestClient) -> None:
     assert resp.status_code == 404
 
 
+def test_reject_spec_persists_status_and_note(client: TestClient) -> None:
+    manifest = _create_spec(client)
+    spec_uuid = spec_id_for_key(manifest["id"])
+
+    resp = client.post(
+        f"/spec/specs/{spec_uuid}/reject", json={"note": "Missing offline handling"}
+    )
+
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["status"] == "rejected"
+    assert body["review_note"] == "Missing offline handling"
+
+    # The decision survives a re-read (persisted, not echoed).
+    fetched = client.get(f"/spec/specs/{spec_uuid}")
+    assert fetched.status_code == 200
+    assert fetched.json()["status"] == "rejected"
+    assert fetched.json()["review_note"] == "Missing offline handling"
+
+
+def test_request_changes_persists_status_and_note(client: TestClient) -> None:
+    manifest = _create_spec(client)
+    spec_uuid = spec_id_for_key(manifest["id"])
+
+    resp = client.post(
+        f"/spec/specs/{spec_uuid}/request-changes", json={"note": "Please add a rate limit"}
+    )
+
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["status"] == "changes_requested"
+    assert body["review_note"] == "Please add a rate limit"
+
+    fetched = client.get(f"/spec/specs/{spec_uuid}")
+    assert fetched.json()["status"] == "changes_requested"
+    assert fetched.json()["review_note"] == "Please add a rate limit"
+
+
+def test_reject_after_approval_is_409(client: TestClient) -> None:
+    manifest = _create_spec(client)
+    spec_uuid = spec_id_for_key(manifest["id"])
+    assert client.post(f"/spec/specs/{spec_uuid}/approve").status_code == 200
+
+    resp = client.post(f"/spec/specs/{spec_uuid}/reject", json={"note": "too late"})
+
+    assert resp.status_code == 409
+    # The illegal transition did not mutate the spec.
+    assert client.get(f"/spec/specs/{spec_uuid}").json()["status"] == "approved"
+
+
+def test_request_changes_after_approval_is_409(client: TestClient) -> None:
+    manifest = _create_spec(client)
+    spec_uuid = spec_id_for_key(manifest["id"])
+    assert client.post(f"/spec/specs/{spec_uuid}/approve").status_code == 200
+
+    resp = client.post(f"/spec/specs/{spec_uuid}/request-changes", json={"note": "too late"})
+
+    assert resp.status_code == 409
+
+
+def test_reject_missing_spec_is_404(client: TestClient) -> None:
+    resp = client.post(f"/spec/specs/{uuid.uuid4()}/reject", json={"note": "no such spec"})
+    assert resp.status_code == 404
+
+
+def test_rejected_spec_cannot_generate_tasks(client: TestClient) -> None:
+    manifest = _create_spec(client)
+    spec_uuid = spec_id_for_key(manifest["id"])
+    client.post(f"/spec/specs/{spec_uuid}/reject", json={"note": "nope"})
+
+    resp = client.post(f"/spec/specs/{spec_uuid}/tasks")
+
+    assert resp.status_code == 409
+
+
 def test_lifecycle_clarify_plan_approve_tasks(client: TestClient) -> None:
     manifest = _create_spec(client)
     spec_uuid = spec_id_for_key(manifest["id"])
diff --git a/apps/web/src/components/spec-studio/read-mode.test.tsx b/apps/web/src/components/spec-studio/read-mode.test.tsx
index 4bff4d70..cb1938eb 100644
--- a/apps/web/src/components/spec-studio/read-mode.test.tsx
+++ b/apps/web/src/components/spec-studio/read-mode.test.tsx
@@ -22,6 +22,8 @@ function setup(overrides: Partial<React.ComponentProps<typeof ReadMode>> = {}) {
   const props = {
     spec: baseSpec,
     onApprove: vi.fn(),
+    onReject: vi.fn(),
+    onRequestChanges: vi.fn(),
     ...overrides,
   } as React.ComponentProps<typeof ReadMode>;
   render(<ReadMode {...props} />);
@@ -65,7 +67,7 @@ describe("ReadMode", () => {
     expect(onApprove).toHaveBeenCalledTimes(1);
   });
 
-  it("pressing 'x' opens the reject note composer, and confirming records + calls onReject", () => {
+  it("pressing 'x' opens the reject note composer, and confirming sends the note to onReject", () => {
     const onReject = vi.fn();
     setup({ onReject });
     fireEvent.keyDown(screen.getByTestId("read-mode"), { key: "x" });
@@ -75,11 +77,12 @@ describe("ReadMode", () => {
     });
     fireEvent.click(screen.getByTestId("confirm-decision"));
     expect(onReject).toHaveBeenCalledWith("Missing offline handling");
-    expect(screen.getByTestId("review-recorded")).toHaveTextContent("Rejected");
-    expect(screen.getByTestId("review-recorded")).toHaveTextContent("Missing offline handling");
+    // The composer closes; the decision renders from the server-persisted
+    // manifest (via the spec prop), never from local component state.
+    expect(screen.queryByTestId("reason-composer")).not.toBeInTheDocument();
   });
 
-  it("pressing 'r' opens the request-changes note composer, and confirming records + calls onRequestChanges", () => {
+  it("pressing 'r' opens the request-changes note composer, and confirming sends the note to onRequestChanges", () => {
     const onRequestChanges = vi.fn();
     setup({ onRequestChanges });
     fireEvent.keyDown(screen.getByTestId("read-mode"), { key: "r" });
@@ -89,10 +92,9 @@ describe("ReadMode", () => {
     });
     fireEvent.click(screen.getByTestId("confirm-decision"));
     expect(onRequestChanges).toHaveBeenCalledWith("Please add a rate limit");
-    expect(screen.getByTestId("review-recorded")).toHaveTextContent("Changes requested");
   });
 
-  it("Escape cancels the note composer without recording a decision", () => {
+  it("Escape cancels the note composer without sending a decision", () => {
     const onReject = vi.fn();
     setup({ onReject });
     fireEvent.keyDown(screen.getByTestId("read-mode"), { key: "x" });
@@ -101,7 +103,30 @@ describe("ReadMode", () => {
     });
     expect(screen.queryByTestId("reason-composer")).not.toBeInTheDocument();
     expect(onReject).not.toHaveBeenCalled();
-    expect(screen.queryByTestId("review-recorded")).not.toBeInTheDocument();
+  });
+
+  it("renders a persisted rejected decision (status + note) from the manifest", () => {
+    setup({
+      spec: { ...baseSpec, status: "rejected", review_note: "Missing offline handling" },
+    });
+    expect(screen.getByTestId("read-status")).toHaveTextContent("Rejected");
+    expect(screen.getByTestId("review-decision")).toHaveTextContent("Rejected");
+    expect(screen.getByTestId("review-decision")).toHaveTextContent("Missing offline handling");
+  });
+
+  it("renders a persisted changes-requested decision from the manifest", () => {
+    setup({
+      spec: { ...baseSpec, status: "changes_requested", review_note: "Please add a rate limit" },
+    });
+    expect(screen.getByTestId("read-status")).toHaveTextContent("Changes requested");
+    expect(screen.getByTestId("review-decision")).toHaveTextContent("Changes requested");
+    expect(screen.getByTestId("review-decision")).toHaveTextContent("Please add a rate limit");
+  });
+
+  it("keeps the review gate open for a rejected spec (the decision can be revised)", () => {
+    setup({ spec: { ...baseSpec, status: "rejected" } });
+    expect(screen.queryByTestId("review-gate-closed")).not.toBeInTheDocument();
+    expect(screen.getByTestId("decision-approve")).toBeEnabled();
   });
 
   it("disables the decision bar once the spec is past the human gate", () => {
@@ -117,13 +142,13 @@ describe("ReadMode", () => {
     expect(onApprove).not.toHaveBeenCalled();
   });
 
-  it("surfaces an approve error from the caller", () => {
-    setup({ approveError: "Couldn't reach the spec engine" });
+  it("surfaces a server error from any review decision", () => {
+    setup({ errorMessage: "Couldn't reach the spec engine" });
     expect(screen.getByRole("alert")).toHaveTextContent("Couldn't reach the spec engine");
   });
 
-  it("shows a saving state on Approve while the mutation is pending", () => {
-    setup({ approving: true });
+  it("disables the decision bar while a review decision is in flight", () => {
+    setup({ pending: true });
     expect(screen.getByTestId("decision-approve")).toBeDisabled();
   });
 });
diff --git a/apps/web/src/components/spec-studio/read-mode.tsx b/apps/web/src/components/spec-studio/read-mode.tsx
index c9ec5b3c..39e6dcf1 100644
--- a/apps/web/src/components/spec-studio/read-mode.tsx
+++ b/apps/web/src/components/spec-studio/read-mode.tsx
@@ -20,21 +20,16 @@ function isEditableTarget(target: EventTarget | null): boolean {
 
 export interface ReadModeProps {
   spec: SpecManifest;
-  /** Approves the spec at the human gate (`POST /spec/specs/{id}/approve`, real). */
+  /** Approves the spec at the human gate (`POST /spec/specs/{id}/approve`). */
   onApprove: () => void;
-  approving?: boolean;
-  approveError?: string | null;
-  /**
-   * Reject / request-changes have no backend endpoint yet — `forge_spec`'s
-   * `FileSpecEngine` only exposes `approve_spec` (no `reject_spec` /
-   * `request_changes` state transition, and `SpecStatus` has no such values).
-   * Read mode still records the decision + note locally (so the keyboard-first
-   * review flow is fully usable) and surfaces it through these optional
-   * callbacks for a caller to persist once that endpoint exists — parked,
-   * tracked separately; not faked as a server round-trip.
-   */
-  onReject?: (note: string) => void;
-  onRequestChanges?: (note: string) => void;
+  /** Rejects the spec, persisting the note (`POST /spec/specs/{id}/reject`). */
+  onReject: (note: string) => void;
+  /** Requests changes, persisting the note (`POST /spec/specs/{id}/request-changes`). */
+  onRequestChanges: (note: string) => void;
+  /** True while any review decision (approve/reject/request-changes) is in flight. */
+  pending?: boolean;
+  /** Server error from the most recent review decision — always surfaced, never swallowed. */
+  errorMessage?: string | null;
 }
 
 /**
@@ -49,18 +44,19 @@ export interface ReadModeProps {
 export function ReadMode({
   spec,
   onApprove,
-  approving = false,
-  approveError = null,
   onReject,
   onRequestChanges,
+  pending = false,
+  errorMessage = null,
 }: ReadModeProps) {
   const [activeNote, setActiveNote] = useState<"reject" | "request_changes" | null>(null);
   const [note, setNote] = useState("");
-  const [recorded, setRecorded] = useState<{ action: "reject" | "request_changes"; note: string } | null>(
-    null,
-  );
 
   const reviewable = isApprovable(spec.status);
+  // The persisted review decision (server state, via the manifest) — never a
+  // local echo of a click that might not have survived the round-trip.
+  const decision =
+    spec.status === "rejected" || spec.status === "changes_requested" ? spec.status : null;
 
   const submit = useCallback(
     (action: ApprovalAction, reason?: string) => {
@@ -68,20 +64,18 @@ export function ReadMode({
         onApprove();
         return;
       }
-      const decision = action as "reject" | "request_changes";
       const trimmed = (reason ?? "").trim();
-      setRecorded({ action: decision, note: trimmed });
       setActiveNote(null);
       setNote("");
-      if (decision === "reject") onReject?.(trimmed);
-      else onRequestChanges?.(trimmed);
+      if (action === "reject") onReject(trimmed);
+      else onRequestChanges(trimmed);
     },
     [onApprove, onReject, onRequestChanges],
   );
 
   const trigger = useCallback(
     (action: ApprovalAction) => {
-      if (!reviewable || approving) return;
+      if (!reviewable || pending) return;
       if (action === "reject" || action === "request_changes") {
         setNote("");
         setActiveNote(action);
@@ -89,7 +83,7 @@ export function ReadMode({
         submit(action);
       }
     },
-    [reviewable, approving, submit],
+    [reviewable, pending, submit],
   );
 
   const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
@@ -246,15 +240,14 @@ export function ReadMode({
             </span>
           ) : null}
         </div>
-        {recorded ? (
+        {decision ? (
           <p
             role="status"
-            data-testid="review-recorded"
+            data-testid="review-decision"
             className="px-4 pt-3 text-xs text-muted-foreground"
           >
-            {recorded.action === "reject" ? "Rejected" : "Changes requested"}
-            {recorded.note ? ` — "${recorded.note}"` : ""} (recorded locally; not yet
-            persisted server-side).
+            {decision === "rejected" ? "Rejected" : "Changes requested"}
+            {spec.review_note ? ` — "${spec.review_note}"` : ""}
           </p>
         ) : null}
         <DecisionBar
@@ -262,9 +255,9 @@ export function ReadMode({
           activeNote={activeNote}
           note={note}
           onNoteChange={setNote}
-          pending={approving}
+          pending={pending}
           disabled={!reviewable}
-          errorMessage={approveError}
+          errorMessage={errorMessage}
           onTrigger={trigger}
           onConfirm={() => activeNote && submit(activeNote, note)}
           onCancel={() => {
diff --git a/apps/web/src/components/spec-studio/spec-studio.test.tsx b/apps/web/src/components/spec-studio/spec-studio.test.tsx
index f1614b63..103b4ffa 100644
--- a/apps/web/src/components/spec-studio/spec-studio.test.tsx
+++ b/apps/web/src/components/spec-studio/spec-studio.test.tsx
@@ -168,6 +168,88 @@ describe("SpecStudio", () => {
     );
   });
 
+  it("rejecting in Read mode posts the note to the server and renders the returned status", async () => {
+    const rejected: SpecManifest = {
+      ...manifest,
+      status: "rejected",
+      review_note: "Missing offline handling",
+    };
+    const client = makeClient({
+      getSpecManifest: vi.fn().mockResolvedValueOnce(manifest).mockResolvedValue(rejected),
+      rejectSpec: vi.fn(() => Promise.resolve(rejected)),
+    });
+    renderStudio(client);
+    await screen.findByTestId("guided-mode");
+
+    fireEvent.click(screen.getByTestId("studio-mode-read"));
+    await screen.findByTestId("read-mode");
+    fireEvent.click(screen.getByTestId("decision-reject"));
+    const composer = screen.getByTestId("reason-composer");
+    fireEvent.change(composer.querySelector("textarea") as HTMLTextAreaElement, {
+      target: { value: "Missing offline handling" },
+    });
+    fireEvent.click(screen.getByTestId("confirm-decision"));
+
+    await waitFor(() =>
+      expect(client.rejectSpec).toHaveBeenCalledWith("SPEC-1", "Missing offline handling"),
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("read-status")).toHaveTextContent("Rejected"),
+    );
+    expect(screen.getByTestId("review-decision")).toHaveTextContent("Missing offline handling");
+  });
+
+  it("requesting changes in Read mode posts the note to the server", async () => {
+    const changed: SpecManifest = {
+      ...manifest,
+      status: "changes_requested",
+      review_note: "Please add a rate limit",
+    };
+    const client = makeClient({
+      getSpecManifest: vi.fn().mockResolvedValueOnce(manifest).mockResolvedValue(changed),
+      requestSpecChanges: vi.fn(() => Promise.resolve(changed)),
+    });
+    renderStudio(client);
+    await screen.findByTestId("guided-mode");
+
+    fireEvent.click(screen.getByTestId("studio-mode-read"));
+    await screen.findByTestId("read-mode");
+    fireEvent.click(screen.getByTestId("decision-request_changes"));
+    const composer = screen.getByTestId("reason-composer");
+    fireEvent.change(composer.querySelector("textarea") as HTMLTextAreaElement, {
+      target: { value: "Please add a rate limit" },
+    });
+    fireEvent.click(screen.getByTestId("confirm-decision"));
+
+    await waitFor(() =>
+      expect(client.requestSpecChanges).toHaveBeenCalledWith("SPEC-1", "Please add a rate limit"),
+    );
+    await waitFor(() =>
+      expect(screen.getByTestId("read-status")).toHaveTextContent("Changes requested"),
+    );
+  });
+
+  it("surfaces a server error when rejecting fails (no silent local state)", async () => {
+    const client = makeClient({
+      rejectSpec: vi.fn(() => Promise.reject(new Error("spec engine unavailable"))),
+    });
+    renderStudio(client);
+    await screen.findByTestId("guided-mode");
+
+    fireEvent.click(screen.getByTestId("studio-mode-read"));
+    await screen.findByTestId("read-mode");
+    fireEvent.click(screen.getByTestId("decision-reject"));
+    fireEvent.change(
+      screen.getByTestId("reason-composer").querySelector("textarea") as HTMLTextAreaElement,
+      { target: { value: "nope" } },
+    );
+    fireEvent.click(screen.getByTestId("confirm-decision"));
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("spec engine unavailable");
+    // The status must not pretend the decision persisted.
+    expect(screen.getByTestId("read-status")).toHaveTextContent("Draft");
+  });
+
   it("disables the YAML save button and surfaces errors for an invalid manifest", async () => {
     renderStudio(makeClient());
     await screen.findByTestId("guided-mode");
diff --git a/apps/web/src/components/spec-studio/spec-studio.tsx b/apps/web/src/components/spec-studio/spec-studio.tsx
index c92c1f93..1289d1f0 100644
--- a/apps/web/src/components/spec-studio/spec-studio.tsx
+++ b/apps/web/src/components/spec-studio/spec-studio.tsx
@@ -5,7 +5,7 @@ import { useState } from "react";
 
 import { toast } from "@/components/ui/toast";
 import { apiClient, ApiError, type ForgeApiClient } from "@/lib/api/client";
-import { useApproveSpec } from "@/lib/api/spec";
+import { useApproveSpec, useRejectSpec, useRequestSpecChanges } from "@/lib/api/spec";
 import {
   useSaveGuidedManifest,
   useSaveSpecMarkdown,
@@ -123,6 +123,18 @@ export function SpecStudio({ specId, client = apiClient, collab }: SpecStudioPro
   const saveMarkdown = useSaveSpecMarkdown(specId, client);
   const saveYaml = useSaveSpecManifestYaml(specId, client);
   const approveSpec = useApproveSpec(client);
+  const rejectSpec = useRejectSpec(client);
+  const requestChanges = useRequestSpecChanges(client);
+
+  const reviewPending =
+    approveSpec.isPending || rejectSpec.isPending || requestChanges.isPending;
+  const reviewError = approveSpec.isError
+    ? errorMessage(approveSpec.error)
+    : rejectSpec.isError
+      ? errorMessage(rejectSpec.error)
+      : requestChanges.isError
+        ? errorMessage(requestChanges.error)
+        : null;
 
   const manifest = manifestQuery.data ?? null;
   const guidedValue = guidedOverride ?? manifest;
@@ -290,8 +302,20 @@ export function SpecStudio({ specId, client = apiClient, collab }: SpecStudioPro
                   { onSuccess: () => toast.success("Spec approved") },
                 )
               }
-              approving={approveSpec.isPending}
-              approveError={approveSpec.isError ? errorMessage(approveSpec.error) : null}
+              onReject={(note) =>
+                rejectSpec.mutate(
+                  { specId, note },
+                  { onSuccess: () => toast.success("Spec rejected") },
+                )
+              }
+              onRequestChanges={(note) =>
+                requestChanges.mutate(
+                  { specId, note },
+                  { onSuccess: () => toast.success("Changes requested") },
+                )
+              }
+              pending={reviewPending}
+              errorMessage={reviewError}
             />
           ) : null}
           {mode === "history" ? <VersionHistory specId={specId} client={client} /> : null}
diff --git a/apps/web/src/components/spec/spec-meta.test.ts b/apps/web/src/components/spec/spec-meta.test.ts
index 4d5a6c0b..4c535174 100644
--- a/apps/web/src/components/spec/spec-meta.test.ts
+++ b/apps/web/src/components/spec/spec-meta.test.ts
@@ -11,6 +11,8 @@ import {
   plainCurrentStep,
   plainStepCompletion,
   plainStepState,
+  STATUS_LABELS,
+  statusBadgeClass,
   traceSealed,
 } from "./spec-meta";
 
@@ -38,6 +40,26 @@ describe("isApprovable", () => {
     expect(isApprovable("approved")).toBe(false);
     expect(isApprovable("validated")).toBe(false);
   });
+
+  it("keeps rejected / changes-requested specs reviewable (still before the gate)", () => {
+    expect(isApprovable("rejected")).toBe(true);
+    expect(isApprovable("changes_requested")).toBe(true);
+  });
+});
+
+describe("review decision statuses", () => {
+  it("labels and badges the review statuses", () => {
+    expect(STATUS_LABELS.rejected).toBe("Rejected");
+    expect(STATUS_LABELS.changes_requested).toBe("Changes requested");
+    expect(statusBadgeClass("rejected")).toContain("danger");
+    expect(statusBadgeClass("changes_requested")).toContain("warning");
+  });
+
+  it("does not count a rejected spec as past the Approve step on the lifecycle rail", () => {
+    const [describeDone, , approveDone] = plainStepCompletion({ status: "rejected" });
+    expect(describeDone).toBe(true); // requirements were captured and reviewed
+    expect(approveDone).toBe(false); // the human gate was NOT passed
+  });
 });
 
 describe("plain-language lifecycle stepper", () => {
diff --git a/apps/web/src/components/spec/spec-meta.ts b/apps/web/src/components/spec/spec-meta.ts
index 1b8450fb..714105c5 100644
--- a/apps/web/src/components/spec/spec-meta.ts
+++ b/apps/web/src/components/spec/spec-meta.ts
@@ -19,6 +19,8 @@ export type StageState = "done" | "current" | "upcoming";
 export const STATUS_LABELS: Record<SpecStatus, string> = {
   draft: "Draft",
   clarifying: "Clarifying",
+  changes_requested: "Changes requested",
+  rejected: "Rejected",
   approved: "Approved",
   implementing: "Implementing",
   validated: "Validated",
@@ -35,16 +37,28 @@ export function statusBadgeClass(status: SpecStatus | undefined): string {
     case "implementing":
       return "border-primary/40 bg-primary/10 text-primary";
     case "clarifying":
+    case "changes_requested":
       return "border-warning/40 bg-warning/10 text-warning";
+    case "rejected":
+      return "border-danger/40 bg-danger/10 text-danger";
     case "draft":
     default:
       return "border-border bg-muted text-muted-foreground";
   }
 }
 
-/** The two statuses at (or before) the human approval gate. */
+/**
+ * The statuses at (or before) the human approval gate. Rejected /
+ * changes-requested specs stay reviewable — the decision can be revised
+ * (mirroring the engine's `REVIEWABLE_STATUSES` gate).
+ */
 export function isApprovable(status: SpecStatus | undefined): boolean {
-  return status === "draft" || status === "clarifying";
+  return (
+    status === "draft" ||
+    status === "clarifying" ||
+    status === "changes_requested" ||
+    status === "rejected"
+  );
 }
 
 export interface GateSummary {
diff --git a/apps/web/src/lib/api/client-spec.test.tsx b/apps/web/src/lib/api/client-spec.test.tsx
index ef989673..39c9d08c 100644
--- a/apps/web/src/lib/api/client-spec.test.tsx
+++ b/apps/web/src/lib/api/client-spec.test.tsx
@@ -134,6 +134,40 @@ describe("ForgeApiClient spec-engine surface", () => {
     expect(report.passed).toBe(true);
   });
 
+  it("rejectSpec and requestSpecChanges post the note to the review endpoints", async () => {
+    const fetchImpl = vi.fn((input: RequestInfo | URL, _init?: RequestInit) => {
+      const url = String(input);
+      if (url.includes("/request-changes")) {
+        return Promise.resolve(
+          json({ id: "SPEC-1", name: "x", status: "changes_requested", review_note: "tighten" }),
+        );
+      }
+      if (url.includes("/reject")) {
+        return Promise.resolve(
+          json({ id: "SPEC-1", name: "x", status: "rejected", review_note: "nope" }),
+        );
+      }
+      throw new Error(`unexpected request: ${url}`);
+    });
+    const client = new ForgeApiClient({ fetch: fetchImpl as unknown as typeof fetch });
+
+    const rejected = await client.rejectSpec("spec-1", "nope");
+    expect(rejected.status).toBe("rejected");
+    expect(rejected.review_note).toBe("nope");
+
+    const changed = await client.requestSpecChanges("spec-1", "tighten");
+    expect(changed.status).toBe("changes_requested");
+
+    const [rejectUrl, rejectInit] = fetchImpl.mock.calls[0];
+    expect(String(rejectUrl)).toContain("/spec/specs/spec-1/reject");
+    expect(rejectInit?.method).toBe("POST");
+    expect(JSON.parse(rejectInit?.body as string)).toEqual({ note: "nope" });
+
+    const [changesUrl, changesInit] = fetchImpl.mock.calls[1];
+    expect(String(changesUrl)).toContain("/spec/specs/spec-1/request-changes");
+    expect(JSON.parse(changesInit?.body as string)).toEqual({ note: "tighten" });
+  });
+
   it("getConstitution reads /spec/constitution/{project_id}", async () => {
     const fetchImpl = vi.fn((_input: RequestInfo | URL, _init?: RequestInit) =>
       Promise.resolve(json({ project_id: "proj-1", principles: ["Ship small"] })),
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index b5f4cd30..e3dab469 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -586,6 +586,22 @@ export class ForgeApiClient {
     );
   }
 
+  /** Reject a spec at the human gate — persists the decision + note (409 once approved). */
+  rejectSpec(specId: string, note: string): Promise<SpecManifest> {
+    return this.request<SpecManifest>(
+      `/spec/specs/${encodeURIComponent(specId)}/reject`,
+      { method: "POST", body: { note } },
+    );
+  }
+
+  /** Request changes on a spec at the human gate — persists the decision + note (409 once approved). */
+  requestSpecChanges(specId: string, note: string): Promise<SpecManifest> {
+    return this.request<SpecManifest>(
+      `/spec/specs/${encodeURIComponent(specId)}/request-changes`,
+      { method: "POST", body: { note } },
+    );
+  }
+
   /** Generate implementation tasks from an *approved* spec (409 if not). */
   generateTasks(specId: string): Promise<TaskDTO[]> {
     return this.request<TaskDTO[]>(
diff --git a/apps/web/src/lib/api/spec.test.tsx b/apps/web/src/lib/api/spec.test.tsx
index b4230233..e8bf446a 100644
--- a/apps/web/src/lib/api/spec.test.tsx
+++ b/apps/web/src/lib/api/spec.test.tsx
@@ -11,6 +11,8 @@ import {
   useCreateSpec,
   useGenerateTasks,
   usePlanSpec,
+  useRejectSpec,
+  useRequestSpecChanges,
   useSpecOverview,
   useValidateSpec,
 } from "./spec";
@@ -108,6 +110,102 @@ describe("useApproveSpec (optimistic)", () => {
   });
 });
 
+describe("useRejectSpec (optimistic review decision)", () => {
+  it("posts the note and flips the spec's status to rejected before the request resolves", async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+    });
+    queryClient.setQueryData(specKeys.overview("p1"), dashboard);
+
+    let resolve!: (value: SpecManifest) => void;
+    const pending = new Promise<SpecManifest>((r) => {
+      resolve = r;
+    });
+    const client = {
+      rejectSpec: vi.fn(() => pending),
+    } as unknown as ForgeApiClient;
+
+    const { result } = renderHook(() => useRejectSpec(client), {
+      wrapper: makeWrapper(queryClient),
+    });
+
+    act(() => {
+      result.current.mutate({ specId: "s1", note: "Missing offline handling" });
+    });
+
+    await waitFor(() => {
+      const data = queryClient.getQueryData<SpecDashboard>(specKeys.overview("p1"));
+      expect(data?.specs.find((s) => s.id === "s1")?.status).toBe("rejected");
+    });
+
+    act(() => {
+      resolve({
+        id: "s1",
+        name: "Passwordless auth",
+        status: "rejected",
+        review_note: "Missing offline handling",
+      });
+    });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(client.rejectSpec).toHaveBeenCalledWith("s1", "Missing offline handling");
+  });
+
+  it("rolls the dashboard back when the rejection fails server-side", async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+    });
+    queryClient.setQueryData(specKeys.overview("p1"), dashboard);
+    const client = {
+      rejectSpec: vi.fn(() => Promise.reject(new Error("409 conflict"))),
+    } as unknown as ForgeApiClient;
+
+    const { result } = renderHook(() => useRejectSpec(client), {
+      wrapper: makeWrapper(queryClient),
+    });
+
+    act(() => {
+      result.current.mutate({ specId: "s1", note: "too late" });
+    });
+
+    await waitFor(() => expect(result.current.isError).toBe(true));
+    const data = queryClient.getQueryData<SpecDashboard>(specKeys.overview("p1"));
+    expect(data?.specs.find((s) => s.id === "s1")?.status).toBe("clarifying");
+  });
+});
+
+describe("useRequestSpecChanges (optimistic review decision)", () => {
+  it("posts the note and flips the spec's status to changes_requested", async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: false }, queries: { retry: false } },
+    });
+    queryClient.setQueryData(specKeys.overview("p1"), dashboard);
+
+    const client = {
+      requestSpecChanges: vi.fn(() =>
+        Promise.resolve({
+          id: "s1",
+          name: "Passwordless auth",
+          status: "changes_requested",
+          review_note: "Please add a rate limit",
+        } satisfies SpecManifest),
+      ),
+    } as unknown as ForgeApiClient;
+
+    const { result } = renderHook(() => useRequestSpecChanges(client), {
+      wrapper: makeWrapper(queryClient),
+    });
+
+    act(() => {
+      result.current.mutate({ specId: "s1", note: "Please add a rate limit" });
+    });
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(client.requestSpecChanges).toHaveBeenCalledWith("s1", "Please add a rate limit");
+    const data = queryClient.getQueryData<SpecDashboard>(specKeys.overview("p1"));
+    expect(data?.specs.find((s) => s.id === "s1")?.status).toBe("changes_requested");
+  });
+});
+
 describe("useClarifySpec (optimistic, Describe step)", () => {
   it("flips the spec's status to clarifying before the request resolves", async () => {
     const queryClient = new QueryClient({
diff --git a/apps/web/src/lib/api/spec.ts b/apps/web/src/lib/api/spec.ts
index 01bff70a..35f35c29 100644
--- a/apps/web/src/lib/api/spec.ts
+++ b/apps/web/src/lib/api/spec.ts
@@ -196,6 +196,77 @@ export function useApproveSpec(
   });
 }
 
+export interface ReviewSpecVariables {
+  specId: string;
+  /** The reviewer's note — persisted server-side with the decision. */
+  note: string;
+}
+
+interface ReviewSpecContext {
+  previous: [readonly unknown[], SpecDashboard | undefined][];
+  previousManifest: SpecManifest | undefined;
+}
+
+/**
+ * Shared optimistic mutation for the two review decisions (reject /
+ * request-changes). Mirrors `useApproveSpec`'s treatment — a review decision
+ * is a simple status flip — but also flips the Spec Studio manifest cache so
+ * Read mode reflects the decision instantly; `onError` rolls both back and
+ * `onSettled` revalidates from the engine (the authoritative status +
+ * persisted note win).
+ */
+function useReviewSpecDecision(
+  client: ForgeApiClient,
+  status: "rejected" | "changes_requested",
+  send: (specId: string, note: string) => Promise<SpecManifest>,
+): UseMutationResult<SpecManifest, Error, ReviewSpecVariables, ReviewSpecContext> {
+  const queryClient = useQueryClient();
+  return useMutation<SpecManifest, Error, ReviewSpecVariables, ReviewSpecContext>({
+    mutationFn: ({ specId, note }) => send(specId, note),
+    onMutate: async ({ specId, note }) => {
+      await queryClient.cancelQueries({ queryKey: specKeys.overviews() });
+      await queryClient.cancelQueries({ queryKey: specStudioKeys.manifest(specId) });
+      const previous = optimisticallySetStatus(queryClient, specId, status);
+      const previousManifest = queryClient.getQueryData<SpecManifest>(
+        specStudioKeys.manifest(specId),
+      );
+      if (previousManifest) {
+        queryClient.setQueryData<SpecManifest>(specStudioKeys.manifest(specId), {
+          ...previousManifest,
+          status,
+          review_note: note || null,
+        });
+      }
+      return { previous, previousManifest };
+    },
+    onError: (_error, { specId }, context) => {
+      rollbackStatus(queryClient, context);
+      if (context?.previousManifest) {
+        queryClient.setQueryData(specStudioKeys.manifest(specId), context.previousManifest);
+      }
+    },
+    onSettled: (_data, _error, { specId }) => invalidateSpecCaches(queryClient, specId),
+  });
+}
+
+/** Reject a spec at the human gate (`POST /spec/specs/{id}/reject`). */
+export function useRejectSpec(
+  client: ForgeApiClient = apiClient,
+): UseMutationResult<SpecManifest, Error, ReviewSpecVariables, ReviewSpecContext> {
+  return useReviewSpecDecision(client, "rejected", (specId, note) =>
+    client.rejectSpec(specId, note),
+  );
+}
+
+/** Request changes on a spec at the human gate (`POST /spec/specs/{id}/request-changes`). */
+export function useRequestSpecChanges(
+  client: ForgeApiClient = apiClient,
+): UseMutationResult<SpecManifest, Error, ReviewSpecVariables, ReviewSpecContext> {
+  return useReviewSpecDecision(client, "changes_requested", (specId, note) =>
+    client.requestSpecChanges(specId, note),
+  );
+}
+
 // --------------------------------------------------------------------------- //
 // ss-lifecycle: the plain-language stepper's inline actions                   //
 //                                                                              //
diff --git a/apps/web/src/lib/api/types.ts b/apps/web/src/lib/api/types.ts
index 8c2233a2..3e5af362 100644
--- a/apps/web/src/lib/api/types.ts
+++ b/apps/web/src/lib/api/types.ts
@@ -345,10 +345,17 @@ export interface RedTeamGateOut {
 // Hand-maintained mirror of the spec DTOs in `forge_contracts.dtos` (Pydantic
 // v2). Enum string values match the Python `SpecStatus` StrEnum verbatim.
 
-/** The SDD lifecycle stages (forge_contracts.enums.SpecStatus), in order. */
+/**
+ * The SDD lifecycle stages (forge_contracts.enums.SpecStatus), in order.
+ * `changes_requested`/`rejected` are review decisions at the human gate: they
+ * sit between `clarifying` and `approved` (reviewed, but NOT past the gate) —
+ * ordering matters to every `indexOf`-based lifecycle comparison below.
+ */
 export const SPEC_STATUSES = [
   "draft",
   "clarifying",
+  "changes_requested",
+  "rejected",
   "approved",
   "implementing",
   "validated",
@@ -399,6 +406,8 @@ export interface SpecManifest {
   id: string;
   name: string;
   status?: SpecStatus;
+  /** Reviewer note from a reject / request-changes decision; cleared on approve. */
+  review_note?: string | null;
   constitution_refs?: string[];
   repos?: string[];
   requirements?: Requirement[];
diff --git a/apps/web/src/lib/spec-studio/markdown-parse.ts b/apps/web/src/lib/spec-studio/markdown-parse.ts
index 32e954eb..bdc11d6a 100644
--- a/apps/web/src/lib/spec-studio/markdown-parse.ts
+++ b/apps/web/src/lib/spec-studio/markdown-parse.ts
@@ -275,7 +275,7 @@ function parseDecisions(section: Section, issues: MarkdownIssue[]): ADR[] {
 }
 
 const FRONTMATTER_STRING_ARRAY_FIELDS = ["constitution_refs", "repos"] as const;
-const FRONTMATTER_NULLABLE_STRING_FIELDS = ["plan_ref", "tasks_ref", "validation_ref", "skill_profile"] as const;
+const FRONTMATTER_NULLABLE_STRING_FIELDS = ["review_note", "plan_ref", "tasks_ref", "validation_ref", "skill_profile"] as const;
 
 /**
  * Parse `spec.md` `text` into a best-effort `SpecManifest` plus every
diff --git a/apps/web/src/lib/spec-studio/yaml-schema.ts b/apps/web/src/lib/spec-studio/yaml-schema.ts
index 21934df2..b5a57178 100644
--- a/apps/web/src/lib/spec-studio/yaml-schema.ts
+++ b/apps/web/src/lib/spec-studio/yaml-schema.ts
@@ -29,7 +29,7 @@ export interface YamlIssue {
 const EXECUTION_MODES = ["single_agent", "supervised_multi_agent"] as const;
 
 const STRING_ARRAY_FIELDS = ["constitution_refs", "repos", "constraints"] as const;
-const NULLABLE_STRING_FIELDS = ["plan_ref", "tasks_ref", "validation_ref", "skill_profile"] as const;
+const NULLABLE_STRING_FIELDS = ["review_note", "plan_ref", "tasks_ref", "validation_ref", "skill_profile"] as const;
 
 /** Required scalar id/text shape shared by requirements, ACs, questions, ADRs. */
 function offsetToLine(text: string, offset: number): { line: number; column: number } {
diff --git a/packages/contracts/forge_contracts/dtos.py b/packages/contracts/forge_contracts/dtos.py
index f9051303..9b03db7a 100644
--- a/packages/contracts/forge_contracts/dtos.py
+++ b/packages/contracts/forge_contracts/dtos.py
@@ -723,6 +723,9 @@ class SpecManifest(_Model):
     id: str
     name: str
     status: SpecStatus = SpecStatus.DRAFT
+    #: Reviewer note recorded with a reject / request-changes decision at the
+    #: human gate; cleared when the spec is approved.
+    review_note: str | None = None
     constitution_refs: list[str] = Field(default_factory=list)
     repos: list[str] = Field(default_factory=list)
     requirements: list[Requirement] = Field(default_factory=list)
diff --git a/packages/contracts/forge_contracts/enums.py b/packages/contracts/forge_contracts/enums.py
index 9250f35c..2c8c6733 100644
--- a/packages/contracts/forge_contracts/enums.py
+++ b/packages/contracts/forge_contracts/enums.py
@@ -123,10 +123,17 @@ class ExecutionMode(enum.StrEnum):
 
 
 class SpecStatus(enum.StrEnum):
-    """Spec manifest status (spec: Spec Manifest Schema)."""
+    """Spec manifest status (spec: Spec Manifest Schema).
+
+    ``changes_requested``/``rejected`` are review decisions at the human gate:
+    they sit between ``clarifying`` and ``approved`` in lifecycle order (the
+    spec has been reviewed but has NOT passed the gate).
+    """
 
     DRAFT = "draft"
     CLARIFYING = "clarifying"
+    CHANGES_REQUESTED = "changes_requested"
+    REJECTED = "rejected"
     APPROVED = "approved"
     IMPLEMENTING = "implementing"
     VALIDATED = "validated"
diff --git a/packages/contracts/tests/test_contracts.py b/packages/contracts/tests/test_contracts.py
index 23c1d865..6a660b14 100644
--- a/packages/contracts/tests/test_contracts.py
+++ b/packages/contracts/tests/test_contracts.py
@@ -290,6 +290,8 @@ def test_spec_status_values() -> None:
     assert {s.value for s in fc.SpecStatus} == {
         "draft",
         "clarifying",
+        "changes_requested",
+        "rejected",
         "approved",
         "implementing",
         "validated",
diff --git a/packages/spec-engine/forge_spec/engine.py b/packages/spec-engine/forge_spec/engine.py
index a60a377d..e5f308e2 100644
--- a/packages/spec-engine/forge_spec/engine.py
+++ b/packages/spec-engine/forge_spec/engine.py
@@ -36,7 +36,7 @@
 from forge_contracts.dtos import ADR
 from forge_spec import manifest as manifest_io
 from forge_spec.errors import SpecNotFoundError, SpecReconcileWarning
-from forge_spec.gates import check_implementation_gate
+from forge_spec.gates import check_implementation_gate, check_review_gate
 from forge_spec.ids import (
     constitution_id_for,
     spec_dirname,
@@ -191,9 +191,43 @@ def spec_plan(self, spec_id: uuid.UUID) -> SpecManifest:
         return manifest
 
     def approve_spec(self, spec_id: uuid.UUID) -> SpecManifest:
-        """Approve a spec (the human gate); moves it to ``approved``."""
+        """Approve a spec (the human gate); moves it to ``approved``.
+
+        Clears any ``review_note`` left by an earlier reject / request-changes
+        decision — the note belongs to the latest review outcome.
+        """
         spec_dir, manifest = self._resolve(spec_id)
         manifest.status = SpecStatus.APPROVED
+        manifest.review_note = None
+        self._persist(manifest, spec_dir)
+        return manifest
+
+    def reject_spec(self, spec_id: uuid.UUID, note: str | None = None) -> SpecManifest:
+        """Reject a spec at the human gate; moves it to ``rejected``.
+
+        Persists the reviewer's ``note`` in the manifest (both canonical
+        serializations), so the decision survives reloads. Raises
+        ``SpecGateError`` when the spec is already past the gate
+        (``approved`` and beyond) — mirroring the implementation gate's
+        error family.
+        """
+        spec_dir, manifest = self._resolve(spec_id)
+        check_review_gate(manifest)
+        manifest.status = SpecStatus.REJECTED
+        manifest.review_note = note or None
+        self._persist(manifest, spec_dir)
+        return manifest
+
+    def request_changes(self, spec_id: uuid.UUID, note: str | None = None) -> SpecManifest:
+        """Request changes on a spec at the human gate; moves it to ``changes_requested``.
+
+        The counterpart of :meth:`reject_spec` for the softer review outcome;
+        same persistence and gating semantics.
+        """
+        spec_dir, manifest = self._resolve(spec_id)
+        check_review_gate(manifest)
+        manifest.status = SpecStatus.CHANGES_REQUESTED
+        manifest.review_note = note or None
         self._persist(manifest, spec_dir)
         return manifest
 
diff --git a/packages/spec-engine/forge_spec/gates.py b/packages/spec-engine/forge_spec/gates.py
index 8c35095c..31b1f541 100644
--- a/packages/spec-engine/forge_spec/gates.py
+++ b/packages/spec-engine/forge_spec/gates.py
@@ -18,6 +18,19 @@
 )
 
 
+#: Statuses from which a reviewer may still record a reject / request-changes
+#: decision. Once a spec is past the human gate (``approved`` and beyond) the
+#: review window is closed and the decision endpoints refuse the transition.
+REVIEWABLE_STATUSES: frozenset[SpecStatus] = frozenset(
+    {
+        SpecStatus.DRAFT,
+        SpecStatus.CLARIFYING,
+        SpecStatus.CHANGES_REQUESTED,
+        SpecStatus.REJECTED,
+    }
+)
+
+
 def check_implementation_gate(manifest: SpecManifest) -> SpecManifest:
     """Return ``manifest`` if it is implementable; else raise ``SpecGateError``."""
     if manifest.status not in IMPLEMENTABLE_STATUSES:
@@ -29,4 +42,25 @@ def check_implementation_gate(manifest: SpecManifest) -> SpecManifest:
     return manifest
 
 
-__all__ = ["IMPLEMENTABLE_STATUSES", "check_implementation_gate"]
+def check_review_gate(manifest: SpecManifest) -> SpecManifest:
+    """Return ``manifest`` if a review decision may still be recorded.
+
+    Raises the shared ``SpecGateError`` (the same domain-error family the
+    approve/tasks gates use) when the spec is already past the human gate —
+    e.g. rejecting an ``approved`` spec.
+    """
+    if manifest.status not in REVIEWABLE_STATUSES:
+        raise SpecGateError(
+            f"spec {manifest.id!r} is {manifest.status.value!r}; review decisions "
+            f"(reject / request changes) are only allowed before the human gate "
+            f"(allowed: {sorted(s.value for s in REVIEWABLE_STATUSES)})"
+        )
+    return manifest
+
+
+__all__ = [
+    "IMPLEMENTABLE_STATUSES",
+    "REVIEWABLE_STATUSES",
+    "check_implementation_gate",
+    "check_review_gate",
+]
diff --git a/packages/spec-engine/forge_spec/markdown.py b/packages/spec-engine/forge_spec/markdown.py
index e5ee6282..bc6689b8 100644
--- a/packages/spec-engine/forge_spec/markdown.py
+++ b/packages/spec-engine/forge_spec/markdown.py
@@ -17,6 +17,7 @@
     ---
     id: SPEC-1
     status: draft
+    review_note: null
     constitution_refs: []
     repos: []
     execution_mode: single_agent
@@ -106,6 +107,7 @@ def __init__(self, message: str, *, line: int | None = None) -> None:
 _FRONTMATTER_KEYS: tuple[str, ...] = (
     "id",
     "status",
+    "review_note",
     "constitution_refs",
     "repos",
     "execution_mode",
diff --git a/packages/spec-engine/tests/test_spec_lifecycle.py b/packages/spec-engine/tests/test_spec_lifecycle.py
index ed3d3ee7..2d222e90 100644
--- a/packages/spec-engine/tests/test_spec_lifecycle.py
+++ b/packages/spec-engine/tests/test_spec_lifecycle.py
@@ -164,6 +164,123 @@ def test_spec_tasks_writes_tasks_artifacts(engine) -> None:
     assert engine.read_manifest(spec_id).tasks_ref == "tasks.md"
 
 
+# --------------------------------------------------------------------------- #
+# Review decisions: reject / request changes (the other side of the human gate)#
+# --------------------------------------------------------------------------- #
+
+
+def test_reject_spec_moves_to_rejected_and_persists_note(engine, tmp_path) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+
+    rejected = engine.reject_spec(spec_id, "Missing pagination limits")
+
+    assert rejected.status is SpecStatus.REJECTED
+    assert rejected.review_note == "Missing pagination limits"
+    # The decision survives a fresh engine over the same root (disk, not memory),
+    # and the two on-disk serializations agree (no reconcile warning).
+    import warnings as _warnings
+
+    with _warnings.catch_warnings():
+        _warnings.simplefilter("error")
+        reloaded = FileSpecEngine(tmp_path).read_manifest(spec_id)
+    assert reloaded.status is SpecStatus.REJECTED
+    assert reloaded.review_note == "Missing pagination limits"
+
+
+def test_request_changes_moves_to_changes_requested_and_persists_note(engine, tmp_path) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.spec_clarify(spec_id)
+
+    changed = engine.request_changes(spec_id, "Please add a rate limit")
+
+    assert changed.status is SpecStatus.CHANGES_REQUESTED
+    assert changed.review_note == "Please add a rate limit"
+    reloaded = FileSpecEngine(tmp_path).read_manifest(spec_id)
+    assert reloaded.status is SpecStatus.CHANGES_REQUESTED
+    assert reloaded.review_note == "Please add a rate limit"
+
+
+def test_reject_without_note_stores_none(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+
+    rejected = engine.reject_spec(spec_id)
+
+    assert rejected.status is SpecStatus.REJECTED
+    assert rejected.review_note is None
+
+
+def test_reject_already_approved_spec_raises_gate_error(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.approve_spec(spec_id)
+
+    with pytest.raises(SpecGateError):
+        engine.reject_spec(spec_id, "too late")
+    # The illegal transition must not have mutated the manifest.
+    assert engine.read_manifest(spec_id).status is SpecStatus.APPROVED
+
+
+def test_request_changes_on_approved_spec_raises_gate_error(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.approve_spec(spec_id)
+
+    with pytest.raises(SpecGateError):
+        engine.request_changes(spec_id, "too late")
+
+
+def test_review_decision_can_be_revised_before_the_gate(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+
+    engine.reject_spec(spec_id, "first pass: no")
+    revised = engine.request_changes(spec_id, "actually, just add auth")
+
+    assert revised.status is SpecStatus.CHANGES_REQUESTED
+    assert revised.review_note == "actually, just add auth"
+
+
+def test_rejected_spec_is_not_implementable(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.reject_spec(spec_id, "nope")
+
+    with pytest.raises(SpecGateError):
+        engine.spec_tasks(spec_id)
+    with pytest.raises(SpecGateError):
+        engine.ensure_implementable(spec_id)
+
+
+def test_changes_requested_spec_is_not_implementable(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.request_changes(spec_id, "tighten acceptance criteria")
+
+    with pytest.raises(SpecGateError):
+        engine.ensure_implementable(spec_id)
+
+
+def test_approve_after_review_decision_clears_the_note(engine) -> None:
+    manifest = engine.spec_create(uuid.uuid4(), "Customer endpoint", _requirements())
+    spec_id = spec_id_for_key(manifest.id)
+    engine.request_changes(spec_id, "add auth first")
+
+    approved = engine.approve_spec(spec_id)
+
+    assert approved.status is SpecStatus.APPROVED
+    assert approved.review_note is None
+
+
+def test_reject_unknown_spec_raises_not_found(engine) -> None:
+    from forge_spec import SpecNotFoundError
+
+    with pytest.raises(SpecNotFoundError):
+        engine.reject_spec(uuid.uuid4(), "no such spec")
+
+
 # --------------------------------------------------------------------------- #
 # manifest read/write                                                          #
 # --------------------------------------------------------------------------- #
diff --git a/packages/spec-engine/tests/test_spec_manifest.py b/packages/spec-engine/tests/test_spec_manifest.py
index 950ed946..a06a9970 100644
--- a/packages/spec-engine/tests/test_spec_manifest.py
+++ b/packages/spec-engine/tests/test_spec_manifest.py
@@ -97,6 +97,26 @@ def test_load_manifest_accepts_plain_dict_text() -> None:
     assert manifest.acceptance_criteria == []
 
 
+def test_review_statuses_and_note_round_trip_through_yaml() -> None:
+    # Reject / request-changes decisions live in the manifest (file-based
+    # engine), so the new statuses + note must survive dump/load.
+    for status, note in (
+        (SpecStatus.REJECTED, "Missing offline handling"),
+        (SpecStatus.CHANGES_REQUESTED, "Please add a rate limit"),
+    ):
+        original = SpecManifest(id="SPEC-5", name="Review me", status=status, review_note=note)
+        again = load_manifest(dump_manifest(original))
+        assert again.status is status
+        assert again.review_note == note
+        assert again == original
+
+
+def test_load_manifest_without_review_note_defaults_to_none() -> None:
+    # Pre-existing manifests (written before review decisions existed) load fine.
+    manifest = load_manifest("id: SPEC-9\nname: Minimal\nstatus: draft\n")
+    assert manifest.review_note is None
+
+
 def test_dump_manifest_status_enum_is_a_string_not_python_repr() -> None:
     # Guards against ``!!python/object`` leaking into the YAML for StrEnum fields.
     text = dump_manifest(SpecManifest(id="SPEC-1", name="x", status=SpecStatus.DRAFT))
diff --git a/packages/spec-engine/tests/test_spec_markdown.py b/packages/spec-engine/tests/test_spec_markdown.py
index f41eb482..d3970e86 100644
--- a/packages/spec-engine/tests/test_spec_markdown.py
+++ b/packages/spec-engine/tests/test_spec_markdown.py
@@ -142,6 +142,22 @@ def test_unicode_survives_round_trip() -> None:
     assert parse_spec_md(render_spec_md(manifest)) == manifest
 
 
+def test_review_status_and_note_survive_round_trip() -> None:
+    # Reject / request-changes decisions are manifest state, so spec.md (the
+    # other canonical serialization) must carry them too — otherwise the two
+    # formats diverge on every load.
+    manifest = SpecManifest(
+        id="SPEC-7",
+        name="Reviewed spec",
+        status=SpecStatus.REJECTED,
+        review_note="Missing offline handling",
+    )
+    parsed = parse_spec_md(render_spec_md(manifest))
+    assert parsed == manifest
+    assert parsed.status is SpecStatus.REJECTED
+    assert parsed.review_note == "Missing offline handling"
+
+
 def test_goal_section_carries_the_name() -> None:
     text = render_spec_md(_full_manifest())
     assert "## Goal\n\nCustomer endpoint improvements" in text

From ab21ce485356dcbed33a0ff32aac2e873ce36645 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 04:02:07 +0200
Subject: [PATCH 35/47] fix(web): clear stale review error when a sibling
 review mutation fires

---
 .../spec-studio/spec-studio.test.tsx          | 31 ++++++++++++++++
 .../components/spec-studio/spec-studio.tsx    | 36 ++++++++++++++-----
 2 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/apps/web/src/components/spec-studio/spec-studio.test.tsx b/apps/web/src/components/spec-studio/spec-studio.test.tsx
index 103b4ffa..6929dc19 100644
--- a/apps/web/src/components/spec-studio/spec-studio.test.tsx
+++ b/apps/web/src/components/spec-studio/spec-studio.test.tsx
@@ -250,6 +250,37 @@ describe("SpecStudio", () => {
     expect(screen.getByTestId("read-status")).toHaveTextContent("Draft");
   });
 
+  it("clears a stale rejection error once a later Approve succeeds (no unclearable alert)", async () => {
+    const client = makeClient({
+      rejectSpec: vi.fn(() => Promise.reject(new Error("spec engine unavailable"))),
+      approveSpec: vi.fn(() =>
+        Promise.resolve({ ...manifest, status: "approved" } satisfies SpecManifest),
+      ),
+    });
+    renderStudio(client);
+    await screen.findByTestId("guided-mode");
+
+    fireEvent.click(screen.getByTestId("studio-mode-read"));
+    await screen.findByTestId("read-mode");
+
+    // Reject fails first — its mutation is left in an error state.
+    fireEvent.click(screen.getByTestId("decision-reject"));
+    fireEvent.change(
+      screen.getByTestId("reason-composer").querySelector("textarea") as HTMLTextAreaElement,
+      { target: { value: "nope" } },
+    );
+    fireEvent.click(screen.getByTestId("confirm-decision"));
+    expect(await screen.findByRole("alert")).toHaveTextContent("spec engine unavailable");
+
+    // Approve then succeeds. A `rejectSpec` mutation only clears `isError` when
+    // IT is re-fired, so a naive "priority ternary over all three mutations"
+    // would keep showing the stale reject error forever.
+    fireEvent.click(screen.getByTestId("decision-approve"));
+    await waitFor(() => expect(client.approveSpec).toHaveBeenCalledWith("SPEC-1"));
+
+    await waitFor(() => expect(screen.queryByRole("alert")).not.toBeInTheDocument());
+  });
+
   it("disables the YAML save button and surfaces errors for an invalid manifest", async () => {
     renderStudio(makeClient());
     await screen.findByTestId("guided-mode");
diff --git a/apps/web/src/components/spec-studio/spec-studio.tsx b/apps/web/src/components/spec-studio/spec-studio.tsx
index 1289d1f0..bdc26e25 100644
--- a/apps/web/src/components/spec-studio/spec-studio.tsx
+++ b/apps/web/src/components/spec-studio/spec-studio.tsx
@@ -128,6 +128,13 @@ export function SpecStudio({ specId, client = apiClient, collab }: SpecStudioPro
 
   const reviewPending =
     approveSpec.isPending || rejectSpec.isPending || requestChanges.isPending;
+  // A priority ternary over three independent mutations would be unsafe on
+  // its own: react-query keeps `isError` set on a mutation until IT is
+  // re-fired, so an old failure could otherwise linger in `reviewError`
+  // after a *different* review decision has since succeeded. Safe here only
+  // because each `onApprove`/`onReject`/`onRequestChanges` handler below
+  // resets its siblings immediately before mutating, so at most one of these
+  // three can be `isError` at a time.
   const reviewError = approveSpec.isError
     ? errorMessage(approveSpec.error)
     : rejectSpec.isError
@@ -296,24 +303,35 @@ export function SpecStudio({ specId, client = apiClient, collab }: SpecStudioPro
           {mode === "read" ? (
             <ReadMode
               spec={manifest}
-              onApprove={() =>
+              onApprove={() => {
+                // Clear the siblings' settled state *before* firing this
+                // mutation: a mutation keeps `isError`/`isSuccess` until IT is
+                // re-fired, so without this a stale error from a previous
+                // reject/request-changes attempt would linger in `reviewError`
+                // forever, even after this decision succeeds.
+                rejectSpec.reset();
+                requestChanges.reset();
                 approveSpec.mutate(
                   { specId },
                   { onSuccess: () => toast.success("Spec approved") },
-                )
-              }
-              onReject={(note) =>
+                );
+              }}
+              onReject={(note) => {
+                approveSpec.reset();
+                requestChanges.reset();
                 rejectSpec.mutate(
                   { specId, note },
                   { onSuccess: () => toast.success("Spec rejected") },
-                )
-              }
-              onRequestChanges={(note) =>
+                );
+              }}
+              onRequestChanges={(note) => {
+                approveSpec.reset();
+                rejectSpec.reset();
                 requestChanges.mutate(
                   { specId, note },
                   { onSuccess: () => toast.success("Changes requested") },
-                )
-              }
+                );
+              }}
               pending={reviewPending}
               errorMessage={reviewError}
             />

From 5f7dd0dcc35314d4769f9debc00bb51ef44085de Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 04:15:09 +0200
Subject: [PATCH 36/47] feat(worker): dispatch supervised multi-agent runs
 through forge_coordinator

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/worker/forge_worker/agent_runner.py |  18 +-
 apps/worker/forge_worker/multi_agent.py  | 232 +++++++++++++++++++++++
 apps/worker/pyproject.toml               |   3 +
 apps/worker/tests/test_agent_runner.py   | 215 ++++++++++++++++++++-
 uv.lock                                  |  30 ++-
 5 files changed, 478 insertions(+), 20 deletions(-)
 create mode 100644 apps/worker/forge_worker/multi_agent.py

diff --git a/apps/worker/forge_worker/agent_runner.py b/apps/worker/forge_worker/agent_runner.py
index 62ead82e..87c9f22f 100644
--- a/apps/worker/forge_worker/agent_runner.py
+++ b/apps/worker/forge_worker/agent_runner.py
@@ -44,7 +44,7 @@
 from forge_agent.testing import ScriptedModelClient, finish_response
 from forge_agent.tools import ToolRegistry
 from forge_auth.redaction import SecretRedactor
-from forge_contracts import AgentObjective, AgentRunResult, ModelClient
+from forge_contracts import AgentObjective, AgentRunResult, ExecutionMode, ModelClient
 from forge_db.models import RunRecording
 from forge_db.session import create_session_factory
 from forge_worker.celery_app import celery_app
@@ -316,6 +316,22 @@ def run_agent_task(
     dedup_key = idempotency_key or objective.get("task_id")
     if self.is_duplicate(dedup_key):
         return {"deduplicated": True, "idempotency_key": dedup_key}
+    if objective.get("execution_mode") == ExecutionMode.SUPERVISED_MULTI_AGENT.value:
+        # Task 17 (F27): a supervised-mode objective is driven by the
+        # deterministic multi-agent Supervisor, never a single AgentRunner.
+        # FORGE_RECORD_RUNS is a documented no-op on this branch (see the
+        # forge_worker.multi_agent module docstring).
+        from forge_worker.multi_agent import run_supervised_objective
+
+        try:
+            result = run_supervised_objective(objective)
+        except SoftTimeLimitExceeded:
+            return {
+                "escalated": True,
+                "reason": "soft_time_limit_exceeded",
+                "idempotency_key": dedup_key,
+            }
+        return result.model_dump(mode="json")
     runner = build_agent_runner()
     try:
         result = run_objective(runner, AgentObjective.model_validate(objective))
diff --git a/apps/worker/forge_worker/multi_agent.py b/apps/worker/forge_worker/multi_agent.py
new file mode 100644
index 00000000..13c04c74
--- /dev/null
+++ b/apps/worker/forge_worker/multi_agent.py
@@ -0,0 +1,232 @@
+"""Supervised multi-agent dispatch (Task 17 — worker-side wiring of F27).
+
+``forge.agent.run`` branches here when an :class:`~forge_contracts.AgentObjective`
+selects ``execution_mode=supervised_multi_agent``: the run is driven by the
+deterministic F27 :class:`~forge_coordinator.Supervisor` instead of a single
+:class:`~forge_agent.AgentRunner`, returning the same ``AgentRunResult`` contract
+(the Supervisor implements the foundation ``AgentRuntime`` protocol, so the task's
+observable contract — a JSON-serialisable result dict, dedup marker, soft-time-limit
+escalation — is unchanged).
+
+Glue provided here, all injectable for tests:
+
+* model clients — each subagent runtime is a real ``AgentRunner`` on the client
+  resolved ONCE per run by :func:`forge_worker.agent_runner._resolve_model_client`
+  (BYOK env lane, or the loud Task-1 scripted fallback);
+* persistence — ``sub_agent_run`` rows land via the coordinator's own
+  :class:`~forge_coordinator.SqlAlchemySubAgentRunSink` when the database and the
+  objective's identity (``context.workspace_id`` + ``context.parent_agent_run_id``)
+  are available. The supervisor's parent ``agent_run`` row (``is_supervisor=True``)
+  is ensured before dispatch (it is the FK target of every ``sub_agent_run`` row)
+  and finalized best-effort after the run. Without a reachable DB or identity the
+  adapter degrades to the in-memory sink with a WARNING instead of failing the run
+  (mirrors the fail-open recording sink in ``agent_runner``).
+
+Recording limitation (Time-Travel Runs): ``FORGE_RECORD_RUNS=1`` is a documented
+no-op on this path. The single-agent recorder wraps exactly one runner's model and
+tool boundaries into one linear ``RunCassette``; a supervised run spawns N subagent
+runners (concurrently under fan-out) plus git worktree/merge side effects outside
+the recorded boundaries, so a single shared cassette would interleave
+nondeterministically and could not honestly replay. Rather than fake parity, the
+branch logs a WARNING and records nothing; per-subagent cassettes need the durable
+child ``agent_run`` linkage that is still parked (see
+``agent_runner._maybe_persist_recording``).
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from forge_agent import AgentRunner
+from forge_contracts import AgentObjective, AgentRunResult, ModelClient
+from forge_coordinator import (
+    CoordinatorDeps,
+    CoordinatorSettings,
+    InMemorySubAgentRunSink,
+    SqlAlchemySubAgentRunSink,
+    SubAgentRunSink,
+    Supervisor,
+)
+from forge_db.models.enums import RunStatus as DbRunStatus
+from forge_db.session import create_session_factory
+
+__all__ = ["run_supervised_objective"]
+
+logger = logging.getLogger("forge.multi_agent")
+
+#: A zero-arg callable yielding a (context-manager) SQLAlchemy session.
+SessionFactory = Callable[[], Any]
+
+
+def _as_uuid(value: Any) -> uuid.UUID | None:
+    if isinstance(value, uuid.UUID):
+        return value
+    try:
+        return uuid.UUID(str(value)) if value else None
+    except ValueError:
+        return None
+
+
+def _with_parent_run_id(objective: AgentObjective) -> AgentObjective:
+    """Pin ``context.parent_agent_run_id`` so persisted rows and the returned
+    ``result.run_id`` share one identity (the Supervisor would otherwise mint an
+    id internally that this adapter could not have created the parent row for)."""
+    if _as_uuid(objective.context.get("parent_agent_run_id")) is not None:
+        return objective
+    context = {**objective.context, "parent_agent_run_id": str(uuid.uuid4())}
+    return objective.model_copy(update={"context": context})
+
+
+def _ensure_parent_agent_run(
+    session_factory: SessionFactory,
+    *,
+    parent_id: uuid.UUID,
+    workspace_id: uuid.UUID,
+    objective: AgentObjective,
+) -> None:
+    """Insert the supervisor's own ``agent_run`` row if it does not exist yet.
+
+    Every ``sub_agent_run`` row FKs ``parent_agent_run_id -> agent_run.id``, so
+    the parent row must exist before the graph dispatches (the coordinator's own
+    Postgres suite seeds exactly this row). ``task_id`` is intentionally left
+    NULL: the objective's task uuid is not guaranteed to exist in ``task``.
+    """
+    from forge_db.models import AgentRun
+
+    with session_factory() as session:
+        if session.get(AgentRun, parent_id) is not None:
+            return
+        session.add(
+            AgentRun(
+                id=parent_id,
+                workspace_id=workspace_id,
+                role="primary",
+                is_supervisor=True,
+                status=DbRunStatus.RUNNING,
+                inputs={
+                    "objective": objective.objective,
+                    "execution_mode": objective.execution_mode.value,
+                    "key": objective.key,
+                },
+                started_at=datetime.now(UTC),
+            )
+        )
+        session.commit()
+
+
+def _finalize_parent_agent_run(session_factory: SessionFactory, *, result: AgentRunResult) -> None:
+    """Best-effort: mirror the final supervised status onto the parent row.
+
+    Never raises — the run's contract is the returned ``AgentRunResult``; the
+    row update is durable observability on top (same fail-open stance as the
+    recording sink).
+    """
+    from forge_db.models import AgentRun
+
+    if result.run_id is None:  # pragma: no cover - finalize always sets run_id
+        return
+    try:
+        with session_factory() as session:
+            row = session.get(AgentRun, result.run_id)
+            if row is None:  # pragma: no cover - ensured before the run
+                return
+            row.status = DbRunStatus(result.status.value)
+            row.pattern = result.artifacts.get("pattern")
+            row.confidence = result.confidence
+            row.output = {"summary": result.summary, "output": result.output}
+            row.completed_at = datetime.now(UTC)
+            session.commit()
+    except Exception:
+        logger.exception("failed to finalize supervisor agent_run row (non-fatal)")
+
+
+def _resolve_sub_agent_sink(
+    objective: AgentObjective,
+) -> tuple[SubAgentRunSink, SessionFactory | None]:
+    """The durable SQL sink when DB + identity allow it; else in-memory (loud)."""
+    workspace_id = _as_uuid(objective.context.get("workspace_id"))
+    parent_id = _as_uuid(objective.context.get("parent_agent_run_id"))
+    if workspace_id is None or parent_id is None:
+        logger.warning(
+            "supervised run has no context.workspace_id/parent_agent_run_id; "
+            "sub_agent_run rows will NOT be durable (in-memory sink)"
+        )
+        return InMemorySubAgentRunSink(), None
+    try:
+        session_factory = create_session_factory()
+        _ensure_parent_agent_run(
+            session_factory,
+            parent_id=parent_id,
+            workspace_id=workspace_id,
+            objective=objective,
+        )
+        return SqlAlchemySubAgentRunSink(session_factory), session_factory
+    except Exception:
+        logger.warning(
+            "database unavailable for supervised-run persistence; sub_agent_run "
+            "rows will NOT be durable (in-memory sink)",
+            exc_info=True,
+        )
+        return InMemorySubAgentRunSink(), None
+
+
+def _agent_factory(default_client: ModelClient) -> Callable[[ModelClient | None], AgentRunner]:
+    """Build one subagent runtime per dispatch, on the per-role client when the
+    coordinator routed one, else the run's shared default client."""
+
+    def factory(model_client: ModelClient | None = None) -> AgentRunner:
+        return AgentRunner(model_client or default_client)
+
+    return factory
+
+
+def run_supervised_objective(
+    payload: dict[str, Any] | AgentObjective,
+    *,
+    model_client: ModelClient | None = None,
+    sub_agent_sink: SubAgentRunSink | None = None,
+    settings: CoordinatorSettings | None = None,
+) -> AgentRunResult:
+    """Run a supervised multi-agent objective through the F27 Supervisor.
+
+    Keyword seams exist for tests/DI only; the Celery task calls this with just
+    the payload. Settings come from the ``MULTI_AGENT_*`` environment — with
+    ``MULTI_AGENT_ENABLED`` unset the coordinator's own gate escalates the run
+    with ``needs_human_reason=multi_agent_disabled`` (never a silent
+    single-agent fallback).
+    """
+    # Local import: agent_runner lazily imports this module inside the task body,
+    # and this module needs its Task-1 model-client seam — resolve at call time.
+    from forge_worker.agent_runner import _recording_enabled, _resolve_model_client
+
+    objective = (
+        payload if isinstance(payload, AgentObjective) else AgentObjective.model_validate(payload)
+    )
+    objective = _with_parent_run_id(objective)
+
+    if _recording_enabled():
+        logger.warning(
+            "FORGE_RECORD_RUNS=1 is not supported on the supervised multi-agent "
+            "path; this run will NOT be recorded (single-cassette record/replay "
+            "cannot honestly capture N concurrent subagent runners — see the "
+            "forge_worker.multi_agent module docstring)"
+        )
+
+    session_factory: SessionFactory | None = None
+    if sub_agent_sink is None:
+        sub_agent_sink, session_factory = _resolve_sub_agent_sink(objective)
+
+    client = _resolve_model_client(model_client)
+    deps = CoordinatorDeps(
+        agent_factory=_agent_factory(client),
+        sub_agent_sink=sub_agent_sink,
+        settings=settings or CoordinatorSettings.from_env(),
+    )
+    result = Supervisor(deps).run(objective)
+    if session_factory is not None:
+        _finalize_parent_agent_run(session_factory, result=result)
+    return result
diff --git a/apps/worker/pyproject.toml b/apps/worker/pyproject.toml
index 863df779..4c577c0a 100644
--- a/apps/worker/pyproject.toml
+++ b/apps/worker/pyproject.toml
@@ -31,6 +31,9 @@ dependencies = [
     # forge-integrations supplies the GitHub PR-data source in the prod seam.
     "forge-eval",
     "forge-integrations",
+    # Task 17 — supervised multi-agent dispatch: forge.agent.run drives the F27
+    # Supervisor (forge_coordinator) when execution_mode=supervised_multi_agent.
+    "forge-coordinator",
 ]
 
 [build-system]
diff --git a/apps/worker/tests/test_agent_runner.py b/apps/worker/tests/test_agent_runner.py
index a85a029d..5f19e117 100644
--- a/apps/worker/tests/test_agent_runner.py
+++ b/apps/worker/tests/test_agent_runner.py
@@ -1,20 +1,32 @@
 """Tests for the worker agent-runner task (plan Task 1.9 — single-agent loop).
 
 Hermetic: an offline scripted model client drives the runtime; no network, no
-live model provider, no Celery broker.
+live model provider, no Celery broker. The supervised multi-agent dispatch tests
+(Task 17) use an in-memory SQLite engine for the ``sub_agent_run`` persistence
+assertions (mirrors ``test_run_recording.py``).
 """
 
 from __future__ import annotations
 
 import importlib.util
 import logging
+import uuid
+from collections.abc import Iterator
+from typing import Any
 
 import pytest
+from sqlalchemy import Engine, create_engine, select
+from sqlalchemy.orm import Session
 
 from forge_agent import AgentRunner
 from forge_agent.testing import ScriptedModelClient, finish_response
 from forge_contracts import AgentObjective
 from forge_contracts.enums import RunStatus
+from forge_db.base import Base
+from forge_db.models import AgentRun, RunRecording, SubAgentRun, Workspace
+from forge_db.models.enums import RunStatus as DbRunStatus
+from forge_worker import agent_runner as agent_runner_module
+from forge_worker import multi_agent
 from forge_worker.agent_runner import build_agent_runner, run_agent_task, run_objective
 
 
@@ -105,3 +117,204 @@ def test_run_agent_task_executes_and_serializes() -> None:
     import json
 
     json.dumps(result)
+
+
+# --------------------------------------------------------------------------- #
+# Supervised multi-agent dispatch (Task 17 — F27 wiring)                       #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.fixture
+def sqlite_engine() -> Iterator[Engine]:
+    engine = create_engine("sqlite://")
+    Base.metadata.create_all(engine)
+    try:
+        yield engine
+    finally:
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+
+def _seed_workspace(engine: Engine) -> uuid.UUID:
+    with Session(engine) as session:
+        ws = Workspace(name="Acme", slug=f"acme-{uuid.uuid4().hex[:8]}")
+        session.add(ws)
+        session.commit()
+        return ws.id
+
+
+def _supervised_payload(workspace_id: uuid.UUID, parent_id: uuid.UUID) -> dict[str, Any]:
+    """A supervised-mode objective payload as the Celery task receives it (JSON)."""
+    return {
+        "task_id": str(uuid.uuid4()),
+        "key": "TASK-17",
+        "objective": "Implement the feature under supervision",
+        "execution_mode": "supervised_multi_agent",
+        "subagent_policy": {"allowed": True, "max_parallel": 2},
+        "context": {
+            "workspace_id": str(workspace_id),
+            "parent_agent_run_id": str(parent_id),
+            "review_required": True,
+            "subagent_rules": {
+                "allow_subagents": True,
+                "allowed_roles": ["implementer", "reviewer"],
+                "max_parallel": 2,
+            },
+        },
+    }
+
+
+def _use_sqlite(monkeypatch: pytest.MonkeyPatch, engine: Engine) -> None:
+    """Point the adapter's DB seam at the hermetic SQLite engine."""
+    monkeypatch.setattr(multi_agent, "create_session_factory", lambda: lambda: Session(engine))
+
+
+def test_supervised_mode_dispatches_coordinator_and_persists_rows(
+    monkeypatch: pytest.MonkeyPatch, sqlite_engine: Engine, caplog: pytest.LogCaptureFixture
+) -> None:
+    """The supervised branch drives forge_coordinator end-to-end, offline.
+
+    Asserts the full Task-17 contract: the run completes through the Celery task
+    with the single-path observable contract (a JSON-serialisable AgentRunResult
+    dict), coordinator persistence rows exist (``sub_agent_run`` per specialist +
+    the supervisor's own ``agent_run`` row), and model-client construction reused
+    ``_resolve_model_client`` (the Task-1 scripted-fallback WARNING fires).
+    """
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    monkeypatch.delenv("FORGE_RECORD_RUNS", raising=False)
+    monkeypatch.setenv("MULTI_AGENT_ENABLED", "1")
+    _use_sqlite(monkeypatch, sqlite_engine)
+
+    ws_id = _seed_workspace(sqlite_engine)
+    parent_id = uuid.uuid4()
+
+    with caplog.at_level(logging.WARNING, logger="forge.agent_runner"):
+        result = run_agent_task(_supervised_payload(ws_id, parent_id))
+
+    # Same observable contract as the single path: a JSON-safe result dict.
+    import json
+
+    json.dumps(result)
+    assert result["status"] == RunStatus.SUCCEEDED.value
+    assert result["needs_human"] is False
+    assert result["artifacts"]["pattern"] == "maker_checker"
+    assert result["artifacts"]["is_supervisor"] is True
+    assert result["run_id"] == str(parent_id)
+
+    # Coordinator persistence rows: one sub_agent_run per spawned specialist.
+    with Session(sqlite_engine) as session:
+        rows = session.execute(select(SubAgentRun).order_by(SubAgentRun.ordinal)).scalars().all()
+        assert [r.role for r in rows] == ["implementer", "reviewer"]
+        assert all(r.parent_agent_run_id == parent_id for r in rows)
+        assert all(r.workspace_id == ws_id for r in rows)
+        assert all(r.status is DbRunStatus.SUCCEEDED for r in rows)
+        # The supervisor's own agent_run row exists and was finalized.
+        parent = session.get(AgentRun, parent_id)
+        assert parent is not None
+        assert parent.is_supervisor is True
+        assert parent.status is DbRunStatus.SUCCEEDED
+        assert parent.pattern == "maker_checker"
+        assert parent.completed_at is not None
+
+    # Model clients came through _resolve_model_client: the Task-1 loud fallback.
+    fallback = [
+        r
+        for r in caplog.records
+        if r.name == "forge.agent_runner"
+        and r.levelno == logging.WARNING
+        and "ScriptedModelClient" in r.getMessage()
+    ]
+    assert len(fallback) == 1, "expected exactly one scripted-fallback WARNING per run"
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {"objective": "do the thing"},
+        {"objective": "do the thing", "execution_mode": "single_agent"},
+    ],
+)
+def test_default_mode_builds_exactly_one_agent_runner(
+    monkeypatch: pytest.MonkeyPatch, payload: dict[str, Any]
+) -> None:
+    """Regression: non-supervised modes still build exactly one AgentRunner."""
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    calls: list[int] = []
+    real_build = agent_runner_module.build_agent_runner
+
+    def _counting_build(**kwargs: Any) -> AgentRunner:
+        calls.append(1)
+        return real_build(**kwargs)
+
+    monkeypatch.setattr(agent_runner_module, "build_agent_runner", _counting_build)
+
+    def _boom(*args: Any, **kwargs: Any) -> Any:
+        raise AssertionError("the supervised path must not run for non-supervised modes")
+
+    monkeypatch.setattr(multi_agent, "run_supervised_objective", _boom)
+
+    result = run_agent_task(payload)
+    assert len(calls) == 1
+    assert result["status"] in {RunStatus.SUCCEEDED.value, RunStatus.ESCALATED.value}
+
+
+def test_supervised_mode_single_runner_never_built(
+    monkeypatch: pytest.MonkeyPatch, sqlite_engine: Engine
+) -> None:
+    """The supervised branch never builds the single-agent runner."""
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    monkeypatch.setenv("MULTI_AGENT_ENABLED", "1")
+    _use_sqlite(monkeypatch, sqlite_engine)
+
+    def _boom(**kwargs: Any) -> Any:
+        raise AssertionError("build_agent_runner must not be called in supervised mode")
+
+    monkeypatch.setattr(agent_runner_module, "build_agent_runner", _boom)
+    ws_id = _seed_workspace(sqlite_engine)
+    result = run_agent_task(_supervised_payload(ws_id, uuid.uuid4()))
+    assert result["status"] == RunStatus.SUCCEEDED.value
+
+
+def test_supervised_mode_disabled_gate_escalates_without_db(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """MULTI_AGENT_ENABLED unset -> the coordinator's own disabled gate escalates.
+
+    Also covers the DB-unavailable degrade: with no reachable database the
+    adapter falls back to the in-memory sink instead of failing the run.
+    """
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    monkeypatch.delenv("MULTI_AGENT_ENABLED", raising=False)
+
+    def _no_db() -> Any:
+        raise RuntimeError("database unavailable")
+
+    monkeypatch.setattr(multi_agent, "create_session_factory", _no_db)
+
+    result = run_agent_task(_supervised_payload(uuid.uuid4(), uuid.uuid4()))
+    assert result["status"] == RunStatus.ESCALATED.value
+    assert result["needs_human"] is True
+    assert result["artifacts"]["needs_human_reason"] == "multi_agent_disabled"
+
+
+def test_supervised_mode_recording_is_honest_noop(
+    monkeypatch: pytest.MonkeyPatch, sqlite_engine: Engine, caplog: pytest.LogCaptureFixture
+) -> None:
+    """FORGE_RECORD_RUNS=1 on the supervised path: loud no-op, no RunRecording rows."""
+    monkeypatch.delenv("FORGE_MODEL_PROVIDER", raising=False)
+    monkeypatch.setenv("FORGE_RECORD_RUNS", "1")
+    monkeypatch.setenv("MULTI_AGENT_ENABLED", "1")
+    _use_sqlite(monkeypatch, sqlite_engine)
+
+    ws_id = _seed_workspace(sqlite_engine)
+    with caplog.at_level(logging.WARNING, logger="forge.multi_agent"):
+        result = run_agent_task(_supervised_payload(ws_id, uuid.uuid4()))
+
+    assert result["status"] == RunStatus.SUCCEEDED.value
+    with Session(sqlite_engine) as session:
+        assert session.execute(select(RunRecording)).scalars().all() == []
+    assert any(
+        "FORGE_RECORD_RUNS" in r.getMessage() and r.levelno == logging.WARNING
+        for r in caplog.records
+        if r.name == "forge.multi_agent"
+    )
diff --git a/uv.lock b/uv.lock
index 7487d674..6928908d 100644
--- a/uv.lock
+++ b/uv.lock
@@ -576,34 +576,34 @@ wheels = [
 
 [package.optional-dependencies]
 cudart = [
-    { name = "nvidia-cuda-runtime", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cuda-runtime" },
 ]
 cufft = [
-    { name = "nvidia-cufft", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cufft" },
 ]
 cufile = [
-    { name = "nvidia-cufile", marker = "sys_platform == 'linux'" },
+    { name = "nvidia-cufile" },
 ]
 cupti = [
-    { name = "nvidia-cuda-cupti", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cuda-cupti" },
 ]
 curand = [
-    { name = "nvidia-curand", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-curand" },
 ]
 cusolver = [
-    { name = "nvidia-cusolver", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cusolver" },
 ]
 cusparse = [
-    { name = "nvidia-cusparse", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cusparse" },
 ]
 nvjitlink = [
-    { name = "nvidia-nvjitlink", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-nvjitlink" },
 ]
 nvrtc = [
-    { name = "nvidia-cuda-nvrtc", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-cuda-nvrtc" },
 ]
 nvtx = [
-    { name = "nvidia-nvtx", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { name = "nvidia-nvtx" },
 ]
 
 [[package]]
@@ -1317,6 +1317,7 @@ dependencies = [
     { name = "forge-approval" },
     { name = "forge-board" },
     { name = "forge-contracts" },
+    { name = "forge-coordinator" },
     { name = "forge-db" },
     { name = "forge-deploy" },
     { name = "forge-eval" },
@@ -1338,6 +1339,7 @@ requires-dist = [
     { name = "forge-approval", editable = "packages/approval-sdk" },
     { name = "forge-board", editable = "packages/board-core" },
     { name = "forge-contracts", editable = "packages/contracts" },
+    { name = "forge-coordinator", editable = "packages/multi-agent-coordinator" },
     { name = "forge-db", editable = "packages/db" },
     { name = "forge-deploy", editable = "packages/deploy-core" },
     { name = "forge-eval", editable = "packages/evaluation" },
@@ -1427,9 +1429,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c3/93/43e116ee114b28737ba7e12952a0d4e2f55944d0f84e42bc91ba7192a3c9/greenlet-3.5.3-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:fd2e02fa07485778536a036222d616ab957b1d533f36b3ed98ce725d9c9d3117", size = 288202, upload-time = "2026-06-26T18:23:49.604Z" },
     { url = "https://files.pythonhosted.org/packages/82/2f/146d218299046a43d1f029fd544b3d110d0f175a09c715c7e8da4a4a345d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:df0a0628d1597eb0897b62f55d1343f772405fd25f3b2a796c76874b0c2e22e8", size = 654096, upload-time = "2026-06-26T19:07:12.71Z" },
     { url = "https://files.pythonhosted.org/packages/a0/cc/04738cafb3f45fa991ea44f9de94c47dcec964f5a972300988a6751f49d9/greenlet-3.5.3-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ebd933a6adabc298bab47731a130fe6bfb888bd934eee37810f151159544540d", size = 666304, upload-time = "2026-06-26T19:10:09.503Z" },
-    { url = "https://files.pythonhosted.org/packages/86/a9/73fa62893d5b84b4205544e6b673c654cc43aa5b9899bac00f04d64af73d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8d19fe6c39ebff9259f07bcc685d3290f8fa4ea2278e51dd0008e4d6b0f2d814", size = 670657, upload-time = "2026-06-26T19:24:19.967Z" },
     { url = "https://files.pythonhosted.org/packages/ce/aa/4e0dad5e605c270c784ab911c43da6adb136ccd4d81180f763ca429a723d/greenlet-3.5.3-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4b9d501b40e80b70e32323c799dd9b420a5577a9601469d362ae1ffb690f3a7c", size = 663635, upload-time = "2026-06-26T18:32:20.802Z" },
-    { url = "https://files.pythonhosted.org/packages/29/7e/2ffce64929fb3cab7b65d5a0b20aaf9764e227681d731b041077fc9a525a/greenlet-3.5.3-cp314-cp314-manylinux_2_39_riscv64.whl", hash = "sha256:962c5df2db8cb446da51edf1ca5296c389d93b99c9d8aa2ee4c7d0d8f1218260", size = 473497, upload-time = "2026-06-26T19:25:39.421Z" },
     { url = "https://files.pythonhosted.org/packages/d1/50/13efdbea246fe3d3b735e191fec08fb50809f53cd2383ebe123d0809e44b/greenlet-3.5.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a1fad1d11e7d6aab184107baa8e4ece11ccba3ec9599cd7efa5ff4d70d43256a", size = 1621252, upload-time = "2026-06-26T19:09:05.647Z" },
     { url = "https://files.pythonhosted.org/packages/f7/22/c0a336ae4a1410fd5f5121098e5bfbf1865f64c5ef80b4b5412886c4a332/greenlet-3.5.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:fad5aec764399f1b5cc347ad250a59660f20c8f8888ea6bae1f93b769cce1154", size = 1684824, upload-time = "2026-06-26T18:31:47.738Z" },
     { url = "https://files.pythonhosted.org/packages/7a/94/91aec0030bea75c4b3244251d0de60a1f3432d1ecb53ab6c437fb5c3ba61/greenlet-3.5.3-cp314-cp314-win_amd64.whl", hash = "sha256:7669aa24cf2a1041d6f7899575b494a3ab4cf68bfcc8609b1dc0be7272db835e", size = 240754, upload-time = "2026-06-26T18:22:15.669Z" },
@@ -1437,18 +1437,14 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/91/95/3e161213d7f1d378d15aa9e792093e9bfe01844680d04b7fd6e0107c9098/greenlet-3.5.3-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:271a8ea7c1024e8a0d7dd2be66dd66dda8a07193f41a17b9e924f7600f5b62be", size = 296389, upload-time = "2026-06-26T18:22:20.657Z" },
     { url = "https://files.pythonhosted.org/packages/00/92/715c44721abe2b4d1ae9abde4179411868a5bff312479f54e105d372f131/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:19131729ae0ddc3c2e1ef85e650169b5e37ee32e400f215f78b94d7b0d567310", size = 653382, upload-time = "2026-06-26T19:07:14.209Z" },
     { url = "https://files.pythonhosted.org/packages/a0/83/37a10372a1090a6624cca8e74c12df1a36c2dc36429ed0255b7fb1aeee23/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1540dd8e5fc2a5aec40fbb98ef8e149fa47c89a4b4a1cf2575a14d3d1869d7a8", size = 659401, upload-time = "2026-06-26T19:10:10.876Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/73/8faec206b851c22b1733545fda900829a1f3f5b1c78ae7e0fb3dba57d9f4/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b897d97759425953f69a9c0fac67f8fe333ec0ce7377ef186fb2b0c3ad5e354d", size = 659582, upload-time = "2026-06-26T19:24:21.357Z" },
     { url = "https://files.pythonhosted.org/packages/db/e2/d1509cad4207da559cc42986ecdd8fc67ad0d1bba2bf03023c467fd5e0f3/greenlet-3.5.3-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e81fa194a1d20967877bdf9c7794db2bc99063e5be36aee710c08f04c5bb087f", size = 656969, upload-time = "2026-06-26T18:32:22.272Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/55/50c19e49f8045834ada71ef12f8ad048eba8517c6aa41161bed676328fae/greenlet-3.5.3-cp314-cp314t-manylinux_2_39_riscv64.whl", hash = "sha256:3236754d423955ea08e9bb5f6c04a7895f9e22c290b66aa7653fcb922d839eb0", size = 491037, upload-time = "2026-06-26T19:25:40.672Z" },
     { url = "https://files.pythonhosted.org/packages/86/7d/eaf70de20aadca3a5884aec58362861c64ce45e7b277f47ed026926a3b89/greenlet-3.5.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:55cf4d777485d43110e47133cbba6d74a8885a87ec1227ef0267f9ee80c5aa21", size = 1617822, upload-time = "2026-06-26T19:09:06.893Z" },
     { url = "https://files.pythonhosted.org/packages/8a/f9/414d38fc400ae4350d4185eaad1827676f7cf5287b9136e0ed1cbbe20a7f/greenlet-3.5.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:12a248ba75f6a9a236375f52296c498c89ff1d8badf32deb9eca7abd5853f7da", size = 1677983, upload-time = "2026-06-26T18:31:49.396Z" },
     { url = "https://files.pythonhosted.org/packages/e4/15/7edb977e08f9bff702fe42d6c902702786ff6b9694058b4e6a2a6ac90e57/greenlet-3.5.3-cp314-cp314t-win_amd64.whl", hash = "sha256:efc6bd60ea02e085862c74a3ef64b147ffc6f1a5ea7d9f26e7a939943f68c1e3", size = 243626, upload-time = "2026-06-26T18:24:41.485Z" },
     { url = "https://files.pythonhosted.org/packages/2c/8a/93928dce91e6b3598b5e779e8d1fd6576a504640c58e78627077f6a7a91a/greenlet-3.5.3-cp315-cp315-macosx_11_0_universal2.whl", hash = "sha256:ea03f2f04367845d6b58eeed276e1e56e51f0b97d8ad5a88a7d20a91dc9056cc", size = 288860, upload-time = "2026-06-26T18:22:48.07Z" },
     { url = "https://files.pythonhosted.org/packages/4f/ca/69db42d447a1378043e2c8f19c09cbbd1263371505053c496b49066d3d16/greenlet-3.5.3-cp315-cp315-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78dbef602fda6d97d957eb7937f70c9ce9e9527330347f8f6b6f9e554a9e7a47", size = 659747, upload-time = "2026-06-26T19:07:15.565Z" },
     { url = "https://files.pythonhosted.org/packages/a8/0b/af7ac2ef8dd41e3da1a40dda6305c23b9a03e13ba975ec916357b50f8575/greenlet-3.5.3-cp315-cp315-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6f73857adb8fee13fa56c172bd11262f888c0c648f9fea113e777bb2c7904a81", size = 670419, upload-time = "2026-06-26T19:10:12.293Z" },
-    { url = "https://files.pythonhosted.org/packages/25/aa/952cf28c2ff949a8c971134fb43854dd7eaa737218723aaef758f8c9aead/greenlet-3.5.3-cp315-cp315-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:cefa9cef4b371f9844c6053db71f1138bc6807bab1578b0dae5149c1f1141357", size = 674261, upload-time = "2026-06-26T19:24:22.79Z" },
     { url = "https://files.pythonhosted.org/packages/51/1e/1d51640cacbfc455dbe9f9a9f594c49e4e244f63b9971a2f4764e46cc53d/greenlet-3.5.3-cp315-cp315-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:232fec92e823addaf02d9472cf7381e24a1d046a6ced1103c5caa4c21b9dfc1d", size = 668787, upload-time = "2026-06-26T18:32:24.298Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/f2/b00d6f5e63e531a93562b2ec1a4c320fbee91f580fc42e6417af69d706e5/greenlet-3.5.3-cp315-cp315-manylinux_2_39_riscv64.whl", hash = "sha256:6219b6d04dbf6ba6084d77dc609e8473060dc55f759cbf626d512122781fa128", size = 480322, upload-time = "2026-06-26T19:25:41.852Z" },
     { url = "https://files.pythonhosted.org/packages/21/66/4030d5b0b5894500023f003bb054d9bb354dfbd1e186c3a296759172f5f5/greenlet-3.5.3-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:2421c3564da9429d5586d46ca31ebb26516b5498a802cf65c041a8e8a8980d34", size = 1626305, upload-time = "2026-06-26T19:09:08.281Z" },
     { url = "https://files.pythonhosted.org/packages/0e/50/5221371c7550108dfa3c378debc41d032aa9c78e89abb01d8011cfc93289/greenlet-3.5.3-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:e0f0d160f0b2e558e6c75f7930967183255dc9735e5f5b8cae58ee09c9576d8b", size = 1688631, upload-time = "2026-06-26T18:31:51.278Z" },
     { url = "https://files.pythonhosted.org/packages/68/5d/00d469daae3c65d2bf620b10eee82eb022127d483c6bc8c69fae6f3fbf17/greenlet-3.5.3-cp315-cp315-win_amd64.whl", hash = "sha256:dd99329bbc15ca78dcc583dba05d0b1b0bae01ab6c2174989f5aaee3e41ac930", size = 241027, upload-time = "2026-06-26T18:22:38.203Z" },
@@ -1456,9 +1452,7 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1c/da/4f4a8450962fad137c1c8981a3f1b8919d06c829993d4d476f9c525d5173/greenlet-3.5.3-cp315-cp315t-macosx_11_0_universal2.whl", hash = "sha256:176bc16a721fa5fc294d70b87b4dfa5fbdd251b3da5d5372735ecef9bd7d6d0c", size = 297221, upload-time = "2026-06-26T18:23:27.176Z" },
     { url = "https://files.pythonhosted.org/packages/57/66/b3bfae3e220a9b63ea539a0eea681800c69ab1aada757eae8789f183e7ce/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:629b614d2b786e89c50440e246f33eea78f58a962d0bdbbcc809e6d13605903f", size = 657221, upload-time = "2026-06-26T19:07:16.973Z" },
     { url = "https://files.pythonhosted.org/packages/7b/81/b6d4d73a709684fc77e7fa034d7c2fe82cffa9fc920fadcaa659c2626213/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:2b2e857ae16f5f72142edf75f9f176fe7526ba19a2841df1420516f83831c9f2", size = 663226, upload-time = "2026-06-26T19:10:13.723Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/39/0e0938a75115b939d42733a2a12e1d349653c9531fe6fe563e8a681f04e6/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:16d192579ed281051396dddd7f7754dac6259e6b1fb26378c87b66622f8e3f91", size = 663706, upload-time = "2026-06-26T19:24:24.312Z" },
     { url = "https://files.pythonhosted.org/packages/f5/07/e210b02b589f16e74ff48b730690e4a34ffe984219fce4f3c1a0e7ec8545/greenlet-3.5.3-cp315-cp315t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e515757e2e36bcbf1fad09a46e1557e8b1ae1797d4b44d09da7deed88ad28608", size = 660802, upload-time = "2026-06-26T18:32:26.081Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/41/35d1c678cdb3c3b9e6bee691728e563cfb294202b23c7a4c3c2ccc343589/greenlet-3.5.3-cp315-cp315t-manylinux_2_39_riscv64.whl", hash = "sha256:4399eb8d041f20b68d943918bc55502a93d6fdc0a37c14da7881c04139acee9d", size = 498803, upload-time = "2026-06-26T19:25:43.063Z" },
     { url = "https://files.pythonhosted.org/packages/eb/2e/5303eb3fa06bca089060f479707182a93e360683bc252acf846c3090d34e/greenlet-3.5.3-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:b363d46ed1ea431825fdb01471bb024fc08399bad1572a616e853c7684415adb", size = 1622157, upload-time = "2026-06-26T19:09:09.527Z" },
     { url = "https://files.pythonhosted.org/packages/54/70/50de47a488f14df260b50ae34fb5d56016e308b098eab02c878b5223c26a/greenlet-3.5.3-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:e44da2f5bbdaabaf7d80b73dbb430c7035771e9f244e3c8b769715c9d8fa0a16", size = 1681159, upload-time = "2026-06-26T18:31:52.986Z" },
     { url = "https://files.pythonhosted.org/packages/a7/13/1055e1dda7882073eda533e2b96c62e55bbd2db7fda6d5ece992febc7071/greenlet-3.5.3-cp315-cp315t-win_amd64.whl", hash = "sha256:8ff8bed3e3baa20a3ea261ce00526f1898ad4801d4886fd2220580ee0ad8fadf", size = 244007, upload-time = "2026-06-26T18:22:04.353Z" },

From e4f05c5778ffe144ec9a1ec6757dbd62e52e5e3d Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 04:22:39 +0200
Subject: [PATCH 37/47] docs(config): document MULTI_AGENT_ENABLED gate in
 .env.example

---
 .env.example | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.env.example b/.env.example
index 79b1c2cc..31139896 100644
--- a/.env.example
+++ b/.env.example
@@ -102,6 +102,10 @@ FORGE_AUTH_PURGE_KEYS_INTERVAL_SECONDS=900
 # precedence; FORGE_MODEL_API_KEY is the provider-agnostic fallback.
 # FORGE_MODEL_API_KEY=
 
+# Multi-agent coordinator (supervised runs). Required `true` to enable; when false,
+# supervised runs escalate to a human with reason `multi_agent_disabled`.
+# MULTI_AGENT_ENABLED=false
+
 # Embeddings for hybrid-retrieval evaluation (OpenAI-compatible embedder), shown
 # with the built-in defaults; override to point at another endpoint.
 # EMBEDDING_MODEL=text-embedding-3-small

From 1d486eff7fe7f5e6987ad45a2ebbf47e1ccb7e4e Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 04:40:03 +0200
Subject: [PATCH 38/47] feat(pm): wire webhook intake to board-write sync task

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/pm.py          |  12 +-
 apps/api/forge_api/services/pm_service.py |  70 +++-
 apps/api/tests/pm_api/conftest.py         |  12 +-
 apps/api/tests/pm_api/test_webhooks.py    |  72 ++++
 apps/worker/forge_worker/celery_app.py    |   1 +
 apps/worker/forge_worker/tasks/pm_sync.py | 389 ++++++++++++++++++++++
 apps/worker/tests/test_pm_sync_task.py    | 364 ++++++++++++++++++++
 7 files changed, 905 insertions(+), 15 deletions(-)
 create mode 100644 apps/worker/forge_worker/tasks/pm_sync.py
 create mode 100644 apps/worker/tests/test_pm_sync_task.py

diff --git a/apps/api/forge_api/routers/pm.py b/apps/api/forge_api/routers/pm.py
index ae26d640..81780b9e 100644
--- a/apps/api/forge_api/routers/pm.py
+++ b/apps/api/forge_api/routers/pm.py
@@ -4,10 +4,14 @@
 signature/secret-verified webhook intake routes (no bearer). All queries are
 workspace-scoped (cross-workspace ids -> 404, no existence leak).
 
-Parked (needs the F01 Postgres board substrate — see ``pm_service`` docstring and
-the slice report): OAuth code-exchange routes, ``backfill`` enqueue, the manual
-conflict ``resolve`` execution, and the worker board-write/scan tasks. The
-sync engine that performs those is fully unit-tested in ``forge_integrations``.
+An accepted webhook now completes the inbound loop: the service persists the
+delivery and enqueues the worker board-write task ``forge.pm.process_webhook``
+(``forge_worker.tasks.pm_sync`` — re-fetch through the provider adapter, then
+``PMSyncEngine.sync_in`` onto the F01 Postgres board substrate, workspace-scoped
+and idempotent on redelivery; see the ``pm_service`` docstring).
+
+Still parked: OAuth code-exchange routes, ``backfill`` enqueue, the manual
+conflict ``resolve`` execution, and the outbound ``activity_events`` scan.
 """
 
 from __future__ import annotations
diff --git a/apps/api/forge_api/services/pm_service.py b/apps/api/forge_api/services/pm_service.py
index cd6c0b0a..711ae6e1 100644
--- a/apps/api/forge_api/services/pm_service.py
+++ b/apps/api/forge_api/services/pm_service.py
@@ -6,23 +6,32 @@
 dedupes inbound webhooks, and writes an immutable audit entry per accepted
 webhook / health probe.
 
-Board-write execution (the worker's ``process_webhook`` -> re-fetch ->
-``sync_in`` and the outbound ``activity_events`` scan) is intentionally **not**
-performed here — see module notes / the slice report: it depends on the F01
-Postgres board substrate (``activity_events`` outbox + versioned task service)
-which is not present in this foundation. The engine that performs it lives in
-``forge_integrations.pm.sync_engine`` and is fully unit-tested against fakes.
+Board-write execution now runs: each accepted (non-skipped) delivery enqueues
+the worker task ``forge.pm.process_webhook``
+(``forge_worker.tasks.pm_sync``), which re-fetches the changed issue through
+the provider adapter and upserts the board via the F01 Postgres board
+substrate (``SqlAlchemyBoardService`` + ``DbLinkRepository``), workspace-
+scoped and idempotent on redelivery. Enqueueing is fail-open: a broker outage
+logs a loud warning and the webhook still returns 202 (the persisted delivery
+row is the durable record for reprocessing).
+
+Still parked (unchanged scope): OAuth code exchange, historical backfill,
+manual conflict-resolve execution, external delete propagation, and the
+outbound ``activity_events`` scan.
 """
 
 from __future__ import annotations
 
 import builtins
 import hashlib
+import logging
+import os
 import secrets
 import time
 import uuid
 from collections.abc import Callable
 from datetime import UTC, datetime
+from functools import lru_cache
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
@@ -59,6 +68,29 @@
     PMTransport,
 )
 
+logger = logging.getLogger(__name__)
+
+#: Must match ``apps/worker/forge_worker/tasks/pm_sync.py::PM_SYNC_TASK`` —
+#: duplicated (not imported) because ``forge-api`` cannot depend on
+#: ``forge-worker`` (the dependency runs the other way); mirrors the
+#: ``FULL_SYNC_TASK`` pattern in ``mcp_index_service.py``.
+PROCESS_WEBHOOK_TASK = "forge.pm.process_webhook"
+
+
+@lru_cache(maxsize=1)
+def _celery_app() -> object:  # pragma: no cover - prod seam
+    from celery import Celery
+
+    url = os.environ.get("FORGE_REDIS_URL", "redis://localhost:6379/0")
+    return Celery("forge-api-enqueue", broker=url, backend=url)
+
+
+def enqueue_process_webhook(delivery_row_id: uuid.UUID) -> None:  # pragma: no cover - prod seam
+    """Enqueue the worker board-write task for one persisted delivery."""
+    _celery_app().send_task(  # type: ignore[attr-defined]
+        PROCESS_WEBHOOK_TASK, args=[str(delivery_row_id)]
+    )
+
 
 class PMConnectionNotFound(LookupError):
     """Raised when a connection id is absent in the caller's workspace."""
@@ -91,11 +123,13 @@ def __init__(
         vault: SecretVault,
         audit: AuditLog,
         transport_factory: Callable[[PMConnection], PMTransport] = _default_transport_factory,
+        process_webhook_enqueue: Callable[[uuid.UUID], None] = enqueue_process_webhook,
     ) -> None:
         self._sf = session_factory
         self._vault = vault
         self._audit = audit
         self._transport_factory = transport_factory
+        self._enqueue_process_webhook = process_webhook_enqueue
 
     # ------------------------------------------------------------------ #
     # connection CRUD                                                     #
@@ -322,10 +356,12 @@ def get_connection_any_workspace(self, connection_id: uuid.UUID) -> PMConnection
     def receive_webhook(
         self, connection: PMConnection, body: bytes, headers: dict[str, str]
     ) -> tuple[int, WebhookEvent | None]:
-        """Verify -> dedupe -> persist a delivery. Returns ``(status_code, event)``.
+        """Verify -> dedupe -> persist -> enqueue. Returns ``(status_code, event)``.
 
-        The payload is a *hint*; the worker re-fetches authoritative state before
-        any board write (parked — see module docstring). 401 on bad signature.
+        The payload is a *hint*; the worker task (``forge.pm.process_webhook``)
+        re-fetches authoritative state before the board write. 401 on bad
+        signature. Enqueue failures never fail the response (fail-open + warn);
+        skipped deliveries (disabled / outbound-only) are never enqueued.
         """
         adapter = self._build_adapter(connection)
         secret = self._webhook_secret(connection)
@@ -359,6 +395,7 @@ def receive_webhook(
             )
             session.add(delivery)
             session.commit()
+            delivery_row_id = delivery.id
 
         self._audit.record(
             category=AuditCategory.SYSTEM,
@@ -368,7 +405,18 @@ def receive_webhook(
             status=status.value,
             payload_hash=payload_hash,
         )
-        # NOTE: enqueue of pm.process_webhook is parked (worker board-write path).
+        if status == PMDeliveryStatus.RECEIVED:
+            try:
+                self._enqueue_process_webhook(delivery_row_id)
+            except Exception:
+                logger.warning(
+                    "pm webhook accepted but worker enqueue failed "
+                    "(delivery row %s, connection %s); the board write will not "
+                    "run until the delivery is reprocessed",
+                    delivery_row_id,
+                    connection.id,
+                    exc_info=True,
+                )
         return 202, event
 
     # ------------------------------------------------------------------ #
@@ -474,8 +522,10 @@ def _default_priority_map(provider: PMProvider) -> dict:
 
 
 __all__ = [
+    "PROCESS_WEBHOOK_TASK",
     "PMConflictExists",
     "PMConnectionNotFound",
     "PMConnectionService",
     "PMError",
+    "enqueue_process_webhook",
 ]
diff --git a/apps/api/tests/pm_api/conftest.py b/apps/api/tests/pm_api/conftest.py
index 23b8fa5c..7af395da 100644
--- a/apps/api/tests/pm_api/conftest.py
+++ b/apps/api/tests/pm_api/conftest.py
@@ -105,15 +105,25 @@ def audit() -> AuditLog:
     return AuditLog()
 
 
+@pytest.fixture
+def enqueued() -> list[uuid.UUID]:
+    """Delivery row ids handed to the worker-enqueue seam (recorded, no broker)."""
+    return []
+
+
 @pytest.fixture
 def pm_service(
-    session_factory: sessionmaker[Session], vault: SecretVault, audit: AuditLog
+    session_factory: sessionmaker[Session],
+    vault: SecretVault,
+    audit: AuditLog,
+    enqueued: list[uuid.UUID],
 ) -> PMConnectionService:
     return PMConnectionService(
         session_factory=session_factory,
         vault=vault,
         audit=audit,
         transport_factory=_transport_factory,
+        process_webhook_enqueue=enqueued.append,
     )
 
 
diff --git a/apps/api/tests/pm_api/test_webhooks.py b/apps/api/tests/pm_api/test_webhooks.py
index cb47ebf4..ce2fafdd 100644
--- a/apps/api/tests/pm_api/test_webhooks.py
+++ b/apps/api/tests/pm_api/test_webhooks.py
@@ -174,6 +174,78 @@ def test_outbound_only_records_skipped(
         assert row.status == PMDeliveryStatus.SKIPPED
 
 
+def _signed_linear(pm_service, vault, conn: dict, *, webhook_id: str) -> tuple[bytes, dict]:
+    secret = _webhook_secret(pm_service, uuid.UUID(conn["id"]), vault)
+    ts = int(datetime.now(UTC).timestamp() * 1000)
+    body = json.dumps(
+        {
+            "action": "update",
+            "type": "Issue",
+            "webhookTimestamp": ts,
+            "webhookId": webhook_id,
+            "data": {"id": "uuid-1", "identifier": "ENG-1"},
+        }
+    ).encode()
+    sig = sign_linear(secret, body)
+    return body, {"Linear-Signature": sig, "Content-Type": "application/json"}
+
+
+# --- Worker enqueue (board-write path) -------------------------------------- #
+
+
+def test_webhook_enqueues_board_write_once(
+    client, project_id, pm_service, vault, session_factory, enqueued
+) -> None:
+    """Post-persist the intake enqueues the worker task with the delivery row id;
+    a provider redelivery (same delivery id) never enqueues twice."""
+    conn = _create(client, project_id, "linear")
+    body, headers = _signed_linear(pm_service, vault, conn, webhook_id="wh-enq-1")
+    url = f"/integrations/pm/webhooks/linear/{conn['id']}"
+
+    assert client.post(url, content=body, headers=headers).status_code == 202
+    assert client.post(url, content=body, headers=headers).status_code == 202
+
+    from forge_db.models.pm import PMWebhookDelivery
+
+    with session_factory() as session:
+        row = session.query(PMWebhookDelivery).one()
+    assert enqueued == [row.id]
+
+
+def test_webhook_enqueue_failure_still_202(
+    client, project_id, pm_service, vault, monkeypatch, caplog
+) -> None:
+    """A broken broker must never fail the webhook response (fail-open + warn)."""
+    import logging
+
+    conn = _create(client, project_id, "linear")
+    body, headers = _signed_linear(pm_service, vault, conn, webhook_id="wh-enq-2")
+
+    def _boom(_row_id: uuid.UUID) -> None:
+        raise RuntimeError("broker down")
+
+    monkeypatch.setattr(pm_service, "_enqueue_process_webhook", _boom)
+    with caplog.at_level(logging.WARNING, logger="forge_api.services.pm_service"):
+        resp = client.post(
+            f"/integrations/pm/webhooks/linear/{conn['id']}", content=body, headers=headers
+        )
+    assert resp.status_code == 202
+    assert "enqueue failed" in caplog.text
+
+
+def test_webhook_skipped_delivery_not_enqueued(
+    client, project_id, pm_service, vault, enqueued
+) -> None:
+    """Outbound-only connections persist a skipped delivery and never enqueue."""
+    conn = _create(client, project_id, "linear", sync_direction="outbound_only")
+    body, headers = _signed_linear(pm_service, vault, conn, webhook_id="wh-enq-3")
+    resp = client.post(
+        f"/integrations/pm/webhooks/linear/{conn['id']}", content=body, headers=headers
+    )
+    assert resp.status_code == 202
+    assert enqueued == []
+
+
 def test_webhook_unknown_connection_404(client) -> None:
     resp = client.post(
         f"/integrations/pm/webhooks/linear/{uuid.uuid4()}",
diff --git a/apps/worker/forge_worker/celery_app.py b/apps/worker/forge_worker/celery_app.py
index b73e409d..0db19b6f 100644
--- a/apps/worker/forge_worker/celery_app.py
+++ b/apps/worker/forge_worker/celery_app.py
@@ -45,6 +45,7 @@ def get_broker_url() -> str:
         "forge_worker.tasks.self_eval_mint",
         "forge_worker.tasks.self_eval_run",
         "forge_worker.tasks.deployments",
+        "forge_worker.tasks.pm_sync",
         "forge_worker.beat",
     ],
 )
diff --git a/apps/worker/forge_worker/tasks/pm_sync.py b/apps/worker/forge_worker/tasks/pm_sync.py
new file mode 100644
index 00000000..cd4bb1f2
--- /dev/null
+++ b/apps/worker/forge_worker/tasks/pm_sync.py
@@ -0,0 +1,389 @@
+"""PM webhook board-write task (F18): ``forge.pm.process_webhook``.
+
+Completes the inbound half of the F18 sync loop that ``pm_service`` parked
+before the F01 Postgres board substrate existed. The API side verifies,
+dedupes, persists, and audits a webhook delivery, then enqueues this task with
+the delivery row id; here the worker:
+
+1. loads the persisted :class:`~forge_db.models.pm.PMWebhookDelivery` + its
+   :class:`~forge_db.models.pm.PMConnection` (the row carries the tenant);
+2. re-fetches the authoritative issue state through the provider adapter built
+   by the registry seam (``forge_integrations.pm.registry.build_adapter`` via
+   ``PMConnectionService`` — the payload is only ever a hint);
+3. runs :meth:`~forge_integrations.pm.sync_engine.PMSyncEngine.sync_in`, which
+   maps + upserts the board task through :class:`SqlBoardWriter` (the F01
+   ``SqlAlchemyBoardService`` scoped to the connection's workspace) and links
+   it durably via :class:`~forge_api.services.pm_link_repository_db.DbLinkRepository`.
+
+Idempotency is layered: the intake already dedupes on ``delivery_id`` (a
+provider redelivery never enqueues twice); a Celery redelivery of the same row
+early-returns once the row is marked processed; and a *distinct* delivery with
+identical content is echo-suppressed by the engine's content hash (no board
+write, row marked ``echo_suppressed``).
+
+Multi-tenancy: every write surface (board service, link repository, adapter
+resolution) is bound to the connection's ``workspace_id`` — a delivery can
+never write outside its own tenant.
+
+Still parked (unchanged scope): OAuth code exchange, historical backfill,
+manual conflict resolution, external delete propagation, and the outbound
+``activity_events`` scan.
+
+The pure function (``process_webhook``) is testable without Celery; the
+``*_task`` body is the production seam (mirrors ``sprint_tasks.py``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from forge_api.observability.audit import AuditCategory, AuditLog
+from forge_api.services.pm_link_repository_db import DbLinkRepository
+from forge_api.services.pm_service import PMConnectionService
+from forge_board import EntityNotFoundError, SqlAlchemyBoardService
+from forge_contracts import TaskDTO
+from forge_contracts.enums import Priority, TaskStatus
+from forge_contracts.pm import (
+    ConflictPolicy,
+    ForgePriority,
+    ForgeTask,
+    StatusCategory,
+    SyncDirection,
+)
+from forge_db.models.enums import PMConnectionStatus, PMDeliveryStatus, PMSyncDirection
+from forge_db.models.pm import PMConnection, PMWebhookDelivery
+from forge_integrations.pm.sync_engine import ForgeTaskPatch, PMSyncEngine
+from forge_worker.celery_app import celery_app
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
+    from forge_contracts.pm import ExternalTask, PMAdapter, SyncOutcome
+
+logger = logging.getLogger(__name__)
+
+#: Enqueued by name from ``forge_api.services.pm_service`` (the API cannot
+#: import ``forge_worker``; the dependency runs the other way).
+PM_SYNC_TASK = "forge.pm.process_webhook"
+
+# StatusCategory <-> board TaskStatus: the sync grain is the *category*; the
+# reverse map collapses the richer board states onto their category.
+_CATEGORY_TO_STATUS: dict[StatusCategory, TaskStatus] = {
+    StatusCategory.backlog: TaskStatus.BACKLOG,
+    StatusCategory.unstarted: TaskStatus.READY,
+    StatusCategory.started: TaskStatus.IN_PROGRESS,
+    StatusCategory.completed: TaskStatus.DONE,
+    StatusCategory.canceled: TaskStatus.CANCELLED,
+}
+_STATUS_TO_CATEGORY: dict[TaskStatus, StatusCategory] = {
+    TaskStatus.BACKLOG: StatusCategory.backlog,
+    TaskStatus.READY: StatusCategory.unstarted,
+    TaskStatus.READY_FOR_AGENT: StatusCategory.unstarted,
+    TaskStatus.IN_PROGRESS: StatusCategory.started,
+    TaskStatus.IN_REVIEW: StatusCategory.started,
+    TaskStatus.BLOCKED: StatusCategory.started,
+    TaskStatus.DONE: StatusCategory.completed,
+    TaskStatus.CANCELLED: StatusCategory.canceled,
+}
+# ForgePriority (PM grain, has ``none``) <-> board Priority (no ``none``).
+_PRIORITY_TO_BOARD: dict[ForgePriority, Priority] = {
+    ForgePriority.none: Priority.LOW,
+    ForgePriority.low: Priority.LOW,
+    ForgePriority.medium: Priority.MEDIUM,
+    ForgePriority.high: Priority.HIGH,
+    ForgePriority.urgent: Priority.URGENT,
+}
+_BOARD_TO_PRIORITY: dict[Priority, ForgePriority] = {
+    Priority.LOW: ForgePriority.low,
+    Priority.MEDIUM: ForgePriority.medium,
+    Priority.HIGH: ForgePriority.high,
+    Priority.URGENT: ForgePriority.urgent,
+}
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _aware(value: datetime | None) -> datetime:
+    """Normalise a (possibly naive, e.g. SQLite-read) timestamp to aware UTC."""
+    if value is None:
+        return _now()
+    return value if value.tzinfo is not None else value.replace(tzinfo=UTC)
+
+
+def _dto_to_forge_task(dto: TaskDTO) -> ForgeTask:
+    """Project a board ``TaskDTO`` onto the PM-sync ``ForgeTask`` grain."""
+    if dto.id is None or dto.project_id is None:  # pragma: no cover - persisted DTOs carry both
+        raise ValueError("persisted TaskDTO must carry id + project_id")
+    return ForgeTask(
+        id=dto.id,
+        key=dto.key or "",
+        project_id=dto.project_id,
+        title=dto.title,
+        description_md=dto.description,
+        status_category=_STATUS_TO_CATEGORY[dto.status],
+        priority=_BOARD_TO_PRIORITY[dto.priority],
+        assignee_email=None,  # board tasks key assignees by id, not email
+        label_names=list(dto.labels),
+        version=0,  # the board substrate carries no version column (see SqlBoardWriter)
+        updated_at=_aware(dto.updated_at),
+    )
+
+
+class SqlBoardWriter:
+    """The engine's ``BoardWriter`` over the F01 ``SqlAlchemyBoardService``.
+
+    Bound to a single workspace, so every create/update lands in the
+    connection's tenant only. ``expected_version`` is accepted but not enforced:
+    the board substrate has no per-row version column yet; last-write-wins
+    within the engine's own conflict detection (which compares content hashes,
+    not versions, before ever calling ``update``).
+    """
+
+    def __init__(self, session_factory: sessionmaker[Session], workspace_id: uuid.UUID) -> None:
+        self._board = SqlAlchemyBoardService(session_factory, workspace_id)
+
+    def get(self, forge_task_id: uuid.UUID) -> ForgeTask | None:
+        try:
+            dto = self._board.get_task(forge_task_id)
+        except EntityNotFoundError:
+            return None
+        return _dto_to_forge_task(dto)
+
+    def create(self, patch: ForgeTaskPatch, *, source: dict) -> ForgeTask:
+        dto = TaskDTO(
+            project_id=patch.project_id,
+            title=patch.title,
+            description=patch.description_md,
+            status=_CATEGORY_TO_STATUS[patch.status_category],
+            priority=_PRIORITY_TO_BOARD[patch.priority],
+            labels=list(patch.label_names),
+        )
+        return _dto_to_forge_task(self._board.create_task(dto))
+
+    def update(
+        self,
+        forge_task_id: uuid.UUID,
+        patch: ForgeTaskPatch,
+        *,
+        expected_version: int | None,
+        source: dict,
+    ) -> ForgeTask:
+        current = self._board.get_task(forge_task_id)
+        updated = current.model_copy(
+            update={
+                "title": patch.title,
+                "description": patch.description_md,
+                "status": _CATEGORY_TO_STATUS[patch.status_category],
+                "priority": _PRIORITY_TO_BOARD[patch.priority],
+                "labels": list(patch.label_names),
+            }
+        )
+        return _dto_to_forge_task(self._board.update_task(forge_task_id, updated))
+
+
+class _EngineAuditSink:
+    """Adapt the engine's dict-record ``AuditSink`` onto the structured AuditLog."""
+
+    def __init__(self, audit: AuditLog, workspace_id: uuid.UUID) -> None:
+        self._audit = audit
+        self._workspace_id = workspace_id
+
+    def record(self, entry: dict) -> None:
+        self._audit.record(
+            category=AuditCategory.SYSTEM,
+            action=f"pm_sync_{entry.get('operation', 'op')}",
+            workspace_id=self._workspace_id,
+            connection_id=entry.get("connection_id"),
+            target=entry.get("external_id"),
+            status=str(entry.get("result", "ok")),
+            payload_hash=entry.get("payload_hash"),
+            metadata={
+                "provider": entry.get("provider"),
+                "direction": entry.get("direction"),
+                "forge_task_id": entry.get("forge_task_id"),
+            },
+        )
+
+
+def _mark(
+    session_factory: sessionmaker[Session],
+    row_id: uuid.UUID,
+    status: PMDeliveryStatus,
+    *,
+    error: str | None = None,
+) -> None:
+    with session_factory() as session:
+        row = session.get(PMWebhookDelivery, row_id)
+        if row is None:  # pragma: no cover - row deleted mid-flight
+            return
+        row.status = status
+        row.processed_at = _now()
+        row.error = error
+        session.commit()
+
+
+def _result(action: str, row_id: uuid.UUID, **extra: str | None) -> dict[str, str | None]:
+    return {"action": action, "delivery_row_id": str(row_id), **extra}
+
+
+async def _fetch_and_sync(
+    adapter: PMAdapter, engine: PMSyncEngine, external_id: str
+) -> SyncOutcome:
+    external: ExternalTask = await adapter.fetch_external(external_id)
+    return await engine.sync_in(external)
+
+
+def process_webhook(
+    session_factory: sessionmaker[Session],
+    delivery_row_id: uuid.UUID,
+    *,
+    connections: PMConnectionService,
+    audit: AuditLog | None = None,
+) -> dict[str, str | None]:
+    """Re-fetch the changed issue for one persisted delivery and upsert the board.
+
+    Idempotent: an already-processed row early-returns; identical redelivered
+    content is echo-suppressed by the engine's content hash. Failures mark the
+    row ``error`` and re-raise (so Celery retry semantics still apply); the
+    next run of the same row proceeds again (``error``/``received`` both run).
+    """
+    audit = audit or AuditLog()
+    with session_factory() as session:
+        row = session.get(PMWebhookDelivery, delivery_row_id)
+        if row is None:
+            logger.warning("pm_sync: delivery row %s not found; dropping", delivery_row_id)
+            return _result("missing_delivery", delivery_row_id)
+        session.expunge(row)
+
+    if row.status in (PMDeliveryStatus.PROCESSED, PMDeliveryStatus.ECHO_SUPPRESSED):
+        return _result("already_processed", delivery_row_id)
+    if row.status == PMDeliveryStatus.SKIPPED:
+        return _result("skipped", delivery_row_id)
+
+    if row.event_type == "issue.deleted":
+        # External delete propagation follows the connection's
+        # ``on_external_delete`` policy — parked; never a blind board delete.
+        _mark(session_factory, delivery_row_id, PMDeliveryStatus.SKIPPED)
+        return _result("skipped_delete", delivery_row_id)
+
+    if row.connection_id is None or row.external_id is None:
+        _mark(session_factory, delivery_row_id, PMDeliveryStatus.SKIPPED)
+        return _result("skipped", delivery_row_id)
+
+    connection = connections.get_connection_any_workspace(row.connection_id)
+    if connection is None:
+        _mark(session_factory, delivery_row_id, PMDeliveryStatus.SKIPPED)
+        return _result("skipped", delivery_row_id)
+    if (
+        connection.status == PMConnectionStatus.DISABLED
+        or connection.sync_direction == PMSyncDirection.OUTBOUND_ONLY
+    ):
+        _mark(session_factory, delivery_row_id, PMDeliveryStatus.SKIPPED)
+        return _result("skipped", delivery_row_id)
+
+    try:
+        outcome = _sync_delivery(session_factory, connections, connection, row, audit)
+    except Exception as exc:
+        _mark(session_factory, delivery_row_id, PMDeliveryStatus.ERROR, error=str(exc)[:2000])
+        logger.exception(
+            "pm_sync: board write failed for delivery %s (connection %s)",
+            delivery_row_id,
+            row.connection_id,
+        )
+        raise
+
+    status = (
+        PMDeliveryStatus.ECHO_SUPPRESSED
+        if outcome.action == "skipped_echo"
+        else PMDeliveryStatus.PROCESSED
+    )
+    _mark(session_factory, delivery_row_id, status)
+    return _result(
+        outcome.action,
+        delivery_row_id,
+        forge_task_id=str(outcome.forge_task_id) if outcome.forge_task_id else None,
+        external_id=outcome.external_id,
+    )
+
+
+def _sync_delivery(
+    session_factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection: PMConnection,
+    row: PMWebhookDelivery,
+    audit: AuditLog,
+) -> SyncOutcome:
+    # Resolved through the registry seam (``build_adapter``) and scoped to the
+    # connection's workspace + project — never a cross-tenant adapter.
+    adapter = connections.get_adapter_for_project(
+        connection.workspace_id, connection.project_id, connection.provider.value
+    )
+    engine = PMSyncEngine(
+        adapter=adapter,
+        links=DbLinkRepository(session_factory),
+        board=SqlBoardWriter(session_factory, connection.workspace_id),
+        audit=_EngineAuditSink(audit, connection.workspace_id),
+        connection_id=connection.id,
+        workspace_id=connection.workspace_id,
+        forge_project_id=connection.project_id,
+        conflict_policy=ConflictPolicy(connection.conflict_policy.value),
+        sync_direction=SyncDirection(connection.sync_direction.value),
+    )
+    assert row.external_id is not None  # guarded by the caller
+    return asyncio.run(_fetch_and_sync(adapter, engine, row.external_id))
+
+
+# --------------------------------------------------------------------------- #
+# Production seams                                                            #
+# --------------------------------------------------------------------------- #
+
+
+def _session_factory() -> sessionmaker[Session]:  # pragma: no cover - prod seam
+    from forge_db import create_db_engine, create_session_factory, get_database_url
+
+    return create_session_factory(create_db_engine(get_database_url()))
+
+
+def _connection_service(
+    session_factory: sessionmaker[Session],
+) -> PMConnectionService:  # pragma: no cover - prod seam
+    from forge_api.auth.service import get_auth_service
+
+    return PMConnectionService(
+        session_factory=session_factory,
+        vault=get_auth_service().vault,
+        audit=AuditLog(),
+    )
+
+
+def process_webhook_task(delivery_row_id: str) -> dict[str, str | None]:  # pragma: no cover
+    factory = _session_factory()
+    return process_webhook(
+        factory,
+        uuid.UUID(delivery_row_id),
+        connections=_connection_service(factory),
+        audit=AuditLog(),
+    )
+
+
+def register_pm_sync_tasks() -> None:
+    """Register the PM sync Celery task (idempotent)."""
+    celery_app.task(name=PM_SYNC_TASK)(process_webhook_task)
+
+
+register_pm_sync_tasks()
+
+
+__all__ = [
+    "PM_SYNC_TASK",
+    "SqlBoardWriter",
+    "process_webhook",
+    "process_webhook_task",
+    "register_pm_sync_tasks",
+]
diff --git a/apps/worker/tests/test_pm_sync_task.py b/apps/worker/tests/test_pm_sync_task.py
new file mode 100644
index 00000000..91978f8b
--- /dev/null
+++ b/apps/worker/tests/test_pm_sync_task.py
@@ -0,0 +1,364 @@
+"""Worker board-write path for PM webhooks (``forge.pm.process_webhook``).
+
+The webhook intake (``pm_service.receive_webhook``) verifies, dedupes, and
+persists a delivery, then enqueues this task with the delivery row id. These
+tests prove the worker side actually lands the board write:
+
+* the task loads the persisted delivery, re-fetches the changed issue through
+  the adapter built by the registry seam (a fake adapter is injected via
+  ``build_adapter``; the real provider adapters stay untouched), and upserts a
+  board task plus a durable ``pm_task_link`` row scoped to the connection's
+  workspace (no cross-tenant leakage);
+* redelivery is a no-op twice over: re-running the *same* delivery row is an
+  early-returned no-op (row already marked processed), and a *new* delivery
+  carrying identical content is echo-suppressed by the sync engine's content
+  hash — board row count and ``updated_at`` stay stable in both cases.
+
+Hermetic: in-memory SQLite (StaticPool), no Celery broker, no sockets.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator
+from datetime import UTC, datetime
+from typing import Any
+
+import pytest
+from sqlalchemy import StaticPool, create_engine, select
+from sqlalchemy.orm import Session, sessionmaker
+
+from forge_api.auth.crypto import HmacAeadCipher
+from forge_api.auth.vault import SecretVault
+from forge_api.observability.audit import AuditLog
+from forge_api.services import pm_service as pm_service_module
+from forge_api.services.pm_service import PMConnectionService
+from forge_contracts.enums import Direction
+from forge_contracts.pm import (
+    ExternalTask,
+    PMConnectionConfig,
+    PMProvider,
+    StatusCategory,
+)
+from forge_db.base import Base
+from forge_db.models import Project, Task, Workspace
+from forge_db.models.enums import PMDeliveryStatus
+from forge_db.models.enums import PMProvider as DbPMProvider
+from forge_db.models.pm import PMTaskLink, PMWebhookDelivery
+from forge_worker.celery_app import celery_app
+from forge_worker.tasks.pm_sync import PM_SYNC_TASK, process_webhook
+
+WS_ID = uuid.uuid4()
+OTHER_WS_ID = uuid.uuid4()
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures                                                                    #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.fixture
+def factory() -> Iterator[sessionmaker[Session]]:
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    Base.metadata.create_all(engine)
+    yield sessionmaker(bind=engine, expire_on_commit=False)
+    engine.dispose()
+
+
+@pytest.fixture
+def project_id(factory: sessionmaker[Session]) -> uuid.UUID:
+    with factory() as session:
+        session.add(Workspace(id=WS_ID, name="Acme", slug="acme"))
+        session.add(Workspace(id=OTHER_WS_ID, name="Other", slug="other"))
+        session.flush()
+        project = Project(workspace_id=WS_ID, name="Core", key="CORE")
+        session.add(project)
+        session.commit()
+        return project.id
+
+
+class FakeAdapter:
+    """A controllable inbound-path PMAdapter registered through the registry seam."""
+
+    provider = PMProvider.linear
+
+    def __init__(self) -> None:
+        self.external: ExternalTask | None = None
+        self.fetch_calls: list[str] = []
+
+    # --- mapping (pure) ---
+    def map_status(self, value: str, direction: Direction) -> str:
+        return StatusCategory.started.value
+
+    def map_priority(self, value: str, direction: Direction) -> str:
+        return value
+
+    def map_fields(self, fields: dict, direction: Direction) -> dict:
+        return dict(fields)
+
+    # --- external I/O (only the inbound fetch is legal here) ---
+    async def fetch_external(self, external_id: str) -> ExternalTask:
+        self.fetch_calls.append(external_id)
+        assert self.external is not None, "fake adapter has no external staged"
+        return self.external
+
+
+@pytest.fixture
+def fake_adapter(monkeypatch: pytest.MonkeyPatch) -> FakeAdapter:
+    """Register a fake adapter through the ``build_adapter`` registry seam."""
+    adapter = FakeAdapter()
+
+    def _fake_build_adapter(
+        provider: object, transport: object, ctx: object, *, auth_header: str | None = None
+    ) -> FakeAdapter:
+        return adapter
+
+    # ``pm_service`` binds ``build_adapter`` at import time, so patch both the
+    # registry function and the already-bound name.
+    monkeypatch.setattr("forge_integrations.pm.registry.build_adapter", _fake_build_adapter)
+    monkeypatch.setattr(pm_service_module, "build_adapter", _fake_build_adapter)
+    return adapter
+
+
+@pytest.fixture
+def connections(factory: sessionmaker[Session]) -> PMConnectionService:
+    return PMConnectionService(
+        session_factory=factory,
+        vault=SecretVault(cipher=HmacAeadCipher(b"0" * 32)),
+        audit=AuditLog(),
+        transport_factory=lambda connection: object(),  # type: ignore[arg-type,return-value]
+    )
+
+
+@pytest.fixture
+def connection_id(connections: PMConnectionService, project_id: uuid.UUID) -> uuid.UUID:
+    cfg = PMConnectionConfig(
+        provider=PMProvider.linear,
+        name="Linear",
+        project_id=project_id,
+        external_project_key="ENG",
+        auth_type="api_token",
+        api_token="tok",
+    )
+    return connections.create(WS_ID, cfg).id
+
+
+# --------------------------------------------------------------------------- #
+# Helpers                                                                     #
+# --------------------------------------------------------------------------- #
+
+
+def _seed_delivery(
+    factory: sessionmaker[Session],
+    connection_id: uuid.UUID,
+    *,
+    delivery_id: str = "wh-1",
+    event_type: str = "issue.updated",
+    external_id: str | None = "ext-1",
+) -> uuid.UUID:
+    with factory() as session:
+        row = PMWebhookDelivery(
+            provider=DbPMProvider.LINEAR,
+            connection_id=connection_id,
+            delivery_id=delivery_id,
+            event_type=event_type,
+            external_id=external_id,
+            payload_hash="deadbeef",
+            signature_valid=True,
+            received_at=datetime.now(UTC),
+            status=PMDeliveryStatus.RECEIVED,
+        )
+        session.add(row)
+        session.commit()
+        return row.id
+
+
+def _external(title: str = "Add pagination", description: str = "body") -> ExternalTask:
+    return ExternalTask(
+        provider=PMProvider.linear,
+        external_id="ext-1",
+        external_key="ENG-1",
+        url="https://linear.app/acme/issue/ENG-1",
+        title=title,
+        description_md=description,
+        status_name="In Progress",
+        status_category=StatusCategory.started,
+        priority_token="high",
+        labels=["backend"],
+        external_updated_at=datetime(2026, 7, 20, 12, 0, 0, tzinfo=UTC),
+    )
+
+
+def _board_state(factory: sessionmaker[Session]) -> tuple[list[Any], list[Any]]:
+    with factory() as session:
+        tasks = session.execute(select(Task)).scalars().all()
+        links = session.execute(select(PMTaskLink)).scalars().all()
+        for row in (*tasks, *links):
+            session.expunge(row)
+        return list(tasks), list(links)
+
+
+def _delivery(factory: sessionmaker[Session], row_id: uuid.UUID) -> PMWebhookDelivery:
+    with factory() as session:
+        row = session.get(PMWebhookDelivery, row_id)
+        assert row is not None
+        session.expunge(row)
+        return row
+
+
+# --------------------------------------------------------------------------- #
+# Tests                                                                       #
+# --------------------------------------------------------------------------- #
+
+
+def test_process_webhook_fetches_and_upserts_board_task(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+    project_id: uuid.UUID,
+) -> None:
+    fake_adapter.external = _external()
+    row_id = _seed_delivery(factory, connection_id)
+
+    result = process_webhook(factory, row_id, connections=connections)
+
+    assert result["action"] == "created"
+    assert fake_adapter.fetch_calls == ["ext-1"]
+
+    tasks, links = _board_state(factory)
+    assert len(tasks) == 1
+    task = tasks[0]
+    # Multi-tenancy: the board write is scoped to the connection's workspace.
+    assert task.workspace_id == WS_ID
+    assert task.project_id == project_id
+    assert task.title == "Add pagination"
+    assert task.description == "body"
+    assert list(task.labels) == ["backend"]
+
+    assert len(links) == 1
+    link = links[0]
+    assert link.workspace_id == WS_ID
+    assert link.connection_id == connection_id
+    assert link.forge_task_id == task.id
+    assert link.external_id == "ext-1"
+
+    delivery = _delivery(factory, row_id)
+    assert delivery.status == PMDeliveryStatus.PROCESSED
+    assert delivery.processed_at is not None
+
+
+def test_same_delivery_row_reprocessed_is_noop(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    fake_adapter.external = _external()
+    row_id = _seed_delivery(factory, connection_id)
+    first = process_webhook(factory, row_id, connections=connections)
+    assert first["action"] == "created"
+    tasks_before, links_before = _board_state(factory)
+
+    second = process_webhook(factory, row_id, connections=connections)
+
+    assert second["action"] == "already_processed"
+    assert fake_adapter.fetch_calls == ["ext-1"]  # no second re-fetch
+    tasks_after, links_after = _board_state(factory)
+    assert len(tasks_after) == len(tasks_before) == 1
+    assert len(links_after) == len(links_before) == 1
+    assert tasks_after[0].updated_at == tasks_before[0].updated_at
+
+
+def test_redelivered_content_is_echo_suppressed(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    fake_adapter.external = _external()
+    first_id = _seed_delivery(factory, connection_id, delivery_id="wh-1")
+    process_webhook(factory, first_id, connections=connections)
+    tasks_before, _ = _board_state(factory)
+
+    # A *distinct* delivery (provider retried) carrying identical content.
+    second_id = _seed_delivery(factory, connection_id, delivery_id="wh-2")
+    result = process_webhook(factory, second_id, connections=connections)
+
+    assert result["action"] == "skipped_echo"
+    tasks_after, links_after = _board_state(factory)
+    assert len(tasks_after) == 1
+    assert len(links_after) == 1
+    assert tasks_after[0].updated_at == tasks_before[0].updated_at
+    assert _delivery(factory, second_id).status == PMDeliveryStatus.ECHO_SUPPRESSED
+
+
+def test_changed_external_content_updates_in_place(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    fake_adapter.external = _external()
+    process_webhook(
+        factory, _seed_delivery(factory, connection_id, delivery_id="wh-1"), connections=connections
+    )
+
+    fake_adapter.external = _external(title="Add pagination v2")
+    result = process_webhook(
+        factory, _seed_delivery(factory, connection_id, delivery_id="wh-2"), connections=connections
+    )
+
+    assert result["action"] == "updated"
+    tasks, links = _board_state(factory)
+    assert len(tasks) == 1
+    assert len(links) == 1
+    assert tasks[0].title == "Add pagination v2"
+    assert tasks[0].workspace_id == WS_ID
+
+
+def test_deleted_event_is_skipped(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    fake_adapter.external = _external()
+    row_id = _seed_delivery(factory, connection_id, event_type="issue.deleted")
+
+    result = process_webhook(factory, row_id, connections=connections)
+
+    assert result["action"] == "skipped_delete"
+    assert fake_adapter.fetch_calls == []
+    tasks, links = _board_state(factory)
+    assert tasks == []
+    assert links == []
+    assert _delivery(factory, row_id).status == PMDeliveryStatus.SKIPPED
+
+
+def test_missing_connection_is_skipped(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    row_id = _seed_delivery(factory, connection_id)
+    with factory() as session:
+        row = session.get(PMWebhookDelivery, row_id)
+        assert row is not None
+        row.connection_id = None  # connection deleted post-intake (ON DELETE SET NULL)
+        session.commit()
+
+    result = process_webhook(factory, row_id, connections=connections)
+
+    assert result["action"] == "skipped"
+    assert _board_state(factory) == ([], [])
+    assert _delivery(factory, row_id).status == PMDeliveryStatus.SKIPPED
+
+
+def test_task_registered_in_celery_app() -> None:
+    assert PM_SYNC_TASK == "forge.pm.process_webhook"
+    assert PM_SYNC_TASK in celery_app.tasks
+    assert "forge_worker.tasks.pm_sync" in celery_app.conf.include

From cf7aa14ea16daa96c74affe4f90325ef84988e6f Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 04:55:50 +0200
Subject: [PATCH 39/47] fix(pm): real retry semantics for sync task and honest
 failure docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/worker/forge_worker/tasks/pm_sync.py |  57 +++++++++-
 apps/worker/tests/test_pm_sync_task.py    | 122 ++++++++++++++++++++--
 2 files changed, 167 insertions(+), 12 deletions(-)

diff --git a/apps/worker/forge_worker/tasks/pm_sync.py b/apps/worker/forge_worker/tasks/pm_sync.py
index cd4bb1f2..d255976a 100644
--- a/apps/worker/forge_worker/tasks/pm_sync.py
+++ b/apps/worker/forge_worker/tasks/pm_sync.py
@@ -56,8 +56,11 @@
 )
 from forge_db.models.enums import PMConnectionStatus, PMDeliveryStatus, PMSyncDirection
 from forge_db.models.pm import PMConnection, PMWebhookDelivery
+from forge_integrations.pm.errors import ProviderError, RateLimitError
 from forge_integrations.pm.sync_engine import ForgeTaskPatch, PMSyncEngine
 from forge_worker.celery_app import celery_app
+from forge_worker.reliability import ForgeTask as ForgeReliableTask
+from forge_worker.reliability import TransientError
 
 if TYPE_CHECKING:
     from sqlalchemy.orm import Session, sessionmaker
@@ -143,6 +146,11 @@ class SqlBoardWriter:
     the board substrate has no per-row version column yet; last-write-wins
     within the engine's own conflict detection (which compares content hashes,
     not versions, before ever calling ``update``).
+
+    A patch's ``assignee_email`` is intentionally **not** written: the board keys
+    assignees by ``assignee_id`` (a Forge user), not by an external email, so the
+    inbound assignee is dropped at this seam rather than guessed at (resolving an
+    external email to a Forge user is parked; see ``_dto_to_forge_task``).
     """
 
     def __init__(self, session_factory: sessionmaker[Session], workspace_id: uuid.UUID) -> None:
@@ -232,6 +240,24 @@ def _result(action: str, row_id: uuid.UUID, **extra: str | None) -> dict[str, st
     return {"action": action, "delivery_row_id": str(row_id), **extra}
 
 
+def _is_transient(exc: BaseException) -> bool:
+    """Is ``exc`` a *retryable* provider failure (vs. a deterministic one)?
+
+    Transient (retry with backoff): a provider rate-limit (429 — always resolves)
+    or an upstream **5xx** ``ProviderError`` blip, plus raw network faults
+    (connect / timeout). Everything else is deterministic and must fail fast to
+    ``ERROR`` — auth, not-found, unmappable field, sync-conflict, an *unsupported*
+    provider (a ``ProviderError`` with no 5xx status, e.g. the registry's
+    ``unsupported PM provider``), or a malformed payload — because retrying it
+    only burns the budget and delays the terminal state.
+    """
+    if isinstance(exc, RateLimitError):
+        return True
+    if isinstance(exc, ProviderError):
+        return exc.status_code is not None and exc.status_code >= 500
+    return isinstance(exc, ConnectionError | TimeoutError)
+
+
 async def _fetch_and_sync(
     adapter: PMAdapter, engine: PMSyncEngine, external_id: str
 ) -> SyncOutcome:
@@ -249,9 +275,19 @@ def process_webhook(
     """Re-fetch the changed issue for one persisted delivery and upsert the board.
 
     Idempotent: an already-processed row early-returns; identical redelivered
-    content is echo-suppressed by the engine's content hash. Failures mark the
-    row ``error`` and re-raise (so Celery retry semantics still apply); the
-    next run of the same row proceeds again (``error``/``received`` both run).
+    content is echo-suppressed by the engine's content hash.
+
+    Failure semantics (honest): any fetch / board-write failure first marks the
+    row ``error`` (truncated). A *transient* provider failure — a rate-limit, an
+    upstream 5xx, a raw network blip — is then re-raised as
+    :class:`~forge_worker.reliability.TransientError`, so the
+    :class:`~forge_worker.reliability.ForgeTask` base auto-retries it ``N`` times
+    with exponential backoff; only once that budget is spent does the row stay
+    ``ERROR``. A *permanent* failure — auth, not-found, unmappable field, an
+    unsupported provider, a malformed payload — is re-raised as-is and lands
+    ``ERROR`` immediately (retrying it only burns the budget). Either way the
+    independent recovery path is the next webhook for the same issue, which
+    re-fetches authoritative state and re-runs from ``received``.
     """
     audit = audit or AuditLog()
     with session_factory() as session:
@@ -296,6 +332,10 @@ def process_webhook(
             delivery_row_id,
             row.connection_id,
         )
+        # Transient provider blips retry with backoff on the ForgeTask base;
+        # deterministic failures fail fast to ERROR (see module docstring).
+        if _is_transient(exc):
+            raise TransientError(str(exc)) from exc
         raise
 
     status = (
@@ -373,8 +413,15 @@ def process_webhook_task(delivery_row_id: str) -> dict[str, str | None]:  # prag
 
 
 def register_pm_sync_tasks() -> None:
-    """Register the PM sync Celery task (idempotent)."""
-    celery_app.task(name=PM_SYNC_TASK)(process_webhook_task)
+    """Register the PM sync Celery task on the reliability base (idempotent).
+
+    ``ForgeTask`` gives the task ``acks_late`` + auto-retry of
+    :class:`~forge_worker.reliability.TransientError` with exponential backoff
+    (mirrors ``agent_runner`` / ``syncer`` / ``indexer``), so a transient
+    provider blip re-fetches instead of dropping the delivery — recovery no
+    longer relies solely on the next webhook event.
+    """
+    celery_app.task(name=PM_SYNC_TASK, base=ForgeReliableTask)(process_webhook_task)
 
 
 register_pm_sync_tasks()
diff --git a/apps/worker/tests/test_pm_sync_task.py b/apps/worker/tests/test_pm_sync_task.py
index 91978f8b..c48d4883 100644
--- a/apps/worker/tests/test_pm_sync_task.py
+++ b/apps/worker/tests/test_pm_sync_task.py
@@ -45,7 +45,11 @@
 from forge_db.models.enums import PMDeliveryStatus
 from forge_db.models.enums import PMProvider as DbPMProvider
 from forge_db.models.pm import PMTaskLink, PMWebhookDelivery
+from forge_integrations.pm.errors import ExternalNotFound, RateLimitError
 from forge_worker.celery_app import celery_app
+from forge_worker.reliability import ForgeTask as ForgeReliableTask
+from forge_worker.reliability import TransientError
+from forge_worker.tasks import pm_sync as pm_sync_module
 from forge_worker.tasks.pm_sync import PM_SYNC_TASK, process_webhook
 
 WS_ID = uuid.uuid4()
@@ -87,6 +91,9 @@ class FakeAdapter:
     def __init__(self) -> None:
         self.external: ExternalTask | None = None
         self.fetch_calls: list[str] = []
+        #: When set, ``fetch_external`` raises this instead of returning — models a
+        #: provider fault (transient or permanent) so the failure path is testable.
+        self.raise_on_fetch: Exception | None = None
 
     # --- mapping (pure) ---
     def map_status(self, value: str, direction: Direction) -> str:
@@ -101,6 +108,8 @@ def map_fields(self, fields: dict, direction: Direction) -> dict:
     # --- external I/O (only the inbound fetch is legal here) ---
     async def fetch_external(self, external_id: str) -> ExternalTask:
         self.fetch_calls.append(external_id)
+        if self.raise_on_fetch is not None:
+            raise self.raise_on_fetch
         assert self.external is not None, "fake adapter has no external staged"
         return self.external
 
@@ -208,6 +217,37 @@ def _delivery(factory: sessionmaker[Session], row_id: uuid.UUID) -> PMWebhookDel
         return row
 
 
+def _seed_other_tenant_link(
+    factory: sessionmaker[Session], *, external_id: str = "ext-1"
+) -> tuple[uuid.UUID, uuid.UUID]:
+    """Seed a full OTHER_WS_ID task + PM link carrying the *same* external_id.
+
+    Under a *different* connection (outside WS_ID's scope), so the WS_ID sync must
+    never read or overwrite it despite the id collision. Returns (task_id, link_id).
+    """
+    with factory() as session:
+        project = Project(workspace_id=OTHER_WS_ID, name="OtherCore", key="OCORE")
+        session.add(project)
+        session.flush()
+        task = Task(
+            workspace_id=OTHER_WS_ID, project_id=project.id, key="OCORE-1", title="Untouchable"
+        )
+        session.add(task)
+        session.flush()
+        link = PMTaskLink(
+            workspace_id=OTHER_WS_ID,
+            connection_id=uuid.uuid4(),  # a foreign connection, outside WS_ID's scope
+            forge_task_id=task.id,
+            provider=DbPMProvider.LINEAR,
+            external_id=external_id,
+            external_key="OCORE-1",
+            external_url="https://linear.app/other/issue/OCORE-1",
+        )
+        session.add(link)
+        session.commit()
+        return task.id, link.id
+
+
 # --------------------------------------------------------------------------- #
 # Tests                                                                       #
 # --------------------------------------------------------------------------- #
@@ -221,6 +261,9 @@ def test_process_webhook_fetches_and_upserts_board_task(
     project_id: uuid.UUID,
 ) -> None:
     fake_adapter.external = _external()
+    # A different tenant already holds a task + link under the *same* external_id
+    # (via a foreign connection): the sync must not read or clobber it.
+    other_task_id, other_link_id = _seed_other_tenant_link(factory, external_id="ext-1")
     row_id = _seed_delivery(factory, connection_id)
 
     result = process_webhook(factory, row_id, connections=connections)
@@ -229,22 +272,30 @@ def test_process_webhook_fetches_and_upserts_board_task(
     assert fake_adapter.fetch_calls == ["ext-1"]
 
     tasks, links = _board_state(factory)
-    assert len(tasks) == 1
-    task = tasks[0]
-    # Multi-tenancy: the board write is scoped to the connection's workspace.
-    assert task.workspace_id == WS_ID
+    # Multi-tenancy: the board write is scoped to the connection's workspace only.
+    ws_tasks = [t for t in tasks if t.workspace_id == WS_ID]
+    other_tasks = [t for t in tasks if t.workspace_id == OTHER_WS_ID]
+    ws_links = [link for link in links if link.workspace_id == WS_ID]
+    other_links = [link for link in links if link.workspace_id == OTHER_WS_ID]
+
+    assert len(ws_tasks) == 1
+    task = ws_tasks[0]
     assert task.project_id == project_id
     assert task.title == "Add pagination"
     assert task.description == "body"
     assert list(task.labels) == ["backend"]
 
-    assert len(links) == 1
-    link = links[0]
-    assert link.workspace_id == WS_ID
+    assert len(ws_links) == 1
+    link = ws_links[0]
     assert link.connection_id == connection_id
     assert link.forge_task_id == task.id
     assert link.external_id == "ext-1"
 
+    # The identically-keyed OTHER_WS_ID rows are untouched (no cross-tenant leak).
+    assert [t.id for t in other_tasks] == [other_task_id]
+    assert other_tasks[0].title == "Untouchable"
+    assert [link.id for link in other_links] == [other_link_id]
+
     delivery = _delivery(factory, row_id)
     assert delivery.status == PMDeliveryStatus.PROCESSED
     assert delivery.processed_at is not None
@@ -358,7 +409,64 @@ def test_missing_connection_is_skipped(
     assert _delivery(factory, row_id).status == PMDeliveryStatus.SKIPPED
 
 
+def test_permanent_fetch_failure_lands_error_and_reraises(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+) -> None:
+    # A *permanent* provider fault (the issue does not exist): fail fast to ERROR,
+    # re-raise as-is (never wrapped as TransientError), never touch the board.
+    fake_adapter.raise_on_fetch = ExternalNotFound("x" * 2500)  # long -> exercises truncation
+    row_id = _seed_delivery(factory, connection_id)
+
+    with pytest.raises(ExternalNotFound):
+        process_webhook(factory, row_id, connections=connections)
+
+    assert fake_adapter.fetch_calls == ["ext-1"]  # tried once, not retried
+    assert _board_state(factory) == ([], [])  # no board write
+    delivery = _delivery(factory, row_id)
+    assert delivery.status == PMDeliveryStatus.ERROR
+    assert delivery.error is not None
+    assert len(delivery.error) == 2000  # truncated error text
+    assert delivery.processed_at is not None
+
+
+def test_transient_fetch_failure_is_retried_by_reliability_base(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A *transient* provider fault (rate-limit): the ForgeTask base auto-retries.
+    # Drive the real registered task in eager mode and assert the authoritative
+    # re-fetch is attempted more than once (initial + backoff retries).
+    fake_adapter.raise_on_fetch = RateLimitError("rate limited")
+    row_id = _seed_delivery(factory, connection_id)
+
+    # Point the production seams at the hermetic test factory + connections.
+    monkeypatch.setattr(pm_sync_module, "_session_factory", lambda: factory)
+    monkeypatch.setattr(pm_sync_module, "_connection_service", lambda _factory: connections)
+    monkeypatch.setattr(celery_app.conf, "task_always_eager", True)
+    monkeypatch.setattr(celery_app.conf, "task_eager_propagates", False)
+
+    result = celery_app.tasks[PM_SYNC_TASK].apply(args=[str(row_id)])
+
+    assert result.failed()  # retry budget spent -> terminal failure
+    # A retry *was* attempted: initial call + ForgeTask.max_retries re-fetches.
+    assert len(fake_adapter.fetch_calls) == ForgeReliableTask.max_retries + 1
+    assert len(fake_adapter.fetch_calls) > 1
+    assert _delivery(factory, row_id).status == PMDeliveryStatus.ERROR
+
+
 def test_task_registered_in_celery_app() -> None:
     assert PM_SYNC_TASK == "forge.pm.process_webhook"
     assert PM_SYNC_TASK in celery_app.tasks
     assert "forge_worker.tasks.pm_sync" in celery_app.conf.include
+    # Registered on the reliability base: acks_late + auto-retry of TransientError
+    # (so transient provider blips retry with backoff instead of being dropped).
+    task = celery_app.tasks[PM_SYNC_TASK]
+    assert isinstance(task, ForgeReliableTask)
+    assert TransientError in task.autoretry_for
+    assert task.acks_late is True

From 437e86a1e052cf9666785a36365eb5b6be2e8de2 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 05:01:28 +0200
Subject: [PATCH 40/47] fix(pm): classify httpx transport faults as transient
 for sync retries

---
 apps/worker/forge_worker/tasks/pm_sync.py | 17 ++++++++-----
 apps/worker/tests/test_pm_sync_task.py    | 31 +++++++++++++++++++++++
 2 files changed, 42 insertions(+), 6 deletions(-)

diff --git a/apps/worker/forge_worker/tasks/pm_sync.py b/apps/worker/forge_worker/tasks/pm_sync.py
index d255976a..d3cf3717 100644
--- a/apps/worker/forge_worker/tasks/pm_sync.py
+++ b/apps/worker/forge_worker/tasks/pm_sync.py
@@ -41,6 +41,8 @@
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+import httpx
+
 from forge_api.observability.audit import AuditCategory, AuditLog
 from forge_api.services.pm_link_repository_db import DbLinkRepository
 from forge_api.services.pm_service import PMConnectionService
@@ -245,17 +247,20 @@ def _is_transient(exc: BaseException) -> bool:
 
     Transient (retry with backoff): a provider rate-limit (429 — always resolves)
     or an upstream **5xx** ``ProviderError`` blip, plus raw network faults
-    (connect / timeout). Everything else is deterministic and must fail fast to
-    ``ERROR`` — auth, not-found, unmappable field, sync-conflict, an *unsupported*
-    provider (a ``ProviderError`` with no 5xx status, e.g. the registry's
-    ``unsupported PM provider``), or a malformed payload — because retrying it
-    only burns the budget and delays the terminal state.
+    (connect / timeout — ``httpx.TransportError`` and its subclasses, which is
+    what the real provider adapters' transport actually raises, e.g.
+    ``httpx.ConnectError`` / ``httpx.ReadTimeout``). Everything else is
+    deterministic and must fail fast to ``ERROR`` — auth, not-found, unmappable
+    field, sync-conflict, an *unsupported* provider (a ``ProviderError`` with no
+    5xx status, e.g. the registry's ``unsupported PM provider``), or a malformed
+    payload — because retrying it only burns the budget and delays the terminal
+    state.
     """
     if isinstance(exc, RateLimitError):
         return True
     if isinstance(exc, ProviderError):
         return exc.status_code is not None and exc.status_code >= 500
-    return isinstance(exc, ConnectionError | TimeoutError)
+    return isinstance(exc, ConnectionError | TimeoutError | httpx.TransportError)
 
 
 async def _fetch_and_sync(
diff --git a/apps/worker/tests/test_pm_sync_task.py b/apps/worker/tests/test_pm_sync_task.py
index c48d4883..b313f8cd 100644
--- a/apps/worker/tests/test_pm_sync_task.py
+++ b/apps/worker/tests/test_pm_sync_task.py
@@ -24,6 +24,7 @@
 from datetime import UTC, datetime
 from typing import Any
 
+import httpx
 import pytest
 from sqlalchemy import StaticPool, create_engine, select
 from sqlalchemy.orm import Session, sessionmaker
@@ -460,6 +461,36 @@ def test_transient_fetch_failure_is_retried_by_reliability_base(
     assert _delivery(factory, row_id).status == PMDeliveryStatus.ERROR
 
 
+def test_transport_error_fetch_failure_is_retried_by_reliability_base(
+    factory: sessionmaker[Session],
+    connections: PMConnectionService,
+    connection_id: uuid.UUID,
+    fake_adapter: FakeAdapter,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A raw network fault from the real transport (connect refused): the real
+    # provider adapters raise httpx's transport errors, not the ``ConnectionError``
+    # / ``TimeoutError`` builtins, so this must classify as transient too.
+    fake_adapter.raise_on_fetch = httpx.ConnectError(
+        "boom", request=httpx.Request("GET", "https://example.com/issue/ext-1")
+    )
+    row_id = _seed_delivery(factory, connection_id)
+
+    # Point the production seams at the hermetic test factory + connections.
+    monkeypatch.setattr(pm_sync_module, "_session_factory", lambda: factory)
+    monkeypatch.setattr(pm_sync_module, "_connection_service", lambda _factory: connections)
+    monkeypatch.setattr(celery_app.conf, "task_always_eager", True)
+    monkeypatch.setattr(celery_app.conf, "task_eager_propagates", False)
+
+    result = celery_app.tasks[PM_SYNC_TASK].apply(args=[str(row_id)])
+
+    assert result.failed()  # retry budget spent -> terminal failure
+    # A retry *was* attempted: initial call + ForgeTask.max_retries re-fetches.
+    assert len(fake_adapter.fetch_calls) == ForgeReliableTask.max_retries + 1
+    assert len(fake_adapter.fetch_calls) > 1
+    assert _delivery(factory, row_id).status == PMDeliveryStatus.ERROR
+
+
 def test_task_registered_in_celery_app() -> None:
     assert PM_SYNC_TASK == "forge.pm.process_webhook"
     assert PM_SYNC_TASK in celery_app.tasks

From c74d157eaee87632d53656e1560784e12979bc25 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 05:19:31 +0200
Subject: [PATCH 41/47] feat(attest): expose attested changesets over REST with
 approvals UI panel

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/cli_verify.py              | 105 ++++-
 apps/api/forge_api/routers/__init__.py        |   3 +
 apps/api/forge_api/routers/attestations.py    | 166 ++++++++
 apps/api/forge_api/schemas/attestation.py     |  74 ++++
 apps/api/tests/attest/test_attestation_api.py | 376 ++++++++++++++++++
 .../approvals/review-panel.test.tsx           |  40 ++
 .../src/components/approvals/review-panel.tsx |   9 +-
 .../attestations/attestation-panel.test.tsx   | 112 ++++++
 .../attestations/attestation-panel.tsx        | 131 ++++++
 apps/web/src/lib/api/approvals.ts             |  23 ++
 apps/web/src/lib/api/attestations.test.ts     |  55 +++
 apps/web/src/lib/api/client.ts                |  40 ++
 apps/web/src/lib/api/types.ts                 |  44 ++
 docs/trust-layer.md                           |  41 +-
 14 files changed, 1191 insertions(+), 28 deletions(-)
 create mode 100644 apps/api/forge_api/routers/attestations.py
 create mode 100644 apps/api/forge_api/schemas/attestation.py
 create mode 100644 apps/api/tests/attest/test_attestation_api.py
 create mode 100644 apps/web/src/components/attestations/attestation-panel.test.tsx
 create mode 100644 apps/web/src/components/attestations/attestation-panel.tsx
 create mode 100644 apps/web/src/lib/api/attestations.test.ts

diff --git a/apps/api/forge_api/cli_verify.py b/apps/api/forge_api/cli_verify.py
index ca4c40e0..4e0b3027 100644
--- a/apps/api/forge_api/cli_verify.py
+++ b/apps/api/forge_api/cli_verify.py
@@ -31,9 +31,11 @@
 
 import argparse
 import base64
+import binascii
 import hashlib
 import sys
 import uuid
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -49,7 +51,13 @@
 if TYPE_CHECKING:
     from sqlalchemy.orm import Session, sessionmaker
 
-__all__ = ["build_parser", "main"]
+__all__ = [
+    "StoredAttestationVerification",
+    "build_parser",
+    "main",
+    "resolve_verification_key",
+    "verify_stored_attestation",
+]
 
 
 # --------------------------------------------------------------------------- #
@@ -64,14 +72,15 @@ def _read_source(path: str) -> str:
     return Path(path).read_text(encoding="utf-8")
 
 
-def _resolve_public_key(explicit: str | None) -> str:
+def resolve_verification_key(explicit: str | None = None) -> str:
     """The base64 Ed25519 public key to verify against.
 
-    An explicit ``--public-key`` wins; otherwise fall back to the public half of
-    the env signing key (``FORGE_ATTEST_SIGNING_KEY``) so an attestation signed
-    on this host can be verified without re-passing the key. When no signing key
-    is set, ``EnvSigningKeyProvider`` warns and generates an ephemeral key whose
-    public half will simply not match a real signature — an honest REJECT.
+    An explicit key (``--public-key`` on the CLI) wins; otherwise fall back to
+    the public half of the env signing key (``FORGE_ATTEST_SIGNING_KEY``) so an
+    attestation signed on this host can be verified without re-passing the key.
+    When no signing key is set, ``EnvSigningKeyProvider`` warns and generates an
+    ephemeral key whose public half will simply not match a real signature — an
+    honest REJECT.
     """
     if explicit:
         return explicit
@@ -80,6 +89,62 @@ def _resolve_public_key(explicit: str | None) -> str:
     return EnvSigningKeyProvider().public_key_b64
 
 
+@dataclass(frozen=True)
+class StoredAttestationVerification:
+    """Outcome of verifying a stored :class:`Attestation` row's envelope.
+
+    ``payload_hash_ok`` — the sha256 over the envelope's PAE re-derivation
+    matches the recorded ``payload_hash`` column; ``signature_ok`` — an Ed25519
+    signature on the envelope verifies for the resolved public key. ``error``
+    is set (and both flags are ``False``) when the envelope payload is not
+    valid base64 — a malformed record is "not verified", never an exception.
+    """
+
+    payload_hash_ok: bool
+    signature_ok: bool
+    recomputed_payload_hash: str | None = None
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        """True iff the recorded hash matches AND the signature verifies."""
+        return self.payload_hash_ok and self.signature_ok
+
+
+def verify_stored_attestation(
+    envelope: DsseEnvelope,
+    recorded_payload_hash: str,
+    *,
+    public_key_b64: str | None = None,
+) -> StoredAttestationVerification:
+    """Verify a stored attestation exactly as ``forge-verify --run`` does.
+
+    Re-derives ``payload_hash`` from the envelope's PAE encoding, confirms it
+    matches the recorded column, and Ed25519-verifies the signature against
+    ``public_key_b64`` (resolved via :func:`resolve_verification_key` when not
+    given). This is the single DB-backed verification seam — the REST surface
+    (``forge_api.routers.attestations``) and the CLI's ``--run`` mode both call
+    it, so "verified" can never mean two different things.
+    """
+    try:
+        payload_bytes = base64.b64decode(envelope.payload, validate=True)
+    except (binascii.Error, ValueError, TypeError) as exc:
+        return StoredAttestationVerification(
+            payload_hash_ok=False,
+            signature_ok=False,
+            error=f"envelope payload is not valid base64: {exc}",
+        )
+    recomputed = hashlib.sha256(pae(envelope.payloadType, payload_bytes)).hexdigest()
+    signature_ok = DsseVerifier().verify(
+        envelope, public_key_b64=resolve_verification_key(public_key_b64)
+    )
+    return StoredAttestationVerification(
+        payload_hash_ok=recomputed == recorded_payload_hash,
+        signature_ok=signature_ok,
+        recomputed_payload_hash=recomputed,
+    )
+
+
 def _print_envelope_summary(envelope: DsseEnvelope) -> None:
     """Print the envelope's predicate type + first subject digest, best-effort."""
     print(f"payloadType: {envelope.payloadType}")
@@ -129,7 +194,7 @@ def _cmd_attestation(args: argparse.Namespace) -> int:
     except (OSError, ValueError) as exc:
         print(f"error: invalid DSSE envelope: {exc}", file=sys.stderr)
         return 1
-    public_key = _resolve_public_key(args.public_key)
+    public_key = resolve_verification_key(args.public_key)
     ok = DsseVerifier().verify(envelope, public_key_b64=public_key)
     _print_envelope_summary(envelope)
     print("VERIFIED" if ok else "REJECTED")
@@ -174,24 +239,20 @@ def _cmd_run(args: argparse.Namespace) -> int:
         keyid = row.keyid
         attestation_id = row.id
 
-    try:
-        payload_bytes = base64.b64decode(envelope.payload, validate=True)
-    except (ValueError, TypeError) as exc:
-        print(f"error: envelope payload is not valid base64: {exc}", file=sys.stderr)
+    result = verify_stored_attestation(envelope, recorded_hash, public_key_b64=args.public_key)
+    if result.error is not None:
+        print(f"error: {result.error}", file=sys.stderr)
         return 1
-    recomputed_hash = hashlib.sha256(pae(envelope.payloadType, payload_bytes)).hexdigest()
-    hash_ok = recomputed_hash == recorded_hash
-
-    public_key = _resolve_public_key(args.public_key)
-    sig_ok = DsseVerifier().verify(envelope, public_key_b64=public_key)
 
     print(f"attestation: {attestation_id} (keyid {keyid})")
     _print_envelope_summary(envelope)
-    print(f"payload_hash match: {hash_ok} (recorded={recorded_hash}, recomputed={recomputed_hash})")
-    print(f"signature verified: {sig_ok}")
-    ok = hash_ok and sig_ok
-    print("VERIFIED" if ok else "REJECTED")
-    return 0 if ok else 1
+    print(
+        f"payload_hash match: {result.payload_hash_ok} "
+        f"(recorded={recorded_hash}, recomputed={result.recomputed_payload_hash})"
+    )
+    print(f"signature verified: {result.signature_ok}")
+    print("VERIFIED" if result.ok else "REJECTED")
+    return 0 if result.ok else 1
 
 
 # --------------------------------------------------------------------------- #
diff --git a/apps/api/forge_api/routers/__init__.py b/apps/api/forge_api/routers/__init__.py
index e631d766..e3b381f4 100644
--- a/apps/api/forge_api/routers/__init__.py
+++ b/apps/api/forge_api/routers/__init__.py
@@ -16,6 +16,7 @@
     alerts,
     ao_settings,
     approvals,
+    attestations,
     audit,
     auth,
     automations,
@@ -64,6 +65,7 @@
     benchmarks.router,
     integration.router,
     approvals.router,
+    attestations.router,
     audit.router,
     cost.router,
     incidents.router,
@@ -90,6 +92,7 @@
     "alerts",
     "ao_settings",
     "approvals",
+    "attestations",
     "audit",
     "auth",
     "automations",
diff --git a/apps/api/forge_api/routers/attestations.py b/apps/api/forge_api/routers/attestations.py
new file mode 100644
index 00000000..ad1b1658
--- /dev/null
+++ b/apps/api/forge_api/routers/attestations.py
@@ -0,0 +1,166 @@
+"""Attested Changesets read-only REST surface (Task 19).
+
+* ``GET /attestations``                    — workspace-scoped page, newest first
+* ``GET /attestations/{id}``               — one record (foreign ids look nonexistent)
+* ``GET /approvals/{id}/attestation``      — the record minted when the gate's
+  linked workflow run was attested (404 when none)
+
+Read-only by design: attestations are minted exclusively as a side effect of
+approving a ``pr`` gate (``PrAttestationResolutionHook``); there is no HTTP
+route that creates one, mirroring the audit router's producer/consumer split.
+Reads go straight through the append-only ``AttestationRepository`` scoped to
+the caller's workspace on the row itself (the red-team surface's convention).
+
+``verified`` is computed per record by the exact seam ``forge-verify --run``
+uses (:func:`forge_api.cli_verify.verify_stored_attestation`): re-derive
+``payload_hash`` from the envelope's PAE and Ed25519-verify against the
+deployment's verification key (the public half of ``FORGE_ATTEST_SIGNING_KEY``,
+resolved once per request). Signature verification is never re-implemented
+here, so the REST answer and the CLI's exit code can never disagree.
+
+Auth/tenancy mirror the F36 approvals router exactly: every route hangs off the
+authenticated principal (READ permission) and scopes by
+``principal.workspace_id``; cross-workspace ids map to ``404`` (no existence
+leak).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy.orm import Session
+
+from forge_api.auth.rbac import Permission
+from forge_api.cli_verify import resolve_verification_key, verify_stored_attestation
+from forge_api.db import get_db
+from forge_api.deps import Principal, get_current_principal
+from forge_api.routers._rbac import require_permission
+from forge_api.schemas.attestation import (
+    AttestationListResponse,
+    AttestationOut,
+    AttestationProvenance,
+)
+from forge_api.services.approval_service import get_approval_service
+from forge_approval import ApprovalNotFoundError, ApprovalService
+from forge_contracts.attestation import DsseEnvelope
+from forge_db.attest.repository import AttestationRepository
+from forge_db.models import Attestation
+
+router = APIRouter(tags=["attestations"], dependencies=[Depends(get_current_principal)])
+
+ReaderDep = Annotated[Principal, Depends(require_permission(Permission.READ))]
+SessionDep = Annotated[Session, Depends(get_db)]
+ApprovalServiceDep = Annotated[ApprovalService, Depends(get_approval_service)]
+
+
+def _to_out(row: Attestation, *, public_key_b64: str) -> AttestationOut:
+    """Map one ORM row onto the response schema, verifying it live.
+
+    Verification is total (a malformed envelope is "not verified", never a
+    500): both the envelope re-validation and the shared seam degrade to
+    ``verified=False`` on any decode failure.
+    """
+    try:
+        envelope = DsseEnvelope.model_validate(row.envelope)
+    except ValueError:
+        verified = False
+    else:
+        verified = verify_stored_attestation(
+            envelope, row.payload_hash, public_key_b64=public_key_b64
+        ).ok
+    return AttestationOut(
+        id=row.id,
+        changeset_hash=row.subject_digest,
+        predicate_type=row.predicate_type,
+        keyid=row.keyid,
+        payload_hash=row.payload_hash,
+        created_at=row.created_at,
+        verified=verified,
+        provenance=AttestationProvenance.model_validate(row),
+    )
+
+
+def _not_found(attestation_id: uuid.UUID) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND, detail=f"no attestation {attestation_id}"
+    )
+
+
+@router.get("/attestations", response_model=AttestationListResponse)
+def list_attestations(
+    principal: ReaderDep,
+    session: SessionDep,
+    workflow_run_id: Annotated[uuid.UUID | None, Query()] = None,
+    agent_run_id: Annotated[uuid.UUID | None, Query()] = None,
+    spec_key: Annotated[str | None, Query()] = None,
+    limit: Annotated[int, Query(ge=1, le=200)] = 50,
+    offset: Annotated[int, Query(ge=0)] = 0,
+) -> AttestationListResponse:
+    """One workspace-scoped page of attestations, newest first."""
+    rows = AttestationRepository(session).list(
+        principal.workspace_id,
+        workflow_run_id=workflow_run_id,
+        agent_run_id=agent_run_id,
+        spec_key=spec_key,
+        limit=limit,
+        offset=offset,
+    )
+    public_key = resolve_verification_key()
+    return AttestationListResponse(
+        items=[_to_out(row, public_key_b64=public_key) for row in rows],
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.get("/attestations/{attestation_id}", response_model=AttestationOut)
+def get_attestation(
+    principal: ReaderDep, session: SessionDep, attestation_id: uuid.UUID
+) -> AttestationOut:
+    """One attestation (workspace-scoped; cross-workspace ids look nonexistent)."""
+    row = session.get(Attestation, attestation_id)
+    if row is None or row.workspace_id != principal.workspace_id:
+        raise _not_found(attestation_id)
+    return _to_out(row, public_key_b64=resolve_verification_key())
+
+
+@router.get("/approvals/{approval_id}/attestation", response_model=AttestationOut)
+async def get_approval_attestation(
+    principal: ReaderDep,
+    session: SessionDep,
+    service: ApprovalServiceDep,
+    approval_id: uuid.UUID,
+) -> AttestationOut:
+    """The attestation minted for the gate's linked workflow run (404 when none).
+
+    Resolves the gate through the same workspace-scoped ``ApprovalService.get``
+    the approvals router uses (foreign gate ids 404 identically), then reads the
+    newest attestation for its ``workflow_run_id``. A gate without a linked run,
+    or whose run was never attested (e.g. still pending), is an honest 404 —
+    the UI renders that as "not attested", never a fake state.
+    """
+    try:
+        request = await service.get(approval_id, workspace_id=principal.workspace_id)
+    except ApprovalNotFoundError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=f"no approval request {approval_id}"
+        ) from None
+
+    row = (
+        AttestationRepository(session).get_by_run(
+            principal.workspace_id, workflow_run_id=request.workflow_run_id
+        )
+        if request.workflow_run_id is not None
+        else None
+    )
+    if row is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"no attestation recorded for approval {approval_id}",
+        )
+    return _to_out(row, public_key_b64=resolve_verification_key())
+
+
+__all__ = ["router"]
diff --git a/apps/api/forge_api/schemas/attestation.py b/apps/api/forge_api/schemas/attestation.py
new file mode 100644
index 00000000..8d6f477f
--- /dev/null
+++ b/apps/api/forge_api/schemas/attestation.py
@@ -0,0 +1,74 @@
+"""Response schemas for the Attested Changesets read-only REST surface
+(``GET /attestations``, ``GET /attestations/{id}``,
+``GET /approvals/{id}/attestation`` — Task 19).
+
+Field mapping is truthful to ``forge_db.models.attestation.Attestation``:
+``changeset_hash`` is the row's ``subject_digest`` (the labeled sha256 of the
+attested subject), ``keyid``/``predicate_type``/``payload_hash``/``created_at``
+are the columns verbatim, and ``provenance`` carries the queryable provenance
+columns the dashboard filters on. ``verified`` is **computed, never stored**:
+the router runs the exact ``forge-verify --run`` verification seam
+(:func:`forge_api.cli_verify.verify_stored_attestation` — PAE re-derivation +
+Ed25519 over the envelope) against the deployment's verification key, so a
+record this deployment cannot vouch for honestly reads ``verified: false``.
+
+The raw DSSE ``envelope`` is deliberately not exposed here: independent
+(offline) verification goes through ``forge-verify``, which re-reads the row —
+the REST surface never becomes a second source of truth for the signature.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["AttestationListResponse", "AttestationOut", "AttestationProvenance"]
+
+
+class AttestationProvenance(BaseModel):
+    """The queryable provenance columns of one ``attestation`` row."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    workflow_run_id: uuid.UUID | None = None
+    agent_run_id: uuid.UUID | None = None
+    #: PR numbers this attestation covers (mirrors
+    #: ``TraceabilityCriterionLink.pr_numbers``).
+    pr_numbers: list[int] = Field(default_factory=list)
+    #: Spec identity the changeset was produced against; the service degrades
+    #: honestly to ``""`` / ``0`` when no traceability exists.
+    spec_key: str | None = None
+    spec_version: int | None = None
+    #: Position of the chained ``changeset.attested`` F39 audit event.
+    audit_seq: int | None = None
+
+
+class AttestationOut(BaseModel):
+    """One immutable DSSE-signed changeset attestation, with live verification."""
+
+    id: uuid.UUID
+    #: The attested subject's labeled digest (``Attestation.subject_digest``,
+    #: ``sha256:<hex>``) — the changeset identity the envelope signs over.
+    changeset_hash: str
+    #: The in-toto predicate type URI of the signed Statement.
+    predicate_type: str
+    #: sha256 of the raw Ed25519 public key that signed the envelope.
+    keyid: str
+    #: sha256 hex of the canonical (PAE-encoded) payload the signature covers.
+    payload_hash: str
+    created_at: datetime
+    #: Computed by the same seam ``forge-verify --run`` uses: recorded
+    #: ``payload_hash`` matches the PAE re-derivation AND the Ed25519 signature
+    #: verifies against this deployment's verification key.
+    verified: bool
+    provenance: AttestationProvenance
+
+
+class AttestationListResponse(BaseModel):
+    """Body of ``GET /attestations`` — one workspace-scoped page, newest first."""
+
+    items: list[AttestationOut] = Field(default_factory=list)
+    limit: int
+    offset: int
diff --git a/apps/api/tests/attest/test_attestation_api.py b/apps/api/tests/attest/test_attestation_api.py
new file mode 100644
index 00000000..3d440dc2
--- /dev/null
+++ b/apps/api/tests/attest/test_attestation_api.py
@@ -0,0 +1,376 @@
+"""Integration tests for the Attested Changesets read-only REST surface
+(Task 19: ``GET /attestations``, ``GET /attestations/{id}``,
+``GET /approvals/{id}/attestation``).
+
+Mints real records through :class:`AttestationService` (the same path the
+``pr``-gate approval hook uses — mirroring ``test_attestation_service.py``'s
+seeding) on hermetic SQLite (mirrors ``test_red_team_api.py``'s convention: the
+Postgres immutability trigger is a no-op here; the append-only property itself
+is proven by the service tests). ``verified`` must be computed by the exact
+verification path ``forge-verify --run`` uses — re-derive ``payload_hash`` from
+the envelope's PAE, then Ed25519-verify against the deployment key — so a
+record signed by a *different* key honestly reads ``verified: false``.
+"""
+
+from __future__ import annotations
+
+import base64
+import uuid
+from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy import StaticPool, create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from forge_api.db import get_db
+from forge_api.deps import Principal, get_current_principal
+from forge_api.main import create_app
+from forge_api.services.approval_service import get_approval_service
+from forge_api.services.attestation_service import AttestationService
+from forge_approval import (
+    ApprovalAuthorizer,
+    ApprovalService,
+    GateRegistry,
+    InMemoryApprovalRepository,
+)
+from forge_contracts import UserRole
+from forge_db.base import Base
+from forge_db.models import AgentRun, Attestation, Project, Task, WorkflowRun, Workspace
+from forge_obs.attest.signing import DsseSigner, EnvSigningKeyProvider
+
+WS = uuid.UUID("00000000-0000-0000-0000-0000000000e1")
+WS2 = uuid.UUID("00000000-0000-0000-0000-0000000000e2")
+
+#: Fixed 32-byte Ed25519 seeds → deterministic, silent signers. ``_SEED_B64`` is
+#: also exported as ``FORGE_ATTEST_SIGNING_KEY`` (autouse below), so the REST
+#: surface's env-fallback verification key matches records minted with it —
+#: and does NOT match records minted with ``_OTHER_SEED_B64``.
+_SEED_B64 = base64.b64encode(bytes(range(1, 33))).decode("ascii")
+_OTHER_SEED_B64 = base64.b64encode(bytes(range(33, 65))).decode("ascii")
+
+
+@pytest.fixture(autouse=True)
+def _deployment_signing_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FORGE_ATTEST_SIGNING_KEY", _SEED_B64)
+
+
+@pytest.fixture
+def signer() -> DsseSigner:
+    return DsseSigner(EnvSigningKeyProvider(environ={"FORGE_ATTEST_SIGNING_KEY": _SEED_B64}))
+
+
+@pytest.fixture
+def other_signer() -> DsseSigner:
+    return DsseSigner(EnvSigningKeyProvider(environ={"FORGE_ATTEST_SIGNING_KEY": _OTHER_SEED_B64}))
+
+
+@pytest.fixture
+def factory() -> Iterator[sessionmaker[Session]]:
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    Base.metadata.create_all(engine)
+    sf: sessionmaker[Session] = sessionmaker(bind=engine, expire_on_commit=False, class_=Session)
+    with sf() as s:
+        s.add(Workspace(id=WS, name="Acme", slug="acme"))
+        s.add(Workspace(id=WS2, name="Rival", slug="rival"))
+        s.commit()
+    yield sf
+    engine.dispose()
+
+
+def _seed_run(factory: sessionmaker[Session], *, workspace_id: uuid.UUID = WS) -> uuid.UUID:
+    """Seed workspace -> project -> task -> workflow_run + agent_run; return run id."""
+    with factory() as s:
+        project = Project(workspace_id=workspace_id, name="Core", key=f"C{uuid.uuid4().hex[:4]}")
+        s.add(project)
+        s.flush()
+        task = Task(
+            workspace_id=workspace_id,
+            project_id=project.id,
+            key=f"TASK-{uuid.uuid4().hex[:6]}",
+            title="attested changeset task",
+        )
+        s.add(task)
+        s.flush()
+        run = WorkflowRun(workspace_id=workspace_id, task_id=task.id)
+        s.add(run)
+        s.flush()
+        s.add(
+            AgentRun(
+                workspace_id=workspace_id,
+                workflow_run_id=run.id,
+                task_id=task.id,
+                role="implementer",
+                model="claude-sonnet-4-5",
+                sandbox_kind="gvisor",
+                steps=[{"index": 0, "kind": "tool_call", "tool_call": {"tool": "edit_file"}}],
+                output={"artifacts": {"model_usage": {"version": "2025-09-29"}}},
+            )
+        )
+        s.commit()
+        run_id = run.id
+    return run_id
+
+
+def _mint(
+    factory: sessionmaker[Session],
+    signer: DsseSigner,
+    run_id: uuid.UUID,
+    *,
+    pr_numbers: list[int] | None = None,
+    created_at: datetime | None = None,
+) -> uuid.UUID:
+    """Mint one attestation via the real service (the approval hook's path)."""
+    with factory() as s:
+        row = AttestationService(s, signer=signer).attest_changeset(
+            run_id, pr_numbers=pr_numbers if pr_numbers is not None else [7, 9]
+        )
+        if created_at is not None:
+            # Deterministic ordering on SQLite (second-resolution timestamps);
+            # the Postgres trigger forbidding this is proven by the service tests.
+            s.query(Attestation).filter(Attestation.id == row.id).update({"created_at": created_at})
+        s.commit()
+        att_id = row.id
+    return att_id
+
+
+def _principal(workspace_id: uuid.UUID = WS) -> Principal:
+    return Principal(
+        user_id=uuid.uuid4(),
+        workspace_id=workspace_id,
+        role=UserRole.MEMBER,
+        email="member@acme.test",
+        auth_method="test",
+        scopes=["*"],
+    )
+
+
+def _client(
+    factory: sessionmaker[Session],
+    principal: Principal,
+    approval_service: ApprovalService | None = None,
+) -> TestClient:
+    app: FastAPI = create_app()
+
+    def _get_db() -> Iterator[Session]:
+        with factory() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = _get_db
+    app.dependency_overrides[get_current_principal] = lambda: principal
+    if approval_service is not None:
+        app.dependency_overrides[get_approval_service] = lambda: approval_service
+    return TestClient(app)
+
+
+def _approval_service() -> ApprovalService:
+    """A hermetic approval service (no resolution hooks — read/create only)."""
+    return ApprovalService(InMemoryApprovalRepository(), GateRegistry(), ApprovalAuthorizer())
+
+
+# --------------------------------------------------------------------------- #
+# GET /attestations (list)                                                    #
+# --------------------------------------------------------------------------- #
+
+
+def test_list_returns_minted_record_with_verified_true(factory, signer) -> None:
+    run_id = _seed_run(factory)
+    att_id = _mint(factory, signer, run_id)
+    client = _client(factory, _principal())
+
+    resp = client.get("/attestations")
+    assert resp.status_code == 200, resp.text
+    items = resp.json()["items"]
+    assert len(items) == 1
+    item = items[0]
+
+    assert item["id"] == str(att_id)
+    assert item["changeset_hash"].startswith("sha256:")
+    assert item["keyid"] == signer.keyid
+    assert item["verified"] is True
+    assert item["created_at"] is not None
+    assert item["predicate_type"].startswith("https://")
+    # sha256 hex of the PAE-encoded payload (64 hex chars).
+    assert len(item["payload_hash"]) == 64
+    # Provenance mirrors the queryable model columns, truthfully degraded
+    # (no traceability seeded -> spec_key "" / spec_version 0).
+    prov = item["provenance"]
+    assert prov["workflow_run_id"] == str(run_id)
+    assert prov["agent_run_id"] is not None
+    assert prov["pr_numbers"] == [7, 9]
+    assert prov["spec_key"] == ""
+    assert prov["spec_version"] == 0
+    assert prov["audit_seq"] is not None
+
+
+def test_list_is_newest_first_and_paginates(factory, signer) -> None:
+    now = datetime.now(UTC)
+    run_ids = [_seed_run(factory) for _ in range(3)]
+    att_ids = [
+        _mint(factory, signer, run_id, created_at=now + timedelta(minutes=i))
+        for i, run_id in enumerate(run_ids)
+    ]
+    client = _client(factory, _principal())
+
+    resp = client.get("/attestations", params={"limit": 2})
+    assert resp.status_code == 200, resp.text
+    page_one = resp.json()["items"]
+    assert [i["id"] for i in page_one] == [str(att_ids[2]), str(att_ids[1])]
+
+    resp = client.get("/attestations", params={"limit": 2, "offset": 2})
+    assert resp.status_code == 200, resp.text
+    page_two = resp.json()["items"]
+    assert [i["id"] for i in page_two] == [str(att_ids[0])]
+
+
+def test_list_filters_by_workflow_run_id(factory, signer) -> None:
+    run_a = _seed_run(factory)
+    run_b = _seed_run(factory)
+    att_a = _mint(factory, signer, run_a)
+    _mint(factory, signer, run_b)
+    client = _client(factory, _principal())
+
+    resp = client.get("/attestations", params={"workflow_run_id": str(run_a)})
+    assert resp.status_code == 200, resp.text
+    items = resp.json()["items"]
+    assert [i["id"] for i in items] == [str(att_a)]
+
+
+def test_list_never_leaks_cross_workspace_records(factory, signer) -> None:
+    """The row-level workspace scope, not record existence, is the boundary."""
+    own_run = _seed_run(factory, workspace_id=WS)
+    foreign_run = _seed_run(factory, workspace_id=WS2)
+    own_att = _mint(factory, signer, own_run)
+    foreign_att = _mint(factory, signer, foreign_run)
+
+    resp = _client(factory, _principal(workspace_id=WS)).get("/attestations")
+    assert resp.status_code == 200, resp.text
+    assert [i["id"] for i in resp.json()["items"]] == [str(own_att)]
+
+    resp = _client(factory, _principal(workspace_id=WS2)).get("/attestations")
+    assert resp.status_code == 200, resp.text
+    assert [i["id"] for i in resp.json()["items"]] == [str(foreign_att)]
+
+
+def test_list_verification_failure_is_reported_honestly(factory, other_signer) -> None:
+    """A record signed by a key that is NOT the deployment's verification key
+    reads ``verified: false`` — never a fake pass."""
+    run_id = _seed_run(factory)
+    _mint(factory, other_signer, run_id)
+    client = _client(factory, _principal())
+
+    resp = client.get("/attestations")
+    assert resp.status_code == 200, resp.text
+    item = resp.json()["items"][0]
+    assert item["keyid"] == other_signer.keyid
+    assert item["verified"] is False
+
+
+# --------------------------------------------------------------------------- #
+# GET /attestations/{id} (detail)                                             #
+# --------------------------------------------------------------------------- #
+
+
+def test_detail_returns_one_record(factory, signer) -> None:
+    run_id = _seed_run(factory)
+    att_id = _mint(factory, signer, run_id)
+    client = _client(factory, _principal())
+
+    resp = client.get(f"/attestations/{att_id}")
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["id"] == str(att_id)
+    assert body["verified"] is True
+    assert body["provenance"]["workflow_run_id"] == str(run_id)
+
+
+def test_detail_unknown_id_404s(factory) -> None:
+    client = _client(factory, _principal())
+    resp = client.get(f"/attestations/{uuid.uuid4()}")
+    assert resp.status_code == 404
+
+
+def test_detail_foreign_workspace_id_404s(factory, signer) -> None:
+    """A cross-workspace id looks nonexistent (no existence leak)."""
+    run_id = _seed_run(factory, workspace_id=WS)
+    att_id = _mint(factory, signer, run_id)
+
+    resp = _client(factory, _principal(workspace_id=WS2)).get(f"/attestations/{att_id}")
+    assert resp.status_code == 404
+
+
+# --------------------------------------------------------------------------- #
+# GET /approvals/{id}/attestation (by-approval lookup)                        #
+# --------------------------------------------------------------------------- #
+
+
+def _open_pr_gate(
+    client: TestClient, *, workflow_run_id: uuid.UUID | None, subject_id: uuid.UUID | None = None
+) -> str:
+    resp = client.post(
+        "/approvals",
+        json={
+            "gate_type": "pr",
+            "subject_type": "workflow_run",
+            "subject_id": str(subject_id or workflow_run_id or uuid.uuid4()),
+            "workflow_run_id": str(workflow_run_id) if workflow_run_id else None,
+            "title": "PR gate",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    return resp.json()["id"]
+
+
+def test_by_approval_returns_the_runs_attestation(factory, signer) -> None:
+    run_id = _seed_run(factory)
+    att_id = _mint(factory, signer, run_id)
+    client = _client(factory, _principal(), approval_service=_approval_service())
+    approval_id = _open_pr_gate(client, workflow_run_id=run_id)
+
+    resp = client.get(f"/approvals/{approval_id}/attestation")
+    assert resp.status_code == 200, resp.text
+    body = resp.json()
+    assert body["id"] == str(att_id)
+    assert body["verified"] is True
+    assert body["provenance"]["workflow_run_id"] == str(run_id)
+
+
+def test_by_approval_404_when_gate_has_no_workflow_run(factory) -> None:
+    client = _client(factory, _principal(), approval_service=_approval_service())
+    approval_id = _open_pr_gate(client, workflow_run_id=None)
+
+    resp = client.get(f"/approvals/{approval_id}/attestation")
+    assert resp.status_code == 404
+
+
+def test_by_approval_404_when_run_is_unattested(factory) -> None:
+    run_id = _seed_run(factory)
+    client = _client(factory, _principal(), approval_service=_approval_service())
+    approval_id = _open_pr_gate(client, workflow_run_id=run_id)
+
+    resp = client.get(f"/approvals/{approval_id}/attestation")
+    assert resp.status_code == 404
+
+
+def test_by_approval_unknown_approval_404s(factory) -> None:
+    client = _client(factory, _principal(), approval_service=_approval_service())
+    resp = client.get(f"/approvals/{uuid.uuid4()}/attestation")
+    assert resp.status_code == 404
+
+
+def test_by_approval_cross_workspace_404s(factory, signer) -> None:
+    """A foreign workspace's approval id looks nonexistent — same contract as
+    the approvals router itself."""
+    run_id = _seed_run(factory, workspace_id=WS)
+    _mint(factory, signer, run_id)
+    service = _approval_service()
+    owner_client = _client(factory, _principal(workspace_id=WS), approval_service=service)
+    approval_id = _open_pr_gate(owner_client, workflow_run_id=run_id)
+
+    foreign_client = _client(factory, _principal(workspace_id=WS2), approval_service=service)
+    resp = foreign_client.get(f"/approvals/{approval_id}/attestation")
+    assert resp.status_code == 404
diff --git a/apps/web/src/components/approvals/review-panel.test.tsx b/apps/web/src/components/approvals/review-panel.test.tsx
index b84ea96a..e4c4cf55 100644
--- a/apps/web/src/components/approvals/review-panel.test.tsx
+++ b/apps/web/src/components/approvals/review-panel.test.tsx
@@ -7,6 +7,7 @@ import type { ForgeApiClient } from "@/lib/api/client";
 import type {
   ApprovalContext,
   ApprovalSummary,
+  AttestationOut,
   RedTeamGateOut,
 } from "@/lib/api/types";
 
@@ -66,9 +67,28 @@ function noRedTeamScan(): Promise<RedTeamGateOut> {
   return Promise.resolve({ workflow_run_id: "wf-1", latest: null, records: [] });
 }
 
+const verifiedAttestation: AttestationOut = {
+  id: "att-1",
+  changeset_hash: "sha256:" + "ab".repeat(32),
+  predicate_type: "https://forge.dev/attestations/changeset/v1",
+  keyid: "cd".repeat(32),
+  payload_hash: "ef".repeat(32),
+  created_at: "2026-07-19T00:00:00Z",
+  verified: true,
+  provenance: {
+    workflow_run_id: "wf-1",
+    agent_run_id: "ag-1",
+    pr_numbers: [7, 9],
+    spec_key: "F41",
+    spec_version: 2,
+    audit_seq: 12,
+  },
+};
+
 function makeClient(overrides: Partial<ForgeApiClient> = {}): ForgeApiClient {
   return {
     getWorkflowRunRedTeam: vi.fn(noRedTeamScan),
+    getApprovalAttestation: vi.fn(() => Promise.resolve<AttestationOut | null>(null)),
     ...overrides,
   } as unknown as ForgeApiClient;
 }
@@ -198,6 +218,26 @@ describe("ReviewPanel — nine must-show items", () => {
     );
   });
 
+  it("surfaces a verified attested changeset on the run trace section", async () => {
+    const client = makeClient({
+      getApprovalAttestation: vi.fn(() => Promise.resolve(verifiedAttestation)),
+    });
+    renderPanel(fullContext, {}, client);
+
+    const panel = await screen.findByTestId("attestation-panel");
+    expect(panel).toHaveAttribute("data-state", "verified");
+    expect(within(panel).getByText(/signature verified/i)).toBeInTheDocument();
+    expect(client.getApprovalAttestation).toHaveBeenCalledWith("a1");
+  });
+
+  it("shows the honest not-attested state when the server confirms absence", async () => {
+    renderPanel(fullContext);
+
+    const panel = await screen.findByTestId("attestation-panel");
+    expect(panel).toHaveAttribute("data-state", "absent");
+    expect(within(panel).getByText(/not attested/i)).toBeInTheDocument();
+  });
+
   it("shows no red-team badge before a scan has landed", async () => {
     renderPanel(fullContext);
     await waitFor(() => expect(screen.getByTestId("run-trace")).toBeInTheDocument());
diff --git a/apps/web/src/components/approvals/review-panel.tsx b/apps/web/src/components/approvals/review-panel.tsx
index b824a71c..d8a930f4 100644
--- a/apps/web/src/components/approvals/review-panel.tsx
+++ b/apps/web/src/components/approvals/review-panel.tsx
@@ -13,6 +13,7 @@ import {
 } from "lucide-react";
 import type { ReactNode } from "react";
 
+import { AttestationPanel } from "@/components/attestations/attestation-panel";
 import { ErrorState } from "@/components/ui/error-state";
 import { Loading, Skeleton } from "@/components/ui/skeleton";
 import { apiClient, type ForgeApiClient } from "@/lib/api/client";
@@ -177,7 +178,7 @@ export function ReviewPanel({
       {/* 8 — Run trace */}
       {runTrace ? (
         <Section n={8} title="Run trace" icon={GitBranch}>
-          <RunTrace runTrace={runTrace} client={client} />
+          <RunTrace runTrace={runTrace} approvalId={summary.id} client={client} />
         </Section>
       ) : null}
     </div>
@@ -540,9 +541,11 @@ function RiskRow({ flag }: { flag: RiskFlag }) {
 
 function RunTrace({
   runTrace,
+  approvalId,
   client,
 }: {
   runTrace: Record<string, unknown>;
+  approvalId: string;
   client?: ForgeApiClient;
 }) {
   const entries = Object.entries(runTrace).filter(([, v]) => scalar(v) !== null);
@@ -556,6 +559,10 @@ function RunTrace({
           was blocked by) before reaching this human gate. Renders nothing
           until a scan has landed — see RedTeamBadge. */}
       <RedTeamBadge workflowRunId={workflowRunId} client={client} />
+      {/* Attested Changesets: the DSSE-signed provenance record for this
+          gate's run — verified / verification-failed / honestly absent
+          (records are minted on approval). See AttestationPanel. */}
+      <AttestationPanel approvalId={approvalId} client={client} />
       <dl className="flex flex-col gap-1.5" data-testid="run-trace">
         {entries.map(([key, value]) => (
           <div key={key} className="flex items-center justify-between gap-3">
diff --git a/apps/web/src/components/attestations/attestation-panel.test.tsx b/apps/web/src/components/attestations/attestation-panel.test.tsx
new file mode 100644
index 00000000..44168895
--- /dev/null
+++ b/apps/web/src/components/attestations/attestation-panel.test.tsx
@@ -0,0 +1,112 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import type { ForgeApiClient } from "@/lib/api/client";
+import type { AttestationOut } from "@/lib/api/types";
+
+import { AttestationPanel } from "./attestation-panel";
+
+const verifiedAttestation: AttestationOut = {
+  id: "att-1",
+  changeset_hash: "sha256:" + "ab".repeat(32),
+  predicate_type: "https://forge.dev/attestations/changeset/v1",
+  keyid: "cd".repeat(32),
+  payload_hash: "ef".repeat(32),
+  created_at: "2026-07-19T00:00:00Z",
+  verified: true,
+  provenance: {
+    workflow_run_id: "wf-1",
+    agent_run_id: "ag-1",
+    pr_numbers: [7, 9],
+    spec_key: "F41",
+    spec_version: 2,
+    audit_seq: 12,
+  },
+};
+
+function makeClient(
+  getApprovalAttestation: () => Promise<AttestationOut | null>,
+): ForgeApiClient {
+  return {
+    getApprovalAttestation: vi.fn(getApprovalAttestation),
+  } as unknown as ForgeApiClient;
+}
+
+function renderPanel(approvalId: string | null | undefined, client: ForgeApiClient) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  }
+  return render(<AttestationPanel approvalId={approvalId} client={client} />, {
+    wrapper: Wrapper,
+  });
+}
+
+describe("AttestationPanel", () => {
+  it("renders nothing when no approval id is known", () => {
+    const client = makeClient(() => Promise.resolve(null));
+    const { container } = renderPanel(null, client);
+    expect(container).toBeEmptyDOMElement();
+    expect(client.getApprovalAttestation).not.toHaveBeenCalled();
+  });
+
+  it("shows an honest absent state when no attestation exists (404)", async () => {
+    const client = makeClient(() => Promise.resolve(null));
+    renderPanel("a1", client);
+
+    const panel = await screen.findByTestId("attestation-panel");
+    expect(panel).toHaveAttribute("data-state", "absent");
+    expect(within(panel).getByText(/not attested/i)).toBeInTheDocument();
+    expect(client.getApprovalAttestation).toHaveBeenCalledWith("a1");
+  });
+
+  it("shows a verified state and reveals provenance on expand", async () => {
+    const client = makeClient(() => Promise.resolve(verifiedAttestation));
+    renderPanel("a1", client);
+
+    const panel = await screen.findByTestId("attestation-panel");
+    expect(panel).toHaveAttribute("data-state", "verified");
+    expect(within(panel).getByText(/signature verified/i)).toBeInTheDocument();
+
+    const toggle = within(panel).getByRole("button");
+    expect(toggle).toHaveAttribute("aria-expanded", "false");
+    expect(screen.queryByTestId("attestation-details")).not.toBeInTheDocument();
+
+    fireEvent.click(toggle);
+
+    expect(toggle).toHaveAttribute("aria-expanded", "true");
+    const details = await screen.findByTestId("attestation-details");
+    expect(within(details).getByText(verifiedAttestation.changeset_hash)).toBeInTheDocument();
+    expect(within(details).getByText(verifiedAttestation.keyid)).toBeInTheDocument();
+    expect(within(details).getByText("7, 9")).toBeInTheDocument();
+    expect(within(details).getByText("F41 v2")).toBeInTheDocument();
+  });
+
+  it("shows an honest failure state when the signature does not verify", async () => {
+    const client = makeClient(() =>
+      Promise.resolve({ ...verifiedAttestation, verified: false }),
+    );
+    renderPanel("a1", client);
+
+    const panel = await screen.findByTestId("attestation-panel");
+    expect(panel).toHaveAttribute("data-state", "verification-failed");
+    expect(
+      within(panel).getByText(/signature failed verification/i),
+    ).toBeInTheDocument();
+    expect(within(panel).queryByText(/signature verified/i)).not.toBeInTheDocument();
+  });
+
+  it("renders nothing when the fetch fails (an error is not proof of absence)", async () => {
+    const client = makeClient(() => Promise.reject(new Error("network down")));
+    const { container } = renderPanel("a1", client);
+
+    await waitFor(() => expect(client.getApprovalAttestation).toHaveBeenCalled());
+    await waitFor(() => expect(container).toBeEmptyDOMElement());
+  });
+});
diff --git a/apps/web/src/components/attestations/attestation-panel.tsx b/apps/web/src/components/attestations/attestation-panel.tsx
new file mode 100644
index 00000000..476b6456
--- /dev/null
+++ b/apps/web/src/components/attestations/attestation-panel.tsx
@@ -0,0 +1,131 @@
+"use client";
+
+import { BadgeCheck, BadgeX, FileQuestion } from "lucide-react";
+import { useState } from "react";
+
+import { useApprovalAttestation } from "@/lib/api/approvals";
+import { apiClient, type ForgeApiClient } from "@/lib/api/client";
+import type { AttestationOut } from "@/lib/api/types";
+import { cn } from "@/lib/utils";
+
+export interface AttestationPanelProps {
+  /**
+   * The approval gate whose attestation to show (`ApprovalSummary.id`).
+   * Absent -> nothing renders.
+   */
+  approvalId?: string | null;
+  client?: ForgeApiClient;
+}
+
+/**
+ * The Attested Changeset panel (Attested Changesets, Task 19).
+ *
+ * Approving a `pr` gate that carries a workflow run mints a DSSE/Ed25519-signed
+ * provenance record over the changeset. This panel shows exactly what the
+ * server can vouch for — three honest states, no fake ones:
+ *
+ * - **verified** — a signed record exists and its signature verifies against
+ *   the deployment's key (computed server-side by the same path the
+ *   `forge-verify` CLI uses);
+ * - **verification-failed** — a signed record exists but its signature does
+ *   NOT verify (wrong or rotated key, or a tampered record);
+ * - **absent** — the server confirmed no attestation exists (normal while the
+ *   gate is still pending: records are minted on approval).
+ *
+ * While loading — or when the fetch itself fails — nothing renders: a failed
+ * request is not proof of absence, so the panel stays quiet rather than
+ * claiming a state it cannot back.
+ */
+export function AttestationPanel({ approvalId, client = apiClient }: AttestationPanelProps) {
+  const [expanded, setExpanded] = useState(false);
+  const query = useApprovalAttestation(approvalId, client);
+
+  if (!approvalId || query.isPending || query.isError) {
+    return null;
+  }
+
+  const attestation = query.data ?? null;
+
+  if (attestation === null) {
+    return (
+      <div
+        data-testid="attestation-panel"
+        data-state="absent"
+        className="inline-flex w-fit items-center gap-1.5 rounded-full border border-border bg-muted/40 px-2.5 py-1 text-xs font-medium text-muted-foreground"
+      >
+        <FileQuestion aria-hidden className="h-3.5 w-3.5" />
+        Not attested — no signed changeset record for this gate yet
+      </div>
+    );
+  }
+
+  const failed = !attestation.verified;
+  const Icon = failed ? BadgeX : BadgeCheck;
+
+  return (
+    <div
+      data-testid="attestation-panel"
+      data-state={failed ? "verification-failed" : "verified"}
+      className="flex flex-col gap-2"
+    >
+      <button
+        type="button"
+        aria-expanded={expanded}
+        onClick={() => setExpanded((v) => !v)}
+        className={cn(
+          "inline-flex w-fit items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs font-medium transition-colors",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          failed
+            ? "border-danger/40 bg-danger/10 text-danger"
+            : "border-success/40 bg-success/10 text-success",
+        )}
+      >
+        <Icon aria-hidden className="h-3.5 w-3.5" />
+        {failed
+          ? "Attested changeset — signature failed verification"
+          : "Attested changeset — signature verified"}
+      </button>
+
+      {expanded ? <AttestationDetails attestation={attestation} /> : null}
+    </div>
+  );
+}
+
+function DetailRow({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="flex items-start justify-between gap-3">
+      <dt className="shrink-0 text-muted-foreground">{label}</dt>
+      <dd className="min-w-0 truncate text-right font-mono text-foreground">{value}</dd>
+    </div>
+  );
+}
+
+function AttestationDetails({ attestation }: { attestation: AttestationOut }) {
+  const { provenance } = attestation;
+  const spec =
+    provenance.spec_key && provenance.spec_version
+      ? `${provenance.spec_key} v${provenance.spec_version}`
+      : null;
+  return (
+    <div
+      data-testid="attestation-details"
+      className="flex flex-col gap-1.5 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs"
+    >
+      <dl className="flex flex-col gap-1">
+        <DetailRow label="Changeset" value={attestation.changeset_hash} />
+        <DetailRow label="Signing key" value={attestation.keyid} />
+        {provenance.pr_numbers.length > 0 ? (
+          <DetailRow label="PRs" value={provenance.pr_numbers.join(", ")} />
+        ) : null}
+        {spec ? <DetailRow label="Spec" value={spec} /> : null}
+        {provenance.audit_seq != null ? (
+          <DetailRow label="Audit seq" value={String(provenance.audit_seq)} />
+        ) : null}
+        <DetailRow
+          label="Attested at"
+          value={new Date(attestation.created_at).toLocaleString()}
+        />
+      </dl>
+    </div>
+  );
+}
diff --git a/apps/web/src/lib/api/approvals.ts b/apps/web/src/lib/api/approvals.ts
index 6865e1c6..c103de5d 100644
--- a/apps/web/src/lib/api/approvals.ts
+++ b/apps/web/src/lib/api/approvals.ts
@@ -27,6 +27,7 @@ import type {
   ApprovalDecisionRequest,
   ApprovalResolution,
   ApprovalSummary,
+  AttestationOut,
   RedTeamGateOut,
 } from "./types";
 
@@ -43,6 +44,8 @@ export const approvalKeys = {
     ["approvals", "decisions", approvalId] as const,
   redTeam: (workflowRunId: string) =>
     ["approvals", "red-team", workflowRunId] as const,
+  attestation: (approvalId: string) =>
+    ["approvals", "attestation", approvalId] as const,
 } as const;
 
 export type ApprovalFilters = Record<
@@ -115,6 +118,26 @@ export function useRedTeamVerdict(
   });
 }
 
+/**
+ * The Attested Changeset for one gate (Attested Changesets, Task 19) — the
+ * DSSE/Ed25519-signed provenance record minted when a `pr` gate carrying a
+ * workflow run is approved. `null` is the confirmed-absent state (the API's
+ * 404, mapped by the client): the gate has no attestation, which is normal
+ * while it is still pending. Retries are disabled for the same reason as the
+ * red-team query: absence is an answer, not an error to retry.
+ */
+export function useApprovalAttestation(
+  approvalId: string | null | undefined,
+  client: ForgeApiClient = apiClient,
+): UseQueryResult<AttestationOut | null> {
+  return useQuery({
+    queryKey: approvalKeys.attestation(approvalId ?? ""),
+    queryFn: () => client.getApprovalAttestation(approvalId as string),
+    enabled: Boolean(approvalId),
+    retry: false,
+  });
+}
+
 export interface DecideVariables {
   approvalId: string;
   body: ApprovalDecisionRequest;
diff --git a/apps/web/src/lib/api/attestations.test.ts b/apps/web/src/lib/api/attestations.test.ts
new file mode 100644
index 00000000..e7ca850b
--- /dev/null
+++ b/apps/web/src/lib/api/attestations.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { ForgeApiClient } from "./client";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function makeClient(response: Response) {
+  const fetchImpl = vi.fn(() => Promise.resolve(response));
+  const client = new ForgeApiClient({
+    baseUrl: "http://api.test",
+    fetch: fetchImpl as unknown as typeof fetch,
+  });
+  return { client, fetchImpl };
+}
+
+describe("ForgeApiClient — attestations", () => {
+  it("maps a 404 from the by-approval endpoint to null (confirmed absence)", async () => {
+    const { client, fetchImpl } = makeClient(
+      jsonResponse(404, { detail: "no attestation recorded for approval a1" }),
+    );
+
+    await expect(client.getApprovalAttestation("a1")).resolves.toBeNull();
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "http://api.test/approvals/a1/attestation",
+      expect.anything(),
+    );
+  });
+
+  it("still throws for non-404 failures (an error is not absence)", async () => {
+    const { client } = makeClient(jsonResponse(500, { detail: "boom" }));
+
+    await expect(client.getApprovalAttestation("a1")).rejects.toMatchObject({
+      name: "ApiError",
+      status: 500,
+    });
+  });
+
+  it("requests the workspace attestation page with its query params", async () => {
+    const { client, fetchImpl } = makeClient(
+      jsonResponse(200, { items: [], limit: 25, offset: 50 }),
+    );
+
+    const page = await client.listAttestations({ limit: 25, offset: 50 });
+    expect(page).toEqual({ items: [], limit: 25, offset: 50 });
+    expect(fetchImpl).toHaveBeenCalledWith(
+      "http://api.test/attestations?limit=25&offset=50",
+      expect.anything(),
+    );
+  });
+});
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index e3dab469..166d2063 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -21,6 +21,8 @@ import type {
   ApprovalRequest,
   ApprovalResolution,
   ApprovalSummary,
+  AttestationListResponse,
+  AttestationOut,
   AuditEntry,
   AuditListResponse,
   AuditQuery,
@@ -452,6 +454,44 @@ export class ForgeApiClient {
     );
   }
 
+  // --- Attested Changesets (read-only /attestations surface) -------------- //
+
+  /** One workspace-scoped page of signed changeset attestations, newest first. */
+  listAttestations(
+    query?: RequestOptions["query"],
+  ): Promise<AttestationListResponse> {
+    return this.request<AttestationListResponse>("/attestations", { query });
+  }
+
+  /** One attestation by id (workspace-isolated; foreign ids 404). */
+  getAttestation(attestationId: string): Promise<AttestationOut> {
+    return this.request<AttestationOut>(
+      `/attestations/${encodeURIComponent(attestationId)}`,
+    );
+  }
+
+  /**
+   * The attestation minted for a gate's linked workflow run. The API answers
+   * 404 when none exists (unlinked gate, or the run was never attested —
+   * e.g. the gate is still pending); that is a normal "not attested" state,
+   * surfaced as `null` so the UI can render honest absence, while every other
+   * failure still throws.
+   */
+  async getApprovalAttestation(
+    approvalId: string,
+  ): Promise<AttestationOut | null> {
+    try {
+      return await this.request<AttestationOut>(
+        `/approvals/${encodeURIComponent(approvalId)}/attestation`,
+      );
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
   // --- Spec engine / SDD lifecycle (F02 /spec + F23 dashboard) ------------ //
 
   /**
diff --git a/apps/web/src/lib/api/types.ts b/apps/web/src/lib/api/types.ts
index 3e5af362..6bf71882 100644
--- a/apps/web/src/lib/api/types.ts
+++ b/apps/web/src/lib/api/types.ts
@@ -341,6 +341,50 @@ export interface RedTeamGateOut {
   records: RedTeamRecordOut[];
 }
 
+// --- Attested Changesets (GET /attestations, /approvals/{id}/attestation) - //
+// Hand-maintained mirror of `forge_api.schemas.attestation.*`. A DSSE/Ed25519
+// signed provenance record over a changeset, minted as a side effect of
+// approving a `pr` gate. `verified` is computed server-side by the exact
+// verification path the `forge-verify` CLI uses — never stored, never faked.
+
+/** The queryable provenance columns of one attestation row. */
+export interface AttestationProvenance {
+  workflow_run_id?: string | null;
+  agent_run_id?: string | null;
+  /** PR numbers the attestation covers. */
+  pr_numbers: number[];
+  /** Spec identity; degrades honestly to `""` / `0` without traceability. */
+  spec_key?: string | null;
+  spec_version?: number | null;
+  /** Position of the chained `changeset.attested` audit event. */
+  audit_seq?: number | null;
+}
+
+/** One immutable DSSE-signed changeset attestation, with live verification. */
+export interface AttestationOut {
+  id: string;
+  /** The attested subject's labeled digest (`sha256:<hex>`). */
+  changeset_hash: string;
+  /** The in-toto predicate type URI of the signed Statement. */
+  predicate_type: string;
+  /** sha256 of the raw Ed25519 public key that signed the envelope. */
+  keyid: string;
+  /** sha256 hex of the PAE-encoded payload the signature covers. */
+  payload_hash: string;
+  created_at: string;
+  /** Recorded payload hash matches the PAE re-derivation AND the Ed25519
+   * signature verifies against the deployment's verification key. */
+  verified: boolean;
+  provenance: AttestationProvenance;
+}
+
+/** Body of `GET /attestations` — one workspace-scoped page, newest first. */
+export interface AttestationListResponse {
+  items: AttestationOut[];
+  limit: number;
+  offset: number;
+}
+
 // --- Spec engine / SDD (F02 /spec + F23 spec-validation) ------------------ //
 // Hand-maintained mirror of the spec DTOs in `forge_contracts.dtos` (Pydantic
 // v2). Enum string values match the Python `SpecStatus` StrEnum verbatim.
diff --git a/docs/trust-layer.md b/docs/trust-layer.md
index 52ed8a5c..0ceb6d8e 100644
--- a/docs/trust-layer.md
+++ b/docs/trust-layer.md
@@ -83,8 +83,35 @@ batch-Merkle anchoring scheme, unused today).
 Attestations are minted as a **side effect of approval**:
 `PrAttestationResolutionHook` is registered against the F36 approval system, so
 approving a `pr` gate that carries a `workflow_run_id` attests the changeset
-(recording the approving user as `human_approver`). There is no dedicated REST
-endpoint or UI yet.
+(recording the approving user as `human_approver`). There is deliberately no
+HTTP route that mints one.
+
+Records are surfaced **read-only over REST**
+(`apps/api/forge_api/routers/attestations.py`), workspace-scoped with the same
+auth/tenancy contract as the approvals router (cross-workspace ids read as
+`404` — no existence leak):
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET /attestations` | One workspace-scoped page (`limit`/`offset`, newest first; filters: `workflow_run_id`, `agent_run_id`, `spec_key`) |
+| `GET /attestations/{id}` | One record (`404` for unknown or foreign ids) |
+| `GET /approvals/{id}/attestation` | The record minted for the gate's linked workflow run (`404` when none exists — normal while the gate is still pending) |
+
+Every response carries a computed `verified: bool` produced by the **same
+verification seam `forge-verify --run` uses**
+(`forge_api.cli_verify.verify_stored_attestation`): re-derive `payload_hash`
+from the envelope's PAE encoding, confirm it matches the recorded column, then
+Ed25519-verify the signature against the deployment's verification key (the
+public half of `FORGE_ATTEST_SIGNING_KEY`). A record this deployment cannot
+vouch for honestly reads `verified: false` — the flag is computed per request,
+never stored.
+
+In the web app, the approvals review surface renders an attestation panel
+(`apps/web/src/components/attestations/attestation-panel.tsx`, on the gate's
+run-trace section next to the red-team badge) with three honest states:
+signed + verified, signed + verification-failed, and confirmed-absent ("not
+attested" — normal while the gate is pending, since records are minted on
+approval). A failed fetch renders nothing: an error is not proof of absence.
 
 Verification is offline-first via the `forge-verify` CLI (`python -m
 forge_api.cli_verify`, `apps/api/forge_api/cli_verify.py`). Three
@@ -104,9 +131,13 @@ tampered").
 ### Current limitations
 
 - **Minted only as an approval side effect.** An attestation is produced when a
-  `pr` approval gate carrying a `workflow_run_id` is approved. There is **no
-  REST endpoint and no UI** to list, fetch, or trigger attestations — those
-  arrive in a later task (Attested Changesets REST endpoints + UI, Task 19).
+  `pr` approval gate carrying a `workflow_run_id` is approved. The REST surface
+  and the approvals-UI panel are **read-only**: there is deliberately no
+  endpoint to trigger or mint an attestation.
+- **REST `verified` is deployment-relative.** The endpoints verify against the
+  public half of this deployment's `FORGE_ATTEST_SIGNING_KEY`, and the raw DSSE
+  envelope is not exposed over REST — independent third-party verification goes
+  through `forge-verify`, which re-reads the stored row.
 - **Default signing key is process-ephemeral.** If `FORGE_ATTEST_SIGNING_KEY`
   is unset, signatures are made with a warned-about ephemeral key and will fail
   verification after a restart or from another process. Set a stable key in any

From 7de1f549b7a8fcbbd1786d6899ec939fc94bceeb Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 05:43:43 +0200
Subject: [PATCH 42/47] feat(red-team): trigger endpoint and V1 worker gate
 parity

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/workflow.py        | 142 +++++++++-
 apps/api/forge_api/schemas/red_team.py        |  20 +-
 apps/api/tests/test_red_team_trigger_api.py   | 252 ++++++++++++++++++
 docs/trust-layer.md                           |  60 +++--
 .../forge_workflow/red_team_gate.py           | 204 ++++++++++++++
 .../forge_workflow/temporal/activities.py     |  13 +-
 .../forge_workflow/temporal/payloads.py       |  56 +---
 .../tests/test_red_team_v1_gate.py            | 198 ++++++++++++++
 8 files changed, 863 insertions(+), 82 deletions(-)
 create mode 100644 apps/api/tests/test_red_team_trigger_api.py
 create mode 100644 packages/workflow-engine/forge_workflow/red_team_gate.py
 create mode 100644 packages/workflow-engine/tests/test_red_team_v1_gate.py

diff --git a/apps/api/forge_api/routers/workflow.py b/apps/api/forge_api/routers/workflow.py
index 0872e019..fe837220 100644
--- a/apps/api/forge_api/routers/workflow.py
+++ b/apps/api/forge_api/routers/workflow.py
@@ -6,19 +6,29 @@
 * ``GET  /workflow/runs/{run_id}``           — fetch a run.
 * ``POST /workflow/runs/{run_id}/transition``— apply an FSM event and return the run.
 * ``GET  /workflow/runs/{run_id}/red-team``  — Red-Team Gate verdict + evidence.
+* ``POST /workflow/runs/{run_id}/red-team``  — trigger a Red-Team scan for a run.
 
 Handlers delegate to a process-wide :class:`~forge_workflow.WorkflowEngineImpl`
 backed by an in-memory run store (the SQLAlchemy-backed store is swapped in
 behind the same dependency via ``app.dependency_overrides`` / config). Domain
 errors map to HTTP: unknown run -> 404; invalid/ambiguous transition -> 409.
 
-The ``red-team`` route reads directly off the append-only ``red_team_record``
+The ``red-team`` GET reads directly off the append-only ``red_team_record``
 table (see ``forge_db.redteam``) rather than through the FSM engine: it is
 workspace-scoped on the row itself (``run_id`` is the same
 ``WorkflowParams.workflow_run_id`` the Temporal ``FeatureWorkflow`` scans before
 the human spec gate — see ``forge_workflow.temporal.workflows``), so it needs
 no engine/ownership lookup and degrades safely (empty history, no leak) for an
 unscanned or foreign run.
+
+Red-Team Gate, V1 parity (Task 20): the V1 FSM is a plain transition graph with
+no gate hooks, and this router is its only production driver — so when a V1
+transition lands a run in ``spec_review`` (the human spec gate, exactly where
+the Temporal spine scans), the handler mints the run's verdict once via the
+shared :func:`forge_workflow.red_team_gate.ensure_red_team_verdict`: the
+configured adversary when one is wired (:func:`get_red_team_fn`), an explicit
+parked-pass otherwise — park-don't-fake, never silent. The Temporal spine keeps
+owning its own scan inside ``FeatureWorkflow.run`` (the mint is V1-engine-only).
 """
 
 from __future__ import annotations
@@ -37,8 +47,8 @@
 from forge_api.db import get_db
 from forge_api.deps import Principal, get_current_principal
 from forge_api.routers._rbac import require_permission
-from forge_api.schemas.red_team import RedTeamGateOut, RedTeamRecordOut
-from forge_contracts import WorkflowRun
+from forge_api.schemas.red_team import RedTeamGateOut, RedTeamRecordOut, RedTeamTriggerOut
+from forge_contracts import WorkflowRun, WorkflowState
 from forge_db.redteam import RedTeamRepository
 from forge_workflow import (
     AmbiguousTransitionError,
@@ -49,6 +59,11 @@
     WorkflowEngineImpl,
     WorkflowRunNotFoundError,
 )
+from forge_workflow.red_team_gate import (
+    RedTeamFn,
+    ensure_red_team_verdict,
+    run_and_record_red_team,
+)
 
 router = APIRouter(
     prefix="/workflow",
@@ -132,8 +147,30 @@ def get_workflow_ownership() -> WorkflowOwnership:
     return _workflow_ownership_singleton()
 
 
+def get_red_team_fn() -> RedTeamFn | None:
+    """The configured Red-Team adversary harness (override in tests / deploys via DI).
+
+    ``None`` (the default — no adversary model/sandbox is wired in the API
+    process) makes every V1/triggered scan an EXPLICIT parked-pass
+    (``kind="parked"``, evidence naming the reason) — park-don't-fake, mirroring
+    the Temporal activity's ``_default_red_team``. A real deployment overrides
+    this with a callable that runs the heterogeneous, sandboxed adversary
+    (``forge_coordinator.red_team.run_red_team``).
+    """
+    return None
+
+
 EngineDep = Annotated[WorkflowEngineImpl, Depends(get_workflow_engine)]
 OwnershipDep = Annotated[WorkflowOwnership, Depends(get_workflow_ownership)]
+RedTeamFnDep = Annotated[RedTeamFn | None, Depends(get_red_team_fn)]
+
+#: Run states at which a red-team scan may be triggered, mapped to the gate
+#: phase the scan runs before (mirrors ``RedTeamInput.phase``: spec | pr).
+_GATEABLE_STATES: dict[str, str] = {
+    WorkflowState.SPEC_REVIEW.value: "spec",
+    WorkflowState.PR_OPENED.value: "pr",
+    WorkflowState.AWAITING_REVIEW.value: "pr",
+}
 
 
 # --------------------------------------------------------------------------- #
@@ -185,6 +222,20 @@ def _require_owned(
         )
 
 
+def _run_task_id(run: WorkflowRun) -> uuid.UUID:
+    """Narrow the contract's optional ``task_id`` (always set by ``start_run``).
+
+    A run without one cannot be red-team scanned (``RedTeamInput.task_id`` is
+    required) — fail loud rather than silently skipping the gate.
+    """
+    if run.task_id is None:  # pragma: no cover — start_run always sets it
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"workflow run {run.id} has no task_id; cannot red-team scan",
+        )
+    return run.task_id
+
+
 @router.post("/runs", response_model=WorkflowRun, status_code=status.HTTP_201_CREATED)
 def start_run(
     engine: EngineDep,
@@ -213,15 +264,40 @@ def get_run(
 def transition(
     engine: EngineDep,
     ownership: OwnershipDep,
+    session: SessionDep,
     principal: WriterDep,
+    red_team_fn: RedTeamFnDep,
     run_id: uuid.UUID,
     request: TransitionRequest,
 ) -> WorkflowRun:
-    """Apply an FSM transition event and return the updated run."""
+    """Apply an FSM transition event and return the updated run.
+
+    Red-Team Gate (V1 parity): when a V1 (FSM-engine) transition lands the run
+    in ``spec_review`` — the human spec gate, exactly where the Temporal spine
+    scans — mint the run's verdict once (idempotent across gate re-entries):
+    the configured adversary when wired, an explicit parked-pass otherwise.
+    Failure to record is loud (500), never a silently skipped gate. The
+    Temporal engine is excluded: its workflow body owns the scan.
+    """
     _require_owned(ownership, run_id, principal.workspace_id)
     with _workflow_errors():
         engine.transition(run_id, request.event)
-        return engine.get_run(run_id)
+        run = engine.get_run(run_id)
+    if (
+        isinstance(engine, WorkflowEngineImpl)
+        and run.current_state == WorkflowState.SPEC_REVIEW.value
+        and run.id is not None
+    ):
+        ensure_red_team_verdict(
+            session,
+            principal.workspace_id,
+            workflow_run_id=run.id,
+            task_id=_run_task_id(run),
+            phase=_GATEABLE_STATES[run.current_state],
+            red_team_fn=red_team_fn,
+        )
+        session.commit()
+    return run
 
 
 @router.get("/runs/{run_id}/red-team", response_model=RedTeamGateOut)
@@ -245,10 +321,66 @@ def get_run_red_team(
     )
 
 
+@router.post(
+    "/runs/{run_id}/red-team",
+    response_model=RedTeamTriggerOut,
+    status_code=status.HTTP_202_ACCEPTED,
+)
+def trigger_run_red_team(
+    engine: EngineDep,
+    ownership: OwnershipDep,
+    session: SessionDep,
+    principal: WriterDep,
+    red_team_fn: RedTeamFnDep,
+    run_id: uuid.UUID,
+) -> RedTeamTriggerOut:
+    """Trigger a Red-Team scan for a run and append its verdict to the history.
+
+    Runs the configured adversary when one is wired (:func:`get_red_team_fn`);
+    otherwise records an EXPLICIT parked-pass (``kind="parked"``, evidence
+    naming the missing adversary) — never disguised as a real adversarial pass.
+    Each trigger appends a fresh ``red_team_record`` (a ``blocked`` scan
+    followed by a re-triggered ``survived`` one is the documented history the
+    GET surface returns). ``409`` when the run is not at a gateable state
+    (``spec_review`` for the spec phase; ``pr_opened``/``awaiting_review`` for
+    the pr phase); unknown or foreign runs read as ``404`` (no existence leak).
+    """
+    _require_owned(ownership, run_id, principal.workspace_id)
+    with _workflow_errors():
+        run = engine.get_run(run_id)
+    phase = _GATEABLE_STATES.get(run.current_state)
+    if phase is None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=(
+                f"run {run_id} is not at a red-team gateable state "
+                f"(current_state={run.current_state!r}; gateable: "
+                f"{', '.join(sorted(_GATEABLE_STATES))})"
+            ),
+        )
+    row = run_and_record_red_team(
+        session,
+        principal.workspace_id,
+        workflow_run_id=run_id,
+        task_id=_run_task_id(run),
+        phase=phase,
+        red_team_fn=red_team_fn,
+        actor_id=principal.user_id,
+    )
+    session.commit()
+    return RedTeamTriggerOut(
+        workflow_run_id=run_id,
+        record_id=row.id,
+        verdict=row.verdict,
+        kind=row.kind,
+    )
+
+
 __all__ = [
     "StartRunRequest",
     "TransitionRequest",
     "WorkflowOwnership",
+    "get_red_team_fn",
     "get_workflow_engine",
     "get_workflow_ownership",
     "router",
diff --git a/apps/api/forge_api/schemas/red_team.py b/apps/api/forge_api/schemas/red_team.py
index 3a41d4f2..5cd2a544 100644
--- a/apps/api/forge_api/schemas/red_team.py
+++ b/apps/api/forge_api/schemas/red_team.py
@@ -1,5 +1,6 @@
-"""Response schema for the Red-Team Gate surface
-(``GET /workflow/runs/{run_id}/red-team``, Red-Team Gate, slice redteam-surface).
+"""Response schemas for the Red-Team Gate surface
+(``GET``/``POST /workflow/runs/{run_id}/red-team``, Red-Team Gate,
+slices redteam-surface + redteam-trigger).
 """
 
 from __future__ import annotations
@@ -10,7 +11,7 @@
 
 from pydantic import BaseModel, ConfigDict, Field
 
-__all__ = ["RedTeamGateOut", "RedTeamRecordOut"]
+__all__ = ["RedTeamGateOut", "RedTeamRecordOut", "RedTeamTriggerOut"]
 
 
 class RedTeamRecordOut(BaseModel):
@@ -46,3 +47,16 @@ class RedTeamGateOut(BaseModel):
     workflow_run_id: uuid.UUID
     latest: RedTeamRecordOut | None = None
     records: list[RedTeamRecordOut] = Field(default_factory=list)
+
+
+class RedTeamTriggerOut(BaseModel):
+    """Acknowledgement of ``POST /workflow/runs/{run_id}/red-team``: the scan ran
+    and its verdict row was appended. ``record_id`` is the freshly-recorded
+    ``red_team_record`` the follow-up GET returns as ``latest``. ``kind="parked"``
+    means no adversary is configured — an explicit park, never a claimed
+    adversarial pass."""
+
+    workflow_run_id: uuid.UUID
+    record_id: uuid.UUID
+    verdict: str
+    kind: str
diff --git a/apps/api/tests/test_red_team_trigger_api.py b/apps/api/tests/test_red_team_trigger_api.py
new file mode 100644
index 00000000..1ecc7fe1
--- /dev/null
+++ b/apps/api/tests/test_red_team_trigger_api.py
@@ -0,0 +1,252 @@
+"""Integration tests for the Red-Team Gate V1 parity + trigger endpoint (Task 20).
+
+Two surfaces over real handlers on hermetic SQLite (mirrors
+``test_red_team_api.py`` / ``test_workflow_router.py`` conventions):
+
+* the V1 (FSM) gate-arrival mint — a run transitioned into ``spec_review``
+  through ``POST /workflow/runs/{id}/transition`` persists ONE honest parked
+  verdict row (no adversary is configured in the API process), exactly where
+  the Temporal spine scans (post-``submit_spec_for_review``, pre-human-gate);
+* ``POST /workflow/runs/{id}/red-team`` — explicit trigger: 202 + record id,
+  appends to the scan history, 409 off-gate, 404 unknown/foreign, 403 viewer.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from sqlalchemy import StaticPool, create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from forge_api.db import get_db
+from forge_api.deps import Principal, get_current_principal
+from forge_api.main import create_app
+from forge_api.routers.workflow import (
+    WorkflowOwnership,
+    get_workflow_engine,
+    get_workflow_ownership,
+)
+from forge_contracts import UserRole
+from forge_db.base import Base
+from forge_db.models import Workspace
+from forge_workflow import WorkflowEngineImpl
+
+WS = uuid.UUID("00000000-0000-0000-0000-0000000000e1")
+WS2 = uuid.UUID("00000000-0000-0000-0000-0000000000e2")
+
+PARKED_EVIDENCE = {"parked": True, "reason": "no adversary model/sandbox wired"}
+
+#: created -> spec_drafting -> clarification -> spec_review (the human spec gate).
+_TO_SPEC_REVIEW = ("generate_spec_draft", "gather_clarifications", "submit_spec_for_review")
+
+
+@pytest.fixture
+def factory() -> Iterator[sessionmaker[Session]]:
+    engine = create_engine(
+        "sqlite://", connect_args={"check_same_thread": False}, poolclass=StaticPool
+    )
+    Base.metadata.create_all(engine)
+    sf: sessionmaker[Session] = sessionmaker(bind=engine, expire_on_commit=False, class_=Session)
+    with sf() as s:
+        s.add(Workspace(id=WS, name="Acme", slug="acme"))
+        s.add(Workspace(id=WS2, name="Rival", slug="rival"))
+        s.commit()
+    yield sf
+    engine.dispose()
+
+
+def _principal(workspace_id: uuid.UUID = WS, role: UserRole = UserRole.MEMBER) -> Principal:
+    return Principal(
+        user_id=uuid.uuid4(),
+        workspace_id=workspace_id,
+        role=role,
+        email="member@acme.test",
+        auth_method="test",
+        scopes=["*"],
+    )
+
+
+@pytest.fixture
+def harness(factory: sessionmaker[Session]):
+    """(app, make_client) with a fresh V1 engine + ownership per test."""
+    app: FastAPI = create_app()
+    engine = WorkflowEngineImpl()
+    ownership = WorkflowOwnership()
+
+    def _get_db() -> Iterator[Session]:
+        with factory() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = _get_db
+    app.dependency_overrides[get_workflow_engine] = lambda: engine
+    app.dependency_overrides[get_workflow_ownership] = lambda: ownership
+
+    def make_client(principal: Principal) -> TestClient:
+        app.dependency_overrides[get_current_principal] = lambda: principal
+        return TestClient(app)
+
+    return app, make_client
+
+
+def _start(client: TestClient) -> str:
+    resp = client.post("/workflow/runs", json={"task_id": str(uuid.uuid4())})
+    assert resp.status_code == 201, resp.text
+    return resp.json()["id"]
+
+
+def _drive(client: TestClient, run_id: str, *events: str) -> None:
+    for event in events:
+        resp = client.post(f"/workflow/runs/{run_id}/transition", json={"event": event})
+        assert resp.status_code == 200, f"{event}: {resp.text}"
+
+
+def _records(client: TestClient, run_id: str) -> dict:
+    resp = client.get(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 200, resp.text
+    return resp.json()
+
+
+# --------------------------------------------------------------------------- #
+# V1 gate-arrival parity                                                       #
+# --------------------------------------------------------------------------- #
+
+
+def test_v1_run_reaching_spec_review_persists_parked_verdict(harness) -> None:
+    """A V1 run transitioned into ``spec_review`` mints one honest parked
+    verdict row — same shape as the Temporal default — with no extra calls."""
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+
+    _drive(client, run_id, *_TO_SPEC_REVIEW)
+
+    body = _records(client, run_id)
+    assert body["latest"] is not None
+    assert body["latest"]["verdict"] == "survived"
+    assert body["latest"]["kind"] == "parked"
+    assert body["latest"]["evidence"] == PARKED_EVIDENCE
+    assert body["latest"]["adversary_model"] is None
+    assert body["latest"]["coder_model"] is None
+    assert len(body["records"]) == 1
+
+
+def test_v1_gate_mint_is_once_per_run(harness) -> None:
+    """Re-entering the gate (changes requested -> resubmit) does not rescan."""
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+    _drive(client, run_id, *_TO_SPEC_REVIEW)
+    _drive(client, run_id, "spec_changes_requested", "submit_spec_for_review")
+
+    body = _records(client, run_id)
+    assert len(body["records"]) == 1
+
+
+def test_v1_pre_gate_states_record_nothing(harness) -> None:
+    """No verdict is minted before the run reaches the gate."""
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+    _drive(client, run_id, "generate_spec_draft")
+
+    body = _records(client, run_id)
+    assert body["latest"] is None
+    assert body["records"] == []
+
+
+# --------------------------------------------------------------------------- #
+# POST /workflow/runs/{id}/red-team (trigger)                                  #
+# --------------------------------------------------------------------------- #
+
+
+def test_trigger_returns_202_and_get_returns_the_verdict(harness) -> None:
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+    _drive(client, run_id, *_TO_SPEC_REVIEW)
+
+    resp = client.post(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 202, resp.text
+    body = resp.json()
+    assert body["workflow_run_id"] == run_id
+    assert body["verdict"] == "survived"
+    assert body["kind"] == "parked"
+    record_id = body["record_id"]
+
+    # NOTE: ``latest`` identity is not asserted — SQLite's second-resolution
+    # CURRENT_TIMESTAMP ties the gate-arrival mint with the triggered scan and
+    # the repository tiebreaks on ``id.desc()`` (random UUID order), a
+    # documented property of ``RedTeamRepository.get_by_run`` (see
+    # ``test_red_team_api.py``). Membership + shape is the stable contract.
+    got = _records(client, run_id)
+    triggered = [r for r in got["records"] if r["id"] == record_id]
+    assert len(triggered) == 1
+    assert triggered[0]["verdict"] == "survived"
+    assert triggered[0]["kind"] == "parked"
+    assert triggered[0]["evidence"] == PARKED_EVIDENCE
+
+
+def test_trigger_appends_to_the_scan_history(harness) -> None:
+    """The gate-arrival mint plus an explicit trigger = two records."""
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+    _drive(client, run_id, *_TO_SPEC_REVIEW)  # mints record #1
+
+    resp = client.post(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 202, resp.text
+
+    body = _records(client, run_id)
+    assert len(body["records"]) == 2
+    assert resp.json()["record_id"] in {r["id"] for r in body["records"]}
+
+
+def test_trigger_off_gate_is_409(harness) -> None:
+    """A run not at a gateable state (freshly created) conflicts."""
+    _, make_client = harness
+    client = make_client(_principal())
+    run_id = _start(client)
+
+    resp = client.post(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 409, resp.text
+    assert "gateable" in resp.json()["detail"]
+
+    # And nothing was recorded (no silent gating either way).
+    assert _records(client, run_id)["records"] == []
+
+
+def test_trigger_unknown_run_is_404(harness) -> None:
+    _, make_client = harness
+    client = make_client(_principal())
+
+    resp = client.post(f"/workflow/runs/{uuid.uuid4()}/red-team")
+    assert resp.status_code == 404
+
+
+def test_trigger_foreign_workspace_run_is_404(harness) -> None:
+    """Another workspace's run id reads as nonexistent (no existence leak)."""
+    _, make_client = harness
+    owner_client = make_client(_principal(workspace_id=WS))
+    run_id = _start(owner_client)
+    _drive(owner_client, run_id, *_TO_SPEC_REVIEW)
+
+    foreign_client = make_client(_principal(workspace_id=WS2))
+    resp = foreign_client.post(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 404
+
+
+def test_trigger_requires_write_permission(harness) -> None:
+    """A read-only viewer cannot trigger a scan (matches the router's other
+    write endpoints)."""
+    _, make_client = harness
+    member = make_client(_principal())
+    run_id = _start(member)
+    _drive(member, run_id, *_TO_SPEC_REVIEW)
+
+    viewer = make_client(_principal(role=UserRole.VIEWER))
+    resp = viewer.post(f"/workflow/runs/{run_id}/red-team")
+    assert resp.status_code == 403
diff --git a/docs/trust-layer.md b/docs/trust-layer.md
index 0ceb6d8e..ad85caa8 100644
--- a/docs/trust-layer.md
+++ b/docs/trust-layer.md
@@ -242,36 +242,52 @@ adversary model).
 
 ### API / CLI surface
 
-The gate is driven inside the **Temporal** workflow
-(`packages/workflow-engine/forge_workflow/temporal/workflows.py`): after the spec
-is drafted and clarified but **before** the human spec-approval gate, the
-workflow runs a red-team scan. A `blocked` verdict routes the change back for
-changes (→ clarification → spec review) so a human must address the finding; a
-`survived` verdict proceeds unchanged and the recorder writes the
-`RedTeamRecord` plus a `redteam.survived` audit event.
-
-The verdict is surfaced read-only at `GET /workflow/runs/{run_id}/red-team`
+The gate runs on **both** engine spines, minting the same verdict contract
+through the shared `forge_workflow.red_team_gate` helper:
+
+- **Temporal (V2)** — driven inside the workflow
+  (`packages/workflow-engine/forge_workflow/temporal/workflows.py`): after the
+  spec is drafted and clarified but **before** the human spec-approval gate, the
+  workflow runs a red-team scan. A `blocked` verdict routes the change back for
+  changes (→ clarification → spec review) so a human must address the finding; a
+  `survived` verdict proceeds unchanged and the recorder writes the
+  `RedTeamRecord` plus a `redteam.survived` audit event.
+- **V1 (Postgres FSM)** — the FSM is a plain transition graph with no gate
+  hooks, and its one production driver is the workflow router: when a
+  transition lands a V1 run in `spec_review` (the human spec gate — the same
+  position the Temporal spine scans), the handler mints the run's verdict once
+  via `ensure_red_team_verdict` (idempotent across gate re-entries: a block →
+  changes → resubmit loop does not rescan) and appends it to `red_team_record`
+  with the same `redteam.survived` audit chaining.
+
+The verdict is surfaced at `GET /workflow/runs/{run_id}/red-team`
 (`apps/api/forge_api/routers/workflow.py`), returning the latest verdict plus the
 full scan history (a `blocked` scan followed by a re-submitted `survived` one is
 common). It reads the append-only table scoped to the caller's workspace on the
 row itself; an unscanned or foreign run reads as `latest=None` with an empty
 history — never a 404, so the endpoint never leaks cross-tenant existence.
 
+A scan can also be triggered explicitly: `POST /workflow/runs/{run_id}/red-team`
+(write permission, same pattern as the router's other write endpoints) runs the
+configured adversary — or records an explicit parked-pass when none is wired —
+and **appends** a fresh verdict to the run's history, returning `202` with the
+new `record_id` (+ `verdict`/`kind`); the follow-up GET returns it. It answers
+`409` when the run is not at a gateable state (`spec_review` for the spec
+phase; `pr_opened`/`awaiting_review` for the pr phase) and `404` for unknown or
+foreign runs (no existence leak).
+
 ### Current limitations
 
-- **Parked-pass when no adversary is wired.** The Temporal activity's default
-  `red_team_fn`
-  (`packages/workflow-engine/forge_workflow/temporal/activities.py`,
-  `_default_red_team`) records a **parked-pass**: `verdict=survived`,
-  `kind=parked`, `evidence={"parked": true, "reason": "no adversary model/sandbox
-  wired"}`. This is a *park-don't-fake* stand-in so the durable spine runs and
-  the human gate is still reached — it is **not** a real adversarial review, and
-  a `survived`/`parked` record must not be read as "an adversary tried and
-  failed to break this". A real deployment must inject a `red_team_fn` that runs
-  the heterogeneous, sandboxed adversary (`run_red_team`).
-- **Temporal path only.** The scan runs today only inside the Temporal workflow.
-  A trigger endpoint and a non-Temporal worker path arrive in a later task
-  (Red-Team trigger endpoint + non-Temporal worker path, Task 20).
+- **Parked-pass when no adversary is wired.** The default `red_team_fn` on both
+  spines (`forge_workflow.red_team_gate.parked_pass_verdict`, which the Temporal
+  activity's `_default_red_team` and the API's `get_red_team_fn` default to)
+  records a **parked-pass**: `verdict=survived`, `kind=parked`,
+  `evidence={"parked": true, "reason": "no adversary model/sandbox wired"}`.
+  This is a *park-don't-fake* stand-in so the spine runs and the human gate is
+  still reached — it is **not** a real adversarial review, and a
+  `survived`/`parked` record must not be read as "an adversary tried and failed
+  to break this". A real deployment must inject a `red_team_fn` that runs the
+  heterogeneous, sandboxed adversary (`run_red_team`).
 
 ---
 
diff --git a/packages/workflow-engine/forge_workflow/red_team_gate.py b/packages/workflow-engine/forge_workflow/red_team_gate.py
new file mode 100644
index 00000000..50d3edae
--- /dev/null
+++ b/packages/workflow-engine/forge_workflow/red_team_gate.py
@@ -0,0 +1,204 @@
+"""Engine-agnostic Red-Team Gate verdict building + recording (V1/V2 parity).
+
+The Red-Team Gate's verdict shape was born inside the Temporal (V2) activity
+layer (``temporal/activities.py``); this module EXTRACTS it so the V1
+(Postgres-FSM) path mints the identical contract instead of copying it:
+
+* :class:`RedTeamInput` / :class:`RedTeamResult` + the two verdict constants —
+  the pure gate payloads, moved here from ``temporal/payloads.py`` (which
+  re-exports them unchanged, so every Temporal import path is untouched);
+* :func:`parked_pass_verdict` — the explicit park-don't-fake default: with no
+  adversary model/sandbox wired the verdict is ``survived``/``kind="parked"``
+  with evidence saying so plainly. It is **never** disguised as a real
+  adversarial pass;
+* :func:`evaluate_red_team` — run the configured adversary when one is wired,
+  the parked-pass otherwise (the Temporal activity's ``_default_red_team``
+  delegates here);
+* :func:`ensure_red_team_verdict` / :func:`run_and_record_red_team` — the
+  session-in recorders the V1 gate path and the trigger endpoint call: evaluate,
+  then append the verdict to the append-only ``red_team_record`` table via
+  :func:`forge_db.redteam.record_red_team_verdict` (which chains the
+  ``redteam.survived`` audit event on a survive).
+
+Module-level imports stay pure (dataclasses only): ``temporal/payloads.py``
+imports this module inside the workflow determinism sandbox, so the DB pieces
+are imported lazily inside the recorder functions (the ``store.py`` precedent).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Session
+
+    from forge_db.models.red_team import RedTeamRecord
+
+__all__ = [
+    "REDTEAM_BLOCKED",
+    "REDTEAM_SURVIVED",
+    "RedTeamFn",
+    "RedTeamInput",
+    "RedTeamResult",
+    "ensure_red_team_verdict",
+    "evaluate_red_team",
+    "parked_pass_verdict",
+    "run_and_record_red_team",
+]
+
+#: The two terminal verdicts of the Red-Team Gate (mirror
+#: ``forge_db.models.red_team.VERDICT_*`` without importing the DB into the
+#: workflow determinism sandbox).
+REDTEAM_BLOCKED = "blocked"
+REDTEAM_SURVIVED = "survived"
+
+
+@dataclass
+class RedTeamInput:
+    """Argument to a red-team scan (the ``forge.run_red_team_scan`` activity's
+    payload, shared verbatim by the V1 gate path).
+
+    The adversary attacks the candidate spec/diff for ``workflow_run_id`` before
+    the human implementation gate; ``coder_model`` is the model that produced the
+    change, so the adversary can be routed onto a HETEROGENEOUS one.
+    """
+
+    workflow_run_id: uuid.UUID
+    workspace_id: uuid.UUID
+    task_id: uuid.UUID
+    phase: str = "spec"  # the gate the scan runs before (spec | pr)
+    coder_model: str | None = None
+    idempotency_key: str = ""
+
+
+@dataclass
+class RedTeamResult:
+    """Verdict of an adversarial scan.
+
+    ``verdict`` is :data:`REDTEAM_BLOCKED` (the adversary produced a failing test
+    or a structured spec-violation) or :data:`REDTEAM_SURVIVED` (it could not).
+    ``kind`` names the attack class (``failing_test`` / ``spec_violation`` /
+    ``parked``); ``evidence`` carries the structured result. Both models are
+    recorded so the survive is a truthful, heterogeneous-review provenance fact.
+    """
+
+    verdict: str = REDTEAM_SURVIVED
+    kind: str = "parked"
+    evidence: dict[str, Any] = field(default_factory=dict)
+    adversary_model: str | None = None
+    coder_model: str | None = None
+
+    @property
+    def blocked(self) -> bool:
+        return self.verdict == REDTEAM_BLOCKED
+
+
+#: An adversary harness: scan the candidate for ``RedTeamInput`` and return the
+#: verdict (real wiring runs the heterogeneous, sandboxed ``run_red_team``).
+RedTeamFn = Callable[[RedTeamInput], RedTeamResult]
+
+
+def parked_pass_verdict() -> RedTeamResult:
+    """The explicit park-don't-fake verdict used when no adversary is wired.
+
+    The evidence states plainly that no adversary model/sandbox was configured —
+    a ``survived``/``parked`` record must never be read as "an adversary tried
+    and failed to break this".
+    """
+    return RedTeamResult(
+        verdict=REDTEAM_SURVIVED,
+        kind="parked",
+        evidence={"parked": True, "reason": "no adversary model/sandbox wired"},
+    )
+
+
+def evaluate_red_team(inp: RedTeamInput, red_team_fn: RedTeamFn | None = None) -> RedTeamResult:
+    """Build the gate verdict: the configured adversary when wired, the explicit
+    parked-pass otherwise. Both engine spines call exactly this."""
+    if red_team_fn is not None:
+        return red_team_fn(inp)
+    return parked_pass_verdict()
+
+
+def run_and_record_red_team(
+    session: Session,
+    workspace_id: uuid.UUID,
+    *,
+    workflow_run_id: uuid.UUID,
+    task_id: uuid.UUID,
+    phase: str = "spec",
+    coder_model: str | None = None,
+    red_team_fn: RedTeamFn | None = None,
+    actor_id: uuid.UUID | None = None,
+) -> RedTeamRecord:
+    """Evaluate the gate and APPEND the verdict row (+ ``redteam.survived``
+    audit event on a survive) on the caller's transaction.
+
+    Always records a fresh scan — the explicit-trigger semantics (a ``blocked``
+    scan followed by a re-triggered ``survived`` one builds the history the
+    read surface documents). The caller commits.
+    """
+    from forge_db.redteam import record_red_team_verdict
+
+    result = evaluate_red_team(
+        RedTeamInput(
+            workflow_run_id=workflow_run_id,
+            workspace_id=workspace_id,
+            task_id=task_id,
+            phase=phase,
+            coder_model=coder_model,
+            idempotency_key=f"{workflow_run_id}:red_team:{phase}",
+        ),
+        red_team_fn,
+    )
+    row, _ = record_red_team_verdict(
+        session,
+        workspace_id,
+        verdict=result.verdict,
+        kind=result.kind,
+        evidence=result.evidence,
+        adversary_model=result.adversary_model,
+        coder_model=result.coder_model,
+        workflow_run_id=workflow_run_id,
+        actor_id=actor_id,
+    )
+    return row
+
+
+def ensure_red_team_verdict(
+    session: Session,
+    workspace_id: uuid.UUID,
+    *,
+    workflow_run_id: uuid.UUID,
+    task_id: uuid.UUID,
+    phase: str = "spec",
+    coder_model: str | None = None,
+    red_team_fn: RedTeamFn | None = None,
+    actor_id: uuid.UUID | None = None,
+) -> tuple[RedTeamRecord, bool]:
+    """Idempotently mint the gate verdict for a run: evaluate + record only when
+    the run has no scan yet; otherwise return the newest existing record.
+
+    Mirrors the Temporal spine's once-per-run scan (a block -> changes ->
+    resubmit loop re-enters the gate without rescanning). Returns
+    ``(record, created)``. The caller commits.
+    """
+    from forge_db.redteam import RedTeamRepository
+
+    existing = RedTeamRepository(session).get_by_run(workspace_id, workflow_run_id)
+    if existing:
+        return existing[0], False
+    row = run_and_record_red_team(
+        session,
+        workspace_id,
+        workflow_run_id=workflow_run_id,
+        task_id=task_id,
+        phase=phase,
+        coder_model=coder_model,
+        red_team_fn=red_team_fn,
+        actor_id=actor_id,
+    )
+    return row, True
diff --git a/packages/workflow-engine/forge_workflow/temporal/activities.py b/packages/workflow-engine/forge_workflow/temporal/activities.py
index f35953ff..8ab784ac 100644
--- a/packages/workflow-engine/forge_workflow/temporal/activities.py
+++ b/packages/workflow-engine/forge_workflow/temporal/activities.py
@@ -22,9 +22,9 @@
 from temporalio import activity
 
 from forge_contracts import RunStatus, WorkflowRun, WorkflowState
+from forge_workflow.red_team_gate import evaluate_red_team
 from forge_workflow.store import InMemoryWorkflowStore, WorkflowStore
 from forge_workflow.temporal.payloads import (
-    REDTEAM_SURVIVED,
     AgentRunResultDTO,
     ApprovalInput,
     ChecksResult,
@@ -123,16 +123,13 @@ def _default_approval(_: ApprovalInput) -> uuid.UUID:
     return uuid.uuid4()
 
 
-def _default_red_team(_: RedTeamInput) -> RedTeamResult:
+def _default_red_team(inp: RedTeamInput) -> RedTeamResult:
     # No adversary model / sandbox wired (park-don't-fake): the scan is a
     # parked-pass so the durable spine runs and the human gate is reached
     # unchanged. A real deployment injects a red_team_fn that runs a
-    # heterogeneous adversary against the candidate in a sandbox.
-    return RedTeamResult(
-        verdict=REDTEAM_SURVIVED,
-        kind="parked",
-        evidence={"parked": True, "reason": "no adversary model/sandbox wired"},
-    )
+    # heterogeneous adversary against the candidate in a sandbox. The verdict
+    # construction is the shared, engine-agnostic helper (V1 mints the same).
+    return evaluate_red_team(inp, red_team_fn=None)
 
 
 class WorkflowActivities:
diff --git a/packages/workflow-engine/forge_workflow/temporal/payloads.py b/packages/workflow-engine/forge_workflow/temporal/payloads.py
index eb7ca095..06fce1d9 100644
--- a/packages/workflow-engine/forge_workflow/temporal/payloads.py
+++ b/packages/workflow-engine/forge_workflow/temporal/payloads.py
@@ -18,6 +18,16 @@
 
 from forge_contracts import WorkflowState
 
+# The Red-Team gate payloads + verdict constants moved to the engine-agnostic
+# ``forge_workflow.red_team_gate`` (Task 20 — V1 gate parity); re-exported here
+# unchanged so every Temporal import path keeps working byte-identically.
+from forge_workflow.red_team_gate import (
+    REDTEAM_BLOCKED,
+    REDTEAM_SURVIVED,
+    RedTeamInput,
+    RedTeamResult,
+)
+
 # -- canonical human/agent gate event tokens (subset of the DSL vocabulary) -- #
 EVENT_SPEC_APPROVED = "spec_approved_by_human"
 EVENT_SPEC_CHANGES = "spec_changes_requested"
@@ -182,50 +192,8 @@ class ApprovalInput:
     idempotency_key: str = ""
 
 
-#: The two terminal verdicts of the Red-Team Gate (mirror
-#: ``forge_db.models.red_team.VERDICT_*`` without importing the DB into the
-#: workflow determinism sandbox).
-REDTEAM_BLOCKED = "blocked"
-REDTEAM_SURVIVED = "survived"
-
-
-@dataclass
-class RedTeamInput:
-    """Argument to the ``forge.run_red_team_scan`` activity.
-
-    The adversary attacks the candidate spec/diff for ``workflow_run_id`` before
-    the human implementation gate; ``coder_model`` is the model that produced the
-    change, so the adversary can be routed onto a HETEROGENEOUS one.
-    """
-
-    workflow_run_id: uuid.UUID
-    workspace_id: uuid.UUID
-    task_id: uuid.UUID
-    phase: str = "spec"  # the gate the scan runs before (spec | pr)
-    coder_model: str | None = None
-    idempotency_key: str = ""
-
-
-@dataclass
-class RedTeamResult:
-    """Verdict of an adversarial scan.
-
-    ``verdict`` is :data:`REDTEAM_BLOCKED` (the adversary produced a failing test
-    or a structured spec-violation) or :data:`REDTEAM_SURVIVED` (it could not).
-    ``kind`` names the attack class (``failing_test`` / ``spec_violation`` /
-    ``parked``); ``evidence`` carries the structured result. Both models are
-    recorded so the survive is a truthful, heterogeneous-review provenance fact.
-    """
-
-    verdict: str = REDTEAM_SURVIVED
-    kind: str = "parked"
-    evidence: dict[str, Any] = field(default_factory=dict)
-    adversary_model: str | None = None
-    coder_model: str | None = None
-
-    @property
-    def blocked(self) -> bool:
-        return self.verdict == REDTEAM_BLOCKED
+# (RedTeamInput / RedTeamResult / REDTEAM_* are re-exported from the
+# engine-agnostic ``forge_workflow.red_team_gate`` — see the import block.)
 
 
 @dataclass
diff --git a/packages/workflow-engine/tests/test_red_team_v1_gate.py b/packages/workflow-engine/tests/test_red_team_v1_gate.py
new file mode 100644
index 00000000..4b777de6
--- /dev/null
+++ b/packages/workflow-engine/tests/test_red_team_v1_gate.py
@@ -0,0 +1,198 @@
+"""V1/V2 parity for Red-Team Gate verdict building (Task 20).
+
+``forge_workflow.red_team_gate`` is the single source of the gate's verdict
+shape for BOTH spines: the Temporal activity's default parked-pass delegates to
+it (byte-identical), and the V1 (FSM) path evaluates + persists through
+``ensure_red_team_verdict`` / ``run_and_record_red_team`` against the
+append-only ``red_team_record`` table (hermetic SQLite here, mirroring
+``packages/db/tests/test_red_team_models.py``).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterator
+
+import pytest
+from sqlalchemy import create_engine, select
+from sqlalchemy.orm import Session
+
+from forge_db.base import Base
+from forge_db.models import Project, Task, WorkflowRun, Workspace
+from forge_db.models.audit import AuditLog
+from forge_db.redteam import REDTEAM_SURVIVED_ACTION, RedTeamRepository
+from forge_workflow.red_team_gate import (
+    REDTEAM_BLOCKED,
+    REDTEAM_SURVIVED,
+    RedTeamInput,
+    RedTeamResult,
+    ensure_red_team_verdict,
+    evaluate_red_team,
+    parked_pass_verdict,
+    run_and_record_red_team,
+)
+
+
+@pytest.fixture
+def sqlite_session() -> Iterator[Session]:
+    engine = create_engine("sqlite://")
+    Base.metadata.create_all(engine)
+    try:
+        with Session(engine) as session:
+            yield session
+    finally:
+        Base.metadata.drop_all(engine)
+        engine.dispose()
+
+
+def _seed(session: Session) -> tuple[uuid.UUID, uuid.UUID, uuid.UUID]:
+    """Seed workspace -> project -> task -> workflow_run; return (ws, task, run) ids."""
+    ws = Workspace(name="Acme", slug=f"acme-{uuid.uuid4().hex[:8]}")
+    session.add(ws)
+    session.flush()
+    project = Project(workspace_id=ws.id, name="Core", key=f"C{uuid.uuid4().hex[:4]}")
+    session.add(project)
+    session.flush()
+    task = Task(
+        workspace_id=ws.id,
+        project_id=project.id,
+        key=f"TASK-{uuid.uuid4().hex[:6]}",
+        title="red-team task",
+    )
+    session.add(task)
+    session.flush()
+    run = WorkflowRun(workspace_id=ws.id, task_id=task.id)
+    session.add(run)
+    session.flush()
+    return ws.id, task.id, run.id
+
+
+def _inp(ws: uuid.UUID, task: uuid.UUID, run: uuid.UUID) -> RedTeamInput:
+    return RedTeamInput(
+        workflow_run_id=run,
+        workspace_id=ws,
+        task_id=task,
+        phase="spec",
+        idempotency_key=f"{run}:red_team:spec",
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Extraction parity (the Temporal default must be byte-identical)              #
+# --------------------------------------------------------------------------- #
+
+
+def test_parked_pass_shape_matches_temporal_default() -> None:
+    """The shared parked-pass IS the Temporal activity's default verdict."""
+    from forge_workflow.temporal.activities import _default_red_team
+
+    inp = _inp(uuid.uuid4(), uuid.uuid4(), uuid.uuid4())
+    shared = evaluate_red_team(inp)
+    temporal = _default_red_team(inp)
+
+    assert shared == temporal
+    assert shared.verdict == REDTEAM_SURVIVED
+    assert shared.kind == "parked"
+    assert shared.evidence == {"parked": True, "reason": "no adversary model/sandbox wired"}
+    assert shared.adversary_model is None
+    assert shared.coder_model is None
+    assert shared == parked_pass_verdict()
+
+
+def test_payloads_reexport_the_same_objects() -> None:
+    """`temporal/payloads` re-exports the extracted types unchanged (same objects),
+    so every existing Temporal import path keeps working byte-identically."""
+    from forge_workflow import red_team_gate
+    from forge_workflow.temporal import payloads
+
+    assert payloads.RedTeamInput is red_team_gate.RedTeamInput
+    assert payloads.RedTeamResult is red_team_gate.RedTeamResult
+    assert payloads.REDTEAM_BLOCKED is red_team_gate.REDTEAM_BLOCKED
+    assert payloads.REDTEAM_SURVIVED is red_team_gate.REDTEAM_SURVIVED
+
+
+def test_configured_adversary_fn_is_invoked() -> None:
+    """When an adversary is configured, the helper runs IT — never the parked-pass."""
+    calls: list[RedTeamInput] = []
+
+    def block(inp: RedTeamInput) -> RedTeamResult:
+        calls.append(inp)
+        return RedTeamResult(
+            verdict=REDTEAM_BLOCKED,
+            kind="failing_test",
+            evidence={"stdout": "AssertionError"},
+            adversary_model="gpt-5-heavy",
+            coder_model="claude-sonnet-4",
+        )
+
+    inp = _inp(uuid.uuid4(), uuid.uuid4(), uuid.uuid4())
+    result = evaluate_red_team(inp, red_team_fn=block)
+
+    assert calls == [inp]
+    assert result.blocked
+    assert result.kind == "failing_test"
+
+
+# --------------------------------------------------------------------------- #
+# V1 gate persistence (ensure/run_and_record over the append-only table)       #
+# --------------------------------------------------------------------------- #
+
+
+def test_ensure_persists_parked_verdict_once(sqlite_session: Session) -> None:
+    """A V1 run reaching its gate persists ONE honest parked verdict row."""
+    ws, task, run = _seed(sqlite_session)
+
+    row, created = ensure_red_team_verdict(sqlite_session, ws, workflow_run_id=run, task_id=task)
+    assert created is True
+    assert row.verdict == REDTEAM_SURVIVED
+    assert row.kind == "parked"
+    assert row.evidence == {"parked": True, "reason": "no adversary model/sandbox wired"}
+    assert row.adversary_model is None
+    assert row.coder_model is None
+    assert row.workflow_run_id == run
+
+    # Idempotent: the gate re-entered (block -> changes -> resubmit) does not rescan.
+    again, created_again = ensure_red_team_verdict(
+        sqlite_session, ws, workflow_run_id=run, task_id=task
+    )
+    assert created_again is False
+    assert again.id == row.id
+    assert len(RedTeamRepository(sqlite_session).get_by_run(ws, run)) == 1
+
+
+def test_ensure_survived_chains_the_audit_event(sqlite_session: Session) -> None:
+    """The parked survive still chains the ``redteam.survived`` audit event
+    (recorded honestly as kind=parked in its details)."""
+    ws, task, run = _seed(sqlite_session)
+    row, _ = ensure_red_team_verdict(sqlite_session, ws, workflow_run_id=run, task_id=task)
+
+    audit = sqlite_session.scalars(
+        select(AuditLog).where(AuditLog.action == REDTEAM_SURVIVED_ACTION)
+    ).all()
+    assert len(audit) == 1
+    assert audit[0].detail_ref == {"table": "red_team_record", "id": str(row.id)}
+    assert audit[0].details["kind"] == "parked"
+
+
+def test_run_and_record_appends_a_new_scan(sqlite_session: Session) -> None:
+    """An explicit trigger appends (block -> re-trigger -> survive history)."""
+    ws, task, run = _seed(sqlite_session)
+    ensure_red_team_verdict(sqlite_session, ws, workflow_run_id=run, task_id=task)
+
+    def block(_: RedTeamInput) -> RedTeamResult:
+        return RedTeamResult(
+            verdict=REDTEAM_BLOCKED,
+            kind="failing_test",
+            evidence={"stdout": "AssertionError"},
+            adversary_model="gpt-5-heavy",
+            coder_model="claude-sonnet-4",
+        )
+
+    row = run_and_record_red_team(
+        sqlite_session, ws, workflow_run_id=run, task_id=task, red_team_fn=block
+    )
+    assert row.verdict == REDTEAM_BLOCKED
+    rows = RedTeamRepository(sqlite_session).get_by_run(ws, run)
+    assert len(rows) == 2
+    verdicts = {r.verdict for r in rows}
+    assert verdicts == {REDTEAM_BLOCKED, REDTEAM_SURVIVED}

From 1b54cd95458509eb04fd70fe6399e0eba11ebeb4 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 05:52:08 +0200
Subject: [PATCH 43/47] fix(red-team): state spine persistence asymmetry
 honestly; loud mint guards

---
 apps/api/forge_api/routers/workflow.py        | 29 ++++++++++++--
 docs/trust-layer.md                           | 40 +++++++++++++++----
 .../forge_workflow/red_team_gate.py           |  5 +++
 3 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/apps/api/forge_api/routers/workflow.py b/apps/api/forge_api/routers/workflow.py
index fe837220..de7f574d 100644
--- a/apps/api/forge_api/routers/workflow.py
+++ b/apps/api/forge_api/routers/workflow.py
@@ -236,6 +236,22 @@ def _run_task_id(run: WorkflowRun) -> uuid.UUID:
     return run.task_id
 
 
+def _run_id(run: WorkflowRun) -> uuid.UUID:
+    """Narrow the contract's optional ``id`` (always set by ``start_run``).
+
+    Mirrors :func:`_run_task_id`: a run reaching the mint gate without an id
+    cannot be scanned or recorded (``ensure_red_team_verdict`` requires
+    ``workflow_run_id``) — fail loud (500) rather than silently skipping the
+    gate. Previously this case was a quiet ``if run.id is not None:`` skip.
+    """
+    if run.id is None:  # pragma: no cover — start_run always sets it
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="workflow run has no id; cannot red-team scan",
+        )
+    return run.id
+
+
 @router.post("/runs", response_model=WorkflowRun, status_code=status.HTTP_201_CREATED)
 def start_run(
     engine: EngineDep,
@@ -276,8 +292,14 @@ def transition(
     in ``spec_review`` — the human spec gate, exactly where the Temporal spine
     scans — mint the run's verdict once (idempotent across gate re-entries):
     the configured adversary when wired, an explicit parked-pass otherwise.
-    Failure to record is loud (500), never a silently skipped gate. The
-    Temporal engine is excluded: its workflow body owns the scan.
+    Failure to record is loud (500 via ``_run_id``/``_run_task_id``), never a
+    silently skipped gate. The Temporal engine is excluded: its workflow body
+    owns the scan. Recovery from a mint failure needs no special-casing: the
+    FSM transition itself has already landed (it is a separate store from this
+    mint), so the next transition that re-enters ``spec_review`` re-attempts
+    the mint (``ensure_red_team_verdict`` is idempotent on "no existing
+    record"); alternatively, ``POST /workflow/runs/{run_id}/red-team`` records
+    the verdict directly as a manual recovery path.
     """
     _require_owned(ownership, run_id, principal.workspace_id)
     with _workflow_errors():
@@ -286,12 +308,11 @@ def transition(
     if (
         isinstance(engine, WorkflowEngineImpl)
         and run.current_state == WorkflowState.SPEC_REVIEW.value
-        and run.id is not None
     ):
         ensure_red_team_verdict(
             session,
             principal.workspace_id,
-            workflow_run_id=run.id,
+            workflow_run_id=_run_id(run),
             task_id=_run_task_id(run),
             phase=_GATEABLE_STATES[run.current_state],
             red_team_fn=red_team_fn,
diff --git a/docs/trust-layer.md b/docs/trust-layer.md
index ad85caa8..34a80aae 100644
--- a/docs/trust-layer.md
+++ b/docs/trust-layer.md
@@ -250,15 +250,23 @@ through the shared `forge_workflow.red_team_gate` helper:
   spec is drafted and clarified but **before** the human spec-approval gate, the
   workflow runs a red-team scan. A `blocked` verdict routes the change back for
   changes (→ clarification → spec review) so a human must address the finding; a
-  `survived` verdict proceeds unchanged and the recorder writes the
-  `RedTeamRecord` plus a `redteam.survived` audit event.
+  `survived` verdict proceeds unchanged, and — **only if the wired `red_team_fn`
+  itself records** — a recorder writes the `RedTeamRecord` plus a
+  `redteam.survived` audit event. The `forge.run_red_team_scan` activity
+  (`packages/workflow-engine/forge_workflow/temporal/activities.py`) returns
+  exactly `self._red_team_fn(inp)` — the pure verdict that drives the
+  workflow's routing decision — and persists nothing itself; whether anything
+  lands in `red_team_record` depends entirely on what `red_team_fn` does. See
+  **Current limitations** for what the stock (no-adversary-wired) default
+  actually persists.
 - **V1 (Postgres FSM)** — the FSM is a plain transition graph with no gate
   hooks, and its one production driver is the workflow router: when a
   transition lands a V1 run in `spec_review` (the human spec gate — the same
-  position the Temporal spine scans), the handler mints the run's verdict once
-  via `ensure_red_team_verdict` (idempotent across gate re-entries: a block →
-  changes → resubmit loop does not rescan) and appends it to `red_team_record`
-  with the same `redteam.survived` audit chaining.
+  position the Temporal spine scans), the handler **unconditionally** mints the
+  run's verdict once via `ensure_red_team_verdict` (idempotent across gate
+  re-entries: a block → changes → resubmit loop does not rescan) and appends it
+  to `red_team_record` with the same `redteam.survived` audit chaining — no
+  extra step or injected recorder required.
 
 The verdict is surfaced at `GET /workflow/runs/{run_id}/red-team`
 (`apps/api/forge_api/routers/workflow.py`), returning the latest verdict plus the
@@ -281,13 +289,31 @@ foreign runs (no existence leak).
 - **Parked-pass when no adversary is wired.** The default `red_team_fn` on both
   spines (`forge_workflow.red_team_gate.parked_pass_verdict`, which the Temporal
   activity's `_default_red_team` and the API's `get_red_team_fn` default to)
-  records a **parked-pass**: `verdict=survived`, `kind=parked`,
+  builds a **parked-pass** verdict: `verdict=survived`, `kind=parked`,
   `evidence={"parked": true, "reason": "no adversary model/sandbox wired"}`.
   This is a *park-don't-fake* stand-in so the spine runs and the human gate is
   still reached — it is **not** a real adversarial review, and a
   `survived`/`parked` record must not be read as "an adversary tried and failed
   to break this". A real deployment must inject a `red_team_fn` that runs the
   heterogeneous, sandboxed adversary (`run_red_team`).
+- **The default parked-pass is persisted on V1, NOT on Temporal — the two
+  spines are asymmetric here.** The V1 router transition handler always calls
+  `ensure_red_team_verdict`, which evaluates *and* appends to `red_team_record`
+  — so a V1 run reaching `spec_review` under the stock (no-adversary) default
+  always has a persisted `survived`/`parked` row, and `GET
+  /workflow/runs/{run_id}/red-team` shows it. The Temporal spine's
+  `run_red_team_scan` activity only returns the pure verdict from
+  `_default_red_team`; the worker's activity wiring
+  (`apps/worker/forge_worker/temporal_main.py`) passes no `red_team_fn`, so
+  nothing records it to `red_team_record`. The parked verdict still durably
+  drives the workflow's routing decision (it is real Temporal workflow
+  history), but an identical Temporal run's `GET
+  /workflow/runs/{run_id}/red-team` reads `latest=None` with an empty history —
+  not because no scan happened, but because the default scan was never told to
+  record. To put a Temporal run's verdict on record, either call `POST
+  /workflow/runs/{run_id}/red-team` (which always evaluates *and* appends via
+  `run_and_record_red_team`, on either engine) or construct
+  `WorkflowActivities` with a `red_team_fn` that records as well as evaluates.
 
 ---
 
diff --git a/packages/workflow-engine/forge_workflow/red_team_gate.py b/packages/workflow-engine/forge_workflow/red_team_gate.py
index 50d3edae..ee498c2e 100644
--- a/packages/workflow-engine/forge_workflow/red_team_gate.py
+++ b/packages/workflow-engine/forge_workflow/red_team_gate.py
@@ -188,6 +188,11 @@ def ensure_red_team_verdict(
     """
     from forge_db.redteam import RedTeamRepository
 
+    # Query-first idempotency is best-effort, not a hard guarantee: two
+    # concurrent callers can both see "no existing scan" and both record.
+    # Worst case under a race is a duplicate honest `parked`/`survived` row in
+    # the append-only history (extra noise on the GET's `records` list) — it
+    # is never a verdict flip, and never fabricates a block or a survive.
     existing = RedTeamRepository(session).get_by_run(workspace_id, workflow_run_id)
     if existing:
         return existing[0], False

From 779c3828d71157a3a10a0a12ff2eb1eb7e05d234 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 06:14:12 +0200
Subject: [PATCH 44/47] feat(self-eval): settings panel for suite, baseline,
 runs, and gate status

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/api/forge_api/routers/ao_settings.py     | 127 +++++++
 apps/api/forge_api/schemas/ao_settings.py     |  55 ++-
 apps/api/forge_api/services/self_eval_gate.py |   3 +-
 .../forge_api/services/self_eval_service.py   |  38 ++
 apps/api/tests/test_ao_settings_router.py     | 212 +++++++++++-
 .../src/app/(board)/settings/models/page.tsx  |  12 +-
 .../self-eval/self-eval-panel.test.tsx        | 197 +++++++++++
 .../components/self-eval/self-eval-panel.tsx  | 327 ++++++++++++++++++
 apps/web/src/lib/api/ao-settings.ts           |  29 ++
 apps/web/src/lib/api/client.ts                |  18 +
 apps/web/src/lib/api/types.ts                 |  43 +++
 docs/trust-layer.md                           |  37 +-
 12 files changed, 1084 insertions(+), 14 deletions(-)
 create mode 100644 apps/web/src/components/self-eval/self-eval-panel.test.tsx
 create mode 100644 apps/web/src/components/self-eval/self-eval-panel.tsx

diff --git a/apps/api/forge_api/routers/ao_settings.py b/apps/api/forge_api/routers/ao_settings.py
index dabc7bef..9b59ee7c 100644
--- a/apps/api/forge_api/routers/ao_settings.py
+++ b/apps/api/forge_api/routers/ao_settings.py
@@ -11,6 +11,10 @@
 * ``PUT  /ao/settings``             — partially update those (admin).
 * ``POST /ao/routing-preview``      — what tier/model/strategy a sample task
   would get, given this workspace's current settings.
+* ``GET  /ao/self-eval/status``     — the Self-Eval Gate facts: enforcement
+  flag, the workspace's private suite, and the recorded baseline.
+* ``POST /ao/self-eval/runs``       — enqueue the worker-owned
+  ``forge.self_eval.run`` task for this workspace (admin, 202).
 
 Reads are ``Permission.READ``-gated (a viewer may inspect its own workspace's
 AO configuration); every mutation is ``Permission.ADMIN``-gated, matching the
@@ -24,6 +28,8 @@
 from typing import Annotated, Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
+from sqlalchemy import select
+from sqlalchemy.orm import Session
 
 from forge_api.auth.rbac import Permission
 from forge_api.deps import DbSession, Principal, get_current_principal
@@ -36,7 +42,12 @@
     RoleConfigUpsertRequest,
     RoutingPreviewRequest,
     RoutingPreviewResponse,
+    SelfEvalBaselineOut,
+    SelfEvalRunAccepted,
+    SelfEvalStatusOut,
+    SelfEvalSuiteOut,
 )
+from forge_api.services import self_eval_service
 from forge_api.services.ao_settings_service import (
     AoSettingsService,
     EffectiveAoSettings,
@@ -47,6 +58,7 @@
 from forge_contracts.audit import AuditEvent
 from forge_contracts.orchestration_config import AgentRole, EffectiveRoleConfig
 from forge_db.ao_settings import SqlAoSettingsStore
+from forge_db.models.benchmark import BenchmarkSuite, SelfEvalBaseline
 from forge_db.role_config import SqlRoleConfigStore
 from forge_eval.sweval import SelfEvalGate, SelfEvalRegressionError
 
@@ -315,3 +327,118 @@ def routing_preview(
         medior_max=preview.medior_max,
         auto_route_enabled=preview.auto_route_enabled,
     )
+
+
+# --------------------------------------------------------------------------- #
+# Self-Eval Gate: status read + run trigger (Phase A)                          #
+# --------------------------------------------------------------------------- #
+
+
+def _private_suite(
+    session: Session, workspace_id: uuid.UUID, *, published_only: bool = False
+) -> BenchmarkSuite | None:
+    """The workspace's private Self-Eval suite (published preferred), or ``None``."""
+    stmt = select(BenchmarkSuite).where(
+        BenchmarkSuite.workspace_id == workspace_id,
+        BenchmarkSuite.private.is_(True),
+    )
+    if published_only:
+        stmt = stmt.where(BenchmarkSuite.published.is_(True))
+    stmt = stmt.order_by(BenchmarkSuite.published.desc(), BenchmarkSuite.version.desc())
+    return session.scalars(stmt).first()
+
+
+def _effective_config_snapshot(session: Session, workspace_id: uuid.UUID) -> dict[str, Any]:
+    """The redacted effective AO settings a self-eval run scores (no secrets)."""
+    effective = _service(session).get_settings(workspace_id)
+    return {
+        "scope": "ao.settings",
+        "auto_route": effective.auto_route,
+        "tier_model_overrides": effective.tier_model_overrides,
+        "junior_max": effective.junior_max,
+        "medior_max": effective.medior_max,
+    }
+
+
+@router.get(
+    "/self-eval/status",
+    summary="Self-Eval Gate facts: enforcement flag, private suite, recorded baseline.",
+)
+def self_eval_status(principal: ReaderDep, session: DbSession) -> SelfEvalStatusOut:
+    suite = _private_suite(session, principal.workspace_id)
+    baseline = session.scalars(
+        select(SelfEvalBaseline)
+        .where(SelfEvalBaseline.workspace_id == principal.workspace_id)
+        .order_by(SelfEvalBaseline.updated_at.desc())
+    ).first()
+    return SelfEvalStatusOut(
+        workspace_id=principal.workspace_id,
+        enforced=get_app_settings().self_eval_enforce,
+        suite=SelfEvalSuiteOut(
+            id=suite.id,
+            slug=suite.slug,
+            version=suite.version,
+            title=suite.title,
+            task_count=suite.task_count,
+            repo_id=suite.repo_id,
+            published=suite.published,
+        )
+        if suite is not None
+        else None,
+        baseline=SelfEvalBaselineOut(
+            benchmark_suite_id=baseline.benchmark_suite_id,
+            baseline_rate=baseline.baseline_rate,
+            resolved=baseline.resolved,
+            total=baseline.total,
+            recorded_at=baseline.updated_at,
+        )
+        if baseline is not None
+        else None,
+    )
+
+
+@router.post(
+    "/self-eval/runs",
+    status_code=status.HTTP_202_ACCEPTED,
+    summary="Enqueue the worker-owned self-eval run for this workspace (admin).",
+)
+def request_self_eval_run(principal: AdminDep, session: DbSession) -> SelfEvalRunAccepted:
+    """Queue ``forge.self_eval.run`` over the workspace's private suite.
+
+    The run itself stays in the worker (minutes-long, agent-driven, A4) — this
+    endpoint only enqueues it with the workspace's current effective AO config
+    snapshot. 409 when no published private suite exists: there is nothing the
+    worker could score, so we refuse rather than queue a guaranteed no-op.
+    """
+    suite = _private_suite(session, principal.workspace_id, published_only=True)
+    if suite is None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "error": "no_private_suite",
+                "message": (
+                    "No published private Self-Eval suite exists for this "
+                    "workspace; one is minted from merged PRs by the "
+                    "forge.self_eval.mint worker task."
+                ),
+            },
+        )
+    self_eval_service.enqueue_self_eval_run(
+        principal.workspace_id,
+        _effective_config_snapshot(session, principal.workspace_id),
+        recorded_by=principal.user_id,
+    )
+    _audit(
+        session,
+        principal,
+        "ao.self_eval.run_requested",
+        result="success",
+        severity="info",
+        details={"benchmark_suite_id": str(suite.id)},
+    )
+    session.commit()
+    return SelfEvalRunAccepted(
+        task=self_eval_service.SELF_EVAL_RUN_TASK,
+        workspace_id=principal.workspace_id,
+        benchmark_suite_id=suite.id,
+    )
diff --git a/apps/api/forge_api/schemas/ao_settings.py b/apps/api/forge_api/schemas/ao_settings.py
index 895cddaf..6b16732c 100644
--- a/apps/api/forge_api/schemas/ao_settings.py
+++ b/apps/api/forge_api/schemas/ao_settings.py
@@ -1,11 +1,13 @@
 """Request/response schemas for the Adaptive Orchestration settings API
 (``ao-settings-api``): per-role model+effort config, the workspace-wide
-``tier -> model`` map / complexity thresholds / auto-route toggle, and a
-routing-preview endpoint.
+``tier -> model`` map / complexity thresholds / auto-route toggle, a
+routing-preview endpoint, and the Self-Eval Gate status/run surface.
 """
 
 from __future__ import annotations
 
+from datetime import datetime
+from typing import Literal
 from uuid import UUID
 
 from pydantic import BaseModel, Field
@@ -22,6 +24,10 @@
     "RoleConfigUpsertRequest",
     "RoutingPreviewRequest",
     "RoutingPreviewResponse",
+    "SelfEvalBaselineOut",
+    "SelfEvalRunAccepted",
+    "SelfEvalStatusOut",
+    "SelfEvalSuiteOut",
 ]
 
 
@@ -110,3 +116,48 @@ class RoutingPreviewResponse(BaseModel):
     junior_max: int
     medior_max: int
     auto_route_enabled: bool
+
+
+class SelfEvalSuiteOut(BaseModel):
+    """The workspace's private Self-Eval suite (case content is never exposed)."""
+
+    id: UUID
+    slug: str
+    version: str
+    title: str
+    task_count: int
+    repo_id: str | None
+    published: bool
+
+
+class SelfEvalBaselineOut(BaseModel):
+    """The frozen baseline the Self-Eval Gate blocks regressions against."""
+
+    benchmark_suite_id: UUID
+    baseline_rate: float
+    resolved: int
+    total: int
+    #: When the baseline row was last minted/refreshed by a scoring run.
+    recorded_at: datetime
+
+
+class SelfEvalStatusOut(BaseModel):
+    """Body for ``GET /ao/self-eval/status`` — raw facts, no derived verdicts.
+
+    ``suite``/``baseline`` are ``None`` on cold start; ``enforced`` mirrors the
+    ``self_eval_enforce`` app setting. The UI derives gate status from these.
+    """
+
+    workspace_id: UUID
+    enforced: bool
+    suite: SelfEvalSuiteOut | None
+    baseline: SelfEvalBaselineOut | None
+
+
+class SelfEvalRunAccepted(BaseModel):
+    """Body for ``POST /ao/self-eval/runs`` (202): the run is queued, not done."""
+
+    status: Literal["queued"] = "queued"
+    task: str
+    workspace_id: UUID
+    benchmark_suite_id: UUID
diff --git a/apps/api/forge_api/services/self_eval_gate.py b/apps/api/forge_api/services/self_eval_gate.py
index 975c339f..e5c56e86 100644
--- a/apps/api/forge_api/services/self_eval_gate.py
+++ b/apps/api/forge_api/services/self_eval_gate.py
@@ -13,7 +13,8 @@
 API gate has no fresh scorecard for the *proposed* config and no-ops, while the
 gate MECHANISM (baseline lookup, regression block, force override, audit) is
 fully wired and exercised in tests by injecting a runner. Establishing/refreshing
-a baseline is the worker-owned ``POST /ao/self-eval/runs`` path (A4).
+a baseline is the worker-owned ``forge.self_eval.run`` Celery task (A4), which
+``POST /ao/self-eval/runs`` enqueues.
 """
 
 from __future__ import annotations
diff --git a/apps/api/forge_api/services/self_eval_service.py b/apps/api/forge_api/services/self_eval_service.py
index b8c8e69a..61044ec4 100644
--- a/apps/api/forge_api/services/self_eval_service.py
+++ b/apps/api/forge_api/services/self_eval_service.py
@@ -11,9 +11,11 @@
 
 from __future__ import annotations
 
+import os
 import uuid
 from collections.abc import Mapping
 from dataclasses import dataclass
+from functools import lru_cache
 from typing import Any
 
 from sqlalchemy import select
@@ -21,6 +23,42 @@
 
 from forge_db.models.benchmark import SelfEvalBaseline
 
+#: Must match ``apps/worker/forge_worker/tasks/self_eval_run.py``'s task name —
+#: duplicated (not imported) because ``forge-api`` cannot depend on
+#: ``forge-worker`` (the dependency runs the other way); mirrors the
+#: ``PROCESS_WEBHOOK_TASK`` pattern in ``pm_service.py``.
+SELF_EVAL_RUN_TASK = "forge.self_eval.run"
+
+
+@lru_cache(maxsize=1)
+def _celery_app() -> object:  # pragma: no cover - prod seam
+    from celery import Celery
+
+    url = os.environ.get("FORGE_REDIS_URL", "redis://localhost:6379/0")
+    return Celery("forge-api-enqueue", broker=url, backend=url)
+
+
+def enqueue_self_eval_run(  # pragma: no cover - prod seam
+    workspace_id: uuid.UUID,
+    proposed_config: Mapping[str, Any],
+    *,
+    recorded_by: uuid.UUID | None = None,
+) -> None:
+    """Enqueue the worker-owned private-suite run (``forge.self_eval.run``).
+
+    The run itself stays in the worker (minutes-long, agent-driven); this is the
+    thin API->worker seam the settings panel's "run self-eval" action goes
+    through. ``proposed_config`` must already be redacted (no secrets).
+    """
+    _celery_app().send_task(  # type: ignore[attr-defined]
+        SELF_EVAL_RUN_TASK,
+        args=[
+            str(workspace_id),
+            dict(proposed_config),
+            str(recorded_by) if recorded_by else None,
+        ],
+    )
+
 
 @dataclass(frozen=True)
 class BaselineRecord:
diff --git a/apps/api/tests/test_ao_settings_router.py b/apps/api/tests/test_ao_settings_router.py
index bd095715..4c14bb53 100644
--- a/apps/api/tests/test_ao_settings_router.py
+++ b/apps/api/tests/test_ao_settings_router.py
@@ -3,9 +3,10 @@
 Real handlers over a real Postgres session (``pg_engine``, shared root
 fixture): per-role model+effort config (list/upsert/delete, workspace vs
 project override precedence, RBAC, workspace isolation), the workspace-wide
-settings (auto-route, tier-model overrides, complexity thresholds, RBAC), and
-the routing-preview endpoint (default sizing, custom thresholds, custom
-tier-model overrides, invalid provider).
+settings (auto-route, tier-model overrides, complexity thresholds, RBAC), the
+routing-preview endpoint (default sizing, custom thresholds, custom
+tier-model overrides, invalid provider), and the Self-Eval Gate surface
+(status read + the admin run trigger that enqueues ``forge.self_eval.run``).
 """
 
 from __future__ import annotations
@@ -16,14 +17,19 @@
 import pytest
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
+from sqlalchemy import select
 from sqlalchemy.orm import Session, sessionmaker
 
 from forge_api.db import get_db
 from forge_api.deps import Principal
 from forge_api.main import create_app
+from forge_api.routers import ao_settings as ao_module
+from forge_api.services import self_eval_service as self_eval_service_module
+from forge_api.settings import Settings
 from forge_contracts import UserRole
 from forge_db.base import Base
-from forge_db.models import Project, Workspace
+from forge_db.models import AuditLog, Project, User, Workspace
+from forge_db.models.benchmark import BenchmarkSuite, SelfEvalBaseline
 
 pytestmark = pytest.mark.usefixtures("pg_engine")
 
@@ -334,3 +340,201 @@ def test_routing_preview_rejects_invalid_provider(
         json={"kind": "doc", "priority": "low", "provider": "not-a-provider"},
     )
     assert resp.status_code == 422
+
+
+# --------------------------------------------------------------------------- #
+# Self-Eval Gate: status read + run trigger                                   #
+# --------------------------------------------------------------------------- #
+
+
+def _workspace_of(client: TestClient) -> uuid.UUID:
+    return uuid.UUID(client.get("/ao/settings").json()["workspace_id"])
+
+
+def _seed_private_suite(
+    factory: sessionmaker[Session], workspace_id: uuid.UUID, *, published: bool = True
+) -> uuid.UUID:
+    with factory() as session:
+        suite = BenchmarkSuite(
+            slug=f"self-eval-{uuid.uuid4().hex[:8]}",
+            version="1.0.0",
+            title="Private self-eval suite",
+            task_count=10,
+            content_hash="deadbeef",
+            frozen=True,
+            published=published,
+            workspace_id=workspace_id,
+            repo_id="github:acme/app",
+            private=True,
+        )
+        session.add(suite)
+        session.flush()
+        suite_id = suite.id
+        session.commit()
+    return suite_id
+
+
+def _seed_baseline(
+    factory: sessionmaker[Session], workspace_id: uuid.UUID, suite_id: uuid.UUID
+) -> None:
+    with factory() as session:
+        session.add(
+            SelfEvalBaseline(
+                workspace_id=workspace_id,
+                benchmark_suite_id=suite_id,
+                baseline_rate=0.8,
+                resolved=8,
+                total=10,
+                config={"scope": "ao.settings"},
+            )
+        )
+        session.commit()
+
+
+def test_self_eval_status_cold_start_is_honest_nulls(
+    client_for: Callable[[UserRole], TestClient],
+) -> None:
+    client = client_for(UserRole.VIEWER)
+    resp = client.get("/ao/self-eval/status")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["enforced"] is False
+    assert body["suite"] is None
+    assert body["baseline"] is None
+
+
+def test_self_eval_status_reports_suite_and_baseline(
+    client_for: Callable[[UserRole], TestClient], factory: sessionmaker[Session]
+) -> None:
+    client = client_for(UserRole.VIEWER)
+    workspace_id = _workspace_of(client)
+    suite_id = _seed_private_suite(factory, workspace_id)
+    _seed_baseline(factory, workspace_id, suite_id)
+
+    body = client.get("/ao/self-eval/status").json()
+    assert body["suite"]["id"] == str(suite_id)
+    assert body["suite"]["published"] is True
+    assert body["suite"]["repo_id"] == "github:acme/app"
+    assert body["baseline"]["benchmark_suite_id"] == str(suite_id)
+    assert body["baseline"]["baseline_rate"] == 0.8
+    assert (body["baseline"]["resolved"], body["baseline"]["total"]) == (8, 10)
+    assert body["baseline"]["recorded_at"]
+
+
+def test_self_eval_status_reflects_enforcement_flag(
+    client_for: Callable[[UserRole], TestClient], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(ao_module, "get_app_settings", lambda: Settings(self_eval_enforce=True))
+    client = client_for(UserRole.VIEWER)
+    assert client.get("/ao/self-eval/status").json()["enforced"] is True
+
+
+def test_self_eval_status_is_workspace_isolated(
+    factory: sessionmaker[Session], authenticate_app: Callable[..., FastAPI]
+) -> None:
+    ws_a = _seed_workspace(factory, name="A", slug=f"a-{uuid.uuid4().hex[:8]}")
+    ws_b = _seed_workspace(factory, name="B", slug=f"b-{uuid.uuid4().hex[:8]}")
+    suite_a = _seed_private_suite(factory, ws_a)
+    _seed_baseline(factory, ws_a, suite_a)
+
+    app = create_app()
+    authenticate_app(app, _principal(UserRole.VIEWER, ws_b))
+
+    def _get_db() -> Iterator[Session]:
+        with factory() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = _get_db
+    body = TestClient(app).get("/ao/self-eval/status").json()
+    assert body["suite"] is None
+    assert body["baseline"] is None
+
+
+def test_viewer_cannot_request_self_eval_run(
+    client_for: Callable[[UserRole], TestClient],
+) -> None:
+    client = client_for(UserRole.VIEWER)
+    assert client.post("/ao/self-eval/runs").status_code == 403
+
+
+def test_self_eval_run_without_private_suite_is_409(
+    client_for: Callable[[UserRole], TestClient],
+) -> None:
+    client = client_for(UserRole.ADMIN)
+    resp = client.post("/ao/self-eval/runs")
+    assert resp.status_code == 409
+    assert resp.json()["detail"]["error"] == "no_private_suite"
+
+
+def test_self_eval_run_unpublished_suite_is_409(
+    client_for: Callable[[UserRole], TestClient], factory: sessionmaker[Session]
+) -> None:
+    client = client_for(UserRole.ADMIN)
+    _seed_private_suite(factory, _workspace_of(client), published=False)
+    resp = client.post("/ao/self-eval/runs")
+    assert resp.status_code == 409
+    assert resp.json()["detail"]["error"] == "no_private_suite"
+
+
+def test_admin_self_eval_run_enqueues_worker_task_and_audits(
+    factory: sessionmaker[Session],
+    authenticate_app: Callable[..., FastAPI],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Self-contained client: the run-request audit row carries a real actor FK,
+    # so the principal must be a persisted user (unlike the shared client_for).
+    workspace_id = _seed_workspace(factory, name="Run", slug=f"run-{uuid.uuid4().hex[:8]}")
+    with factory() as session:
+        admin = User(workspace_id=workspace_id, email="admin@forge.local", role=UserRole.ADMIN)
+        session.add(admin)
+        session.flush()
+        user_id = admin.id
+        session.commit()
+
+    app = create_app()
+    principal = Principal(
+        user_id=user_id,
+        workspace_id=workspace_id,
+        role=UserRole.ADMIN,
+        email="admin@forge.local",
+        auth_method="test",
+        scopes=["*"],
+    )
+    authenticate_app(app, principal)
+
+    def _get_db() -> Iterator[Session]:
+        with factory() as session:
+            yield session
+
+    app.dependency_overrides[get_db] = _get_db
+    client = TestClient(app)
+    suite_id = _seed_private_suite(factory, workspace_id)
+
+    calls: list[tuple[tuple, dict]] = []
+    monkeypatch.setattr(
+        self_eval_service_module,
+        "enqueue_self_eval_run",
+        lambda *args, **kwargs: calls.append((args, kwargs)),
+    )
+
+    resp = client.post("/ao/self-eval/runs")
+    assert resp.status_code == 202
+    body = resp.json()
+    assert body["status"] == "queued"
+    assert body["task"] == "forge.self_eval.run"
+    assert body["benchmark_suite_id"] == str(suite_id)
+
+    assert len(calls) == 1
+    (ws_arg, config_arg), kwargs = calls[0]
+    assert ws_arg == workspace_id
+    assert config_arg["scope"] == "ao.settings"
+    assert "auto_route" in config_arg
+    assert kwargs["recorded_by"] is not None
+
+    with factory() as session:
+        actions = list(
+            session.scalars(
+                select(AuditLog.action).where(AuditLog.workspace_id == workspace_id)
+            ).all()
+        )
+    assert "ao.self_eval.run_requested" in actions
diff --git a/apps/web/src/app/(board)/settings/models/page.tsx b/apps/web/src/app/(board)/settings/models/page.tsx
index b996ce2a..b18316bd 100644
--- a/apps/web/src/app/(board)/settings/models/page.tsx
+++ b/apps/web/src/app/(board)/settings/models/page.tsx
@@ -1,11 +1,21 @@
 import { AoSettingsView } from "@/components/ao-settings/ao-settings-view";
+import { SelfEvalPanel } from "@/components/self-eval/self-eval-panel";
 
 /**
  * Adaptive Orchestration "Models & effort" settings (`ao-settings-ui`): per-role
  * model + effort selectors, the tier -> model map editor, complexity thresholds,
  * the auto-route toggle, and a live routing-preview panel. Backed by the typed
  * `/ao/role-config`, `/ao/settings` and `/ao/routing-preview` routers.
+ *
+ * Below it, the Self-Eval Gate panel (`/ao/self-eval/*`): the private suite,
+ * frozen baseline, gate posture for pending config changes, and the run
+ * trigger — the gate guards exactly the config edited on this page.
  */
 export default function AoSettingsPage() {
-  return <AoSettingsView />;
+  return (
+    <div className="flex flex-col gap-6">
+      <AoSettingsView />
+      <SelfEvalPanel />
+    </div>
+  );
 }
diff --git a/apps/web/src/components/self-eval/self-eval-panel.test.tsx b/apps/web/src/components/self-eval/self-eval-panel.test.tsx
new file mode 100644
index 00000000..490419fd
--- /dev/null
+++ b/apps/web/src/components/self-eval/self-eval-panel.test.tsx
@@ -0,0 +1,197 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { ApiError, type ForgeApiClient } from "@/lib/api/client";
+import type { SelfEvalRunAccepted, SelfEvalStatusOut } from "@/lib/api/types";
+
+import { SelfEvalPanel } from "./self-eval-panel";
+
+function makeStatus(over: Partial<SelfEvalStatusOut> = {}): SelfEvalStatusOut {
+  return {
+    workspace_id: "w-test",
+    enforced: true,
+    suite: {
+      id: "s-1",
+      slug: "acme-app-self-eval",
+      version: "1.2.0",
+      title: "Acme private suite",
+      task_count: 12,
+      repo_id: "github:acme/app",
+      published: true,
+    },
+    baseline: {
+      benchmark_suite_id: "s-1",
+      baseline_rate: 0.8,
+      resolved: 8,
+      total: 10,
+      recorded_at: "2026-07-01T12:00:00Z",
+    },
+    ...over,
+  };
+}
+
+function makeAccepted(): SelfEvalRunAccepted {
+  return {
+    status: "queued",
+    task: "forge.self_eval.run",
+    workspace_id: "w-test",
+    benchmark_suite_id: "s-1",
+  };
+}
+
+function makeClient(overrides: Partial<ForgeApiClient> = {}): ForgeApiClient {
+  return {
+    getSelfEvalStatus: vi.fn(() => Promise.resolve(makeStatus())),
+    runSelfEval: vi.fn(() => Promise.resolve(makeAccepted())),
+    ...overrides,
+  } as unknown as ForgeApiClient;
+}
+
+function renderPanel(client: ForgeApiClient) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  }
+  return render(<SelfEvalPanel client={client} />, { wrapper: Wrapper });
+}
+
+describe("SelfEvalPanel", () => {
+  it("renders the loading skeleton while the status loads", () => {
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() => new Promise<SelfEvalStatusOut>(() => {})),
+      }),
+    );
+    expect(screen.getByTestId("self-eval-skeleton")).toBeInTheDocument();
+  });
+
+  it("shows a fetch error state distinct from the empty (cold-start) state", async () => {
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() =>
+          Promise.reject(new ApiError(500, "boom", null)),
+        ),
+      }),
+    );
+    expect(await screen.findByTestId("self-eval-error")).toBeInTheDocument();
+    expect(screen.queryByTestId("self-eval-panel")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("self-eval-no-baseline")).not.toBeInTheDocument();
+  });
+
+  it("renders suite, baseline and last-run facts from the API", async () => {
+    renderPanel(makeClient());
+
+    expect(await screen.findByTestId("self-eval-panel")).toBeInTheDocument();
+    expect(screen.getByTestId("self-eval-suite")).toHaveTextContent(
+      "acme-app-self-eval",
+    );
+    expect(screen.getByTestId("self-eval-suite")).toHaveTextContent("1.2.0");
+    expect(screen.getByTestId("self-eval-suite")).toHaveTextContent(
+      "github:acme/app",
+    );
+    expect(screen.getByTestId("self-eval-baseline")).toHaveTextContent("80.0%");
+    expect(screen.getByTestId("self-eval-baseline")).toHaveTextContent("8/10");
+    expect(screen.getByTestId("self-eval-last-run")).toHaveTextContent("8/10");
+  });
+
+  it("shows the gate as able to block when enforcement is on and a baseline exists", async () => {
+    renderPanel(makeClient());
+    const gate = await screen.findByTestId("self-eval-gate-status");
+    expect(gate).toHaveTextContent(/enforcement on/i);
+    // The Phase-A limitation is stated inline, always.
+    expect(screen.getByTestId("self-eval-phase-a")).toHaveTextContent(/phase a/i);
+  });
+
+  it("shows the gate as off when enforcement is disabled", async () => {
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() =>
+          Promise.resolve(makeStatus({ enforced: false })),
+        ),
+      }),
+    );
+    expect(await screen.findByTestId("self-eval-gate-status")).toHaveTextContent(
+      /enforcement off/i,
+    );
+  });
+
+  it("states plainly that the gate cannot block until a baseline exists", async () => {
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() =>
+          Promise.resolve(makeStatus({ baseline: null })),
+        ),
+      }),
+    );
+    const empty = await screen.findByTestId("self-eval-no-baseline");
+    expect(empty).toHaveTextContent(/cannot block any config change/i);
+    expect(screen.getByTestId("self-eval-last-run")).toHaveTextContent(
+      /no scored runs/i,
+    );
+  });
+
+  it("explains the missing suite on cold start and disables the run action", async () => {
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() =>
+          Promise.resolve(makeStatus({ suite: null, baseline: null })),
+        ),
+      }),
+    );
+    expect(await screen.findByTestId("self-eval-no-suite")).toHaveTextContent(
+      /no private suite/i,
+    );
+    expect(screen.getByTestId("self-eval-run")).toBeDisabled();
+  });
+
+  it("disables the run action for an unpublished suite", async () => {
+    const status = makeStatus();
+    renderPanel(
+      makeClient({
+        getSelfEvalStatus: vi.fn(() =>
+          Promise.resolve({
+            ...status,
+            suite: { ...status.suite!, published: false },
+          }),
+        ),
+      }),
+    );
+    await screen.findByTestId("self-eval-panel");
+    expect(screen.getByTestId("self-eval-run")).toBeDisabled();
+  });
+
+  it("queues a run and renders the accepted state", async () => {
+    const client = makeClient();
+    renderPanel(client);
+    await screen.findByTestId("self-eval-panel");
+
+    fireEvent.click(screen.getByTestId("self-eval-run"));
+
+    await waitFor(() => expect(client.runSelfEval).toHaveBeenCalledTimes(1));
+    expect(await screen.findByTestId("self-eval-run-accepted")).toHaveTextContent(
+      /queued/i,
+    );
+  });
+
+  it("shows a run error distinct from the accepted state", async () => {
+    renderPanel(
+      makeClient({
+        runSelfEval: vi.fn(() =>
+          Promise.reject(new ApiError(409, "no_private_suite", null)),
+        ),
+      }),
+    );
+    await screen.findByTestId("self-eval-panel");
+
+    fireEvent.click(screen.getByTestId("self-eval-run"));
+
+    expect(await screen.findByTestId("self-eval-run-error")).toBeInTheDocument();
+    expect(screen.queryByTestId("self-eval-run-accepted")).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/components/self-eval/self-eval-panel.tsx b/apps/web/src/components/self-eval/self-eval-panel.tsx
new file mode 100644
index 00000000..a115151a
--- /dev/null
+++ b/apps/web/src/components/self-eval/self-eval-panel.tsx
@@ -0,0 +1,327 @@
+"use client";
+
+import { FlaskConical, Play, ShieldCheck } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { apiClient, type ForgeApiClient } from "@/lib/api/client";
+import { useRunSelfEval, useSelfEvalStatus } from "@/lib/api/ao-settings";
+import type { SelfEvalStatusOut } from "@/lib/api/types";
+import { cn } from "@/lib/utils";
+
+export interface SelfEvalPanelProps {
+  client?: ForgeApiClient;
+}
+
+/**
+ * Self-Eval Gate settings panel (trust layer, Phase A): the workspace's
+ * private per-repo suite, the frozen baseline the gate defends, the last
+ * scoring run, the gate's current posture for pending config changes, and a
+ * "run self-eval" action that enqueues the worker-owned `forge.self_eval.run`
+ * task via `POST /ao/self-eval/runs`. Every state is backed by
+ * `GET /ao/self-eval/status`; the Phase-A limitation is stated inline rather
+ * than hidden.
+ */
+export function SelfEvalPanel({ client = apiClient }: SelfEvalPanelProps) {
+  const statusQuery = useSelfEvalStatus(client);
+  const runMutation = useRunSelfEval(client);
+
+  if (statusQuery.isLoading) {
+    return (
+      <section
+        data-testid="self-eval-skeleton"
+        aria-busy="true"
+        className="mx-auto w-full max-w-4xl"
+      >
+        <div className="h-64 animate-pulse rounded-xl border border-border bg-card" />
+      </section>
+    );
+  }
+
+  if (statusQuery.isError || !statusQuery.data) {
+    return (
+      <section
+        data-testid="self-eval-error"
+        role="status"
+        className="mx-auto flex w-full max-w-4xl flex-col items-center gap-3 rounded-xl border border-dashed border-border px-6 py-12 text-center"
+      >
+        <ShieldCheck className="h-8 w-8 text-muted-foreground" aria-hidden />
+        <div className="flex flex-col gap-1">
+          <p className="text-sm font-medium text-foreground">
+            Self-Eval Gate status unavailable
+          </p>
+          <p className="max-w-sm text-xs text-muted-foreground">
+            The status read failed — this is a fetch error, not an empty
+            workspace. Try again in a moment.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={() => void statusQuery.refetch()}
+          className="inline-flex h-9 items-center rounded-md border border-border px-3 text-sm font-medium text-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          Retry
+        </button>
+      </section>
+    );
+  }
+
+  const status = statusQuery.data;
+  const runnable = status.suite !== null && status.suite.published;
+
+  return (
+    <section
+      data-testid="self-eval-panel"
+      className="mx-auto flex w-full max-w-4xl flex-col gap-4 rounded-xl border border-border bg-card p-5"
+    >
+      <div className="flex items-start gap-3">
+        <span className="mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-md border border-border bg-muted/60 text-primary">
+          <ShieldCheck className="h-5 w-5" aria-hidden />
+        </span>
+        <div>
+          <h2 className="font-display text-base font-semibold tracking-tight">
+            Self-Eval Gate
+          </h2>
+          <p className="text-sm text-muted-foreground">
+            Blocks a model/router config change that regresses your private
+            per-repo regression suite below its frozen baseline.
+          </p>
+        </div>
+      </div>
+
+      <div className="grid gap-4 lg:grid-cols-3">
+        <SuiteBlock status={status} />
+        <BaselineBlock status={status} />
+        <GateStatusBlock status={status} />
+      </div>
+
+      <LastRunLine status={status} />
+
+      {/* Run action — enqueues the worker task; a run is minutes-long. */}
+      <div className="flex flex-col gap-2 border-t border-border pt-4">
+        <div className="flex flex-wrap items-center gap-3">
+          <button
+            type="button"
+            data-testid="self-eval-run"
+            disabled={!runnable || runMutation.isPending}
+            onClick={() => runMutation.mutate()}
+            className="inline-flex h-9 items-center gap-2 rounded-md bg-primary px-4 text-sm font-semibold text-primary-foreground transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
+          >
+            <Play className="h-4 w-4" aria-hidden />
+            {runMutation.isPending ? "Queueing…" : "Run self-eval"}
+          </button>
+          {!runnable ? (
+            <span className="text-xs text-muted-foreground">
+              Requires a published private suite.
+            </span>
+          ) : null}
+        </div>
+        {runMutation.isSuccess ? (
+          <p
+            data-testid="self-eval-run-accepted"
+            role="status"
+            className="text-sm text-success"
+          >
+            Run queued — the <Mono>forge.self_eval.run</Mono> worker task will
+            score the private suite and record the baseline. Refresh in a few
+            minutes.
+          </p>
+        ) : null}
+        {runMutation.isError ? (
+          <p
+            data-testid="self-eval-run-error"
+            role="alert"
+            className="text-sm text-danger"
+          >
+            Couldn&apos;t queue the self-eval run. It needs a published private
+            suite and admin access — please try again.
+          </p>
+        ) : null}
+      </div>
+
+      {/* Phase-A limitation, stated inline (honesty rule). */}
+      <p
+        data-testid="self-eval-phase-a"
+        className="rounded-lg border border-warning/40 bg-warning/10 p-3 text-xs text-muted-foreground"
+      >
+        <span className="font-medium text-warning">Phase A limitation:</span>{" "}
+        the API layer does not re-evaluate a proposed config inline. Without a
+        baseline the gate cannot block anything, and even with one, a stock
+        deployment no-ops at config-change time until an eval runner is
+        injected — baselines are recorded only by the worker-owned{" "}
+        <Mono>forge.self_eval.run</Mono> task queued above.
+      </p>
+    </section>
+  );
+}
+
+// --- Blocks ------------------------------------------------------------------ //
+
+function SuiteBlock({ status }: { status: SelfEvalStatusOut }) {
+  return (
+    <FactBlock title="Private suite" testId="self-eval-suite">
+      {status.suite ? (
+        <div className="flex flex-col gap-1">
+          <span className="font-mono text-xs text-foreground">
+            {status.suite.slug} @ {status.suite.version}
+          </span>
+          <span className="text-xs text-muted-foreground">
+            {status.suite.title} · {status.suite.task_count} hidden cases
+          </span>
+          {status.suite.repo_id ? (
+            <span className="font-mono text-[11px] text-muted-foreground">
+              {status.suite.repo_id}
+            </span>
+          ) : null}
+          <span
+            className={cn(
+              "w-fit rounded-full border px-2 py-0.5 text-[10px] uppercase tracking-wide",
+              status.suite.published
+                ? "border-success/40 bg-success/10 text-success"
+                : "border-warning/40 bg-warning/10 text-warning",
+            )}
+          >
+            {status.suite.published ? "published" : "unpublished — not runnable"}
+          </span>
+        </div>
+      ) : (
+        <p data-testid="self-eval-no-suite" className="text-xs text-muted-foreground">
+          No private suite yet — one is minted from your merged PRs by the{" "}
+          <Mono>forge.self_eval.mint</Mono> worker task.
+        </p>
+      )}
+    </FactBlock>
+  );
+}
+
+function BaselineBlock({ status }: { status: SelfEvalStatusOut }) {
+  return (
+    <FactBlock title="Baseline" testId="self-eval-baseline">
+      {status.baseline ? (
+        <div className="flex flex-col gap-1">
+          <span className="font-display text-xl font-semibold text-foreground">
+            {formatRate(status.baseline.baseline_rate)}
+          </span>
+          <span className="text-xs text-muted-foreground">
+            {status.baseline.resolved}/{status.baseline.total} cases resolved
+          </span>
+          <span className="text-xs text-muted-foreground">
+            recorded {formatWhen(status.baseline.recorded_at)}
+          </span>
+        </div>
+      ) : (
+        <p
+          data-testid="self-eval-no-baseline"
+          className="text-xs text-muted-foreground"
+        >
+          No baseline recorded — the Self-Eval Gate cannot block any config
+          change until a baseline exists.
+        </p>
+      )}
+    </FactBlock>
+  );
+}
+
+function GateStatusBlock({ status }: { status: SelfEvalStatusOut }) {
+  const gate = deriveGate(status);
+  return (
+    <FactBlock title="Gate status" testId="self-eval-gate-status">
+      <div className="flex flex-col gap-1">
+        <span
+          className={cn(
+            "w-fit rounded-full border px-2.5 py-0.5 text-xs font-medium",
+            gate.tone,
+          )}
+        >
+          {gate.label}
+        </span>
+        <p className="text-xs text-muted-foreground">{gate.description}</p>
+      </div>
+    </FactBlock>
+  );
+}
+
+function LastRunLine({ status }: { status: SelfEvalStatusOut }) {
+  return (
+    <p data-testid="self-eval-last-run" className="text-xs text-muted-foreground">
+      <FlaskConical className="mr-1 inline h-3.5 w-3.5 align-text-bottom" aria-hidden />
+      {status.baseline ? (
+        <>
+          Last scoring run: {status.baseline.resolved}/{status.baseline.total}{" "}
+          resolved ({formatRate(status.baseline.baseline_rate)}) on{" "}
+          {formatWhen(status.baseline.recorded_at)}.
+        </>
+      ) : (
+        <>No scored runs recorded.</>
+      )}{" "}
+      Phase A keeps no separate run history — a run that scores updates the
+      baseline; a run that cannot score (missing provisioning) leaves no record
+      here.
+    </p>
+  );
+}
+
+// --- Derivations & primitives ------------------------------------------------ //
+
+function deriveGate(status: SelfEvalStatusOut): {
+  label: string;
+  description: string;
+  tone: string;
+} {
+  if (!status.enforced) {
+    return {
+      label: "Enforcement off",
+      description:
+        "self_eval_enforce is disabled — pending config changes are not checked against the baseline.",
+      tone: "border-border bg-muted text-muted-foreground",
+    };
+  }
+  if (!status.baseline) {
+    return {
+      label: "Enforcement on — cannot block yet",
+      description:
+        "Enforcement is on, but with no baseline there is nothing to regress against, so every pending config change passes.",
+      tone: "border-warning/40 bg-warning/10 text-warning",
+    };
+  }
+  return {
+    label: "Enforcement on — baseline recorded",
+    description:
+      "A pending config change that regresses below the baseline is refused (409) unless forced — once an eval runner is wired (see the Phase A note).",
+    tone: "border-success/40 bg-success/10 text-success",
+  };
+}
+
+function formatRate(rate: number): string {
+  return `${(rate * 100).toFixed(1)}%`;
+}
+
+function formatWhen(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
+}
+
+function FactBlock({
+  title,
+  testId,
+  children,
+}: {
+  title: string;
+  testId: string;
+  children: ReactNode;
+}) {
+  return (
+    <div
+      data-testid={testId}
+      className="flex flex-col gap-2 rounded-lg border border-border bg-muted/30 p-4"
+    >
+      <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+        {title}
+      </h3>
+      {children}
+    </div>
+  );
+}
+
+function Mono({ children }: { children: ReactNode }) {
+  return <span className="font-mono text-[11px]">{children}</span>;
+}
diff --git a/apps/web/src/lib/api/ao-settings.ts b/apps/web/src/lib/api/ao-settings.ts
index 799d7496..64079b00 100644
--- a/apps/web/src/lib/api/ao-settings.ts
+++ b/apps/web/src/lib/api/ao-settings.ts
@@ -33,6 +33,8 @@ import type {
   RoleConfigUpsertRequest,
   RoutingPreviewRequest,
   RoutingPreviewResponse,
+  SelfEvalRunAccepted,
+  SelfEvalStatusOut,
 } from "./types";
 
 export const aoSettingsKeys = {
@@ -40,6 +42,7 @@ export const aoSettingsKeys = {
   roleConfig: (projectId?: string) =>
     ["ao-settings", "role-config", projectId ?? null] as const,
   settings: () => ["ao-settings", "workspace-settings"] as const,
+  selfEval: () => ["ao-settings", "self-eval"] as const,
 } as const;
 
 /** Every role's effective `{model_or_tier, effort}` (optionally project-scoped). */
@@ -133,3 +136,29 @@ export function usePreviewAoRouting(
     mutationFn: (body) => client.previewAoRouting(body),
   });
 }
+
+/** Self-Eval Gate facts: enforcement flag, private suite, recorded baseline. */
+export function useSelfEvalStatus(
+  client: ForgeApiClient = apiClient,
+): UseQueryResult<SelfEvalStatusOut> {
+  return useQuery({
+    queryKey: aoSettingsKeys.selfEval(),
+    queryFn: () => client.getSelfEvalStatus(),
+  });
+}
+
+/**
+ * Queue the worker-owned `forge.self_eval.run` task (admin). Revalidates the
+ * status read so a freshly recorded baseline eventually shows up on refetch.
+ */
+export function useRunSelfEval(
+  client: ForgeApiClient = apiClient,
+): UseMutationResult<SelfEvalRunAccepted, Error, void> {
+  const queryClient = useQueryClient();
+  return useMutation<SelfEvalRunAccepted, Error, void>({
+    mutationFn: () => client.runSelfEval(),
+    onSettled: () => {
+      void queryClient.invalidateQueries({ queryKey: aoSettingsKeys.selfEval() });
+    },
+  });
+}
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index 166d2063..42c849c1 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -98,6 +98,8 @@ import type {
   RoutingPreviewRequest,
   RoutingPreviewResponse,
   RunTrace,
+  SelfEvalRunAccepted,
+  SelfEvalStatusOut,
   ServiceInfo,
   Team,
   TeamInput,
@@ -809,6 +811,22 @@ export class ForgeApiClient {
     });
   }
 
+  /** Self-Eval Gate facts: enforcement flag, private suite, recorded baseline. */
+  getSelfEvalStatus(): Promise<SelfEvalStatusOut> {
+    return this.request<SelfEvalStatusOut>("/ao/self-eval/status");
+  }
+
+  /**
+   * Enqueue the worker-owned `forge.self_eval.run` task for this workspace
+   * (admin, 202). The run itself is minutes-long and agent-driven — it scores
+   * the private suite and records the baseline; this call only queues it.
+   */
+  runSelfEval(): Promise<SelfEvalRunAccepted> {
+    return this.request<SelfEvalRunAccepted>("/ao/self-eval/runs", {
+      method: "POST",
+    });
+  }
+
   /**
    * The in-process F38 metric registry as Prometheus text exposition. Returns
    * an empty string when observability is disabled (the registry is a no-op).
diff --git a/apps/web/src/lib/api/types.ts b/apps/web/src/lib/api/types.ts
index 6bf71882..eb7a9c29 100644
--- a/apps/web/src/lib/api/types.ts
+++ b/apps/web/src/lib/api/types.ts
@@ -2317,6 +2317,49 @@ export interface RoutingPreviewResponse {
   auto_route_enabled: boolean;
 }
 
+// --- Self-Eval Gate (trust layer, /ao/self-eval/*) ------------------------- //
+
+/** The workspace's private Self-Eval suite (case content is never exposed). */
+export interface SelfEvalSuiteOut {
+  id: string;
+  slug: string;
+  version: string;
+  title: string;
+  task_count: number;
+  repo_id: string | null;
+  published: boolean;
+}
+
+/** The frozen baseline the Self-Eval Gate blocks regressions against. */
+export interface SelfEvalBaselineOut {
+  benchmark_suite_id: string;
+  baseline_rate: number;
+  resolved: number;
+  total: number;
+  /** When the baseline row was last minted/refreshed by a scoring run. */
+  recorded_at: string;
+}
+
+/**
+ * Body for `GET /ao/self-eval/status` — raw facts, no derived verdicts.
+ * `suite`/`baseline` are `null` on cold start; `enforced` mirrors the
+ * `self_eval_enforce` app setting. The UI derives gate status from these.
+ */
+export interface SelfEvalStatusOut {
+  workspace_id: string;
+  enforced: boolean;
+  suite: SelfEvalSuiteOut | null;
+  baseline: SelfEvalBaselineOut | null;
+}
+
+/** Body for `POST /ao/self-eval/runs` (202): the run is queued, not done. */
+export interface SelfEvalRunAccepted {
+  status: "queued";
+  task: string;
+  workspace_id: string;
+  benchmark_suite_id: string;
+}
+
 // --- Public benchmark leaderboard (F35 /public router) --------------------- //
 // Payload-free, unauthenticated projections: no submitter contact, raw config,
 // or raw payloads ever appear on these shapes (mirrors the API's `Public*`
diff --git a/docs/trust-layer.md b/docs/trust-layer.md
index 34a80aae..4a5a4cc8 100644
--- a/docs/trust-layer.md
+++ b/docs/trust-layer.md
@@ -368,6 +368,23 @@ setting (a no-op unless set). On a regression the block is **audited**
 *before* the mutation is applied; a `force=true` override is audited
 (`ao.config.self_eval_forced`) and allowed through.
 
+Two thin endpoints back the web panel (same router):
+
+- `GET /ao/self-eval/status` (READ) — raw facts, no derived verdicts: the
+  `self_eval_enforce` flag, the workspace's private suite (published
+  preferred; case content is never exposed), and the most recently updated
+  baseline (`baseline_rate`, `resolved`/`total`, `recorded_at`). `null`s on
+  cold start.
+- `POST /ao/self-eval/runs` (ADMIN, `202`) — enqueues the worker-owned
+  `forge.self_eval.run` Celery task with the workspace's current effective AO
+  config snapshot (redacted) via the api->worker `send_task` seam
+  (`enqueue_self_eval_run` in
+  `apps/api/forge_api/services/self_eval_service.py`, mirroring
+  `pm_service.py`). `409 no_private_suite` when no published private suite
+  exists (nothing the worker could score); the request is audited
+  (`ao.self_eval.run_requested`). The run itself still executes only in the
+  worker — this endpoint queues it, nothing more.
+
 Two worker tasks own the offline, agent-driven halves (they run in the worker,
 never a request path, because a real run is minutes-long):
 
@@ -395,9 +412,17 @@ never a request path, because a real run is minutes-long):
   runner, but a stock API deployment does not evaluate the proposed config
   inline.
 - **Enforcement is off by default** (`self_eval_enforce`).
-- **Baseline establishment/refresh is worker-driven only.** It is the
-  `forge.self_eval.run` Celery task. (Some in-code docstrings refer to this as
-  "the worker-owned `POST /ao/self-eval/runs` path" — that HTTP endpoint does
-  **not** exist today; `benchmarks.py` states there is no inline `POST /runs`,
-  and the baseline run is the Celery task.)
-- **No web UI yet** (Self-Eval web UI, Task 21).
+- **Baseline establishment/refresh is worker-executed.** The run is the
+  `forge.self_eval.run` Celery task; `POST /ao/self-eval/runs` is only a thin
+  admin trigger that enqueues it (there is still no inline run in any request
+  path — `benchmarks.py`'s "no inline `POST /runs`" note stands for the
+  community-suite router).
+- **Web UI**: the Self-Eval Gate settings panel
+  (`apps/web/src/components/self-eval/self-eval-panel.tsx`, rendered on
+  Settings -> "Models & effort" beneath the AO config it guards) shows the
+  private suite, the frozen baseline (rate + recorded-at), the last scoring
+  run, the derived gate posture, and a "Run self-eval" action over
+  `POST /ao/self-eval/runs`. The Phase-A limitation above is stated inline in
+  the panel — a no-baseline workspace is told plainly that the gate cannot
+  block until a baseline exists. Phase B (inline evaluation of the proposed
+  config at the API layer) remains out of scope.

From ed07c0c0636648a467a00c080a352108c5773dc5 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 06:19:35 +0200
Subject: [PATCH 45/47] fix(web): attempt-language for self-eval run-accepted
 message

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/components/self-eval/self-eval-panel.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/self-eval/self-eval-panel.tsx b/apps/web/src/components/self-eval/self-eval-panel.tsx
index a115151a..a0731d1b 100644
--- a/apps/web/src/components/self-eval/self-eval-panel.tsx
+++ b/apps/web/src/components/self-eval/self-eval-panel.tsx
@@ -122,8 +122,8 @@ export function SelfEvalPanel({ client = apiClient }: SelfEvalPanelProps) {
             className="text-sm text-success"
           >
             Run queued — the <Mono>forge.self_eval.run</Mono> worker task will
-            score the private suite and record the baseline. Refresh in a few
-            minutes.
+            attempt to score the private suite; if it can score, it records the
+            baseline. Refresh in a few minutes.
           </p>
         ) : null}
         {runMutation.isError ? (

From 16974346f379a6e1cc2761ab90bef50b4decf910 Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 06:39:46 +0200
Subject: [PATCH 46/47] fix(deploy): pass model-provider and multi-agent env
 contract into containers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 deploy/docker-compose.dev.yml                 | 13 +++++++
 deploy/docker-compose.yml                     | 27 +++++++++++++
 .../helm/forge/templates/configmap-env.yaml   |  3 ++
 .../tests/secret_config_separation_test.yaml  | 17 ++++++++
 deploy/helm/forge/values.schema.json          |  3 +-
 deploy/helm/forge/values.yaml                 |  5 +++
 deploy/tests/test_compose_contract.py         | 39 +++++++++++++++++++
 7 files changed, 106 insertions(+), 1 deletion(-)

diff --git a/deploy/docker-compose.dev.yml b/deploy/docker-compose.dev.yml
index 5262e019..c00af18f 100644
--- a/deploy/docker-compose.dev.yml
+++ b/deploy/docker-compose.dev.yml
@@ -38,6 +38,19 @@ x-python-env: &python-env
   FORGE_REDIS_URL: redis://redis:6379/0
   MCP_GATEWAY_URL: http://mcp-gateway:8001
   MINIO_ENDPOINT: http://minio:9000
+  # HARD-02 BYOK model provider. FORGE_MODEL_PROVIDER (anthropic|openai) is the
+  # master switch; unset OR empty -> the offline deterministic scripted client
+  # (ModelClientConfig.from_env strips/falsy-checks these, so the empty-default
+  # form is unset-equivalent). Provider-native ANTHROPIC/OPENAI keys win, then the
+  # provider-agnostic FORGE_MODEL_API_KEY. Passed explicitly because this shared
+  # env map has no env_file, so a root .env only reaches ${VAR} references.
+  FORGE_MODEL_PROVIDER: ${FORGE_MODEL_PROVIDER:-}
+  FORGE_MODEL_NAME: ${FORGE_MODEL_NAME:-}
+  FORGE_MODEL_API_KEY: ${FORGE_MODEL_API_KEY:-}
+  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+  OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+  # F27 multi-agent coordinator (supervised runs); read by CoordinatorSettings.
+  MULTI_AGENT_ENABLED: ${MULTI_AGENT_ENABLED:-false}
 
 services:
   # --------------------------------------------------------------------- #
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 22651a74..cbcfb9e4 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -140,6 +140,17 @@ services:
       FORGE_SECRET_KEY_FILE: /run/secrets/forge_secret_key
       # Two-tier envelope encryption for BYOK secrets (rotatable, versioned KEK).
       FORGE_ENVELOPE_ENCRYPTION: ${FORGE_ENVELOPE_ENCRYPTION:-true}
+      # HARD-02 BYOK model provider. The API resolves a per-workspace model client
+      # via AuthService.resolve_model_client -> ModelClientConfig.from_env(), whose
+      # env fallback (no vault secret_id) reads these same vars — so they must reach
+      # the api, not just the worker. Empty-default == unset == offline scripted
+      # client (from_env strips/falsy-checks them). Passed explicitly: this service
+      # uses an `environment:` map with no env_file (a root .env only fills ${VAR}).
+      FORGE_MODEL_PROVIDER: ${FORGE_MODEL_PROVIDER:-}
+      FORGE_MODEL_NAME: ${FORGE_MODEL_NAME:-}
+      FORGE_MODEL_API_KEY: ${FORGE_MODEL_API_KEY:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
       # Incident alert webhook signing secrets (F17); absent -> 501 fail-closed.
       FORGE_PAGERDUTY_WEBHOOK_SECRET: ${FORGE_PAGERDUTY_WEBHOOK_SECRET:-}
       FORGE_DATADOG_WEBHOOK_SECRET: ${FORGE_DATADOG_WEBHOOK_SECRET:-}
@@ -238,6 +249,22 @@ services:
       # the API; fail-closed if unset (no ephemeral key in production).
       FORGE_SECRET_KEY: ${FORGE_SECRET_KEY:?set a stable FORGE_SECRET_KEY (see deploy/.env.production.example)}
       FORGE_ENVELOPE_ENCRYPTION: ${FORGE_ENVELOPE_ENCRYPTION:-true}
+      # HARD-02 BYOK model provider. FORGE_MODEL_PROVIDER (anthropic|openai) is the
+      # master switch; unset OR empty -> the offline deterministic scripted client
+      # (ModelClientConfig.from_env strips/falsy-checks these, so the empty-default
+      # form below is unset-equivalent). The key is BYOK: provider-native
+      # ANTHROPIC_API_KEY / OPENAI_API_KEY win, FORGE_MODEL_API_KEY is the
+      # provider-agnostic fallback. Passed explicitly because this service uses an
+      # `environment:` map with no env_file, so a root .env only reaches ${VAR} refs.
+      FORGE_MODEL_PROVIDER: ${FORGE_MODEL_PROVIDER:-}
+      FORGE_MODEL_NAME: ${FORGE_MODEL_NAME:-}
+      FORGE_MODEL_API_KEY: ${FORGE_MODEL_API_KEY:-}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      # F27 multi-agent coordinator (supervised runs). Read by forge_coordinator's
+      # CoordinatorSettings (MULTI_AGENT_ENABLED); "false"/unset keeps supervised
+      # runs single-agent (escalate with reason `multi_agent_disabled`).
+      MULTI_AGENT_ENABLED: ${MULTI_AGENT_ENABLED:-false}
       FORGE_PAGERDUTY_WEBHOOK_SECRET: ${FORGE_PAGERDUTY_WEBHOOK_SECRET:-}
       FORGE_DATADOG_WEBHOOK_SECRET: ${FORGE_DATADOG_WEBHOOK_SECRET:-}
       FORGE_SENTRY_WEBHOOK_SECRET: ${FORGE_SENTRY_WEBHOOK_SECRET:-}
diff --git a/deploy/helm/forge/templates/configmap-env.yaml b/deploy/helm/forge/templates/configmap-env.yaml
index 5acceadc..1408391a 100644
--- a/deploy/helm/forge/templates/configmap-env.yaml
+++ b/deploy/helm/forge/templates/configmap-env.yaml
@@ -26,6 +26,9 @@ data:
   {{- with .Values.forge.modelName }}
   FORGE_MODEL_NAME: {{ . | quote }}
   {{- end }}
+  # --- F27 multi-agent coordinator (supervised runs). Read by CoordinatorSettings;
+  #     the worker consumes this ConfigMap via envFrom. Default "false". ---
+  MULTI_AGENT_ENABLED: {{ .Values.forge.multiAgentEnabled | quote }}
   MCP_GATEWAY_URL: {{ printf "http://%s-mcp-gateway:%d" (include "forge.fullname" .) (int .Values.mcpGateway.service.port) | quote }}
   # --- BYOK vault: the ACTIVE key VERSION is non-secret; the key MATERIAL
   #     (FORGE_VAULT_KEYS) is in the Secret only (F37). ---
diff --git a/deploy/helm/forge/tests/secret_config_separation_test.yaml b/deploy/helm/forge/tests/secret_config_separation_test.yaml
index 2a920256..f1d4645f 100644
--- a/deploy/helm/forge/tests/secret_config_separation_test.yaml
+++ b/deploy/helm/forge/tests/secret_config_separation_test.yaml
@@ -54,6 +54,23 @@ tests:
           of: ConfigMap
       - isNotNull:
           path: data.FORGE_MODEL_PROVIDER
+  - it: the multi-agent coordinator toggle renders in the ConfigMap (default off)
+    template: templates/configmap-env.yaml
+    asserts:
+      # Non-secret knob (F27); default false so packaged deployments can reach it.
+      - isNotNull:
+          path: data.MULTI_AGENT_ENABLED
+      - equal:
+          path: data.MULTI_AGENT_ENABLED
+          value: "false"
+  - it: the multi-agent coordinator toggle honours forge.multiAgentEnabled=true
+    template: templates/configmap-env.yaml
+    set:
+      forge.multiAgentEnabled: true
+    asserts:
+      - equal:
+          path: data.MULTI_AGENT_ENABLED
+          value: "true"
   - it: fails closed when secrets.create=false and existingSecret is empty
     template: templates/worker/deployment.yaml
     set:
diff --git a/deploy/helm/forge/values.schema.json b/deploy/helm/forge/values.schema.json
index e130d658..25307339 100644
--- a/deploy/helm/forge/values.schema.json
+++ b/deploy/helm/forge/values.schema.json
@@ -91,7 +91,8 @@
         "publicUrl": {"type": "string"},
         "logLevel": {"enum": ["debug", "info", "warning", "error"]},
         "modelProvider": {"type": "string", "enum": ["anthropic", "openai"]},
-        "modelName": {"type": "string"}
+        "modelName": {"type": "string"},
+        "multiAgentEnabled": {"type": "boolean"}
       }
     },
     "image": {
diff --git a/deploy/helm/forge/values.yaml b/deploy/helm/forge/values.yaml
index 4d868396..8e20f559 100644
--- a/deploy/helm/forge/values.yaml
+++ b/deploy/helm/forge/values.yaml
@@ -42,6 +42,11 @@ forge:
   # Rename any --set secrets.data.MODEL_PROVIDER_KEY=... to FORGE_MODEL_API_KEY.
   modelProvider: anthropic
   modelName: ""
+  # F27 multi-agent coordinator (supervised runs). Rendered as MULTI_AGENT_ENABLED
+  # in the ConfigMap and read by forge_coordinator's CoordinatorSettings. `false`
+  # (default) keeps supervised runs single-agent (they escalate to a human with
+  # reason `multi_agent_disabled`); set `true` to enable parallel sub-agents.
+  multiAgentEnabled: false
 
 # Image defaults shared by all four workloads. Per-workload image.repository/tag/
 # digest live under each workload block below.
diff --git a/deploy/tests/test_compose_contract.py b/deploy/tests/test_compose_contract.py
index c8429c8a..566654db 100644
--- a/deploy/tests/test_compose_contract.py
+++ b/deploy/tests/test_compose_contract.py
@@ -414,6 +414,45 @@ def test_worker_env_carries_f34_sandbox_settings() -> None:
     assert "FORGE_SANDBOX_JAILER_ROOT" in env
 
 
+# --------------------------------------------------------------------------- #
+# HARD-02 — BYOK model provider + F27 multi-agent env contract                 #
+# The app services use explicit `environment:` maps with no env_file, so a     #
+# quickstart operator's FORGE_MODEL_* / provider keys reach the container ONLY #
+# if the var is listed here; otherwise the scripted offline client is forced.  #
+# --------------------------------------------------------------------------- #
+
+_MODEL_ENV_KEYS = (
+    "FORGE_MODEL_PROVIDER",
+    "FORGE_MODEL_NAME",
+    "FORGE_MODEL_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+)
+
+
+def test_worker_env_carries_model_provider_contract() -> None:
+    """The worker's agent runtime reads FORGE_MODEL_* / provider keys from env."""
+    env = _service("worker")["environment"]
+    for key in _MODEL_ENV_KEYS:
+        assert key in env, f"worker env missing {key}"
+        # Empty-default form so an unset var stays unset-equivalent (offline).
+        assert env[key] == f"${{{key}:-}}", f"{key} not passed empty-default"
+
+
+def test_api_env_carries_model_provider_contract() -> None:
+    """The API resolve_model_client env fallback (ModelClientConfig.from_env) reads
+    the same keys, so they must reach the api service too — not just the worker."""
+    env = _service("api")["environment"]
+    for key in _MODEL_ENV_KEYS:
+        assert key in env, f"api env missing {key}"
+
+
+def test_worker_env_carries_multi_agent_toggle() -> None:
+    """F27 MULTI_AGENT_ENABLED must reach the worker (the coordinator reader)."""
+    env = _service("worker")["environment"]
+    assert env.get("MULTI_AGENT_ENABLED") == "${MULTI_AGENT_ENABLED:-false}"
+
+
 def test_docker_proxy_verbs_unchanged_by_f34() -> None:
     """AC15 — runtime selection is a create-body field; no new proxy verbs."""
     env = _service("docker-proxy")["environment"]

From d218b1b42fff2eedeb440a6270e7aeb64f32849d Mon Sep 17 00:00:00 2001
From: Forge Swarm <swarm@forge.local>
Date: Tue, 21 Jul 2026 06:40:46 +0200
Subject: [PATCH 47/47] docs(release): re-pin readiness snapshot at branch tip

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 RELEASE_READINESS.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/RELEASE_READINESS.md b/RELEASE_READINESS.md
index 8c249d35..e1ee6e25 100644
--- a/RELEASE_READINESS.md
+++ b/RELEASE_READINESS.md
@@ -2,8 +2,8 @@
 
 - **Target bar:** Beta
 - **Overall verdict:** ❌ **NOT MET**
-- **Generated (UTC):** 2026-07-20T21:04:04Z
-- **Commit:** `a06ad55b4491697126b048ce5a56f545bfeae6d4`
+- **Generated (UTC):** 2026-07-21T04:40:04Z
+- **Commit:** `16974346f379a6e1cc2761ab90bef50b4decf910`
 - **Version (cz):** `0.1.0`
 
 > A bar is **MET** only when every gate at-or-below it is `GREEN` or `MANUAL_ATTESTED`. `SKIPPED_NO_CREDS`, `MISSING_EVIDENCE`, `STALE`, `MANUAL_PENDING`, and `RED` all mean **NOT MET** — the engine never infers a pass.
@@ -12,16 +12,16 @@
 
 | Gate | Blocker | Workstream | Status | Evidence (cmd/artifact) | Last-checked |
 |---|---|---|---|---|---|
-| `G-DB` | #6 | HARD-01 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m postgres -q packages/db | 2026-07-20T21:04:04Z |
-| `G-MODEL` | #1 | HARD-02 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q apps/api -k model_provider | 2026-07-20T21:04:04Z |
-| `G-RAG-REAL` | #2 | HARD-04 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m realeval -q | 2026-07-20T21:04:04Z |
-| `G-GH` | #1 | HARD-05 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k github_app | 2026-07-20T21:04:04Z |
-| `G-MCP` | #1 | HARD-06 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k mcp_live | 2026-07-20T21:04:04Z |
-| `G-SLACK` | #1 | HARD-07 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k slack_live | 2026-07-20T21:04:04Z |
-| `G-BUILD` | #3 | HARD-08 | 🟢 GREEN | deploy/build-manifest.json | 2026-07-20T21:04:04Z |
-| `G-TYPES` | #6 | HARD-12 | 🟢 GREEN | make typecheck | 2026-07-20T21:04:04Z |
-| `G-SEC-AUTOMATED` | #4 | HARD-09 | 🟢 GREEN | uv run pytest -m security -q | 2026-07-20T21:04:04Z |
-| `G-CRYPTO` | #5 | HARD-10 | 🟢 GREEN | uv run pytest -q apps/api/tests/test_auth_crypto_envelope.py apps/api/tests/test_cli_secrets.py | 2026-07-20T21:04:04Z |
+| `G-DB` | #6 | HARD-01 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m postgres -q packages/db | 2026-07-21T04:40:04Z |
+| `G-MODEL` | #1 | HARD-02 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q apps/api -k model_provider | 2026-07-21T04:40:04Z |
+| `G-RAG-REAL` | #2 | HARD-04 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m realeval -q | 2026-07-21T04:40:04Z |
+| `G-GH` | #1 | HARD-05 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k github_app | 2026-07-21T04:40:04Z |
+| `G-MCP` | #1 | HARD-06 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k mcp_live | 2026-07-21T04:40:04Z |
+| `G-SLACK` | #1 | HARD-07 | ⏭️ SKIPPED_NO_CREDS | uv run pytest -m integration -q -k slack_live | 2026-07-21T04:40:04Z |
+| `G-BUILD` | #3 | HARD-08 | 🟢 GREEN | deploy/build-manifest.json | 2026-07-21T04:40:04Z |
+| `G-TYPES` | #6 | HARD-12 | 🟢 GREEN | make typecheck | 2026-07-21T04:40:04Z |
+| `G-SEC-AUTOMATED` | #4 | HARD-09 | 🟢 GREEN | uv run pytest -m security -q | 2026-07-21T04:40:04Z |
+| `G-CRYPTO` | #5 | HARD-10 | 🟢 GREEN | uv run pytest -q apps/api/tests/test_auth_crypto_envelope.py apps/api/tests/test_cli_secrets.py | 2026-07-21T04:40:04Z |
 
 ## Verdict