@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

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

@@ -0,0 +1,845 @@
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import { SETUP_STARTUP_MS, startupObserver, observationDetails } from './setup-progress.mjs';
+import { callDaemonObserved } from './daemon-observation.mjs';
+import { admitNativeRequestBuffer } from "./native-streams.mjs";
+import { ObservationClock } from "./observation-clock.mjs";
+import { prepareDaemonRequest } from "./native-request-proof.mjs";
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import net from "node:net";
+import { durableDaemonDispatch, completeDaemonShutdown, commitDaemonShutdown, assertDaemonDispatch, assertDaemonRestartable, trackDaemonConnections, retireDaemonEndpoint, retireFailedDaemon } from "./daemon-operations.mjs";
+import path from "node:path";
+import { assertStartupChild, prepareRuntimeOwner, cleanupFailedDaemonStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, scheduleDaemonProcessHeartbeat, registerDaemonProcess, startManagedBridge, stopProcessGroup } from "./managed-daemon.mjs";
+import { acceptNativeHookRequest, readNativeHookFailures, writeNativeHookFailure } from "./native-hook-command.mjs";
+import { parseLifecycleCommand, continuationCommand, commandOption } from "./lifecycle-command.mjs";
+import { errorRecord, isNativeHookObservationLoss, isProvenShellCorrection, reportedError } from "./operation-errors.mjs";
+
+import {
+  AcpBridge,
+  cancelSessionWithBridge,
+  cancelChildWithBridge,
+  createSessionWithBridge,
+  doctor,
+  forkSessionWithBridge,
+  inspectSessionWithBridge,
+  promptSessionWithBridge,
+  zcodeChildSessionIds,
+  observeClosedZcodeTree,
+  readZcodeSubagents,
+} from "./dd-zcode.mjs";
+
+const REQUEST_SCHEMA = "dd-zcode/daemon-request@1";
+import { settledNativeTree, nativeExecutionReceipt } from "./native-children.mjs";
+const RESPONSE_SCHEMA = "dd-zcode/daemon-response@1";
+const STATE_SCHEMA = "dd-zcode/daemon-state@1";
+// ACP silence starts diagnostics; it is not a provider-failure deadline.
+export const DEFAULT_LIVENESS_TIMEOUT_MS = 600_000;
+export const DEFAULT_REQUEST_TIMEOUT_MS = null;
+
+function positiveDuration(value, name, fallback) {
+  const duration = value ?? fallback;
+  if (!Number.isFinite(duration) || duration <= 0) throw new DaemonError("invalid_duration", `${name} must be a positive finite duration`, false, { name, value: duration });
+  return duration;
+}
+
+function optionalDuration(value, name, fallback) {
+  if (value === null) return null;
+  if (value === undefined && fallback === null) return null;
+  return positiveDuration(value, name, fallback);
+}
+
+class DaemonError extends Error {
+  constructor(code, message, retryable = false, details) {
+    super(message); this.code = code; this.retryable = retryable; this.details = details;
+  }
+}
+
+function absolute(value, label) {
+  if (!value || !path.isAbsolute(value)) throw new DaemonError("invalid_path", `${label} must be an absolute path`);
+  return path.resolve(value);
+}
+
+function locations(stateDir) {
+  const dir = absolute(stateDir, "--state-dir");
+  const localSocket = path.join(dir, "daemon.sock");
+  const socket = Buffer.byteLength(localSocket) < 100
+    ? localSocket
+    : `/tmp/dd-zcode-${createHash("sha256").update(dir).digest("hex").slice(0, 24)}.sock`;
+  return { dir, socket, state: path.join(dir, "daemon.json"), log: path.join(dir, "daemon.log") };
+}
+
+async function readState(stateDir) {
+  const file = locations(stateDir).state;
+  try { return JSON.parse(await readFile(file, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function writeState(file, value) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, file);
+}
+
+async function removeSocket(socket, dir) {
+  if (socket !== locations(dir).socket) throw new DaemonError("unsafe_socket", "daemon socket does not match the exact state directory");
+  try {
+    const info = await lstat(socket);
+    if (!info.isSocket()) throw new DaemonError("unsafe_socket", "refusing to remove a non-socket daemon path");
+    await unlink(socket);
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+}
+
+const errorPayload = errorRecord;
+
+export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 30_000) {
+  const request = prepareDaemonRequest({ schema_id: REQUEST_SCHEMA, id: process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation, params });
+  return await callDaemonObserved({ stateDir, socket: locations(stateDir).socket, request, responseSchema: RESPONSE_SCHEMA, harness: 'zcode', timeoutMs });
+}
+
+const ZCODE_ROUTING_ENV = ["ZCODE_HOME", "ZCODE_STORAGE_DIR", "ZCODE_SESSION_DB_PATH"];
+
+function nativeRoutingEnv() {
+  return Object.fromEntries(ZCODE_ROUTING_ENV.filter(key => process.env[key] !== undefined)
+    .map(key => [key, absolute(process.env[key], key)]));
+}
+
+function sameNativeRouting(previous, config) {
+  return ZCODE_ROUTING_ENV.every(key => (previous?.env?.[key] ?? null) === (config.env?.[key] ?? null));
+}
+
+function sameConfig(state, config) {
+  return sameNativeRouting(state.config, config) && ["cwd", "journal", "bin", "zcodePath", "ddFlowBin", "ddFlowHome", "projectRoot", "resourceHome", "livenessTimeoutMs", "requestTimeoutMs"].every((key) => (state.config?.[key] ?? null) === (config[key] ?? null));
+}
+
+export async function startDaemon(options) {
+  if (options.noFlow) options = { ...options, ddFlowHome: undefined, ddFlowBin: undefined, projectRoot: undefined };
+  const paths = locations(options.stateDir);
+  const hasFlowContext = Boolean(options.ddFlowHome || options.projectRoot || options.ddFlowBin);
+  if (hasFlowContext && (!options.ddFlowHome || !options.projectRoot || !options.ddFlowBin)) {
+    throw new DaemonError("flow_context_incomplete", "--dd-flow-home, --dd-flow-bin and --project-root must be provided together for ZCode lifecycle forwarding");
+  }
+  const config = {
+    cwd: absolute(options.cwd, "--cwd"),
+    journal: absolute(options.journal, "--journal"),
+    bin: options.bin ?? null,
+    zcodePath: options.zcodePath ?? null,
+    ddFlowBin: hasFlowContext ? absolute(options.ddFlowBin, "--dd-flow-bin") : null,
+    ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null,
+    projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : null,
+    resourceHome: !options.noFlow && process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null,
+    env: { ...nativeRoutingEnv(), ...(options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home"), ...(options.ddFlowBin ? { DD_FLOW_BIN: absolute(options.ddFlowBin, "--dd-flow-bin") } : {}) } : {}) },
+    livenessTimeoutMs: positiveDuration(options.livenessTimeoutMs, "livenessTimeoutMs", DEFAULT_LIVENESS_TIMEOUT_MS),
+    requestTimeoutMs: optionalDuration(options.requestTimeoutMs, "requestTimeoutMs", DEFAULT_REQUEST_TIMEOUT_MS),
+  };
+  await prepareRuntimeOwner(config, paths.dir);
+  await mkdir(paths.dir, { recursive: true, mode: 0o700 });
+  await chmod(paths.dir, 0o700);
+  let previous = await readState(paths.dir); assertDaemonRestartable(previous);
+  try {
+    const status = await callDaemon(paths.dir, "daemon.status", {}, 1000);
+    if (!sameConfig(status, config)) throw new DaemonError("daemon_config_mismatch", "a daemon is already running with different configuration");
+    return { ...status, already_running: true };
+  } catch (error) { if (error.code !== "daemon_not_running" && error.code !== "daemon_timeout") throw error; }
+
+  previous = await readState(paths.dir); assertDaemonRestartable(previous);
+  if (previous?.shutdown_state === "clean") {
+    if (!sameNativeRouting(previous.config, config)) throw new DaemonError("daemon_config_mismatch", "retained ZCode native storage routing changed");
+    await authorizeRetainedDaemonResume(paths.dir, previous, options.sessionId, config);
+  }
+  if (previous?.shutdown_state === "running" && previous.active_tree) {
+    throw new DaemonError("invalid_harness_crash", "the previous daemon died with an active or unproven Session tree", false, { daemon_id: previous.daemon_id });
+  }
+  await removeSocket(paths.socket, paths.dir);
+  const versions = await doctor({ bin: config.bin, zcodePath: config.zcodePath });
+  if (hasFlowContext && versions.compatible !== true) {
+    throw new DaemonError("zcode_lifecycle_unqualified", "ZCode native event identity is not qualified for managed CLI admission; inspect lifecycle_qualification before starting E2E.", false, { startup_resources: "not_created", observed_runtime: versions.observed_runtime, lifecycle_qualification: versions.lifecycle_qualification });
+  }
+  const resourceProcess = await registerDaemonProcess(config, {
+    kind: "zcode-daemon", owner: `zcode:${path.basename(paths.dir)}`, operation: `zcode-daemon:${path.basename(paths.dir)}`,
+    stdout: paths.log, stderr: paths.log,
+  });
+  const state = {
+    schema_id: STATE_SCHEMA,
+    daemon_id: randomUUID(),
+    pid: null,
+    socket: paths.socket,
+    cwd: config.cwd,
+    journal: config.journal,
+    started_at: new Date().toISOString(),
+    shutdown_state: "starting",
+    active_tree: false,
+    recovery_status: previous?.shutdown_state === "running" ? "recovered_idle" : "clean_start",
+    versions: versions.versions,
+    config,
+    sessions: previous?.sessions ?? [],
+    resource_process: resourceProcess,
+  };
+  await writeState(paths.state, state);
+  const log = await open(paths.log, "a", 0o600);
+  const child = spawn(process.execPath, [absolute(options.entryPath, "dd-zcode entry"), "daemon", "serve", "--state-dir", paths.dir], {
+    cwd: config.cwd, detached: true, stdio: ["ignore", log.fd, log.fd],
+  });
+  child.unref();
+  await log.close();
+  try {
+    await confirmDaemonProcess(config, resourceProcess, child);
+    const startupClock = new ObservationClock({ timeoutMs: SETUP_STARTUP_MS }); const startupProgress = startupObserver(paths.dir, state.daemon_id);
+    while (!startupClock.sample(await startupProgress())) {
+      assertStartupChild(child, state, await readState(paths.dir), paths.log);
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      try { return await callDaemon(paths.dir, "daemon.status", {}, 1000); }
+      catch (error) { if (error.code !== "daemon_not_running" && error.code !== "daemon_timeout") throw error; }
+    }
+    throw Object.assign(new DaemonError("daemon_start_failed", "daemon did not become ready", true), { details: observationDetails(startupClock, 'daemon-start', child.pid) });
+  } catch (error) {
+    await cleanupFailedDaemonStart(config, resourceProcess, child, error, () => readState(paths.dir), state.daemon_id);
+    throw error;
+  }
+}
+
+export async function stopDaemon(options) {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const { socket } = locations(options.stateDir);
+  return await confirmDaemonStopped(() => callDaemon(options.stateDir, "daemon.stop", { cancelTree: options.cancelTree === true }, timeoutMs), socket, timeoutMs, { readState: () => readState(options.stateDir) });
+}
+
+export class DaemonRuntime {
+  constructor(paths, state, bridge, initialized) {
+    this.paths = paths; this.state = state; this.bridge = bridge; this.initialized = initialized;
+    this.state.capabilities = { ...(this.state.capabilities ?? {}), retained_child_observation: true };
+    this.sessions = new Map((state.sessions ?? []).map((item) => [item.provider_session_id, item]));
+    this.liveAdapters = new Set();
+    this.activeProductive = null; this.server = null; this.persisting = Promise.resolve();
+  }
+
+  persist(patch = {}) {
+    Object.assign(this.state, patch, { pid: process.pid, updated_at: new Date().toISOString(), sessions: [...this.sessions.values()] });
+    const snapshot = structuredClone(this.state);
+    this.persisting = this.persisting.catch(() => {}).then(() => writeState(this.paths.state, snapshot));
+    return this.persisting;
+  }
+
+  options(params) {
+    const known = this.sessions.get(params.sessionId);
+    const adapter = params.adapterSessionId ?? known?.adapter_session_id ?? params.sessionId;
+    const generation = this.activeGeneration ?? this.controlGeneration ?? 0;
+    return {
+      ...this.state.config, ...params, operationId: this.state.active_request?.request_id, nativeHookOwner: this.nativeHookOperation ?? null, knownChildSessionIds: known?.known_child_session_ids ?? [], adapterSessionId: adapter,
+      neverPromptedRootProof: this.neverPromptedRootProof(params.sessionId),
+      daemonId: this.state.daemon_id, allowBackground: true, liveSession: this.liveAdapters.has(adapter),
+      assertDispatch: () => { if (generation !== (this.controlGeneration ?? 0)) throw new DaemonError("operation_cancelled", "ZCode prompt was cancelled before native dispatch"); },
+      onActivity: async ({ sessionId, requestId, progress }) => {
+        const request = this.state.active_request;
+        if (!request || request.adapter_session_id !== sessionId || this.activeGeneration !== request.generation) return;
+        await this.persist({ active_request: { ...request, observation: { state: "productive", request_id: requestId, progress } } });
+      },
+      // The bridge owns the quiet timer; the daemon owns the durable status.
+      // Do not infer provider state or cancel here.
+      onInactivity: async ({ requestId, sessionId, lastActivityAt, idleTimeoutMs, cursor }) => {
+        const request = this.state.active_request;
+        // `sessionId` is ACP identity; the durable request's `session_id` is
+        // native/provider identity. These strings can coincide but are not
+        // interchangeable.
+        if (!request || request.adapter_session_id !== sessionId) return;
+        const adapterSessionId = request.adapter_session_id;
+        let diagnostics;
+        try {
+          // Both are non-mutating native observations. In particular, do not
+          // inspect/resume a running child: some ZCode children are known to
+          // be non-resident and unsubscribable while their request is alive.
+          const [resident, topology] = await Promise.all([
+            this.bridge.request("zcode/session/resident", { sessionId: adapterSessionId }, 5_000),
+            // childSessionIds is complete on every page. This diagnostic reads
+            // identities only, not ended outcomes or a settlement verdict.
+            this.bridge.request("zcode/session/retainedSubagents", { sessionId: adapterSessionId }, 5_000),
+          ]);
+          diagnostics = {
+            observed_at: new Date().toISOString(), adapter_session_id: adapterSessionId,
+            resident: resident?.resident === true,
+            child_session_ids: zcodeChildSessionIds(topology?.topology ?? topology),
+          };
+        } catch (error) {
+          diagnostics = { observed_at: new Date().toISOString(), adapter_session_id: adapterSessionId, observation_error: errorPayload(error) };
+        }
+        // The probe is asynchronous. Do not recreate a completed or
+        // reconnected request with a stale callback snapshot.
+        const current = this.state.active_request;
+        if (!current || current.request_id !== request.request_id || current.adapter_session_id !== adapterSessionId || this.activeGeneration !== request.generation
+            || cursor !== undefined && this.bridge.pending?.get(requestId)?.progress?.cursor !== cursor && cursor !== 0) return;
+        await this.persist({ active_request: {
+          ...current,
+          observation: { state: "quiet", request_id: requestId, detected_at: new Date().toISOString(), last_activity_at: new Date(lastActivityAt).toISOString(), quiet_threshold_ms: idleTimeoutMs, diagnostics },
+        } });
+      },
+      // Native create publishes its identities before post-create work. Keep
+      // that allocation in the same durable request record so recovery can
+      // distinguish "no Session allocated" from "allocated, later step lost".
+      onSessionAliasAllocated: async (identity) => {
+        const current = this.state.active_request;
+        await this.persist({
+          active_request: {
+            ...(current ?? {
+              request_id: randomUUID(),
+              session_id: params.sessionId ?? null,
+              adapter_session_id: identity.adapter_session_id,
+              generation: this.controlGeneration ?? 0,
+              dispatched_at: new Date().toISOString(),
+            }),
+            allocation: {
+              adapter_session_id: identity.adapter_session_id,
+              provider_session_id: null,
+              cwd: identity.cwd,
+              allocated_at: new Date().toISOString(),
+            },
+          },
+        });
+      },
+      onSessionAllocated: async (identity) => {
+        const current = this.state.active_request;
+        // A late identity is evidence, not permission to resurrect a completed
+        // request or overwrite another operation's ownership.
+        this.track(identity);
+        const allocated = this.sessions.get(identity.provider_session_id);
+        if (allocated && this.activeProductive === "session.create" && current?.allocation?.adapter_session_id === identity.adapter_session_id
+          && allocated.prompt_dispatched === undefined) {
+          allocated.prompt_dispatched = false;
+          allocated.created_by_daemon_id = this.state.daemon_id;
+        }
+        if (!current || current.allocation?.adapter_session_id !== identity.adapter_session_id) {
+          await this.persist({});
+          return;
+        }
+        await this.persist({
+          active_request: {
+            ...(current ?? {
+              request_id: randomUUID(),
+              session_id: params.sessionId ?? null,
+              adapter_session_id: params.adapterSessionId ?? params.sessionId ?? null,
+              generation: this.controlGeneration ?? 0,
+              dispatched_at: new Date().toISOString(),
+            }),
+            allocation: {
+              adapter_session_id: identity.adapter_session_id,
+              provider_session_id: identity.provider_session_id,
+              cwd: identity.cwd,
+              allocated_at: new Date().toISOString(),
+            },
+          },
+        });
+      },
+    };
+  }
+
+  track(result, topology = result?.evidence?.subagents) {
+    if (result?.provider_session_id) { const existing = this.sessions.get(result.provider_session_id); const suppliedParent = result.parent_provider_session_id;
+      if (existing && suppliedParent !== undefined && suppliedParent !== existing.parent_provider_session_id) {
+        throw new DaemonError("session_ancestry_conflict", "ZCode Session parent changed after it was recorded", false, { session_id: result.provider_session_id, expected_parent: existing.parent_provider_session_id, actual_parent: suppliedParent });
+      }
+      const parent = suppliedParent ?? existing?.parent_provider_session_id ?? null;
+      const parentRoot = parent ? this.sessions.get(parent)?.root_provider_session_id ?? null : null;
+      this.sessions.set(result.provider_session_id, {
+      provider_session_id: result.provider_session_id,
+      adapter_session_id: result.adapter_session_id ?? existing?.adapter_session_id ?? result.provider_session_id,
+      parent_provider_session_id: parent,
+      root_provider_session_id: existing?.root_provider_session_id ?? (parent ? parentRoot : result.provider_session_id),
+      topology: topology ?? existing?.topology ?? null,
+      known_child_session_ids: [...new Set([...(existing?.known_child_session_ids ?? zcodeChildSessionIds(existing?.topology)), ...zcodeChildSessionIds(topology)])],
+      completed_turns: existing?.completed_turns ?? 0,
+      prompt_dispatched: existing?.prompt_dispatched,
+      created_by_daemon_id: existing?.created_by_daemon_id,
+      close_receipt: result.close?.closed === true ? result : existing?.close_receipt ?? null,
+    }); }
+    if (result?.adapter_session_id) this.liveAdapters.add(result.adapter_session_id);
+    for (const child of topology?.running ?? []) {
+      const adapter = child.childSessionId ?? child.adapterSessionId ?? child.sessionId;
+      if (typeof adapter === "string" && adapter) this.liveAdapters.add(adapter);
+    }
+  }
+
+  treeRunning(result) {
+    const closed = this.sessions.get(result?.provider_session_id)?.close_receipt;
+    if (closed) return closed.settled !== true;
+    const evidence = result?.evidence ?? result;
+    const children = evidence?.subagents?.running;
+    return evidence?.read?.projection?.status !== "idle" || !Array.isArray(children) || children.length > 0 || Boolean(evidence?.subagents?.observation_error);
+  }
+
+  async productive(name, task, request = null) {
+    if (this.activeProductive) throw new DaemonError("operation_busy", `${this.activeProductive} is already running`, true);
+    this.activeProductive = name;
+    this.activeGeneration = this.controlGeneration ?? 0;
+    const current = this.nativeHookOperation = { operationId: request?.operation_id, rootProviderSessionId: request?.session_id, generation: this.activeGeneration, requests: new Map() };
+    current.valid = () => current.generation === (this.controlGeneration ?? 0);
+    let rejectHook;
+    const hookFailed = new Promise((_, reject) => { rejectHook = reject; });
+    void hookFailed.catch(() => {}); // A hook can fail while the dispatch receipt is still persisting.
+    current.reject = error => { if (this.nativeHookOperation !== current || current.error) return; current.error = error; this.bridge.lifecycleFailure ??= error; this.bridge.notificationError = this.bridge.lifecycleFailure; this.bridge.rejectAll(this.bridge.lifecycleFailure); rejectHook(this.bridge.lifecycleFailure); };
+    const timer = setInterval(() => { void this.observeHookFailures(current).catch(error => current.reject(error)); }, 100);
+    try {
+      if (name === "session.prompt") this.state.last_native_failure = null;
+      await this.persist({ active_tree: true, active_operation: name, ...(request ? { active_request: request } : {}) });
+      const result = await Promise.race([task(), hookFailed]);
+      // The native tool cannot finish before its hook returns. Drain any
+      // already-written failure before discarding this operation's requests.
+      await this.observeHookFailures(current);
+      if (current.error) throw current.error;
+      const hookDiagnostics = (this.bridge.lifecycleDiagnostics ?? []).filter(item => item.operation_id === current.operationId && item.generation === current.generation);
+      if (hookDiagnostics.length) result.native_hook_diagnostics = [...new Map([...(result.native_hook_diagnostics ?? []), ...hookDiagnostics].map(item => [JSON.stringify(item), item])).values()];
+      this.track(result);
+      const running = this.treeRunning(result);
+      await this.persist({ active_tree: running, active_operation: null, active_request: null });
+      return { ...result, settled: !running };
+    } catch (error) {
+      // Keep an allocated identity visible until the controller seals the
+      // outcome. Clearing it here was the source of `provider_identity_unknown`
+      // after a late/partial create: the native Session existed, but the
+      // daemon state no longer carried the only correlation to it.
+      const active = this.state?.active_request;
+      const response = error?.details?.terminal_response;
+      if (name === "session.prompt" && response?.method === "session/prompt" && error.details.provider_session_id)
+        this.state.last_native_failure = { provider_session_id: error.details.provider_session_id, request_id: response.request_id };
+      try {
+        await this.persist({
+          active_operation: null,
+          active_request: active?.allocation
+            ? { ...active, outcome: "unknown", error: errorPayload(error) }
+            : null,
+        });
+      } catch (cleanupError) {
+        // Preserve the operation's primary failure if durable cleanup itself
+        // is unavailable. The caller will retain the outcome as unknown and
+        // the next recovery pass can retry the state write.
+        if (error && typeof error === "object") error.cleanup_error = errorPayload(cleanupError);
+      }
+      throw error;
+    } finally { clearInterval(timer); if (!current.retainNativeHooks) current.requests.clear(); if (this.nativeHookOperation === current) this.nativeHookOperation = null; this.activeProductive = null; this.activeGeneration = null; }
+  }
+
+  async observeHookFailures(current = this.nativeHookOperation) {
+    if (!current || this.nativeHookOperation !== current) return;
+    while (current.reading) {
+      await current.reading;
+      if (this.nativeHookOperation !== current) return;
+    }
+    const reading = readNativeHookFailures(this.paths.dir, current.requests, current, error => this.acceptHookFailure(current, error));
+    current.reading = reading;
+    try { await reading; } finally { if (current.reading === reading) current.reading = null; }
+  }
+
+  acceptHookFailure(current, error) {
+    if (this.nativeHookOperation !== current) return;
+    const unconfirmed = error.details?.native_hook_binding?.native_creator === "unconfirmed";
+    if (!unconfirmed && isProvenShellCorrection(error)) return;
+    if (unconfirmed || isNativeHookObservationLoss(error)) {
+      const diagnostic = { ...errorRecord(error), session_id: this.state.active_request?.adapter_session_id ?? null,
+        operation_id: current.operationId, generation: current.generation, delivery_stage: "hook_observation", completeness: "incomplete" };
+      this.bridge.lifecycleDiagnostics ??= [];
+      this.bridge.lifecycleDiagnostics.push(diagnostic);
+      try { void Promise.resolve(this.bridge.journal?.write("native_hook_observation_failure", diagnostic)).catch(() => {}); } catch { /* diagnostic is optional */ }
+      return;
+    }
+    current.reject(error);
+  }
+
+  hookOwner(binding) {
+    if (!binding?.request_id) return null;
+    const turns = this.bridge.nativeHookOwnership?.turns?.values() ?? [];
+    const owners = new Set([this.nativeHookOperation, ...[...turns].filter(turn => !turn.invalid).map(turn => turn.owner)]);
+    for (const owner of owners) {
+      if (!owner || owner.operationId !== binding.operation_id || owner.generation !== binding.turn_generation || owner.generation !== (this.controlGeneration ?? 0)) continue;
+      const accepted = owner.requests.get(binding.request_id);
+      if (accepted?.current !== owner || JSON.stringify(accepted.binding) !== JSON.stringify(binding)) continue;
+      if (binding.source_harness === "zcode-acp") {
+        const proof = this.bridge.nativeHookOwnership?.fact(binding.provider_session_id, binding.tool_call_id, binding.native_command);
+        if (!proof || proof.owner !== owner || proof.parent !== binding.parent_provider_session_id) continue;
+      }
+      return owner;
+    }
+    return null;
+  }
+
+  async requireSettled(params) {
+    if (this.sessions.get(params.sessionId)?.close_receipt) throw new DaemonError("session_closed", "Closed Session requires explicit recovery");
+    // A freshly created ZCode Session has no prior Turn and is not yet exposed
+    // by the provider's subagent index. Its first prompt is therefore safe.
+    if (this.neverPromptedRootProof(params.sessionId)) return null;
+    const observed = await inspectSessionWithBridge(this.bridge, this.options(params));
+    const runningChildren = observed.subagents?.running ?? [];
+    if (this.treeRunning(observed)) {
+      throw new DaemonError("tree_not_settled", "the prior ZCode agent tree is not fully settled", false, { session_id: params.sessionId, running_children: runningChildren.map((child) => child.sessionId ?? child.childSessionId ?? null) });
+    }
+    this.track(observed, observed.subagents);
+    return observed;
+  }
+
+  neverPromptedRootProof(sessionId) {
+    const known = this.sessions.get(sessionId);
+    return known?.prompt_dispatched === false && known.created_by_daemon_id === this.state.daemon_id
+      && known.parent_provider_session_id === null && known.root_provider_session_id === sessionId
+      && Array.isArray(known.known_child_session_ids) && known.known_child_session_ids.length === 0
+      ? { source: "owned_daemon_create_without_prompt", daemon_id: this.state.daemon_id, provider_session_id: sessionId }
+      : null;
+  }
+
+  async markPromptDispatched(sessionId) {
+    const known = this.sessions.get(sessionId);
+    if (known) known.prompt_dispatched = true;
+    await this.persist();
+  }
+
+  async dispatch(operation, params, operationId = null) {
+    if (["session.create", "session.prompt", "session.start", "session.fork", "session.resume"].includes(operation)) assertDaemonDispatch(this.paths.dir);
+    if (operation === "session.observe-children") {
+      assertDaemonDispatch(this.paths.dir);
+      const root = this.sessions.get(params.sessionId);
+      if (!root || root.close_receipt) throw new DaemonError("session_identity_mismatch", "Retained observation requires a registered open root Session");
+      const generation = this.controlGeneration ?? 0;
+      const active = this.state.active_request;
+      const activeIdentity = value => JSON.stringify([value?.operation_id ?? null, value?.session_id ?? null, value?.adapter_session_id ?? null, value?.generation ?? null]);
+      const capturedIdentity = activeIdentity(active);
+      if (active && active.session_id !== params.sessionId) throw new DaemonError("session_identity_mismatch", "Retained observation has a foreign active root");
+      const cacheScope = `${params.sessionId}:${generation}`;
+      if (this.childObservationScope !== cacheScope) { this.childObservationScope = cacheScope; this.childTerminalCache = new Map(); this.childObservationKeys = new Set(); }
+      const subagents = await readZcodeSubagents(this.bridge, root.adapter_session_id, 30_000, true, this.childTerminalCache, root.provider_session_id);
+      if (generation !== (this.controlGeneration ?? 0)) throw new DaemonError("operation_cancelled", "Observation generation was retired");
+      if (activeIdentity(this.state.active_request) !== capturedIdentity) throw new DaemonError("operation_cancelled", "Observation belongs to a retired active Turn");
+      assertDaemonDispatch(this.paths.dir);
+      const receipt = { schema_id: "dd-zcode/child-observation@1", daemon_id: this.state.daemon_id, provider_session_id: params.sessionId,
+        generation, active_operation_id: active?.operation_id ?? null, subagents };
+      const failed = (subagents.ended?.items ?? subagents.completed ?? []).filter(child => child.status === "failed" && child.terminal_turn_id);
+      const fresh = failed.filter(child => !this.childObservationKeys.has(`${child.childSessionId}:${child.terminal_turn_id}`));
+      if (fresh.length) {
+        await this.bridge.journal.write("native_child_observation", { ...receipt, subagents: { running: [], ended: { total: fresh.length, items: fresh } } });
+        await this.bridge.journal.flush();
+        if (this.state.config?.journal) {
+          const journal = await open(this.state.config.journal, "a");
+          try { await journal.sync(); } finally { await journal.close(); }
+        }
+        for (const child of fresh) this.childObservationKeys.add(`${child.childSessionId}:${child.terminal_turn_id}`);
+      }
+      if (generation !== (this.controlGeneration ?? 0)) throw new DaemonError("operation_cancelled", "Observation generation was retired before ACK");
+      if (activeIdentity(this.state.active_request) !== capturedIdentity) throw new DaemonError("operation_cancelled", "Observation Turn changed before ACK");
+      assertDaemonDispatch(this.paths.dir);
+      return receipt;
+    }
+    if (operation === "daemon.status") return {
+      daemon_id: this.state.daemon_id, pid: process.pid, socket: this.paths.socket,
+      cwd: this.state.cwd, journal: this.state.journal, versions: this.state.versions,
+      started_at: this.state.started_at, updated_at: this.state.updated_at,
+      shutdown_state: this.state.shutdown_state, recovery_status: this.state.recovery_status,
+      active_tree: this.state.active_tree, active_operation: this.activeProductive, active_request: this.state.active_request ?? null,
+      sessions: [...this.sessions.values()], config: this.state.config, capabilities: { retained_child_observation: true },
+    };
+    if (operation === "hook.resolve") {
+      const sessionId = String(params.sessionId ?? "");
+      const payload = params.payload, command = payload?.tool_input?.command ?? payload?.tool_input?.cmd;
+      const tool = payload?.tool_use_id ?? payload?.tool_call_id;
+      const source = this.bridge.nativeHookOwnership;
+      let proof = source?.fact(sessionId, tool, command);
+      const tracked = this.sessions.get(sessionId);
+      if (!proof && (!tracked || tracked.parent_provider_session_id) && source && tool && typeof command === "string") {
+        await source.wait(sessionId, tool, command, params.hookDeadlineAt);
+        proof = source.fact(sessionId, tool, command);
+      }
+      const session = proof ? { root_provider_session_id: proof.root, parent_provider_session_id: proof.parent } : tracked;
+      if (!session?.root_provider_session_id) throw new DaemonError("hook_identity_unknown", "ZCode hook Session is not a tracked controlled Session", false, { session_id: sessionId });
+      const identity = { daemonId: this.state.daemon_id, rootProviderSessionId: session.root_provider_session_id, parentProviderSessionId: session.parent_provider_session_id ?? null, observedProfile: this.bridge.modelProfiles?.get(sessionId) ?? {} };
+      if (payload?.hook_event_name === "PreToolUse" && typeof command === "string" && (["lifecycle", "auxiliary"].includes(parseLifecycleCommand(command).participation) || continuationCommand(command))) {
+        // A retained child can only be attributed through the exact observed
+        // native turn and tool. Otherwise preserve the legacy handler without
+        // guessing that the currently active prompt created it.
+        if (sessionId !== session.root_provider_session_id && !proof) return identity;
+        const current = proof?.owner ?? this.nativeHookOperation, active = this.state.active_request;
+        const pending = [...(this.bridge.pending?.values() ?? [])].some(request => request.method === "session/prompt" && request.sessionId === active?.adapter_session_id);
+        const root = active?.session_id ?? active?.allocation?.provider_session_id;
+        if (!current || current.generation !== (this.controlGeneration ?? 0) || !tool || !proof && (!active || !pending || session.root_provider_session_id !== root)) throw new DaemonError("native_hook_unproven", "Native hook has no exact owned Session operation");
+        assertDaemonDispatch(this.paths.dir);
+        const nativePayload = proof ? { ...proof.message, _meta: { ...(proof.message._meta ?? {}), ddZcode: { daemonId: this.state.daemon_id, rootProviderSessionId: proof.root, parentProviderSessionId: proof.parent } } } : null;
+        const binding = await acceptNativeHookRequest(this.paths.dir, { daemon_id: this.state.daemon_id, operation_id: current.operationId, turn_generation: current.generation, provider_session_id: sessionId, root_provider_session_id: session.root_provider_session_id, parent_provider_session_id: session.parent_provider_session_id ?? null, tool_call_id: tool, event: "PreToolUse", command_sha256: createHash("sha256").update(command).digest("hex"), native_cwd: payload.cwd ?? null, native_creator: proof ? "confirmed" : "unconfirmed", ...(proof ? { source_harness: "zcode-acp", native_command: command, native_payload: nativePayload } : {}) }, current);
+        if (current.generation !== (this.controlGeneration ?? 0) || proof && source.fact(sessionId, tool, command) !== proof || !proof && this.nativeHookOperation !== current) throw new DaemonError("native_hook_unproven", "Native hook operation changed during acceptance");
+        current.requests.set(binding.request_id, { current, binding }); identity.nativeHookBinding = binding;
+        const parsed = parseLifecycleCommand(command);
+        if (proof && parsed.kind === "standalone" && parsed.invocation.operation === "work_start" && commandOption(parsed.invocation, "invocation-id")) identity.fastAck = true;
+      }
+      return identity;
+    }
+    if (operation === "hook.verify") {
+      if (params.daemonId !== this.state.daemon_id) throw new DaemonError("native_hook_unproven", "Native hook daemon identity differs");
+      const owner = this.hookOwner(params.binding);
+      if (!owner) throw new DaemonError("native_hook_unproven", "Native hook has no matching retained operation");
+      assertDaemonDispatch(this.paths.dir);
+      return { verified: true, nativeHookBinding: params.binding };
+    }
+    if (operation === "hook.failed") {
+      if (params.binding !== undefined || params.failure !== undefined) {
+        const binding = params.binding, failure = params.failure, current = this.hookOwner(binding);
+        // Join an in-flight file observation before checking the request. A
+        // direct fallback and its receipt must not be delivered twice.
+        while (current?.reading) await current.reading;
+        const accepted = current?.requests.get(binding?.request_id);
+        if (!current || this.hookOwner(binding) !== current || accepted?.current !== current
+          || JSON.stringify(accepted.binding) !== JSON.stringify(binding) || typeof failure?.code !== "string" || typeof failure?.message !== "string")
+          throw new DaemonError("native_hook_unproven", "Hook failure has no exact current owned delivery");
+        assertDaemonDispatch(this.paths.dir);
+        if (this.nativeHookOperation !== current) {
+          await writeNativeHookFailure(this.paths.dir, binding, reportedError(failure, "Native hook failed"));
+          return { observed: true, retained: true };
+        }
+        current.requests.delete(binding.request_id);
+        const error = reportedError(failure, "Native hook failed");
+        error.details = { ...error.details, native_hook_binding: binding };
+        this.acceptHookFailure(current, error);
+        return { observed: true };
+      }
+      await this.observeHookFailures(); return { observed: true };
+    }
+    if (operation === "session.create") {
+      const request = {
+        operation_id: operationId,
+        request_id: randomUUID(),
+        session_id: params.sessionId ?? null,
+        adapter_session_id: params.adapterSessionId ?? params.sessionId ?? null,
+        generation: this.controlGeneration ?? 0,
+        dispatched_at: new Date().toISOString(),
+        request_timeout_ms: this.state.config.requestTimeoutMs,
+      };
+      return await this.productive(operation, async () => await createSessionWithBridge(this.bridge, this.options(params), this.initialized), request);
+    }
+    if (operation === "session.prompt") {
+      if (this.sessions.get(params.sessionId)?.close_receipt) throw new DaemonError("session_closed", "Closed Session requires explicit recovery before another prompt");
+      const known = this.sessions.get(params.sessionId);
+      const request = {
+        operation_id: operationId,
+        request_id: randomUUID(),
+        session_id: params.sessionId,
+        adapter_session_id: params.adapterSessionId ?? known?.adapter_session_id ?? params.sessionId,
+        generation: this.controlGeneration ?? 0,
+        dispatched_at: new Date().toISOString(),
+        request_timeout_ms: this.state.config.requestTimeoutMs,
+      };
+      const result = await this.productive(operation, async () => { await this.requireSettled(params); await this.markPromptDispatched(params.sessionId); return await promptSessionWithBridge(this.bridge, { ...this.options(params), timeoutMs: request.request_timeout_ms }); }, request);
+      const session = this.sessions.get(result.provider_session_id); if (session) session.completed_turns = (session.completed_turns ?? 0) + 1;
+      await this.persist(); return result;
+    }
+    if (operation === "session.fork") return await this.productive(operation, async () => { await this.requireSettled(params); await this.markPromptDispatched(params.sessionId); return await forkSessionWithBridge(this.bridge, this.options(params)); });
+    if (operation === "session.inspect" || operation === "session.resume") {
+      const closed = this.sessions.get(params.sessionId)?.close_receipt;
+      if (closed) {
+        if (operation === "session.resume") throw new DaemonError("session_closed", "Closed Session requires explicit recovery");
+        const topology = closed.topology;
+        if (topology?.root_session_id !== params.sessionId || !Array.isArray(topology.child_session_ids) || topology.child_session_ids.some(id => typeof id !== "string" || !id)) return { ...closed, settled: false, observation_error: { code: "topology_incomplete", message: "closed Session has no native topology identity" } };
+        const previous = this.state.settlement_observations?.[params.sessionId];
+        // A confirmed closed tree cannot resume through this daemon. Retain
+        // that terminal evidence even after its bridge has been retired.
+        for (const receipt of [previous, closed]) {
+          if (receipt?.close?.closed === true && receipt.settled === true
+            && receipt.topology?.complete === true && receipt.topology.root_session_id === params.sessionId
+            && Array.isArray(receipt.topology.child_session_ids)) return nativeExecutionReceipt(receipt, { daemonId: this.state.daemon_id, generation: this.controlGeneration ?? 0 });
+        }
+        const known = [...new Set([...topology.child_session_ids, ...(previous?.topology?.child_session_ids ?? [])])];
+        const emptyRoot = this.neverPromptedRootProof(params.sessionId);
+        const observation = { ...closed, ...await observeClosedZcodeTree(this.bridge, params.sessionId, known, emptyRoot && closed.close?.closed === true ? {...emptyRoot,close_confirmed:true} : null), observed_at: new Date().toISOString() };
+        // Observations are not ownership inventory: their timestamps must not
+        // invalidate a drain fence on every read.
+        this.state.settlement_observations ??= {};
+        this.state.settlement_observations[params.sessionId] = observation;
+        await this.persist();
+        return nativeExecutionReceipt(observation, { daemonId: this.state.daemon_id, generation: this.controlGeneration ?? 0 });
+      }
+      const adapter = params.adapterSessionId ?? params.sessionId;
+      if (!this.liveAdapters.has(adapter) && this.activeProductive) {
+        throw new DaemonError(
+          "child_inspection_unavailable",
+          "cannot inspect an unregistered child while a daemon-owned turn is running; inspection would resume and mutate it",
+          true,
+          { session_id: params.sessionId },
+        );
+      }
+      const result = await inspectSessionWithBridge(this.bridge, this.options(params));
+      // A child can be inspected through its parent's live bridge, but is not
+      // an independently daemon-owned root Session. Do not promote it into
+      // `sessions`: daemon shutdown would then treat the child as a second
+      // root and could reject an otherwise settled parent tree.
+      if (this.sessions.has(result.provider_session_id)) this.track(result, result.subagents);
+      else if (result.adapter_session_id) this.liveAdapters.add(result.adapter_session_id);
+      await this.persist({ active_tree: this.treeRunning(result) || Boolean(this.activeProductive) });
+      const settled = !this.treeRunning(result) && !this.activeProductive;
+      const failure = this.state.last_native_failure;
+      const nativeChildren = (result.evidence ?? result).subagents;
+      const childIds = [...new Set([...(this.sessions.get(result.provider_session_id)?.known_child_session_ids ?? []), ...zcodeChildSessionIds(nativeChildren)])];
+      const childStates = new Map([...(nativeChildren?.ended?.items ?? nativeChildren?.completed ?? []), ...(nativeChildren?.running ?? []).map(child => ({ ...child, status: "running" }))].map(child => [child.childSessionId ?? child.sessionId, child.status]));
+      const rootSettled = !this.activeProductive && failure?.provider_session_id === result.provider_session_id && (result.evidence ?? result).read?.projection?.status === "idle";
+      return nativeExecutionReceipt({ ...result, settled, ...settledNativeTree(result.provider_session_id, childIds.map(childSessionId => ({ childSessionId, status: childStates.get(childSessionId) ?? "unknown" })), settled, rootSettled),
+        ...(failure?.provider_session_id === result.provider_session_id ? { terminal_turn_id: String(failure.request_id) } : {}) }, { daemonId: this.state.daemon_id, generation: this.controlGeneration ?? 0 });
+    }
+    if (operation === "session.cancel") {
+      if (!this.sessions.has(params.sessionId)) throw new DaemonError("session_identity_mismatch", "cancellation Session is not owned by this daemon");
+      const closed = this.sessions.get(params.sessionId)?.close_receipt;
+      if (closed) return closed;
+      this.controlGeneration = (this.controlGeneration ?? 0) + 1;
+      const result = await cancelSessionWithBridge(this.bridge, this.options(params));
+      this.track(result, result.after);
+      await this.persist({ active_tree: result.settled !== true && (this.treeRunning(result) || Boolean(this.activeProductive)) });
+      return result;
+    }
+    if (operation === "session.cancel-child") {
+      const result = await cancelChildWithBridge(this.bridge, this.options(params));
+      this.track(result, result.after);
+      await this.persist({ active_tree: this.treeRunning(result) || Boolean(this.activeProductive) });
+      return result;
+    }
+    if (operation === "daemon.stop") return await completeDaemonShutdown(this.paths.dir, this.state, patch => this.persist(patch), () => this.prepareStop(params.cancelTree === true), [
+      ["provider", () => this.bridge.close?.()],
+      ["provider_resource", () => finishDaemonProcess(this.state.config, this.state.provider_process)],
+      ["daemon_resource", () => finishDaemonProcess(this.state.config, this.state.resource_process)]
+    ], undefined, { cancelTree: params.cancelTree === true });
+    throw new DaemonError("unknown_operation", `unknown daemon operation: ${operation}`);
+  }
+
+  async prepareStop(cancel) {
+    if (this.activeProductive && !cancel) throw new DaemonError("tree_not_settled", "productive operation is running");
+    if (cancel) this.controlGeneration = (this.controlGeneration ?? 0) + 1;
+    if (!this.state.native_stop_proof || this.state.native_stop_proof.daemon_id !== this.state.daemon_id) {
+    const unsettled = [];
+    for (const session of this.sessions.values()) {
+      if (session.close_receipt) {
+        const observed = await this.dispatch("session.inspect", { sessionId: session.provider_session_id });
+        if (observed.settled !== true) unsettled.push(session.provider_session_id);
+        continue;
+      }
+      const options = this.options({ sessionId: session.provider_session_id, adapterSessionId: session.adapter_session_id });
+      let observed;
+      // A daemon-owned allocation with no productive dispatch cannot have
+      // children, and native ZCode has no durable read index for it yet. Close
+      // that resident directly; do not send cancellation for default stop.
+      const emptyRoot = !cancel && !this.activeProductive ? this.neverPromptedRootProof(session.provider_session_id) : null;
+      if (emptyRoot) {
+        const close = await this.bridge.request("zcode/session/close", { sessionId: session.adapter_session_id });
+        const observation = close?.closed === true
+          ? await observeClosedZcodeTree(this.bridge, session.provider_session_id, [], { ...emptyRoot, close_confirmed: true })
+          : { settled: false, topology: { root_session_id: session.provider_session_id, child_session_ids: [], complete: false } };
+        this.track({ provider_session_id: session.provider_session_id, adapter_session_id: session.adapter_session_id, cancellation_requested: false, close_requested: true, close, ...observation });
+        await this.persist({ active_tree: observation.settled !== true });
+        if (observation.settled !== true) unsettled.push(session.provider_session_id);
+        continue;
+      }
+      if (!cancel) observed = await inspectSessionWithBridge(this.bridge, options);
+      if (cancel || !observed || this.treeRunning(observed)) {
+        if (!cancel) unsettled.push(session.provider_session_id);
+        else {
+          let cancelled;
+          try { cancelled = await cancelSessionWithBridge(this.bridge, options); }
+          catch (error) { unsettled.push(session.provider_session_id); continue; }
+          this.track(cancelled, cancelled.after);
+          await this.persist({ active_tree: cancelled.settled !== true });
+          if (cancelled.close?.closed === true) {
+            if (!cancelled.settled) unsettled.push(session.provider_session_id);
+            continue;
+          }
+          // A cooperative cancel needs a final read. A close receipt is
+          // terminal itself: native session/read correctly rejects it as no
+          // longer resident, so treating that rejection as unsettled would
+          // turn a successful close into an immortal daemon.
+          if (!cancelled.settled) {
+            try { observed = await inspectSessionWithBridge(this.bridge, options); }
+            catch (error) { unsettled.push(session.provider_session_id); continue; }
+            if (this.treeRunning(observed)) unsettled.push(session.provider_session_id);
+          }
+        }
+      }
+    }
+    if (unsettled.length) throw new DaemonError("tree_not_settled", "daemon still owns running Sessions", false, { sessions: unsettled });
+    commitDaemonShutdown(this.paths.dir);
+    await this.persist({ native_stop_proof: { daemon_id: this.state.daemon_id, sessions: [...this.sessions.keys()], observed_at: new Date().toISOString() } });
+    }
+    commitDaemonShutdown(this.paths.dir);
+    if (!cancel) {
+      // The native tree has been observed idle. Publish that execution proof
+      // before attempting to close the independent bridge process. A close
+      // failure is cleanup debt and must not erase the already observed turn.
+      await this.persist({ active_tree: false, shutdown_state: "stopping", active_operation: null, active_request: null });
+      return { daemon_id: this.state.daemon_id, clean: true, settled: true, native_settled: true };
+    }
+    // A cooperative close can make the native Session non-resident while its
+    // original ACP prompt is still pending.  For an explicitly whole-RUN
+    // cancellation this daemon owns the bridge process group, so retire that
+    // group now rather than reporting a clean-looking but still live tree.
+    // A per-child cancellation never takes this path.
+    let bridgeClosed = false;
+    if (this.activeProductive && cancel) {
+      try {
+        if (typeof this.bridge.close === "function") await this.bridge.close();
+        bridgeClosed = true;
+      } catch (error) {
+        throw new DaemonError(error.code ?? "provider_process_stop_incomplete", error.message ?? String(error), false, error.details);
+      }
+    }
+    const deadline = Date.now() + 5000;
+    while (this.activeProductive && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 50));
+    if (this.activeProductive) throw new DaemonError("tree_not_settled", "productive operation did not settle after cancellation");
+    // The owned bridge process group is the physical stop barrier. A native
+    // closed/resident receipt only proves API state and cannot seal recovery.
+    // A bridge without a close method occurs only in in-memory diagnostics: it
+    // owns no OS process boundary. Production AcpBridge always has one.
+    try { if (!bridgeClosed && typeof this.bridge.close === "function") await this.bridge.close(); }
+    catch (error) { throw new DaemonError(error.code ?? "provider_process_stop_incomplete", error.message ?? String(error), false, error.details); }
+    await this.persist({ active_tree: false, shutdown_state: "stopping", active_operation: null, active_request: null, physical_settlement: { confirmed_at: new Date().toISOString(), bridge_pid: this.bridge.child?.pid ?? null } });
+    return { daemon_id: this.state.daemon_id, stopped: true, clean: true, settled: true, native_settled: true, physical_settlement: this.state.physical_settlement, _shutdown: true };
+  }
+
+}
+
+export function zcodeBridgeEnv(config, daemonId) {
+  return { ...config.env, ...managedFlowEnv(config, daemonId), DD_ZCODE_STATE_DIR: !config.noFlow && daemonId ? config.runtime_owner?.state_dir : undefined };
+}
+
+export async function serveDaemon(stateDir) {
+  const paths = locations(stateDir);
+  const state = await readState(paths.dir);
+  if (!state || state.schema_id !== STATE_SCHEMA) throw new DaemonError("daemon_state_missing", "daemon state is missing or incompatible");
+  const bridge = new AcpBridge({ ...state.config, env: zcodeBridgeEnv(state.config, state.daemon_id) });
+  const initialized = await startManagedBridge({ config: state.config, state, bridge, kind: "zcode-provider", publish: snapshot => writeState(paths.state, snapshot), log: paths.log });
+  const runtime = new DaemonRuntime(paths, state, bridge, initialized);
+  scheduleDaemonProcessHeartbeat(state.config, state.resource_process);
+  await removeSocket(paths.socket, paths.dir);
+  const server = net.createServer((connection) => {
+    connection.setEncoding("utf8"); let buffer = "", consumed = false;
+    connection.on("data", (chunk) => {
+      if (consumed) return;
+      buffer += chunk; if (!admitNativeRequestBuffer(buffer, connection, RESPONSE_SCHEMA)) { consumed = true; return; }
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) return;
+      consumed = true;
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      void (async () => {
+        let request;
+        try {
+          request = JSON.parse(line);
+          if (request.schema_id !== REQUEST_SCHEMA || !request.id || !request.operation) throw new DaemonError("daemon_protocol_mismatch", "invalid daemon request");
+          const result = await durableDaemonDispatch(paths.dir, request, () => runtime.dispatch(request.operation, request.params ?? {}, request.id), () => runtime.dispatch("session.inspect", request.params ?? {}));
+          if (result?._shutdown) retireDaemonEndpoint(server);
+          connection.end(`${JSON.stringify({ schema_id: RESPONSE_SCHEMA, id: request.id, ok: true, result: { ...result, _shutdown: undefined } })}\n`);
+        } catch (error) {
+          await retireFailedDaemon(server, state, error, patch => runtime.persist(patch));
+          connection.end(`${JSON.stringify({ schema_id: RESPONSE_SCHEMA, id: request?.id ?? null, ok: false, error: errorPayload(error) })}\n`);
+        }
+      })();
+    });
+  });
+  runtime.server = server;
+  trackDaemonConnections(server);
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(paths.socket, resolve); });
+  await chmod(paths.socket, 0o600);
+  await runtime.persist({ shutdown_state: "running", active_tree: false });
+  let shuttingDown = false;
+  const onSignal = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    void runtime.shutdown().catch(async () => { await runtime.persist({ shutdown_state: "running" }); }).finally(() => process.exit(1));
+  };
+  process.on("SIGTERM", onSignal);
+  process.on("SIGINT", onSignal);
+  return await new Promise(() => {});
+}
+import { authorizeRetainedDaemonResume } from "./driver-recovery.mjs";