@deksden-com/dd-flow-cli 0.9.0-beta.13 → 0.9.0-beta.134

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

@@ -0,0 +1,703 @@
+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 { 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 { prepareRuntimeOwner, cleanupFailedDaemonStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, scheduleDaemonProcessHeartbeat, registerDaemonProcess, startManagedBridge, stopProcessGroup } from "./managed-daemon.mjs";
+import { acceptNativeHookRequest, hookBudget, readNativeHookFailures } from "./native-hook-command.mjs";
+import { parseLifecycleCommand, continuationCommand } from "./lifecycle-command.mjs";
+import { errorRecord, isProvenShellCorrection } from "./operation-errors.mjs";
+
+import {
+  AcpBridge,
+  cancelSessionWithBridge,
+  cancelChildWithBridge,
+  createSessionWithBridge,
+  doctor,
+  forkSessionWithBridge,
+  inspectSessionWithBridge,
+  promptSessionWithBridge,
+  zcodeChildSessionIds,
+  observeClosedZcodeTree,
+} from "./dd-zcode.mjs";
+
+const REQUEST_SCHEMA = "dd-zcode/daemon-request@1";
+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 = { 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) {
+  const paths = locations(options.stateDir);
+  const hasFlowContext = Boolean(options.ddFlowHome || options.projectRoot || options.ddFlowBin);
+  if (hasFlowContext && (!options.ddFlowHome || !options.projectRoot)) {
+    throw new DaemonError("flow_context_incomplete", "--dd-flow-home 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,
+    // The worker itself invokes `dd-flow` from PATH.  Use that same executable
+    // for the trusted event bridge unless a pinned executable was supplied.
+    ddFlowBin: hasFlowContext ? (options.ddFlowBin ? absolute(options.ddFlowBin, "--dd-flow-bin") : "dd-flow") : null,
+    ddFlowHome: options.ddFlowHome ? absolute(options.ddFlowHome, "--dd-flow-home") : null,
+    projectRoot: options.projectRoot ? absolute(options.projectRoot, "--project-root") : null,
+    resourceHome: 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())) {
+      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.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, 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, generation: this.activeGeneration, requests: new Map() };
+    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 {
+      await this.persist({ active_tree: true, active_operation: name, ...(request ? { active_request: request } : {}) });
+      const result = await Promise.race([task(), hookFailed]);
+      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;
+      try {
+        await hookBudget(1_000, null).run(() => this.persist({
+          active_operation: null,
+          active_request: active?.allocation
+            ? { ...active, outcome: "unknown", error: errorPayload(error) }
+            : null,
+        }), "failure_persistence");
+      } 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); 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 || current.reading) return;
+    current.reading = true;
+    try { await readNativeHookFailures(this.paths.dir, current.requests, current, error => {
+      if (!isProvenShellCorrection(error)) current.reject(error);
+    }); } finally { current.reading = false; }
+  }
+
+  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 === "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,
+    };
+    if (operation === "hook.resolve") {
+      const sessionId = String(params.sessionId ?? "");
+      const session = this.sessions.get(sessionId);
+      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) ?? {} };
+      const payload = params.payload, command = payload?.tool_input?.command ?? payload?.tool_input?.cmd;
+      if (payload?.hook_event_name === "PreToolUse" && typeof command === "string" && (["lifecycle", "auxiliary"].includes(parseLifecycleCommand(command).participation) || continuationCommand(command))) {
+        const current = this.nativeHookOperation, active = this.state.active_request;
+        const tool = payload.tool_use_id ?? payload.tool_call_id;
+        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 || !active || !pending || current.generation !== (this.controlGeneration ?? 0) || session.root_provider_session_id !== root || !tool) throw new DaemonError("native_hook_unproven", "Native hook has no exact active Session operation");
+        const binding = await hookBudget(1_000, null).run(() => 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, tool_call_id: tool, event: "PreToolUse", command_sha256: createHash("sha256").update(command).digest("hex"), native_cwd: payload.cwd ?? null }, current), "hook_binding");
+        if (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;
+      }
+      return identity;
+    }
+    if (operation === "hook.failed") { 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 receipt;
+        }
+        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 observation;
+      }
+      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) });
+      return { ...result, settled: !this.treeRunning(result) && !this.activeProductive };
+    }
+    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_resource", () => finishDaemonProcess(this.state.config, this.state.provider_process)],
+      ["daemon_resource", () => finishDaemonProcess(this.state.config, this.state.resource_process)]
+    ]);
+    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);
+    // 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, physical_settlement: this.state.physical_settlement, _shutdown: true };
+  }
+
+}
+
+export function zcodeBridgeEnv(config, daemonId) {
+  return { ...config.env, DD_FLOW_DAEMON_ID: daemonId,
+    DD_FLOW_RUNTIME_OWNER: config.runtime_owner ? JSON.stringify(config.runtime_owner) : 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) });
+  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";