wicked-crew 0.6.0 → 0.7.1

package/dist/api/routes.js

@@ -3,7 +3,7 @@ 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 { isAbsolute, join, resolve } 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';
@@ -14,14 +14,18 @@ import { outputUnavailableReason, resolveUnit, unitKeysFor } from './unit-output
 import { execCapped, ExecOutputTooLarge } from '../core/exec.js';
 import { SeatHealthTracker } from './seat-health.js';
 import { applyWorkerConfigRoot, signedInHeuristic } from './seat-signin.js';
-import { isInsideRoot, openWithSystemDefault } from './open-path.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 { InteractiveBridgePool } from '../interactive/bridge-pool.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.
@@ -120,11 +124,30 @@ export const LaunchSchema = 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(),
-}).strict();
+    /** 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. */
@@ -148,6 +171,26 @@ 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`.
@@ -172,6 +215,24 @@ runtime = {}) {
     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.
@@ -181,7 +242,12 @@ runtime = {}) {
     // 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 () => {
+    // `config.manifest` on the routes below (TH-11): the declaration channel the endpoint manifest
+    // reads — type names bind to `wicked-crew-api-types` exports where one exists, structural
+    // spellings where the contract has no name, statusCodes list every code the route answers on
+    // purpose. Declared on the highest-traffic run-lifecycle routes first; the manifest records
+    // null / [] for the rest ("where declared", never invented). See src/api/endpoint-manifest.ts.
+    app.get(`${V}/health`, { config: { manifest: { statusCodes: [200] } } }, async () => {
         const ping = await adapter.ping();
         return { status: 'ok', version: PKG_VERSION, ping };
     });
@@ -261,24 +327,18 @@ runtime = {}) {
             return reply.code(400).send({ error: '`path` must be an absolute path' });
         }
         const target = resolve(rawPath);
-        const roots = [];
+        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}` });
                 }
-                const workdir = view.session.workdir;
-                if (typeof workdir === 'string' && workdir.length > 0)
-                    roots.push(workdir);
-                for (const r of view.session.extra_write_roots ?? []) {
-                    if (typeof r === 'string' && r.length > 0)
-                        roots.push(r);
-                }
+                session = view.session;
             }
-            for (const repo of await adapter.listRepos())
-                roots.push(repo.root_path);
+            roots = allowedRootsFor(session, await adapter.listRepos());
         }
         catch (err) {
             return reply.code(500).send({ error: message(err) });
@@ -296,6 +356,144 @@ runtime = {}) {
         }
         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) => {
@@ -349,7 +547,17 @@ runtime = {}) {
     });
     // Launch a run (replaces POST /sessions). `clisJson` defaults to the roster;
     // `sessionId` is minted if the client omits it.
-    app.post(`${V}/runs`, async (req, reply) => {
+    app.post(`${V}/runs`, {
+        config: {
+            manifest: {
+                requestType: 'LaunchRunBody',
+                responseType: '{ runId: string }',
+                // 404/409: unknown project / archived-or-synthesized project + busy engine (see the
+                // catch below); 400: zod reject or a retryOf naming no existing run.
+                statusCodes: [201, 400, 404, 409],
+            },
+        },
+    }, async (req, reply) => {
         const parsed = LaunchSchema.safeParse(req.body);
         if (!parsed.success) {
             return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
@@ -368,8 +576,34 @@ runtime = {}) {
             input.repoRef = b.repoRef;
         if (b.workflow !== undefined)
             input.workflow = b.workflow;
-        if (b.projectId !== undefined)
+        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
@@ -381,8 +615,14 @@ runtime = {}) {
                     ...(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
@@ -411,7 +651,7 @@ runtime = {}) {
     });
     // 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 (req) => {
+    app.get(`${V}/runs`, { config: { manifest: { responseType: '{ runs: SessionView[] }', statusCodes: [200] } } }, async (req) => {
         const views = await adapter.sessionsDetail();
         gateCache.reconcile(views);
         elicitationCache.reconcile(views);
@@ -426,7 +666,7 @@ runtime = {}) {
         const visible = includeArchived
             ? views
             : views.filter((v) => v.session.archived_at == null);
-        return { runs: sortActionableFirst(visible) };
+        return { runs: sortActionableFirst(visible).map(decorateRun) };
     });
     // ── Run archival (crew#265) — write-off, not delete ────────────────────────
     const ArchiveSchema = z.object({
@@ -480,13 +720,53 @@ runtime = {}) {
         return { results, archived: results.filter((r) => r.ok).length };
     });
     // One run's detail.
-    app.get(`${V}/runs/:id`, async (req, reply) => {
+    app.get(`${V}/runs/:id`, { config: { manifest: { responseType: '{ run: SessionView }', statusCodes: [200, 404] } } }, async (req, reply) => {
         const { id } = req.params;
         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' });
-        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`, {
+        config: {
+            manifest: {
+                requestType: 'SetGuidanceBody',
+                responseType: 'SetGuidanceResult',
+                statusCodes: [200, 400, 404],
+            },
+        },
+    }, 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;
@@ -700,7 +980,16 @@ runtime = {}) {
         });
     });
     // The steering gate (§11.1). approve+amend = approve-with-steer; approve:false = reject (cancels).
-    app.post(`${V}/runs/:id/gate`, async (req, reply) => {
+    app.post(`${V}/runs/:id/gate`, {
+        config: {
+            manifest: {
+                requestType: 'GateDecision',
+                responseType: '{ status: SessionStatus }',
+                // 409 twice over: a run not awaiting a human gate, and an engine refusal at confirm.
+                statusCodes: [200, 400, 404, 409],
+            },
+        },
+    }, async (req, reply) => {
         const { id } = req.params;
         const parsed = GateSchema.safeParse(req.body);
         if (!parsed.success) {
@@ -1287,6 +1576,12 @@ runtime = {}) {
         if (page === null) {
             return reply.code(404).send({ error: 'requirements_graph.json not generated for this repo yet' });
         }
+        // Overrides keyed by ids the corpus no longer mints (an estate id-scheme migration re-keys
+        // method/field SymbolIds) would otherwise vanish without a trace — the count is on the page
+        // AND in the log, because the operator who edited them is not the one reading the response.
+        if ((page.orphanedOverrides ?? 0) > 0) {
+            req.log.warn({ repo: id, orphanedOverrides: page.orphanedOverrides }, 'requirements_overrides.json holds keys matching no requirement — stale after a re-index/migration; re-run the annotation workflow, then re-apply or delete them');
+        }
         return page;
     });
     app.get(`${V}/repos/:id/requirements/:key`, async (req, reply) => {
@@ -1385,8 +1680,10 @@ runtime = {}) {
     });
     // ── Git history (last 20 commits via git log) ─────────────────────────────
     // ── Blast radius for a symbol (via wicked-estate blast-radius --json).
-    //    Carries the honesty contract through: dependents PLUS the unresolved-call
-    //    count — an empty dependents list must never read as "safe to change".
+    //    Carries the honesty contract through: dependents PLUS the count of references
+    //    no resolver bound (ENGINE-CONTRACT §2.1 — repeat sites of an already-bound
+    //    relationship are not counted, so 0 is legitimate for a fully-resolved symbol).
+    //    When non-zero, an empty dependents list must never read as "safe to change".
     app.get(`${V}/repos/:id/graph/blast-radius`, async (req, reply) => {
         const { id } = req.params;
         const q = req.query;
@@ -1521,19 +1818,22 @@ runtime = {}) {
         }
     });
     // ── 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' });
             }
         }
-        if ('worker_config_root' in patch) {
+        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({
@@ -1541,22 +1841,82 @@ runtime = {}) {
                 });
             }
         }
-        // Only allow known keys through.
+        // 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];
         }
+        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);
-        audit.record('settings.updated', actorOf(req), { detail: { changed: Object.keys(safe) } });
+        // `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 ────────
@@ -1566,7 +1926,16 @@ runtime = {}) {
     // 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) }),
+        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),
     });
 }