wicked-crew 0.7.8 → 0.7.10

package/dist/api/routes.js

@@ -21,17 +21,20 @@ import { registerProjectRoutes } from '../projects/routes.js';
 import { registerCampaignRoutes } from '../campaigns/routes.js';
 import { registerGovernanceWikiRoutes } from './governance-wiki.js';
 import { DEFAULT_STEERING_TYPE, STEERING_TYPE_VALUES, STEERING_TYPES, registerGovernanceSteeringRoutes, } from './governance-steering.js';
+import { isSteeringAuthorRun, landSteeringProposal } from './steering-landing.js';
 import { registerTestingRoutes } from './testing.js';
 import { ProjectSettingsStore } from '../projects/settings.js';
 import { boundOrigin, InteractiveBridgePool } from '../interactive/bridge-pool.js';
 import { registerInteractiveProxy } from '../interactive/proxy-routes.js';
+import { registerInteractiveDocDelete } from '../interactive/doc-delete-routes.js';
 import { MembershipIndex } from '../projects/membership-index.js';
 import { MEMBERSHIP_ATTACHED, membershipAttachedKey } from '../projects/events.js';
 import { AuditLog } from './audit.js';
 import { AcpFoldCache, EngineVersionCache, eventsDirOf, installedPackageVersion, listStoreFiles, readStudioBundleVersion, } from './diagnostics.js';
 import { RetryIndex } from './retry-index.js';
 import { GuidanceIndex } from './guidance-index.js';
-import { DeliveryIndex } from './delivery-index.js';
+import { DeliveryIndex, deliveryStateWithVacuity, gitRunBranchIsEmpty, gitWorktreeIsClean, prUrlFrom, } from './delivery-index.js';
+import { runDeliverScript } from './post-hoc-deliver.js';
 import { LOCAL_ACTOR } from './auth.js';
 // Re-exported so existing `import { API_PREFIX } from './routes.js'` callers keep working; the
 // value lives in the leaf module api-prefix.ts to keep unit-output.ts out of this file's cycle.
@@ -137,14 +140,18 @@ export const LaunchSchema = z.object({
      *  the launch record. Unknown/archived ⇒ the launch fails (never a silent unfiled run). */
     projectId: z.string().min(1).optional(),
     /** 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.literal('pr').optional(),
+     *  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). crew#393 —
+     *  `"none"` explicitly declines delivery (legal with or without a workflow); OMITTED means the
+     *  daemon decides: repo-scoped + a CODE-WORK workflow (a def with an `executes_code` phase)
+     *  defaults to `"pr"` (flippable via the `deliverDefault` setting), everything else to
+     *  `"none"` — see the resolution below. */
+    deliver: z.enum(['pr', 'none']).optional(),
     /** 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.string().min(1).optional(),
-}).strict().refine((b) => b.deliver === undefined || b.workflow !== undefined, {
+}).strict().refine((b) => b.deliver !== 'pr' || b.workflow !== undefined, {
     message: 'deliver: "pr" requires a workflow — a free-text run has no def to append the deliver phase to',
     path: ['deliver'],
 });
@@ -230,14 +237,30 @@ runtime = {}) {
     const retryIndex = runtime.retryIndex ?? new RetryIndex();
     const guidanceIndex = runtime.guidanceIndex ?? new GuidanceIndex();
     const deliveryIndex = runtime.deliveryIndex ?? new DeliveryIndex();
+    const worktreeExists = runtime.worktreeExists ?? ((p) => existsSync(p));
+    const vacuityProbes = {
+        worktreeExists,
+        worktreeIsClean: runtime.worktreeIsClean ?? gitWorktreeIsClean(),
+        runBranchIsEmpty: runtime.runBranchIsEmpty ??
+            gitRunBranchIsEmpty(async (repoRef) => {
+                const repos = await adapter.listRepos();
+                return repos.find((r) => r.id === repoRef)?.root_path;
+            }),
+    };
+    const deliverExec = runtime.deliverExec ?? runDeliverScript;
     // The run-DTO joins (DES-UX-001 §8.2/§8.3, DES-UX-002 §7.2): `project_id` from the membership
     // record — `null` = genuinely unfiled, so the field is ALWAYS present on served runs —
-    // `retry_of` from the lineage index, `guidance` from the guidance index, and `delivery`
-    // from the delivery index (CREW-UX-8, crew#321), each set only when known (absent, never
-    // null, spells "not a retry" / "no note" / "delivered nothing").
+    // `retry_of` from the lineage index and `guidance` from the guidance index, each set only
+    // when known (absent, never null, spells "not a retry" / "no note"). `delivery` (crew#393,
+    // api-types 0.18.0) is DERIVED on every served run — delivered from the index (CREW-UX-8's
+    // durable record), stranded from the run record + a worktree stat, none otherwise — so a
+    // completed code run whose work is sitting unlifted in its worktree is VISIBLE on the wire,
+    // legacy records included. The would-be-stranded runs are further split (crew#311): a
+    // completed run whose worktree carries NO contribution at all reads `'vacuous'` — units all
+    // "done" with nothing produced must be LOUD on the wire, never silently green.
     // Applied at DTO assembly on exactly the two endpoints that serve the run DTO
     // (GET /runs + GET /runs/:id); the internal sessionsDetail() consumers are untouched.
-    const decorateRun = (view) => {
+    const decorateRun = async (view) => {
         view.session.project_id = projects.index.projectOf(view.session.id) ?? null;
         const retryOf = retryIndex.retryOfFor(view.session.id);
         if (retryOf !== undefined)
@@ -245,9 +268,10 @@ runtime = {}) {
         const guidance = guidanceIndex.guidanceFor(view.session.id);
         if (guidance !== undefined)
             view.session.guidance = guidance;
-        const delivery = deliveryIndex.deliveryFor(view.session.id);
-        if (delivery !== undefined)
-            view.session.delivery = delivery;
+        const state = await deliveryStateWithVacuity(view.session, deliveryIndex.urlFor(view.session.id), vacuityProbes);
+        view.session.delivery = state.delivery;
+        if (state.deliverUrl !== undefined)
+            view.session.deliverUrl = state.deliverUrl;
         return view;
     };
     // Resolved ONCE and shared by the project routes (which read/write `interactiveRoot`) and the
@@ -643,8 +667,44 @@ runtime = {}) {
                 input.projectGraph = decision.binding;
             req.log.info({ runId: input.sessionId, projectId: b.projectId, repoRef: b.repoRef ?? null }, `run ${input.sessionId}: ${decision.reason}`);
         }
-        if (b.deliver !== undefined)
-            input.deliver = b.deliver;
+        // The delivery contract (crew#393): a completed code run must end with a reviewable
+        // deliverable, or an explicit, recorded decision not to. So the deliver option is resolved
+        // HERE, at the boundary, for every launch:
+        //   - explicit 'pr' / 'none' wins (the operator decided);
+        //   - omitted + repo-scoped + a CODE-WORK workflow (the def carries at least one
+        //     `executes_code` phase — feature/bug/migration, not chat/onboarding/recon) ⇒ the
+        //     daemon's `deliverDefault` setting ('pr' unless the operator flipped it) — the default
+        //     that keeps run 83052f0b's work from stranding invisibly again. The code-work guard is
+        //     the issue's own scope ("default deliver:'pr' for CODE-WORK launches"): a read-only
+        //     workflow leaves a clean worktree, and the deliver script FAILS a clean worktree loudly
+        //     ("nothing to deliver", crew#317) — defaulting it on would flip every repo-scoped chat
+        //     from completed to failed;
+        //   - omitted otherwise ⇒ 'none': a repo-less run has no worktree to lift, and a free-text
+        //     run has no def to append the deliver phase to (the adapter REFUSES deliver:'pr'
+        //     without a workflow rather than silently dropping it, so defaulting it on would turn
+        //     a legal launch into a 400).
+        // The adapter input spells 'none' as an omitted field; the audit entry below records the
+        // RESOLVED value either way, plus whether it was defaulted.
+        let deliver;
+        let deliverDefaulted = false;
+        if (b.deliver !== undefined) {
+            deliver = b.deliver;
+        }
+        else if (b.repoRef !== undefined && b.workflow !== undefined) {
+            // Unknown def ⇒ no default (the launch fails at workflow resolution with its own error —
+            // defaulting 'pr' onto it would swap that for a misleading deliver-flavored one).
+            const def = adapter.getWorkflow(b.workflow);
+            const codeWork = def !== null && def.phases.some((p) => p.executes_code === true);
+            deliver =
+                codeWork && (await adapter.getSettings()).deliverDefault !== 'none' ? 'pr' : 'none';
+            deliverDefaulted = true;
+        }
+        else {
+            deliver = 'none';
+            deliverDefaulted = true;
+        }
+        if (deliver === 'pr')
+            input.deliver = 'pr';
         // Retry lineage (DES-UX-001 §8.3): `retryOf` must name an EXISTING run — recording lineage
         // to a run that never existed would be provenance pointing at nothing, so the launch fails
         // loudly (400, before anything is committed) rather than filing a dangling edge.
@@ -667,7 +727,10 @@ runtime = {}) {
                     ...(b.workflow !== undefined ? { workflow: b.workflow } : {}),
                     ...(b.repoRef !== undefined ? { repoRef: b.repoRef } : {}),
                     ...(b.projectId !== undefined ? { projectId: b.projectId } : {}),
-                    ...(b.deliver !== undefined ? { deliver: b.deliver } : {}),
+                    // crew#393: the RESOLVED delivery decision, not just the caller's field — so the
+                    // trail says what the run will actually do, and whether the daemon decided it.
+                    deliver,
+                    ...(deliverDefaulted ? { deliverDefaulted: true } : {}),
                     // CREW-UX-3: the trail is the durable record of lineage — the retry index (and a
                     // restarted daemon's hydrate) reads it back from exactly this entry.
                     ...(b.retryOf !== undefined ? { retryOf: b.retryOf } : {}),
@@ -718,7 +781,7 @@ runtime = {}) {
         const visible = includeArchived
             ? views
             : views.filter((v) => v.session.archived_at == null);
-        return { runs: sortActionableFirst(visible).map(decorateRun) };
+        return { runs: await Promise.all(sortActionableFirst(visible).map(decorateRun)) };
     });
     // ── Run archival (crew#265) — write-off, not delete ────────────────────────
     const ArchiveSchema = z.object({
@@ -778,7 +841,107 @@ runtime = {}) {
         const run = views.find((v) => v.session.id === id);
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
-        return { run: decorateRun(run) };
+        return { run: await decorateRun(run) };
+    });
+    // ── Post-hoc delivery (crew#393) — lift a stranded run's worktree into a PR ──
+    // The recovery path for the run 83052f0b class: a COMPLETED repo-scoped run whose reviewable
+    // work was never lifted (`delivery: 'stranded'` on the wire — including runs recorded long
+    // before this route existed). Runs the SAME hardened script as the deliver phase (#293/#317:
+    // commit, refuse the default branch, rebase — a conflict aborts LOUDLY with nothing pushed —
+    // never force, push, `gh pr create`, success re-derived from a real PR URL) against the run's
+    // existing worktree. Idempotent: a delivered run answers its recorded URL, never a second PR.
+    // Failure is a loud 4xx/5xx carrying the script's own words — never a silent 200.
+    const deliverInFlight = new Set();
+    /** The last words of a failed deliver script — enough to name the refusal, bounded so a full
+     *  git transcript never becomes an error body. */
+    const deliverErrorTail = (output) => {
+        const trimmed = output.trim();
+        return trimmed.length <= 2000 ? trimmed : `…${trimmed.slice(-2000)}`;
+    };
+    app.post(`${V}/runs/:id/deliver`, {
+        config: {
+            manifest: {
+                responseType: 'DeliverRunResult',
+                // 404: unknown run. 409: not completed / repo-less / worktree gone / already in
+                // flight / the script's own loud refusal (conflict, nothing to deliver, gh failure).
+                // 500: exit 0 with no verifiable PR URL, or the spawn itself failed.
+                statusCodes: [200, 404, 409, 500],
+            },
+        },
+    }, async (req, reply) => {
+        const { id } = req.params;
+        // Idempotency first: a recorded delivery answers the SAME URL — `gh pr create` is never
+        // re-run on a delivered run, so a double-click (or a retry after a slow response) cannot
+        // double-open. The index only ever holds real runs, so this needs no store round-trip.
+        const existing = deliveryIndex.urlFor(id);
+        if (existing !== undefined)
+            return { prUrl: existing };
+        const views = await adapter.sessionsDetail();
+        const run = views.find((v) => v.session.id === id);
+        if (!run)
+            return reply.code(404).send({ error: 'Run not found' });
+        const s = run.session;
+        if (s.status !== 'completed') {
+            return reply.code(409).send({
+                error: `run ${id} is ${s.status} — only a completed run can be delivered post-hoc`,
+            });
+        }
+        if (s.repo_ref == null || typeof s.workdir !== 'string' || s.workdir === '') {
+            return reply.code(409).send({
+                error: `run ${id} is not repo-scoped — there is no worktree to lift into a PR`,
+            });
+        }
+        if (!worktreeExists(s.workdir)) {
+            return reply.code(409).send({
+                error: `run ${id}'s worktree is gone (${s.workdir}) — nothing left to deliver`,
+            });
+        }
+        // One delivery per run at a time: the script pushes and opens a PR, so two concurrent
+        // spawns could race gh into two PRs — the exact double-open idempotency forbids.
+        if (deliverInFlight.has(id)) {
+            return reply.code(409).send({
+                error: `a delivery for run ${id} is already in progress — wait for it to finish`,
+            });
+        }
+        deliverInFlight.add(id);
+        let result;
+        try {
+            result = await deliverExec(s.workdir, s.problem);
+        }
+        catch (err) {
+            return reply.code(500).send({ error: `deliver script could not run: ${message(err)}` });
+        }
+        finally {
+            deliverInFlight.delete(id);
+        }
+        if (result.spawnFailure === true) {
+            // The script never reached its own verdict (spawn failure, timeout kill) — an infra
+            // fault, not a refusal: 500 so the caller knows a retry is reasonable.
+            return reply.code(500).send({
+                error: `deliver script could not run to completion: ${deliverErrorTail(result.output)}`,
+            });
+        }
+        if (result.status !== 0) {
+            // The script's own words (crew#317's rule: never silent, never masked) — it names
+            // exactly what it refused (rebase conflict, nothing to deliver, gh's error) and
+            // guarantees nothing was pushed on the refusing paths.
+            return reply.code(409).send({
+                error: `deliver failed (exit ${result.status}): ${deliverErrorTail(result.output)}`,
+            });
+        }
+        const url = prUrlFrom(result.output);
+        if (url === null) {
+            // Exit 0 with no URL should be unreachable (the script re-derives its own success),
+            // but a delivery nothing can be pointed at is never recorded (crew#317).
+            return reply.code(500).send({
+                error: 'deliver script exited 0 but produced no PR URL — refusing to record a delivery nothing can be pointed at',
+            });
+        }
+        // The durable record first, then the read-side index — the same write order as the
+        // deliver-phase resolution in server.ts, so the index can only LAG a crash, never lead it.
+        audit.record('run.delivered', actorOf(req), { runId: id, detail: { url, via: 'post-hoc' } });
+        deliveryIndex.set(id, url);
+        return { prUrl: url };
     });
     // Durable pre-gate guidance (DES-UX-002 §7.2 — spec'd there as CREW-UX-4, implemented as
     // CREW-UX-7 because crew#308 already spent that id; see guidance-index.ts). Upserts the ONE
@@ -1042,7 +1205,7 @@ runtime = {}) {
         config: {
             manifest: {
                 requestType: 'GateDecision',
-                responseType: '{ status: SessionStatus }',
+                responseType: '{ status: SessionStatus; landing?: SteeringLandingResult }',
                 // 409 twice over: a run not awaiting a human gate, and an engine refusal at confirm.
                 statusCodes: [200, 400, 404, 409],
             },
@@ -1062,6 +1225,15 @@ runtime = {}) {
                 .code(409)
                 .send({ error: `Run is not awaiting a human gate (status: ${run.session.status})` });
         }
+        // The steering-author landing (crew#388): decided — and the gate prompt captured — BEFORE
+        // the confirm, because a terminal-phase approve prunes the gate cache and moves the run out
+        // of `awaiting_human`. The landing itself runs AFTER a successful approve only.
+        // (`listWorkflows` is presence-guarded for partial-stub adapters — a registry-less adapter
+        // cannot be hosting a steering-author run, and the legacy gate path must not 500 over it.)
+        const steeringPropose = parsed.data.approve &&
+            typeof adapter.listWorkflows === 'function' &&
+            isSteeringAuthorRun(run, adapter.listWorkflows());
+        const gatePrompt = steeringPropose ? gateCache.get(id)?.prompt : undefined;
         try {
             const status = await adapter.confirmGate(id, parsed.data.approve, parsed.data.amend);
             // WHO approved/rejected — the gate-decision audit (task #88). The engine
@@ -1075,7 +1247,18 @@ runtime = {}) {
                     status,
                 },
             });
-            return reply.send({ status });
+            // APPROVE of the steering-author propose gate = the doctrine's landing moment: the
+            // approved proposal is written to the governance store with `provenance.source: "chat"`,
+            // audited per rule, idempotent on replay, and LOUD on failure — the response carries the
+            // outcome either way, so the studio can show "landed PAT-101" or the explicit error
+            // instead of the silent no-op crew#388 recorded. An approve WITH an amend note still
+            // lands the proposal UNCHANGED: the amend steers the RUN's continuation, not the rule
+            // text (an operator who wants different rules rejects and re-authors). A reject lands
+            // nothing — the run cancels and the proposal stays an artifact.
+            const landing = steeringPropose
+                ? await landSteeringProposal({ adapter, audit, actor: actorOf(req) }, run, gatePrompt)
+                : undefined;
+            return reply.send({ status, ...(landing !== undefined ? { landing } : {}) });
         }
         catch (err) {
             return reply.code(409).send({ error: message(err) });
@@ -1105,8 +1288,37 @@ runtime = {}) {
         const run = views.find((v) => v.session.id === id);
         if (!run)
             return reply.code(404).send({ error: 'Run not found' });
+        // A TERMINAL run is refused LOUDLY, with the actual recovery named (crew#311 defect 2).
+        // The engine's `resume_run` no-ops on completed/cancelled and answers the status token, so
+        // this route used to reply 200 {"status":"cancelled"} — on the exact runs an operator was
+        // trying to rescue, the recovery affordance read as "resume destroyed my run". A cancelled
+        // run has NO in-run recovery (the path is a retry launch, `POST /runs {retryOf}`); a
+        // completed run has nothing to resume — but a stranded one's work IS liftable post-hoc.
+        // The 409 body carries the machine-readable pointer (`ResumeRefusal` in api-types).
+        const terminal = run.session.status;
+        if (terminal === 'completed' || terminal === 'cancelled') {
+            const state = await deliveryStateWithVacuity(run.session, deliveryIndex.urlFor(id), vacuityProbes);
+            const recovery = terminal === 'completed' && state.delivery === 'stranded'
+                ? 'deliver'
+                : 'retry';
+            const why = terminal === 'cancelled'
+                ? `run ${id} is cancelled — a terminal run cannot be resumed; relaunch the work as a new run with POST /runs {"retryOf":"${id}"}`
+                : state.delivery === 'stranded'
+                    ? `run ${id} is already completed — nothing to resume; its unlifted work is in the worktree: deliver it with POST /runs/${id}/deliver`
+                    : state.delivery === 'vacuous'
+                        ? `run ${id} is already completed, but VACUOUSLY — its units produced no work to resume or deliver; relaunch with POST /runs {"retryOf":"${id}"}`
+                        : `run ${id} is already completed — nothing to resume; relaunch the work as a new run with POST /runs {"retryOf":"${id}"}`;
+            return reply.code(409).send({ error: why, recovery });
+        }
         try {
             const gated = run.session.status === 'awaiting_human';
+            // A gated resume IS a gate approval, so it lands a steering-author proposal exactly like
+            // POST /runs/:id/gate would — the "no side door" rule (task #88) holds for the landing
+            // write too (crew#388). Prompt captured pre-confirm; see the gate route.
+            const steeringPropose = gated &&
+                typeof adapter.listWorkflows === 'function' &&
+                isSteeringAuthorRun(run, adapter.listWorkflows());
+            const gatePrompt = steeringPropose ? gateCache.get(id)?.prompt : undefined;
             const status = gated ? await adapter.confirmGate(id, true) : await adapter.resumeRun(id);
             // A resume of a gated run IS a gate approval — audit it as one, so the
             // "who approved" trail has no side door (task #88).
@@ -1114,7 +1326,10 @@ runtime = {}) {
                 runId: id,
                 detail: gated ? { approve: true, via: 'resume', status } : { status },
             });
-            return reply.send({ status });
+            const landing = steeringPropose
+                ? await landSteeringProposal({ adapter, audit, actor: actorOf(req) }, run, gatePrompt)
+                : undefined;
+            return reply.send({ status, ...(landing !== undefined ? { landing } : {}) });
         }
         catch (err) {
             return reply.code(409).send({ error: message(err) });
@@ -1225,11 +1440,13 @@ runtime = {}) {
         if (!ids.includes(id))
             return reply.code(404).send({ error: 'Run not found' });
         // Durable probe (DES-PROJECT-001 §5.3): `interaction_requests` reserves kind `elicitation`.
-        // The engine writes no elicitation rows yet (its elicitation surface is future work — the
-        // resolve path still answers 501), so this read is empty today; it exists so the cache is
-        // STRUCTURALLY a latency layer, and the day the engine writes the rows, restart survival
-        // holds here exactly as it does for gates, with no route change. Guarded like `runEvents`:
-        // a partial-stub adapter (tests) or a pre-0.6.0 addon simply has no durable half.
+        // The engine writes no elicitation rows yet — the LIVE elicitation wire is complete
+        // (create → cache → resolve, crew#357/#358), but the durable half of the PROMPT is still
+        // engine-side future work (wicked-core interaction.rs: "gate today; elicitation reserved") —
+        // so this read is empty today; it exists so the cache is STRUCTURALLY a latency layer, and
+        // the day the engine writes the rows, restart survival holds here exactly as it does for
+        // gates, with no route change. Guarded like `runEvents`: a partial-stub adapter (tests) or
+        // a pre-0.6.0 addon simply has no durable half.
         const durable = typeof adapter.interactionRequests === 'function'
             ? await adapter.interactionRequests(id, 'open')
             : null;
@@ -2048,6 +2265,45 @@ runtime = {}) {
                     .send({ error: 'workerStallMinutes must be an integer between 1 and 1440' });
             }
         }
+        // The escalation ladder's knobs (crew#341). This trio lets the PLATFORM touch runs, so a
+        // typo must be a 400, never a silently-dropped key that leaves the operator believing they
+        // armed (or disarmed) automatic recovery. `workerStallEscalateMinutes: 0` is the explicit
+        // OFF spelling — and the shipped default is off (absent).
+        if (Object.hasOwn(patch, 'workerStallEscalateMinutes')) {
+            const mins = patch.workerStallEscalateMinutes;
+            if (typeof mins !== 'number' || !Number.isInteger(mins) || mins < 0 || mins > 1440) {
+                return reply.code(400).send({
+                    error: 'workerStallEscalateMinutes must be an integer between 0 (escalation off) and 1440',
+                });
+            }
+        }
+        if (Object.hasOwn(patch, 'workerStallEscalateAction')) {
+            const a = patch.workerStallEscalateAction;
+            if (a !== 'reassign' && a !== 'notify') {
+                return reply
+                    .code(400)
+                    .send({ error: "workerStallEscalateAction must be 'reassign' or 'notify'" });
+            }
+        }
+        if (Object.hasOwn(patch, 'workerStallMaxEscalations')) {
+            const n = patch.workerStallMaxEscalations;
+            if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > 10) {
+                return reply
+                    .code(400)
+                    .send({ error: 'workerStallMaxEscalations must be an integer between 1 and 10' });
+            }
+        }
+        // deliverDefault (crew#393): the repo-scoped launch delivery default. Two values only —
+        // this knob decides whether completed code runs open PRs, so a typo must be a 400, never
+        // a silently-dropped key that leaves the operator believing they flipped it.
+        if (Object.hasOwn(patch, 'deliverDefault')) {
+            const d = patch.deliverDefault;
+            if (d !== 'pr' && d !== 'none') {
+                return reply
+                    .code(400)
+                    .send({ error: "deliverDefault must be 'pr' or 'none'" });
+            }
+        }
         // Skin-owned keys (crew#323): allowed through, but VALIDATED rather than trusted. The
         // daemon does not read these values, so the only two things it can check are the two that
         // can hurt it — a value it cannot persist, and a value big enough to bloat settings.json.
@@ -2084,6 +2340,10 @@ runtime = {}) {
             'graphNodeLimit',
             'worker_config_root',
             'workerStallMinutes',
+            'workerStallEscalateMinutes',
+            'workerStallEscalateAction',
+            'workerStallMaxEscalations',
+            'deliverDefault',
         ];
         const safe = {};
         for (const key of allowed) {
@@ -2153,18 +2413,37 @@ runtime = {}) {
     // ── The wicked-interactive bridge, reverse-proxied (DES-MERGE-001 §5.3/§7.2) ──
     // Mounted BESIDE the routes above and under the same `${V}` prefix, so it inherits one
     // origin, one auth hook, and one CORS posture — the whole point of slice 1.
+    // ONE pool, shared with the governed doc-delete route below: two pools over one root would
+    // race each other into starting duplicate bridges.
+    const interactiveBridges = runtime.interactiveBridges ??
+        new InteractiveBridgePool({
+            log: (m) => app.log.warn(m),
+            debug: (m) => app.log.debug(m),
+            // #298: the daemon's own origin, read LAZILY off the bound server — the pool is built
+            // before `listen`, but only consulted while serving a request, i.e. once bound. The
+            // pool POSTs it to the bridge's /api/studio-origin on start/adopt so the bridge's
+            // `GET /` redirects into studio.
+            studioOrigin: () => boundOrigin(app.server.address()),
+        });
     registerInteractiveProxy(app, adapter, {
         settings: projectSettings,
-        pool: runtime.interactiveBridges ??
-            new InteractiveBridgePool({
-                log: (m) => app.log.warn(m),
-                debug: (m) => app.log.debug(m),
-                // #298: the daemon's own origin, read LAZILY off the bound server — the pool is built
-                // before `listen`, but only consulted while serving a request, i.e. once bound. The
-                // pool POSTs it to the bridge's /api/studio-origin on start/adopt so the bridge's
-                // `GET /` redirects into studio.
-                studioOrigin: () => boundOrigin(app.server.address()),
-            }),
+        pool: interactiveBridges,
+        log: (m) => app.log.warn(m),
+    });
+    // ── Governed doc delete (crew#338) — the one door that changes BOTH stores ──
+    // `DELETE /projects/:id/interactive/docs/:doc` retires the doc on the bridge AND drops crew's
+    // handoff-ledger rows for it (the draft leg keys by document id, so a stale row claims the
+    // name forever — studio#119's ghost). One static segment more specific than the proxy's
+    // wildcard, so the proxy stays pure transport for everything else.
+    registerInteractiveDocDelete(app, adapter, {
+        settings: projectSettings,
+        pool: interactiveBridges,
+        audit,
+        actorOf,
+        // The inert default mirrors AuditLog.noop(): a directly-driven route set must never sweep
+        // the operator's real ~/.wicked-crew ledgers. The real sweep always arrives from
+        // `createServer`.
+        dropDocLedgerRows: runtime.dropDocLedgerRows ?? (() => ({ ok: true, removed_keys: [] })),
         log: (m) => app.log.warn(m),
     });
 }