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

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

@@ -0,0 +1,739 @@
+import { managedFlowEnv } from './managed-flow-env.mjs';
+import { processSnapshot } from "./process-snapshot.mjs";
+import { ToolObservations, droidToolObservations, journalToolObservations } from "./tool-observations.mjs";
+export { processSnapshot } from "./process-snapshot.mjs";
+import { captureDispatchGuard, cancelPendingDispatch } from "./dispatch-fence.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, chmod, copyFile, mkdir, readFile, readdir, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { ObservationClock, observedTimeout, validateObservationDuration } from "./observation-clock.mjs";
+import { operationProgressReporter } from "./operation-progress.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+import { errorRecord, reportedError, isObservationLoss, isNativeHookObservationLoss, isProvenShellCorrection } from "./operation-errors.mjs";
+import { hookBudget, invokeNativeHook, retainNativeWorkStart, isStandaloneWorkStart } from "./native-hook-command.mjs";
+import { assertDaemonDispatch } from "./daemon-operations.mjs";
+import { isDeepStrictEqual } from "node:util";
+import { parseLifecycleCommand } from "./lifecycle-command.mjs";
+import { checkObservedProfile, observeModel } from "./model-observations.mjs";
+import { readNativeLines, streamNativeDiagnostics, nativeObservationError } from "./native-streams.mjs";
+import { commandText } from "./process-json.mjs";
+import { DroidMetadataReader, readDroidRoutingLog } from "./droid-observation.mjs";
+const metadataReaders = new Map();
+function metadataReader(factory) { if (!metadataReaders.has(factory)) metadataReaders.set(factory, new DroidMetadataReader(factory)); return metadataReaders.get(factory); }
+import { confirmDaemonProcess, finishDaemonProcess, scheduleDaemonProcessHeartbeat, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.mjs";
+import { renderAdapterPolicy, lifecycleRetryInstruction } from "./delegation-instructions.mjs";
+import { classifyRecoveryError as classifyProviderError, safeProviderError } from "./provider-overload-policy.mjs";
+import { settledNativeTree, nativeExecutionReceipt } from "./native-children.mjs";
+
+export const DROID_CONTRACT = "dd-droid-harness@1";
+export const DROID_PROTOCOL = "1.201.0";
+const LATE_RESPONSE_GRACE_MS = 5_000;
+export class DroidError extends Error {
+  constructor(code, message, details) { super(message); this.code = code; if (details) this.details = details; }
+}
+export const absolute = (value, label) => { if (!value || !path.isAbsolute(value)) throw new DroidError("invalid_path", `${label} must be absolute`); return path.resolve(value); };
+export const executable = (bin, args = []) => /\.[cm]?js$/.test(bin) ? { command: process.execPath, args: [bin, ...args] } : { command: bin, args };
+const shell = value => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const responseSummary = event => ({ request_id: event?.id ?? null, has_result: event?.result !== undefined,
+  result_keys: event?.result && typeof event.result === "object" && !Array.isArray(event.result) ? Object.keys(event.result).slice(0, 32) : [], error: event?.error ?? null });
+export async function readJson(file) { try { return JSON.parse(await readFile(file, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
+export function droidPaths(stateDir) {
+  const dir = absolute(stateDir, "state directory"), digest = createHash("sha256").update(dir).digest("hex").slice(0, 24);
+  const local = path.join(dir, "daemon.sock");
+  return { dir, socket: Buffer.byteLength(local) < 100 ? local : `/tmp/dd-droid-${digest}.sock`, state: path.join(dir, "daemon.json"), log: path.join(dir, "daemon.log"), home: path.join(dir, "home"), factory: path.join(dir, "home", ".factory"), bindings: path.join(dir, "native-operations") };
+}
+export function droidEnvironment(config) {
+  const env = { ...process.env, FACTORY_HOME_OVERRIDE: config.home, FACTORY_DROID_AUTO_UPDATE_ENABLED: "false", ...(config.ddFlowHome ? { DD_FLOW_HOME: config.ddFlowHome, DD_FLOW_BIN: config.ddFlowBin } : {}) };
+  // This adapter deliberately uses the operator's existing Factory login.
+  // Undefined is a tombstone: downstream env overlays must not resurrect keys.
+  for (const key of Object.keys(env)) if (key.endsWith("API_KEY")) env[key] = undefined;
+  return { ...env, ...managedFlowEnv(config) };
+}
+export async function prepareDroidHome(config) {
+  const paths = droidPaths(config.stateDir);
+  for (const dir of [paths.dir, paths.home, paths.factory, paths.bindings, path.join(paths.factory, "droids")]) { await mkdir(dir, { recursive: true, mode: 0o700 }); await chmod(dir, 0o700); }
+  const auth = path.join(config.authHome ?? os.homedir(), ".factory");
+  for (const name of ["auth.encrypted", "auth.v2.key", "auth.v2.file", "auth.json"]) {
+    try { await copyFile(path.join(auth, name), path.join(paths.factory, name)); await chmod(path.join(paths.factory, name), 0o600); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  await writeJsonAtomic(path.join(paths.factory, "settings.json"), { cloudSessionSync: false, enabledPlugins: {}, enableHooks: true, hooksDisabled: false, enableCustomDroids: true, ideAutoConnect: false, subagentAutonomyLevel: "inherit" });
+  const command = `${shell(process.execPath)} ${shell(config.entryPath)} hook handle --state-dir ${shell(paths.dir)}`;
+  const hooks = Object.fromEntries(["SessionStart", "PreToolUse", "PostToolUse", "Stop", "SessionEnd", "SubagentStop"].map(event => [event, [{ matcher: "*", hooks: [{ type: "command", command, timeout: 30 }] }]]));
+  await writeJsonAtomic(path.join(paths.factory, "hooks.json"), hooks);
+  const worker = `---\nname: dd-flow-worker\ndescription: Execute one explicit dd-flow Work packet or a technical capacity marker\nmodel: ${config.model}\nreasoningEffort: ${config.reasoning}\nmcpServers: []\n---\nFor a Work assignment, your first technical action is the exact standalone work start command supplied by the coordinator. If that command is absent, report an incomplete packet and stop: do not run stage pause, stage finish, or another lifecycle command. Execute the supplied operation and target exactly; lifecycle invocation IDs are internal runtime authority, so never add or invent them. Continue only after a successful start returns the Work packet. ${lifecycleRetryInstruction} Follow only the returned Work packet, invoke its exact work finish or fail command, then stop. A Task child never executes or finishes its coordinator's Stage Work. Do not create children or take another Work. For a technical capacity marker, only return the requested marker; do not read the project or call dd-flow.\n`;
+  await writeFile(path.join(paths.factory, "droids", "dd-flow-worker.md"), worker, { mode: 0o600 });
+  return { hooks_sha256: createHash("sha256").update(JSON.stringify(hooks)).digest("hex"), worker_sha256: createHash("sha256").update(worker).digest("hex") };
+}
+export async function removeDroidAuth(config) {
+  for (const name of ["auth.encrypted", "auth.v2.key", "auth.v2.file", "auth.json"]) await unlink(path.join(config.home, ".factory", name)).catch(error => { if (error.code !== "ENOENT") throw error; });
+}
+export async function droidVersion(bin) { const target = executable(bin, ["--version"]); return await commandText(target.command, target.args, { phase: "native-version" }); }
+
+/** The qualified OpenAI profile reports uncached input separately from caches;
+ * output already includes thinking. Keep native counters alongside normalization. */
+export function physicalUsage(value) {
+  if (!value || !["inputTokens", "outputTokens", "cacheReadTokens", "cacheCreationTokens", "thinkingTokens"].every(key => Number.isFinite(value[key]) && value[key] >= 0)) return null;
+  const input = value.inputTokens + value.cacheReadTokens + value.cacheCreationTokens;
+  return { totalTokens: input + value.outputTokens, inputTokens: input, uncachedInputTokens: value.inputTokens, cacheReadTokens: value.cacheReadTokens, cacheCreationTokens: value.cacheCreationTokens, outputTokens: value.outputTokens, reasoningTokens: value.thinkingTokens, native: value };
+}
+export function parseDroidTranscript(text, settings, expectedId) {
+  const records = []; let complete = true;
+  for (const line of text.split("\n")) { if (!line.trim()) continue; try { records.push(JSON.parse(line)); } catch { complete = false; } }
+  const header = records.find(record => record.type === "session_start");
+  if (!header || header.id !== expectedId) throw new DroidError("session_identity_mismatch", "Droid transcript has a different or missing native Session ID", { expected_session_id: expectedId, observed_session_id: header?.id ?? null });
+  const tools = new ToolObservations();
+  for (const record of records) for (const event of droidToolObservations(record, expectedId)) tools.add(event);
+  if (!complete) tools.gaps.add("transcript_incomplete");
+  return { header, records, outcomes: records.filter(record => record.type === "agent_turn_outcome"), usage: physicalUsage(settings?.tokenUsage), settings, complete, tool_calls: tools.summary() };
+}
+export async function readDroidSession(factory, id) {
+  const file = await metadataReader(factory).locate(id);
+  if (!file) return null;
+  const text = await readFile(file, "utf8"); let settings = null, complete = true;
+  try { settings = await readJson(file.replace(/\.jsonl$/, ".settings.json")); } catch (error) { if (!(error instanceof SyntaxError)) throw error; complete = false; }
+  const parsed = parseDroidTranscript(text, settings, id);
+  return { ...parsed, complete: parsed.complete && complete, transcript_path: file, source_sha256: createHash("sha256").update(text).digest("hex") };
+}
+const terminal = value => ["completed", "cancelled", "failed", "process_exit", "error"].includes(value);
+const status = value => value === "completed" ? "completed" : ["cancelled", "process_exit"].includes(value) ? "cancelled" : ["failed", "error"].includes(value) ? "failed" : "unknown";
+
+export function droidTerminalFailure(outcome, sessionId, settled) {
+  if (!["failed", "error"].includes(outcome?.reason) || !outcome.error || typeof outcome.error !== "object") return null;
+  const code = classifyProviderError(outcome.error);
+  if (code === "provider_failed") return null;
+  const turnId = outcome.turnId;
+  return Object.assign(new DroidError(code, "Droid native provider request failed", {
+    provider_session_id: sessionId, session_id: sessionId, turn_id: turnId, native_turn_id: turnId,
+    terminal_status: "failed", native_source: "droid.agent_turn_outcome", observed_at: new Date().toISOString(),
+    provider_error: safeProviderError(outcome.error), will_retry: outcome.error.willRetry === true, native_retry_active: outcome.error.willRetry === true,
+    native_turn_items: { observed: settled === true, possible_effects: true, pending: settled !== true }
+  }), { retryable: ["provider_capacity_transient", "provider_rate_limited", "provider_network_transient"].includes(code) });
+}
+
+
+function descendants(rows, rootPid) { const ids = new Set([rootPid]); for (;;) { const size = ids.size; for (const row of rows) if (ids.has(row.ppid)) ids.add(row.pid); if (size === ids.size) return rows.filter(row => ids.has(row.pid)); } }
+
+export class DroidRuntime {
+  constructor(config, state, persist) {
+    this.config = config; this.state = state; this.paths = droidPaths(config.stateDir); this.persist = persist; this.pending = new Map(); this.lateResponses = new Map(); this.active = null; this.child = null; this.closed = true; this.loaded = false; this.ownedProcesses = state.owned_processes ?? []; this.closing = false; this.workingState = "idle"; this.protocol = null; this.rootId = state.root_session_id ?? null; this.topology = new Map(state.descendants?.map(child => [child.provider_session_id, child]) ?? []); this.nativeCreatorTurns = new Map(); this.draining = Promise.resolve(); this.journalling = Promise.resolve(); this.activity = 0; this.providerProcess = null; this.cancelled = false; this.lastResult = state.last_result ?? null; this.metadata = metadataReader(this.paths.factory); this.fatalError = state.fatal_error ? reportedError(state.fatal_error) : null;
+  }
+  async journal(kind, payload) { const line = JSON.stringify({ schema_id: "dd-droid/event@1", observed_at: new Date().toISOString(), kind, ...payload }); this.journalling = this.journalling.then(() => appendFile(this.config.journal, `${line}\n`, { mode: 0o600 })); return await this.journalling; }
+  async save(patch = {}) { return await this.persist({ root_session_id: this.rootId, sessions: this.rootId ? [this.rootId] : [], descendants: [...this.topology.values()], working_state: this.workingState, last_activity: this.activity, ...patch }); }
+  async start() {
+    if (this.child && !this.closed) return;
+    this.closed = false; this.loaded = false; this.closing = false; this.protocol = null; this.buffer = "";
+    const args = ["exec", "--input-format", "stream-jsonrpc", "--output-format", "stream-jsonrpc"];
+    const target = executable(this.config.bin, args);
+    this.providerProcess = await registerDaemonProcess(this.config, { kind: "droid-provider", owner: `droid:${this.config.daemonId}`, operation: `droid-provider:${randomUUID()}`, stdout: this.paths.log, stderr: this.paths.log });
+    this.child = spawn(target.command, target.args, { cwd: this.config.cwd, env: droidEnvironment(this.config), detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    const observationFailure = async error => {
+      if (error.code === "operation_observation_lost") { this.observationError = error; this.rejectPending(error); return; }
+      await this.handleObservationError(error); if (!this.fatalError) this.rejectPending(error);
+    };
+    this.nativeDrain = readNativeLines(this.child.stdout, line => this.draining = this.event(JSON.parse(line)), observationFailure);
+    this.diagnostics = streamNativeDiagnostics(this.child.stderr, chunk => this.journal("stderr", { text: chunk }), observationFailure);
+    this.child.on("error", error => this.rejectPending(error));
+    this.child.on("close", (code, signal) => { this.closed = true; void Promise.all([this.nativeDrain, this.diagnostics]).finally(() => { const error = new DroidError("operation_observation_lost", "Droid process exited before a confirmed reply", { code, signal }); this.rejectPending(error); }); });
+    await this.captureProcesses(); await confirmDaemonProcess(this.config, this.providerProcess, this.child); scheduleDaemonProcessHeartbeat(this.config, this.providerProcess); await this.save({ provider_pid: this.child.pid, provider_process: this.providerProcess });
+    clearInterval(this.processObserver);
+    this.processObserver = setInterval(() => { if (!this.processObservation) this.processObservation = this.captureProcesses().catch(error => { this.ownershipError = error; }).finally(() => { this.processObservation = null; }); }, 1_000);
+    this.processObserver.unref();
+    const models = await this.request("droid.list_models", {});
+    if (this.protocol !== DROID_PROTOCOL) throw new DroidError("droid_protocol_mismatch", "Unqualified Factory protocol", { expected: DROID_PROTOCOL, observed: this.protocol });
+    this.models = models.models ?? [];
+    clearInterval(this.modelObserver);
+    this.modelObserver = setInterval(() => {
+      if (!this.loaded || this.closing || this.modelObservation) return;
+      this.modelObservation = this.observeModels().catch(error => this.handleObservationError(error)).finally(() => { this.modelObservation = null; });
+    }, 2_000);
+    this.modelObserver.unref();
+  }
+  rejectPending(error) { for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); } this.pending.clear(); if (this.active && !this.closing) this.active.reject(error); }
+  async event(event) {
+    await this.journal("native", { event });
+    if (event.type === "response") {
+      this.protocol ??= event.factoryProtocolVersion;
+      const pending = this.pending.get(event.id); if (!pending) { this.lateResponses.set(event.id, event); while (this.lateResponses.size > 128) this.lateResponses.delete(this.lateResponses.keys().next().value); await this.journal("late_response", responseSummary(event)); return; }
+      this.pending.delete(event.id); clearTimeout(pending.timer);
+      if (pending.timedOut) await this.journal("late_response", { ...responseSummary(event), method: pending.method, grace_ms: LATE_RESPONSE_GRACE_MS });
+      event.error ? pending.reject(new DroidError("droid_rpc_error", event.error.message ?? "Droid rejected request", event.error)) : pending.resolve(event.result ?? {}); return;
+    }
+    if (event.method === "droid.request_permission" || event.method === "droid.ask_user") {
+      const result = event.method === "droid.request_permission" ? { selectedOption: "cancel" } : { cancelled: true, answers: [] };
+      this.send({ jsonrpc: "2.0", type: "response", factoryApiVersion: "1.0.0", factoryProtocolVersion: DROID_PROTOCOL, id: event.id, result });
+      await this.journal("unexpected_input_rejected", { method: event.method }); return;
+    }
+    if (event.method !== "droid.session_notification") return;
+    const { sessionId, notification: n } = event.params ?? {}; if (!n) return;
+    const fingerprint = createHash("sha256").update(JSON.stringify(event.params)).digest("hex");
+    if (sessionId && this.rootId && sessionId !== this.rootId && !this.topology.has(sessionId)) throw new DroidError("session_identity_mismatch", "Unrelated native Session notification");
+    const current = this.active;
+    let currentGuarded = Boolean(current && typeof current.guard === "function");
+    try { if (currentGuarded) current.guard(); } catch { currentGuarded = false; }
+    const scoped = currentGuarded && sessionId && (sessionId === this.rootId || this.topology.get(sessionId)?.operation_id === current.operationId)
+      && (!n.turnId || n.turnId === current.turnId) && (!n.requestId || n.requestId === current.requestId);
+    let productive = ["assistant_text_delta", "assistant_thought_delta"].includes(n.type) && Boolean(n.textDelta ?? n.thoughtDelta)
+      || ["agent_turn_completed", "create_message"].includes(n.type);
+    if (scoped && ["agent_turn_completed", "create_message"].includes(n.type)) {
+      current.lifecycleProgress ??= new Set();
+      const key = JSON.stringify([sessionId, n.type, n.requestId ?? null, n.turnId ?? null, n.message?.id ?? null]);
+      if (current.lifecycleProgress.has(key)) productive = false;
+      else {
+        if (current.lifecycleProgress.size >= 1_024) current.lifecycleProgress.delete(current.lifecycleProgress.values().next().value);
+        current.lifecycleProgress.add(key);
+      }
+    }
+    if (scoped && ["tool_call_started", "tool_call_update", "tool_call_completed"].includes(n.type)) {
+      const toolId = n.toolUseId ?? n.toolCallId ?? n.toolCall?.id;
+      current.toolProgress ??= new Set();
+      const key = `${sessionId}:${toolId}`, semantic = JSON.stringify({ type: n.type, toolCall: n.toolCall, status: n.status, input: n.input, output: n.output, content: n.content, error: n.error });
+      // Keep fixed-size fingerprints, not 1,024 copies of growing tool output.
+      const snapshot = createHash("sha256").update(JSON.stringify([key, semantic])).digest("hex");
+      if (toolId && !current.toolProgress.has(snapshot)) {
+        productive = n.type !== "tool_call_update" || n.status !== undefined || n.output !== undefined || n.content !== undefined || n.toolCall !== undefined || n.error !== undefined;
+        if (productive) {
+          // ponytail: retain the latest 1,024 snapshots for replay detection,
+          // not a lifetime progress quota. Native sequence IDs can extend proof.
+          if (current.toolProgress.size >= 1_024) current.toolProgress.delete(current.toolProgress.values().next().value);
+          current.toolProgress.add(snapshot);
+        }
+      }
+    }
+    if (scoped && productive) {
+      this.activity += 1; this.progress = { cursor: this.activity, observed_at: Date.now() };
+      const pending = this.pending.get(current.requestId);
+      if (pending?.method === "droid.add_user_message") {
+        pending.progress = this.progress;
+      }
+      await current.publish?.("native_progress", { native_request_id: String(current.requestId), session_id: this.rootId, observed_at: new Date(this.progress.observed_at).toISOString() });
+    }
+    if (n.type === "droid_working_state_changed" && (!sessionId || sessionId === this.rootId)) this.workingState = n.newState;
+    if (n.type === "child_session_available") {
+      if (!this.rootId || sessionId !== this.rootId || !n.childSessionId || !n.toolUseId) throw new DroidError("droid_child_identity_invalid", "Native child event lacks physical parent or tool identity");
+      // A notification may arrive after another prompt starts. Session and
+      // child identity alone do not identify the originating operation.
+      const byTurn = typeof n.turnId === "string" && n.turnId ? this.nativeCreatorTurns.get(`turn:${n.turnId}`) : null;
+      const byRequest = typeof n.requestId === "string" && n.requestId ? this.nativeCreatorTurns.get(`request:${n.requestId}`) : null;
+      const candidate = byTurn ?? byRequest ?? current;
+      const exact = candidate && (typeof n.turnId === "string" && n.turnId && n.turnId === candidate.turnId
+        || typeof n.requestId === "string" && n.requestId && n.requestId === candidate.requestId)
+        && (!n.turnId || n.turnId === candidate.turnId) && (!n.requestId || n.requestId === candidate.requestId)
+        && (!byTurn || !byRequest || byTurn === byRequest);
+      const previous = this.topology.get(n.childSessionId), sameTool = previous?.tool_use_id === n.toolUseId;
+      if (previous && ((previous.parent_provider_session_id && previous.parent_provider_session_id !== sessionId)
+        || previous.tool_use_id && !sameTool))
+        throw new DroidError("droid_child_identity_invalid", "Native child parent or creation tool contradicts the retained identity");
+      const retainedCreator = sameTool ? previous.creator_operation_id ?? previous.operation_id : null;
+      if (retainedCreator && exact && retainedCreator !== candidate.operationId)
+        throw new DroidError("droid_child_identity_invalid", "Native child creator contradicts the retained operation");
+      let proven = Boolean(exact && typeof candidate.guard === "function");
+      try { if (proven) candidate.guard(); } catch { proven = false; }
+      const creator = retainedCreator || (proven ? candidate.operationId : null);
+      this.topology.set(n.childSessionId, { ...(previous ?? {}), provider_session_id: n.childSessionId, parent_provider_session_id: sessionId, tool_use_id: n.toolUseId,
+        creator_operation_id: creator, operation_id: previous?.latest_tool_use_id && previous.latest_tool_use_id !== n.toolUseId ? null : creator,
+        status: "running", source: "droid.child_session_available" }); await this.save();
+    }
+    if (n.type === "settings_updated" && this.loaded) await this.observeSettings(sessionId ?? this.rootId, n.settings, { kind: "native.settings_updated", event_sha256: fingerprint });
+    if (n.type === "create_message" && n.requestId === current?.requestId) {
+      if (n.message?.id !== current.turnId) throw new DroidError("droid_turn_identity_mismatch", "Droid did not preserve the requested message ID");
+      current.accepted = true; await this.saveBinding(current, { accepted: true });
+    }
+    if (n.type === "assistant_text_delta" && scoped && sessionId === this.rootId) current.text += n.textDelta ?? "";
+    if (n.type === "agent_turn_completed" && current && n.turnId === current.turnId && (!sessionId || sessionId === this.rootId)) {
+      current.outcome = n; this.lastResult = n; await this.saveBinding(current, { native_outcome: n, assistant_text: current.text }); current.resolve(n);
+      if (current.observerReturned && this.active === current) { this.active = null; await this.save({ active_tree: this.workingState !== "idle" }); }
+    }
+  }
+  request(method, params, id = randomUUID(), timeoutMs = 30_000) {
+    if (!this.child || this.closed) return Promise.reject(new DroidError("operation_observation_lost", "Droid runtime is not connected"));
+    return new Promise((resolve, reject) => {
+      const timer = observedTimeout(() => {
+        const pending = this.pending.get(id); if (!pending || pending.timedOut) return;
+        pending.timedOut = true;
+        const timeoutError = new DroidError("rpc_timeout", `${method} has no observed reply`, { request_id: id, timeout_ms: timeoutMs, grace_ms: LATE_RESPONSE_GRACE_MS });
+        void this.journal("request_deadline", { method, request_id: id, timeout_ms: timeoutMs, grace_ms: LATE_RESPONSE_GRACE_MS });
+        pending.timer = observedTimeout(() => { if (this.pending.get(id) !== pending) return; this.pending.delete(id); reject(timeoutError); }, LATE_RESPONSE_GRACE_MS, { progress: () => pending.progress });
+      }, timeoutMs, { progress: () => this.pending.get(id)?.progress });
+      this.pending.set(id, { resolve, reject, timer, method });
+      try { this.send({ jsonrpc: "2.0", type: "request", factoryApiVersion: "1.0.0", factoryProtocolVersion: DROID_PROTOCOL, id, method, params }, error => { if (error) { clearTimeout(timer); this.pending.delete(id); reject(nativeObservationError(error)); } }); }
+      catch (error) { clearTimeout(timer); this.pending.delete(id); reject(nativeObservationError(error)); }
+    });
+  }
+  send(value, callback) {
+    const stdin = this.child?.stdin;
+    if (!stdin || stdin.destroyed) {
+      const error = new DroidError("bridge_pipe_broken", "Droid runtime stdin is closed");
+      this.rejectPending(error);
+      throw error;
+    }
+    try { stdin.write(`${JSON.stringify(value)}\n`, callback); }
+    catch (cause) { const error = nativeObservationError(cause); this.rejectPending(error); throw error; }
+  }
+  profile(settings) {
+    const model = settings?.modelId ?? settings?.model ?? null;
+    const nativeModel = this.models?.find(item => (item.id ?? item.modelId) === model);
+    const result = { provider: settings?.provider ?? nativeModel?.provider ?? null, model, reasoning: settings?.reasoningEffort ?? null, mode: settings?.autonomyMode ?? (settings?.autonomyLevel ? `auto-${settings.autonomyLevel}` : null) };
+    checkObservedProfile(this.config, result, { required: this.config.mode ? ["mode"] : [] });
+    return result;
+  }
+  async observeSettings(id, settings, source, extra = {}) {
+    const observed = this.profile(settings);
+    const event = await observeModel({ journal: this.config.journal, harness: "droid-cli", sessionId: id, parentSessionId: id === this.rootId ? null : this.topology.get(id)?.parent_provider_session_id ?? this.rootId,
+      requested: this.config, observed, source, ...extra });
+    if (id === this.rootId) this.observedProfile = observed;
+    this.modelEventIds ??= new Map();
+    if (event && this.modelEventIds.get(id) !== event.id) {
+      this.modelEventIds.set(id, event.id);
+      await this.save({ model_observation: { last_event_id: event.id, observed_at: event.observed_at } });
+    }
+    return observed;
+  }
+  validateMetadata(id, native) {
+    const parent = native?.header.callingSessionId;
+    if (!native || path.resolve(native.header.cwd) !== this.config.cwd || native.header.id !== id || (id !== this.rootId && (id === parent || parent !== this.rootId && !this.topology.has(parent) || this.topology.has(id) && this.topology.get(id).parent_provider_session_id !== parent))) throw new DroidError("session_identity_mismatch", "Native model observation is outside the owned Session tree");
+    if (id !== this.rootId && !this.topology.has(id)) this.topology.set(id, { provider_session_id: id, parent_provider_session_id: parent, tool_use_id: native.header.callingToolUseId, status: "unknown", source: "native.metadata" });
+  }
+  async observeModels() {
+    if (!this.rootId || !this.loaded) return;
+    const catalog = path.join(this.paths.factory, "task-invocations.json");
+    const info = await stat(catalog).catch(error => { if (error.code === "ENOENT") return null; throw error; });
+    if (info && info.mtimeMs !== this.modelCatalogMtime) {
+      const value = await readJson(catalog);
+      const tasks = Array.isArray(value?.invocations) ? value.invocations : [];
+      for (let size = -1; size !== this.topology.size;) { size = this.topology.size;
+        for (const task of tasks) if (task?.childSessionId && (task.parentSessionId === this.rootId || this.topology.has(task.parentSessionId))) {
+          const native = await this.metadata.read(task.childSessionId);
+          if (native) this.validateMetadata(task.childSessionId, native);
+        }
+      }
+      this.modelCatalogMtime = info.mtimeMs;
+    }
+    const log = path.join(this.paths.factory, "logs", "droid-log-single.log");
+    const routing = await readDroidRoutingLog(log, this.state.model_log_cursor);
+    for (const transition of routing.events) {
+      const native = await this.metadata.read(transition.session_id);
+      if (!native || (transition.session_id !== this.rootId && native.header.callingSessionId !== this.rootId && !this.topology.has(native.header.callingSessionId))) continue;
+      this.validateMetadata(transition.session_id, native);
+      await this.observeSettings(transition.session_id, { ...native.settings, modelId: transition.model, model: transition.model },
+        { path: log, channel: "native_router", event_sha256: transition.event_sha256 }, { reason: transition.reason, nativeTimestamp: transition.native_timestamp, previousModel: transition.previous_model });
+    }
+    await this.save({ model_log_cursor: routing.cursor });
+    for (const id of [this.rootId, ...this.topology.keys()]) {
+      const native = await this.metadata.read(id);
+      if (!native) {
+        await observeModel({ journal: this.config.journal, harness: "droid-cli", sessionId: id, requested: this.config, source: "native.settings", evidence: "unavailable", reason: "settings_missing_or_partial" });
+        continue;
+      }
+      this.validateMetadata(id, native);
+      await this.observeSettings(id, native.settings, native.source);
+    }
+  }
+  async handleObservationError(error) {
+    if (error.code === "model_observation_storage_failed") {
+      this.observationError = Object.assign(new Error("Droid model observation could not be published", { cause: error }), { code: "operation_observation_lost", details: { native_outcome: "unknown", observation_error: errorRecord(error) } });
+      this.rejectPending(this.observationError);
+      return;
+    }
+    if (["profile_integrity_violation", "session_identity_mismatch", "droid_child_identity_invalid", "droid_turn_identity_mismatch", "droid_hook_identity_invalid"].includes(error.code)) {
+      if (!this.fatalError) {
+        this.fatalError = error;
+        try { await this.save({ fatal_error: errorRecord(error) }); await this.journal("integrity_failure", { error: errorRecord(error) }); }
+        finally {
+          this.rejectPending(error);
+          // Never await cleanup from the native event drain: closeTree waits for it.
+          setTimeout(() => { void this.closeTree(true).catch(cleanup => this.save({ cleanup_error: errorRecord(cleanup) }).catch(() => {})); }, 0);
+        }
+      }
+      return;
+    }
+    try { await observeModel({ journal: this.config.journal, harness: "droid-cli", sessionId: this.rootId, requested: this.config, source: "native.observer", evidence: "unavailable", reason: error.code ?? "observation_unavailable" }); }
+    catch (failure) { await this.handleObservationError(Object.assign(new Error(`Cannot persist model observation: ${failure.message}`), { code: "model_observation_storage_failed" })); }
+  }
+  async saveBinding(binding, patch = {}) { Object.assign(binding.saved, patch); await writeJsonAtomic(path.join(this.paths.bindings, `${createHash("sha256").update(binding.operationId).digest("hex")}.json`), binding.saved); }
+  async create(operationId) {
+    if (this.rootId) throw new DroidError("session_already_created", "This execution daemon already owns a root Session");
+    await this.start(); const sessionId = randomUUID(); this.rootId = sessionId; const requestId = randomUUID();
+    const binding = { operationId, saved: { operation: "session.create", provider_session_id: sessionId, request_id: requestId } }; await this.saveBinding(binding);
+    const result = await this.request("droid.initialize_session", { machineId: "dd-eval", cwd: this.config.cwd, sessionId, modelId: this.config.model, reasoningEffort: this.config.reasoning, interactionMode: "auto", autonomyLevel: "high", autoRejectPermissionRequests: true, disableBuiltinSkills: true, disabledToolIds: ["AskUser"], mcpServers: [], systemPrompt: { type: "preset", preset: "droid", append: `${renderAdapterPolicy({ harness: "droid-cli" })} Use the same worker for technical capacity markers and separately declared productive Work. Never delegate an already-bound coordinator or Stage Work through Task: execute it in this root Session. A productive Task must receive the runner's exact work start command and may execute only that child Work; otherwise it must stop. User clarification belongs to the root coordinator through dd-flow stage pause, not native AskUser. At a work_fanout boundary, stop when the launcher says runner dispatches and wait for the runner's next instruction. Never use Missions.` } }, requestId);
+    if (result.sessionId !== sessionId) throw new DroidError("session_identity_mismatch", "Droid initialized a different Session");
+    this.rootId = result.sessionId; this.loaded = true; this.observedProfile = await this.observeSettings(this.rootId, result.settings, "native.initialize_session"); this.workingState = "idle"; await this.save();
+    return await this.inspect(sessionId);
+  }
+  requireIdentity(id) { if (!id || id !== this.rootId) throw new DroidError("session_identity_mismatch", "Requested root Session is not owned by this daemon", { requested: id ?? null, observed: this.rootId }); }
+  async resume(id) {
+    this.requireIdentity(id); if (this.state.cleanup?.forced) throw new DroidError("invalid_harness_crash", "Forced teardown is unclean; same-ID resume is not qualified for this execution"); if (this.closed && (await this.captureProcesses()).length) throw new DroidError("tree_not_settled", "Previous provider still owns processes; cancel the tree before resume"); if (!this.closed && this.loaded) return await this.inspect(id);
+    await this.start(); const result = await this.request("droid.load_session", { sessionId: id, loadAllMessages: false, autoRejectPermissionRequests: true, disableBuiltinSkills: true, disabledToolIds: ["AskUser"], mcpServers: [] });
+    const source = await readDroidSession(this.paths.factory, id); if (!source || path.resolve(source.header.cwd) !== this.config.cwd) throw new DroidError("session_identity_mismatch", "Resumed Session does not match its controlled workspace");
+    this.loaded = true; this.observedProfile = await this.observeSettings(id, result.settings, "native.load_session"); this.workingState = result.workingState ?? (result.isAgentLoopInProgress ? "unknown" : "idle"); this.cancelled = false; await this.save(); return await this.inspect(id);
+  }
+  async prompt(id, prompt, operationId, livenessTimeoutMs = this.config.inactivityMs ?? 600_000) {
+    validateObservationDuration(livenessTimeoutMs);
+    const assertDispatch = captureDispatchGuard(this);
+    if (this.fatalError) throw this.fatalError;
+    this.requireIdentity(id); if (!prompt) throw new DroidError("prompt_required", "prompt is required"); if (this.active) throw new DroidError("operation_busy", "Another Droid operation is active");
+    if (this.closed || !this.loaded) await this.resume(id);
+    if (this.ownershipError) throw new DroidError("process_ownership_unknown", "Owned process observation failed", { error: errorRecord(this.ownershipError) });
+    const before = await this.inspect(id); if (!before.settled) throw new DroidError("tree_not_settled", "Prior Droid tree has not settled");
+    let resolve, reject; const completed = new Promise((a, b) => { resolve = a; reject = b; }); void completed.catch(() => {});
+    const requestId = randomUUID(), turnId = randomUUID();
+    const current = { operationId, requestId, turnId, sessionId: id, generation: (this.state.hook_generation ?? 0) + 1, resolve, reject, guard: assertDispatch, text: "", publish: operationProgressReporter(), saved: { operation: "session.prompt", provider_session_id: id, request_id: requestId, turn_id: turnId, accepted: false } };
+    this.state.hook_generation = current.generation; this.lastNativeHookOperation = current;
+    this.active = current; this.cancelled = false; await this.saveBinding(current); await this.save({ active_tree: true });
+    const creator = { operationId, turnId, requestId, guard: assertDispatch };
+    this.nativeCreatorTurns.set(`turn:${turnId}`, creator); this.nativeCreatorTurns.set(`request:${requestId}`, creator);
+    const clock = new ObservationClock({ timeoutMs: livenessTimeoutMs, onGap: gap => { void this.journal("observation_gap", { gap }).catch(() => {}); } });
+    let checkingTerminal = false;
+    const timer = setInterval(() => {
+      if (checkingTerminal || !clock.sample(this.progress)) return;
+      checkingTerminal = true;
+      const cursor = this.progress?.cursor;
+      void this.recoverOperation(operationId).then(() => {
+        if (this.active === current && !current.outcome && this.progress?.cursor === cursor && clock.sample(this.progress)) reject(new DroidError("operation_observation_lost", "Droid native outcome remains unknown after its silence window", { operation_id: operationId, native_outcome: "unknown" }));
+      }).catch(error => reject(new DroidError("operation_observation_lost", "Cannot reconcile native outcome before declaring inactivity", { error: errorRecord(error) }))).finally(() => { checkingTerminal = false; });
+    }, Math.max(10, Math.min(1_000, livenessTimeoutMs / 4)));
+    let primary;
+    try {
+      assertDispatch();
+      current.dispatched = true;
+      await this.request("droid.add_user_message", { text: prompt, messageId: turnId }, requestId);
+      try { await this.journal("native_dispatch", { operation_id: operationId, provider_session_id: id, native_request_id: requestId }); }
+      catch (cause) {
+        const error = nativeObservationError(cause);
+        if (!current.outcome || error.code !== "operation_observation_lost") throw error;
+        throw Object.assign(new Error("Droid completed natively but its dispatch journal could not be saved", { cause }), {
+          code: "native_outcome_observation_failed", details: { native_outcome: { provider_session_id: id, turn_id: turnId, result: current.outcome }, settled: false, observation_error: errorRecord(error) }
+        });
+      }
+      const outcome = await completed; await this.draining;
+      let receipt;
+      try {
+        receipt = await this.inspect(id, { ignoreActive: true });
+      } catch (error) {
+        // A terminal native outcome is durable independently of a later
+        // filesystem/topology observation.  Preserve it and let settlement
+        // reconcile; do not convert it into a failed prompt.
+        return { provider_session_id: id, adapter_session_id: id, result: { ...outcome, status: status(outcome.reason) }, assistant_text: current.text, turn_id: turnId, settled: false, settlement_observation_error: errorRecord(error), ...(current.hookDiagnostics?.length ? { native_hook_diagnostics: current.hookDiagnostics } : {}) };
+      }
+      const providerFailure = droidTerminalFailure(outcome, id, receipt.settled);
+      if (providerFailure) throw providerFailure;
+      return { ...receipt, result: { ...outcome, status: status(outcome.reason) }, assistant_text: current.text, turn_id: turnId, ...(current.hookDiagnostics?.length ? { native_hook_diagnostics: current.hookDiagnostics } : {}) };
+    } catch (error) {
+      if (current.outcome && isObservationLoss(error)) error = Object.assign(new Error("Droid completed natively but its dispatch acknowledgement was lost", { cause: error }), {
+        code: "native_outcome_observation_failed", details: { native_outcome: { provider_session_id: id, turn_id: turnId, result: current.outcome }, settled: false, observation_error: errorRecord(error) }
+      });
+      primary = error;
+      try { await this.journal("prompt_error", { operation_id: operationId, error: errorRecord(error) }); }
+      catch (publication) { error.cleanup_error ??= errorRecord(publication); }
+      throw error;
+    } finally {
+      clearInterval(timer); current.observerReturned = true;
+      if (this.active === current && (current.outcome || !current.dispatched)) this.active = null;
+      try { await this.save({ active_tree: Boolean(this.active) || this.workingState !== "idle" }); }
+      catch (publication) {
+        if (primary) primary.cleanup_error ??= errorRecord(publication);
+        else throw Object.assign(new Error("Droid outcome bookkeeping could not be published", { cause: publication }), { code: current.outcome ? "native_outcome_observation_failed" : "operation_observation_lost", details: { native_outcome: current.outcome ?? "unknown", observation_error: errorRecord(publication) } });
+      }
+    }
+  }
+  async recoverOperation(operationId) {
+    const binding = await readJson(path.join(this.paths.bindings, `${createHash("sha256").update(operationId).digest("hex")}.json`));
+    if (!binding || binding.operation !== "session.prompt") return null;
+    this.requireIdentity(binding.provider_session_id);
+    const native = await readDroidSession(this.paths.factory, binding.provider_session_id);
+    const outcome = native?.outcomes.find(item => item.turnId === binding.turn_id);
+    if (!outcome || !terminal(outcome.reason)) return null;
+    let receipt;
+    try { receipt = await this.inspect(binding.provider_session_id, { ignoreActive: true }); }
+    catch (error) {
+      receipt = { provider_session_id: binding.provider_session_id, adapter_session_id: binding.provider_session_id, settled: false, settlement_observation_error: errorRecord(error) };
+    }
+    const failure = droidTerminalFailure(outcome, binding.provider_session_id, receipt.settled);
+    if (failure) throw failure;
+    // Native outcome and tree settlement are independent. Retain the former
+    // even while children are running; settled:false keeps capacity reserved.
+    const current = this.active;
+    if (current?.operationId === operationId && current.turnId === binding.turn_id) {
+      current.outcome = outcome; this.lastResult = outcome;
+      await this.saveBinding(current, { native_outcome: outcome });
+      current.resolve(outcome);
+      if (current.observerReturned) {
+        if (this.active === current) this.active = null;
+        await this.save({ active_tree: this.workingState !== "idle" });
+        return { ...receipt, result: { ...outcome, status: status(outcome.reason) }, assistant_text: binding.assistant_text ?? "", turn_id: binding.turn_id, recovered_from: "native.agent_turn_outcome" };
+      }
+      // Let the original dispatch persist its one terminal reply. Settlement
+      // is reconciled separately; do not race a second writer or replay it.
+      return null;
+    }
+    return { ...receipt, result: { ...outcome, status: status(outcome.reason) }, assistant_text: binding.assistant_text ?? "", turn_id: binding.turn_id, recovered_from: "native.agent_turn_outcome" };
+  }
+  async refreshTopology() {
+    let catalog, missing = false;
+    try { catalog = JSON.parse(await readFile(path.join(this.paths.factory, "task-invocations.json"), "utf8")); }
+    catch (error) { if (error.code === "ENOENT") missing = true; else { if (!(error instanceof SyntaxError)) throw error; this.topologyIncomplete = true; return [...this.topology.values()]; } }
+    this.topologyIncomplete = false;
+    const root = this.rootId ? await readDroidSession(this.paths.factory, this.rootId) : null;
+    const taskTools = native => new Map((native?.records ?? []).flatMap(record => record.message?.content ?? []).filter(block => block.type === "tool_use" && block.name === "Task").map(block => [block.id, block]));
+    const validCatalog = catalog && !Array.isArray(catalog) && Array.isArray(catalog.invocations);
+    if (!validCatalog) {
+      const noChildren = !this.topology.size && !taskTools(root).size;
+      const noDispatch = !this.active && !this.lastResult && !this.state.active_tree && (!root || root.complete && root.records.every(record => record.type === "session_start"));
+      const completeNoTask = root?.complete && terminal(root.outcomes.at(-1)?.reason) && root.tool_calls.completeness === "complete";
+      this.topologyIncomplete = !(missing && noChildren && (noDispatch || completeNoTask));
+      return [...this.topology.values()];
+    }
+    const invocations = catalog.invocations, owned = new Set([this.rootId, ...this.topology.keys()]);
+    // Resolve ancestry before validating records so malformed foreign entries
+    // do not block this tree, while malformed reachable children do.
+    for (let size = -1; size !== owned.size;) { size = owned.size; for (const task of invocations) if (owned.has(task?.parentSessionId) && task?.childSessionId) owned.add(task.childSessionId); }
+    const parents = new Map([[this.rootId, root]]);
+    for (const id of owned) if (id !== this.rootId) parents.set(id, await readDroidSession(this.paths.factory, id));
+    for (const [parentId, native] of parents) {
+      if (!native?.complete) this.topologyIncomplete = true;
+      for (const toolId of taskTools(native).keys()) if (!invocations.some(task => task?.parentSessionId === parentId && task?.parentToolUseId === toolId)) this.topologyIncomplete = true;
+    }
+    const groups = new Map();
+    for (const task of invocations) {
+      if (!task || typeof task !== "object") { this.topologyIncomplete = true; continue; }
+      if (!owned.has(task.parentSessionId) && !owned.has(task.childSessionId) && ![...parents.values()].some(native => taskTools(native).has(task.parentToolUseId))) continue;
+      if (![task.parentSessionId, task.childSessionId, task.parentToolUseId, task.taskInvocationId, task.status].every(value => typeof value === "string" && value.length)) { this.topologyIncomplete = true; continue; }
+      const tasks = groups.get(task.childSessionId) ?? []; tasks.push(task); groups.set(task.childSessionId, tasks);
+    }
+    for (const id of this.topology.keys()) if (!groups.has(id)) this.topologyIncomplete = true;
+    for (const [id, tasks] of groups) {
+      const native = parents.get(id), parentId = tasks[0].parentSessionId, rootTools = taskTools(parents.get(parentId));
+      if (!native || !native.settings) { this.topologyIncomplete = true; continue; }
+      if (id === this.rootId || id === parentId || tasks.some(task => task.parentSessionId !== parentId) || native.header.callingSessionId !== parentId || path.resolve(native.header.cwd) !== this.config.cwd) throw new DroidError("droid_child_identity_invalid", "Task invocation disagrees with physical child parent/workspace");
+      if (new Set(tasks.map(task => task.taskInvocationId)).size !== tasks.length) this.topologyIncomplete = true;
+      const creationTool = native.header.callingToolUseId;
+      for (const task of tasks) {
+        if (!rootTools.has(task.parentToolUseId)) {
+          const block = (parents.get(parentId)?.records ?? []).flatMap(record => record.message?.content ?? []).find(block => block.type === "tool_use" && block.id === task.parentToolUseId);
+          if (block) throw new DroidError("droid_child_identity_invalid", "Task invocation is bound to a non-Task tool");
+          this.topologyIncomplete = true; continue;
+        }
+        if (task.parentToolUseId === creationTool) continue;
+        const tool = rootTools.get(task.parentToolUseId);
+        if (tool?.name !== "Task" || tool.input?.resume !== id) throw new DroidError("droid_child_identity_invalid", "Repeated child invocation has no matching native Task resume evidence");
+      }
+      await this.observeSettings(id, native.settings, { path: native.transcript_path, sha256: native.source_sha256 });
+      // Task resume adds a Turn to the same physical child, not another
+      // Session. Its transcript retains the original creation edge. Work
+      // reassignment is checked by dd-flow's physical Session binding.
+      const order = [...rootTools.keys()];
+      const ordered = tasks.toSorted((a, b) => order.indexOf(a.parentToolUseId) - order.indexOf(b.parentToolUseId));
+      const latest = ordered.at(-1); const running = !terminal(latest.status);
+      const outcome = native.outcomes.at(-1), nativeTurn = outcome && terminal(outcome.reason) && typeof outcome.turnId === "string" ? outcome.turnId : null;
+      const parentResult = (parents.get(parentId)?.records ?? []).flatMap(record => record.message?.content ?? []).some(block => block.type === "tool_result" && block.tool_use_id === latest.parentToolUseId);
+      const exactTurn = nativeTurn && (tasks.length === 1 || latest.turnId === nativeTurn);
+      // A resumed Task's previous terminal Turn is not its current outcome.
+      // The matching native Task result proves completion without attributing
+      // a previous error/Turn ID to this invocation.
+      const evidence = !running && nativeTurn && (tasks.length === 1 || parentResult || exactTurn) ? {
+        ...(exactTurn ? { terminal_turn_id: nativeTurn } : {}), native_source: "droid.agent_turn_outcome",
+        native_turn_items: { observed: native.complete && native.tool_calls.completeness === "complete", possible_effects: native.tool_calls.total > 0, pending: native.tool_calls.pending > 0 },
+        ...(exactTurn && outcome.error && typeof outcome.error === "object" ? { provider_error: safeProviderError(outcome.error) } : {}) } : {};
+      const previous = this.topology.get(id);
+      if (previous && (previous.parent_provider_session_id && previous.parent_provider_session_id !== parentId
+        || previous.tool_use_id && previous.tool_use_id !== creationTool))
+        throw new DroidError("droid_child_identity_invalid", "Native task inventory contradicts the retained child creation edge");
+      const creator = previous?.creator_operation_id ?? (previous?.latest_tool_use_id && previous.latest_tool_use_id !== creationTool ? null : previous?.operation_id) ?? null;
+      this.topology.set(id, { provider_session_id: id, parent_provider_session_id: parentId, tool_use_id: creationTool, latest_tool_use_id: latest.parentToolUseId,
+        creator_operation_id: creator, operation_id: latest.parentToolUseId === creationTool ? creator : null,
+        task_id: latest.taskInvocationId, task_invocation_ids: ordered.map(task => task.taskInvocationId), status: running ? "running" : status(latest.status), source: "droid.task_invocations", transcript_path: native.transcript_path, ...evidence });
+    }
+    return [...this.topology.values()];
+  }
+  async snapshotUsage(id, { ingest = true } = {}) {
+    const native = await readDroidSession(this.paths.factory, id); if (!native) return { status: "unavailable", provider_session_id: id };
+    this.journaledTools ??= new Map();
+    journalToolObservations(this.config.journal, [...native.records.flatMap(record => droidToolObservations(record, id)), ...native.tool_calls.reasons.map(reason => ({ reason }))], this.journaledTools);
+    const measured = native.usage;
+    const payload = { provider_session_id: id, daemon_id: this.config.daemonId, observed_at: new Date().toISOString(), usage_scope: "physical_session", completeness: native.complete && measured ? "complete" : "partial", usage: measured, tool_calls: native.tool_calls, source: { path: native.transcript_path, sha256: native.source_sha256 } };
+    if (ingest && measured && this.config.ddFlowBin) await this.flow("usage", "ingest", payload);
+    return { status: measured ? "measured" : "unavailable", ...payload };
+  }
+  async flow(family, command, payload, timeoutMs = 25_000) {
+    return await invokeNativeHook({ bin: this.config.ddFlowBin, args: ["droid", family, command, "--project-root", this.config.projectRoot, "--json"], payload,
+      cwd: this.config.cwd, env: droidEnvironment(this.config), home: this.config.ddFlowHome, timeoutMs });
+  }
+  async inspect(id, { ignoreActive = false, ingestUsage = true } = {}) {
+    this.requireIdentity(id); await this.captureProcesses(); const children = await this.refreshTopology(); const source = await readDroidSession(this.paths.factory, id);
+    const usage = []; for (const sessionId of [id, ...children.map(child => child.provider_session_id)]) usage.push(await this.snapshotUsage(sessionId, { ingest: ingestUsage }));
+    const settled = !this.topologyIncomplete && (!this.active || ignoreActive) && (this.closed || this.workingState === "idle") && source?.tool_calls.pending === 0 && children.every(child => terminal(child.status) && child.native_turn_items?.observed === true && child.native_turn_items.pending === false);
+    const rootSettled = source?.complete && source.tool_calls.completeness === "complete" && source.tool_calls.pending === 0 && (!this.active || ignoreActive) && (this.closed || this.workingState === "idle") && terminal((source?.outcomes?.at(-1) ?? this.lastResult)?.reason);
+    const neverPrompted = source?.complete && !this.active && !this.lastResult && source.records.every(record => record.type === "session_start");
+    const nativeSettled = Boolean(settled && (rootSettled || neverPrompted));
+    return nativeExecutionReceipt({ harness: "droid-cli", runtime_family: "droid", session: { harness_id: "droid-cli", session_id: id }, provider_session_id: id, adapter_session_id: id, cwd: this.config.cwd, observed_profile: source?.settings ? await this.observeSettings(id, source.settings, { path: source.transcript_path, sha256: source.source_sha256 }) : this.observedProfile, observed_runtime: { droid: this.config.version, factory_protocol: this.protocol ?? DROID_PROTOCOL, dd_harness_contract: DROID_CONTRACT }, status: settled ? "idle" : "running", settled, native_settled: nativeSettled, ...settledNativeTree(id, children, settled, rootSettled && !this.topologyIncomplete), terminal_turn_id: source?.outcomes?.at(-1)?.turnId ?? this.lastResult?.turnId, descendants: children, transcript_path: source?.transcript_path ?? null, usage, result: this.lastResult, provider_pid: this.closed ? null : this.child?.pid ?? null,
+      ...(this.topologyIncomplete ? { native_settlement: { confirmed: false, state: "unproven", reason: "native_task_inventory_incomplete" } } : {}) }, { daemonId: this.config.daemonId });
+  }
+  async observeHook(payload, eventId, deadlineAt = null) {
+    if (!this.config.noFlow && this.config.runtime_owner && this.config.ddFlowBin && this.rootId
+      && ["PreToolUse", "PostToolUse"].includes(payload.hook_event_name)
+      && typeof payload.tool_name === "string" && payload.tool_name && typeof payload.session_id === "string" && payload.session_id
+      && typeof eventId === "string" && eventId) {
+      if (payload.tool_name !== "Execute") return {}; // Read/Edit/etc. never carry lifecycle commands.
+      const analysis = typeof payload.tool_input?.command === "string" ? parseLifecycleCommand(payload.tool_input.command) : null;
+      // No RUN/Work receipt or native ancestry is needed for ordinary shell.
+      // Real notification progress remains source-bound in observe().
+      if (analysis?.participation === "none" && !analysis.unresolved) return {};
+    }
+    if (payload.hook_event_name === "PreToolUse" && payload.tool_name === "Execute" && this.config.runtime_owner && this.config.ddFlowBin
+      && typeof payload.session_id === "string" && payload.session_id && typeof eventId === "string" && eventId && this.rootId
+      && isStandaloneWorkStart(payload.tool_input?.command)) {
+      assertDaemonDispatch(this.paths.dir);
+      this.retainedWorkStarts ??= new Map();
+      const command = payload.tool_input?.command;
+      const accepted = await retainNativeWorkStart(this.paths.dir, { daemon_id: this.config.daemonId, source_harness: "droid-cli",
+        root_provider_session_id: this.rootId, provider_session_id: payload.session_id, parent_provider_session_id: null,
+        tool_call_id: payload.tool_use_id ?? eventId, native_tool_identity: payload.tool_use_id ? "native" : "callback_request",
+        event: "PreToolUse", native_command: command, native_cwd: payload.cwd ?? null,
+        native_payload: { schema_id: "dd-flow/droid-tool-event@1", phase: "before", event_id: eventId, tool_call_id: payload.tool_use_id ?? eventId,
+          daemon_id: this.config.daemonId, session: { provider_session_id: payload.session_id }, tool: "Execute", input: payload.tool_input,
+          transcript_path: payload.transcript_path, callback_cwd: payload.cwd } }, this.active ?? this.lastNativeHookOperation, this.retainedWorkStarts);
+      if (accepted) return {};
+    }
+    try { return await this.observeHookChecked(payload, eventId, hookBudget(23_000, deadlineAt)); }
+    catch (error) { if (error.details?.scope !== "foreign_hook") await this.handleObservationError(error); throw error; }
+  }
+  async verifyWorkStart(params) {
+    const retained = this.retainedWorkStarts?.get(params.requestId);
+    if (!retained || !isDeepStrictEqual(retained.binding, params.binding)) throw new DroidError("native_hook_unproven", "Unknown native Work start callback");
+    retained.guard();
+    const binding = retained.binding, id = binding.provider_session_id, payload = binding.native_payload;
+    if (binding.root_provider_session_id !== this.rootId) throw new DroidError("droid_hook_identity_invalid", "Native Work start root changed");
+    const report = operationProgressReporter();
+    const checkpoint = cursor => report('verification_progress', { native_request_id: cursor, session_id: id });
+    const native = await this.metadata.read(id, checkpoint);
+    if (!native || !path.isAbsolute(payload.callback_cwd ?? "") || path.resolve(payload.callback_cwd) !== this.config.cwd
+      || path.resolve(native.header.cwd) !== this.config.cwd || await realpath(payload.transcript_path) !== await realpath(native.transcript_path))
+      throw new DroidError("droid_hook_identity_invalid", "Native Work start has no verified physical Session/workspace");
+    const parent = native.header.callingSessionId ?? null, seen = new Set([id]);
+    let ancestor = parent;
+    while (ancestor && ancestor !== this.rootId) {
+      if (seen.has(ancestor)) throw new DroidError("droid_hook_identity_invalid", "Native Work start ancestry contains a cycle");
+      seen.add(ancestor);
+      const owner = await this.metadata.read(ancestor, checkpoint);
+      if (!owner || path.resolve(owner.header.cwd) !== this.config.cwd) throw new DroidError("droid_hook_identity_invalid", "Native Work start ancestry is unproven");
+      ancestor = owner.header.callingSessionId ?? null;
+    }
+    if (id !== this.rootId && ancestor !== this.rootId || id === this.rootId && parent)
+      throw new DroidError("droid_hook_identity_invalid", "Native Work start belongs to another root");
+    const previous = this.topology.get(id);
+    if (previous && (previous.parent_provider_session_id !== parent || previous.tool_use_id && previous.tool_use_id !== native.header.callingToolUseId))
+      throw new DroidError("droid_hook_identity_invalid", "Native Work start contradicts retained ancestry");
+    const profile = await this.observeSettings(id, native.settings, { path: native.transcript_path, sha256: native.source_sha256 ?? native.source?.sha256 });
+    retained.guard();
+    return { verified: true, registeredHookBinding: binding, nativeHookBinding: { ...binding, parent_provider_session_id: parent,
+      native_ancestry: "confirmed", native_payload: { ...payload, session: { provider_session_id: id, parent_provider_session_id: parent, directory: this.config.cwd }, profile } } };
+  }
+  async observeHookChecked(payload, eventId, budget = hookBudget(23_000)) {
+    const id = payload.session_id, event = payload.hook_event_name;
+    if (!id || !event || !eventId) throw new DroidError("droid_hook_invalid", "Hook lacks native identity or event ID");
+    // SessionStart can be invoked synchronously by initialize/load before the
+    // provider creates its transcript. Acknowledge only the outstanding owned
+    // root request; this is not evidence that initialization succeeded.
+    const initPending = [...this.pending.values()].some(item => ["droid.initialize_session", "droid.load_session"].includes(item.method));
+    if (event === "SessionStart" && initPending && id === this.rootId && typeof payload.cwd === "string" && path.resolve(payload.cwd) === this.config.cwd && typeof payload.transcript_path === "string") {
+      const sessions = path.join(this.paths.factory, "sessions"), transcript = path.resolve(payload.transcript_path), relative = path.relative(sessions, transcript);
+      if (path.isAbsolute(payload.transcript_path) && relative && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative) && path.basename(transcript) === `${id}.jsonl`) return {};
+    }
+    // Hooks can precede the root initialize response or the child notification.
+    const deadline = Date.now() + 3_000; let native;
+    do { native = ["PreToolUse", "PostToolUse"].includes(event) ? await this.metadata.read(id) : await readDroidSession(this.paths.factory, id); if (native) break; await sleep(25); } while (Date.now() < deadline);
+    const foreign = message => new DroidError("droid_hook_identity_invalid", message, { scope: "foreign_hook", provider_session_id: id });
+    if (!native || path.resolve(payload.cwd) !== this.config.cwd || await realpath(payload.transcript_path) !== await realpath(native.transcript_path)) throw foreign("Hook is outside its controlled native Session/workspace");
+    const parent = native.header.callingSessionId ?? null;
+    if (parent && parent !== this.rootId && !this.topology.has(parent)) throw foreign("Hook child belongs to another root");
+    if (parent && (id === parent || this.topology.has(id) && this.topology.get(id).parent_provider_session_id !== parent)) throw foreign("Hook child ancestry changed");
+    if (!parent && this.rootId && id !== this.rootId) throw foreign("Hook came from an unrelated root");
+    if (path.resolve(native.header.cwd) !== this.config.cwd) throw new DroidError("droid_hook_identity_invalid", "Owned native Session workspace changed");
+    if (parent && !terminal(this.topology.get(id)?.status)) {
+      const previous = this.topology.get(id), creationTool = native.header.callingToolUseId;
+      if (previous?.tool_use_id && previous.tool_use_id !== creationTool) throw foreign("Hook child creation tool contradicts retained native identity");
+      this.topology.set(id, { ...(previous ?? {}), provider_session_id: id, parent_provider_session_id: parent, tool_use_id: creationTool, status: "running", source: "droid.session_start" });
+    }
+    this.activity += 1; await this.journal("hook", { event_id: eventId, event, session_id: id, parent_session_id: parent }); await this.save();
+    if (!["PreToolUse", "PostToolUse"].includes(event)) return {};
+    if (this.fatalError) return { continue: false, stopReason: this.fatalError.message };
+    let profile;
+    try { profile = await this.observeSettings(id, native.settings, { path: native.transcript_path, sha256: native.source_sha256 }); }
+    catch (error) { await this.handleObservationError(error); return { continue: false, stopReason: error.message }; }
+    if (!this.config.ddFlowBin || payload.tool_name !== "Execute") return {};
+    // Usage is ingested by inspect/turn completion, never ahead of admission.
+    try {
+      return await this.flow("event", "handle", { schema_id: "dd-flow/droid-tool-event@1", phase: event === "PreToolUse" ? "before" : "after", event_id: eventId, daemon_id: this.config.daemonId, session: { provider_session_id: id, parent_provider_session_id: parent, directory: this.config.cwd }, tool: payload.tool_name, input: payload.tool_input, profile, transcript_path: native.transcript_path, outcome: { status: payload.tool_response?.is_error ? "error" : "completed" } }, budget.remaining("admission"));
+    } catch (error) {
+      if (event === "PreToolUse" && isProvenShellCorrection(error)) {
+        const refusal = errorRecord(error);
+        await this.journal("hook_rejected", { error: refusal, event_id: eventId, session_id: id });
+        await this.save();
+        return { continue: false, stopReason: error.message };
+      }
+      if (isNativeHookObservationLoss(error)) {
+        // A lost hook observation does not establish the tool or CLI outcome.
+        // Do not authorize this pre-tool request, but do not poison the Turn.
+        if (this.active) (this.active.hookDiagnostics ??= []).push(errorRecord(error));
+        try { await this.journal("native_hook_observation_unavailable", { event_id: eventId, session_id: id, error: errorRecord(error) }); } catch { /* optional diagnostic */ }
+        return event === "PreToolUse" ? { continue: false, stopReason: "Lifecycle observation unavailable; retry the command." } : {};
+      }
+      // Identity is proven above; only this owned admission can fail its turn.
+      this.fatalError ??= Object.assign(error, { details: { ...error.details, provider_session_id: id, event_id: eventId, effect: error.details?.effect ?? "unknown", native_turn_items: { observed: false, possible_effects: true, pending: true } } });
+      this.rejectPending(this.fatalError);
+      try { await budget.run(async () => { await this.save({ fatal_error: errorRecord(this.fatalError) }); await this.journal("hook_rejected", { error: errorRecord(this.fatalError) }); }, "failure_persistence"); }
+      catch (storage) { this.fatalError.details.receipt_error = errorRecord(storage); }
+      throw this.fatalError;
+    }
+  }
+  async captureProcesses() {
+    const rows = await processSnapshot();
+    const roots = this.ownedProcesses.filter(old => rows.some(row => row.pid === old.pid && row.started === old.started));
+    if (this.child && !this.closed) roots.push({ pid: this.child.pid });
+    for (const root of roots) for (const row of descendants(rows, root.pid)) if (!this.ownedProcesses.some(old => old.pid === row.pid && old.started === row.started)) this.ownedProcesses.push(row);
+    await this.save({ owned_processes: this.ownedProcesses });
+    return rows.filter(row => !row.zombie && this.ownedProcesses.some(old => old.pid === row.pid && old.started === row.started));
+  }
+  async closeTree(cancel = false) {
+    if (this.cleanupPromise) return await this.cleanupPromise;
+    this.cleanupPromise = this.closeOwnedTree(cancel);
+    try { return await this.cleanupPromise; } finally { this.cleanupPromise = null; }
+  }
+  async closeOwnedTree(cancel) {
+    await this.captureProcesses();
+    if (cancel) cancelPendingDispatch(this);
+    this.closing = true; this.cancelled = cancel;
+    if (cancel && !this.closed) { try { await this.request("droid.interrupt_session", {}, randomUUID(), 5_000); } catch (error) { await this.journal("interrupt_unobserved", { error: errorRecord(error) }); } }
+    let forced = this.state.cleanup?.forced === true;
+    try { if (!this.closed && this.rootId) await this.request("droid.close_session", { reason: "other" }, randomUUID(), 10_000); else if (!this.closed) this.child.stdin.end(); } catch (error) { await this.journal("close_unobserved", { error: errorRecord(error) }); }
+    const alive = () => this.captureProcesses();
+    const deadline = Date.now() + 8_000; while ((!this.closed || (await alive()).length) && Date.now() < deadline) await sleep(100);
+    if (!this.closed || (await alive()).length) {
+      forced = true; if (!this.closed) await stopProcessGroup(this.child, 2_000).catch(error => this.journal("group_stop_unconfirmed", { error: errorRecord(error) }));
+      // Execute can own a separate process group. Kill only still-matching
+      // observed descendants; never use a process-name search or broad pkill.
+      for (const row of await alive()) { try { process.kill(row.pid, "SIGTERM"); } catch (error) { if (error.code !== "ESRCH") throw error; } }
+      await sleep(1_000);
+      for (const row of await alive()) { try { process.kill(row.pid, "SIGKILL"); } catch (error) { if (error.code !== "ESRCH") throw error; } }
+      await sleep(200);
+    }
+    const survivors = await alive(); if (!this.closed || survivors.length) throw new DroidError("tree_not_settled", "Droid cleanup did not settle its owned process tree", { survivors });
+    clearInterval(this.processObserver); clearInterval(this.modelObserver); await this.processObservation;
+    await this.draining; this.workingState = "idle";
+    if (this.active && !this.active.outcome) this.active.reject(new DroidError(cancel ? "operation_cancelled" : "operation_observation_lost", "Droid runtime closed before a native terminal reply"));
+    await finishDaemonProcess(this.config, this.providerProcess, forced ? "failed" : "stopped", forced ? "forced_tree_shutdown" : "native_tree_closed");
+    let topologyError = null;
+    try { await this.refreshTopology(); }
+    catch (error) { topologyError = errorRecord(error); await this.journal("closed_tree_topology_error", { error: topologyError }); }
+    const root = this.rootId ? await readDroidSession(this.paths.factory, this.rootId) : null;
+    const nativeSettled = !forced && !topologyError && !this.topologyIncomplete
+      && (!this.rootId || root?.complete && (terminal(root.outcomes.at(-1)?.reason) || !this.active && !this.lastResult && root.records.every(record => record.type === "session_start")) && root.tool_calls.pending === 0)
+      && [...this.topology.values()].every(child => terminal(child.status) && child.native_turn_items?.observed === true && child.native_turn_items.pending === false);
+    const cleanup = { settled: true, physical_stopped: true, native_settled: nativeSettled, forced, observed_processes: this.ownedProcesses.length, ...(topologyError ? { topology_error: topologyError } : {}) };
+    await this.save({ active_tree: false, cleanup });
+    return cleanup;
+  }
+}