wicked-crew 0.6.0 → 0.7.1

package/dist/core/deliverable-floor.js

@@ -0,0 +1,248 @@
+/**
+ * THE DELIVERABLE FLOOR (crew#311) — "done" is re-derived from the artifact, never asserted.
+ *
+ * ## The defect
+ *
+ * A governed unit that produced NOTHING still passed its execution gate on the strength of a
+ * prose reply. The engine's only universal floor is the SUBSTANCE floor
+ * (wicked-core `actor.rs`, "phase produced no reviewable substance"): a governed
+ * Creator/Neutral unit is rejected only when its output carries BOTH under 200 trimmed chars
+ * of prose AND no worktree change. So ~200 characters of narration — "I'll read the design
+ * spec, let me check the API types…" — clears it, with no file anywhere. Prose length stood in
+ * for evidence.
+ *
+ * The engine has two real evidence instruments, and neither reaches a run of this shape:
+ *
+ *  1. `validator_pin` → the built-in EVIDENCE floor (`builtin_floors::EVIDENCE_FLOOR_PIN`,
+ *     criterion "the run left a change in its worktree (done is re-derived from the diff, never
+ *     asserted)"). It re-verifies a git DIFF, and is fail-closed on a run with no worktree — so
+ *     an UNBOUND run (`repoRef` omitted, `workdir: null`) can never satisfy it. Every crew
+ *     interactive seam launches unbound on purpose (wicked-core#293/#294), and their deliverable
+ *     is a FILE in a declared write root, invisible to a diff.
+ *  2. `required_deliverables` → enforced by wicked-core as of FINDING-101, but only in the
+ *     WRAPPED-CLI runner (`execute_wrapped.rs`), only against the unit's own cwd, and any
+ *     absolute or `..`-escaping path is counted MISSING by construction. The ACP runner — the
+ *     path a real seat takes — never consults it. So for a run whose deliverable is an absolute
+ *     path under `extraWriteRoots`, declaring it there would fail every run on one runner and
+ *     check nothing on the other. That gap is wicked-core's to close
+ *     (wicked-core#297, items 1 and 3); once it is, this phase can retire in favour of the
+ *     engine field. Crew must not paper over it meanwhile by declaring something unverifiable.
+ *
+ * ## What this module does
+ *
+ * It gives crew the instrument it can honestly own: a deterministic TOOL phase, appended to a
+ * PER-RUN copy of the workflow def (the exact mechanism `core/deliver.ts` proved for
+ * `deliver: "pr"` — the shared def is never mutated, nothing lands in the overlay dir, the
+ * catalog never grows a per-run entry), which asserts that the artifacts the launcher declared
+ * EXIST, are non-empty, and were written by THIS run (crew#320 — existence alone re-derives
+ * nothing at a path a prior run already populated). A Tool phase's failure surface is its exit
+ * code: wicked-core's
+ * `run_tool_cmd` maps a non-zero exit to `StepStatus::Failed`, which fails the unit and the run
+ * through the unchanged completion path. No LLM, no worktree, no judgement about the content —
+ * only "the phase promised this file; is it there".
+ *
+ * That is deliberately a FLOOR and not a review, in exactly the sense `builtin_floors` documents:
+ * it proves an artifact exists. It says nothing about whether the artifact is correct, or even
+ * related to the task. What it removes is the failure mode crew#311 recorded — a unit whose
+ * `Write` was policy-denied, which therefore produced no file at all, reporting done.
+ *
+ * ## The report
+ *
+ * The script prints what was EXPECTED and what was FOUND before it exits, on both branches, so
+ * the failure is legible from the unit output alone: which paths were declared, which exist
+ * (with their size), and which are missing and why (absent / empty file / empty directory).
+ * An operator reading a failed run must never have to guess what the phase was supposed to
+ * produce.
+ */
+/** The id of the appended floor phase — also the collision probe when a def already carries one. */
+export const DELIVERABLE_FLOOR_PHASE_ID = 'verify-deliverables';
+/** The marker line the failing branch prints. Asserted by tests and greppable in a unit output. */
+export const DELIVERABLE_FLOOR_FAILURE_MARKER = '[wicked-crew] DELIVERABLE FLOOR FAILED';
+/**
+ * Slack allowed on the freshness comparison, in milliseconds (crew#320).
+ *
+ * The launch timestamp comes from the daemon's `Date.now()` (millisecond resolution); the
+ * artifact timestamp comes from the FILESYSTEM, and not every filesystem keeps milliseconds —
+ * HFS+ and ext3 truncate mtime to whole seconds, and some SMB/NFS mounts are coarser still. A
+ * file genuinely written 400 ms after a launch at `…:07.600Z` can therefore report an mtime of
+ * `…:07.000Z` and read as older than the launch that produced it.
+ *
+ * One second absorbs that truncation without weakening the check this exists to make: the stale
+ * artifact crew#320 describes is the PREVIOUS run's output, which predates this run's launch by
+ * that run's whole remaining lifetime plus the turnaround before the next one — orders of
+ * magnitude more than a timestamp-granularity rounding error.
+ */
+export const DELIVERABLE_FLOOR_MTIME_SLACK_MS = 1_000;
+/**
+ * The floor program, run as `node -e <script> <launchedAtMs> <path...>`.
+ *
+ * Node rather than a shell: this must work identically on macOS, Linux, and Windows, and the
+ * daemon already IS node, so `process.execPath` is a guaranteed-present absolute interpreter
+ * (see {@link deliverableFloorPhase}). `-e` runs CommonJS, so `require` is available; the launch
+ * timestamp and the declared paths arrive as `process.argv.slice(1)`, passed as argv rather than
+ * interpolated into a shell string so a path containing a space, a quote, or a `$` cannot be
+ * re-parsed.
+ *
+ * A path counts as PRODUCED when it exists, carries bytes, and was written by THIS RUN:
+ *
+ *  - a non-empty file whose `mtimeMs` is at or after the launch timestamp;
+ *  - a directory holding at least one direct entry whose `mtimeMs` is at or after it (a phase may
+ *    declare a directory of outputs; the directory's own mtime is not enough, because a directory
+ *    left over from a prior run keeps its entries and its mtime).
+ *
+ * A zero-byte file is NOT evidence — it is the same "nothing was produced" this exists to catch,
+ * and the draft/chat seams already treated an empty deliverable as a failure at their own
+ * post-hoc check.
+ *
+ * ## Why the timestamp (crew#320)
+ *
+ * Existence alone re-derives nothing when the path can be pre-populated. The interactive seams
+ * copy their deliverable to `outPath` and never remove it, and demo/draft/edit run directories
+ * are keyed by DOCUMENT ID (edit by `doc:version`) — so a second run over the same key starts
+ * with the previous run's file already sitting at the declared path. The floor would find it,
+ * find bytes, and pass: the artifact exists, but this run did not produce it. "Done" would be
+ * asserted by a leftover rather than derived from this run's work — the exact failure shape one
+ * level in from the one crew#311 closed.
+ *
+ * The comparison is the stronger of the two available fixes. Clearing `outPath` at launch would
+ * also work, but only for as long as every seam remembers to clear it; the mtime check survives
+ * a seam that forgets, and it survives a seam that has not been written yet.
+ *
+ * A launch timestamp that does not parse FAILS CLOSED. An armed floor that cannot judge freshness
+ * is not a floor, and passing on the grounds that the check itself is broken is precisely the
+ * "assert done" move this module exists to refuse.
+ */
+export function deliverableFloorScript() {
+    return [
+        'const fs=require("node:fs");',
+        'const pathmod=require("node:path");',
+        'const launch=Number(process.argv[1]);',
+        'const want=process.argv.slice(2);',
+        'const iso=(t)=>{try{return new Date(t).toISOString()}catch(e){return String(t)}};',
+        'if(!Number.isFinite(launch)){',
+        `console.log(${JSON.stringify(DELIVERABLE_FLOOR_FAILURE_MARKER)}+" — the floor was armed without a parseable launch timestamp ("+JSON.stringify(process.argv[1])+"), so it cannot tell this run's artifacts from a prior run's leftovers. Failing closed (crew#320).");`,
+        'process.exit(1)}',
+        `const floorAt=launch-${DELIVERABLE_FLOOR_MTIME_SLACK_MS};`,
+        'const fresh=(t)=>t>=floorAt;',
+        'const found=[],missing=[];',
+        'for(const p of want){',
+        'let s=null;',
+        'try{s=fs.statSync(p)}catch(e){s=null}',
+        'if(s===null){missing.push(p+" (does not exist)");continue}',
+        'if(s.isDirectory()){',
+        'let names=[];try{names=fs.readdirSync(p)}catch(e){names=[]}',
+        'if(names.length===0){missing.push(p+" (directory is empty)");continue}',
+        'let n=0;',
+        'for(const e of names){let es=null;try{es=fs.statSync(pathmod.join(p,e))}catch(err){es=null}if(es!==null&&fresh(es.mtimeMs)){n++}}',
+        'if(n===0){missing.push(p+" (directory, "+names.length+" entries, but NONE written by this run — every entry predates the launch at "+iso(launch)+", so they are a PRIOR run\'s output)")}',
+        'else{found.push(p+" (directory, "+names.length+" entries, "+n+" written by this run)")}',
+        'continue}',
+        'if(s.size===0){missing.push(p+" (file is empty, 0 bytes)");continue}',
+        'if(!fresh(s.mtimeMs)){missing.push(p+" (STALE: last modified "+iso(s.mtimeMs)+", before this run launched at "+iso(launch)+" — it is a PRIOR run\'s artifact, not this run\'s)");continue}',
+        'found.push(p+" ("+s.size+" bytes)");',
+        '}',
+        'console.log("[wicked-crew] deliverable floor: this phase declared "+want.length+" artifact(s); this run launched at "+iso(launch)+".");',
+        'console.log("[wicked-crew] EXPECTED: "+(want.length?want.join(", "):"(none)"));',
+        'console.log("[wicked-crew] FOUND:    "+(found.length?found.join(", "):"(nothing)"));',
+        'if(missing.length===0){',
+        'console.log("[wicked-crew] every declared deliverable exists, carries bytes, and was written by THIS run — done is re-derived from the artifact, not asserted.");',
+        'process.exit(0)}',
+        'console.log("[wicked-crew] MISSING:  "+missing.join(", "));',
+        `console.log(${JSON.stringify(DELIVERABLE_FLOOR_FAILURE_MARKER)}+" — the run reported done without producing the artifact(s) it was launched to produce. A prose reply is not a deliverable (crew#311), and a prior run's leftover file is not this run's evidence (crew#320).");`,
+        'process.exit(1);',
+    ].join('');
+}
+/**
+ * The floor PhaseDef for `paths`, judged against `launchedAtMs`.
+ *
+ * `launchedAtMs` is positional and required rather than defaulted (crew#320): a default would let
+ * a new caller arm a floor that checks existence only, and the resulting run would report done on
+ * a leftover with nothing in its output saying the freshness half was never applied. The compiler
+ * asking the question is the point.
+ *
+ * `cmd[0]` is `process.execPath` — the ABSOLUTE path of the node binary already running the
+ * daemon — not the bare name `node`. wicked-core preflights every Tool phase at launch
+ * (`workflow::preflight_tool_phases`) and REFUSES to start a run whose tool binary does not
+ * resolve; a bare `node` resolves only if the engine's PATH happens to carry one, which is
+ * exactly the kind of environment-dependent gate that fails in production and passes in tests.
+ * The composed def is per-run and hot-registered only, so baking a machine-local path into it
+ * costs nothing: it never reaches the catalog or the overlay dir.
+ *
+ * `role: 'neutral'` + `executes_code: false` + `governed`-free Tool dispatch: this phase is
+ * deterministic tooling, so the substance floor, the agent judge, and the input-governance fold
+ * do not apply to it — its verdict IS its exit code.
+ */
+export function deliverableFloorPhase(paths, launchedAtMs, dependsOn = []) {
+    return {
+        id: DELIVERABLE_FLOOR_PHASE_ID,
+        kind: 'test',
+        executor: {
+            type: 'tool',
+            // The timestamp rides ahead of the paths as its own argv slot: a path is arbitrary user
+            // text and could itself look like a number, so position — not parsing — separates them.
+            cmd: [process.execPath, '-e', deliverableFloorScript(), String(launchedAtMs), ...paths],
+        },
+        gate_type: 'execution',
+        gate: 'auto',
+        executes_code: false,
+        // NOT `verified_evidence: true`: wicked-core arms any `verified_evidence` phase that names no
+        // pin of its own with the worktree-DIFF floor (FINDING-055), which is fail-closed on the
+        // repo-less runs this phase exists to serve — it would deny every one of them for the wrong
+        // reason. This phase carries its own re-verification in its exit code.
+        verified_evidence: false,
+        // NOT the declared paths either: core checks `required_deliverables` relative to the unit's
+        // cwd and counts every absolute path as missing (see the module doc; wicked-core#297).
+        // Declaring them here would fail the run on the wrapped-CLI path for the wrong reason.
+        required_deliverables: [],
+        depends_on: dependsOn,
+        role: 'neutral',
+        skill_ref: null,
+        allowed_skills: [],
+        validator_pin: null,
+    };
+}
+/**
+ * Compose a PER-RUN def: `base`'s phases (untouched — the shared def is never mutated) plus the
+ * deliverable floor appended last, under a run-scoped id. Mirrors `composeDeliverWorkflow`'s
+ * contract exactly, including the id charset/length rules `registerWorkflow` enforces and the
+ * deliberate absence of `is_system` (core's register schema rejects unknown fields on this path,
+ * and a composed def is engine input, not catalog data).
+ *
+ * Throws on an empty `paths` list — a floor over nothing would pass vacuously, which is the
+ * defect, not the fix. Throws on a def that already carries the floor phase, for the same
+ * ambiguity reason `composeDeliverWorkflow` does.
+ *
+ * `launchedAtMs` defaults to composition time, which is the correct instant on every path that
+ * exists: composition is the last thing that happens before `core.launchRun`, so nothing this run
+ * produces can predate it, and a nonsense value is rejected here rather than being discovered by
+ * the tool phase minutes later (crew#320).
+ */
+export function composeDeliverableFloor(base, runId, paths, launchedAtMs = Date.now()) {
+    if (paths.length === 0) {
+        throw new Error('requireDeliverables: at least one path must be declared — a floor over nothing passes vacuously');
+    }
+    for (const p of paths) {
+        if (p.trim().length === 0) {
+            throw new Error('requireDeliverables: a declared deliverable path must not be blank');
+        }
+    }
+    if (!Number.isFinite(launchedAtMs) || launchedAtMs <= 0) {
+        throw new Error(`requireDeliverables: launchedAtMs must be a positive epoch-millisecond timestamp, got ` +
+            `${String(launchedAtMs)} — the floor compares it against each artifact's mtime to prove ` +
+            `THIS run produced them`);
+    }
+    if (base.phases.some((p) => p.id === DELIVERABLE_FLOOR_PHASE_ID)) {
+        throw new Error(`workflow '${base.id}' already has a '${DELIVERABLE_FLOOR_PHASE_ID}' phase — launch it without requireDeliverables`);
+    }
+    const last = base.phases[base.phases.length - 1];
+    const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const composedId = `${base.id}-verified-${safeRunId}`.slice(0, 128);
+    return {
+        id: composedId,
+        phases: [
+            ...base.phases,
+            deliverableFloorPhase(paths, launchedAtMs, last !== undefined ? [last.id] : []),
+        ],
+    };
+}
+//# sourceMappingURL=deliverable-floor.js.map

package/dist/core/deliverable-floor.js.map

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

package/dist/core/exec.d.ts

@@ -18,6 +18,8 @@ type ExecOpts = {
     timeout?: number;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /** Suppress the console window a child would open on Windows (git, etc.). */
+    windowsHide?: boolean;
     /** `number | undefined` on purpose: `exactOptionalPropertyTypes` would otherwise reject the very
      *  shape this module defends against, making the guard below untypeable and untestable. */
     maxBuffer?: number | undefined;

package/dist/core/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AA+BA;;sFAEsF;AACtF,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAUtD;;;;oDAIoD;AACpD,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM;gBADlB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM;CAS9B;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMtD;AAED,KAAK,QAAQ,GAAG;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;+FAC2F;IAC3F,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF;;kFAEkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED;;kEAEkE;AAClE,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,QAAa,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB7C"}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AA+BA;;sFAEsF;AACtF,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAUtD;;;;oDAIoD;AACpD,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM;gBADlB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM;CAS9B;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMtD;AAED,KAAK,QAAQ,GAAG;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;+FAC2F;IAC3F,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,CAAC;AAEF;;kFAEkF;AAClF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEvD;AAED;;kEAEkE;AAClE,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,QAAa,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoB7C"}

package/dist/core/exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,eAAe;AACf,EAAE;AACF,oGAAoG;AACpG,iGAAiG;AACjG,gGAAgG;AAChG,2FAA2F;AAC3F,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,qCAAqC;AACrC,EAAE;AACF,wDAAwD;AACxD,EAAE;AACF,gGAAgG;AAChG,8FAA8F;AAC9F,mGAAmG;AACnG,0EAA0E;AAC1E,EAAE;AACF,0BAA0B;AAC1B,EAAE;AACF,8FAA8F;AAC9F,6FAA6F;AAC7F,0BAA0B;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;sFAEsF;AACtF,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD;kFACkF;AAClF,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;IACpE,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,OAAO,GAAG,CAAC,QAAQ,CAAC;AACtB,CAAC;AAED;;;;oDAIoD;AACpD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IACA;IAFX,YACW,IAAY,EACZ,UAAkB;QAE3B,KAAK,CACH,GAAG,IAAI,uBAAuB,UAAU,CAAC,UAAU,CAAC,wCAAwC;YAC1F,0CAA0C,IAAI,8CAA8C;YAC5F,wDAAwD,CAC3D,CAAC;QAPO,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAQ;QAO3B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACX,GAA0B,CAAC,IAAI,KAAK,mCAAmC,CACzE,CAAC;AACJ,CAAC;AAWD;;kFAEkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC;AACjD,CAAC;AAED;;kEAEkE;AAClE,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,IAAc,EACd,OAAiB,EAAE;IAEnB,gGAAgG;IAChG,6FAA6F;IAC7F,2FAA2F;IAC3F,iCAAiC;IACjC,EAAE;IACF,sFAAsF;IACtF,6EAA6E;IAC7E,8DAA8D;IAC9D,EAAE;IACF,8FAA8F;IAC9F,uFAAuF;IACvF,4CAA4C;IAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,gBAAgB,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACzE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,EAAE;AACF,eAAe;AACf,EAAE;AACF,oGAAoG;AACpG,iGAAiG;AACjG,gGAAgG;AAChG,2FAA2F;AAC3F,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,qCAAqC;AACrC,EAAE;AACF,wDAAwD;AACxD,EAAE;AACF,gGAAgG;AAChG,8FAA8F;AAC9F,mGAAmG;AACnG,0EAA0E;AAC1E,EAAE;AACF,0BAA0B;AAC1B,EAAE;AACF,8FAA8F;AAC9F,6FAA6F;AAC7F,0BAA0B;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C;;sFAEsF;AACtF,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtD;kFACkF;AAClF,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;IACpE,IAAI,CAAC,IAAI,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,OAAO,GAAG,CAAC,QAAQ,CAAC;AACtB,CAAC;AAED;;;;oDAIoD;AACpD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IACA;IAFX,YACW,IAAY,EACZ,UAAkB;QAE3B,KAAK,CACH,GAAG,IAAI,uBAAuB,UAAU,CAAC,UAAU,CAAC,wCAAwC;YAC1F,0CAA0C,IAAI,8CAA8C;YAC5F,wDAAwD,CAC3D,CAAC;QAPO,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAQ;QAO3B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACX,GAA0B,CAAC,IAAI,KAAK,mCAAmC,CACzE,CAAC;AACJ,CAAC;AAaD;;kFAEkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,IAAc;IAC7C,OAAO,IAAI,CAAC,SAAS,IAAI,qBAAqB,CAAC;AACjD,CAAC;AAED;;kEAEkE;AAClE,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAY,EACZ,IAAc,EACd,OAAiB,EAAE;IAEnB,gGAAgG;IAChG,6FAA6F;IAC7F,2FAA2F;IAC3F,iCAAiC;IACjC,EAAE;IACF,sFAAsF;IACtF,6EAA6E;IAC7E,8DAA8D;IAC9D,EAAE;IACF,8FAA8F;IAC9F,uFAAuF;IACvF,4CAA4C;IAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,gBAAgB,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACzE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/core/types.d.ts

@@ -55,6 +55,84 @@ export interface LaunchRunInput {
      * fails the launch with no session persisted. Omit for runs that deliver inside their workdir.
      */
     extraWriteRoots?: string[];
+    /**
+     * The PROJECT's co-located code graph this run's governed workers should query instead of the
+     * run repo's own — resolved by `projects/graph.ts::resolveProjectGraphBinding`, which is the ONE
+     * thing that knows where a project graph lives and what each repo is labelled inside it.
+     *
+     * `repoLabel` is optional in the TYPE because a repo-LESS run legitimately has none — there is
+     * no own repo to name. It is not optional in MEANING for a repo-bound run: the engine uses it to
+     * confirm the co-located graph actually holds this run's repo.
+     *
+     * TypeScript cannot catch a missing label here — the invariant ties this field to `repoRef`, a
+     * sibling field — so `CoreAdapter.launchRun` enforces it at RUNTIME. Two failure modes, and they
+     * are NOT the same thing:
+     *
+     *  - **crew refuses the launch outright.** Passing `projectGraph` without `projectId`, or with
+     *    `repoRef` set and no `repoLabel`, THROWS: no session is created and nothing runs. These are
+     *    caller bugs with no sensible degraded reading, so they fail before anything is persisted.
+     *  - **the ENGINE declines the binding.** A well-formed binding whose graph turns out not to hold
+     *    the named label is refused engine-side and the run proceeds against its own repo graph — a
+     *    real launch, quietly narrower. That is the fallback; it is not what a missing `repoLabel`
+     *    gets you.
+     *
+     * Omit the whole field for the per-repo behaviour.
+     */
+    projectGraph?: {
+        dbPath: string;
+        repoLabel?: string;
+    };
+    /**
+     * Delivery mode (crew#293). `"pr"` ⇒ the adapter appends the hardened deliver Tool phase
+     * (push the run branch + `gh pr create`, see `core/deliver.ts`) to a PER-RUN copy of the
+     * selected workflow def and launches that copy — the shared def is never mutated. Requires
+     * `workflow`; a free-text run has no def to append to. Omit ⇒ no delivery phase (default).
+     */
+    deliver?: 'pr';
+    /**
+     * THE DELIVERABLE FLOOR (crew#311) — absolute paths this run MUST have produced by the time
+     * it finishes. When non-empty (and `workflow` is set), the adapter appends a deterministic
+     * verification Tool phase to a PER-RUN copy of the def (see `core/deliverable-floor.ts`)
+     * which re-derives "done" from the artifacts: every declared path must exist and carry bytes,
+     * or the phase exits non-zero and the RUN FAILS, naming what was expected and what was found.
+     *
+     * This is the instrument for runs whose deliverable is a FILE in a declared write root rather
+     * than a worktree diff — every crew interactive seam. The engine's own two floors do not
+     * reach them: the built-in evidence floor re-verifies a git diff and is fail-closed on a
+     * repo-less run, and `required_deliverables` is checked only by the wrapped-CLI runner and
+     * only against the unit's cwd (an absolute path counts as missing there by construction).
+     *
+     * Omit for runs whose evidence is the worktree diff — those are the engine's to floor.
+     */
+    requireDeliverables?: string[];
+}
+/** Default `workerStallMinutes` (crew#287): silent minutes before the stall watchdog fires. */
+export declare const DEFAULT_WORKER_STALL_MINUTES = 15;
+/**
+ * LOCAL extension of the published `SystemSettings` (wicked-crew-api-types 0.6.0): the crew#287
+ * stall-watchdog knob is daemon-owned until the contract picks it up. NOTE for the next
+ * api-types release: fold `workerStallMinutes` into `SystemSettings` (and the synthetic
+ * `workerStalled` /ws frame — see `api/stall-watchdog.ts` `WorkerStalledFrame` — into the
+ * event documentation). Extra fields are forward-additive on the wire (DES-STUDIO-001 §5.1),
+ * so shipping it daemon-side first breaks no consumer.
+ */
+export interface CrewSystemSettings extends SystemSettings {
+    /**
+     * Minutes a run in `executing` may go without ANY engine event on the daemon's relay before
+     * a synthetic `workerStalled` frame is broadcast on /ws (detection only; default 15).
+     */
+    workerStallMinutes?: number;
+    /**
+     * Skin-owned preference blobs, round-tripped verbatim (crew#323). RESTATED here rather than
+     * merely inherited from `SystemSettings` so the daemon's own type SAYS the settings store is
+     * shared with the experience plane — the fact that used to live only in a comment in the
+     * studio's client, which is how `studio.appearance` / `studio.notifications` could be
+     * silently dropped by `PUT /settings` without either side's types objecting.
+     *
+     * The daemon never interprets a value here; it enforces only "JSON-serializable, under the
+     * per-key byte cap" at the PUT boundary (`api/routes.ts` `STUDIO_SETTINGS_MAX_BYTES`).
+     */
+    [key: `studio.${string}`]: unknown;
 }
-export declare const DEFAULT_SETTINGS: SystemSettings;
+export declare const DEFAULT_SETTINGS: CrewSystemSettings;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mBAAmB,uBAAuB,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,eAAO,MAAM,gBAAgB,EAAE,cAE9B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mBAAmB,uBAAuB,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAAY,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC;IACf;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,+FAA+F;AAC/F,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,CAAC,GAAG,EAAE,UAAU,MAAM,EAAE,GAAG,OAAO,CAAC;CACpC;AAED,eAAO,MAAM,gBAAgB,EAAE,kBAG9B,CAAC"}

package/dist/core/types.js

@@ -18,7 +18,10 @@
  * daemon speaks these daemon-owned shapes, which is what quarantines the
  * FINALIZING core-ts `subscribe` seam to a single file (DES-STUDIO-001 §5.2).
  */
+/** Default `workerStallMinutes` (crew#287): silent minutes before the stall watchdog fires. */
+export const DEFAULT_WORKER_STALL_MINUTES = 15;
 export const DEFAULT_SETTINGS = {
     graphNodeLimit: 150,
+    workerStallMinutes: DEFAULT_WORKER_STALL_MINUTES,
 };
 //# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA4CH,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,cAAc,EAAE,GAAG;CACpB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA2FH,+FAA+F;AAC/F,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAC;AA6B/C,MAAM,CAAC,MAAM,gBAAgB,GAAuB;IAClD,cAAc,EAAE,GAAG;IACnB,kBAAkB,EAAE,4BAA4B;CACjD,CAAC"}

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

@@ -19,9 +19,39 @@
  * live pid earns three 1.5 s attempts before the bridge is declared dead. Identity is checked
  * too: `/api/health` must report THIS root, or a recycled port belonging to some other service
  * would be proxied as if it were ours.
+ *
+ * On start/adopt the pool also records the daemon's own origin with the bridge (crew#298,
+ * `POST /api/studio-origin`, interactive ≥ 0.8.0) so the bridge's `GET /` redirects a direct
+ * visitor into studio instead of its API-only fallback page. Fire-and-forget, once per pooled
+ * bridge: recording can never fail — or slow down — a proxied request.
  */
 import { type ChildProcess } from 'node:child_process';
+import type { AddressInfo } from 'node:net';
 export declare const LOCK_NAME = ".wi-serve.json";
+/**
+ * The wicked-interactive range crew will start, as an npm spec.
+ *
+ * The spawn used to be a bare `npx --yes wicked-interactive`, which resolves whatever the public
+ * registry calls `latest` AT RUNTIME — no lockfile entry, no integrity hash, no floor. Three things
+ * follow from that, and none of them are theoretical:
+ *
+ *  - a breaking wicked-interactive release changes crew's behaviour with no crew change, no review,
+ *    and nothing in crew's history to point at during the incident;
+ *  - crew has no way to REQUIRE a route it depends on. The learned-theme readback
+ *    (`GET /d/:docId/api/theme/learned`, interactive#181) shipped in 0.8.1; against 0.8.0 the
+ *    brand-learn surface polls forever and degrades silently. A floor turns that into a resolvable
+ *    version, not a mystery;
+ *  - the resolution is a network fetch from a public registry into a long-lived daemon.
+ *
+ * A caret floor is the smallest fix that closes the first two: it pins the MAJOR-compatible range so
+ * a 0.9.0 cannot arrive unannounced, and it states the minimum crew actually needs. It does NOT make
+ * the fetch reproducible — that needs a real dependency with a lockfile entry, which is the
+ * follow-up this comment exists to keep visible.
+ *
+ * Bump this when crew starts depending on a newer interactive route, and say which route in the
+ * commit.
+ */
+export declare const INTERACTIVE_SPEC = "wicked-interactive@^0.8.1";
 /** ADR-0025: 1.5 s × 3 while the pid lives. */
 export declare const HEALTH_TIMEOUT_MS = 1500;
 export declare const HEALTH_ATTEMPTS = 3;
@@ -45,7 +75,21 @@ export interface BridgePoolIo {
     startTimeoutMs?: number;
     healthTimeoutMs?: number;
     log?: (msg: string) => void;
+    /** Lower-severity channel for EXPECTED skips (a pre-0.8.0 bridge without the endpoint, #298). */
+    debug?: (msg: string) => void;
+    /**
+     * The daemon's own origin (`http://<bound host>:<bound port>`), resolved LAZILY — the pool is
+     * built before `listen`, but only consulted while serving a request, i.e. after the address is
+     * bound. Null (or absent) means "nothing to record" and the pool never POSTs (#298).
+     */
+    studioOrigin?: () => string | null;
 }
+/**
+ * The daemon's own http origin from its bound server address, or null before `listen`. Wildcard
+ * binds (`0.0.0.0` / `::`) are not dialable from a browser, so they normalize to loopback — the
+ * bridge is local-only anyway, so whoever hits its port can reach the daemon at 127.0.0.1 too.
+ */
+export declare function boundOrigin(addr: AddressInfo | string | null): string | null;
 /** `<root>/.wi-serve.json`, or null when absent/unparseable/incomplete. */
 export declare function readLock(root: string): LiveBridge | null;
 /** Signal 0 probes existence without delivering: EPERM means alive-but-not-ours. */
@@ -64,6 +108,14 @@ export declare class InteractiveBridgePool {
     /** Live bridges, for tests and future operator introspection. */
     keys(): string[];
     private resolveOrStart;
+    /**
+     * POST the daemon's own origin to the bridge's `/api/studio-origin` (#298), so the bridge's
+     * `GET /` redirects a direct visitor into studio instead of the API-only fallback page.
+     * At most one attempt per pooled bridge per process; 404/405 means the bridge predates the
+     * endpoint (interactive < 0.8.0) and is an expected skip, any other failure is a warn — never
+     * an error, because origin recording must never fail a proxy request.
+     */
+    private recordStudioOrigin;
     /** The lockfile points at a bridge that is alive, answering, and serving THIS root. */
     private healthy;
     private start;

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

@@ -1 +1 @@
-{"version":3,"file":"bridge-pool.d.ts","sourceRoot":"","sources":["../../src/interactive/bridge-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI3E,eAAO,MAAM,SAAS,mBAAmB,CAAC;AAC1C,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sFAAsF;AACtF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAOD,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAQxD;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ7C;AAkBD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiC;IACtD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEvD,EAAE,GAAE,YAAiB;IAIjC,qGAAqG;IAC/F,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc/C,uFAAuF;IACvF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,iEAAiE;IACjE,IAAI,IAAI,MAAM,EAAE;YAIF,cAAc;IAW5B,uFAAuF;YACzE,OAAO;YAeP,KAAK;CAsCpB"}
+{"version":3,"file":"bridge-pool.d.ts","sourceRoot":"","sources":["../../src/interactive/bridge-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C,eAAO,MAAM,SAAS,mBAAmB,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAC5D,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,6FAA6F;AAC7F,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,sFAAsF;AACtF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAOD,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,iGAAiG;IACjG,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAS5E;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAQxD;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQ7C;AAyBD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;IAClC,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmC;IACxD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEvD,EAAE,GAAE,YAAiB;IAIjC,qGAAqG;IAC/F,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc/C,uFAAuF;IACvF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,iEAAiE;IACjE,IAAI,IAAI,MAAM,EAAE;YAIF,cAAc;IAW5B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA+B1B,uFAAuF;YACzE,OAAO;YAeP,KAAK;CAsCpB"}

package/dist/interactive/bridge-pool.js

@@ -19,11 +19,40 @@
  * live pid earns three 1.5 s attempts before the bridge is declared dead. Identity is checked
  * too: `/api/health` must report THIS root, or a recycled port belonging to some other service
  * would be proxied as if it were ours.
+ *
+ * On start/adopt the pool also records the daemon's own origin with the bridge (crew#298,
+ * `POST /api/studio-origin`, interactive ≥ 0.8.0) so the bridge's `GET /` redirects a direct
+ * visitor into studio instead of its API-only fallback page. Fire-and-forget, once per pooled
+ * bridge: recording can never fail — or slow down — a proxied request.
  */
 import { spawn as nodeSpawn } from 'node:child_process';
 import { mkdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 export const LOCK_NAME = '.wi-serve.json';
+/**
+ * The wicked-interactive range crew will start, as an npm spec.
+ *
+ * The spawn used to be a bare `npx --yes wicked-interactive`, which resolves whatever the public
+ * registry calls `latest` AT RUNTIME — no lockfile entry, no integrity hash, no floor. Three things
+ * follow from that, and none of them are theoretical:
+ *
+ *  - a breaking wicked-interactive release changes crew's behaviour with no crew change, no review,
+ *    and nothing in crew's history to point at during the incident;
+ *  - crew has no way to REQUIRE a route it depends on. The learned-theme readback
+ *    (`GET /d/:docId/api/theme/learned`, interactive#181) shipped in 0.8.1; against 0.8.0 the
+ *    brand-learn surface polls forever and degrades silently. A floor turns that into a resolvable
+ *    version, not a mystery;
+ *  - the resolution is a network fetch from a public registry into a long-lived daemon.
+ *
+ * A caret floor is the smallest fix that closes the first two: it pins the MAJOR-compatible range so
+ * a 0.9.0 cannot arrive unannounced, and it states the minimum crew actually needs. It does NOT make
+ * the fetch reproducible — that needs a real dependency with a lockfile entry, which is the
+ * follow-up this comment exists to keep visible.
+ *
+ * Bump this when crew starts depending on a newer interactive route, and say which route in the
+ * commit.
+ */
+export const INTERACTIVE_SPEC = 'wicked-interactive@^0.8.1';
 /** ADR-0025: 1.5 s × 3 while the pid lives. */
 export const HEALTH_TIMEOUT_MS = 1500;
 export const HEALTH_ATTEMPTS = 3;
@@ -41,7 +70,22 @@ export class BridgeUnavailableError extends Error {
 }
 /** The one command that reproduces a failed start in a terminal, where its output is visible. */
 function serveCommand(root) {
-    return `npx wicked-interactive serve --root ${root}`;
+    return `npx ${INTERACTIVE_SPEC} serve --root ${root}`;
+}
+/**
+ * The daemon's own http origin from its bound server address, or null before `listen`. Wildcard
+ * binds (`0.0.0.0` / `::`) are not dialable from a browser, so they normalize to loopback — the
+ * bridge is local-only anyway, so whoever hits its port can reach the daemon at 127.0.0.1 too.
+ */
+export function boundOrigin(addr) {
+    if (addr === null || typeof addr === 'string')
+        return null;
+    const host = addr.address === '' || addr.address === '0.0.0.0' || addr.address === '::'
+        ? '127.0.0.1'
+        : addr.address.includes(':')
+            ? `[${addr.address}]`
+            : addr.address;
+    return `http://${host}:${addr.port}`;
 }
 /** `<root>/.wi-serve.json`, or null when absent/unparseable/incomplete. */
 export function readLock(root) {
@@ -97,8 +141,8 @@ export class InteractiveBridgePool {
         // Fast path: we started/adopted it and its pid is still alive. A full health round-trip on
         // every proxied request would put a 1.5 s timeout budget in front of every asset fetch.
         const cached = this.live.get(root);
-        if (cached && pidAlive(cached.pid))
-            return cached;
+        if (cached && pidAlive(cached.bridge.pid))
+            return cached.bridge;
         this.live.delete(root);
         const pending = this.inflight.get(root);
         if (pending)
@@ -116,14 +160,51 @@ export class InteractiveBridgePool {
         return [...this.live.keys()];
     }
     async resolveOrStart(root) {
-        const adopted = await this.healthy(root);
-        if (adopted) {
-            this.live.set(root, adopted);
-            return adopted;
-        }
-        const started = await this.start(root);
-        this.live.set(root, started);
-        return started;
+        // Adopt-or-start; either way the bridge just answered `/api/health` for this root, which is
+        // exactly the moment #298 wants the studio origin recorded — fire-and-forget, so recording
+        // can never delay (let alone fail) the proxied request that triggered the resolution.
+        const bridge = (await this.healthy(root)) ?? (await this.start(root));
+        const entry = { bridge, originRecorded: false };
+        this.live.set(root, entry);
+        this.recordStudioOrigin(entry);
+        return bridge;
+    }
+    /**
+     * POST the daemon's own origin to the bridge's `/api/studio-origin` (#298), so the bridge's
+     * `GET /` redirects a direct visitor into studio instead of the API-only fallback page.
+     * At most one attempt per pooled bridge per process; 404/405 means the bridge predates the
+     * endpoint (interactive < 0.8.0) and is an expected skip, any other failure is a warn — never
+     * an error, because origin recording must never fail a proxy request.
+     */
+    recordStudioOrigin(entry) {
+        if (entry.originRecorded)
+            return;
+        entry.originRecorded = true;
+        const origin = this.io.studioOrigin?.() ?? null;
+        if (origin === null)
+            return; // no origin to record (pool not bootstrapped from a listening daemon)
+        const { host, port } = entry.bridge;
+        const timeout = this.io.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+        void (async () => {
+            try {
+                const res = await fetch(`http://${host}:${port}/api/studio-origin`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ origin }),
+                    signal: AbortSignal.timeout(timeout),
+                });
+                await res.arrayBuffer().catch(() => undefined); // drain, so the connection is released
+                if (res.status === 404 || res.status === 405) {
+                    this.io.debug?.(`bridge at ${host}:${port} has no /api/studio-origin (interactive < 0.8.0) — skipping origin record`);
+                }
+                else if (!res.ok) {
+                    this.io.log?.(`recording studio origin ${origin} with the bridge at ${host}:${port} failed: HTTP ${res.status}`);
+                }
+            }
+            catch (err) {
+                this.io.log?.(`recording studio origin ${origin} with the bridge at ${host}:${port} failed: ${err.message}`);
+            }
+        })();
     }
     /** The lockfile points at a bridge that is alive, answering, and serving THIS root. */
     async healthy(root) {
@@ -178,7 +259,7 @@ export class InteractiveBridgePool {
 function defaultSpawn(root) {
     // `--yes` is load-bearing: without it npx PROMPTS when the package is not installed, and a
     // daemon has no tty to answer with — the request would hang instead of failing to a 503.
-    return nodeSpawn('npx', ['--yes', 'wicked-interactive', 'serve', '--root', root], {
+    return nodeSpawn('npx', ['--yes', INTERACTIVE_SPEC, 'serve', '--root', root], {
         cwd: root,
         detached: true,
         stdio: 'ignore',