wicked-crew 0.5.0 → 0.7.0

package/dist/api/guidance-index.js

@@ -0,0 +1,67 @@
+/**
+ * The run→operator-guidance index (DES-UX-002 §7.2, CREW-UX-7).
+ *
+ * NAMING NOTE: DES-UX-002 §7.2 labels this slice CREW-UX-4, but that id was already spent on an
+ * unrelated merged slice (crew#308) — this implementation is CREW-UX-7; the doc's §7.2 spec is
+ * what it implements.
+ *
+ * A durable pre-gate annotation: ONE operator guidance note per run, upserted via
+ * `PUT /runs/:id/guidance` and echoed as `AgentSession.guidance` on the run DTOs. The engine's
+ * run record carries no such field (wicked-core-ts 0.6.x), so — exactly like retry lineage
+ * (CREW-UX-3) and the actor trail (task #88) — the durable record is the audit trail: every
+ * write lands as a `guidance.set` entry whose `detail.text` is the full note (empty string =
+ * cleared), and this map is the read-side latency layer that lets the run DTOs echo it without
+ * a trail scan per request.
+ *
+ * Mirrors `RetryIndex`'s posture: hydrated once at server start (best-effort — a missing or
+ * unreadable trail leaves guidance blank, the pre-CREW-UX-7 behavior, not an error) and updated
+ * at the same post-commit point that writes the audit entry, so the map can only lag by a
+ * failed hydrate, never diverge silently.
+ */
+export class GuidanceIndex {
+    runToGuidance = new Map();
+    /**
+     * Load guidance from EVERY `guidance.set` entry in the trail — exhaustively, not capped
+     * (BRIEF-UX-002 C5, same defect as `RetryIndex.hydrate`: a durable note must not vanish
+     * because 1000+ newer writes landed on top of it). The trail answers newest first, so the
+     * FIRST entry seen per run is the current note — later (older) entries for the same run
+     * are superseded writes and are skipped, which is also what keeps a cleared note (newest
+     * entry has `text: ''`) from being resurrected by an older non-empty one. Still best-effort,
+     * like `RetryIndex.hydrate`; cost is one full-file scan at boot.
+     */
+    async hydrate(audit, log) {
+        try {
+            const superseded = new Set();
+            for (const entry of await audit.readAll({ action: 'guidance.set' })) {
+                if (typeof entry.runId !== 'string')
+                    continue;
+                if (superseded.has(entry.runId))
+                    continue;
+                // The NEWEST entry for a run decides — even when its text is malformed. Marking the
+                // run seen BEFORE the text check keeps a corrupt newest write from resurrecting an
+                // older superseded note (Copilot, #312): unknowable current note = no note.
+                superseded.add(entry.runId);
+                const text = entry.detail?.['text'];
+                if (typeof text !== 'string')
+                    continue;
+                if (text !== '')
+                    this.runToGuidance.set(entry.runId, text);
+            }
+        }
+        catch (err) {
+            log?.(`[runs] guidance-index hydrate failed (prior runs read as no-guidance until restart): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** Upsert the note; the empty string CLEARS it (the DTO field goes back to absent). */
+    set(runId, text) {
+        if (text === '')
+            this.runToGuidance.delete(runId);
+        else
+            this.runToGuidance.set(runId, text);
+    }
+    /** The note for this run, or `undefined` (the DTO spells that as an ABSENT field). */
+    guidanceFor(runId) {
+        return this.runToGuidance.get(runId);
+    }
+}
+//# sourceMappingURL=guidance-index.js.map

package/dist/api/guidance-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance-index.js","sourceRoot":"","sources":["../../src/api/guidance-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,OAAO,aAAa;IACP,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3D;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,CAAC,KAAe,EAAE,GAA2B;QACxD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;YACrC,KAAK,MAAM,KAAK,IAAI,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;gBACpE,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;oBAAE,SAAS;gBAC9C,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;oBAAE,SAAS;gBAC1C,oFAAoF;gBACpF,mFAAmF;gBACnF,4EAA4E;gBAC5E,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;gBAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;gBACpC,IAAI,OAAO,IAAI,KAAK,QAAQ;oBAAE,SAAS;gBACvC,IAAI,IAAI,KAAK,EAAE;oBAAE,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,EAAE,CACH,wFACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uFAAuF;IACvF,GAAG,CAAC,KAAa,EAAE,IAAY;QAC7B,IAAI,IAAI,KAAK,EAAE;YAAE,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;;YAC7C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,sFAAsF;IACtF,WAAW,CAAC,KAAa;QACvB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}

package/dist/api/open-path.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Is `target` inside `root` (or `root` itself), after normalization? Traversal-safe: the check is
+ * on the RESOLVED relative path's first segment, so `/root/../evil` never passes, and a sibling
+ * whose name merely starts with dots (`/a/..hidden`) is not wrongly excluded.
+ */
+export declare function isInsideRoot(root: string, target: string): boolean;
+/** The session fields the root set is derived from — structural on purpose, so this stays a leaf
+ *  module (routes.ts hands it the wire-shape `SessionView.session`; tests hand it a literal). */
+export interface RootSourceSession {
+    workdir?: string | null;
+    extra_write_roots?: string[] | null;
+}
+/**
+ * The ONE root set a caller-supplied path is contained against (DES-FEEDBACK-002 CREW-1):
+ * the run's workdir + its `extra_write_roots` (when a run is in play) + every registered repo
+ * root. Extracted from the `POST /open` handler so `/open`, `GET /runs/:id/files`, and
+ * `GET /runs/:id/diff` cannot drift — three copies of a containment root set is how one of
+ * them quietly widens.
+ */
+export declare function allowedRootsFor(session: RootSourceSession | undefined, repos: ReadonlyArray<{
+    root_path: string;
+}>): string[];
+/** The platform's opener invocation. Exported for tests; args are always a real argv array. */
+export declare function platformOpenCommand(target: string): {
+    cmd: string;
+    args: string[];
+};
+/**
+ * Spawn the platform opener, detached, and resolve on SPAWN success (the OS accepted the process —
+ * what the opener then does with the path is the desktop environment's business). Rejects when the
+ * opener binary itself cannot be spawned, which the route reports as 502.
+ */
+export declare function openWithSystemDefault(target: string): Promise<void>;
+//# sourceMappingURL=open-path.d.ts.map

package/dist/api/open-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-path.d.ts","sourceRoot":"","sources":["../../src/api/open-path.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA2BlE;AAED;iGACiG;AACjG,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,KAAK,EAAE,aAAa,CAAC;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1C,MAAM,EAAE,CAWV;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnE"}

package/dist/api/open-path.js

@@ -0,0 +1,101 @@
+// POST /open (crew#273): open a file/folder with the OS default application, daemon-side.
+//
+// The studio is a browser SPA and cannot spawn a process, so the open MUST happen here — which is
+// exactly why the path is validated against known roots first (the run's workdir / extra write
+// roots, registered repo roots) and the opener is spawned with the path as a single argv element,
+// never through a shell string. There is no injection surface: `open`/`xdg-open`/`cmd /c start`
+// receive the path verbatim as one argument.
+import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+/**
+ * Is `target` inside `root` (or `root` itself), after normalization? Traversal-safe: the check is
+ * on the RESOLVED relative path's first segment, so `/root/../evil` never passes, and a sibling
+ * whose name merely starts with dots (`/a/..hidden`) is not wrongly excluded.
+ */
+export function isInsideRoot(root, target) {
+    // Symlink-safe (Copilot, PR#279): containment is judged on REAL paths, or a
+    // `<root>/symlink-to-outside` opens a file the validation never looked at. A missing
+    // leaf resolves through its deepest EXISTING ancestor (never a bare lexical fallback:
+    // on macOS the tmpdir itself sits under the /var → /private/var symlink, and a lexical
+    // fallback on one side of the comparison would break containment for real children).
+    // Only ENOENT falls to the ancestor walk; any OTHER filesystem error (EACCES, ELOOP, …)
+    // fails CLOSED — an unresolvable-but-existing path must not be judged lexically (Copilot).
+    const real = (p) => {
+        const abs = resolve(p);
+        try {
+            return realpathSync(abs);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                return null;
+            const parent = dirname(abs);
+            if (parent === abs)
+                return abs;
+            const rp = real(parent);
+            return rp === null ? null : join(rp, basename(abs));
+        }
+    };
+    const realRoot = real(root);
+    const realTarget = real(target);
+    if (realRoot === null || realTarget === null)
+        return false;
+    const rel = relative(realRoot, realTarget);
+    if (rel === '')
+        return true; // the root itself
+    if (isAbsolute(rel))
+        return false; // different drive/tree entirely (win32)
+    return rel.split(sep)[0] !== '..';
+}
+/**
+ * The ONE root set a caller-supplied path is contained against (DES-FEEDBACK-002 CREW-1):
+ * the run's workdir + its `extra_write_roots` (when a run is in play) + every registered repo
+ * root. Extracted from the `POST /open` handler so `/open`, `GET /runs/:id/files`, and
+ * `GET /runs/:id/diff` cannot drift — three copies of a containment root set is how one of
+ * them quietly widens.
+ */
+export function allowedRootsFor(session, repos) {
+    const roots = [];
+    if (session !== undefined) {
+        const workdir = session.workdir;
+        if (typeof workdir === 'string' && workdir.length > 0)
+            roots.push(workdir);
+        for (const r of session.extra_write_roots ?? []) {
+            if (typeof r === 'string' && r.length > 0)
+                roots.push(r);
+        }
+    }
+    for (const repo of repos)
+        roots.push(repo.root_path);
+    return roots;
+}
+/** The platform's opener invocation. Exported for tests; args are always a real argv array. */
+export function platformOpenCommand(target) {
+    switch (process.platform) {
+        case 'darwin':
+            return { cmd: 'open', args: [target] };
+        case 'win32':
+            // `start` is a cmd builtin; the empty string is start's window-title slot so the path is
+            // never mistaken for a title. Still an argv array — no shell string is ever composed.
+            return { cmd: 'cmd', args: ['/c', 'start', '', target] };
+        default:
+            return { cmd: 'xdg-open', args: [target] };
+    }
+}
+/**
+ * Spawn the platform opener, detached, and resolve on SPAWN success (the OS accepted the process —
+ * what the opener then does with the path is the desktop environment's business). Rejects when the
+ * opener binary itself cannot be spawned, which the route reports as 502.
+ */
+export function openWithSystemDefault(target) {
+    const { cmd, args } = platformOpenCommand(target);
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        child.once('error', rejectPromise);
+        child.once('spawn', () => {
+            child.unref();
+            resolvePromise();
+        });
+    });
+}
+//# sourceMappingURL=open-path.js.map

package/dist/api/open-path.js.map

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

package/dist/api/retry-index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The run→retry-lineage index (DES-UX-001 §8.3, CREW-UX-3).
+ *
+ * The engine's `LaunchOptions` carries no lineage field (checked, wicked-core-ts 0.6.x), so —
+ * exactly like the actor trail (task #88) — WHICH run a launch retries is knowledge only the
+ * daemon's HTTP layer ever holds. The durable record is the `run.launched` audit entry whose
+ * `detail.retryOf` the launch route writes; this map is the read-side latency layer that lets
+ * `GET /runs` / `GET /runs/:id` echo `AgentSession.retry_of` without a trail scan per request.
+ *
+ * Mirrors `MembershipIndex`'s posture: hydrated once at server start (from the audit trail,
+ * best-effort — a missing/unreadable trail leaves lineage blank for PRIOR runs, which is the
+ * pre-CREW-UX-3 behavior, not an error) and updated at the same post-commit point that writes
+ * the audit entry, so the map can only lag by a failed hydrate, never diverge silently.
+ */
+import type { AuditLog } from './audit.js';
+export declare class RetryIndex {
+    private readonly runToRetryOf;
+    /**
+     * Load lineage from EVERY `run.launched` entry in the trail — exhaustively, not capped
+     * (BRIEF-UX-002 C5: a lineage fact 2,678 launches deep must survive a restart; the newest-1000
+     * cap silently dropped it and the chronicle rendered the chain as peer episodes). Still
+     * best-effort: a missing/unreadable trail leaves lineage blank, the pre-CREW-UX-3 answer.
+     * Cost: one full-file scan at boot — `read` already parses the whole file anyway.
+     */
+    hydrate(audit: AuditLog, log?: (msg: string) => void): Promise<void>;
+    set(runId: string, retryOf: string): void;
+    /** The run id this run retries, or `undefined` (the DTO spells that as an ABSENT field). */
+    retryOfFor(runId: string): string | undefined;
+}
+//# sourceMappingURL=retry-index.d.ts.map

package/dist/api/retry-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-index.d.ts","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB1E,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIzC,4FAA4F;IAC5F,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAG9C"}

package/dist/api/retry-index.js

@@ -0,0 +1,45 @@
+/**
+ * The run→retry-lineage index (DES-UX-001 §8.3, CREW-UX-3).
+ *
+ * The engine's `LaunchOptions` carries no lineage field (checked, wicked-core-ts 0.6.x), so —
+ * exactly like the actor trail (task #88) — WHICH run a launch retries is knowledge only the
+ * daemon's HTTP layer ever holds. The durable record is the `run.launched` audit entry whose
+ * `detail.retryOf` the launch route writes; this map is the read-side latency layer that lets
+ * `GET /runs` / `GET /runs/:id` echo `AgentSession.retry_of` without a trail scan per request.
+ *
+ * Mirrors `MembershipIndex`'s posture: hydrated once at server start (from the audit trail,
+ * best-effort — a missing/unreadable trail leaves lineage blank for PRIOR runs, which is the
+ * pre-CREW-UX-3 behavior, not an error) and updated at the same post-commit point that writes
+ * the audit entry, so the map can only lag by a failed hydrate, never diverge silently.
+ */
+export class RetryIndex {
+    runToRetryOf = new Map();
+    /**
+     * Load lineage from EVERY `run.launched` entry in the trail — exhaustively, not capped
+     * (BRIEF-UX-002 C5: a lineage fact 2,678 launches deep must survive a restart; the newest-1000
+     * cap silently dropped it and the chronicle rendered the chain as peer episodes). Still
+     * best-effort: a missing/unreadable trail leaves lineage blank, the pre-CREW-UX-3 answer.
+     * Cost: one full-file scan at boot — `read` already parses the whole file anyway.
+     */
+    async hydrate(audit, log) {
+        try {
+            for (const entry of await audit.readAll({ action: 'run.launched' })) {
+                const retryOf = entry.detail?.['retryOf'];
+                if (typeof entry.runId === 'string' && typeof retryOf === 'string') {
+                    this.runToRetryOf.set(entry.runId, retryOf);
+                }
+            }
+        }
+        catch (err) {
+            log?.(`[runs] retry-index hydrate failed (prior runs read as not-a-retry until restart): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    set(runId, retryOf) {
+        this.runToRetryOf.set(runId, retryOf);
+    }
+    /** The run id this run retries, or `undefined` (the DTO spells that as an ABSENT field). */
+    retryOfFor(runId) {
+        return this.runToRetryOf.get(runId);
+    }
+}
+//# sourceMappingURL=retry-index.js.map

package/dist/api/retry-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-index.js","sourceRoot":"","sources":["../../src/api/retry-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,OAAO,UAAU;IACJ,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1D;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAe,EAAE,GAA2B;QACxD,IAAI,CAAC;YACH,KAAK,MAAM,KAAK,IAAI,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;gBACpE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC;gBAC1C,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACnE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,EAAE,CACH,qFACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAa,EAAE,OAAe;QAChC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IAED,4FAA4F;IAC5F,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/api/routes.d.ts

@@ -1,11 +1,174 @@
 import type { FastifyInstance } from 'fastify';
+import { z } from 'zod';
 import { CoreAdapter } from '../core/adapter.js';
 import type { GateCache } from './gate-cache.js';
 import type { ElicitationCache } from './elicitation-cache.js';
+import { QeGateCache } from '../qe/gate-events.js';
+import { SeatHealthTracker } from './seat-health.js';
+import { type ProjectRoutesDeps } from '../projects/routes.js';
+import { InteractiveBridgePool } from '../interactive/bridge-pool.js';
+import { AuditLog } from './audit.js';
+import { RetryIndex } from './retry-index.js';
+import { GuidanceIndex } from './guidance-index.js';
+import { type AuthMode } from './auth.js';
 export { API_PREFIX } from './api-prefix.js';
+/**
+ * The launch body. Every field but `problem` is optional, which is what made stripping dangerous:
+ * omitting one is a legitimate request that gets an engine default, so a MISSPELLED one was
+ * indistinguishable from an omitted one and the run went ahead on a configuration the caller never
+ * asked for (FINDING-031).
+ *
+ * The names differ from core's on purpose and this is the trap worth knowing about: core's
+ * `LaunchSpec` takes `clis` (an array) and `workflow`, this takes `clisJson` (a JSON *string*) and
+ * `workflow`, and the `/ws` `sessionStarted` frame reports the chosen workflow as `workflowId`. A
+ * caller who reads the event stream to learn the field names arrives at `workflowId`, which this
+ * schema does not accept — so `.strict()` is what turns that trip into a 400 instead of an
+ * unworkflowed run reported as `201`.
+ */
+export declare const LaunchSchema: z.ZodEffects<z.ZodObject<{
+    problem: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    clisJson: z.ZodOptional<z.ZodString>;
+    entityMode: z.ZodOptional<z.ZodEnum<["shared", "isolated"]>>;
+    humanConfirm: z.ZodOptional<z.ZodString>;
+    repoRef: z.ZodOptional<z.ZodString>;
+    workflow: z.ZodOptional<z.ZodString>;
+    /** DES-PROJECT-001 §2.2 — file the run into a project; membership attaches atomically with
+     *  the launch record. Unknown/archived ⇒ the launch fails (never a silent unfiled run). */
+    projectId: z.ZodOptional<z.ZodString>;
+    /** crew#293 — `"pr"` appends the hardened deliver Tool phase (push run branch + `gh pr create`)
+     *  to a PER-RUN copy of the selected workflow. Requires `workflow` (enforced by the refine
+     *  below, so the 400 happens at parse time, not after the adapter is consulted). */
+    deliver: z.ZodOptional<z.ZodLiteral<"pr">>;
+    /** DES-UX-001 §8.3 (CREW-UX-3) — the run this launch retries. Must name an EXISTING run id
+     *  (the route checks the store and 400s with a named error otherwise); persisted via the
+     *  `run.launched` audit entry + retry index and echoed as `AgentSession.retry_of`. */
+    retryOf: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    problem: string;
+    retryOf?: string | undefined;
+    deliver?: "pr" | undefined;
+    projectId?: string | undefined;
+    sessionId?: string | undefined;
+    clisJson?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+    repoRef?: string | undefined;
+    workflow?: string | undefined;
+}, {
+    problem: string;
+    retryOf?: string | undefined;
+    deliver?: "pr" | undefined;
+    projectId?: string | undefined;
+    sessionId?: string | undefined;
+    clisJson?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+    repoRef?: string | undefined;
+    workflow?: string | undefined;
+}>, {
+    problem: string;
+    retryOf?: string | undefined;
+    deliver?: "pr" | undefined;
+    projectId?: string | undefined;
+    sessionId?: string | undefined;
+    clisJson?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+    repoRef?: string | undefined;
+    workflow?: string | undefined;
+}, {
+    problem: string;
+    retryOf?: string | undefined;
+    deliver?: "pr" | undefined;
+    projectId?: string | undefined;
+    sessionId?: string | undefined;
+    clisJson?: string | undefined;
+    entityMode?: "shared" | "isolated" | undefined;
+    humanConfirm?: string | undefined;
+    repoRef?: string | undefined;
+    workflow?: string | undefined;
+}>;
+export declare const GateSchema: z.ZodObject<{
+    approve: z.ZodBoolean;
+    amend: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    approve: boolean;
+    amend?: string | undefined;
+}, {
+    approve: boolean;
+    amend?: string | undefined;
+}>;
+/** `PUT /runs/:id/guidance` (DES-UX-002 §7.2, CREW-UX-7) — the durable pre-gate note body.
+ *  The empty string is a legal body: it CLEARS the note. The byte cap is checked in the route
+ *  (not zod's char-counting `max`) so the 400 names the actual limit. */
+export declare const GuidanceSchema: z.ZodObject<{
+    text: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    text: string;
+}, {
+    text: string;
+}>;
+export declare const OpenTerminalSchema: z.ZodObject<{
+    cwd: z.ZodString;
+    cmd: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+    governed: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    cwd: string;
+    cols: number;
+    rows: number;
+    cmd?: string[] | undefined;
+    governed?: boolean | undefined;
+}, {
+    cwd: string;
+    cols: number;
+    rows: number;
+    cmd?: string[] | undefined;
+    governed?: boolean | undefined;
+}>;
+/** `POST /open` (crew#273) — the studio Files tab's "open with the OS default app" body. */
+export declare const OpenPathSchema: z.ZodObject<{
+    path: z.ZodString;
+    runId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    runId?: string | undefined;
+}, {
+    path: string;
+    runId?: string | undefined;
+}>;
+/** The actor/audit deps (task #88) — threaded from `createServer`. */
+export interface SecurityDeps {
+    audit: AuditLog;
+    authMode: AuthMode;
+}
+/**
+ * Daemon-runtime deps the routes read but `createServer` owns: the seat-health fold (crew#274,
+ * fed by the daemon's single CoreEvent subscription) and the OS opener for `/open` (crew#273,
+ * injectable so tests never actually open anything).
+ */
+export interface RuntimeDeps {
+    seatHealth?: SeatHealthTracker;
+    /** Run→retry-lineage index (CREW-UX-3) — `createServer` hydrates one from the audit trail so
+     *  a restarted daemon still echoes `retry_of`; a directly-driven route set gets a fresh one. */
+    retryIndex?: RetryIndex;
+    /** Run→operator-guidance index (CREW-UX-7) — `createServer` hydrates one from the audit trail
+     *  so a restarted daemon still echoes `guidance`; a directly-driven route set gets a fresh one. */
+    guidanceIndex?: GuidanceIndex;
+    openWithOs?: (target: string) => Promise<void>;
+    /** Seat sign-in presence probe (seat sign-in) — injectable so route tests never read the
+     *  developer's real dotfiles. Defaults to the file/env heuristic in seat-signin.ts. */
+    signedIn?: (seatKey: string, workerConfigRoot?: string) => boolean | null;
+    /** The wicked-interactive bridge pool behind `/projects/:id/interactive/*` (DES-MERGE-001
+     *  slice 1). Injectable so the integration suite proxies to a FAKE bridge instead of
+     *  spawning a real `npx wicked-interactive serve`. */
+    interactiveBridges?: InteractiveBridgePool;
+}
 /**
  * The daemon REST surface. Every endpoint is a thin wrapper over one adapter /
  * core-ts call (DES-STUDIO-001 §2). `session`/`phase` nouns are now `run`/`unit`.
  */
-export declare function registerRoutes(app: FastifyInstance, adapter: CoreAdapter, gateCache: GateCache, elicitationCache: ElicitationCache): void;
+export declare function registerRoutes(app: FastifyInstance, adapter: CoreAdapter, gateCache: GateCache, elicitationCache: ElicitationCache, qeGateEvents?: QeGateCache, projects?: ProjectRoutesDeps, security?: SecurityDeps, runtime?: RuntimeDeps): void;
 //# sourceMappingURL=routes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAQ/C,OAAO,EAAwB,WAAW,EAAkD,MAAM,oBAAoB,CAAC;AAEvH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAO/D,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0I7C;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,GACjC,IAAI,CAuiCN"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,EAAwB,WAAW,EAAkD,MAAM,oBAAoB,CAAC;AAEvH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAWrD,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,EAAe,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAInF,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAyF7C;;;;;;;;;;;;GAYG;AAIH,eAAO,MAAM,YAAY;;;;;;;;IAQvB;+FAC2F;;IAE3F;;wFAEoF;;IAEpF;;0FAEsF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKtF,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;;;;;EAGZ,CAAC;AAEZ;;yEAEyE;AACzE,eAAO,MAAM,cAAc;;;;;;EAEhB,CAAC;AAUZ,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;EAQpB,CAAC;AAOZ,4FAA4F;AAC5F,eAAO,MAAM,cAAc;;;;;;;;;EAGhB,CAAC;AAwBZ,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;oGACgG;IAChG,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;uGACmG;IACnG,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;2FACuF;IACvF,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAC1E;;0DAEsD;IACtD,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,SAAS,EACpB,gBAAgB,EAAE,gBAAgB,EAIlC,YAAY,GAAE,WAA+B,EAG7C,QAAQ,GAAE,iBAAqF,EAK/F,QAAQ,GAAE,YAA0D,EAGpE,OAAO,GAAE,WAAgB,GACxB,IAAI,CAqtDN"}