wicked-crew 0.3.1 → 0.4.0

package/dist/api/routes.js

@@ -1,14 +1,14 @@
 import { z } from 'zod';
+import { listRequirements, getRequirement, patchRequirement } from './requirements.js';
 import { randomUUID } from 'node:crypto';
 import { readFileSync, existsSync } from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { CoreAdapter } from '../core/adapter.js';
+import { ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError } from '../core/adapter.js';
+import { codeGraphDb, requirementsGraph } from '../core/repoPaths.js';
 import { buildEvidenceBundle, evidenceFilename } from './evidence.js';
-const execFileAsync = promisify(execFile);
+import { execCapped, ExecOutputTooLarge } from '../core/exec.js';
 const V = '/api/v1';
 // Daemon version reported by /health — read from package.json so it never drifts
 // from the shipped version across releases. Resolves the package root from the
@@ -32,6 +32,25 @@ function sortActionableFirst(views) {
 function message(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/**
+ * Turns a failed parse into a 400 body, naming any field the schema does not know.
+ *
+ * Every schema here is `.strict()`, because zod's default is to STRIP unknown keys — which made a
+ * misspelled optional field a silent behaviour change (FINDING-031). `POST /runs {"clis":[...],
+ * "workflowId":"feature"}` — core's field names, not the HTTP layer's — answered `201` and ran the
+ * full roster with no workflow. Rejecting is only half the fix: a bare "Invalid request body" leaves
+ * the caller comparing their JSON against the source, so the unknown keys are named in `error`
+ * itself, where a human and a `curl | jq .error` both see it without reading `details`.
+ */
+function invalidBody(err, what) {
+    const unknown = err.issues.flatMap((i) => (i.code === 'unrecognized_keys' ? i.keys : []));
+    const error = unknown.length > 0
+        ? `${what}: unknown field${unknown.length > 1 ? 's' : ''} ${unknown
+            .map((k) => `\`${k}\``)
+            .join(', ')} — this endpoint does not accept ${unknown.length > 1 ? 'them' : 'it'}, and ignoring ${unknown.length > 1 ? 'them' : 'it'} would run a different request than you sent`
+        : what;
+    return { error, details: err.issues };
+}
 // Repo names become directory components under ~/.wicked/repos/ — reject anything
 // that would allow path traversal (slashes, dots-only segments, control chars).
 const SAFE_REPO_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -48,6 +67,7 @@ const RegisterRepoSchema = z
     rootPath: z.string().optional(),
     gitUrl: z.string().optional(),
 })
+    .strict()
     .refine((d) => {
     const hasRemote = typeof d.gitUrl === 'string' && d.gitUrl.length > 0;
     const hasLocal = typeof d.rootPath === 'string' && d.rootPath.length > 0;
@@ -55,6 +75,19 @@ const RegisterRepoSchema = z
     // or rootPath alone (register existing local repo) — all valid.
     return hasRemote || hasLocal;
 }, { message: 'Provide gitUrl (remote clone) or rootPath (local registration), or both.' });
+/**
+ * The launch body. Every field but `problem` is optional, which is what made stripping dangerous:
+ * omitting one is a legitimate request that gets an engine default, so a MISSPELLED one was
+ * indistinguishable from an omitted one and the run went ahead on a configuration the caller never
+ * asked for (FINDING-031).
+ *
+ * The names differ from core's on purpose and this is the trap worth knowing about: core's
+ * `LaunchSpec` takes `clis` (an array) and `workflow`, this takes `clisJson` (a JSON *string*) and
+ * `workflow`, and the `/ws` `sessionStarted` frame reports the chosen workflow as `workflowId`. A
+ * caller who reads the event stream to learn the field names arrives at `workflowId`, which this
+ * 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({
     problem: z.string().min(1),
     sessionId: z.string().min(1).optional(),
@@ -63,16 +96,16 @@ 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({
     approve: z.boolean(),
     amend: z.string().optional(),
-});
+}).strict();
 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({
     cwd: z.string().min(1),
     cmd: z.array(z.string().min(1)).min(1).optional(),
@@ -81,16 +114,16 @@ const OpenTerminalSchema = z.object({
     // Optional so omission is the SAFE governed default (§7 — `false` is never a
     // default; the ungoverned operator shell must opt in explicitly).
     governed: z.boolean().optional(),
-});
+}).strict();
 const ResizeTerminalSchema = z.object({
     cols: z.number().int().positive(),
     rows: z.number().int().positive(),
-});
+}).strict();
 /**
  * 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) {
+export function registerRoutes(app, adapter, gateCache, elicitationCache) {
     // Liveness — also proves the actor + event pump are up.
     app.get(`${V}/health`, async () => {
         const ping = await adapter.ping();
@@ -110,7 +143,7 @@ export function registerRoutes(app, adapter, gateCache) {
     app.post(`${V}/repos`, async (req, reply) => {
         const parsed = RegisterRepoSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         const { name, rootPath, gitUrl } = parsed.data;
         try {
@@ -161,7 +194,7 @@ export function registerRoutes(app, adapter, gateCache) {
     app.post(`${V}/runs`, async (req, reply) => {
         const parsed = LaunchSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         const b = parsed.data;
         const input = {
@@ -187,10 +220,12 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(busy ? 409 : 400).send({ error: msg });
         }
     });
-    // Run list (replaces GET /sessions). Actionable-first; reconciles the gate cache.
+    // 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 () => {
         const views = await adapter.sessionsDetail();
         gateCache.reconcile(views);
+        elicitationCache.reconcile(views);
         return { runs: sortActionableFirst(views) };
     });
     // One run's detail.
@@ -205,6 +240,99 @@ export function registerRoutes(app, adapter, gateCache) {
     // A unit's captured transcript. unitKey is the suffix after `<run>:` — `u<ord>` for free-text
     // runs, `<phase_id>` for workflow runs (e.g. "survey", "coverage"). Strip any accidental
     // `<id>:` prefix so both `survey` and `run-1:survey` resolve to the same key.
+    // ── 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;
+    // messages fan out to warm seats; replies stream on /ws as chatDelta/chatReply.
+    const ChatOpenSchema = z.object({
+        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(),
+    }).strict();
+    app.post(`${V}/chats`, async (req, reply) => {
+        const parsed = ChatOpenSchema.safeParse(req.body ?? {});
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        const b = parsed.data;
+        const chatId = b.chatId ?? randomUUID();
+        let cwd;
+        if (b.repoRef !== undefined) {
+            const repos = await adapter.listRepos();
+            const repo = repos.find((r) => r.id === b.repoRef);
+            if (!repo)
+                return reply.code(404).send({ error: `Repo ${b.repoRef} not found` });
+            cwd = repo.root_path;
+        }
+        const clis = b.clis ??
+            CoreAdapter.roster()
+                .map((s) => s.key)
+                .filter((k) => typeof k === 'string');
+        try {
+            const seats = await adapter.chatOpen(chatId, clis, cwd);
+            return reply.code(201).send({ chatId, seats });
+        }
+        catch (err) {
+            return reply.code(400).send({ error: message(err) });
+        }
+    });
+    const ChatMessageSchema = z.object({
+        text: z.string().min(1).max(65536),
+        targets: z.array(z.string().min(1)).min(1).max(8).optional(),
+    }).strict();
+    app.post(`${V}/chats/:id/messages`, async (req, reply) => {
+        const { id } = req.params;
+        const parsed = ChatMessageSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        try {
+            const seats = await adapter.chatSend(id, parsed.data.text, parsed.data.targets);
+            return reply.code(202).send({ seats });
+        }
+        catch (err) {
+            const msg = message(err);
+            return reply.code(/no warm seats/.test(msg) ? 409 : 400).send({ error: msg });
+        }
+    });
+    // Enumerate live chats (FINDING-027 gap 4). Chat sessions deliberately outlive the page, and
+    // their ids are minted client-side — so before this route the only record of an orphaned seat
+    // lived in the tab that abandoned it, and an operator could not reclaim one without restarting
+    // the daemon. Registered BEFORE `/chats/:id` is irrelevant to fastify (it routes on the literal
+    // segment first), but the order reads the way the routes nest.
+    app.get(`${V}/chats`, async (_req, reply) => {
+        try {
+            return { chats: await adapter.chatList() };
+        }
+        catch (err) {
+            // A build that cannot do chat is a capability gap, not a bad request: 501 tells an operator to
+            // upgrade rather than to fix a call that was already correct. Branching on the type, not on
+            // the message — regexing the text here caught the missing-binding phrasing and missed the
+            // engine's own ("chat unsupported: engine spawned without the ACP runner"), so half of one
+            // condition answered 400.
+            return reply
+                .code(err instanceof ChatUnsupportedError ? 501 : 400)
+                .send({ error: message(err) });
+        }
+    });
+    app.get(`${V}/chats/:id`, async (req, reply) => {
+        const { id } = req.params;
+        try {
+            return { chatId: id, seats: await adapter.chatSeats(id) };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: message(err) });
+        }
+    });
+    app.delete(`${V}/chats/:id`, async (req, reply) => {
+        const { id } = req.params;
+        try {
+            await adapter.chatClose(id);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: message(err) });
+        }
+    });
     app.get(`${V}/runs/:id/units/:unitKey/output`, async (req, reply) => {
         const { id, unitKey } = req.params;
         const suffix = unitKey.startsWith(`${id}:`) ? unitKey.slice(id.length + 1) : unitKey;
@@ -212,15 +340,15 @@ export function registerRoutes(app, adapter, gateCache) {
         return reply.send({ output });
     });
     // The whole run as one auditable JSON attachment: the run, its units (each with
-    // the captured transcript), and the gate/routing decision trail re-derived from
-    // the run DTO — the daemon keeps no event log of its own.
+    // the captured transcript), and the decision trail read back from core's durable
+    // per-run event log — what actually happened, not a re-derivation of it.
     app.get(`${V}/runs/:id/evidence`, 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' });
-        const bundle = await buildEvidenceBundle(run, (unitId) => adapter.workOutput(unitId));
+        const bundle = await buildEvidenceBundle(run, (unitId) => adapter.workOutput(unitId), (runId) => adapter.runEvents(runId));
         return reply
             .header('Content-Disposition', `attachment; filename="${evidenceFilename(id)}"`)
             .send(bundle);
@@ -230,7 +358,7 @@ export function registerRoutes(app, adapter, gateCache) {
         const { id } = req.params;
         const parsed = GateSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         const views = await adapter.sessionsDetail();
         const run = views.find((v) => v.session.id === id);
@@ -289,7 +417,7 @@ export function registerRoutes(app, adapter, gateCache) {
         const { id } = req.params;
         const parsed = InjectSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         const ids = await adapter.sessions();
         if (!ids.includes(id))
@@ -302,14 +430,188 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(409).send({ error: message(err) });
         }
     });
-    // The daemon-cached gate prompt for a paused run (not a core call) so a fresh
-    // browser can render the gate after a late join.
+    // The gate prompt for a paused run, so a fresh browser can render the gate after a late join.
+    //
+    // Cache first, durable event log second (FINDING-051). The cache is process-lifetime, so before
+    // the fallback existed a daemon restart left every parked run unable to say what it was asking —
+    // not because the prompt was gone (core records `awaitingHuman` to the log) but because nothing
+    // read it. A restart is routine: deploy, crash, laptop sleep.
     app.get(`${V}/runs/:id/gate`, async (req, reply) => {
         const { id } = req.params;
-        const entry = gateCache.get(id);
-        if (!entry)
+        const cached = gateCache.get(id);
+        if (cached)
+            return { runId: id, ...cached };
+        // A miss is not evidence of anything on its own, so ask the run what it is doing before paying
+        // to replay it. Only `awaiting_human` can have an open gate, and that answer is definitive:
+        // every other status is a 404 that needs no log at all — which is also the overwhelmingly
+        // common case here, since studio polls this route for runs that are merely finished.
+        //
+        // Reading status first is therefore CHEAPER than not reading it, the opposite of what the first
+        // cut of this assumed: it trades one `sessionsDetail()` for replaying an entire event history,
+        // and it was that skipped check which made a completed run answer 503 on any build without the
+        // binding (CI caught it) — an error where the honest, knowable answer was "no gate".
+        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' });
+        if (run.session.status !== 'awaiting_human') {
             return reply.code(404).send({ error: 'No open gate for this run' });
-        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
+            // this build cannot say what it is asking. Distinct cause, distinct message; answering "no
+            // gate" here would report a capability gap as a fact about the run (the FINDING-050 shape).
+            return reply.code(503).send({
+                error: 'Gate history is unavailable: this wicked-core build has no event-log read binding',
+            });
+        }
+        const replayed = gateCache.rebuild(id, events);
+        if (!replayed) {
+            // Parked, with a history that records no open gate. Pre-log runs land here (their prompt is
+            // genuinely lost), as does a gate whose `awaitingHuman` predates the log's retention.
+            return reply.code(404).send({ error: 'No open gate for this run' });
+        }
+        return { runId: id, ...replayed };
+    });
+    // ── Elicitation (DES-002) ────────────────────────────────────────────────────
+    //
+    // GET returns the current pending elicitation prompt for a run (display-store read).
+    // POST resolves it: the body carries the elicitationId to guard against stale tabs,
+    // the action (accept|decline|cancel), and — for accept — the operator's response.
+    app.get(`${V}/runs/:id/elicitation`, async (req, reply) => {
+        const { id } = req.params;
+        const entry = elicitationCache.get(id);
+        // `entry` already carries `runId`; return it directly to avoid TS2783
+        // ("runId is specified more than once") from a redundant spread.
+        if (entry)
+            return entry;
+        // Cache miss: check existence before returning 404.
+        // Use sessions() (IDs only) — cheaper than sessionsDetail() on this read path.
+        const ids = await adapter.sessions();
+        if (!ids.includes(id))
+            return reply.code(404).send({ error: 'Run not found' });
+        return reply.code(404).send({ error: 'No pending elicitation for this run' });
+    });
+    const ElicitationRespondSchema = z
+        .object({
+        /** Guards against stale-tab submissions: must match the current elicitation's id. */
+        elicitationId: z.string().min(1),
+        action: z.enum(['accept', 'decline', 'cancel']),
+        /** Required when action is "accept" (response must be non-empty); must be absent for decline/cancel. */
+        content: z.object({ response: z.string().min(1) }).optional(),
+    })
+        .strict()
+        .superRefine((val, ctx) => {
+        if (val.action !== 'accept' && val.content !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['content'],
+                message: 'content must only be provided when action is "accept"',
+            });
+        }
+    });
+    app.post(`${V}/runs/:id/elicitation`, async (req, reply) => {
+        const { id } = req.params;
+        // 1. Validate body.
+        const parsed = ElicitationRespondSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
+        }
+        const body = parsed.data;
+        // 1b. Accept requires content.response — validated here, before any state query, so
+        //     the 400 is deterministic regardless of run-existence / cache state (P2).
+        if (body.action === 'accept' && !body.content?.response) {
+            return reply.code(400).send({ error: 'action:accept requires content.response' });
+        }
+        // 2. Existence check (IDs only — cheaper than sessionsDetail).
+        const ids = await adapter.sessions();
+        if (!ids.includes(id))
+            return reply.code(404).send({ error: 'Run not found' });
+        // 3. Atomically take the pending elicitation.
+        const taken = elicitationCache.take(id);
+        if (!taken)
+            return reply.code(409).send({ error: 'No pending elicitation for this run' });
+        // 4. Stale-tab check: submitted elicitationId must match the one we just took.
+        if (body.elicitationId !== taken.entry.elicitationId) {
+            elicitationCache.restoreIfUnchanged(id, taken.entry, taken.gen);
+            return reply
+                .code(409)
+                .send({ error: 'Elicitation superseded; fetch the current prompt and resubmit' });
+        }
+        // 5. Accept-specific validation.
+        if (body.action === 'accept') {
+            // 5a. content.response must be present.
+            if (typeof body.content?.response !== 'string') {
+                elicitationCache.restoreIfUnchanged(id, taken.entry, taken.gen);
+                return reply.code(400).send({ error: 'action:accept requires content.response' });
+            }
+            // 5b. Enum check: if the schema constrained the response, honour it.
+            if (taken.entry.options !== null &&
+                !taken.entry.options.includes(body.content.response)) {
+                elicitationCache.restoreIfUnchanged(id, taken.entry, taken.gen);
+                return reply.code(400).send({ error: 'response must be one of the allowed options' });
+            }
+        }
+        const response = body.action === 'accept' ? body.content.response : null;
+        // 6. Forward to the actor.
+        try {
+            await adapter.resolveElicitation(id, taken.entry.elicitationId, body.action, response);
+        }
+        catch (err) {
+            elicitationCache.restoreIfUnchanged(id, taken.entry, taken.gen);
+            const code = err instanceof ElicitationUnsupportedError ? 501 : 500;
+            return reply.code(code).send({ error: message(err) });
+        }
+        // 7. Done.
+        return { status: 'resolved' };
+    });
+    // The durable history of one run (FINDING-057).
+    //
+    // `/ws` is a live tap and explicitly replays nothing on late join, so until this route existed
+    // the event log had exactly one reader — the gate route above, which reads it for a single
+    // `awaitingHuman` frame and discards the rest. Everything else a run recorded (routing councils,
+    // gate verdicts, per-unit cost) was write-only: observable if you happened to be attached while
+    // it streamed, and unrecoverable afterwards. That makes an incident un-investigable and a run's
+    // audit trail unciteable, which is the opposite of what a durable log is for.
+    //
+    // `type` filters server-side because the alternative is shipping an entire run's history to
+    // answer "what did the gates decide" — the log already excludes high-volume frames
+    // (`is_high_volume` drops CLI/chat deltas and terminal output), so what remains is the
+    // lifecycle, but a long run is still thousands of frames.
+    app.get(`${V}/runs/:id/events`, async (req, reply) => {
+        const { id } = req.params;
+        // Fastify's default querystring parser yields a string for `?type=a` and an ARRAY for a
+        // repeated `?type=a&type=b`. Typing it as `string` and calling `.split` would have thrown a
+        // 500 on the repeated form — a caller asking for two types the obvious way.
+        const { type } = req.query;
+        // IDs only: this is an existence check, and `sessionsDetail()` would load and parse every
+        // run's full unit detail to answer it — the same reason `/runs/:id/inject` uses `sessions()`.
+        const ids = await adapter.sessions();
+        if (!ids.includes(id)) {
+            return reply.code(404).send({ error: 'Run not found' });
+        }
+        const events = await adapter.runEvents(id);
+        if (events === null) {
+            // Same shape as the gate route's 503, and for the same reason: "no events" would report a
+            // missing binding as a fact about the run. The run may well have a rich history.
+            return reply.code(503).send({
+                error: 'Run history is unavailable: this wicked-core build has no event-log read binding',
+            });
+        }
+        // An empty array here is a real answer, not a failure: runs that predate the log have no
+        // history, and saying so is the honest response.
+        // Both spellings of "several types" mean the same thing: `?type=a,b` and `?type=a&type=b`.
+        // An empty filter (`?type=`, or only separators) is treated as NO filter rather than as a
+        // filter matching nothing — "show me events of no type" is not a question anyone asks, and
+        // answering it with an empty list looks identical to a run that recorded nothing.
+        const names = (Array.isArray(type) ? type : type === undefined ? [] : [type])
+            .flatMap((t) => t.split(','))
+            .map((t) => t.trim())
+            .filter(Boolean);
+        const wanted = names.length > 0 ? new Set(names) : null;
+        const filtered = wanted ? events.filter((e) => wanted.has(e.type)) : events;
+        return { runId: id, total: events.length, returned: filtered.length, events: filtered };
     });
     // ── Governance reads (crew#40) ──────────────────────────────────────────────
     app.get(`${V}/governance/policies`, async () => {
@@ -347,6 +649,32 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(400).send({ error: message(err) });
         }
     });
+    // Retire, not delete. The record survives so past decisions citing it stay explicable; it just
+    // stops being enforced (FINDING-038 — a mis-authored policy otherwise denied forever).
+    app.delete(`${V}/governance/policies/:id`, async (req, reply) => {
+        const { id } = req.params;
+        try {
+            const existed = await adapter.retirePolicy(id);
+            if (!existed)
+                return reply.code(404).send({ error: `policy '${id}' not found` });
+            return { status: 'retired', id };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: message(err) });
+        }
+    });
+    app.delete(`${V}/governance/rules/:id`, async (req, reply) => {
+        const { id } = req.params;
+        try {
+            const existed = await adapter.retireConformanceRule(id);
+            if (!existed)
+                return reply.code(404).send({ error: `conformance rule '${id}' not found` });
+            return { status: 'retired', id };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: message(err) });
+        }
+    });
     app.get(`${V}/governance/rules/preview`, async (req, reply) => {
         const q = req.query;
         try {
@@ -434,16 +762,31 @@ export function registerRoutes(app, adapter, gateCache) {
         const repo = repos.find((r) => r.id === id);
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
-        const graphPath = join(repo.root_path, '.wicked-estate', 'requirements', 'requirements_graph.json');
-        const dbPath = join(repo.root_path, '.codegraph', 'estate.db');
+        const graphPath = requirementsGraph(repo);
+        const dbPath = codeGraphDb(repo);
         // Coverage from the live estate store — computed by wicked-core governance layer.
         let coverage = null;
         if (existsSync(dbPath)) {
             try {
-                const { stdout } = await execFileAsync(process.env['WICKED_CORE_EXE'] ?? 'wicked-core', ['coverage', '--db', dbPath, '--json'], { timeout: 20_000, cwd: repo.root_path });
+                const { stdout } = await execCapped(process.env['WICKED_CORE_EXE'] ?? 'wicked-core', ['coverage', '--db', dbPath, '--json'], { timeout: 20_000, cwd: repo.root_path });
                 coverage = JSON.parse(stdout);
             }
-            catch { /* store not yet indexed — coverage stays null */ }
+            catch (err) {
+                // The bare `catch {}` here claimed "store not yet indexed" for EVERY failure — a comment
+                // asserting a diagnosis the code never checked. An output overflow, a timeout and a missing
+                // binary all became a silent null, so the panel showed "no coverage" for reasons that are
+                // not the same problem and do not have the same fix (FINDING-016, and FINDING-050's shape:
+                // distinct causes collapsed into one outcome).
+                //
+                // Coverage stays optional — this endpoint must not 500 because the store is not indexed yet,
+                // which is a legitimate and common state. But a cause that is NOT that gets said out loud.
+                if (err instanceof ExecOutputTooLarge) {
+                    req.log.warn({ err: err.message }, 'coverage output exceeded the buffer cap');
+                }
+                else if (!(err instanceof SyntaxError)) {
+                    req.log.debug({ err: message(err) }, 'coverage unavailable');
+                }
+            }
         }
         try {
             const content = await fsp.readFile(graphPath, 'utf8');
@@ -458,20 +801,112 @@ export function registerRoutes(app, adapter, gateCache) {
     // ── Repo code graph (via wicked-estate graph-view) ──────────────────────────
     // Delegates to the estate CLI so the query goes through the proper service
     // layer (store-seam aware, overlay edges included). Postgres-safe.
+    // ── Requirements management (server-side search over requirements_graph.json +
+    //    operator overrides sidecar; see api/requirements.ts) ─────────────────────
+    const ReqQuerySchema = z.object({
+        q: z.string().optional(),
+        risk: z.enum(['risk', 'no-risk']).optional(),
+        category: z.enum(['functional', 'config-data']).optional(),
+        domain: z.string().optional(),
+        offset: z.coerce.number().int().min(0).default(0),
+        limit: z.coerce.number().int().min(1).max(200).default(50),
+    }).strict();
+    app.get(`${V}/repos/:id/requirements`, async (req, reply) => {
+        const { id } = req.params;
+        const repos = await adapter.listRepos();
+        const repo = repos.find((r) => r.id === id);
+        if (!repo)
+            return reply.code(404).send({ error: `Repo ${id} not found` });
+        const parsed = ReqQuerySchema.safeParse(req.query);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid query'));
+        }
+        const page = await listRequirements(repo, parsed.data);
+        if (page === null) {
+            return reply.code(404).send({ error: 'requirements_graph.json not generated for this repo yet' });
+        }
+        return page;
+    });
+    app.get(`${V}/repos/:id/requirements/:key`, async (req, reply) => {
+        const { id, key } = req.params;
+        const repos = await adapter.listRepos();
+        const repo = repos.find((r) => r.id === id);
+        if (!repo)
+            return reply.code(404).send({ error: `Repo ${id} not found` });
+        let decoded;
+        try {
+            decoded = decodeURIComponent(key);
+        }
+        catch {
+            return reply.code(400).send({ error: 'Malformed requirement key encoding' });
+        }
+        const detail = await getRequirement(repo, decoded);
+        if (detail === null)
+            return reply.code(404).send({ error: 'Requirement not found' });
+        return { requirement: detail };
+    });
+    const ReqPatchSchema = z
+        .object({
+        title: z.string().min(1).max(500).optional(),
+        notes: z.string().max(5000).optional(),
+        status: z.enum(['active', 'deprecated', 'review']).optional(),
+        risk: z.boolean().optional(),
+    })
+        .strict()
+        // `.strict()` BEFORE `.refine()`: the refine runs on the parsed object, so with stripping still
+        // in effect `{"title":"x","note":"y"}` would pass the non-empty check having silently discarded
+        // the edit the caller cared about. Every field here is optional, which is exactly the shape
+        // FINDING-031 makes dangerous.
+        .refine((b) => Object.keys(b).length > 0, { message: 'empty patch' });
+    app.patch(`${V}/repos/:id/requirements/:key`, async (req, reply) => {
+        const { id, key } = req.params;
+        const repos = await adapter.listRepos();
+        const repo = repos.find((r) => r.id === id);
+        if (!repo)
+            return reply.code(404).send({ error: `Repo ${id} not found` });
+        const parsed = ReqPatchSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid patch'));
+        }
+        let decodedKey;
+        try {
+            decodedKey = decodeURIComponent(key);
+        }
+        catch {
+            return reply.code(400).send({ error: 'Malformed requirement key encoding' });
+        }
+        const detail = await patchRequirement(repo, decodedKey, parsed.data);
+        if (detail === null)
+            return reply.code(404).send({ error: 'Requirement not found' });
+        return { requirement: detail };
+    });
     app.get(`${V}/repos/:id/graph`, async (req, reply) => {
         const { id } = req.params;
         const repos = await adapter.listRepos();
         const repo = repos.find((r) => r.id === id);
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
-        const dbPath = join(repo.root_path, '.codegraph', 'estate.db');
+        const dbPath = codeGraphDb(repo);
         if (!existsSync(dbPath)) {
             return reply.send({ graph: null });
         }
         try {
             const settings = await adapter.getSettings();
-            const nodeLimit = String(settings.graphNodeLimit);
-            const { stdout } = await execFileAsync('wicked-estate', ['graph-view', '--limit', nodeLimit, '--db', dbPath], { timeout: 30_000, cwd: repo.root_path });
+            const q = req.query;
+            const parsedLimit = q.limit !== undefined ? Number.parseInt(q.limit, 10) : NaN;
+            const nodeLimit = String(Number.isFinite(parsedLimit) && parsedLimit > 0 && parsedLimit <= 1000
+                ? parsedLimit
+                : settings.graphNodeLimit);
+            const args = ['graph-view', '--limit', nodeLimit, '--db', dbPath];
+            // FOCUS (ego-graph) mode: seed the slice from one symbol and expand its
+            // neighbourhood — the navigation primitive (estate graph-view --focus).
+            if (q.focus !== undefined && q.focus.trim() !== '') {
+                args.push('--focus', q.focus.trim());
+            }
+            const { stdout } = await execCapped('wicked-estate', args, {
+                timeout: 30_000,
+                cwd: repo.root_path,
+            });
             const raw = JSON.parse(stdout);
             const fileCount = new Set(raw.nodes.map((n) => n.file)).size;
             return reply.send({
@@ -487,6 +922,31 @@ export function registerRoutes(app, adapter, gateCache) {
         }
     });
     // ── 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".
+    app.get(`${V}/repos/:id/graph/blast-radius`, async (req, reply) => {
+        const { id } = req.params;
+        const q = req.query;
+        if (q.name === undefined || q.name.trim() === '') {
+            return reply.code(400).send({ error: 'name query parameter required' });
+        }
+        const repos = await adapter.listRepos();
+        const repo = repos.find((r) => r.id === id);
+        if (!repo)
+            return reply.code(404).send({ error: `Repo ${id} not found` });
+        const dbPath = codeGraphDb(repo);
+        if (!existsSync(dbPath)) {
+            return reply.code(404).send({ error: 'Code graph not built for this repo yet' });
+        }
+        try {
+            const { stdout } = await execCapped('wicked-estate', ['blast-radius', q.name.trim(), '--db', dbPath, '--json'], { timeout: 30_000, cwd: repo.root_path });
+            return reply.send(JSON.parse(stdout));
+        }
+        catch (err) {
+            return reply.code(500).send({ error: message(err) });
+        }
+    });
     app.get(`${V}/repos/:id/git-history`, async (req, reply) => {
         const { id } = req.params;
         const repos = await adapter.listRepos();
@@ -494,7 +954,7 @@ export function registerRoutes(app, adapter, gateCache) {
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
         try {
-            const { stdout } = await execFileAsync('git', ['log', '--pretty=format:%H\x1f%h\x1f%s\x1f%an\x1f%ar', '-n', '20'], { timeout: 10_000, cwd: repo.root_path });
+            const { stdout } = await execCapped('git', ['log', '--pretty=format:%H\x1f%h\x1f%s\x1f%an\x1f%ar', '-n', '20'], { timeout: 10_000, cwd: repo.root_path });
             const commits = stdout.trim().split('\n').filter(Boolean).map((line) => {
                 const parts = line.split('\x1f');
                 return {
@@ -526,7 +986,7 @@ export function registerRoutes(app, adapter, gateCache) {
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
         try {
-            const { stdout } = await execFileAsync('git', ['shortlog', '-sne', '-n', '--no-merges', 'HEAD'], { timeout: 10_000, cwd: repo.root_path });
+            const { stdout } = await execCapped('git', ['shortlog', '-sne', '-n', '--no-merges', 'HEAD'], { timeout: 10_000, cwd: repo.root_path });
             // Output: "  42\tFull Name <email@example.com>"
             const contributors = stdout.trim().split('\n').filter(Boolean).slice(0, 10).map((line) => {
                 const m = line.match(/^\s*(\d+)\s+(.+?)\s+<([^>]+)>/);
@@ -558,7 +1018,7 @@ export function registerRoutes(app, adapter, gateCache) {
     app.post(`${V}/terminals`, async (req, reply) => {
         const parsed = OpenTerminalSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         const b = parsed.data;
         try {
@@ -575,7 +1035,7 @@ export function registerRoutes(app, adapter, gateCache) {
         const { id } = req.params;
         const parsed = ResizeTerminalSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid request body'));
         }
         try {
             const status = await adapter.resizeTerminal(id, parsed.data.cols, parsed.data.rows);