faberun 0.3.0

package/src/engine/bulk-read.mjs

@@ -0,0 +1,361 @@
+/**
+ * One question about many files, answered without the files ever entering the
+ * asking context: the exact bytes are packed into a single temp file, a
+ * delegated provider reads that one file and answers in bullets, and only the
+ * bullets come back. Packing, table-driven delegation routing, and the
+ * usage.jsonl accounting of a delegation live here because all three are
+ * engine work; the CLI shape belongs to cli.mjs and the command build to the
+ * adapter registry.
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdtempSync, openSync, readSync, rmSync, statSync, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { DECLARED_MODEL_CATALOGUES, stableJsonDocument } from "../harnesses/catalogue.mjs";
+import { READ_LINE_LIMIT, normalizeProviderResult, providerCommand } from "../harnesses/index.mjs";
+import { appendUsageRecord, emptyUsage, priceUsage } from "../run/usage.mjs";
+import { errorMessage, fail } from "../util.mjs";
+import { DISCOVERY_RUNTIME_DEFINITIONS } from "./runtime-discovery.mjs";
+
+/** Fixed-size copy buffer: the pack is built through this, never through a corpus-sized string. */
+const CHUNK_BYTES = 64 * 1024;
+/** Answer budget: bullets are small, so anything past this is a runaway provider, not evidence. */
+const ANSWER_LIMIT_BYTES = 512 * 1024;
+/** Rough bytes-per-token heuristic, not a measurement; it only sizes windows an order apart. */
+const CORPUS_BYTES_PER_TOKEN = 4;
+/** Wall clock for one delegated read+answer. Not measured; generous on purpose, SIGKILL backs the SIGTERM. */
+const DELEGATION_TIMEOUT_MS = 300_000;
+
+/** @typedef {import("../harnesses/index.mjs").HarnessRuntime} HarnessRuntime */
+/** @typedef {import("../harnesses/index.mjs").ProviderEnvelope} ProviderEnvelope */
+/** @typedef {import("./process.mjs").Invocation} Invocation */
+
+/**
+ * A routing-table entry: the same shape `DISCOVERY_RUNTIME_DEFINITIONS` carries,
+ * with `vendor` optional because routing never compares vendors.
+ *
+ * @typedef {{harness: string, model: string, vendor?: string, tier?: number, costRank?: number, config?: Record<string, unknown>}} BulkReadRuntime
+ */
+
+/** @typedef {{question: string, paths: string[], cwd?: string, runtimes?: Record<string, BulkReadRuntime>}} BulkReadOptions */
+
+/** @typedef {{status: "done"|"refused"|"failed", result: string|null, runtimeId: string|null, usage: {inputTokens: number|null, outputTokens: number|null, cacheReadInputTokens: number|null}|null, costUsd: number|null, costProvenance?: "priced", reason: string|null, error: {code: string, message: string}|null}} BulkReadResult */
+
+/**
+ * Copy every path's exact bytes into one pack file through a fixed-size chunk
+ * buffer — header, byte-a-byte content, footer, no inserted newlines — so no
+ * buffer or string the size of the corpus is ever allocated. Line counts cover
+ * content only, the way the delegation floor is measured.
+ *
+ * @param {string[]} paths
+ * @param {string} packPath
+ * @returns {{bytes: number, lines: number, files: number}}
+ */
+export function writeBulkReadPack(paths, packPath) {
+  const chunk = Buffer.alloc(CHUNK_BYTES);
+  const out = openSync(packPath, "wx", 0o600);
+  let bytes = 0;
+  let lines = 0;
+  try {
+    for (const path of paths) {
+      const header = `<file path="${path.replaceAll("\"", "&quot;")}">`;
+      bytes += writeSync(out, header, null, "utf8");
+      const fd = openSync(path, "r");
+      try {
+        let read;
+        while ((read = readSync(fd, chunk, 0, chunk.length, null)) > 0) {
+          for (let index = 0; index < read; index += 1) {
+            if (chunk[index] === 0x0a) lines += 1;
+          }
+          bytes += writeSync(out, chunk, 0, read);
+        }
+      } finally {
+        closeSync(fd);
+      }
+      bytes += writeSync(out, "</file>", null, "utf8");
+    }
+  } finally {
+    closeSync(out);
+  }
+  return { bytes, lines, files: paths.length };
+}
+
+/**
+ * Sort key mirroring the discovery allocation law: tier first, costRank
+ * second, declaration order through sort stability.
+ *
+ * @param {BulkReadRuntime} runtime
+ * @returns {[number, number]}
+ */
+function bulkReadOrder(runtime) {
+  return [runtime.tier ?? runtime.costRank ?? Number.MAX_SAFE_INTEGER, runtime.costRank ?? Number.MAX_SAFE_INTEGER];
+}
+
+/**
+ * The declared context window of a runtime's model, from the catalogue the
+ * `models` report already keeps. `null` means undeclared, and an undeclared
+ * window is no reason to refuse a runtime.
+ *
+ * @param {BulkReadRuntime} runtime
+ * @returns {number|null}
+ */
+function declaredContextWindow(runtime) {
+  const model = (DECLARED_MODEL_CATALOGUES[runtime.harness] ?? []).find((entry) => entry.id === runtime.model);
+  return model?.contextWindowTokens ?? null;
+}
+
+/**
+ * The cheapest table entry whose declared window holds the corpus.
+ *
+ * @param {Record<string, BulkReadRuntime>} runtimes
+ * @param {number} corpusTokens
+ * @returns {string|null}
+ */
+function selectBulkReadRuntime(runtimes, corpusTokens) {
+  return Object.entries(runtimes)
+    .filter(([, runtime]) => {
+      const window = declaredContextWindow(runtime);
+      return window === null || corpusTokens <= window;
+    })
+    .sort((left, right) => {
+      const [leftTier, leftRank] = bulkReadOrder(left[1]);
+      const [rightTier, rightRank] = bulkReadOrder(right[1]);
+      return leftTier - rightTier || leftRank - rightRank;
+    })
+    .at(0)?.[0] ?? null;
+}
+
+/**
+ * @param {string} packPath
+ * @param {number} files
+ * @param {string} question
+ * @returns {string}
+ */
+function delegationPrompt(packPath, files, question) {
+  return [
+    `Answer one question about ${files} files packed into one file.`,
+    `Read ${packPath}. It holds each file's exact bytes wrapped as <file path="...">…</file>.`,
+    "Answer with bullets only. Every bullet starts with the exact symbol name or file:line number it concerns. No greeting, no prose.",
+    `Question: ${question}`,
+  ].join("\n");
+}
+
+/**
+ * @typedef {{startedAt: string, stdout: string, stderr: string, exitCode: number|null, signal: string|null, spawnError: string|null}} DelegationObservation */
+
+/**
+ * The runner environment plus the command's env overlay — a null overlay value
+ * removes the ambient variable, the same contract the spawn gate applies.
+ *
+ * @param {Record<string, string|null>|undefined} overlay
+ * @returns {NodeJS.ProcessEnv}
+ */
+function environmentWith(overlay) {
+  const env = { ...process.env };
+  for (const [key, value] of Object.entries(overlay ?? {})) {
+    if (value === null) delete env[key];
+    else env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * Spawn one delegated provider with the command `providerCommand` builds — the
+ * same argv, prompt transport, and env overlay every other invocation uses —
+ * and collect a bounded answer.
+ *
+ * @param {HarnessRuntime} runtime
+ * @param {string} prompt
+ * @param {string} cwd
+ * @returns {Promise<DelegationObservation>}
+ */
+function invokeDelegation(runtime, prompt, cwd) {
+  const command = providerCommand(runtime, prompt);
+  /** @type {DelegationObservation} */
+  const observation = { startedAt: new Date().toISOString(), stdout: "", stderr: "", exitCode: null, signal: null, spawnError: null };
+  return new Promise((resolve) => {
+    /** @type {import("node:child_process").ChildProcess} */
+    let child;
+    try {
+      child = spawn(command.executable, command.args, {
+        cwd,
+        env: environmentWith(command.env),
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (error) {
+      observation.spawnError = errorMessage(error);
+      resolve(observation);
+      return;
+    }
+    let settled = false;
+    /** @type {ReturnType<typeof setTimeout>|null} */
+    let timer = null;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(observation);
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      observation.stdout = (observation.stdout + chunk).slice(-ANSWER_LIMIT_BYTES);
+    });
+    child.stderr?.on("data", (chunk) => {
+      observation.stderr = (observation.stderr + chunk).slice(-4096);
+    });
+    // stdin adapters own the prompt stream; argv adapters carry it in args and
+    // still get their unused stdin pipe closed.
+    child.stdin?.on("error", () => {
+      // A provider exiting before draining stdin is not a failure of the answer.
+    });
+    child.stdin?.end(command.promptTransport === "stdin" ? command.input ?? undefined : undefined);
+    timer = setTimeout(() => {
+      observation.signal = "SIGTERM";
+      child.kill("SIGTERM");
+      // A delegation that outlives its SIGTERM gets SIGKILL five seconds later.
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+    }, DELEGATION_TIMEOUT_MS);
+    child.once("error", (error) => {
+      observation.spawnError = errorMessage(error);
+      finish();
+    });
+    child.once("close", (exitCode, signal) => {
+      observation.exitCode = exitCode;
+      observation.signal = observation.signal ?? signal;
+      finish();
+    });
+  });
+}
+
+/**
+ * Record the delegation in the owning run's usage.jsonl when the controller
+ * exported the run directory and node it belongs to. A human terminal exports
+ * neither, and the accounting is skipped without error.
+ *
+ * `priced` is the already-computed `{costUsd, costProvenance}` pair from the
+ * one `priceUsage` call in `bulkRead`; this function never reprices.
+ *
+ * @param {string} runtimeId
+ * @param {HarnessRuntime} runtime
+ * @param {ProviderEnvelope} envelope
+ * @param {{costUsd: number|null, costProvenance: "priced"|undefined}} priced
+ * @param {DelegationObservation} observation
+ */
+function accountDelegation(runtimeId, runtime, envelope, priced, observation) {
+  const runDir = process.env.FABERUN_RUN_DIR;
+  const nodeId = process.env.FABERUN_NODE_ID;
+  if (!runDir || !nodeId) return;
+  appendUsageRecord(runDir, /** @type {Invocation} */ ({
+    id: randomUUID(),
+    runId: basename(runDir),
+    nodeId,
+    role: "worker",
+    runtimeId,
+    model: runtime.model,
+    usage: envelope.usage,
+    costUsd: priced.costUsd,
+    costProvenance: priced.costProvenance,
+    startedAt: observation.startedAt,
+    closedAt: new Date().toISOString(),
+  }));
+}
+
+/** @param {string} reason @returns {BulkReadResult} */
+function refused(reason) {
+  return { status: "refused", result: null, runtimeId: null, usage: null, costUsd: null, reason, error: null };
+}
+
+/**
+ * Ask one question about many files. Refuses — never tolerates — a corpus the
+ * delegation floor says to read directly, and a corpus no declared window
+ * holds.
+ *
+ * @param {BulkReadOptions} options
+ * @returns {Promise<BulkReadResult>}
+ */
+export async function bulkRead(options) {
+  const question = options.question.trim();
+  const paths = [...new Set(options.paths.map((path) => path.trim()).filter(Boolean))];
+  if (!question) throw fail("invalid_options", "bulk-read requires a question");
+  if (!paths.length) throw fail("invalid_options", "bulk-read requires at least one path");
+  for (const path of paths) {
+    if (!statSync(path, { throwIfNoEntry: false })?.isFile()) throw fail("invalid_path", `not a readable file: ${path}`);
+  }
+  const runtimes = options.runtimes ?? DISCOVERY_RUNTIME_DEFINITIONS;
+  const directory = mkdtempSync(join(tmpdir(), "faberun-bulk-read-"));
+  const packPath = join(directory, "corpus.pack");
+  try {
+    const pack = writeBulkReadPack(paths, packPath);
+    if (pack.lines < READ_LINE_LIMIT) {
+      return refused(`corpus is ${pack.lines} lines across ${pack.files} files, below the ${READ_LINE_LIMIT}-line delegation floor — read the files directly`);
+    }
+    const corpusTokens = Math.ceil(pack.bytes / CORPUS_BYTES_PER_TOKEN);
+    const runtimeId = selectBulkReadRuntime(runtimes, corpusTokens);
+    if (!runtimeId) {
+      return refused(`corpus of ~${corpusTokens} tokens fits no declared runtime context window — split the paths or read the files directly`);
+    }
+    const runtime = /** @type {HarnessRuntime} */ ({ ...runtimes[runtimeId], id: runtimeId });
+    const observation = await invokeDelegation(runtime, delegationPrompt(packPath, pack.files, question), options.cwd ?? process.cwd());
+    const envelope = observation.spawnError !== null
+      ? {
+        status: /** @type {"failed"} */ ("failed"),
+        result: null,
+        continuationId: null,
+        usage: emptyUsage(),
+        costUsd: null,
+        error: { code: "spawn_error", message: observation.spawnError },
+      }
+      : normalizeProviderResult(runtime, observation.stdout, observation.exitCode, observation.signal, { stderr: observation.stderr });
+    // Price once, here, and thread the same pair into the ledger and every
+    // returned result. `costProvenance` is present only as `"priced"`, never as
+    // the ledger's separate `"provider"` rule — a provider-reported number
+    // leaves it absent on the result while `appendUsageRecord` writes
+    // `"provider"` for the record.
+    const priced = priceUsage(runtime, envelope.usage, envelope.costUsd);
+    const provenance = priced.costProvenance ? { costProvenance: priced.costProvenance } : {};
+    accountDelegation(runtimeId, runtime, envelope, priced, observation);
+    if (envelope.status !== "done" && envelope.status !== "no-op") {
+      return {
+        status: "failed",
+        result: null,
+        runtimeId,
+        usage: envelope.usage,
+        costUsd: priced.costUsd,
+        ...provenance,
+        reason: null,
+        error: envelope.error ?? { code: `provider_${envelope.status}`, message: observation.stderr.split(/\r?\n/u).filter(Boolean).at(-1) ?? envelope.status },
+      };
+    }
+    return { status: "done", result: envelope.result ?? "", runtimeId, usage: envelope.usage, costUsd: priced.costUsd, ...provenance, reason: null, error: null };
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The CLI shape, in the `modelsCommand` pattern: normalize the parsed options,
+ * run the work, write the report. Bullets go to stdout on success; a refusal
+ * or failure explains itself on stderr and fails the exit code.
+ *
+ * @param {{question?: unknown, paths?: unknown, json?: boolean}} options
+ * @returns {Promise<void>}
+ */
+export async function bulkReadCommand(options = {}) {
+  const question = typeof options.question === "string" ? options.question.trim() : "";
+  const paths = (Array.isArray(options.paths) ? options.paths : [])
+    .flatMap((value) => String(value).split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (!question || !paths.length) throw fail("invalid_options", "bulk-read requires --question <text> and --paths <a,b,c>");
+  const result = await bulkRead({ question, paths });
+  if (options.json === true) {
+    process.stdout.write(stableJsonDocument(result));
+  } else if (result.status === "done") {
+    process.stdout.write(`${(result.result ?? "").trim()}\n`);
+  } else {
+    process.stderr.write(`[bulk-read] ${result.reason ?? `${result.error?.code ?? "failed"}: ${result.error?.message ?? ""}`}\n`);
+  }
+  if (result.status !== "done") process.exitCode = 1;
+}

package/src/engine/cancel.mjs

@@ -0,0 +1,177 @@
+/**
+ * Stopping a run that is still going.
+ *
+ * `cancel` is not a flag on a loop: the controller may be another process, or
+ * gone with its lock still on disk. It signals the holder, waits for the
+ * process to actually die rather than assuming, takes over the now-stale lock,
+ * terminates every recorded invocation, and only then marks the run terminal.
+ * It refuses a lock held by its own process, because that is a bug and not a
+ * cancellation.
+ */
+import { LockBusyError, acquire as acquireLock, pidAlive, readLock } from "../run/lock.mjs";
+import { SETTLED } from "./prompts.mjs";
+import { assertRunMutable } from "./lifecycle.mjs";
+import { delay, errorCode } from "../util.mjs";
+import { invocationOwned } from "./process-identity.mjs";
+import { terminateInvocation } from "./process.mjs";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { readRunNodes } from "./scheduler.mjs";
+import { syncAgentSignal } from "../repo/signal.mjs";
+import { transition, writeNode } from "./state.mjs";
+import { validateContract } from "../contract/index.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+
+/** @typedef {import("./process.mjs").InvocationProbe} InvocationProbe */
+/** @typedef {import("../cli.mjs").LockHandle} LockHandle */
+/** @typedef {import("../run/lock.mjs").LockRecord} LockRecord */
+
+/**
+ * @param {string} runDirPath
+ * @returns {Promise<boolean>}
+ */
+export async function cancelRun(runDirPath) {
+  const runDir = resolve(runDirPath);
+  assertRunMutable(runDir);
+  const contractPath = join(runDir, "contract.json");
+  const contract = validateContract(JSON.parse(readFileSync(contractPath, "utf8")), contractPath, { persisted: true });
+  writeJsonAtomic(join(runDir, "cancel.request.json"), { requestedAt: new Date().toISOString(), pid: process.pid });
+  const current = readLock(runDir);
+  const holder = current && !current.invalid ? /** @type {LockRecord} */ (current) : null;
+  if (holder && holder.pid === process.pid) {
+    throw new Error("cancel cannot take over a controller lock held by this process");
+  }
+  if (holder) {
+    const controller = { pid: holder.pid, processStartToken: holder.processStartToken };
+    if (invocationOwned(controller)) {
+      signalController(holder, "SIGTERM");
+      if (!await waitForProcessDeath(controller, 2_000)) {
+        signalController(holder, "SIGKILL");
+        if (!await waitForProcessDeath(controller, 2_000)) throw new Error("cancel could not confirm controller termination");
+      }
+    }
+  }
+  const controllerLock = await acquireStaleLock(runDir);
+  try {
+    const states = readRunNodes(runDir, contract);
+    /** @type {Error[]} */
+    const failures = [];
+    for (const state of states) {
+      for (const invocation of state.invocations ?? []) {
+        if (invocation.status === "active" || invocationOwned(invocation)) {
+          try {
+            await terminateInvocation(invocation, { runDir });
+          } catch (error) {
+            failures.push(error instanceof Error ? error : new Error(String(error)));
+          }
+        }
+      }
+      for (const invocation of state.invocations ?? []) {
+        if (invocationOwned(invocation)) failures.push(new Error(`provider invocation ${invocation.id} is still alive after cancellation`));
+      }
+      for (const attempt of state.verification?.attempts ?? []) {
+        if (attempt.status !== "active" && (!attempt.pid || !invocationOwned(attempt))) continue;
+        if (attempt.pid) {
+          try {
+            await terminateInvocation({
+              id: attempt.invocationId,
+              pid: attempt.pid,
+              processGroupId: attempt.processGroupId,
+              processStartToken: attempt.processStartToken,
+            }, { runDir });
+          } catch (error) {
+            failures.push(error instanceof Error ? error : new Error(String(error)));
+          }
+        }
+        if (attempt.pid && invocationOwned(attempt)) failures.push(new Error(`verification attempt ${attempt.invocationId} is still alive after cancellation`));
+        const completedAt = new Date().toISOString();
+        state.verification = state.verification ?? { passed: false, commands: [], completed: false, attempts: [] };
+        state.verification.attempts = (state.verification.attempts ?? []).map((item) => item.invocationId === attempt.invocationId
+          ? { ...item, status: "canceled", completedAt, result: { passed: false, stdout: "", stderr: "", error: "verification canceled", exitCode: null, signal: "SIGTERM", timedOut: false, durationMs: null } }
+          : item);
+        state.verification.completed = true;
+        state.verification.passed = false;
+        state.verification.error = "verification canceled";
+      }
+      if (state.verification?.attempts?.length) writeNode(runDir, state, controllerLock);
+      if (failures.length) continue;
+      const closedAt = new Date().toISOString();
+      const invocations = (state.invocations ?? []).map((invocation) => invocation.status === "active"
+        ? { ...invocation, status: "terminated", closedAt, updatedAt: closedAt }
+        : invocation);
+      if (!SETTLED.has(state.status)) transition(runDir, state, "canceled", { phase: "canceled", invocations }, controllerLock);
+    }
+    if (failures.length) {
+      const error = new Error(`cancel could not confirm termination of ${failures.length} invocation${failures.length === 1 ? "" : "s"}`);
+      error.cause = failures[0];
+      throw error;
+    }
+    if (!await waitForTerminal(runDir, 1_000)) throw new Error("cancel could not confirm a terminal run state");
+    syncAgentSignal(join(runDir, ".."));
+    return true;
+  } finally {
+    controllerLock.release();
+  }
+}
+/**
+ * The controller pid is already confirmed dead (or was never alive) by the
+ * time this is called, so the lock is stale and acquire() takes it over on
+ * its own; the retry here only covers a lock file whose write has not
+ * settled yet, never a live rival.
+ * @param {string} runDir
+ * @returns {Promise<LockHandle>}
+ */
+async function acquireStaleLock(runDir) {
+  for (;;) {
+    try {
+      return acquireLock(runDir);
+    } catch (error) {
+      if (!(error instanceof LockBusyError)) throw error;
+      const holder = /** @type {LockRecord|null} */ (error.lock);
+      if (!holder || pidAlive(holder.pid)) throw error;
+      await delay(50);
+    }
+  }
+}
+/**
+ * @param {LockRecord} lock
+ * @param {NodeJS.Signals} signal
+ */
+function signalController(lock, signal) {
+  if (!invocationOwned({ pid: lock.pid, processStartToken: lock.processStartToken })) return;
+  try {
+    process.kill(lock.pid, signal);
+  } catch (error) {
+    // ESRCH: the controller is already gone. EPERM: it is not ours to signal.
+    if (errorCode(error) !== "ESRCH" && errorCode(error) !== "EPERM") throw error;
+  }
+}
+/**
+ * @param {InvocationProbe} invocation
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+async function waitForProcessDeath(invocation, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!invocationOwned(invocation)) return true;
+    await delay(50);
+  }
+  return !invocationOwned(invocation);
+}
+/**
+ * @param {string} runDir
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+async function waitForTerminal(runDir, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const contractPath = join(runDir, "contract.json");
+    const contract = validateContract(JSON.parse(readFileSync(contractPath, "utf8")), contractPath, { persisted: true });
+    const states = readRunNodes(runDir, contract);
+    if (states.every((state) => SETTLED.has(state.status)) && states.every((state) => (state.invocations ?? []).every((invocation) => !invocationOwned(invocation)))) return true;
+    await delay(100);
+  }
+  return false;
+}

package/src/engine/detach.mjs

@@ -0,0 +1,101 @@
+/**
+ * The detached-bootstrap handshake, from the controller's side.
+ *
+ * `run --detach` and `resume --detach` spawn a second process that becomes the
+ * controller and outlives the launcher. The launcher must not exit until that
+ * child has proved it owns the run, and the child must not start burning tokens
+ * until the launcher has seen the proof. The two halves meet in three files
+ * under the run directory, all named by `run/store.mjs`:
+ *
+ *   bootstrap.json              the child's own claim: status, pid, start token
+ *   bootstrap.<nonce>.json      that claim, per attempt, so a stale one is
+ *                               distinguishable from the current one
+ *   bootstrap.<nonce>.ack.json  the launcher's acknowledgement of the claim
+ *
+ * The nonce travels to the child in `FABERUN_BOOTSTRAP_NONCE`, so the
+ * child can recognise its own attempt among the artifacts of earlier ones.
+ *
+ * This module holds the controller's half, because the controller is what waits
+ * on the acknowledgement. Until 2026-09-11 it lived in the CLI, which made
+ * `engine/scheduler.mjs` import `cli.mjs` -- the one import cycle in the tree
+ * that a layered layout could not express. The launcher's half (writing the
+ * acknowledgement, spawning the child, deciding whether *this* process is the
+ * detached child at all) stays in the CLI, where the answer depends on which
+ * file was the process entry point.
+ */
+import { randomUUID } from "node:crypto";
+import { unlinkSync } from "node:fs";
+import { sameProcessStartToken, validBootstrapNonce } from "../run/lock.mjs";
+import { bootstrapAckPath, bootstrapAttemptPath, readJson } from "../run/store.mjs";
+import { delay, errorCode } from "../util.mjs";
+
+/** How long a detached child waits for its launcher to acknowledge. */
+const ACKNOWLEDGEMENT_TIMEOUT_MS = 5_000;
+
+/** @typedef {{status?: string, nonce?: string, pid?: number, processStartToken?: string|null}} BootstrapRecord */
+
+/**
+ * The nonce this controller process should stamp on its bootstrap record: the
+ * one its launcher handed it, or a fresh one when it was started directly.
+ *
+ * @returns {string}
+ */
+export function bootstrapNonceForProcess() {
+  return validBootstrapNonce(process.env.FABERUN_BOOTSTRAP_NONCE)
+    ? /** @type {string} */ (process.env.FABERUN_BOOTSTRAP_NONCE)
+    : randomUUID();
+}
+
+/**
+ * Block until the launcher acknowledges this exact claim -- same nonce, same
+ * pid, same process start token, so a reused pid cannot be mistaken for it.
+ * Returns on timeout rather than failing: an unacknowledged controller has
+ * still taken the lock and is still the owner, and the launcher's silence is
+ * the launcher's problem.
+ *
+ * @param {string} runDir
+ * @param {{nonce: string, pid: number, processStartToken: string|null}} expected
+ * @returns {Promise<void>}
+ */
+export async function waitForBootstrapAcknowledgement(runDir, expected) {
+  if (!validBootstrapNonce(expected.nonce)) return;
+  const deadline = Date.now() + ACKNOWLEDGEMENT_TIMEOUT_MS;
+  const path = bootstrapAckPath(runDir, expected.nonce);
+  try {
+    while (Date.now() < deadline) {
+      try {
+        const acknowledgement = /** @type {BootstrapRecord} */ (readJson(path));
+        if (
+          acknowledgement.status === "acknowledged" &&
+          acknowledgement.nonce === expected.nonce &&
+          acknowledgement.pid === expected.pid &&
+          sameProcessStartToken(acknowledgement.processStartToken, expected.processStartToken)
+        ) {
+          return;
+        }
+      } catch (error) {
+        if (errorCode(error) !== "ENOENT") throw error;
+      }
+      await delay(25);
+    }
+  } finally {
+    cleanupBootstrapNonce(runDir, expected.nonce);
+  }
+}
+
+/**
+ * Remove one attempt's artifacts. Both halves of the handshake call this, so
+ * the successful path leaves nothing behind for the next attempt to read.
+ *
+ * @param {string} runDir
+ * @param {string} nonce
+ */
+export function cleanupBootstrapNonce(runDir, nonce) {
+  if (!validBootstrapNonce(nonce)) return;
+  for (const path of [bootstrapAttemptPath(runDir, nonce), bootstrapAckPath(runDir, nonce)]) {
+    try { unlinkSync(path); } catch (error) {
+      if (errorCode(error) !== "ENOENT") throw error;
+    }
+  }
+}
+