wicked-crew 0.4.0 → 0.6.0

package/dist/interactive/bridge-pool.js

@@ -0,0 +1,187 @@
+/**
+ * The wicked-interactive bridge pool — discovery, health, reuse-or-start (DES-MERGE-001 §5.3/§5.6).
+ *
+ * A bridge is a local `wicked-interactive serve` process that records itself in
+ * `<root>/.wi-serve.json` = `{ port, host, pid, startedAt, version }` (ADR-0022). Its port is
+ * DYNAMIC — the first free port above its base — which is precisely why crew, a server process
+ * that can read that lockfile, proxies it instead of the browser dialling a port literal.
+ *
+ * LOCAL-ONLY BY DESIGN. Every mechanism here (a pid, a file in a directory, spawning a child)
+ * is single-host. That is the slice-1 posture, not an oversight: when the execution seam goes
+ * remote, this module is the seam that gets a remote implementation, and the proxy above it
+ * does not change.
+ *
+ * Pooling is keyed by the RESOLVED root (see `bridge-root.ts`), so two projects that share the
+ * default root share one bridge and one port; projects bound to different roots get their own.
+ *
+ * Health follows ADR-0025's hardened reuse check, and the ORDER matters: a recorded pid that is
+ * alive but slow (cold first hit, busy materializing) must be REUSED, not duplicated — so a
+ * live pid earns three 1.5 s attempts before the bridge is declared dead. Identity is checked
+ * too: `/api/health` must report THIS root, or a recycled port belonging to some other service
+ * would be proxied as if it were ours.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const LOCK_NAME = '.wi-serve.json';
+/** ADR-0025: 1.5 s × 3 while the pid lives. */
+export const HEALTH_TIMEOUT_MS = 1500;
+export const HEALTH_ATTEMPTS = 3;
+/** A cold `npx wicked-interactive serve` may have to resolve and fetch the package first. */
+export const START_TIMEOUT_MS = 60_000;
+/** The 503 the proxy renders as `{"code":"bridge_unavailable","hint":...}` (§5.6). */
+export class BridgeUnavailableError extends Error {
+    /** An ACTIONABLE command an operator can actually run — never a bare "try again". */
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'BridgeUnavailableError';
+        this.hint = hint;
+    }
+}
+/** The one command that reproduces a failed start in a terminal, where its output is visible. */
+function serveCommand(root) {
+    return `npx wicked-interactive serve --root ${root}`;
+}
+/** `<root>/.wi-serve.json`, or null when absent/unparseable/incomplete. */
+export function readLock(root) {
+    try {
+        const raw = JSON.parse(readFileSync(join(root, LOCK_NAME), 'utf8'));
+        if (typeof raw.port !== 'number' || typeof raw.pid !== 'number')
+            return null;
+        return { host: typeof raw.host === 'string' && raw.host !== '' ? raw.host : '127.0.0.1', port: raw.port, pid: raw.pid };
+    }
+    catch {
+        return null;
+    }
+}
+/** Signal 0 probes existence without delivering: EPERM means alive-but-not-ours. */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** `GET /api/health` → the root that bridge is serving, or null (timeout, refusal, non-200). */
+async function bridgeIdentity(bridge, timeoutMs) {
+    try {
+        const res = await fetch(`http://${bridge.host}:${bridge.port}/api/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.root === 'string' ? body.root : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class InteractiveBridgePool {
+    io;
+    /** Last bridge known good per root — the fast path that keeps the proxy off `fetch` per request. */
+    live = new Map();
+    /** In-flight resolutions per root, so a burst of first requests starts ONE bridge, not N. */
+    inflight = new Map();
+    constructor(io = {}) {
+        this.io = io;
+    }
+    /** Reuse-or-start, idempotent per root. Throws `BridgeUnavailableError` when start is impossible. */
+    async ensure(root) {
+        // Fast path: we started/adopted it and its pid is still alive. A full health round-trip on
+        // every proxied request would put a 1.5 s timeout budget in front of every asset fetch.
+        const cached = this.live.get(root);
+        if (cached && pidAlive(cached.pid))
+            return cached;
+        this.live.delete(root);
+        const pending = this.inflight.get(root);
+        if (pending)
+            return pending;
+        const started = this.resolveOrStart(root).finally(() => this.inflight.delete(root));
+        this.inflight.set(root, started);
+        return started;
+    }
+    /** Drop the cached bridge for a root — called when a proxied connection is refused. */
+    invalidate(root) {
+        this.live.delete(root);
+    }
+    /** Live bridges, for tests and future operator introspection. */
+    keys() {
+        return [...this.live.keys()];
+    }
+    async resolveOrStart(root) {
+        const adopted = await this.healthy(root);
+        if (adopted) {
+            this.live.set(root, adopted);
+            return adopted;
+        }
+        const started = await this.start(root);
+        this.live.set(root, started);
+        return started;
+    }
+    /** The lockfile points at a bridge that is alive, answering, and serving THIS root. */
+    async healthy(root) {
+        const lock = readLock(root);
+        if (lock === null || !pidAlive(lock.pid))
+            return null;
+        const timeout = this.io.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+        for (let attempt = 0; attempt < HEALTH_ATTEMPTS; attempt++) {
+            const identity = await bridgeIdentity(lock, timeout);
+            if (identity !== null && resolve(identity) === root)
+                return lock;
+            // Only keep retrying while the pid still lives — a bridge that exited mid-probe is dead,
+            // not slow, and burning the remaining attempts on it just delays the restart.
+            if (!pidAlive(lock.pid))
+                return null;
+            if (attempt < HEALTH_ATTEMPTS - 1)
+                await sleep(300);
+        }
+        return null;
+    }
+    async start(root) {
+        try {
+            // `npx` runs with cwd=root; a missing directory fails the spawn with an opaque error.
+            mkdirSync(root, { recursive: true });
+        }
+        catch (err) {
+            throw new BridgeUnavailableError(`interactive root ${root} is not usable: ${err.message}`, `create the docs root and retry: mkdir -p ${root} && ${serveCommand(root)}`);
+        }
+        let spawnFailure = null;
+        const child = (this.io.spawn ?? defaultSpawn)(root);
+        // Detached + unref: the bridge is a SHARED instance keyed by root, so it must outlive the
+        // daemon that happened to start it (and be adoptable by the next one via the lockfile).
+        child.on('error', (err) => {
+            spawnFailure = err.message;
+        });
+        child.unref?.();
+        const deadline = Date.now() + (this.io.startTimeoutMs ?? START_TIMEOUT_MS);
+        while (Date.now() < deadline) {
+            if (spawnFailure !== null) {
+                throw new BridgeUnavailableError(`could not spawn the interactive bridge in ${root}: ${spawnFailure}`, `install Node 22+ so \`npx\` is on PATH, then run: ${serveCommand(root)}`);
+            }
+            const healthy = await this.healthy(root);
+            if (healthy)
+                return healthy;
+            await sleep(150);
+        }
+        this.io.log?.(`interactive bridge for ${root} did not come up within the start budget`);
+        throw new BridgeUnavailableError(`the interactive bridge for ${root} did not become healthy in time`, `run \`${serveCommand(root)}\` in a terminal to see the failure (or check ${join(root, '.wi-serve.log')})`);
+    }
+}
+/** `npx wicked-interactive serve` in `<root>`, detached, output to the bridge's own log. */
+function defaultSpawn(root) {
+    // `--yes` is load-bearing: without it npx PROMPTS when the package is not installed, and a
+    // daemon has no tty to answer with — the request would hang instead of failing to a 503.
+    return nodeSpawn('npx', ['--yes', 'wicked-interactive', 'serve', '--root', root], {
+        cwd: root,
+        detached: true,
+        stdio: 'ignore',
+    });
+}
+//# sourceMappingURL=bridge-pool.js.map

package/dist/interactive/bridge-pool.js.map

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

package/dist/interactive/bridge-root.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which wicked-interactive document root a crew project speaks to (DES-MERGE-001 §7.1/§7.2).
+ *
+ * §7.1 closed the identity question: a crew Project is THE entity, and an interactive
+ * "instance" (a docs directory) maps onto it through ONE nullable setting, `interactiveRoot`.
+ * Null means "the shared default root" — it is a default, never a constraint (§7.2): two
+ * projects that leave it null share one bridge, a project that sets it gets its own.
+ *
+ * The resolved string is also the BRIDGE POOL KEY, which is why every spelling of the same
+ * directory has to collapse to one value here rather than in the pool. `~/decks`, `decks`
+ * (relative), and `/Users/me/decks/` are the same instance; keying on the raw setting would
+ * start a second `wicked-interactive serve` on a second port for each spelling — exactly the
+ * "why is it on 5 ports" confusion ADR-0025 exists to prevent.
+ */
+/** The setting carrier — a `Project` record or a crew-side settings row both satisfy this. */
+export interface InteractiveRootSetting {
+    /** Absolute or `~`-relative docs root; null/absent ⇒ the shared default. */
+    interactiveRoot?: string | null | undefined;
+}
+/** Env override for the SHARED DEFAULT only (never for an explicit per-project setting).
+ *  Exists so a test harness or an e2e run can point "the default root" at a scratch dir. */
+export declare const ROOT_ENV = "WICKED_INTERACTIVE_ROOT";
+/**
+ * What `wicked-interactive serve` uses with no `--root`: the canonical shared root
+ * `~/wicked-interactive/docs` (ADR-0025 amended, `bin/wicked-interactive.js:181`). Kept
+ * byte-identical to interactive's own default on purpose — that is what lets an operator's
+ * already-running default bridge be ADOPTED by the pool instead of duplicated.
+ */
+export declare function defaultInteractiveRoot(home?: string): string;
+/**
+ * The resolved, canonical docs root for a project — and therefore its bridge pool key.
+ * Precedence: the project's own `interactiveRoot` › `WICKED_INTERACTIVE_ROOT` › the shared
+ * default. A blank/whitespace setting is treated as null, not as "the cwd".
+ */
+export declare function resolveInteractiveRoot(setting: InteractiveRootSetting | null | undefined, env?: Record<string, string | undefined>, home?: string): string;
+//# sourceMappingURL=bridge-root.d.ts.map

package/dist/interactive/bridge-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-root.d.ts","sourceRoot":"","sources":["../../src/interactive/bridge-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,8FAA8F;AAC9F,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C;AAED;4FAC4F;AAC5F,eAAO,MAAM,QAAQ,4BAA4B,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAkB,GAAG,MAAM,CAEvE;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EAClD,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,IAAI,GAAE,MAAkB,GACvB,MAAM,CAMR"}

package/dist/interactive/bridge-root.js

@@ -0,0 +1,48 @@
+/**
+ * Which wicked-interactive document root a crew project speaks to (DES-MERGE-001 §7.1/§7.2).
+ *
+ * §7.1 closed the identity question: a crew Project is THE entity, and an interactive
+ * "instance" (a docs directory) maps onto it through ONE nullable setting, `interactiveRoot`.
+ * Null means "the shared default root" — it is a default, never a constraint (§7.2): two
+ * projects that leave it null share one bridge, a project that sets it gets its own.
+ *
+ * The resolved string is also the BRIDGE POOL KEY, which is why every spelling of the same
+ * directory has to collapse to one value here rather than in the pool. `~/decks`, `decks`
+ * (relative), and `/Users/me/decks/` are the same instance; keying on the raw setting would
+ * start a second `wicked-interactive serve` on a second port for each spelling — exactly the
+ * "why is it on 5 ports" confusion ADR-0025 exists to prevent.
+ */
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/** Env override for the SHARED DEFAULT only (never for an explicit per-project setting).
+ *  Exists so a test harness or an e2e run can point "the default root" at a scratch dir. */
+export const ROOT_ENV = 'WICKED_INTERACTIVE_ROOT';
+/**
+ * What `wicked-interactive serve` uses with no `--root`: the canonical shared root
+ * `~/wicked-interactive/docs` (ADR-0025 amended, `bin/wicked-interactive.js:181`). Kept
+ * byte-identical to interactive's own default on purpose — that is what lets an operator's
+ * already-running default bridge be ADOPTED by the pool instead of duplicated.
+ */
+export function defaultInteractiveRoot(home = homedir()) {
+    return resolve(home, 'wicked-interactive', 'docs');
+}
+/** Expand a leading `~` and absolutize, so every spelling of one directory keys the same. */
+function canonicalize(value, home) {
+    const expanded = value === '~' ? home : value.startsWith('~/') || value.startsWith('~\\') ? resolve(home, value.slice(2)) : value;
+    return resolve(expanded);
+}
+/**
+ * The resolved, canonical docs root for a project — and therefore its bridge pool key.
+ * Precedence: the project's own `interactiveRoot` › `WICKED_INTERACTIVE_ROOT` › the shared
+ * default. A blank/whitespace setting is treated as null, not as "the cwd".
+ */
+export function resolveInteractiveRoot(setting, env = process.env, home = homedir()) {
+    const own = setting?.interactiveRoot;
+    if (typeof own === 'string' && own.trim() !== '')
+        return canonicalize(own.trim(), home);
+    const shared = env[ROOT_ENV];
+    if (typeof shared === 'string' && shared.trim() !== '')
+        return canonicalize(shared.trim(), home);
+    return defaultInteractiveRoot(home);
+}
+//# sourceMappingURL=bridge-root.js.map

package/dist/interactive/bridge-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-root.js","sourceRoot":"","sources":["../../src/interactive/bridge-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;4FAC4F;AAC5F,MAAM,CAAC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe,OAAO,EAAE;IAC7D,OAAO,OAAO,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,6FAA6F;AAC7F,SAAS,YAAY,CAAC,KAAa,EAAE,IAAY;IAC/C,MAAM,QAAQ,GACZ,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnH,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkD,EAClD,MAA0C,OAAO,CAAC,GAAG,EACrD,OAAe,OAAO,EAAE;IAExB,MAAM,GAAG,GAAG,OAAO,EAAE,eAAe,CAAC;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACxF,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACjG,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/interactive/draft-events.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Opt-in governed answering of wicked-interactive's first-draft generation (task #86 spike,
+ * Phase 7c first leg).
+ *
+ * wicked-interactive's service is model-free: when a doc is created with `kind: "source"` it
+ * seeds a placeholder v0 and emits `wicked.interactive.doc.created`, expecting *something with
+ * intelligence* to answer with `wicked.interactive.draft.completed` carrying the first draft
+ * (the service then instruments `data-wid` anchors, themes it, and lands `_v1.html`). Today
+ * that answerer is an ad-hoc `assist` agent session. This module makes a crew-governed run the
+ * answerer instead — same bus vocabulary, zero interactive-service changes beyond the additive
+ * producer row (`wi-crew`) in interactive's events.js ownership table.
+ *
+ * Shape mirrors `qe/gate-events.ts` (crew's existing bus seam, Phase 6a): OPT-IN, dynamic
+ * wicked-bus import, graceful degradation when the bus is absent, durable cursor with
+ * `cursor_init: 'latest'` under a dedicated plugin name.
+ *
+ * Behavioral invariants honored (recon-verified against interactive):
+ *  - Heartbeat: the canvas shows a working veil and the browser fires ~20s
+ *    `status.requested` heartbeats; a silent answerer reads as a frozen UI. We narrate
+ *    `wicked.interactive.status.posted` on every phase transition AND on a ≤15s timer.
+ *  - Idempotency: the durable cursor redelivers under at-least-once semantics, and a replayed
+ *    `doc.created` must not produce a duplicate `_v2.html`. A durable per-doc ledger
+ *    (JSON file, atomic rename) gates the launch, and the final `draft.completed` emit carries
+ *    a deterministic idempotency key (`crew:interactive.draft:<doc>:v1`) so even a double
+ *    emit dedupes at the bus (WB-002).
+ *  - INV-2 (`data-wid`): first drafts are whole documents with no pre-existing anchors — the
+ *    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.
+ */
+import { InteractiveHandoffLedger } from './ledger.js';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { WorkflowDef } from '../core/types.js';
+export declare const INTERACTIVE_DOMAIN = "wicked-interactive";
+export declare const DOC_CREATED = "wicked.interactive.doc.created";
+export declare const DRAFT_COMPLETED = "wicked.interactive.draft.completed";
+export declare const STATUS_POSTED = "wicked.interactive.status.posted";
+/** Exact-type filter with a domain guard — no wildcard, one event type is the whole trigger. */
+export declare const INTERACTIVE_BUS_FILTER = "wicked.interactive.doc.created@wicked-interactive";
+/** Dedicated durable-cursor identity — NOT the qe subscriber's `wicked-crew`, so the two
+ *  seams advance independent cursors and stopping one never strands the other. */
+export declare const INTERACTIVE_BUS_PLUGIN = "wicked-crew-interactive-draft";
+/** The producer identity stamped on every event crew's interactive seams emit (this module and
+ *  edit-events.ts). Must appear in interactive's events.js ownership table for DRAFT_COMPLETED,
+ *  EDIT_COMPLETED, and STATUS_POSTED — the additive vocabulary rows that are the only
+ *  interactive changes Phase 7c is allowed. */
+export declare const INTERACTIVE_PRODUCER = "wi-crew";
+/** Interactive's doc-name grammar (server.js DOC_NAME) — re-checked before any launch so a
+ *  malformed document_id can't name a ledger key or a draft file path. Shared with the
+ *  structural-edit seam (edit-events.ts), which guards the same identity. */
+export declare const DOC_NAME: RegExp;
+export declare const INTERACTIVE_DRAFT_WORKFLOW = "interactive-draft";
+/**
+ * The governed workflow that produces a first draft. Two agent phases — outline (recon) then
+ * draft (build, creator role) — so the run narrates a real phase transition and the drafting
+ * worker builds on a planned structure instead of one-shotting the whole document.
+ *
+ * The phase `instructions` adapt the draft-production contract from interactive's assist skill
+ * (Step 5): honor the brief/sources/style, ground content in what the brief supports, produce a
+ * complete self-contained HTML document, and NEVER mint `data-wid` attributes (the service
+ * instruments fresh anchors itself). They are SINGLE-LINE by contract: the engine folds
+ * instructions onto the unit description with a single-line separator, and the PTY seat runner
+ * refuses any prompt carrying an embedded newline (wicked-core FINDING-011).
+ *
+ * All gates are `auto` with `validator_pin: null` — no human gate, no deterministic floor —
+ * because the acceptance gate for a draft is the INTERACTIVE side (the service's INV-2
+ * instrument+theme pipeline and the user's own eyes on the canvas). Registered via
+ * `adapter.registerWorkflow()` at arm time (validate-before-persist, hot-registered into the
+ * engine), not added to BUILTIN_WORKFLOWS: this def is crew-only data owned by this seam, not a
+ * mirror of a wicked-core drop-in.
+ */
+export declare const INTERACTIVE_DRAFT_WORKFLOW_DEF: WorkflowDef;
+/** The doc-creation fields this seam acts on. */
+export interface SourceDocCreated {
+    documentId: string;
+    brief: string;
+    sourcePaths: string[];
+    style: string;
+    /** The crew project this doc is bound to (required — parseSourceDocCreated returns null when
+     *  absent; unbound docs are handled solo by the assist skill, not by this seam). */
+    projectId: string;
+}
+/**
+ * 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.
+ */
+export declare function parseSourceDocCreated(eventType: string, payload: unknown): SourceDocCreated | null;
+/** 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
+ *  not balloon the worker prompt. Shared with the structural-edit seam. */
+export declare function oneLine(text: string, cap: number): string;
+/**
+ * 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.
+ */
+export declare function draftProblem(doc: SourceDocCreated, outPath: string): string;
+/** Deterministic bus idempotency key for the one draft this seam may land per document. */
+export declare function draftIdempotencyKey(documentId: string): string;
+export { InteractiveHandoffLedger, type HandoffLedgerEntry } from './ledger.js';
+/** Options for {@link startInteractiveDraftSubscriber}. */
+export interface InteractiveDraftOptions {
+    /** Bus SQLite db path. Omit to let wicked-bus resolve its own default
+     *  (honors `WICKED_BUS_DATA_DIR`) — which is where interactive's service emits unless
+     *  redirected, so the default is usually right. */
+    dbPath?: string;
+    /** Poll cadence, ms (default 2000; tests shorten it). */
+    pollIntervalMs?: number;
+    /** Heartbeat narration cadence while a run is in flight, ms (default 15000 — inside the
+     *  UI's ~20s `status.requested` window so the canvas never reads frozen). */
+    heartbeatMs?: number;
+    /** Ledger file (default `~/.wicked-crew/interactive-draft-ledger.json`). */
+    ledgerPath?: string;
+    /** Where governed workers write finished drafts (default `~/.wicked-crew/interactive-drafts`). */
+    draftDir?: string;
+    /** Seat roster JSON for the governed run (default: the production council roster).
+     *  The functional-test harness passes a deterministic stub seat here. */
+    clisJson?: string;
+    /** Called after a launch that FILED the run into a project (doc.created carried
+     *  `project_id`). The server wires this to the same post-commit half the launch route
+     *  performs: tag the run in the live membership index + emit `wicked.crew.membership.attached`
+     *  (the engine already attached the crew.run membership atomically with the launch). */
+    onRunFiled?: (runId: string, projectId: string) => void;
+    /** Diagnostics sink (default: console.error). */
+    log?: (message: string) => void;
+}
+/** Handle for a running subscription. */
+export interface InteractiveDraftSubscription {
+    stop(): Promise<void> | void;
+    /** The durable ledger (diagnostics / tests). */
+    ledger: InteractiveHandoffLedger;
+}
+/**
+ * Arm the seam: register the `interactive-draft` workflow, open a durable
+ * `wicked.interactive.doc.created` subscription, and answer each `kind: "source"` creation
+ * with a governed run that ends in `wicked.interactive.draft.completed`.
+ *
+ * Graceful degradation mirrors `startQeGateSubscriber`: 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; interactive's assist loop remains the (always-available) fallback answerer.
+ */
+export declare function startInteractiveDraftSubscriber(adapter: CoreAdapter, opts?: InteractiveDraftOptions): Promise<InteractiveDraftSubscription | null>;
+//# sourceMappingURL=draft-events.d.ts.map

package/dist/interactive/draft-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-events.d.ts","sourceRoot":"","sources":["../../src/interactive/draft-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAOH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/D,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,WAAW,mCAAmC,CAAC;AAC5D,eAAO,MAAM,eAAe,uCAAuC,CAAC;AACpE,eAAO,MAAM,aAAa,qCAAqC,CAAC;AAEhE,gGAAgG;AAChG,eAAO,MAAM,sBAAsB,sDAAyC,CAAC;AAE7E;kFACkF;AAClF,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE;;;+CAG+C;AAC/C,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C;;6EAE6E;AAC7E,eAAO,MAAM,QAAQ,QAA8B,CAAC;AAIpD,eAAO,MAAM,0BAA0B,sBAAsB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAqC5C,CAAC;AAIF,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd;wFACoF;IACpF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAiBlG;AAED;;2EAE2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAW3E;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D;AAQD,OAAO,EAAE,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIhF,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC;;uDAEmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;iFAC6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;6EACyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;4FAGwF;IACxF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,iDAAiD;IACjD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,yCAAyC;AACzC,MAAM,WAAW,4BAA4B;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,gDAAgD;IAChD,MAAM,EAAE,wBAAwB,CAAC;CAClC;AAoBD;;;;;;;;GAQG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,WAAW,EACpB,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC,CAmW9C"}