wicked-crew 0.5.0 → 0.7.0

package/dist/interactive/repo-snapshot.js

@@ -0,0 +1,289 @@
+/**
+ * Launch-scoped REPO SNAPSHOTS for grounding governed interactive runs (CREW-UX-8 v4).
+ *
+ * WHY a snapshot instead of the live repo: the interactive seams launch their governed runs
+ * UNBOUND — on a repoRef-bound run the worker's ACP tool-permission stream closes on the first
+ * call that needs a permission prompt and the session dies (wicked-core#293) — and an unbound
+ * worker's governance boundary is {sandbox, extraWriteRoots, ~/.claude/plugins}, so even READS
+ * of the live repo root are governance-denied (wicked-core#294; the v3 "hand the worker the
+ * root path to read" design rested on read evidence gathered under a *bound* boundary, which
+ * does not transfer). The one location an unbound worker can always read is the inbox the run
+ * already writes to — write roots are readable (wicked-core#259) — so grounding means putting
+ * a copy of the repo INSIDE the inbox, crew-side, BEFORE the launch, and naming that snapshot
+ * in the task.
+ *
+ * Mechanism, in preference order:
+ *  1. `git clone --depth 1 --no-hardlinks file://<root> <dest>` — a shallow LOCAL clone:
+ *     one commit of history, `--no-hardlinks` so the snapshot never aliases the live object
+ *     store. Because a clone checks out EVERY tracked path, the result is then swept: tracked
+ *     `node_modules` trees and every symlink are removed (see below), and the swept snapshot
+ *     is re-measured against the budget before it counts as usable.
+ *  2. A plain file copy that skips `.git`/`node_modules` AND symlinks — for roots that are not
+ *     git repos (or where git itself is unavailable/failing).
+ *
+ * SYMLINKS NEVER SURVIVE into a snapshot, on either path (Copilot, crew#313): the snapshot
+ * lands inside the worker-visible inbox, so a repo symlink pointing OUTSIDE the repo would
+ * hand the worker readable reach beyond the governance boundary — and a link to a huge tree
+ * would bypass the size cap the preflight walk (which skips links) enforced. The copy filter
+ * refuses them and the post-clone sweep deletes the ones a clone checked out.
+ *
+ * The snapshot is CAPPED: a working tree whose (`.git`/`node_modules`/symlink-excluded) size
+ * exceeds the budget is not snapshotted at all — the caller degrades honestly to an ungrounded
+ * launch with a visible status note, never a truncated half-repo the worker would mistake for
+ * the whole. Snapshots are launch-scoped: the seams remove them when the run reaches a
+ * terminal state (finalize/failure folds), so the inbox never accretes dead clones.
+ *
+ * OVERLAP REFUSAL: a configured draft dir could place `dest` inside the live repo (or a repo
+ * could be registered AT the inbox). Clearing a stale dest with `rm -rf` before noticing that
+ * would DELETE live repository content — so source/dest containment is checked (realpath'd,
+ * both directions) BEFORE anything is removed, and any overlap refuses the snapshot outright.
+ * For the same reason THIS helper creates `dest`'s parent directory (after the check passes) —
+ * a caller that pre-created it would already have written into the live repo (Copilot round 2).
+ *
+ * Fully ASYNC on purpose: this runs inline in a bus handler whose process also feeds ~15s UI
+ * heartbeats — a synchronous clone/copy of a big repo would starve the event loop and the
+ * canvas would read frozen (Copilot, crew#313). All I/O is fs/promises; the clone goes through
+ * the daemon's capped exec chokepoint (`execCapped`, FINDING-016).
+ */
+import { cp, lstat, mkdir, readdir, realpath, rm, stat } from 'node:fs/promises';
+import path, { basename, dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execCapped } from '../core/exec.js';
+/** Default snapshot budget (~200MB). A repo whose working tree exceeds this is not
+ *  snapshotted — the launch proceeds ungrounded, honestly narrated. */
+export const REPO_SNAPSHOT_MAX_BYTES = 200 * 1024 * 1024;
+/** Never snapshotted: git's object store (the clone brings its own shallow one; the copy
+ *  fallback wants working files only) and dependency trees (huge, reproducible, ungrounding). */
+const SNAPSHOT_SKIP = new Set(['.git', 'node_modules']);
+/** `true` when the tree under `root` exceeds `cap` bytes, skipping {@link SNAPSHOT_SKIP} dirs
+ *  and symlinks (a link to a huge tree — or out of the repo — must not distort the estimate;
+ *  the copy filter and post-clone sweep exclude exactly the same set, so the preflight counts
+ *  what a snapshot would actually hold), with an early exit the moment the cap is passed so a
+ *  10GB monorepo is never fully walked just to learn it is too big. */
+async function treeExceeds(root, cap) {
+    let total = 0;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable subdir — the clone/copy will surface a real error if it matters
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (!SNAPSHOT_SKIP.has(entry.name))
+                    stack.push(join(dir, entry.name));
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += (await stat(join(dir, entry.name))).size;
+                }
+                catch {
+                    // raced deletion — ignore
+                }
+                if (total > cap)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** Post-clone sweep: delete every symlink (junctions included — boundary escape, cap bypass)
+ *  and every {@link SNAPSHOT_SKIP} tree a `git clone` checked out (a clone materializes ALL
+ *  tracked paths — tracked `node_modules` ignores the skip list otherwise). The clone's own
+ *  top-level `.git` (its shallow object store) is the one deliberate survivor. */
+async function sweepSnapshot(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const p = join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                await rm(p, { recursive: true, force: true });
+            }
+            else if (entry.isDirectory()) {
+                if (dir === root && entry.name === '.git')
+                    continue; // the shallow clone's own store
+                if (SNAPSHOT_SKIP.has(entry.name)) {
+                    await rm(p, { recursive: true, force: true });
+                }
+                else {
+                    stack.push(p);
+                }
+            }
+        }
+    }
+}
+/** Resolve `p` through its nearest EXISTING ancestor's realpath (the path itself may not exist
+ *  yet — a fresh dest usually does not), so symlinked parents cannot hide an overlap. Only
+ *  ENOENT falls to the ancestor walk (the `api/open-path.ts` rule, Copilot round 2): any OTHER
+ *  error (EACCES, ELOOP, …) means an EXISTING component could not be resolved — a lexical
+ *  reconstruction there could miss an overlap through the unresolved link, so it THROWS and
+ *  the caller's overlap-check catch fails closed (no snapshot, degrade). */
+async function realpathNearest(p) {
+    let existing = resolve(p);
+    const tail = [];
+    // Walk up until something exists; dirname() at the root returns itself, which always exists.
+    for (;;) {
+        try {
+            const real = await realpath(existing);
+            return tail.length > 0 ? join(real, ...tail) : real;
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+            const parent = dirname(existing);
+            if (parent === existing)
+                return existing; // unreachable in practice — a root always resolves
+            tail.unshift(basename(existing));
+            existing = parent;
+        }
+    }
+}
+/** Is `child` equal to `parent` or inside it? `relative()`-based (the `api/open-path.ts`
+ *  containment pattern) — a plain `startsWith(base + sep)` never matches a ROOT base (`/`,
+ *  `C:\`), whose spelling already ends in the separator (Copilot round 2). */
+function contains(parent, child, p) {
+    const rel = p.relative(parent, child);
+    if (rel === '')
+        return true; // the same path
+    if (p.isAbsolute(rel))
+        return false; // different drive/tree entirely (win32)
+    return rel !== '..' && !rel.startsWith(`..${p.sep}`);
+}
+/** `true` when `a` and `b` name the same path or one contains the other — including when one
+ *  of them is a filesystem root (`/`, a win32 drive root). Exported for its unit tests. */
+export function pathsOverlap(a, b, p = path) {
+    return contains(a, b, p) || contains(b, a, p);
+}
+/**
+ * Materialize a snapshot of the repo at `rootPath` into `dest` (creating it), for a worker to
+ * READ as grounding context. Resolves `{ok: true}` when `dest` now holds a usable snapshot,
+ * `{ok: false, reason}` when it does not — see {@link SnapshotFailureReason}; the reason lets
+ * the caller narrate the RIGHT degrade (too large ≠ unreadable ≠ clone failed) — in which case
+ * any partial `dest` has been removed and the caller must launch UNGROUNDED (and say so on the
+ * thread). Never rejects: a grounding failure must degrade the launch, not kill it.
+ *
+ * The clone is the git-preferred path, so on a real repo the snapshot is HEAD's tracked
+ * content (uncommitted/untracked files are not included) minus swept symlinks/`node_modules`;
+ * the copy fallback takes the working tree as-is minus `.git`/`node_modules`/symlinks.
+ */
+export async function snapshotRepo(rootPath, dest, opts = {}) {
+    const log = opts.log ?? (() => { });
+    const maxBytes = opts.maxBytes ?? REPO_SNAPSHOT_MAX_BYTES;
+    try {
+        if (!(await stat(rootPath)).isDirectory()) {
+            log(`[repo-snapshot] repo root ${rootPath} is not a directory — no snapshot`);
+            return { ok: false, reason: 'root-unreadable' };
+        }
+    }
+    catch {
+        log(`[repo-snapshot] repo root ${rootPath} does not exist — no snapshot`);
+        return { ok: false, reason: 'root-unreadable' };
+    }
+    // Overlap refusal comes BEFORE the stale-dest clear (Copilot, crew#313): with a configurable
+    // draft dir, `dest` can sit inside the registered repo (or vice versa) — clearing it first
+    // would `rm -rf` live repository content, and a copy could recurse into its own output.
+    try {
+        const realRoot = await realpath(rootPath);
+        const realDest = await realpathNearest(dest);
+        if (pathsOverlap(realRoot, realDest)) {
+            log(`[repo-snapshot] refusing snapshot: destination ${dest} (${realDest}) overlaps the repo root ${rootPath} (${realRoot})`);
+            return { ok: false, reason: 'dest-overlap' };
+        }
+    }
+    catch (err) {
+        log(`[repo-snapshot] could not resolve ${rootPath} / ${dest} for the overlap check: ${err instanceof Error ? err.message : String(err)} — no snapshot`);
+        return { ok: false, reason: 'root-unreadable' };
+    }
+    if (await treeExceeds(rootPath, maxBytes)) {
+        log(`[repo-snapshot] repo at ${rootPath} exceeds the ${maxBytes}-byte snapshot budget — no snapshot`);
+        return { ok: false, reason: 'too-large' };
+    }
+    // The snapshot's PARENT (the caller's per-run dir) is created HERE — only after containment
+    // was validated. The caller must never pre-create it: with an overlapping config that mkdir
+    // would write into the live repository before the refusal above could fire (Copilot round 2).
+    try {
+        await mkdir(dirname(dest), { recursive: true });
+    }
+    catch (err) {
+        log(`[repo-snapshot] could not create the snapshot parent for ${dest}: ${err instanceof Error ? err.message : String(err)} — no snapshot`);
+        return { ok: false, reason: 'copy-failed' };
+    }
+    // A stale snapshot (crashed prior run, replayed key) never survives into a new launch.
+    try {
+        await rm(dest, { recursive: true, force: true });
+    }
+    catch (err) {
+        log(`[repo-snapshot] could not clear ${dest}: ${err instanceof Error ? err.message : String(err)}`);
+        return { ok: false, reason: 'dest-unclearable' };
+    }
+    // Preferred: shallow local clone. `file://` (not a plain path) is what makes --depth honored
+    // on a local source; pathToFileURL keeps the URL spelling right on Windows too.
+    try {
+        await execCapped('git', ['clone', '--depth', '1', '--no-hardlinks', pathToFileURL(rootPath).href, dest], {
+            timeout: 120_000,
+            windowsHide: true,
+        });
+        // The clone checked out EVERY tracked path — sweep what the snapshot contract excludes
+        // (tracked node_modules, all symlinks), then verify the SWEPT tree against the budget:
+        // the preflight measured the source with these exclusions, so a clean sweep normally
+        // passes, but the honest gate is what actually landed on disk.
+        await sweepSnapshot(dest);
+        if (await treeExceeds(dest, maxBytes)) {
+            log(`[repo-snapshot] clone of ${rootPath} exceeds the ${maxBytes}-byte budget after sweep — no snapshot`);
+            await rm(dest, { recursive: true, force: true }).catch(() => { });
+            return { ok: false, reason: 'too-large' };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        log(`[repo-snapshot] git clone of ${rootPath} failed (${err instanceof Error ? err.message : String(err)}) — falling back to a file copy`);
+    }
+    try {
+        await rm(dest, { recursive: true, force: true }); // whatever the failed clone left behind
+        await cp(rootPath, dest, {
+            recursive: true,
+            filter: async (src) => {
+                if (SNAPSHOT_SKIP.has(basename(src)))
+                    return false;
+                try {
+                    // Symlinks NEVER ride into the worker-visible inbox: a link out of the repo is a
+                    // boundary escape, a link to a huge tree a cap bypass (Copilot, crew#313).
+                    return !(await lstat(src)).isSymbolicLink();
+                }
+                catch {
+                    return false; // raced deletion / unreadable — leave it out
+                }
+            },
+        });
+        // The honest gate is what actually LANDED (same rule as the clone path's post-sweep
+        // re-measure): the preflight walked the SOURCE, and a file that grew between that walk and
+        // the copy would otherwise put an over-budget tree in the worker-visible inbox
+        // (Copilot round 2).
+        if (await treeExceeds(dest, maxBytes)) {
+            log(`[repo-snapshot] copy of ${rootPath} exceeds the ${maxBytes}-byte budget — no snapshot`);
+            await rm(dest, { recursive: true, force: true }).catch(() => { });
+            return { ok: false, reason: 'too-large' };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        log(`[repo-snapshot] file copy of ${rootPath} failed too (${err instanceof Error ? err.message : String(err)}) — no snapshot`);
+        await rm(dest, { recursive: true, force: true }).catch(() => { }); // never leave a partial snapshot
+        return { ok: false, reason: 'copy-failed' };
+    }
+}
+//# sourceMappingURL=repo-snapshot.js.map

package/dist/interactive/repo-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-snapshot.js","sourceRoot":"","sources":["../../src/interactive/repo-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjF,OAAO,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;uEACuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD;iGACiG;AACjG,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAoBxD;;;;uEAIuE;AACvE,KAAK,UAAU,WAAW,CAAC,IAAY,EAAE,GAAW;IAClD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACzB,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,6EAA6E;QACzF,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,cAAc,EAAE;gBAAE,SAAS;YACrC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACxE,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBACpD,CAAC;gBAAC,MAAM,CAAC;oBACP,0BAA0B;gBAC5B,CAAC;gBACD,IAAI,KAAK,GAAG,GAAG;oBAAE,OAAO,IAAI,CAAC;YAC/B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;kFAGkF;AAClF,KAAK,UAAU,aAAa,CAAC,IAAY;IACvC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACzB,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC3B,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAChD,CAAC;iBAAM,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBAC/B,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;oBAAE,SAAS,CAAC,gCAAgC;gBACrF,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBAClC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAChD,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;4EAK4E;AAC5E,KAAK,UAAU,eAAe,CAAC,CAAS;IACtC,IAAI,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,6FAA6F;IAC7F,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YACjC,IAAI,MAAM,KAAK,QAAQ;gBAAE,OAAO,QAAQ,CAAC,CAAC,mDAAmD;YAC7F,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;YACjC,QAAQ,GAAG,MAAM,CAAC;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAMD;;8EAE8E;AAC9E,SAAS,QAAQ,CAAC,MAAc,EAAE,KAAa,EAAE,CAAW;IAC1D,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,CAAC,gBAAgB;IAC7C,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,wCAAwC;IAC7E,OAAO,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;2FAC2F;AAC3F,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,CAAS,EAAE,IAAc,IAAI;IACnE,OAAO,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAChD,CAAC;AAUD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAAY,EACZ,OAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,uBAAuB,CAAC;IAE1D,IAAI,CAAC;QACH,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAC1C,GAAG,CAAC,6BAA6B,QAAQ,mCAAmC,CAAC,CAAC;YAC9E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,CAAC,6BAA6B,QAAQ,+BAA+B,CAAC,CAAC;QAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IAED,6FAA6F;IAC7F,2FAA2F;IAC3F,wFAAwF;IACxF,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YACrC,GAAG,CACD,kDAAkD,IAAI,KAAK,QAAQ,4BAA4B,QAAQ,KAAK,QAAQ,GAAG,CACxH,CAAC;YACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CACD,qCAAqC,QAAQ,MAAM,IAAI,2BACrD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,gBAAgB,CACjB,CAAC;QACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,MAAM,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,2BAA2B,QAAQ,gBAAgB,QAAQ,qCAAqC,CAAC,CAAC;QACtG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IAED,4FAA4F;IAC5F,4FAA4F;IAC5F,8FAA8F;IAC9F,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CACD,4DAA4D,IAAI,KAC9D,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,gBAAgB,CACjB,CAAC;QACF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC9C,CAAC;IAED,uFAAuF;IACvF,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,mCAAmC,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACnD,CAAC;IAED,6FAA6F;IAC7F,gFAAgF;IAChF,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,gBAAgB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;YACvG,OAAO,EAAE,OAAO;YAChB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,uFAAuF;QACvF,uFAAuF;QACvF,qFAAqF;QACrF,+DAA+D;QAC/D,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,MAAM,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YACtC,GAAG,CAAC,4BAA4B,QAAQ,gBAAgB,QAAQ,wCAAwC,CAAC,CAAC;YAC1G,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CACD,gCAAgC,QAAQ,YACtC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,iCAAiC,CAClC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,wCAAwC;QAC1F,MAAM,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE;YACvB,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBACpB,IAAI,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACnD,IAAI,CAAC;oBACH,iFAAiF;oBACjF,2EAA2E;oBAC3E,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;gBAC9C,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,KAAK,CAAC,CAAC,6CAA6C;gBAC7D,CAAC;YACH,CAAC;SACF,CAAC,CAAC;QACH,oFAAoF;QACpF,2FAA2F;QAC3F,+EAA+E;QAC/E,qBAAqB;QACrB,IAAI,MAAM,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YACtC,GAAG,CAAC,2BAA2B,QAAQ,gBAAgB,QAAQ,4BAA4B,CAAC,CAAC;YAC7F,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACjE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CACD,gCAAgC,QAAQ,gBACtC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,iBAAiB,CAClB,CAAC;QACF,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,iCAAiC;QACnG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/interactive/ws-relay.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DES-MERGE-001 §5.4 / §6.1 (slice 3) — the `wicked.interactive.*` ↔ `/ws` relay.
+ *
+ * wicked-studio is absorbing wicked-interactive. The SPA already holds crew's `/ws` socket for
+ * CoreEvent frames; interactive's own progress travels on the wicked-bus. This module bridges the
+ * two so the skin needs exactly ONE socket — no second websocket, no new port.
+ *
+ * Two halves, one bus handle:
+ *
+ * 1. RELAY (bus → /ws). Subscribe to `wicked.interactive.**` and rebroadcast each event as
+ *    `{ type: 'interactiveEvent', event: <the full bus event> }` — ONE envelope type, the original
+ *    event nested whole, no field renaming, no project filter. Ordering is as received (the bus
+ *    hands a batch to the handler in order and `broadcast` is synchronous), and there is no
+ *    buffering beyond what the existing broadcast path already does.
+ *
+ * 2. EMIT (/ws client → bus). `POST /projects/:projectId/interactive-events` validates the body
+ *    against a SERVER-SIDE whitelist ({@link EMITTABLE_TYPES}) and puts the event on the bus with
+ *    interactive's own envelope conventions (domain `wicked-interactive`, producer `wi-crew`,
+ *    `ts`-stamped payload — draft-events.ts is the precedent), so interactive's own subscribers
+ *    see a UI-originated event exactly as they see a service-originated one.
+ *
+ * Deliberately DISTINCT from the `projectActivity` bridge in projects/events.ts, which reads the
+ * same filter: that one is project-FILTERED and reshapes the event into an activity frame for a
+ * project view. This one is unfiltered and verbatim, because the studio's document canvas must see
+ * the events of a doc that was never filed under a project. Separate plugin identity → separate
+ * durable cursor, so neither seam can strand the other.
+ *
+ * Posture mirrors every other bus seam here: LOUD-non-fatal. No wicked-bus, or a broken db → the
+ * factory logs once and returns null, the daemon boots without the relay, and the POST route
+ * answers 503 instead of pretending the emit landed.
+ */
+import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
+/** The ONE envelope type this relay puts on `/ws`. Consumers that don't know it ignore it — the
+ *  CoreEvent contract is additive-safe (DES-STUDIO-001 §2.1). */
+export declare const INTERACTIVE_EVENT_FRAME = "interactiveEvent";
+/**
+ * Server-side whitelist of the event types a `/ws` client may emit through
+ * `POST /projects/:projectId/interactive-events`. A non-whitelisted type is a 400 that NAMES this
+ * array — the UI never has to guess. Extend here; nothing else needs to change.
+ */
+export declare const EMITTABLE_TYPES: readonly string[];
+/** The request body: a whitelisted type plus that type's own payload. Strict — an unknown key is
+ *  a 400, not a silently-dropped field. */
+export declare const EmitInteractiveEventSchema: z.ZodObject<{
+    type: z.ZodString;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    payload?: Record<string, unknown> | undefined;
+}, {
+    type: string;
+    payload?: Record<string, unknown> | undefined;
+}>;
+export interface InteractiveRelay {
+    /**
+     * Emit one interactive event onto the bus. Returns true on success (or on WB-002, a duplicate
+     * key — the emit already happened); logs and returns false otherwise. Never throws.
+     */
+    emitInteractive(type: string, payload: Record<string, unknown>, idempotencyKey: string): boolean;
+    stop(): Promise<void>;
+}
+export interface InteractiveRelayOptions {
+    /** Bus db path; omit for wicked-bus's own resolution (honors WICKED_BUS_DATA_DIR). */
+    dbPath?: string;
+    /** Poll cadence for the relay subscriber, ms (tests shorten it). */
+    pollIntervalMs?: number;
+    log?: (msg: string) => void;
+}
+/**
+ * Open the bus and arm both halves. Returns `null` (logged) when wicked-bus is not importable or
+ * the db cannot open — the caller degrades to a daemon whose `/ws` simply carries no interactive
+ * frames, exactly as before this slice.
+ */
+export declare function startInteractiveWsRelay(opts?: InteractiveRelayOptions): Promise<InteractiveRelay | null>;
+/** Occurrence-unique, type-inclusive (DES-EXEC-001 rev0.2 #4a): two types sharing a key would
+ *  silently drop one on the bus's UNIQUE constraint, and every UI emission is a new fact. */
+export declare function interactiveEmitKey(projectId: string, type: string): string;
+/**
+ * `POST /api/v1/projects/:projectId/interactive-events` — the UI-emittable direction (§6.1).
+ * Registered even when the relay is null, so the failure is an honest 503 rather than a 404 that
+ * reads like "this daemon doesn't have the feature".
+ */
+export declare function registerInteractiveEventRoutes(app: FastifyInstance, relay: InteractiveRelay | null): void;
+//# sourceMappingURL=ws-relay.d.ts.map

package/dist/interactive/ws-relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-relay.d.ts","sourceRoot":"","sources":["../../src/interactive/ws-relay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;iEACiE;AACjE,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAG5C,CAAC;AAEF;2CAC2C;AAC3C,eAAO,MAAM,0BAA0B;;;;;;;;;EAK5B,CAAC;AAEZ,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;IACjG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgGlC;AAED;6FAC6F;AAC7F,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAC7B,IAAI,CAmCN"}

package/dist/interactive/ws-relay.js

@@ -0,0 +1,191 @@
+/**
+ * DES-MERGE-001 §5.4 / §6.1 (slice 3) — the `wicked.interactive.*` ↔ `/ws` relay.
+ *
+ * wicked-studio is absorbing wicked-interactive. The SPA already holds crew's `/ws` socket for
+ * CoreEvent frames; interactive's own progress travels on the wicked-bus. This module bridges the
+ * two so the skin needs exactly ONE socket — no second websocket, no new port.
+ *
+ * Two halves, one bus handle:
+ *
+ * 1. RELAY (bus → /ws). Subscribe to `wicked.interactive.**` and rebroadcast each event as
+ *    `{ type: 'interactiveEvent', event: <the full bus event> }` — ONE envelope type, the original
+ *    event nested whole, no field renaming, no project filter. Ordering is as received (the bus
+ *    hands a batch to the handler in order and `broadcast` is synchronous), and there is no
+ *    buffering beyond what the existing broadcast path already does.
+ *
+ * 2. EMIT (/ws client → bus). `POST /projects/:projectId/interactive-events` validates the body
+ *    against a SERVER-SIDE whitelist ({@link EMITTABLE_TYPES}) and puts the event on the bus with
+ *    interactive's own envelope conventions (domain `wicked-interactive`, producer `wi-crew`,
+ *    `ts`-stamped payload — draft-events.ts is the precedent), so interactive's own subscribers
+ *    see a UI-originated event exactly as they see a service-originated one.
+ *
+ * Deliberately DISTINCT from the `projectActivity` bridge in projects/events.ts, which reads the
+ * same filter: that one is project-FILTERED and reshapes the event into an activity frame for a
+ * project view. This one is unfiltered and verbatim, because the studio's document canvas must see
+ * the events of a doc that was never filed under a project. Separate plugin identity → separate
+ * durable cursor, so neither seam can strand the other.
+ *
+ * Posture mirrors every other bus seam here: LOUD-non-fatal. No wicked-bus, or a broken db → the
+ * factory logs once and returns null, the daemon boots without the relay, and the POST route
+ * answers 503 instead of pretending the emit landed.
+ */
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { broadcast } from '../events/bus.js';
+import { API_PREFIX } from '../api/api-prefix.js';
+import { LOCAL_ACTOR } from '../api/auth.js';
+import { INTERACTIVE_DOMAIN, INTERACTIVE_PRODUCER } from './draft-events.js';
+const V = API_PREFIX;
+/** Dedicated durable-cursor identity — NOT the projects bridge's, so the two seams that read
+ *  `wicked.interactive.**` advance independent cursors. */
+const RELAY_PLUGIN = 'wicked-crew-interactive-relay';
+const RELAY_FILTER = 'wicked.interactive.**';
+/** The scope guard, restated locally: the property "only interactive events are relayed" is this
+ *  module's, not the bus glob's. */
+const RELAY_TYPE_PREFIX = 'wicked.interactive.';
+/** The ONE envelope type this relay puts on `/ws`. Consumers that don't know it ignore it — the
+ *  CoreEvent contract is additive-safe (DES-STUDIO-001 §2.1). */
+export const INTERACTIVE_EVENT_FRAME = 'interactiveEvent';
+/**
+ * Server-side whitelist of the event types a `/ws` client may emit through
+ * `POST /projects/:projectId/interactive-events`. A non-whitelisted type is a 400 that NAMES this
+ * array — the UI never has to guess. Extend here; nothing else needs to change.
+ */
+export const EMITTABLE_TYPES = [
+    'wicked.interactive.feedback.submitted',
+    'wicked.interactive.status.requested',
+];
+/** The request body: a whitelisted type plus that type's own payload. Strict — an unknown key is
+ *  a 400, not a silently-dropped field. */
+export const EmitInteractiveEventSchema = z
+    .object({
+    type: z.string().min(1).max(128),
+    payload: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+/**
+ * Open the bus and arm both halves. Returns `null` (logged) when wicked-bus is not importable or
+ * the db cannot open — the caller degrades to a daemon whose `/ws` simply carries no interactive
+ * frames, exactly as before this slice.
+ */
+export async function startInteractiveWsRelay(opts = {}) {
+    const log = opts.log ?? (() => undefined);
+    let bus;
+    try {
+        bus = await import('wicked-bus');
+    }
+    catch (err) {
+        log(`[interactive-relay] wicked-bus is not importable — the interactive /ws relay is disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let db;
+    let config;
+    try {
+        const override = opts.dbPath !== undefined ? { db_path: opts.dbPath } : {};
+        config = bus.loadConfig(override);
+        db = bus.openDb(override);
+    }
+    catch (err) {
+        log(`[interactive-relay] could not open the bus db${opts.dbPath !== undefined ? ` at ${opts.dbPath}` : ''} — the interactive /ws relay is disabled: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    // Half 1 — bus → /ws. maxRetries: 0 for the same reason the projects bridge uses it: a retry
+    // loop or a DLQ entry for a lost liveness frame is noise, and the durable feed is the record.
+    //
+    // This subscription also sees the events emitted by half 2 (they match the same filter). That
+    // is not a loop — the relay only broadcasts, never re-emits — and the echo is the UI's
+    // confirmation that its own emission actually landed on the bus.
+    let subscription = null;
+    try {
+        subscription = bus.subscribe({
+            db,
+            plugin: RELAY_PLUGIN,
+            filter: RELAY_FILTER,
+            cursor_init: 'latest',
+            pollIntervalMs: opts.pollIntervalMs ?? 2000,
+            maxRetries: 0,
+            handler: (event) => {
+                if (!event.event_type.startsWith(RELAY_TYPE_PREFIX))
+                    return;
+                broadcast({ type: INTERACTIVE_EVENT_FRAME, event });
+            },
+            onError: (err, event) => {
+                log(`[interactive-relay] relay error on event ${String(event?.event_id ?? '?')}: ${err.message}`);
+            },
+        });
+    }
+    catch (err) {
+        log(`[interactive-relay] could not arm the /ws relay subscriber (the emit direction still works): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Half 2 — the emit surface the POST route calls after the whitelist check. The subdomain is
+    // the third segment of interactive's own type grammar (`wicked.interactive.<subdomain>.<verb>`).
+    function emitInteractive(type, payload, idempotencyKey) {
+        try {
+            bus.emit(db, config, {
+                event_type: type,
+                domain: INTERACTIVE_DOMAIN,
+                subdomain: type.split('.')[2] ?? 'status',
+                payload: { ts: new Date().toISOString(), ...payload },
+                producer_id: INTERACTIVE_PRODUCER,
+                idempotency_key: idempotencyKey,
+            });
+            return true;
+        }
+        catch (err) {
+            const code = err.error;
+            if (code === 'WB-002')
+                return true; // duplicate key — the emit already happened
+            log(`[interactive-relay] emit ${type} failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    return {
+        emitInteractive,
+        stop: async () => {
+            if (subscription !== null)
+                await subscription.stop();
+        },
+    };
+}
+/** Occurrence-unique, type-inclusive (DES-EXEC-001 rev0.2 #4a): two types sharing a key would
+ *  silently drop one on the bus's UNIQUE constraint, and every UI emission is a new fact. */
+export function interactiveEmitKey(projectId, type) {
+    return `crew:interactive.ui:${projectId}:${type}:${randomUUID()}`;
+}
+/**
+ * `POST /api/v1/projects/:projectId/interactive-events` — the UI-emittable direction (§6.1).
+ * Registered even when the relay is null, so the failure is an honest 503 rather than a 404 that
+ * reads like "this daemon doesn't have the feature".
+ */
+export function registerInteractiveEventRoutes(app, relay) {
+    const actorOf = (req) => req.actor ?? LOCAL_ACTOR;
+    app.post(`${V}/projects/:projectId/interactive-events`, async (req, reply) => {
+        const { projectId } = req.params;
+        const parsed = EmitInteractiveEventSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return reply.code(400).send({ error: 'Invalid request body', details: parsed.error.issues });
+        }
+        const { type } = parsed.data;
+        if (!EMITTABLE_TYPES.includes(type)) {
+            return reply.code(400).send({
+                error: `Event type '${type}' is not emittable from a client`,
+                allowed: EMITTABLE_TYPES,
+            });
+        }
+        if (relay === null) {
+            return reply
+                .code(503)
+                .send({ error: 'the interactive bus seam is not armed on this daemon' });
+        }
+        // Server-side fields go LAST: `project_id` and `actor` are the daemon's to state, never the
+        // caller's (task #88 — event actors are not caller-supplied), so a payload that names either
+        // one cannot override them.
+        const idempotencyKey = interactiveEmitKey(projectId, type);
+        const emitted = relay.emitInteractive(type, { ...(parsed.data.payload ?? {}), project_id: projectId, actor: actorOf(req).id }, idempotencyKey);
+        if (!emitted) {
+            return reply.code(502).send({ error: `the bus refused the ${type} emit` });
+        }
+        return reply.code(202).send({ emitted: true, type, projectId, idempotencyKey });
+    });
+}
+//# sourceMappingURL=ws-relay.js.map

package/dist/interactive/ws-relay.js.map

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

package/dist/projects/activity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The project activity feed (DES-PROJECT-001 §5.2) — a READ-SIDE MERGE, not a new store.
+ *
+ * Two sources, one normalized shape:
+ * - CREW: the durable core-event log of the project's `crew.run`/`crew.chat` members
+ *   (`adapter.runEvents` — the same log `/runs/:id/events` serves), entry id `crew:<run>:<seq>`.
+ * - INTERACTIVE: `wicked.interactive.*` bus events carrying this `project_id`, read directly
+ *   from the bus SQLite READ-ONLY (`node:sqlite`, the `requirements.ts` precedent — wicked-bus
+ *   exposes subscribe-cursors, not ad-hoc history queries, and a durable cursor per feed-read
+ *   would turn a GET into a write), entry id `bus:<event_id>`.
+ *
+ * Newest-first, cursor on `(ts, id)` — an opaque `<ts>:<id>` token, base64url. The merge is
+ * recomputed per read; members are few and the log excludes high-volume frames, so the simple
+ * full-merge is the honest v1 (the ADR explicitly rejects a new store here).
+ */
+import type { CoreAdapter } from '../core/adapter.js';
+import type { ActivityEntry } from '../core/types.js';
+/** Opaque cursor: base64url of `<ts>:<id>`. */
+export declare function encodeCursor(ts: number, id: string): string;
+export declare function decodeCursor(cursor: string): {
+    ts: number;
+    id: string;
+} | null;
+/** Build one page of the merged feed. `refs` = the project's run/chat member refs. */
+export declare function buildActivityPage(adapter: CoreAdapter, projectId: string, refs: string[], busDbPath: string | null, cursor: string | undefined, limit: number): Promise<{
+    entries: ActivityEntry[];
+    nextCursor: string | null;
+}>;
+//# sourceMappingURL=activity.d.ts.map

package/dist/projects/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/projects/activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAuDtD,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW9E;AAsFD,sFAAsF;AACtF,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAgBlE"}