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

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

@@ -0,0 +1,667 @@
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import { SETUP_STARTUP_MS, startupObserver, observationDetails } from './setup-progress.mjs';
+import { callDaemonObserved } from './daemon-observation.mjs';
+import { canonicalNativeOperation } from './adapter-timeouts.mjs';
+import { admitNativeRequestBuffer } from "./native-streams.mjs";
+import { prepareDaemonRequest } from "./native-request-proof.mjs";
+import { captureDispatchGuard, cancelPendingDispatch } from "./dispatch-fence.mjs";
+import { errorRecord, isNativeHookObservationLoss, isProvenShellCorrection, reportedError } from "./operation-errors.mjs";
+import { ToolObservations, acpToolObservation } from "./tool-observations.mjs";
+import { acceptNativeHookRequest, readNativeHookFailures, writeNativeHookFailure } from "./native-hook-command.mjs";
+import { parseLifecycleCommand, continuationCommand, commandOption } from "./lifecycle-command.mjs";
+import { ObservationClock } from "./observation-clock.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, copyFile, cp, lstat, mkdir, open, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { durableDaemonDispatch as dispatchOperation, completeDaemonShutdown, trackDaemonConnections, retireDaemonEndpoint, retireFailedDaemon, assertDaemonDispatch, assertDaemonRestartable } from "./daemon-operations.mjs";
+import { waitForSettlement } from "./session-settlement.mjs";
+import os from "node:os";
+import path from "node:path";
+
+import { AcpBridge } from "./dd-zcode.mjs";
+import { safeProviderError } from "./provider-overload-policy.mjs";
+import { settledNativeTree, nativeExecutionReceipt } from "./native-children.mjs";
+import { observeModel, readModelObservations } from "./model-observations.mjs";
+import { cancelSessionWithBridge, createSessionWithBridge, doctor, forkSessionWithBridge, inspectSessionWithBridge, promptSessionWithBridge } from "./dd-grok.mjs";
+import { prepareRuntimeOwner, cleanupFailedDaemonStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, scheduleDaemonProcessHeartbeat, registerDaemonProcess, startManagedBridge, stopProcessGroup } from "./managed-daemon.mjs";
+
+const REQUEST_SCHEMA = "dd-grok/daemon-request@1";
+const RESPONSE_SCHEMA = "dd-grok/daemon-response@1";
+const STATE_SCHEMA = "dd-grok/daemon-state@1";
+// Normalize raw socket callers too, before the shared layer reserves capacity.
+export function durableDaemonDispatch(root, request, action, observe) {
+  return dispatchOperation(root, { ...request, operation: canonicalNativeOperation("grok", request.operation) }, action, observe);
+}
+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"); return { dir, socket: Buffer.byteLength(localSocket) < 100 ? localSocket : `/tmp/dd-grok-${createHash("sha256").update(dir).digest("hex").slice(0, 24)}.sock`, state: path.join(dir, "daemon.json"), log: path.join(dir, "daemon.log"), home: path.join(dir, "grok-home") }; }
+async function readState(dir) { try { return JSON.parse(await readFile(locations(dir).state, "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 its 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;
+function shellQuote(value) { return `'${String(value).replace(/'/g, "'\\''")}'`; }
+
+function executable(command, args = []) { const resolved = command ?? process.env.DD_GROK_BIN ?? "grok"; return /\.[cm]?js$/.test(resolved) ? { command: process.execPath, args: [resolved, ...args] } : { command: resolved, args }; }
+export function isolatedEnv(config) { return { ...process.env, HOME: config.grokHome, GROK_HOME: config.grokHome, ...(config.authPath ? { GROK_AUTH_PATH: config.authPath } : {}), ...managedFlowEnv(config),
+  DD_GROK_STATE_DIR: !config.noFlow && config.daemonId ? config.runtime_owner?.state_dir : undefined }; }
+function within(candidate, root) { const resolved = path.resolve(candidate); const parent = path.resolve(root); return resolved === parent || resolved.startsWith(`${parent}${path.sep}`); }
+
+async function writeIsolatedConfig(paths) {
+  const disabled = ["skills", "rules", "agents", "mcps", "hooks", "sessions"].map((key) => `${key} = false`).join("\n");
+  await writeFile(path.join(paths.home, "config.toml"), `# Managed by dd-grok. Do not add user configuration here.\n[cli]\nauto_update = false\n\n[compat.claude]\n${disabled}\n\n[compat.cursor]\n${disabled}\n\n[compat.codex]\nsessions = false\n`, { mode: 0o600 });
+}
+
+async function inspectIsolatedConfig(config) {
+  const target = executable(config.bin, ["inspect", "--json"]);
+  const raw = await commandText(target.command, target.args, { cwd: config.cwd, env: isolatedEnv(config), phase: "native-inspect" });
+  let report; try { report = JSON.parse(raw); } catch (error) { throw new DaemonError("grok_inspect_invalid", `grok inspect did not return JSON: ${error.message}`); }
+  const foreign = [];
+  const checkSource = (kind, value, roots) => { const candidate = value?.source?.path ?? value?.path ?? value?.filePath; if (candidate && !roots.some((root) => within(candidate, root))) foreign.push({ kind, path: candidate }); };
+  for (const layer of report.configSources?.layers ?? []) checkSource("config", layer, [config.grokHome]);
+  for (const hook of report.hooks ?? []) checkSource("hook", hook, [config.grokHome]);
+  for (const skill of report.skills ?? []) checkSource("skill", skill, [config.grokHome]);
+  for (const agent of report.agents ?? []) checkSource("agent", agent, [config.grokHome]);
+  for (const instruction of report.projectInstructions ?? []) checkSource("instruction", instruction, [config.cwd, config.projectRoot]);
+  const compatEnabled = (report.externalCompat?.cells ?? []).filter((cell) => ["claude", "cursor", "codex"].includes(cell.vendor) && cell.enabled).map((cell) => `${cell.vendor}.${cell.surface}`);
+  const violations = [
+    ...(foreign.length ? [{ kind: "foreign_sources", foreign }] : []),
+    ...((report.plugins ?? []).length ? [{ kind: "plugins_loaded", count: report.plugins.length }] : []),
+    ...((report.mcpServers ?? []).length ? [{ kind: "mcp_loaded", count: report.mcpServers.length }] : []),
+    ...((report.permissions?.sources ?? []).length ? [{ kind: "permission_sources", count: report.permissions.sources.length }] : []),
+    ...(report.externalCompat?.remoteSettingsLoaded ? [{ kind: "remote_compat" }] : []),
+    ...(compatEnabled.length ? [{ kind: "compat_enabled", values: compatEnabled }] : []),
+    ...((report.configWarnings ?? []).length ? [{ kind: "config_warnings", warnings: report.configWarnings }] : [])
+  ];
+  if (violations.length) throw new DaemonError("grok_config_not_isolated", "Grok Build loaded configuration outside the managed isolation boundary", false, { violations });
+  return { checked_at: new Date().toISOString(), config_path: path.join(config.grokHome, "config.toml"), hooks: (report.hooks ?? []).length, skills: (report.skills ?? []).length, agents: (report.agents ?? []).length, config_layers: (report.configSources?.layers ?? []).map((layer) => layer.path), compatibility: "disabled" };
+}
+
+async function writeHook(paths, config, entryPath) {
+  const hookDir = path.join(paths.home, "hooks"); await mkdir(hookDir, { recursive: true, mode: 0o700 });
+  const command = [shellQuote(process.execPath), shellQuote(entryPath), "hook", "handle", "--state-dir", shellQuote(paths.dir), "--project-root", shellQuote(config.projectRoot), "--dd-flow-bin", shellQuote(config.ddFlowBin), "--dd-flow-home", shellQuote(config.ddFlowHome)].join(" ");
+  const hook = { type: "command", command, timeout: 30 };
+  // ACP exposes the native terminal as run_terminal_command; interactive
+  // Grok clients still use Bash. Register both rather than assuming one UI.
+  await writeFile(path.join(hookDir, "dd-flow.json"), `${JSON.stringify({ hooks: { PreToolUse: ["Bash", "run_terminal_command"].map((matcher) => ({ matcher, hooks: [hook] })) } }, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function observeAcpToolCall(config, identity, message) {
+  // Grok's synchronous native hook owns admission. This ACP mirror is
+  // observational only; forwarding it used to create a second receipt after
+  // the command had already run.
+  void config; void identity; void message;
+}
+
+async function copyAuth(paths, source) {
+  const target = path.join(paths.home, "auth.json");
+  try { await copyFile(source, target); await chmod(target, 0o600); return target; }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+const ARCHIVE_SCHEMA = "dd-grok/session-archive@1";
+function sessionDirectory(home, sourceCwd, sessionId) {
+  if (!/^[A-Za-z0-9-]+$/.test(String(sessionId))) throw new DaemonError("invalid_session_id", "Grok Build session id is unsafe");
+  return path.join(home, "sessions", encodeURIComponent(absolute(sourceCwd, "Grok Build source cwd")), String(sessionId));
+}
+async function privateTree(root) {
+  const info = await lstat(root);
+  if (info.isSymbolicLink()) throw new DaemonError("unsafe_session_archive", "session archive must not contain symbolic links");
+  if (info.isDirectory()) {
+    await chmod(root, 0o700);
+    for (const entry of await readdir(root)) await privateTree(path.join(root, entry));
+  } else if (info.isFile()) await chmod(root, 0o600);
+  else throw new DaemonError("unsafe_session_archive", "session archive contains an unsupported filesystem entry");
+}
+async function mustNotExist(target, code, message) {
+  try { await lstat(target); throw new DaemonError(code, message); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+}
+async function exportSessionArchive(paths, sessionId, sourceCwd, archiveDir, versions) {
+  const destination = absolute(archiveDir, "--archive-dir");
+  await mustNotExist(destination, "archive_exists", "session archive directory already exists");
+  const source = sessionDirectory(paths.home, sourceCwd, sessionId);
+  const sourceInfo = await lstat(source);
+  if (!sourceInfo.isDirectory()) throw new DaemonError("session_archive_missing", "Grok Build session files are unavailable for export");
+  await privateTree(source);
+  await mkdir(destination, { recursive: false, mode: 0o700 });
+  await cp(source, path.join(destination, "session"), { recursive: true, errorOnExist: true });
+  const manifest = { schema_id: ARCHIVE_SCHEMA, provider_session_id: sessionId, source_cwd: sourceCwd, grok_version: versions.grok, exported_at: new Date().toISOString() };
+  await writeFile(path.join(destination, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  await privateTree(destination);
+  return { archive_dir: destination, ...manifest };
+}
+async function readSessionArchiveManifest(archiveDir) {
+  const source = absolute(archiveDir, "--session-archive");
+  let manifest;
+  try { manifest = JSON.parse(await readFile(path.join(source, "manifest.json"), "utf8")); }
+  catch (error) { throw new DaemonError("invalid_session_archive", `cannot read session archive manifest: ${error.message}`); }
+  if (manifest?.schema_id !== ARCHIVE_SCHEMA || !manifest.provider_session_id || !manifest.source_cwd) throw new DaemonError("invalid_session_archive", "session archive manifest is incompatible");
+  return { source, manifest };
+}
+async function materializeSessionArchive(paths, archiveDir) {
+  if (!archiveDir) return null;
+  const { source, manifest } = await readSessionArchiveManifest(archiveDir);
+  const target = sessionDirectory(paths.home, manifest.source_cwd, manifest.provider_session_id);
+  await mustNotExist(target, "session_archive_collision", "managed Grok home already contains this session");
+  const archiveSession = path.join(source, "session");
+  const sourceInfo = await lstat(archiveSession);
+  if (!sourceInfo.isDirectory()) throw new DaemonError("invalid_session_archive", "session archive payload is missing");
+  await privateTree(archiveSession);
+  await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  await cp(archiveSession, target, { recursive: true, errorOnExist: true });
+  await privateTree(target);
+  return { schema_id: ARCHIVE_SCHEMA, provider_session_id: manifest.provider_session_id, source_cwd: manifest.source_cwd, grok_version: manifest.grok_version ?? null, archive_dir: source };
+}
+
+export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 30_000) {
+  operation = canonicalNativeOperation('grok', operation);
+  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: 'grok', timeoutMs });
+}
+
+function sameConfig(state, config) { return ["cwd", "journal", "bin", "authSource", "model", "reasoning", "mode", "ddFlowBin", "ddFlowHome", "projectRoot", "sessionArchive", "resourceHome", "noFlow"].every((key) => (state.config?.[key] ?? null) === (config[key] ?? null)); }
+export function grokStartupFailure(state) {
+  if (!["failed", "cleanup_failed"].includes(state?.shutdown_state) || !state.startup_error) return null;
+  const failure = state.startup_error;
+  return new DaemonError(failure.code ?? "daemon_start_failed", failure.message ?? "Grok daemon failed before becoming ready", failure.retryable === true, failure.details);
+}
+export async function startDaemon(options) {
+  const paths = locations(options.stateDir); const archive = options.sessionArchive ? await readSessionArchiveManifest(options.sessionArchive) : null; const archiveCwd = archive ? absolute(archive.manifest.source_cwd, "Grok Build archive source cwd") : null; const cwd = options.cwd ? absolute(options.cwd, "--cwd") : archiveCwd; if (!cwd) throw new DaemonError("invalid_path", "--cwd must be an absolute path when no session archive is supplied"); if (archiveCwd && cwd !== archiveCwd) throw new DaemonError("session_archive_cwd_mismatch", "Grok Build session archives must start from their recorded source cwd", false, { archive_cwd: archiveCwd, requested_cwd: cwd }); const noFlow = options.noFlow === true; const authSource = options.authPath ? absolute(options.authPath, "--auth-path") : path.join(os.homedir(), ".grok", "auth.json"); const config = { cwd, journal: absolute(options.journal, "--journal"), bin: options.bin ?? process.env.DD_GROK_BIN ?? "grok", authSource, authPath: path.join(paths.home, "auth.json"), model: String(options.model ?? ""), reasoning: String(options.reasoning ?? ""), mode: options.mode ?? "bypassPermissions", ddFlowBin: noFlow ? null : absolute(options.ddFlowBin, "--dd-flow-bin"), ddFlowHome: noFlow ? null : absolute(options.ddFlowHome, "--dd-flow-home"), projectRoot: noFlow ? cwd : absolute(options.projectRoot, "--project-root"), resourceHome: noFlow ? null : (process.env.DD_FLOW_RESOURCE_HOME ? absolute(process.env.DD_FLOW_RESOURCE_HOME, "DD_FLOW_RESOURCE_HOME") : null), env: noFlow ? {} : { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") }, sessionArchive: archive?.source ?? null, grokHome: paths.home, noFlow };
+  await prepareRuntimeOwner(config, paths.dir);
+  if (!config.model || !config.reasoning) throw new DaemonError("profile_required", "--model and --reasoning are required");
+  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.ready", {}, 5000); if (!sameConfig(status, config)) throw new DaemonError("daemon_config_mismatch", "a daemon is already running with different configuration"); if (!status.ready) throw new DaemonError("daemon_start_in_progress", "an existing daemon is still starting", true); return { ...status, already_running: true }; } catch (error) { if (error.code !== "daemon_not_running") throw error; }
+  previous = await readState(paths.dir); assertDaemonRestartable(previous);
+  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", "previous daemon died with an active or unproven Session tree", false, { daemon_id: previous.daemon_id });
+  await removeSocket(paths.socket, paths.dir); await mkdir(paths.home, { recursive: true, mode: 0o700 }); const importedSession = await materializeSessionArchive(paths, config.sessionArchive); const copiedAuth = await copyAuth(paths, authSource); await writeIsolatedConfig(paths); if (!noFlow) await writeHook(paths, config, absolute(options.entryPath, "dd-grok entry")); const versions = await doctor({ bin: config.bin }); if (importedSession && importedSession.grok_version !== versions.versions.grok) throw new DaemonError("session_archive_version_mismatch", "Grok Build session archive was created by a different CLI version", false, { archive_version: importedSession.grok_version, current_version: versions.versions.grok }); const configIsolation = await inspectIsolatedConfig(config);
+  const resourceProcess = await registerDaemonProcess(config, { kind: "grok-daemon", owner: `grok:${path.basename(paths.dir)}`, operation: `grok-daemon:${path.basename(paths.dir)}`, stdout: paths.log, stderr: paths.log });
+  const daemonId = randomUUID();
+  const state = { descendants: previous?.descendants ?? [], schema_id: STATE_SCHEMA, daemon_id: daemonId, pid: null, socket: paths.socket, started_at: new Date().toISOString(), shutdown_state: "starting", active_tree: false, recovery_status: previous?.shutdown_state === "running" ? "recovered_idle" : "clean_start", auth_status: copiedAuth ? "copied" : "absent", ...(importedSession ? { imported_session: importedSession } : {}), versions: versions.versions, config_isolation: configIsolation, config: { ...config, daemonId }, sessions: importedSession ? [{ provider_session_id: importedSession.provider_session_id, adapter_session_id: importedSession.provider_session_id, parent_provider_session_id: null, root_provider_session_id: importedSession.provider_session_id, cwd: importedSession.source_cwd }] : (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-grok entry"), "daemon", "serve", "--state-dir", paths.dir], { cwd: config.cwd, env: isolatedEnv(state.config), 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)); const failure = grokStartupFailure(await readState(paths.dir)); if (failure) throw failure; try { const status = await callDaemon(paths.dir, "daemon.ready", {}, 5000); if (status.ready) return status; } 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), daemonId); throw error; }
+}
+export async function stopDaemon(options) { const timeoutMs = options.timeoutMs ?? 30_000; return await confirmDaemonStopped(() => callDaemon(options.stateDir, "daemon.stop", { cancelTree: options.cancelTree === true }, timeoutMs), locations(options.stateDir).socket, timeoutMs, { readState: () => readState(options.stateDir) }); }
+
+export class Runtime {
+  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.descendants = new Map((state.descendants ?? []).map(child => [child.provider_session_id, child])); for (const session of this.sessions.values()) if (session.parent_provider_session_id && !this.descendants.has(session.provider_session_id)) this.descendants.set(session.provider_session_id, { provider_session_id: session.provider_session_id, parent_provider_session_id: session.parent_provider_session_id, status: "unknown", source: "legacy.daemon_state", outcome_error: { code: "native_child_outcome_unavailable", message: "Retained Grok child has no durable outcome receipt" } }); this.toolUsage = new Map(); this.promptCreators = new Map(); this.childCreators = new Map(); this.childSpawnWaiters = new Map(); this.loadedSessionId = null; this.active = null; this.server = null; this.ready = false; this.persisting = Promise.resolve(); }
+  persist(patch = {}) { Object.assign(this.state, patch, { pid: process.pid, updated_at: new Date().toISOString(), sessions: [...this.sessions.values()], descendants: [...this.descendants.values()] }); const snapshot = structuredClone(this.state); this.persisting = this.persisting.catch(() => {}).then(() => writeState(this.paths.state, snapshot)); return this.persisting; }
+  async reduceTerminal(outcome) {
+    const session = this.sessions.get(outcome.session_id), turn = session?.native_prompt_operation;
+    if (outcome.method !== "session/prompt" || !turn || typeof outcome.connection_id !== "string" || !outcome.connection_id
+      || !Number.isSafeInteger(outcome.request_id) || outcome.request_id < 1 || !Number.isSafeInteger(outcome.native_sequence) || outcome.native_sequence < 1 || turn.daemon_id !== this.state.daemon_id
+      || turn.connection_id !== outcome.connection_id || turn.operation_id !== outcome.operation_id || turn.generation !== outcome.generation
+      || turn.native_request_id !== outcome.request_id) return;
+    const message = outcome.terminal_response;
+    const kind = message?.error ? "failed" : message?.result?.stopReason;
+    if (!["failed", "end_turn", "cancelled"].includes(kind)) return;
+    const receipt = { kind, ...turn, request_id: outcome.request_id, native_sequence: outcome.native_sequence };
+    if (session.native_root_receipt && (session.native_root_receipt.kind !== kind || session.native_root_receipt.request_id !== outcome.request_id)) {
+      this.state.observation_error = { code: "native_terminal_outcome_conflict", message: "Conflicting native terminal outcomes for the same prompt" };
+      await this.persist();
+      throw new DaemonError(this.state.observation_error.code, this.state.observation_error.message);
+    }
+    if (session.native_root_receipt) return;
+    if (session.native_activity && session.native_activity.connection_id === outcome.connection_id && session.native_activity.sequence > outcome.native_sequence) {
+      return await this.invalidateTerminal(session);
+    }
+    session.native_root_receipt = receipt;
+    await this.persist();
+  }
+  async invalidateTerminal(session) {
+    session.native_root_receipt = null;
+    this.state.observation_error = { code: "native_activity_after_terminal", message: "Productive root activity followed its native terminal outcome" };
+    await this.persist();
+  }
+  async observeRootActivity(message, observation) {
+    const session = this.sessions.get(message?.params?.sessionId), turn = session?.native_prompt_operation;
+    if (!observation?.productive || !turn || session.parent_provider_session_id || turn.connection_id !== observation.connection_id) return;
+    if (session.native_activity?.connection_id !== observation.connection_id || session.native_activity.sequence < observation.sequence) session.native_activity = { connection_id: observation.connection_id, sequence: observation.sequence };
+    const receipt = session.native_root_receipt;
+    if (receipt?.connection_id === observation.connection_id && observation.sequence > receipt.native_sequence) await this.invalidateTerminal(session);
+  }
+  async drainTerminal() { await this.bridge.terminalOutcomes; await this.persisting; if (this.bridge.terminalProjectionError) throw this.bridge.terminalProjectionError; }
+  settledRoot(id) { return !this.active && !this.rootRunning({ provider_session_id: id }) && this.topology(id).every(child => !this.rootRunning({ provider_session_id: child.provider_session_id }) && !child.outcome_error && !child.activity_status); }
+  async restoreTerminals() {
+    if (!this.state.config?.journal) return;
+    let contents;
+    try { contents = await readFile(this.state.config.journal, "utf8"); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+    for (const line of contents.split("\n").filter(Boolean)) {
+      const event = JSON.parse(line);
+      if (["native_terminal_outcome", "native_terminal_after_hook_failure"].includes(event.kind)) await this.reduceTerminal(event.payload);
+    }
+  }
+  options(params) { const sessionId = params.sessionId; const session = sessionId ? this.sessions.get(sessionId) : null; const root = session?.root_provider_session_id ?? sessionId; return { ...this.state.config, ...params, cwd: params.cwd ?? session?.cwd ?? this.state.config.cwd, initialized: this.initialized, daemonId: this.state.daemon_id, rootProviderSessionId: root, toolUsage: this.toolUsage, allowBackground: true, rootSettled: id => this.settledRoot(id), liveSession: params.liveSession ?? Boolean(sessionId && sessionId === this.loadedSessionId) }; }
+  track(result, before = null) { if (!result?.provider_session_id) return; const session = this.sessions.get(result.provider_session_id); const root = result.parent_provider_session_id ? (this.sessions.get(result.parent_provider_session_id)?.root_provider_session_id ?? result.parent_provider_session_id) : (session?.root_provider_session_id ?? result.provider_session_id); this.sessions.set(result.provider_session_id, { ...session, native_root_receipt: session?.native_root_receipt ?? null, provider_session_id: result.provider_session_id, adapter_session_id: result.adapter_session_id ?? result.provider_session_id, parent_provider_session_id: result.parent_provider_session_id ?? session?.parent_provider_session_id ?? null, root_provider_session_id: root, cwd: result.cwd ?? result.target?.newCwd ?? result.info?.cwd ?? session?.cwd ?? null }); for (const child of this.running(result)) this.recordDescendant({ ...child, stale_activity: Boolean(before && before.get(child.sessionId ?? child.subagentId ?? child.provider_session_id) !== this.descendants.get(child.sessionId ?? child.subagentId ?? child.provider_session_id)) }, root, "x.ai/subagent/list_running", "running"); for (const child of result.descendants ?? []) this.recordDescendant(child, root, child.source ?? "x.ai/subagent/event", child.status ?? "unknown"); }
+  recordDescendant(value, root, source, fallback, nativeSpawn = false) {
+    const id = value?.provider_session_id ?? value?.session_id ?? value?.sessionId ?? value?.childSessionId ?? value?.subagentId ?? value?.child_session_id ?? value?.subagent_id;
+    const parent = value?.parent_provider_session_id ?? value?.parentSessionId ?? value?.parent_session_id ?? root;
+    if (typeof id !== "string" || !id || typeof parent !== "string" || !parent) return;
+    if (id === parent) throw new DaemonError("session_parent_conflict", "Grok child Session cannot be its own native parent", false, { provider_session_id: id, observed_parent_provider_session_id: parent });
+    const prior = this.sessions.get(id);
+    if (prior?.parent_provider_session_id && prior.parent_provider_session_id !== parent) {
+      throw new DaemonError("session_parent_conflict", "Grok child Session was observed with conflicting native parents", false, {
+        provider_session_id: id,
+        retained_parent_provider_session_id: prior.parent_provider_session_id,
+        observed_parent_provider_session_id: parent
+      });
+    }
+    const parentSession = this.sessions.get(parent);
+    const rootProviderSessionId = prior?.root_provider_session_id
+      ?? parentSession?.root_provider_session_id
+      ?? root;
+    const cwd = value?.cwd ?? prior?.cwd ?? parentSession?.cwd ?? this.state.config?.cwd ?? null;
+    // A descendant is a managed native Session, not merely a liveness item.
+    // Register it in the same registry used by inspect/hook.resolve so a
+    // parentless inspection cannot downgrade it into a second root.
+    const descendant = this.descendants.get(id);
+    const attempt = value.attempt_id;
+    const retired = descendant?.retired_attempt_ids ?? [];
+    if (attempt && retired.includes(attempt)) return;
+    const spawned = value.sessionUpdate === "subagent_spawned";
+    const newAttempt = spawned && typeof attempt === "string" && attempt !== descendant?.attempt_id;
+    const terminal = status => ["completed", "failed", "cancelled"].includes(status);
+    const status = value?.status ?? value?.state ?? (fallback === "unknown" ? descendant?.status ?? fallback : fallback);
+    if (attempt && descendant?.attempt_id && attempt !== descendant.attempt_id && !newAttempt) throw new DaemonError("native_child_execution_ambiguous", "Grok child event has no matching native spawn attempt", false, { session_id: id, attempt_id: attempt });
+    if (source === "x.ai/subagent/event" && terminal(status) && descendant?.attempt_id && !attempt) throw new DaemonError("native_child_execution_ambiguous", "Grok terminal event omits the retained child attempt identity", false, { session_id: id });
+    if (!newAttempt && terminal(descendant?.status) && status === "running") {
+      if (value.stale_activity || attempt === descendant.attempt_id && attempt) return;
+      const error = { code: "native_child_execution_ambiguous", message: "Grok child activity follows a terminal result without native new-attempt evidence", details: { session_id: id } };
+      this.descendants.set(id, { ...descendant, activity_status: "running", outcome_error: error });
+      if (spawned) throw new DaemonError(error.code, error.message, false, error.details);
+      return;
+    }
+    if (!newAttempt && terminal(descendant?.status) && terminal(status) && descendant.status !== status) throw new DaemonError("native_child_outcome_conflict", "Grok child has contradictory terminal outcomes", false, { session_id: id, previous: descendant.status, observed: status });
+    if (nativeSpawn && spawned && typeof attempt === "string" && attempt && source === "x.ai/subagent/event") {
+      const promptId = value.parent_prompt_id;
+      const creator = typeof promptId === "string" && promptId ? this.promptCreators.get(JSON.stringify([parent, promptId])) : null;
+      const old = this.childCreators.get(id);
+      if (old && old.attempt === attempt && (old.parent !== parent || typeof promptId === "string" && promptId && old.promptId !== promptId)) throw new DaemonError("native_child_execution_ambiguous", "Grok child attempt has conflicting native creator", false, { session_id: id });
+      if (creator) this.childCreators.set(id, { parent, promptId, attempt, creator });
+      else if (newAttempt) this.childCreators.delete(id);
+    }
+    this.sessions.set(id, {
+      ...prior,
+      provider_session_id: id,
+      adapter_session_id: prior?.adapter_session_id ?? id,
+      parent_provider_session_id: parent,
+      root_provider_session_id: rootProviderSessionId,
+      cwd,
+      native_root_receipt: prior?.native_root_receipt ?? null
+    });
+    this.bridge.registerModelSession?.(id, id, this.state.config, parent, true, newAttempt);
+    this.descendants.set(id, {
+      provider_session_id: id,
+      parent_provider_session_id: parent,
+      status,
+      source,
+      ...(terminal(status) && typeof attempt === "string" && attempt ? { terminal_turn_id: attempt,
+        ...(typeof value.observed_at === "string" ? { terminal_observed_at: value.observed_at } : {}),
+        ...(value.provider_error && typeof value.provider_error === "object" ? { provider_error: safeProviderError(value.provider_error), native_source: "grok.subagent.event" } : {}),
+        ...(value.native_turn_items && typeof value.native_turn_items === "object" ? { native_turn_items: value.native_turn_items } : {}) } : {}),
+      ...(attempt || descendant?.attempt_id ? { attempt_id: attempt ?? descendant.attempt_id } : {}),
+      ...(newAttempt && descendant?.attempt_id ? { retired_attempt_ids: [...retired, descendant.attempt_id] } : retired.length ? { retired_attempt_ids: retired } : {}),
+      ...(!newAttempt && !terminal(status) && descendant?.outcome_error ? { outcome_error: descendant.outcome_error } : {})
+    });
+    if (this.childCreators.has(id)) for (const wake of this.childSpawnWaiters.get(id) ?? []) wake();
+    if (spawned && typeof value.model === "string" && value.model.trim()) {
+      return { sessionId: id, parentSessionId: parent, attemptId: attempt ?? null, parentPromptId: value.parent_prompt_id ?? null, model: value.model.trim() };
+    }
+  }
+  observeSubagentEvent(message) {
+    const root = message?.params?.sessionId, update = message?.params?.update;
+    const kind = String(update?.sessionUpdate ?? update?.type ?? message?.method ?? "");
+    if (!root) return [];
+    const modelFacts = [];
+    if (/subagent/i.test(kind)) {
+      for (const value of [update?.subagent, update?.subagentInfo, update?.child, update?.result, update]) {
+        const fact = this.recordDescendant(value, root, "x.ai/subagent/event", /fail|error/i.test(kind) ? "failed" : /cancel/i.test(kind) ? "cancelled" : /complete|finish|done/i.test(kind) ? "completed" : "running", value === update);
+        if (fact) modelFacts.push(fact);
+      }
+    }
+    // list_running omits completed children. Retain native tool receipts, never
+    // extract identities from the model's prose or from arbitrary shell output.
+    this.subagentCalls ??= new Map();
+    const key = `${root}:${update?.toolCallId}`;
+    const tool = update?._meta?.["x.ai/tool"]?.name ?? (kind === "tool_call" ? update.title : null);
+    if (["spawn_subagent", "get_command_or_subagent_output"].includes(tool) && !this.subagentCalls.has(key)) this.subagentCalls.set(key, { name: tool, input: update.rawInput, attempts: new Map([...this.descendants].map(([id, child]) => [id, child.attempt_id])) });
+    const call = this.subagentCalls.get(key), name = call?.name, output = update?.rawOutput;
+    if (call && update.rawInput) call.input = update.rawInput;
+    if (kind !== "tool_call_update" || update.status !== "completed") return modelFacts;
+    if (name === "spawn_subagent" && output?.type === "Text") {
+      const id = /^subagent_id:\s*(\S+)\s*$/m.exec(output.text ?? "")?.[1];
+      if (id) this.recordDescendant({ session_id: id, stale_activity: !call.attempts.has(id) || call.attempts.get(id) !== this.descendants.get(id)?.attempt_id }, root, "x.ai/tool/spawn_subagent", "running");
+    }
+    if (name === "get_command_or_subagent_output" && output?.type === "TaskOutput") {
+      const results = output.Result ? [output.Result] : output.MultiResult?.results ?? [];
+      if (!Array.isArray(results)) throw new DaemonError("native_child_outcome_unavailable", "Grok TaskOutput has a malformed result list");
+      // TaskNotFound is prose in the native contract; identity comes from the
+      // matching tool input, never by scraping its diagnostic message.
+      if (output.TaskNotFound && typeof call.input?.task_id === "string") results.push({ task_id: call.input.task_id, status: "not_found" });
+      let firstError;
+      for (const result of results) {
+        const child = this.descendants.get(result?.task_id);
+        if (!child || call.attempts.get(result.task_id) !== child.attempt_id) continue;
+        if (result.status === "not_found") {
+          const error = new DaemonError("native_child_outcome_unavailable", "Grok cannot retrieve the owned child's native outcome", false, { session_id: result.task_id, tool_call_id: update.toolCallId });
+          this.descendants.set(result.task_id, { ...child, outcome_error: errorPayload(error) });
+          firstError ??= error;
+          continue;
+        }
+        if (!["running", "completed", "failed", "cancelled"].includes(result.status)) throw new DaemonError("native_child_outcome_unavailable", "Grok child returned an unknown native outcome", false, { session_id: result.task_id, status: result.status });
+        this.recordDescendant({ session_id: result.task_id, status: result.status, attempt_id: child.attempt_id }, root, "x.ai/tool/TaskOutput", "unknown");
+      }
+      if (firstError) throw firstError;
+    }
+    return modelFacts;
+  }
+  topology(root) { if (this.state.observation_error) { const error = this.state.observation_error; throw new DaemonError(error.code, error.message, false, error.details); } return [...this.descendants.values()].filter((child) => child.parent_provider_session_id === root || this.sessions.get(child.provider_session_id)?.root_provider_session_id === root); }
+  observeToolCall(message) { this.toolObservations ??= new ToolObservations(); this.toolObservations.add(acpToolObservation(message, { harness: "grok-acp" })); const sessionId = message?.params?.sessionId; if (sessionId) this.toolUsage.set(sessionId, this.toolObservations.summary(sessionId)); }
+  running(result) { return result?.evidence?.subagents?.subagents ?? result?.subagents?.subagents ?? []; }
+  treeRunning(result) {
+    const evidence = result?.evidence ?? result;
+    const children = evidence?.subagents?.subagents;
+    return this.rootRunning({ ...result, ...evidence }) || !Array.isArray(children) || children.length > 0 || Boolean(evidence?.subagents?.observation_error)
+      || this.topology(result?.provider_session_id).some(child => this.rootRunning({ provider_session_id: child.provider_session_id }) || child.outcome_error || child.activity_status);
+  }
+  rootRunning(result) {
+    const status = String(result?.info?.status ?? result?.info?.state ?? result?.info?.data?.status ?? "unknown").toLowerCase();
+    const child = this.descendants.get(result?.provider_session_id);
+    // Grok may retire a completed child Session before session/info can be
+    // inspected. A retained TaskOutput for that exact attempt is native
+    // terminal proof; missing session/info alone is not.
+    if (status === "unknown" && ["x.ai/tool/TaskOutput", "x.ai/subagent/event"].includes(child?.source) && child.attempt_id && !child.outcome_error && !child.activity_status
+      && ["completed", "failed", "cancelled"].includes(child.status)) return false;
+    // Grok 1.0.17 omits status from session/info. Only a durable native
+    // creation/end_turn receipt can then establish an idle root. Dispatch
+    // clears that receipt before sending any subsequent productive request.
+    const receipt = this.sessions.get(result?.provider_session_id)?.native_root_receipt;
+    if (status === "unknown" && ["created", "end_turn", "cancelled", "failed"].includes(receipt?.kind)) return false;
+    return !["completed", "failed", "cancelled", "stopped", "idle"].includes(status);
+  }
+  async refreshTree(cancel = false) {
+    await this.drainTerminal();
+    const running = [];
+    for (const session of [...this.sessions.values()].filter(item => !item.parent_provider_session_id)) {
+      const id = session.provider_session_id;
+      const before = new Map(this.descendants);
+      let observed = await inspectSessionWithBridge(this.bridge, this.options({ sessionId: id, liveSession: true }));
+      this.track(observed, before);
+      const rootActive = Boolean(this.active);
+      if (cancel && (rootActive || this.treeRunning(observed))) {
+        await cancelSessionWithBridge(this.bridge, this.options({ sessionId: id, liveSession: true }));
+        const beforeCancelledInspection = new Map(this.descendants);
+        observed = await inspectSessionWithBridge(this.bridge, this.options({ sessionId: id, liveSession: true }));
+        this.track(observed, beforeCancelledInspection);
+      }
+      if (this.active || this.treeRunning(observed)) running.push(id);
+    }
+    await this.persist({ active_tree: running.length > 0 || Boolean(this.active) });
+    return running;
+  }
+  async requireSettled() { const running = await this.refreshTree(); if (running.length) throw new DaemonError("tree_not_settled", "daemon still owns a running Session tree", false, { sessions: running }); }
+  async productive(name, task, sessionId, operationId = null) {
+    assertDaemonDispatch(this.paths?.dir);
+    if (this.active) throw new DaemonError("operation_busy", `${this.active} is already running`, true);
+    this.active = name;
+    const current = this.nativeHookOperation = { operationId, sessionId, generation: (this.hookGeneration = (this.hookGeneration ?? 0) + 1), requests: new Map(), guard: captureDispatchGuard(this) };
+    let rejectHook;
+    const hookFailed = new Promise((_, reject) => { rejectHook = reject; });
+    void hookFailed.catch(() => {});
+    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);
+    // Only a new native turn invalidates its own root proof. Creation, fork
+    // and local archive export must not erase an unrelated Session's receipt.
+    if (name === "session.prompt" && this.sessions.has(sessionId)) {
+      const session = this.sessions.get(sessionId);
+      if (typeof operationId === "string" && operationId) {
+        current.nativePromptId = randomUUID();
+        // Retain only for this daemon lifetime: a late native spawn or hook
+        // cannot be safely distinguished from an expired one by a timer.
+        // After restart the in-memory correlation is deliberately unavailable.
+        this.promptCreators.set(JSON.stringify([sessionId, current.nativePromptId]), current);
+      }
+      session.native_root_receipt = null;
+      this.bridge.dispatchGeneration = current.generation;
+      session.native_prompt_operation = { daemon_id: this.state.daemon_id, connection_id: this.bridge.connectionId, operation_id: operationId, generation: current.generation,
+        ...(current.nativePromptId ? { native_prompt_id: current.nativePromptId } : {}) };
+    }
+    try {
+      await this.persist({ active_tree: true, active_operation: name });
+      assertDaemonDispatch(this.paths?.dir);
+      const before = new Map(this.descendants);
+      const result = await Promise.race([task(), hookFailed]);
+      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()];
+      await this.drainTerminal();
+      this.track(result, before);
+      const session = this.sessions.get(result.provider_session_id);
+      if (session && ["session.create", "session.fork"].includes(name)) session.native_root_receipt = { kind: "created", daemon_id: this.state.daemon_id };
+      // Archive requires an idle tree before entering this exclusive section
+      // and performs no native work. Its file receipt is not tree evidence.
+      const running = name === "session.archive" ? false : this.treeRunning(result);
+      await this.persist({ active_tree: running, active_operation: null });
+      return { ...result, descendants: this.topology(result.provider_session_id), settled: !running };
+    } catch (error) {
+      // A matched JSON-RPC error completes this native prompt request. It is
+      // root-turn proof, not proof that any descendants have stopped. A lost
+      // response, bridge error, or failure before dispatch earns no receipt.
+      try { await this.drainTerminal(); } catch (storage) { error.cleanup_error ??= errorRecord(storage); }
+      try { await this.persist({ active_tree: true, active_operation: null }); }
+      catch (storage) { error.cleanup_error = errorRecord(storage); }
+      throw error;
+    }
+    finally { clearInterval(timer); if (!current.nativePromptId) current.requests.clear(); if (this.nativeHookOperation === current) this.nativeHookOperation = null; this.active = 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: current.sessionId, 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);
+  }
+  async acceptHook(identity, sessionId, payload) {
+    const input = payload?.tool_input ?? payload?.toolInput;
+    const command = input?.command ?? input?.cmd;
+    if ((payload?.hook_event_name ?? payload?.hookEventName) !== "PreToolUse" || typeof command !== "string" || (!["lifecycle", "auxiliary"].includes(parseLifecycleCommand(command).participation) && !continuationCommand(command))) return identity;
+    const active = this.nativeHookOperation, tool = payload.tool_use_id ?? payload.toolUseId ?? payload.tool_call_id;
+    const root = identity.rootProviderSessionId;
+    const source = sessionId !== root ? this.childCreators.get(sessionId) : null;
+    // An older Grok may not surface creator metadata. Preserve its ordinary
+    // stateful handler, but never turn the current prompt into guessed proof.
+    if (sessionId !== root && !source) return identity;
+    const current = sessionId !== root ? source?.creator : active;
+    const pending = [...(this.bridge.pending?.values() ?? [])].some(request => request.method === "session/prompt" && request.sessionId === root);
+    const nativePrompt = payload.prompt_id ?? payload.promptId;
+    if (!current || current.sessionId !== root || !tool || sessionId === root && (!pending || active !== current)
+      || sessionId === root && typeof nativePrompt === "string" && nativePrompt && nativePrompt !== current.nativePromptId
+      || sessionId !== root && (source.parent !== identity.parentProviderSessionId || this.promptCreators.get(JSON.stringify([source.parent, source.promptId])) !== current))
+      throw new DaemonError("native_hook_unproven", "Native hook has no exact source-bound Session operation");
+    current.guard(); assertDaemonDispatch(this.paths.dir);
+    const nativePayload = { ...payload, _meta: { ...(payload._meta ?? {}), ddGrok: { ...identity } } };
+    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: root, parent_provider_session_id: identity.parentProviderSessionId ?? null,
+      tool_call_id: tool, event: "PreToolUse", command_sha256: createHash("sha256").update(command).digest("hex"), native_cwd: payload.cwd ?? null,
+      native_creator: source || typeof nativePrompt === "string" && nativePrompt && nativePrompt === current.nativePromptId ? "confirmed" : "unconfirmed",
+      ...(source ? { source_harness: "grok-acp", native_command: command, native_payload: nativePayload } : {}) }, current);
+    current.guard();
+    if (sessionId === root && this.nativeHookOperation !== current || sessionId !== root && this.childCreators.get(sessionId) !== source)
+      throw new DaemonError("native_hook_unproven", "Native hook operation changed during acceptance");
+    current.requests.set(binding.request_id, { current, binding });
+    const parsed = parseLifecycleCommand(command);
+    const fastAck = Boolean(source && parsed.kind === "standalone" && parsed.invocation.operation === "work_start" && commandOption(parsed.invocation, "invocation-id"));
+    return { ...identity, nativeHookBinding: binding, ...(fastAck ? { fastAck: true } : {}) };
+  }
+  async waitForChildCreator(sessionId, deadlineAt) {
+    const remaining = deadlineAt - Date.now();
+    if (this.childCreators.has(sessionId) || !Number.isSafeInteger(deadlineAt) || remaining <= 0 || remaining > 30_000) return;
+    // Leave most of the existing host budget to the legacy handler if this
+    // provider omits the optional spawn correlation; do not poll the provider.
+    const waitMs = Math.floor(remaining / 3);
+    if (!waitMs) return;
+    await new Promise(resolve => {
+      const waiters = this.childSpawnWaiters.get(sessionId) ?? new Set();
+      const wake = () => { clearTimeout(timer); waiters.delete(wake); if (!waiters.size) this.childSpawnWaiters.delete(sessionId); resolve(); };
+      const timer = setTimeout(wake, waitMs);
+      waiters.add(wake); this.childSpawnWaiters.set(sessionId, waiters);
+    });
+  }
+  hookOwner(binding) {
+    if (!binding?.request_id) return null;
+    const owners = new Set([this.nativeHookOperation, ...this.promptCreators.values()]);
+    for (const owner of owners) {
+      if (!owner || owner.operationId !== binding.operation_id || owner.generation !== binding.turn_generation) continue;
+      const accepted = owner.requests.get(binding.request_id);
+      if (accepted?.current === owner && JSON.stringify(accepted.binding) === JSON.stringify(binding)) return owner;
+    }
+    return null;
+  }
+  async dispatch(operation, params, operationId = null) {
+    const assertDispatch = captureDispatchGuard(this);
+    if (["session.create", "session.prompt", "session.fork", "session.archive"].includes(operation)) assertDaemonDispatch(this.paths.dir);
+    if (operation === "daemon.ready") return { ready: this.ready, daemon_id: this.state.daemon_id, pid: process.pid, socket: this.paths.socket, versions: this.state.versions, config_isolation: this.state.config_isolation, shutdown_state: this.state.shutdown_state, recovery_status: this.state.recovery_status, auth_status: this.state.auth_status, active_tree: this.state.active_tree, active_operation: this.active, sessions: [...this.sessions.values()], config: this.state.config };
+    if (operation === "daemon.status") { let observationError; if (!this.active && !this.state.shutdown?.phases?.execution && !this.state.shutdown?.physical_only) try { await this.refreshTree(); } catch (error) { observationError = errorPayload(error); } return { ...await this.dispatch("daemon.ready", {}), observation_error: observationError ?? this.state.observation_error ?? null }; }
+    if (operation === "hook.resolve") { const sessionId = String(params.sessionId ?? ""); if (!sessionId) throw new DaemonError("hook_identity_missing", "hook has no sessionId"); let session = this.sessions.get(sessionId); if ((!session || session.parent_provider_session_id) && !this.childCreators.has(sessionId) && this.promptCreators.size) { await this.waitForChildCreator(sessionId, params.hookDeadlineAt); session = this.sessions.get(sessionId); } if (!session) { const roots = [...this.sessions.values()].filter((item) => !item.parent_provider_session_id); if (roots.length !== 1) throw new DaemonError("hook_identity_unknown", "unknown hook Session has no unique root"); const observed = await inspectSessionWithBridge(this.bridge, this.options({ sessionId, liveSession: true })); this.track(observed); session = this.sessions.get(sessionId); if (!session || session.root_provider_session_id !== roots[0].provider_session_id) throw new DaemonError("hook_identity_unknown", "hook Session is not a member of the retained native tree"); await this.persist(); } return await this.acceptHook({ daemonId: this.state.daemon_id, rootProviderSessionId: session.root_provider_session_id, parentProviderSessionId: session.parent_provider_session_id ?? null, observedProfile: this.bridge.modelProfiles?.get(sessionId) ?? {} }, sessionId, params.payload); }
+    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");
+      owner.guard(); 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;
+        const current = this.hookOwner(binding);
+        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");
+        current.guard(); assertDaemonDispatch(this.paths.dir);
+        if (this.nativeHookOperation !== current) {
+          // The creator has returned. Retain the bound failure under its
+          // original operation, without rejecting the newer productive turn.
+          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") return await this.productive(operation, async () => { const result = await createSessionWithBridge(this.bridge, { ...this.options(params), onSessionCreated: async (session) => { this.track(session); this.loadedSessionId = session.provider_session_id; await this.persist(); } }, this.initialized); this.loadedSessionId = result.provider_session_id; return result; }, null, operationId);
+    if (operation === "session.prompt") { await this.requireSettled(); return await this.productive(operation, async () => { const result = await promptSessionWithBridge(this.bridge, { ...this.options(params), assertDispatch, operationId, nativePromptId: this.nativeHookOperation?.nativePromptId }); this.loadedSessionId = params.sessionId; return result; }, params.sessionId, operationId); }
+    if (operation === "session.fork") { await this.requireSettled(); return await this.productive(operation, async () => { const result = await forkSessionWithBridge(this.bridge, this.options(params)); this.loadedSessionId = params.sessionId; return result; }); }
+    if (operation === "session.inspect" || operation === "session.resume") { const before = new Map(this.descendants); const result = await inspectSessionWithBridge(this.bridge, this.options({ ...params, liveSession: true })); this.track(result, before); await this.persist(); const settled = !this.active && !this.treeRunning(result); const descendants = this.topology(result.provider_session_id); const terminal = this.sessions.get(result.provider_session_id)?.native_root_receipt; return nativeExecutionReceipt({ ...result, settled, descendants, ...settledNativeTree(result.provider_session_id, descendants, settled, !this.active && !this.rootRunning(result)), ...(terminal?.kind === "failed" && terminal.request_id !== undefined ? { terminal_turn_id: String(terminal.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"); cancelPendingDispatch(this); const result = await cancelSessionWithBridge(this.bridge, this.options({ ...params, liveSession: true })); await this.persist({ active_tree: Boolean(this.active) || !result.settled }); return result; }
+    if (operation === "session.archive") { await this.requireSettled(); return await this.productive(operation, async () => { let session = this.sessions.get(params.sessionId); if (!session?.cwd) { const result = await inspectSessionWithBridge(this.bridge, this.options({ ...params, liveSession: true })); this.track(result); session = this.sessions.get(result.provider_session_id); } return await exportSessionArchive(this.paths, session.provider_session_id, absolute(session.cwd, "Grok Build session cwd"), params.archiveDir, this.state.versions); }); }
+    if (operation === "daemon.stop") {
+      return await completeDaemonShutdown(this.paths.dir, this.state, patch => this.persist(patch), async () => {
+      if (params.cancelTree) cancelPendingDispatch(this);
+      await waitForSettlement({
+        knownSessions: () => [...this.sessions.values()].filter(s => !s.parent_provider_session_id).map(s => s.provider_session_id),
+        observe: async () => ({ sessions: await this.refreshTree(), active: Boolean(this.active), active_operation: this.active }),
+        ...(params.cancelTree ? { cancel: id => cancelSessionWithBridge(this.bridge, this.options({ sessionId: id, liveSession: true })) } : {})
+      });
+      return { clean: true, settled: true, native_settled: true };
+      }, [
+        ["provider", () => this.bridge.close()],
+        ["provider_resource", () => finishDaemonProcess(this.state.config, this.state.provider_process)],
+        ["auth", () => unlink(path.join(this.paths.home, "auth.json")).catch(error => { if (error.code !== "ENOENT") throw error; })],
+        ["daemon_resource", () => finishDaemonProcess(this.state.config, this.state.resource_process)]
+      ], undefined, { cancelTree: params.cancelTree === true });
+    }
+    throw new DaemonError("unknown_operation", `unknown daemon operation: ${operation}`);
+  }
+}
+
+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"); let runtime;
+  const bridge = new AcpBridge({ ...state.config, initializeTimeoutMs: 60_000, commandArgs: ["agent", "--no-leader", "--always-approve", "--model", state.config.model, "--reasoning-effort", state.config.reasoning, "stdio"], env: isolatedEnv(state.config), clientInfo: { name: "dd-grok", version: "0.1.0" }, permission: "allow", onNotification: async (message, observation) => {
+    const sessionId = message?.params?.sessionId;
+    if (!runtime || !sessionId) return;
+    try {
+      await runtime.observeRootActivity(message, observation);
+      runtime.observeToolCall(message);
+      for (const fact of runtime.observeSubagentEvent(message)) {
+        const source = { channel: "x.ai/subagent_spawned", scope: "configured", attempt_id: fact.attemptId, parent_prompt_id: fact.parentPromptId,
+          event_sha256: createHash("sha256").update(JSON.stringify(fact)).digest("hex") };
+        await observeModel({ journal: state.config.journal, harness: "grok-acp", sessionId: fact.sessionId, parentSessionId: fact.parentSessionId,
+          requested: state.config, observed: { model: fact.model }, source, evidence: "configured" });
+        bridge.modelProfiles?.set(fact.sessionId, { model: fact.model });
+      }
+    } catch (error) {
+      // Native notifications are fire-and-forget. Persist topology conflicts
+      // for the next inspect/status call instead of creating an unhandled
+      // rejection that can kill the daemon without a causal receipt.
+      try { await runtime.persist({ observation_error: errorPayload(error) }); } catch { /* status/inspect will report the original native failure */ }
+    }
+    const session = runtime.sessions.get(sessionId);
+    const rootProviderSessionId = session?.root_provider_session_id ?? sessionId;
+    await observeAcpToolCall(state.config, { daemonId: state.daemon_id, rootProviderSessionId, parentProviderSessionId: session?.parent_provider_session_id ?? null, observedProfile: bridge.modelProfiles?.get(sessionId) ?? {} }, message);
+  } }); const initialized = await startManagedBridge({ config: state.config, state, bridge, kind: "grok-provider", publish: snapshot => writeState(paths.state, snapshot), log: paths.log }); runtime = new Runtime(paths, state, bridge, initialized);
+  bridge.configure({ onTerminalOutcome: outcome => runtime.reduceTerminal(outcome), onPromptDispatch: async dispatch => {
+    const turn = runtime.sessions.get(dispatch.session_id)?.native_prompt_operation;
+    if (!turn || turn.operation_id !== dispatch.operation_id || turn.connection_id !== dispatch.connection_id || turn.generation !== dispatch.generation) throw new DaemonError("native_dispatch_binding_mismatch", "Native prompt dispatch differs from retained operation");
+    turn.native_request_id = dispatch.native_request_id;
+    await runtime.persist();
+  } });
+  await runtime.restoreTerminals();
+  for (const fact of await readModelObservations(state.config.journal)) {
+    if (fact.harness === "grok-acp" && fact.source?.channel === "x.ai/subagent_spawned" && runtime.sessions.has(fact.session_id)
+      && (runtime.descendants.get(fact.session_id)?.attempt_id ?? null) === (fact.source.attempt_id ?? null) && fact.observed?.model) {
+      bridge.modelProfiles?.set(fact.session_id, { model: fact.observed.model });
+    }
+  }
+  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 at = buffer.indexOf("\n"); if (at < 0) return; consumed = true;
+      void (async () => {
+        let request;
+        try {
+          request = JSON.parse(buffer.slice(0, at));
+          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`);
+        }
+      })();
+    });
+  });
+  trackDaemonConnections(server); 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 }); runtime.ready = true; return await new Promise(() => {});
+}
+import { authorizeRetainedDaemonResume } from "./driver-recovery.mjs";
+import { commandText } from "./process-json.mjs";