@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.137

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.137
+
+- Preserve shared reasoning/mode options in OpenCode v2 and support non-generative doctor before daemon startup.
+
+### Patch Changes
+
+- e65a615: Retain scoped native child failures through read-only ZCode observation and durable dispatch fences. Bind failure provenance to current Work/Session/controller identities. Publish materialized PROTOCOLIZE evidence separately from authored input, and replay completed stages without revalidating an archived worktree or regressing later stages.
+
 ## 0.9.0-beta.136
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.136",
-  "cli_commit": "2a01d3ee7f3ae52b3fc8c43ad88b5e6bcd5104aa",
-  "built_at": "2026-10-13T21:36:08.226Z",
+  "cli_version": "0.9.0-beta.137",
+  "cli_commit": "3a1e4cb4a0a24e388228ebb85591350fa4f5886b",
+  "built_at": "2026-10-14T05:52:24.329Z",
   "built_with_canon": {
     "version": "4.1.2",
     "commit": "1ddedf9d3f086e046f8e7b194c739ec386e7c8b9",

package/dist/harness-runtime/DD-ZCODE.md

@@ -18,6 +18,19 @@ closed transport is not proof that its native descendants stopped. The adapter
 must retain causal errors, missing observations and usage completeness rather
 than turn them into successful/zero-valued results.
 
+## Retained child observations
+
+Daemon capability `retained_child_observation` enables `session observe-children`
+for its registered root. It reads retained topology and exact terminal metadata,
+never loads/resumes a child or performs semantic work. During fanout the controller
+records failed child facts before dispatching anything else; healthy in-flight
+siblings may settle normally. Observation polling is not productive model activity.
+Ordinary `session inspect` is not a substitute for this read-only operation.
+
+Native attribution is a reported fact, not proof that an HTTP request reached a
+provider. If the native store discarded the causal exception, retain unknown;
+do not scrape ambient logs or infer overload/retry authority from an error message.
+
 The bridge marks heuristic ACP completion with
 `_meta.zcodeCompletionEvidence: "inferred"` and exhausted failed turns with
 `"failed"`. dd-zcode rejects these before any post-turn materializing read:

package/dist/harness-runtime/bin/dd-opencode.mjs

@@ -2,19 +2,19 @@
 import { adapterTimeoutOptions } from "../lib/adapter-timeouts.mjs";
 import { durableDaemonStart, inspectDaemonOperation, interruptDaemonOperation, settleDaemonOperation } from "../lib/daemon-operations.mjs";
 import { readFile } from "node:fs/promises";
-import { callDaemon, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-opencode-daemon.mjs";
+import { callDaemon, doctor, openCodeProfileOptions, serveDaemon, startDaemon, stopDaemon } from "../lib/dd-opencode-daemon.mjs";
 
 function parse(argv) { const positional = [], options = {}; for (let i = 0; i < argv.length; i += 1) { const token = argv[i]; if (!token.startsWith("--")) { positional.push(token); continue; } const key = token.slice(2); if (["json","cancel-tree","no-flow"].includes(key)) options[key] = true; else { if (argv[i + 1] === undefined) throw new Error(`--${key} requires a value`); options[key] = argv[++i]; } } return { positional, options }; }
 const prompt = async options => options["prompt-file"] ? await readFile(options["prompt-file"], "utf8") : options.prompt;
 try {
-  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, bin: options["opencode-bin"], provider: options.provider, model: options.model, variant: options.variant, agent: options.agent, authPath: options["auth-path"], configPath: options["config-path"], projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, sessionArchive: options["session-archive"], ...adapterTimeoutOptions(options, family === "session" ? command : null) }; let result;
+  const { positional, options } = parse(process.argv.slice(2)), [family, command, modifier] = positional; const common = { journal: options.journal, stateDir: options["state-dir"], sessionId: options["session-id"], cwd: options.cwd, bin: options["opencode-bin"], provider: options.provider, model: options.model, ...openCodeProfileOptions(options), authPath: options["auth-path"], configPath: options["config-path"], projectRoot: options["project-root"], ddFlowBin: options["dd-flow-bin"], ddFlowHome: options["dd-flow-home"], noFlow: options["no-flow"] === true, sessionArchive: options["session-archive"], ...adapterTimeoutOptions(options, family === "session" ? command : null) }; let result;
   if (family === "daemon" && command === "start") result = await durableDaemonStart({ ...common, entryPath: process.argv[1] }, startDaemon);
   else if (family === "daemon" && command === "serve") { await serveDaemon(common.stateDir); process.exit(0); }
   else if (family === "daemon" && command === "status") result = await callDaemon(common.stateDir, "daemon.status");
   else if (family === "daemon" && command === "operation" && modifier === "interrupt") result = await interruptDaemonOperation(common.stateDir, options["operation-id"], { control_id: options["control-id"], stop_operation_id: options["stop-operation-id"], daemon_id: options["daemon-id"], session_id: options["session-id"], evidence: options.evidence ? JSON.parse(options.evidence) : null });
   else if (family === "daemon" && command === "operation" && modifier === "settle") result = await settleDaemonOperation(common.stateDir, options["operation-id"]);
   else if (family === "daemon" && command === "operation") result = await inspectDaemonOperation(common.stateDir, options["operation-id"]);
-  else if (family === "doctor") result = await callDaemon(common.stateDir, "daemon.doctor");
+  else if (family === "doctor") result = await doctor(common);
   else if (family === "daemon" && command === "stop") result = await stopDaemon({ stateDir: common.stateDir, cancelTree: options["cancel-tree"], timeoutMs: common.timeoutMs });
   else if (family === "session") { const operation = command === "status" ? "inspect" : command; const params = { livenessTimeoutMs: common.livenessTimeoutMs, sessionId: options["session-id"], title: options.title, messageId: options["message-id"], archiveFile: options["archive-file"], ...(command === "prompt" ? { prompt: await prompt(options) } : {}) }; result = await callDaemon(common.stateDir, `session.${operation}`, params, common.timeoutMs ?? 1_800_000); }
   else throw new Error("usage: dd-opencode daemon start|status|stop | session create|prompt|inspect|fork|cancel|archive [options] --json");

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

@@ -22,6 +22,19 @@ import { prepareRuntimeOwner, cleanupFailedStart, confirmDaemonProcess, confirmD
 const REQUEST_SCHEMA = "dd-opencode/daemon-request@1", RESPONSE_SCHEMA = "dd-opencode/daemon-response@1", STATE_SCHEMA = "dd-opencode/daemon-state@2", ARCHIVE_SCHEMA = "dd-opencode/session-archive@2";
 class DaemonError extends Error { constructor(code, message, retryable = false, details) { super(message); this.code = code; this.retryable = retryable; this.details = details; } }
 const absolute = (value, label) => { if (!value || !path.isAbsolute(value)) throw new DaemonError("invalid_path", `${label} must be an absolute path`); return path.resolve(value); };
+export function openCodeProfileOptions(options) {
+  for (const [native, shared] of [["variant", "reasoning"], ["agent", "mode"]]) {
+    if (options[native] !== undefined && options[shared] !== undefined && options[native] !== options[shared]) throw new DaemonError("profile_conflict", `--${native} and --${shared} disagree`);
+  }
+  return { variant: options.variant ?? options.reasoning, agent: options.agent ?? options.mode };
+}
+export async function doctor(options) {
+  if (options.stateDir) return await callDaemon(options.stateDir, "daemon.doctor");
+  const output = (await run(options.bin ?? process.env.DD_OPENCODE_BIN ?? "opencode", ["--version"], { cwd: options.cwd ?? process.cwd() })).trim();
+  const version = output.match(/(?:^|\s)v?(2\.\d+\.\d+(?:[-+][\w.-]+)?)(?:\s|$)/)?.[1];
+  if (!version) throw new DaemonError("unsupported_version", "dd-opencode supports OpenCode v2 only");
+  return { compatible: true, native_protocol: 2, observed_runtime: { opencode: version }, productive_hooks: false, profile_observation: "pending_native_session" };
+}
 function locations(stateDir) { const dir = absolute(stateDir, "--state-dir"), local = path.join(dir, "daemon.sock"); return { dir, socket: Buffer.byteLength(local) < 100 ? local : `/tmp/dd-opencode-${createHash("sha256").update(dir).digest("hex").slice(0, 20)}.sock`, state: path.join(dir, "daemon.json"), journal: path.join(dir, "events.jsonl"), log: path.join(dir, "daemon.log"), data: path.join(dir, "xdg-data"), config: path.join(dir, "xdg-config"), cache: path.join(dir, "xdg-cache"), archive: path.join(dir, "import.json"), db: path.join(dir, "native.db"), xdgState: path.join(dir, "xdg-state") }; }
 const writeJson = writeJsonAtomic;
 async function readState(dir) { try { return JSON.parse(await readFile(locations(dir).state, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
@@ -272,7 +285,7 @@ export class Runtime {
       if (info.pid !== this.child?.pid || info.version !== this.state.versions.opencode) throw new DaemonError("foreign_server", "OpenCode endpoint is not the owned process");
       const pluginID = this.state.config.noFlow ? "dd-flow-security" : "dd-flow";
       if (!plugins.data.some(plugin => plugin.id === pluginID && plugin.state?.status === "active")) throw new DaemonError("opencode_plugin_missing", "Owned v2 plugin is not active");
-      return { compatible: true, native_protocol: 2, productive_hooks: !this.state.config.noFlow, versions: this.state.versions, plugin_sha256: this.state.config.pluginSha256, auth_status: this.state.auth_status };
+      return { compatible: true, native_protocol: 2, observed_runtime: this.state.versions, productive_hooks: !this.state.config.noFlow, versions: this.state.versions, plugin_sha256: this.state.config.pluginSha256, auth_status: this.state.auth_status };
     }
     if (operation === "session.create") return this.productive(operation, async () => {
       const info = await this.client.create(params.title, this.state.config);

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

@@ -24,6 +24,7 @@ import {
   promptSessionWithBridge,
   zcodeChildSessionIds,
   observeClosedZcodeTree,
+  readZcodeSubagents,
 } from "./dd-zcode.mjs";
 
 const REQUEST_SCHEMA = "dd-zcode/daemon-request@1";
@@ -203,6 +204,7 @@ export async function stopDaemon(options) {
 export class DaemonRuntime {
   constructor(paths, state, bridge, initialized) {
     this.paths = paths; this.state = state; this.bridge = bridge; this.initialized = initialized;
+    this.state.capabilities = { ...(this.state.capabilities ?? {}), retained_child_observation: true };
     this.sessions = new Map((state.sessions ?? []).map((item) => [item.provider_session_id, item]));
     this.liveAdapters = new Set();
     this.activeProductive = null; this.server = null; this.persisting = Promise.resolve();
@@ -439,13 +441,46 @@ export class DaemonRuntime {
 
   async dispatch(operation, params, operationId = null) {
     if (["session.create", "session.prompt", "session.start", "session.fork", "session.resume"].includes(operation)) assertDaemonDispatch(this.paths.dir);
+    if (operation === "session.observe-children") {
+      assertDaemonDispatch(this.paths.dir);
+      const root = this.sessions.get(params.sessionId);
+      if (!root || root.close_receipt) throw new DaemonError("session_identity_mismatch", "Retained observation requires a registered open root Session");
+      const generation = this.controlGeneration ?? 0;
+      const active = this.state.active_request;
+      const activeIdentity = value => JSON.stringify([value?.operation_id ?? null, value?.session_id ?? null, value?.adapter_session_id ?? null, value?.generation ?? null]);
+      const capturedIdentity = activeIdentity(active);
+      if (active && active.session_id !== params.sessionId) throw new DaemonError("session_identity_mismatch", "Retained observation has a foreign active root");
+      const cacheScope = `${params.sessionId}:${generation}`;
+      if (this.childObservationScope !== cacheScope) { this.childObservationScope = cacheScope; this.childTerminalCache = new Map(); this.childObservationKeys = new Set(); }
+      const subagents = await readZcodeSubagents(this.bridge, root.adapter_session_id, 30_000, true, this.childTerminalCache);
+      if (generation !== (this.controlGeneration ?? 0)) throw new DaemonError("operation_cancelled", "Observation generation was retired");
+      if (activeIdentity(this.state.active_request) !== capturedIdentity) throw new DaemonError("operation_cancelled", "Observation belongs to a retired active Turn");
+      assertDaemonDispatch(this.paths.dir);
+      const receipt = { schema_id: "dd-zcode/child-observation@1", daemon_id: this.state.daemon_id, provider_session_id: params.sessionId,
+        generation, active_operation_id: active?.operation_id ?? null, subagents };
+      const failed = (subagents.ended?.items ?? subagents.completed ?? []).filter(child => child.status === "failed" && child.terminal_turn_id);
+      const fresh = failed.filter(child => !this.childObservationKeys.has(`${child.childSessionId}:${child.terminal_turn_id}`));
+      if (fresh.length) {
+        await this.bridge.journal.write("native_child_observation", { ...receipt, subagents: { running: [], ended: { total: fresh.length, items: fresh } } });
+        await this.bridge.journal.flush();
+        if (this.state.config?.journal) {
+          const journal = await open(this.state.config.journal, "a");
+          try { await journal.sync(); } finally { await journal.close(); }
+        }
+        for (const child of fresh) this.childObservationKeys.add(`${child.childSessionId}:${child.terminal_turn_id}`);
+      }
+      if (generation !== (this.controlGeneration ?? 0)) throw new DaemonError("operation_cancelled", "Observation generation was retired before ACK");
+      if (activeIdentity(this.state.active_request) !== capturedIdentity) throw new DaemonError("operation_cancelled", "Observation Turn changed before ACK");
+      assertDaemonDispatch(this.paths.dir);
+      return receipt;
+    }
     if (operation === "daemon.status") return {
       daemon_id: this.state.daemon_id, pid: process.pid, socket: this.paths.socket,
       cwd: this.state.cwd, journal: this.state.journal, versions: this.state.versions,
       started_at: this.state.started_at, updated_at: this.state.updated_at,
       shutdown_state: this.state.shutdown_state, recovery_status: this.state.recovery_status,
       active_tree: this.state.active_tree, active_operation: this.activeProductive, active_request: this.state.active_request ?? null,
-      sessions: [...this.sessions.values()], config: this.state.config,
+      sessions: [...this.sessions.values()], config: this.state.config, capabilities: { retained_child_observation: true },
     };
     if (operation === "hook.resolve") {
       const sessionId = String(params.sessionId ?? "");

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

@@ -544,7 +544,7 @@ async function resume(bridge, sessionId, cwd) {
 
 /** Ended children are paginated by the native API (20 by default). A partial
  * directory is never settlement evidence, including during teardown. */
-export async function readZcodeSubagents(bridge, sessionId, timeoutMs = 30_000, retained = false) {
+export async function readZcodeSubagents(bridge, sessionId, timeoutMs = 30_000, retained = false, terminalCache = new Map()) {
   const clock = new ObservationClock({ timeoutMs });
   const cursors = new Set(), ended = new Map();
   let first, cursor;
@@ -575,6 +575,8 @@ export async function readZcodeSubagents(bridge, sessionId, timeoutMs = 30_000,
         if (child.status !== "failed" || !Number.isSafeInteger(child.startedAt) || child.startedAt <= 0
           || !Number.isSafeInteger(child.endedAt) || child.endedAt < child.startedAt || child.endedAt > 8.64e15) { items.push(child); continue; }
         // Closed children must never be loaded merely to explain their failure.
+        const cacheKey = JSON.stringify([child.childSessionId, child.startedAt, child.endedAt]);
+        if (terminalCache.has(cacheKey)) { items.push(terminalCache.get(cacheKey)); continue; }
         let terminal;
         try { terminal = await bridge.request("zcode/session/retainedTerminal", { sessionId: child.childSessionId, startedAt: child.startedAt, endedAt: child.endedAt }, timeoutMs); }
         catch (error) { items.push({ ...child, terminal_metadata_unavailable: error.code ?? "terminal_metadata_unavailable" }); continue; }
@@ -584,8 +586,10 @@ export async function readZcodeSubagents(bridge, sessionId, timeoutMs = 30_000,
           || terminal.startedAt !== child.startedAt || terminal.endedAt !== child.endedAt
           || !Number.isFinite(observedAt) || observedAt < child.startedAt || observedAt > child.endedAt) fail("ZCode terminal failure metadata has foreign identity", "native_child_turn_conflict");
         const providerError = safeNativeFailure(terminal.provider_error);
-        items.push({ ...child, terminal_turn_id: terminal.terminal_turn_id, terminal_observed_at: terminal.terminal_observed_at,
-          ...(providerError ? { provider_error: providerError } : {}) });
+        const item = { ...child, terminal_turn_id: terminal.terminal_turn_id, terminal_observed_at: terminal.terminal_observed_at,
+          ...(providerError ? { provider_error: providerError } : {}) };
+        terminalCache.set(cacheKey, item);
+        items.push(item);
         clock.sample(child.childSessionId);
       }
       return { ...first, ended: { total: first.ended.total, items } };

package/dist/harness-runtime/lib/opencode-plugin.mjs

@@ -29,7 +29,9 @@ export function makeOpenCodePlugin(binding, invoke = invokeNativeHook) {
       delete event.env.OPENCODE_PASSWORD; delete event.env.OPENCODE_SERVER_PASSWORD;
     });
     await ctx.tool.hook("execute.before", async event => {
-      if (event.tool !== "shell" || !binding.ddFlowBin) return;
+      if (event.tool !== "shell") return;
+      if (event.input.timeout === undefined) event.input.timeout = 0;
+      if (!binding.ddFlowBin) return;
       const budget = hookBudget(), payload = await envelope("before", event, budget);
       event.input = { ...event.input, workdir: payload.session.directory };
       const result = await deliver({ ...payload, input: event.input }, budget);

package/dist/services/controller-child-observer.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import { normalizeNativeChildren, safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
+/** A durable observation is a dispatch fence, not authority to complete Work. */
+export function retainedChildObserver(input) {
+    let active = true, pending;
+    let gap = null;
+    const retained = new Map();
+    const sameScope = (scope) => scope?.controller_id === input.scope.controller_id && scope.generation === input.scope.generation && scope.stage === input.scope.stage && scope.root_session_id === input.scope.root_session_id;
+    const normalized = (child) => {
+        if (!child || child.parent_session_id !== input.scope.root_session_id || child.status !== "failed" || typeof child.terminal_turn_id !== "string" || ![child.session_id, child.terminal_turn_id, child.source].every(value => typeof value === "string" && value.length > 0 && value.length <= 256))
+            throw new Error("native_child_observation_invalid");
+        const provider_error = safeNativeFailure(child.provider_error);
+        return { session_id: child.session_id, parent_session_id: child.parent_session_id, status: "failed", source: child.source, terminal_turn_id: child.terminal_turn_id,
+            ...(typeof child.terminal_observed_at === "string" && Number.isFinite(Date.parse(child.terminal_observed_at)) ? { terminal_observed_at: child.terminal_observed_at } : {}),
+            ...(provider_error ? { provider_error } : {}) };
+    };
+    const accept = (children) => {
+        for (const raw of children) {
+            const child = normalized(raw);
+            retained.set(`${child.session_id}:${child.terminal_turn_id}`, child);
+        }
+    };
+    if (fs.existsSync(input.file))
+        for (const line of fs.readFileSync(input.file, "utf8").split("\n").filter(Boolean)) {
+            const observation = JSON.parse(line);
+            if (sameScope(observation.scope)) {
+                if (Array.isArray(observation.children))
+                    accept(observation.children);
+                if (Object.hasOwn(observation, "gap"))
+                    gap = observation.gap ?? null;
+            }
+        }
+    const complete = (children) => {
+        if (!active)
+            return;
+        input.assertOwner();
+        const failed = children.filter(child => child.parent_session_id === input.scope.root_session_id && child.status === "failed" && child.terminal_turn_id && !retained.has(`${child.session_id}:${child.terminal_turn_id}`)).map(normalized);
+        if (!failed.length && !gap)
+            return;
+        const fd = fs.openSync(input.file, "a", 0o600);
+        try {
+            fs.writeSync(fd, `${JSON.stringify({ scope: input.scope, children: failed, gap: null })}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        accept(failed);
+        gap = null;
+    };
+    return {
+        failed: () => [...retained.values()],
+        gap: () => gap,
+        drain: () => pending ?? Promise.resolve(),
+        completePostTurn(receipt) {
+            const evidence = receipt.evidence;
+            const tree = evidence?.subagents;
+            if (receipt.provider_session_id !== input.scope.root_session_id || receipt.observation_error || evidence?.observation_error || !evidence?.read?.projection || !evidence.read.session || !tree || tree.observation_error || !Array.isArray(tree.running))
+                return false;
+            if (tree.ended ? !Array.isArray(tree.ended.items) || tree.ended.total !== tree.ended.items.length || tree.ended.nextCursor : !Array.isArray(tree.completed))
+                return false;
+            const children = normalizeNativeChildren(receipt, input.scope.root_session_id);
+            if (children.some(child => child.status === "failed" && !child.terminal_turn_id))
+                return false;
+            complete(children);
+            return true;
+        },
+        tick() {
+            if (!active || pending)
+                return;
+            pending = (async () => {
+                const children = await input.read();
+                if (!active || children === null)
+                    return;
+                complete(children);
+            })().catch(error => {
+                if (!active)
+                    return;
+                try {
+                    input.assertOwner();
+                    const code = String(error?.code ?? "observation_unavailable");
+                    gap = /^[\w-]{1,128}$/.test(code) ? code : "observation_unavailable";
+                    const fd = fs.openSync(input.file, "a", 0o600);
+                    try {
+                        fs.writeSync(fd, `${JSON.stringify({ scope: input.scope, gap })}\n`);
+                        fs.fsyncSync(fd);
+                    }
+                    finally {
+                        fs.closeSync(fd);
+                    }
+                }
+                catch { /* Lost owner cannot publish; the gap remains an explicit caller error. */ }
+                input.gap(error);
+            }).finally(() => { pending = undefined; });
+        },
+        // The caller aborts its request; a late reply cannot publish after closure.
+        close() { active = false; return pending ?? Promise.resolve(); },
+    };
+}

package/dist/services/controller-fanout.js

@@ -1,6 +1,6 @@
 import { AppError, errorRecord } from "../shared/errors.js";
 import { normalizeNativeChildren, safeNativeFailure } from "../harness-runtime/lib/native-children.mjs";
-import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey } from "./vnext-fanout.js";
+import { getVnextFanoutStatus, observeVnextNativeChildren, reconcileVnextFanout, subagentCapacityKey, verifiedNativeWorkFailure } from "./vnext-fanout.js";
 import { getFlowRunVariables } from "./runs.js";
 import { dispatchVnextPlanReview } from "./vnext-plan-review.js";
 import { resolveExecutionPolicy } from "./execution-policy.js";
@@ -54,8 +54,11 @@ export async function nextControllerFanout(context, input) {
             throw new AppError("fanout_reconciliation_required", "Native children have unresolved lifecycle ownership", 1, { issues });
     }
     let fanout = getVnextFanoutStatus(context, input).orchestration;
-    if (!fanout)
+    if (!fanout) {
+        if (input.dispatchFence)
+            throw new AppError("fanout_reconciliation_required", "Observed native failure has no current graph; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
         return { kind: "none" };
+    }
     if (fanout.state === "compatibility_required")
         throw new AppError("stage_graph_compatibility_required", "The retained graph cannot be dispatched by this controller; use the RUN's pinned engine", 1, { stage: input.stage, run_id: input.runId, graph: fanout });
     if (children.length) {
@@ -67,6 +70,8 @@ export async function nextControllerFanout(context, input) {
             return { kind: "wait", reason: "native_children_unsettled" };
         fanout = getVnextFanoutStatus(context, input).orchestration;
     }
+    if (input.dispatchFence && !fanout.works.failed)
+        throw new AppError("fanout_reconciliation_required", "Observed native failure has no proven failed Work; dispatch stays fenced", 1, { stage: input.stage, run_id: input.runId });
     if (fanout.state === "dispatch_required") {
         dispatchVnextPlanReview(context, input);
         fanout = getVnextFanoutStatus(context, input).orchestration;
@@ -88,7 +93,9 @@ export async function nextControllerFanout(context, input) {
             }
             catch { /* Missing legacy metadata is unknown. */ }
             const providerError = safeNativeFailure(receipt.provider_error);
+            const nativeBinding = verifiedNativeWorkFailure(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, parentSessionId: input.sessionId, parentWorkId: fanout.parent_work_id, workId: work.work_id, receipt });
             return { work_id: work.work_id, status: work.status, ...(providerError ? { provider_error: providerError } : {}),
+                ...(nativeBinding ? { native_binding: nativeBinding } : {}),
                 ...Object.fromEntries(["terminal_turn_id", "terminal_observed_at"].filter(key => typeof receipt[key] === "string" && receipt[key].length <= 256).map(key => [key, receipt[key]])) };
         });
         throw new AppError("fanout_child_failed", "A child Work failed or was cancelled; no retry authority has been issued", 1, { stage: input.stage, run_id: input.runId, parent_work_id: fanout.parent_work_id, failed: fanout.works.failed, cancelled: fanout.works.cancelled, failures, effect: "unknown" });

package/dist/services/run-controller.js

@@ -31,6 +31,7 @@ import { requireRun, requireController, controllerReceipt, appendEvent, saveStat
 import { assertNoCorrelatedRejection } from "./continuation-outcome.js";
 import { spawnController, recordControllerLauncher, claimControllerProcess, markControllerDispatchReady, assertControllerRecoveryAllowed } from "./run-controller-process.js";
 import { controllerAdapter, controllerEnvironment, sessionArguments } from "./run-controller-adapter.js";
+import { retainedChildObserver } from "./controller-child-observer.js";
 import { capacityDelay, continueCodexCapacity, eligibleCodexChildOverload } from "./codex-capacity.js";
 import { resumeControllerSession, failControllerRecovery } from "./run-controller-recovery.js";
 import { captureControllerBoundary } from "./run-controller-capture.js";
@@ -460,6 +461,52 @@ async function executeController(context, row, manifest, state, assertOwnership,
     let fatal;
     let stopping;
     const cancellation = new AbortController();
+    const observationCancellation = new AbortController();
+    const childObservers = new Map();
+    let promptPending = false;
+    let observedPromptOperation = null;
+    const childObserver = (session) => {
+        if (runtimeHarness(session.profile) !== "zcode-acp" || !state.stage || !["plan-review", "code", "code-review"].includes(state.stage))
+            return undefined;
+        if (readNativeDaemonState(session.state_dir).capabilities?.retained_child_observation !== true)
+            return undefined;
+        const scope = { controller_id: row.controller_id, generation: row.generation, stage: state.stage, root_session_id: session.id };
+        const key = JSON.stringify(scope);
+        let retained = childObservers.get(key);
+        if (!retained) {
+            retained = retainedChildObserver({ file: path.join(row.state_dir, "native-child-observations.jsonl"), scope, assertOwner: assertOwnership,
+                gap: error => { process.stderr.write(`${JSON.stringify({ event: "native_child_observation_gap", scope, error_code: String(error?.code ?? "observation_unavailable") })}\n`); },
+                read: async () => {
+                    assertOwnership();
+                    const operation = observedPromptOperation;
+                    const binding = requireManagedDaemonBinding(executionContext, { stateDir: session.state_dir, projectId: row.project_id, runId: row.run_id });
+                    let receipt;
+                    try {
+                        receipt = await runHarnessAdapter({ executable: manifest.adapters["zcode-acp"].executable,
+                            args: ["session", "observe-children", "--session-id", session.id, ...sessionArguments(context, manifest, session)],
+                            env: controllerEnvironment(context, manifest, session), operationId: crypto.randomUUID(), harness: "zcode", timeoutMs: 30_000,
+                            signal: AbortSignal.any([cancellation.signal, observationCancellation.signal]) });
+                    }
+                    catch (error) {
+                        if (!promptPending || observedPromptOperation !== operation)
+                            return null;
+                        throw error;
+                    }
+                    if (!promptPending || observedPromptOperation !== operation || receipt.active_operation_id === null)
+                        return null;
+                    if (receipt.schema_id !== "dd-zcode/child-observation@1" || receipt.provider_session_id !== session.id || receipt.daemon_id !== binding.state.daemon_id)
+                        throw new AppError("native_child_observation_conflict", "Retained child observation has foreign daemon/root identity", 1);
+                    if (receipt.active_operation_id !== operation)
+                        throw new AppError("native_child_observation_conflict", "Retained observation has a foreign productive operation", 1);
+                    const children = controllerNativeChildren(receipt, session.id).filter(child => !(state.native_baseline ?? []).includes(child.session_id));
+                    if (children.some(child => child.status === "failed" && !child.terminal_turn_id))
+                        throw new AppError("operation_observation_lost", "Retained child terminal identity is unavailable", 1);
+                    return children;
+                } });
+            childObservers.set(key, retained);
+        }
+        return retained;
+    };
     const capacityUncertain = (error) => error instanceof AppError && ["capacity_continuation_blocked", "operation_observation_lost"].includes(error.code) && error.details.capacity_uncertainty === true || Boolean(state.pending_capacity) && (String(error?.code) === "capacity_continuation_blocked" || isObservationLoss(error));
     const stopAfterFailure = (error) => {
         // A retained successor may already be running. Fencing/recovery records
@@ -492,10 +539,15 @@ async function executeController(context, row, manifest, state, assertOwnership,
         }).finally(() => cancellation.abort());
         return stopping;
     };
-    const setStatus = (status) => {
-        const changed = context.db.run("UPDATE run_controllers SET status = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status <> ?", [status, context.now(), row.controller_id, row.owner_token, status]);
-        if (changed.changes)
-            appendEvent(context, row.controller_id, "status_changed", { status, stage: state.stage });
+    const setStatus = (status, terminalData) => {
+        context.db.writeTransaction(() => {
+            const changed = context.db.run("UPDATE run_controllers SET status = ?, updated_at = ? WHERE controller_id = ? AND owner_token = ? AND status <> ?", [status, context.now(), row.controller_id, row.owner_token, status]);
+            if (changed.changes) {
+                appendEvent(context, row.controller_id, "status_changed", { status, stage: state.stage });
+                if (terminalData)
+                    appendEvent(context, row.controller_id, status, terminalData);
+            }
+        });
     };
     const call = (session, args, productive = true) => controllerAdapter(executionContext, row, manifest, session, args, productive ? assertOwner : undefined, undefined, productive ? cancellation.signal : undefined, productive ? renewLease : undefined);
     const confirmStopped = async (stateDir, receipt) => {
@@ -575,7 +627,17 @@ async function executeController(context, row, manifest, state, assertOwnership,
                         throw new AppError("capacity_continuation_conflict", "Retained capacity root has no failure receipt", 1);
                     throw JSON.parse(root.error_json);
                 }
-                receipt = await send(text, firstOperationId);
+                if (childObserver(session)?.failed().length)
+                    throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids another coordinator dispatch", 1);
+                promptPending = true;
+                observedPromptOperation = firstOperationId;
+                try {
+                    receipt = await send(text, firstOperationId);
+                }
+                finally {
+                    promptPending = false;
+                    observedPromptOperation = null;
+                }
             }
             catch (error) {
                 if (!["codex-desktop", "opencode-server"].includes(runtimeHarness(session.profile)))
@@ -640,6 +702,11 @@ async function executeController(context, row, manifest, state, assertOwnership,
                 receipt = resumed;
             }
             checkOutcomes();
+            await childObserver(session)?.drain();
+            childObserver(session)?.completePostTurn(receipt);
+            const observationGap = childObserver(session)?.gap();
+            if (observationGap)
+                throw new AppError("operation_observation_lost", "In-flight child observation remained unavailable at the safe Turn boundary", 1, { observation_error_code: observationGap, provider_session_id: session.id, stage: state.stage });
             if (fatal)
                 throw fatal;
         }
@@ -661,6 +728,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
             return;
         try {
             checkOutcomes();
+            if (promptPending && state.current_session !== null)
+                childObserver(state.sessions[state.current_session])?.tick();
         }
         catch (error) {
             void stopAfterFailure(error);
@@ -692,15 +761,16 @@ async function executeController(context, row, manifest, state, assertOwnership,
             const next = view.continuation;
             terminalFinalization = next.kind === "terminal";
             const completed = state.stage && view.index.stage_runs.find(stage => stage.stage === state.stage && ["done", "skipped"].includes(stage.status));
+            if (state.current_session !== null && (completed || next.stage !== state.stage) && childObserver(state.sessions[state.current_session])?.failed().length)
+                throw new AppError("fanout_dispatch_fenced", "A retained child failure forbids completing or advancing its Stage", 1);
             if (completed && manifest.request.stop_after === state.stage) {
                 // A bounded run is final evidence, not an entry fixture for its successor.
                 // Stop owned observers before capture; keep the controller lease/fence.
                 await settle();
                 if (manifest.request.capture_root)
                     await captureControllerBoundary(executionContext, row, manifest, completed, null, assertPhysicalOwner);
-                setStatus("stop_target_reached");
                 setFlowRunRecoveryPaused(context, row.project_id, row.run_id, true);
-                appendEvent(context, row.controller_id, "stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
+                setStatus("stop_target_reached", { stage: state.stage, attempt: completed.attempt ?? null });
                 return;
             }
             if (completed && manifest.request.capture_root && ["start_stage", "terminal"].includes(next.kind)) {
@@ -839,6 +909,8 @@ async function executeController(context, row, manifest, state, assertOwnership,
             const session = state.sessions[state.current_session];
             const baseline = new Set(state.native_baseline ?? []);
             let children = controllerNativeChildren(state.last_receipt ?? {}, session.id).filter(child => !baseline.has(child.session_id));
+            const retainedFailures = childObserver(session)?.failed() ?? [];
+            children = controllerNativeChildren({ descendants: [...children, ...retainedFailures] }, session.id);
             if (runtimeHarness(session.profile) === "codex-desktop" && children.some(child => child.status === "failed")) {
                 const inspected = await call(session, ["session", "inspect", "--session-id", session.id, ...sessionArguments(context, manifest, session)], false);
                 state.last_receipt = inspected;
@@ -941,7 +1013,7 @@ async function executeController(context, row, manifest, state, assertOwnership,
                     continue;
                 }
             }
-            const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles });
+            const fanout = await nextControllerFanout(executionContext, { projectRoot: run.project_root, runId: run.id, stage: next.stage, harness: runtimeHarness(session.profile), sessionId: session.id, children, policy, profiles, dispatchFence: retainedFailures.length > 0 });
             assertOwner();
             if (fanout.kind === "none") {
                 assertNoCorrelatedRejection(context, { projectId: row.project_id, runId: row.run_id, generation: row.generation, stage: next.stage, turn: state.turns });
@@ -1013,6 +1085,9 @@ async function executeController(context, row, manifest, state, assertOwnership,
     }
     finally {
         clearInterval(monitor);
+        const drainedObservations = [...childObservers.values()].map(retained => retained.close());
+        observationCancellation.abort();
+        await Promise.allSettled(drainedObservations);
         if (stopping)
             await stopping;
         observer.db.close?.();

package/dist/services/stage-lifecycle.js

@@ -741,7 +741,8 @@ function buildStageReport(context, view, stage, status, semantic, stageRoot, lin
             next_action: stringValue(semantic.next_action) ?? "Resolve the stage result before continuing.",
             ...(Array.isArray(semantic.questions) ? { questions: semantic.questions } : {}),
             ...(Array.isArray(semantic.reviewer_findings) ? { reviewer_findings: semantic.reviewer_findings } : {}),
-            ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {})
+            ...(Array.isArray(semantic.def_outcomes) ? { def_outcomes: semantic.def_outcomes } : {}),
+            ...(semantic.materialization !== undefined ? { materialization: semantic.materialization } : {})
         },
         mechanical: {
             started_at: startedAt,

package/dist/services/stage-report-renderer.js

@@ -164,6 +164,19 @@ export function reconcileRunStageReports(context, projectId, runId, exceptStage)
 }
 function normalizeStageReport(report) {
     const semantic = object(report.semantic);
+    if (semantic.materialization !== undefined) {
+        const value = object(semantic.materialization);
+        const authored = object(value.authored_result);
+        const relative = (item) => typeof item === "string" && item.length > 0 && !path.isAbsolute(item) && !item.split(/[\\/]/).includes("..");
+        if (value.schema_id !== "dd-flow/protocolize-materialization@1" || value.run_id !== report.run_id || report.stage !== "protocolize" || value.stage !== "protocolize"
+            || !["create", "link", "update", "not_applicable"].includes(String(value.action)) || value.status !== "passed"
+            || authored.role !== "authored_input" || !relative(authored.run_relative_path) || !/^[a-f0-9]{64}$/.test(String(authored.sha256))
+            || !(value.feature_path === null || relative(value.feature_path)) || !Array.isArray(value.protocol_ids) || value.protocol_ids.some(id => typeof id !== "string")
+            || !Array.isArray(value.documents) || value.documents.some(item => { const ref = object(item); return !relative(ref.path) || !/^[a-f0-9]{64}$/.test(String(ref.sha256)); })
+            || !Array.isArray(value.owned_links) || value.owned_links.some(item => { const edge = object(item); return !relative(edge.feature_path) || !relative(edge.protocol_path) || !value.protocol_ids.includes(edge.protocol_id); })) {
+            throw new AppError("stage_report_materialization_invalid", "PROTOCOLIZE materialization receipt is malformed or out of scope", 1);
+        }
+    }
     const sourceArtifacts = object(report.artifacts);
     return {
         ...report,