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

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

@@ -0,0 +1,471 @@
+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, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import os from "node:os";
+import path from "node:path";
+import { ObservationClock, observedTimeout } from "./observation-clock.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+import { errorRecord, reportedError } from "./operation-errors.mjs";
+import { checkObservedProfile, observeModel } from "./model-observations.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, heartbeatDaemonProcess, registerDaemonProcess, stopProcessGroup } from "./managed-daemon.mjs";
+import { renderAdapterPolicy } from "./delegation-instructions.mjs";
+
+const run = promisify(execFile);
+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.
+  for (const key of Object.keys(env)) if (key.endsWith("API_KEY")) delete env[key];
+  return env;
+}
+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. 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 run(target.command, target.args, { timeout: 10_000 })).stdout.trim(); }
+
+/** 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";
+
+
+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.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, 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"] });
+    this.child.stdout.setEncoding("utf8").on("data", chunk => { this.buffer += chunk; let at; while ((at = this.buffer.indexOf("\n")) >= 0) { const line = this.buffer.slice(0, at); this.buffer = this.buffer.slice(at + 1); this.draining = this.draining.then(async () => { if (!line.trim()) return; await this.event(JSON.parse(line)); }).catch(async error => { await this.handleObservationError(error); if (!this.fatalError) this.rejectPending(error); }); } });
+    this.child.stderr.setEncoding("utf8").on("data", chunk => { void this.journal("stderr", { text: chunk.slice(0, 4000) }).catch(() => {}); });
+    this.child.on("error", error => this.rejectPending(error));
+    this.child.on("close", (code, signal) => { this.closed = true; void this.draining.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); await heartbeatDaemonProcess(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 (fingerprint !== this.lastEvent) { this.activity += 1; this.lastEvent = fingerprint; }
+    if (sessionId && this.rootId && sessionId !== this.rootId && !this.topology.has(sessionId)) throw new DroidError("session_identity_mismatch", "Unrelated native Session notification");
+    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");
+      this.topology.set(n.childSessionId, { provider_session_id: n.childSessionId, parent_provider_session_id: sessionId, tool_use_id: n.toolUseId, 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 });
+    const current = this.active;
+    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" && current) 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);
+    }
+  }
+  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);
+      }, timeoutMs);
+      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(error); } }); }
+      catch (error) { clearTimeout(timer); this.pending.delete(id); reject(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 (error) { 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.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) {
+    if (!native || path.resolve(native.header.cwd) !== this.config.cwd || native.header.id !== id || (id !== this.rootId && native.header.callingSessionId !== this.rootId)) 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: this.rootId, 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);
+      for (const task of value?.invocations ?? []) if (task.parentSessionId === this.rootId && task.childSessionId) {
+        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)) 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 (["profile_integrity_violation", "session_identity_mismatch", "droid_child_identity_invalid", "droid_turn_identity_mismatch", "droid_hook_identity_invalid", "model_observation_storage_failed"].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) {
+    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, resolve, reject, text: "", saved: { operation: "session.prompt", provider_session_id: id, request_id: requestId, turn_id: turnId, accepted: false } };
+    this.active = current; this.cancelled = false; await this.saveBinding(current); await this.save({ active_tree: true });
+    const clock = new ObservationClock({ timeoutMs: this.config.inactivityMs ?? 600_000, onGap: gap => { void this.journal("observation_gap", { gap }).catch(() => {}); } });
+    let checkingTerminal = false;
+    const timer = setInterval(() => {
+      if (!clock.sample(this.activity) || checkingTerminal) return;
+      checkingTerminal = true;
+      void this.recoverOperation(operationId).then(() => {
+        if (!current.outcome) reject(new DroidError("subject_liveness_timeout", "Droid emitted no native progress within its inactivity window"));
+      }).catch(error => reject(new DroidError("operation_observation_lost", "Cannot reconcile native outcome before declaring inactivity", { error: errorRecord(error) })));
+    }, 1_000);
+    try {
+      assertDispatch();
+      await this.request("droid.add_user_message", { text: prompt, messageId: turnId }, requestId);
+      const outcome = await completed; await this.draining;
+      try {
+        const receipt = await this.inspect(id, { ignoreActive: true });
+        return { ...receipt, result: { ...outcome, status: status(outcome.reason) }, assistant_text: current.text, turn_id: turnId };
+      } 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) };
+      }
+    } catch (error) {
+      await this.journal("prompt_error", { operation_id: operationId, error: errorRecord(error) }); throw error;
+    } finally { clearInterval(timer); if (this.active === current) this.active = null; await this.save({ active_tree: this.workingState !== "idle" }); }
+  }
+  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) };
+    }
+    // A terminal root turn is not enough to recover the operation while a
+    // child Task or owned provider process is still active.  Leave the
+    // durable binding for the normal settlement observer instead of exposing
+    // a misleading successful receipt.
+    if (receipt.settled !== true) return null;
+    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);
+      // 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;
+    try { catalog = await readJson(path.join(this.paths.factory, "task-invocations.json")); }
+    catch (error) { if (!(error instanceof SyntaxError)) throw error; this.topologyIncomplete = true; return [...this.topology.values()]; }
+    this.topologyIncomplete = false;
+    const invocations = catalog?.invocations ?? [];
+    const root = this.rootId ? await readDroidSession(this.paths.factory, this.rootId) : null;
+    const rootTools = new Map((root?.records ?? []).flatMap(record => record.message?.content ?? []).filter(block => block.type === "tool_use").map(block => [block.id, block]));
+    const groups = new Map();
+    for (const task of invocations) {
+      if (task.parentSessionId !== this.rootId || !task.childSessionId || !task.parentToolUseId) continue;
+      const tasks = groups.get(task.childSessionId) ?? []; tasks.push(task); groups.set(task.childSessionId, tasks);
+    }
+    for (const [id, tasks] of groups) {
+      const native = await readDroidSession(this.paths.factory, id);
+      if (!native || !native.settings) { this.topologyIncomplete = true; continue; }
+      if (native.header.callingSessionId !== this.rootId) throw new DroidError("droid_child_identity_invalid", "Task invocation disagrees with physical child parent");
+      const creationTool = native.header.callingToolUseId;
+      for (const task of tasks) {
+        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 });
+      const prior = this.topology.get(id);
+      // 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 ordered = tasks.toSorted((a, b) => (a.createdAt ?? 0) - (b.createdAt ?? 0));
+      const latest = ordered.at(-1); const running = tasks.some(task => !terminal(task.status));
+      const closed = running && prior?.source === "adapter.tree_closed";
+      this.topology.set(id, { provider_session_id: id, parent_provider_session_id: this.rootId, tool_use_id: creationTool, latest_tool_use_id: latest.parentToolUseId, task_id: latest.taskInvocationId, task_invocation_ids: ordered.map(task => task.taskInvocationId), status: closed ? prior.status : running ? "running" : status(latest.status), source: closed ? prior.source : "droid.task_invocations", transcript_path: native.transcript_path });
+    }
+    return [...this.topology.values()];
+  }
+  async snapshotUsage(id) {
+    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 (measured && this.config.ddFlowBin) await this.flow("usage", "ingest", payload);
+    return { status: measured ? "measured" : "unavailable", ...payload };
+  }
+  async flow(family, command, payload) {
+    const target = executable(this.config.ddFlowBin, ["droid", family, command, "--project-root", this.config.projectRoot, "--json"]);
+    return await new Promise((resolve, reject) => {
+      const child = spawn(target.command, target.args, { cwd: this.config.cwd, env: droidEnvironment(this.config), stdio: ["pipe", "pipe", "pipe"] }); let stdout = "", stderr = "";
+      const timer = observedTimeout(() => { child.kill("SIGTERM"); reject(new DroidError("droid_flow_timeout", "dd-flow did not acknowledge Droid evidence")); }, 25_000);
+      child.stdout.setEncoding("utf8").on("data", chunk => stdout += chunk); child.stderr.setEncoding("utf8").on("data", chunk => stderr += chunk);
+      child.on("error", error => { clearTimeout(timer); reject(error); }); child.on("close", code => { clearTimeout(timer); if (code !== 0) return reject(new DroidError("droid_flow_rejected", stderr || "dd-flow rejected Droid evidence")); try { resolve(JSON.parse(stdout)); } catch (error) { reject(error); } }); child.stdin.end(`${JSON.stringify(payload)}\n`);
+    });
+  }
+  async inspect(id, { ignoreActive = false } = {}) {
+    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));
+    const settled = !this.topologyIncomplete && (!this.active || ignoreActive) && (this.closed || this.workingState === "idle") && children.every(child => terminal(child.status));
+    return { 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, descendants: children, transcript_path: source?.transcript_path ?? null, usage, result: this.lastResult, provider_pid: this.closed ? null : this.child?.pid ?? null };
+  }
+  async observeHook(payload, eventId) {
+    try { return await this.observeHookChecked(payload, eventId); }
+    catch (error) { await this.handleObservationError(error); throw error; }
+  }
+  async observeHookChecked(payload, eventId) {
+    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");
+    // 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);
+    if (!native || path.resolve(native.header.cwd) !== this.config.cwd || path.resolve(payload.cwd) !== this.config.cwd || await realpath(payload.transcript_path) !== await realpath(native.transcript_path)) throw new DroidError("droid_hook_identity_invalid", "Hook is outside its controlled native Session/workspace");
+    const parent = native.header.callingSessionId ?? null;
+    if (parent && parent !== this.rootId) throw new DroidError("droid_hook_identity_invalid", "Hook child belongs to another root");
+    if (!parent && this.rootId && id !== this.rootId) throw new DroidError("droid_hook_identity_invalid", "Hook came from an unrelated root");
+    if (parent && !terminal(this.topology.get(id)?.status)) this.topology.set(id, { ...(this.topology.get(id) ?? {}), provider_session_id: id, parent_provider_session_id: parent, tool_use_id: native.header.callingToolUseId, 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 {};
+    await this.snapshotUsage(id);
+    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" } });
+  }
+  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 }); }
+    for (const [id, child] of this.topology) if (!terminal(child.status)) this.topology.set(id, { ...child, status: "cancelled", source: "adapter.tree_closed", native_status: child.status });
+    const cleanup = { settled: true, forced, observed_processes: this.ownedProcesses.length, ...(topologyError ? { topology_error: topologyError } : {}) };
+    await this.save({ active_tree: false, cleanup });
+    return cleanup;
+  }
+}