@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

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

@@ -0,0 +1,1175 @@
+import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
+import { ToolObservations, acpToolObservation, zcodePhysicalSession } from "./tool-observations.mjs";
+import { hookBudget, invokeNativeHook } from "./native-hook-command.mjs";
+import { parseLifecycleCommand, continuationCommand, commandOption } from "./lifecycle-command.mjs";
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from 'node:fs';
+import { publishSetup, SETUP_STARTUP_MS } from './setup-progress.mjs';
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { closeBridgeProcess } from "./managed-daemon.mjs";
+import { errorRecord, isProvenShellCorrection } from "./operation-errors.mjs";
+import { checkObservedProfile, observeModel, observedFields } from "./model-observations.mjs";
+import { commandText } from "./process-json.mjs";
+import { readNativeLines, streamNativeDiagnostics, nativeObservationError } from "./native-streams.mjs";
+import { operationProgressReporter } from "./operation-progress.mjs";
+import { safeNativeFailure } from "./native-children.mjs";
+import { classifyProviderError, safeProviderError } from "./provider-overload-policy.mjs";
+
+import { readZcodeUsage } from "./zcode-usage.mjs";
+const ZCODE_HARNESS_CONTRACT = "dd-zcode-harness@1";
+export const supportedZcodeHarnessContract = contract => [ZCODE_HARNESS_CONTRACT, "dd-zcode-harness@2"].includes(contract);
+// A deadline is an observation boundary, not permission to replay an ACP
+// request.  Keep the original correlation slot briefly so a slow native
+// response (especially cold-start/session creation) can still settle it.
+const LATE_RESPONSE_GRACE_MS = 5_000;
+// Only the owned lifecycle transport can attest a persisted CLI barrier.
+// Model text and arbitrary callback error.details cannot grant correction.
+const correctableLifecycleErrors = new WeakSet();
+
+function fail(message, code) { const error = new Error(message); if (code) error.code = code; throw error; }
+function absolute(value, label) { if (!value || !path.isAbsolute(value)) fail(`${label} must be an absolute path`); return path.resolve(value); }
+function text(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} is required`); return value.trim(); }
+function now() { return new Date().toISOString(); }
+function responseSummary(message, method = null) {
+  const result = message?.result;
+  return { request_id: message?.id ?? null, method, has_result: result !== undefined,
+    result_keys: result && typeof result === "object" && !Array.isArray(result) ? Object.keys(result).slice(0, 32) : [], error: message?.error ?? null };
+}
+
+function executable(command, args = []) {
+  const resolved = command ?? process.env.DD_ZCODE_ACP_BIN ?? "zcode-acp";
+  return /\.[cm]?js$/.test(resolved) ? { command: process.execPath, args: [resolved, ...args] } : { command: resolved, args };
+}
+
+async function commandOutput(command, args) {
+  const target = executable(command, args);
+  return await commandText(target.command, target.args, { phase: "native-version" });
+}
+
+async function runWithStdin(command, args, stdin, env = {}) {
+  const target = executable(command, args);
+  return await commandText(target.command, target.args, { input: stdin, env, phase: "usage-ingest" });
+}
+
+class Journal {
+  constructor(file) {
+    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;
+    const line = JSON.stringify({ order: ++this.order, observed_at: now(), kind, payload });
+    this.pending = this.pending.then(() => appendFile(this.file, `${line}\n`));
+    void this.pending.catch(() => {});
+    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`);
+    });
+    void this.pending.catch(() => {});
+    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;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.allocationObservers = new Map();
+    this.lateResponses = new Map();
+    this.expiredRequests = new Map();
+    this.sessionActivity = new Map();
+    this.notifications = Promise.resolve();
+    this.terminalOutcomes = Promise.resolve();
+    this.terminalRequests = new Map();
+    this.connectionId = randomUUID();
+    this.receivedSequence = 0;
+    this.lifecycleNotifications = new Set();
+    this.notificationError = null;
+    this.bridgeStderr = "";
+    this.toolObservations = new ToolObservations();
+    this.assistantText = new Map();
+    this.journal = new Journal(options.journal);
+    this.modelSessions = new Map(); this.modelProfiles = new Map();
+  }
+
+  configure(options) { this.options = { ...this.options, ...options }; }
+  registerModelSession(adapterId, sessionId, requested, parentSessionId = null, armed = true, bindCurrentRequest = false) {
+    const parentAdapter = parentSessionId ? [...this.modelSessions].find(([key, value]) => key === parentSessionId || value.sessionId === parentSessionId)?.[0] : null;
+    const parentRequest = this.activityOwner(parentAdapter);
+    const prior = this.modelSessions.get(adapterId);
+    this.modelSessions.set(adapterId, { sessionId, requested, parentSessionId, armed, parentRequestId: prior && !bindCurrentRequest ? prior.parentRequestId ?? null : parentRequest?.id ?? null });
+  }
+  async recordModel(adapterId, observed, source) {
+    const identity = this.modelSessions.get(adapterId); if (!identity) return;
+    this.modelProfiles.set(identity.sessionId, observed);
+    await observeModel({ journal: this.options.journal, harness: this.options.clientInfo?.name === "dd-grok" ? "grok-acp" : "zcode-acp",
+      sessionId: identity.sessionId, parentSessionId: identity.parentSessionId, requested: identity.requested, observed, source: typeof source === "string" ? { channel: source, scope: "configured", raw_model: observed.raw_model ?? observed.model, raw_provider: observed.provider } : source });
+  }
+  async observeModelUpdate(message) {
+    const update = message.params?.update;
+    if (update?.sessionUpdate !== "config_option_update" || !Array.isArray(update.configOptions)) return;
+    const value = category => update.configOptions.find(option => option.type === "select" && (option.category === category || option.id === category))?.currentValue ?? null;
+    const raw = value("model");
+    const model = this.options.clientInfo?.name === "dd-grok" ? { model: raw } : zcodeModelSelector(raw);
+    const observed = { ...model, reasoning: value("thought_level"), mode: value("mode") };
+    const identity = this.modelSessions.get(message.params.sessionId); if (!identity?.armed) return;
+    checkObservedProfile(identity.requested, observed);
+    await this.recordModel(message.params.sessionId, observed, "acp.config_option_update");
+  }
+
+  async start() {
+    const target = executable(this.options.bin, this.options.commandArgs ?? ["server"]);
+    const cwd = this.options.cwd ? absolute(this.options.cwd, "--cwd") : process.cwd();
+    this.child = spawn(target.command, target.args, { cwd, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, ...(this.options.env ?? {}) } });
+    this.diagnostics = streamNativeDiagnostics(this.child.stderr, async chunk => { this.bridgeStderr = (this.bridgeStderr + chunk).slice(-65_536); await this.journal.write("bridge_stderr", { text: chunk }); }, error => this.rejectAll(error));
+    this.child.stdin?.on("error", (error) => {
+      error.details = { system_code: error.code ?? null };
+      error.code = "bridge_pipe_broken";
+      this.rejectAll(error);
+    });
+    this.child.on("error", (error) => { error.code ??= "bridge_exited"; this.rejectAll(error); });
+    this.child.on("close", code => { void Promise.all([this.nativeDrain, this.diagnostics]).then(() => { const error = new Error(`zcode-acp exited ${code}${this.bridgeStderr.trim() ? `: ${this.bridgeStderr.trim()}` : ""}`); error.code = "bridge_exited"; this.rejectAll(error); }); });
+    this.nativeDrain = readNativeLines(this.child.stdout, async line => { this.receive(line); await this.journal.flush(); }, error => this.rejectAll(error));
+    if (this.options.onSpawn) await this.options.onSpawn(this.child);
+    publishSetup('probe_started', 'native-initialize');
+    const initialized = await this.request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, elicitation: { form: {} } },
+      clientInfo: this.options.clientInfo ?? { name: "dd-zcode", version: "0.1.0" },
+    }, this.options.initializeTimeoutMs ?? SETUP_STARTUP_MS);
+    publishSetup('native_initialized', 'native-initialize');
+    return initialized;
+  }
+
+  receive(line) {
+    let message;
+    try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
+    const observation = { connection_id: this.connectionId, sequence: ++this.receivedSequence, productive: isProductiveSessionNotification(message) };
+    const request = message.id !== undefined ? this.pending.get(message.id) : null;
+    const expired = message.id !== undefined ? this.expiredRequests.get(message.id) : null;
+    const isResponse = message.id !== undefined && !message.method;
+    const rejected = isResponse && this.rejectedHookRequests?.get(message.id);
+    if (rejected || isResponse && (request?.method === "session/prompt" || this.terminalRequests.has(message.id))) {
+      const owner = rejected ?? request ?? this.terminalRequests.get(message.id);
+      const terminal = { request_id: message.id, method: owner.method, session_id: owner.sessionId, terminal_response: message,
+        connection_id: this.connectionId, operation_id: owner.operationId ?? null, generation: owner.generation ?? null, native_sequence: observation.sequence };
+      this.terminalOutcomes = this.terminalOutcomes.then(async () => {
+        await this.journal.write(rejected ? "native_terminal_after_hook_failure" : "native_terminal_outcome", terminal);
+        await this.journal.flush();
+        await this.options.onTerminalOutcome?.(terminal);
+        this.terminalRequests.set(message.id, owner);
+        while (this.terminalRequests.size > 128) this.terminalRequests.delete(this.terminalRequests.keys().next().value);
+        if (rejected) this.rejectedHookRequests.delete(message.id);
+      });
+      void this.terminalOutcomes.catch(storage => { this.terminalProjectionError ??= storage; if (rejected) rejected.error.cleanup_error ??= errorRecord(storage); });
+      if (rejected) {
+      rejected.error.details = { ...rejected.error.details, native_terminal_after_hook_failure: terminal };
+      }
+    }
+    if (!isResponse || request) this.journal.writeInbound(message, request?.method);
+    if (typeof message.params?.sessionId === "string" && isProductiveSessionNotification(message)) this.observeActivity(message.params.sessionId, message.params.update);
+    const update = message.params?.update;
+    // ZCode emits this as `session/update`; Grok Build wraps the same ACP
+    // payload in `_x.ai/session_notification`.  Preserve either provider's
+    // native error before its generic JSON-RPC terminal response arrives.
+    if (typeof message.params?.sessionId === "string" && update?.sessionUpdate === "retry_state") {
+      for (const pending of this.pending.values()) {
+        if (pending.method === "session/prompt" && pending.sessionId === message.params.sessionId) {
+          pending.nativeRetryActive = update.type !== "failed";
+          if (update.type === "failed") pending.providerError = { ...update, observed_at: now(), provider_session_id: pending.sessionId, source: message.method };
+        }
+      }
+    }
+    if (message.method === "session/update" && message.params?.update?.sessionUpdate === "agent_message_chunk" && message.params.update.content?.type === "text") {
+      const sessionId = message.params.sessionId;
+      this.assistantText.set(sessionId, `${this.assistantText.get(sessionId) ?? ""}${message.params.update.content.text ?? ""}`);
+    }
+    if (message.method === "zcode/session/allocated") {
+      const identity = message.params;
+      const observer = this.allocationObservers.get(identity?.adapter_session_id);
+      if (observer && typeof identity?.provider_session_id === "string" && identity.provider_session_id.length > 0) {
+        this.allocationObservers.delete(identity.adapter_session_id);
+        this.notifications = this.notifications.then(() => observer(identity));
+        void this.notifications.catch(error => { this.notificationError ??= error; });
+      }
+    }
+    this.observeToolCall(message);
+    if (message.method === "session/update" && this.options.onLifecycleNotification) {
+      const observer = this.options.onLifecycleNotification;
+      const pending = Promise.resolve().then(() => observer(message)).catch(async error => {
+        // A validated no-effect rejection is returned through the invocation
+        // ledger. It is evidence, not a poisoned ACP Session.
+        const current = this.options.onLifecycleNotification === observer;
+        const correctable = current && correctableLifecycleErrors.has(error);
+        if (current && !correctable) {
+          this.lifecycleFailure ??= this.notificationError?.code === "profile_integrity_violation" ? this.notificationError : error;
+          this.notificationError = this.lifecycleFailure;
+        }
+        // A missing/foreign authority is not a recoverable CLI validation
+        // result. Stop admitting productive requests immediately; the managed
+        // controller still owns physical stop/drain and evidence capture.
+        if (current && !correctable) this.rejectAll(this.notificationError);
+        try {
+          await hookBudget(1_000, null).run(() => this.journal.write("notification_failure", { ...errorRecord(error),
+            session_id: message.params?.sessionId ?? null, tool_call_id: update?.toolCallId ?? null, event_time: now(), delivery_stage: "lifecycle_receipt", completeness: "incomplete" }), "failure_persistence");
+        } catch (persistenceError) {
+          if (current) this.notificationError ??= persistenceError;
+          process.stderr.write(`${JSON.stringify({ code: error.code, message: error.message, persistence_error: persistenceError.message })}\n`);
+        }
+      });
+      this.lifecycleNotifications.add(pending);
+      void pending.then(() => this.lifecycleNotifications.delete(pending), () => this.lifecycleNotifications.delete(pending));
+    }
+    if (message.id !== undefined && message.method) { void this.answer(message).catch((error) => this.rejectAll(error)); return; }
+    if (message.id !== undefined) {
+      const pending = request ?? this.pending.get(message.id);
+      if (!pending) {
+        this.lateResponses.set(message.id, message);
+        while (this.lateResponses.size > 128) this.lateResponses.delete(this.lateResponses.keys().next().value);
+        this.journal.write("late_response", responseSummary(message, expired?.method ?? null));
+        return;
+      }
+      clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); this.pending.delete(message.id);
+      if (pending.timedOut) this.journal.write("late_response", { ...responseSummary(message, pending.method), grace_ms: LATE_RESPONSE_GRACE_MS });
+      if (message.error) {
+        const data = message.error.data && typeof message.error.data === "object" && !Array.isArray(message.error.data) ? message.error.data : null;
+        const details = data?.details ?? data?.message ?? data ?? null;
+        const provider = pending.providerError;
+        const providerDetails = provider?.message ?? null;
+        const messageText = [message.error.message, details, providerDetails].filter(Boolean).map(value => typeof value === "string" ? value : JSON.stringify(value)).join(": ") || JSON.stringify(message.error);
+        const error = new Error(messageText);
+        const nativeCode = typeof data?.code === "string" ? data.code : typeof data?.native_code === "string" ? data.native_code : null;
+        const unknown = ["native_timeout", "native_backend_dead", "native_backend_pipe_broken", "native_outcome_unknown"].includes(nativeCode);
+        const nativeFailure = { ...(provider ?? {}), ...(data ?? {}),
+          code: [provider?.code, data?.code, data?.native_code].filter(value => typeof value === "string").join(" "), message: messageText };
+        const category = pending.method === "session/prompt" ? classifyProviderError(nativeFailure) : "provider_failed";
+        error.code = unknown ? nativeCode : category === "provider_failed" ? "acp_request_failed" : category;
+        error.retryable = ["provider_rate_limited", "provider_capacity_transient"].includes(error.code);
+        error.details = { acp_code: message.error.code ?? null,
+          observed_at: provider?.observed_at ?? now(), provider_session_id: pending.sessionId ?? null, source: "acp.error_response", request_id: message.id,
+          terminal_response: { method: pending.method, session_id: pending.sessionId, request_id: message.id },
+          ...(pending.method === "session/prompt" ? { native_source: "acp.error_response", terminal_status: "failed", turn_id: String(message.id), native_turn_id: String(message.id), provider_error: safeProviderError(nativeFailure),
+            native_retry_active: pending.nativeRetryActive === true, will_retry: nativeFailure.willRetry === true,
+            native_turn_items: { observed: this.toolSummary(pending.sessionId).completeness === "complete", possible_effects: this.toolSummary(pending.sessionId).total > 0, pending: this.toolSummary(pending.sessionId).pending > 0 } } : {}),
+          ...(data ? { native: data } : {}), ...(details ? { provider_details: details } : {}), ...(providerDetails ? { provider_update: provider } : {}) };
+        pending.reject(error);
+      }
+      else { pending.resolve(message.result ?? {}); }
+      return;
+    }
+    if (message.method) this.notifications = this.notifications
+      .then(async () => { await this.observeModelUpdate(message); await this.options.onNotification?.(message, observation); })
+      .catch(async (error) => {
+        const failure = { code: error.code ?? "notification_observation_failed", message: error.message, ...(error.details ? { details: error.details } : {}), session_id: message.params?.sessionId ?? null, tool_call_id: message.params?.update?.toolCallId ?? null, event_time: now(), delivery_stage: "acp_evidence", completeness: "incomplete" };
+        try { await this.journal.write("notification_failure", failure); }
+        catch (persistenceError) { process.stderr.write(`${JSON.stringify({ ...failure, persistence_error: persistenceError.message })}\n`); }
+        // Evidence loss does not retroactively revoke a committed native hook.
+        // Permission/profile integrity is a separate, still-fatal contract.
+        if (error.code === "profile_integrity_violation") { this.notificationError ??= error; this.rejectAll(error); }
+      });
+  }
+
+  observeToolCall(message) {
+    const rootSessionId = this.modelSessions.get(message.params?.sessionId)?.sessionId;
+    this.toolObservations.add(acpToolObservation(message, { harness: this.options.observationHarness ?? "zcode-acp", rootSessionId }));
+  }
+
+  observeActivity(sessionId, update) {
+    const observedAt = Date.now(), seen = new Set();
+    let adapterId = sessionId;
+    // ACP has no Turn ID: scope direct notifications to the active request on
+    // this connection, and descendants to their parent's dispatch generation.
+    const owner = this.activityOwner(adapterId);
+    if (!owner) return;
+    if (["tool_call", "tool_call_update"].includes(update?.sessionUpdate)) {
+      const toolId = update.toolCallId;
+      if (!toolId) return;
+      owner.toolProgress ??= new Map();
+      const signature = JSON.stringify({ status: update.status, kind: update.kind, title: update.title, content: update.content, rawInput: update.rawInput, rawOutput: update.rawOutput });
+      const key = `${sessionId}:${toolId}`, previous = owner.toolProgress.get(key);
+      if (previous === signature) return;
+      // An empty update is only a replay/metadata snapshot, not tool work.
+      if (update.sessionUpdate === "tool_call_update" && !update.status && !update.content?.length && update.rawInput === undefined && update.rawOutput === undefined) return;
+      if (owner.toolProgress.size >= 1_024 && !owner.toolProgress.has(key)) return;
+      owner.toolProgress.set(key, signature);
+    }
+    while (adapterId && !seen.has(adapterId)) {
+      seen.add(adapterId);
+      const pending = [...this.pending.values()].find(value => value.method === "session/prompt" && value.sessionId === adapterId);
+      if (pending) {
+        pending.progress = { cursor: (pending.progress?.cursor ?? 0) + 1, observed_at: observedAt };
+        const rejectObservation = cause => {
+          if (this.pending.get(pending.id) !== pending) return;
+          clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer);
+          this.pending.delete(pending.id); pending.reject(nativeObservationError(cause));
+        };
+        void pending.publish("native_progress", { native_request_id: String(pending.id), session_id: adapterId, observed_at: new Date(observedAt).toISOString() }).catch(rejectObservation);
+        this.sessionActivity.set(adapterId, observedAt);
+        void Promise.resolve(this.options.onActivity?.({ sessionId: adapterId, requestId: pending.id, progress: pending.progress })).catch(rejectObservation);
+      }
+      const child = this.modelSessions.get(adapterId), parent = child?.parentSessionId;
+      const next = parent ? [...this.modelSessions].find(([key, value]) => key === parent || value.sessionId === parent)?.[0] : null;
+      const parentPending = this.activityOwner(next);
+      adapterId = parentPending?.id === child?.parentRequestId ? next : null;
+    }
+  }
+
+  activityOwner(sessionId) {
+    const path = [], seen = new Set();
+    while (sessionId && !seen.has(sessionId)) {
+      seen.add(sessionId);
+      const pending = [...this.pending.values()].find(value => value.method === "session/prompt" && value.sessionId === sessionId);
+      if (pending) return path.every(child => child.parentRequestId === pending.id) ? pending : null;
+      const identity = this.modelSessions.get(sessionId);
+      if (!identity?.parentSessionId) return null;
+      path.push(identity);
+      sessionId = [...this.modelSessions].find(([key, value]) => key === identity.parentSessionId || value.sessionId === identity.parentSessionId)?.[0];
+    }
+    return null;
+  }
+
+  toolSummary(sessionId) {
+    return this.toolObservations.summary(this.modelSessions.get(sessionId)?.sessionId ?? sessionId);
+  }
+  toolCursor() { return this.toolObservations.cursor(); }
+  assistantTextCursor(sessionId) { return (this.assistantText.get(sessionId) ?? "").length; }
+  assistantTextSince(sessionId, cursor) { return (this.assistantText.get(sessionId) ?? "").slice(cursor); }
+  toolSummarySince(cursor, sessionId) {
+    return this.toolObservations.summary(this.modelSessions.get(sessionId)?.sessionId ?? sessionId, cursor);
+  }
+
+  async answer(message) {
+    await this.notifications;
+    let result;
+    if (message.method === "session/request_permission") {
+      const options = message.params?.options ?? [];
+      const selected = this.options.permission === "allow" && !this.notificationError
+        ? options.find((item) => item.optionId === "allow_once") ?? options[0]
+        : options.find((item) => item.optionId === "deny");
+      result = selected ? { outcome: { outcome: "selected", optionId: selected.optionId } } : { outcome: { outcome: "cancelled" } };
+    } else if (message.method === "elicitation/create") {
+      result = this.options.answers ? { action: "accept", content: this.options.answers } : { action: "decline", reason: "dd-zcode has no declared answers" };
+    } else {
+      this.send({ jsonrpc: "2.0", id: message.id, error: { code: -32601, message: `unsupported client request: ${message.method}` } });
+      return;
+    }
+    this.journal.write("interaction", { method: message.method, params: message.params, result });
+    this.send({ jsonrpc: "2.0", id: message.id, result });
+  }
+
+  request(method, params = {}, timeoutMs = 30_000, { idleSessionId = null, idleTimeoutMs = null, inactivityMode = "reject" } = {}) {
+    if (method === "session/prompt" && (this.rejectedHookRequests?.size ?? 0) + [...this.pending.values()].filter(request => request.method === "session/prompt").length >= 32) return Promise.reject(Object.assign(new Error("Unreconciled native terminal evidence limit reached"), { code: "native_terminal_evidence_pending" }));
+    if (timeoutMs !== null) validateObservationDuration(timeoutMs);
+    if (idleTimeoutMs !== null) validateObservationDuration(idleTimeoutMs);
+    if ((this.lifecycleFailure || this.notificationError?.code === "profile_integrity_violation") && ["session/new", "session/prompt", "session/fork"].includes(method)) return Promise.reject(this.lifecycleFailure ?? this.notificationError);
+    if (this.inactivityError && ["session/new", "session/prompt", "session/fork"].includes(method)) return Promise.reject(this.inactivityError);
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const finish = (error) => {
+        const pending = this.pending.get(id); if (!pending) return;
+        clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); this.pending.delete(id); reject(error);
+      };
+      // Productive Turns use the sliding session-activity timeout below.  A
+      // second wall-clock timeout would kill an active, long-running Turn.
+      const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? observedTimeout(() => {
+          const pending = this.pending.get(id);
+          if (!pending || pending.timedOut) return;
+          pending.timedOut = true;
+          const timeoutError = Object.assign(new Error(`${method} timed out`), {
+            code: "rpc_timeout",
+            details: { method, request_id: id, session_id: params.sessionId ?? null, timeout_ms: timeoutMs, grace_ms: LATE_RESPONSE_GRACE_MS },
+          });
+          this.journal.write("request_deadline", timeoutError.details);
+          pending.timer = observedTimeout(() => {
+            this.expiredRequests.set(id, { method, sessionId: params.sessionId ?? null });
+            while (this.expiredRequests.size > 128) this.expiredRequests.delete(this.expiredRequests.keys().next().value);
+            finish(timeoutError);
+          }, LATE_RESPONSE_GRACE_MS, { progress: () => pending.progress });
+        }, timeoutMs, { progress: () => this.pending.get(id)?.progress })
+        : null;
+      const validIdleTimeout = Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0 ? idleTimeoutMs : null;
+      if (idleSessionId) this.sessionActivity.set(idleSessionId, Date.now());
+      const clock = validIdleTimeout ? new ObservationClock({ timeoutMs: validIdleTimeout,
+        onGap: gap => this.journal.write("observation_gap", { ...gap, method, request_id: id, session_id: idleSessionId }) }) : null;
+      let checking = false, quietCursor = null;
+      const checkIdle = async () => {
+        const pending = this.pending.get(id);
+        if (!pending || checking || !clock.sample(pending.progress)) return;
+        const cursor = pending.progress?.cursor ?? 0;
+        if (quietCursor === cursor) return;
+        quietCursor = cursor; checking = true;
+        const lastActivity = this.sessionActivity.get(idleSessionId) ?? pending.dispatchedAt;
+        try {
+          this.journal.write("inactivity_detected", { method, request_id: id, session_id: idleSessionId, last_activity_at: new Date(lastActivity).toISOString(), idle_timeout_ms: validIdleTimeout, observed_at: now() });
+          if (inactivityMode === "diagnostic") await this.options.onInactivity?.({ method, requestId: id, sessionId: idleSessionId, lastActivityAt: lastActivity, idleTimeoutMs: validIdleTimeout, cursor });
+          const current = this.pending.get(id);
+          if (current !== pending || (current.progress?.cursor ?? 0) !== cursor || !clock.sample(current.progress)) return;
+          this.expiredRequests.set(id, { method, sessionId: pending.sessionId });
+          finish(Object.assign(new Error(`${method} native outcome cannot be confirmed after ${validIdleTimeout}ms of silence`), { code: clock.observationLost ? "operation_observation_lost" : "subject_liveness_timeout", details: { request_id: id, session_id: idleSessionId, last_activity_at: new Date(lastActivity).toISOString(), idle_timeout_ms: validIdleTimeout, native_outcome: "unknown" } }));
+        } catch (error) {
+          const current = this.pending.get(id);
+          if (current === pending && (current.progress?.cursor ?? 0) === cursor) finish(Object.assign(new Error("ACP inactivity reconciliation could not confirm the native outcome"), { code: "operation_observation_lost", details: { request_id: id, session_id: idleSessionId, native_outcome: "unknown", observation_error: errorRecord(error) }, cause: error }));
+        } finally { checking = false; }
+      };
+      const idleTimer = validIdleTimeout ? setInterval(() => {
+        void checkIdle().catch((error) => {
+          // A timer callback is outside the request promise. Preserve the
+          // failure for the owning daemon/flush path instead of creating an
+          // unhandled rejection that loses the primary request evidence.
+          this.inactivityError ??= error;
+          void this.journal.write("inactivity_observation_failure", { method, request_id: id, session_id: idleSessionId, error: { code: error?.code ?? "inactivity_observation_failed", message: error?.message ?? String(error) } }).catch(() => {});
+        });
+      }, Math.max(10, Math.min(1_000, Math.floor(validIdleTimeout / 4)))) : null;
+      this.pending.set(id, { id, resolve, reject, timer, idleTimer, method, sessionId: params.sessionId ?? null, operationId: this.dispatchOperationId ?? process.env.DD_EVAL_OPERATION_ID ?? null, generation: this.dispatchGeneration ?? null, dispatchedAt: Date.now(), publish: operationProgressReporter() });
+      if (method === "session/prompt") {
+        void (async () => {
+          const dispatch = { operation_id: this.pending.get(id)?.operationId, session_id: params.sessionId, native_request_id: id,
+            connection_id: this.connectionId, generation: this.pending.get(id)?.generation };
+          await this.journal.write("native_dispatch_prepared", dispatch);
+          await this.journal.flush();
+          await this.options.onPromptDispatch?.(dispatch);
+          if (!this.pending.has(id) || this.pending.get(id).timedOut || this.lifecycleFailure) return;
+          this.send({ jsonrpc: "2.0", id, method, params });
+          await this.journal.write("native_dispatch", dispatch);
+        })().catch(finish);
+      } else this.send({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  notify(method, params = {}) { this.send({ jsonrpc: "2.0", method, params }); }
+  send(message) {
+    this.journal.write("outbound", message);
+    const stdin = this.child?.stdin;
+    if (!stdin || stdin.destroyed) {
+      const error = Object.assign(new Error("zcode-acp stdin is closed"), { code: "bridge_pipe_broken" });
+      this.rejectAll(error);
+      throw error;
+    }
+    try { stdin.write(`${JSON.stringify(message)}\n`); }
+    catch (error) { error.details = { system_code: error.code ?? null }; error.code = "bridge_pipe_broken"; this.rejectAll(error); throw error; }
+  }
+  rejectAll(error) {
+    for (const [id, pending] of this.pending) {
+      if (this.notificationError === error && pending.method === "session/prompt") {
+        this.rejectedHookRequests ??= new Map(); this.rejectedHookRequests.set(id, { method: pending.method, sessionId: pending.sessionId, operationId: pending.operationId, generation: pending.generation, error });
+      }
+      clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); pending.reject(error);
+    }
+    this.pending.clear();
+  }
+  async flush() {
+    await this.terminalOutcomes;
+    if (this.notificationError) throw this.notificationError;
+    try { await Promise.all([...this.lifecycleNotifications]); await this.notifications; await this.journal.flush(); }
+    catch (error) { throw this.notificationError ?? error; }
+    if (this.notificationError) throw this.notificationError;
+    if (this.inactivityError) throw this.inactivityError;
+  }
+  async close() {
+    // Productive notification failures belong to flush()/the original Turn.
+    // Draining them must not relabel a successful physical shutdown as failed.
+    return await closeBridgeProcess(this, async () => {
+      await Promise.all([this.nativeDrain, this.diagnostics]);
+      await this.terminalOutcomes;
+      await Promise.allSettled([...this.lifecycleNotifications, this.notifications]);
+      if (this.notificationError) await hookBudget(1_000, null).run(() => this.journal.flush(), "failure_drain");
+      else await this.journal.flush();
+    });
+  }
+}
+
+function isProductiveSessionNotification(message) {
+  if (!["session/update", "_x.ai/session_notification"].includes(message.method)) return false;
+  const update = message.params?.update;
+  // Transport state and the bridge's cosmetic thinking hint are not native
+  // progress. The latter is identifiable without leaking a ZCode-specific
+  // synthetic flag through the ACP wire contract.
+  if (update?.sessionUpdate === "heartbeat" || update?.type === "heartbeat") return false;
+  if (update?.sessionUpdate === "agent_thought_chunk" && typeof update?.messageId === "string" && update.messageId.startsWith("thinking_")) return false;
+  if (["agent_message_chunk", "agent_thought_chunk"].includes(update?.sessionUpdate)) return update.content?.type === "text" && typeof update.content.text === "string" && update.content.text.length > 0;
+  return ["agent_message_chunk", "agent_thought_chunk", "tool_call", "tool_call_update"].includes(update?.sessionUpdate);
+}
+
+// The qualified bridge encodes exactly providerId\\modelId; no other suffix or
+// slash normalization is authorized. Bare IDs do not prove account routing.
+export function zcodeModelSelector(raw, provider = null) {
+  if (typeof raw !== "string") return { model: null, provider, raw_model: raw };
+  const parts = raw.split("\\");
+  if (parts.length === 1) return { model: raw || null, provider, raw_model: raw };
+  if (parts.length !== 2 || !parts.every(Boolean) || provider && provider !== parts[0]) return { model: null, provider, raw_model: raw };
+  return { model: parts[1], provider: parts[0], raw_model: raw };
+}
+
+export function observedProfile(read) {
+  const model = read?.settings?.model?.current ?? {};
+  return {
+    ...zcodeModelSelector(model.modelId, typeof model.providerId === "string" ? model.providerId : null),
+    reasoning: read?.settings?.thoughtLevel?.current ?? null,
+    mode: read?.settings?.mode?.current ?? read?.projection?.mode ?? null,
+  };
+}
+
+export function assertProfile(requested, observed) { return checkObservedProfile(requested, observed); }
+
+async function resume(bridge, sessionId, cwd) {
+  await bridge.request("session/resume", { sessionId: text(sessionId, "--session-id"), cwd: absolute(cwd, "--cwd"), mcpServers: [] });
+  return sessionId;
+}
+
+/** 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, terminalCache = new Map()) {
+  const clock = new ObservationClock({ timeoutMs });
+  const cursors = new Set(), ended = new Map();
+  let first, cursor;
+  for (;;) {
+    if (clock.sample()) fail("ZCode child observation is unavailable", "operation_observation_lost");
+    const response = await bridge.request(retained ? "zcode/session/retainedSubagents" : "zcode/session/subagents", { sessionId, ...(cursor ? { endedCursor: cursor } : {}) }, timeoutMs);
+    if (retained && response?.sessionId !== sessionId) fail("Retained ZCode child directory has a foreign Session identity", "native_topology_incomplete");
+    const page = retained ? response.topology : response;
+    if (!page || !Array.isArray(page.running)) fail("ZCode child directory is unavailable", "native_topology_incomplete");
+    if (!first) first = page;
+    if (!page.ended) {
+      if (cursor) fail("ZCode child page omitted ended outcomes", "native_topology_incomplete");
+      return page; // Older qualified bridges expose an unpaginated completed array.
+    }
+    if (!Array.isArray(page.ended.items) || !Number.isSafeInteger(page.ended.total) || page.ended.total < 0
+      || page.revision !== first.revision || page.ended.total !== first.ended.total) fail("ZCode child directory changed or is malformed during pagination", "native_topology_incomplete");
+    for (const child of page.ended.items) {
+      if (typeof child.childSessionId !== "string" || !child.childSessionId) fail("ZCode ended child has no identity", "native_topology_incomplete");
+      const prior = ended.get(child.childSessionId);
+      if (prior && JSON.stringify(prior) !== JSON.stringify(child)) fail("ZCode child pages contain conflicting outcomes", "native_topology_incomplete");
+      ended.set(child.childSessionId, child);
+    }
+    cursor = page.ended.nextCursor;
+    if (!cursor) {
+      if (ended.size !== first.ended.total) fail("ZCode child directory is incomplete", "native_topology_incomplete");
+      const items = [];
+      for (const child of ended.values()) {
+        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; }
+        if (terminal?.available !== true) { items.push({ ...child, terminal_metadata_unavailable: "terminal_metadata_unavailable" }); continue; }
+        const observedAt = Date.parse(terminal.terminal_observed_at);
+        if (terminal.sessionId !== child.childSessionId || typeof terminal.terminal_turn_id !== "string" || !terminal.terminal_turn_id
+          || 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);
+        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 } };
+    }
+    if (typeof cursor !== "string" || cursors.has(cursor) || !Number.isSafeInteger(first.revision)) fail("ZCode child pagination has no advancing, versioned cursor", "native_topology_incomplete");
+    cursors.add(cursor);
+    if (cursors.size > 1_024) fail("ZCode child pagination exceeds its bounded directory limit", "native_topology_incomplete");
+    clock.sample(cursor);
+  }
+}
+
+async function inspect(bridge, sessionId) {
+  const [read, subagents] = await Promise.all([
+    bridge.request("zcode/session/read", { sessionId }),
+    readZcodeSubagents(bridge, sessionId),
+  ]);
+  let usage = null, usage_observation_error = null;
+  try { usage = await readZcodeUsage(bridge, sessionId); }
+  catch (error) { usage_observation_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
+  const observed = observedProfile(read);
+  await bridge.recordModel?.(sessionId, observed, "zcode/session/read");
+  return { read, subagents, usage, ...(usage_observation_error ? { usage_observation_error } : {}), observed_profile: observed };
+}
+
+// The journal is the immutable transcript.  CLI receipts only need the
+// operational projection; returning every message makes a routine status
+// command enormous and obscures the useful facts.
+function publicEvidence(evidence) {
+  return {
+    ...evidence,
+    read: {
+      projection: evidence.read?.projection ?? null,
+      session: evidence.read?.session ?? null,
+      settings: evidence.read?.settings ?? null,
+    },
+  };
+}
+
+// ACP returns the terminal turn separately from its visible transcript.  The
+// probe contract needs the literal terminal answer, so extract only text parts
+// from the last assistant message rather than asking a model to interpret it.
+export function latestAssistantText(read) {
+  const messages = Array.isArray(read?.messages) ? read.messages : [];
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message?.info?.role !== "assistant") continue;
+    const text = (Array.isArray(message.parts) ? message.parts : [])
+      .filter((part) => part?.type === "text" && typeof part.text === "string")
+      .map((part) => part.text)
+      .join("")
+      .trim();
+    if (text) return text;
+  }
+  return null;
+}
+
+export function zcodeChildSessionIds(snapshot) {
+  return [...new Set([
+    ...(Array.isArray(snapshot?.childSessionIds) ? snapshot.childSessionIds : []),
+    ...(Array.isArray(snapshot?.running) ? snapshot.running : []).map(child => child?.childSessionId),
+    ...(Array.isArray(snapshot?.ended?.items) ? snapshot.ended.items : []).map(child => child?.childSessionId),
+  ].filter(id => typeof id === "string" && id))];
+}
+
+// Read residency BEFORE each durable topology snapshot. An inactive node cannot
+// add descendants; a resident node never proves settlement, even when idle.
+// No resolve/read/subagents extension here: those may implicitly resume.
+export async function observeClosedZcodeTree(bridge, root, retainedChildren = [], neverPromptedRootProof = null) {
+  const pending = new Set([root, ...retainedChildren]), residents = [], snapshots = [];
+  const clock = new ObservationClock({ timeoutMs: 30_000 });
+  try {
+    for (const sessionId of pending) {
+      if (pending.size > 1024 || clock.sample()) throw new Error("Closed tree observation limit exceeded");
+      const resident = await bridge.request("zcode/session/resident", { sessionId }, 5_000);
+      if (resident?.sessionId !== sessionId || typeof resident.resident !== "boolean") throw new Error("Invalid residency identity or state");
+      residents.push(resident);
+      // A newly allocated root is not durable in ZCode until its first prompt.
+      // This is an explicit owned-daemon ledger fact, never error→empty inference.
+      if (sessionId === root && resident.resident === false && pending.size === 1
+        && neverPromptedRootProof?.source === "owned_daemon_create_without_prompt"
+        && neverPromptedRootProof.close_confirmed === true
+        && neverPromptedRootProof.provider_session_id === root && typeof neverPromptedRootProof.daemon_id === "string") {
+        snapshots.push({ sessionId, childSessionIds: [], running: [], ended: {total:0,items:[]}, provenance: neverPromptedRootProof });
+        continue;
+      }
+      const tree = await readZcodeSubagents(bridge, sessionId, 30_000, true);
+      if (!Array.isArray(tree?.childSessionIds)
+        || tree.childSessionIds.some(id => typeof id !== "string" || !id || id === sessionId)
+        || !Array.isArray(tree?.running) || !Array.isArray(tree?.ended?.items)
+        || !Number.isSafeInteger(tree.ended.total) || tree.ended.total < 0
+        || tree.ended.total > tree.childSessionIds.length
+        || [...tree.running, ...tree.ended.items].some(child => !tree.childSessionIds.includes(child?.childSessionId))) throw new Error("Incomplete retained native topology");
+      snapshots.push({ sessionId, ...tree });
+      clock.sample(sessionId);
+      for (const child of tree.childSessionIds) pending.add(child);
+    }
+    return { topology: { root_session_id: root, child_session_ids: [...pending].filter(id => id !== root), complete: true }, residents, snapshots, settled: residents.every(item => item.resident === false) };
+  } catch (error) {
+    return { topology: { root_session_id: root, child_session_ids: [...pending].filter(id => id !== root), complete: false }, residents, snapshots, settled: false, observation_error: errorRecord(error) };
+  }
+}
+
+async function cancelTree(bridge, sessionId, before, providerSessionId, retainedChildren = [], neverPromptedRootProof = null) {
+  const knownChildren = new Set(retainedChildren);
+  const remember = snapshot => {
+    for (const id of zcodeChildSessionIds(snapshot)) knownChildren.add(id);
+  };
+  remember(before);
+  const cancellations = [];
+  for (const child of before.running ?? []) {
+    const taskId = child.taskId ?? child.agentId;
+    if (taskId) {
+      try { cancellations.push(await bridge.request("session/cancelBackgroundTask", { sessionId, taskId })); }
+      catch (error) { cancellations.push({ taskId, cancelled: false, error: errorRecord(error) }); }
+    }
+  }
+  // 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, 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));
+    const timeout = Math.max(1, deadline - Date.now());
+    [after, read] = await Promise.all([
+      readZcodeSubagents(bridge, sessionId, timeout).catch(error => ({ observation_error: errorRecord(error) })),
+      bridge.request("zcode/session/read", { sessionId }, timeout).catch(error => ({ observation_error: errorRecord(error) })),
+    ]);
+    root_status = read?.projection?.status ?? read?.session?.status ?? null;
+    remember(after);
+    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)) {
+      // Idle is only a turn-level observation. Close the owned resident before
+      // proving the transitive tree cannot create another child.
+      break;
+    }
+  }
+  let close = null;
+  try { close = await bridge.request("zcode/session/close", { sessionId }); }
+  catch (error) { close = { closed: false, error: errorRecord(error) }; }
+  const observation = close?.closed === true ? await observeClosedZcodeTree(bridge, providerSessionId, [...knownChildren], neverPromptedRootProof ? {...neverPromptedRootProof,close_confirmed:true} : null)
+    : { topology: { root_session_id: providerSessionId, child_session_ids: [...knownChildren], complete: false }, settled: false };
+  return { cancellations, before, after, root_status, cancellation_requested: true, close_requested: true, close, ...observation };
+}
+
+// Cancel one known child without cancelling its parent turn.  The parent keeps
+// its ACP listener, so later child lifecycle events still reach dd-flow.
+export async function cancelChildWithBridge(bridge, options) {
+  requireJournal(options);
+  const identity = await controlledIdentity(bridge, options);
+  const childSessionId = text(options.childSessionId, "--child-session-id");
+  const before = await readZcodeSubagents(bridge, identity.adapterSessionId);
+  const child = (before.running ?? []).find((item) => item.childSessionId === childSessionId);
+  if (!child) fail(`ZCode has no running child ${childSessionId}`, "child_not_running");
+  const taskId = child.taskId ?? child.agentId;
+  if (!taskId) fail(`ZCode child ${childSessionId} has no cancellation identifier`, "child_cancel_unsupported");
+  const cancellation = await bridge.request("session/cancelBackgroundTask", { sessionId: identity.adapterSessionId, taskId });
+  let after = before;
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    after = await readZcodeSubagents(bridge, identity.adapterSessionId);
+    if (!(after.running ?? []).some((item) => item.childSessionId === childSessionId)) break;
+  }
+  if ((after.running ?? []).some((item) => item.childSessionId === childSessionId)) {
+    fail(`ZCode child ${childSessionId} did not stop`, "partial_cancellation");
+  }
+  return receipt(options, {
+    harness: "zcode-acp",
+    provider_session_id: identity.providerSessionId,
+    adapter_session_id: identity.adapterSessionId,
+    child_session_id: childSessionId,
+    cancellation,
+    before,
+    after,
+  });
+}
+
+export async function cancelChild(options) {
+  return await withBridge(options, async (bridge) => await cancelChildWithBridge(bridge, options));
+}
+
+async function controlledIdentity(bridge, options) {
+  const providerSessionId = text(options.sessionId, "--session-id");
+  const adapterSessionId = options.adapterSessionId ?? providerSessionId;
+  if (!options.liveSession) await resume(bridge, adapterSessionId, options.cwd);
+  const resolved = await bridge.request("zcode/session/resolve", { sessionId: adapterSessionId });
+  if (resolved.providerSessionId !== providerSessionId) fail(`ZCode Session identity mismatch: expected ${providerSessionId}, observed ${resolved.providerSessionId}`, "session_identity_mismatch");
+  bridge.registerModelSession?.(adapterSessionId, providerSessionId, profile(options));
+  return { providerSessionId, adapterSessionId };
+}
+
+async function applyProfile(bridge, sessionId, requested, assertDispatch = () => {}) {
+  const identity = bridge.modelSessions?.get(sessionId);
+  if (identity) identity.armed = false;
+  assertDispatch();
+  if (requested.mode) await bridge.request("session/set_mode", { sessionId, modeId: requested.mode });
+  assertDispatch();
+  if (requested.reasoning) await bridge.request("session/setThoughtLevel", { sessionId, thoughtLevel: requested.reasoning });
+  assertDispatch();
+  if (requested.model) await bridge.request("session/setModel", { sessionId, modelId: requested.provider ? `${requested.provider}\\${requested.model}` : requested.model });
+  assertDispatch();
+  const read = await bridge.request("zcode/session/read", { sessionId });
+  await bridge.notifications;
+  const observed = observedProfile(read);
+  await bridge.recordModel?.(sessionId, observed, "zcode/session/read.applied");
+  const receipt = assertProfile(requested, observed);
+  if (identity) identity.armed = true;
+  return receipt;
+}
+
+function profile(options) { return { provider: options.provider ?? null, model: options.model ?? null, reasoning: options.reasoning ?? null, mode: options.mode ?? null }; }
+
+function requiredProfile(options) {
+  const requested = profile(options);
+  for (const key of ["provider", "model", "reasoning", "mode"]) text(requested[key], `--${key}`);
+  return requested;
+}
+
+function requireJournal(options) { absolute(options.journal, "--journal"); }
+
+function receipt(options, value) { return options.daemonId ? { daemon_id: options.daemonId, ...value } : value; }
+
+async function withBridge(options, operation) {
+  const bridge = new AcpBridge(options); let primary, result;
+  try { const initialized = await bridge.start(); result = await operation(bridge, initialized); await bridge.flush(); return result; }
+  catch (error) { primary = result === undefined ? error : nativeObservationError(error, { result }); throw primary; }
+  finally { try { await bridge.close(); } catch (error) { if (!primary) throw nativeObservationError(error, result === undefined ? {} : { result }); primary.cleanup_error = errorRecord(error); primary.details = { ...primary.details, cleanup_error: primary.cleanup_error }; } }
+}
+
+function flowForwarder(options, rootProviderSessionId, bridge) {
+  return async (notification) => {
+    if (notification.method !== "session/update") return;
+    const update = notification.params?.update;
+    const command = update?.sessionUpdate === "tool_call" ? update.rawInput?.command ?? update.rawInput?.cmd : null;
+    if (typeof command !== "string" || !command.includes("dd-flow")) return;
+    const childId = notification.params?.update?._meta?.zcodeRuntime?.childSessionId;
+    const observed = bridge?.modelProfiles?.get(childId ?? rootProviderSessionId) ?? {};
+    if (childId && !observed.model) await observeModel({ journal: options.journal, harness: "zcode-acp", sessionId: childId, parentSessionId: rootProviderSessionId, requested: profile(options), observed, source: "zcode.child_tool_event", evidence: "unavailable" });
+    // This serialized path is model evidence only. The independent observer
+    // below owns qualified ACP admission; do not mint a second receipt here.
+  };
+}
+
+/** Preserve native tool ownership independently of slow secondary evidence.
+ * Rehydration uses this same session's retained inbound journal, not model text. */
+export async function zcodeInvocationObserver(options, rootProviderSessionId, send = invokeNativeHook) {
+  if (!options.ddFlowBin) return async () => {};
+  const owners = new Map();
+  const remember = (message, mandatory = false) => {
+    const update = message.params?.update;
+    if (message.method !== "session/update" || update?.sessionUpdate !== "tool_call") return null;
+    if (options.adapterSessionId && message.params?.sessionId !== options.adapterSessionId) return null;
+    const native = update._meta?.zcodeRuntime ?? {};
+    const session = zcodePhysicalSession(update, rootProviderSessionId);
+    if (!session) {
+      if (mandatory) throw Object.assign(new Error("Native subagent event has no physical child identity"), { code: "zcode_child_identity_missing" });
+      return null;
+    }
+    const key = update.toolCallId;
+    if (!key || typeof session !== "string") return null;
+    if (owners.has(key) && owners.get(key) !== session) {
+      if (mandatory) throw Object.assign(new Error("Native tool id has conflicting Session ownership"), { code: "zcode_tool_identity_conflict" });
+      return null;
+    }
+    owners.set(key, session);
+    return { update, native, session };
+  };
+  if (options.journal) {
+    try {
+      const contents = await readFile(options.journal, "utf8");
+      for (const line of contents.split("\n").filter(Boolean)) {
+        const event = JSON.parse(line);
+        if (event.kind === "inbound") remember(event.payload);
+      }
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  // The same native Session can host several Turns. Retained tool IDs belong
+  // to earlier Turns; a delayed duplicate cannot reject a new prompt waiter.
+  const priorTools = new Set(owners.keys());
+  return async message => {
+    if (priorTools.has(message.params?.update?.toolCallId)) return;
+    const candidate = message.params?.update, command = candidate?.rawInput?.command ?? candidate?.rawInput?.cmd;
+    const shell = ["Bash", "bash", "execute"].includes(candidate?._meta?.claudeCode?.toolName) && typeof command === "string";
+    const analysis = shell ? parseLifecycleCommand(command) : null;
+    const mandatory = shell && (analysis.kind !== "none" || ["lifecycle", "auxiliary"].includes(analysis.participation) || continuationCommand(command));
+    const facts = remember(message, mandatory);
+    if (!facts || !options.ddFlowBin) return;
+    const { native, session } = facts;
+    if (!mandatory) return;
+    const parent = session === rootProviderSessionId ? null : owners.get(native.parentToolCallId);
+    if (session !== rootProviderSessionId && !parent) throw Object.assign(new Error("Native child has no confirmed immediate parent tool owner"), { code: "zcode_parent_identity_missing" });
+    try {
+      await send({ bin: options.ddFlowBin, home: options.ddFlowHome,
+        args: ["zcode", "event", "handle", "--project-root", options.projectRoot ?? options.cwd, "--json"],
+        payload: { ...message, _meta: { ddZcode: { daemonId: options.daemonId, rootProviderSessionId, parentProviderSessionId: parent } } },
+      });
+    } catch (error) {
+      const details = error.details;
+      // Issued-ID commands cannot cross the CLI CAS without the receipt.
+      // This proof concerns lifecycle effects only, never shell-prefix replay.
+      if (analysis.kind !== "none" && commandOption(analysis.invocation, "invocation-id")
+        && isProvenShellCorrection(error)
+        && details.issued_invocation_id === commandOption(analysis.invocation, "invocation-id")) correctableLifecycleErrors.add(error);
+      throw error;
+    }
+  };
+}
+
+export function zcodeLifecycleEnvelope(notification, options, rootProviderSessionId) {
+  return { ...notification, _meta: { ddZcode: {
+    rootProviderSessionId,
+    requestedProfile: profile(options),
+    observedProfile: observedFields(options.observedProfile),
+    ...(options.daemonId ? { daemonId: options.daemonId } : {}),
+  } } };
+}
+
+async function forwardUsage(options, providerSessionId, usage, toolCalls) {
+  if (!options.ddFlowBin || !usage) return;
+  const projectRoot = absolute(options.projectRoot, "--project-root");
+  const payload = {
+    provider_session_id: providerSessionId,
+    daemon_id: options.daemonId ?? null,
+    observed_at: new Date().toISOString(),
+    usage,
+    // ZCode exposes counters for the addressed physical session only. State
+    // this explicitly so dd-flow never has to infer an aggregation model.
+    usage_scope: "physical_session",
+    completeness: usage?.usageIsIncomplete ? "partial" : "complete",
+    ...(toolCalls ? { tool_calls: toolCalls } : {}),
+  };
+  await runWithStdin(options.ddFlowBin, ["zcode", "usage", "ingest", "--project-root", projectRoot, "--json"], `${JSON.stringify(payload)}\n`, options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {});
+}
+
+async function forwardUsageBestEffort(options, providerSessionId, usage, toolCalls) {
+  try { await forwardUsage(options, providerSessionId, usage, toolCalls); return null; }
+  catch (error) { return { code: error.code ?? "usage_ingest_failed", message: error.message ?? String(error) }; }
+}
+
+export function zcodeLifecycleQualification(sha256, bridgeCommit, harnessContract) {
+  // The native app bundle is an auto-updated runtime.  Its whole-file SHA is
+  // evidence for provenance, not a protocol identity: an unchanged bridge
+  // must not reject every normal ZCode patch release.  The bridge contract is
+  // the compatibility boundary; native event identity is checked by the
+  // lifecycle observer and receipts during the bounded qualification probe.
+  const qualifiedBridgeCommits = new Map([
+    ["e0600fe3c46e215695f257e65aa6f674ced998d8", ZCODE_HARNESS_CONTRACT],
+    ["60af0d31e13076a313d9770f10aa70f7c94742cf", ZCODE_HARNESS_CONTRACT],
+    ["8c0a893f3c26a0b96cb138acf762db84c800298b", ZCODE_HARNESS_CONTRACT],
+    ["f4d47b517073f9bdb8d4eba3d0d59ce66c6a2833", "dd-zcode-harness@2"],
+    ["5a8c89ab716a4b2ccc50df81cb4d204ff5c06368", "dd-zcode-harness@2"],
+    ["91a1470650f5fd6105f9863fd31d1cad7b90a109", "dd-zcode-harness@2"],
+    ["b9e0f5106dddb439b76186278bd9be5f45dbf3ef", "dd-zcode-harness@2"],
+    ["636b14181d5c9a95476055079836fd6b58169f58", "dd-zcode-harness@2"],
+    ["4621fabd3f517ecdd349dfebebae9077c01d2f2b", "dd-zcode-harness@2"],
+    ["9c5ca6cc81c4eb5065e43f8b7ab6b7cc5ab7ae47", "dd-zcode-harness@2"],
+  ]);
+  const qualified = qualifiedBridgeCommits.get(bridgeCommit) === harnessContract;
+  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" };
+}
+
+let doctorDigestScanOrdinal = 0;
+export async function doctor(options = {}) {
+  const zcodeAcp = await commandOutput(options.bin, ["--version"]);
+  const zcodeAcpCommit = await commandOutput(options.bin, ["--dd-harness-commit"]);
+  const ddHarness = await commandOutput(options.bin, ["--dd-harness-version"]);
+  const zcodePath = options.zcodePath ?? process.env.ZCODE_BIN ?? process.env.ZCODE_PATH ?? "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs";
+  const zcode = await commandOutput(zcodePath, ["--version"]);
+  const hash = createHash('sha256'); let bytes = 0;
+  const scan = `zcode-digest:${zcodePath}:scan-${++doctorDigestScanOrdinal}`;
+  publishSetup('probe_started', scan);
+  for await (const chunk of createReadStream(zcodePath)) {
+    hash.update(chunk); bytes += chunk.length;
+    if (bytes % (4 * 1024 * 1024) < chunk.length) publishSetup('identity_digest_progress', `${scan}:${bytes}`);
+  }
+  const sha256 = hash.digest('hex'); publishSetup('identity_digest_completed', scan);
+  const qualification = zcodeLifecycleQualification(sha256, zcodeAcpCommit, ddHarness);
+  return { compatible: qualification.status === "qualified", contract_supported: supportedZcodeHarnessContract(ddHarness), lifecycle_qualification: qualification, observed_runtime: { zcode, zcode_acp: zcodeAcp, zcode_acp_commit: zcodeAcpCommit, dd_harness_contract: ddHarness } };
+}
+
+export async function createSession(options) {
+  requireJournal(options);
+  return await withBridge(options, async (bridge, initialized) => await createSessionWithBridge(bridge, options, initialized));
+}
+
+export async function createSessionWithBridge(bridge, options, initialized) {
+  requireJournal(options);
+  const cwd = absolute(options.cwd, "--cwd"); const requested = requiredProfile(options);
+  let forward;
+  bridge.configure({ ...options, onNotification: async (event) => { await forward?.(event); await options.onNotification?.(event); } });
+  const created = await bridge.request("session/new", { cwd, mcpServers: [] });
+  // The ACP alias is the first durable identity available. Persist it before
+  // resolving the native Session so a later resolve timeout cannot erase the
+  // fact that allocation was already admitted.
+  await options.onSessionAliasAllocated?.({ adapter_session_id: created.sessionId, cwd });
+  bridge.allocationObservers?.set(created.sessionId, async identity => {
+    // ZCode 0.46.x emits adapter/provider identities on this notification but
+    // does not repeat the workspace. The cwd from session/new is authoritative
+    // for this live bridge; reject only an explicitly conflicting workspace.
+    if (identity.cwd !== undefined && identity.cwd !== cwd) fail("ZCode allocation workspace mismatch", "session_identity_mismatch");
+    await options.onSessionAllocated?.({ ...identity, cwd });
+  });
+  // Two provider syncs (10s each) and native create (90s) run inside resolve.
+  const resolved = await bridge.request("zcode/session/resolve", { sessionId: created.sessionId }, 150_000);
+  const providerSessionId = resolved.providerSessionId;
+  // Expose both identities before profile/usage bookkeeping. The owning
+  // daemon can persist this allocation even when a later step fails.
+  await options.onSessionAllocated?.({
+    adapter_session_id: created.sessionId,
+    provider_session_id: providerSessionId,
+    cwd,
+  });
+  bridge.registerModelSession?.(created.sessionId, providerSessionId, requested, null, false);
+  const profile_receipt = await applyProfile(bridge, created.sessionId, requested);
+  forward = flowForwarder(options, providerSessionId, bridge);
+  let usage = null, usage_observation_error = null;
+  try { usage = await readZcodeUsage(bridge, created.sessionId); }
+  catch (error) { usage_observation_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
+  const usage_ingest_error = await forwardUsageBestEffort(options, providerSessionId, usage, bridge.toolSummary(created.sessionId));
+  await bridge.flush();
+  // ZCode materializes `subagents` only after its first prompt.  Session
+  // creation is intentionally nonproductive, so querying that topology here
+  // would both fail on real ZCode and turn the common create contract into an
+  // implicit first turn.  The first prompt/inspect records full evidence.
+  const evidence = { read: null, subagents: { running: [], completed: [] }, usage, ...(usage_observation_error ? { usage_observation_error } : {}), ...(usage_ingest_error ? { usage_ingest_error } : {}), observed_profile: profile_receipt.observed, tool_calls: bridge.toolSummary(created.sessionId) };
+  return receipt(options, { harness: "zcode-acp", runtime_family: "zcode", adapter_session_id: created.sessionId, provider_session_id: providerSessionId, cwd, initialized, profile: profile_receipt, evidence: publicEvidence(evidence) });
+}
+
+export async function promptSession(options) {
+  requireJournal(options);
+  return await withBridge(options, async (bridge) => await promptSessionWithBridge(bridge, options));
+}
+
+export async function promptSessionWithBridge(bridge, options) {
+  requireJournal(options);
+  const cwd = absolute(options.cwd, "--cwd"); const prompt = text(options.prompt, "prompt"); const requested = requiredProfile(options);
+  let forward;
+  bridge.configure({ ...options, onNotification: async (event) => { await forward?.(event); await options.onNotification?.(event); } });
+  const identity = await controlledIdentity(bridge, { ...options, cwd }); forward = flowForwarder(options, identity.providerSessionId, bridge);
+  await bridge.journal.flush();
+  bridge.configure({ onLifecycleNotification: await zcodeInvocationObserver({ ...options, adapterSessionId: identity.adapterSessionId }, identity.providerSessionId) });
+  const profile_receipt = await applyProfile(bridge, identity.adapterSessionId, requested, options.assertDispatch);
+  options.assertDispatch?.();
+  let initial_usage_error = null;
+  try { initial_usage_error = await forwardUsageBestEffort(options, identity.providerSessionId, await readZcodeUsage(bridge, identity.adapterSessionId), bridge.toolSummary(identity.adapterSessionId)); }
+  catch (error) { initial_usage_error = { code: error.code ?? "usage_observation_failed", message: error.message ?? String(error) }; }
+  // This is the request budget. ACP silence is observed separately and must
+  // never turn a long native child request into a fabricated provider failure.
+  const timeoutMs = null;
+  const textCursor = bridge.assistantTextCursor(identity.adapterSessionId);
+  options.assertDispatch?.();
+  bridge.dispatchOperationId = options.operationId;
+  const turn = await bridge.request("session/prompt", { sessionId: identity.adapterSessionId, prompt: [{ type: "text", text: prompt }] }, timeoutMs, {
+    idleSessionId: identity.adapterSessionId,
+    idleTimeoutMs: options.livenessTimeoutMs ?? 600_000,
+    inactivityMode: "diagnostic",
+  }).catch(error => {
+    if (error.details?.terminal_response?.session_id === identity.adapterSessionId) error.details.provider_session_id = identity.providerSessionId;
+    throw error;
+  });
+  const stopReason = typeof turn?.stopReason === "string" ? turn.stopReason : null;
+  const completionEvidence = turn?._meta?.zcodeCompletionEvidence;
+  if (completionEvidence === "inferred" || completionEvidence === "failed") {
+    let observationError = null;
+    try { await bridge.flush(); } catch (error) { observationError = errorRecord(error); }
+    const error = new Error(`ZCode completion is ${completionEvidence}, not a confirmed successful native turn`);
+    error.code = completionEvidence === "inferred" ? "native_outcome_unknown" : "zcode_turn_not_completed";
+    error.retryable = false;
+    error.details = { completion_evidence: completionEvidence, provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...(observationError ? { observation_error: observationError } : {}) };
+    throw error;
+  }
+  if (stopReason && stopReason !== "end_turn") {
+    // A close can settle the pending prompt before its terminal event. Do not
+    // collect live evidence first: ordinary inspection is allowed to recover
+    // an evicted Session, which would undo the just-confirmed close.
+    let observationError = null;
+    try { await bridge.flush(); } catch (error) { observationError = errorRecord(error); }
+    const error = new Error(`ZCode ended the provider request with ${stopReason}, not end_turn`);
+    error.code = stopReason === "cancelled" ? "zcode_turn_cancelled" : "zcode_turn_not_completed";
+    error.details = { stop_reason: stopReason, provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...(observationError ? { observation_error: observationError } : {}) };
+    throw error;
+  }
+  let evidence;
+  try { await bridge.flush(); evidence = await inspect(bridge, identity.adapterSessionId); }
+  catch (cause) {
+    const error = new Error("ZCode completed the native turn, but post-turn observation failed");
+    error.code = "native_outcome_observation_failed";
+    error.retryable = false;
+    error.cause = cause;
+    error.details = { native_outcome: { status: "completed", stop_reason: stopReason ?? "end_turn", completion_evidence: completionEvidence ?? "native" }, provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, observation_error: errorRecord(cause) };
+    throw error;
+  }
+  evidence.tool_calls = bridge.toolSummary(identity.adapterSessionId);
+  const usage_ingest_error = await forwardUsageBestEffort(options, identity.providerSessionId, evidence.usage, evidence.tool_calls);
+  if (initial_usage_error) evidence.initial_usage_error = initial_usage_error;
+  if (usage_ingest_error) evidence.usage_ingest_error = usage_ingest_error;
+  if (!options.allowBackground && (evidence.subagents.running ?? []).length) {
+    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) });
+}
+
+export async function inspectSession(options) {
+  requireJournal(options);
+  return await withBridge(options, async (bridge) => await inspectSessionWithBridge(bridge, options));
+}
+
+export async function inspectSessionWithBridge(bridge, options) {
+  requireJournal(options);
+  const identity = await controlledIdentity(bridge, options);
+  return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...publicEvidence(await inspect(bridge, identity.adapterSessionId)) });
+}
+
+export async function cancelSession(options) {
+  requireJournal(options);
+  return await withBridge(options, async (bridge) => await cancelSessionWithBridge(bridge, options));
+}
+
+export async function cancelSessionWithBridge(bridge, options) {
+  requireJournal(options);
+  const identity = await controlledIdentity(bridge, options);
+  const before = await readZcodeSubagents(bridge, identity.adapterSessionId).catch(error => ({ observation_error: errorRecord(error) }));
+  return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...await cancelTree(bridge, identity.adapterSessionId, before, identity.providerSessionId, options.knownChildSessionIds, options.neverPromptedRootProof) });
+}
+
+export async function forkSession(options) {
+  requireJournal(options);
+  return await withBridge(options, async (bridge) => await forkSessionWithBridge(bridge, options));
+}
+
+export async function forkSessionWithBridge(bridge, options) {
+  requireJournal(options);
+  if (!options.target || typeof options.target !== "object") fail("explicit --target-json is required");
+  const identity = await controlledIdentity(bridge, options);
+  const topology = await readZcodeSubagents(bridge, identity.adapterSessionId);
+  if ((topology.running ?? []).length) fail("cannot fork while background children are running");
+  const result = await bridge.request("session/fork", { sessionId: identity.adapterSessionId, target: options.target });
+  if (!result.forkedSessionId) fail("ZCode fork returned no provider Session ID");
+  return receipt(options, { harness: "zcode-acp", parent_provider_session_id: identity.providerSessionId, parent_adapter_session_id: identity.adapterSessionId, provider_session_id: result.forkedSessionId, adapter_session_id: result.forkedSessionId, target: options.target });
+}
+
+export async function promptFromFile(file) { return await readFile(absolute(file, "--prompt-file"), "utf8"); }