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

package/dist/harness-runtime/lib/delegation-instructions.d.mts

@@ -0,0 +1,14 @@
+export type DelegationWork = { work_id: string; start_command: string; launch_policy?: string };
+export type DelegationInput = { harness: string; stage: string; capacity: number; works?: DelegationWork[]; totalWorks?: number; remainingWorks?: number };
+export function delegationAdapter(harness: string): string | null;
+export function renderNativeChildFollowupInstruction(harness: string, childId: string | { session_id?: unknown; parent_session_id?: unknown; terminal_turn_id?: unknown; continuation_ref?: unknown }): string | null;
+export function delegationContract(harness: string): string;
+export const lifecycleRetryInstruction: string;
+export const lifecycleCommandCompletionInstruction: string;
+export const stageLifecycleInstruction: string;
+export function workerDelegationTask(input: { workId: string; startCommand: string; launchPolicy?: string }): string;
+export function renderDelegationInstructions(input: DelegationInput): string;
+export function renderCapacityInstructions(input: { harness: string; maximum: number }): string;
+export function renderWaitInstructions(input: { harness: string; stage: string }): string;
+export function renderAdapterPolicy(input: { harness: string }): string;
+export function renderRecoveryProbeInstructions(input: { harness: string; command: string }): string;

package/dist/harness-runtime/lib/delegation-instructions.mjs

@@ -0,0 +1,166 @@
+const ADAPTERS = {
+  codex: {
+    name: "Codex",
+    launch: "This Session uses the Codex multi-agent v2 API in the `collaboration` namespace. In code mode call `tools.collaboration__spawn_agent` once per assignment with exactly `task_name`, `message`, and `fork_turns: \"none\"` for fresh context. Keep the current model and reasoning by omitting overrides. Do not create a root Session or run the child's command yourself.",
+    wait: "The spawn result is a handle, not completion. In code mode use `tools.collaboration__wait_agent` and native completion messages until every launched child is terminal. A mailbox update is not necessarily final. A wait timeout leaves the same child running: continue waiting without relaunch or interruption. Retain terminal results and product Work receipts. Codex v2 owns idle-agent residency; do not interrupt a completed child as cleanup.",
+    partial: "If a spawn is refused, stop issuing new spawns and retain every successful child handle. Wait for every already-launched child to become terminal; silence is not completion. Do not interrupt a running child to free capacity, and do not interrupt completed children as cleanup. Report completed/launched assignments, assignments not launched and the exact refusal. Return after this partial wave; the controller will issue remaining Work when capacity is available. Do not replay an ambiguous spawn."
+  },
+  zcode: {
+    name: "ZCode",
+    launch: "Use the native `Agent` tool for every assignment in this current session. Use `TaskOutput` (or the tool's native wait operation) to await the returned child; never call a shell, create a new root session, or ask a child to create descendants.",
+    wait: "Wait on the returned native Agent task handles with `TaskOutput` (or the native wait operation) until all direct children settle. A missing or quiet result is not permission to launch a replacement.",
+  },
+  droid: {
+    name: "Droid",
+    launch: "Use the native `Task` tool for every assignment with `subagent_type: \"dd-flow-worker\"` and no complexity override. Do not use Missions, a root Session, or a shell command as a delegation substitute.",
+    wait: "Wait for each native Task result. Do not interrupt or replace a quiet Task; the coordinator remains responsible for the Stage.",
+  },
+  grok: {
+    name: "Grok",
+    launch: "Use the native `spawn_subagent` tool for each assignment in this current session. Keep the returned child handles and wait with `get_command_or_subagent_output`; do not invoke external roots or shell-based substitutes.",
+    wait: "Use `get_command_or_subagent_output` for every returned child handle before continuing. Never infer completion from silence or replace an unavailable child.",
+  },
+  opencode: {
+    name: "OpenCode",
+    launch: "Use OpenCode v2's native `subagent` tool with agent: \"dd-flow-worker\", description, and prompt containing the assignment. Omit sessionID for a fresh child and omit model overrides. For independent fanout assignments use background: true. Do not create a new root Session or use an external runner. Use `shell` with explicit workdir and timeout: 0 for issued lifecycle calls, never background those CLI calls.",
+    wait: "Await each native subagent result or its automatic background completion notification. Retain the real returned sessionID. Do not invent a wait tool or poll by sending child prompts. Native notifications can continue the parent automatically; a running tool handle is not completion. Never synthesize a Session ID or relaunch a quiet child."
+  },
+  antigravity: {
+    name: "Antigravity",
+    launch: "Use the harness's native subagent action in this current conversation for each assignment. Do not create a root Session, use an external runner, or ask a child to create descendants; the adapter will observe the native `subagent_info.subagents` records.",
+    wait: "Wait for the native child result and let the adapter observe its conversation ID and terminal status. Never invent or synthesize IDs, infer completion from text, or replace a quiet child.",
+  }
+};
+
+export function delegationAdapter(harness) {
+  const aliases = { codex: "codex", "codex-desktop": "codex", zcode: "zcode", "zcode-acp": "zcode", droid: "droid", "droid-cli": "droid", grok: "grok", "grok-acp": "grok", opencode: "opencode", "opencode-server": "opencode", agy: "antigravity", antigravity: "antigravity", "antigravity-cli": "antigravity" };
+  return Object.hasOwn(aliases, harness) ? aliases[harness] : null;
+}
+
+/** Only documented same-child APIs may continue an existing native worker. */
+export function renderNativeChildFollowupInstruction(harness, childId) {
+  const child = childId && typeof childId === "object" ? childId : null;
+  childId = child?.session_id ?? childId;
+  if (typeof childId !== "string" || !childId) return null;
+  const adapter = delegationAdapter(harness), target = JSON.stringify(childId);
+  const message = JSON.stringify("Continue the same assigned Work after the transient provider failure; do not restart it or repeat committed lifecycle commands.");
+  if (adapter === "zcode") {
+    const ref = child?.continuation_ref;
+    if (ref?.schema_id !== "zcode/child-continuation@1" || ref.capability !== "dd-flow/managed-provider-recovery@1" || ref.child_session_id !== childId
+      || ref.parent_session_id !== child.parent_session_id || ref.terminal_turn_id !== child.terminal_turn_id || !/^agent_[\w-]{1,200}$/.test(ref.agent_id ?? "")) return null;
+    return `Use the native SendMessage tool exactly once with to: ${JSON.stringify(ref.agent_id)}, summary: "Continue existing Work", and message: ${message}. Retain messageId and delivery only when the native result supplies them; never invent missing IDs. The adapter verifies typed native completion and successor evidence. Wait for this same agent with TaskOutput. If admission is uncertain, do not resend. Do not spawn a replacement or override model/reasoning.`;
+  }
+  if (adapter === "codex") return `Use collaboration.followup_task with target: ${target} and message: ${message}. Do not spawn a replacement.`;
+  if (adapter === "opencode") return `Use the native subagent tool with sessionID: ${target} and prompt: ${message}. Keep the same model and reasoning. Do not spawn a replacement.`;
+  if (adapter === "droid") return `Use the native Task tool with resume: ${target}, subagent_type: "dd-flow-worker", and prompt: ${message}. Omit model and complexity overrides. Do not spawn a replacement.`;
+  if (adapter === "grok") return `Use the native send_subagent_message tool with subagent_id: ${target}, delivery: "queue", and text: ${message}. Retain its accepted message_id and wait on the same subagent. If admission is uncertain, do not resend. Do not spawn a replacement.`;
+  return null;
+}
+
+function requireAdapter(harness) {
+  const key = delegationAdapter(harness);
+  if (!key) throw Object.assign(new Error(`Unsupported delegation adapter: ${harness}`), { code: "delegation_contract_unsupported" });
+  return ADAPTERS[key];
+}
+
+export function delegationContract(harness) {
+  const key = delegationAdapter(harness);
+  requireAdapter(harness);
+  return `dd-flow/delegation/${key}@${["codex", "opencode"].includes(key) ? 2 : 1}`;
+}
+
+export const lifecycleCommandCompletionInstruction = "Run runtime-issued lifecycle CLI calls in the foreground, never with a native background or detached-shell option. A shell tool may yield before the lifecycle process exits. Retain and poll its exact process/session handle to completion, including inside a tool wrapper; empty interim output is not a CLI result. If a wrapper returns 'Script running with cell ID …', use that wrapper's wait tool to finish the same cell before expecting an inner shell session handle; do not execute the command again. Read final stdout or response_file before deciding continuation, and never reissue the command while it is pending. When the result provides prompt_delivery, read its complete plain Markdown file at prompt_delivery.path before working; it contains the current instructions, unlike the historical prompt_path. If delivery publication is pending, stop for reconciliation without repeating the accepted command.";
+
+export const lifecycleRetryInstruction = `${lifecycleCommandCompletionInstruction} A failure is not permission to replay a lifecycle command. For proven effect=no_effect with recoverable=true and retry_command, correct the input and execute that exact issued successor. A check failure can retain receipts while leaving Work running: correct the evidenced cause first, then use the CLI's exact retry_command for an intentional fresh check attempt; never replay a check merely because Work is unsettled. If a successful CODE finish returns outcome=verification_required, inspect the retained receipts, update its verification file, and use only next.finish_command: the Stage is still running and the previous invocation ID is consumed. If continuation.kind=repair_required, or a successful result has outcome=repair_required and a repair Work ID, end this Turn for the registered repair child; use any retry_command only after that repair settles and verification is refreshed. Unknown effects require reconciliation, never replay. A committed effect without an explicit continuation is not retryable. A native shell launch refusal before the CLI starts permits correcting only that shell-form error and retrying the same exact command. Otherwise report the primary error and stop; never invent IDs, call hooks directly, or run status as a substitute.`;
+
+export const stageLifecycleInstruction = [
+  "The project root identifies this RUN; use the Stage packet's declared execution workspace and absolute artifact paths. Do not change a native Session's working directory to a workspace provisioned for a later Stage.",
+  "In a controller-managed fanout, the coordinator ends the entry Turn after the Work graph is returned; the controller dispatches children. A completed child or Work is not Stage success: settle the declared graph and Stage gate before finishing.",
+  "Execute each runtime-issued lifecycle operation and its arguments exactly. One literal lifecycle call may be composed with ordinary shell commands; preserve conditions, stdin and redirects, and never replay the surrounding shell chain after failure. Invocation IDs are internal authority; never add, copy or invent one.",
+  lifecycleRetryInstruction
+].join(" ");
+
+export function workerDelegationTask({ workId, startCommand, launchPolicy }) {
+  if (!workId || !startCommand) throw new Error("ready fan-out Work lacks its exact start command");
+  const context = launchPolicy === "fresh_agent_required"
+    ? "You are the already-selected fresh leaf worker for this Work. Execute its lifecycle start yourself; do not delegate it to another child."
+    : "You are the already-selected worker. Execute this Work yourself; do not delegate it to another child.";
+  return [
+    `Complete one already-declared Work: ${workId}.`,
+    context,
+    "Your first technical action must be this exact lifecycle command:",
+    startCommand,
+    "Execute the issued operation and target exactly. Lifecycle invocation IDs are internal runtime authority and are intentionally omitted; never add or invent them. Preserve any explicit native receipt handle that the command does contain.",
+    startCommand.startsWith("cd '")
+      ? "Execute the literal cd shell prefix exactly; it routes this command into its runtime-owned private execution copy. Do not invent native spawn fields. After start, obey the packet's read_only/write scopes and prefix subsequent issued lifecycle commands with the same literal cd route. A review copy never grants permission to write reviewed inputs. The runtime independently checks the CLI process directory."
+      : "Use the native shell's inherited working directory. Do not set or override a workdir/cwd field for this lifecycle command.",
+    "Continue only if it succeeds and returns the authoritative Work packet.",
+    lifecycleRetryInstruction,
+    "After a successful start, complete the assigned Work, write its required result, invoke its exact work finish command, then stop.",
+    "Do not start another Work, create a child, change dependencies, ask the user, or treat a quiet sibling as failed. You cannot ask the user or pause the parent Stage. Missing facts go through this Work's declared result/failure contract; only the coordinator handles Stage HITL."
+  ].join("\n");
+}
+
+export function renderDelegationInstructions({ harness, stage, capacity, works = [], totalWorks = works.length, remainingWorks = 0 }) {
+  const adapter = requireAdapter(harness);
+  const count = works.length;
+  if (!Number.isInteger(capacity) || capacity < 1 || count < 1 || count > capacity) throw new Error("Invalid native delegation wave size");
+  const assignments = works.map((work, index) => {
+    const task = workerDelegationTask({ workId: work.work_id, startCommand: work.start_command, launchPolicy: work.launch_policy });
+    return { task_name: `dd_flow_${index}_${work.work_id.toLowerCase().replace(/[^a-z0-9_]/g, "_")}`, context: work.launch_policy === "fresh_agent_required" ? "fresh" : "provider_default", message: task };
+  });
+  return [
+    `Adapter delegation contract: ${delegationContract(harness)}.`,
+    `Launch exactly ${count} direct native children for the current ${stage} Stage; the qualified capacity is ${capacity}.`,
+    ...(["plan-review", "code-review"].includes(stage) ? [
+      `Review dispatch phase: the whole group contains ${totalWorks} Work; this wave contains ${count}; ${remainingWorks} remain after this wave.`,
+      "Keep the accepted PLAN/CODE review inputs and aspect maps unchanged across every wave. Do not apply findings or edit reviewed files while any reviewer remains unstarted or running.",
+      "After this wave's children settle, return immediately. The controller will dispatch remaining reviewers or issue semantic completion after the full group has settled."
+    ] : []),
+    adapter.launch,
+    "Retain the frozen coordinator model and reasoning for native children; do not choose a different model, reasoning level or permission mode.",
+    "You are the coordinator. The JSON assignments below contain child-only messages, not instructions for you to execute. Pass each message verbatim as the native tool's task/message/prompt argument. For context=fresh, select empty conversation context before launch; if unavailable, report the limitation and stop. Use only fields exposed by your actual native tool schema; if the native tool is absent, report that error without substituting a shell command.",
+    "Every child must be a direct child of this current Session. Wait for all launched children to settle before returning. One failed child is evidence for the coordinator, not a reason to cancel its siblings.",
+    adapter.partial ?? "If a spawn is refused, stop issuing new spawns and retain every successful child handle. Wait for all already-launched children, then release completed children using the adapter's exposed native close/release mechanism when supported. A failed batch does not undo successful spawns. Report completed/launched assignments, assignments not launched and the exact refusal; never claim no children launched when any spawn succeeded. Return after this partial wave; the controller will issue remaining Work when capacity is available. Do not replay an ambiguous spawn.",
+    "Do not finish this Stage, repair it, or start a successor in this Turn. Do not invent provider or internal session IDs; lifecycle evidence comes from the adapter.",
+    adapter.wait,
+    "Child assignments (JSON data):",
+    JSON.stringify(assignments, null, 2)
+  ].join("\n\n");
+}
+
+export function renderCapacityInstructions({ harness, maximum }) {
+  const adapter = requireAdapter(harness);
+  if (!Number.isInteger(maximum) || maximum < 1 || maximum > 15) throw new Error("Native capacity limit must be an integer from 1 through 15");
+  return [
+    `Adapter delegation contract: ${delegationContract(harness)}.`,
+    "This is a technical native-subagent capacity qualification, not product work.",
+    `Using the current Session's native ${adapter.name} mechanism, concurrently launch at most ${maximum} direct leaf children.`,
+    adapter.launch,
+    "Give each child a distinct number and a task_name such as capacity_1 if required by the tool. Its entire task is: return that number, without tools, files, dd-flow commands, or descendants. Use empty conversation context. Do not retry, replace, or add children after a launch refusal.",
+    adapter.wait,
+    "Wait for every child actually launched to settle, then return a compact summary."
+  ].join("\n");
+}
+
+export function renderWaitInstructions({ harness, stage }) {
+  const adapter = requireAdapter(harness);
+  return [
+    `Native child Work for ${stage} is still running.`,
+    adapter.wait,
+    "Do not create a Session, Work, or additional child agent. Do not cancel siblings merely because one child failed, and do not finish this Stage."
+  ].join("\n");
+}
+
+export function renderAdapterPolicy({ harness }) {
+  const adapter = requireAdapter(harness);
+  return [adapter.launch, adapter.wait, "Lifecycle identity and completion must come from adapter observations; never synthesize provider or internal Session IDs."].join(" ");
+}
+
+export function renderRecoveryProbeInstructions({ harness, command }) {
+  const adapter = requireAdapter(harness);
+  return ["Technical native child cancellation qualification, not product work.", adapter.launch,
+    "Launch exactly one fresh direct child, task_name recovery_probe if required. Pass this JSON string as its message/prompt:",
+    JSON.stringify(`Run exactly this read-only command: ${command}\nDo not access files, use the network, modify anything, or create children.`),
+    adapter.wait, "External operator control will interrupt this tree. Do not close it early or launch replacements."].join("\n");
+}

package/dist/harness-runtime/lib/dispatch-fence.mjs

@@ -0,0 +1,14 @@
+const generations = new WeakMap();
+
+// A cancellation invalidates preparation already in flight, while a later
+// explicit prompt captures a fresh generation and can resume normally.
+export function captureDispatchGuard(owner) {
+  const generation = generations.get(owner) ?? 0;
+  return () => {
+    if (generation !== (generations.get(owner) ?? 0)) throw Object.assign(new Error("Prompt cancelled before native dispatch"), { code: "operation_cancelled" });
+  };
+}
+
+export function cancelPendingDispatch(owner) {
+  generations.set(owner, (generations.get(owner) ?? 0) + 1);
+}

package/dist/harness-runtime/lib/driver-recovery.mjs

@@ -0,0 +1,140 @@
+import { processSnapshot } from "./process-snapshot.mjs";
+import { readdir, readFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { inspectDaemonOperation } from "./daemon-operations.mjs";
+import { writeJsonAtomic } from "./runner-events.mjs";
+import { reportedError } from "./operation-errors.mjs";
+import { ObservationClock } from "./observation-clock.mjs";
+import { runtimeProcess } from "./managed-daemon.mjs";
+import { nativeShutdownConfirmed } from "./native-children.mjs";
+
+async function cleanShutdownConfirmed(root, state) {
+  const proof = state.shutdown;
+  let fence;
+  try { fence = JSON.parse(await readFile(path.join(root, 'operation-fence.json'), 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  return state.shutdown_state === "clean" && state.active_tree === false
+    && typeof state.daemon_id === 'string' && fence?.daemon_id === state.daemon_id && Number.isSafeInteger(fence.generation) && fence.generation >= 0
+    && nativeShutdownConfirmed(proof, { daemonId: state.daemon_id, generation: fence.generation });
+}
+
+/** Explicit same-Session restart retains native stores and the old daemon
+ * receipt; it does not turn a terminal directory into a new execution. */
+export async function authorizeRetainedDaemonResume(root, previous, sessionId, config) {
+  const sessions = [...(previous.sessions ?? []), ...(previous.root_session_id ? [previous.root_session_id] : [])];
+  if (!await cleanShutdownConfirmed(root, previous) || typeof sessionId !== "string" || !sessions.some(session => (typeof session === "string" ? session : session.provider_session_id) === sessionId)) throw Object.assign(new Error("terminal daemon restart requires a retained, settled Session identity and complete shutdown proof"), { code: "daemon_state_terminal" });
+  for (const key of ["cwd", "projectRoot", "ddFlowHome", "ddFlowBin", "provider", "model", "reasoning", "mode", "variant", "agent", "bin", "noFlow"]) {
+    if ((previous.config?.[key] ?? null) !== (config[key] ?? null)) throw Object.assign(new Error(`retained daemon configuration changed: ${key}`), { code: "daemon_config_mismatch" });
+  }
+  await assertDaemonReplaceable(root);
+  await reconcileDriverReplies(root);
+  if (!/^[a-zA-Z0-9-]+$/.test(previous.daemon_id ?? "")) throw Object.assign(new Error("original daemon identity is invalid"), { code: "daemon_state_terminal" });
+  const directory = path.join(root, "daemon-history"); await mkdir(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${previous.daemon_id}.json`), bytes = `${JSON.stringify(previous, null, 2)}\n`;
+  try { await writeFile(file, bytes, { flag: "wx", mode: 0o600 }); }
+  catch (error) { if (error.code !== "EEXIST" || await readFile(file, "utf8") !== bytes) throw error; }
+}
+
+/** A dead bridge alone does not prove its provider tree was stopped. Require
+ * the adapter's durable clean-shutdown receipt as well, for every bridge. */
+export async function recoverySettlement(driversRoot) {
+  const daemons = [];
+  const registries = new Map();
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const daemonRoot = entries.some(entry => entry.name === "daemon.json" && entry.isFile());
+    for (const entry of entries) {
+      const file = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw Object.assign(new Error("driver evidence contains a symbolic link"), { code: "recovery_settlement_unconfirmed" });
+      // Native stores contain package/auth symlinks, not adapter daemon
+      // receipts. Do not traverse their contents as a daemon inventory.
+      if (entry.isDirectory()) {
+        if (daemonRoot && ["gemini", "grok-home", "home", "xdg-data", "xdg-cache", "xdg-config"].includes(entry.name)) continue;
+        await visit(file);
+      }
+      else if (entry.name === "daemon.json") {
+        const state = JSON.parse(await readFile(file, "utf8"));
+        if (!await cleanShutdownConfirmed(directory, state)) throw Object.assign(new Error("provider tree has no complete clean shutdown receipt"), { code: "recovery_settlement_unconfirmed" });
+        await assertDaemonReplaceable(directory);
+        await reconcileDriverReplies(directory);
+        if (state.config?.resourceHome && state.resource_process?.id) {
+          const key = state.config.resourceHome;
+          if (!registries.has(key)) registries.set(key, await runtimeProcess(state.config, "status"));
+          const processes = registries.get(key)?.processes;
+          if (!Array.isArray(processes) || !processes.some(record => record.id === state.resource_process.id)) throw Object.assign(new Error("managed daemon registration is missing"), { code: "recovery_settlement_unconfirmed" });
+          const attemptRoot = path.dirname(path.resolve(driversRoot));
+          for (const record of processes.filter(record => record.id === state.resource_process.id || [record.stdout_path, record.stderr_path].some(file => typeof file === "string" && path.resolve(file).startsWith(`${attemptRoot}${path.sep}`)))) {
+            if (!["stopped", "failed"].includes(record.state)) throw Object.assign(new Error("a retained managed process has not settled"), { code: "recovery_settlement_unconfirmed", details: { process_id: record.id, state: record.state } });
+            if (Number.isInteger(record.pid) && record.pid > 0) {
+              try { process.kill(record.pid, 0); }
+              catch (error) { if (error.code === "ESRCH") continue; }
+              if (typeof record.pid_started_at === "string" && record.pid_started_at.trim()) {
+                const observed = (await processSnapshot()).find(item => item.pid === record.pid);
+                if (!observed || record.pid_started_at.trim().replace(/\s+/g, " ") !== observed.started) continue;
+              }
+              throw Object.assign(new Error("a retained managed process is still live or unconfirmed"), { code: "recovery_settlement_unconfirmed", details: { process_id: record.id } });
+            }
+          }
+        }
+        daemons.push({ state_file: file, daemon_id: state.daemon_id, shutdown_state: state.shutdown_state, pid: state.pid });
+      }
+    }
+  }
+  await visit(driversRoot);
+  if (!daemons.length) throw Object.assign(new Error("no provider shutdown evidence found"), { code: "recovery_settlement_unconfirmed" });
+  return { settled: true, reason: "observed_clean_adapter_shutdown", observed_at: new Date().toISOString(), daemons };
+}
+
+export async function assertDaemonReplaceable(root) {
+  let state;
+  try { state = JSON.parse(await readFile(path.join(root, "daemon.json"), "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  if (!Number.isInteger(state.pid) || state.pid <= 0) throw Object.assign(new Error("original daemon ownership is unknown"), { code: "operation_observation_lost", details: { state_dir: root } });
+  const pids = new Set([state.pid, state.provider_pid, ...(state.owned_processes ?? []).map(process => process.pid)].filter(pid => Number.isInteger(pid) && pid > 0));
+  for (const pid of pids) {
+    try { process.kill(pid, 0); }
+    catch (error) { if (error.code === "ESRCH") continue; }
+    const retained = state.owned_processes?.filter(record => record.pid === pid && typeof record.started === "string" && record.started.trim());
+    if (retained?.length) {
+      const observed = (await processSnapshot()).find(record => record.pid === pid);
+      if (!observed || retained.every(record => record.started !== observed.started)) continue;
+    }
+    throw Object.assign(new Error("original daemon/provider is live or its ownership is unconfirmed; do not create a competing bridge"), { code: "operation_observation_lost", details: { state_dir: root, pid } });
+  }
+}
+
+/** Observe the original operation; never re-send its parameters. */
+export async function recoverDriverReply(root, id, { timeoutMs = 30_000, pollMs = 250 } = {}) {
+  const clock = new ObservationClock({ timeoutMs });
+  do {
+    let receipt;
+    try { receipt = await inspectDaemonOperation(root, id); }
+    catch (error) { if (error.code !== "operation_not_found") throw error; }
+    if (receipt?.state === "completed") return receipt.result;
+    if (receipt?.state === "failed") throw reportedError(receipt.error, "provider operation failed");
+    if (clock.sample()) break;
+    await new Promise(resolve => setTimeout(resolve, pollMs));
+  } while (true);
+  throw Object.assign(new Error("original provider operation has no confirmed reply; reconcile it before starting another Turn"), {
+    code: "operation_observation_lost", details: { operation_id: id, state_dir: root }
+  });
+}
+
+/** Crash recovery barrier. Import late replies into the client ledger before
+ * any subsequent productive call, even when a new runner process is used. */
+export async function reconcileDriverReplies(root) {
+  const directory = path.join(root, "client-operations");
+  let entries;
+  try { entries = await readdir(directory); } catch (error) { if (error.code === "ENOENT") return; throw error; }
+  for (const entry of entries.filter(name => name.endsWith(".json"))) {
+    const file = path.join(directory, entry), record = JSON.parse(await readFile(file, "utf8"));
+    if (["completed", "failed", "interrupted"].includes(record.state)) continue;
+    let receipt;
+    try { receipt = await inspectDaemonOperation(root, record.operation_id); }
+    catch (error) { if (error.code !== "operation_not_found") throw error; }
+    if (!["completed", "failed", "interrupted"].includes(receipt?.state)) throw Object.assign(new Error("a previous driver request has an unknown outcome; no new productive request was sent"), {
+      code: "operation_observation_lost", details: { operation_id: record.operation_id, state_dir: root }
+    });
+    await writeJsonAtomic(file, { ...record, state: receipt.state, result: receipt.result, error: receipt.error, reconciled_at: new Date().toISOString() });
+  }
+}

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

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** Cache native filenames, then read only a bounded header and small settings.
+ * New child discovery may walk the directory once; heartbeats never replay it. */
+export class DroidMetadataReader {
+  constructor(factory) { this.factory = factory; this.files = new Map(); this.cache = new Map(); }
+  async locate(id) {
+    if (this.files.has(id)) return this.files.get(id);
+    const visit = async directory => {
+      for (const entry of await readdir(directory, { withFileTypes: true }).catch(error => { if (error.code === "ENOENT") return []; throw error; })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory()) await visit(file);
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) this.files.set(entry.name.slice(0, -6), file);
+      }
+    };
+    await visit(path.join(this.factory, "sessions"));
+    return this.files.get(id) ?? null;
+  }
+  async read(id) {
+    const file = await this.locate(id); if (!file) return null;
+    const settingsFile = file.replace(/\.jsonl$/, ".settings.json");
+    const info = await stat(settingsFile).catch(error => { if (error.code === "ENOENT") return null; throw error; });
+    if (!info || info.size > 1_048_576) return null;
+    const identity = `${info.ino}:${info.mtimeMs}:${info.size}`;
+    if (this.cache.get(id)?.identity === identity) return this.cache.get(id).value;
+    const handle = await open(file, "r"); const buffer = Buffer.alloc(65_536);
+    let header;
+    try { const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0); header = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8").split("\n")[0]); }
+    finally { await handle.close(); }
+    if (header.type !== "session_start" || header.id !== id) throw Object.assign(new Error("native metadata Session identity differs"), { code: "session_identity_mismatch" });
+    let bytes, settings;
+    try { bytes = await readFile(settingsFile, "utf8"); settings = JSON.parse(bytes); }
+    catch (error) { if (error instanceof SyntaxError || error.code === "ENOENT") return null; throw error; }
+    const value = { header, settings, transcript_path: file, source: { path: settingsFile, sha256: createHash("sha256").update(bytes).digest("hex") } };
+    this.cache.set(id, { identity, value }); return value;
+  }
+}
+
+export function parseDroidRoutingLine(line) {
+  if (!line.includes("[Model-Router] Model transition | Context: ")) return null;
+  let context; try { context = JSON.parse(line.split(" | Context: ").slice(1).join(" | Context: ")); } catch { return null; }
+  if (context.slot !== "main" || typeof context.sessionId !== "string" || typeof context.modelId !== "string") return null;
+  return { session_id: context.sessionId, model: context.modelId, previous_model: context.previousModelId ?? null,
+    reason: typeof context.reason === "string" ? context.reason : null, native_timestamp: /^\[([^\]]+)\]/.exec(line)?.[1] ?? null,
+    event_sha256: createHash("sha256").update(line).digest("hex") };
+}
+
+/** Keep the cursor in daemon state. Bound every read, tolerate incomplete lines
+ * and restart from zero after truncation/rotation of this execution's own log. */
+export async function readDroidRoutingLog(file, cursor = {}) {
+  let handle;
+  try { handle = await open(file, "r"); } catch (error) { if (error.code === "ENOENT") return { cursor, events: [] }; throw error; }
+  try {
+    const info = await handle.stat();
+    const offset = info.ino === cursor.ino && info.size >= (cursor.offset ?? 0) ? cursor.offset ?? 0 : 0;
+    const buffer = Buffer.alloc(Math.min(1_048_576, Math.max(0, info.size - offset)));
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+    const end = buffer.subarray(0, bytesRead).lastIndexOf(10) + 1;
+    const lines = buffer.subarray(0, end).toString("utf8").split("\n");
+    // Persist offsets only, never a partial native line that may contain secrets.
+    return { cursor: { ino: info.ino, offset: offset + (end || (bytesRead === buffer.length && bytesRead === 1_048_576 ? bytesRead : 0)) }, events: lines.map(parseDroidRoutingLine).filter(Boolean) };
+
+  } finally { await handle.close(); }
+}

package/dist/harness-runtime/lib/entity-references.d.mts

@@ -0,0 +1,2 @@
+export function shortEntityReference(id: string): string;
+export function entityReferenceVariants(id: string): string[];

package/dist/harness-runtime/lib/entity-references.mjs

@@ -0,0 +1,9 @@
+/** Stable model-facing reference for persisted project, RUN and Work IDs. */
+export function shortEntityReference(id) {
+  return /^(?:PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id;
+}
+
+/** Accepted spellings of one already-resolved entity. Wrong full slugs stay distinct. */
+export function entityReferenceVariants(id) {
+  return [...new Set([id, shortEntityReference(id)])];
+}

package/dist/harness-runtime/lib/lease-renewal.d.mts

@@ -0,0 +1,8 @@
+export const RENEWAL_POLICY: Readonly<{ startupMs: number; budgetMs: number; attemptMs: number; safetyMs: number }>;
+export type RenewalState = { uncertainSince: number | null; attempt: number; exhausted: boolean; leaseExpiresAt: string | null };
+export function createRenewalState(options?: { leaseExpiresAt?: string | null }): RenewalState;
+export function renewalRemaining(state: RenewalState, now?: number, wallNow?: number): number;
+export function renewalFailure(state: RenewalState, now?: number): number;
+export function renewalDelay(state: RenewalState): number;
+export function renewalConfirmed(state: RenewalState, now?: number, leaseExpiresAt?: string | null): boolean;
+export function maintenanceRetryable(error: unknown): boolean;

package/dist/harness-runtime/lib/lease-renewal.mjs

@@ -0,0 +1,37 @@
+/** Shared policy only; transports and owner-specific fences stay at callsites. */
+export const RENEWAL_POLICY = Object.freeze({ startupMs: 120_000, budgetMs: 126_000, attemptMs: 5_000, safetyMs: 1_000 });
+export function createRenewalState({ leaseExpiresAt = null } = {}) { return { uncertainSince: null, attempt: 0, exhausted: false, leaseExpiresAt }; }
+export function renewalRemaining(state, now = performance.now(), wallNow = Date.now()) {
+  const expiry = Date.parse(state.leaseExpiresAt ?? "");
+  const budget = Number.isFinite(expiry) ? Math.max(0, expiry - wallNow - RENEWAL_POLICY.safetyMs) : state.leaseExpiresAt != null ? 0 : RENEWAL_POLICY.budgetMs;
+  const remaining = state.exhausted ? 0 : Number.isFinite(expiry) || state.uncertainSince === null ? budget : Math.max(0, budget - (now - state.uncertainSince));
+  if (remaining === 0) state.exhausted = true;
+  return remaining;
+}
+export function renewalFailure(state, now = performance.now()) { state.uncertainSince ??= now; state.attempt++; return renewalRemaining(state, now); }
+export function renewalDelay(state) { return Math.min(2_000, 250 * 2 ** Math.min(3, Math.max(0, state.attempt - 1))); }
+export function renewalConfirmed(state, now = performance.now(), leaseExpiresAt = null) {
+  // Caller verifies exact owner/fence. A committed receipt, not elapsed time,
+  // establishes the new authority horizon.
+  if (leaseExpiresAt !== null) {
+    const expiry = Date.parse(leaseExpiresAt);
+    if (!Number.isFinite(expiry) || expiry <= Date.now() + RENEWAL_POLICY.safetyMs) return false;
+    state.leaseExpiresAt = leaseExpiresAt; state.exhausted = false;
+  }
+  if (!renewalRemaining(state, now)) return false;
+  state.uncertainSince = null; state.attempt = 0; return true;
+}
+export function maintenanceRetryable(error) {
+  let retryable = false;
+  // Inspect only bounded typed causes from our maintenance transport, never text.
+  for (let depth = 0; error && depth < 8; depth++, error = error.cause ?? error.details?.cause) {
+    if (error.details?.cleanup_unconfirmed === true || error.cleanup_error || error.details?.cleanup_error
+      || error.details?.store_cleanup_errors?.length || error.details?.transaction_cleanup_error || error.details?.transaction_close_error) return false;
+    if (error.details?.effect === "unknown") return false;
+    if (["process_lease_lost", "controller_lease_lost", "process_maintenance_receipt_invalid", "runtime_owner_mismatch"].includes(error.code)) return false;
+    if (error.code === "process_ownership_unknown" && error.details?.reason === "physical_identity_unavailable" && ["process_confirmation", "observer_registration"].includes(error.details.phase) && error.details.effect === "no_effect" && error.details.native_dispatch_started === false) retryable = true;
+    if (["process_heartbeat_timeout", "process_maintenance_timeout", "hook_deadline_exceeded", "native_hook_timeout", "SQLITE_BUSY", "SQLITE_LOCKED"].includes(error.code)) retryable = true;
+    if (error.code === "ERR_SQLITE_ERROR" && [5, 6].includes((error.details?.sqlite_extended_code ?? error.sqlite_extended_code ?? error.errcode) & 255)) retryable = true;
+  }
+  return retryable;
+}

package/dist/harness-runtime/lib/lifecycle-command.d.mts

@@ -0,0 +1,20 @@
+import type { LifecycleOperation } from "./lifecycle-contract.mjs";
+export type { LifecycleOperation } from "./lifecycle-contract.mjs";
+export interface ParsedCommandArgs { positional: string[]; options: Map<string, string[]> }
+export interface LifecycleInvocation {
+  operation: LifecycleOperation; executable: string; launcher?: string; argv: string[]; env: Record<string, string>; args: ParsedCommandArgs; command: string;
+  rewriteSafe: boolean; wrapped: boolean; heredoc: boolean; sourceRange?: { start: number; end: number }; contexts?: string[]; expectedCwd?: string;
+}
+export type LifecycleAnalysis = ({ participation: "none" | "lifecycle" | "auxiliary" | "unproven"; auxiliary?: { operation: string; args: ParsedCommandArgs; expectedCwd?: string } } & (
+  | { kind: "none"; unresolved?: true; reason?: string }
+  | { kind: "standalone"; invocation: LifecycleInvocation; supported?: boolean; invocations?: LifecycleInvocation[] }
+  | { kind: "compound"; invocation: LifecycleInvocation; reason: string; supported?: boolean; invocations?: LifecycleInvocation[] }));
+export function lifecycleCommandFromPayload(payload: { command?: unknown; tool_input?: unknown }): string | undefined;
+export function parseLifecycleCommand(command: string): LifecycleAnalysis;
+export function continuationCommand(command: string): { operation: string; args: ParsedCommandArgs; expectedCwd?: string } | null;
+export function unwrapShellCommand(command: string): string;
+export function parseCommandArgs(argv: string[]): ParsedCommandArgs;
+export function commandOption(invocation: LifecycleInvocation, name: string): string | undefined;
+export function commandHasOption(invocation: LifecycleInvocation, name: string): boolean;
+export function commandPosition(invocation: LifecycleInvocation, index: number): string | undefined;
+export function shellSuffixOffset(command: string): number;