catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/daemon.ts

@@ -0,0 +1,181 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { errorMessage } from "../domain/errors.ts";
+import { launchDaemon } from "../infra/launch.ts";
+import type { SuperviseClock } from "../infra/supervisor.ts";
+import { lockHeld, tryLock } from "../infra/filelock.ts";
+import { log } from "../infra/log.ts";
+import { processStartTime } from "../infra/proc.ts";
+import { readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import type { Deps } from "./ports.ts";
+import type { RunEvent } from "../domain/run-events.ts";
+import { type Action, actionKey, confirms, failKey, next } from "../domain/run-machine.ts";
+import { reduce, replay, type RunState } from "../domain/run-state.ts";
+import { type Effects, realEffects } from "./run-effects.ts";
+import { appendEvent, eventsFile, isDaemonRun, readEvents } from "./run-events-store.ts";
+import { findRun, type Run } from "./run-store.ts";
+
+/** The daemon holds this lock for its whole life: a second holder gets none, a dead one's is reclaimed. */
+export const daemonLockTarget = (run: Run): string => join(run.dir, "daemon");
+export const heartbeatFile = (run: Run): string => join(run.dir, "daemon.json");
+
+/** `beatMs`: how often the heartbeat is written; `pollMs`: how often the loop reads the events. Tests shorten them. */
+export const daemonLimits = { beatMs: 5_000, pollMs: 500 };
+
+export interface Heartbeat {
+  schema: 1;
+  pid: number;
+  startTime: string | null;
+  beatAt: string;
+  seq: number;
+  version: string;
+}
+
+const HeartbeatSchema = z.looseObject({
+  schema: z.literal(1),
+  pid: z.number().int(),
+  startTime: z.string().nullable(),
+  beatAt: z.string(),
+  seq: z.number().int(),
+  version: z.string(),
+});
+
+/** The daemon's last beat, or null when it never wrote one or the file cannot be read. */
+export function readHeartbeat(run: Run): Heartbeat | null {
+  try {
+    return readVersioned(heartbeatFile(run), HeartbeatSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a live process holds the run's daemon lock: its pid and start time, never the heartbeat. */
+export const daemonAlive = (run: Run): boolean => lockHeld(daemonLockTarget(run));
+
+/** How the daemon is started; tests replace it so no process is spawned. */
+export const daemonLauncher = { launch: launchDaemon };
+
+/** Whether the run's events say it ended (`run.ended`). A `"type":"run.ended"` never occurs inside a JSON string. */
+function hasEnded(run: Run): boolean {
+  try {
+    return readFileSync(eventsFile(run), "utf8").includes('"type":"run.ended"');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Makes sure a 2.0 run that has not ended has a daemon: one that is alive is left alone, a dead one is
+ * started again (two callers at once start two processes, and the lock lets one run). A 1.5 run has none.
+ */
+export function ensureDaemon(run: Run): "alive" | "revived" | "ended" | "1.5" {
+  if (!isDaemonRun(run)) return "1.5";
+  if (hasEnded(run)) return "ended";
+  if (daemonAlive(run)) return "alive";
+  daemonLauncher.launch(run.id, run.dir);
+  return "revived";
+}
+
+/** Writes the heartbeat: who holds the lock, since when, and how far it has read. */
+export function beat(run: Run, deps: Deps, seq: number): void {
+  const pid = process.pid;
+  writeJsonAtomic(heartbeatFile(run), {
+    schema: 1,
+    pid,
+    startTime: processStartTime(pid),
+    beatAt: new Date(deps.now()).toISOString(),
+    seq,
+    version: deps.version,
+  } satisfies Heartbeat);
+}
+
+export interface DaemonOptions {
+  /** what carries the machine's actions out; the real services when absent */
+  effects?: Effects;
+  /** the loop's time; the real clock when absent */
+  clock?: SuperviseClock;
+  /** ends the loop early (tests) */
+  until?: () => boolean;
+}
+
+const REAL_CLOCK: SuperviseClock = { now: () => Date.now(), sleep: (ms) => Bun.sleep(ms) };
+
+/**
+ * Drives one run: takes its lock (`"lost-lock"` without it), returns `"ended"` at once for a run that ended,
+ * else replays the events, announces itself, and then feeds each new event to the machine: it clears the keys
+ * the event confirms, runs each action of `next` it has not issued (not awaited), appends one `tick` when a
+ * hold or wait has passed and beats. It leaves, releasing the lock, once the run has ended and every effect
+ * is done. The effects append the events, so a crash loses nothing: a new daemon replays and issues again
+ * what never got its event.
+ */
+export async function runDaemon(
+  deps: Deps,
+  runId: string,
+  o: DaemonOptions = {},
+): Promise<"ended" | "lost-lock"> {
+  const run = findRun(runId);
+  const release = tryLock(daemonLockTarget(run));
+  if (!release) return "lost-lock";
+  try {
+    if (!isDaemonRun(run) || hasEnded(run)) return "ended";
+    const clock = o.clock ?? REAL_CLOCK;
+    const effects = o.effects ?? realEffects(deps, run);
+    let state: RunState = replay(readEvents(run), run.id);
+    const hello = await appendEvent(
+      run,
+      { type: "daemon.started", pid: process.pid, version: deps.version },
+      new Date(clock.now()),
+    );
+    log("info", "daemon", { run: run.id, pid: process.pid, seq: hello.seq });
+    beat(run, deps, hello.seq);
+    /** action key → the key `effect.failed` frees it by */
+    const issued = new Map<string, string>();
+    const inFlight = new Set<Promise<void>>();
+    const issue = (a: Action): void => {
+      const key = actionKey(a);
+      if (issued.has(key)) return;
+      issued.set(key, failKey(a, state));
+      const p: Promise<void> = effects
+        .run(a, state)
+        .catch((e: unknown) =>
+          log("error", "daemon", { run: run.id, action: a.type, error: errorMessage(e) }),
+        )
+        .finally(() => {
+          inFlight.delete(p);
+          // a notice, and a merge check that found nothing, leave no event behind: nothing else would free their key
+          if (a.type === "notify" || a.type === "checkMerged") issued.delete(key);
+        });
+      inFlight.add(p);
+    };
+    const take = (e: RunEvent): void => {
+      state = reduce(state, e);
+      for (const k of confirms(e))
+        for (const [key, fk] of issued) if (key === k || fk === k) issued.delete(key);
+      for (const a of next(state, e)) issue(a);
+    };
+    let beatAt = clock.now();
+    while (!o.until?.()) {
+      const fresh = readEvents(run, state.seq + 1);
+      for (const e of fresh) take(e);
+      if (fresh.length > 0) continue;
+      if (state.wakeAt !== null && Date.parse(state.wakeAt) <= clock.now()) {
+        await appendEvent(run, { type: "tick" }, new Date(clock.now()));
+        continue;
+      }
+      if (clock.now() - beatAt >= daemonLimits.beatMs) {
+        beat(run, deps, state.seq);
+        beatAt = clock.now();
+      }
+      if (state.phase === "ended" && inFlight.size === 0) break;
+      await clock.sleep(daemonLimits.pollMs);
+    }
+    beat(run, deps, Math.max(state.seq, hello.seq));
+    return "ended";
+  } catch (e) {
+    log("error", "daemon", { run: runId, error: errorMessage(e) });
+    throw e;
+  } finally {
+    release();
+  }
+}

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,
@@ -33,9 +35,13 @@ import {
 } from "./dispatches.ts";
 import { finalizeDispatch, finalizingElsewhere, waitForFinish } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
+import { isDaemonRun } from "./run-events-store.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 +49,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 +181,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,12 +206,26 @@ 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
  * to their new owner (a second settle of a dispatch is harmless: finalize and failover run once).
  */
 export function adopt(deps: Deps, run: Run): void {
+  // a 2.0 run's daemon watches its roles and fails them over itself
+  if (isDaemonRun(run)) return;
   for (const d of liveDispatches(run, deps.now())) if (!watching.has(d.admit.dispatchId)) watch(deps, run, d);
 }
 
@@ -214,6 +245,17 @@ 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> {
+  if (isDaemonRun(run)) return;
   adopt(deps, run);
   let r = recovering.get(run.id);
   if (!r) {
@@ -281,24 +323,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 +465,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 +480,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 +690,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);
@@ -598,7 +790,7 @@ async function stopOrphan(deps: Deps, d: Dispatch): Promise<void> {
 /**
  * Spec §4.7: stop a live dispatch (interrupt, SIGTERM, SIGKILL) and record it as cancelled. With `read` (the MCP
  * `cancel` tool, whose caller holds the record it returns) the record is marked read, so `peek` no longer lists
- * it. Without it (the dashboard, `catherd runs cancel`) the record stays unread and catherd announces it to the
+ * it. Without it (the panel, `catherd runs cancel`) the record stays unread and catherd announces it to the
  * run's owner at `later` (spec §3.6).
  */
 export async function cancel(

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(

package/src/services/doctor-backends.ts

@@ -151,7 +151,7 @@ export async function backendChecks(
             }
           : { id: `backend:${id}`, label: id, state: "ok", word: "ready", detail },
       );
-      // spec 1.3 §6.6: asked only of a logged-in CLI (a logged-out agy -p would open a browser)
+      // spec 1.3 §6.6: asked only of a logged-in CLI (a logged-out CLI may open a browser)
       const quota = probe.loggedIn && a.quota ? await a.quota().catch(() => null) : null;
       if (quota)
         checks.push({ id: `quota:${id}`, label: `${id} quota`, state: "info", word: "quota", detail: quota });