@gobing-ai/spur 0.3.92 → 0.3.94

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.92",
+    "version": "0.3.94",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -45,11 +45,11 @@ const DOCUMENTED = {
         'file.read.into-var',
         'hitl.confirm',
         'hitl.input',
-        'hitl.select',
         'agent.run',
         'proof.fingerprint',
         'run.artifact',
         'command.gate',
+        'decide',
     ]),
     guards: new Set(['always', 'shell', 'action-ok', 'contract-violation']),
 } as const;

package/plugins/sp/scripts/inline-run-setup.mjs

@@ -29,7 +29,10 @@ function usage() {
   console.error("Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]");
   console.error("       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]");
   console.error("       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> " + "--status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]");
-  console.error("       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]");
+  console.error("       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]");
+  console.error("       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--spur-bin <path>]");
+  console.error("       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, " + "failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted");
+  console.error("       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]");
   process.exit(2);
 }
 var SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
@@ -151,6 +154,17 @@ async function printFingerprint(taskFile, featureFile, spurBin) {
   return 0;
 }
 var CLOSE_STATUSES = new Set(["done", "failed", "paused"]);
+var TERMINAL_REASONS = new Set([
+  "done",
+  "paused-operator",
+  "failed-check",
+  "failed-agent",
+  "failed-timeout",
+  "failed-guard",
+  "cancelled",
+  "interrupted",
+  "retry-exhausted"
+]);
 var ACTION_STATUSES = new Set(["done", "failed"]);
 function runRecordLogPath(runDir, runId) {
   const markdownPath = join(runDir, `${runId}.md`);
@@ -159,7 +173,7 @@ function runRecordLogPath(runDir, runId) {
     return legacyLogPath;
   return markdownPath;
 }
-function appendTraceFailureLine(runId, detail) {
+function appendRunLogLine(runId, detail) {
   try {
     const runDir = join(process.cwd(), ".spur", "run");
     if (!existsSync(runDir))
@@ -173,7 +187,7 @@ function appendTraceFailureLine(runId, detail) {
 async function runTraceMode(input) {
   const operation = input.close ? "run.close" : "action.finish";
   const fail = (error) => {
-    appendTraceFailureLine(input.runId, `trace-emission-failed operation=${operation} run=${input.runId}${input.node === "" ? "" : ` node=${input.node}`}${input.kind === "" ? "" : ` kind=${input.kind}`}: ${error}`);
+    appendRunLogLine(input.runId, `trace-emission-failed operation=${operation} run=${input.runId}${input.node === "" ? "" : ` node=${input.node}`}${input.kind === "" ? "" : ` kind=${input.kind}`}: ${error}`);
     process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error })}
 `);
     return input.close ? 1 : 0;
@@ -185,9 +199,9 @@ async function runTraceMode(input) {
     projectDb = await app.openInlineRunProjectDb(process.cwd());
     const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure) => {
       const detail = failure;
-      appendTraceFailureLine(input.runId, `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? "unknown error"}`);
+      appendRunLogLine(input.runId, `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? "unknown error"}`);
     });
-    const result = input.close ? await writer.closeRun(input.runId, input.status) : await writer.recordAction({
+    const result = input.close ? await writer.closeRun(input.runId, input.status, undefined, input.reason) : await writer.recordAction({
       runId: input.runId,
       node: input.node,
       kind: input.kind,
@@ -199,13 +213,20 @@ async function runTraceMode(input) {
       const failure = result.failure;
       return fail(failure.error ?? "unknown trace emission failure");
     }
+    if (input.close && input.status === "done" && result.actionRows === 0) {
+      const error = `run ${input.runId} closed done with zero action_runs rows`;
+      appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${error}`);
+      process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error, code: "NO_ACTION_ROWS", actionRows: 0 })}
+`);
+      return 1;
+    }
     process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}
 `);
     return 0;
   } catch (error) {
     if (input.close && error.name === "RunRowNotFoundError") {
       const message = error instanceof Error ? error.message : String(error);
-      appendTraceFailureLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
+      appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
       process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error: message, code: "RUN_NOT_FOUND" })}
 `);
       return 1;
@@ -215,6 +236,57 @@ async function runTraceMode(input) {
     projectDb?.close();
   }
 }
+async function runDecideMode(input) {
+  const decideFailed = (error) => {
+    process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error })}
+`);
+    return 1;
+  };
+  let outcome;
+  try {
+    const { entry, portable } = resolveAppEntry(input.spurBin);
+    const app = await import(entry);
+    const lib = await import(fileURLToPath(new URL("../lib/inline-run.generated.mjs", import.meta.url)));
+    const enabled = await lib.resolveDecideDecisionMakerEnabled(process.cwd(), portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined);
+    outcome = await app.runDecideForInlineRun({
+      workdir: process.cwd(),
+      optionsFile: input.optionsFile,
+      enabled
+    });
+  } catch (error) {
+    return decideFailed(error instanceof Error ? error.message : String(error));
+  }
+  if (!outcome.ok)
+    return decideFailed(outcome.error ?? "decide failed without an error message");
+  process.stdout.write(`${JSON.stringify({ ok: true, runId: input.runId, node: input.node, ...outcome })}
+`);
+  appendRunLogLine(input.runId, `decide node=${input.node} value=${outcome.value ?? ""} source=${outcome.source ?? "default"} reason=${outcome.reason ?? ""}`);
+  return await runTraceMode({
+    runId: input.runId,
+    close: false,
+    node: input.node,
+    kind: "decide",
+    status: "done",
+    ok: true,
+    durationMs: outcome.durationMs ?? 0,
+    spurBin: input.spurBin
+  });
+}
+async function runPersistOutMode(input) {
+  try {
+    const { entry } = resolveAppEntry(input.spurBin);
+    const app = await import(entry);
+    const result = await app.persistWorktreeRuns({ fromWorkdir: input.from, toWorkdir: process.cwd() });
+    process.stdout.write(`${JSON.stringify({ ok: true, persisted: result.persisted, skipped: result.skipped })}
+`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stdout.write(`${JSON.stringify({ ok: false, error: message })}
+`);
+    return 1;
+  }
+}
 async function main() {
   if (!process.versions.bun) {
     const child = spawnSync("bun", [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
@@ -231,9 +303,14 @@ async function main() {
   let featureFile = "";
   let action = false;
   let close = false;
+  let decide = false;
+  let persistOut = false;
+  let from = "";
+  let optionsJson = "";
   let node = "";
   let kind = "";
   let status = "";
+  let reason = "";
   let okRaw = "";
   let durationRaw = "";
   let spurBin = getEnvVar("SPUR_BIN") ?? "";
@@ -253,12 +330,22 @@ async function main() {
       action = true;
     else if (argv[i] === "--close")
       close = true;
+    else if (argv[i] === "--decide")
+      decide = true;
+    else if (argv[i] === "--persist-out")
+      persistOut = true;
+    else if (argv[i] === "--from")
+      from = argv[++i] ?? "";
+    else if (argv[i] === "--options-json")
+      optionsJson = argv[++i] ?? "";
     else if (argv[i] === "--node")
       node = argv[++i] ?? "";
     else if (argv[i] === "--kind")
       kind = argv[++i] ?? "";
     else if (argv[i] === "--status")
       status = argv[++i] ?? "";
+    else if (argv[i] === "--reason")
+      reason = argv[++i] ?? "";
     else if (argv[i] === "--ok")
       okRaw = argv[++i] ?? "";
     else if (argv[i] === "--duration-ms")
@@ -271,6 +358,22 @@ async function main() {
       usage();
     process.exit(await printFingerprint(taskFile, featureFile, spurBin));
   }
+  if (decide) {
+    if (action || close || fingerprint || file !== "" || taskFile !== "")
+      usage();
+    if (runId.trim() === "" || node.trim() === "" || optionsJson.trim() === "")
+      usage();
+    if (!SAFE_RUN_ID_RE.test(runId))
+      refuseUnsafeRunId(runId);
+    process.exit(await runDecideMode({ runId, node, optionsFile: optionsJson, spurBin }));
+  }
+  if (persistOut) {
+    if (fingerprint || decide || action || close || runId !== "" || file !== "" || taskFile !== "")
+      usage();
+    if (from.trim() === "")
+      usage();
+    process.exit(await runPersistOutMode({ from, spurBin }));
+  }
   if (action || close) {
     if (action && close)
       usage();
@@ -281,6 +384,12 @@ async function main() {
     if (close) {
       if (!CLOSE_STATUSES.has(status))
         usage();
+      if (reason.trim() === "") {
+        if (status === "failed")
+          usage();
+      } else if (!TERMINAL_REASONS.has(reason)) {
+        usage();
+      }
       process.exit(await runTraceMode({
         runId,
         close: true,
@@ -289,7 +398,8 @@ async function main() {
         status,
         ok: true,
         durationMs: 0,
-        spurBin
+        spurBin,
+        ...reason.trim() === "" ? {} : { reason }
       }));
     }
     if (node.trim() === "" || kind.trim() === "")

package/plugins/sp/scripts/inline-run-setup.ts

@@ -31,8 +31,10 @@
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> \
+ *   bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]
  *       --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
- *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--spur-bin <path>]
  *
  * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
  * creates nothing (task 0862 R5).
@@ -44,6 +46,20 @@
  * `.spur/run/<run-id>.md` and the script still exits 0 with `{"ok":false}` on stdout, so
  * observation never wedges the run. `--close` is NOT best-effort: the run-row closure is
  * bookkeeping, so a missing run row or a persistence failure exits 1 with a named error.
+ * The `--decide` mode (task 0941 R5) executes the non-pausing decide action through the SAME
+ * app runner the engine registers (`runDecideForInlineRun`), writing the same resultFile row
+ * and recording the same `action_runs` trace row (`kind=decide`, best-effort). A degraded
+ * decision is still `ok: true` — the run continues — so exit 0 covers every model-level
+ * outcome; only an invalid options schema exits 1 (fail closed).
+ *
+ * The `--persist-out --from <worktree-path>` mode (task 0975 R1) is the WT-4a step a
+ * `--worktree` run executes BEFORE teardown: it copies the worktree's run provenance — the
+ * `runs`/`action_runs`/`phase_runs`/`transition_runs`/`workflow_states` rows and the two-file
+ * run records — into THIS tree's project DB and `.spur/run/` (cwd = the invoking tree).
+ * Idempotent; collisions are reported as `skipped[{id,reason}]`, never overwrites. Exit 0 =
+ * persisted (possibly with skips); exit 1 = fail closed — the driver routes to WT-5 and
+ * retains the worktree; usage errors exit 2.
+ *
  * Exit 2 is reserved for usage errors.
  *
  * Env: SPUR_BIN
@@ -93,7 +109,17 @@ function usage(): never {
             '--status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
     );
     console.error(
-        '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]',
+    );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--spur-bin <path>]',
+    );
+    console.error(
+        '       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, ' +
+            'failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted',
+    );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --decide --run-id <id> --node <state> --options-json <file> [--spur-bin <path>]',
     );
     process.exit(2);
 }
@@ -305,6 +331,24 @@ async function printFingerprint(taskFile: string, featureFile: string, spurBin:
 /** Terminal statuses the inline driver may declare when closing its run row. */
 const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
 
+/**
+ * 0937 R2: closed terminal-reason vocabulary the driver may declare on `--close`.
+ * COPIED from packages/app/src/workflow/terminal-reason.ts — the plugin standalone
+ * contract forbids a value import of app code; the parity test asserts the copy
+ * equals the app export.
+ */
+const TERMINAL_REASONS = new Set([
+    'done',
+    'paused-operator',
+    'failed-check',
+    'failed-agent',
+    'failed-timeout',
+    'failed-guard',
+    'cancelled',
+    'interrupted',
+    'retry-exhausted',
+]);
+
 /** Finalize statuses — a finish emission is terminal, so only done|failed are valid (0868 #4). */
 const ACTION_STATUSES = new Set(['done', 'failed']);
 
@@ -316,6 +360,8 @@ interface TraceModeInput {
     readonly close: boolean;
     readonly node: string;
     readonly kind: string;
+    /** Declared terminal reason (0937 R2) — validated against TERMINAL_REASONS before this point. */
+    readonly reason?: string;
     readonly status: string;
     readonly ok: boolean;
     readonly durationMs: number;
@@ -341,7 +387,7 @@ function runRecordLogPath(runDir: string, runId: string): string {
  * exit immediately after), and never throws: an unwritable log must not wedge the run
  * (ADR-117 R3).
  */
-function appendTraceFailureLine(runId: string, detail: string): void {
+function appendRunLogLine(runId: string, detail: string): void {
     try {
         const runDir = join(process.cwd(), '.spur', 'run');
         if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
@@ -363,7 +409,7 @@ function appendTraceFailureLine(runId: string, detail: string): void {
 async function runTraceMode(input: TraceModeInput): Promise<number> {
     const operation = input.close ? 'run.close' : 'action.finish';
     const fail = (error: string): number => {
-        appendTraceFailureLine(
+        appendRunLogLine(
             input.runId,
             `trace-emission-failed operation=${operation} run=${input.runId}` +
                 `${input.node === '' ? '' : ` node=${input.node}`}${input.kind === '' ? '' : ` kind=${input.kind}`}: ${error}`,
@@ -390,14 +436,14 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
         projectDb = await app.openInlineRunProjectDb(process.cwd());
         const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure: unknown) => {
             const detail = failure as { operation?: string; error?: string };
-            appendTraceFailureLine(
+            appendRunLogLine(
                 input.runId,
                 `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? 'unknown error'}`,
             );
         });
         const result = (
             input.close
-                ? await writer.closeRun(input.runId, input.status)
+                ? await writer.closeRun(input.runId, input.status, undefined, input.reason)
                 : await writer.recordAction({
                       runId: input.runId,
                       node: input.node,
@@ -413,6 +459,18 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
             const failure = result.failure as { error?: string };
             return fail(failure.error ?? 'unknown trace emission failure');
         }
+        if (input.close && input.status === 'done' && result.actionRows === 0) {
+            // A run finalized `done` with ZERO recorded action rows is a bookkeeping defect
+            // (task 0975 R2): the row is already terminal — closeRun ran above — but the
+            // driver must surface this instead of reporting a clean close, and must never
+            // backfill rows. Exit 1 with the named code; the run record carries the finding.
+            const error = `run ${input.runId} closed done with zero action_runs rows`;
+            appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${error}`);
+            process.stdout.write(
+                `${JSON.stringify({ ok: false, runId: input.runId, error, code: 'NO_ACTION_ROWS', actionRows: 0 })}\n`,
+            );
+            return 1;
+        }
         process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}\n`);
         return 0;
     } catch (error) {
@@ -420,7 +478,7 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
             // The run row must exist before --close can mark it terminal (R6); a missing row
             // is a loud correctness failure, not a best-effort emission failure (finding #4).
             const message = error instanceof Error ? error.message : String(error);
-            appendTraceFailureLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
+            appendRunLogLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
             process.stdout.write(
                 `${JSON.stringify({ ok: false, runId: input.runId, error: message, code: 'RUN_NOT_FOUND' })}\n`,
             );
@@ -432,6 +490,116 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
     }
 }
 
+/**
+ * `--decide` mode (task 0941 R5): execute the non-pausing decide action through the same app
+ * function the engine registers (`runDecideForInlineRun` → `DecideActionRunner`), then record
+ * the `action_runs` trace row through the shared writer. The decide-enabled switch
+ * (`workflow.decideDecisionMaker`) is resolved HERE at the driver boundary (ADR-082) through
+ * the bridged facade derivation and passed into the app runner as an explicit parameter —
+ * app services never load Spur config. Degraded outcomes (`disabled`,
+ * `no-backend`, `error`, `timeout`, `low-confidence`) are normal — the value is the declared
+ * default and the run continues — so they print `ok: true` and exit 0. Only an invalid options
+ * schema, an unreadable options file, or a failed config load fails closed with exit 1.
+ */
+async function runDecideMode(input: {
+    runId: string;
+    node: string;
+    optionsFile: string;
+    spurBin: string;
+}): Promise<number> {
+    type DecideOutcome = {
+        ok: boolean;
+        error?: string;
+        value?: string;
+        degraded?: boolean;
+        reason?: string;
+        source?: 'model' | 'default';
+        backend?: string | null;
+        confidence?: number | null;
+        resultFile?: string;
+        durationMs?: number;
+    };
+    const decideFailed = (error: string): number => {
+        process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error })}\n`);
+        return 1;
+    };
+    let outcome: DecideOutcome;
+    try {
+        const { entry, portable } = resolveAppEntry(input.spurBin);
+        const app = (await import(entry)) as {
+            runDecideForInlineRun: (input2: {
+                workdir: string;
+                optionsFile: string;
+                enabled: boolean;
+            }) => Promise<DecideOutcome>;
+        };
+        // Config switch at the driver boundary (ADR-082 / task 0941 gate fix): the flag comes
+        // from the bridged facade derivation in the generated lib — the same committed bundle
+        // the inventory flow imports — never a @gobing-ai/* value import. Embedded schemas
+        // ride along only in the portable layout, mirroring the setup mode's load posture.
+        const lib = (await import(
+            fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url))
+        )) as typeof import('../lib/inline-run.generated.mjs');
+        const enabled = await lib.resolveDecideDecisionMakerEnabled(
+            process.cwd(),
+            portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined,
+        );
+        outcome = await app.runDecideForInlineRun({
+            workdir: process.cwd(),
+            optionsFile: input.optionsFile,
+            enabled,
+        });
+    } catch (error) {
+        return decideFailed(error instanceof Error ? error.message : String(error));
+    }
+    if (!outcome.ok) return decideFailed(outcome.error ?? 'decide failed without an error message');
+    process.stdout.write(`${JSON.stringify({ ok: true, runId: input.runId, node: input.node, ...outcome })}\n`);
+    // 0976 R2: the run log names the decision's provenance, so a declared-default fallback is
+    // never read as a model decision. Best-effort through the same run-log appender.
+    appendRunLogLine(
+        input.runId,
+        `decide node=${input.node} value=${outcome.value ?? ''} source=${outcome.source ?? 'default'} reason=${outcome.reason ?? ''}`,
+    );
+    // Trace row is best-effort, exactly like --action: an emission failure never wedges the run.
+    return await runTraceMode({
+        runId: input.runId,
+        close: false,
+        node: input.node,
+        kind: 'decide',
+        status: 'done',
+        ok: true,
+        durationMs: outcome.durationMs ?? 0,
+        spurBin: input.spurBin,
+    });
+}
+
+/**
+ * `--persist-out --from <worktree-path>` (task 0975 R1): resolve the app through the shared
+ * chain and copy the worktree's inline-run provenance into THIS tree. No persistence policy
+ * lives here — the app's `persistWorktreeRuns` (→ domain `transferRunTables`) owns the DB
+ * transfer, the idempotence and the conflict skips. Success prints
+ * `{ok:true,persisted:<n>,skipped:[…]}` and exits 0; any failure prints `{ok:false,error}`
+ * and exits 1 (the driver routes to WT-5 and retains the worktree).
+ */
+async function runPersistOutMode(input: { from: string; spurBin: string }): Promise<number> {
+    try {
+        const { entry } = resolveAppEntry(input.spurBin);
+        const app = (await import(entry)) as {
+            persistWorktreeRuns: (i: {
+                fromWorkdir: string;
+                toWorkdir: string;
+            }) => Promise<{ ok: true; persisted: number; skipped: ReadonlyArray<{ id: string; reason: string }> }>;
+        };
+        const result = await app.persistWorktreeRuns({ fromWorkdir: input.from, toWorkdir: process.cwd() });
+        process.stdout.write(`${JSON.stringify({ ok: true, persisted: result.persisted, skipped: result.skipped })}\n`);
+        return 0;
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`${JSON.stringify({ ok: false, error: message })}\n`);
+        return 1;
+    }
+}
+
 async function main(): Promise<void> {
     // The portable Node twin has no workspace imports; SQLite still uses Spur's existing Bun runtime.
     if (!process.versions.bun) {
@@ -448,9 +616,14 @@ async function main(): Promise<void> {
     let featureFile = '';
     let action = false;
     let close = false;
+    let decide = false;
+    let persistOut = false;
+    let from = '';
+    let optionsJson = '';
     let node = '';
     let kind = '';
     let status = '';
+    let reason = '';
     let okRaw = '';
     let durationRaw = '';
     let spurBin = getEnvVar('SPUR_BIN') ?? '';
@@ -463,9 +636,14 @@ async function main(): Promise<void> {
         else if (argv[i] === '--feature-file') featureFile = argv[++i] ?? '';
         else if (argv[i] === '--action') action = true;
         else if (argv[i] === '--close') close = true;
+        else if (argv[i] === '--decide') decide = true;
+        else if (argv[i] === '--persist-out') persistOut = true;
+        else if (argv[i] === '--from') from = argv[++i] ?? '';
+        else if (argv[i] === '--options-json') optionsJson = argv[++i] ?? '';
         else if (argv[i] === '--node') node = argv[++i] ?? '';
         else if (argv[i] === '--kind') kind = argv[++i] ?? '';
         else if (argv[i] === '--status') status = argv[++i] ?? '';
+        else if (argv[i] === '--reason') reason = argv[++i] ?? '';
         else if (argv[i] === '--ok') okRaw = argv[++i] ?? '';
         else if (argv[i] === '--duration-ms') durationRaw = argv[++i] ?? '';
         else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
@@ -481,12 +659,37 @@ async function main(): Promise<void> {
     // ADR-117 emission modes (task 0868): the inline driver reports one completed action
     // boundary, or closes its run row at the declared terminal state. Both share the run-id
     // filename guard, the app-entry resolution chain and the best-effort failure contract.
+    // Non-pausing decide action (0941 R5): --decide is mutually exclusive with the run-setup,
+    // fingerprint, and trace modes; it requires the run id (filename-guarded), the state id
+    // for the trace row, and the options JSON file.
+    if (decide) {
+        if (action || close || fingerprint || file !== '' || taskFile !== '') usage();
+        if (runId.trim() === '' || node.trim() === '' || optionsJson.trim() === '') usage();
+        if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
+        process.exit(await runDecideMode({ runId, node, optionsFile: optionsJson, spurBin }));
+    }
+
+    // Worktree provenance persist-out (task 0975 R1): mutually exclusive with every other
+    // mode; requires the source worktree path. Runs with cwd = the invoking tree.
+    if (persistOut) {
+        if (fingerprint || decide || action || close || runId !== '' || file !== '' || taskFile !== '') usage();
+        if (from.trim() === '') usage();
+        process.exit(await runPersistOutMode({ from, spurBin }));
+    }
+
     if (action || close) {
         if (action && close) usage();
         if (runId.trim() === '' || status.trim() === '') usage();
         if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
         if (close) {
             if (!CLOSE_STATUSES.has(status)) usage();
+            // 0937 R2: a failed close requires a declared reason, and any declared reason
+            // must be a closed-enum value — both fail loudly BEFORE any write happens.
+            if (reason.trim() === '') {
+                if (status === 'failed') usage();
+            } else if (!TERMINAL_REASONS.has(reason)) {
+                usage();
+            }
             process.exit(
                 await runTraceMode({
                     runId,
@@ -497,6 +700,7 @@ async function main(): Promise<void> {
                     ok: true,
                     durationMs: 0,
                     spurBin,
+                    ...(reason.trim() === '' ? {} : { reason }),
                 }),
             );
         }