wicked-crew 0.6.0 → 0.7.0

package/dist/interactive/draft-events.js

@@ -27,12 +27,21 @@
  *    service instruments fresh ones — so the worker contract explicitly forbids inventing
  *    `data-wid` attributes rather than requiring preservation. The feedback→edit leg (fragment
  *    preservation at scale) is the structural seam next door: edit-events.ts.
+ *  - UNFILED DOCS ARE ANSWERED TOO: this seam originally rejected `doc.created` frames without
+ *    a `project_id` ("unbound docs are the assist skill's solo business") — superseded by
+ *    DES-UX-001 slice U (wicked-studio, §6.2 + §8.4.1 probe 3), which made unfiled docs a
+ *    first-class path created through crew's synthesized `default` mount with NO project field.
+ *    Nothing else answers those (BRIEF-UX-001 J3 CRITICAL: the doc sat on its placeholder
+ *    forever), so the launch simply omits `projectId` — an unfiled governed run (CREW-UX-2).
  */
-import { mkdirSync, existsSync, statSync } from 'node:fs';
+import { resolveProjectGraphBinding } from '../projects/graph.js';
+import { mkdirSync, existsSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { InteractiveHandoffLedger } from './ledger.js';
+import { snapshotRepo } from './repo-snapshot.js';
+import { DELIVERABLE_FLOOR_PHASE_ID } from '../core/deliverable-floor.js';
 // ── Vocabulary constants (interactive's, verbatim — src/service/events.js is the truth) ──────
 export const INTERACTIVE_DOMAIN = 'wicked-interactive';
 export const DOC_CREATED = 'wicked.interactive.doc.created';
@@ -112,7 +121,10 @@ export const INTERACTIVE_DRAFT_WORKFLOW_DEF = {
 /**
  * Parse a bus frame into a {@link SourceDocCreated}, or `null` when it is not an actionable
  * `doc.created` (wrong type, non-`source` kind, missing/malformed document_id). `kind: "demo"`
- * and plain html docs are the assist loop's business, not this seam's.
+ * and plain html docs are the assist loop's business, not this seam's. A missing `project_id`
+ * is NOT a rejection: unfiled docs (DES-UX-001 slice U) are actionable with `projectId`
+ * undefined — the earlier "unbound docs are the assist skill's solo business" gate is
+ * superseded (nothing else answers a doc created through the default mount; BRIEF-UX-001 J3).
  */
 export function parseSourceDocCreated(eventType, payload) {
     if (eventType !== DOC_CREATED)
@@ -131,10 +143,7 @@ export function parseSourceDocCreated(eventType, payload) {
         : [];
     const style = typeof p['style'] === 'string' && p['style'].length > 0 ? p['style'] : 'web';
     const projectId = typeof p['project_id'] === 'string' && p['project_id'].length > 0 ? p['project_id'] : undefined;
-    // Only project-bound docs route through crew; unbound docs are the assist skill's solo business.
-    if (projectId === undefined)
-        return null;
-    return { documentId, brief, sourcePaths, style, projectId };
+    return { documentId, brief, sourcePaths, style, ...(projectId !== undefined ? { projectId } : {}) };
 }
 /** Collapse whitespace/newlines to single spaces and cap length — the intent must stay a
  *  single line (the PTY seat runner refuses embedded newlines) and a pasted-novel brief must
@@ -143,18 +152,88 @@ export function oneLine(text, cap) {
     const flat = text.replace(/\s+/g, ' ').trim();
     return flat.length > cap ? `${flat.slice(0, cap)}…` : flat;
 }
+/**
+ * Resolve the repo a project is bound to (CREW-UX-8): the project's first `crew.repo` member,
+ * verified against the repo registry so a stale membership (repo deleted after attach) never
+ * grounds the task in a path the registry no longer vouches for. `undefined` when the project
+ * has no repo member, the registry no longer knows the ref, or the adapter cannot answer (old
+ * addon, engine hiccup) — every one of those degrades to today's behavior: an ungrounded launch.
+ *
+ * WHY: a doc created under a repo-backed project used to launch its governed draft/revision
+ * run with NO repo context at all, so the worker could not read the project's actual code and
+ * generated placeholder content (operator report, wicked-studio project). Shared by the draft
+ * and chat seams.
+ *
+ * WHY the result feeds a SNAPSHOT, never a binding and never a direct read path (the v4
+ * design): the launch itself stays UNBOUND (no `repoRef`), even though the project verifiably
+ * has one, because on a repoRef-bound run the worker's ACP tool-permission stream closes on
+ * the FIRST call that needs a permission prompt, so the session dies before any work lands —
+ * no write destination works, not the external inbox, not an in-repo path (wicked-core#293;
+ * v2 of this seam tried both and the adversarial verifier killed each with run evidence).
+ * v3 then handed the unbound worker the absolute `rootPath` to READ — but that rested on a
+ * boundary-context-dependent premise: the "repo reads work" evidence came from BOUND runs,
+ * and an UNBOUND worker's governance boundary is {sandbox, extraWriteRoots,
+ * ~/.claude/plugins}, so its reads of the live repo root are governance-DENIED
+ * (wicked-core#294). What an unbound worker can always read is the inbox the run already
+ * writes to (write roots are readable, wicked-core#259) — so v4 grounds via a capped,
+ * launch-scoped repo SNAPSHOT cloned into the inbox crew-side BEFORE the launch (see
+ * repo-snapshot.ts), and the grounding clause names the snapshot. `rootPath` here is the
+ * clone SOURCE only; `projectId` still passes on the launch — filing is unaffected.
+ */
+export async function resolveProjectRepo(adapter, projectId, log) {
+    try {
+        const members = await adapter.projectMembers(projectId);
+        const repoMember = members.find((m) => m.member_kind === 'crew.repo');
+        if (repoMember === undefined)
+            return undefined;
+        const ref = repoMember.member_ref;
+        const repo = (await adapter.listRepos()).find((r) => r.id === ref);
+        if (repo === undefined) {
+            log?.(`[interactive] project ${projectId} has repo member ${ref} but the registry does not — launching without repo context`);
+            return undefined;
+        }
+        return { repoRef: ref, rootPath: repo.root_path };
+    }
+    catch (err) {
+        log?.(`[interactive] could not resolve project ${projectId}'s repo — launching without repo context: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/** The longest snapshot path the grounding clause will carry. NOT a truncation cap — the
+ *  clause embeds the path VERBATIM or not at all (see {@link groundablePath}): the snapshot
+ *  sits at exactly one spelling, so a flattened/truncated path would ground the worker on a
+ *  directory that does not exist (Copilot, crew#313). The budget exists for the PTY prompt
+ *  length; a dest over it degrades the launch to ungrounded, honestly narrated. */
+export const SNAPSHOT_PATH_MAX = 300;
+/** `true` when a snapshot path can ride the grounding clause EXACTLY as spelled: single-line
+ *  (the PTY seat runner refuses embedded newlines — and `oneLine`'s whitespace collapse would
+ *  respell the path, so it is never applied to paths) and within the prompt budget. */
+export function groundablePath(path) {
+    return path.length <= SNAPSHOT_PATH_MAX && !/[\n\r\t]/.test(path);
+}
 /**
  * The run's problem statement (the engine scopes it per phase and folds each phase's
  * instructions on top). Carries everything doc-specific: identity, brief, sources, style, and
- * the absolute path the finished HTML must land at.
+ * the absolute path the finished HTML must land at. When the doc's project is repo-bound
+ * (CREW-UX-8 v4), a SHORT grounding clause names the launch-scoped repo SNAPSHOT inside the
+ * inbox for the worker to READ — the run itself launches unbound (wicked-core#293) and cannot
+ * read the live repo (wicked-core#294), so the snapshot named by this clause is the whole
+ * grounding mechanism, not a nudge on top of an engine binding.
+ *
+ * `snapshotDir` is embedded VERBATIM — never flattened, never truncated (the snapshot exists
+ * at exactly this path; Copilot, crew#313). The caller guards it with {@link groundablePath}
+ * BEFORE snapshotting and skips grounding (honest degrade) when the path cannot ride.
  */
-export function draftProblem(doc, outPath) {
+export function draftProblem(doc, outPath, snapshotDir) {
     const sources = doc.sourcePaths.length > 0
         ? `Source materials to read: ${doc.sourcePaths.join(', ')}.`
         : 'There are no source files — the brief alone is the spec.';
     const brief = doc.brief.length > 0 ? oneLine(doc.brief, 2000) : '(no brief provided)';
+    const grounding = snapshotDir !== undefined
+        ? `Ground the document in the repository snapshot at ${snapshotDir} — read it and use its real content, never placeholders. `
+        : '';
     return (`Produce the first draft of the wicked-interactive document "${doc.documentId}" ` +
-        `(requested style: ${doc.style}). The user's brief: ${brief} ${sources} ` +
+        `(requested style: ${doc.style}). The user's brief: ${brief} ${sources} ${grounding}` +
         `The finished draft MUST be written to exactly this absolute file path: ${outPath}`);
 }
 /** Deterministic bus idempotency key for the one draft this seam may land per document. */
@@ -218,8 +297,14 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
     const ledger = new InteractiveHandoffLedger(opts.ledgerPath ?? join(defaultStateDir(), 'interactive-draft-ledger.json'));
     const draftDir = opts.draftDir ?? join(defaultStateDir(), 'interactive-drafts');
     const heartbeatMs = opts.heartbeatMs ?? 15_000;
-    const phaseCount = INTERACTIVE_DRAFT_WORKFLOW_DEF.phases.length;
-    const inFlight = new Map(); // runId → live state
+    // The run executes ONE MORE unit than the def declares: the crew#311 deliverable floor,
+    // appended per-run by `launchRun` from `requireDeliverables`. `agentPhaseCount` is what the
+    // council-and-worker narration branches key on (unchanged); `phaseCount` is the run's real
+    // length, so the thread never reports "phase 3/2" or calls the verification "the draft".
+    const agentPhaseCount = INTERACTIVE_DRAFT_WORKFLOW_DEF.phases.length;
+    const phaseCount = agentPhaseCount + 1;
+    const inFlight = new Map(); // runId → live state (pre-launch placeholders included)
+    let closed = false; // set by stop(): a handler mid-snapshot must never launch after shutdown
     /** Emit onto interactive's vocabulary as the `wi-crew` producer. Never throws into the
      *  caller: narration/announce failures are logged — a lost status line must not kill the
      *  subscription, and a duplicate draft emit (WB-002) is the idempotency key WORKING. */
@@ -256,11 +341,28 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
     function endFlight(runId) {
         const flight = inFlight.get(runId);
         if (flight) {
-            clearInterval(flight.heartbeat);
+            if (flight.heartbeat !== undefined)
+                clearInterval(flight.heartbeat);
             inFlight.delete(runId);
         }
         return flight;
     }
+    /** CREW-UX-8 v4: the repo snapshot is launch-scoped — remove it on EVERY terminal path
+     *  (success, no-file, emit-failure, run failure/cancel) so the inbox never accretes dead
+     *  clones. Best-effort: a leftover snapshot is a disk-space wart, never a correctness one. */
+    function removeSnapshot(flight) {
+        const dir = flight.snapshotDir;
+        if (dir === undefined)
+            return;
+        flight.snapshotDir = undefined;
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            log(`[interactive-draft] removed repo snapshot ${dir}`);
+        }
+        catch (err) {
+            log(`[interactive-draft] could not remove repo snapshot ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /** Terminal-event fold: turn the governed run's own events into interactive narration, and
      *  close the loop with `draft.completed` when the run lands. */
     const offCoreEvents = adapter.onEvent((event) => {
@@ -273,17 +375,29 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
         // Narration ladder (#user-feedback 2026-08-14): the heartbeat repeats the LATEST line, and
         // the interactive transcript dedups consecutive repeats — so the more the line ADVANCES with
         // the run's real events, the more the thread reads as progress instead of a stuck echo.
-        const phaseName = (ord) => INTERACTIVE_DRAFT_WORKFLOW_DEF.phases[ord - 1]?.id ?? `phase ${ord}`;
+        const phaseName = (ord) => ord > agentPhaseCount
+            ? DELIVERABLE_FLOOR_PHASE_ID
+            : (INTERACTIVE_DRAFT_WORKFLOW_DEF.phases[ord - 1]?.id ?? `phase ${ord}`);
+        // The crew#311 deliverable floor is a DETERMINISTIC tool phase — no seat, no council. Core
+        // still emits the seat-selection events for it (its `cli` is the node interpreter's absolute
+        // path), so narrating them verbatim put "Council picked /opt/homebrew/.../node for
+        // verify-deliverables…" in the reader's thread. Drop those two lines for the floor ord; the
+        // `unitDispatched` line that follows immediately says what the phase actually is.
+        const isFloorOrd = (e) => typeof e.ord === 'number' && e.ord > agentPhaseCount;
         if (event.type === 'councilConvened') {
+            if (isFloorOrd(event))
+                return;
             const ord = typeof event.ord === 'number' ? event.ord : 0;
             const seats = Array.isArray(event.clis) ? event.clis.length : 0;
             // "0-seat council" reads like a bug — generic phrasing whenever clis is missing or empty
             // (Copilot, #269).
             const council = seats > 0 ? `a ${seats}-seat council` : 'a council';
-            narrate(flight, `Convening ${council} to pick who ${ord >= phaseCount ? 'writes the draft' : 'plans the outline'}…`);
+            narrate(flight, `Convening ${council} to pick who ${ord >= agentPhaseCount ? 'writes the draft' : 'plans the outline'}…`);
             return;
         }
         if (event.type === 'unitDistributed') {
+            if (isFloorOrd(event))
+                return;
             const ord = typeof event.ord === 'number' ? event.ord : 0;
             const who = typeof event.cli === 'string' ? event.cli : 'a worker';
             const pct = typeof event.agreement_pct === 'number' ? ` (${event.agreement_pct}% agreement)` : '';
@@ -293,9 +407,11 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
         if (event.type === 'unitDispatched') {
             const ord = typeof event.ord === 'number' ? event.ord : 0;
             const phase = phaseName(ord);
-            narrate(flight, ord >= phaseCount
-                ? `Crew phase ${ord}/${phaseCount}: writing the draft (${phase})…`
-                : `Crew phase ${ord}/${phaseCount}: ${phase} — planning the document…`);
+            narrate(flight, ord > agentPhaseCount
+                ? `Crew phase ${ord}/${phaseCount}: checking the draft file was actually written (${phase})…`
+                : ord >= agentPhaseCount
+                    ? `Crew phase ${ord}/${phaseCount}: writing the draft (${phase})…`
+                    : `Crew phase ${ord}/${phaseCount}: ${phase} — planning the document…`);
             return;
         }
         if (event.type === 'toolInvoked') {
@@ -311,9 +427,11 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
         }
         if (event.type === 'gateDecided' && event.allow === true) {
             const ord = typeof event.ord === 'number' ? event.ord : 0;
-            narrate(flight, ord >= phaseCount
-                ? 'Gate approved the draft — landing it now…'
-                : `Gate approved ${phaseName(ord)} — moving on…`);
+            narrate(flight, ord > agentPhaseCount
+                ? 'Draft file verified on disk — landing it now…'
+                : ord >= agentPhaseCount
+                    ? 'Gate approved the draft — checking the file landed…'
+                    : `Gate approved ${phaseName(ord)} — moving on…`);
             return;
         }
         if (event.type === 'acpFallback') {
@@ -326,19 +444,31 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
             finalize(flight, runId);
             return;
         }
+        if (event.type === 'stepFailed') {
+            // Remember the engine's own reason (crew#311): the terminal status below reads far better
+            // as "the draft file was never written" than as "inspect it via the API".
+            const detail = typeof event.detail === 'string' ? event.detail.trim() : '';
+            if (detail.length > 0)
+                flight.failureDetail = detail;
+            return;
+        }
         if (event.type === 'sessionFailed' || event.type === 'runCancelled') {
             endFlight(runId);
+            removeSnapshot(flight); // the failure path cleans its snapshot too (CREW-UX-8 v4)
             ledger.recordFailure(flight.documentId);
+            const why = flight.failureDetail !== undefined ? ` Reason: ${oneLine(flight.failureDetail, 600)}` : '';
             emitInteractive(STATUS_POSTED, {
                 document_id: flight.documentId,
                 state: 'error',
                 message: `The crew run answering this document ${event.type === 'runCancelled' ? 'was cancelled' : 'failed'} ` +
-                    `(run ${runId}). Inspect it via the crew API (GET /api/v1/runs/${runId}); the assist loop can still take over.`,
+                    `(run ${runId}).${why} Inspect it via the crew API (GET /api/v1/runs/${runId}); the assist loop can still take over.`,
             });
             log(`[interactive-draft] run ${runId} for doc ${flight.documentId} ended: ${event.type}`);
         }
     });
     function finalize(flight, runId) {
+        // The run is terminal — its grounding snapshot is done serving reads, on every branch below.
+        removeSnapshot(flight);
         const { documentId, outPath } = flight;
         let ok = false;
         try {
@@ -396,33 +526,192 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
             if (f.documentId === doc.documentId)
                 return;
         }
-        mkdirSync(draftDir, { recursive: true });
-        const outPath = join(draftDir, `${doc.documentId}-v1.html`);
+        // Per-run ISOLATION (Copilot, crew#313): every launch gets its OWN subdirectory holding
+        // both the deliverable and (when grounded) the repo snapshot, and declares ONLY that
+        // subdirectory as its extra write root below. Declaring the shared draftDir wholesale let
+        // any draft worker read/write every other run's deliverable AND every other project's
+        // snapshot — cross-project exposure through the governance boundary itself.
+        // NOT created here (Copilot round 2): runDir is only mkdir'd after the snapshot helper's
+        // containment check has ruled the location safe — see the pre-launch mkdir below.
+        const runDir = join(draftDir, doc.documentId);
+        const outPath = join(runDir, `${doc.documentId}-v1.html`);
         const runId = randomUUID();
+        // PRE-LAUNCH placeholder (Copilot round 2): the awaits below (repo resolution, snapshot)
+        // open a window in which this doc has no `inFlight` entry — so the chat seam's `isDocBusy`
+        // saw it idle (double-launch race) and stop()'s sweep could not find a half-made snapshot.
+        // Register the flight FIRST; every exit path below (refusal, shutdown, launch failure)
+        // must endFlight() it.
+        const flight = {
+            documentId: doc.documentId,
+            outPath,
+            narration: 'Crew run launched — working on your draft…',
+        };
+        inFlight.set(runId, flight);
+        // CREW-UX-8 v4: a repo-bound project's doc is grounded in a REPO SNAPSHOT — resolve the
+        // binding BEFORE the launch. Unbound docs and repo-less projects resolve to `undefined`
+        // and launch exactly as before.
+        const repo = doc.projectId !== undefined ? await resolveProjectRepo(adapter, doc.projectId, log) : undefined;
         emitInteractive(STATUS_POSTED, {
             document_id: doc.documentId,
             state: 'processing',
             message: 'A governed crew picked up your brief — planning the draft…',
         });
+        // The snapshot happens crew-side, AFTER the pickup narration (a big clone must not starve
+        // the UI's silence budget) and BEFORE launchRun: <runDir>/repo sits inside the run's OWN
+        // declared extra write root, so the unbound worker can read it (write roots are readable,
+        // wicked-core#259) even though the live repo root is boundary-denied (wicked-core#294) —
+        // and NO OTHER run can (per-run isolation, Copilot crew#313). An unsnapshotable repo (over
+        // budget, unreadable, clone+copy failed) degrades HONESTLY: ungrounded launch, a visible
+        // per-cause note on the thread, and the full reason in the log.
+        let snapshotDir;
+        let snapshotDest; // where a snapshot was ATTEMPTED (shutdown cleanup)
+        if (repo !== undefined) {
+            const dest = join(runDir, 'repo');
+            if (!groundablePath(dest)) {
+                // The PATH itself cannot ride the grounding clause (too long for the PTY prompt
+                // budget, or multi-line) — and a truncated spelling would name a nonexistent dir, so
+                // grounding is SKIPPED before any clone happens (Copilot, crew#313).
+                emitInteractive(STATUS_POSTED, {
+                    document_id: doc.documentId,
+                    state: 'working',
+                    message: 'snapshot path too long to hand to the worker — drafting without repo grounding',
+                });
+                log(`[interactive-draft] doc ${doc.documentId}: snapshot dest ${dest} cannot ride the grounding clause — launching ungrounded`);
+            }
+            else {
+                // Track the dest BEFORE the await (Copilot round 2): stop() during the clone must be
+                // able to sweep the half-made snapshot through the placeholder flight.
+                snapshotDest = dest;
+                flight.snapshotDir = dest;
+                const snap = await snapshotRepo(repo.rootPath, dest, { maxBytes: opts.repoSnapshotMaxBytes, log });
+                if (snap.ok) {
+                    snapshotDir = dest;
+                }
+                else {
+                    flight.snapshotDir = undefined; // nothing landed — snapshotRepo cleans its partials
+                    if (snap.reason === 'dest-overlap') {
+                        // FAIL CLOSED (Copilot round 2): the configured draft dir places this run's write
+                        // root inside the live repository (or the repo is registered at the inbox). An
+                        // "ungrounded" launch would still hand the unbound worker read/write access to
+                        // live repo content through `extraWriteRoots: [runDir]` — so the launch is REFUSED
+                        // outright: no mkdir, no run, no ledger row. The status names the CONFIG problem;
+                        // the thrown error dead-letters the frame, replayable after the config is fixed.
+                        endFlight(runId);
+                        const message = `Crew refused to draft this document: the configured draft directory (${draftDir}) ` +
+                            `overlaps the project's repository (${repo.rootPath}), so launching would give the ` +
+                            `worker write access inside the live repo. Point the crew draft directory outside ` +
+                            `every registered repository, then replay the request.`;
+                        emitInteractive(STATUS_POSTED, {
+                            document_id: doc.documentId,
+                            state: 'error',
+                            message,
+                        });
+                        log(`[interactive-draft] doc ${doc.documentId}: REFUSING launch — draft dir ${draftDir} overlaps repo ${repo.rootPath} (dest-overlap)`);
+                        throw new Error(message);
+                    }
+                    // Per-cause operator message (Copilot, crew#313): "too large" was previously
+                    // claimed for EVERY failure — a deleted repo is not a large one. (`dest-overlap`
+                    // is handled above: it refuses the launch instead of degrading.)
+                    const because = {
+                        'too-large': 'repository too large to snapshot',
+                        'root-unreadable': 'repository path is missing or unreadable',
+                        'dest-unclearable': 'a stale snapshot could not be cleared',
+                        'copy-failed': 'repository snapshot failed (clone and copy both errored)',
+                    };
+                    emitInteractive(STATUS_POSTED, {
+                        document_id: doc.documentId,
+                        state: 'working',
+                        message: `${because[snap.reason]} — drafting without repo grounding`,
+                    });
+                    log(`[interactive-draft] doc ${doc.documentId}: repo ${repo.rootPath} could not be snapshotted (${snap.reason}) — launching ungrounded`);
+                }
+            }
+        }
+        // Shutdown gate (Copilot round 2): stop() may have run during the awaits above — its sweep
+        // already dropped the placeholder, but a clone can re-materialize files after that rm, and
+        // a launch must never start once the subscriber detached from the engine's events.
+        if (closed) {
+            endFlight(runId);
+            flight.snapshotDir = undefined;
+            if (snapshotDest !== undefined) {
+                try {
+                    rmSync(snapshotDest, { recursive: true, force: true });
+                }
+                catch {
+                    // best-effort — a leftover snapshot is a disk-space wart, never a correctness one
+                }
+            }
+            log(`[interactive-draft] doc ${doc.documentId}: subscriber stopped before launch — abandoned (a replay retries)`);
+            return;
+        }
+        // Containment is settled (any repo overlap refused above) — the run's write root may exist.
+        mkdirSync(runDir, { recursive: true });
+        // Resolve the project's graph BEFORE the launch, never indexing (a refresh is
+        // `wicked-estate index` per member, bounded at 600s EACH — doing that inside a launch turns
+        // "start a draft" into an unannounced multi-repo job). Missing or stale degrades to no
+        // binding and the run proceeds exactly as before; the graph is a bonus, never a gate.
+        //
+        // The decision is RECORDED on both outcomes, like the API launch path (`api/routes.ts`).
+        // "this draft sees the project" and "this draft sees nothing, because X" are equally facts
+        // about what the run could observe, and the second is the one someone needs when a worker
+        // reports that a sibling repo does not exist. An unexpected failure degrades the same way,
+        // but says so — a silent `catch(() => null)` would make a broken binding indistinguishable
+        // from a project that simply has no graph yet.
+        let projectGraphBinding = null;
+        if (doc.projectId !== undefined) {
+            const decision = await resolveProjectGraphBinding(adapter, doc.projectId, undefined).catch((err) => ({
+                binding: null,
+                reason: `the project graph binding could not be resolved ` +
+                    `(${err instanceof Error ? err.message : String(err)}). ` +
+                    `This repo-less run gets no code graph.`,
+            }));
+            projectGraphBinding = decision.binding;
+            log(`run ${runId}: ${decision.reason}`);
+        }
         try {
             await adapter.launchRun({
-                problem: draftProblem(doc, outPath),
+                problem: draftProblem(doc, outPath, snapshotDir),
                 sessionId: runId,
                 clisJson: opts.clisJson ?? JSON.stringify(rosterOf(adapter)),
                 workflow: INTERACTIVE_DRAFT_WORKFLOW,
                 // A project-bound doc's governed draft is FILED (P7 gate DEFECT-1): the engine attaches
                 // the crew.run membership atomically with the launch, so the run shows up in the
-                // project's activity feed instead of floating unattributed.
-                projectId: doc.projectId,
-                // The task text names `outPath` (inside draftDir) as the deliverable, which sits OUTSIDE
+                // project's activity feed instead of floating unattributed. An UNFILED doc (DES-UX-001
+                // slice U — created through the default mount with no project field) launches with the
+                // key OMITTED: an unfiled governed run (project_id: null on the DTO, CREW-UX-2) — never
+                // a fabricated 'default' membership.
+                ...(doc.projectId !== undefined ? { projectId: doc.projectId } : {}),
+                // A project-filed run sees the PROJECT's graph, like any other (verification
+                // found this seam launching filed but unbound). These launches are repo-LESS,
+                // which is exactly the case that gets a graph where it previously got none.
+                ...(projectGraphBinding !== null ? { projectGraph: projectGraphBinding } : {}),
+                // CREW-UX-8: deliberately NO `repoRef`, even when the project has one — a repoRef-bound
+                // run's tool-permission stream closes on the first prompt-needing call, so no write
+                // destination works (wicked-core#293) — and NO live-repo path in the task either: the
+                // unbound boundary denies those reads (wicked-core#294). The grounding clause in
+                // `problem` names the in-inbox snapshot instead; this ONE launch shape serves all docs.
+                // The task text names `outPath` (inside runDir) as the deliverable, which sits OUTSIDE
                 // the unit's sandbox — on the wrapped-CLI path the boundary denied that exact write and
-                // failed the run AFTER the draft was produced (crew#263, run eed69dfa). Declare the inbox
-                // so the engine widens the boundary by exactly this root (validated launch-side,
+                // failed the run AFTER the draft was produced (crew#263, run eed69dfa). Declare the
+                // run's OWN subdirectory — never the shared draftDir (Copilot, crew#313: the wholesale
+                // declaration let one project's worker read another's snapshot and deliverables) — so
+                // the engine widens the boundary by exactly this run's inbox (validated launch-side,
                 // wicked-core#259).
-                extraWriteRoots: [draftDir],
+                extraWriteRoots: [runDir],
+                // THE DELIVERABLE FLOOR (crew#311): the draft file IS the deliverable, so the run is
+                // not done until it exists. Without this the engine's substance floor is the only
+                // check on this unbound run, and it passes a worker whose Write was denied as long as
+                // ~200 characters of narration came first — the exact reproducer shape. The floor
+                // phase FAILS the run naming this path; `finalize` below stays as the belt-and-braces
+                // check for a run that never reaches the floor at all.
+                requireDeliverables: [outPath],
             });
         }
         catch (err) {
+            // A launch that never happened keeps no flight and no snapshot (a replayed frame
+            // re-registers and re-snapshots fresh).
+            endFlight(runId);
+            removeSnapshot(flight);
             // The 'processing' status is already on the thread — close it out honestly so the
             // canvas never sits in an in-between state on a launch that went nowhere.
             const reason = err instanceof Error ? err.message : String(err);
@@ -441,24 +730,26 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
         // delivery retries. The crash window between launch and this write is the reason the
         // draft emit ALSO carries a deterministic idempotency key.
         ledger.recordLaunch(doc.documentId, runId);
-        opts.onRunFiled?.(runId, doc.projectId);
-        const flight = {
-            documentId: doc.documentId,
-            outPath,
-            narration: 'Crew run launched — working on your draft…',
-            heartbeat: setInterval(() => {
-                // Repeat the last real narration so the ~20s status.requested window is always fed,
-                // even mid-phase when the engine is quiet.
-                emitInteractive(STATUS_POSTED, {
-                    document_id: flight.documentId,
-                    state: 'working',
-                    message: flight.narration,
-                });
-            }, heartbeatMs),
-            // Do not keep the daemon alive for narration alone.
-        };
+        if (closed) {
+            // stop() ran while the engine was accepting the launch: its sweep already dropped the
+            // placeholder and the snapshot, and the engine's workers die with the daemon — the
+            // ledger row above is what keeps a post-restart redelivery from double-launching.
+            return;
+        }
+        if (doc.projectId !== undefined)
+            opts.onRunFiled?.(runId, doc.projectId);
+        // Upgrade the placeholder to a live flight: the heartbeat starts once the run exists.
+        flight.heartbeat = setInterval(() => {
+            // Repeat the last real narration so the ~20s status.requested window is always fed,
+            // even mid-phase when the engine is quiet.
+            emitInteractive(STATUS_POSTED, {
+                document_id: flight.documentId,
+                state: 'working',
+                message: flight.narration,
+            });
+        }, heartbeatMs);
+        // Do not keep the daemon alive for narration alone.
         flight.heartbeat.unref?.();
-        inFlight.set(runId, flight);
         log(`[interactive-draft] doc ${doc.documentId} → governed run ${runId} (draft → ${outPath})`);
     }
     const sub = bus.subscribe({
@@ -479,10 +770,22 @@ export async function startInteractiveDraftSubscriber(adapter, opts = {}) {
     });
     return {
         ledger,
+        inFlightDocs: () => [...new Set([...inFlight.values()].map((f) => f.documentId))],
         stop: async () => {
+            closed = true; // a handler mid-snapshot sees this and never launches (Copilot round 2)
             offCoreEvents();
-            for (const runId of [...inFlight.keys()])
-                endFlight(runId);
+            for (const runId of [...inFlight.keys()]) {
+                const flight = endFlight(runId);
+                // Best-effort snapshot sweep (Copilot, crew#313): a graceful shutdown with a run in
+                // flight would otherwise strand the clone forever — after restart the ledger's launch
+                // row suppresses redelivery, so no later fold ever revisits it. Pre-launch
+                // placeholders are in the map too (Copilot round 2), so a snapshot still
+                // materializing is swept as well — and the handler's own closed-gate re-sweeps
+                // whatever the in-flight clone re-materializes after this rm. The engine's workers
+                // die with the daemon, so nothing is still reading the snapshot.
+                if (flight !== undefined)
+                    removeSnapshot(flight);
+            }
             await sub.stop();
         },
     };