@deksden-com/dd-flow-cli 0.9.0-beta.7 → 0.9.0-beta.75

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

@@ -0,0 +1,644 @@
+import { observedTimeout } 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 } from "./daemon-operations.mjs";
+import path from "node:path";
+import { prepareRuntimeOwner, cleanupFailedStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, heartbeatDaemonProcess, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.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; }
+}
+
+function errorPayload(error) {
+  return {
+    code: error.code ?? "operation_failed",
+    message: error.message ?? String(error),
+    retryable: error.retryable === true,
+    ...(error.details === undefined ? {} : { details: error.details }),
+  };
+}
+
+export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 30_000) {
+  const { socket } = locations(stateDir);
+  const request = { schema_id: REQUEST_SCHEMA, id: process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation, params };
+  return await new Promise((resolve, reject) => {
+    const client = net.createConnection(socket);
+    let buffer = ""; let settled = false;
+    // A prompt has its own sliding ACP liveness deadline.  Do not add an
+    // independent wall-clock deadline here: it can cut off an actively
+    // producing Turn merely because it is long.
+    const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? observedTimeout(() => { client.destroy(); reject(new DaemonError("daemon_timeout", `${operation} timed out`, true)); }, timeoutMs)
+      : null;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true; if (timer) clearTimeout(timer); client.destroy(); error ? reject(error) : resolve(value);
+    };
+    client.setEncoding("utf8");
+    client.on("connect", () => client.write(`${JSON.stringify(request)}\n`));
+    client.on("data", (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) return;
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        if (response.schema_id !== RESPONSE_SCHEMA || response.id !== request.id) return finish(new DaemonError("daemon_protocol_mismatch", "invalid daemon response"));
+        if (!response.ok) return finish(new DaemonError(response.error?.code ?? "operation_failed", response.error?.message ?? "daemon operation failed", response.error?.retryable, response.error?.details));
+        finish(null, response.result);
+      } catch (error) { finish(new DaemonError("daemon_protocol_mismatch", error.message)); }
+    });
+    client.on("error", (error) => finish(new DaemonError("daemon_not_running", error.message, true)));
+    client.on("end", () => finish(new DaemonError("daemon_connection_closed", `${operation} connection closed before a response`, true)));
+    client.on("close", () => finish(new DaemonError("daemon_connection_closed", `${operation} connection closed before a response`, true)));
+  });
+}
+
+function sameConfig(state, config) {
+  return ["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: options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {},
+    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);
+  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; }
+
+  const previous = await readState(paths.dir);
+  if (previous?.shutdown_state === "clean") 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 deadline = Date.now() + 15_000;
+    while (Date.now() < deadline) {
+      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 new DaemonError("daemon_start_failed", "daemon did not become ready", true);
+  } catch (error) {
+    await cleanupFailedStart(config, resourceProcess, child, error);
+    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);
+}
+
+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.then(() => writeState(this.paths.state, snapshot));
+    const resourceProcess = this.state.resource_process;
+    if (resourceProcess?.id && resourceProcess.lease_token) {
+      this.persisting = this.persisting.then(async () => {
+        try { await heartbeatDaemonProcess(this.state.config, resourceProcess); }
+        catch { /* A crashed client is recovered through the durable lease. */ }
+      });
+    }
+    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, knownChildSessionIds: known?.known_child_session_ids ?? [], adapterSessionId: adapter,
+      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"); },
+      // 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 }) => {
+        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),
+            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) 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);
+        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,
+      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;
+    try {
+      await this.persist({ active_tree: true, active_operation: name, ...(request ? { active_request: request } : {}) });
+      const result = await task();
+      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 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 { this.activeProductive = null; this.activeGeneration = null; }
+  }
+
+  async requireSettled(params) {
+    if (this.sessions.get(params.sessionId)?.close_receipt) throw new DaemonError("session_closed", "Closed Session requires explicit recovery");
+    const known = this.sessions.get(params.sessionId);
+    // 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 (known && (known.completed_turns ?? 0) === 0) 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;
+  }
+
+  async dispatch(operation, params) {
+    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 });
+      return { 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 (operation === "session.create") {
+      const request = {
+        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 = {
+        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); 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); 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 observation = { ...closed, ...await observeClosedZcodeTree(this.bridge, params.sessionId, known), 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 this.prepareStop(params.cancelTree === true);
+    throw new DaemonError("unknown_operation", `unknown daemon operation: ${operation}`);
+  }
+
+  async prepareStop(cancel) {
+    if (cancel) this.controlGeneration = (this.controlGeneration ?? 0) + 1;
+    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;
+      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 });
+    // 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);
+      }
+    }
+    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); }
+    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 };
+  }
+
+  async shutdown() {
+    // prepareStop has already closed the owned bridge. Signal shutdown may get
+    // here directly, so close remains idempotent.
+    await this.bridge.close();
+    await this.persist({ active_tree: false, shutdown_state: "clean", stopped_at: new Date().toISOString() });
+    const resourceProcess = this.state.resource_process;
+    if (resourceProcess?.id && resourceProcess.lease_token) {
+      try { await finishDaemonProcess(this.state.config, resourceProcess, "stopped", "daemon_stopped"); }
+      catch { /* Keep the state; the next reconciler owns stale processes. */ }
+    }
+    await new Promise((resolve) => this.server.close(resolve));
+    await removeSocket(this.paths.socket, this.paths.dir);
+  }
+}
+
+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);
+  const initialized = await bridge.start();
+  const runtime = new DaemonRuntime(paths, state, bridge, initialized);
+  await removeSocket(paths.socket, paths.dir);
+  const server = net.createServer((connection) => {
+    connection.setEncoding("utf8"); let buffer = "";
+    connection.on("data", (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) return;
+      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 ?? {}), () => runtime.dispatch("session.inspect", request.params ?? {}));
+          connection.end(`${JSON.stringify({ schema_id: RESPONSE_SCHEMA, id: request.id, ok: true, result: { ...result, _shutdown: undefined } })}\n`);
+          if (result?._shutdown) setImmediate(() => void runtime.shutdown().then(() => process.exit(0)));
+        } catch (error) {
+          connection.end(`${JSON.stringify({ schema_id: RESPONSE_SCHEMA, id: request?.id ?? null, ok: false, error: errorPayload(error) })}\n`);
+        }
+      })();
+    });
+  });
+  runtime.server = 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";