wicked-crew 0.3.2 → 0.5.0

package/dist/api/routes.js

@@ -5,12 +5,16 @@ 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 { buildEvidenceBundle, evidenceFilename } from './evidence.js';
-const execFileAsync = promisify(execFile);
-const V = '/api/v1';
+import { ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError, humanGatePhaseIds } from '../core/adapter.js';
+import { codeGraphDb, requirementsGraph } from '../core/repoPaths.js';
+import { buildEvidenceBundle, coreUnitId, evidenceFilename } from './evidence.js';
+import { outputUnavailableReason, resolveUnit, unitKeysFor } from './unit-output.js';
+import { execCapped, ExecOutputTooLarge } from '../core/exec.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';
+import { API_PREFIX } from './api-prefix.js';
+const V = API_PREFIX;
 // 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
 // compiled module location (dist/api/routes.js → ../../package.json) and works the
@@ -33,6 +37,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._-]*$/;
@@ -49,6 +72,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;
@@ -56,6 +80,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(),
@@ -64,16 +101,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(),
@@ -82,16 +119,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();
@@ -111,7 +148,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 {
@@ -162,7 +199,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 = {
@@ -188,10 +225,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.
@@ -203,25 +242,137 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(404).send({ error: 'Run not found' });
         return { run };
     });
-    // 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) });
+        }
+    });
+    // A unit's captured transcript. `unitKey` accepts the fully-qualified id (`run-1:survey`),
+    // the id suffix (`survey`, `u3`), or the ordinal (`u3`, `3`) — see `resolveUnit`.
+    //
+    // A `null` body is never bare here. An unknown run or an unknown key is a 404 that names the
+    // keys this run does have; a unit that exists but has no stored transcript answers 200 with
+    // `outputUnavailable` saying WHICH cause applies — denied, not finished, or a store that
+    // disagrees with itself. It previously answered `200 {"output": null}` to all four, so the
+    // failed unit an operator opens during triage was the one that told them nothing (FINDING-006).
     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;
-        const output = await adapter.workOutput(`${id}:${suffix}`);
-        return reply.send({ output });
+        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 unit = resolveUnit(run, unitKey);
+        if (!unit) {
+            return reply.code(404).send({
+                error: `Unit '${unitKey}' not found in run ${id}`,
+                units: unitKeysFor(run),
+            });
+        }
+        // Keyed off the unit RECORD (the same derivation the evidence bundle uses), not off the
+        // caller's path segment — the two disagreeing is what made a resolvable unit unreadable.
+        const output = await adapter.workOutput(coreUnitId(id, unit));
+        if (output !== null)
+            return reply.send({ output });
+        return reply.send({ output: null, outputUnavailable: outputUnavailableReason(unit) });
     });
     // 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);
@@ -231,7 +382,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);
@@ -290,7 +441,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))
@@ -303,14 +454,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 () => {
@@ -325,10 +650,54 @@ export function registerRoutes(app, adapter, gateCache) {
         const claims = await adapter.listConformanceClaims();
         return { claims };
     });
-    app.get(`${V}/governance/coverage`, async () => {
+    // Normalize a `?repo=` query: Fastify parses a repeated `?repo=a&repo=b` into a `string[]` (take
+    // the first), and the value is TRIMMED so it's both validated and PASSED trimmed — a `?repo=%20x%20`
+    // must not pass the guard then miss the registry lookup on whitespace (Copilot #227).
+    const repoParam = (req) => {
+        const raw = req.query?.repo;
+        const first = Array.isArray(raw) ? raw[0] : raw;
+        const trimmed = first?.trim();
+        return trimmed ? trimmed : undefined;
+    };
+    // An unknown repo is the CALLER's error (404); a binding/parse failure is OURS (500). Don't collapse
+    // them (Copilot #227). Core spells the not-found case `no registered repo '<ref>'`.
+    const repoReadStatus = (msg) => (/no registered repo/i.test(msg) ? 404 : 500);
+    app.get(`${V}/governance/coverage`, async (req, reply) => {
+        // FINDING-009: with `?repo=<ref>`, report coverage over THAT repo's own code graph. The bare
+        // endpoint reads the daemon store and reports a vacuous `coverage: 1.0` that names no repo — the
+        // real gate lives per-repo. An unknown repo is an ERROR in core (never a silent vacuous report).
+        const repo = repoParam(req);
+        if (repo) {
+            try {
+                const report = await adapter.getCoverageReportForRepo(repo);
+                return { report };
+            }
+            catch (err) {
+                const msg = message(err);
+                return reply.code(repoReadStatus(msg)).send({ error: msg });
+            }
+        }
         const report = await adapter.getCoverageReport();
         return { report };
     });
+    app.get(`${V}/governance/graph`, async (req, reply) => {
+        // #122: node-count-by-kind summary of a repo's OWN code graph. Repo-scoped ONLY — there is no
+        // meaningful daemon-wide graph view (the daemon store holds run/governance nodes, not a repo's
+        // code graph), so a missing `?repo=` is a 400, an unknown repo a 404, and an engine/binding
+        // failure a 500 (not masked as 404).
+        const repo = repoParam(req);
+        if (!repo) {
+            return reply.code(400).send({ error: 'governance/graph requires a ?repo=<ref>' });
+        }
+        try {
+            const kinds = await adapter.getGraphKindsForRepo(repo);
+            return { kinds };
+        }
+        catch (err) {
+            const msg = message(err);
+            return reply.code(repoReadStatus(msg)).send({ error: msg });
+        }
+    });
     // ── Governance writes (crew#42) ────────────────────────────────────────────
     app.post(`${V}/governance/policies`, async (req, reply) => {
         try {
@@ -348,6 +717,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 {
@@ -368,7 +763,9 @@ export function registerRoutes(app, adapter, gateCache) {
         const workflow = adapter.getWorkflow(id);
         if (!workflow)
             return reply.code(404).send({ error: `workflow '${id}' not found` });
-        return { workflow };
+        // humanGates: the phases that will PAUSE for a person even under humanConfirm:none (core#208).
+        // Surfaced so an operator can see a workflow's gates BEFORE launching it (FINDING-023).
+        return { workflow, humanGates: humanGatePhaseIds(workflow) };
     });
     // Register (or replace) a user-authored workflow definition.
     // Validates, persists to ~/.wicked/workflows/<id>.json, hot-registers in the
@@ -435,16 +832,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');
@@ -468,7 +880,7 @@ export function registerRoutes(app, adapter, gateCache) {
         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();
@@ -477,9 +889,9 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(404).send({ error: `Repo ${id} not found` });
         const parsed = ReqQuerySchema.safeParse(req.query);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid query', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid query'));
         }
-        const page = await listRequirements(repo.root_path, parsed.data);
+        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' });
         }
@@ -498,7 +910,7 @@ export function registerRoutes(app, adapter, gateCache) {
         catch {
             return reply.code(400).send({ error: 'Malformed requirement key encoding' });
         }
-        const detail = await getRequirement(repo.root_path, decoded);
+        const detail = await getRequirement(repo, decoded);
         if (detail === null)
             return reply.code(404).send({ error: 'Requirement not found' });
         return { requirement: detail };
@@ -510,6 +922,11 @@ export function registerRoutes(app, adapter, gateCache) {
         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;
@@ -519,7 +936,7 @@ export function registerRoutes(app, adapter, gateCache) {
             return reply.code(404).send({ error: `Repo ${id} not found` });
         const parsed = ReqPatchSchema.safeParse(req.body);
         if (!parsed.success) {
-            return reply.code(400).send({ error: 'Invalid patch', details: parsed.error.issues });
+            return reply.code(400).send(invalidBody(parsed.error, 'Invalid patch'));
         }
         let decodedKey;
         try {
@@ -528,7 +945,7 @@ export function registerRoutes(app, adapter, gateCache) {
         catch {
             return reply.code(400).send({ error: 'Malformed requirement key encoding' });
         }
-        const detail = await patchRequirement(repo.root_path, decodedKey, parsed.data);
+        const detail = await patchRequirement(repo, decodedKey, parsed.data);
         if (detail === null)
             return reply.code(404).send({ error: 'Requirement not found' });
         return { requirement: detail };
@@ -539,7 +956,7 @@ 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 dbPath = join(repo.root_path, '.codegraph', 'estate.db');
+        const dbPath = codeGraphDb(repo);
         if (!existsSync(dbPath)) {
             return reply.send({ graph: null });
         }
@@ -556,7 +973,7 @@ export function registerRoutes(app, adapter, gateCache) {
             if (q.focus !== undefined && q.focus.trim() !== '') {
                 args.push('--focus', q.focus.trim());
             }
-            const { stdout } = await execFileAsync('wicked-estate', args, {
+            const { stdout } = await execCapped('wicked-estate', args, {
                 timeout: 30_000,
                 cwd: repo.root_path,
             });
@@ -588,12 +1005,12 @@ 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 dbPath = join(repo.root_path, '.codegraph', 'estate.db');
+        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 execFileAsync('wicked-estate', ['blast-radius', q.name.trim(), '--db', dbPath, '--json'], { timeout: 30_000, cwd: repo.root_path });
+            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) {
@@ -607,7 +1024,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 {
@@ -639,7 +1056,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+<([^>]+)>/);
@@ -671,7 +1088,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 {
@@ -688,7 +1105,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);