@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/harness-runtime/lib/daemon-operations.mjs

@@ -0,0 +1,462 @@
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { mkdir, readFile, readdir, link, unlink, open } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { hashJson, writeJsonAtomic } from "./runner-events.mjs";
+import { errorRecord, isObservationLoss, isProvenShellCorrection, reportedError } from "./operation-errors.mjs";
+import { assertDaemonOwnership, budgetObservationScope, releaseBudgetObservation, completeBudgetOperation, stopProcessGroup } from "./managed-daemon.mjs";
+import { processSnapshot } from "./process-snapshot.mjs";
+import { NATIVE_SHUTDOWN_CONTRACT, NATIVE_SHUTDOWN_PHASES } from "./native-children.mjs";
+import { readModelObservations, modelAttribution } from "./model-observations.mjs";
+import { publishOperationProgress, publishOperationWaiting, withOperationProgress } from './operation-progress.mjs';
+import { prepareDaemonRequest } from "./native-request-proof.mjs";
+
+const productive = new Set(["session.create", "session.prompt", "session.start", "session.fork", "session.resume"]);
+const controls = new Map();
+const dispatchGenerations = new Map();
+const shutdowns = new Map();
+const settlements = new Map();
+
+// Configuration locations only: credentials and arbitrary process env are not
+// replay inputs. The browser cache is additive for historical five-key launches.
+const nativeLaunchEnvironmentKeys = ["CODEX_HOME", "DD_FLOW_CONFIG_HOME", "DD_FLOW_HOME", "DD_FLOW_BIN", "DD_FLOW_RESOURCE_HOME"];
+export function validateNativeLaunchEnvironment(value) {
+  const cache = value?.PLAYWRIGHT_BROWSERS_PATH;
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).some(key => ![...nativeLaunchEnvironmentKeys, "PLAYWRIGHT_BROWSERS_PATH"].includes(key))
+    || nativeLaunchEnvironmentKeys.some(key => value[key] !== null && typeof value[key] !== "string")
+    || Object.hasOwn(value, "PLAYWRIGHT_BROWSERS_PATH") && cache !== null
+      && (typeof cache !== "string" || !cache || cache.length > 4096 || cache.includes("\0") || !path.isAbsolute(cache)))
+    throw Object.assign(new Error("Native launch requires explicit configuration locations and an absolute browser cache"), { code: "runtime_scope_native_launch_required" });
+  return value;
+}
+
+// Progress is not outcome authority. Once native effect is retained, a failed
+// diagnostic write must keep its identity and prohibit redispatch.
+async function publishRetainedProgress(root, id, phase, result, metadata) {
+  try { return await publishOperationProgress(root, id, phase, metadata); }
+  catch (cause) {
+    throw Object.assign(new Error('native outcome retained but operation progress could not be published'), {
+      code: 'operation_observation_lost', retryable: false, cause,
+      details: { operation_id: id, state_dir: root, native_outcome: 'completed', native_result: result, progress_error: errorRecord(cause) }
+    });
+  }
+}
+
+export function assertDaemonDispatch(root) {
+  const stop = shutdowns.get(root);
+  if (stop?.pending || stop?.committed) throw Object.assign(new Error("daemon shutdown fences productive dispatch"), { code: "daemon_stopping" });
+}
+export function assertDaemonRestartable(state) {
+  if (["unclean", "cleanup_failed", "stopping"].includes(state?.shutdown_state)) throw Object.assign(new Error("previous daemon shutdown is unresolved; do not restart a native bridge for cleanup"), { code: "daemon_state_terminal", details: { daemon_id: state.daemon_id ?? state.config?.daemonId, shutdown_state: state.shutdown_state } });
+}
+export function commitDaemonShutdown(root) {
+  if (typeof root !== 'string') return; // In-memory adapter diagnostics own no daemon endpoint.
+  const fence = shutdowns.get(root) ?? { pending: 0 };
+  fence.committed = true; shutdowns.set(root, fence);
+}
+
+function ownedSnapshot(snapshot, rootPid) {
+  const owned = new Set([rootPid]); let size;
+  do { size = owned.size; for (const item of snapshot) if (owned.has(item.ppid)) owned.add(item.pid); } while (size !== owned.size);
+  return snapshot.filter(item => item.pid !== rootPid && owned.has(item.pid) && !item.zombie);
+}
+const mergeProcesses = (...snapshots) => [...new Map(snapshots.flat().map(item => [`${item.pid}:${item.started}`, item])).values()];
+
+/** The same incarnation may retry remaining cleanup, never a native Turn. */
+export async function completeDaemonShutdown(root, state, persist, prepare, phases, reconcileResources) {
+  const daemonId = state.daemon_id ?? state.config?.daemonId;
+  let shutdown = state.shutdown;
+  if (shutdown && shutdown.schema_id !== NATIVE_SHUTDOWN_CONTRACT) throw Object.assign(new Error("shutdown contract mismatch; retain historical owner evidence"), { code: "native_contract_mismatch" });
+  if (!shutdown || shutdown.daemon_id !== daemonId) shutdown = { schema_id: NATIVE_SHUTDOWN_CONTRACT, daemon_id: daemonId, generation: dispatchGenerations.get(root) ?? 0, phases: {} };
+  shutdown = { ...shutdown, required_phases: [...new Set([...NATIVE_SHUTDOWN_PHASES, ...phases.map(([phase]) => phase)])] };
+  try {
+    if (!shutdown.phases.execution) {
+      // Some native adapters close their provider inside prepare(). Observe
+      // ownership first, before that close can reparent a support process.
+      const before = ownedSnapshot(await processSnapshot(), state.pid);
+      shutdown = { ...shutdown, generation: dispatchGenerations.get(root) ?? shutdown.generation,
+        owned_processes: mergeProcesses(shutdown.owned_processes ?? [], before), inventory_complete: state.pid === process.pid };
+      await persist({ shutdown });
+      const result = await prepare();
+      commitDaemonShutdown(root);
+      // Compute ancestry within each snapshot, not across recycled parent PIDs.
+      const resources = mergeProcesses(shutdown.owned_processes, ownedSnapshot(await processSnapshot(), state.pid));
+      shutdown = { ...shutdown, phases: { execution: true }, owned_processes: resources,
+        inventory_complete: state.pid === process.pid, tree_observed_at: new Date().toISOString(), preparation_clean: result?.clean !== false, result: result ?? {} };
+      await persist({ shutdown, shutdown_state: "stopping" });
+    }
+    commitDaemonShutdown(root);
+    if (reconcileResources && !shutdown.phases.owned_resources) {
+      const revision = state.native_execution_revision, generation = dispatchGenerations.get(root) ?? shutdown.generation;
+      const resources = await reconcileResources();
+      const prior = shutdown.result?.native_resources;
+      if ((state.daemon_id ?? state.config?.daemonId) !== daemonId || state.native_execution_revision !== revision
+        || (dispatchGenerations.get(root) ?? shutdown.generation) !== generation || state.active_tree !== false || state.unclaimed_activity
+        || !resources || resources.schema_id !== 'native-resources@1' || resources.owner_daemon_id !== daemonId
+        || resources.generation !== prior?.generation || resources.revision !== prior?.revision || !Array.isArray(resources.entries)
+        || resources.entries.some(item => item.owner_daemon_id !== daemonId || item.generation !== resources.generation))
+        throw Object.assign(new Error('native resource reconciliation lost its owner/execution fence'), { code: 'native_resources_unproven' });
+      shutdown = { ...shutdown, result: { ...shutdown.result, native_resources: resources } };
+      await persist({ shutdown });
+    }
+    for (const [phase, action] of phases) {
+      if (phase === "daemon_resource" && !shutdown.phases.owned_resources) {
+        if (!shutdown.inventory_complete) throw Object.assign(new Error("owned resource coverage is unknown"), { code: "native_resources_unproven" });
+        for (const retained of shutdown.owned_processes ?? []) {
+          const current = (await processSnapshot()).find(item => item.pid === retained.pid);
+          if (!current || current.started !== retained.started || current.zombie) continue;
+          await stopProcessGroup({ pid: retained.pid, started: retained.started }, 1000, { detached: false });
+        }
+        const remaining = await processSnapshot();
+        if ((shutdown.owned_processes ?? []).some(retained => remaining.some(item => item.pid === retained.pid && item.started === retained.started && !item.zombie))) throw Object.assign(new Error("owned resources remain live"), { code: "native_resources_unproven" });
+        const nativeResources = shutdown.result?.native_resources;
+        const resourceGap = nativeResources?.entries?.some(resource => resource.observation_conflict === true || resource.state !== "stopped"
+          && !(resource.classification === "required_work" && shutdown.result?.native_settled === true && shutdown.result?.settled === true)
+          && !(shutdown.owned_processes ?? []).some(item => resource.pid === item.pid && resource.started === item.started));
+        shutdown = { ...shutdown, phases: { ...shutdown.phases, owned_resources: !resourceGap },
+          resource_retirement: { confirmed: !resourceGap, reason: resourceGap ? "native_resource_identity_unproven" : "owned_processes_retired" } };
+        await persist({ shutdown });
+        // Keep the technical cleanup owner/endpoint available for a later
+        // read-only reconciliation. Retiring its lease here would make the
+        // actual daemon exit before the retained resources can converge.
+        if (resourceGap) throw Object.assign(new Error("native resource retirement remains unproven"), { code: "native_resources_unproven" });
+      }
+      if (shutdown.phases[phase]) continue;
+      await action();
+      shutdown = { ...shutdown, phases: { ...shutdown.phases, [phase]: true } };
+      await persist({ shutdown });
+    }
+    const publishedRevision = state.native_execution_revision;
+    const sameRevision = publishedRevision === undefined || publishedRevision === shutdown.result?.native_settlement?.revision;
+    const nativeSettled = sameRevision && state.active_tree === false && !state.unclaimed_activity && shutdown.result?.settled === true && shutdown.result?.native_settled === true && shutdown.result?.native_settlement?.confirmed !== false;
+    const physicalStopped = shutdown.required_phases.every(phase => shutdown.phases[phase] === true);
+    // Cleanup retries/joining controls advance the control fence, not the old
+    // native Turn. Publish the current control generation with retained phases.
+    shutdown = { ...shutdown, generation: dispatchGenerations.get(root) ?? shutdown.generation };
+    const { result: ignored, ...proof } = shutdown; void ignored;
+    let result = { ...shutdown.result, daemon_id: daemonId, stopped: true, physical_stopped: physicalStopped,
+      settled: nativeSettled, native_settled: nativeSettled, clean: (shutdown.preparation_clean ?? shutdown.result?.clean !== false) && nativeSettled && physicalStopped,
+      resource_retirement: shutdown.resource_retirement,
+      shutdown_contract: NATIVE_SHUTDOWN_CONTRACT, shutdown_proof: proof, _shutdown: true };
+    shutdown = { ...shutdown, result };
+    // prepare() owns execution quiescence. A stale publication must not clear
+    // activity that arrives while its durable write is in flight.
+    await persist({ shutdown, shutdown_state: result.clean === true ? "clean" : "unclean", stopped_at: new Date().toISOString(), cleanup_error: null });
+    if (nativeSettled && (state.native_execution_revision !== publishedRevision || state.active_tree !== false || state.unclaimed_activity)) {
+      shutdown = { ...shutdown, phases: { ...shutdown.phases, execution: false } };
+      result = { ...result, clean: false, settled: false, native_settled: false,
+        native_settlement: { ...result.native_settlement, confirmed: false, reason: "late_activity_during_shutdown_publication" },
+        shutdown_proof: { ...proof, phases: shutdown.phases } };
+      shutdown = { ...shutdown, result };
+      await persist({ shutdown, shutdown_state: "unclean" });
+    }
+    return result;
+  } catch (error) {
+    if (error.code === "tree_not_settled" && !shutdowns.get(root)?.committed) throw error;
+    try { await persist({ shutdown_state: "cleanup_failed", cleanup_error: errorRecord(error) }); }
+    catch (storage) { error.details = { ...error.details, persistence_error: errorRecord(storage) }; }
+    throw error;
+  }
+}
+
+const daemonConnections = new WeakMap();
+export function trackDaemonConnections(server) {
+  const sockets = new Set(); daemonConnections.set(server, sockets);
+  server.once("listening", () => {
+    const endpoint = server.address();
+    if (typeof endpoint !== "string") return;
+    try { const info = lstatSync(endpoint); daemonEndpoints.set(server, { endpoint, dev: info.dev, ino: info.ino }); }
+    catch (error) { daemonEndpoints.set(server, { endpoint, error }); }
+  });
+  server.on("connection", socket => { sockets.add(socket); socket.on("error", () => {}); socket.once("close", () => sockets.delete(socket)); });
+}
+const daemonEndpoints = new WeakMap();
+
+/** Retire the listener after durable publication, before ACK; no provider IO. */
+export function retireDaemonEndpoint(server, exitCode = 0) {
+  if (!server.listening) return;
+  const retained = daemonEndpoints.get(server);
+  let endpointError = retained?.error;
+  if (retained && !endpointError) {
+    try {
+      const current = lstatSync(retained.endpoint);
+      if (current.dev !== retained.dev || current.ino !== retained.ino || !current.isSocket()) endpointError = Object.assign(new Error("daemon endpoint was replaced; refusing to unlink another listener"), { code: "daemon_endpoint_identity_mismatch", details: { socket: retained.endpoint, phase: "retire_listener" } });
+    } catch (error) { if (error.code !== "ENOENT") endpointError = error; }
+  }
+  if (endpointError) {
+    // libuv's close unlinks by pathname, not inode. Exit without closing its
+    // listener handle when the name belongs to a different incarnation.
+    const timer = setTimeout(() => { for (const socket of daemonConnections.get(server) ?? []) socket.destroy(); process.exit(1); }, 1_000);
+    timer.unref();
+    throw endpointError;
+  }
+  const timer = setTimeout(() => { for (const socket of daemonConnections.get(server) ?? []) socket.destroy(); }, 1_000);
+  timer.unref();
+  server.close(() => { clearTimeout(timer); process.exit(exitCode); });
+}
+
+export async function retireFailedDaemon(server, state, error, persist) {
+  // An already-finished registry lease cannot own a listening productive daemon.
+  if (state.shutdown?.phases?.daemon_resource) {
+    // Durable result publication and listener retirement occur after the
+    // cleanup helper returns. Their failures still invalidate overall clean.
+    if (persist) try { await persist({ shutdown_state: "cleanup_failed", cleanup_error: errorRecord(error) }); }
+    catch (storage) { error.details = { ...error.details, persistence_error: errorRecord(storage) }; }
+    process.stderr.write(`${JSON.stringify({ shutdown_failure: errorRecord(error) })}\n`);
+    try { retireDaemonEndpoint(server, 1); } catch { /* Retirement already scheduled a nonzero exit without unlinking a foreign endpoint. */ }
+  }
+}
+
+async function controlDispatch(root, request, action) {
+  const key = request.operation === "daemon.stop" ? `stop:${request.params?.cancelTree === true}` : `cancel:${request.params?.sessionId ?? ""}`;
+  let pending = controls.get(root);
+  if (!pending) { pending = new Map(); controls.set(root, pending); }
+  if (pending.has(key)) return await pending.get(key);
+  // Preserve the adapter's identity check for every distinct cancel target.
+  // A stop arriving after cancel waits for its attempts before verification.
+  const predecessors = key.startsWith("stop:") ? [...pending.values()] : [];
+  const promise = (async () => { await Promise.allSettled(predecessors); return await action(); })();
+  pending.set(key, promise);
+  let completed = false;
+  try { const result = await promise; completed = true; return result; }
+  // Successful whole-tree stop remains idempotent for this daemon lifetime.
+  // Durable publication for a concurrent caller may arrive after cleanup ends.
+  finally { if (!completed || !key.startsWith('stop:')) { pending.delete(key); if (!pending.size) controls.delete(root); } }
+}
+function location(root, id) {
+  if (typeof id !== "string" || !id) throw Object.assign(new Error("operation id is required"), { code: "operation_id_required" });
+  return path.join(root, "operations", createHash("sha256").update(id).digest("hex"));
+}
+async function read(file) { try { return JSON.parse(await readFile(file, "utf8")); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
+
+export async function inspectDaemonOperation(root, id) {
+  if (typeof root !== "string" || !path.isAbsolute(root)) throw Object.assign(new Error("operation observation requires an absolute state directory"), { code: "invalid_path" });
+  const directory = location(root, id);
+  const requested = await read(path.join(directory, "requested.json"));
+  if (!requested) throw Object.assign(new Error("daemon operation is not recorded"), { code: "operation_not_found", details: { operation_id: id } });
+  const settlement = await read(path.join(directory, "settlement.json"));
+  const hookFailures = [];
+  const hookCorrections = [];
+  const hookDiagnostics = [];
+  for (const name of await readdir(path.join(directory, "hooks")).catch(error => { if (error.code === "ENOENT") return []; throw error; })) {
+    if (!/^[A-Za-z0-9-]{1,128}\.json$/.test(name)) continue;
+    const binding = await read(path.join(directory, "hooks", name));
+    if (binding?.schema_id !== "dd-flow/hook-request@1" || binding.request_id !== name.slice(0, -5) || binding.operation_id !== id || binding.daemon_id !== requested.daemon_id) continue;
+    let failure;
+    try { failure = await read(path.join(root, "hook-failures", name)); }
+    catch (error) { hookDiagnostics.push({ code: "native_hook_receipt_invalid", message: error.message, request_id: binding.request_id, effect: "unknown", receipt_bound: false }); continue; }
+    if (failure?.request_id !== binding.request_id || typeof failure.code !== "string" || typeof failure.message !== "string") continue;
+    if (binding.command_sha256 && JSON.stringify(failure.native_hook_binding) !== JSON.stringify(binding)) continue;
+    const correction = isProvenShellCorrection(failure);
+    (correction ? hookCorrections : hookFailures).push({ ...errorRecord(failure), observed_at: failure.observed_at ?? null, details: { ...failure.details, native_hook_binding: binding, effect: correction ? "no_effect" : "unknown" } });
+  }
+  hookFailures.sort((a, b) => String(a.observed_at ?? "").localeCompare(String(b.observed_at ?? "")));
+  // Admission failure is causal evidence, not proof that the native tree stopped.
+  return { ...requested, ...(await read(path.join(directory, "result.json")) ?? await read(path.join(directory, "interrupted.json")) ?? await read(path.join(directory, "observation-lost.json")) ?? { state: "running" }), ...(settlement ? { settlement } : {}), ...(hookFailures[0] ? { primary_error: hookFailures[0] } : {}), ...(hookCorrections.length ? { hook_corrections: hookCorrections } : {}), ...(hookDiagnostics.length ? { hook_diagnostics: hookDiagnostics.slice(0, 16) } : {}) };
+}
+
+/** Retry only the bookkeeping that follows a durable productive receipt.
+ * This is intentionally separate from dispatch: it never invokes a native
+ * prompt/create/fork operation, so recovery cannot duplicate agent work. */
+export async function settleDaemonOperation(root, id) {
+  const key = `${root}\0${id}`;
+  if (settlements.has(key)) return await settlements.get(key);
+  const pending = settleOriginalOperation(root, id);
+  settlements.set(key, pending);
+  try { return await pending; } finally { if (settlements.get(key) === pending) settlements.delete(key); }
+}
+async function settleOriginalOperation(root, id) {
+  const current = await inspectDaemonOperation(root, id);
+  if (current.state !== "completed") return current;
+  if (['settled', 'not_required'].includes(current.settlement?.state)) return current;
+  const daemon = await read(path.join(root, 'daemon.json'));
+  const daemonId = daemon?.daemon_id ?? daemon?.config?.daemonId ?? null;
+  const fence = await read(path.join(root, 'operation-fence.json'));
+  const generation = dispatchGenerations.get(root) ?? (fence?.daemon_id === daemonId ? fence.generation : 0);
+  if (current.daemon_id !== (daemon?.daemon_id ?? daemon?.config?.daemonId ?? null)
+    || current.owner_id !== undefined && current.owner_id !== (daemon?.config?.runtime_owner?.owner_id ?? null)
+    || current.generation !== undefined && current.generation !== generation
+    || ['stopping','clean','unclean','cleanup_failed','failed'].includes(daemon?.shutdown_state)) throw Object.assign(new Error('settlement authority changed'), { code: 'settlement_reconciliation_required' });
+  assertDaemonDispatch(root);
+  let settlement;
+  try {
+    settlement = await completeBudgetOperation(root, {
+      id: current.operation_id,
+      operation: current.operation,
+      params: { sessionId: current.session_id ?? undefined }
+    }, current.result);
+  } catch (error) {
+    settlement = { state: "pending", reason: "settlement_error", observed_at: new Date().toISOString(), error: errorRecord(error) };
+  }
+  try { await writeSettlement(root, id, settlement); }
+  catch (error) {
+    settlement = { state: "blocked", reason: "settlement_storage_error", observed_at: new Date().toISOString(), error: errorRecord(error) };
+  }
+  return { ...current, settlement };
+}
+
+/** A sealed whole-tree stop is the only authority that may turn an unknown
+ * productive request into a terminal interruption.  This is deliberately a
+ * journal operation: a closed daemon cannot be asked to manufacture a reply. */
+export async function interruptDaemonOperation(root, id, barrier) {
+  if (!barrier || typeof barrier !== "object" || typeof barrier.control_id !== "string" || !barrier.control_id) throw Object.assign(new Error("interruption requires a sealed control identity"), { code: "stop_barrier_invalid" });
+  const current = await inspectDaemonOperation(root, id);
+  if (["completed", "failed", "interrupted"].includes(current.state)) return current;
+  if (!(["running", "awaiting_provider"].includes(current.state)) || !productive.has(current.operation)) throw Object.assign(new Error("only an observed productive operation may be interrupted"), { code: "operation_not_interruptible" });
+  // A lazy session/create is allowed to have no ACP/native session id yet.
+  // The owned daemon identity plus the sealed stop operation is the authority
+  // in that case; never manufacture a session id merely to satisfy the check.
+  const barrierSession = barrier.session_id ?? null;
+  const currentSession = current.session_id ?? null;
+  if (barrier.daemon_id !== current.daemon_id || barrierSession !== currentSession) throw Object.assign(new Error("interruption barrier belongs to another daemon operation"), { code: "stop_barrier_mismatch" });
+  const value = { state: "interrupted", outcome: "interrupted", observed_at: new Date().toISOString(), interrupted_by: { control_id: barrier.control_id, stop_operation_id: barrier.stop_operation_id, evidence: barrier.evidence ?? null }, error: { code: "operation_interrupted", message: "Operation was interrupted after the owned native tree was stopped", cause: current.error ?? null } };
+  const saved = await writeTerminal(root, id, value);
+  if (saved.state !== "interrupted" || saved.interrupted_by?.control_id !== barrier.control_id) throw Object.assign(new Error("operation already has a conflicting terminal outcome"), { code: "operation_terminal_conflict" });
+  return await inspectDaemonOperation(root, id);
+}
+
+/** At-most-once dispatch and a durable terminal reply, including when the socket
+ * observer disconnects. Recovery reads this receipt; it never resends a prompt. */
+export async function durableDaemonDispatch(root, request, action, observe) {
+  if (request.operation === "operation.inspect") return request.params?.settle === true ? await settleDaemonOperation(root, request.params?.operationId) : await inspectDaemonOperation(root, request.params?.operationId);
+  if (request.operation === "daemon.status") {
+    const result = await action();
+    if (!result?.config?.journal) return result;
+    try { return { ...result, model_attribution: modelAttribution(await readModelObservations(result.config.journal)) }; }
+    catch (error) { return { ...result, model_observation_error: errorRecord(error) }; }
+  }
+  if (request.operation === "session.inspect") {
+    const scope = await budgetObservationScope(root, request.params?.sessionId);
+    const result = await action();
+    let settlement;
+    if (!scope?.operationIds.length) settlement = { state: "not_required" };
+    else if (result?.settled !== true) settlement = { state: "pending", reason: "tree_unsettled" };
+    else try {
+      await releaseBudgetObservation(scope, result);
+      settlement = { state: "settled", operation_ids: scope.operationIds, source: "inspection" };
+    } catch (error) {
+      settlement = { state: "pending", reason: "settlement_error", observed_at: new Date().toISOString(), error: errorRecord(error) };
+    }
+    return settlement.state === "not_required" || !result || typeof result !== "object" || Array.isArray(result) ? result : { ...result, settlement };
+  }
+  const control = ["daemon.stop", "session.cancel"].includes(request.operation);
+  if (!productive.has(request.operation) && !control) return await action();
+  const generation = dispatchGenerations.get(root) ?? 0;
+  // Once retirement is committed there is no productive dispatch to cancel.
+  // Retrying/joining cleanup must not stale its own durable generation proof.
+  if (control && !(request.operation === "daemon.stop" && shutdowns.get(root)?.committed)) { dispatchGenerations.set(root, generation + 1); const state = await read(path.join(root,'daemon.json')); await writeJsonAtomic(path.join(root,'operation-fence.json'), { generation: generation + 1, daemon_id: state?.daemon_id ?? state?.config?.daemonId ?? null }); }
+  const assertCurrent = () => { assertDaemonDispatch(root); if (generation !== (dispatchGenerations.get(root) ?? 0)) throw Object.assign(new Error("control cancelled a queued productive dispatch"), { code: "operation_cancelled" }); };
+  const stop = request.operation === "daemon.stop" ? (shutdowns.get(root) ?? { pending: 0, committed: false }) : null;
+  if (stop) { stop.pending++; shutdowns.set(root, stop); }
+  let result;
+  try { result = await journalDispatch(root, request, async () => {
+    // Persist before admission so a racing fence can observe the writer.
+    if (!control) await assertDaemonOwnership(root, { "operation-id": request.id, operation: request.operation, "native-session-id": request.params?.sessionId, "prompt-sha256": typeof request.params?.prompt === "string" ? createHash("sha256").update(request.params.prompt).digest("hex") : undefined }, assertCurrent, phase => publishOperationProgress(root, request.id, phase), receipt => publishOperationWaiting(root,request.id,receipt));
+    if (!control) assertCurrent();
+    await publishOperationProgress(root, request.id, 'native_dispatched');
+    return await withOperationProgress(root, request.id, () => control ? controlDispatch(root, request, action) : action());
+  }); } catch (error) {
+    if (control) controls.get(root)?.delete(request.operation === 'daemon.stop' ? `stop:${request.params?.cancelTree === true}` : `cancel:${request.params?.sessionId ?? ''}`);
+    throw error;
+  } finally { if (stop) { stop.pending--; if (!stop.pending && !stop.committed) shutdowns.delete(root); } }
+  if (control) return result;
+  let settlement;
+  await publishRetainedProgress(root, request.id, 'settlement_started', result);
+  try {
+    settlement = await completeBudgetOperation(root, request, result, observe);
+  } catch (error) {
+    settlement = { state: "pending", reason: "settlement_error", observed_at: new Date().toISOString(), error: errorRecord(error) };
+  }
+  try { await writeSettlement(root, request.id, settlement); }
+  catch (error) {
+    settlement = { state: "blocked", reason: "settlement_storage_error", observed_at: new Date().toISOString(), error: errorRecord(error) };
+  }
+  await publishRetainedProgress(root, request.id, settlement?.state === 'settled' || settlement?.state === 'not_required' ? 'settlement_completed' : 'settlement_pending', result);
+  return settlement?.state === "not_required" || !result || typeof result !== "object" || Array.isArray(result)
+    ? result
+    : { ...result, settlement };
+}
+
+async function writeSettlement(root, id, value) {
+  const directory = location(root, id);
+  await writeJsonAtomic(path.join(directory, "settlement.json"), value);
+}
+
+/** Startup has no registered daemon yet. Its existing native implementation
+ * owns registration/admission; only the CLI entrypoint uses this journal path. */
+export async function durableDaemonStart(options, action) {
+  const root = options.stateDir;
+  if (typeof root !== "string" || !path.isAbsolute(root)) throw Object.assign(new Error("daemon startup requires an absolute state directory"), { code: "invalid_path" });
+  // Keep only configuration locations, never inherited credentials. The owned
+  // scope can reuse this exact adapter launch after retiring the old daemon.
+  const launch = { schema_id: "dd-flow/native-launch@1", executable: options.entryPath ?? null, args: process.argv.slice(2), cwd: process.cwd(), runtime_owner: process.env.DD_FLOW_RUNTIME_OWNER ?? null,
+    env: validateNativeLaunchEnvironment(Object.fromEntries([...nativeLaunchEnvironmentKeys, ...(process.env.PLAYWRIGHT_BROWSERS_PATH === undefined ? [] : ["PLAYWRIGHT_BROWSERS_PATH"])].map(key => [key, process.env[key] ?? null]))) };
+  const request = prepareDaemonRequest({ id: process.env.DD_EVAL_OPERATION_ID ?? randomUUID(), operation: "daemon.start", params: { ...options, runtimeOwner: process.env.DD_FLOW_RUNTIME_OWNER ?? null, resourceHome: process.env.DD_FLOW_RESOURCE_HOME ?? null, launch } });
+  return await journalDispatch(root, request, () => action(options));
+}
+
+async function journalDispatch(root, request, action) {
+  const directory = location(root, request.id), fingerprint = hashJson({ operation: request.operation, params: request.params ?? {} });
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  // Publish a complete request atomically and exclusively. Writing directly with
+  // wx exposes a partially written JSON document to a concurrent observer.
+  const temporary = path.join(directory, `requested-${randomUUID()}.json`);
+  const daemon = await read(path.join(root, "daemon.json"));
+  const startup = request.operation === "daemon.start";
+  const daemonId = daemon?.daemon_id ?? daemon?.config?.daemonId ?? null;
+  await writeJsonAtomic(temporary, { schema_id: "dd-flow/daemon-operation@1", operation_id: request.id, operation: request.operation, session_id: request.params?.sessionId ?? null, daemon_id: startup ? null : daemonId, owner_id: daemon?.config?.runtime_owner?.owner_id ?? null, generation: dispatchGenerations.get(root) ?? 0, ...(startup ? { predecessor_daemon_id: daemonId, launch: request.params?.launch } : {}), params_sha256: fingerprint, ...(request.invocation_sha256 ? { invocation_sha256: request.invocation_sha256 } : {}), requested_at: new Date().toISOString() });
+  try {
+    await link(temporary, path.join(directory, "requested.json"));
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const saved = await inspectDaemonOperation(root, request.id);
+    if (saved.params_sha256 !== fingerprint || (saved.invocation_sha256 ?? null) !== (request.invocation_sha256 ?? null)) throw Object.assign(new Error("operation id was reused with different parameters or invocation"), { code: "operation_conflict", details: { operation_id: request.id } });
+    if (saved.state === "completed") return saved.result;
+    if (["failed", "interrupted"].includes(saved.state)) throw reportedError(saved.error, "provider operation failed");
+    throw Object.assign(new Error("provider operation has no confirmed terminal result; inspect the existing operation instead of resending it"), { code: "operation_observation_lost", details: { operation_id: request.id, receipt_directory: directory } });
+  } finally { await unlink(temporary); }
+  let result;
+  await publishOperationProgress(root, request.id, 'accepted');
+  try {
+    result = await action();
+  }
+  catch (error) {
+    const unknown = isObservationLoss(error);
+    if (unknown) await writeJsonAtomic(path.join(directory, "observation-lost.json"), { state: "awaiting_provider", observed_at: new Date().toISOString(), error: errorRecord(error) });
+    else {
+      const terminal = await writeTerminal(root, request.id, { state: "failed", observed_at: new Date().toISOString(), error: errorRecord(error) });
+      if (terminal.state !== "failed") throw reportedError(terminal.error, "provider operation did not retain this failure");
+    }
+    throw error;
+  }
+  try {
+    const terminal = await writeTerminal(root, request.id, { state: "completed", ...(startup ? { started_daemon_id: result?.daemon_id ?? null } : {}), finished_at: new Date().toISOString(), result });
+    if (terminal.state !== "completed") throw reportedError(terminal.error, "provider operation was terminalized before its late reply arrived");
+  } catch (cause) {
+    if (cause?.code === "operation_interrupted" || cause?.code === "operation_terminal_conflict") throw cause;
+    throw Object.assign(new Error("provider returned but the durable reply could not be saved; do not resend the operation"), { code: "operation_observation_lost", cause, details: { operation_id: request.id, receipt_directory: directory } });
+  }
+  await publishRetainedProgress(root, request.id, 'native_outcome_retained', result, { session_id: result?.session_id ?? result?.sessionId });
+  return result;
+}
+
+/** `result.json` is the one exclusive terminal slot. Old interrupted.json
+ * files remain readable for compatibility, but new writes never race them. */
+async function writeTerminal(root, id, value) {
+  const file = path.join(location(root, id), "result.json");
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, "wx", 0o600);
+  try { await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`); await handle.sync(); }
+  finally { await handle.close(); }
+  try {
+    await link(temporary, file);
+    return value;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const saved = await read(file);
+    if (!saved || !["completed", "failed", "interrupted"].includes(saved.state)) throw Object.assign(new Error("operation terminal record is invalid"), { code: "operation_terminal_conflict" });
+    return saved;
+  } finally { await unlink(temporary); }
+}

package/dist/harness-runtime/lib/dd-agy-daemon.d.mts

@@ -0,0 +1,6 @@
+export declare function qualifyAgyHooks(projectRoot: string, options?: { stateDir?: string | null; install?: boolean }): Promise<{
+  hooksSha256: string;
+  workspaceHooksPath: string;
+  workspaceHooksSha256: string;
+  workspaceHooksInstalled: string;
+}>;