@deksden-com/dd-flow-cli 0.9.0-beta.11 → 0.9.0-beta.111

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

@@ -0,0 +1,982 @@
+import { observedTimeout } from "./observation-clock.mjs";
+import { ToolObservations, acpToolObservation, zcodePhysicalSession } from "./tool-observations.mjs";
+import { invokeNativeHook } from "./native-hook-command.mjs";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { stopProcessGroup } from "./managed-daemon.mjs";
+import { checkObservedProfile, observeModel, observedFields } from "./model-observations.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;
+
+function fail(message, code) { const error = new Error(message); if (code) error.code = code; throw error; }
+function fatalLifecycleError(error) {
+  return ["invocation_unknown", "invocation_identity_mismatch", "invocation_identity_conflict", "invocation_receipt_missing", "invocation_command_mismatch", "invocation_scope_mismatch", "invocation_generation_stale", "invocation_expired", "zcode_parent_identity_missing", "zcode_tool_identity_conflict"].includes(error?.code);
+}
+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 new Promise((resolve, reject) => {
+    const child = spawn(target.command, target.args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || `${target.command} exited ${code}`)));
+  });
+}
+
+async function runWithStdin(command, args, stdin, env = {}) {
+  const target = executable(command, args);
+  return await new Promise((resolve, reject) => {
+    const child = spawn(target.command, target.args, { env: { ...process.env, ...env }, stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject);
+    child.on("close", (code) => code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || `${target.command} exited ${code}`)));
+    child.stdin.end(stdin);
+  });
+}
+
+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`));
+    return this.pending;
+  }
+  writeInbound(payload, method) {
+    if (!this.file || method !== "zcode/session/read" || !payload?.result || typeof payload.result !== "object") return this.write("inbound", payload);
+    const raw = JSON.stringify(payload.result);
+    const sha256 = createHash("sha256").update(raw).digest("hex");
+    const artifactDir = `${this.file}.artifacts`, artifact = path.join(artifactDir, `${sha256}.json`);
+    const blobs = new Map();
+    const messages = Array.isArray(payload.result.messages) ? payload.result.messages.map(message => {
+      const bytes = Buffer.from(JSON.stringify(message));
+      const chunks = [];
+      for (let offset = 0; offset < bytes.length; offset += 65536) {
+        const chunk = bytes.subarray(offset, offset + 65536);
+        const hash = createHash("sha256").update(chunk).digest("hex");
+        const file = path.join(artifactDir, `${hash}.chunk`);
+        blobs.set(file, chunk); chunks.push({ path: path.basename(file), sha256: hash, bytes: chunk.length });
+      }
+      return { chunks };
+    }) : null;
+    const manifest = JSON.stringify({ encoding: "dd-zcode/session-read@1", result: { ...payload.result, ...(messages ? { messages } : {}) } });
+    const result = { ...payload.result };
+    if (Array.isArray(result.messages)) result.messages = { omitted_count: result.messages.length };
+    const compact = { ...payload, result, raw_result: { sha256, bytes: Buffer.byteLength(raw), path: artifact, encoding: "dd-zcode/session-read@1" } };
+    const line = JSON.stringify({ order: ++this.order, observed_at: now(), kind: "inbound", payload: compact });
+    this.pending = this.pending.then(async () => {
+      await mkdir(artifactDir, { recursive: true });
+      for (const [file, bytes] of [...blobs, [artifact, manifest]]) {
+        if (this.artifacts.has(file)) continue;
+        try { await writeFile(file, bytes, { flag: "wx" }); }
+        catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+          if (!Buffer.from(await readFile(file)).equals(Buffer.from(bytes))) throw new Error(`Journal artifact conflict: ${file}`);
+        }
+        this.artifacts.add(file);
+      }
+      await appendFile(this.file, `${line}\n`);
+    });
+    return this.pending;
+  }
+  async flush() { await this.pending; }
+}
+
+/** Reconstruct a retained read, verifying every chunk and the original result. */
+export async function readSessionJournalArtifact(reference) {
+  const stored = JSON.parse(await readFile(reference.path, "utf8"));
+  const result = reference.encoding === "dd-zcode/session-read@1" ? stored.result : stored;
+  if (reference.encoding === "dd-zcode/session-read@1" && Array.isArray(result.messages)) {
+    const messages = [];
+    for (const message of result.messages) {
+      const parts = [];
+      for (const chunk of message.chunks) {
+        if (chunk.path !== `${chunk.sha256}.chunk` || !/^[a-f0-9]{64}$/.test(chunk.sha256)) throw new Error("Invalid journal chunk reference");
+        const bytes = await readFile(path.join(path.dirname(reference.path), chunk.path));
+        if (bytes.length !== chunk.bytes || createHash("sha256").update(bytes).digest("hex") !== chunk.sha256) throw new Error("Journal chunk integrity mismatch");
+        parts.push(bytes);
+      }
+      messages.push(JSON.parse(Buffer.concat(parts).toString("utf8")));
+    }
+    result.messages = messages;
+  }
+  const raw = JSON.stringify(result);
+  if (Buffer.byteLength(raw) !== reference.bytes || createHash("sha256").update(raw).digest("hex") !== reference.sha256) throw new Error("Journal result integrity mismatch");
+  return result;
+}
+
+export class AcpBridge {
+  constructor(options) {
+    this.options = options;
+    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.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) {
+    this.modelSessions.set(adapterId, { sessionId, requested, parentSessionId, armed });
+  }
+  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 });
+  }
+  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 observed = { model: value("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.child.stderr.setEncoding("utf8").on("data", (chunk) => { this.bridgeStderr += String(chunk); this.journal.write("bridge_stderr", { text: String(chunk) }); });
+    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("exit", (code) => { const error = new Error(`zcode-acp exited ${code}${this.bridgeStderr.trim() ? `: ${this.bridgeStderr.trim()}` : ""}`); error.code = "bridge_exited"; this.rejectAll(error); });
+    readline.createInterface({ input: this.child.stdout }).on("line", (line) => this.receive(line));
+    if (this.options.onSpawn) await this.options.onSpawn(this.child);
+    return 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" },
+    });
+  }
+
+  receive(line) {
+    let message;
+    try { message = JSON.parse(line); } catch { this.journal.write("malformed", { line }); return; }
+    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;
+    if (!isResponse || request) this.journal.writeInbound(message, request?.method);
+    if (typeof message.params?.sessionId === "string" && isProductiveSessionNotification(message)) this.sessionActivity.set(message.params.sessionId, Date.now());
+    const update = message.params?.update;
+    // ZCode emits this as `session/update`; Grok Build wraps the same ACP
+    // 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" && update.type === "failed") {
+      for (const pending of this.pending.values()) {
+        if (pending.method === "session/prompt" && pending.sessionId === message.params.sessionId) pending.providerError = update;
+      }
+    }
+    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 fatal = fatalLifecycleError(error);
+        if (!this.notificationError || fatal) this.notificationError = error;
+        // 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 (fatal) this.rejectAll(error);
+        try {
+          await this.journal.write("notification_failure", { code: error.code ?? "invocation_observation_failed", message: error.message,
+            session_id: message.params?.sessionId ?? null, tool_call_id: update?.toolCallId ?? null, event_time: now(), delivery_stage: "lifecycle_receipt", completeness: "incomplete" });
+        } catch (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);
+        error.code = unknown ? nativeCode : /rate limit/i.test(messageText) ? "provider_rate_limited" : /payment required|usage balance exhausted/i.test(messageText) ? "provider_quota_exhausted" : "acp_request_failed";
+        error.retryable = !unknown && /rate limit/i.test(messageText);
+        error.details = { acp_code: message.error.code ?? null, ...(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); })
+      .catch(async (error) => {
+        const failure = { code: error.code ?? "notification_observation_failed", message: error.message, 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 }));
+  }
+
+  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 ((this.notificationError?.code === "profile_integrity_violation" || fatalLifecycleError(this.notificationError)) && ["session/new", "session/prompt", "session/fork"].includes(method)) return Promise.reject(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);
+        }, timeoutMs)
+        : null;
+      const validIdleTimeout = Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0 ? idleTimeoutMs : null;
+      if (idleSessionId) this.sessionActivity.set(idleSessionId, Date.now());
+      let lastTimerAt = Date.now();
+      let resumedAt = null;
+      let inactivityRecorded = false;
+      const checkIdle = async () => {
+        if (!this.pending.has(id)) return;
+        const observedAt = Date.now();
+        const observationGapMs = observedAt - lastTimerAt;
+        lastTimerAt = observedAt;
+        // A host pause makes wall time jump while this process cannot observe
+        // native progress. Keep the SAME native request alive so its late
+        // result can still be persisted. Grant one fresh observation window;
+        // do not rewrite provider activity or resend the request.
+        if (observationGapMs > 60_000) {
+          resumedAt = observedAt;
+          this.journal.write("observation_gap", { method, request_id: id, session_id: idleSessionId, observation_gap_ms: observationGapMs, observed_at: new Date(observedAt).toISOString() });
+          return;
+        }
+        const lastActivity = this.sessionActivity.get(idleSessionId) ?? Date.now();
+        if (observedAt - Math.max(lastActivity, resumedAt ?? lastActivity) < validIdleTimeout || inactivityRecorded) return;
+        // ACP silence is diagnostic only. A native child can be computing while
+        // its Session is non-resident and therefore unsubscribable.
+        inactivityRecorded = true;
+        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: new Date(observedAt).toISOString() });
+        if (inactivityMode !== "diagnostic") {
+          finish(Object.assign(new Error(`${method} received no session update for ${validIdleTimeout}ms`), { code: "subject_liveness_timeout", details: { session_id: idleSessionId, last_activity_at: new Date(lastActivity).toISOString(), idle_timeout_ms: validIdleTimeout } }));
+          return;
+        }
+        await this.options.onInactivity?.({ method, requestId: id, sessionId: idleSessionId, lastActivityAt: lastActivity, idleTimeoutMs: validIdleTimeout });
+      };
+      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, { resolve, reject, timer, idleTimer, method, sessionId: params.sessionId ?? null });
+      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 pending of this.pending.values()) { clearTimeout(pending.timer); if (pending.idleTimer) clearInterval(pending.idleTimer); pending.reject(error); } this.pending.clear(); }
+  async flush() {
+    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.
+    await Promise.allSettled([...this.lifecycleNotifications, this.notifications]);
+    if (this.child) {
+      this.child.stdin.end();
+      await Promise.race([new Promise((resolve) => this.child.once("exit", resolve)), new Promise((resolve) => setTimeout(resolve, 2000))]);
+      await stopProcessGroup(this.child, 2_000);
+    }
+    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 ((update?.sessionUpdate === "status" || update?.type === "status") && update?.status === "running") return false;
+  return true;
+}
+
+export function observedProfile(read) {
+  const model = read?.settings?.model?.current ?? {};
+  return {
+    provider: typeof model.providerId === "string" ? model.providerId : null,
+    model: typeof model.modelId === "string" ? model.modelId : 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) {
+  const deadline = performance.now() + timeoutMs;
+  const cursors = new Set(), ended = new Map();
+  let first, cursor;
+  for (;;) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) fail("ZCode child observation deadline expired", "native_topology_incomplete");
+    const response = await bridge.request(retained ? "zcode/session/retainedSubagents" : "zcode/session/subagents", { sessionId, ...(cursor ? { endedCursor: cursor } : {}) }, remaining);
+    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 (performance.now() >= deadline) fail("ZCode child observation deadline expired", "native_topology_incomplete");
+    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");
+      return { ...first, ended: { total: first.ended.total, items: [...ended.values()] } };
+    }
+    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);
+  }
+}
+
+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 = []) {
+  const pending = new Set([root, ...retainedChildren]), residents = [], snapshots = [];
+  const deadline = performance.now() + 30_000;
+  try {
+    for (const sessionId of pending) {
+      if (pending.size > 1024 || performance.now() >= deadline) throw new Error("Closed tree observation limit exceeded");
+      const timeout = () => Math.max(1, Math.min(5000, deadline - performance.now()));
+      const resident = await bridge.request("zcode/session/resident", { sessionId }, timeout());
+      if (resident?.sessionId !== sessionId || typeof resident.resident !== "boolean") throw new Error("Invalid residency identity or state");
+      residents.push(resident);
+      const tree = await readZcodeSubagents(bridge, sessionId, deadline - performance.now(), 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 });
+      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: { code: error.code ?? "topology_observation_failed", message: error.message } };
+  }
+}
+
+async function cancelTree(bridge, sessionId, before, providerSessionId, retainedChildren = []) {
+  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: { code: error.code ?? "cancel_failed", message: error.message } }); }
+    }
+  }
+  // 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: { code: error.code, message: error.message } })),
+      bridge.request("zcode/session/read", { sessionId }, timeout).catch(error => ({ observation_error: { code: error.code, message: error.message } })),
+    ]);
+    root_status = read?.projection?.status ?? read?.session?.status ?? null;
+    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: { code: error.code ?? "close_failed", message: error.message } }; }
+  const observation = close?.closed === true ? await observeClosedZcodeTree(bridge, providerSessionId, [...knownChildren])
+    : { 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);
+  try { const initialized = await bridge.start(); const result = await operation(bridge, initialized); await bridge.flush(); return result; }
+  finally { await bridge.close(); }
+}
+
+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" });
+    // Native PreToolUse has already admitted (or denied) the command. ACP is
+    // intentionally only journal/model evidence: its serialized delivery can
+    // lag behind execution and must never mint a second lifecycle receipt.
+  };
+}
+
+/** 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 => {
+    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) throw Object.assign(new Error("Native subagent event has no physical child identity"), { code: "zcode_child_identity_missing" });
+    const key = update.toolCallId;
+    if (!key || typeof session !== "string") return null;
+    if (owners.has(key) && owners.get(key) !== session) throw Object.assign(new Error("Native tool id has conflicting Session ownership"), { code: "zcode_tool_identity_conflict" });
+    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; }
+  }
+  return async message => {
+    const facts = remember(message);
+    if (!facts || !options.ddFlowBin) return;
+    const { update, native, session } = facts;
+    const command = update.rawInput?.command ?? update.rawInput?.cmd;
+    const toolName = update._meta?.claudeCode?.toolName;
+    if (!["Bash", "bash", "execute"].includes(toolName) || typeof command !== "string") 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" });
+    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 } } },
+    });
+  };
+}
+
+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"],
+  ]);
+  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" };
+}
+
+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 native = await readFile(zcodePath);
+  const sha256 = createHash("sha256").update(native).digest("hex");
+  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 });
+  });
+  const resolved = await bridge.request("zcode/session/resolve", { sessionId: created.sessionId });
+  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 = options.timeoutMs === undefined ? 1_800_000 : options.timeoutMs;
+  const textCursor = bridge.assistantTextCursor(identity.adapterSessionId);
+  options.assertDispatch?.();
+  const turn = await bridge.request("session/prompt", { sessionId: identity.adapterSessionId, prompt: [{ type: "text", text: prompt }] }, timeoutMs, {
+    idleSessionId: identity.adapterSessionId,
+    idleTimeoutMs: options.livenessTimeoutMs ?? null,
+    inactivityMode: "diagnostic",
+  });
+  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 = { code: error.code ?? "zcode_post_turn_observation_failed", message: error.message ?? String(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 = { code: error.code ?? "zcode_post_turn_observation_failed", message: error.message ?? String(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.details = { native_outcome: { stop_reason: stopReason ?? "end_turn", completion_evidence: completionEvidence ?? "native" }, provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, observation_error: { code: cause.code ?? "zcode_post_turn_observation_failed", message: cause.message ?? String(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: { code: error.code, message: error.message } }));
+  return receipt(options, { harness: "zcode-acp", provider_session_id: identity.providerSessionId, adapter_session_id: identity.adapterSessionId, ...await cancelTree(bridge, identity.adapterSessionId, before, identity.providerSessionId, options.knownChildSessionIds) });
+}
+
+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"); }