@andromarces/agent-loops 0.2.1 → 0.3.0

package/src/lib/process-ancestry.mjs

@@ -0,0 +1,104 @@
+// Process-ancestry harness detection (#139). A nested harness inherits the
+// parent's session variables, so no environment variable can identify the
+// running harness. The nearest harness process above the shell command can.
+// Returns null when the platform, the process table, or the ancestry is absent,
+// so the Claude, Codex, and Antigravity skills refuse to start instead of
+// registering the wrong parent.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+// Process basename (lowercased, extension stripped) to harness id.
+const HARNESS_BY_PROCESS = new Map([
+  ["claude", "claude"],
+  ["codex", "codex"],
+  ["copilot", "copilot"],
+  ["opencode", "opencode"],
+  ["agy", "antigravity"],
+  ["antigravity", "antigravity"],
+]);
+
+export function harnessForProcessName(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return null;
+  }
+  const normalized = name
+    .trim()
+    .split(/[\\/]/)
+    .pop()
+    .toLowerCase()
+    .replace(/\.(exe|cmd|bat|com)$/, "");
+  return HARNESS_BY_PROCESS.get(normalized) ?? null;
+}
+
+async function readWindowsProcesses() {
+  const script =
+    "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Json -Compress";
+  const { stdout } = await execFileAsync(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", script],
+    { windowsHide: true, maxBuffer: 32 * 1024 * 1024 },
+  );
+  const parsed = JSON.parse(stdout.trim() || "[]");
+  const rows = Array.isArray(parsed) ? parsed : [parsed];
+  return rows.map((row) => ({
+    pid: row.ProcessId,
+    ppid: row.ParentProcessId,
+    name: row.Name,
+  }));
+}
+
+async function readPosixProcesses() {
+  const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid=,comm="], {
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  return stdout
+    .split("\n")
+    .map((line) => line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/))
+    .filter(Boolean)
+    .map((match) => ({ pid: Number(match[1]), ppid: Number(match[2]), name: match[3] }));
+}
+
+export async function readProcessTable() {
+  return process.platform === "win32" ? readWindowsProcesses() : readPosixProcesses();
+}
+
+/**
+ * Walks from `startPid` to the first process that is a known harness.
+ * @returns {Promise<string|null>} the harness id, or null when ancestry is absent
+ */
+export async function nearestHarness({
+  startPid = process.ppid,
+  readProcesses = readProcessTable,
+} = {}) {
+  if (!Number.isInteger(Number(startPid)) || Number(startPid) <= 0) {
+    return null;
+  }
+  const byPid = new Map();
+  for (const entry of await readProcesses()) {
+    byPid.set(String(entry.pid), entry);
+  }
+
+  const seen = new Set();
+  let pid = String(startPid);
+  while (pid && !seen.has(pid)) {
+    seen.add(pid);
+    const entry = byPid.get(pid);
+    if (!entry) {
+      return null;
+    }
+    const harness = harnessForProcessName(entry.name);
+    if (harness) {
+      return harness;
+    }
+    if (entry.ppid === undefined || entry.ppid === null) {
+      return null;
+    }
+    pid = String(entry.ppid);
+    if (pid === "0" || pid === "1") {
+      return null;
+    }
+  }
+  return null;
+}

package/src/lib/runstate.mjs

@@ -3,13 +3,18 @@
 // resolved work tree cwd, never passed as a flag; tests override the runs
 // root with AGENT_LOOP_RUNS_ROOT.
 import { createHash } from "node:crypto";
-import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { link, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { logWarn } from "./log.mjs";
 
 export const TERMINAL_LIFECYCLES = new Set(["halted", "finished", "aborted"]);
 
+// An unparseable lock younger than this is never treated as stale: a fresh
+// unreadable lock is a contender racing a removal, a foreign file, or (on the
+// exclusive-create fallback path) a half-written owner.
+export const STALE_LOCK_GRACE_MS = 60_000;
+
 /**
  * Resolve the state paths for one run. `cwd` derives the per-work-tree state
  * directory; `parentSession` derives the session index entry that the #57 hook
@@ -54,8 +59,24 @@ function canonicalCwd(cwd) {
   return resolved.replace(/^[A-Za-z]:/, (drive) => drive.toLowerCase());
 }
 
+// A parent session id is one path segment under <root>/sessions and is matched
+// verbatim against the harness session id by the #57 guard. Real harness ids
+// are opaque tokens, but an unexpanded template (`${CLAUDE_SESSION_ID}`,
+// `%CODEX_THREAD_ID%`, `<parent-session-id>`), a path separator, or whitespace
+// can only come from a caller that failed to expand its placeholder. Any of
+// them would register a run whose parent never matches, so refuse all of them
+// before a state file exists. A bare placeholder name with no punctuation
+// (`CLAUDE_SESSION_ID`) is indistinguishable from a real token here; only a
+// harness-id allowlist would catch it, which ADR 0006 rejects.
+const SESSION_ID_FORBIDDEN = /[\\/\0\s$`{}%<>]/;
+
 function assertSessionId(sessionId) {
-  if (!sessionId || /[\\/\0]/.test(sessionId) || sessionId === "." || sessionId === "..") {
+  if (
+    !sessionId ||
+    sessionId === "." ||
+    sessionId === ".." ||
+    SESSION_ID_FORBIDDEN.test(sessionId)
+  ) {
     throw new Error(`Invalid session id: ${JSON.stringify(sessionId ?? null)}`);
   }
 }
@@ -81,13 +102,17 @@ export async function readStateForSession(parentSession) {
 }
 
 /**
- * Exclusive access around one state-file operation. Creates `state.lock` with
- * O_EXCL, treats an existing lock with a live owner pid as busy and a dead one
- * as stale (removed with a warning, then retried). Returns a release function.
+ * Exclusive access around one state-file operation. Creates `state.lock` (an
+ * atomic hard link where supported, otherwise an exclusive create), treats an
+ * existing lock with a live owner pid as busy and a dead one as stale
+ * (removed with a warning, then retried). Returns the result of `fn`. `label`
+ * names the guarded resource in a refusal, so an installer refusal can say what
+ * is locked instead of the generic default; `noun` is the same resource as a
+ * lowercase phrase for the stale-removal warning.
  */
-export async function withStateLock(lockFile, fn) {
+export async function withStateLock(lockFile, fn, { label = "State", noun = "state" } = {}) {
   await mkdir(dirname(lockFile), { recursive: true });
-  await acquireLock(lockFile);
+  await acquireLock(lockFile, { label, noun });
   try {
     return await fn();
   } finally {
@@ -95,47 +120,121 @@ export async function withStateLock(lockFile, fn) {
   }
 }
 
-async function acquireLock(lockFile, retry = true) {
-  try {
-    const handle = await open(lockFile, "wx");
-    try {
-      await handle.writeFile(
-        JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
-        "utf8",
-      );
-    } finally {
-      await handle.close();
-    }
-    // The O_EXCL create above is the lock; the content write closes the
-    // reader-visible window. Contenders finding an unparseable lock fail
-    // closed below and never remove it while it is fresh.
+// Monotonic suffix for lock temp files; keeps same-process contenders that
+// share a pid on distinct paths so one's cleanup never removes another's.
+let lockTempCounter = 0;
+
+// `link` is the atomic create primitive, but FAT/exFAT and some network mounts
+// have no hard links and report one of these codes. They fall back to an
+// exclusive create, where the pre-#176 create/write window returns.
+// EISDIR is the Windows mapping: libuv translates the ERROR_INVALID_FUNCTION
+// from CreateHardLinkW on FAT/exFAT to EISDIR (nodejs/node#65817).
+const LINK_UNSUPPORTED = new Set([
+  "EPERM",
+  "EACCES",
+  "ENOTSUP",
+  "EOPNOTSUPP",
+  "EINVAL",
+  "ENOSYS",
+  "EMLINK",
+  "EXDEV",
+  "EISDIR",
+]);
+
+// Matches the `<pid>.<counter>.tmp` suffix of a lock temp file name.
+const LOCK_TEMP_SUFFIX = /^(\d+)\.\d+\.tmp$/;
+
+async function acquireLock(lockFile, { retry = true, label = "State", noun = "state" } = {}) {
+  if (await createLock(lockFile)) {
+    // Best-effort removal of temp files left by a crash between the temp write
+    // and the link (#178). Runs while the lock is held and never touches a live
+    // contender's temp, so it cannot break a racing acquisition.
+    await pruneStaleLockTemps(lockFile);
     return;
-  } catch (err) {
-    if (err.code !== "EEXIST") {
-      throw err;
-    }
   }
 
   const owner = await readLockOwner(lockFile);
   if (owner && pidAlive(owner.pid)) {
     throw new Error(
-      `State is locked by a live process (pid ${owner.pid}, started ${owner.startedAt ?? "unknown"}).`,
+      `${label} is locked by a live process (pid ${owner.pid}, started ${owner.startedAt ?? "unknown"}).`,
     );
   }
 
   if (!owner && (await lockAgeMs(lockFile)) < STALE_LOCK_GRACE_MS) {
-    // Unparseable and fresh: the creator may still be between create and
-    // content write, so it is never treated as stale here.
-    throw new Error("State is locked (the lock file is not readable yet; retry shortly).");
+    // Unparseable and fresh: fail closed. On a link-capable filesystem creation
+    // is atomic, so this is a removal race (lockAgeMs reads 0 on ENOENT) or a
+    // foreign file; the exclusive-create fallback can leave a half-written
+    // owner, which this refusal also covers.
+    throw new Error(`${label} is locked (the lock file is not readable yet; retry shortly).`);
   }
 
   if (!retry) {
-    throw new Error("State lock could not be acquired after stale removal.");
+    throw new Error(`${label} lock could not be acquired after stale removal.`);
   }
 
-  logWarn(`removing stale state lock (dead pid ${owner?.pid ?? "unknown"})`);
+  logWarn(`removing stale ${noun} lock (dead pid ${owner?.pid ?? "unknown"})`);
   await rm(lockFile, { force: true });
-  return acquireLock(lockFile, false);
+  return acquireLock(lockFile, { retry: false, label, noun });
+}
+
+// Create the lock and its owner content. The owner JSON goes to a private temp
+// file that is hard linked to the lock path; the link is atomic, so EEXIST
+// means a contender won and the owner is readable the instant the lock exists
+// (fixes #176 path 1). On a filesystem with no hard links, an exclusive create
+// and write keeps the lock usable at the cost of that window. Returns false
+// only when another owner already holds the lock.
+async function createLock(lockFile) {
+  const owner = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  const tempFile = `${lockFile}.${process.pid}.${lockTempCounter++}.tmp`;
+  await writeFile(tempFile, owner, "utf8");
+  try {
+    await link(tempFile, lockFile);
+    return true;
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      return false;
+    }
+    if (!LINK_UNSUPPORTED.has(err.code)) {
+      throw err;
+    }
+    try {
+      await writeFile(lockFile, owner, { encoding: "utf8", flag: "wx" });
+      return true;
+    } catch (openErr) {
+      if (openErr.code === "EEXIST") {
+        return false;
+      }
+      throw openErr;
+    }
+  } finally {
+    await rm(tempFile, { force: true });
+  }
+}
+
+// Removes lock temp files whose creating pid is gone. A live contender's temp
+// is never touched, so a concurrent acquisition is unaffected; failures are
+// ignored because cleanup is best-effort and must not fail the lock holder.
+async function pruneStaleLockTemps(lockFile) {
+  try {
+    const dir = dirname(lockFile);
+    const prefix = `${basename(lockFile)}.`;
+    for (const entry of await readdir(dir)) {
+      if (!entry.startsWith(prefix)) {
+        continue;
+      }
+      const match = LOCK_TEMP_SUFFIX.exec(entry.slice(prefix.length));
+      if (match === null) {
+        continue;
+      }
+      const pid = Number(match[1]);
+      if (pid === process.pid || pidAlive(pid)) {
+        continue;
+      }
+      await rm(join(dir, entry), { force: true });
+    }
+  } catch {
+    // The lock is already held; a failed scan or unlink leaves only a temp file.
+  }
 }
 
 export function pidAlive(pid) {
@@ -159,10 +258,6 @@ async function readLockOwner(lockFile) {
   }
 }
 
-// An unparseable lock younger than this is assumed to be a contender still
-// between create and content write; only an older one is stale.
-export const STALE_LOCK_GRACE_MS = 60_000;
-
 async function lockAgeMs(lockFile) {
   try {
     const stats = await stat(lockFile);
@@ -200,7 +295,7 @@ export async function writeState(stateFile, state) {
   await rename(temp, stateFile);
 }
 
-export async function appendSessionIndex(sessionIndexFile, stateFile) {
+export async function writeSessionIndex(sessionIndexFile, stateFile) {
   // The index entry is overwritten by the next init call from the same session.
   await mkdir(dirname(sessionIndexFile), { recursive: true });
   return writeFile(sessionIndexFile, `${stateFile}\n`, "utf8");

package/src/lib/snapshot.mjs

@@ -1,7 +1,7 @@
-import { createHash } from "node:crypto";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { execa } from "execa";
+import { sha256 } from "./hash.mjs";
 import { logDebug, logError } from "./log.mjs";
 
 export class MutationError extends Error {
@@ -34,10 +34,6 @@ export async function assertGitWorkTree(cwd) {
   }
 }
 
-function sha256(data) {
-  return createHash("sha256").update(data).digest("hex");
-}
-
 // Returns null only for an absent or non-regular file; read errors other than ENOENT propagate.
 export async function sha256File(path) {
   let s;
@@ -141,8 +137,8 @@ export async function snapshot(cwd) {
 /**
  * Diff two snapshots. Returns the sorted changed work-tree paths, plus the
  * sentinel entries `<index>` and `<HEAD>` when the index or HEAD changed.
- * @param {ReturnType<typeof snapshot>} before
- * @param {ReturnType<typeof snapshot>} after
+ * @param {Awaited<ReturnType<typeof snapshot>>} before
+ * @param {Awaited<ReturnType<typeof snapshot>>} after
  * @returns {string[]}
  */
 export function diffSnapshots(before, after) {

package/src/role.mjs

@@ -6,19 +6,24 @@ import { readFile, appendFile, rename } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { defaultAgents, normalizeAgent, supportedAgents } from "./agents/index.mjs";
 import {
+  CHILD_ROLE_KINDS,
+  DEFAULT_MAX_STEPS,
+  DEFAULT_TIMEOUT,
+  ROLE_FLAG_BY_OPTION,
   assertOpenCodeOptions,
   readArgValue,
   readNonNegativeInt,
   readPositiveInt,
+  roleFlags,
 } from "./lib/args.mjs";
 import { logInfo, setVerbose, setLogsToStderr } from "./lib/log.mjs";
 import { parseReportBlock, parseVerdict } from "./lib/report.mjs";
 import {
   TERMINAL_LIFECYCLES,
-  appendSessionIndex,
   readState,
   statePaths,
   withStateLock,
+  writeSessionIndex,
   writeState,
 } from "./lib/runstate.mjs";
 import { assertGitWorkTree } from "./lib/snapshot.mjs";
@@ -27,9 +32,8 @@ import { validateAction } from "./contracts/orchestrator-action.mjs";
 
 const OPERATIONS = new Set(["dispatch", "finish", "abort"]);
 const MODES = new Set(["work-first", "review-first", "review-only"]);
-const ROLE_NAMES = new Set(["worker", "reviewer"]);
-const DEFAULT_MAX_STEPS = 20;
-const DEFAULT_TIMEOUT = 3600;
+const ROLE_NAMES = new Set(CHILD_ROLE_KINDS);
+const ROLE_FLAGS = roleFlags(CHILD_ROLE_KINDS);
 // Bound for `raw` in the envelope when the closing block could not be parsed.
 const RAW_TAIL_LIMIT = 2000;
 
@@ -107,26 +111,6 @@ export function parseRoleArgs(argv) {
         args.parentSession = readValue(arg, ++index);
         break;
 
-      case "--worker":
-        args.worker = readValue(arg, ++index);
-        break;
-      case "--worker-model":
-        args.workerModel = readValue(arg, ++index);
-        break;
-      case "--worker-effort":
-        args.workerEffort = readValue(arg, ++index);
-        break;
-
-      case "--reviewer":
-        args.reviewer = readValue(arg, ++index);
-        break;
-      case "--reviewer-model":
-        args.reviewerModel = readValue(arg, ++index);
-        break;
-      case "--reviewer-effort":
-        args.reviewerEffort = readValue(arg, ++index);
-        break;
-
       case "--max-steps":
         args.maxSteps = readPositiveInt(arg, readValue(arg, ++index));
         break;
@@ -159,7 +143,11 @@ export function parseRoleArgs(argv) {
         break;
 
       default:
-        throw new RoleError(`Unknown argument: ${arg}`);
+        if (!Object.hasOwn(ROLE_FLAGS, arg)) {
+          throw new RoleError(`Unknown argument: ${arg}`);
+        }
+        args[ROLE_FLAGS[arg]] = readValue(arg, ++index);
+        break;
     }
   }
 
@@ -175,9 +163,8 @@ function isInitCall(args) {
   return args.task !== null;
 }
 
-/** Loads state for a non-init call, rejecting a missing state file. */
-async function loadExistingState(paths, cwd) {
-  const state = await readState(paths.stateFile);
+/** Rejects a non-init call when no state file exists for the work tree. */
+function requireState(state, cwd) {
   if (!state) {
     throw new RoleError(
       `No run state for ${cwd}. Start one with: agent-loop role --task "..." --worker ... --reviewer ...`,
@@ -190,9 +177,17 @@ function validateInitFlags(args, agents = {}) {
   if (args.task === null || String(args.task).trim() === "") {
     throw new RoleError('Init requires --task, for example --task "Implement the change."');
   }
+  // The parent guard is the hard backstop for the prompt-only parent rule, so an
+  // interactive run is never left unguarded by default. The headless `agent-loop`
+  // command (no subcommand) is the explicit unguarded path.
+  if (args.parentSession === null) {
+    throw new RoleError(
+      "Init requires --parent-session (the harness session id the parent-edit guard matches).",
+    );
+  }
   // review-only never dispatches the worker, so --worker is optional there.
   const requiredRoles =
-    (args.mode ?? "work-first") === "review-only" ? ["reviewer"] : ["worker", "reviewer"];
+    (args.mode ?? "work-first") === "review-only" ? ["reviewer"] : CHILD_ROLE_KINDS;
   for (const roleName of requiredRoles) {
     if (args[roleName] === null) {
       throw new RoleError(`Missing required --${roleName}.`);
@@ -200,12 +195,12 @@ function validateInitFlags(args, agents = {}) {
   }
   // Every supplied role is still validated; review-only may omit the worker.
   // A model or effort without its role kind is an orphan option, not a silent drop.
-  for (const roleName of ["worker", "reviewer"]) {
+  for (const roleName of CHILD_ROLE_KINDS) {
     const kind = args[roleName];
     if (kind === null) {
       for (const flag of [`${roleName}Model`, `${roleName}Effort`]) {
         if (args[flag] !== null) {
-          throw new RoleError(`--${kebab(flag)} requires --${roleName}.`);
+          throw new RoleError(`${ROLE_FLAG_BY_OPTION[flag]} requires --${roleName}.`);
         }
       }
       continue;
@@ -251,52 +246,30 @@ function roleState(source, roleName) {
 }
 
 /**
- * New-run rule: init over a terminal or absent state file archives any
- * existing file as `state.<timestamp>.json` and creates a new state; init over
- * a non-terminal lifecycle is rejected and the parent must abort it first.
+ * Archives a terminal state file as `state.<timestamp>.json` so a new run can
+ * take its place. Absence is a no-op. Called only after every init check and
+ * the prompt read pass, so a rejected init archives nothing (#123).
  */
-async function initRun(args, paths, existing, agents) {
-  validateInitFlags(args, agents);
-
-  if (existing) {
-    if (!TERMINAL_LIFECYCLES.has(existing.lifecycle)) {
-      throw new RoleError(
-        `Existing run is ${existing.lifecycle}; abort it before starting a new run.`,
-      );
-    }
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const archived = join(dirname(paths.stateFile), `state.${stamp}.json`);
-    await rename(paths.stateFile, archived);
-    logInfo(`archived terminal state file to ${archived}`);
+async function archiveState(paths, existing) {
+  if (!existing) {
+    return;
   }
-
-  const state = initialState(args);
-  await writeState(paths.stateFile, state);
-  if (args.parentSession) {
-    await appendSessionIndex(paths.sessionIndexFile, paths.stateFile);
-  }
-  logInfo(`initialized run state (mode: ${state.mode}, maxSteps: ${state.maxSteps})`);
-  return state;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const archived = join(dirname(paths.stateFile), `state.${stamp}.json`);
+  await rename(paths.stateFile, archived);
+  logInfo(`archived terminal state file to ${archived}`);
 }
 
-const INIT_COMPARATORS = {
-  task: (state) => state.task,
-  mode: (state) => state.mode,
-  parentSession: (state) => state.parentSession,
-  maxSteps: (state) => state.maxSteps,
-  timeout: (state) => state.timeout,
-};
-
 /** Later calls read configuration from the state file and reject any change. */
 function rejectInitFlagChanges(args, state) {
   const provided = [];
   for (const flag of INIT_FIELDS) {
     const isGiven = flag === "timeout" ? args.timeoutProvided : args[flag] !== null;
     if (isGiven) {
-      provided.push([flag, args[flag], INIT_COMPARATORS[flag](state)]);
+      provided.push([flag, args[flag], state[flag]]);
     }
   }
-  for (const roleName of ["worker", "reviewer"]) {
+  for (const roleName of CHILD_ROLE_KINDS) {
     for (const [flag, path] of [
       [roleName, "kind"],
       [`${roleName}Model`, "model"],
@@ -316,7 +289,7 @@ function rejectInitFlagChanges(args, state) {
   for (const [flag, value, existing] of provided) {
     if (value !== existing) {
       throw new RoleError(
-        `--${kebab(flag)} cannot be changed after init (state holds: ${JSON.stringify(existing ?? null)}).`,
+        `${ROLE_FLAG_BY_OPTION[flag] ?? `--${kebab(flag)}`} cannot be changed after init (state holds: ${JSON.stringify(existing ?? null)}).`,
       );
     }
   }
@@ -407,12 +380,24 @@ async function dispatch(args, { agents, stdin = readStdin, signal }) {
 }
 
 async function dispatchLocked(args, { agents, stdin, signal, paths, onEvent }) {
-  let state = await readState(paths.stateFile);
+  const existing = await readState(paths.stateFile);
   const init = isInitCall(args);
+  let state;
+
   if (init) {
-    state = await initRun(args, paths, state, agents);
+    // New-run rule: init over a terminal or absent state file is allowed; init
+    // over a non-terminal lifecycle is rejected and the parent must abort it
+    // first. Nothing is archived or written until every init check and the
+    // prompt read pass, so a rejected init leaves the previous state untouched.
+    validateInitFlags(args, agents);
+    if (existing && !TERMINAL_LIFECYCLES.has(existing.lifecycle)) {
+      throw new RoleError(
+        `Existing run is ${existing.lifecycle}; abort it before starting a new run.`,
+      );
+    }
+    state = initialState(args);
   } else {
-    state = await loadExistingState(paths, args.cwd);
+    state = requireState(existing, args.cwd);
     rejectInitFlagChanges(args, state);
   }
 
@@ -452,6 +437,17 @@ async function dispatchLocked(args, { agents, stdin, signal, paths, onEvent }) {
 
   const prompt = await readPrompt(args, stdin);
 
+  if (init) {
+    // Every check and the prompt read passed; now archive the old terminal
+    // state file, if any, and write the new one.
+    await archiveState(paths, existing);
+    await writeState(paths.stateFile, state);
+    if (args.parentSession) {
+      await writeSessionIndex(paths.sessionIndexFile, paths.stateFile);
+    }
+    logInfo(`initialized run state (mode: ${state.mode}, maxSteps: ${state.maxSteps})`);
+  }
+
   // Charge the step before execution, matching the headless runtime.
   state.stepsUsed += 1;
   state.lifecycle = "dispatched";
@@ -474,24 +470,12 @@ async function dispatchLocked(args, { agents, stdin, signal, paths, onEvent }) {
     });
   } catch (err) {
     const canceled = Boolean(err?.isCanceled);
+    const payload = { role: roleName, status: "error", error: errorMessage(err) };
     state.lifecycle = canceled ? "interrupted" : "halted";
-    state.lastResult = {
-      role: roleName,
-      status: "error",
-      error: errorMessage(err),
-      at: new Date().toISOString(),
-    };
+    state.lastResult = { ...payload, at: new Date().toISOString() };
     await writeState(paths.stateFile, state);
-    onEvent({
-      type: "result",
-      role: roleName,
-      result: { role: roleName, status: "error", error: errorMessage(err) },
-      stepsUsed: state.stepsUsed,
-    });
-    return {
-      exitCode: canceled ? 130 : 1,
-      payload: { role: roleName, status: "error", error: errorMessage(err) },
-    };
+    onEvent({ type: "result", role: roleName, result: payload, stepsUsed: state.stepsUsed });
+    return { exitCode: canceled ? 130 : 1, payload };
   }
 
   state.lifecycle = "active";
@@ -537,7 +521,7 @@ async function finish(args, { stdin = readStdin }) {
 
   const paths = statePaths({ cwd: args.cwd });
   return withStateLock(paths.lockFile, async () => {
-    const state = await loadExistingState(paths, args.cwd);
+    const state = requireState(await readState(paths.stateFile), args.cwd);
     rejectInitFlagChanges(args, state);
     if (TERMINAL_LIFECYCLES.has(state.lifecycle)) {
       throw new RoleError(`Run is already ${state.lifecycle}.`);
@@ -577,7 +561,7 @@ async function abort(args) {
 
   const paths = statePaths({ cwd: args.cwd });
   return withStateLock(paths.lockFile, async () => {
-    const state = await loadExistingState(paths, args.cwd);
+    const state = requireState(await readState(paths.stateFile), args.cwd);
     rejectInitFlagChanges(args, state);
     if (TERMINAL_LIFECYCLES.has(state.lifecycle)) {
       throw new RoleError(`Run is already ${state.lifecycle}.`);