@deksden-com/dd-flow-cli 0.9.0-beta.10 → 0.9.0-beta.103

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

@@ -0,0 +1,387 @@
+import { captureDispatchGuard, cancelPendingDispatch } from "./dispatch-fence.mjs";
+import { ToolObservations, acpToolObservation } from "./tool-observations.mjs";
+import { observedTimeout } 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 } 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 { cancelSessionWithBridge, createSessionWithBridge, doctor, forkSessionWithBridge, inspectSessionWithBridge, promptSessionWithBridge } from "./dd-grok.mjs";
+import { prepareRuntimeOwner, cleanupFailedStart, closeManagedBridge, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, heartbeatDaemonProcess, 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 === "session.resume" ? { ...request, operation: "session.inspect" } : request, 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; } }
+function errorPayload(error) { return { code: error.code ?? "operation_failed", message: error.message ?? String(error), retryable: error.retryable === true, ...(error.details === undefined ? {} : { details: error.details }) }; }
+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 }; }
+function isolatedEnv(config) { return { ...process.env, HOME: config.grokHome, GROK_HOME: config.grokHome, ...(config.ddFlowHome ? { DD_FLOW_HOME: config.ddFlowHome } : {}), ...(config.resourceHome ? { DD_FLOW_RESOURCE_HOME: config.resourceHome } : {}), ...(config.authPath ? { GROK_AUTH_PATH: config.authPath } : {}) }; }
+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 new Promise((resolve, reject) => {
+    const child = spawn(target.command, target.args, { cwd: config.cwd, env: isolatedEnv(config), stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk)); child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject); child.on("close", (code) => code === 0 ? resolve(stdout) : reject(new DaemonError("grok_inspect_failed", stderr.trim() || `${target.command} exited ${code}`)));
+  });
+  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) {
+  // Grok resume observes an already-owned Session; it never starts a turn.
+  if (operation === "session.resume") operation = "session.inspect";
+  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;
+    const timer = operation === "session.prompt" ? null : observedTimeout(() => finish(new DaemonError("daemon_timeout", `${operation} timed out`, true)), timeoutMs);
+    const finish = (error, value) => { if (settled) return; settled = true; 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", "authSource", "model", "reasoning", "mode", "ddFlowBin", "ddFlowHome", "projectRoot", "sessionArchive", "resourceHome", "noFlow"].every((key) => (state.config?.[key] ?? null) === (config[key] ?? null)); }
+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);
+  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; }
+  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", "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 state = { descendants: previous?.descendants ?? [], schema_id: STATE_SCHEMA, daemon_id: randomUUID(), 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, 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(config), detached: true, stdio: ["ignore", log.fd, log.fd] }); child.unref(); await log.close();
+  try { await confirmDaemonProcess(config, resourceProcess, child); const deadline = Date.now() + 30_000; while (Date.now() < deadline) { await new Promise((resolve) => setTimeout(resolve, 100)); 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 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; return await confirmDaemonStopped(() => callDaemon(options.stateDir, "daemon.stop", { cancelTree: options.cancelTree === true }, timeoutMs), locations(options.stateDir).socket, timeoutMs); }
+
+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.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.then(() => writeState(this.paths.state, snapshot)); return this.persisting; }
+  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, 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, { 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) {
+    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.
+    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);
+    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 });
+    this.descendants.set(id, {
+      provider_session_id: id,
+      parent_provider_session_id: parent,
+      status,
+      source,
+      ...(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 } : {})
+    });
+  }
+  observeSubagentEvent(message) {
+    const root = message?.params?.sessionId, update = message?.params?.update;
+    const kind = String(update?.sessionUpdate ?? update?.type ?? message?.method ?? "");
+    if (!root) return;
+    if (/subagent/i.test(kind)) {
+      for (const value of [update?.subagent, update?.subagentInfo, update?.child, update?.result, update]) 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");
+    }
+    // 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;
+    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;
+    }
+  }
+  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); }
+  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);
+  }
+  rootRunning(result) {
+    const status = String(result?.info?.status ?? result?.info?.state ?? result?.info?.data?.status ?? "unknown").toLowerCase();
+    // 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"].includes(receipt?.kind)) return false;
+    return !["completed", "failed", "cancelled", "stopped", "idle"].includes(status);
+  }
+  async refreshTree(cancel = false) {
+    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) {
+    if (this.active) throw new DaemonError("operation_busy", `${this.active} is already running`, true);
+    this.active = name;
+    // 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)) this.sessions.get(sessionId).native_root_receipt = null;
+    try {
+      await this.persist({ active_tree: true, active_operation: name });
+      const before = new Map(this.descendants);
+      const result = await task();
+      this.track(result, before);
+      const session = this.sessions.get(result.provider_session_id);
+      if (session && (["session.create", "session.fork"].includes(name) || ["end_turn", "cancelled"].includes(result.turn?.stopReason))) session.native_root_receipt = { kind: name === "session.prompt" ? result.turn.stopReason : "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) { await this.persist({ active_tree: true, active_operation: null }); throw error; }
+    finally { this.active = null; }
+  }
+  async dispatch(operation, params) {
+    const assertDispatch = captureDispatchGuard(this);
+    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) 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) { 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 { 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") 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; });
+    if (operation === "session.prompt") { await this.requireSettled(); return await this.productive(operation, async () => { const result = await promptSessionWithBridge(this.bridge, { ...this.options(params), assertDispatch }); this.loadedSessionId = params.sessionId; return result; }, params.sessionId); }
+    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(); return { ...result, settled: !this.active && !this.treeRunning(result), descendants: this.topology(result.provider_session_id) }; }
+    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") {
+      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 })) } : {})
+      });
+      await this.persist({ active_tree: false, shutdown_state: "stopping" });
+      return { daemon_id: this.state.daemon_id, stopped: true, clean: true, _shutdown: true };
+    }
+    throw new DaemonError("unknown_operation", `unknown daemon operation: ${operation}`);
+  }
+  async shutdown() { await closeManagedBridge(this.state.config, this.state, this.bridge); await finishDaemonProcess(this.state.config, this.state.resource_process); await unlink(path.join(this.paths.home, "auth.json")).catch(error => { if (error.code !== "ENOENT") throw error; }); await this.persist({ shutdown_state: "clean", stopped_at: new Date().toISOString() }); 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"); let runtime;
+  const bridge = new AcpBridge({ ...state.config, 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) => {
+    const sessionId = message?.params?.sessionId;
+    if (!runtime || !sessionId) return;
+    try {
+      runtime.observeToolCall(message); runtime.observeSubagentEvent(message);
+    } 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) }); runtime = new Runtime(paths, state, bridge, initialized);
+  await heartbeatDaemonProcess(state.config, state.resource_process);
+  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 => runtime.persist({ shutdown_state: "cleanup_failed", cleanup_error: errorPayload(error) }))); } 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 }); runtime.ready = true; return await new Promise(() => {});
+}
+import { authorizeRetainedDaemonResume } from "./driver-recovery.mjs";

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

@@ -0,0 +1,174 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { AcpBridge } from "./dd-zcode.mjs";
+import { checkObservedProfile, observeModel } from "./model-observations.mjs";
+
+const GROK_HARNESS_CONTRACT = "dd-grok-harness@1";
+
+function fail(message, code) { const error = new Error(message); if (code) error.code = code; throw error; }
+function absolute(value, label) { if (!value || !path.isAbsolute(value)) fail(`${label} must be an absolute path`); return path.resolve(value); }
+function text(value, label) { if (typeof value !== "string" || !value.trim()) fail(`${label} is required`); return value.trim(); }
+function 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 }; }
+
+async function commandOutput(command, args) {
+  const target = executable(command, args);
+  return await new Promise((resolve, reject) => {
+    const child = spawn(target.command, target.args, { stdio: ["ignore", "pipe", "pipe"] }); let stdout = ""; let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk)); child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject); child.on("close", (code) => code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || `${target.command} exited ${code}`)));
+  });
+}
+
+function profile(options) { return { provider: "xai", model: options.model ?? null, reasoning: options.reasoning ?? null, mode: options.mode ?? "bypassPermissions" }; }
+function requiredProfile(options) { const result = profile(options); text(result.model, "--model"); text(result.reasoning, "--reasoning"); return result; }
+function requireJournal(options) { absolute(options.journal, "--journal"); }
+function receipt(options, value) { return options.daemonId ? { daemon_id: options.daemonId, ...value } : value; }
+function unwrap(value) { return value?.result ?? value ?? {}; }
+function extension(method) { return method.startsWith("_") ? method : `_${method}`; }
+function usageScope(options, providerSessionId) { return providerSessionId === options.rootProviderSessionId ? "execution_tree_inclusive" : "physical_session"; }
+function emptyToolCalls() { return { total: 0, failures: 0, by_tool: {} }; }
+function sessionToolCalls(options, bridge, sessionId) { return options.toolUsage ? (options.toolUsage.get(sessionId) ?? emptyToolCalls()) : bridge.toolSummary(sessionId); }
+function recordToolCalls(options, bridge, sessionId, cursor) {
+  const result = options.toolUsage
+    ? sessionToolCalls(options, bridge, sessionId)
+    : typeof bridge.toolSummarySince === "function"
+      ? bridge.toolSummarySince(cursor, sessionId)
+      : bridge.toolSummary(sessionId);
+  options.toolUsage?.set(sessionId, result);
+  return result;
+}
+
+function bridgeOptions(options) {
+  const requested = profile(options);
+  const grokHome = options.grokHome ? absolute(options.grokHome, "--grok-home") : null;
+  return {
+    ...options,
+    observationHarness: "grok-acp",
+    // AcpBridge defaults to zcode-acp; Grok must always name its own executable.
+    bin: options.bin ?? process.env.DD_GROK_BIN ?? "grok",
+    commandArgs: ["agent", "--no-leader", "--always-approve", "--model", requested.model ?? "grok-4.6", "--reasoning-effort", requested.reasoning ?? "high", "stdio"],
+    env: { ...(grokHome ? { HOME: grokHome, GROK_HOME: grokHome } : {}), ...(options.authPath ? { GROK_AUTH_PATH: absolute(options.authPath, "--auth-path") } : {}) },
+    clientInfo: { name: "dd-grok", version: "0.1.0" }, permission: "allow"
+  };
+}
+
+async function withBridge(options, operation) {
+  const bridge = new AcpBridge(bridgeOptions(options));
+  try { const initialized = await bridge.start(); return await operation(bridge, initialized); }
+  finally { await bridge.close(); }
+}
+
+export function observedProfile(initialized, requested) {
+  const state = initialized?._meta?.modelState ?? {};
+  const model = state.currentModelId ?? null;
+  const available = (state.availableModels ?? []).find((item) => item?.modelId === model);
+  return { provider: null, model, reasoning: available?._meta?.reasoningEffort ?? null, mode: null };
+}
+
+export function assertProfile(requested, observed) { return checkObservedProfile(requested, observed); }
+
+async function sessionInfo(bridge, sessionId) { return unwrap(await bridge.request(extension("x.ai/session/info"), { sessionId })); }
+async function sessionUsage(bridge, sessionId) { try { return unwrap(await bridge.request(extension("x.ai/session/usage"), { sessionId })); } catch (error) { return { unavailable: true, error: error.message }; } }
+async function subagents(bridge, sessionId) { return unwrap(await bridge.request(extension("x.ai/subagent/list_running"), { sessionId })); }
+
+async function inspect(bridge, sessionId, options) {
+  const [info, topology, usage] = await Promise.all([sessionInfo(bridge, sessionId), subagents(bridge, sessionId), sessionUsage(bridge, sessionId)]);
+  const native = info?.data ?? info ?? {}, model = typeof native.model === "string" ? native.model : native.model?.modelId ?? null;
+  const current = model ? { model, provider: native.provider ?? null, reasoning: native.reasoningEffort ?? null, mode: native.mode ?? null } : bridge.modelProfiles?.get(sessionId) ?? { model: null, provider: null, reasoning: null, mode: null };
+  await observeModel({ journal: options.journal, harness: "grok-acp", sessionId, requested: profile(options), observed: current, source: model ? "x.ai/session/info" : "native.model_source_incomplete", evidence: model ? "configured" : "unavailable", reason: model ? null : "session_info_omits_model" });
+  return { info, subagents: topology, usage, observed_profile: model ? current : { model: null, provider: null, reasoning: null, mode: null } };
+}
+
+async function forwardUsage(options, providerSessionId, usage, toolCalls) {
+  if (options.noFlow || !options.ddFlowBin || !usage || usage.unavailable) return;
+  const measured = usage.usage && typeof usage.usage === "object" ? usage.usage : usage;
+  const input = JSON.stringify({ provider_session_id: providerSessionId, daemon_id: options.daemonId ?? null, observed_at: new Date().toISOString(), usage: measured, tool_calls: toolCalls, usage_scope: usageScope(options, providerSessionId), completeness: measured.usageIsIncomplete ? "partial" : "complete" });
+  const target = executable(options.ddFlowBin, ["grok", "usage", "ingest", "--project-root", absolute(options.projectRoot, "--project-root"), "--json"]);
+  await new Promise((resolve, reject) => {
+    const child = spawn(target.command, target.args, { env: { ...process.env, ...(options.ddFlowHome ? { DD_FLOW_HOME: absolute(options.ddFlowHome, "--dd-flow-home") } : {}) }, stdio: ["pipe", "ignore", "pipe"] }); let stderr = "";
+    child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk)); child.on("error", reject); child.on("close", (code) => code === 0 ? resolve() : reject(new Error(stderr || "dd-flow grok usage failed"))); child.stdin.end(`${input}\n`);
+  });
+}
+
+async function forwardUsageBestEffort(options, providerSessionId, usage, toolCalls) {
+  try { await forwardUsage(options, providerSessionId, usage, toolCalls); return null; }
+  catch (error) { return { code: error.code ?? "usage_ingest_failed", message: error.message ?? String(error) }; }
+}
+
+async function identity(bridge, options) {
+  const sessionId = text(options.sessionId, "--session-id");
+  if (!options.liveSession) await bridge.request("session/load", { sessionId, cwd: absolute(options.cwd, "--cwd"), mcpServers: [] });
+  bridge.registerModelSession?.(sessionId, sessionId, profile(options), options.rootProviderSessionId && options.rootProviderSessionId !== sessionId ? options.rootProviderSessionId : null);
+  return sessionId;
+}
+
+async function cancelTree(bridge, sessionId) {
+  const before = await subagents(bridge, sessionId).catch(error => ({ observation_error: { code: error.code, message: error.message } })); const cancellations = [];
+  for (const child of before.subagents ?? []) {
+    const childId = child.sessionId ?? child.subagentId;
+    if (childId) {
+      try { cancellations.push(await bridge.request(extension("x.ai/subagent/cancel"), { sessionId, subagentId: childId })); }
+      catch (error) { cancellations.push({ session_id: childId, cancelled: false, error: { code: error.code, message: error.message } }); }
+    }
+  }
+  bridge.notify("session/cancel", { sessionId });
+  for (let attempt = 0; attempt < 50; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const after = await subagents(bridge, sessionId).catch(error => ({ observation_error: { code: error.code, message: error.message } }));
+    if (after.observation_error) return { before, after, cancellations, settled: false };
+    if (!(after.subagents ?? []).length) {
+      const root = await sessionInfo(bridge, sessionId).catch(error => ({ observation_error: { code: error.code, message: error.message } }));
+      const status = root?.status ?? root?.state ?? root?.data?.status ?? null;
+      return { before, after, cancellations, root_status: status, settled: ["completed", "failed", "cancelled", "stopped", "idle"].includes(String(status).toLowerCase()) };
+    }
+  }
+  const root = await sessionInfo(bridge, sessionId).catch(() => null);
+  return { before, after: await subagents(bridge, sessionId).catch(() => ({ subagents: [] })), cancellations, root_status: root?.status ?? root?.state ?? null, settled: false };
+}
+
+export async function doctor(options = {}) {
+  const raw = await commandOutput(options.bin, ["version", "--json"]); const version = JSON.parse(raw).currentVersion?.split(" ")[0] ?? raw.trim();
+  return { compatible: true, observed_runtime: { grok: version, acp: 1, dd_harness_contract: GROK_HARNESS_CONTRACT } };
+}
+
+export async function createSession(options) { requireJournal(options); return await withBridge(options, async (bridge, initialized) => await createSessionWithBridge(bridge, options, initialized)); }
+export async function createSessionWithBridge(bridge, options, initialized) {
+  requireJournal(options); const cwd = absolute(options.cwd, "--cwd"); const requested = requiredProfile(options);
+  const created = await bridge.request("session/new", { cwd, mcpServers: [], ...(options.authMethodId ? { authMethodId: options.authMethodId } : {}) });
+  const providerSessionId = text(created.sessionId, "Grok Build sessionId");
+  bridge.registerModelSession?.(providerSessionId, providerSessionId, requested);
+  await observeModel({ journal: options.journal, harness: "grok-acp", sessionId: providerSessionId, requested, observed: observedProfile(initialized, requested), source: "acp.initialize.modelState" });
+  const profileReceipt = assertProfile(requested, observedProfile(initialized, requested));
+  await options.onSessionCreated?.({ provider_session_id: providerSessionId, adapter_session_id: providerSessionId, cwd });
+  const local = { ...options, initialized, rootProviderSessionId: providerSessionId }; const initial_usage_error = await forwardUsageBestEffort(local, providerSessionId, await sessionUsage(bridge, providerSessionId), sessionToolCalls(local, bridge, providerSessionId));
+  await bridge.flush(); const evidence = await inspect(bridge, providerSessionId, local); evidence.tool_calls = sessionToolCalls(local, bridge, providerSessionId); const usage_ingest_error = await forwardUsageBestEffort(local, providerSessionId, evidence.usage, evidence.tool_calls); if (initial_usage_error) evidence.initial_usage_error = initial_usage_error; if (usage_ingest_error) evidence.usage_ingest_error = usage_ingest_error;
+  return receipt(options, { harness: "grok-acp", runtime_family: "grok", provider_session_id: providerSessionId, adapter_session_id: providerSessionId, cwd, initialized, profile: profileReceipt, evidence });
+}
+
+export async function promptSession(options) { requireJournal(options); return await withBridge(options, async (bridge, initialized) => await promptSessionWithBridge(bridge, { ...options, initialized })); }
+export async function promptSessionWithBridge(bridge, options) {
+  requireJournal(options); const sessionId = await identity(bridge, options); const prompt = text(options.prompt, "prompt"); const requested = requiredProfile(options); const profileReceipt = assertProfile(requested, observedProfile(options.initialized, requested));
+  const local = { ...options, rootProviderSessionId: options.rootProviderSessionId ?? sessionId }; const initial_usage_error = await forwardUsageBestEffort(local, sessionId, await sessionUsage(bridge, sessionId), sessionToolCalls(local, bridge, sessionId));
+  options.assertDispatch?.();
+  const cursor = bridge.toolCursor(); const textCursor = bridge.assistantTextCursor(sessionId); const turn = await bridge.request("session/prompt", { sessionId, prompt: [{ type: "text", text: prompt }] }, null, { idleSessionId: sessionId, idleTimeoutMs: options.timeoutMs ?? 600_000 }); await bridge.flush();
+  const evidence = await inspect(bridge, sessionId, local); evidence.tool_calls = recordToolCalls(local, bridge, sessionId, cursor); const usage_ingest_error = await forwardUsageBestEffort(local, sessionId, evidence.usage, evidence.tool_calls); if (initial_usage_error) evidence.initial_usage_error = initial_usage_error; if (usage_ingest_error) evidence.usage_ingest_error = usage_ingest_error;
+  if (!options.allowBackground && (evidence.subagents?.subagents ?? []).length) { await cancelTree(bridge, sessionId); fail("background Grok Build subagents cannot outlive the one-shot dd-grok connection"); }
+  return receipt(options, { harness: "grok-acp", provider_session_id: sessionId, adapter_session_id: sessionId, assistant_text: bridge.assistantTextSince(sessionId, textCursor), turn, profile: profileReceipt, evidence });
+}
+
+export async function inspectSession(options) { requireJournal(options); return await withBridge(options, async (bridge, initialized) => await inspectSessionWithBridge(bridge, { ...options, initialized })); }
+export async function inspectSessionWithBridge(bridge, options) { requireJournal(options); const sessionId = await identity(bridge, options); const evidence = await inspect(bridge, sessionId, options); evidence.tool_calls = sessionToolCalls(options, bridge, sessionId); const usage_ingest_error = await forwardUsageBestEffort(options, sessionId, evidence.usage, evidence.tool_calls); if (usage_ingest_error) evidence.usage_ingest_error = usage_ingest_error; return receipt(options, { harness: "grok-acp", provider_session_id: sessionId, adapter_session_id: sessionId, ...evidence }); }
+export async function cancelSession(options) { requireJournal(options); return await withBridge(options, async (bridge) => await cancelSessionWithBridge(bridge, options)); }
+export async function cancelSessionWithBridge(bridge, options) { requireJournal(options); const sessionId = await identity(bridge, options); return receipt(options, { harness: "grok-acp", provider_session_id: sessionId, adapter_session_id: sessionId, ...await cancelTree(bridge, sessionId) }); }
+export async function forkSession(options) { requireJournal(options); return await withBridge(options, async (bridge) => await forkSessionWithBridge(bridge, options)); }
+export async function forkSessionWithBridge(bridge, options) {
+  requireJournal(options); const sessionId = await identity(bridge, options); const target = options.target;
+  if (!target || typeof target !== "object" || !target.newCwd) fail("explicit --target-json with newCwd is required");
+  if ((await subagents(bridge, sessionId)).subagents?.length) fail("cannot fork while Grok Build subagents are running", "tree_not_settled");
+  const source = await sessionInfo(bridge, sessionId);
+  const result = unwrap(await bridge.request(extension("x.ai/session/fork"), { sourceSessionId: sessionId, sourceCwd: source.cwd ? absolute(source.cwd, "Grok Build source cwd") : absolute(options.cwd, "--cwd"), ...target }));
+  const child = text(result.newSessionId, "Grok Build fork newSessionId"); return receipt(options, { harness: "grok-acp", parent_provider_session_id: sessionId, provider_session_id: child, adapter_session_id: child, target, fork: result });
+}
+export async function promptFromFile(file) { return await readFile(absolute(file, "--prompt-file"), "utf8"); }