wicked-crew 0.5.0 → 0.7.0

package/dist/interactive/ledger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Durable handoff ledger shared by crew's wicked-interactive seams (task #86, Phase 7c).
+ *
+ * Extracted from the draft leg (draft-events.ts, PR #241) when the structural-edit leg arrived,
+ * because both seams need the same replay-dedup discipline with DIFFERENT key grammars:
+ *
+ *  - the DRAFT leg keys by document id — one first draft per document lifetime;
+ *  - the EDIT leg keys by `<doc>:v<version>` — one governed edit per HANDOFF, because the same
+ *    document legitimately produces many structural handoffs over its life (versioned targeting).
+ *
+ * The ledger itself is key-agnostic: a durable map `key → HandoffLedgerEntry`, JSON on disk,
+ * written atomically (tmp + rename). The bus cursor alone cannot carry this: at-least-once
+ * delivery means the same trigger can arrive again after a crash between handling and cursor
+ * advance, and in-memory state dies with the process. The ledger is the system of record for
+ * "this handoff was answered"; each seam's in-flight map is just the live half.
+ */
+/** One ledger row — the lifecycle of a handoff a seam answered. */
+export interface HandoffLedgerEntry {
+    runId: string;
+    launchedAt: string;
+    /** Set once the closing event (draft.completed / edit.completed) was emitted. */
+    emittedAt?: string;
+    /** Set when the governed run ended without a usable result; kept so a redelivered trigger
+     *  does not silently relaunch a run an operator should look at first. */
+    failedAt?: string;
+}
+export declare class InteractiveHandoffLedger {
+    private readonly path;
+    private entries;
+    constructor(path: string);
+    has(key: string): boolean;
+    get(key: string): HandoffLedgerEntry | undefined;
+    recordLaunch(key: string, runId: string): void;
+    recordEmitted(key: string): void;
+    recordFailure(key: string): void;
+    size(): number;
+    private persist;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/dist/interactive/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/interactive/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;6EACyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAOD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAqC;gBAExC,IAAI,EAAE,MAAM;IAuCxB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIhD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK9C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQhC,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,OAAO;CAMhB"}

package/dist/interactive/ledger.js

@@ -0,0 +1,93 @@
+/**
+ * Durable handoff ledger shared by crew's wicked-interactive seams (task #86, Phase 7c).
+ *
+ * Extracted from the draft leg (draft-events.ts, PR #241) when the structural-edit leg arrived,
+ * because both seams need the same replay-dedup discipline with DIFFERENT key grammars:
+ *
+ *  - the DRAFT leg keys by document id — one first draft per document lifetime;
+ *  - the EDIT leg keys by `<doc>:v<version>` — one governed edit per HANDOFF, because the same
+ *    document legitimately produces many structural handoffs over its life (versioned targeting).
+ *
+ * The ledger itself is key-agnostic: a durable map `key → HandoffLedgerEntry`, JSON on disk,
+ * written atomically (tmp + rename). The bus cursor alone cannot carry this: at-least-once
+ * delivery means the same trigger can arrive again after a crash between handling and cursor
+ * advance, and in-memory state dies with the process. The ledger is the system of record for
+ * "this handoff was answered"; each seam's in-flight map is just the live half.
+ */
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class InteractiveHandoffLedger {
+    path;
+    entries;
+    constructor(path) {
+        this.path = path;
+        this.entries = {};
+        try {
+            // The persisted top-level field stays `docs` for wire-compat with ledgers the draft leg
+            // already wrote to operator machines (~/.wicked-crew/interactive-draft-ledger.json).
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed && typeof parsed === 'object' && parsed.docs && typeof parsed.docs === 'object') {
+                for (const [key, entry] of Object.entries(parsed.docs)) {
+                    // Per-row validation: one malformed row (null, primitive, missing/empty fields) costs
+                    // that row alone — letting it throw into the outer catch would blank the WHOLE ledger
+                    // and defeat replay-dedup for every handoff already answered. A kept row must satisfy
+                    // the full HandoffLedgerEntry contract (non-empty runId + launchedAt strings).
+                    if (typeof entry !== 'object' ||
+                        entry === null ||
+                        typeof entry.runId !== 'string' ||
+                        entry.runId.length === 0 ||
+                        typeof entry.launchedAt !== 'string') {
+                        continue;
+                    }
+                    const { draftEmittedAt, ...rest } = entry;
+                    this.entries[key] = {
+                        ...rest,
+                        // Migrate the draft leg's original field name in place.
+                        ...(rest.emittedAt === undefined && draftEmittedAt !== undefined
+                            ? { emittedAt: draftEmittedAt }
+                            : {}),
+                    };
+                }
+            }
+        }
+        catch {
+            // Missing or malformed ledger — start empty. Malformed is deliberately NOT fatal: a
+            // corrupt ledger must not stop the daemon, and the worst case is one duplicate closing
+            // emit, which the deterministic bus idempotency key still dedupes.
+        }
+    }
+    has(key) {
+        return Object.prototype.hasOwnProperty.call(this.entries, key);
+    }
+    get(key) {
+        return this.entries[key];
+    }
+    recordLaunch(key, runId) {
+        this.entries[key] = { runId, launchedAt: new Date().toISOString() };
+        this.persist();
+    }
+    recordEmitted(key) {
+        const entry = this.entries[key];
+        if (entry) {
+            entry.emittedAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    recordFailure(key) {
+        const entry = this.entries[key];
+        if (entry) {
+            entry.failedAt = new Date().toISOString();
+            this.persist();
+        }
+    }
+    size() {
+        return Object.keys(this.entries).length;
+    }
+    persist() {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify({ docs: this.entries }, null, 2), 'utf8');
+        renameSync(tmp, this.path);
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/interactive/ledger.js.map

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

package/dist/interactive/proxy-routes.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `/api/v1/projects/:projectId/interactive/*` — crew reverse-proxies the wicked-interactive
+ * bridge (DES-MERGE-001 §5.3, §7.2; slice 1).
+ *
+ * PURE TRANSPORT. Nothing user-visible moves in this slice: what changes is that interactive's
+ * HTTP surface becomes reachable through crew's OWN origin, so the studio client never learns a
+ * second origin, never needs CORS, and never carries a bridge port literal — ADR-0022's dynamic
+ * port is honored rather than worked around, and the bridge stops being browser-reachable at all.
+ *
+ * The path encodes the project (§7.2) because the ROOT is a per-project setting: the same proxy
+ * mount serves N interactive instances, one bridge per resolved root.
+ *
+ * Two things are deliberately hand-rolled over `node:http` rather than delegated to `fetch`:
+ *
+ *  1. UNBUFFERED STREAMING BOTH WAYS. Interactive's generation surface is SSE; a proxy that
+ *     buffers turns a live narration into a single blob delivered at stream close. Piping raw
+ *     sockets keeps every chunk flowing as it arrives, in both directions.
+ *  2. VERBATIM FORWARDING. The path remainder and query string are taken from `req.raw.url`,
+ *     not from Fastify's decoded wildcard param, so percent-encoding survives the hop intact.
+ */
+import type { FastifyInstance } from 'fastify';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { ProjectSettingsStore } from '../projects/settings.js';
+import { InteractiveBridgePool, type LiveBridge } from './bridge-pool.js';
+/**
+ * Point a `Location` back at the proxy. The bridge answers on its own origin and knows nothing
+ * about the mount prefix, so both spellings it can emit have to be re-anchored: an absolute URL
+ * on the bridge origin, and a root-relative path. Anything else (a foreign origin, a relative
+ * path) is left exactly as-is — rewriting those would be inventing a redirect target.
+ */
+export declare function rewriteLocation(location: string, bridge: LiveBridge, prefix: string): string;
+export interface InteractiveProxyDeps {
+    settings: ProjectSettingsStore;
+    pool: InteractiveBridgePool;
+    env?: NodeJS.ProcessEnv;
+    log?: (msg: string) => void;
+}
+export declare function registerInteractiveProxy(app: FastifyInstance, adapter: CoreAdapter, deps: InteractiveProxyDeps): void;
+//# sourceMappingURL=proxy-routes.d.ts.map

package/dist/interactive/proxy-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-routes.d.ts","sourceRoot":"","sources":["../../src/interactive/proxy-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAA0B,qBAAqB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA4BlG;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAO5F;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAiErH"}

package/dist/interactive/proxy-routes.js

@@ -0,0 +1,189 @@
+/**
+ * `/api/v1/projects/:projectId/interactive/*` — crew reverse-proxies the wicked-interactive
+ * bridge (DES-MERGE-001 §5.3, §7.2; slice 1).
+ *
+ * PURE TRANSPORT. Nothing user-visible moves in this slice: what changes is that interactive's
+ * HTTP surface becomes reachable through crew's OWN origin, so the studio client never learns a
+ * second origin, never needs CORS, and never carries a bridge port literal — ADR-0022's dynamic
+ * port is honored rather than worked around, and the bridge stops being browser-reachable at all.
+ *
+ * The path encodes the project (§7.2) because the ROOT is a per-project setting: the same proxy
+ * mount serves N interactive instances, one bridge per resolved root.
+ *
+ * Two things are deliberately hand-rolled over `node:http` rather than delegated to `fetch`:
+ *
+ *  1. UNBUFFERED STREAMING BOTH WAYS. Interactive's generation surface is SSE; a proxy that
+ *     buffers turns a live narration into a single blob delivered at stream close. Piping raw
+ *     sockets keeps every chunk flowing as it arrives, in both directions.
+ *  2. VERBATIM FORWARDING. The path remainder and query string are taken from `req.raw.url`,
+ *     not from Fastify's decoded wildcard param, so percent-encoding survives the hop intact.
+ */
+import { request as httpRequest } from 'node:http';
+import { API_PREFIX } from '../api/api-prefix.js';
+import { ProjectsUnsupportedError } from '../core/adapter.js';
+import { DEFAULT_PROJECT_ID } from '../projects/routes.js';
+import { resolveInteractiveRoot } from './bridge-root.js';
+import { BridgeUnavailableError } from './bridge-pool.js';
+/** Per-hop headers that must never be forwarded across a proxy (RFC 9110 §7.6.1). */
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+function forwardableRequestHeaders(headers, bridge) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (HOP_BY_HOP.has(name) || value === undefined)
+            continue;
+        // Crew's bearer token is CREW's credential. The bridge is a local process with no auth of
+        // its own and no use for it; forwarding it would hand a third-party child crew's ambient
+        // authority for free. One auth path (§5.3) means crew terminates auth, it does not relay it.
+        if (name === 'authorization')
+            continue;
+        out[name] = value;
+    }
+    out['host'] = `${bridge.host}:${bridge.port}`;
+    return out;
+}
+/**
+ * Point a `Location` back at the proxy. The bridge answers on its own origin and knows nothing
+ * about the mount prefix, so both spellings it can emit have to be re-anchored: an absolute URL
+ * on the bridge origin, and a root-relative path. Anything else (a foreign origin, a relative
+ * path) is left exactly as-is — rewriting those would be inventing a redirect target.
+ */
+export function rewriteLocation(location, bridge, prefix) {
+    for (const host of new Set([bridge.host, 'localhost', '127.0.0.1'])) {
+        const origin = `http://${host}:${bridge.port}`;
+        if (location.startsWith(origin))
+            return `${prefix}${location.slice(origin.length)}`;
+    }
+    if (location.startsWith('/'))
+        return `${prefix}${location}`;
+    return location;
+}
+export function registerInteractiveProxy(app, adapter, deps) {
+    const { settings, pool } = deps;
+    const env = deps.env ?? process.env;
+    // Strips exactly the mount prefix off the RAW url, leaving the remainder + query untouched.
+    const prefixRe = new RegExp(`^${API_PREFIX}/projects/[^/?#]+/interactive`);
+    /** The resolved docs root for a project, or null when no such project exists. */
+    async function rootFor(projectId) {
+        // `default` is SYNTHESIZED by the route layer (DES-PROJECT-001 §7) — the engine has no row
+        // for it, so an existence check there would 404 the one project every operator starts with.
+        if (projectId !== DEFAULT_PROJECT_ID) {
+            try {
+                if ((await adapter.projectGet(projectId)) === null)
+                    return null;
+            }
+            catch (err) {
+                // A pre-0.6.0 engine has no project surface at all; the shared default root is still
+                // a truthful answer for the only project such a deployment can have.
+                if (!(err instanceof ProjectsUnsupportedError))
+                    throw err;
+            }
+        }
+        return resolveInteractiveRoot(settings.get(projectId), env);
+    }
+    // Encapsulated so the raw-body parser below applies to the PROXY ONLY. The root instance
+    // installs a JSON parser that buffers and parses the body — correct for every other route,
+    // fatal here: a parsed body is a consumed stream, and an SSE POST would arrive at the bridge
+    // only once the client finished sending.
+    void app.register(async (scope) => {
+        scope.removeAllContentTypeParsers();
+        scope.addContentTypeParser('*', (_req, payload, done) => {
+            done(null, payload);
+        });
+        scope.all(`${API_PREFIX}/projects/:projectId/interactive/*`, async (req, reply) => {
+            const { projectId } = req.params;
+            const prefix = `${API_PREFIX}/projects/${encodeURIComponent(projectId)}/interactive`;
+            const root = await rootFor(projectId);
+            if (root === null)
+                return reply.code(404).send({ error: `Project ${projectId} not found` });
+            let bridge;
+            try {
+                bridge = await pool.ensure(root);
+            }
+            catch (err) {
+                return unavailable(reply, err, deps.log);
+            }
+            const target = (req.raw.url ?? '').replace(prefixRe, '') || '/';
+            try {
+                await forward(req, reply, bridge, target, prefix);
+            }
+            catch (err) {
+                // The cached bridge died between the pid check and the connect (an operator killed it,
+                // a crash). Invalidate and let `ensure` restart it — ONE retry, so a genuinely broken
+                // bridge fails fast to a 503 instead of looping.
+                if (!isConnectionRefused(err) || reply.raw.headersSent)
+                    throw err;
+                pool.invalidate(root);
+                try {
+                    bridge = await pool.ensure(root);
+                }
+                catch (startErr) {
+                    return unavailable(reply, startErr, deps.log);
+                }
+                await forward(req, reply, bridge, target, prefix);
+            }
+            return reply;
+        });
+    });
+}
+function isConnectionRefused(err) {
+    const code = err?.code;
+    return code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EHOSTUNREACH';
+}
+/** §5.6's failure shape: a machine-readable code plus a command the operator can actually run. */
+function unavailable(reply, err, log) {
+    if (!(err instanceof BridgeUnavailableError))
+        throw err;
+    log?.(`interactive bridge unavailable: ${err.message}`);
+    return reply.code(503).send({ code: 'bridge_unavailable', hint: err.hint });
+}
+/**
+ * One proxied exchange, socket to socket. `reply.hijack()` hands us the raw response before
+ * Fastify can serialize or buffer anything, which is what lets an SSE chunk reach the browser
+ * the moment the bridge emits it rather than at stream close.
+ */
+function forward(req, reply, bridge, target, prefix) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const upstream = httpRequest({
+            host: bridge.host,
+            port: bridge.port,
+            method: req.method,
+            path: target,
+            headers: forwardableRequestHeaders(req.headers, bridge),
+        }, (res) => {
+            reply.hijack();
+            const headers = {};
+            for (const [name, value] of Object.entries(res.headers)) {
+                if (HOP_BY_HOP.has(name) || value === undefined)
+                    continue;
+                headers[name] = name === 'location' && typeof value === 'string' ? rewriteLocation(value, bridge, prefix) : value;
+            }
+            reply.raw.writeHead(res.statusCode ?? 502, headers);
+            // No `pipeline` and no buffering layer: `pipe` forwards each chunk as it lands, and
+            // Node flushes it because we never set a highWaterMark barrier in between.
+            res.pipe(reply.raw);
+            res.on('end', () => resolvePromise());
+            res.on('error', (err) => {
+                reply.raw.destroy();
+                rejectPromise(err);
+            });
+        });
+        upstream.on('error', (err) => {
+            if (reply.raw.headersSent)
+                reply.raw.destroy();
+            rejectPromise(err);
+        });
+        // If the client hangs up mid-stream (closing an SSE tab), stop pulling from the bridge.
+        reply.raw.on('close', () => upstream.destroy());
+        req.raw.pipe(upstream);
+    });
+}
+//# sourceMappingURL=proxy-routes.js.map

package/dist/interactive/proxy-routes.js.map

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

package/dist/interactive/repo-snapshot.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 path from 'node:path';
+/** Default snapshot budget (~200MB). A repo whose working tree exceeds this is not
+ *  snapshotted — the launch proceeds ungrounded, honestly narrated. */
+export declare const REPO_SNAPSHOT_MAX_BYTES: number;
+/** Why a snapshot was refused — each maps to a DIFFERENT operator-facing degrade message in
+ *  the calling seam, so "too large" is never claimed about a repo that was merely unreadable
+ *  (Copilot, crew#313). */
+export type SnapshotFailureReason = 
+/** `rootPath` does not exist or is not a directory. */
+'root-unreadable'
+/** The tree (preflight) — or the swept clone (post-check) — exceeds the byte budget. */
+ | 'too-large'
+/** `rootPath` and `dest` overlap (either direction) — clearing/cloning would eat live data. */
+ | 'dest-overlap'
+/** The stale `dest` could not be cleared. */
+ | 'dest-unclearable'
+/** Both the git clone and the file-copy fallback failed. */
+ | 'copy-failed';
+/** The honest outcome of {@link snapshotRepo}: usable snapshot, or the reason there is none. */
+export type SnapshotResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: SnapshotFailureReason;
+};
+/** The subset of `node:path` {@link pathsOverlap} needs — injectable so the win32 drive-root
+ *  behavior is unit-testable on any host (`path.win32`). */
+type PathImpl = Pick<typeof path, 'relative' | 'isAbsolute' | '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 declare function pathsOverlap(a: string, b: string, p?: PathImpl): boolean;
+/** Options for {@link snapshotRepo}. */
+export interface SnapshotRepoOptions {
+    /** Size budget in bytes (default {@link REPO_SNAPSHOT_MAX_BYTES}; tests shrink it). */
+    maxBytes?: number | undefined;
+    /** Diagnostics sink — every degrade path logs its real reason here. */
+    log?: ((message: string) => void) | undefined;
+}
+/**
+ * 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 declare function snapshotRepo(rootPath: string, dest: string, opts?: SnapshotRepoOptions): Promise<SnapshotResult>;
+export {};
+//# sourceMappingURL=repo-snapshot.d.ts.map

package/dist/interactive/repo-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo-snapshot.d.ts","sourceRoot":"","sources":["../../src/interactive/repo-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAGH,OAAO,IAA0C,MAAM,WAAW,CAAC;AAInE;uEACuE;AACvE,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAMzD;;2BAE2B;AAC3B,MAAM,MAAM,qBAAqB;AAC/B,uDAAuD;AACrD,iBAAiB;AACnB,wFAAwF;GACtF,WAAW;AACb,+FAA+F;GAC7F,cAAc;AAChB,6CAA6C;GAC3C,kBAAkB;AACpB,4DAA4D;GAC1D,aAAa,CAAC;AAElB,gGAAgG;AAChG,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAyFzF;4DAC4D;AAC5D,KAAK,QAAQ,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,UAAU,GAAG,YAAY,GAAG,KAAK,CAAC,CAAC;AAYrE;2FAC2F;AAC3F,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,QAAe,GAAG,OAAO,CAE9E;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,uEAAuE;IACvE,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,cAAc,CAAC,CA0HzB"}