wicked-crew 0.5.0 → 0.7.0

package/dist/api/routes.js

@@ -3,13 +3,30 @@ import { listRequirements, getRequirement, patchRequirement } from './requiremen
 import { randomUUID } from 'node:crypto';
 import { readFileSync, existsSync } from 'node:fs';
 import { promises as fsp } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError, humanGatePhaseIds } from '../core/adapter.js';
 import { codeGraphDb, requirementsGraph } from '../core/repoPaths.js';
+import { QeGateCache } from '../qe/gate-events.js';
+import { buildAcceptanceView, resolveRunWorkflow } from '../qe/acceptance.js';
 import { buildEvidenceBundle, coreUnitId, evidenceFilename } from './evidence.js';
 import { outputUnavailableReason, resolveUnit, unitKeysFor } from './unit-output.js';
 import { execCapped, ExecOutputTooLarge } from '../core/exec.js';
+import { SeatHealthTracker } from './seat-health.js';
+import { applyWorkerConfigRoot, signedInHeuristic } from './seat-signin.js';
+import { allowedRootsFor, isInsideRoot, openWithSystemDefault } from './open-path.js';
+import { InvalidDiffBaseError, NotARegularFileError, UnresolvableDiffBaseError, readFileCapped, worktreeDiff, } from './run-files.js';
+import { resolveProjectGraphBinding } from '../projects/graph.js';
+import { registerProjectRoutes } from '../projects/routes.js';
+import { ProjectSettingsStore } from '../projects/settings.js';
+import { boundOrigin, InteractiveBridgePool } from '../interactive/bridge-pool.js';
+import { registerInteractiveProxy } from '../interactive/proxy-routes.js';
+import { MembershipIndex } from '../projects/membership-index.js';
+import { MEMBERSHIP_ATTACHED, membershipAttachedKey } from '../projects/events.js';
+import { AuditLog } from './audit.js';
+import { RetryIndex } from './retry-index.js';
+import { GuidanceIndex } from './guidance-index.js';
+import { LOCAL_ACTOR } from './auth.js';
 // Re-exported so existing `import { API_PREFIX } from './routes.js'` callers keep working; the
 // value lives in the leaf module api-prefix.ts to keep unit-output.ts out of this file's cycle.
 export { API_PREFIX } from './api-prefix.js';
@@ -93,7 +110,10 @@ const RegisterRepoSchema = z
  * schema does not accept — so `.strict()` is what turns that trip into a 400 instead of an
  * unworkflowed run reported as `201`.
  */
-const LaunchSchema = z.object({
+// The request-body schemas below are exported so `tests/wire-contract.test.ts` can prove, at
+// compile time, that every body the published contract (`wicked-crew-api-types`) lets a client
+// send is a body these schemas accept — the request-direction half of the drift guard (task #84).
+export const LaunchSchema = z.object({
     problem: z.string().min(1),
     sessionId: z.string().min(1).optional(),
     clisJson: z.string().min(1).optional(),
@@ -101,17 +121,39 @@ const LaunchSchema = z.object({
     humanConfirm: z.string().min(1).optional(),
     repoRef: z.string().min(1).optional(),
     workflow: z.string().min(1).optional(),
-}).strict();
-const GateSchema = z.object({
+    /** DES-PROJECT-001 §2.2 — file the run into a project; membership attaches atomically with
+     *  the launch record. Unknown/archived ⇒ the launch fails (never a silent unfiled run). */
+    projectId: z.string().min(1).optional(),
+    /** crew#293 — `"pr"` appends the hardened deliver Tool phase (push run branch + `gh pr create`)
+     *  to a PER-RUN copy of the selected workflow. Requires `workflow` (enforced by the refine
+     *  below, so the 400 happens at parse time, not after the adapter is consulted). */
+    deliver: z.literal('pr').optional(),
+    /** DES-UX-001 §8.3 (CREW-UX-3) — the run this launch retries. Must name an EXISTING run id
+     *  (the route checks the store and 400s with a named error otherwise); persisted via the
+     *  `run.launched` audit entry + retry index and echoed as `AgentSession.retry_of`. */
+    retryOf: z.string().min(1).optional(),
+}).strict().refine((b) => b.deliver === undefined || b.workflow !== undefined, {
+    message: 'deliver: "pr" requires a workflow — a free-text run has no def to append the deliver phase to',
+    path: ['deliver'],
+});
+export const GateSchema = z.object({
     approve: z.boolean(),
     amend: z.string().optional(),
 }).strict();
+/** `PUT /runs/:id/guidance` (DES-UX-002 §7.2, CREW-UX-7) — the durable pre-gate note body.
+ *  The empty string is a legal body: it CLEARS the note. The byte cap is checked in the route
+ *  (not zod's char-counting `max`) so the 400 names the actual limit. */
+export const GuidanceSchema = z.object({
+    text: z.string(),
+}).strict();
+/** ~8KB — a guidance note is operator prose, not a document store. */
+const GUIDANCE_MAX_BYTES = 8192;
 const InjectSchema = z.object({
     message: z.string().min(1),
     /** `"all"` broadcasts to every active worker; any other value is a CLI key. */
     target: z.string().min(1).default('all'),
 }).strict();
-const OpenTerminalSchema = z.object({
+export const OpenTerminalSchema = z.object({
     cwd: z.string().min(1),
     cmd: z.array(z.string().min(1)).min(1).optional(),
     cols: z.number().int().positive(),
@@ -124,16 +166,119 @@ const ResizeTerminalSchema = z.object({
     cols: z.number().int().positive(),
     rows: z.number().int().positive(),
 }).strict();
+/** `POST /open` (crew#273) — the studio Files tab's "open with the OS default app" body. */
+export const OpenPathSchema = z.object({
+    path: z.string().min(1),
+    runId: z.string().min(1).optional(),
+}).strict();
+/**
+ * A SKIN-OWNED settings key (crew#323): one lowercase segment under the `studio.` namespace,
+ * e.g. `studio.appearance`, `studio.notifications`. The daemon never interprets these values —
+ * the settings store is shared with the skin, and the namespace is what makes that legible.
+ */
+const STUDIO_SETTINGS_KEY = /^studio\.[a-z][a-z0-9-]*$/;
+/**
+ * Per-key ceiling on a `studio.*` value, as the UTF-8 byte length of its JSON form.
+ *
+ * 512KB, not "a few KB": `studio.appearance` carries the operator's logo as a data URI, and
+ * base64 costs ~33%, so this admits a ~380KB image — a real logo, not a favicon — while a
+ * preferences blob like `studio.notifications` spends a few dozen bytes of it. One generous
+ * cap covers both because the daemon cannot tell them apart; what it stops is settings.json
+ * quietly becoming an asset store. It sits at half of Fastify's 1MiB default body limit, so a
+ * realistic multi-key patch (one blob near the cap plus small preference blobs) is still parsed
+ * before it is judged — but note the two limits COMPOSE: a body whose keys total more than 1MiB
+ * is refused by Fastify with a 413 that this route never sees, so the per-key 400 below is the
+ * ceiling on ONE key, not on the patch.
+ */
+const STUDIO_SETTINGS_MAX_BYTES = 512 * 1024;
 /**
  * The daemon REST surface. Every endpoint is a thin wrapper over one adapter /
  * core-ts call (DES-STUDIO-001 §2). `session`/`phase` nouns are now `run`/`unit`.
  */
-export function registerRoutes(app, adapter, gateCache, elicitationCache) {
+export function registerRoutes(app, adapter, gateCache, elicitationCache, 
+// Defaulted so a caller that never arms the bus seam (tests drive this
+// function directly) gets the same behavior as an unarmed daemon: an empty
+// cache, `busEvent: null`, and the lazy ledger read doing all the work.
+qeGateEvents = new QeGateCache(), 
+// Defaulted for the same reason: tests that drive this function directly get
+// the projects surface with no bus (events skipped) and a fresh index.
+projects = { bus: null, index: new MembershipIndex(), log: () => undefined }, 
+// Defaulted likewise — to a NOOP trail, deliberately: a directly-driven
+// route set (unit tests) must never write the operator's real
+// ~/.wicked-crew/audit.log or leave appends pending after close. The real
+// trail always arrives from `createServer`.
+security = { audit: AuditLog.noop(), authMode: 'off' }, 
+// Defaulted likewise: a directly-driven route set gets a fresh (all-active) health map and the
+// real OS opener — tests inject both through this seam.
+runtime = {}) {
+    const { audit } = security;
+    const seatHealth = runtime.seatHealth ?? new SeatHealthTracker();
+    const openWithOs = runtime.openWithOs ?? openWithSystemDefault;
+    const signedIn = runtime.signedIn ?? signedInHeuristic;
+    const retryIndex = runtime.retryIndex ?? new RetryIndex();
+    const guidanceIndex = runtime.guidanceIndex ?? new GuidanceIndex();
+    // The run-DTO joins (DES-UX-001 §8.2/§8.3, DES-UX-002 §7.2): `project_id` from the membership
+    // record — `null` = genuinely unfiled, so the field is ALWAYS present on served runs —
+    // `retry_of` from the lineage index, and `guidance` from the guidance index, each set only
+    // when known (absent, never null, spells "not a retry" / "no note").
+    // Applied at DTO assembly on exactly the two endpoints that serve the run DTO
+    // (GET /runs + GET /runs/:id); the internal sessionsDetail() consumers are untouched.
+    const decorateRun = (view) => {
+        view.session.project_id = projects.index.projectOf(view.session.id) ?? null;
+        const retryOf = retryIndex.retryOfFor(view.session.id);
+        if (retryOf !== undefined)
+            view.session.retry_of = retryOf;
+        const guidance = guidanceIndex.guidanceFor(view.session.id);
+        if (guidance !== undefined)
+            view.session.guidance = guidance;
+        return view;
+    };
+    // Resolved ONCE and shared by the project routes (which read/write `interactiveRoot`) and the
+    // interactive proxy (which resolves a root from it) — two stores would let a PATCH land in one
+    // and the proxy keep reading the other.
+    const projectSettings = projects.settings ?? new ProjectSettingsStore();
+    // `req.actor` is pinned by the auth hooks `createServer` installs; a caller
+    // driving this function directly (tests) has no hooks, so downstream code
+    // still gets the ONE actor shape via this accessor.
+    const actorOf = (req) => req.actor ?? LOCAL_ACTOR;
     // Liveness — also proves the actor + event pump are up.
     app.get(`${V}/health`, async () => {
         const ping = await adapter.ping();
         return { status: 'ok', version: PKG_VERSION, ping };
     });
+    // Who am I talking to the daemon as? (task #88). In local mode this is
+    // always the implicit full-trust local actor; in required mode it names the
+    // token's actor — the cheap probe a skin uses to decide what to render.
+    app.get(`${V}/whoami`, async (req) => ({
+        actor: actorOf(req),
+        authMode: security.authMode,
+    }));
+    // The actor audit trail (task #88): who launched/steered/governed what.
+    // Read-only (observer trust); newest first; `?runId=` / `?action=` / `?limit=`.
+    app.get(`${V}/audit`, async (req, reply) => {
+        const q = req.query;
+        const first = (v) => (Array.isArray(v) ? v[0] : v)?.trim() || undefined;
+        const runId = first(q.runId);
+        const action = first(q.action);
+        const limitRaw = first(q.limit);
+        // Reject partial-numeric strings like "10abc" — parseInt accepts those,
+        // Number() is strict and returns NaN for them (Copilot, #250).
+        const limit = limitRaw !== undefined ? Number(limitRaw) : undefined;
+        if (limitRaw !== undefined && (!Number.isFinite(limit) || limit < 1 || !Number.isInteger(limit))) {
+            return reply.code(400).send({ error: '`limit` must be a positive integer' });
+        }
+        try {
+            const entries = await audit.read({
+                ...(runId !== undefined ? { runId } : {}),
+                ...(action !== undefined ? { action } : {}),
+                ...(limit !== undefined ? { limit } : {}),
+            });
+            return { entries };
+        }
+        catch (err) {
+            return reply.code(500).send({ error: message(err) });
+        }
+    });
     // Report the actually-bound port/host (honours --port / CREW_PORT / port 0).
     app.get(`${V}/config`, async () => {
         const addr = app.server.address();
@@ -141,8 +286,209 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         const host = typeof addr === 'object' && addr ? addr.address : '127.0.0.1';
         return { port, host };
     });
-    // The council seats for the launch form (static production roster).
-    app.get(`${V}/roster`, async () => ({ roster: CoreAdapter.roster() }));
+    // The council seats for the launch form (static production roster), each carrying its RUNTIME
+    // health (crew#274). The roster is declarative — every configured seat is listed — and `health`
+    // is what the platform has observed: default active with no message; inactive + the error
+    // excerpt after a seat-level failure, until an ok output or the recovery probe flips it back.
+    // Existing fields ride through verbatim (the seat still round-trips into `clisJson` on launch)
+    // — the spread is deliberately NOT a field whitelist, which is what lets the engine's
+    // `login_invocation` (seat sign-in, wicked-core PR#278) pass through untouched. Each seat also
+    // gains `signed_in`: the cheap file/env presence heuristic, computed against the LIVE
+    // `WICKED_WORKER_HOME` env — the same value the engine reads at the next worker spawn, kept
+    // current by `applyWorkerConfigRoot` at boot and on every settings change.
+    app.get(`${V}/roster`, async () => {
+        const workerRoot = process.env['WICKED_WORKER_HOME'];
+        return {
+            roster: CoreAdapter.roster().map((seat) => ({
+                ...seat,
+                health: seatHealth.healthFor(String(seat.key)),
+                signed_in: signedIn(String(seat.key), workerRoot === '' ? undefined : workerRoot),
+            })),
+        };
+    });
+    // Open a file/folder with the OS default application (crew#273) — the studio Files tab's
+    // click-to-open. The open MUST happen daemon-side (the SPA cannot spawn a process), which is
+    // why the path is validated first: absolute, and inside one of the caller-visible roots — the
+    // run's workdir + extra write roots (when `runId` is given) or a registered repo root. The
+    // run's QE evidence/decisions dirs (`.wicked-qe`/`.wicked-testing`) live under the repo root,
+    // so the repo-root rule covers them. Never an arbitrary path.
+    app.post(`${V}/open`, async (req, reply) => {
+        const parsed = OpenPathSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid open request'));
+        }
+        const { path: rawPath, runId } = parsed.data;
+        if (!isAbsolute(rawPath)) {
+            return reply.code(400).send({ error: '`path` must be an absolute path' });
+        }
+        const target = resolve(rawPath);
+        let roots;
+        try {
+            let session;
+            if (runId !== undefined) {
+                const views = await adapter.sessionsDetail();
+                const view = views.find((v) => v.session.id === runId);
+                if (view === undefined) {
+                    return reply.code(404).send({ error: `unknown run: ${runId}` });
+                }
+                session = view.session;
+            }
+            roots = allowedRootsFor(session, await adapter.listRepos());
+        }
+        catch (err) {
+            return reply.code(500).send({ error: message(err) });
+        }
+        if (!roots.some((root) => isInsideRoot(root, target))) {
+            return reply.code(403).send({
+                error: "path is outside every allowed root (the run's workdir/write roots and the registered repos)",
+            });
+        }
+        try {
+            await openWithOs(target);
+        }
+        catch (err) {
+            return reply.code(502).send({ error: `could not open ${target}: ${message(err)}` });
+        }
+        return { status: 'opened' };
+    });
+    // ── Run file & diff reads (DES-FEEDBACK-002 CREW-1) ────────────────────────
+    // The studio's in-app viewer (P0-3). Both routes are GET-only assembly of reviewed machinery:
+    // the SAME containment `POST /open` runs (`allowedRootsFor` + fail-closed `isInsideRoot`) over
+    // the SAME root set (run workdir + extra write roots + registered repo roots), capped payloads,
+    // and `execCapped` git with argv arrays. Threat delta over /open is strictly smaller: these only
+    // return bytes the daemon can already read inside the same containment — no OS opener, no write.
+    /** Resolve `:id` → the run's session, and the contained target from `?path=` when present.
+     *  Shared by both routes so their validation ladders (404 unknown run → 400 non-absolute →
+     *  403 outside every root) cannot drift. Returns `null` after replying. */
+    const resolveRunPath = async (reply, id, rawPath) => {
+        let session;
+        let roots;
+        try {
+            const views = await adapter.sessionsDetail();
+            const view = views.find((v) => v.session.id === id);
+            if (view === undefined) {
+                await reply.code(404).send({ error: `unknown run: ${id}` });
+                return null;
+            }
+            session = view.session;
+            if (rawPath === undefined)
+                return { session };
+            roots = allowedRootsFor(session, await adapter.listRepos());
+        }
+        catch (err) {
+            await reply.code(500).send({ error: message(err) });
+            return null;
+        }
+        if (!isAbsolute(rawPath)) {
+            await reply.code(400).send({ error: '`path` must be an absolute path' });
+            return null;
+        }
+        const target = resolve(rawPath);
+        if (!roots.some((root) => isInsideRoot(root, target))) {
+            await reply.code(403).send({
+                error: "path is outside every allowed root (the run's workdir/write roots and the registered repos)",
+            });
+            return null;
+        }
+        return { session, target };
+    };
+    // Fastify parses a repeated param as string[] (Copilot, #250/#266). These are FILE-READ
+    // routes: `?path=a&path=b` is rejected outright (400) rather than silently reading as
+    // either (Copilot, #305).
+    const REPEATED_PATH = Symbol('repeated path param');
+    const singlePathQ = (v) => Array.isArray(v) ? REPEATED_PATH : v?.trim() || undefined;
+    // File content from the run's contained roots: 512 KB cap (`truncated: true` past it, first
+    // 512 KB served), NUL-in-first-8KB binary sniff (`binary: true`, `content: ""`). Read-only by
+    // construction (`fs` read); no directory listing — the studio already has the file list.
+    app.get(`${V}/runs/:id/files`, async (req, reply) => {
+        const { id } = req.params;
+        const rawPath = singlePathQ(req.query.path);
+        if (rawPath === REPEATED_PATH) {
+            return reply.code(400).send({ error: '`path` may be given at most once' });
+        }
+        if (rawPath === undefined) {
+            return reply.code(400).send({ error: '`path` query parameter is required' });
+        }
+        const resolved = await resolveRunPath(reply, id, rawPath);
+        if (resolved === null)
+            return reply;
+        const target = resolved.target;
+        try {
+            const read = await readFileCapped(target);
+            return { path: target, ...read };
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return reply.code(404).send({ error: `no such file: ${target}` });
+            }
+            if (err instanceof NotARegularFileError) {
+                return reply.code(400).send({ error: `\`path\` is not a regular file: ${target}` });
+            }
+            return reply.code(500).send({ error: message(err) });
+        }
+    });
+    // The run's worktree diff against HEAD — or, with `?base=` (CREW-UX-1, DES-UX-001 §8.1),
+    // against the run branch's fork point (`base=merge-base`) or a plain in-repo ref, so committed
+    // run work is visible. Staged + unstaged; untracked appended as all-addition `--no-index`
+    // hunks; whole-tree or `?path=` narrowed. 1 MB output cap. `diff: ""` is a real answer (clean
+    // tree), not an error. 409 — not 404 — when the run has no workdir or the workdir has been
+    // reaped: the RUN exists; what is gone is the thing to diff against. `base` is a baseline,
+    // NEVER a command surface: anything that is not the merge-base literal or a plain resolvable
+    // ref (flags, paths, ranges, separators) is a named 400 before any git process sees it.
+    app.get(`${V}/runs/:id/diff`, async (req, reply) => {
+        const { id } = req.params;
+        const q = req.query;
+        const rawPath = singlePathQ(q.path);
+        if (rawPath === REPEATED_PATH) {
+            return reply.code(400).send({ error: '`path` may be given at most once' });
+        }
+        const rawBase = singlePathQ(q.base);
+        if (rawBase === REPEATED_PATH) {
+            return reply.code(400).send({ error: '`base` may be given at most once' });
+        }
+        const resolved = await resolveRunPath(reply, id, rawPath);
+        if (resolved === null)
+            return reply;
+        const workdir = resolved.session.workdir;
+        if (typeof workdir !== 'string' || workdir.length === 0) {
+            return reply.code(409).send({ error: `run ${id} has no workdir — nothing to diff` });
+        }
+        if (!existsSync(workdir)) {
+            return reply.code(409).send({ error: `run ${id}'s workdir no longer exists: ${workdir}` });
+        }
+        // Narrowing is WORKTREE-scoped: a contained-but-outside-the-worktree path (extra write
+        // root / repo root) is a valid FILE read but has no meaning as a diff pathspec — rejected
+        // explicitly here rather than handing git a `../`-prefixed pathspec and surfacing its
+        // "outside repository" error as a 500 (Copilot, #305).
+        if (resolved.target !== undefined && !isInsideRoot(workdir, resolved.target)) {
+            return reply.code(400).send({
+                error: `\`path\` must be inside the run's worktree to diff: ${workdir}`,
+            });
+        }
+        const rel = resolved.target === undefined ? undefined : relative(workdir, resolved.target);
+        try {
+            return await worktreeDiff(workdir, rel, rawBase);
+        }
+        catch (err) {
+            // Named 400s (§8.1): malformed base (not a plain ref) and well-formed-but-unresolvable
+            // base are both client errors, each with its error name in the body — never a git 500.
+            if (err instanceof InvalidDiffBaseError || err instanceof UnresolvableDiffBaseError) {
+                return reply.code(400).send({ error: `${err.name}: ${message(err)}` });
+            }
+            if (err.code === 'ENOENT') {
+                return reply.code(500).send({ error: 'git executable not found on server' });
+            }
+            // execCapped throws (no partial output attached) past its 64 MiB daemon-wide buffer —
+            // beyond graceful truncation, so the answer is an explicit, actionable refusal
+            // rather than a generic 500 (Copilot, #305).
+            if (err instanceof ExecOutputTooLarge) {
+                return reply.code(507).send({
+                    error: "diff output exceeds the server's execution buffer — narrow the request with ?path=",
+                });
+            }
+            return reply.code(500).send({ error: message(err) });
+        }
+    });
     // Registered repos → target-repo picker.
     app.get(`${V}/repos`, async () => ({ repos: await adapter.listRepos() }));
     app.post(`${V}/repos`, async (req, reply) => {
@@ -215,23 +561,148 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             input.repoRef = b.repoRef;
         if (b.workflow !== undefined)
             input.workflow = b.workflow;
+        if (b.projectId !== undefined) {
+            input.projectId = b.projectId;
+            // A project is a CONTEXT (crew#326): a run filed into one should see the project's whole
+            // co-located graph, not just its own repo's. Resolved — never REFRESHED — at launch: a
+            // launch that silently indexed N repos would block this response for as long as the slowest
+            // of them takes, so a missing or stale graph degrades to the repo graph and says why.
+            //
+            // The decision is recorded either way. "This run sees the project" and "this run sees one
+            // repo, because X" are both facts about what the run could observe, and the second is the one
+            // an operator needs when a worker reports that a sibling repo does not exist.
+            const decision = await resolveProjectGraphBinding(adapter, b.projectId, b.repoRef);
+            if (decision.binding !== null)
+                input.projectGraph = decision.binding;
+            req.log.info({ runId: input.sessionId, projectId: b.projectId, repoRef: b.repoRef ?? null }, `run ${input.sessionId}: ${decision.reason}`);
+        }
+        if (b.deliver !== undefined)
+            input.deliver = b.deliver;
+        // Retry lineage (DES-UX-001 §8.3): `retryOf` must name an EXISTING run — recording lineage
+        // to a run that never existed would be provenance pointing at nothing, so the launch fails
+        // loudly (400, before anything is committed) rather than filing a dangling edge.
+        if (b.retryOf !== undefined) {
+            const known = await adapter.sessions();
+            if (!known.includes(b.retryOf)) {
+                return reply.code(400).send({
+                    error: `retryOf names an unknown run: ${b.retryOf} — lineage must point at an existing run id`,
+                });
+            }
+        }
         try {
             const runId = await adapter.launchRun(input);
+            // Who launched it — the engine's LaunchOptions carries no actor field
+            // (checked, wicked-core-ts 0.6.0), so the crew-side trail is the system
+            // of record for run provenance (task #88).
+            audit.record('run.launched', actorOf(req), {
+                runId,
+                detail: {
+                    ...(b.workflow !== undefined ? { workflow: b.workflow } : {}),
+                    ...(b.repoRef !== undefined ? { repoRef: b.repoRef } : {}),
+                    ...(b.projectId !== undefined ? { projectId: b.projectId } : {}),
+                    ...(b.deliver !== undefined ? { deliver: b.deliver } : {}),
+                    // CREW-UX-3: the trail is the durable record of lineage — the retry index (and a
+                    // restarted daemon's hydrate) reads it back from exactly this entry.
+                    ...(b.retryOf !== undefined ? { retryOf: b.retryOf } : {}),
+                },
+            });
+            if (b.retryOf !== undefined)
+                retryIndex.set(runId, b.retryOf);
+            if (b.projectId !== undefined) {
+                // The engine attached the crew.run membership ATOMICALLY with the launch record
+                // (DES-PROJECT-001 §2.2) — this is the post-commit half: tag future /ws frames and
+                // emit the membership event (auto-attach at launch is an attach, §4).
+                projects.index.set(runId, b.projectId);
+                projects.bus?.emit(MEMBERSHIP_ATTACHED, 
+                // The AUTHENTICATED actor id, not a caller-supplied string — locked
+                // decision #6 replaces spoofable actor strings on the event surface.
+                { project_id: b.projectId, member: { kind: 'crew.run', ref: runId }, actor: actorOf(req).id }, membershipAttachedKey(b.projectId, 'crew.run', runId, Date.now()));
+            }
             return reply.code(201).send({ runId });
         }
         catch (err) {
             const msg = message(err);
+            // An unknown/archived project is a state conflict on a real resource, not a malformed
+            // request: 404/409 per the projects error mapping; anything else keeps the launch 400/409.
+            if (b.projectId !== undefined && /project.*not registered/i.test(msg)) {
+                return reply.code(404).send({ error: msg });
+            }
+            if (b.projectId !== undefined && /archived|'default'|synthesized/i.test(msg)) {
+                return reply.code(409).send({ error: msg });
+            }
             const busy = /busy|in flight|already/i.test(msg);
             return reply.code(busy ? 409 : 400).send({ error: msg });
         }
     });
     // Run list (replaces GET /sessions). Actionable-first; reconciles the gate and elicitation caches
     // so that terminal-run entries are pruned even when their terminal CoreEvent was missed.
-    app.get(`${V}/runs`, async () => {
+    app.get(`${V}/runs`, async (req) => {
         const views = await adapter.sessionsDetail();
         gateCache.reconcile(views);
         elicitationCache.reconcile(views);
-        return { runs: sortActionableFirst(views) };
+        // Archived runs are WRITTEN OFF (crew#265): excluded from the default view so finished
+        // history doesn't drown live signal, returned in full with `?include=archived`. The caches
+        // above reconcile over the COMPLETE set either way — a gate on an archived run must still
+        // resolve, not leak.
+        // Fastify parses a REPEATED query param as string[] — normalize so `?include=archived`
+        // and `?include=archived&include=archived` behave identically (Copilot).
+        const { include } = req.query;
+        const includeArchived = (Array.isArray(include) ? include : [include]).includes('archived');
+        const visible = includeArchived
+            ? views
+            : views.filter((v) => v.session.archived_at == null);
+        return { runs: sortActionableFirst(visible).map(decorateRun) };
+    });
+    // ── Run archival (crew#265) — write-off, not delete ────────────────────────
+    const ArchiveSchema = z.object({
+        archived: z.boolean(),
+        note: z.string().max(500).optional(),
+    }).strict();
+    app.post(`${V}/runs/:id/archive`, async (req, reply) => {
+        const { id } = req.params;
+        const parsed = ArchiveSchema.safeParse(req.body ?? {});
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        try {
+            const found = await adapter.archiveRun(id, parsed.data.archived, parsed.data.note);
+            if (!found)
+                return reply.code(404).send({ error: 'Run not found' });
+            return { runId: id, archived: parsed.data.archived };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            // The engine names a NON-terminal status ("run X is Executing — only a terminal run…"):
+            // a state conflict on a real resource, not a bad request (write-off must never hide
+            // live work). Anything else — including the old-addon guard — is a real 500.
+            if (/only a terminal run/i.test(msg))
+                return reply.code(409).send({ error: msg });
+            return reply.code(500).send({ error: msg });
+        }
+    });
+    // Bulk write-off for campaign backlogs — explicit ids only, never implicit age selection.
+    const BulkArchiveSchema = z.object({
+        ids: z.array(z.string().min(1)).min(1).max(200),
+        note: z.string().max(500).optional(),
+    }).strict();
+    app.post(`${V}/runs/archive`, async (req, reply) => {
+        const parsed = BulkArchiveSchema.safeParse(req.body ?? {});
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        // Per-id outcomes rather than all-or-nothing: a batch of 45 with one live run in it
+        // should archive 44 and NAME the refusal, not roll back the write-off.
+        const results = [];
+        for (const id of parsed.data.ids) {
+            try {
+                const found = await adapter.archiveRun(id, true, parsed.data.note);
+                results.push(found ? { id, ok: true } : { id, ok: false, error: 'not found' });
+            }
+            catch (e) {
+                results.push({ id, ok: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        return { results, archived: results.filter((r) => r.ok).length };
     });
     // One run's detail.
     app.get(`${V}/runs/:id`, async (req, reply) => {
@@ -240,7 +711,39 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         const run = views.find((v) => v.session.id === id);
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
-        return { run };
+        return { run: decorateRun(run) };
+    });
+    // Durable pre-gate guidance (DES-UX-002 §7.2 — spec'd there as CREW-UX-4, implemented as
+    // CREW-UX-7 because crew#308 already spent that id; see guidance-index.ts). Upserts the ONE
+    // operator note on the run; the empty string clears it. The durable record is the
+    // `guidance.set` audit entry (actor + full text); the index is the read-side layer the run
+    // DTOs echo it from.
+    //
+    // GOVERNANCE ISOLATION (deliberate): the governance gate does NOT read this field — the
+    // engine's `LaunchOptions` never sees it, and no gate evaluation consults it. It is
+    // operator-visible context only; the amend text at gate decision (`POST /runs/:id/gate`)
+    // stays the ONE injection point. The studio pre-populates its steer textarea from this note,
+    // and injection still happens only through the governed amend.
+    app.put(`${V}/runs/:id/guidance`, async (req, reply) => {
+        const { id } = req.params;
+        const parsed = GuidanceSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        const { text } = parsed.data;
+        if (Buffer.byteLength(text, 'utf8') > GUIDANCE_MAX_BYTES) {
+            return reply.code(400).send({
+                error: `guidance exceeds the ${GUIDANCE_MAX_BYTES}-byte cap — a note this size belongs in the problem statement or a linked doc`,
+            });
+        }
+        const known = await adapter.sessions();
+        if (!known.includes(id))
+            return reply.code(404).send({ error: 'Run not found' });
+        // The trail is the durable record (CREW-UX-3 posture): a restarted daemon's
+        // GuidanceIndex.hydrate reads the note back from exactly this entry.
+        audit.record('guidance.set', actorOf(req), { runId: id, detail: { text } });
+        guidanceIndex.set(id, text);
+        return { runId: id, guidance: text };
     });
     // ── Chat sessions (crew#165): warm ACP seat pool + group fan-out (core#134) ──
     // A chat is NOT a run: no council, no gates, no units. Seats warm on open;
@@ -249,6 +752,8 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         chatId: z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/).optional(),
         clis: z.array(z.string().min(1)).min(1).max(8).optional(),
         repoRef: z.string().optional(),
+        /** DES-PROJECT-001 §2.2 — file the chat into a project (`crew.chat` membership). */
+        projectId: z.string().min(1).optional(),
     }).strict();
     app.post(`${V}/chats`, async (req, reply) => {
         const parsed = ChatOpenSchema.safeParse(req.body ?? {});
@@ -265,12 +770,48 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
                 return reply.code(404).send({ error: `Repo ${b.repoRef} not found` });
             cwd = repo.root_path;
         }
+        // Validate the project BEFORE opening seats: a chat has no launch record for the engine to
+        // attach against atomically (chats are an in-memory seat pool), so the route validates
+        // up-front and attaches right after open — the one non-atomic attach, documented in the ADR
+        // changelog. Fail here and no seats were warmed for a filing that could never happen.
+        if (b.projectId !== undefined) {
+            try {
+                const project = await adapter.projectGet(b.projectId);
+                if (project === null) {
+                    return reply.code(404).send({ error: `Project ${b.projectId} not found` });
+                }
+                if (project.status === 'archived') {
+                    return reply
+                        .code(409)
+                        .send({ error: `project ${b.projectId} is archived and blocks new attachments` });
+                }
+            }
+            catch (err) {
+                return reply.code(501).send({ error: message(err) });
+            }
+        }
         const clis = b.clis ??
             CoreAdapter.roster()
                 .map((s) => s.key)
                 .filter((k) => typeof k === 'string');
         try {
             const seats = await adapter.chatOpen(chatId, clis, cwd);
+            if (b.projectId !== undefined) {
+                try {
+                    const { member, created } = await adapter.projectMemberAttach(b.projectId, 'crew.chat', chatId);
+                    if (created) {
+                        projects.index.set(chatId, b.projectId);
+                        projects.bus?.emit(MEMBERSHIP_ATTACHED, { project_id: b.projectId, member: { kind: 'crew.chat', ref: chatId }, actor: actorOf(req).id }, membershipAttachedKey(b.projectId, 'crew.chat', chatId, member.attached_at));
+                    }
+                }
+                catch (err) {
+                    // The chat is open and usable; the filing failed. Say so instead of failing the open —
+                    // the caller can re-attach via POST /projects/:id/members.
+                    return reply
+                        .code(201)
+                        .send({ chatId, seats, projectAttachError: message(err) });
+                }
+            }
             return reply.code(201).send({ chatId, seats });
         }
         catch (err) {
@@ -377,6 +918,44 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             .header('Content-Disposition', `attachment; filename="${evidenceFilename(id)}"`)
             .send(bundle);
     });
+    // ── Acceptance gate read (Phase 6a) ─────────────────────────────────────────
+    // The QE evidence ledger's verdict + manifest for THIS run's repo, plus the
+    // gate's deny-dominates resolution of the workflow's acceptance requirement.
+    // Sits beside `/runs/:id/evidence` deliberately: evidence is what the RUN
+    // recorded about itself; acceptance is what the QE pipeline recorded about
+    // the repo the run worked on — two different systems of record, two routes.
+    //
+    // Always a 200 for a known run: "no ledger", "no verdict" and "FAIL" are
+    // real answers about the gate (each a deny with its own reason), not errors
+    // in the request. Only an unknown run 404s. `?qeRun=<id>` pins the read to
+    // one QE run's newest verdict instead of the repo's newest overall.
+    app.get(`${V}/runs/:id/acceptance`, async (req, reply) => {
+        const { id } = req.params;
+        const q = req.query;
+        const qeRunRaw = Array.isArray(q.qeRun) ? q.qeRun[0] : q.qeRun;
+        const qeRunId = qeRunRaw?.trim();
+        const views = await adapter.sessionsDetail();
+        const run = views.find((v) => v.session.id === id);
+        if (!run)
+            return reply.code(404).send({ error: 'Run not found' });
+        // `sessionsDetail()` patches workflow_id back to the definition name for
+        // BUILT-INS; runs of user-registered workflows still carry the instance id,
+        // so resolve by phase sequence over the full registry. A free-text run
+        // resolves to no workflow, which reads as "declares no requirement".
+        const workflow = resolveRunWorkflow(run, adapter.listWorkflows());
+        let repo = null;
+        if (run.session.repo_ref !== null) {
+            const repos = await adapter.listRepos();
+            repo = repos.find((r) => r.id === run.session.repo_ref) ?? null;
+        }
+        return buildAcceptanceView({
+            runId: id,
+            repo,
+            workflow,
+            gateEvents: qeGateEvents,
+            ...(qeRunId !== undefined && qeRunId !== '' ? { qeRunId } : {}),
+        });
+    });
     // The steering gate (§11.1). approve+amend = approve-with-steer; approve:false = reject (cancels).
     app.post(`${V}/runs/:id/gate`, async (req, reply) => {
         const { id } = req.params;
@@ -395,6 +974,17 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         }
         try {
             const status = await adapter.confirmGate(id, parsed.data.approve, parsed.data.amend);
+            // WHO approved/rejected — the gate-decision audit (task #88). The engine
+            // records THAT the gate resolved (interaction_requests / gateDecided);
+            // only this HTTP layer knows the authenticated principal behind it.
+            audit.record('gate.decided', actorOf(req), {
+                runId: id,
+                detail: {
+                    approve: parsed.data.approve,
+                    ...(parsed.data.amend !== undefined ? { amend: parsed.data.amend } : {}),
+                    status,
+                },
+            });
             return reply.send({ status });
         }
         catch (err) {
@@ -410,6 +1000,7 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             return reply.code(404).send({ error: 'Run not found' });
         try {
             const status = await adapter.cancelRun(id);
+            audit.record('run.cancelled', actorOf(req), { runId: id, detail: { status } });
             return reply.send({ status });
         }
         catch (err) {
@@ -425,9 +1016,14 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
         try {
-            const status = run.session.status === 'awaiting_human'
-                ? await adapter.confirmGate(id, true)
-                : await adapter.resumeRun(id);
+            const gated = run.session.status === 'awaiting_human';
+            const status = gated ? await adapter.confirmGate(id, true) : await adapter.resumeRun(id);
+            // A resume of a gated run IS a gate approval — audit it as one, so the
+            // "who approved" trail has no side door (task #88).
+            audit.record(gated ? 'gate.decided' : 'run.resumed', actorOf(req), {
+                runId: id,
+                detail: gated ? { approve: true, via: 'resume', status } : { status },
+            });
             return reply.send({ status });
         }
         catch (err) {
@@ -448,6 +1044,7 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             return reply.code(404).send({ error: 'Run not found' });
         try {
             await adapter.injectWorkerMessage(id, parsed.data.message, parsed.data.target);
+            audit.record('run.injected', actorOf(req), { runId: id, detail: { target: parsed.data.target } });
             return reply.send({ status: 'ok' });
         }
         catch (err) {
@@ -481,6 +1078,28 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         if (run.session.status !== 'awaiting_human') {
             return reply.code(404).send({ error: 'No open gate for this run' });
         }
+        // DURABLE TRUTH FIRST (DES-PROJECT-001 §5.3): the engine persists the open prompt in
+        // `interaction_requests`, written in the same transaction as the `awaiting_human` pause —
+        // so a daemon restart reads it back directly instead of replaying the event log. The cache
+        // adopts the row (latency layer over durable truth — its comments finally true). The replay
+        // below stays as the FALLBACK, not just for engines predating the binding: a run parked
+        // BEFORE the engine grew the table is awaiting_human with no row, and answering 404 there
+        // would re-open FINDING-051 for exactly the runs mid-upgrade. Row → serve it; no row →
+        // fall through and let the log speak.
+        const durableRows = typeof adapter.interactionRequests === 'function'
+            ? await adapter.interactionRequests(id, 'open')
+            : null;
+        const durableGate = durableRows?.find((r) => r.kind === 'gate');
+        if (durableGate !== undefined) {
+            const entry = {
+                ord: durableGate.ord ?? 0,
+                prompt: durableGate.prompt,
+                lifecycle: 'open',
+                receivedAt: new Date(durableGate.created_at).toISOString(),
+            };
+            gateCache.adopt(id, entry);
+            return { runId: id, ...entry };
+        }
         const events = await adapter.runEvents(id);
         if (events === null) {
             // Now — and only now — 503 is the honest answer: this run really is holding for a human, and
@@ -515,6 +1134,25 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         const ids = await adapter.sessions();
         if (!ids.includes(id))
             return reply.code(404).send({ error: 'Run not found' });
+        // Durable probe (DES-PROJECT-001 §5.3): `interaction_requests` reserves kind `elicitation`.
+        // The engine writes no elicitation rows yet (its elicitation surface is future work — the
+        // resolve path still answers 501), so this read is empty today; it exists so the cache is
+        // STRUCTURALLY a latency layer, and the day the engine writes the rows, restart survival
+        // holds here exactly as it does for gates, with no route change. Guarded like `runEvents`:
+        // a partial-stub adapter (tests) or a pre-0.6.0 addon simply has no durable half.
+        const durable = typeof adapter.interactionRequests === 'function'
+            ? await adapter.interactionRequests(id, 'open')
+            : null;
+        const pending = durable?.find((r) => r.kind === 'elicitation');
+        if (pending !== undefined) {
+            return {
+                runId: id,
+                elicitationId: pending.id,
+                message: pending.prompt,
+                options: null,
+                receivedAt: new Date(pending.created_at).toISOString(),
+            };
+        }
         return reply.code(404).send({ error: 'No pending elicitation for this run' });
     });
     const ElicitationRespondSchema = z
@@ -588,6 +1226,10 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             return reply.code(code).send({ error: message(err) });
         }
         // 7. Done.
+        audit.record('elicitation.resolved', actorOf(req), {
+            runId: id,
+            detail: { elicitationId: taken.entry.elicitationId, action: body.action },
+        });
         return { status: 'resolved' };
     });
     // The durable history of one run (FINDING-057).
@@ -701,7 +1343,9 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
     // ── Governance writes (crew#42) ────────────────────────────────────────────
     app.post(`${V}/governance/policies`, async (req, reply) => {
         try {
-            await adapter.upsertPolicy(req.body);
+            const policy = req.body;
+            await adapter.upsertPolicy(policy);
+            audit.record('governance.policy.upserted', actorOf(req), { detail: { id: policy?.id } });
             return { status: 'ok' };
         }
         catch (err) {
@@ -710,7 +1354,9 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
     });
     app.post(`${V}/governance/rules`, async (req, reply) => {
         try {
-            await adapter.upsertConformanceRule(req.body);
+            const rule = req.body;
+            await adapter.upsertConformanceRule(rule);
+            audit.record('governance.rule.upserted', actorOf(req), { detail: { id: rule?.id } });
             return { status: 'ok' };
         }
         catch (err) {
@@ -725,6 +1371,7 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             const existed = await adapter.retirePolicy(id);
             if (!existed)
                 return reply.code(404).send({ error: `policy '${id}' not found` });
+            audit.record('governance.policy.retired', actorOf(req), { detail: { id } });
             return { status: 'retired', id };
         }
         catch (err) {
@@ -737,6 +1384,7 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
             const existed = await adapter.retireConformanceRule(id);
             if (!existed)
                 return reply.code(404).send({ error: `conformance rule '${id}' not found` });
+            audit.record('governance.rule.retired', actorOf(req), { detail: { id } });
             return { status: 'retired', id };
         }
         catch (err) {
@@ -780,6 +1428,7 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         }
         try {
             const id = await adapter.registerWorkflow(body);
+            audit.record('workflow.registered', actorOf(req), { detail: { id } });
             return reply.code(201).send({ id, status: 'registered' });
         }
         catch (err) {
@@ -1129,26 +1778,125 @@ export function registerRoutes(app, adapter, gateCache, elicitationCache) {
         }
     });
     // ── System settings ──────────────────────────────────────────────────────────
+    // The store is SHARED with the skin (crew#323): beside the engine's own keys it round-trips
+    // the studio's `studio.*` preference blobs verbatim — see `CrewSystemSettings`'s index
+    // signature in core/types.ts, which states that rather than leaving it to a client comment.
     app.get(`${V}/settings`, async () => ({ settings: await adapter.getSettings() }));
     app.put(`${V}/settings`, async (req, reply) => {
         const patch = req.body;
         if (typeof patch !== 'object' || patch === null || Array.isArray(patch)) {
             return reply.code(400).send({ error: 'body must be a JSON object' });
         }
-        if ('graphNodeLimit' in patch) {
+        if (Object.hasOwn(patch, 'graphNodeLimit')) {
             const limit = patch.graphNodeLimit;
             if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 20 || limit > 500) {
                 return reply.code(400).send({ error: 'graphNodeLimit must be an integer between 20 and 500' });
             }
         }
-        // Only allow known keys through.
-        const allowed = ['graphNodeLimit'];
+        if (Object.hasOwn(patch, 'worker_config_root')) {
+            const root = patch.worker_config_root;
+            if (typeof root !== 'string' || (root !== '' && !isAbsolute(root))) {
+                return reply.code(400).send({
+                    error: 'worker_config_root must be an absolute path, or "" for the default (~/.wicked-worker)',
+                });
+            }
+        }
+        // workerStallMinutes (crew#287): the stall watchdog's silence threshold. Bounded to a day —
+        // a huge value is "off in practice", which should be a deliberate choice, not a typo.
+        if (Object.hasOwn(patch, 'workerStallMinutes')) {
+            const mins = patch.workerStallMinutes;
+            if (typeof mins !== 'number' || !Number.isInteger(mins) || mins < 1 || mins > 1440) {
+                return reply
+                    .code(400)
+                    .send({ error: 'workerStallMinutes must be an integer between 1 and 1440' });
+            }
+        }
+        // Skin-owned keys (crew#323): allowed through, but VALIDATED rather than trusted. The
+        // daemon does not read these values, so the only two things it can check are the two that
+        // can hurt it — a value it cannot persist, and a value big enough to bloat settings.json.
+        // Both answer 400 naming the key: silence is exactly what made #323 invisible for a whole
+        // campaign of appearance work.
+        const studioKeys = Object.keys(patch).filter((k) => STUDIO_SETTINGS_KEY.test(k));
+        for (const key of studioKeys) {
+            const value = patch[key];
+            // `undefined` from a throwing/circular value AND from a value JSON.stringify simply
+            // drops (a function, a symbol) — both are unpersistable, both are refused.
+            let encoded;
+            try {
+                encoded = JSON.stringify(value);
+            }
+            catch {
+                encoded = undefined;
+            }
+            if (encoded === undefined) {
+                return reply.code(400).send({ error: `${key} must be a JSON-serializable value` });
+            }
+            const bytes = Buffer.byteLength(encoded, 'utf8');
+            if (bytes > STUDIO_SETTINGS_MAX_BYTES) {
+                return reply.code(400).send({
+                    error: `${key} is ${bytes} bytes of JSON, over the ${STUDIO_SETTINGS_MAX_BYTES}-byte per-key cap on studio.* settings`,
+                });
+            }
+        }
+        // Only known engine keys and validated `studio.*` keys are persisted. A key that is
+        // NEITHER is dropped, not refused: request bodies are forward-additive too (DES-STUDIO-001
+        // §5.1), so an older daemon meeting a newer client's engine key must not fail the whole
+        // patch and take the caller's other keys down with it. The cost is that a typo goes
+        // unnoticed on the wire — so the dropped keys are NAMED in the audit entry below.
+        const allowed = [
+            'graphNodeLimit',
+            'worker_config_root',
+            'workerStallMinutes',
+        ];
         const safe = {};
         for (const key of allowed) {
-            if (key in patch)
+            // `Object.hasOwn`, NOT `key in patch` (Copilot on #324): `in` walks the prototype chain, so
+            // a body whose prototype carries an engine key would be persisted from a value the caller
+            // never sent. Not reachable through the default JSON parser — `JSON.parse` yields a plain
+            // object and Fastify refuses `__proto__` — but this route already accepts custom
+            // content-type parsers, which can produce non-plain objects. Own properties only, and the
+            // same spelling the `ignored` filter below uses, so the two can never disagree about what
+            // "present" means.
+            if (Object.hasOwn(patch, key))
                 safe[key] = patch[key];
         }
-        return { settings: await adapter.updateSettings(safe) };
+        for (const key of studioKeys) {
+            safe[key] = patch[key];
+        }
+        // `Object.hasOwn`, NOT `k in safe`: `in` walks the prototype chain, so a dropped key named
+        // `toString` / `valueOf` / `constructor` would test as "kept" and vanish from `ignored` —
+        // the exact silent drop this route exists to end.
+        const ignored = Object.keys(patch).filter((k) => !Object.hasOwn(safe, k));
+        const settings = await adapter.updateSettings(safe);
+        // Re-apply the worker-config root to this process's env (seat sign-in). The engine reads
+        // WICKED_WORKER_HOME per worker spawn — never cached — so this alone makes the change live
+        // at the next spawn: no daemon restart, no engine restart.
+        applyWorkerConfigRoot(settings.worker_config_root);
+        // `changed` names every persisted key, engine and `studio.*` alike; `ignored` (present only
+        // when there is one) is where a dropped unknown key stops being invisible.
+        audit.record('settings.updated', actorOf(req), {
+            detail: { changed: Object.keys(safe), ...(ignored.length > 0 ? { ignored } : {}) },
+        });
+        return { settings };
+    });
+    // ── Projects (DES-PROJECT-001) — the 9-route experience-plane surface ────────
+    registerProjectRoutes(app, adapter, { ...projects, settings: projectSettings }, security);
+    // ── The wicked-interactive bridge, reverse-proxied (DES-MERGE-001 §5.3/§7.2) ──
+    // Mounted BESIDE the routes above and under the same `${V}` prefix, so it inherits one
+    // origin, one auth hook, and one CORS posture — the whole point of slice 1.
+    registerInteractiveProxy(app, adapter, {
+        settings: projectSettings,
+        pool: runtime.interactiveBridges ??
+            new InteractiveBridgePool({
+                log: (m) => app.log.warn(m),
+                debug: (m) => app.log.debug(m),
+                // #298: the daemon's own origin, read LAZILY off the bound server — the pool is built
+                // before `listen`, but only consulted while serving a request, i.e. once bound. The
+                // pool POSTs it to the bridge's /api/studio-origin on start/adopt so the bridge's
+                // `GET /` redirects into studio.
+                studioOrigin: () => boundOrigin(app.server.address()),
+            }),
+        log: (m) => app.log.warn(m),
     });
 }
 //# sourceMappingURL=routes.js.map