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

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

@@ -0,0 +1,1362 @@
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import { SETUP_STARTUP_MS, startupObserver, observationDetails } from './setup-progress.mjs';
+import { callDaemonObserved } from './daemon-observation.mjs';
+import { operationProgressReporter } from './operation-progress.mjs';
+import { prepareDaemonRequest } from "./native-request-proof.mjs";
+import { inspectAgyNative, inspectAgyNativeState, stopAgyNativeTree, ownedAgyEndpoint, readAgyNativeQualification, AGY_NATIVE_INSPECTION_CONTRACT } from './agy-native-inspection.mjs';
+import { agyNativeInventory } from './agy-native-inventory.mjs';
+import { processSnapshot } from './process-snapshot.mjs';
+import { streamRequestKey } from './provider-overload-policy.mjs';
+import { captureDispatchGuard, cancelPendingDispatch } from "./dispatch-fence.mjs";
+import { errorRecord } from "./operation-errors.mjs";
+import { ToolObservations, agyToolObservation, createAgyTranscriptObserver } from "./tool-observations.mjs";
+import { readAgyTranscriptSnapshot } from "./agy-transcript-stream.mjs";
+import { constants } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { isDeepStrictEqual } from "node:util";
+import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
+import { hookBudget, retainNativeWorkStart, isStandaloneWorkStart } from "./native-hook-command.mjs";
+import { parseLifecycleCommand } from "./lifecycle-command.mjs";
+import { agyWorkspaceHooks } from "./agy-hooks.mjs";
+import { durableDaemonDispatch, completeDaemonShutdown, assertDaemonDispatch, assertDaemonRestartable, trackDaemonConnections, retireDaemonEndpoint, retireFailedDaemon } from "./daemon-operations.mjs";
+import path from "node:path";
+import { observeModel } from "./model-observations.mjs";
+import { AGY_VERSION_TIMEOUT_MS, AgyError, agyTerminalFailure, agyErrorDiagnostic, agyModelArgs, assertProfile, executable, observedProfile, runAgy, usageSnapshot, managedAgyEnv } from "./dd-agy.mjs";
+import { agyTerminalEnvelope } from "./agy-terminal-envelope.mjs";
+import { settledNativeTree, nativeExecutionReceipt } from "./native-children.mjs";
+import { retainStartupFailure, prepareRuntimeOwner, cleanupFailedStart, cleanupFailedDaemonStart, confirmDaemonProcess, confirmDaemonStopped, finishDaemonProcess, scheduleDaemonProcessHeartbeat, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.mjs";
+import { readNativeLines, nativeObservationError, admitNativeRequestBuffer } from "./native-streams.mjs";
+
+const REQUEST_SCHEMA = "dd-agy/daemon-request@1", RESPONSE_SCHEMA = "dd-agy/daemon-response@1", STATE_SCHEMA = "dd-agy/daemon-state@1";
+class DaemonError extends AgyError {}
+// Only unambiguously correlated native tool results can introduce children or
+// classify services. This transcript format has no tool-call IDs: parallel
+// calls therefore retain unknown resources, never FIFO-derived authority.
+export function agyTranscriptFacts(text, source, sessionId) {
+  const reducer = createAgyTranscriptFacts(source, sessionId), lines = text.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (!line && index === lines.length - 1) continue;
+    let event;
+    try { event = JSON.parse(line); } catch { if (index < lines.length - 1) reducer.gap(); break; }
+    reducer.add(event);
+  }
+  return reducer.finish();
+}
+export function createAgyTranscriptFacts(source, sessionId) {
+  const children = [], resources = new Map(), calls = [];
+  let invalid = false;
+  function add(event) {
+    if (invalid || !source?.locator || !source?.sha256 || !sessionId) return;
+    if (!event || typeof event !== 'object' || Array.isArray(event) || event.conversation_id && event.conversation_id !== sessionId) { invalid = true; return; }
+    const content = typeof event.content === 'string' ? event.content : '';
+    const native_source = { ...source, step_index: event.step_index };
+    if (event.source === 'SYSTEM' && event.type === 'SYSTEM_MESSAGE' && event.status === 'DONE') {
+      const terminal = agyTerminalEnvelope(event);
+      if (terminal) {
+        const prior = resources.get(terminal.task_id);
+        if (prior) resources.set(prior.resource_id, mergeAgyResource(prior, { ...prior, state: 'stopped', ...(terminal.command_outcome ? { native_outcome: terminal.command_outcome } : {}), terminal_source: native_source }));
+      }
+      return;
+    }
+    if (event.source !== 'MODEL') return;
+    if (event.type === 'PLANNER_RESPONSE') { calls.length = 0; if (Array.isArray(event.tool_calls) && event.tool_calls.length === 1) calls.push(event.tool_calls[0]); return; }
+    if (event.type !== 'GENERIC') return;
+    const call = calls.shift();
+    if (call?.name === 'manage_task' && event.status === 'DONE') {
+      const terminal = agyTerminalEnvelope(event, call), prior = resources.get(terminal?.task_id);
+      if (prior) resources.set(prior.resource_id, mergeAgyResource(prior, { ...prior, state: 'stopped', ...(terminal.command_outcome ? { native_outcome: terminal.command_outcome } : {}), terminal_source: native_source }));
+    }
+    if (call?.name === 'invoke_subagent' && event.status === 'DONE') {
+      const match = content.match(/^Created At: [^\n]+\nCompleted At: [^\n]+\nCreated the following subagent:\n(\{[\s\S]*?\})\nThe subagent will send you a message/);
+      if (!match) return;
+      try {
+        const child = JSON.parse(match[1]);
+        if (/^[\w-]+$/.test(child.conversationId) && typeof child.logAbsoluteUri === 'string') children.push({ provider_session_id: child.conversationId, parent_provider_session_id: sessionId, log_uri: child.logAbsoluteUri, workspace_uris: child.workspaceUris ?? [], status: 'unknown', native_source });
+      } catch { /* No partial/guessed native edge. */ }
+    }
+    if (event.status !== 'RUNNING') return;
+    const task = content.match(/^Created At: [^\n]+\nTool is running as a background task with task id: ([\w-]+\/task-\d+)\n/);
+    if (!task || !task[1].startsWith(`${sessionId}/`)) return;
+    let daemon = call?.name === 'run_command' ? call.args?.IsDaemon : null;
+    if (typeof daemon === 'string') { try { daemon = JSON.parse(daemon); } catch { daemon = null; } }
+    const resource = { resource_id: task[1], provider_session_id: sessionId, ...(call?.name === 'schedule' ? { kind: 'schedule' } : {}), classification: daemon === true ? 'support_service' : daemon === false ? 'required_work' : 'unknown', state: 'unknown', native_source,
+      ...(typeof daemon === 'boolean' ? { native_classification: { tool: 'run_command', IsDaemon: daemon } } : {}) };
+    resources.set(resource.resource_id, mergeAgyResource(resources.get(resource.resource_id), resource));
+  }
+  return { add, gap: () => { invalid = true; }, finish: () => ({ children, resources: [...resources.values()], ...(invalid ? { gap: 'agy_transcript_invalid_record' } : {}) }) };
+}
+export function mergeAgyResource(prior, next) {
+  if (!prior) return next;
+  if (prior.provider_session_id !== next.provider_session_id || prior.native_source?.locator !== next.native_source?.locator)
+    return { ...prior, state: 'unknown', observation_conflict: true };
+  if (prior.native_source?.step_index !== next.native_source?.step_index)
+    return { ...prior, state: 'unknown', observation_conflict: true };
+  if (prior.observation_conflict || next.observation_conflict || prior.native_outcome && next.native_outcome && prior.native_outcome !== next.native_outcome)
+    return { ...prior, state: 'unknown', observation_conflict: true };
+  if (next.terminal_source && (!Number.isSafeInteger(next.native_source?.step_index) || !Number.isSafeInteger(next.terminal_source?.step_index) || next.terminal_source.step_index <= next.native_source.step_index))
+    return { ...prior, state: 'unknown', observation_conflict: true };
+  if (prior.state === 'stopped' && next.state !== 'stopped') {
+    if (next.native_source?.step_index > (prior.terminal_source?.step_index ?? prior.native_source?.step_index))
+      return { ...prior, state: 'unknown', observation_conflict: true };
+    return prior;
+  }
+  return { ...prior, ...next };
+}
+export const agyTranscriptResources = (text, source, sessionId) => agyTranscriptFacts(text, source, sessionId).resources;
+export async function captureAgyTranscript(runtimeRoot, child, rootSessionId, ownedSessionIds = [rootSessionId], inspect = null, onProgress = null) {
+  const session = { harness_id: "antigravity-cli", session_id: child.provider_session_id };
+  let handle;
+  try {
+    if (!rootSessionId || !child.provider_session_id || !ownedSessionIds.includes(child.parent_provider_session_id) || !child.log_uri || !/^[\w-]+$/.test(child.provider_session_id)) throw new Error("unbound native locator");
+    const expected = path.join(runtimeRoot, "brain", child.provider_session_id, ".system_generated", "logs", "transcript.jsonl");
+    const canonical = path.join(await realpath(runtimeRoot), "brain", child.provider_session_id, ".system_generated", "logs", "transcript.jsonl");
+    if (![expected, canonical].includes(fileURLToPath(child.log_uri)) || await realpath(expected) !== canonical) throw new Error("foreign or symlink native locator");
+    const before = await lstat(expected);
+    if (!before.isFile()) throw new Error("native locator is not a regular file");
+    handle = await open(expected, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = await handle.stat();
+    if (!before.isFile() || !stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino || await realpath(expected) !== canonical) throw new Error("native locator changed during open");
+    let observer, inspector;
+    const snapshot = await readAgyTranscriptSnapshot(handle, { locator: child.log_uri, onProgress,
+      assertIdentity: async current => { const pathStat = await lstat(expected); if (!pathStat.isFile() || current.dev !== pathStat.dev || current.ino !== pathStat.ino || await realpath(expected) !== canonical) throw new Error('native locator changed during read'); },
+      onRecord: (record, { line, ...source }) => {
+        observer ??= createAgyTranscriptObserver(child.provider_session_id, child.parent_provider_session_id ?? rootSessionId, source);
+        inspector ??= inspect?.(source);
+        observer.add(record, line); inspector?.add(record);
+      } });
+    observer ??= createAgyTranscriptObserver(child.provider_session_id, child.parent_provider_session_id ?? rootSessionId, snapshot.source);
+    if (!snapshot.partial_tail) inspector?.finish();
+    const events = observer.finish();
+    if (snapshot.partial_tail) events.push({ session, reason: "agy_transcript_partial_tail" });
+    return events;
+  } catch (error) { return [{ session, reason: error.code === "ENOENT" ? "agy_transcript_missing" : error.message === 'agy_transcript_invalid_record' ? 'agy_transcript_invalid_record' : "agy_transcript_locator_rejected" }]; }
+  finally { await handle?.close(); }
+}
+const 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"), digest = createHash("sha256").update(dir).digest("hex").slice(0, 22), local = path.join(dir, "daemon.sock");
+  // `tsx` creates Unix-domain sockets below TMPDIR.  An evaluation path is
+  // intentionally descriptive and can exceed the platform's socket-path cap,
+  // so provider temp files must not inherit that path.
+  return { dir, socket: Buffer.byteLength(local) < 100 ? local : `/tmp/dd-agy-${digest}.sock`, state: path.join(dir, "daemon.json"), journal: path.join(dir, "events.jsonl"), log: path.join(dir, "daemon.log"), gemini: path.join(dir, "gemini"), runtime: path.join(dir, "gemini", "runtime"), config: path.join(dir, "gemini", "config"), temporary: `/tmp/dd-agy-tmp-${digest}` };
+}
+async function writeJson(file, value) { const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`; await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 }); await rename(temporary, file); }
+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 removeSocket(paths) { try { if (!(await lstat(paths.socket)).isSocket()) throw new DaemonError("unsafe_socket", "refusing to replace a non-socket daemon path"); await unlink(paths.socket); } catch (error) { if (error.code !== "ENOENT") throw error; } }
+const shell = value => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+export function sanitizedEnv(config) { const env = { ...process.env, TMPDIR: config.temporary, DD_AGY_HOOK_NODE: process.execPath, DD_AGY_HOOK_ENTRY: config.entryPath, DD_AGY_STATE_DIR: config.stateDir, DD_AGY_DAEMON_ID: config.daemonId }; for (const key of ["GEMINI_API_KEY","GOOGLE_API_KEY","ANTHROPIC_API_KEY","OPENAI_API_KEY"]) env[key] = undefined; return managedAgyEnv({ ...env, ...managedFlowEnv(config) }); }
+
+const errorPayload = errorRecord;
+async function forwardUsage(config, sessionId, result, tools, descendants) {
+  if (!config.ddFlowBin || !config.projectRoot) return;
+  const snapshot = usageSnapshot(result, tools), hasChildren = descendants.length > 0;
+  if (snapshot.total_tokens === null) return { status: "unavailable", reason: "provider_did_not_report_total_tokens" };
+  const payload = { provider_session_id: sessionId, daemon_id: config.daemonId, observed_at: new Date().toISOString(), usage_scope: hasChildren ? "unknown" : "physical_session", completeness: hasChildren ? "partial" : "complete", usage: { inputTokens: snapshot.input_tokens, outputTokens: snapshot.output_tokens, reasoningTokens: snapshot.reasoning_tokens, cacheReadInputTokens: snapshot.cache_read_tokens, totalTokens: snapshot.total_tokens }, tool_calls: snapshot.tool_calls };
+  const target = executable(config.ddFlowBin, ["agy", "usage", "ingest", "--project-root", config.projectRoot, "--json"]);
+  await commandText(target.command, target.args, { input: `${JSON.stringify(payload)}\n`, env: { DD_FLOW_HOME: config.ddFlowHome }, phase: "usage-ingest" });
+  return { status: "ingested" };
+}
+
+export async function prepare(paths, config) {
+  config.stateDir = paths.dir;
+  config.hookBinding = "environment-v1";
+  const hooks = agyWorkspaceHooks();
+  for (const dir of [paths.dir, paths.gemini, paths.runtime, paths.config, paths.temporary]) { await mkdir(dir, { recursive: true, mode: 0o700 }); await chmod(dir, 0o700); }
+  if (config.noFlow) {
+    // Technical probes still need native settlement, but must not install
+    // workspace hooks or forward any lifecycle mutation to dd-flow.
+    await writeJson(path.join(paths.config, "hooks.json"), { "dd-flow-observer": { Stop: hooks["dd-flow"].Stop } });
+    return;
+  }
+  // Native discovery follows cwd (feature worktree/reviewer clone), while
+  // projectRoot remains the stable lifecycle identity returned to dd-flow.
+  Object.assign(config, await qualifyAgyHooks(config.cwd ?? config.projectRoot, { stateDir: paths.dir }));
+  // Workspace discovery covers root and children without global duplicates.
+  await writeJson(path.join(paths.config, "hooks.json"), {});
+}
+
+export async function qualifyAgyHooks(projectRoot, { stateDir = null, install = false } = {}) {
+  const hooks = agyWorkspaceHooks();
+  // Register in workspace discovery before creating any Session: native root
+  // and children load these named hook definitions without a global duplicate.
+  // Replace our prior handlers, including the obsolete wildcard post hook,
+  // without dropping unrelated commands in a shared matcher group.
+  const workspaceConfig = path.join(absolute(projectRoot, "--project-root"), ".agents");
+  const workspaceHooks = path.join(workspaceConfig, "hooks.json");
+  let existing = {}, existingText = "";
+  try {
+    existingText = await readFile(workspaceHooks, "utf8");
+    const parsed = JSON.parse(existingText);
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") throw new Error("not an object");
+    existing = parsed;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw new DaemonError("workspace_hooks_invalid", `cannot install Antigravity lifecycle hooks: ${error.message}`);
+    if (!install) throw new DaemonError("workspace_hooks_unqualified", "Antigravity hooks must be installed during qualification before daemon start", false, { hooks_path: workspaceHooks });
+  }
+  const isManagedHandler = handler => typeof handler?.command === "string"
+    && ((handler.command.includes("DD_AGY_HOOK_ENTRY") && handler.command.includes(" hook handle --event ") && handler.command.includes("DD_AGY_STATE_DIR")) || /(?:^|\/)dd-agy\.mjs['"]?\s+hook handle/.test(handler.command));
+  const events = ["PreToolUse", "PostToolUse", "PreInvocation", "PostInvocation", "Stop"];
+  const existingManaged = Object.entries(existing).flatMap(([name, definition]) => {
+    if (events.includes(name) && Array.isArray(definition)) return definition;
+    if (!definition || typeof definition !== "object" || Array.isArray(definition)) return [];
+    return events.flatMap(event => Array.isArray(definition[event]) ? definition[event] : []);
+  }).flatMap(item => Array.isArray(item?.hooks) ? item.hooks : [item]).filter(handler => isManagedHandler(handler) && handler.command.includes("--state-dir") && !handler.command.includes("DD_AGY_STATE_DIR"));
+  if (existingManaged.some(handler => !stateDir || !handler.command.includes(`--state-dir ${shell(stateDir)}`))) {
+    throw new DaemonError("workspace_hooks_drifted", "qualified Antigravity hook routes to another daemon state directory", false, { hooks_path: workspaceHooks, expected_state_dir: stateDir });
+  }
+  const retain = handlers => handlers.flatMap(item => {
+    if (!Array.isArray(item?.hooks)) return isManagedHandler(item) ? [] : [item];
+    const remaining = item.hooks.filter(handler => !isManagedHandler(handler));
+    return remaining.length ? [{ ...item, hooks: remaining }] : [];
+  });
+  const workspace = Object.create(null), legacy = Object.create(null);
+  for (const [name, definition] of Object.entries(existing)) {
+    // Migrate the old adapter's event-keyed workspace format.
+    if (events.includes(name) && Array.isArray(definition)) {
+      const remaining = retain(definition);
+      if (remaining.length) legacy[name] = remaining;
+      continue;
+    }
+    if (!definition || Array.isArray(definition) || typeof definition !== "object") {
+      throw new DaemonError("workspace_hooks_invalid", `invalid named hook definition: ${name}`);
+    }
+    const cleaned = { ...definition };
+    for (const event of events) if (Array.isArray(cleaned[event])) {
+      const remaining = retain(cleaned[event]);
+      if (remaining.length || cleaned[event].length === 0) cleaned[event] = remaining;
+      else delete cleaned[event];
+    }
+    workspace[name] = cleaned;
+  }
+  if (Object.keys(legacy).length) {
+    let name = "dd-flow-legacy";
+    while (Object.hasOwn(workspace, name)) name += "-retained";
+    workspace[name] = legacy;
+  }
+  const managed = workspace["dd-flow"] ?? {};
+  if (managed.enabled === false) throw new DaemonError("workspace_hooks_invalid", "dd-flow lifecycle hooks are disabled");
+  for (const [event, handlers] of Object.entries(hooks["dd-flow"])) {
+    managed[event] = [...(managed[event] ?? []), ...handlers];
+  }
+  workspace["dd-flow"] = managed;
+  const serializedWorkspace = `${JSON.stringify(workspace, null, 2)}\n`;
+  // Hook installation is a qualification/ownership boundary. Reusing the
+  // qualified command must not rewrite the project file when the pinned engine,
+  // daemon directory or workspace location changes.
+  const installed = isDeepStrictEqual(existing, JSON.parse(serializedWorkspace));
+  if (!installed && !install) throw new DaemonError("workspace_hooks_unqualified", "Antigravity hook definitions differ from the qualified contract", false, { hooks_path: workspaceHooks });
+  if (!installed) { await mkdir(workspaceConfig, { recursive: true, mode: 0o700 }); await writeFile(workspaceHooks, serializedWorkspace, { mode: 0o600 }); }
+  return { hooksSha256: createHash("sha256").update(JSON.stringify(hooks)).digest("hex"), workspaceHooksPath: workspaceHooks,
+    workspaceHooksSha256: createHash("sha256").update(installed ? existingText : serializedWorkspace).digest("hex"), workspaceHooksInstalled: installed ? "qualified_existing" : "qualified_install" };
+}
+
+export async function callDaemon(stateDir, operation, params = {}, timeoutMs = 30_000, requestId = null) {
+  const request = prepareDaemonRequest({ schema_id: REQUEST_SCHEMA, id: requestId ?? process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation, params });
+  return await callDaemonObserved({ stateDir, socket: locations(stateDir).socket, request, responseSchema: RESPONSE_SCHEMA, harness: 'agy', timeoutMs });
+}
+
+function sameConfig(state, config) { return ["cwd","journal","bin","provider","model","reasoning","mode","projectRoot","ddFlowBin","ddFlowHome","resourceHome","noFlow","livenessTimeoutMs","nativeQualificationPath"].every(key => (state.config?.[key] ?? null) === (config[key] ?? null)); }
+// Called only after authorizeRetainedDaemonResume verifies the old daemon,
+// provider processes and operation ledger. Native outcomes remain historical;
+// their old liveness flags cannot describe the replacement process tree.
+export function retainedAgyState(previous, sessionId) {
+  if (!sessionId || !previous?.sessions?.some(session => session.provider_session_id === sessionId)) return {};
+  if (previous.shutdown_state !== "clean" || previous.active_tree !== false) return previous;
+  return {
+    ...previous,
+    unclaimed_activity: false,
+    native_resources_entries: [],
+    native_topology_error: null,
+    retained_tree_settlement: { daemon_id: previous.daemon_id, session_id: sessionId, turn_generation: previous.turn_generation ?? 0, evidence: "verified_clean_daemon_shutdown" },
+    session_observations: (previous.session_observations ?? []).map(([id, observation]) => [id, id === sessionId ? { ...observation, retained_stop: observation.stop ?? null, stop: null } : observation]),
+    descendants: (previous.descendants ?? []).map(child => child.tree_settled === true ? child : { ...child, tree_settled: true, settlement_evidence: "prior_clean_daemon_shutdown", settlement_daemon_id: previous.daemon_id })
+  };
+}
+export async function startDaemon(options) {
+  const paths = locations(options.stateDir); await mkdir(paths.dir, { recursive: true, mode: 0o700 }); await chmod(paths.dir, 0o700);
+  const previous = await readState(paths.dir), noFlow = options.noFlow === true, cwd = await realpath(absolute(options.cwd, "--cwd")), config = { cwd, journal: options.journal ? absolute(options.journal, "--journal") : paths.journal, bin: options.bin ?? process.env.DD_AGY_BIN ?? "agy", provider: String(options.provider ?? "google"), model: String(options.model ?? "gemini-3.1-pro-high"), reasoning: String(options.reasoning ?? "high"), mode: String(options.mode ?? "accept-edits"), projectRoot: noFlow ? cwd : await realpath(absolute(options.projectRoot, "--project-root")), ddFlowBin: noFlow ? null : absolute(options.ddFlowBin, "--dd-flow-bin"), ddFlowHome: noFlow ? null : absolute(options.ddFlowHome, "--dd-flow-home"), 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") }, entryPath: absolute(options.entryPath, "dd-agy entry"), daemonId: randomUUID(), resumeSessionId: options.sessionId ?? null, geminiDir: paths.gemini, appDataDir: "runtime", temporary: paths.temporary, noFlow };
+  config.livenessTimeoutMs = options.livenessTimeoutMs ?? 1_800_000;
+  config.nativeQualificationPath = process.env.DD_AGY_NATIVE_QUALIFICATION ? absolute(process.env.DD_AGY_NATIVE_QUALIFICATION, 'DD_AGY_NATIVE_QUALIFICATION') : null;
+  validateObservationDuration(config.livenessTimeoutMs);
+  await prepareRuntimeOwner(config, paths.dir);
+  assertDaemonRestartable(previous);
+  try { const status = await callDaemon(paths.dir, "daemon.status", {}, 1000); if (!sameConfig(status, config)) throw new DaemonError("daemon_config_mismatch", "a daemon is already running with different configuration"); return { ...status, already_running: true }; } catch (error) { if (!["daemon_not_running","daemon_timeout"].includes(error.code)) throw error; }
+  assertDaemonRestartable(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 Antigravity daemon died with an active or unproven tree");
+  await removeSocket(paths); await prepare(paths, config);
+  const version = (await runAgy(config.bin, ["--version"], { cwd: config.cwd, env: sanitizedEnv(config), timeoutMs: AGY_VERSION_TIMEOUT_MS })).stdout.trim();
+  const resourceProcess = await registerDaemonProcess(config, { kind: "agy-daemon", owner: `agy:${path.basename(paths.dir)}`, operation: `agy-daemon:${path.basename(paths.dir)}`, stdout: paths.log, stderr: paths.log });
+  const retained = retainedAgyState(previous, config.resumeSessionId);
+  await writeJson(paths.state, { schema_id: STATE_SCHEMA, daemon_id: config.daemonId, shutdown_state: "starting", active_tree: false, unclaimed_activity: retained.unclaimed_activity ?? false, retained_tree_settlement: retained.retained_tree_settlement ?? null, versions: { agy: version }, config, sessions: [], session_observations: retained.session_observations ?? [], descendants: retained.descendants ?? [], native_resources_entries: retained.native_resources_entries ?? [], native_topology_error: retained.native_topology_error ?? null, ...(Array.isArray(retained.tool_observations) ? { tool_observations: retained.tool_observations } : {}), tool_observation_gaps: retained.tool_observation_gaps ?? [], tool_calls: retained.tool_calls ?? [], completed_tool_steps: retained.completed_tool_steps ?? [], tool_identity_complete: retained.tool_identity_complete !== false, turn_generation: retained.turn_generation ?? 0, last_result: retained.last_result ?? null, resource_process: resourceProcess });
+  const log = await open(paths.log, "a", 0o600), child = spawn(process.execPath, [config.entryPath, "daemon", "serve", "--state-dir", paths.dir], { cwd: config.cwd, env: sanitizedEnv(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, config.daemonId); while (!startupClock.sample(await startupProgress())) { await new Promise(resolve => setTimeout(resolve, 100));
+      const persisted = await readState(paths.dir);
+      if (persisted?.shutdown_state === "failed") {
+        const failure = persisted.startup_error ?? {};
+        throw new DaemonError(failure.code ?? "daemon_start_failed", failure.message ?? "Antigravity daemon failed before becoming ready", failure.retryable === true, failure.details);
+      }
+      try { const status = await callDaemon(paths.dir, "daemon.status", {}, 1000); if (status.provider_ready) return status; } catch (error) { if (!["daemon_not_running","daemon_timeout"].includes(error.code)) throw error; }
+    }
+    throw Object.assign(new DaemonError("daemon_start_failed", "Antigravity daemon did not become ready", true), { details: observationDetails(startupClock, 'daemon-start', child.pid) });
+  } catch (error) {
+    await cleanupFailedDaemonStart(config, resourceProcess, child, error, () => readState(paths.dir), config.daemonId);
+    throw error;
+  }
+}
+export const stopDaemon = async 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) { this.paths = paths; this.state = state; this.config = state.config; this.child = null; this.providerProcess = state.provider_process ?? null; this.providerFinalization = Promise.resolve(); this.buffer = ""; this.init = null; this.readyPromise = null; this.active = null; this.exited = false; this.toolObservations = new ToolObservations(); for (const reason of state.tool_observation_gaps ?? []) this.toolObservations.gaps.add(reason); for (const event of state.tool_observations ?? []) this.toolObservations.add(event); if (state.tool_calls?.length && !state.tool_observations) this.toolObservations.gaps.add("legacy_tools_not_attributed"); this.turnGeneration = state.turn_generation ?? 0; this.descendants = new Map((state.descendants ?? []).map(child => [child.provider_session_id, child])); this.lastResult = state.last_result ?? null; this.sessionObservations = new Map(state.session_observations ?? []); this.startupError = null; this.persisting = Promise.resolve(); this.draining = Promise.resolve(); this.lastActivityAt = state.last_activity_at ?? null; this.usageIngest = null; this.lastProviderEvent = null;
+    const saved = state.native_observation_episode;
+    if (saved?.clock) {
+      this.observationEpisode = { operationId: saved.operation_id, generation: saved.turn_generation, connectionId: saved.connection_id, terminalMetadata: state.last_terminal_metadata,
+        clock: new ObservationClock({ timeoutMs: saved.clock.timeout_ms, saved: saved.clock }) };
+      this.connectionId = saved.connection_id;
+    }
+  }
+  persist(patch = {}) { Object.assign(this.state, patch, { native_observation_episode: this.episodeSnapshot(), pid: process.pid, updated_at: new Date().toISOString(), last_activity_at: this.lastActivityAt, session_observations: [...this.sessionObservations], tool_observations: [...this.toolObservations.calls.values(), ...this.toolObservations.sources.values()], tool_observation_gaps: [...this.toolObservations.gaps], turn_generation: this.turnGeneration, descendants: [...this.descendants.values()], sessions: this.init ? [{ provider_session_id: this.init.conversation_id, root_provider_session_id: this.init.conversation_id, cwd: this.config.cwd }] : [] }); const snapshot = structuredClone(this.state); const queued = performance.now(); this.persisting = this.persisting.catch(() => {}).then(async () => { const started = performance.now(); await writeJson(this.paths.state, snapshot); this.persistTiming = { queue_ms: Math.round(started - queued), write_ms: Math.round(performance.now() - started) }; }); return this.persisting; }
+  async journal(kind, payload = {}, reservedPosition = null) { const position = reservedPosition ?? (this.journalPosition = (this.journalPosition ?? 0) + 1); const line = `${JSON.stringify({ schema_id: "dd-agy/daemon-event@1", event_id: randomUUID(), position, observed_at: new Date().toISOString(), kind, ...payload })}\n`; for (const journal of new Set([this.paths.journal, this.config.journal].filter(Boolean))) { await mkdir(path.dirname(journal), { recursive: true, mode: 0o700 }); await appendFile(journal, line, { mode: 0o600 }); } return position; }
+  args(sessionId) { return ["--input-format", "stream-json", "--output-format", "stream-json", ...agyModelArgs(this.config.model, this.config.reasoning), "--mode", this.config.mode, "--dangerously-skip-permissions", "--print-timeout", "0", ...(this.nativeLogFile ? ['--log-file', this.nativeLogFile] : []), ...(this.nativeCsrfToken ? [`--csrf_token=${this.nativeCsrfToken}`] : []), `--gemini_dir=${this.paths.gemini}`, "--app_data_dir=runtime", ...(sessionId ? ["--conversation", sessionId] : ["--new-project"])]; }
+  requireSessionIdentity(requestedId) {
+    const observedId = this.init?.conversation_id ?? null;
+    if (!requestedId || requestedId === observedId) return observedId;
+    throw new DaemonError("session_identity_mismatch", "requested Antigravity Session is not owned by this daemon", false, {
+      harness: "antigravity-cli", expected_session_id: requestedId, observed_session_id: observedId
+    });
+  }
+  markActivity() { const current = this.active ?? this.observationEpisode; this.nativeRevision = (this.nativeRevision ?? 0) + 1; this.state.native_execution_revision = this.nativeRevision; this.nativeProof = null; this.nativeAbort?.abort(); this.lastActivityAt = new Date().toISOString(); this.progress = { cursor: (this.progress?.cursor ?? 0) + 1, observed_at: Date.now() }; current?.clock?.sample(this.progress); void current?.publishProgress?.('native_progress', { session_id: this.init?.conversation_id, observed_at: this.lastActivityAt }).catch(error => { if(this.active === current) current.reject(error); }); }
+  markTerminalActivity(result) {
+    const current = this.active;
+    if (!current) return;
+    const key = createHash("sha256").update(JSON.stringify({ conversation_id: result.conversation_id ?? this.init?.conversation_id, status: result.status, num_turns: result.num_turns, error: result.error, response: result.response ?? result.text })).digest("hex");
+    current.terminalProgress ??= new Set();
+    if (current.terminalProgress.has(key)) return;
+    current.terminalProgress.add(key); this.markActivity();
+  }
+  observeProviderActivity(event) {
+    const owner = this.active ?? this.observationEpisode;
+    if (!owner || owner.connectionId !== this.connectionId || owner.generation !== this.turnGeneration) return;
+    const root = this.init?.conversation_id, step = event.step_update;
+    const id = step?.conversation_id ?? event.result?.conversation_id ?? root;
+    let parent = id; const seen = new Set();
+    while (parent && parent !== root && !seen.has(parent)) { seen.add(parent); const child = this.descendants.get(parent); if (child?.activity_generation !== owner.generation) return; parent = child.parent_provider_session_id; }
+    if (!root || parent !== root) return;
+    if (event.event === "result") { if (["SUCCESS", "ERROR", "CANCELLED"].includes(event.result?.status)) this.markTerminalActivity(event.result); return; }
+    if (event.event !== "step_update") return;
+    const index = step?.step_index ?? (/^\d+$/.test(step?.step_id ?? "") ? Number(step.step_id) : null);
+    if (!Number.isInteger(index)) return;
+    const floor = this.sessionObservations.get(id)?.step_floor;
+    if (floor != null && index <= floor) return;
+    const tool = step.tool_call ?? step.tool_info ?? (step.step_type === "tool" ? step.tool_name : null);
+    if (!step.content && !step.text && !step.thought && !tool && !step.error && !(step.subagent_info?.subagents?.length)) return;
+    const fingerprint = createHash("sha256").update(JSON.stringify({ content: step.content, text: step.text, thought: step.thought, tool_call: step.tool_call, tool_info: step.tool_info, tool_name: step.tool_name, ...(tool ? { state: step.state, status: step.status } : {}), error: step.error, subagent_info: step.subagent_info })).digest("hex");
+    this.progressSteps ??= new Map(); const prior = this.progressSteps.get(id);
+    if (prior && index < prior.index) return;
+    const snapshots = prior?.index === index ? prior.seen : new Set();
+    if (snapshots.has(fingerprint)) return;
+    // Native step snapshots can alternate/replay; scope retained dedup to the
+    // current step. Unique later updates remain useful activity at any size.
+    snapshots.add(fingerprint); this.progressSteps.set(id, { index, seen: snapshots }); this.invalidateSettlement(id); this.markActivity();
+  }
+  async start(sessionId = null) {
+    if (this.drainingError) throw this.drainingError;
+    assertDaemonDispatch(this.paths?.dir);
+    if (this.child && !this.exited) {
+      await this.readyPromise;
+      this.requireSessionIdentity(sessionId);
+      return this.init;
+    }
+    await this.providerFinalization;
+    if (this.drainingError) throw this.drainingError;
+    assertDaemonDispatch(this.paths?.dir);
+    this.nativeAbort?.abort(); this.nativeProof = null;
+    this.nativeLogFile = path.join(this.paths.dir, `native-${randomUUID()}.log`);
+    this.nativeCsrfToken = randomUUID();
+    this.admissionClock = null;
+    this.nativeQualification = await readAgyNativeQualification(this.paths.dir, this.config.bin, this.config.nativeQualificationPath);
+    const target = executable(this.config.bin, this.args(sessionId)); this.exited = false; this.buffer = ""; this.init = null;
+    let readyResolve, readyReject; this.readyPromise = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+    // The provider can reject before durable registration finishes.  Keep a
+    // handler attached during that small window; `start()` still returns the
+    // original rejection below.
+    void this.readyPromise.catch(() => {});
+    this.providerProcess = await registerDaemonProcess(this.config, { kind: "agy-provider", owner: `agy:${path.basename(this.paths.dir)}`, operation: `agy-provider:${path.basename(this.paths.dir)}`, stdout: this.paths.log, stderr: this.paths.log });
+    const providerProcess = this.providerProcess;
+    try { await this.persist({ provider_process: providerProcess }); }
+    catch (error) { await cleanupFailedStart(this.config, providerProcess, null, error); throw error; }
+    try { assertDaemonDispatch(this.paths?.dir); this.connectionId = randomUUID(); this.child = spawn(target.command, target.args, { cwd: this.config.cwd, env: sanitizedEnv(this.config), detached: true, stdio: ["pipe", "pipe", "pipe"] }); }
+    catch (error) { await cleanupFailedStart(this.config, providerProcess, null, error); throw error; }
+    const providerChild = this.child;
+    this.nativeLaunch = { logFile: this.nativeLogFile, providerPid: providerChild.pid, providerBirth: (await processSnapshot()).find(item => item.pid === providerChild.pid)?.started, connectionId: this.connectionId };
+    let allowProviderFinalization;
+    const providerRegistered = new Promise(resolve => { allowProviderFinalization = resolve; });
+    const observationFailure = error => { this.drainingError ??= error; readyReject(error); this.active?.reject(error); };
+    this.nativeDrain = readNativeLines(this.child.stdout, line => { this.buffer = `${line}\n`; return this.draining = this.drain(readyResolve, readyReject); }, observationFailure);
+    const diagnosticConnection = this.connectionId;
+    this.diagnostics = readNativeLines(this.child.stderr, async line => {
+      const diagnostic = agyErrorDiagnostic(line);
+      if (diagnostic) await this.journal("provider_error_diagnostic", { ...diagnostic, connection_id: diagnosticConnection });
+      else if (!/^AGY_ERROR\s*[: ]/.test(line)) await this.journal("stderr", { text: line });
+    }, observationFailure);
+    this.child.on("error", error => { readyReject(error); if (this.active) { this.active.reject(error); this.active = null; } });
+    // A dead leader is not yet a finalized tree: stop must also join the
+    // pending drain, process-group check and final persistence/lease writes.
+    this.providerFinalization = new Promise((resolve, reject) => {
+      this.child.on("close", (code, signal) => {
+        void Promise.all([this.nativeDrain, this.diagnostics]).then(async () => {
+          const interrupted = Boolean(this.active); this.exited = true; const beforeInit = !this.init;
+          const error = this.startupError ?? new DaemonError(beforeInit ? "agy_init_missing" : "agy_terminal_result_missing", `Antigravity exited ${beforeInit ? "before init" : "before result"} (${code ?? signal})`);
+          if (beforeInit) readyReject(error);
+          if (this.active) { this.active.reject(error); this.active = null; }
+          const patch = beforeInit ? { shutdown_state: "failed", startup_error: errorPayload(error), provider_exit: { code, signal }, active_tree: false } : { provider_exit: { code, signal }, active_tree: interrupted };
+          await providerRegistered;
+          this.retryProviderFinalization = async (graceMs = 1_000) => {
+            try {
+              await stopProcessGroup(providerChild, graceMs);
+              await this.persist(patch);
+              await finishDaemonProcess(this.config, providerProcess, beforeInit || interrupted ? "failed" : "stopped", beforeInit || interrupted ? "provider_interrupted" : "provider_stopped");
+              this.retryProviderFinalization = null;
+            } catch (cleanup) { await this.persist({ shutdown_state: "cleanup_failed", active_tree: true, cleanup_error: errorPayload(cleanup) }); throw cleanup; }
+            finally { if (beforeInit) this.server?.close(); }
+          };
+          await this.retryProviderFinalization();
+        }).then(resolve, reject);
+      });
+    });
+    void this.providerFinalization.catch(() => {});
+    try { await confirmDaemonProcess(this.config, providerProcess, this.child); await this.persist({ provider_pid: this.child.pid }); scheduleDaemonProcessHeartbeat(this.config, providerProcess); }
+    catch (error) { await cleanupFailedStart(this.config, providerProcess, this.child, error); throw error; }
+    finally { allowProviderFinalization(); }
+    let readyTimer;
+    try { return await Promise.race([this.readyPromise, new Promise((_, reject) => { readyTimer = observedTimeout(() => reject(new DaemonError("agy_init_timeout", "Antigravity init timed out", true)), SETUP_STARTUP_MS, { progress: () => this.lastActivityAt }); })]); }
+    finally { clearTimeout(readyTimer); }
+  }
+  async drain(readyResolve, readyReject) { let index; while ((index = this.buffer.indexOf("\n")) >= 0) { const line = this.buffer.slice(0, index).trim(); this.buffer = this.buffer.slice(index + 1); if (!line) continue; let event; try { event = JSON.parse(line); } catch { await this.journal("invalid_json", { line: line.slice(0, 1000) }); continue; }
+    // Record an early provider rejection before journalling: a short-lived
+    // child can close while the asynchronous write is still pending.
+    if (event.event === "result" && ["ERROR", "CANCELLED"].includes(event.result?.status)) {
+      this.lastTerminalFailure ??= this.state.last_terminal_failure;
+      event.terminal_metadata = { observed_at: new Date().toISOString(), provider_session_id: event.result.conversation_id || this.init?.conversation_id || null,
+        operation_id: this.active?.operationId ?? null, turn_generation: this.active?.generation ?? null, journal_locator: this.paths.journal, native_source: "agy.result" };
+      if (!this.init) this.startupError ??= agyTerminalFailure(event.result, event.terminal_metadata);
+      this.receivedTerminalMetadata = event.terminal_metadata;
+    }
+    this.observeProviderActivity(event);
+    if (event.event === "result" && this.init && !this.startupError) { await this.finishTurn(event.result ?? {}, event.terminal_metadata, event); continue; }
+    await this.journal("provider_event", { event }); if (event.event === "init") { this.init = { conversation_id: event.conversation_id, ...(event.init ?? {}) }; if (!this.init.conversation_id) throw new DaemonError("agy_init_missing", "Antigravity init has no conversation ID"); const requested = { provider: this.config.provider, model: this.config.model, reasoning: this.config.reasoning, mode: this.config.mode, permission_mode: "always-proceed" }; this.profile = assertProfile(requested, observedProfile(this.init, requested)); await observeModel({ journal: this.config.journal, harness: "antigravity-cli", sessionId: this.init.conversation_id, requested, observed: this.profile.observed, source: "native.init" }); await this.persist({ shutdown_state: "running", active_tree: false }); readyResolve(this.init); } else if (event.event === "step_update") this.observeStep(event.step_update ?? {}); else if (event.event === "result") {
+      // A successfully read/journalled provider refusal rejects readiness, not
+      // the stream drain that physical cleanup must still join.
+      if (this.startupError) { readyReject(this.startupError); continue; }
+      await this.finishTurn(event.result ?? {});
+    } } }
+  observeStep(step) {
+    const sessionId = step.conversation_id ?? this.init?.conversation_id, observation = this.sessionObservations.get(sessionId) ?? {};
+    const fresh = Number.isInteger(step.step_index) && step.step_index > (observation.last_step_index ?? -1) && step.step_index > (observation.step_floor ?? -1);
+    const bound = sessionId === this.init?.conversation_id || this.descendants.get(sessionId)?.activity_generation === this.active?.generation;
+    // Tree liveness is broader than current-Turn model progress: fresh work
+    // from a retained child invalidates settlement without adopting this Turn.
+    if (fresh && (sessionId === this.init?.conversation_id || this.descendants.has(sessionId))) this.childActivity(sessionId);
+    if (Number.isInteger(step.step_index)) this.sessionObservations.set(sessionId, { ...this.sessionObservations.get(sessionId), ...(step.step_index > (observation.last_step_index ?? -1) ? { last_execution_num: null } : {}), last_step_index: Math.max(observation.last_step_index ?? -1, step.step_index) });
+    this.toolObservations.add(agyToolObservation(step, this.init?.conversation_id));
+    for (const child of step.subagent_info?.subagents ?? []) if (child.conversation_id) {
+      const prior = this.descendants.get(child.conversation_id);
+      if (child.conversation_id === this.init?.conversation_id || prior && prior.parent_provider_session_id !== sessionId) {
+        this.state.native_topology_error = 'agy_native_ancestry_contradiction'; this.invalidateSettlement(sessionId); continue;
+      }
+      this.descendants.set(child.conversation_id, { ...prior, provider_session_id: child.conversation_id, parent_provider_session_id: sessionId ?? null, role: child.role ?? null, subagent_type: child.type_name ?? null, log_uri: child.log_uri ?? null, workspace_uris: child.workspace_uris ?? [], status: prior?.status ?? "unknown",
+        ...(bound && Number.isInteger(step.step_index) ? { native_source: { kind: 'agy.step_update.subagent_info', parent_provider_session_id: sessionId, step_index: step.step_index } } : {}),
+        ...(fresh && bound && this.active ? { activity_generation: this.active.generation } : {}) });
+    }
+  }
+  toolSnapshot() { const summary = this.toolObservations.summary(); const failures_by_name = {}; for (const event of this.toolObservations.calls.values()) if (event.status === "failed") failures_by_name[event.name] = (failures_by_name[event.name] ?? 0) + 1; return { ...summary, by_name: summary.by_tool, failures_by_name }; }
+  async captureChildTools(onProgress = null) {
+    this.capturedToolFacts ??= new Map();
+    this.nativeResources ??= new Map(this.state.native_resources_entries?.map(item => [item.resource_id, item]) ?? []);
+    const root = this.init?.conversation_id ?? this.state.sessions?.[0]?.provider_session_id ?? this.lastResult?.conversation_id;
+    const queue = root && this.paths.runtime ? [{ provider_session_id: root, parent_provider_session_id: root, log_uri: pathToFileURL(path.join(this.paths.runtime, 'brain', root, '.system_generated', 'logs', 'transcript.jsonl')).href }, ...this.descendants.values()] : [...this.descendants.values()];
+    const visited = new Set();
+    for (let index = 0; index < queue.length && index < 256; index++) {
+      const child = queue[index];
+      if (visited.has(child.provider_session_id)) continue;
+      visited.add(child.provider_session_id);
+      const ancestors = new Set(); let parent = child.parent_provider_session_id;
+      while (parent && parent !== root && this.descendants.has(parent) && !ancestors.has(parent)) {
+        ancestors.add(parent); parent = this.descendants.get(parent).parent_provider_session_id;
+      }
+      const events = parent === root && root
+        ? await captureAgyTranscript(this.paths.runtime, child, root, [root, ...ancestors], source => {
+          const reducer = createAgyTranscriptFacts(source, child.provider_session_id);
+          return { add: reducer.add, finish: () => {
+          const facts = reducer.finish();
+          for (const resource of facts.resources) {
+            const prior = this.nativeResources.get(resource.resource_id);
+            this.nativeResources.set(resource.resource_id, { ...mergeAgyResource(prior, resource),
+              owner_daemon_id: prior?.owner_daemon_id ?? this.config.daemonId });
+          }
+          if (facts.gap) { this.state.native_topology_error = facts.gap; this.invalidateSettlement(root); }
+          for (const discovered of facts.children) {
+            const expected = path.join(this.paths.runtime, 'brain', discovered.provider_session_id, '.system_generated', 'logs', 'transcript.jsonl');
+            const sourceBrain = path.resolve(path.dirname(fileURLToPath(source.locator)), '../../..');
+            const sibling = path.join(sourceBrain, discovered.provider_session_id, '.system_generated', 'logs', 'transcript.jsonl');
+            let locator;
+            try { locator = fileURLToPath(discovered.log_uri); } catch { locator = null; }
+            if (locator !== expected && locator !== sibling) { this.state.native_topology_error = 'agy_native_locator_unbound'; this.invalidateSettlement(root); continue; }
+            const prior = this.descendants.get(discovered.provider_session_id);
+            if (discovered.provider_session_id === root || prior && (prior.parent_provider_session_id !== discovered.parent_provider_session_id || prior.log_uri && prior.log_uri !== discovered.log_uri)) {
+              this.state.native_topology_error = 'agy_native_ancestry_contradiction'; this.invalidateSettlement(root); continue;
+            }
+            const value = { ...discovered, ...prior, native_source: discovered.native_source };
+            this.descendants.set(value.provider_session_id, value);
+            queue.push(value);
+          }
+          } };
+        }, onProgress && (cursor => onProgress(`${child.provider_session_id}:${cursor}`)))
+        : [{ session: { harness_id: "antigravity-cli", session_id: child.provider_session_id }, reason: "agy_transcript_ancestry_unproven" }];
+      for (const event of events) {
+        this.toolObservations.add(event);
+        const key = JSON.stringify([event.session, event.call_id, event.reason]), encoded = JSON.stringify(event);
+        if (this.capturedToolFacts.get(key) === encoded) continue;
+        await this.journal("tool_observation", { schema_id: "dd-flow/tool-observation@1", event });
+        this.capturedToolFacts.set(key, encoded);
+      }
+    }
+    if (queue.length > 256 && visited.size < new Set(queue.map(item => item.provider_session_id)).size) { this.state.native_topology_error = 'agy_native_inventory_limit'; this.invalidateSettlement(root); }
+    this.state.native_resources_entries = [...this.nativeResources.values()];
+  }
+  async finishTurn(result, retainedMetadata = null, providerEvent = null) {
+    if (result.status === "RUNNING") { await this.persist({ active_tree: true }); return; }
+    if (!["SUCCESS", "ERROR", "CANCELLED"].includes(result.status)) throw new DaemonError("agy_terminal_result_invalid", "Antigravity result has no recognized terminal status", false, { provider_result: result });
+    if (result.conversation_id && result.conversation_id !== this.init?.conversation_id) {
+      await this.journal("foreign_terminal_observed", { conversation_id: result.conversation_id, result });
+      const child = this.descendants.get(result.conversation_id);
+      if (child) {
+        this.descendants.set(result.conversation_id, { ...child, status: result.status === "SUCCESS" ? "completed" : result.status === "ERROR" ? "failed" : "cancelled" });
+        await this.completePendingTurn();
+      }
+      return;
+    }
+    const current = this.active;
+    if (current?.dispatched === false) {
+      const error = new DaemonError("operation_observation_lost", "Unexpected native terminal before this stream request was dispatched", false, { operation_id: current.operationId, turn_generation: current.generation, native_outcome: "unknown" });
+      this.active = null; current.reject(error);
+      await this.journal("unexpected_terminal_before_dispatch", { result, operation_id: current.operationId });
+      await this.persist({ unclaimed_activity: true, active_tree: true });
+      return;
+    }
+    const terminalMetadata = { received_at: new Date().toISOString(), ...(retainedMetadata ?? this.receivedTerminalMetadata ?? { observed_at: new Date().toISOString(), provider_session_id: result.conversation_id || this.init?.conversation_id || null, operation_id: current?.operationId ?? null,
+        turn_generation: current?.generation ?? null, journal_locator: this.paths.journal, native_source: "agy.result" }) };
+    this.receivedTerminalMetadata = null;
+    // The ordered stream returns one result per input. Model usage counters
+    // are not request IDs: native command rejections can report zero turns.
+    // prompt() drains earlier events before accepting another input.
+    if (!current && this.lastResult) {
+      await this.journal("stale_terminal_observed", { result });
+      if (!isDeepStrictEqual(result, this.lastResult)) await this.persist({ unclaimed_activity: true, active_tree: true });
+      return;
+    }
+    this.lastResult = result; this.markTerminalActivity(result);
+    if (current) { current.terminalResult = result; current.terminalMetadata = terminalMetadata; current.terminalPersisted = false; }
+    this.state.terminal_observation_pending = true;
+    try {
+      await this.persist({ active_tree: true, last_result: result, last_terminal_metadata: terminalMetadata });
+      if (current) current.terminalPersisted = true;
+      const terminalPosition = await this.journal("provider_event", { event: providerEvent ?? { event: "result", result } });
+      terminalMetadata.stream_terminal_position = terminalPosition;
+      if (current?.outboundPosition && current.dispatchJournalSettled && !current.dispatchObservationError && this.config.daemonId && current.connectionId && current.operationId) terminalMetadata.request_proof = {
+        kind: "stream_request", daemon_instance: this.config.daemonId, connection_id: current.connectionId, operation_id: current.operationId,
+        turn_generation: current.generation, session_id: this.init.conversation_id, outbound_position: current.outboundPosition, terminal_position: terminalPosition
+      };
+      await this.captureChildTools();
+    } catch (error) { return this.failTerminalObservation(current, result, terminalMetadata, error); }
+    try { this.usageIngest = await forwardUsage(this.config, result.conversation_id ?? this.init.conversation_id, result, this.toolSnapshot(), [...this.descendants.values()]); }
+    catch (error) { this.usageIngest = { status: "failed", error: error.message ?? String(error) }; try { await this.journal("usage_ingest_failed", this.usageIngest); } catch (storage) { return this.failTerminalObservation(current, result, terminalMetadata, storage); } }
+    try { await this.persist({ terminal_observation_pending: false }); }
+    catch (error) { this.state.terminal_observation_pending = true; return this.failTerminalObservation(current, result, terminalMetadata, error); }
+    this.state.terminal_observation_pending = false;
+    this.queueNativeInspection();
+    if (!current) return;
+    if (this.active !== current) return;
+    if (result.status === "ERROR" || result.status === "CANCELLED") {
+      await this.observeHookFailures();
+      if (this.active !== current) return;
+      this.active = null;
+      const settled = this.receipt().settled;
+      this.lastTerminalFailure = agyTerminalFailure(result, { ...terminalMetadata, native_turn_items: { observed: settled, possible_effects: true, pending: !settled }, provider_error_scope: "terminal_result", usage_ingest: this.usageIngest });
+      try { await this.persist({ active_tree: !settled, last_terminal_failure: errorRecord(this.lastTerminalFailure) }); }
+      catch (error) { return this.failTerminalObservation(current, result, terminalMetadata, error); }
+      return current.reject(this.lastTerminalFailure);
+    }
+    try { await this.completePendingTurn(); }
+    catch (error) { return this.failTerminalObservation(current, result, terminalMetadata, error); }
+  }
+  async completePendingTurn() {
+    await this.observeHookFailures();
+    const current = this.active;
+    if (current?.observationError) throw current.observationError;
+    if (current?.terminalResult?.status !== "SUCCESS" || current.terminalResult !== this.lastResult) return;
+    this.queueNativeInspection();
+    await this.persist({ active_tree: !this.receipt().settled });
+    // Hooks can invalidate the tree while persistence is pending. Never
+    // publish a proof captured before that asynchronous boundary.
+    if (this.active !== current) return;
+    const receipt = this.receipt();
+    if (!receipt.settled) { await this.persist({ active_tree: true }); return; }
+    this.active = null;
+    current.resolve(receipt);
+  }
+  reconcilePendingHook(current) {
+    if (!current || this.active !== current) return Promise.resolve();
+    if (current.hookReconciliation) return current.hookReconciliation;
+    if (!current.pendingHookReconciliation) return Promise.resolve();
+    current.pendingHookReconciliation = false;
+    current.hookReconciliation = this.completePendingTurn().catch(error => {
+      current.observationError ??= error;
+      if (this.active === current) { this.drainingError ??= error; current.reject(error); }
+    }).finally(() => { current.hookReconciliation = null; });
+    return current.hookReconciliation;
+  }
+  failTerminalObservation(current, result, metadata, cause) {
+    this.state.terminal_observation_pending = true;
+    const details = { ...metadata, native_outcome: result, settled: false, terminal_persisted: current?.terminalPersisted === true, observation_error: errorRecord(cause), native_turn_items: { observed: false, possible_effects: true, pending: true } };
+    const error = ["ERROR", "CANCELLED"].includes(result.status)
+      ? agyTerminalFailure(result, details)
+      : new DaemonError("native_outcome_observation_failed", "Antigravity terminal was received but mandatory observation failed", false, details);
+    error.cause = cause;
+    if (result.status !== "SUCCESS") this.lastTerminalFailure = error;
+    if (current) { current.observationError = error; current.reject(error); }
+    throw error;
+  }
+  queueNativeInspection() {
+    const owner = this.active ?? this.observationEpisode, proof = owner?.terminalMetadata?.request_proof;
+    if (!owner?.clock || !proof || this.state.terminal_observation_pending || this.nativeFlight || this.nativeProof || this.exited) return;
+    if (proof.connection_id !== this.connectionId || proof.daemon_instance !== this.config.daemonId || proof.turn_generation !== this.turnGeneration || proof.operation_id !== owner.operationId || proof.session_id !== this.init?.conversation_id) { this.nativeInspection = { state: 'unproven', reason: 'native_owner_binding_changed' }; return; }
+    if (owner.clock.sample(this.progress)) { this.nativeInspection = { state: 'unproven', reason: 'observation_budget_exhausted' }; return; }
+    // The observer's raw wire result is never authority before P3 qualification.
+    if (!this.nativeObserver && !this.nativeQualification?.qualified) { this.nativeInspection = { state: 'unproven', reason: 'native_inspection_not_qualified' }; return; }
+    const revision = this.nativeRevision ?? 0, connection = this.connectionId;
+    const controller = this.nativeAbort = new AbortController();
+    let recording = false;
+    this.nativeInspection = { state: 'inspection_pending', reason: 'native_idle_barrier_pending' };
+    this.nativeFlight = Promise.resolve().then(async () => {
+      await owner.dispatchJournal;
+      const clock = owner.clock.state(), remainingMs = Math.max(0, clock.timeout_ms - clock.elapsed_ms);
+      if (!remainingMs || owner.clock.sample(this.progress)) throw new Error('observation_budget_exhausted');
+      const endpoint = this.nativeObserver ? null : await ownedAgyEndpoint(this.nativeLaunch);
+      const observed = await (this.nativeObserver ?? inspectAgyNative)({ endpoint, sessionId: proof.session_id, cwd: this.config.cwd, remainingMs, signal: controller.signal, rootRelation: this.nativeQualification?.rootRelation, csrfToken: this.nativeCsrfToken });
+      if (!this.nativeObserver && JSON.stringify(await ownedAgyEndpoint(this.nativeLaunch)) !== JSON.stringify(endpoint)) throw new Error('native_endpoint_changed');
+      const current = () => !controller.signal.aborted && this.connectionId === connection && (this.nativeRevision ?? 0) === revision && this.turnGeneration === owner.generation && this.observationEpisode === owner && !this.exited && !owner.clock.sample(this.progress);
+      if (!current()) return;
+      if (!observed.idle) { this.nativeInspection = { state: 'inspection_pending', reason: observed.reason ?? 'native_wait_pending' }; return; }
+      const candidate = { daemon_instance: this.config.daemonId, connection_id: connection, operation_id: owner.operationId, turn_generation: owner.generation, request_proof: proof, revision, method: observed.method, source: 'native_idle_barrier' };
+      recording = true;
+      await this.journal('native_tree_settlement', { proof: candidate });
+      if (!current()) return;
+      // Persist conservatively before publishing. A crash may require another
+      // read-only observation; no concurrent reader gets an uncommitted grant.
+      await this.persist({ active_tree: true });
+      if (!current()) return;
+      this.nativeProof = candidate;
+      this.state.native_execution_revision = revision;
+      this.state.unclaimed_activity = false;
+      this.projectNativeIdleChildren();
+      this.nativeInspection = { state: 'ready', reason: 'native_wait_fully_idle' };
+      this.state.active_tree = !this.receipt().settled;
+      await this.completePendingTurn();
+    }).catch(error => {
+      if (!controller.signal.aborted) {
+        this.nativeProof = null;
+        const transient = !recording && ['grpc_4', 'grpc_14'].includes(error.details?.reason) && !owner.clock.sample(this.progress);
+        this.nativeInspection = { state: transient ? 'inspection_pending' : 'unproven', reason: error.details?.reason ?? error.message ?? 'native_inspection_failed' };
+        if (recording && this.active === owner && owner.terminalResult) {
+          try { this.failTerminalObservation(owner, owner.terminalResult, owner.terminalMetadata, error); } catch { /* original prompt owns the typed failure */ }
+        }
+        if (recording) this.state.terminal_observation_pending = true;
+      }
+    })
+      .finally(() => { this.nativeFlight = null; });
+  }
+  projectNativeIdleChildren() {
+    for (const [id, child] of this.descendants) this.descendants.set(id, { ...child, ...(!['completed', 'failed', 'cancelled'].includes(child.status) ? { previous_native_status: child.status, status: 'settled_by_root' } : {}), ...(child.native_turn_items ? { native_turn_items: { ...child.native_turn_items, observed: true, pending: false } } : {}), tree_settled: true, settlement_evidence: 'native_idle_barrier' });
+  }
+  async reconcileRetainedAdmission() {
+    const retained = this.state.retained_tree_settlement;
+    const fresh = !this.lastResult;
+    if (this.active || this.receipt().settled || !fresh && (retained?.evidence !== 'verified_clean_daemon_shutdown' || retained.session_id !== this.init?.conversation_id)) return;
+    if (!this.nativeObserver && !this.nativeQualification?.qualified) return;
+    if (this.admissionFlight) return await this.admissionFlight;
+    const clock = this.admissionClock ??= new ObservationClock({ timeoutMs: SETUP_STARTUP_MS });
+    if (!clock || clock.sample()) throw new DaemonError('agy_native_inspection_unavailable', 'Retained AGY native admission budget exhausted');
+    const connection = this.connectionId, revision = this.nativeRevision ?? 0, generation = this.turnGeneration;
+    const controller = this.nativeAbort = new AbortController();
+    this.admissionFlight = (async () => {
+      const endpoint = this.nativeObserver ? null : await ownedAgyEndpoint(this.nativeLaunch);
+      const observed = await (this.nativeObserver ?? inspectAgyNative)({ endpoint, sessionId: this.init.conversation_id, cwd: this.config.cwd, remainingMs: Math.max(1, clock.timeoutMs - clock.elapsed), signal: controller.signal, rootRelation: this.nativeQualification?.rootRelation, csrfToken: this.nativeCsrfToken });
+      if (!this.nativeObserver && JSON.stringify(await ownedAgyEndpoint(this.nativeLaunch)) !== JSON.stringify(endpoint)) throw new DaemonError('agy_native_inspection_unavailable', 'AGY admission endpoint changed');
+      const current = () => !controller.signal.aborted && !this.exited && !this.active && !clock.sample() && this.connectionId === connection && this.turnGeneration === generation && (this.nativeRevision ?? 0) === revision;
+      if (!observed.idle || !current()) throw new DaemonError('agy_native_inspection_unavailable', 'AGY fresh native admission is unproven');
+      // Admission is not the old stream request: no invented operation/Turn or
+      // request proof. The old failed result remains historical diagnostics.
+      const candidate = { daemon_instance: this.config.daemonId, connection_id: connection, turn_generation: generation, revision, method: observed.method, source: 'native_idle_admission' };
+      await this.journal('native_idle_admission', { proof: candidate });
+      if (!current()) throw new DaemonError('agy_native_inspection_unavailable', 'AGY native admission changed during observation persistence');
+      await this.persist({ active_tree: true });
+      if (!current()) throw new DaemonError('agy_native_inspection_unavailable', 'AGY native admission changed during observation persistence');
+      this.nativeProof = candidate;
+      this.state.native_execution_revision = revision;
+      this.state.unclaimed_activity = false; this.projectNativeIdleChildren();
+      this.state.active_tree = !this.receipt().settled;
+    })().catch(error => { this.nativeProof = null; this.nativeInspection = { state: 'unproven', reason: error.details?.reason ?? error.code ?? 'native_admission_unproven' }; throw error; }).finally(() => { this.admissionFlight = null; });
+    return await this.admissionFlight;
+  }
+  episodeSnapshot() {
+    const owner = this.observationEpisode;
+    return owner?.clock ? { operation_id: owner.operationId, turn_generation: owner.generation, connection_id: owner.connectionId, clock: owner.clock.state() } : null;
+  }
+  receipt(result = this.lastResult) {
+    if (this.state.last_terminal_failure && !this.lastTerminalFailure) this.lastTerminalFailure = this.state.last_terminal_failure;
+    const metadata = this.active?.terminalResult === result ? this.active.terminalMetadata : this.state.last_result === result ? this.state.last_terminal_metadata : this.lastTerminalFailure && this.lastTerminalFailure.details?.provider_result?.error === result?.error
+      && this.lastTerminalFailure.details.provider_session_id === (result?.conversation_id || this.init?.conversation_id || null) ? this.lastTerminalFailure.details : null;
+    const terminalMetadata = metadata?.request_proof && (metadata.request_proof.connection_id !== this.connectionId || metadata.request_proof.daemon_instance !== this.config.daemonId)
+      ? { ...metadata, request_proof: undefined } : metadata;
+    const assistantText = typeof result?.response === "string" ? result.response : typeof result?.text === "string" ? result.text : null;
+    const root = this.init?.conversation_id; const observation = this.sessionObservations.get(root);
+    const treeSettled = [...this.descendants.values()].every(child => child.tree_settled === true || ["completed", "failed", "cancelled", "settled_by_root"].includes(child.status));
+    // SUCCESS can coexist with background tasks. Only a current native idle
+    // proof (or verified prior clean retirement before new activity) closes it.
+    const retained = this.state.retained_tree_settlement;
+    const rootSettled = this.nativeProof?.turn_generation === this.turnGeneration && this.nativeProof.connection_id === this.connectionId && this.nativeProof.revision === (this.nativeRevision ?? 0)
+      || retained?.evidence === "verified_clean_daemon_shutdown" && retained.session_id === root && retained.turn_generation === this.turnGeneration && !this.child;
+    const terminalPending = this.active?.terminalResult === result;
+    // A positively inspected owned scope before its first Turn has no model
+    // result to manufacture. Native admission alone proves this empty execution.
+    const emptyExecution = !result && this.turnGeneration === 0 && !this.active && !this.descendants.size && this.nativeProof?.source === 'native_idle_admission';
+    const executionTerminal = emptyExecution || result && ["SUCCESS", "ERROR", "CANCELLED"].includes(result.status);
+    const settled = Boolean(!this.state.native_topology_error && !this.state.terminal_observation_pending && !this.active?.observationError && !this.state.unclaimed_activity && (!this.active || terminalPending) && executionTerminal && treeSettled && rootSettled);
+    const clock = this.observationEpisode?.clock;
+    if (clock) clock.sample(this.progress);
+    const exhausted = clock && (clock.observationLost || clock.elapsed >= clock.timeoutMs);
+    const nativeSettlement = { confirmed: Boolean(settled), state: settled ? 'ready' : exhausted ? 'unproven' : this.nativeInspection?.state ?? 'unproven', reason: settled ? 'current_root_idle_proven' : exhausted ? 'observation_budget_exhausted' : this.nativeInspection?.reason ?? 'current_root_idle_proof_missing', capability: AGY_NATIVE_INSPECTION_CONTRACT, operation_id: terminalMetadata?.request_proof?.operation_id, request_key: streamRequestKey(terminalMetadata?.request_proof), provider_session_id: root, daemon_instance: this.config.daemonId, connection_epoch: this.connectionId, generation: this.turnGeneration, ...(this.nativeProof ? { source: this.nativeProof.source, method: this.nativeProof.method, proof_sha256: createHash('sha256').update(JSON.stringify(this.nativeProof)).digest('hex') } : {}), ...(clock ? { observation_clock: clock.state() } : {}) };
+    const hookDiagnostics = (this.state.native_hook_diagnostics ?? []).filter(item => item.turn_generation === this.turnGeneration);
+    return nativeExecutionReceipt({ harness: "antigravity-cli", runtime_family: "antigravity", provider_session_id: root ?? null, adapter_session_id: root ?? null, cwd: this.config.cwd, profile: this.profile, result, ...(terminalMetadata ? { terminal_metadata: terminalMetadata, ...(terminalMetadata.turn_id ? { terminal_turn_id: terminalMetadata.turn_id } : {}) } : {}), ...(assistantText === null ? {} : { assistant_text: assistantText }), ...(hookDiagnostics.length ? { native_hook_diagnostics: hookDiagnostics } : {}), usage: usageSnapshot(result ?? {}, this.toolSnapshot()), usage_ingest: this.usageIngest, descendants: [...this.descendants.values()], ...settledNativeTree(root, [...this.descendants.values()], settled, !this.state.unclaimed_activity && (!this.active || terminalPending) && rootSettled && ["SUCCESS", "ERROR", "CANCELLED"].includes(result?.status)), native_turn_items: { observed: Boolean(terminalMetadata?.request_proof), possible_effects: true, pending: !settled, settled, ...(terminalMetadata?.request_proof ? { request_proof: terminalMetadata.request_proof } : {}) }, transcript_path: observation?.transcript_path ?? null, settled, native_settled: settled, physical_stopped: this.exited === true, native_settlement: nativeSettlement, }, { daemonId: this.config.daemonId, generation: this.turnGeneration, revision: this.nativeRevision ?? 0, resources: { coverage: "partial", entries: [...(this.nativeResources?.values() ?? this.state.native_resources_entries ?? [])], ...(this.state.native_retirement_notifications?.length ? { pending_notifications: this.state.native_retirement_notifications } : {}) } });
+  }
+  async zeroUsage() { await forwardUsage(this.config, this.init.conversation_id, { usage: {} }, this.toolSnapshot(), []); }
+  async prompt(text, assertDispatch = captureDispatchGuard(this), operationId = null, livenessTimeoutMs = 1_800_000) {
+    validateObservationDuration(livenessTimeoutMs);
+    if (!text) throw new DaemonError("prompt_required", "prompt is required");
+    await this.start(); await this.draining;
+    if (!this.nativeObserver && !this.nativeQualification?.qualified && this.config.bin && this.paths.dir) this.nativeQualification = await readAgyNativeQualification(this.paths.dir, this.config.bin, this.config.nativeQualificationPath);
+    if (!this.nativeObserver && !this.nativeQualification?.qualified) throw new DaemonError('agy_native_inspection_unqualified', 'AGY whole-tree inspection requires a matching native qualification receipt before productive dispatch', false, { capability: AGY_NATIVE_INSPECTION_CONTRACT });
+    await this.reconcileRetainedAdmission();
+    if (this.active || this.promptObservation) throw new DaemonError("operation_in_progress", "an Antigravity turn or its mandatory dispatch observation is already running");
+    if (this.state.unclaimed_activity || ((this.state.active_tree || this.lastResult) && !this.receipt().settled)) throw new DaemonError("tree_not_settled", "the prior Antigravity agent tree is not fully settled");
+    let resolveTurn, rejectTurn;
+    const reply = new Promise((resolve, reject) => { resolveTurn = resolve; rejectTurn = reject; });
+    // Cancellation can reject while admission persistence is still pending.
+    void reply.catch(() => {});
+    this.connectionId ??= randomUUID();
+    const current = { resolve: resolveTurn, reject: rejectTurn, generation: ++this.turnGeneration, operationId, connectionId: this.connectionId, dispatched: false, guard: assertDispatch };
+    this.nativeAbort?.abort(); this.nativeProof = null; this.nativeInspection = null;
+    current.clock = new ObservationClock({ timeoutMs: livenessTimeoutMs, onGap: gap => { void this.journal('observation_gap', { gap, operation_id: operationId }).catch(() => {}); } });
+    this.observationEpisode = current;
+    let resolveDispatchJournal;
+    const dispatchJournal = current.dispatchJournal = new Promise(resolve => { resolveDispatchJournal = resolve; });
+    this.promptObservation = current;
+    const finishDispatchJournal = () => {
+      current.dispatchJournalSettled = true; resolveDispatchJournal();
+      if (current.observerReturned && this.promptObservation === current) this.promptObservation = null;
+    };
+    // Reserve before persistence so different operation IDs cannot overlap.
+    current.publishProgress = operationProgressReporter();
+    this.active = current;
+    this.lastNativeHookOperation = current;
+    // A callback's failure receipt may arrive after its Turn has returned.
+    // Keep its accepted request identity; it is an observation binding, not
+    // proof of which native Turn originally produced the callback.
+    this.hookRequests ??= new Map();
+    const root = this.init?.conversation_id, prior = this.sessionObservations.get(root) ?? {};
+    current.stepFloor = prior.last_step_index ?? -1;
+    this.sessionObservations.set(root, { ...prior, step_floor: prior.last_step_index ?? null, stop: null, last_hook: null });
+    this.lastProviderEvent = null; this.progressSteps = new Map(); this.progressHooks = new Map(); this.progress = undefined;
+    try {
+      await this.persist({ active_tree: true, last_hook_rejection: null });
+      assertDispatch();
+      assertDaemonDispatch(this.paths?.dir);
+      if (this.active !== current) throw new DaemonError("operation_cancelled", "prompt reservation was superseded");
+      current.outboundPosition = this.journalPosition = (this.journalPosition ?? 0) + 1;
+      current.dispatched = true;
+      this.child.stdin.write(`${JSON.stringify({ event: "user", message: { content: text } })}\n`, error => {
+        if (error) { this.drainingError ??= nativeObservationError(error); current.dispatchObservationError = this.drainingError; current.reject(this.drainingError); finishDispatchJournal(); }
+        else void Promise.resolve().then(() => this.journal("native_dispatch", { operation_id: operationId, provider_session_id: this.init?.conversation_id, turn_generation: current.generation, connection_id: current.connectionId }, current.outboundPosition)).then(finishDispatchJournal, cause => {
+          this.drainingError ??= nativeObservationError(cause); current.dispatchObservationError = this.drainingError;
+          current.reject(this.drainingError); finishDispatchJournal();
+        });
+      });
+    } catch (error) {
+      if (current.dispatched) { this.drainingError ??= nativeObservationError(error); error = this.drainingError; }
+      else if (this.active === current) this.active = null;
+      current.reject(error); finishDispatchJournal();
+    }
+    const clock = current.clock;
+    let checking = false;
+    const timer = setInterval(() => {
+      if (this.active === current && [...(this.hookRequests?.values() ?? [])].some(binding => binding.current && binding.current !== current)) {
+        void this.observeHookFailures().catch(() => { /* Retry the same retained request on the next observation. */ });
+      }
+      if (this.active === current && current.terminalResult && this.nativeInspection?.state === 'inspection_pending' && !this.nativeFlight) this.queueNativeInspection();
+      if (this.active === current && current.pendingHookReconciliation && !checking) {
+        checking = true;
+        void this.reconcilePendingHook(current).finally(() => { checking = false; });
+        return;
+      }
+      if (this.active !== current || checking || !clock.sample(this.progress)) return;
+      checking = true; const cursor = this.progress?.cursor;
+      void this.completePendingTurn().then(() => {
+        if (this.active !== current || this.progress?.cursor !== cursor || !clock.sample(this.progress)) return;
+        if (current.terminalResult) return this.failTerminalObservation(current, current.terminalResult, current.terminalMetadata, new Error("Native tree settlement was not confirmed within the productive silence window"));
+        current.reject(new DaemonError("operation_observation_lost", "Antigravity native outcome is unknown after the productive silence window", true, { operation_id: operationId, turn_generation: current.generation, native_outcome: "unknown", last_activity_at: this.lastActivityAt ?? null }));
+      }).catch(error => {
+        if (this.active === current && this.progress?.cursor === cursor) {
+          if (current.observationError) current.reject(current.observationError);
+          else if (current.terminalResult) { try { this.failTerminalObservation(current, current.terminalResult, current.terminalMetadata, error); } catch { /* reply owns the typed failure */ } }
+          else current.reject(new DaemonError("operation_observation_lost", "Antigravity quiet reconciliation could not confirm the native outcome", true, { operation_id: operationId, turn_generation: current.generation, native_outcome: "unknown", observation_error: errorRecord(error) }));
+        }
+      }).finally(() => { checking = false; });
+    }, Math.max(10, Math.min(1_000, livenessTimeoutMs / 4)));
+    try {
+      const result = await reply;
+      await dispatchJournal;
+      if (current.dispatchObservationError) {
+        const error = current.dispatchObservationError;
+        if (error.code !== "operation_observation_lost") throw error;
+        throw Object.assign(new Error("Antigravity completed natively but its dispatch journal could not be saved", { cause: error.cause ?? error }), {
+          code: "native_outcome_observation_failed", details: { native_outcome: result, settled: false, observation_error: errorRecord(error) }
+        });
+      }
+      return result;
+    } catch (error) {
+      await dispatchJournal;
+      if (error.code === "native_outcome_observation_failed") throw error;
+      if (current.dispatchObservationError) {
+        if (!current.terminalResult) throw current.dispatchObservationError;
+        const cause = current.dispatchObservationError;
+        const failed = current.terminalResult.status === 'SUCCESS'
+          ? new DaemonError('native_outcome_observation_failed', 'Antigravity completed natively but its dispatch journal could not be saved', false, { native_outcome: this.receipt(current.terminalResult), settled: false, observation_error: errorRecord(cause) })
+          : agyTerminalFailure(current.terminalResult, { ...current.terminalMetadata, native_outcome: current.terminalResult, settled: false, native_turn_items: { observed: false, possible_effects: true, pending: true }, observation_error: errorRecord(cause) });
+        failed.cause = cause.cause ?? cause;
+        current.observationError = failed; current.dispatchObservationError = failed;
+        this.drainingError = failed; this.state.terminal_observation_pending = true;
+        if (current.terminalResult.status !== 'SUCCESS') this.lastTerminalFailure = failed;
+        throw failed;
+      }
+      const metadata = current.terminalMetadata;
+      if (error === this.lastTerminalFailure && metadata && !metadata.request_proof && current.outboundPosition && metadata.stream_terminal_position && this.config.daemonId && current.operationId) {
+        metadata.request_proof = { kind: "stream_request", daemon_instance: this.config.daemonId, connection_id: current.connectionId, operation_id: current.operationId,
+          turn_generation: current.generation, session_id: this.init.conversation_id, outbound_position: current.outboundPosition, terminal_position: metadata.stream_terminal_position };
+        const proven = agyTerminalFailure(current.terminalResult, { ...error.details, ...metadata });
+        this.lastTerminalFailure = proven;
+        await this.persist({ last_terminal_metadata: metadata, last_terminal_failure: errorRecord(proven) });
+        throw proven;
+      }
+      throw error;
+    } finally {
+      clearInterval(timer); current.observerReturned = true;
+      if (current.dispatchJournalSettled && this.promptObservation === current) this.promptObservation = null;
+    }
+  }
+  childActivity(sessionId) {
+    this.invalidateSettlement(sessionId);
+    if (sessionId === this.init?.conversation_id && !this.active) this.state.unclaimed_activity = true;
+    const child = this.descendants.get(sessionId);
+    if (!child) return;
+    this.descendants.set(sessionId, { ...child, previous_terminal_status: child.status === "unknown" ? child.previous_terminal_status : child.status, status: "unknown", tree_settled: false, settlement_evidence: null, settlement_daemon_id: null });
+  }
+  invalidateSettlement(sessionId) {
+    this.nativeProof = null; this.nativeRevision = (this.nativeRevision ?? 0) + 1; this.nativeAbort?.abort();
+    this.state.native_execution_revision = this.nativeRevision;
+    if (this.init) this.state.active_tree = true;
+    this.state.retained_tree_settlement = null;
+    for (const id of new Set([this.init?.conversation_id, sessionId])) {
+      const observation = this.sessionObservations.get(id);
+      if (observation?.stop) this.sessionObservations.set(id, { ...observation, stop: null });
+    }
+  }
+  qualifiedChildForHook(conversationId) {
+    // A fully source-bound in-memory ancestry is already the result of the
+    // observation loop. Avoid re-reading every transcript on each child hook.
+    const retained = this.descendants.get(conversationId), seenRetained = new Set();
+    let node = retained, expected = conversationId, qualified = Boolean(node && !this.state.native_topology_error);
+    while (qualified) {
+      const source = node?.native_source, parent = node?.parent_provider_session_id;
+      let sourceBound = source?.kind === 'agy.step_update.subagent_info'
+        && source.parent_provider_session_id === parent && Number.isSafeInteger(source.step_index) && source.step_index >= 0;
+      if (!sourceBound && typeof source?.locator === 'string' && /^[a-f0-9]{64}$/.test(source?.sha256 ?? '') && typeof parent === 'string') {
+        try {
+          const locator = fileURLToPath(source.locator);
+          sourceBound = locator.endsWith(path.sep + path.join('brain', parent, '.system_generated', 'logs', 'transcript.jsonl'));
+        } catch { /* An invalid locator never grants a fast-path identity. */ }
+      }
+      if (!node || node.provider_session_id !== expected || !sourceBound || !parent || seenRetained.has(expected)
+        || source.parent_provider_session_id && source.parent_provider_session_id !== parent) { qualified = false; break; }
+      seenRetained.add(node.provider_session_id);
+      if (parent === this.init?.conversation_id) break;
+      expected = parent;
+      node = this.descendants.get(parent);
+      if (!node) qualified = false;
+    }
+    return qualified ? retained : null;
+  }
+  async childForHook(conversationId, onProgress = null) {
+    if (conversationId === this.init?.conversation_id) return null;
+    const retained = this.qualifiedChildForHook(conversationId);
+    if (retained) return retained;
+    await this.captureChildTools(onProgress);
+    const deadline = Date.now() + 1_000;
+    while (!this.descendants.has(conversationId) && Date.now() < deadline) { await new Promise(resolve => setTimeout(resolve, 25)); await this.captureChildTools(onProgress); }
+    const child = this.descendants.get(conversationId);
+    if (!child) throw new DaemonError("agy_child_identity_unconfirmed", "Antigravity hook has no confirmed native parent", true, { conversation_id: conversationId });
+    const seen = new Set([conversationId]); let current = child;
+    for (;;) {
+      if (this.state.native_topology_error || current.native_source?.parent_provider_session_id && current.native_source.parent_provider_session_id !== current.parent_provider_session_id)
+        throw new DaemonError("agy_child_parent_unqualified", "Antigravity native ancestry is contradictory");
+      if (current.parent_provider_session_id === this.init?.conversation_id) break;
+      const parent = this.descendants.get(current.parent_provider_session_id);
+      if (!current.native_source || !parent || seen.has(parent.provider_session_id)) throw new DaemonError("agy_child_parent_unqualified", "Antigravity worker has no source-bound ancestry to the controlled Session", false, { conversation_id: conversationId, parent_conversation_id: current.parent_provider_session_id });
+      seen.add(parent.provider_session_id); current = parent;
+    }
+    if (this.state.native_topology_error) throw new DaemonError("agy_child_parent_unqualified", "Antigravity native ancestry is contradictory");
+    return child;
+  }
+  async registerWorkStart(event, payload, callbackRequestId = null) {
+    if (event !== "PreToolUse" || !this.config.runtime_owner || !this.config.ddFlowBin || !this.init?.conversation_id
+      || typeof payload.conversationId !== "string" || !payload.conversationId
+      || !Number.isSafeInteger(payload.stepIdx) || payload.stepIdx < 0
+      || payload.executionNum !== undefined && (!Number.isSafeInteger(payload.executionNum) || payload.executionNum < 0)
+      || !["run_command", "run_terminal_command", "RunTerminalCommand"].includes(payload.toolCall?.name)) return null;
+    const input = payload.toolCall?.args ?? {}, command = input.command ?? input.cmd ?? input.CommandLine;
+    if (!isStandaloneWorkStart(command)) return null;
+    assertDaemonDispatch(this.paths.dir);
+    const tool = createHash("sha256").update(JSON.stringify([this.config.daemonId, payload.conversationId, payload.stepIdx, payload.executionNum ?? null, event])).digest("hex");
+    this.retainedWorkStarts ??= new Map();
+    this.retainedWorkActivity ??= new Set();
+    if (!this.retainedWorkActivity.has(tool)) {
+      this.retainedWorkActivity.add(tool);
+      // A callback is activity even before its ancestry is published. It
+      // invalidates old idle, but cannot identify or finish a creator prompt.
+      this.childActivity(payload.conversationId);
+    }
+    return await retainNativeWorkStart(this.paths.dir, { daemon_id: this.config.daemonId, source_harness: "antigravity-cli",
+      root_provider_session_id: this.init.conversation_id, provider_session_id: payload.conversationId, parent_provider_session_id: null,
+      tool_call_id: tool, event, native_command: command, native_cwd: this.config.cwd,
+      ...(callbackRequestId ? { callback_request_id: callbackRequestId } : {}),
+      native_payload: { schema_id: "dd-flow/agy-tool-event@1", event_id: tool, phase: "before", daemon_id: this.config.daemonId,
+        launch_cwd: this.config.cwd, conversation_id: payload.conversationId, execution_num: payload.executionNum, step_index: payload.stepIdx,
+        tool: payload.toolCall.name, input, workspace_paths: payload.workspacePaths, transcript_path: payload.transcriptPath,
+        profile: payload.model ? observedProfile(payload) : {} } }, this.active ?? this.lastNativeHookOperation, this.retainedWorkStarts);
+  }
+  async verifyWorkStart(params) {
+    const retained = this.retainedWorkStarts?.get(params.requestId);
+    if (!retained || !isDeepStrictEqual(retained.binding, params.binding)) throw new DaemonError("native_hook_unproven", "Unknown native Work start callback");
+    retained.guard(); assertDaemonDispatch(this.paths.dir);
+    if (retained.binding.root_provider_session_id !== this.init?.conversation_id) throw new DaemonError("native_hook_unproven", "Native Work start root changed");
+    const publish = operationProgressReporter();
+    const child = await this.childForHook(retained.binding.provider_session_id,
+      cursor => publish('verification_progress', { native_request_id: cursor, session_id: retained.binding.provider_session_id }));
+    if (retained.binding.provider_session_id !== this.init.conversation_id && this.qualifiedChildForHook(retained.binding.provider_session_id) !== child)
+      throw new DaemonError("native_hook_unproven", "Native Work start child has no source-bound ancestry");
+    retained.guard();
+    const parent = child?.parent_provider_session_id ?? null;
+    const verified = { ...retained.binding, parent_provider_session_id: parent, native_ancestry: "confirmed",
+      native_payload: { ...retained.binding.native_payload, parent_conversation_id: parent } };
+    if (retained.binding.callback_request_id) this.hookRequests?.delete(retained.binding.callback_request_id);
+    return { verified: true, registeredHookBinding: retained.binding, nativeHookBinding: verified };
+  }
+  async recordUnconfirmedHookFailure(error, event, payload, observer, requestId = null) {
+    // The request was observed while this operation was active, but AGY does
+    // not expose the native creator Turn. Preserve the refusal without
+    // attributing it to (or aborting) this potentially unrelated prompt.
+    const key = typeof requestId === 'string' && /^[A-Za-z0-9-]{1,128}$/.test(requestId) ? requestId : null;
+    const scope = key && JSON.stringify([key, observer?.operationId ?? null, observer?.generation ?? null]);
+    this.unconfirmedHookFlights ??= new Map();
+    if (scope && this.unconfirmedHookFlights.has(scope)) return await this.unconfirmedHookFlights.get(scope);
+    const flight = (async () => {
+      let diagnostic = key && (this.state.native_hook_diagnostics ?? []).find(item => item.request_id === key
+        && item.operation_id === (observer?.operationId ?? null) && item.turn_generation === (observer?.generation ?? null));
+      try {
+        if (!diagnostic) {
+          diagnostic = { code: 'native_hook_failed', message: 'Native hook failed without a verified creator Turn',
+            ...(key ? { request_id: key } : {}), primary_error: errorRecord(error), event, conversation_id: payload.conversationId ?? null,
+            daemon_id: this.config.daemonId, operation_id: observer?.operationId ?? null,
+            turn_generation: observer?.generation ?? null, native_creator: 'unconfirmed' };
+          // Do not grow in-memory state when durable journal writing fails.
+          await this.journal('unconfirmed_hook_failure', diagnostic);
+          this.state.native_hook_diagnostics = [...(this.state.native_hook_diagnostics ?? []), diagnostic];
+        }
+        await this.persist(); return true;
+      } catch { return false; /* Optional diagnostic cannot erase a native operation. */ }
+    })();
+    if (scope) this.unconfirmedHookFlights.set(scope, flight);
+    try { return await flight; }
+    finally { if (scope && this.unconfirmedHookFlights.get(scope) === flight) this.unconfirmedHookFlights.delete(scope); }
+  }
+  async observeHookFailures() {
+    if (!this.hookRequests?.size) return;
+    if (this.hookFailuresFlight) return await this.hookFailuresFlight;
+    const flight = (async () => {
+      let names;
+      try { names = new Set(await readdir(path.join(this.paths.dir, "hook-failures"))); }
+      catch (error) { if (error.code === "ENOENT") return; throw error; }
+      for (const [requestId, binding] of this.hookRequests ?? []) {
+        if (!binding.current || !names.has(`${requestId}.json`)) continue;
+        let failure;
+        try { failure = JSON.parse(await readFile(path.join(this.paths.dir, "hook-failures", `${requestId}.json`), "utf8")); }
+        catch (error) { if (error.code === "ENOENT") continue; failure = { code: "native_hook_receipt_invalid", message: error.message }; }
+        if (failure.request_id !== undefined && failure.request_id !== requestId) continue;
+        if (binding.current !== this.active) {
+          if (failure.request_id !== requestId) continue;
+          // The callback request was accepted while this observer operation was
+          // active. AGY has no native creator ID, so this is diagnostic only:
+          // never mutate either the old receipt or the current Turn.
+          await this.journal("late_hook_receipt", { request_id: requestId, daemon_id: this.config.daemonId,
+            observer_operation_id: binding.current.operationId ?? null, observer_turn_generation: binding.current.generation ?? null,
+            native_creator: "unconfirmed", event: binding.event, failure: errorRecord(failure) });
+          this.hookRequests.delete(requestId);
+          continue;
+        }
+        const saved = await this.recordUnconfirmedHookFailure(Object.assign(new Error(failure.message ?? "Native hook failed"), { code: failure.code, details: failure.details }), binding.event, binding.payload, binding.current, requestId);
+        if (saved) this.hookRequests.delete(requestId);
+      }
+    })();
+    this.hookFailuresFlight = flight;
+    try { await flight; } finally { if (this.hookFailuresFlight === flight) this.hookFailuresFlight = null; }
+  }
+  async observeHook(event, payload, budget = null) {
+    const hookOwner = this.active, hookGeneration = this.turnGeneration;
+    const conversationId = payload.conversationId ?? this.init?.conversation_id;
+    const shell = ["run_command", "run_terminal_command", "RunTerminalCommand"].includes(payload.toolCall?.name);
+    const args = payload.toolCall?.args ?? {}, command = args.command ?? args.cmd ?? args.CommandLine;
+    const observationOnly = Boolean(this.config.runtime_owner && this.config.ddFlowBin && (event === "Stop" || !shell
+      || typeof command === "string" && parseLifecycleCommand(command).participation === "none"));
+    // Ordinary native facts cannot grant Work authority. Keep them cheap;
+    // independent observation verifies ancestry/idle after the callback ACK.
+    const child = observationOnly ? this.qualifiedChildForHook(conversationId) : await this.childForHook(conversationId); budget?.remaining("identity");
+    if (this.active !== hookOwner || this.turnGeneration !== hookGeneration) {
+      await this.journal("stale_hook", { hook_event: event, conversation_id: conversationId, reason: "owner_changed_during_identity" });
+      return { stale: true };
+    }
+    const prior = this.sessionObservations.get(conversationId) ?? {};
+    const execution = Number.isInteger(payload.executionNum) ? payload.executionNum : null;
+    const step = Number.isInteger(payload.stepIdx) ? payload.stepIdx : null;
+    const stale = step !== null && (Number.isInteger(prior.step_floor) && step <= prior.step_floor
+      || Number.isInteger(prior.last_step_index) && step < prior.last_step_index
+      || step === prior.last_step_index && execution !== null && Number.isInteger(prior.last_execution_num) && execution < prior.last_execution_num);
+    if (stale) { await this.journal("stale_hook", { hook_event: event, conversation_id: conversationId, step_index: step }); return { stale: true }; }
+    const fingerprint = createHash("sha256").update(JSON.stringify({ event, payload })).digest("hex");
+    if (event === "Stop" && prior.last_stop_hook === fingerprint && prior.last_stop_generation === this.turnGeneration) return { stale: true };
+    this.progressHooks ??= new Map();
+    const scoped = this.active && (!child || child.activity_generation === this.active.generation);
+    // Native hook payloads/step updates carry no creator prompt identity.
+    // A late old step above the new floor is indistinguishable from a new one:
+    // Stop remains a hint, never a whole-tree or child idle grant.
+    const sourceBound = false;
+    const progressKey = JSON.stringify([conversationId, step, execution, event, payload.toolCall ?? null, payload.fullyIdle ?? null]);
+    if (scoped && step !== null && (["PreToolUse", "PostToolUse"].includes(event) || event === "Stop" && payload.fullyIdle === true)) {
+      let progress = this.progressHooks.get(conversationId);
+      if (!progress || progress.step !== step) { progress = { step, seen: new Set() }; this.progressHooks.set(conversationId, progress); }
+      if (!progress.seen.has(progressKey)) { progress.seen.add(progressKey); this.markActivity(); }
+    }
+    if (conversationId) this.sessionObservations.set(conversationId, { ...prior,
+      ...(step !== null ? { last_step_index: step, last_execution_num: execution ?? (step === prior.last_step_index ? prior.last_execution_num : null) } : {}),
+      last_hook: fingerprint, ...(event === "PreToolUse" ? { last_pre_hook: fingerprint } : {}),
+      ...(payload.transcriptPath ? { transcript_path: payload.transcriptPath } : {}),
+      ...(event === "Stop" ? { last_stop_hook: fingerprint, last_stop_generation: this.turnGeneration, stop: { fullyIdle: payload.fullyIdle === true, source_bound: sourceBound, terminationReason: payload.terminationReason ?? null, executionNum: execution } } : {}) });
+    if (event === "PreToolUse" && prior.last_pre_hook !== fingerprint) this.childActivity(conversationId);
+    const parent = child?.parent_provider_session_id ?? null;
+    if (event === "Stop" && !stale) {
+      const observation = this.sessionObservations.get(conversationId);
+      this.sessionObservations.set(conversationId, { ...observation, stop: { ...observation.stop, generation: this.turnGeneration } });
+    }
+    const observed = payload.model ? observedProfile(payload) : {};
+    // An omitted model carries no profile evidence. The hook journal below
+    // retains that fact; do not read/lock/fsync the model history for every
+    // ordinary tool or Stop callback. Actual model observations stay intact.
+    if (payload.model && !observationOnly) await observeModel({ journal: this.config.journal, harness: "antigravity-cli", sessionId: conversationId, parentSessionId: parent, requested: this.config, observed, source: { channel: "native.hook", scope: "configured" }, evidence: "configured" });
+    if (this.active !== hookOwner || this.turnGeneration !== hookGeneration) {
+      await this.journal("stale_hook", { hook_event: event, conversation_id: conversationId, reason: "owner_changed_during_model_observation" });
+      return { stale: true };
+    }
+    const eventId = createHash("sha256").update(JSON.stringify({ daemon: this.config.daemonId, event, conversationId, fully_idle: payload.fullyIdle ?? null, termination_reason: payload.terminationReason ?? null, execution: payload.executionNum ?? null, step: payload.stepIdx ?? null, tool: payload.toolCall?.name ?? null, args: payload.toolCall?.args ?? null })).digest("hex");
+    await this.persist(); await this.journal("hook", { stale, hook_event: event, event_id: eventId, conversation_id: conversationId, turn_generation: hookGeneration, execution_num: execution, step_index: step, termination_reason: payload.terminationReason ?? null, fully_idle: payload.fullyIdle ?? null, ...(payload.model ? {} : { model_observation: "unavailable" }), persistence_timing: this.persistTiming ?? null });
+    if (this.active !== hookOwner || this.turnGeneration !== hookGeneration) return { stale: true };
+    this.queueNativeInspection();
+    // A provider may wait for this hook's ACK before emitting the very event
+    // needed to finish the turn. The fact above is persisted before ACK;
+    // completion reconciliation belongs to the daemon, not the callback.
+    if (hookOwner && this.active === hookOwner && this.turnGeneration === hookGeneration) hookOwner.pendingHookReconciliation = true;
+    return { observationOnly, event_id: eventId, source_bound: sourceBound, daemon_id: this.config.daemonId, launch_cwd: this.config.cwd, parent_conversation_id: parent, profile: observed, requested_profile: { provider: this.config.provider, model: this.config.model, reasoning: this.config.reasoning, mode: this.config.mode }, project_root: this.config.projectRoot, dd_flow_bin: this.config.ddFlowBin, dd_flow_home: this.config.ddFlowHome };
+  }
+  async finalizeProviderForControl() {
+    const pending = this.providerFinalization;
+    try {
+      while (this.active?.pendingHookReconciliation || this.active?.hookReconciliation) await this.reconcilePendingHook(this.active);
+      try { await pending; }
+      catch (error) {
+        // Control retries only retained physical/resource cleanup, never a
+        // missing mandatory stream record or a productive provider request.
+        if (this.providerFinalization !== pending) await this.providerFinalization;
+        else {
+          if (!this.retryProviderFinalization) throw error;
+          this.providerFinalization = this.retryProviderFinalization(5_000);
+          await this.providerFinalization;
+        }
+      }
+      await this.promptObservation?.dispatchJournal;
+      await this.observeHookFailures();
+    } catch (error) {
+      if (!this.drainingError) throw error;
+      this.drainingError.cleanup_error = errorRecord(error);
+      this.drainingError.details = { ...this.drainingError.details, cleanup_error: this.drainingError.cleanup_error };
+      throw this.drainingError;
+    }
+    if (this.drainingError) throw this.drainingError;
+  }
+  async prepareStop(cancelTree) {
+    const current = this.active, priorResult = this.lastResult;
+    if (!cancelTree && !current && !priorResult) await this.reconcileRetainedAdmission();
+    if (cancelTree && (this.active || !this.receipt().settled)) await this.cancel();
+    else if (this.active || this.state.active_tree || this.state.unclaimed_activity || (this.lastResult && !this.receipt().settled)) throw new DaemonError("tree_not_settled", "Antigravity root or child tree is still running");
+    // A physical kill is settlement, not a native clean terminal receipt.
+    // In particular, the previous Turn's SUCCESS cannot certify a cancelled
+    // in-flight Turn that exited without its own result.
+    const currentResult = !current || current.terminalResult === this.lastResult || this.lastResult !== priorResult;
+    const clean = currentResult && this.receipt().settled;
+    return { ...this.receipt(), clean, settled: Boolean(clean), native_settled: Boolean(clean), ...(clean ? {} : { native_settlement: { confirmed: false, reason: "native_terminal_unconfirmed" } }) };
+  }
+  async retireNativeServices() {
+    if (!this.nativeQualification?.qualified) return;
+    this.nativeResources ??= new Map((this.state.native_resources_entries ?? []).map(item => [item.resource_id, item]));
+    const services = [...(this.nativeResources?.values() ?? [])].filter(item => item.classification === 'support_service' && item.state !== 'stopped');
+    const schedules = [...(this.nativeResources?.values() ?? [])].filter(item => item.state !== 'stopped' &&
+      (item.kind === 'schedule' || item.classification === 'unknown'));
+    // Unknown task semantics can be reconciled by exact native handle inventory,
+    // not by inventing a shell outcome or trusting a PID printed to stdout.
+    const revision = this.nativeRevision ?? 0;
+    const endpoint = this.nativeStopper ? null : await ownedAgyEndpoint(this.nativeLaunch);
+    const input = { endpoint, sessionId: this.init.conversation_id, cwd: this.config.cwd,
+      csrfToken: this.nativeCsrfToken, remainingMs: 10_000, rootRelation: this.nativeQualification.rootRelation };
+    const clock = new ObservationClock({ timeoutMs: input.remainingMs });
+    let progress = 0;
+    const requestInput = () => {
+      if (clock.sample()) throw new DaemonError('native_resources_unproven', 'AGY native retirement observation budget exhausted');
+      const remainingMs = Math.max(1, Math.ceil(clock.timeoutMs - clock.elapsed));
+      return { ...input, remainingMs };
+    };
+    const inventory = async () => {
+      if (this.state.native_topology_error) throw new DaemonError('native_resources_unproven', 'AGY native topology is incomplete');
+      const root = this.init.conversation_id, nodes = [{ provider_session_id: root, parent_provider_session_id: '' }, ...this.descendants.values()];
+      for (const node of nodes.slice(1)) {
+        const seen = new Set([node.provider_session_id]); let parent = node.parent_provider_session_id;
+        while (parent !== root) {
+          if (!parent || seen.has(parent)) throw new DaemonError('native_resources_unproven', 'AGY native resource ancestry is unbound');
+          seen.add(parent); parent = this.descendants.get(parent)?.parent_provider_session_id;
+        }
+      }
+      const result = [];
+      for (const node of nodes) {
+        const snapshot = await (this.nativeStateObserver ?? inspectAgyNativeState)({ ...requestInput(),
+          sessionId: node.provider_session_id, rootSessionId: root, parentSessionId: node.parent_provider_session_id });
+        result.push({ session_id: node.provider_session_id, snapshot, ...agyNativeInventory(snapshot, node.provider_session_id) });
+        clock.sample(++progress); // A completed node read, not observer polling.
+      }
+      return result;
+    };
+    // Historical transcript envelopes need not explain whether a timer fired
+    // or was cancelled. Fresh native absence proves retirement, not success.
+    // The transcript ledger is partial. It cannot decide whether a fresh native
+    // inventory is needed: even a missing ledger may hide an active daemon task.
+    let states = await inventory();
+    const required = states.find(state => !state.idle || state.tasks.some(task => task.isDaemon !== true));
+    if (required) {
+      this.childActivity(required.session_id);
+      throw new DaemonError('native_resources_unproven', 'AGY required execution became active before native resource retirement');
+    }
+    const notificationKey = (session, trajectory, message) => JSON.stringify([session, trajectory, message.id, message.sender, message.recipient]);
+    const notifications = new Map((this.state.native_retirement_notifications ?? []).filter(item => item.owner_daemon_id === this.config.daemonId)
+      .map(item => [notificationKey(item.session_id, item.trajectory_id, item), item]));
+    if (states.some(state => state.messages.some(message => !notifications.has(notificationKey(state.session_id, state.snapshot.trajectoryId, message)))))
+      throw new DaemonError('native_resources_unproven', 'AGY has pending delivery before native resource retirement');
+    const stopSenders = new Set(['system', ...states.map(state => state.session_id), ...states.flatMap(state => state.tasks.map(task => task.taskId))]);
+    const trajectories = new Map(states.map(state => [state.session_id, state.snapshot.trajectoryId]));
+    const activeTasks = states.some(state => state.snapshot.hasActiveChildren === true || state.tasks.length > 0);
+    const stopped = services.length || activeTasks
+      ? await (this.nativeStopper ?? stopAgyNativeTree)(requestInput(), [...this.descendants.keys()]) : null;
+    if (stopped) clock.sample(++progress);
+    const observed = await (this.nativeObserver ?? inspectAgyNative)(requestInput());
+    clock.sample(++progress);
+    if (!this.nativeStopper && !isDeepStrictEqual(await ownedAgyEndpoint(this.nativeLaunch), endpoint)
+      || !observed.idle || revision !== (this.nativeRevision ?? 0) || !this.receipt().settled)
+      throw new DaemonError('native_resources_unproven', 'AGY native service retirement lost its owner/execution fence');
+    {
+      states = await inventory();
+      if (states.some(state => !state.idle || trajectories.get(state.session_id) !== state.snapshot.trajectoryId ||
+        state.tasks.length) ||
+        observed.trajectory_id && observed.trajectory_id !== trajectories.get(this.init.conversation_id) ||
+        revision !== (this.nativeRevision ?? 0) || !this.receipt().settled ||
+        !this.nativeStopper && !isDeepStrictEqual(await ownedAgyEndpoint(this.nativeLaunch), endpoint))
+        throw new DaemonError('native_resources_unproven', 'AGY schedule retirement lacks fresh idle inventory and required delivery');
+      for (const state of states) for (const message of state.messages) {
+        const key = notificationKey(state.session_id, state.snapshot.trajectoryId, message);
+        if (notifications.has(key)) continue;
+        if (!stopped || typeof message.id !== 'string' || !message.id || message.recipient !== state.session_id || !stopSenders.has(message.sender))
+          throw new DaemonError('native_resources_unproven', 'AGY post-stop delivery has no owned native control provenance');
+        // Native cancellation creates notices after required execution is
+        // already settled. They remain pending technical evidence until the
+        // fenced provider is closed; do not prompt a model or claim delivery.
+        notifications.set(key, { id: message.id, sender: message.sender, recipient: message.recipient, session_id: state.session_id,
+          trajectory_id: state.snapshot.trajectoryId, owner_daemon_id: this.config.daemonId, generation: this.turnGeneration, revision,
+          status: 'pending', disposition: 'after_owned_native_stop', method: stopped.method });
+      }
+      for (const schedule of schedules) {
+        const state = states.find(item => item.session_id === schedule.provider_session_id);
+        if (!state || state.tasks.some(task => task.taskId === schedule.resource_id))
+          throw new DaemonError('native_resources_unproven', 'AGY schedule owner or retirement is unproven');
+        this.nativeResources.set(schedule.resource_id, { ...schedule, state: 'stopped', native_retirement: {
+          method: state.snapshot.method, reason: 'native_task_inventory_absent', revision,
+          trajectory_id: state.snapshot.trajectoryId, observed_at: state.snapshot.observed_at } });
+      }
+    }
+    // This is native handle retirement, not physical cleanup. Shared shutdown
+    // still re-observes the retained local PID/birth inventory after close.
+    for (const service of services) this.nativeResources.set(service.resource_id, { ...service, state: 'stopped',
+      native_retirement: { method: stopped.method, stopped_session_ids: stopped.stopped_session_ids, revision } });
+    await this.persist({ native_resources_entries: [...this.nativeResources.values()], native_retirement_notifications: [...notifications.values()] });
+    if (revision !== (this.nativeRevision ?? 0) || !this.receipt().settled)
+      throw new DaemonError('native_resources_unproven', 'AGY resource retirement was fenced during publication');
+  }
+  async cancel() { if (!this.active && this.receipt().settled) return { ...this.receipt(), cancelled: true }; this.nativeAbort?.abort(); this.nativeProof = null; this.nativeRevision = (this.nativeRevision ?? 0) + 1; this.state.native_execution_revision = this.nativeRevision; cancelPendingDispatch(this); if (!this.child) return this.receipt(); if (!this.exited) { try { process.kill(-this.child.pid, "SIGINT"); } catch (error) { if (error.code !== "ESRCH") throw error; } const deadline = Date.now() + 5000; while (!this.exited && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 100)); if (!this.exited) await stopProcessGroup(this.child, 5_000); } await this.finalizeProviderForControl(); await this.persist({ active_tree: false }); return { ...this.receipt(), cancelled: true };
+  }
+  async close(cancelTree) { if (cancelTree) cancelPendingDispatch(this); if (!cancelTree && !this.exited && (this.active || this.state.active_tree || this.state.unclaimed_activity || (this.lastResult && !this.receipt().settled))) throw new DaemonError("tree_not_settled", "Antigravity root or child tree is still running"); if (cancelTree) await this.cancel(); else if (this.child && !this.exited) this.child.stdin.end(); const deadline = Date.now() + 5000; while (!this.exited && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 100)); if (!this.exited) { if (!this.active && this.receipt().settled) await stopProcessGroup(this.child, 5_000); else await this.cancel(); } await this.finalizeProviderForControl(); }
+  async abortProvider(reason) {
+    const child = this.child, providerProcess = this.providerProcess;
+    await stopProcessGroup(child);
+    await this.finalizeProviderForControl();
+    await finishDaemonProcess(this.config, providerProcess, "failed", reason);
+  }
+  async finishResource(state = "stopped", reason = "daemon_stopped") { await this.captureChildTools(); await finishDaemonProcess(this.config, this.state.resource_process, state, reason); }
+}
+
+export async function serveDaemon(stateDir) {
+  const paths = locations(stateDir), state = await readState(paths.dir); if (!state?.config) throw new DaemonError("daemon_state_missing", "Antigravity daemon state is missing");
+  scheduleDaemonProcessHeartbeat(state.config, state.resource_process);
+  const runtime = new Runtime(paths, state); await removeSocket(paths);
+  const server = net.createServer(socket => {
+    let buffer = "", consumed = false; socket.setEncoding("utf8");
+    socket.on("data", chunk => {
+      if (consumed) return;
+      buffer += chunk; if (!admitNativeRequestBuffer(buffer, socket, 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));
+          const result = await durableDaemonDispatch(paths.dir, request, () => dispatch(runtime, request), () => dispatch(runtime, { operation: "session.inspect", params: request.params ?? {} }));
+          if (result._shutdown) retireDaemonEndpoint(server);
+          socket.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));
+          socket.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);
+  try { await runtime.start(state.config.resumeSessionId); runtime.requireSessionIdentity(state.config.resumeSessionId); }
+  catch (error) {
+    try { await runtime.abortProvider("daemon_start_failed"); }
+    catch (cleanup) { error.details = { ...error.details, cleanup_failed: errorRecord(cleanup) }; }
+    try { if (!error.details?.cleanup_failed) await runtime.finishResource("failed", "daemon_start_failed"); }
+    catch (cleanup) { error.details = { ...error.details, resource_cleanup_failed: errorRecord(cleanup) }; }
+    Object.assign(state, { shutdown_state: error.details?.cleanup_failed || error.details?.resource_cleanup_failed ? "cleanup_failed" : "failed", active_tree: Boolean(error.details?.cleanup_failed) });
+    await retainStartupFailure({ state, publish: snapshot => runtime.persist(snapshot), log: paths.log, error });
+    await new Promise(resolve => server.close(resolve));
+    throw error;
+  }
+  await new Promise(resolve => server.once("close", resolve));
+}
+
+async function dispatch(runtime, request) {
+  if (request.schema_id !== REQUEST_SCHEMA) throw new DaemonError("daemon_protocol_mismatch", "unsupported dd-agy request schema"); const params = request.params ?? {};
+  if (["session.create", "session.prompt", "session.start", "session.fork", "session.resume"].includes(request.operation)) assertDaemonDispatch(runtime.paths.dir);
+  if (request.operation === "daemon.status") { await runtime.observeHookFailures(); return { daemon_id: runtime.config.daemonId, shutdown_state: runtime.state.shutdown_state, active_tree: runtime.state.active_tree, active_operation: runtime.active?.operationId ?? null, last_hook_rejection: runtime.state.last_hook_rejection ?? null, last_activity_at: runtime.lastActivityAt, provider_ready: Boolean(runtime.init && !runtime.exited), pid: process.pid, provider_pid: runtime.child?.pid ?? null, versions: runtime.state.versions, config: runtime.config, sessions: runtime.state.sessions ?? [], receipt: runtime.receipt() }; }
+  if (request.operation === "session.create") { if (params.sessionId) throw new DaemonError("invalid_create", "create does not accept a Session ID"); if (params.prompt) throw new DaemonError("invalid_create", "create does not execute a prompt; use session.prompt"); await runtime.start(); await runtime.zeroUsage(); return runtime.receipt(); }
+  if (request.operation === "session.prompt") { const assertDispatch = captureDispatchGuard(runtime); await runtime.start(params.sessionId ?? null); runtime.requireSessionIdentity(params.sessionId); return await runtime.prompt(params.prompt, assertDispatch, request.id, params.livenessTimeoutMs ?? runtime.config.livenessTimeoutMs ?? 1_800_000); }
+  if (request.operation === "session.inspect") { runtime.requireSessionIdentity(params.sessionId); await runtime.captureChildTools(); void runtime.reconcileRetainedAdmission().catch(error => { runtime.nativeInspection = { state: 'unproven', reason: error.details?.reason ?? error.code ?? 'native_admission_unproven' }; }); runtime.queueNativeInspection(); await runtime.persist({ native_observation_episode: runtime.episodeSnapshot() }); return runtime.receipt(); }
+  if (request.operation === "session.resume") { await runtime.start(params.sessionId ?? runtime.init?.conversation_id ?? null); runtime.requireSessionIdentity(params.sessionId); return runtime.receipt(); }
+  if (request.operation === "session.cancel") { runtime.requireSessionIdentity(params.sessionId); return await runtime.cancel(); }
+  if (request.operation === "hook.verify") {
+    if (params.daemonId !== runtime.config.daemonId) throw new DaemonError("agy_hook_binding_invalid", "Antigravity hook binding does not name this daemon");
+    assertDaemonDispatch(runtime.paths.dir);
+    if (params.binding?.native_admission === "assigned_work_start") return await runtime.verifyWorkStart(params);
+    const retained = runtime.verifiedHookFacts?.get(params.requestId);
+    if (!retained || !isDeepStrictEqual(retained.binding, params.binding)) throw new DaemonError("native_hook_unproven", "Hook fact is not bound to a verified native delivery");
+    retained.guard();
+    return { verified: true, nativeHookBinding: retained.binding };
+  }
+  if (request.operation === "hook.complete") {
+    if (params.daemonId !== runtime.config.daemonId)
+      throw new DaemonError("agy_hook_binding_invalid", "Antigravity hook binding does not name this daemon");
+    if (typeof params.requestId !== 'string' || !/^[A-Za-z0-9-]{1,128}$/.test(params.requestId))
+      throw new DaemonError("agy_hook_binding_invalid", "Antigravity callback request ID is invalid");
+    // Administrative ACK only: the success of a callback is not proof that a
+    // Work mutation occurred or that a native agent Turn is complete.
+    return { retired: runtime.hookRequests?.delete(params.requestId) === true };
+  }
+  if (request.operation === "hook.observe") {
+    // Check the process binding before correlating a request with an active
+    // turn. A stale/foreign daemon must not poison an unrelated operation.
+    if (runtime.config.hookBinding === "environment-v1" && params.daemonId !== runtime.config.daemonId) throw new DaemonError("agy_hook_binding_invalid", "Antigravity hook binding does not name this daemon", false, { expected_daemon_id: runtime.config.daemonId, observed_daemon_id: params.daemonId ?? null });
+    const current = runtime.active, budget = hookBudget(25_000, params.deadlineAt);
+    runtime.hookRequests ??= new Map();
+    if (/^[A-Za-z0-9-]{1,128}$/.test(request.id)) runtime.hookRequests.set(request.id, { current: current ?? runtime.lastNativeHookOperation, event: params.event, payload: { conversationId: params.payload?.conversationId, toolCall: { name: params.payload?.toolCall?.name } } });
+    try {
+      const deferred = await budget.run(() => runtime.registerWorkStart(params.event, params.payload ?? {}, request.id), "registration");
+      if (deferred) return { fastAck: true, nativeHookBinding: deferred };
+      const result = await budget.run(async () => {
+        if (runtime.hookRequests.has(request.id) && current?.operationId) {
+          const directory = path.join(runtime.paths.dir, "operations", createHash("sha256").update(current.operationId).digest("hex"), "hooks");
+          await mkdir(directory, { recursive: true, mode: 0o700 });
+          await writeJson(path.join(directory, `${request.id}.json`), { schema_id: "dd-flow/hook-request@1", request_id: request.id, daemon_id: runtime.config.daemonId, operation_id: current.operationId, turn_generation: current.generation, native_creator: "unconfirmed", event: params.event, conversation_id: params.payload?.conversationId ?? null, tool: params.payload?.toolCall?.name ?? null });
+        }
+        budget.remaining("observation");
+        return await runtime.observeHook(params.event, params.payload ?? {}, budget);
+      }, "observation");
+      // The AGY stream does not prove which native prompt produced a step.
+      // An unseen old step can exceed a newer prompt's observed floor. Do not
+      // mint an optional CLI admission from event order; legacy hook performs
+      // its existing scoped checks until a native creator binding exists.
+      await runtime.observeHookFailures(); budget.remaining("observation");
+      if (result.stale) runtime.hookRequests.delete(request.id);
+      return result;
+    }
+    catch (error) { await runtime.recordUnconfirmedHookFailure(error, params.event, params.payload ?? {}, current, request.id); throw error; }
+  }
+  if (request.operation === "daemon.stop") return await completeDaemonShutdown(runtime.paths.dir, runtime.state, patch => runtime.persist(patch), () => runtime.prepareStop(params.cancelTree === true), [["provider", async ({ physicalOnly }) => {
+    if (!physicalOnly) return await runtime.close(false);
+    await stopProcessGroup(runtime.child);
+    await finishDaemonProcess(runtime.config, runtime.providerProcess);
+  }], ["daemon_resource", ({ physicalOnly }) => physicalOnly ? finishDaemonProcess(runtime.config, runtime.state.resource_process) : runtime.finishResource()]], async () => {
+    await runtime.retireNativeServices();
+    await runtime.captureChildTools();
+    return runtime.receipt().native_resources;
+  }, { cancelTree: params.cancelTree === true });
+  throw new DaemonError("unknown_operation", `unknown dd-agy daemon operation: ${request.operation}`);
+}
+import { authorizeRetainedDaemonResume } from "./driver-recovery.mjs";
+import { commandText } from "./process-json.mjs";