wicked-crew 0.6.0 → 0.7.0

package/dist/interactive/chat-events.js

@@ -0,0 +1,769 @@
+/**
+ * Opt-in governed answering of wicked-interactive's conversational ITERATION asks (CREW-UX-5 —
+ * the third interactive leg, beside draft-events.ts and edit-events.ts).
+ *
+ * A finished doc's thread send in wicked-studio does `postFork` (mints a version) and injects
+ * `wicked.interactive.chat.posted` — and NOTHING consumed that topic since the ad-hoc assist
+ * agent retired: crew answers `doc.created` (the first draft) and `feedback.processed` (the
+ * structural handoff), but the plain conversational ask ("make the intro punchier") had no
+ * answerer, so BRIEF-UX-001 J3's "iterate twice" was impossible. This module makes a
+ * crew-governed run the answerer: understand-the-ask → revise, announced back on the SAME
+ * `draft.completed` wire the first draft rides — the service lands the revised full HTML as a
+ * generated version (`materializeDraft` → `applyGeneratedHtml`), which is exactly what an
+ * iteration is.
+ *
+ * Shape mirrors draft-events.ts (dynamic wicked-bus import, graceful degradation, durable
+ * cursor `cursor_init: 'latest'` under a dedicated plugin name, durable replay-dedup ledger,
+ * `wi-crew` narration via status.posted). The chat-specific deltas:
+ *
+ *  - THE TRIGGER IS A CONVERSATION LINE, so the actionable filter is layered (the contract):
+ *    (a) `role: "user"` only — agent narration echoes also ride chat.posted;
+ *    (b) the doc must EXIST under the resolved docs root and not belong to a foreign loop —
+ *        and the disk truth here is subtle: interactive's `initManifest` only ever RECORDS a
+ *        `kind` for demo docs (a real `kind: "source"` doc's versions.json carries NO kind
+ *        field at all — the "source" spelling rides the doc.created EVENT only; verified
+ *        against interactive 0.8.0 and main, src/service/server.js `initWorkspace(dir, html)`).
+ *        So the gate accepts `source` (future manifests may record it) and the absent-default
+ *        `doc`, and rejects explicit foreign kinds (`demo`) — a doc we cannot see is not ours
+ *        to answer either;
+ *    (c) per-doc serialization — an ask on a doc whose draft/edit/chat run is still in flight
+ *        is QUEUED (FIFO per doc), never raced: two concurrent revisions of one doc would
+ *        land as two forks of the same parent and the second would silently drop the first;
+ *    (d) the text must be an ASK, not an echo of a machine-composed message — the feedback
+ *        overlay injects its batch as a chat.posted TOO (same `source_message_id` as its
+ *        `feedback.submitted`), and that batch is already the edit seam's business.
+ *  - VERSION SNAPSHOT AT LAUNCH: the seam copies the doc's CURRENT HEAD html into the chat
+ *    inbox and names the COPY in the task, so (1) the worker never needs read access to the
+ *    doc workspace (the one declared write root covers input + deliverable — crew#263 /
+ *    wicked-core#259: write roots are readable) and (2) a queued second ask snapshots the
+ *    head AFTER the first revision landed — which is what "iterate twice" means.
+ *  - THE LANDING GATE: `draft.completed` is announced by path and the service lands the new
+ *    version ASYNCHRONOUSLY. A queued ask drained the instant our run completes would snapshot
+ *    the stale head and silently drop the revision the user just watched land. So a successful
+ *    completion arms a per-doc gate — drain only once the manifest head ADVANCES past the head
+ *    we launched from, or a timeout passes (the service may be down; waiting forever would
+ *    strand the queue).
+ *  - IDEMPOTENCY KEYING: one doc legitimately produces many asks over its life, so the dedupe
+ *    unit is the ASK — `source_message_id` when the frame carries one (the studio reuses the
+ *    SAME message id on a user-driven resend, so a retry that reached the bus twice dedupes),
+ *    else the bus `event_id` (pure redelivery). Never the doc lifetime.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { DOC_NAME, DRAFT_COMPLETED, INTERACTIVE_DOMAIN, INTERACTIVE_PRODUCER, STATUS_POSTED, oneLine, } from './draft-events.js';
+import { InteractiveHandoffLedger } from './ledger.js';
+import { resolveInteractiveRoot } from './bridge-root.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 CHAT_POSTED = 'wicked.interactive.chat.posted';
+/** Exact-type filter with a domain guard — no wildcard, one event type is the whole trigger. */
+export const INTERACTIVE_CHAT_BUS_FILTER = `${CHAT_POSTED}@${INTERACTIVE_DOMAIN}`;
+/** Dedicated durable-cursor identity — NOT the draft/edit seams', so the three interactive
+ *  seams advance independent cursors and stopping one never strands another. */
+export const INTERACTIVE_CHAT_BUS_PLUGIN = 'wicked-crew-interactive-chat';
+// ── The workflow (workflows-as-data) ─────────────────────────────────────────────────────────
+export const INTERACTIVE_CHAT_WORKFLOW = 'interactive-chat';
+/**
+ * The governed workflow that fulfils an iteration ask. Two agent phases — understand (recon)
+ * then revise (build, creator role) — the draft leg's sibling: the reviser builds on a stated
+ * plan instead of one-shotting a rewrite, and the run narrates a real phase transition.
+ *
+ * The phase `instructions` carry the ITERATION contract: start from the CURRENT document (the
+ * snapshot path named in the task), change only what the ask touches, KEEP every existing
+ * `data-wid` on kept elements (interactive's instrument pass preserves pre-existing anchors —
+ * INV-1 — so feedback deep-links survive the iteration) and mint none on added ones. They are
+ * SINGLE-LINE by contract (PTY seat runner, wicked-core FINDING-011).
+ *
+ * All gates are `auto` with `validator_pin: null` — same rationale as the draft leg: the
+ * acceptance gate for a revision is interactive's instrument+theme pipeline and the user's own
+ * eyes on the canvas.
+ */
+export const INTERACTIVE_CHAT_WORKFLOW_DEF = {
+    id: INTERACTIVE_CHAT_WORKFLOW,
+    is_system: true,
+    phases: [
+        {
+            id: 'understand',
+            kind: 'recon',
+            instructions: 'Understand the revision ask, do not write anything yet: read the CURRENT document — the absolute HTML file path named in the task — and the user\'s ask, then produce a concise revision plan as plain text: which sections change, what gets added or removed, and what stays untouched (the default is untouched — this is an iteration on a document the user already accepted, not a rewrite). Never invent facts, numbers, or claims the current document and the ask do not support; where the ask needs material the document lacks, plan honest placeholder copy that says what belongs there. Do NOT write HTML and do NOT create any files in this phase.',
+            gate_type: 'value',
+            gate: 'auto',
+            executes_code: false,
+            verified_evidence: false,
+            required_deliverables: [],
+            depends_on: [],
+            role: 'neutral',
+            skill_ref: null,
+            allowed_skills: [],
+            validator_pin: null,
+        },
+        {
+            id: 'revise',
+            kind: 'build',
+            instructions: 'Using the plan from the prior phase, write the COMPLETE revised HTML document and SAVE it to the absolute output file named in the task (create parent directories if needed, overwrite if present) — the file on disk is the deliverable, so write it before you finish and end your reply with the absolute path you wrote. Contract: start from the CURRENT document (the absolute input path named in the task) and apply the user\'s ask — change only what the ask touches and keep everything else, including the document\'s style and structure; produce a full self-contained HTML document (inline CSS, no external network resources, no build step); KEEP every existing data-wid attribute byte-for-byte on elements you keep, and add NO data-wid to elements you create (the wicked-interactive service instruments its own anchors); never fabricate facts or figures; keep the markup semantic and well-formed (balanced tags) so the instrumentation pass lands cleanly.',
+            gate_type: 'execution',
+            gate: 'auto',
+            executes_code: false,
+            verified_evidence: false,
+            required_deliverables: [],
+            depends_on: ['understand'],
+            role: 'creator',
+            skill_ref: null,
+            allowed_skills: [],
+            validator_pin: null,
+        },
+    ],
+};
+/**
+ * Parse a bus frame into a {@link ChatAsk}, or `null` when it is not an actionable ask:
+ * wrong type, malformed payload, non-`user` role (contract (a) — agent narration and any
+ * transcript echo ride the same topic), slug-invalid document_id, or empty text. Kind and
+ * existence checks (contract (b)) happen against the filesystem, not the payload — the frame
+ * does not carry `kind`.
+ */
+export function parseChatPosted(eventType, payload) {
+    if (eventType !== CHAT_POSTED)
+        return null;
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const p = payload;
+    if (p['role'] !== 'user')
+        return null;
+    const documentId = typeof p['document_id'] === 'string' ? p['document_id'] : '';
+    if (!DOC_NAME.test(documentId))
+        return null;
+    const text = typeof p['text'] === 'string' ? p['text'].trim() : '';
+    if (text.length === 0)
+        return null;
+    const sourceMessageId = typeof p['source_message_id'] === 'string' && p['source_message_id'].length > 0
+        ? p['source_message_id']
+        : undefined;
+    const projectId = typeof p['project_id'] === 'string' && p['project_id'].length > 0 ? p['project_id'] : undefined;
+    return {
+        documentId,
+        text,
+        ...(sourceMessageId !== undefined ? { sourceMessageId } : {}),
+        ...(projectId !== undefined ? { projectId } : {}),
+    };
+}
+/** The feedback overlay's machine-composed batch header (studio `composeBatchMessage`): the
+ *  batch is injected as a chat.posted for TRANSCRIPT fidelity, but the document work it names
+ *  already rides `feedback.submitted` → the deterministic apply / the edit seam. */
+const FEEDBACK_BATCH_ECHO = /^feedback on \d+ places? in /i;
+/** Contract (d): `true` when the text is a conversational ask this seam should answer —
+ *  not the feedback overlay's batch echo (already answered elsewhere). */
+export function isIterationAsk(text) {
+    return !FEEDBACK_BATCH_ECHO.test(text.trim());
+}
+/** The one dedupe unit of this seam: the ASK — the studio's message id when the frame carries
+ *  one (a resend reuses it), else the bus event id (pure redelivery). Never the doc lifetime. */
+export function chatKey(documentId, eventId, sourceMessageId) {
+    return sourceMessageId !== undefined ? `${documentId}:m:${sourceMessageId}` : `${documentId}:e:${eventId}`;
+}
+/** Deterministic bus idempotency key for the one revision this seam may land per ask. */
+export function chatIdempotencyKey(documentId, eventId, sourceMessageId) {
+    return `crew:interactive.chat:${chatKey(documentId, eventId, sourceMessageId)}`;
+}
+/**
+ * Read a doc workspace's manifest (interactive's `versions.json`, fsstore.js shape) and resolve
+ * its head html path. `null` when the doc does not exist under this root or the manifest is
+ * unreadable — not ours to answer, per contract (b). Follows interactive's own tolerant read:
+ * `kind` defaults to `"doc"` when absent (listDocs does the same) — and ABSENT is what a real
+ * source doc looks like on disk (interactive records kind only for demo docs), so the caller
+ * gates through {@link isAnswerableDocKind}, never a `=== 'source'` comparison.
+ */
+export function readDocHead(docsRoot, documentId) {
+    if (!DOC_NAME.test(documentId))
+        return null;
+    const dir = join(docsRoot, documentId);
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, 'versions.json'), 'utf8'));
+        const head = manifest.head;
+        if (typeof head !== 'number' || !Number.isInteger(head) || head < 0)
+            return null;
+        const entry = Array.isArray(manifest.versions)
+            ? manifest.versions.find((v) => v?.version === head)
+            : undefined;
+        // Containment (Copilot, #310): `html_file` comes from a manifest on disk — a corrupted or
+        // hostile value carrying path separators or `..` must never escape the doc dir. Only a plain
+        // basename is accepted; anything else falls back to the version's canonical spelling.
+        const rawHtmlFile = typeof entry?.html_file === 'string' && entry.html_file.length > 0
+            ? entry.html_file
+            : `_v${head}.html`;
+        const htmlFile = basename(rawHtmlFile) === rawHtmlFile && !rawHtmlFile.includes('..')
+            ? rawHtmlFile
+            : `_v${head}.html`;
+        return {
+            kind: typeof manifest.kind === 'string' && manifest.kind.length > 0 ? manifest.kind : 'doc',
+            head,
+            headHtmlPath: join(dir, htmlFile),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Contract (b)'s kind half: `true` when a doc of this manifest kind is this seam's to answer.
+ * `source` is the spec's spelling (recorded by no released interactive yet, accepted for the
+ * day a manifest carries it); `doc` is the absent-default every REAL source (and plain html)
+ * doc reads as — interactive's initManifest keeps non-demo kinds implicit. Explicit foreign
+ * kinds (`demo`, anything future) belong to their own loops.
+ */
+export function isAnswerableDocKind(kind) {
+    return kind === 'source' || kind === 'doc';
+}
+/**
+ * The run's problem statement (the engine scopes it per phase and folds each phase's
+ * instructions on top). Carries everything ask-specific: identity, the flattened ask, the
+ * CURRENT-version snapshot to read, and the absolute path the revised HTML must land at.
+ *
+ * CREW-UX-8 SPLIT — the revision leg carries NO repo grounding, deliberately. The draft leg
+ * (draft-events.ts) grounds its v1 in a launch-scoped repo snapshot and that shape is proven
+ * live; the SAME shape on the revise turn wedged 2/2 on the real engine (crew#288 comment —
+ * the repo-grounded revise turn hits the known second-turn wedge), while UNGROUNDED revisions
+ * are proven to land (the CREW-UX-5 verification). So bound asks launch exactly like unfiled
+ * ones — head-copy in the external inbox, one write root, no repoRef (wicked-core#293), no
+ * live-repo path in the task (wicked-core#294). Revision grounding returns when either of
+ * those is fixed.
+ */
+export function chatProblem(ask, currentPath, outPath) {
+    return (`Revise the wicked-interactive document "${ask.documentId}" per the user's ask. ` +
+        `The user's ask: ${oneLine(ask.text, 2000)} ` +
+        `The document's CURRENT version is the HTML file at this absolute path — read it first: ${currentPath} ` +
+        `The revised COMPLETE document MUST be written to exactly this absolute file path: ${outPath}`);
+}
+function defaultStateDir() {
+    return join(homedir(), '.wicked-crew');
+}
+/** The production council roster, resolved lazily through the adapter's own class so this module
+ *  never imports the native addon at runtime (unit tests pass `clisJson` and a fake adapter). */
+function rosterOf(adapter) {
+    return adapter.constructor.roster();
+}
+/**
+ * Arm the seam: register the `interactive-chat` workflow, open a durable
+ * `wicked.interactive.chat.posted` subscription, and answer each user ask on an existing
+ * answerable doc (contract (b)) with a governed run that ends in `wicked.interactive.draft.completed`
+ * (the service lands the revised full HTML as a generated version).
+ *
+ * Graceful degradation mirrors the sibling seams: a missing wicked-bus package or an
+ * unopenable db LOGS and returns `null` — the daemon must still boot on a machine whose bus
+ * is broken.
+ */
+export async function startInteractiveChatSubscriber(adapter, opts = {}) {
+    const log = opts.log ?? ((m) => console.error(m));
+    let bus;
+    try {
+        bus = await import('wicked-bus');
+    }
+    catch (err) {
+        log(`[interactive-chat] wicked-bus is not importable — governed iteration disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let db;
+    let config;
+    try {
+        config = bus.loadConfig(opts.dbPath !== undefined ? { db_path: opts.dbPath } : {});
+        db = bus.openDb(opts.dbPath !== undefined ? { db_path: opts.dbPath } : {});
+    }
+    catch (err) {
+        log(`[interactive-chat] could not open the bus db${opts.dbPath !== undefined ? ` at ${opts.dbPath}` : ''} — governed iteration disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    // The workflow rides the normal registration path — core validates the def BEFORE it is
+    // persisted/hot-registered (FINDING-002 ordering), so a drifted def fails the arm loudly
+    // instead of failing the first launch obscurely.
+    try {
+        await adapter.registerWorkflow(INTERACTIVE_CHAT_WORKFLOW_DEF);
+    }
+    catch (err) {
+        log(`[interactive-chat] could not register the '${INTERACTIVE_CHAT_WORKFLOW}' workflow — ` +
+            `governed iteration disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const ledger = new InteractiveHandoffLedger(opts.ledgerPath ?? join(defaultStateDir(), 'interactive-chat-ledger.json'));
+    const chatDir = opts.chatDir ?? join(defaultStateDir(), 'interactive-chats');
+    const heartbeatMs = opts.heartbeatMs ?? 15_000;
+    const landingGateMs = opts.landingGateMs ?? 60_000;
+    const resolveDocsRoot = opts.resolveDocsRoot ?? (() => resolveInteractiveRoot(null));
+    // +1 for the crew#311 deliverable floor the adapter appends per-run (`requireDeliverables`):
+    // `agentPhaseCount` drives the council/worker branches, `phaseCount` is the run's real length.
+    const agentPhaseCount = INTERACTIVE_CHAT_WORKFLOW_DEF.phases.length;
+    const phaseCount = agentPhaseCount + 1;
+    const inFlight = new Map(); // runId → live state
+    const queues = new Map(); // documentId → parked asks, FIFO
+    const landingGates = new Map(); // documentId → post-completion gate
+    /** 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 announce (WB-002) is the idempotency key WORKING. */
+    function emitInteractive(type, payload, idempotencyKey) {
+        try {
+            bus.emit(db, config, {
+                event_type: type,
+                domain: INTERACTIVE_DOMAIN,
+                subdomain: type === DRAFT_COMPLETED ? 'generation' : 'status',
+                payload: { ts: new Date().toISOString(), ...payload },
+                producer_id: INTERACTIVE_PRODUCER,
+                ...(idempotencyKey !== undefined ? { idempotency_key: idempotencyKey } : {}),
+            });
+            return true;
+        }
+        catch (err) {
+            const code = err.error;
+            if (code === 'WB-002') {
+                // Duplicate idempotency key — the emit already happened (redelivery race). Success.
+                return true;
+            }
+            log(`[interactive-chat] emit ${type} failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    function narrate(flight, message) {
+        flight.narration = message;
+        emitInteractive(STATUS_POSTED, {
+            document_id: flight.documentId,
+            state: 'working',
+            message,
+        });
+    }
+    function endFlight(runId) {
+        const flight = inFlight.get(runId);
+        if (flight) {
+            clearInterval(flight.heartbeat);
+            inFlight.delete(runId);
+        }
+        return flight;
+    }
+    function docHasFlight(documentId) {
+        for (const f of inFlight.values()) {
+            if (f.documentId === documentId)
+                return true;
+        }
+        return false;
+    }
+    /** Contract (c): the doc is busy while ANY governed run is working it — our own chat runs
+     *  plus whatever the sibling draft/edit seams report through `isDocBusy`. */
+    function docBusy(documentId) {
+        return docHasFlight(documentId) || opts.isDocBusy?.(documentId) === true;
+    }
+    /** 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) => {
+        const runId = typeof event.session === 'string' ? event.session : undefined;
+        if (runId === undefined)
+            return;
+        const flight = inFlight.get(runId);
+        if (flight === undefined)
+            return;
+        // Narration ladder — same rationale as the draft fold: the heartbeat repeats the LATEST
+        // line and the transcript dedups repeats, so advancing the line = visible progress.
+        const phaseName = (ord) => ord > agentPhaseCount
+            ? DELIVERABLE_FLOOR_PHASE_ID
+            : (INTERACTIVE_CHAT_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…" in the
+        // reader's thread. Drop those two lines for the floor ord.
+        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;
+            const council = seats > 0 ? `a ${seats}-seat council` : 'a council';
+            narrate(flight, `Convening ${council} to pick who ${ord >= agentPhaseCount ? 'revises the document' : 'reads your ask'}…`);
+            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)` : '';
+            narrate(flight, `Council picked ${who} for ${phaseName(ord)}${pct}…`);
+            return;
+        }
+        if (event.type === 'unitDispatched') {
+            const ord = typeof event.ord === 'number' ? event.ord : 0;
+            const phase = phaseName(ord);
+            narrate(flight, ord > agentPhaseCount
+                ? `Crew phase ${ord}/${phaseCount}: checking the revised document was actually written (${phase})…`
+                : ord >= agentPhaseCount
+                    ? `Crew phase ${ord}/${phaseCount}: revising the document (${phase})…`
+                    : `Crew phase ${ord}/${phaseCount}: ${phase} — reading the current version and your ask…`);
+            return;
+        }
+        if (event.type === 'toolInvoked') {
+            const tools = Array.isArray(event.tools) ? [...new Set(event.tools)].join(', ') : '';
+            if (tools)
+                narrate(flight, `Worker is using ${tools} on your document…`);
+            return;
+        }
+        if (event.type === 'unitOutputCaptured') {
+            const ord = typeof event.ord === 'number' ? event.ord : 0;
+            narrate(flight, `${phaseName(ord)} finished — the governance gate is reviewing it…`);
+            return;
+        }
+        if (event.type === 'gateDecided' && event.allow === true) {
+            const ord = typeof event.ord === 'number' ? event.ord : 0;
+            narrate(flight, ord > agentPhaseCount
+                ? 'Revised document verified on disk — landing it now…'
+                : ord >= agentPhaseCount
+                    ? 'Gate approved the revision — checking the file landed…'
+                    : `Gate approved ${phaseName(ord)} — moving on…`);
+            return;
+        }
+        if (event.type === 'acpFallback') {
+            const who = typeof event.cliKey === 'string' ? event.cliKey : 'the worker';
+            narrate(flight, `${who}'s live session dropped — continuing in single-shot mode…`);
+            return;
+        }
+        if (event.type === 'sessionCompleted') {
+            endFlight(runId);
+            finalize(flight, runId);
+            drainDoc(flight.documentId);
+            return;
+        }
+        if (event.type === 'stepFailed') {
+            // Remember the engine's own reason (crew#311) so the terminal status can name it.
+            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);
+            ledger.recordFailure(flight.key);
+            const why = flight.failureDetail !== undefined ? ` Reason: ${oneLine(flight.failureDetail, 600)}` : '';
+            emitInteractive(STATUS_POSTED, {
+                document_id: flight.documentId,
+                state: 'error',
+                message: `The crew run answering your ask ${event.type === 'runCancelled' ? 'was cancelled' : 'failed'} ` +
+                    `(run ${runId}).${why} Inspect it via the crew API (GET /api/v1/runs/${runId}), then resend the message.`,
+            });
+            log(`[interactive-chat] run ${runId} for ask ${flight.key} ended: ${event.type}`);
+            // No landing gate on failure — nothing new is landing; the next queued ask (if any)
+            // proceeds on the head that is there.
+            drainDoc(flight.documentId);
+        }
+    });
+    function finalize(flight, runId) {
+        const { key, documentId, outPath } = flight;
+        let ok = false;
+        try {
+            ok = existsSync(outPath) && statSync(outPath).size > 0;
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok) {
+            ledger.recordFailure(key);
+            emitInteractive(STATUS_POSTED, {
+                document_id: documentId,
+                state: 'error',
+                message: `The crew run completed but produced no revised document at ${outPath} (run ${runId}). Resend the message to retry.`,
+            });
+            log(`[interactive-chat] run ${runId} completed but ${outPath} is missing/empty`);
+            return;
+        }
+        // Announce on the SAME wire the first draft rides (ADR-0019 D5: by path — the service
+        // reads the file and lands it as a generated version). The deterministic per-ask key
+        // makes a re-announce a WB-002 no-op.
+        const emitted = emitInteractive(DRAFT_COMPLETED, { document_id: documentId, html_path: outPath }, `crew:interactive.chat:${key}`);
+        if (!emitted) {
+            // The bus refused the announce (non-WB-002): the revision exists on disk but never
+            // reached the service. Fail HONEST — leaving the row launched-but-never-closed would
+            // silently eat a redelivery of this ask (the launch gate is `ledger.has`).
+            ledger.recordFailure(key);
+            emitInteractive(STATUS_POSTED, {
+                document_id: documentId,
+                state: 'error',
+                message: `Crew finished the revision but could not announce it on the bus (run ${runId}); ` +
+                    `the file is at ${outPath}. Inspect the crew daemon log, then resend the message.`,
+            });
+            log(`[interactive-chat] draft.completed emit FAILED for ask ${key} (run ${runId}) — recorded as failure`);
+            return;
+        }
+        ledger.recordEmitted(key);
+        // The landing gate (see module header): the SERVICE lands the announced file as a new
+        // version asynchronously — a queued ask drained right now would snapshot the pre-revision
+        // head and silently drop the revision that just finished. Hold this doc's queue until the
+        // manifest head advances past what this run launched from, or the timeout passes.
+        landingGates.set(documentId, {
+            minHead: flight.headAtLaunch + 1,
+            until: Date.now() + landingGateMs,
+        });
+        emitInteractive(STATUS_POSTED, {
+            document_id: documentId,
+            state: 'complete',
+            message: 'Revision is in — landing the new version on the canvas now.',
+        });
+        log(`[interactive-chat] draft.completed emitted for ask ${key} (run ${runId})`);
+    }
+    /** Launch the governed run for one ask. The head snapshot happens HERE — launch time, not
+     *  parse time — so a queued ask iterates on the version its predecessor landed. Throws on
+     *  launch failure (the caller decides: dead-letter for a live delivery, log for a drain). */
+    async function launchAsk(queued) {
+        const { ask, key } = queued;
+        const docsRoot = resolveDocsRoot(ask.projectId);
+        const doc = readDocHead(docsRoot, ask.documentId);
+        if (doc === null || !isAnswerableDocKind(doc.kind)) {
+            // The doc moved out from under a parked ask (deleted / never ours). Not an error the
+            // thread needs — contract (b) simply stopped holding.
+            log(`[interactive-chat] ask ${key} dropped at launch: doc ${ask.documentId} ${doc === null ? 'not found' : `has kind '${doc.kind}'`} under ${docsRoot}`);
+            return;
+        }
+        let headOk = false;
+        try {
+            headOk = existsSync(doc.headHtmlPath) && statSync(doc.headHtmlPath).size > 0;
+        }
+        catch {
+            headOk = false;
+        }
+        if (!headOk) {
+            emitInteractive(STATUS_POSTED, {
+                document_id: ask.documentId,
+                state: 'error',
+                message: `Crew could not read the document's current version (missing ${doc.headHtmlPath}) — the ask was not answered.`,
+            });
+            log(`[interactive-chat] ask ${key}: head html ${doc.headHtmlPath} is missing/empty`);
+            return;
+        }
+        // Both files live under the ONE declared write root — the run's OWN per-ask subdirectory,
+        // never the shared chatDir (per-run isolation — Copilot, crew#313: the wholesale
+        // declaration let any chat worker read every other doc's head snapshot and revision): the
+        // worker reads the snapshot and writes the deliverable without ever touching the doc
+        // workspace (crew#263 shape; write roots are readable, wicked-core#259). Names derive from
+        // the validated slug + our own key grammar — never from free bus text.
+        const safeKey = key.replace(/[^a-zA-Z0-9_-]/g, '-');
+        const runDir = join(chatDir, safeKey);
+        mkdirSync(runDir, { recursive: true });
+        const currentPath = join(runDir, 'current.html');
+        const outPath = join(runDir, 'revised.html');
+        copyFileSync(doc.headHtmlPath, currentPath);
+        const runId = randomUUID();
+        // The studio's 90s silence budget: this pickup line is what keeps the thread honest, so
+        // it fires BEFORE the launch resolves.
+        emitInteractive(STATUS_POSTED, {
+            document_id: ask.documentId,
+            state: 'processing',
+            message: 'A governed crew picked up your ask — revising the document…',
+        });
+        try {
+            await adapter.launchRun({
+                problem: chatProblem(ask, currentPath, outPath),
+                sessionId: runId,
+                clisJson: opts.clisJson ?? JSON.stringify(rosterOf(adapter)),
+                workflow: INTERACTIVE_CHAT_WORKFLOW,
+                // A project-bound doc's governed revision is FILED (same contract as the sibling
+                // seams); an unbound doc launches with the key OMITTED — an unfiled governed run,
+                // never a fabricated 'default' membership.
+                ...(ask.projectId !== undefined ? { projectId: ask.projectId } : {}),
+                // 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).
+                //
+                // AND — the CREW-UX-8 split — deliberately NO repo snapshot either, unlike the draft
+                // leg. The draft seam's snapshot grounding is proven live; the SAME grounded prompt on
+                // the REVISE turn wedged 2/2 on the real engine (crew#288 comment: the repo-grounded
+                // revise turn hits the known second-turn wedge), while ungrounded revisions are proven
+                // to land (the CREW-UX-5 verification). So bound asks launch exactly like unfiled ones:
+                // head-copy in the external inbox, the ONE write root below, projectId still filed.
+                // Revision grounding returns when wicked-core#293 or #294 is fixed.
+                extraWriteRoots: [runDir],
+                // THE DELIVERABLE FLOOR (crew#311): the revised document IS the deliverable. Without
+                // it the engine's substance floor passes a worker whose Write was denied as long as it
+                // narrated ~200 characters first; with it the run FAILS naming this path.
+                requireDeliverables: [outPath],
+            });
+        }
+        catch (err) {
+            // 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);
+            emitInteractive(STATUS_POSTED, {
+                document_id: ask.documentId,
+                state: 'error',
+                message: `Crew could not start a run for your ask: ${reason}. Resend the message to retry.`,
+            });
+            // DELIBERATELY no ledger write: only an answered ask earns a row, so a replay of the
+            // frame (live path: dead-letter + operator redrive) gets a real retry.
+            throw err;
+        }
+        // Record AFTER the launch resolved: a failed launch leaves no ledger row, so a replayed
+        // delivery retries. The crash window between launch and this write is the reason the
+        // announce ALSO carries a deterministic idempotency key.
+        ledger.recordLaunch(key, runId);
+        if (ask.projectId !== undefined)
+            opts.onRunFiled?.(runId, ask.projectId);
+        const flight = {
+            key,
+            documentId: ask.documentId,
+            outPath,
+            headAtLaunch: doc.head,
+            narration: 'Crew run launched — working on your revision…',
+            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-chat] ask ${key} → governed run ${runId} (v${doc.head} → ${outPath})`);
+    }
+    /** `true` when the doc's landing gate (if any) still holds its queue shut. A satisfied or
+     *  expired gate is removed. `projectId` (when the caller has an ask in hand) beats the
+     *  queue-head lookup — an empty queue must still resolve the right per-project root. */
+    function gateHolds(documentId, projectId) {
+        const gate = landingGates.get(documentId);
+        if (gate === undefined)
+            return false;
+        if (Date.now() > gate.until) {
+            landingGates.delete(documentId);
+            log(`[interactive-chat] landing gate for ${documentId} timed out — draining on the current head`);
+            return false;
+        }
+        // Resolve the root through the ask at hand, else the FIRST queued ask (all asks on one
+        // doc resolve the same way).
+        const next = queues.get(documentId)?.[0];
+        const docsRoot = resolveDocsRoot(projectId ?? next?.ask.projectId);
+        const doc = readDocHead(docsRoot, documentId);
+        if (doc !== null && doc.head >= gate.minHead) {
+            landingGates.delete(documentId);
+            return false;
+        }
+        return true;
+    }
+    /** Drain one doc's queue head if nothing holds it (busy run, landing gate). Fire-and-forget:
+     *  a drain-time launch failure is narrated + logged, never thrown (there is no live bus
+     *  frame left to dead-letter). */
+    function drainDoc(documentId) {
+        const queue = queues.get(documentId);
+        if (queue === undefined || queue.length === 0) {
+            queues.delete(documentId);
+            return;
+        }
+        if (docBusy(documentId) || gateHolds(documentId))
+            return;
+        const next = queue.shift();
+        if (queue.length === 0)
+            queues.delete(documentId);
+        void launchAsk(next).catch((err) => {
+            log(`[interactive-chat] drained ask ${next.key} failed to launch: ${err instanceof Error ? err.message : String(err)}`);
+            // The failed drain must not strand the rest of the queue.
+            drainDoc(documentId);
+        });
+    }
+    // The sweep: foreign runs (draft/edit seams) and landing gates clear OUTSIDE our event flow,
+    // so a timer retries parked queues. Unref'd — parked asks never keep the daemon alive.
+    // Expired landing gates are reaped here too (Copilot, #310): gateHolds() only removes a
+    // gate when a queued ask drains, so a doc revised once and never asked again would hold
+    // its entry forever — the map must stay bounded by each gate's own timeout.
+    const sweep = setInterval(() => {
+        const now = Date.now();
+        for (const [documentId, gate] of landingGates) {
+            if (now > gate.until && (queues.get(documentId)?.length ?? 0) === 0) {
+                landingGates.delete(documentId);
+            }
+        }
+        for (const documentId of [...queues.keys()])
+            drainDoc(documentId);
+    }, opts.queueSweepMs ?? 1000);
+    sweep.unref?.();
+    async function handleChatPosted(event) {
+        const ask = parseChatPosted(event.event_type, event.payload);
+        if (ask === null)
+            return;
+        // Contract (d): the feedback overlay's batch echo is transcript fidelity, not an ask —
+        // its document work already rides feedback.submitted (deterministic apply / edit seam).
+        if (!isIterationAsk(ask.text)) {
+            log(`[interactive-chat] chat.posted on ${ask.documentId} is a feedback-batch echo — not this seam's`);
+            return;
+        }
+        const key = chatKey(ask.documentId, event.event_id, ask.sourceMessageId);
+        // Replay-dedup: the ledger is the durable gate (redelivery after crash/restart, and a
+        // studio resend that reused its message id), the in-flight/queue scan the live one.
+        if (ledger.has(key)) {
+            log(`[interactive-chat] ask ${key} already answered (run ${ledger.get(key)?.runId}) — replay ignored`);
+            return;
+        }
+        for (const f of inFlight.values()) {
+            if (f.key === key)
+                return;
+        }
+        for (const q of queues.values()) {
+            if (q.some((entry) => entry.key === key))
+                return;
+        }
+        // Contract (b): the doc must exist under the resolved root with an answerable kind. Checked at
+        // DELIVERY so a demo doc's chat or an unknown doc never even parks; re-checked at launch
+        // (the snapshot read) because a parked ask can outlive its doc.
+        const docsRoot = resolveDocsRoot(ask.projectId);
+        const doc = readDocHead(docsRoot, ask.documentId);
+        if (doc === null) {
+            log(`[interactive-chat] chat.posted for unknown doc ${ask.documentId} under ${docsRoot} — ignored`);
+            return;
+        }
+        if (!isAnswerableDocKind(doc.kind)) {
+            log(`[interactive-chat] doc ${ask.documentId} has kind '${doc.kind}' — demo (and other foreign-kind) docs are not this seam's to answer`);
+            return;
+        }
+        const queued = { key, ask, eventId: event.event_id };
+        // Contract (c): per-doc serialization, FIFO. A busy doc parks the ask — with an IMMEDIATE
+        // narration so the thread never sits silent inside the studio's 90s budget.
+        if (docBusy(ask.documentId) || gateHolds(ask.documentId, ask.projectId) || queues.has(ask.documentId)) {
+            const queue = queues.get(ask.documentId) ?? [];
+            queue.push(queued);
+            queues.set(ask.documentId, queue);
+            emitInteractive(STATUS_POSTED, {
+                document_id: ask.documentId,
+                state: 'processing',
+                message: 'Crew has your ask — a run is already working this document, so it is queued and will start as soon as the current work lands.',
+            });
+            log(`[interactive-chat] ask ${key} queued behind busy doc ${ask.documentId} (${queue.length} waiting)`);
+            return;
+        }
+        // Re-throwing a launch failure lets the bus (maxRetries 0) dead-letter the frame —
+        // visible, replayable, incapable of hot-looping.
+        await launchAsk(queued);
+    }
+    const sub = bus.subscribe({
+        db,
+        plugin: INTERACTIVE_CHAT_BUS_PLUGIN,
+        filter: INTERACTIVE_CHAT_BUS_FILTER,
+        // Live triggers only: replaying a bus backlog would answer asks whose moment has passed.
+        cursor_init: 'latest',
+        pollIntervalMs: opts.pollIntervalMs ?? 2000,
+        // Our own ledger + idempotency key are the dedupe; a bus-level retry of a failed launch
+        // would double-launch precisely because the ledger row is only written on success.
+        maxRetries: 0,
+        handler: (event) => handleChatPosted(event),
+        onError: (err, event) => {
+            log(`[interactive-chat] handler error on event ${String(event?.event_id ?? '?')}: ${err.message}`);
+        },
+    });
+    return {
+        ledger,
+        inFlightDocs: () => [...new Set([...inFlight.values()].map((f) => f.documentId))],
+        queuedCount: (documentId) => queues.get(documentId)?.length ?? 0,
+        stop: async () => {
+            offCoreEvents();
+            clearInterval(sweep);
+            for (const runId of [...inFlight.keys()])
+                endFlight(runId);
+            queues.clear();
+            await sub.stop();
+        },
+    };
+}
+//# sourceMappingURL=chat-events.js.map