wicked-crew 0.6.0 → 0.7.0

package/dist/api/run-files.js

@@ -0,0 +1,271 @@
+// GET /runs/:id/files + GET /runs/:id/diff machinery (DES-FEEDBACK-002 CREW-1).
+//
+// The studio's in-app file & diff viewer cannot read the daemon host's filesystem, so the daemon
+// serves the bytes — which is exactly why every path is contained FIRST against the same root set
+// `POST /open` validates (`allowedRootsFor` + `isInsideRoot`, open-path.ts), every payload is
+// capped, and git runs through `execCapped` with argv arrays only (never a shell string) and
+// `--no-ext-diff` (a configured external diff driver must never execute here). Both routes are
+// read-only by construction: `fs` reads and `git diff`/`git status` — zero write capability, a
+// strictly smaller threat surface than `/open` handing the path to an OS opener.
+import { promises as fsp } from 'node:fs';
+import { execCapped, ExecOutputTooLarge } from '../core/exec.js';
+/** File-content cap (DES-FEEDBACK-002 §3.3): past this, `content` holds the first 512 KB and
+ *  `truncated: true` — the studio renders a labeled truncation banner, never a silent amputation. */
+export const FILE_CONTENT_CAP_BYTES = 512 * 1024;
+/** Binary sniff window: a NUL byte in the first 8 KB ⇒ `binary: true`, `content: ""` — the studio
+ *  falls back to the external-open affordance rather than rendering mojibake. */
+export const BINARY_SNIFF_BYTES = 8 * 1024;
+/** Diff output cap (§3.3): past this the diff is cut at 1 MB and `truncated: true`. */
+export const DIFF_OUTPUT_CAP_BYTES = 1024 * 1024;
+/** The target exists but is not a regular file (directory, socket, …) — the route's 400, distinct
+ *  from ENOENT's 404. Serving directory listings is explicitly out of scope (§3.3). */
+export class NotARegularFileError extends Error {
+    path;
+    constructor(path) {
+        super(`not a regular file: ${path}`);
+        this.path = path;
+        this.name = 'NotARegularFileError';
+    }
+}
+/**
+ * Read at most `FILE_CONTENT_CAP_BYTES` of `target`. The open-then-fstat order (not stat-then-open)
+ * closes the classic swap race: the size and the bytes come from the SAME open file description.
+ * Callers must have contained `target` already — this function does filesystem work only.
+ */
+export async function readFileCapped(target) {
+    const fh = await fsp.open(target, 'r');
+    try {
+        const st = await fh.stat();
+        if (!st.isFile())
+            throw new NotARegularFileError(target);
+        const size = st.size;
+        const toRead = Math.min(size, FILE_CONTENT_CAP_BYTES);
+        const buf = Buffer.alloc(toRead);
+        let off = 0;
+        while (off < toRead) {
+            const { bytesRead } = await fh.read(buf, off, toRead - off, off);
+            if (bytesRead === 0)
+                break; // file shrank underneath us — serve what exists
+            off += bytesRead;
+        }
+        const got = buf.subarray(0, off);
+        if (got.subarray(0, Math.min(off, BINARY_SNIFF_BYTES)).includes(0)) {
+            return { content: '', size, truncated: false, binary: true };
+        }
+        return { content: got.toString('utf8'), size, truncated: size > FILE_CONTENT_CAP_BYTES, binary: false };
+    }
+    finally {
+        await fh.close();
+    }
+}
+const GIT_TIMEOUT_MS = 10_000;
+// ── Diff base (DES-UX-001 §8.1, CREW-UX-1) ─────────────────────────────────────────────────────
+/** `?base=merge-base` — the one non-ref literal: diff against `git merge-base <default-branch>
+ *  HEAD`, i.e. the run branch's fork point, so committed run work is visible (§8.1). */
+export const MERGE_BASE_LITERAL = 'merge-base';
+/** `base` is not a plain ref — a flag, a path, a revision range, a separator. Rejected BEFORE any
+ *  git process sees it: the query parameter is a diff baseline, never a command surface (§8.1). */
+export class InvalidDiffBaseError extends Error {
+    base;
+    constructor(base) {
+        super('`base` must be a plain git ref (branch, tag, or commit id) — ' +
+            'flags, paths, revision ranges, and separators are rejected');
+        this.base = base;
+        this.name = 'InvalidDiffBaseError';
+    }
+}
+/** `base` is well-formed but does not resolve to a commit inside the run's repo — containment:
+ *  a ref from another repo (or thin air) is a 400, never a git error surfaced as a 500. */
+export class UnresolvableDiffBaseError extends Error {
+    base;
+    constructor(base, detail) {
+        super(`unresolvable \`base\`: ${detail}`);
+        this.base = base;
+        this.name = 'UnresolvableDiffBaseError';
+    }
+}
+/** A plain ref: git's own charset for the safe subset — alphanumeric start (excludes `-flag`,
+ *  `.hidden`, `/abs/path`), then word/dot/slash/dash. `..` (ranges AND traversal), `~`/`^`/`@{}`
+ *  (rev operators), `:`, whitespace, and `;` are all outside the charset or explicitly banned. */
+const PLAIN_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/;
+export function isPlainRef(base) {
+    return PLAIN_REF_RE.test(base) && !base.includes('..') && !base.endsWith('/');
+}
+/** One contained git read: argv array (never a shell string), capped, cwd-scoped to the run's
+ *  workdir. Returns trimmed stdout, or `null` ONLY when git ran to completion and answered "no"
+ *  (unresolvable ref, no merge base, …) — a plain non-zero exit. Operational failures are never
+ *  `null`: ENOENT (git missing), "not a git repository", a timed-out/killed process (`killed`/
+ *  `signal` set), and output-cap overflow all rethrow, so they surface as the route's 500 rather
+ *  than masquerading as a 400 "unresolvable base" (Copilot, #307). */
+async function gitQuery(workdir, args) {
+    try {
+        const { stdout } = await execCapped('git', args, { timeout: GIT_TIMEOUT_MS, cwd: workdir });
+        return stdout.trim();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            throw err;
+        if (err instanceof ExecOutputTooLarge)
+            throw err;
+        const proc = err;
+        if (proc.killed === true || (proc.signal !== undefined && proc.signal !== null))
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.toLowerCase().includes('not a git repository'))
+            throw err;
+        return null;
+    }
+}
+/** SHA shapes rev-parse may emit (SHA-1 today, SHA-256 repos exist). Anything else is treated as
+ *  "did not resolve" — the resolved value is what reaches `git diff`, never the caller's text. */
+const COMMIT_SHA_RE = /^[0-9a-f]{40,64}$/;
+/**
+ * Resolve `?base=` to a commit SHA inside the run's repo, or throw the route's named 400s.
+ * Two accepted spellings (§8.1): the literal `merge-base` → `git merge-base <default-branch>
+ * HEAD`; or a plain ref that `git rev-parse --verify` resolves IN THIS repo. Everything git
+ * ultimately diffs against is the resolved SHA — the raw parameter never reaches `git diff`,
+ * and `--end-of-options` keeps even a validated ref from ever parsing as a flag.
+ */
+async function resolveDiffBase(workdir, base) {
+    if (base === MERGE_BASE_LITERAL) {
+        // Default branch: origin's HEAD when the repo has one, else local main/master.
+        let branch = null;
+        const symref = await gitQuery(workdir, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+        if (symref !== null && symref.startsWith('refs/remotes/')) {
+            branch = symref.slice('refs/remotes/'.length);
+        }
+        else {
+            for (const cand of ['main', 'master']) {
+                if ((await gitQuery(workdir, ['rev-parse', '--verify', `refs/heads/${cand}`])) !== null) {
+                    branch = cand;
+                    break;
+                }
+            }
+        }
+        if (branch === null) {
+            throw new UnresolvableDiffBaseError(base, 'no default branch found in this repo to merge-base against');
+        }
+        const sha = await gitQuery(workdir, ['merge-base', '--end-of-options', branch, 'HEAD']);
+        if (sha === null || !COMMIT_SHA_RE.test(sha)) {
+            throw new UnresolvableDiffBaseError(base, `no merge base between ${branch} and HEAD`);
+        }
+        return sha;
+    }
+    if (!isPlainRef(base))
+        throw new InvalidDiffBaseError(base);
+    const sha = await gitQuery(workdir, [
+        'rev-parse',
+        '--verify',
+        '--end-of-options',
+        `${base}^{commit}`,
+    ]);
+    if (sha === null || !COMMIT_SHA_RE.test(sha)) {
+        throw new UnresolvableDiffBaseError(base, `ref does not resolve inside the run's repo: ${base}`);
+    }
+    return sha;
+}
+/** Git's ways of saying "there is nothing here to diff" — a real answer (`diff: ""`), not an
+ *  error. Mirrors the git-history route's tolerance (routes.ts): a workdir that is not a repo, or
+ *  a repo with no commits yet (`HEAD` unresolvable — every file is untracked and the untracked
+ *  pass still runs for the commit-less case). */
+function isEmptyDiffAnswer(msg) {
+    // Case-insensitive on the repo check: `git log` says "fatal: not a git repository" but
+    // `git diff` says "warning: Not a git repository. Use --no-index …" — measured, not assumed.
+    const lower = msg.toLowerCase();
+    return (lower.includes('not a git repository') ||
+        msg.includes('does not have any commits') ||
+        msg.includes("ambiguous argument 'HEAD'") ||
+        msg.includes('unknown revision'));
+}
+/**
+ * The run's worktree diff against `base` (default HEAD) — staged + unstaged in one answer — with
+ * untracked files appended as `git diff --no-index /dev/null <file>` all-addition hunks (§3.3: a
+ * run's *created* files must diff as additions rather than vanish). `relPath`, when given, narrows
+ * both passes to that one file; it is always a single argv element after `--` (the open-path rule
+ * — no shell string is ever composed). The literal `/dev/null` is git's own cross-platform
+ * null-device spelling (git special-cases it, including on Windows).
+ *
+ * `base` (CREW-UX-1, DES-UX-001 §8.1): the literal `merge-base` diffs from the run branch's fork
+ * point off the default branch — committed run work becomes visible; a plain ref diffs from that
+ * ref, resolved inside this repo first (`resolveDiffBase` — the raw parameter never reaches
+ * `git diff`). Throws `InvalidDiffBaseError` / `UnresolvableDiffBaseError` for the route's 400s.
+ */
+export async function worktreeDiff(workdir, relPath, base) {
+    const limit = relPath === undefined ? [] : ['--', relPath];
+    let out = '';
+    // Resolve the baseline BEFORE any diff pass: a bad `base` must 400 without partial output.
+    let baseRev = 'HEAD';
+    if (base !== undefined && base.length > 0) {
+        try {
+            baseRev = await resolveDiffBase(workdir, base);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                throw err; // git missing — 500
+            const msg = err instanceof Error ? err.message : String(err);
+            // The route's standing tolerance: a non-repo workdir answers an empty diff for any
+            // WELL-FORMED base — a malformed base has already thrown InvalidDiffBaseError above,
+            // and that 400 wins over the tolerance (Copilot, #307).
+            if (msg.toLowerCase().includes('not a git repository'))
+                return { diff: '', truncated: false };
+            throw err;
+        }
+    }
+    // Tracked changes (staged + unstaged, plus committed-since-base when a base was resolved):
+    // diff the worktree against the baseline.
+    try {
+        const { stdout } = await execCapped('git', ['diff', '--no-color', '--no-ext-diff', baseRev, ...limit], { timeout: GIT_TIMEOUT_MS, cwd: workdir });
+        out = stdout;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            throw err; // git missing — the route's 500
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.toLowerCase().includes('not a git repository'))
+            return { diff: '', truncated: false };
+        if (!isEmptyDiffAnswer(msg))
+            throw err;
+        // No commits yet: tracked diff is vacuously empty; fall through to the untracked pass.
+    }
+    // Untracked files → all-addition hunks. `-z` (NUL separators, no quoting) + `-uall` (individual
+    // files, never a collapsed `?? dir/` entry that --no-index could not diff).
+    const { stdout: statusOut } = await execCapped('git', ['status', '--porcelain', '-z', '-uall', ...limit], { timeout: GIT_TIMEOUT_MS, cwd: workdir });
+    const untracked = statusOut
+        .split('\0')
+        .filter((entry) => entry.startsWith('?? '))
+        .map((entry) => entry.slice(3));
+    for (const file of untracked) {
+        // Cap is in BYTES; `out.length` counts UTF-16 code units. `>=`: exactly-at-cap is
+        // already done — spawning one more git only to discard its output is waste (Copilot, #305).
+        if (Buffer.byteLength(out, 'utf8') >= DIFF_OUTPUT_CAP_BYTES)
+            break;
+        try {
+            const { stdout } = await execCapped('git', ['diff', '--no-color', '--no-ext-diff', '--no-index', '--', '/dev/null', file], { timeout: GIT_TIMEOUT_MS, cwd: workdir });
+            out += stdout;
+        }
+        catch (err) {
+            // `--no-index` exits 1 WHEN THE FILES DIFFER — which is every hit here. The diff is still
+            // on stdout; only a stdout-less failure is a real error.
+            const stdout = err.stdout;
+            if (typeof stdout === 'string' && stdout.length > 0)
+                out += stdout;
+            else if (err.code === 'ENOENT')
+                throw err;
+            else
+                throw err;
+        }
+    }
+    // Byte-accurate cap (Copilot, #305): `slice` on the string counts UTF-16 code units, which
+    // under-enforces for non-ASCII diffs. Cut on the UTF-8 byte buffer, then back off any
+    // incomplete trailing multibyte sequence — decoding a torn tail yields U+FFFD, which
+    // re-encodes LARGER and would breach the cap by a byte.
+    const outBytes = Buffer.from(out, 'utf8');
+    if (outBytes.byteLength > DIFF_OUTPUT_CAP_BYTES) {
+        let end = DIFF_OUTPUT_CAP_BYTES;
+        while (end > 0 && (outBytes[end] & 0xc0) === 0x80)
+            end--; // land on a sequence boundary
+        return { diff: outBytes.subarray(0, end).toString('utf8'), truncated: true };
+    }
+    return { diff: out, truncated: false };
+}
+//# sourceMappingURL=run-files.js.map

package/dist/api/run-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-files.js","sourceRoot":"","sources":["../../src/api/run-files.ts"],"names":[],"mappings":"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"}

package/dist/api/server.d.ts

@@ -71,6 +71,69 @@ export interface CreateServerOptions {
         editDir?: string;
         /** Seat roster override (JSON array); omit for the production council roster. */
         clisJson?: string;
+        /** Docs-root resolver override (tests); default = per-project `interactiveRoot` setting.
+         *  Used ONLY as the demo-kind gate (CREW-UX-9) — demo docs' step feedback belongs to the
+         *  demo seam. */
+        resolveDocsRoot?: (projectId: string | undefined) => string;
+    };
+    /**
+     * Opt-in governed answering of wicked-interactive DEMO docs (CREW-UX-9 — video generation's
+     * missing brain, the retired assist agent's Step 8). When enabled, a durable subscriber
+     * answers `wicked.interactive.doc.created` (kind:demo) with a governed `interactive-demo`
+     * run that authors `demo.spec.mjs`, installs it into the doc workspace, and ends in
+     * `wicked.interactive.demo.requested` — the model-free service then records the video
+     * (Playwright + ffmpeg) and lands the storyboard version itself. Step feedback on a demo doc
+     * (`feedback.processed`, manifest kind demo) is answered by RE-authoring the spec and
+     * re-emitting demo.requested (assist SKILL.md Step 8c). When absent (the default), demo docs
+     * keep their "Learning …" placeholder — the pre-CREW-UX-9 state.
+     */
+    interactiveDemoEvents?: {
+        enabled: boolean;
+        /** Bus db path; omit for wicked-bus's own default resolution (honors WICKED_BUS_DATA_DIR). */
+        dbPath?: string;
+        /** Poll cadence, ms (tests shorten it). */
+        pollIntervalMs?: number;
+        /** Heartbeat narration cadence, ms (default 15000). */
+        heartbeatMs?: number;
+        /** Durable replay-dedup ledger path (default ~/.wicked-crew/interactive-demo-ledger.json). */
+        ledgerPath?: string;
+        /** Where governed workers write specs (default ~/.wicked-crew/interactive-demos). */
+        demoDir?: string;
+        /** Seat roster override (JSON array); omit for the production council roster. */
+        clisJson?: string;
+        /** Docs-root resolver override (tests); default = per-project `interactiveRoot` setting. */
+        resolveDocsRoot?: (projectId: string | undefined) => string;
+    };
+    /**
+     * Opt-in governed answering of wicked-interactive's conversational ITERATION asks
+     * (CREW-UX-5, the doc thread's plain send). When enabled, a durable subscriber answers
+     * `wicked.interactive.chat.posted` (role:user, existing kind:source doc, not an in-flight
+     * doc, not a feedback-batch echo) with a governed `interactive-chat` run —
+     * understand-the-ask → revise — that ends in `wicked.interactive.draft.completed` (the
+     * service lands the revised full HTML as a generated version). Asks on a busy doc queue
+     * FIFO per doc. When absent (the default), the topic goes unanswered — the pre-CREW-UX-5
+     * state.
+     */
+    interactiveChatEvents?: {
+        enabled: boolean;
+        /** Bus db path; omit for wicked-bus's own default resolution (honors WICKED_BUS_DATA_DIR). */
+        dbPath?: string;
+        /** Poll cadence, ms (tests shorten it). */
+        pollIntervalMs?: number;
+        /** Heartbeat narration cadence, ms (default 15000). */
+        heartbeatMs?: number;
+        /** Durable replay-dedup ledger path (default ~/.wicked-crew/interactive-chat-ledger.json). */
+        ledgerPath?: string;
+        /** Where head snapshots land and workers write revisions (default ~/.wicked-crew/interactive-chats). */
+        chatDir?: string;
+        /** Seat roster override (JSON array); omit for the production council roster. */
+        clisJson?: string;
+        /** Queue-drain sweep cadence, ms (tests shorten it). */
+        queueSweepMs?: number;
+        /** Post-completion landing-gate timeout, ms (tests shorten it). */
+        landingGateMs?: number;
+        /** Docs-root resolver override (tests); default = per-project `interactiveRoot` setting. */
+        resolveDocsRoot?: (projectId: string | undefined) => string;
     };
     /**
      * The project bus seam (DES-PROJECT-001 §4/§5.2). DEFAULT-ON, unlike the opt-in seams
@@ -117,6 +180,22 @@ export interface CreateServerOptions {
         intervalMs?: number;
         timeoutMs?: number;
     };
+    /**
+     * The worker stall watchdog (crew#287): DETECTION ONLY. For every run whose engine status is
+     * `executing`, the daemon tracks the last CoreEvent observed on its own relay (any frame for
+     * that run, `unitOutputDelta` included); silence past `workerStallMinutes` (setting, default
+     * 15) broadcasts ONE synthetic `{ type: "workerStalled", session, ord?, quietForMs }` frame
+     * on /ws per quiet period and logs at warn. Any new event re-arms. The run is never killed
+     * or mutated — the operator decides. `enabled` defaults to ON in the daemon and OFF under a
+     * test runner (VITEST / NODE_ENV=test), the seat-health-probe posture.
+     */
+    stallWatchdog?: {
+        enabled?: boolean;
+        /** Sweep cadence, ms (default 30 s; tests shorten it). */
+        sweepIntervalMs?: number;
+        /** Threshold override, minutes — bypasses the settings read (tests). */
+        stallMinutes?: number;
+    };
 }
 export declare function createServer(adapter: CoreAdapter, options?: CreateServerOptions): Promise<ReturnType<typeof Fastify>>;
 export interface StartedServer {

package/dist/api/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/api/server.ts"],"names":[],"mappings":"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"}

package/dist/api/server.js

@@ -8,18 +8,26 @@ import { GateCache } from './gate-cache.js';
 import { ElicitationCache } from './elicitation-cache.js';
 import { registerAuthHooks, resolveAuth } from './auth.js';
 import { AuditLog } from './audit.js';
+import { RetryIndex } from './retry-index.js';
+import { GuidanceIndex } from './guidance-index.js';
 import { registerClient, broadcast } from '../events/bus.js';
 import { TerminalHub, registerTerminalWs } from '../events/terminals.js';
 import { QeGateCache, startQeGateSubscriber } from '../qe/gate-events.js';
 import { startInteractiveDraftSubscriber } from '../interactive/draft-events.js';
 import { startInteractiveEditSubscriber } from '../interactive/edit-events.js';
+import { startInteractiveChatSubscriber } from '../interactive/chat-events.js';
+import { startInteractiveDemoSubscriber } from '../interactive/demo-events.js';
+import { resolveInteractiveRoot } from '../interactive/bridge-root.js';
+import { ProjectSettingsStore } from '../projects/settings.js';
 import { startProjectBus, MEMBERSHIP_ATTACHED, membershipAttachedKey } from '../projects/events.js';
 import { startInteractiveWsRelay, registerInteractiveEventRoutes } from '../interactive/ws-relay.js';
 import { MembershipIndex } from '../projects/membership-index.js';
 import { writeRunEvidencePointer } from '../projects/charter.js';
 import { CoreAdapter } from '../core/adapter.js';
 import { SeatHealthTracker, startSeatHealthProbe } from './seat-health.js';
+import { WorkerStallWatchdog } from './stall-watchdog.js';
 import { applyWorkerConfigRoot } from './seat-signin.js';
+import { DEFAULT_WORKER_STALL_MINUTES } from '../core/types.js';
 // Allow the studio (a separate localhost origin, e.g. :4200) to call the
 // daemon's REST API. Restricted to loopback origins — the daemon only binds
 // 127.0.0.1, so this never widens exposure beyond the local machine.
@@ -68,6 +76,19 @@ export async function createServer(adapter, options) {
     // post-commit half (index tag + membership.attached emit) via `fileRun`.
     const membershipIndex = new MembershipIndex();
     await membershipIndex.hydrate(adapter, (m) => app.log.warn(m));
+    // Per-project crew-side settings (DES-MERGE-001 §7.1's `interactiveRoot`). ONE instance,
+    // created here so the chat seam's docs-root resolution below and the routes (project PATCH +
+    // interactive proxy) all read/write the same store — two instances over one file would let a
+    // PATCH land in one while the other keeps serving the stale root.
+    const projectSettings = new ProjectSettingsStore();
+    // Retry lineage (CREW-UX-3): hydrated from the audit trail — the durable record the launch
+    // route writes — so a restarted daemon still echoes `retry_of` on prior runs' DTOs.
+    const retryIndex = new RetryIndex();
+    await retryIndex.hydrate(audit, (m) => app.log.warn(m));
+    // Operator guidance (CREW-UX-7, DES-UX-002 §7.2): same durable pattern — hydrated from the
+    // trail's `guidance.set` entries so notes survive a daemon restart.
+    const guidanceIndex = new GuidanceIndex();
+    await guidanceIndex.hydrate(audit, (m) => app.log.warn(m));
     const projectBus = options?.projectEvents?.disabled === true
         ? null
         : await startProjectBus({
@@ -118,6 +139,11 @@ export async function createServer(adapter, options) {
         // under the task #88 rule that event actors are never caller-supplied.
         { project_id: projectId, member: { kind: 'crew.run', ref: runId }, actor: 'interactive' }, membershipAttachedKey(projectId, 'crew.run', runId, Date.now()));
     };
+    /** The docs root a project's interactive docs live under — the SAME per-project settings
+     *  resolution the project routes, the interactive proxy, and the chat seam share
+     *  (DES-MERGE-001 §7.1/§7.2). Shared by the edit seam (demo-kind gate, CREW-UX-9) and the
+     *  demo seam (spec install + manifest reads). */
+    const interactiveDocsRoot = (projectId) => resolveInteractiveRoot(projectId !== undefined ? projectSettings.get(projectId) : null);
     // Arm the opt-in QE gate-event subscription (crew's bus seam). Failure to
     // arm is LOUD but non-fatal: the acceptance route never depends on the bus.
     if (options?.qeGateEvents?.enabled === true) {
@@ -136,10 +162,12 @@ export async function createServer(adapter, options) {
     }
     // Arm the opt-in interactive-draft answering seam (task #86 spike). Same posture as the QE
     // seam: failure to arm is LOUD but non-fatal — interactive's assist loop is the fallback
-    // answerer, and this daemon must boot on a machine whose bus is broken.
+    // answerer, and this daemon must boot on a machine whose bus is broken. The handle is kept:
+    // the chat seam below consults its in-flight docs (CREW-UX-5 per-doc serialization).
+    let draftSub = null;
     if (options?.interactiveDraftEvents?.enabled === true) {
         const o = options.interactiveDraftEvents;
-        const sub = await startInteractiveDraftSubscriber(adapter, {
+        draftSub = await startInteractiveDraftSubscriber(adapter, {
             ...(o.dbPath !== undefined ? { dbPath: o.dbPath } : {}),
             ...(o.pollIntervalMs !== undefined ? { pollIntervalMs: o.pollIntervalMs } : {}),
             ...(o.heartbeatMs !== undefined ? { heartbeatMs: o.heartbeatMs } : {}),
@@ -149,35 +177,118 @@ export async function createServer(adapter, options) {
             onRunFiled: fileRun,
             log: (m) => app.log.warn(m),
         });
-        if (sub !== null) {
+        if (draftSub !== null) {
+            const sub = draftSub;
             app.log.info('interactive-draft subscription armed (filter wicked.interactive.doc.created)');
             app.addHook('onClose', async () => {
                 await sub.stop();
             });
         }
     }
+    // Declared BEFORE the edit seam it is probed by: the demo seam arms after (it must, so the
+    // per-doc serialization contract can see the edit seam's in-flight set), but the edit seam's
+    // demo-kind gate needs to know at EVENT time whether the demo seam actually came up. A
+    // closure over this binding reads the settled value; a boolean captured here would not.
+    let demoSub = null;
     // Arm the opt-in interactive STRUCTURAL-edit answering seam (task #86 final leg). Same
     // posture as the draft seam: failure to arm is LOUD but non-fatal — interactive's assist
     // loop is the fallback answerer, and this daemon must boot on a machine whose bus is broken.
+    let editSub = null;
     if (options?.interactiveEditEvents?.enabled === true) {
         const o = options.interactiveEditEvents;
-        const sub = await startInteractiveEditSubscriber(adapter, {
+        editSub = await startInteractiveEditSubscriber(adapter, {
             ...(o.dbPath !== undefined ? { dbPath: o.dbPath } : {}),
             ...(o.pollIntervalMs !== undefined ? { pollIntervalMs: o.pollIntervalMs } : {}),
             ...(o.heartbeatMs !== undefined ? { heartbeatMs: o.heartbeatMs } : {}),
             ...(o.ledgerPath !== undefined ? { ledgerPath: o.ledgerPath } : {}),
             ...(o.editDir !== undefined ? { editDir: o.editDir } : {}),
             ...(o.clisJson !== undefined ? { clisJson: o.clisJson } : {}),
+            // The demo-kind gate (CREW-UX-9): a demo doc's step feedback is the demo seam's — but
+            // only when that seam is actually up. Probed per event (the demo seam arms below), so an
+            // un-armed demo seam gets an honest error status instead of a silent, unanswerable drop.
+            resolveDocsRoot: o.resolveDocsRoot ?? interactiveDocsRoot,
+            demoSeamArmed: () => demoSub !== null,
             onRunFiled: fileRun,
             log: (m) => app.log.warn(m),
         });
-        if (sub !== null) {
+        if (editSub !== null) {
+            const sub = editSub;
             app.log.info('interactive-edit subscription armed (filter wicked.interactive.feedback.processed)');
             app.addHook('onClose', async () => {
                 await sub.stop();
             });
         }
     }
+    // Arm the opt-in interactive DEMO answering seam (CREW-UX-9 — the retired assist agent's
+    // Step 8). Same posture as the sibling seams: failure to arm is LOUD but non-fatal — a demo
+    // doc then keeps its placeholder, and this daemon must boot on a machine whose bus is
+    // broken. Armed beside the edit seam because the two split `feedback.processed` by the doc
+    // manifest's kind (demo → re-author the spec here; everything else → structural edit there).
+    if (options?.interactiveDemoEvents?.enabled === true) {
+        const o = options.interactiveDemoEvents;
+        demoSub = await startInteractiveDemoSubscriber(adapter, {
+            ...(o.dbPath !== undefined ? { dbPath: o.dbPath } : {}),
+            ...(o.pollIntervalMs !== undefined ? { pollIntervalMs: o.pollIntervalMs } : {}),
+            ...(o.heartbeatMs !== undefined ? { heartbeatMs: o.heartbeatMs } : {}),
+            ...(o.ledgerPath !== undefined ? { ledgerPath: o.ledgerPath } : {}),
+            ...(o.demoDir !== undefined ? { demoDir: o.demoDir } : {}),
+            ...(o.clisJson !== undefined ? { clisJson: o.clisJson } : {}),
+            resolveDocsRoot: o.resolveDocsRoot ?? interactiveDocsRoot,
+            onRunFiled: fileRun,
+            log: (m) => app.log.warn(m),
+        });
+        if (demoSub !== null) {
+            const sub = demoSub;
+            app.log.info('interactive-demo subscription armed (filters wicked.interactive.doc.created + feedback.processed, kind:demo)');
+            app.addHook('onClose', async () => {
+                await sub.stop();
+            });
+        }
+    }
+    // Arm the opt-in interactive CHAT answering seam (CREW-UX-5 — the iteration ask). Same
+    // posture again: failure to arm is LOUD but non-fatal. Armed AFTER the sibling seams so the
+    // per-doc serialization contract (no draft/edit/chat run races another on one doc) can
+    // consult their in-flight sets; docs roots resolve through the SAME per-project settings
+    // store the project routes and the interactive proxy share.
+    if (options?.interactiveChatEvents?.enabled === true) {
+        const o = options.interactiveChatEvents;
+        const sub = await startInteractiveChatSubscriber(adapter, {
+            ...(o.dbPath !== undefined ? { dbPath: o.dbPath } : {}),
+            ...(o.pollIntervalMs !== undefined ? { pollIntervalMs: o.pollIntervalMs } : {}),
+            ...(o.heartbeatMs !== undefined ? { heartbeatMs: o.heartbeatMs } : {}),
+            ...(o.ledgerPath !== undefined ? { ledgerPath: o.ledgerPath } : {}),
+            ...(o.chatDir !== undefined ? { chatDir: o.chatDir } : {}),
+            ...(o.clisJson !== undefined ? { clisJson: o.clisJson } : {}),
+            ...(o.queueSweepMs !== undefined ? { queueSweepMs: o.queueSweepMs } : {}),
+            ...(o.landingGateMs !== undefined ? { landingGateMs: o.landingGateMs } : {}),
+            resolveDocsRoot: o.resolveDocsRoot ??
+                ((projectId) => resolveInteractiveRoot(projectId !== undefined ? projectSettings.get(projectId) : null)),
+            isDocBusy: (documentId) => (draftSub?.inFlightDocs().includes(documentId) ?? false) ||
+                (editSub?.inFlightDocs().includes(documentId) ?? false),
+            onRunFiled: fileRun,
+            log: (m) => app.log.warn(m),
+        });
+        if (sub !== null) {
+            app.log.info('interactive-chat subscription armed (filter wicked.interactive.chat.posted)');
+            app.addHook('onClose', async () => {
+                await sub.stop();
+            });
+        }
+    }
+    // The worker stall watchdog (crew#287). Built BEFORE the single CoreEvent subscription below
+    // so every relayed frame stamps its run's liveness clock; armed (sweep interval) further down
+    // beside the seat-health probe, under the same test-runner gate. Detection only: its sole
+    // outputs are one synthetic `workerStalled` /ws frame per quiet period and a warn log.
+    const stallWatchdog = new WorkerStallWatchdog({
+        listExecuting: async () => (await adapter.sessionsDetail())
+            .filter((v) => v.session.status === 'executing')
+            .map((v) => ({ id: v.session.id, ord: v.session.unit_ix })),
+        broadcast: (frame) => broadcast(frame),
+        stallMinutes: async () => options?.stallWatchdog?.stallMinutes ??
+            (await adapter.getSettings()).workerStallMinutes ??
+            DEFAULT_WORKER_STALL_MINUTES,
+        log: (m) => app.log.warn(m),
+    });
     // The daemon's single CoreEvent subscription fans out here: cache gate prompts
     // (§3.3), cache elicitation prompts (DES-002), route terminal frames to their owning
     // per-terminal socket (by id, DES-TERMINAL-001 §6), then forward every frame — tagged
@@ -187,10 +298,17 @@ export async function createServer(adapter, options) {
     // Unregistered on close: a process can build more than one server over the same
     // adapter (tests do), and a closed server's caches must stop consuming events —
     // otherwise every discarded server keeps folding state forever (listener leak).
+    const stallWatchdogArmed = options?.stallWatchdog?.enabled ??
+        !(process.env['VITEST'] !== undefined || process.env['NODE_ENV'] === 'test');
     const offEvent = adapter.onEvent((event) => {
         gateCache.ingest(event);
         elicitationCache.ingest(event);
         seatHealth.ingest(event);
+        // Only feed the watchdog when its sweep is (or will be) armed: sweeping is what
+        // prunes its per-run maps, so ingesting while disabled grows without bound
+        // (Copilot on #301).
+        if (stallWatchdogArmed)
+            stallWatchdog.ingest(event);
         terminals.route(event);
         const session = typeof event.session === 'string' ? event.session : undefined;
         const projectId = session !== undefined ? membershipIndex.projectOf(session) : undefined;
@@ -235,6 +353,16 @@ export async function createServer(adapter, options) {
             probe.stop();
         });
     }
+    // Arm the stall watchdog's sweep (crew#287). Same gate as the probe: ON in the daemon, OFF
+    // under a test runner unless a test opts in — a suite building servers over stub adapters
+    // must not have a background interval calling `sessionsDetail()` on them.
+    const stallCfg = options?.stallWatchdog;
+    if (stallWatchdogArmed) {
+        stallWatchdog.start(stallCfg?.sweepIntervalMs);
+        app.addHook('onClose', async () => {
+            stallWatchdog.stop();
+        });
+    }
     app.addHook('onRequest', async (req, reply) => {
         const origin = req.headers.origin;
         // Loopback origins are always allowed (the studio on another localhost
@@ -288,7 +416,8 @@ export async function createServer(adapter, options) {
         bus: projectBus,
         index: membershipIndex,
         log: (m) => app.log.warn(m),
-    }, { audit, authMode: auth.mode }, { seatHealth });
+        settings: projectSettings,
+    }, { audit, authMode: auth.mode }, { seatHealth, retryIndex, guidanceIndex });
     // The UI-emittable direction of the interactive seam. Registered unconditionally (a null relay
     // answers 503, not 404) and BEFORE the static/SPA fallback below, like every other API route.
     registerInteractiveEventRoutes(app, interactiveRelay);