wicked-crew 0.7.28 → 0.7.30

package/dist/api/routes.js

@@ -6,7 +6,7 @@ import { promises as fsp } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CampaignsUnsupportedError, ChatUnsupportedError, CoreAdapter, ElicitationUnsupportedError, SteeringUnsupportedError, humanGatePhaseIds } from '../core/adapter.js';
-import { codeGraphDb, requirementsGraph } from '../core/repoPaths.js';
+import { codeGraphDb, codeGraphErrorStatus, requirementsGraph } from '../core/repoPaths.js';
 import { resolveCursorUnit } from '../core/cursor.js';
 import { detectRefusal } from './gate-cache.js';
 import { QeGateCache } from '../qe/gate-events.js';
@@ -17,6 +17,8 @@ import { execCapped, ExecOutputTooLarge } from '../core/exec.js';
 import { callEstateTool, EstateMcpError } from '../core/estate-mcp-client.js';
 import { SeatHealthTracker } from './seat-health.js';
 import { applyWorkerConfigRoot, signedInHeuristic } from './seat-signin.js';
+import { chatSeatAdmission, seatStanding } from './seat-standing.js';
+import { ChatScopeIndex, chatScopeDeps, prepareChatScratch, removeChatScratch, resolveChatScope, } from './chat-scope.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';
@@ -30,6 +32,7 @@ import { registerSkillsRoutes } from './skills.js';
 import { disabledSkillsHealth } from '../skills/runtime.js';
 import { ProjectSettingsStore } from '../projects/settings.js';
 import { boundOrigin, InteractiveBridgePool } from '../interactive/bridge-pool.js';
+import { composeDeliverText, factsFromRun, framedDeliverText, runUrlFor } from '../core/deliver-text.js';
 import { registerInteractiveProxy } from '../interactive/proxy-routes.js';
 import { registerInteractiveDocDelete } from '../interactive/doc-delete-routes.js';
 import { registerInteractiveDocList } from '../interactive/doc-list-routes.js';
@@ -37,6 +40,8 @@ import { MembershipIndex } from '../projects/membership-index.js';
 import { MEMBERSHIP_ATTACHED, membershipAttachedKey } from '../projects/events.js';
 import { AuditLog } from './audit.js';
 import { AcpFoldCache, EngineVersionCache, eventsDirOf, installedPackageVersion, listStoreFiles, readStudioBundleVersion, } from './diagnostics.js';
+import { GovernanceDiagnostics } from './governance-health.js';
+import { legacyHomeOutboxPath } from '../core/governance-store.js';
 import { RetryIndex } from './retry-index.js';
 import { GroupIndex } from './group-index.js';
 import { RunTimingIndex, recordRunLaunched } from './run-timing-index.js';
@@ -69,6 +74,18 @@ const STATUS_ORDER = {
 function sortActionableFirst(views) {
     return [...views].sort((a, b) => (STATUS_ORDER[a.session.status] ?? 9) - (STATUS_ORDER[b.session.status] ?? 9));
 }
+function codeGraphDbOr503(repo, reply) {
+    try {
+        return codeGraphDb(repo);
+    }
+    catch (err) {
+        const status = codeGraphErrorStatus(err);
+        if (status === null)
+            throw err;
+        void reply.code(status).send({ error: message(err) });
+        return null;
+    }
+}
 function message(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -411,6 +428,21 @@ 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`.
  */
+/**
+ * `POST /chats` body (crew#165; `projectId` DES-PROJECT-001 §2.2; `repoRefs` + scope semantics
+ * crew#502). Exported for the wire-contract drift guard (`tests/wire-contract.test.ts`).
+ */
+export 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(),
+    /** One repo in scope — the legacy spelling, merged into `repoRefs` (crew#502). */
+    repoRef: z.string().min(1).optional(),
+    /** The repos in scope, by registry id or name (crew#502). */
+    repoRefs: z.array(z.string().min(1)).min(1).max(32).optional(),
+    /** File the chat into a project (`crew.chat` membership) — and, with no `repoRefs`, scope it to
+     *  every registered `crew.repo` member of that project (crew#502). */
+    projectId: z.string().min(1).optional(),
+}).strict();
 export function registerRoutes(app, adapter, gateCache, elicitationCache, 
 // Defaulted so a caller that never arms the bus seam (tests drive this
 // function directly) gets the same behavior as an unarmed daemon: an empty
@@ -435,6 +467,7 @@ runtime = {}) {
     const groupIndex = runtime.groupIndex ?? new GroupIndex();
     const runTimingIndex = runtime.runTimingIndex ?? new RunTimingIndex();
     const guidanceIndex = runtime.guidanceIndex ?? new GuidanceIndex();
+    const chatScopes = runtime.chatScopes ?? new ChatScopeIndex();
     const deliveryIndex = runtime.deliveryIndex ?? new DeliveryIndex();
     const worktreeExists = runtime.worktreeExists ?? ((p) => existsSync(p));
     const vacuityProbes = {
@@ -457,6 +490,12 @@ runtime = {}) {
             isDelivered: (runId) => deliveryIndex.urlFor(runId) !== undefined,
         });
     const deliverExec = runtime.deliverExec ?? runDeliverScript;
+    // crew#524: the deliver phase's script asks THIS daemon for the run-derived PR text, and the PR
+    // body links the run here — so the adapter learns the bound origin lazily (the server has not
+    // listened yet when routes register). Guarded: directly-driven route sets hand in fakes.
+    if (typeof adapter.setDeliverApiOrigin === 'function') {
+        adapter.setDeliverApiOrigin(() => boundOrigin(app.server.address()));
+    }
     const reprovisionWorktree = runtime.reprovisionWorktree ?? gitReprovisionWorktree;
     // The estate MCP client behind `/proposals*` AND `/memory*` (DES-MEM-FACETED-001) — one seam. The
     // default is the real spawn-per-call `wicked-estate-mcp` client; route tests inject a stub so no
@@ -572,16 +611,22 @@ runtime = {}) {
     // can never turn this GET into an event-log re-reader or a `--version` spawner per request.
     const acpFoldCache = new AcpFoldCache();
     const engineVersionCache = new EngineVersionCache();
+    // The governance block (crew#495): the store the engine's emit seam writes to (as the adapter
+    // exported it — `null` on a boot that resolved none), its record count through the engine
+    // binding when the addon has one, and the dead-letter outbox folded on change. Built at boot so
+    // the record baseline is the boot baseline.
+    const governanceDiagnostics = new GovernanceDiagnostics(adapter.governanceStore ?? null, CoreAdapter.eventStoreCounter(), runtime.governanceLegacyOutboxPath === undefined ? legacyHomeOutboxPath() : runtime.governanceLegacyOutboxPath);
     app.get(`${V}/diagnostics`, { config: { manifest: { responseType: 'DiagnosticsResponse', statusCodes: [200] } } }, async () => {
         // `dbPath` is a readonly field of the real adapter; a stub-driven route set may lack it,
         // and diagnostics over an unknown store honestly reports no stores and no ACP record.
         const dbPath = typeof adapter.dbPath === 'string' && adapter.dbPath !== '' ? adapter.dbPath : null;
-        const [stores, byCli, engineBinaries] = await Promise.all([
+        const [stores, byCli, engineBinaries, governance] = await Promise.all([
             dbPath !== null ? listStoreFiles(dbPath) : Promise.resolve([]),
             dbPath !== null
                 ? acpFoldCache.get(eventsDirOf(dbPath))
                 : Promise.resolve({}),
             engineVersionCache.get(),
+            governanceDiagnostics.health(),
         ]);
         const uptimeMs = Math.round(process.uptime() * 1000);
         const addr = app.server.address();
@@ -601,6 +646,9 @@ runtime = {}) {
             // config-error, with the `skills.*` findings the ladder produced — the operator's one
             // read-only answer to "why do launches refuse the snapshot".
             skills: runtime.skills?.health() ?? disabledSkillsHealth(),
+            // Is the governance evidence LANDING (crew#495): the store, the records on it, the dead
+            // letters — with a `governance.deadletter` finding the moment the outbox holds one.
+            governance,
         };
     });
     // Who am I talking to the daemon as? (task #88). In local mode this is
@@ -653,16 +701,29 @@ runtime = {}) {
     // gains `signed_in`: the cheap file/env presence heuristic, computed against the LIVE
     // `WICKED_WORKER_HOME` env — the same value the engine reads at the next worker spawn, kept
     // current by `applyWorkerConfigRoot` at boot and on every settings change.
-    app.get(`${V}/roster`, async () => {
+    //
+    // Each seat ALSO carries its STANDING (F-2R2-009): `auth` re-reads `signed_in` for what it means
+    // (a `signed_out` codex is benched on its first ballot; a `not_required` opencode answers on its
+    // free tier), and `council_eligible` says what a council would do with the seat as far as the
+    // daemon can tell. `POST /chats` seats its defaults through the SAME standing, so the roster and
+    // the chat never disagree about a seat.
+    const rosterWithStanding = () => {
         const workerRoot = process.env['WICKED_WORKER_HOME'];
-        return {
-            roster: CoreAdapter.roster().map((seat) => ({
+        return CoreAdapter.roster().map((seat) => {
+            const key = String(seat.key);
+            const health = seatHealth.healthFor(key);
+            const signed = signedIn(key, workerRoot === '' ? undefined : workerRoot);
+            return {
                 ...seat,
-                health: seatHealth.healthFor(String(seat.key)),
-                signed_in: signedIn(String(seat.key), workerRoot === '' ? undefined : workerRoot),
-            })),
-        };
-    });
+                health,
+                signed_in: signed,
+                // The bench is THIS daemon's council evidence (councilSeatFailed, bounded window) — the
+                // prediction learns from what the engine actually did with the seat (#533 review, F-1).
+                ...seatStanding(seat, signed, health, seatHealth.councilBenchFor(key)),
+            };
+        });
+    };
+    app.get(`${V}/roster`, async () => ({ roster: rosterWithStanding() }));
     // Open a file/folder with the OS default application (crew#273) — the studio Files tab's
     // click-to-open. The open MUST happen daemon-side (the SPA cannot spawn a process), which is
     // why the path is validated first: absolute, and inside one of the caller-visible roots — the
@@ -1181,6 +1242,28 @@ runtime = {}) {
             return reply.code(404).send({ error: 'Run not found' });
         return { run: decorateRun(run) };
     });
+    /** The full workflow registry, or `[]` on a directly-driven route set whose fake adapter has none. */
+    const listWorkflowsSafe = () => typeof adapter.listWorkflows === 'function' ? adapter.listWorkflows() : [];
+    // ── Deliver text (crew#524 / F-3R2-014) — the PR title + body a run's delivery carries ──
+    // `gh pr create --fill` gave wicked-studio#249 a mid-word title and an EMPTY body. The deliver
+    // script now asks this route for the text composed from the PERSISTED RUN RECORD: the intent,
+    // `Fixes #N`, the run link, every phase with its seat and gate outcome, the repo checks with
+    // their exit codes, the evaluator verdict (`core/deliver-text.ts`). text/plain, FRAMED as line 1
+    // title, line 2 blank, then the body — the same shape the script's embedded fallback has, so the
+    // script parses exactly one thing. Read-only; the run's `deliver` unit is still running when it
+    // asks, and is listed as `this PR`.
+    app.get(`${V}/runs/:id/deliver-text`, { config: { manifest: { 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' });
+        const origin = boundOrigin(app.server.address());
+        // The workflow DEFINITION (a user-registered workflow's view carries the engine instance id).
+        const def = resolveRunWorkflow(run, listWorkflowsSafe());
+        const text = composeDeliverText(factsFromRun(decorateRun(run), runUrlFor(origin, id), { workflowId: def?.id ?? null }));
+        return reply.type('text/plain; charset=utf-8').send(framedDeliverText(text));
+    });
     // ── Post-hoc delivery (crew#393) — lift a stranded run's worktree into a PR ──
     // The recovery path for the run 83052f0b class: a COMPLETED repo-scoped run whose reviewable
     // work was never lifted (`delivery: 'stranded'` on the wire — including runs recorded long
@@ -1299,7 +1382,15 @@ runtime = {}) {
                         workdir = reprov.workdir;
                         cw = reprov.cleanup;
                     }
-                    result = await deliverExec(workdir, s.problem ?? undefined);
+                    // crew#524: the post-hoc lift composes its PR text from the run record it already
+                    // holds (the fallback), and names this daemon so the script can re-ask at delivery.
+                    const origin = boundOrigin(app.server.address());
+                    const def = resolveRunWorkflow(run, listWorkflowsSafe());
+                    result = await deliverExec(workdir, s.problem ?? undefined, {
+                        runId: id,
+                        apiOrigin: origin,
+                        facts: factsFromRun(run, runUrlFor(origin, id), { workflowId: def?.id ?? null }),
+                    });
                 }
                 finally {
                     if (cw !== null)
@@ -1394,28 +1485,27 @@ runtime = {}) {
     // ── 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(),
-        /** DES-PROJECT-001 §2.2 — file the chat into a project (`crew.chat` membership). */
-        projectId: z.string().min(1).optional(),
-    }).strict();
-    app.post(`${V}/chats`, async (req, reply) => {
+    //
+    // A chat is SCOPED (crew#502, F-067): its seats run in a private scratch root — never a repo,
+    // never the daemon's cwd — with the scoped repos as read roots and, where a graph binds, the
+    // READ-ONLY estate MCP over it (the grounding governed runs get). The scope is resolved and
+    // validated BEFORE any seat warms, stated to the seats in the scratch root's AGENTS.md /
+    // CLAUDE.md, and returned as `scope` (see `chat-scope.ts`).
+    app.post(`${V}/chats`, {
+        config: {
+            manifest: {
+                requestType: 'ChatOpenBody',
+                responseType: 'ChatOpenResponse',
+                statusCodes: [201, 400, 404, 409, 500, 501],
+            },
+        },
+    }, 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;
-        }
         // Validate the project BEFORE opening seats: a chat has no launch record for the engine to
         // attach against atomically (chats are an in-memory seat pool), so the route validates
         // up-front and attaches right after open — the one non-atomic attach, documented in the ADR
@@ -1436,32 +1526,205 @@ runtime = {}) {
                 return reply.code(501).send({ error: message(err) });
             }
         }
-        const clis = b.clis ??
-            CoreAdapter.roster()
-                .map((s) => s.key)
-                .filter((k) => typeof k === 'string');
+        // A chat id this daemon already holds a scope for is LIVE: re-preparing its scratch root and
+        // re-opening it would overwrite the statement its seats are reading and (on a changed scope)
+        // evict them mid-conversation (Copilot, #518). Close it first, or let the daemon mint the id.
+        const token = chatScopes.reserve(chatId);
+        if (token === null) {
+            const state = chatScopes.stateOf(chatId);
+            return reply.code(409).send({
+                error: state === 'closing'
+                    ? `chat ${chatId} is closing; wait for its chatClosed (a few seconds at most) before reusing the id, or omit chatId to mint a fresh one`
+                    : `chat ${chatId} is already open on this daemon; DELETE /chats/${chatId} first, or omit chatId to mint a fresh one`,
+            });
+        }
+        // Everything below either ends in `chatScopes.set(chatId, …, token)` or releases the reservation.
         try {
-            const seats = await adapter.chatOpen(chatId, clis, cwd);
-            if (b.projectId !== undefined) {
-                try {
-                    const { member, created } = await adapter.projectMemberAttach(b.projectId, 'crew.chat', chatId);
-                    if (created) {
-                        projects.index.set(chatId, b.projectId);
-                        projects.bus?.emit(MEMBERSHIP_ATTACHED, { project_id: b.projectId, member: { kind: 'crew.chat', ref: chatId }, actor: actorOf(req).id }, membershipAttachedKey(b.projectId, 'crew.chat', chatId, member.attached_at));
+            // The scope (crew#502): explicit repos (`repoRefs`, the legacy `repoRef` merged in) or the
+            // project's members — each ref checked against the registry, EVERY missing one named — else
+            // none. Resolved before any seat warms: a 404 here warmed nothing.
+            const resolution = await resolveChatScope({
+                chatId,
+                ...(b.projectId !== undefined ? { projectId: b.projectId } : {}),
+                repoRefs: [...(b.repoRef !== undefined ? [b.repoRef] : []), ...(b.repoRefs ?? [])],
+            }, { ...chatScopeDeps(adapter), scratchBase: chatScopes.base, log: (m) => req.log.warn(m) });
+            if (!resolution.ok) {
+                chatScopes.release(chatId, token);
+                return reply.code(resolution.status).send({
+                    error: resolution.error,
+                    ...(resolution.missing !== undefined ? { missing: resolution.missing } : {}),
+                });
+            }
+            const { scope, engine } = resolution;
+            try {
+                // Cleans up only what it created itself on failure (Copilot, #518).
+                prepareChatScratch(chatId, scope);
+            }
+            catch (err) {
+                chatScopes.release(chatId, token);
+                return reply
+                    .code(500)
+                    .send({ error: `cannot prepare the chat's scratch root ${scope.cwd}: ${message(err)}` });
+            }
+            // The DEFAULT seats are the roster seats the daemon's own admission admits (F-2R2-007,
+            // F-2R2-009): the seat's auth standing (a signed-out seat is refused up front, with the
+            // reason, instead of failing its first turn — the same predicate `GET /roster` reports as
+            // `council_eligible`) and, for a SCOPED chat, the engine's rule restated (only a seat whose
+            // ACP adapter asks permissions or whose record arms the kernel write floor can be held to
+            // read-only roots — with the default roster that is claude and opencode). Every seat dropped
+            // here is NAMED on the response (`refused`) and in the thread (`chatSeatRefused`), so a
+            // person can see why pi is missing. Explicit `clis` are passed through as asked; the engine
+            // refuses per seat with its reason, which is copied into `refused` too.
+            const scoped = scope.kind !== 'none';
+            const refused = [];
+            let clis;
+            if (b.clis !== undefined) {
+                clis = b.clis;
+            }
+            else {
+                clis = [];
+                for (const seat of rosterWithStanding()) {
+                    const key = String(seat.key);
+                    const admission = chatSeatAdmission(seat, seat.auth ?? 'unknown', scoped);
+                    if (admission.ok)
+                        clis.push(key);
+                    else
+                        refused.push({ cliKey: key, reason: admission.reason });
+                }
+            }
+            if (clis.length === 0) {
+                chatScopes.release(chatId, token);
+                removeChatScratch(scope.cwd, chatScopes.base);
+                return reply.code(409).send({
+                    error: (scoped
+                        ? 'no seat in the roster can be held to a scoped chat (an ACP adapter admitted to input ' +
+                            'governance, or `os_sandbox = true` on its [cli.acp] record) and take a turn; open the ' +
+                            'chat unscoped, sign a seat in, or name seats with `clis`'
+                        : 'no seat in the roster can take a turn (every seat is signed out); sign a seat in from ' +
+                            'the System page, or name seats with `clis`') + ' — see refused',
+                    refused,
+                });
+            }
+            try {
+                const seats = await adapter.chatOpen(chatId, clis, engine.cwd, {
+                    codeGraphDb: engine.codeGraphDb,
+                    readRoots: engine.readRoots,
+                });
+                // A REQUESTED seat the engine refused joins the same list, with the engine's reason.
+                for (const s of seats) {
+                    if (!s.ok)
+                        refused.push({ cliKey: s.cliKey, reason: s.error ?? 'the engine refused the seat' });
+                }
+                // Nothing warmed (independent review, W1): the engine holds no pool row and has dropped the
+                // scope itself (no `chatClosed` will come) — report the PER-SEAT reasons, never an
+                // engine-version guess; the root goes, the id is free again.
+                if (seats.every((s) => !s.ok)) {
+                    chatScopes.release(chatId, token);
+                    removeChatScratch(scope.cwd, chatScopes.base);
+                    return reply.code(409).send({
+                        error: `chat ${chatId}: no seat warmed (${seats.length} failed) — see seats`,
+                        seats,
+                        refused,
+                    });
+                }
+                // Honest scope (Copilot, #518): a SCOPED chat is a promise — the roots are read-only, the
+                // graph is attached, the seats see nothing else — and only an engine that CONFIRMS it
+                // recorded the scope (its `chatList` row carries the scope fields) can keep it. An engine
+                // predating chat scope (wicked-core#410) dropped `scopeJson` and runs the seats unbounded in
+                // the scratch root; an engine that cannot be asked has confirmed nothing. Neither may hold a
+                // scoped chat: it is closed again, its root removed, and the caller gets a 501 naming the
+                // remedy — never a chat whose statement promises what its seats do not enforce. An UNSCOPED
+                // chat (`kind: 'none'`) promises nothing beyond its scratch root and proceeds.
+                const applied = await adapter.chatScopeApplied(chatId);
+                if (applied !== true && scoped) {
+                    await adapter.chatClose(chatId).catch(() => undefined);
+                    // The engine's `chatClosed` for this id is still on its way: park, do not release
+                    // (Copilot, #518), so a reuse cannot have its root removed by the late event.
+                    chatScopes.abortToClosing(chatId, token);
+                    removeChatScratch(scope.cwd, chatScopes.base);
+                    if (applied === false) {
+                        // A row WITHOUT the scope fields: the engine predates chat scope (wicked-core#410).
+                        return reply.code(501).send({
+                            error: 'the installed wicked-core-ts predates chat scope (wicked-core#410): it cannot ground ' +
+                                'a scoped chat or hold its read roots read-only — upgrade the engine, or open the ' +
+                                'chat without projectId/repoRefs.',
+                            seats,
+                        });
                     }
+                    // NO row although a seat reported warm: nothing is actually held for this chat.
+                    return reply.code(409).send({
+                        error: `chat ${chatId}: a seat reported warm but the engine holds no row for the chat — ` +
+                            'nothing warmed; open it again (see seats)',
+                        seats,
+                    });
                 }
-                catch (err) {
-                    // The chat is open and usable; the filing failed. Say so instead of failing the open —
-                    // the caller can re-attach via POST /projects/:id/members.
-                    return reply
-                        .code(201)
-                        .send({ chatId, seats, projectAttachError: message(err) });
+                // File the chat into its project WHILE the id is still reserved (Copilot, #518): publishing
+                // first would let a concurrent DELETE / engine `chatClosed` land during this await and leave
+                // a 201 with a stale scope and a membership attached to a closed chat.
+                let projectAttachError;
+                let attachedMemberId;
+                if (b.projectId !== undefined) {
+                    try {
+                        const { member, created } = await adapter.projectMemberAttach(b.projectId, 'crew.chat', chatId);
+                        if (created)
+                            attachedMemberId = member.id;
+                        if (created) {
+                            projects.index.set(chatId, b.projectId);
+                            projects.bus?.emit(MEMBERSHIP_ATTACHED, { project_id: b.projectId, member: { kind: 'crew.chat', ref: chatId }, actor: actorOf(req).id }, membershipAttachedKey(b.projectId, 'crew.chat', chatId, member.attached_at));
+                        }
+                    }
+                    catch (err) {
+                        // The chat is open and usable; the filing failed. Said on the 201 rather than failing
+                        // the open — the caller can re-attach via POST /projects/:id/members.
+                        projectAttachError = message(err);
+                    }
+                }
+                if (!chatScopes.set(chatId, scope, token)) {
+                    // The reservation was cancelled while the open was in flight — an engine `chatClosed` or a
+                    // `DELETE` for this id (Copilot, #518). Nothing was recorded; tear the chat down (engine
+                    // session, scratch root, and the filing just made) instead of returning a stale 201.
+                    await adapter.chatClose(chatId).catch(() => undefined);
+                    removeChatScratch(scope.cwd, chatScopes.base);
+                    if (b.projectId !== undefined && attachedMemberId !== undefined) {
+                        await adapter.projectMemberDetach(b.projectId, attachedMemberId).catch(() => false);
+                        projects.index.delete(chatId);
+                    }
+                    return reply.code(409).send({
+                        error: `chat ${chatId} was closed while it was being opened; open it again`,
+                    });
                 }
+                // The thread learns of every refused seat the way it learns of everything else — a frame
+                // on /ws — AFTER the scope is published, so a reader never sees a refusal for a chat it
+                // cannot yet look up.
+                for (const r of refused) {
+                    runtime.broadcast?.({
+                        type: 'chatSeatRefused',
+                        chat: chatId,
+                        cliKey: r.cliKey,
+                        reason: r.reason,
+                        ...(b.projectId !== undefined ? { project_id: b.projectId } : {}),
+                    });
+                }
+                return reply.code(201).send({
+                    chatId,
+                    seats,
+                    scope,
+                    refused,
+                    ...(projectAttachError !== undefined ? { projectAttachError } : {}),
+                });
+            }
+            catch (err) {
+                // Nothing warmed: the scratch root prepared above must not linger — removed under the SAME
+                // base the resolver created it in (Copilot, #518), fail-closed like every removal.
+                chatScopes.release(chatId, token);
+                removeChatScratch(scope.cwd, chatScopes.base);
+                return reply.code(400).send({ error: message(err) });
             }
-            return reply.code(201).send({ chatId, seats });
         }
-        catch (err) {
-            return reply.code(400).send({ error: message(err) });
+        finally {
+            // A reservation that never became a scope (any early return above) must not pin the id —
+            // token-guarded, so a reservation that is no longer ours is left alone.
+            chatScopes.release(chatId, token);
         }
     });
     const ChatMessageSchema = z.object({
@@ -1488,7 +1751,7 @@ runtime = {}) {
     // 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) => {
+    app.get(`${V}/chats`, { config: { manifest: { responseType: 'ChatListResponse', statusCodes: [200, 400, 501] } } }, async (_req, reply) => {
         try {
             return { chats: await adapter.chatList() };
         }
@@ -1503,10 +1766,11 @@ runtime = {}) {
                 .send({ error: message(err) });
         }
     });
-    app.get(`${V}/chats/:id`, async (req, reply) => {
+    app.get(`${V}/chats/:id`, { config: { manifest: { responseType: 'ChatDetailResponse', statusCodes: [200, 400] } } }, async (req, reply) => {
         const { id } = req.params;
         try {
-            return { chatId: id, seats: await adapter.chatSeats(id) };
+            // The scope recorded at open (crew#502) — `null` for a chat this daemon did not open.
+            return { chatId: id, seats: await adapter.chatSeats(id), scope: chatScopes.get(id) ?? null };
         }
         catch (err) {
             return reply.code(400).send({ error: message(err) });
@@ -1514,6 +1778,10 @@ runtime = {}) {
     });
     app.delete(`${V}/chats/:id`, async (req, reply) => {
         const { id } = req.params;
+        // The scratch root goes with the chat at once, whether or not the engine still knew it
+        // (crew#502); the id stays parked until the engine's `chatClosed` is observed, so a delayed
+        // close can never land on a chat that reused it (Copilot, #518).
+        chatScopes.beginClose(id);
         try {
             await adapter.chatClose(id);
             return { ok: true };
@@ -2411,7 +2679,9 @@ runtime = {}) {
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
         const graphPath = requirementsGraph(repo);
-        const dbPath = codeGraphDb(repo);
+        const dbPath = codeGraphDbOr503(repo, reply);
+        if (dbPath === null)
+            return reply;
         // Coverage from the live estate store — computed by wicked-core governance layer.
         let coverage = null;
         if (existsSync(dbPath)) {
@@ -2469,7 +2739,17 @@ runtime = {}) {
         if (!parsed.success) {
             return reply.code(400).send(invalidBody(parsed.error, 'Invalid query'));
         }
-        const page = await listRequirements(repo, parsed.data);
+        let page;
+        try {
+            page = await listRequirements(repo, parsed.data);
+        }
+        catch (err) {
+            // wicked-core#406: a CURRENT engine with no repo-graph root is a 503, not a 500.
+            const status = codeGraphErrorStatus(err);
+            if (status === null)
+                throw err;
+            return reply.code(status).send({ error: message(err) });
+        }
         if (page === null) {
             return reply.code(404).send({ error: 'requirements_graph.json not generated for this repo yet' });
         }
@@ -2494,7 +2774,17 @@ runtime = {}) {
         catch {
             return reply.code(400).send({ error: 'Malformed requirement key encoding' });
         }
-        const detail = await getRequirement(repo, decoded);
+        let detail;
+        try {
+            detail = await getRequirement(repo, decoded);
+        }
+        catch (err) {
+            // wicked-core#406: a CURRENT engine with no repo-graph root is a 503, not a 500.
+            const status = codeGraphErrorStatus(err);
+            if (status === null)
+                throw err;
+            return reply.code(status).send({ error: message(err) });
+        }
         if (detail === null)
             return reply.code(404).send({ error: 'Requirement not found' });
         return { requirement: detail };
@@ -2529,20 +2819,42 @@ runtime = {}) {
         catch {
             return reply.code(400).send({ error: 'Malformed requirement key encoding' });
         }
-        const detail = await patchRequirement(repo, decodedKey, parsed.data);
+        let detail;
+        try {
+            detail = await patchRequirement(repo, decodedKey, parsed.data);
+        }
+        catch (err) {
+            // wicked-core#406: a CURRENT engine with no repo-graph root is a 503, not a 500.
+            const status = codeGraphErrorStatus(err);
+            if (status === null)
+                throw err;
+            return reply.code(status).send({ error: message(err) });
+        }
         if (detail === null)
             return reply.code(404).send({ error: 'Requirement not found' });
         return { requirement: detail };
     });
-    app.get(`${V}/repos/:id/graph`, async (req, reply) => {
+    app.get(`${V}/repos/:id/graph`, { config: { manifest: { responseType: 'RepoGraphResponse', statusCodes: [200, 404, 500, 503] } } }, 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 = codeGraphDb(repo);
+        const dbPath = codeGraphDbOr503(repo, reply);
+        if (dbPath === null)
+            return reply;
         if (!existsSync(dbPath)) {
-            return reply.send({ graph: null });
+            // `graph: null` alone cannot tell "not indexed" from "empty" (F-2R2-005): say WHY, with the
+            // same finding text the repos wire carries when the engine has one.
+            const finding = (repo.findings ?? []).find((f) => f.code === 'in_tree_code_graph_ignored' || f.code === 'code_graph_root_unresolvable');
+            const unbuilt = {
+                graph: null,
+                reason: finding?.message ??
+                    `no code graph has been built for '${repo.name}' yet (nothing at ${dbPath}) — run onboarding ` +
+                        `(POST /api/v1/repos/${repo.id}/onboard) to index it`,
+                ...(finding !== undefined ? { finding } : {}),
+            };
+            return reply.send(unbuilt);
         }
         try {
             const settings = await adapter.getSettings();
@@ -2563,13 +2875,14 @@ runtime = {}) {
             });
             const raw = JSON.parse(stdout);
             const fileCount = new Set(raw.nodes.map((n) => n.file)).size;
-            return reply.send({
+            const built = {
                 graph: {
                     nodes: raw.nodes,
                     edges: raw.edges,
                     stats: { nodeCount: raw.nodes.length, edgeCount: raw.edges.length, fileCount },
                 },
-            });
+            };
+            return reply.send(built);
         }
         catch (err) {
             return reply.code(500).send({ error: message(err) });
@@ -2591,7 +2904,9 @@ runtime = {}) {
         const repo = repos.find((r) => r.id === id);
         if (!repo)
             return reply.code(404).send({ error: `Repo ${id} not found` });
-        const dbPath = codeGraphDb(repo);
+        const dbPath = codeGraphDbOr503(repo, reply);
+        if (dbPath === null)
+            return reply;
         if (!existsSync(dbPath)) {
             return reply.code(404).send({ error: 'Code graph not built for this repo yet' });
         }