catherd-cli 1.4.0 → 1.5.0

package/src/services/budget.ts

@@ -2,13 +2,14 @@ import { existsSync, readFileSync } from "node:fs";
 import { adapterFor } from "../adapters/registry.ts";
 import "../adapters/all.ts";
 import { type Budget, type BudgetStatus, budgetStatus, type Spend } from "../domain/budget.ts";
+import { CatherdError } from "../domain/errors.ts";
 import type { RunRecord } from "../domain/record.ts";
 import { dispatchPaths } from "../infra/dispatch-dir.ts";
 import { type Dispatch, liveDispatches } from "./dispatches.ts";
 import { readAgentRuns, readRecords, type Run } from "./run-store.ts";
 
 /** Tokens a running dispatch has used so far, summed from the events its CLI has written. */
-export function liveTokens(d: Dispatch): number {
+export function liveTokens(d: Dispatch, strict = false): number {
   const a = adapterFor(d.admit.backend);
   const file = dispatchPaths(d.dir).events;
   if (!a || !existsSync(file)) return 0;
@@ -17,8 +18,13 @@ export function liveTokens(d: Dispatch): number {
     if (!line.trim()) continue;
     try {
       const t = a.parse(line).tokens;
-      if (t) n += t.input + t.output;
-    } catch {
+      if (t) {
+        if (strict && Object.values(t).some((value) => !Number.isFinite(value) || value < 0))
+          throw new CatherdError("E_RUN_CORRUPT", `dispatch ${d.admit.dispatchId} has invalid token usage`);
+        n += t.input + t.output;
+      }
+    } catch (error) {
+      if (strict && error instanceof CatherdError) throw error;
       // a line the adapter cannot read adds nothing
     }
   }
@@ -29,15 +35,29 @@ export function liveTokens(d: Dispatch): number {
  * Spec §4.6: minutes are wall clock since run_start; tokens and dollars sum every record (every
  * backend), every native subagent run the orchestrator reported, and what live roles used so far.
  */
-export function spendOf(run: Run, records: RunRecord[], live: Dispatch[], now: number): Spend {
-  const agents = readAgentRuns(run);
+export function spendOf(
+  run: Run,
+  records: RunRecord[],
+  live: Dispatch[],
+  now: number,
+  strict = false,
+): Spend {
+  const agents = readAgentRuns(run, strict);
+  if (strict) {
+    const invalid = (value: number | null) => value !== null && (!Number.isFinite(value) || value < 0);
+    if (
+      records.some((record) => Object.values(record.tokens).some(invalid) || invalid(record.costUsd)) ||
+      agents.some((agent) => invalid(agent.totalTokens) || invalid(agent.costUsd))
+    )
+      throw new CatherdError("E_RUN_CORRUPT", `run ${run.id} has invalid cost or token usage`);
+  }
   const sum = <T>(xs: T[], f: (x: T) => number) => xs.reduce((n, x) => n + f(x), 0);
   return {
     minutes: Math.max(0, (now - Date.parse(run.meta.createdAt)) / 60_000),
     tokens:
       sum(records, (r) => r.tokens.input + r.tokens.output) +
       sum(agents, (a) => a.totalTokens) +
-      sum(live, liveTokens),
+      sum(live, (dispatch) => liveTokens(dispatch, strict)),
     usd: sum(records, (r) => r.costUsd ?? 0) + sum(agents, (a) => a.costUsd ?? 0),
   };
 }

package/src/services/catalog-service.ts

@@ -99,18 +99,23 @@ export function measuredSecs(base: Catalog): Catalog["secs"] {
     if (kind) add(`${canonical}|${kind}`, secs);
   };
   for (const run of listRuns().runs) {
-    const routes = readRoutes(run);
-    for (const r of readRecords(run).records)
-      if (r.status === "ok") count(routes, r.rung, r.secs, r.lane, r.startedAt);
-    for (const a of readAgentRuns(run)) {
-      if (a.status !== "ok" || a.secs === null) continue;
-      // a row is written when the subagent ends; it started `secs` earlier
-      const lane = typeof a.lane === "string" ? a.lane : null;
-      const end = Date.parse(a.at);
-      // a duration past the Date range (record_agent_run takes any) keeps the end, not a RangeError
-      const start = new Date(end - a.secs * 1000);
-      const startedAt = Number.isNaN(start.getTime()) ? a.at : start.toISOString();
-      count(routes, a.rung, a.secs, lane, startedAt);
+    // a run whose files cannot be read gives no timings; it never fails a route (1.2 minor)
+    try {
+      const routes = readRoutes(run);
+      for (const r of readRecords(run).records)
+        if (r.status === "ok") count(routes, r.rung, r.secs, r.lane, r.startedAt);
+      for (const a of readAgentRuns(run)) {
+        if (a.status !== "ok" || a.secs === null) continue;
+        // a row is written when the subagent ends; it started `secs` earlier
+        const lane = typeof a.lane === "string" ? a.lane : null;
+        const end = Date.parse(a.at);
+        // a duration past the Date range (record_agent_run takes any) keeps the end, not a RangeError
+        const start = new Date(end - a.secs * 1000);
+        const startedAt = Number.isNaN(start.getTime()) ? a.at : start.toISOString();
+        count(routes, a.rung, a.secs, lane, startedAt);
+      }
+    } catch (e) {
+      log("debug", "catalog", { run: run.id, timings: errorMessage(e) });
     }
   }
   const secs: Catalog["secs"] = {};
@@ -340,6 +345,8 @@ function rungRows(
         date: string;
         /** spec 1.2 §5.3: the rung a borrowed or inferred value belongs to */
         from?: string;
+        /** what lent it: a treat-like's mapping (`like X`) or an inferred stand-in's guess (1.2 minor) */
+        lent?: "treat-like" | "stand-in";
       }
     > = {};
     for (const v of valuesUsed(c, info.canonical))
@@ -351,6 +358,7 @@ function rungRows(
         source: v.source,
         date: v.date,
         ...(v.from ? { from: v.from } : {}),
+        ...(v.lent ? { lent: v.lent } : {}),
       };
     const like = c.treatLike[info.canonical] ?? null;
     return {

package/src/services/credentials.ts

@@ -1,7 +1,8 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { CatherdError, isCatherdError } from "../domain/errors.ts";
+import { withFileLockSync } from "../infra/filelock.ts";
 import { log } from "../infra/log.ts";
 import { configDir } from "../infra/paths.ts";
 import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
@@ -45,13 +46,17 @@ export function savedCredential(field: CredentialField): {
 
 /**
  * Keeps every other credential, and the file at mode 600 (spec §10.4). A missing file starts empty; an
- * unreadable or newer-schema one is refused (it throws) rather than overwritten.
+ * unreadable or newer-schema one is refused (it throws) rather than overwritten. The read and the write hold
+ * the file's lock (1.2 minor), so two concurrent `init`s never lose a key.
  */
 export function saveCredential(field: CredentialField, key: string): void {
-  const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
-    ? readCredentials()
-    : { schema: 1 };
-  writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, [field]: key.trim() }, { mode: 0o600 });
+  mkdirSync(configDir(), { recursive: true });
+  withFileLockSync(credentialsPath(), () => {
+    const cur: z.infer<typeof CredentialsSchema> = existsSync(credentialsPath())
+      ? readCredentials()
+      : { schema: 1 };
+    writeJsonAtomic(credentialsPath(), { ...cur, schema: 1, [field]: key.trim() }, { mode: 0o600 });
+  });
 }
 
 /**

package/src/services/dispatch-service.ts

@@ -1,5 +1,6 @@
 import { assertNativeHost } from "./backends.ts";
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { CatherdError, errorMessage, isCatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
 import type { RunRecord } from "../domain/record.ts";
@@ -16,8 +17,9 @@ import {
 import { lockHeld, withFileLock } from "../infra/filelock.ts";
 import { log } from "../infra/log.ts";
 import { isAlive, isSurelyAlive, killGroup } from "../infra/proc.ts";
+import { groupAlive, stopGroup } from "../infra/supervisor.ts";
 import { writeJsonAtomic } from "../infra/store.ts";
-import { admit, KILL_GRACE_MS, laneFile, launch } from "./admission.ts";
+import { admit, KILL_GRACE_MS, laneFile, laneOwns, launch } from "./admission.ts";
 import { standInFor } from "./backends.ts";
 import {
   type Dispatch,
@@ -34,8 +36,11 @@ import {
 import { finalizeDispatch, finalizingElsewhere, waitForFinish } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
 import { route } from "./lane-service.ts";
-import { findRun, readRecords, readRoutes, type Run } from "./run-store.ts";
-import { claimRun, ownsRun, runOwner } from "./sessions.ts";
+import { currentRoute } from "../domain/route.ts";
+import { appendRoute, findRun, readRecords, readRoleRoutes, readRoutes, type Run } from "./run-store.ts";
+import { sessionKey } from "../domain/host.ts";
+import { claimRun, currentSession, ownsRun, runOwner, type SessionRef } from "./sessions.ts";
+import { pinChanges, runProfile } from "./run-pin.ts";
 import { type NotesPatch, refreshState } from "./state.ts";
 
 export interface DispatchInput {
@@ -43,7 +48,8 @@ export interface DispatchInput {
   role: Role;
   name: string;
   brief: string;
-  rung: string;
+  /** spec 1.5 plan 24: optional with `lane` (the lane's current rung); required without one */
+  rung?: string;
   thread?: string;
   lane?: string;
   next?: string;
@@ -174,9 +180,19 @@ export async function watchersSettled(): Promise<void> {
  */
 export function watch(deps: Deps, run: Run, d: Dispatch): void {
   watching.add(d.admit.dispatchId);
+  // the session this watcher started under, kept apart from its live identity: an MCP connection that closes
+  // invalidates the scoped host (no session), yet the watcher still came from that session (PR #47 P1)
+  const origin = currentSession(deps);
   const w = (async () => {
     await waitForFinish(d, { pollMs: deps.pollMs, now: deps.now, onPoll: stallPoll(run, d) });
-    const s = await settle(deps, run, d, await finalizeDispatch(run, d));
+    const record = await finalizeDispatch(run, d);
+    // a session that lost the run since it dispatched leaves a limit to the owner's claim (1.1 push minors):
+    // only the run's owner starts a stand-in. A process with no session (a terminal) settles as before.
+    if (record.status === "limit" && !limitIsMine(deps, run, origin)) {
+      log("info", "dispatch", { run: run.id, name: d.admit.name, limit: "left to the run's owner" });
+      return;
+    }
+    const s = await settle(deps, run, d, record);
     if (s.stateHints[0]) log("warn", "dispatch", { run: run.id, name: d.admit.name, hint: s.stateHints[0] });
   })()
     .catch((e: unknown) =>
@@ -189,6 +205,18 @@ export function watch(deps: Deps, run: Run, d: Dispatch): void {
   watchers.add(w);
 }
 
+/**
+ * Whether a watcher settles a limit (fails it over): a watcher with no session, then or now (a terminal, a
+ * test), always does; one that started under a session does only while that session, or its live one, owns
+ * the run.
+ */
+function limitIsMine(deps: Deps, run: Run, origin: SessionRef | null): boolean {
+  if (origin === null && currentSession(deps) === null) return true;
+  if (ownsRun(deps, run)) return true;
+  const owner = runOwner(run);
+  return origin !== null && owner !== null && sessionKey(owner) === sessionKey(origin);
+}
+
 /**
  * Spec §3.3: a run this session has just taken over may have roles another session's server launched. This
  * process watches each live one it is not already watching, so it settles them and its notifier announces them
@@ -214,6 +242,16 @@ export function adopt(deps: Deps, run: Run): void {
  */
 export async function claim(deps: Deps, run: Run, o: { background?: boolean } = {}): Promise<void> {
   if (!(await claimRun(deps, run)) && !ownsRun(deps, run)) return;
+  await recoverOwned(deps, run, o);
+}
+
+/**
+ * What `claim` does for a run this session already owns, without taking it: watch its live roles, record and
+ * settle what finished unrecorded, settle its unsettled limits and unannounced records. A server that does not
+ * lead the boot runs it for each run its session owns (PR #47 P1: a role that finished while that server was
+ * away has no live process to watch and no record to scan).
+ */
+export async function recoverOwned(deps: Deps, run: Run, o: { background?: boolean } = {}): Promise<void> {
   adopt(deps, run);
   let r = recovering.get(run.id);
   if (!r) {
@@ -281,24 +319,138 @@ function unannounced(run: Run): { d: Dispatch; record: RunRecord }[] {
   });
 }
 
+/** How long a dispatch waits for another dispatch's route of the same lane (Jev may take tens of seconds). */
+const ROUTE_LOCK_MS = 120_000;
+
+/**
+ * What admission would refuse anyway, refused before a lane is routed, so a refused dispatch asks Jev nothing
+ * and writes no route row: the role off, the lane file missing or with no Owns:, the name or the lane already
+ * running. Admission checks them again under its lock.
+ */
+function refuseBeforeRouting(deps: Deps, run: Run, i: DispatchInput & { lane: string }): void {
+  const profile = runProfile(deps, run);
+  if (!profile.roles[i.role]?.enabled)
+    throw new CatherdError("E_ADMIT_RUNG", `the ${i.role} role is off in profile ${profile.name}`, {
+      fix: "skip the role, or turn it on with profile_set",
+    });
+  laneOwns(run, i.lane);
+  // live only: a finished, unrecorded dispatch is recorded by admission (finalizeFinished), not refused here
+  const pending = liveDispatches(run, deps.now());
+  const same = pending.find((d) => d.admit.name === i.name);
+  if (same)
+    throw new CatherdError("E_ADMIT_DUPLICATE", `${i.name} is already running on ${same.admit.rung}`, {
+      fix: `its record is announced when it finishes; or cancel(run, "${i.name}")`,
+    });
+  const lane = pending.find((d) => d.admit.lane === i.lane);
+  if (lane)
+    throw new CatherdError("E_ADMIT_OVERLAP", `lane ${i.lane} is already running as ${lane.admit.name}`, {
+      fix: `dispatch it after ${lane.admit.name} finishes`,
+    });
+}
+
+/**
+ * Plan 22: the thread a dispatch resumes. `"latest"` is the name's last recorded thread; any other id must be one
+ * the name's records in this run hold (`runs.jsonl`), in any case, so a wrong id is refused before a CLI starts
+ * and fails on it. Null for a fresh thread.
+ */
+function threadFor(run: Run, name: string, thread: string | undefined): string | null {
+  if (thread === undefined) return null;
+  assertId("role name", name);
+  const mine = readRecords(run)
+    .records.filter((r) => r.name === name && r.thread !== null)
+    .map((r) => r.thread as string);
+  const last = mine.at(-1);
+  if (thread === "latest") {
+    if (last) return last;
+    throw new CatherdError("E_ADMIT_THREAD", `${name} has no earlier thread in this run`, {
+      fix: "omit thread for a fresh thread",
+    });
+  }
+  const known = mine.findLast((t) => t.toLowerCase() === thread.toLowerCase());
+  if (known) return known;
+  throw new CatherdError("E_ADMIT_THREAD", `${thread} is not a thread of ${name} in this run`, {
+    fix: last
+      ? `pass thread: "latest" for ${name}'s last thread (${last}), or omit thread for a fresh one`
+      : "omit thread for a fresh thread",
+  });
+}
+
+/**
+ * Plan 22, resume hygiene: what an earlier turn on `thread` left running in its process group (a server, a
+ * watcher, a background command) is stopped before the thread is resumed, so it never ends the resumed CLI
+ * (exit 143). Only a dispatch whose supervisor and group leader are both gone is touched (with or without
+ * exit.json: a supervisor killed before it stopped the group writes none): a live group with no process of the
+ * leader's pid can only be that dispatch's leftovers (a pid is never reused while its group lives), and a pid
+ * that answers belongs to someone else by now. Returns a hint per group stopped.
+ */
+async function stopLeftovers(deps: Deps, run: Run, thread: string): Promise<string[]> {
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const hints: string[] = [];
+  for (const d of listDispatches(run)) {
+    const on = d.admit.thread ?? records.get(d.admit.dispatchId)?.thread ?? null;
+    if (on?.toLowerCase() !== thread.toLowerCase()) continue;
+    const proc = readProc(d.dir);
+    const pgid = proc?.pgid ?? proc?.pid;
+    if (!proc || pgid === undefined || pgid !== proc.pid) continue;
+    // a live supervisor stops its own group when its worker ends; exit.json is not the test, since a supervisor
+    // killed (SIGKILL, OOM) before it stopped the group never writes one
+    if (isAlive(proc.supervisorPid, proc.supervisorStartTime)) continue;
+    if (isAlive(proc.pid, null) || !groupAlive(pgid)) continue;
+    await stopGroup(pgid, orphanLimits.killGraceMs, deps.pollMs);
+    log("info", "dispatch", { run: run.id, name: d.admit.name, thread, stoppedGroup: pgid });
+    hints.push(`resume: stopped what ${d.admit.name}'s earlier turn left running on thread ${thread}`);
+  }
+  return hints;
+}
+
 /**
  * Spec §4.4, plan 9 ruling 1: admit and launch one role, start its watcher, then refresh state.md with
  * `next` (after the launch, so nothing delays it). Returns at once; catherd announces the record (spec §3).
  */
 export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchStarted> {
   const run = findRun(i.run);
+  // refused before the claim, so a wrong thread changes nothing
+  const thread = threadFor(run, i.name, i.thread);
   await claim(deps, run);
   const hints: string[] = [];
-  let rung = i.rung;
-  // spec 1.1 §6: a lane is routed before its first dispatch; a rung off the routed ladder starts at the routed one
-  if (i.lane !== undefined && !readRoutes(run).some((r) => r.lane === i.lane)) {
-    assertId("lane", i.lane);
-    const routed = await route(deps, { run: i.run, laneFile: `lanes/${i.lane}.md`, role: i.role });
-    if (!routed.ladder.includes(i.rung)) {
+  if (thread !== null) hints.push(...(await stopLeftovers(deps, run, thread)));
+  let rung: string;
+  if (i.lane !== undefined) {
+    const lane = i.lane;
+    assertId("lane", lane);
+    // spec 1.1 §6: a lane is routed before its first dispatch; a rung off the routed ladder starts at the routed one
+    let current = currentRoute(readRoutes(run), lane);
+    let routed: Awaited<ReturnType<typeof route>> | null = null;
+    if (!current) {
+      refuseBeforeRouting(deps, run, { ...i, lane });
+      // one route per lane: a second dispatch of the lane waits for the first's route and takes it
+      const got = await withFileLock(
+        join(run.dir, `route-${lane}`),
+        async () => {
+          const now = currentRoute(readRoutes(run), lane);
+          return now
+            ? { current: now, routed: null }
+            : {
+                current: null,
+                routed: await route(deps, { run: i.run, laneFile: `lanes/${lane}.md`, role: i.role }),
+              };
+        },
+        { timeoutMs: ROUTE_LOCK_MS },
+      );
+      current = got.current;
+      routed = got.routed;
+    }
+    // spec 1.5 plan 24: without a rung, a lane runs at its current rung (its route, after any climb)
+    rung = i.rung ?? routed?.rung ?? (current?.rung as string);
+    if (routed && i.rung !== undefined && !routed.ladder.includes(i.rung)) {
       rung = routed.rung;
-      hints.push(`${i.rung} is not on ${i.lane}'s routed ladder: dispatched at ${routed.rung}`);
+      hints.push(`${i.rung} is not on ${lane}'s routed ladder: dispatched at ${routed.rung}`);
     }
-  }
+  } else if (i.rung === undefined)
+    throw new CatherdError("E_INPUT_INVALID", `dispatch ${i.name}: a role outside a lane needs a rung`, {
+      fix: `route(run, role: "${i.role}") gives the role's rung; pass it as rung`,
+    });
+  else rung = i.rung;
   // the rung that runs, after routing: an off-ladder native rung routing replaced is never launched
   assertNativeHost(rung, deps.host.host);
   const { d, specPath } = await admit(
@@ -309,7 +461,7 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
       name: i.name,
       brief: i.brief,
       rung,
-      thread: i.thread ?? null,
+      thread,
       lane: i.lane ?? null,
       failoverFrom: null,
     },
@@ -324,10 +476,46 @@ export async function dispatch(deps: Deps, i: DispatchInput): Promise<DispatchSt
     // a launch that failed is still watched: its record (lost, after the start grace) is announced
     watch(deps, run, d);
   }
-  await refresh(run, i.next ? { next: i.next } : {}, hints);
+  if (i.lane === undefined) recordRoleDispatch(deps, run, i.role, i.name, rung);
+  // spec 1.5: a change since the run's pin is logged in state.md each time a role starts
+  const changes = pinChanges(deps, run);
+  if (changes.length)
+    hints.push(
+      `dispatched on the run's pinned values: ${changes.join("; ")}; run_pin(run) re-pins to the repo's now`,
+    );
+  await refresh(run, { ...(i.next ? { next: i.next } : {}), pinChanges: changes }, hints);
   return { dispatched: dispatchedOf(d), hints };
 }
 
+/**
+ * Spec 1.5 plan 24: a lane-less dispatch's rung in routes.jsonl, so every role's decision can be audited:
+ * `route` when it is the rung the role's last `route` gave (with that ladder), else the coordinator's own pick.
+ * A failed write is logged, never a failed dispatch: the role is already running.
+ */
+function recordRoleDispatch(deps: Deps, run: Run, role: Role, name: string, rung: string): void {
+  try {
+    const last = readRoleRoutes(run).findLast((r) => r.role === role && r.source === "route");
+    const routed = last?.rung === rung;
+    appendRoute(run, {
+      at: new Date(deps.now()).toISOString(),
+      lane: null,
+      role,
+      name,
+      rung,
+      ladder: last?.ladder ?? [rung],
+      source: "dispatch",
+      decidedBy: routed ? last.decidedBy : "orchestrator",
+      why: routed
+        ? `the rung route gave the ${role}`
+        : last
+          ? `the coordinator's rung; route gave the ${role} ${last.rung}`
+          : `the coordinator's rung; the ${role} was never routed`,
+    });
+  } catch (e) {
+    log("warn", "dispatch", { run: run.id, name, routes: errorMessage(e) });
+  }
+}
+
 /** How long a settle waits for another process's failover of the same dispatch (a test seam). */
 export const failoverLock = { timeoutMs: 120_000 };
 
@@ -498,7 +686,7 @@ async function failover(deps: Deps, run: Run, d: Dispatch, limited: RunRecord):
     return failedOver(already.admit.rung, already);
   }
   // else that stand-in never ran and is over (recorded as lost, or past its start grace): admit a new one
-  const standIn = standInFor(deps.profiles.forRepo(run.meta.repo).failover, limited.rung, run.meta.repo);
+  const standIn = standInFor(runProfile(deps, run).failover, limited.rung, run.meta.repo);
   if (!standIn) return { hints, started: null, pause: paused };
   // the stand-in answers to whoever owns the run now, which a claim from another host may have changed
   assertNativeHost(standIn, runOwner(run)?.host ?? deps.host.host);

package/src/services/dispatches.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
 import { dispatchHints } from "../domain/hints.ts";
 import { ACCESS, type RunRecord } from "../domain/record.ts";
 import { ROLES } from "../domain/roles.ts";
@@ -18,6 +19,11 @@ const AdmitSchema = z.looseObject({
   role: z.enum(ROLES),
   lane: z.string().nullable(),
   owns: z.array(z.string()),
+  /**
+   * spec 1.5 plan 21: a laneless writer's implicit Owns (its brief's Owns: line, else docs/** and *.md), so its
+   * edits are its own and never a concurrent lane's violation; admission never refuses an overlap with it
+   */
+  ownsImplicit: z.array(z.string()).optional(),
   rung: z.string(),
   backend: z.string(),
   thread: z.string().nullable(),
@@ -54,9 +60,11 @@ export const startLimits = { graceMs: STARTING_GRACE_MS };
 export const admitPath = (dir: string): string => join(dir, "admit.json");
 export const launchPath = (dir: string): string => join(dir, "launch.json");
 export const roleDir = (run: Run, name: string): string => join(runPaths(run.dir).roles, name);
+/** Spec 1.5 plan 21: the role's TMPDIR, `<run>/scratch/<name>/`, removed with the run's scratch. */
+export const scratchDir = (run: Run, name: string): string => join(runPaths(run.dir).scratch, name);
 
 /** Every admitted dispatch of the run, oldest first; a folder whose admit.json cannot be read is skipped. */
-export function listDispatches(run: Run): Dispatch[] {
+export function listDispatches(run: Run, strict = false): Dispatch[] {
   const roles = runPaths(run.dir).roles;
   const out: Dispatch[] = [];
   if (!existsSync(roles)) return out;
@@ -68,6 +76,8 @@ export function listDispatches(run: Run): Dispatch[] {
       try {
         out.push({ dir, admit: decodeAdmit(readVersioned(admitPath(dir), AdmitSchema, 1)) });
       } catch {
+        if (strict && existsSync(admitPath(dir)))
+          throw new CatherdError("E_RUN_CORRUPT", `run ${run.id} has unreadable admission evidence: ${dir}`);
         // admission never finished writing this folder
       }
     }
@@ -124,9 +134,10 @@ export function pendingDispatches(
   run: Run,
   now = Date.now(),
   records: RunRecord[] = readRecords(run).records,
+  strict = false,
 ): LiveDispatch[] {
   const recorded = new Set(records.map((r) => r.dispatchId));
-  return listDispatches(run)
+  return listDispatches(run, strict)
     .filter((d) => !recorded.has(d.admit.dispatchId))
     .map((d) => ({ ...d, state: dispatchState(d, now) }));
 }
@@ -134,6 +145,23 @@ export function pendingDispatches(
 export const liveDispatches = (run: Run, now = Date.now()): LiveDispatch[] =>
   pendingDispatches(run, now).filter((d) => d.state !== "finished");
 
+/** The thread the supervisor saw the role's CLI name (thread.json), else null. */
+export function readThread(dir: string): string | null {
+  const t = readJson<{ thread?: unknown }>(dispatchPaths(dir).thread)?.thread;
+  return typeof t === "string" && t ? t : null;
+}
+
+/**
+ * Spec 1.5 plan 21: the role whose thread `thread` is, in this run: a recorded thread, a resumed one, or the one
+ * a live role's supervisor wrote down. Null for any other thread, the orchestrator's among them.
+ */
+export function roleThreadOf(run: Run, thread: string): string | null {
+  const recorded = readRecords(run).records.find((r) => r.thread === thread);
+  if (recorded) return recorded.name;
+  const d = listDispatches(run).find((x) => x.admit.thread === thread || readThread(x.dir) === thread);
+  return d ? d.admit.name : null;
+}
+
 /** Spec §4.1: `roles/<name>/latest` names the newest dispatch of a role. */
 export function setLatest(run: Run, name: string, dispatchId: string): void {
   writeTextAtomic(join(roleDir(run, name), "latest"), dispatchId);

package/src/services/doctor-access.ts

@@ -172,9 +172,14 @@ export function workspaceWriteNetwork(profiles: Profile[]): Map<string, boolean>
 
 /**
  * The `sandbox:codex` row (which `codex sandbox` form runs) and one `access:<backend>` row per backend; a
- * backend not in `installed` (its CLI is not on PATH) is skipped without running a probe.
+ * backend not in `installed` (its CLI is not on PATH) is skipped without running a probe. `repos`: where
+ * workers run (doctor's repo and every bound one), for a sandbox set per repo.
  */
-export async function accessChecks(profiles: Profile[], installed: ReadonlySet<string>): Promise<Check[]> {
+export async function accessChecks(
+  profiles: Profile[],
+  installed: ReadonlySet<string>,
+  repos: string[] = [],
+): Promise<Check[]> {
   const checks: Check[] = [];
   for (const [id, network] of workspaceWriteNetwork(profiles)) {
     const a = adapterFor(id);
@@ -190,7 +195,7 @@ export async function accessChecks(profiles: Profile[], installed: ReadonlySet<s
       continue;
     }
     const shell = a.accessShell
-      ? await a.accessShell({ network }).catch((e: unknown) => String(e))
+      ? await a.accessShell({ network, repos }).catch((e: unknown) => String(e))
       : `no way to run a shell in ${id}'s sandbox without a model turn; the live kit (docs/dev/live-verification.md) runs the five probes as one worker turn`;
     if (id === "codex")
       checks.push(