@deksden-com/dd-flow-cli 0.9.0-beta.54 → 0.9.0-beta.56

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.56
+
+### Patch Changes
+
+- Keep RUN database and runtime status aligned with pause, stop, controller failures and trusted recovery. Preserve real Stage pauses and terminal results, reject late revival under a recovery fence, roll back status changes after persistence failures, and provide an explicit backed-up legacy status repair tool.
+
+## 0.9.0-beta.55
+
+### Patch Changes
+
+- Require autonomous check evidence, preflight commands in their actual workspace, bind final retry arguments, and settle ZCode cancellation through verified native residency. Retain closed sessions without implicit resume and store growing transcripts in reusable content-addressed chunks.
+
 ## 0.9.0-beta.54
 
 ### Patch Changes

package/README.md

@@ -452,3 +452,25 @@ pnpm build
 ```
 
 Manual smoke checks should use a temporary `DD_FLOW_HOME` when they do not intentionally inspect the operator's real local state.
+
+### RUN status during recovery
+
+A controller failure pauses the logical RUN without rewriting its Stage/Work
+outcomes. Accepted pause/stop or recovery intent immediately persists `paused` in the RUN row,
+`index_json`, and `run.json`. A trusted recovery acknowledgement restores the
+operational status; an existing Stage/Work pause remains paused. Terminal RUNs
+are never reopened. Physical tree settlement remains a separate control receipt.
+
+Legacy stores with a fenced recovery may still contain `running`. After building,
+inspect one exact RUN with:
+
+```sh
+node tools/repair-paused-run-status.mjs --home /path/to/dd-flow-home --project PRJ-001-project --run RUN-001-eval-subject
+```
+
+Add `--apply` to repair it. This requires the latest recovery to be draining, sealed or resuming, saves the original row and runtime JSON
+beside `run.json`, and changes no schema, engine binding or recovery capture.
+It does not claim physical settlement or alter its receipts. `--cancel-abandoned`
+explicitly cancels an abandoned fixture only when the project directory is absent
+and it has no Work, Session, controller or recovery history. Historical experiment
+engine snapshots remain pinned; rebuild/release the engine for future executions.

package/dist/build-info.json

@@ -1,11 +1,11 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.54",
-  "cli_commit": "eb2cb9746a9ee386d40f63791f5dbe0847bf5017",
-  "built_at": "2026-09-13T12:29:37.211Z",
+  "cli_version": "0.9.0-beta.56",
+  "cli_commit": "ae4bbaa5b2299aeedf3ee90bccc8ed3db19a6191",
+  "built_at": "2026-09-13T21:08:32.108Z",
   "built_with_canon": {
-    "version": "4.1.0",
-    "commit": "ef349bf47cba1c987468e51d73a0dbadbd48dc1f",
+    "version": "4.1.1",
+    "commit": "97f811d33c212ae3497020178b1ed825c7c3ebac",
     "flow_contract": "dd-flow-canonical-2026-08",
     "repo_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank",
     "memorybank_root": "/home/runner/work/dd-flow-cli/dd-flow-cli/dd-memorybank/.memory-bank",

package/dist/harness-runtime/lib/dd-zcode-daemon.mjs

@@ -245,6 +245,7 @@ export class DaemonRuntime {
       root_provider_session_id: existing?.root_provider_session_id ?? (parent ? parentRoot : result.provider_session_id),
       topology: topology ?? existing?.topology ?? null,
       completed_turns: existing?.completed_turns ?? 0,
+      close_receipt: result.close?.closed === true ? result : existing?.close_receipt ?? null,
     }); }
     if (result?.adapter_session_id) this.liveAdapters.add(result.adapter_session_id);
     for (const child of topology?.running ?? []) {
@@ -254,6 +255,8 @@ export class DaemonRuntime {
   }
 
   treeRunning(result) {
+    const closed = this.sessions.get(result?.provider_session_id)?.close_receipt;
+    if (closed) return closed.settled !== true;
     const evidence = result?.evidence ?? result;
     const children = evidence?.subagents?.running;
     return evidence?.read?.projection?.status !== "idle" || !Array.isArray(children) || children.length > 0 || Boolean(evidence?.subagents?.observation_error);
@@ -277,6 +280,7 @@ export class DaemonRuntime {
   }
 
   async requireSettled(params) {
+    if (this.sessions.get(params.sessionId)?.close_receipt) throw new DaemonError("session_closed", "Closed Session requires explicit recovery");
     const known = this.sessions.get(params.sessionId);
     // A freshly created ZCode Session has no prior Turn and is not yet exposed
     // by the provider's subagent index. Its first prompt is therefore safe.
@@ -307,12 +311,18 @@ export class DaemonRuntime {
     }
     if (operation === "session.create") return await this.productive(operation, async () => await createSessionWithBridge(this.bridge, this.options(params), this.initialized));
     if (operation === "session.prompt") {
+      if (this.sessions.get(params.sessionId)?.close_receipt) throw new DaemonError("session_closed", "Closed Session requires explicit recovery before another prompt");
       const result = await this.productive(operation, async () => { await this.requireSettled(params); return await promptSessionWithBridge(this.bridge, this.options(params)); });
       const session = this.sessions.get(result.provider_session_id); if (session) session.completed_turns = (session.completed_turns ?? 0) + 1;
       await this.persist(); return result;
     }
     if (operation === "session.fork") return await this.productive(operation, async () => { await this.requireSettled(params); return await forkSessionWithBridge(this.bridge, this.options(params)); });
     if (operation === "session.inspect" || operation === "session.resume") {
+      const closed = this.sessions.get(params.sessionId)?.close_receipt;
+      if (closed) {
+        if (operation === "session.resume") throw new DaemonError("session_closed", "Closed Session requires explicit recovery");
+        return { ...closed, read: { projection: { status: "stopped" } }, subagents: closed.after, settled: closed.settled === true };
+      }
       const adapter = params.adapterSessionId ?? params.sessionId;
       if (!this.liveAdapters.has(adapter) && this.activeProductive) {
         throw new DaemonError(
@@ -334,10 +344,12 @@ export class DaemonRuntime {
     }
     if (operation === "session.cancel") {
       if (!this.sessions.has(params.sessionId)) throw new DaemonError("session_identity_mismatch", "cancellation Session is not owned by this daemon");
+      const closed = this.sessions.get(params.sessionId)?.close_receipt;
+      if (closed) return closed;
       this.controlGeneration = (this.controlGeneration ?? 0) + 1;
       const result = await cancelSessionWithBridge(this.bridge, this.options(params));
       this.track(result, result.after);
-      await this.persist({ active_tree: this.treeRunning(result) || Boolean(this.activeProductive) });
+      await this.persist({ active_tree: result.settled !== true && (this.treeRunning(result) || Boolean(this.activeProductive)) });
       return result;
     }
     if (operation === "session.cancel-child") {
@@ -354,6 +366,10 @@ export class DaemonRuntime {
     if (cancel) this.controlGeneration = (this.controlGeneration ?? 0) + 1;
     const unsettled = [];
     for (const session of this.sessions.values()) {
+      if (session.close_receipt) {
+        if (!session.close_receipt.settled) unsettled.push(session.provider_session_id);
+        continue;
+      }
       const options = this.options({ sessionId: session.provider_session_id, adapterSessionId: session.adapter_session_id });
       let observed;
       if (!cancel) observed = await inspectSessionWithBridge(this.bridge, options);
@@ -363,11 +379,21 @@ export class DaemonRuntime {
           let cancelled;
           try { cancelled = await cancelSessionWithBridge(this.bridge, options); }
           catch (error) { unsettled.push(session.provider_session_id); continue; }
-          // Cancellation acceptance is not settlement.  Re-read the same
-          // controlled tree before letting the daemon close its endpoint.
-          try { observed = await inspectSessionWithBridge(this.bridge, options); }
-          catch (error) { unsettled.push(session.provider_session_id); continue; }
-          if (!cancelled.settled || this.treeRunning(observed)) unsettled.push(session.provider_session_id);
+          this.track(cancelled, cancelled.after);
+          await this.persist({ active_tree: cancelled.settled !== true });
+          if (cancelled.close?.closed === true) {
+            if (!cancelled.settled) unsettled.push(session.provider_session_id);
+            continue;
+          }
+          // A cooperative cancel needs a final read. A close receipt is
+          // terminal itself: native session/read correctly rejects it as no
+          // longer resident, so treating that rejection as unsettled would
+          // turn a successful close into an immortal daemon.
+          if (!cancelled.settled) {
+            try { observed = await inspectSessionWithBridge(this.bridge, options); }
+            catch (error) { unsettled.push(session.provider_session_id); continue; }
+            if (this.treeRunning(observed)) unsettled.push(session.provider_session_id);
+          }
         }
       }
     }

package/dist/harness-runtime/lib/dd-zcode.mjs

@@ -2,7 +2,7 @@ import { observedTimeout } from "./observation-clock.mjs";
 import { invokeNativeHook } from "./native-hook-command.mjs";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline";
 import { stopProcessGroup } from "./managed-daemon.mjs";
@@ -53,6 +53,7 @@ class Journal {
     this.file = file ? absolute(file, "--journal") : null;
     this.pending = this.file ? mkdir(path.dirname(this.file), { recursive: true }) : Promise.resolve();
     this.order = 0;
+    this.artifacts = new Set();
   }
   write(kind, payload) {
     if (!this.file) return;
@@ -60,9 +61,69 @@ class Journal {
     this.pending = this.pending.then(() => appendFile(this.file, `${line}\n`));
     return this.pending;
   }
+  writeInbound(payload, method) {
+    if (!this.file || method !== "zcode/session/read" || !payload?.result || typeof payload.result !== "object") return this.write("inbound", payload);
+    const raw = JSON.stringify(payload.result);
+    const sha256 = createHash("sha256").update(raw).digest("hex");
+    const artifactDir = `${this.file}.artifacts`, artifact = path.join(artifactDir, `${sha256}.json`);
+    const blobs = new Map();
+    const messages = Array.isArray(payload.result.messages) ? payload.result.messages.map(message => {
+      const bytes = Buffer.from(JSON.stringify(message));
+      const chunks = [];
+      for (let offset = 0; offset < bytes.length; offset += 65536) {
+        const chunk = bytes.subarray(offset, offset + 65536);
+        const hash = createHash("sha256").update(chunk).digest("hex");
+        const file = path.join(artifactDir, `${hash}.chunk`);
+        blobs.set(file, chunk); chunks.push({ path: path.basename(file), sha256: hash, bytes: chunk.length });
+      }
+      return { chunks };
+    }) : null;
+    const manifest = JSON.stringify({ encoding: "dd-zcode/session-read@1", result: { ...payload.result, ...(messages ? { messages } : {}) } });
+    const result = { ...payload.result };
+    if (Array.isArray(result.messages)) result.messages = { omitted_count: result.messages.length };
+    const compact = { ...payload, result, raw_result: { sha256, bytes: Buffer.byteLength(raw), path: artifact, encoding: "dd-zcode/session-read@1" } };
+    const line = JSON.stringify({ order: ++this.order, observed_at: now(), kind: "inbound", payload: compact });
+    this.pending = this.pending.then(async () => {
+      await mkdir(artifactDir, { recursive: true });
+      for (const [file, bytes] of [...blobs, [artifact, manifest]]) {
+        if (this.artifacts.has(file)) continue;
+        try { await writeFile(file, bytes, { flag: "wx" }); }
+        catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+          if (!Buffer.from(await readFile(file)).equals(Buffer.from(bytes))) throw new Error(`Journal artifact conflict: ${file}`);
+        }
+        this.artifacts.add(file);
+      }
+      await appendFile(this.file, `${line}\n`);
+    });
+    return this.pending;
+  }
   async flush() { await this.pending; }
 }
 
+/** Reconstruct a retained read, verifying every chunk and the original result. */
+export async function readSessionJournalArtifact(reference) {
+  const stored = JSON.parse(await readFile(reference.path, "utf8"));
+  const result = reference.encoding === "dd-zcode/session-read@1" ? stored.result : stored;
+  if (reference.encoding === "dd-zcode/session-read@1" && Array.isArray(result.messages)) {
+    const messages = [];
+    for (const message of result.messages) {
+      const parts = [];
+      for (const chunk of message.chunks) {
+        if (chunk.path !== `${chunk.sha256}.chunk` || !/^[a-f0-9]{64}$/.test(chunk.sha256)) throw new Error("Invalid journal chunk reference");
+        const bytes = await readFile(path.join(path.dirname(reference.path), chunk.path));
+        if (bytes.length !== chunk.bytes || createHash("sha256").update(bytes).digest("hex") !== chunk.sha256) throw new Error("Journal chunk integrity mismatch");
+        parts.push(bytes);
+      }
+      messages.push(JSON.parse(Buffer.concat(parts).toString("utf8")));
+    }
+    result.messages = messages;
+  }
+  const raw = JSON.stringify(result);
+  if (Buffer.byteLength(raw) !== reference.bytes || createHash("sha256").update(raw).digest("hex") !== reference.sha256) throw new Error("Journal result integrity mismatch");
+  return result;
+}
+
 export class AcpBridge {
   constructor(options) {
     this.options = options;
@@ -118,7 +179,8 @@ export class AcpBridge {
   receive(line) {
     let message;
     try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
-    this.journal.write("inbound", message);
+    const request = message.id !== undefined ? this.pending.get(message.id) : null;
+    this.journal.writeInbound(message, request?.method);
     if (typeof message.params?.sessionId === "string" && isProductiveSessionNotification(message)) this.sessionActivity.set(message.params.sessionId, Date.now());
     const update = message.params?.update;
     // ZCode emits this as `session/update`; Grok Build wraps the same ACP
@@ -154,7 +216,7 @@ export class AcpBridge {
     }
     if (message.id !== undefined && message.method) { void this.answer(message).catch((error) => this.rejectAll(error)); return; }
     if (message.id !== undefined) {
-      const pending = this.pending.get(message.id);
+      const pending = request ?? this.pending.get(message.id);
       if (!pending) return;
       clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); this.pending.delete(message.id);
       if (message.error) {
@@ -367,7 +429,7 @@ export function latestAssistantText(read) {
   return null;
 }
 
-async function cancelTree(bridge, sessionId, before) {
+async function cancelTree(bridge, sessionId, before, providerSessionId) {
   const cancellations = [];
   for (const child of before.running ?? []) {
     const taskId = child.taskId ?? child.agentId;
@@ -376,20 +438,41 @@ async function cancelTree(bridge, sessionId, before) {
       catch (error) { cancellations.push({ taskId, cancelled: false, error: { code: error.code ?? "cancel_failed", message: error.message } }); }
     }
   }
-  // ZCode's stop is deliberately idempotent.  Send it once: session/read
-  // returns the full transcript, so polling it while the turn is stopping can
-  // make cancellation slower than the work we are trying to interrupt.
+  // ZCode's stop is deliberately idempotent. A stop acknowledgement is not a
+  // terminal receipt: native turns (and a root without children) can remain
+  // active after it. Observe a bounded drain, then close this owned Session.
   bridge.notify("session/cancel", { sessionId });
-  let after = before;
-  for (let attempt = 0; attempt < 6; attempt += 1) {
+  let after = before, read = null, root_status = null;
+  const deadline = Date.now() + 6000;
+  for (let attempt = 0; attempt < 6 && Date.now() < deadline; attempt += 1) {
     await new Promise((resolve) => setTimeout(resolve, 1000));
-    after = await bridge.request("zcode/session/subagents", { sessionId }).catch(error => ({ observation_error: { code: error.code, message: error.message } }));
-    if (after.observation_error || !(after.running ?? []).length) break;
+    const timeout = Math.max(1, deadline - Date.now());
+    [after, read] = await Promise.all([
+      bridge.request("zcode/session/subagents", { sessionId }, timeout).catch(error => ({ observation_error: { code: error.code, message: error.message } })),
+      bridge.request("zcode/session/read", { sessionId }, timeout).catch(error => ({ observation_error: { code: error.code, message: error.message } })),
+    ]);
+    root_status = read?.projection?.status ?? read?.session?.status ?? null;
+    if (after.observation_error || read?.observation_error) break;
+    if (Array.isArray(after.running) && !after.running.length && !(read?.projection?.activeToolCalls ?? []).length && ["idle", "completed", "cancelled", "failed", "stopped"].includes(root_status)) {
+      return { cancellations, before, after, root_status, cancellation_requested: false, settled: true, close_requested: false };
+    }
   }
-  const read = await bridge.request("zcode/session/read", { sessionId }).catch(error => ({ observation_error: { code: error.code, message: error.message } }));
-  const root_status = read?.projection?.status ?? read?.session?.status ?? null;
-  const settled = !after.observation_error && !(after.running ?? []).length && ["idle", "completed", "cancelled", "failed", "stopped"].includes(root_status);
-  return { cancellations, before, after, root_status, cancellation_requested: !settled, settled };
+  let close = null;
+  try { close = await bridge.request("zcode/session/close", { sessionId }); }
+  catch (error) { close = { closed: false, error: { code: error.code ?? "close_failed", message: error.message } }; }
+  const knownChildren = [...new Set([...(before.running ?? []), ...(after.running ?? [])].map(child => child.childSessionId).filter(Boolean))];
+  const residents = close?.closed === true ? await Promise.all([providerSessionId, ...knownChildren].map(async id => {
+    try {
+      const observed = await bridge.request("zcode/session/resident", { sessionId: id }, 5000);
+      if (observed.sessionId !== id) throw Object.assign(new Error("Residency evidence belongs to another Session"), { code: "session_identity_mismatch" });
+      return observed;
+    }
+    catch (error) { return { sessionId: id, observation_error: { code: error.code, message: error.message } }; }
+  })) : [];
+  const completeTopology = !before.observation_error && Array.isArray(before.running) && !after.observation_error && Array.isArray(after.running)
+    && [...(before.running ?? []), ...after.running].every(child => typeof child.childSessionId === "string");
+  return { cancellations, before, after, root_status, cancellation_requested: true, close_requested: true, close, residents,
+    settled: close?.closed === true && completeTopology && residents.length > 0 && residents.every(item => item.resident === false) };
 }
 
 // Cancel one known child without cancelling its parent turn.  The parent keeps
@@ -560,7 +643,7 @@ export function zcodeLifecycleQualification(sha256, bridgeCommit, harnessContrac
   // Behavioural evidence: dd-eval production-invocations probe, 2026-09-13.
   // Pin both providers of native event identity, not a string in the bundle.
   const qualified = sha256 === "e9f1868c0fdb863537ed910ee3828b9be96b8c2fd805473f63b439e1113266b8"
-    && bridgeCommit === "43f654bccdbb1aa4f4fb4617f7315c4336dbcde0" && harnessContract === ZCODE_HARNESS_CONTRACT;
+    && bridgeCommit === "e0600fe3c46e215695f257e65aa6f674ced998d8" && harnessContract === ZCODE_HARNESS_CONTRACT;
   return { status: qualified ? "qualified" : "unqualified", mechanism: "cli-invocation@1", sha256,
     capabilities: qualified ? ["root", "concurrent_children", "child_continuation"] : [],
     native_nested_children: false, reason: qualified ? null : "native_event_contract_unqualified" };
@@ -640,7 +723,7 @@ export async function promptSessionWithBridge(bridge, options) {
     throw error;
   }
   if (!options.allowBackground && (evidence.subagents.running ?? []).length) {
-    await cancelTree(bridge, identity.adapterSessionId, evidence.subagents);
+    await cancelTree(bridge, identity.adapterSessionId, evidence.subagents, identity.providerSessionId);
     fail("background ZCode subagents cannot outlive the one-shot dd-zcode connection; the live child tree was cancelled");
   }
   return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, assistant_text: bridge.assistantTextSince(identity.adapterSessionId, textCursor), turn, profile: profile_receipt, evidence: publicEvidence(evidence) });
@@ -666,7 +749,7 @@ export async function cancelSessionWithBridge(bridge, options) {
   requireJournal(options);
   const identity = await controlledIdentity(bridge, options);
   const before = await bridge.request("zcode/session/subagents", { sessionId: identity.adapterSessionId }).catch(error => ({ observation_error: { code: error.code, message: error.message } }));
-  return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...await cancelTree(bridge, identity.adapterSessionId, before) });
+  return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...await cancelTree(bridge, identity.adapterSessionId, before, identity.providerSessionId) });
 }
 
 export async function forkSession(options) {

package/dist/schemas/code-work-batch.schema.json

@@ -16,7 +16,7 @@
     "spine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"$ref": "#/$defs/strings"}, "non_goals": {"$ref": "#/$defs/stringList"}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
     "obligation": {"type": "object", "additionalProperties": false, "required": ["id", "statement"], "properties": {"id": {"type": "string", "minLength": 1}, "statement": {"type": "string", "minLength": 1}}},
     "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"$ref": "#/$defs/stringList"}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"type": "string", "minLength": 1}}},
-    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
+    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "minLength": 1}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}]},
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason", "baseline_sha256"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}, "baseline_sha256": {"type": ["string", "null"], "pattern": "^[a-f0-9]{64}$"}}},
     "reviewFinding": {"type": "object", "additionalProperties": false, "required": ["finding_ref", "priority", "problem", "impact", "required_outcome", "evidence_refs", "obligation_refs", "decision_reason", "check_refs"], "properties": {"finding_ref": {"type": "string", "minLength": 1}, "priority": {"enum": ["p0", "p1", "p2", "p3"]}, "problem": {"type": "string", "minLength": 1}, "impact": {"type": "string", "minLength": 1}, "required_outcome": {"type": "string", "minLength": 1}, "evidence_refs": {"$ref": "#/$defs/strings"}, "obligation_refs": {"$ref": "#/$defs/strings"}, "decision_reason": {"type": "string", "minLength": 1}, "check_refs": {"$ref": "#/$defs/strings"}}},
     "repair": {"type": "object", "additionalProperties": false, "required": ["origin_work_ids", "verification_check_refs"], "anyOf": [{"required": ["check_receipt_id", "failure_receipt_path"]}, {"required": ["review_findings"]}, {"required": ["semantic_unresolved", "verification_path"]}], "properties": {"origin_work_ids": {"$ref": "#/$defs/strings"}, "check_receipt_id": {"type": "string", "minLength": 1}, "failure_receipt_path": {"type": "string", "minLength": 1}, "review_findings": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/reviewFinding"}}, "semantic_unresolved": {"$ref": "#/$defs/strings"}, "verification_path": {"type": "string", "minLength": 1}, "verification_check_refs": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/check"}}}},

package/dist/schemas/vnext-protocol-plan.schema.json

@@ -29,9 +29,9 @@
     "documentUpdate": {"type": "object", "additionalProperties": false, "required": ["path", "action", "owner", "reason"], "properties": {"path": {"type": "string", "minLength": 1}, "action": {"enum": ["create", "update"]}, "owner": {"type": "string", "minLength": 1}, "reason": {"type": "string", "minLength": 1}}},
     "spine": {"type": "object", "additionalProperties": false, "required": ["user_outcome", "component_responsibility", "must_preserve", "non_goals", "acceptance_contribution"], "properties": {"user_outcome": {"type": "string", "minLength": 1}, "component_responsibility": {"type": "string", "minLength": 1}, "must_preserve": {"$ref": "#/$defs/strings"}, "non_goals": {"type": "array", "items": {"type": "string", "minLength": 1}}, "acceptance_contribution": {"type": "string", "minLength": 1}}},
     "execution": {"type": "object", "additionalProperties": false, "required": ["required_read", "discovery_boundary", "planned_write_areas", "stop_conditions"], "properties": {"required_read": {"$ref": "#/$defs/strings", "description": "Mandatory starting sources. This is not a read allowlist."}, "discovery_boundary": {"$ref": "#/$defs/strings", "description": "Likely discovery areas. A worker may inspect other project-local sources when necessary."}, "planned_write_areas": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "Optional file or directory hints used only to coordinate concurrent Works. They never grant or deny write permission."}, "stop_conditions": {"$ref": "#/$defs/strings", "description": "Semantic contradictions or external blockers that require the worker to stop."}}},
-    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}, {"if": {"properties": {"command": {"pattern": "^@check/"}}}, "then": {"required": ["definition"]}}]},
+    "check": {"type": "object", "additionalProperties": false, "required": ["id", "command", "purpose", "run_at", "availability"], "properties": {"id": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}, "command": {"type": "string", "minLength": 1}, "purpose": {"type": "string", "minLength": 1}, "run_at": {"enum": ["work", "code", "readiness", "merge", "release"]}, "availability": {"enum": ["available", "planned"]}, "provided_by": {"type": "string", "pattern": "^P[0-9]+$"}, "definition": {"type": "string", "minLength": 1}, "required_artifacts": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "ports": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]*$"}}, "inputs": {"type": "array", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}, "reuse": {"const": "deterministic"}}, "allOf": [{"if": {"properties": {"availability": {"const": "planned"}}, "required": ["availability"]}, "then": {"required": ["provided_by", "definition"], "properties": {"command": {"pattern": "^@check/"}}}}, {"if": {"properties": {"command": {"pattern": "^@check/"}}}, "then": {"required": ["definition"]}}]},
     "verification": {"type": "object", "additionalProperties": false, "required": ["check_refs"], "properties": {"check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}}},
     "item": {"type": "object", "additionalProperties": false, "required": ["id", "title", "summary", "details", "depends_on", "requirement_refs", "semantic_spine", "execution_context", "verification"], "properties": {"id": {"type": "string", "pattern": "^P[0-9]+$"}, "title": {"type": "string", "minLength": 1}, "summary": {"type": "string", "minLength": 1}, "details": {"type": "string", "minLength": 1}, "depends_on": {"type": "array", "uniqueItems": true, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "requirement_refs": {"$ref": "#/$defs/strings"}, "semantic_spine": {"$ref": "#/$defs/spine"}, "execution_context": {"$ref": "#/$defs/execution"}, "verification": {"$ref": "#/$defs/verification"}}},
-    "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "plan_item_ids", "changed_surfaces", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "plan_item_ids": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "changed_surfaces": {"$ref": "#/$defs/strings"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"type": "array", "items": {"type": "string", "minLength": 1}}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"enum": ["work", "code", "readiness", "merge", "release", "external"]}}}
+    "acceptance": {"type": "object", "additionalProperties": false, "required": ["criterion_id", "plan_item_ids", "changed_surfaces", "path", "environment", "fixtures", "cleanup", "check_refs", "expected_evidence", "proof_limits", "gate"], "properties": {"criterion_id": {"type": "string", "pattern": "^AC-[0-9]+$"}, "plan_item_ids": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^P[0-9]+$"}}, "changed_surfaces": {"$ref": "#/$defs/strings"}, "path": {"type": "string", "minLength": 1}, "environment": {"type": "string", "minLength": 1}, "fixtures": {"type": "array", "items": {"type": "string", "minLength": 1}}, "cleanup": {"type": "string", "minLength": 1}, "check_refs": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^CHK-[A-Za-z0-9-]+$"}}, "expected_evidence": {"$ref": "#/$defs/strings"}, "proof_limits": {"$ref": "#/$defs/strings"}, "gate": {"enum": ["work", "code", "readiness", "merge", "release"]}}}
   }
 }

package/dist/services/code-checks.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { parse } from "shell-quote";
 import { assertRunMutationAllowed } from "./run-recovery.js";
 import { AppError } from "../shared/errors.js";
 import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, managedProcessRuntimeHome, managedOwnerIsAlive, processTreeIsAlive, registerManagedProcess, reservePorts } from "./managed-processes.js";
@@ -37,15 +38,17 @@ export function readCodeCheckProfile(workspaceRoot) {
 }
 export function validateCodeCheckCommands(workspaceRoot, commands) {
     const { profile, file } = readCodeCheckProfile(workspaceRoot);
-    if (!profile)
-        return [...commands];
-    return commands.map((command) => { if (command.startsWith("@check/")) {
-        if (!profile.aliases[command]?.trim())
-            throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
+    return commands.map((command) => {
+        if (command.startsWith("@check/")) {
+            if (!profile?.aliases[command]?.trim())
+                throw new AppError("unknown_code_check_alias", "CODE check alias is not defined by the project profile", 2, { alias: command, file });
+            return command;
+        }
+        for (const [prefix, alias] of Object.entries(profile?.require_alias_for ?? {}))
+            if (command === prefix || command.startsWith(`${prefix} `))
+                throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file });
         return command;
-    } for (const [prefix, alias] of Object.entries(profile.require_alias_for))
-        if (command === prefix || command.startsWith(`${prefix} `))
-            throw new AppError("raw_code_check_forbidden", "CODE check must use the project alias instead of a raw guarded command", 2, { command, required_alias: alias, file }); return command; });
+    });
 }
 export function resolveCodeCheckCommands(workspaceRoot, runId, commands) {
     const validated = validateCodeCheckCommands(workspaceRoot, commands);
@@ -66,12 +69,14 @@ export function validateCheckPlacement(workspaceRoot, checks) { const { profile
     if (check.run_at === "work" && aggregateCommands.has(check.command))
         throw new AppError("aggregate_check_requires_code_gate", "A project aggregate check must run at CODE or readiness, not inside one scoped Work", 2, { check_id: check.id, command: check.command, run_at: check.run_at }); }
 export function validateCheckDeclaration(workspaceRoot, check) {
-    if (check.run_at === "external")
-        return;
+    if (!["work", "code", "readiness", "merge", "release"].includes(check.run_at))
+        throw new AppError("unsupported_check_gate", "Check requires an autonomous executable gate; replan the incompatible declaration", 2, { check_id: check.id, run_at: check.run_at });
     const { profile } = readCodeCheckProfile(workspaceRoot);
     if (check.availability === "planned" && check.command.startsWith("@check/") && !profile?.aliases[check.command])
         throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
     validateCodeCheckCommands(workspaceRoot, [check.command]);
+    if (check.availability === "available" && !check.command.startsWith("@check/"))
+        assertDirectCheckExecutable(workspaceRoot, check.command, check.id);
     validateCheckInputs(workspaceRoot, check.inputs ?? []);
     if (check.command.startsWith("@check/") && check.definition && profile?.aliases[check.command] !== check.definition)
         throw new AppError("check_definition_drift", "The accepted check alias definition differs from the current project profile", 2, { check_id: check.id, alias: check.command, expected: check.definition, actual: profile?.aliases[check.command] ?? null });
@@ -84,6 +89,34 @@ export function validateCheckDeclaration(workspaceRoot, check) {
     if (!profile?.aliases[check.command])
         throw new AppError("planned_check_not_materialized", "A planned check alias was not materialized by its provider Work", 2, { check_id: check.id, command: check.command, provider: check.provided_by ?? null });
 }
+/** Reject a plan-time typo or a fictitious "manual" command before it becomes
+ * a late shell exit. Compound shell programs remain valid: only a simple,
+ * directly named executable is preflighted here. */
+function assertDirectCheckExecutable(workspaceRoot, command, checkId) {
+    const trimmed = command.trim();
+    // A shell operator or expansion makes the launch path dynamic. Do not
+    // guess there; this preflight is deliberately limited to a direct program
+    // with ordinary arguments and optional literal environment assignments.
+    if (/[|&;<>()`$\n\r~]/.test(trimmed))
+        return;
+    const parsed = parse(trimmed);
+    if (parsed.some(word => typeof word !== "string"))
+        return;
+    const words = parsed;
+    let index = 0;
+    const env = codeExecutionEnvironment(workspaceRoot);
+    while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[index] ?? "")) {
+        const assignment = words[index++];
+        const equals = assignment.indexOf("=");
+        env[assignment.slice(0, equals)] = assignment.slice(equals + 1);
+    }
+    const program = words[index];
+    if (!program)
+        return;
+    const probe = spawnSync("/bin/sh", ["-c", "command -v -- \"$1\" >/dev/null", "dd-flow-check", program], { cwd: workspaceRoot, env, encoding: "utf8", timeout: 5000 });
+    if (probe.status !== 0)
+        throw new AppError("check_command_unavailable", "Available CODE check names an executable that is unavailable in this environment", 2, { check_id: checkId, command, executable: program });
+}
 export async function runCodeChecks(context, input) {
     reconcileUnfinishedChecks(context, input);
     reconcileWorkspaceOwnership(context, input.workspaceRoot);
@@ -503,7 +536,7 @@ catch {
     return fallback;
 } }
 function isStringRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string" && item.trim().length > 0); }
-function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release", "external"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
+function isGateRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([gate, aliases]) => ["work", "code", "readiness", "merge", "release"].includes(gate) && Array.isArray(aliases) && aliases.every((item) => typeof item === "string" && item.startsWith("@check/"))); }
 function isPortAliasRecord(value) { return value === undefined || (Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([alias, ports]) => alias.startsWith("@check/") && Array.isArray(ports) && ports.length > 0 && new Set(ports).size === ports.length && ports.every((port) => typeof port === "string" && /^[A-Za-z][A-Za-z0-9_]*$/.test(port)))); }
 function isInputAliasRecord(workspaceRoot, value) { try {
     return value === undefined || (Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.entries(value).every(([alias, inputs]) => alias.startsWith("@check/") && Array.isArray(inputs) && (validateCheckInputs(workspaceRoot, inputs), true)));

package/dist/services/lifecycle-invocations.js

@@ -99,8 +99,18 @@ export function managedLifecycleCommand(context, command) {
         return command;
     const scope = JSON.parse(configured);
     const parsed = invocation(command);
-    if (commandOption(parsed, "invocation-id"))
+    const suppliedId = commandOption(parsed, "invocation-id");
+    // An invocation id is authority, never decorative text.  In particular,
+    // callers that add arguments after rendering must not be able to reuse an
+    // issued id for a different command.
+    if (suppliedId) {
+        const retained = load(context, suppliedId);
+        if (retained.scope_json !== JSON.stringify(scope)) {
+            throw new AppError("invocation_scope_mismatch", "Lifecycle attempt belongs to another managed scope", 1, { invocation_id: suppliedId });
+        }
+        checkCommand(retained, command);
         return command;
+    }
     if (!context.db.writable || context.env.DD_FLOW_INVOCATION_READONLY === "1") {
         const retained = context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'lifecycle_invocations'")
             ? context.db.get("SELECT * FROM lifecycle_invocations WHERE scope_json = ? AND fingerprint = ? ORDER BY rowid DESC LIMIT 1", [JSON.stringify(scope), fingerprint(parsed)]) : undefined;
@@ -133,10 +143,20 @@ export function retryLifecycleInvocationCommand(context, id) {
     const prior = load(context, id);
     if (prior.status !== "executing")
         throw new AppError("invocation_retry_not_authorized", "Only the executing lifecycle operation can publish its next attempt", 1);
-    const marker = ` --invocation-id ${id}`;
-    if (!prior.command.includes(marker))
+    const parsed = invocation(prior.command);
+    const argv = [...parsed.argv];
+    const at = argv.indexOf("--invocation-id");
+    if (at < 0 || argv[at + 1] !== id)
         throw new AppError("invocation_command_invalid", "Retained issued command lost its invocation marker", 1);
-    return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: id } }, prior.command.replace(marker, ""));
+    // The parser proves the marker belongs to argv. Remove that one rendered
+    // token from the retained text so response-file/stdin/heredoc presentation
+    // remains byte-for-byte stable across a retry.
+    const marker = ` --invocation-id ${id}`;
+    const markerAt = prior.command.indexOf(marker);
+    if (markerAt < 0 || prior.command.indexOf(marker, markerAt + marker.length) >= 0)
+        throw new AppError("invocation_command_invalid", "Retained issued command has an ambiguous invocation marker", 1);
+    const command = `${prior.command.slice(0, markerAt)}${prior.command.slice(markerAt + marker.length)}`;
+    return managedLifecycleCommand({ ...context, env: { ...context.env, DD_FLOW_INVOCATION_SCOPE: prior.scope_json, DD_FLOW_CURRENT_INVOCATION: id } }, command);
 }
 /** Settle a conclusive rejection and publish its only legal successor atomically.
  * A crash must leave either the old attempt executing, or both the settled

package/dist/services/native-session-control.js

@@ -9,14 +9,14 @@ export async function cancelControlledNativeSession(input) {
         throw new AppError("controller_operation_mismatch", "Cancellation observation belongs to another operation or Session", 1);
     const result = input.observe ? reply.state === "completed" ? reply.result : null : reply;
     if (!input.observe || reply.state === "completed")
-        assertNativeCancellationReceipt(result, input.sessionId);
+        assertNativeCancellationReceipt(result, input.sessionId, input.requireSettled);
     input.assertCurrent();
     return { status: result ? "completed" : "outcome_unknown", receipt: (result ?? reply) };
 }
-export function assertNativeCancellationReceipt(value, sessionId) {
+export function assertNativeCancellationReceipt(value, sessionId, requireSettled = false) {
     const identity = adapterSessionId(value);
-    if (!value || typeof value !== "object" || Array.isArray(value) || identity && identity !== sessionId)
-        throw new AppError("controller_operation_mismatch", "Cancellation receipt has no valid result for its target Session", 1);
+    if (!value || typeof value !== "object" || Array.isArray(value) || identity && identity !== sessionId || (requireSettled && value.settled !== true))
+        throw new AppError("controller_operation_mismatch", requireSettled ? "Cancellation receipt has no terminal settlement for its target Session" : "Cancellation receipt has no valid result for its target Session", 1);
 }
 /** Native observation is shared by RUN and non-Work EVAL owners. */
 export async function inspectControlledNativeSession(input) {

package/dist/services/run-control.js

@@ -1,3 +1,4 @@
+import { setFlowRunRecoveryPaused } from "./runs.js";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import { ensureRunControlStorage } from "../storage/database.js";
@@ -459,10 +460,10 @@ async function reconcileOwnedSessions(context, input, interrupt, boundary) {
         try {
             if (!inserted.changes && prior.status === "completed") {
                 const saved = JSON.parse(prior.receipt_json);
-                assertNativeCancellationReceipt(saved, session.id);
+                assertNativeCancellationReceipt(saved, session.id, harness === "zcode-acp");
                 return { operation_id: operationId, session_id: session.id, status: prior.status, receipt: saved, reused: true };
             }
-            const { status, receipt } = await cancelControlledNativeSession({ executable, sessionId: session.id, stateDir: session.state_dir, env, operationId, observe: !inserted.changes, assertCurrent });
+            const { status, receipt } = await cancelControlledNativeSession({ executable, sessionId: session.id, stateDir: session.state_dir, env, operationId, observe: !inserted.changes, assertCurrent, requireSettled: harness === "zcode-acp" });
             context.db.run("UPDATE run_control_operations SET status = ?, receipt_json = ?, error_json = NULL, updated_at = ? WHERE operation_id = ?", [status, JSON.stringify(receipt), context.now(), operationId]);
             return { operation_id: operationId, session_id: session.id, status, receipt };
         }
@@ -746,6 +747,7 @@ export function recordRunControlIntent(context, input) {
       FROM runs r, json_each(r.index_json, '$.stage_runs') stage
       WHERE r.project_id = ? AND r.id = ? AND json_extract(stage.value, '$.status') = 'running'
         AND EXISTS (SELECT 1 FROM run_control_admissions a JOIN sessions s ON s.session_id = a.session_id AND s.project_id = r.project_id WHERE a.control_id = ? AND s.current_stage = json_extract(stage.value, '$.stage'))`, [controlId, controlId, project.id, input.runId, controlId]);
+        setFlowRunRecoveryPaused(context, project.id, input.runId, true);
         context.db.exec("COMMIT");
         return { ok: true, control_id: controlId, recovery_id: recoveryId, generation, action: input.action, status: "requested", settled: false };
     }

package/dist/services/run-controller-process.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { AppError } from "../shared/errors.js";
 import { getResourceDatabase } from "../storage/database.js";
 import { finishManagedProcess, managedProcessRuntimeHome, managedProcessStatus, processIsAlive, processStartedAt, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
+import { setFlowRunRecoveryPaused } from "./runs.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
 import { requireRun, requireController, controllerReceipt, appendEvent, digest, errorRecord } from "./run-controller-state.js";
 const launchId = (row) => `${row.controller_id}:owner-launch:${digest(row.owner_token)}`;
@@ -172,7 +173,17 @@ export async function spawnController(context, row) {
         return controllerReceipt(requireController(context, controllerId));
     }
     catch (error) {
-        context.db.run("UPDATE run_controllers SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status = 'starting' AND owner_pid IS NULL", [JSON.stringify(errorRecord(error)), context.now(), controllerId, token]);
+        context.db.exec("SAVEPOINT controller_spawn_status");
+        try {
+            const changed = context.db.run("UPDATE run_controllers SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status = 'starting' AND owner_pid IS NULL", [JSON.stringify(errorRecord(error)), context.now(), controllerId, token]);
+            if (changed.changes && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation)
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+            context.db.exec("RELEASE controller_spawn_status");
+        }
+        catch (failure) {
+            context.db.exec("ROLLBACK TO controller_spawn_status; RELEASE controller_spawn_status");
+            throw failure;
+        }
         throw error;
     }
 }

package/dist/services/run-controller.js

@@ -10,7 +10,7 @@ import { AppError } from "../shared/errors.js";
 import { parseRuntimeBudget } from "./runtime-budget.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, recoveryGuard } from "./run-recovery.js";
-import { getFlowRunStatus } from "./runs.js";
+import { getFlowRunStatus, setFlowRunRecoveryPaused } from "./runs.js";
 import { loadExternalStageContext } from "./stage-context.js";
 import { flowCommand } from "./stage-pause.js";
 import { resolveStageTransition, sameSessionProfile, runtimeHarness } from "./execution-policy.js";
@@ -202,7 +202,17 @@ export async function serveRunController(context, input) {
     };
     const assertOwner = () => { assertPhysicalOwner(); assertRunMutationAllowed(context, row.project_id, row.run_id, row.generation); };
     try {
-        markControllerDispatchReady(context, row);
+        context.db.exec("SAVEPOINT controller_ready_status");
+        try {
+            markControllerDispatchReady(context, row);
+            if (!state.recovery && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation && requireRun(context, row.project_id, row.run_id).status === "paused")
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, false);
+            context.db.exec("RELEASE controller_ready_status");
+        }
+        catch (error) {
+            context.db.exec("ROLLBACK TO controller_ready_status; RELEASE controller_ready_status");
+            throw error;
+        }
         appendEvent(context, row.controller_id, "owner_started", { pid: process.pid, generation: row.generation });
         if (state.recovery)
             await resumeControllerSession(context, row, manifest, state, assertPhysicalOwner);
@@ -221,10 +231,21 @@ export async function serveRunController(context, input) {
                 return controllerReceipt(requireController(context, row.controller_id));
             }
         }
-        // A failed capture must not reopen admission when this process exits.
-        context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ?", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
-        context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status IN ('dispatching','active')", [JSON.stringify(errorRecord(error)), context.now(), row.project_id, row.run_id, row.controller_id]);
-        appendEvent(context, row.controller_id, "recovery_required", errorRecord(error));
+        context.db.exec("SAVEPOINT controller_failure_status");
+        try {
+            // A failed capture must not reopen admission when this process exits.
+            const changed = context.db.run("UPDATE run_controllers SET status = CASE WHEN status IN ('capturing','capture_failed') THEN 'capture_failed' ELSE 'recovery_required' END, last_error_json = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status NOT IN ('completed','cancelled','superseded')", [JSON.stringify(errorRecord(error)), context.now(), row.controller_id, row.owner_token]);
+            context.db.run("UPDATE merge_requests SET status = 'recovery_required', last_error_json = ?, updated_at = ? WHERE project_id = ? AND run_id = ? AND dispatch_owner = ? AND status IN ('dispatching','active')", [JSON.stringify(errorRecord(error)), context.now(), row.project_id, row.run_id, row.controller_id]);
+            if (changed.changes && (recoveryGuard(context, row.project_id, row.run_id)?.generation ?? 0) === row.generation) {
+                setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
+            }
+            appendEvent(context, row.controller_id, "recovery_required", errorRecord(error));
+            context.db.exec("RELEASE controller_failure_status");
+        }
+        catch (failure) {
+            context.db.exec("ROLLBACK TO controller_failure_status; RELEASE controller_failure_status");
+            throw failure;
+        }
         throw error;
     }
     finally {

package/dist/services/run-recovery.js

@@ -5,7 +5,7 @@ import path from "node:path";
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { appendFlowRunTimelineEvent } from "./runs.js";
+import { appendFlowRunTimelineEvent, setFlowRunRecoveryPaused } from "./runs.js";
 import { verifyRecoverySnapshot } from "./eval-snapshots.js";
 import { findRecentMatchingHookEvent, hookSessionIdentity, recoveryAcceptMatchKey } from "./hooks.js";
 import { flowCommand } from "./stage-pause.js";
@@ -123,6 +123,7 @@ export function beginRunRecovery(context, input) {
             context.db.run("UPDATE run_recovery_bindings SET status = 'abandoned' WHERE recovery_id = ? AND status = 'prepared'", [prior.recovery_id]);
         }
         context.db.run("INSERT INTO run_recovery_guards (recovery_id, project_id, run_id, generation, status, interruption_json, settlement_json, capture_path, created_at, updated_at, sealed_at, resumed_at) VALUES (?, ?, ?, ?, 'draining', ?, NULL, NULL, ?, ?, NULL, NULL)", [recoveryId, project.id, run.id, generation, JSON.stringify(interruption), now, now]);
+        setFlowRunRecoveryPaused(context, project.id, run.id, true);
         context.db.exec("COMMIT");
     }
     catch (error) {
@@ -147,9 +148,18 @@ export function sealRunRecovery(context, input) {
         throw new AppError("recovery_invalid_state", "Recovery is not draining", 1, { recovery_id: guard.recovery_id, status: guard.status });
     materializePendingWorkResults(context, project.id, run.id);
     const now = context.now();
-    const updated = context.db.run("UPDATE run_recovery_guards SET status = 'sealed', settlement_json = ?, sealed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'draining' AND generation = (SELECT MAX(generation) FROM run_recovery_guards WHERE project_id = ? AND run_id = ?)", [JSON.stringify(settlement), now, now, guard.recovery_id, project.id, run.id]);
-    if (updated.changes !== 1)
-        throw new AppError("recovery_state_changed", "Recovery state changed before it could be sealed", 1, { recovery_id: guard.recovery_id });
+    context.db.exec("SAVEPOINT seal_run_status");
+    try {
+        const updated = context.db.run("UPDATE run_recovery_guards SET status = 'sealed', settlement_json = ?, sealed_at = ?, updated_at = ? WHERE recovery_id = ? AND status = 'draining' AND generation = (SELECT MAX(generation) FROM run_recovery_guards WHERE project_id = ? AND run_id = ?)", [JSON.stringify(settlement), now, now, guard.recovery_id, project.id, run.id]);
+        if (updated.changes !== 1)
+            throw new AppError("recovery_state_changed", "Recovery state changed before it could be sealed", 1, { recovery_id: guard.recovery_id });
+        setFlowRunRecoveryPaused(context, project.id, run.id, true);
+        context.db.exec("RELEASE seal_run_status");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK TO seal_run_status; RELEASE seal_run_status");
+        throw error;
+    }
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "run_recovery_sealed", recovery_id: guard.recovery_id, generation: guard.generation, settlement });
     return { ok: true, recovery: { recovery_id: guard.recovery_id, run_id: run.id, generation: guard.generation, status: "sealed", settlement } };
 }
@@ -286,6 +296,7 @@ export function acceptRunRecovery(context, input) {
         }
         context.db.run("UPDATE run_recovery_bindings SET status = 'accepted', hook_event_key = ?, accepted_at = ? WHERE recovery_id = ?", [eventKey, now, binding.recovery_id]);
         context.db.run("UPDATE run_recovery_guards SET status = 'recovered', resumed_at = ?, updated_at = ? WHERE recovery_id = ?", [now, now, guard.recovery_id]);
+        setFlowRunRecoveryPaused(context, project.id, run.id, false);
         context.db.exec("COMMIT");
     }
     catch (error) {

package/dist/services/runs.js

@@ -5,7 +5,7 @@ import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { ensureDir, canonicalPath, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
@@ -788,8 +788,24 @@ function operationalRunStatus(context, projectId, runId) {
     const leaves = unfinished.filter((work) => !parents.has(work.work_id));
     return leaves.length > 0 && leaves.every((work) => work.status === "paused") ? "paused" : "running";
 }
+/** Keep the logical RUN projection aligned with recovery authority. Stage/Work
+ * evidence and verdicts survive a reversible stop; terminal runs never reopen. */
+export function setFlowRunRecoveryPaused(context, projectId, runId, paused) {
+    const run = resolveRun(context, projectId, runId);
+    if (!["running", "paused"].includes(run.status))
+        return;
+    const index = authoritativeIndex(run);
+    const status = paused || index.stage_runs.some(stage => ["paused", "waiting_for_user", "blocked"].includes(stage.status))
+        ? "paused" : operationalRunStatus(context, projectId, runId);
+    if (run.status === status && index.status === status)
+        return;
+    index.status = status;
+    index.updated_at = context.now();
+    const project = requireProjectByRoot(context, run.project_root);
+    persistRunState(context, project, run, index);
+}
 export function completeFlowRun(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const project = requireProjectByRoot(context, input.manualOverrideReason ? canonicalPath(input.projectRoot, false) : resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     assertRunMutationAllowed(context, project.id, run.id);
     const index = authoritativeIndex(run);
@@ -856,8 +872,8 @@ export function advanceFlowRun(context, input) {
     index.next_action = control ? null : input.nextAction ?? null;
     index.updated_at = now;
     persistRunState(context, project, run, index);
-    appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: input.status, verdict: input.verdict, next_action: index.next_action } });
-    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_progressed", run_id: run.id, status: input.status, next_action: index.next_action });
+    appendAudit(context, { projectId: project.id, eventType: "flow_run.progressed", payload: { run_id: run.id, status: index.status, verdict: input.verdict, next_action: index.next_action } });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_progressed", run_id: run.id, status: index.status, next_action: index.next_action });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, ...(control ? { control } : {}), run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
@@ -1189,6 +1205,10 @@ function vnextSpecifyGuidance(run, index) {
     };
 }
 function persistRunState(context, project, run, index, options = {}) {
+    // Fenced productive admission is a logical pause, even while physical work
+    // drains. Late admitted Stage results must not revive a stopped RUN.
+    if (index.status === "running" && ["draining", "sealed", "resuming"].includes(recoveryGuard(context, project.id, run.id)?.status ?? ""))
+        index.status = "paused";
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
     const previousRuntime = readRuntimeSnapshot(runtimePath);
     const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
@@ -1199,22 +1219,30 @@ function persistRunState(context, project, run, index, options = {}) {
     }
     const persistedIndex = persistedVnextIndex(index);
     ensureDir(path.dirname(runtimePath));
-    writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
-    context.db.run(`UPDATE runs
+    context.db.exec("SAVEPOINT persist_run_state");
+    try {
+        context.db.run(`UPDATE runs
      SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
        updated_at = ?, completed_at = ?
      WHERE project_id = ? AND id = ?`, [
-        index.status,
-        index.verdict,
-        index.next_action,
-        JSON.stringify(persistedIndex),
-        runtimePath,
-        runtimePath,
-        index.updated_at,
-        index.completed_at ?? null,
-        project.id,
-        run.id
-    ]);
+            index.status,
+            index.verdict,
+            index.next_action,
+            JSON.stringify(persistedIndex),
+            runtimePath,
+            runtimePath,
+            index.updated_at,
+            index.completed_at ?? null,
+            project.id,
+            run.id
+        ]);
+        writeJsonFile(runtimePath, runtimeSnapshotForIndex(persistedIndex, runtimeRevision, history));
+        context.db.exec("RELEASE persist_run_state");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK TO persist_run_state; RELEASE persist_run_state");
+        throw error;
+    }
 }
 /** vNext stores derived stage/work state only once: stage_runs, Works and Sessions. */
 function persistedVnextIndex(index) {
@@ -1576,5 +1604,5 @@ export function gitFacts(workspaceRoot) {
         status: status === null ? "unavailable" : status.length > 0 ? "dirty" : "clean"
     };
 }
-import { assertRunMutationAllowed, assertStageSettlementAllowed } from "./run-recovery.js";
+import { assertRunMutationAllowed, assertStageSettlementAllowed, recoveryGuard } from "./run-recovery.js";
 import { runControlDirective } from "./run-control.js";

package/dist/services/vnext-code-review.js

@@ -103,9 +103,7 @@ export function addVnextCodeReviewRepair(context, input) {
     const unknown = requestedCheckRefs.filter((ref) => !checks.has(ref));
     if (unknown.length)
         throw new AppError("review_check_reference_unknown", "CODE-REVIEW finding cites a check absent from the accepted CODE handoff", 2, { check_refs: unknown });
-    const reviewChecks = requestedCheckRefs.map((ref) => checks.get(ref)).filter((check) => check.run_at !== "external");
-    if (!reviewChecks.length)
-        throw new AppError("review_repair_executable_check_required", "CODE-REVIEW repair requires at least one executable causal check; external-only evidence cannot validate a repair Work", 2, { finding_ids: input.findingIds, check_refs: requestedCheckRefs });
+    const reviewChecks = requestedCheckRefs.map((ref) => checks.get(ref));
     return addVnextCodeRepair(context, {
         projectRoot,
         runId: run.id,
@@ -192,7 +190,7 @@ export async function finishVnextCodeReview(context, input) {
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
             repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`,
-            retry_command: `${finishCommand(context, run.id, projectRoot, decisionFile)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"`
+            retry_command: finishCommand(context, run.id, projectRoot, decisionFile, failed[0].id)
         });
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
@@ -421,7 +419,7 @@ function requireRun(context, projectId, runId) { const run = context.db.get("SEL
     throw new AppError("not_found", "RUN is not registered", 1); return run; }
 function requireHome(run) { if (!run.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1); return run.run_root; }
-function finishCommand(context, runId, projectRoot, decision) { return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`); }
+export function finishCommand(context, runId, projectRoot, decision, retryCheckId) { const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : ""; return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code-review --decision-file ${JSON.stringify(decision)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`); }
 function findFiles(root, name) { if (!fs.existsSync(root))
     return []; const out = []; for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
     const file = path.join(root, entry.name);

package/dist/services/vnext-code.js

@@ -179,7 +179,7 @@ export async function finishVnextCode(context, input) {
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
             repair_command: `${flowCommand(context)} work repair add --run ${run.id} --from-check ${failed[0].id} --origin-work <WORK-ID> --task-stdin --project-root ${JSON.stringify(projectRoot)} --json`,
-            retry_command: `${finishCommand(context, run.id, projectRoot, input.verificationFile)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"`
+            retry_command: finishCommand(context, run.id, projectRoot, input.verificationFile, failed[0].id)
         });
     }
     const finalReceipts = receipts;
@@ -495,18 +495,16 @@ export function verificationProjection(works, receipts, options = {}) {
         return [item.criterion_id, { evidenceRefs, historical }];
     }));
     const hasEvidence = (criterionId) => (acceptanceEvidence.get(criterionId)?.evidenceRefs.length ?? 0) > 0;
-    const isPassed = (checkId, criterionId) => receiptByDeclaration.get(checkId)?.status === "passed" || (declarations.find((check) => check.id === checkId)?.run_at === "external" && hasEvidence(criterionId));
+    const isPassed = (checkId) => receiptByDeclaration.get(checkId)?.status === "passed";
     return {
         checks: declarations.map((check) => {
             const receipt = receiptByDeclaration.get(check.id);
-            const externallyEvidenced = check.run_at === "external" && acceptance.some((item) => item.check_refs.includes(check.id) && hasEvidence(item.criterion_id));
-            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (externallyEvidenced ? "evidence_recorded" : ["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
+            return { id: check.id, run_at: check.run_at, status: receipt?.status ?? (["work", "code", "readiness"].includes(check.run_at) ? "failed" : "not_due"), receipt_ref: receipt?.receipt_path ?? null };
         }),
         acceptance: acceptance.map((item) => {
-            const external = item.check_refs.some((id) => declarations.find((check) => check.id === id)?.run_at === "external");
-            const confirmed = item.check_refs.every((id) => isPassed(id, item.criterion_id)) && hasEvidence(item.criterion_id);
+            const confirmed = item.check_refs.every((id) => isPassed(id)) && hasEvidence(item.criterion_id);
             const evidence = acceptanceEvidence.get(item.criterion_id) ?? { evidenceRefs: [], historical: [] };
-            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? (external ? "confirmed_with_external_evidence" : "confirmed") : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.evidenceRefs, ...(evidence.historical.length ? { reported_evidence_refs: evidence.historical } : {}) };
+            return { criterion_id: item.criterion_id, gate: item.gate, status: confirmed ? "confirmed" : ["work", "code", "readiness"].includes(item.gate) ? "unresolved" : "not_due", check_refs: item.check_refs, evidence_refs: evidence.evidenceRefs, ...(evidence.historical.length ? { reported_evidence_refs: evidence.historical } : {}) };
         })
     };
 }
@@ -604,8 +602,9 @@ function requireHome(run) {
         throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1);
     return run.run_root;
 }
-function finishCommand(context, runId, projectRoot, verificationFile) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`);
+export function finishCommand(context, runId, projectRoot, verificationFile, retryCheckId) {
+    const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : "";
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage code --verification-file ${JSON.stringify(verificationFile)} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`);
 }
 function readVerification(context, input) {
     const file = path.resolve(input.file);

package/dist/services/vnext-merge.js

@@ -260,7 +260,7 @@ export async function finishVnextMerge(context, input) {
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
     if (failed.length) {
         context.db.run("UPDATE merge_requests SET status = 'action_required', last_error_json = ?, updated_at = ? WHERE merge_request_id = ?", [JSON.stringify({ code: "merge_gate_failed", failures: failed }), context.now(), request.merge_request_id]);
-        throw new AppError("merge_gate_failed", "Integrated target checks failed. Classify retained evidence: source defects use source repair; restored environment uses retry.", 2, { failures: failed, repair_command: `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json`, retry_command: `${finishCommand(context, run.id, request, projectRoot)} --retry-check ${failed[0].id} --reason "<environment recovery evidence>"` });
+        throw new AppError("merge_gate_failed", "Integrated target checks failed. Classify retained evidence: source defects use source repair; restored environment uses retry.", 2, { failures: failed, repair_command: `${flowCommand(context)} merge repair ${request.merge_request_id} --project-root ${JSON.stringify(projectRoot)} --json`, retry_command: finishCommand(context, run.id, request, projectRoot, failed[0].id) });
     }
     const passedRefs = new Set(receipts.flatMap((receipt) => receipt.check_refs));
     const missingRefs = frozenGateRefs(gate).filter((ref) => !passedRefs.has(ref));
@@ -561,4 +561,4 @@ function findRootWork(context, projectId, runId) { const work = context.db.get("
 function requireRootWork(context, projectId, runId) { const work = findRootWork(context, projectId, runId); if (work.status !== "running")
     throw new AppError("runtime_missing", "vNext RUN has no running root Work", 1); return work; }
 function applyCommand(context, request, projectRoot) { return `${flowCommand(context)} merge apply ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`; }
-function finishCommand(context, runId, request, projectRoot) { return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage merge --request ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl`); }
+export function finishCommand(context, runId, request, projectRoot, retryCheckId) { const retry = retryCheckId ? ` --retry-check ${retryCheckId} --reason "<environment recovery evidence>"` : ""; return managedLifecycleCommand(context, `${flowCommand(context)} stage finish ${runId} --stage merge --request ${request.merge_request_id} --work ${request.executor_work_id} --project-root ${JSON.stringify(projectRoot)} --json --progress-jsonl${retry}`); }

package/dist/services/vnext-plan.js

@@ -93,10 +93,13 @@ export function startVnextPlan(context, input) {
                 ? [`This RUN must reach MERGE. Project policy already supplies the mandatory merge gate${policyMergeAliases.length === 1 ? "" : "s"}: ${policyMergeAliases.join(", ")}. Do not duplicate them in semantic checks[]. Add another merge check only when the task genuinely needs additional evidence.`]
                 : ["This RUN must reach MERGE and project policy supplies no merge gate. Select at least one real top-level checks[] entry with run_at: merge. It may use an existing project alias or a planned alias materialised by a named P* provider Work. This is a planning obligation: do not defer it to CODE-REVIEW or MERGE."]), "The CLI validates the effective merge gate but never invents one or migrates an incompatible project policy.", "</merge_gate_contract>", ""]
         : [];
-    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(gitFacts(run.workspace_root))}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(fs.existsSync(checkProfile) ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", fs.readFileSync(checkProfile, "utf8").trim(), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.", "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an honestly limited external/manual proof. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
+    const prompt = ["<stage_identity>", `- RUN: ${run.id}`, `- Work: ${planWorkId}`, "- stage: plan", "</stage_identity>", "", "<trusted_runtime_context>", "These facts were collected by dd-flow. Trust them; do not repeat CLI, Git, compatibility or permission discovery.", `- Project root: ${projectRoot}`, `- Workspace: ${run.workspace_root}`, `- Stage workspace: ${root}`, `- Git: ${JSON.stringify(gitFacts(run.workspace_root))}`, capacityContext, "</trusted_runtime_context>", "", "<workspace_contract>", `- route: ${workspaceRoute.route}`, `- feature branch: ${workspaceRoute.feature_branch ?? "not applicable"}`, `- base commit: ${workspaceRoute.base_ref ?? "not applicable"}`, `- write workspace: ${run.workspace_root}`, "The CLI has verified this frozen route. All project reads and writes for PLAN and later CODE happen in the write workspace; project root is only the stable runtime identity for lifecycle commands. Do not create, switch, merge or delete branches/worktrees.", "Keep the task runner's current cwd. Use the absolute paths in this packet instead of trying to set the provisioned workspace as a tool workdir.", "</workspace_contract>", "", "<accepted_inputs>", `- ${path.join(home, "01-specify", "specify.json")}`, `- ${path.join(home, "02-protocolize", "protocolize-result.json")}`, ...protocols.map((id) => `- ${path.join(run.workspace_root, ".memory-bank", "protocol", id, "summary.md")}`), "</accepted_inputs>", "", ...(fs.existsSync(checkProfile) ? ["<code_check_policy>", "You, not the CLI, select evidence for every accepted requirement and acceptance criterion. The profile only lists reusable aliases, mandatory project policy gates and guarded raw command prefixes. Inspect relevant package/test manifests before choosing a check. Do not classify checks by weight and do not omit a needed check because it looks expensive.", fs.readFileSync(checkProfile, "utf8").trim(), "</code_check_policy>", ""] : []), ...mergeContract, "<artifacts>", "The CLI has already materialized every artifact below as a partially filled draft. Edit these files in place; do not create replacements elsewhere.", "Prefilled and CLI-owned plan fields: schema_id, plan_id, protocol_id, initial revision and source_refs.", "Prefilled and CLI-owned aspect-map fields: schema_id, protocol_id, plan_id, plan revision, catalog_ref and every catalog aspect_id.", "You own the remaining semantic fields. Empty or missing semantic values are intentional draft markers and must be completed before validation.", ...planPaths.map((value) => `- partially filled plan: ${value}`), ...mapPaths.map((value) => `- partially filled aspect map: ${value}`), "</artifacts>", "", "<output_contract>", "Complete every named plan and aspect map in place. Do not create or edit code-work-batch.json: dd-flow derives it after validation.", "The CLI owns schema_id, plan_id, protocol_id, revision and source_refs. Preserve them exactly.", "Use protocol-plan@6. Its top-level checks[] is the single check catalog. Every check has id, command, purpose, run_at and availability. available means executable now. planned means one named P* Work first creates a NEW @check/... alias: planned therefore always needs provided_by and the exact alias definition. Every semantic @check alias, including an existing one, repeats its exact accepted profile command in definition so later stages can detect drift. Items and acceptance entries use check_refs only; never duplicate command declarations.", "For each R-* and AC-*, choose an actually relevant proof: an existing focused test, a new planned alias plus its provider Work, a project policy gate, or an autonomous executable check. Every plan item needs at least one check_ref. The CLI validates ids, provider ordering, materialization and guarded command policy; it never chooses a check for you. A provider Work may verify itself with the alias it has just created. A consumer must depend on that provider.", "Each plan item must name concrete existing source/test paths in required_read. planned_write_areas is optional: use stable component directories or files only when they help coordinate parallel Work; it is never a write allowlist. Reference every owned R-* and AC-* in one or more items; every AC-* needs an observable acceptance proof.", "For every selected check, inspect its command's launch path and the runtime entrypoints it starts. The fixture/reset process, service process and client process must observe one intended environment and data world. If a required runtime entrypoint needs a code change, make that change explicit in the Work task and its verification. Use planned_write_areas only to advertise likely concurrent overlap; do not treat it as ownership or assume another Work will repair an omitted change. If an independent infrastructure Work is clearer, plan that Work explicitly and order consumers after it.", reviewGroupingRule, "Complete compact contract and schema paths:", `- protocol plan schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "vnext-protocol-plan.schema.json")}`, `- aspect map schema: ${path.join(run.workspace_root, ".memory-bank", "dd-flow", "schemas", "plan-aspect-map.schema.json")}`, "Minimal valid protocol-plan shape:", "```json", JSON.stringify(planExample(protocols[0]), null, 2), "```", "Minimal valid aspect-map shape:", "```json", JSON.stringify(aspectMapExample(protocols[0]), null, 2), "```", "</output_contract>", "", "<execution_commands>", "PLAN never launches independent reviewers or registers CODE Work.", "If PLAN needs a material user decision with no reasonable default, run this exact one-command heredoc, replacing only its placeholder body. The heredoc is the permitted stdin form; do not use cat, a pipe, a temporary file or a second shell command:", "```sh", pauseCommandTemplate, "```", "Ask the returned user_message, stop, and resume this same PLAN Work with the exact returned command.", "Validate both partially filled drafts after completing their semantic fields:", ...validationCommands.map((command) => `- ${command}`), "Finish PLAN only after all questions are resolved and both validation commands pass:", finishCommand, "The response returns the only PLAN-REVIEW start command. Follow it; do not start CODE directly.", "</execution_commands>", "", "<stage_instructions>", template, "</stage_instructions>", ""].join("\n");
     const artifactMaterialization = { status: "materialized", completeness: "partially_filled", plan_paths: planPaths, aspect_map_paths: mapPaths, cli_owned_plan_fields: ["schema_id", "plan_id", "protocol_id", "revision", "source_refs"], cli_owned_aspect_map_fields: ["schema_id", "protocol_id", "plan_id", "plan_revision", "catalog_ref", "aspects[].aspect_id"], validation_commands: validationCommands };
     const promptPath = path.join(root, "stage-prompt.md");
-    fs.writeFileSync(promptPath, prompt);
+    // This explicit final rule supersedes historical pack wording: a flow gate
+    // has only executable autonomous evidence. Human or external confirmation
+    // is neither a check nor a permitted completion condition.
+    fs.writeFileSync(promptPath, `${prompt}\n<verification_rule>Every flow check must be an autonomous executable command. Do not declare external/manual proof or a human review as a check, evidence substitute, DEF, or gate. The only user interaction supported by this flow is an explicit stage pause for a material unanswered question.</verification_rule>\n`);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     fs.writeFileSync(path.join(root, "work-context.json"), JSON.stringify({ schema_id: "dd-flow/work-context@1", system: { run_id: run.id, work_id: planWorkId, stage: "plan" }, workspace: { project_root: projectRoot, workspace_root: run.workspace_root, stage_root: root }, artifacts: artifactMaterialization, input: { protocols, owned_obligations: Object.fromEntries(owned) } }, null, 2));
     const binding = bindStageCoordinatorWork(context, { workId: planWorkId, hookEventId: input.hookEventId, stage: "plan", promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.54",
+  "version": "0.9.0-beta.56",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {

package/tools/repair-paused-run-status.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/* global process, console */
+// Explicit repair of legacy fenced RUN projections; no migrations or process control.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { DatabaseSync } from 'node:sqlite';
+import { registerStoreWriter } from '../dist/storage/writer-contract.js';
+import { setFlowRunRecoveryPaused, completeFlowRun } from '../dist/services/runs.js';
+
+const { values } = parseArgs({ options: { home: { type: 'string' }, run: { type: 'string' }, project: { type: 'string' }, apply: { type: 'boolean', default: false }, 'cancel-abandoned': { type: 'boolean', default: false } } });
+if (!values.home || !values.run || !values.project) throw new Error('Usage: --home <runtime> --project <project-id> --run <run-id> [--apply]');
+const home = fs.realpathSync(values.home), file = path.join(home, 'db.sqlite');
+const db = new DatabaseSync(file, { readOnly: !values.apply });
+let runtimePath, original, backup, report, changed = false;
+try {
+  db.exec('PRAGMA busy_timeout=4000');
+  if (values.apply) { registerStoreWriter(db); db.exec('BEGIN IMMEDIATE'); }
+  const run = db.prepare('SELECT * FROM runs WHERE project_id=? AND id=?').get(values.project, values.run);
+  if (!run) throw new Error('RUN not found');
+  const guard = db.prepare('SELECT * FROM run_recovery_guards WHERE project_id=? AND run_id=? ORDER BY generation DESC LIMIT 1').get(values.project, values.run);
+  const cancel = values['cancel-abandoned'];
+  if (cancel) {
+    if (fs.existsSync(run.project_root)) throw new Error('Abandoned-fixture cancellation requires an absent project directory');
+    for (const table of ['works', 'sessions', 'run_controllers']) {
+      if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table)) continue;
+      if (db.prepare(`SELECT 1 FROM ${table} WHERE project_id=? AND run_id=? LIMIT 1`).get(values.project, values.run)) throw new Error('Abandoned-fixture cancellation requires no Work, Session or controller history');
+    }
+    if (guard) throw new Error('A recovery-owned RUN requires recovery reconciliation');
+  }
+  if (!cancel && !["draining", "sealed", "resuming"].includes(guard?.status)) throw new Error("Repair requires the current recovery to fence productive admission");
+  if (run.status !== 'running') {
+    report = { run_id: run.id, status: run.status, changed: false };
+  } else {
+    runtimePath = fs.realpathSync(run.runtime_path);
+    const relative = path.relative(home, runtimePath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Runtime file is outside the selected home');
+    original = fs.readFileSync(runtimePath);
+    if (JSON.parse(original).status !== 'running' || JSON.parse(run.index_json).status !== 'running') throw new Error('RUN projections disagree; manual review required');
+    if (values.apply) {
+      backup = `${runtimePath}.status-repair-${crypto.randomUUID()}.json`;
+      fs.writeFileSync(backup, JSON.stringify({ recovery_id: guard?.recovery_id ?? null, row: run, runtime: original.toString('utf8') }), { flag: 'wx', mode: 0o600 });
+      const context = { ddFlowHome: home, env: { ...process.env, DD_FLOW_HOME: home }, now: () => new Date().toISOString(), db: {
+        path: file, writable: true, get: (sql, params = []) => db.prepare(sql).get(...params), all: (sql, params = []) => db.prepare(sql).all(...params), run: (sql, params = []) => db.prepare(sql).run(...params), exec: sql => db.exec(sql)
+      } };
+      changed = true;
+      if (cancel) completeFlowRun(context, { projectRoot: run.project_root, runId: run.id, status: 'cancelled', manualOverrideReason: 'Operator requested cleanup of abandoned fixture: project removed; no Work, Session or controller history.' });
+      else setFlowRunRecoveryPaused(context, values.project, values.run, true);
+    }
+    report = { run_id: run.id, from: 'running', to: cancel ? 'cancelled' : 'paused', recovery_id: guard?.recovery_id ?? null, applied: values.apply, backup };
+  }
+  if (values.apply) db.exec('COMMIT');
+  console.log(JSON.stringify(report));
+} catch (error) {
+  if (values.apply && db.isTransaction) db.exec('ROLLBACK');
+  if (changed && original) { const temporary = `${runtimePath}.repair-rollback`; fs.writeFileSync(temporary, original); fs.renameSync(temporary, runtimePath); }
+  throw error;
+} finally { db.close(); }