catherd-cli 0.2.1 → 1.1.0

package/src/services/profile-store.ts

@@ -0,0 +1,141 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { CatherdError, UPGRADE } from "../domain/errors.ts";
+import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
+import {
+  assertProfileName,
+  defaultProfileDoc,
+  PROFILE_NAME,
+  type Profile,
+  type ProfileDoc,
+  ProfileDocSchema,
+  resolveProfile,
+} from "../domain/profile.ts";
+import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import type { Access } from "../domain/record.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { configDir } from "../infra/paths.ts";
+import { readJsonFile } from "../infra/store.ts";
+import { backendOfKey, loadCatalog } from "./catalog-service.ts";
+
+// Spec §7.3, the read side of the profile service: where profiles, config.json and projects.json live,
+// and reading them. Every write goes through profile-service.ts.
+
+export const profilesDir = (): string => join(configDir(), "profiles");
+export const configFile = (): string => join(configDir(), "config.json");
+export const projectsFile = (): string => join(configDir(), "projects.json");
+/** `<config>/agents/<profile>/<agent>.md`: catherd's own agent files, which the links point at. */
+export const agentsRoot = (): string => join(configDir(), "agents");
+export const profileFile = (name: string): string => join(profilesDir(), `${name}.json`);
+
+const ConfigSchema = z.looseObject({ schema: z.literal(1), activeProfile: z.string().optional() });
+const ProjectsSchema = z.looseObject({
+  schema: z.literal(1),
+  bindings: z.record(z.string(), z.string()).default({}),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+export type Projects = z.infer<typeof ProjectsSchema>;
+
+/**
+ * Reads a schema-1 file. A file without `schema` was written by catherd 0.x, which 1.0 does not read
+ * (spec D2): `catherd init` moves those aside.
+ */
+function readV1<T>(file: string, schema: z.ZodType<T>): T {
+  const raw = readJsonFile(file);
+  const found = (raw as { schema?: unknown } | null)?.schema;
+  if (found === undefined)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is from catherd 0.x`, {
+      fix: "run catherd init, which moves 0.x files aside and writes 1.0 ones",
+    });
+  if (typeof found === "number" && found > 1)
+    throw new CatherdError(
+      "E_CONFIG_NEWER_SCHEMA",
+      `${file} has schema ${found}, newer than this catherd (1)`,
+      {
+        fix: `upgrade catherd: ${UPGRADE}`,
+      },
+    );
+  const r = schema.safeParse(raw);
+  if (!r.success)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is invalid:\n${z.prettifyError(r.error)}`, {
+      fix: `fix it with catherd profile set, or delete ${file}`,
+    });
+  return r.data;
+}
+
+export const readConfig = (): Config =>
+  existsSync(configFile()) ? readV1(configFile(), ConfigSchema) : { schema: 1 };
+export const readProjects = (): Projects =>
+  existsSync(projectsFile()) ? readV1(projectsFile(), ProjectsSchema) : { schema: 1, bindings: {} };
+
+/** Every profile name: the files in `profiles/`, and `default`, which exists even before its file does. */
+export function listProfiles(): string[] {
+  const onDisk = existsSync(profilesDir())
+    ? readdirSync(profilesDir())
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => f.slice(0, -".json".length))
+        .filter((n) => PROFILE_NAME.test(n))
+    : [];
+  return [...new Set(["default", ...onDisk])].sort();
+}
+
+export const profileExists = (name: string): boolean => listProfiles().includes(name);
+
+/** The stored document; `default` without a file is the built-in default profile. */
+export function readProfileDoc(name: string): ProfileDoc {
+  assertProfileName(name);
+  if (existsSync(profileFile(name))) return readV1(profileFile(name), ProfileDocSchema);
+  if (name === "default") return defaultProfileDoc();
+  throw new CatherdError("E_CONFIG_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
+}
+
+export const getProfile = (name: string): Profile => resolveProfile(readProfileDoc(name), name);
+
+/** A profile name the user typed: refused as bad input (exit 2) when no such profile exists. */
+export function requireProfile(name: string): string {
+  if (!profileExists(assertProfileName(name)))
+    throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
+  return name;
+}
+
+/** The profile bound to `repo` (a git toplevel), else the active one, else `default`. */
+export function activeName(repo: string | null = null): string {
+  const bound = repo === null ? undefined : readProjects().bindings[repo];
+  return bound ?? readConfig().activeProfile ?? "default";
+}
+
+export const profileFor = (repo: string | null): Profile => getProfile(activeName(repo));
+
+/** The backends catherd can run: every registered adapter, and the native `claude` path. */
+export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter((id) => adapterFor(id))];
+
+/** Whether a profile's billing or harness key belongs to one of `backends` (default: runnableBackends()). */
+export const keyRunnable = (key: string, backends: string[] = runnableBackends()): boolean =>
+  backends.includes(backendOfKey(key));
+
+/** `repo`: the git toplevel whose listing route reads (opencode lists its models per repository). */
+export function validateNamed(name?: string, repo: string | null = null): Validation {
+  const n = name ?? activeName(repo);
+  const doc = readProfileDoc(n);
+  const catalog = loadCatalog({ timings: false, ...(repo === null ? {} : { repo }) });
+  return validateProfile(resolveProfile(doc, n), catalog, runnableBackends(), doc);
+}
+
+/** Spec D10: how strongly the backend holds a role to its access mode. */
+export function enforcementOf(rung: string, access: Access): "enforced" | "advisory" {
+  const r = tryParseRung(rung);
+  return (r && adapterFor(r.backend)?.enforcement[access]) ?? "advisory";
+}
+
+/** Each role's weakest enforcement over its rungs, for `profile show` and profile_get. */
+export function roleEnforcement(p: Profile): Record<Role, "enforced" | "advisory"> {
+  const out = {} as Record<Role, "enforced" | "advisory">;
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    out[role] = rc.rungs.every((r) => enforcementOf(r, rc.access) === "enforced") ? "enforced" : "advisory";
+  }
+  return out;
+}

package/src/services/protocol.ts

@@ -0,0 +1,212 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { RunRecord } from "../domain/record.ts";
+import type { RouteRow } from "../domain/route.ts";
+import { ensurePrivateDir, readJsonl, writeTextAtomic } from "../infra/store.ts";
+import { type Dispatch, listDispatches, liveDispatches } from "./dispatches.ts";
+import type { VerifierStep } from "./gate-service.ts";
+import {
+  landedMilestones,
+  milestoneReviewer,
+  milestoneVerifier,
+  milestoneStart,
+  namesMilestone,
+  reviewerPassed,
+  verifierPassed,
+} from "./milestones.ts";
+import { readAgentRuns, readRecords, readRoutes, type Run, runPaths } from "./run-store.ts";
+
+// Spec 1.1 §10: the protocol's next step, derived from the run's own files so a session that lost its
+// context (a compaction, a restart) re-enters the milestone loop where it stands; and each landed
+// milestone's digest.
+
+/** The milestone loop, six lines, as run_start and peek return it. */
+export const PROTOCOL_CHECKLIST = [
+  "1. route and preflight the milestone's lanes (dispatch routes a lane not routed yet)",
+  "2. dispatch every independent lane one after another, then end your turn: results arrive as catherd messages",
+  "3. per result: result(run, name), its STATUS and changedOwned, then its fast check once",
+  "4. reviewer-<M> once over the milestone diff, then one fix round",
+  "5. the verifier in the foreground, with gate_check and gate_pass, recorded as record_agent_run(name: verifier-<M>)",
+  "6. commit, then land(run, <M>, …); an owner question parks the milestone (park) and the run goes on",
+];
+
+const milestoneOf = (lane: string): string => lane.split(".")[0] as string;
+const byNumber = (a: string, b: string) => a.localeCompare(b, "en", { numeric: true });
+
+/** The run's lanes, from lanes/*.md, in milestone and lane order. */
+function laneIds(run: Run): string[] {
+  const dir = runPaths(run.dir).lanes;
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.slice(0, -".md".length))
+    .filter((l) => l.includes("."))
+    .sort(byNumber);
+}
+
+/**
+ * Whether `lane` needs no dispatch now: its latest dispatch or native agent run since its latest climb is
+ * still running, or ended ok with no blocked or refused reply. A lane whose last try failed, hit a limit,
+ * was blocked, or was climbed since goes back to dispatch; a plain re-route leaves an ok try standing.
+ */
+function laneDone(run: Run, lane: string, routes: RouteRow[], live: Dispatch[]): boolean {
+  const from = Math.max(
+    ...routes.filter((r) => r.lane === lane && r.source === "climb").map((r) => Date.parse(r.at)),
+  );
+  // a dispatch routes its lane first, so a try at the route's own time counts as after it
+  const after = (t: string) => !(Date.parse(t) < from);
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const running = new Set(live.map((d) => d.admit.dispatchId));
+  const tries = [
+    ...listDispatches(run)
+      .filter((d) => d.admit.lane === lane && after(d.admit.admittedAt))
+      .map((d) => {
+        const r = records.get(d.admit.dispatchId);
+        const ok = r
+          ? r.status === "ok" && r.replyStatus !== "blocked" && r.replyStatus !== "refused"
+          : running.has(d.admit.dispatchId);
+        return { at: Date.parse(d.admit.admittedAt), ok };
+      }),
+    ...readAgentRuns(run)
+      .filter((a) => a.lane === lane && after(a.at))
+      .map((a) => ({ at: Date.parse(a.at), ok: a.status === "ok" })),
+  ];
+  const latest = tries.reduce<(typeof tries)[number] | null>(
+    (best, t) => (best === null || t.at >= best.at ? t : best),
+    null,
+  );
+  return latest?.ok ?? false;
+}
+
+/**
+ * The step the milestone loop is at: the first milestone neither landed nor parked, and within it the
+ * first of route, dispatch, collect, reviewer, verifier and land that is still to do.
+ */
+export function protocolNext(run: Run, parked: string[], now = Date.now()): string {
+  const lanes = laneIds(run);
+  if (lanes.length === 0)
+    return "plan: the architect writes plan.md and lanes/Mx.Ly.md (or you, for a fix run)";
+  const landed = new Set(landedMilestones(run));
+  const milestones = [...new Set(lanes.map(milestoneOf))].sort(byNumber);
+  const m = milestones.find((x) => !landed.has(x) && !parked.includes(x));
+  if (!m)
+    return parked.length
+      ? `${parked.join(", ")} parked: wait for the owner`
+      : "finish: the final gate, then the report";
+  const mine = lanes.filter((l) => milestoneOf(l) === m);
+  const routes = readRoutes(run);
+  const routed = new Set(routes.map((r) => r.lane));
+  if (mine.some((l) => !routed.has(l))) return `route and preflight ${m}'s lanes`;
+  const live = liveDispatches(run, now);
+  const notDone = mine.filter((l) => !laneDone(run, l, routes, live));
+  // spec 1.1 §9: a climb past the top rung (from === rung) leaves nothing to climb to; that is a decision
+  const spent = notDone.filter((l) => {
+    const last = routes.findLast((r) => r.lane === l);
+    return last?.source === "climb" && last.from === last.rung;
+  });
+  const waiting = notDone.filter((l) => !spent.includes(l));
+  if (waiting.length) return `dispatch ${waiting.join(", ")}`;
+  if (spent.length) return `${spent.join(", ")}: out of rungs — ask finding, then the architect or park ${m}`;
+  const running = live.filter((d) => d.admit.lane !== null && mine.includes(d.admit.lane));
+  if (running.length) return `${m}: lanes running (${running.map((d) => d.admit.name).join(", ")})`;
+  const start = milestoneStart(run, m);
+  if (!reviewerPassed(run, m, start)) return `${m}: reviewer`;
+  if (!verifierPassed(run, m, start)) return `${m}: verifier`;
+  return `land ${m}`;
+}
+
+/** What run_start and peek return beside the step: the six-line loop. */
+export const protocolView = (run: Run, parked: string[], now?: number) => ({
+  next: protocolNext(run, parked, now),
+  checklist: PROTOCOL_CHECKLIST,
+});
+
+const FINDING = /^\s*(?:[-*]\s*)?(BLOCKER|BUG|NIT)\b/;
+
+function findingCounts(run: Run, r: RunRecord | undefined): string {
+  if (!r?.replyPath) return "no reply";
+  const file = join(run.dir, r.replyPath);
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const n = { BLOCKER: 0, BUG: 0, NIT: 0 };
+  for (const line of text.split("\n")) {
+    const k = FINDING.exec(line)?.[1] as keyof typeof n | undefined;
+    if (k) n[k]++;
+  }
+  const total = n.BLOCKER + n.BUG + n.NIT;
+  return `${total} finding(s): ${n.BLOCKER} BLOCKER, ${n.BUG} BUG, ${n.NIT} NIT`;
+}
+
+const k = (x: number) => (x >= 1000 ? `${Math.round(x / 1000)}k` : String(x));
+
+/**
+ * Spec 1.1 §10: `R/digests/<m>.md`, written by `land`: the A-lines it names, the commit, the lanes with
+ * their rungs and climbs, the reviewer's findings, the verifier's verdict with its carried items, minutes
+ * and tokens. Returns its path relative to the run folder.
+ */
+export function writeDigest(
+  run: Run,
+  i: { milestone: string; what: string; commit: string; evidence: string; minutes: number; at: string },
+): string {
+  const m = i.milestone;
+  const start = milestoneStart(run, m);
+  const inM = (lane: string | null | undefined) => typeof lane === "string" && lane.startsWith(`${m}.`);
+  const named = new Set([...`${i.what} ${i.evidence}`.matchAll(/\bA(\d+)\b/g)].map((x) => `A${x[1]}`));
+  const aLines = run.meta.aLines.filter((a) => named.has(/^\s*(A\d+)/.exec(a)?.[1] ?? ""));
+  const routes = readRoutes(run).filter((r) => inM(r.lane));
+  const lanes = [...new Set(routes.map((r) => r.lane))].sort(byNumber).map((lane) => {
+    const rows = routes.filter((r) => r.lane === lane);
+    const climbs = rows.filter((r) => r.source === "climb" && r.from !== r.rung);
+    const first = rows[0]?.rung ?? "?";
+    const last = rows.at(-1)?.rung ?? first;
+    return `- ${lane} · ${first}${last !== first ? ` → ${last}` : ""}${climbs.length ? ` · climbs: ${climbs.map((c) => c.reason ?? "").join("; ")}` : ""}`;
+  });
+  const records = readRecords(run).records;
+  // the reviewer the gate counted: since the milestone's lanes started, a dispatch or a native subagent
+  const reviewer = milestoneReviewer(run, m, start);
+  const agents = readAgentRuns(run);
+  // the verdict the gate counted: the latest attempt, native or headless, a FAIL shown as such
+  const verdict = milestoneVerifier(run, m, start);
+  // the milestone's carried items: once any step names its milestone (gate_check's milestone), only the steps
+  // naming this one; before that, every step since the milestone's lanes started
+  const allSteps = readJsonl<VerifierStep>(join(run.dir, "verifier.jsonl")).rows.filter(
+    (s) => typeof s?.item === "string",
+  );
+  const byMilestone = allSteps.some((s) => typeof s.milestone === "string");
+  const steps = allSteps.filter(
+    (s) =>
+      s.carried &&
+      (start === null || Date.parse(s.at) >= Date.parse(start)) &&
+      (!byMilestone || s.milestone === m),
+  );
+  const mineRecords = records.filter((r) => inM(r.lane) || namesMilestone(r.name, m));
+  const tokens = mineRecords.reduce(
+    (t, r) => ({
+      input: t.input + r.tokens.input,
+      cached: t.cached + r.tokens.cached,
+      output: t.output + r.tokens.output,
+    }),
+    { input: 0, cached: 0, output: 0 },
+  );
+  const reported = agents
+    .filter((a) => inM(a.lane) || namesMilestone(a.name, m))
+    .reduce((n, a) => n + a.totalTokens, 0);
+  const text = [
+    `# ${m} — ${i.what}`,
+    "",
+    `Commit ${i.commit} · ${i.minutes} min · landed ${i.at}`,
+    `A-lines: ${aLines.length ? aLines.join("; ") : "none named in what or evidence"}`,
+    "",
+    "Lanes:",
+    ...(lanes.length ? lanes : ["- none routed"]),
+    "",
+    `Reviewer: ${reviewer ? `${reviewer.name} · ${reviewer.record ? findingCounts(run, reviewer.record) : "a Claude subagent (findings in its reply)"}` : "none"}`,
+    `Verifier: ${verdict ? `${verdict.passed ? "PASS" : `FAIL: ${verdict.verdict}`} (${verdict.name}${verdict.headless ? ", headless" : ""})` : "none"}${steps.length ? ` · carried: ${steps.map((s) => `${s.item}${s.commit ? ` from ${s.commit}` : ""}`).join(", ")}` : ""}`,
+    `Evidence: ${i.evidence}`,
+    `Tokens: ${k(tokens.input)} in (${k(tokens.cached)} cached) · ${k(tokens.output)} out · Claude subagents ${k(reported)} (reported)`,
+    "",
+  ].join("\n");
+  const dir = join(run.dir, "digests");
+  ensurePrivateDir(dir);
+  writeTextAtomic(join(dir, `${m}.md`), text);
+  return `digests/${m}.md`;
+}

package/src/services/questions.ts

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import { assertId } from "../domain/ids.ts";
+import { appendJsonl, ensureJsonlHeader, readJsonl } from "../infra/store.ts";
+import type { Deps } from "./ports.ts";
+import { findRun, type Run } from "./run-store.ts";
+import { type Notes, readNotes, refreshState } from "./state.ts";
+
+// Spec 1.1 §8: an owner question parks its milestone instead of stopping the run.
+
+interface QuestionRow {
+  at: string;
+  milestone: string;
+  kind: "question" | "answer";
+  text: string;
+}
+
+export interface OpenQuestion {
+  milestone: string;
+  question: string;
+  at: string;
+}
+
+const questionsFile = (run: Run): string => join(run.dir, "questions.jsonl");
+
+const rows = (run: Run): QuestionRow[] =>
+  readJsonl<QuestionRow>(questionsFile(run)).rows.filter(
+    (r) => typeof r?.milestone === "string" && typeof r.text === "string",
+  );
+
+/** The questions not answered yet, oldest first; a milestone answered after its question is no longer open. */
+export function openQuestions(run: Run): OpenQuestion[] {
+  const open = new Map<string, OpenQuestion>();
+  for (const r of rows(run)) {
+    if (r.kind === "question") open.set(r.milestone, { milestone: r.milestone, question: r.text, at: r.at });
+    else open.delete(r.milestone);
+  }
+  return [...open.values()];
+}
+
+function append(run: Run, row: QuestionRow): void {
+  const file = questionsFile(run);
+  ensureJsonlHeader(file, "questions");
+  appendJsonl(file, row);
+}
+
+/** `park`: the milestone waits on the owner; the rest of the run goes on. */
+export async function park(
+  deps: Deps,
+  i: { run: string; milestone: string; question: string },
+): Promise<{ parked: string[]; hints: string[] }> {
+  const run = findRun(i.run);
+  assertId("milestone", i.milestone);
+  append(run, {
+    at: new Date(deps.now()).toISOString(),
+    milestone: i.milestone,
+    kind: "question",
+    text: i.question,
+  });
+  let parked: string[] = [];
+  const { hints } = await refreshState(run, (n: Notes) => {
+    parked = [...new Set([...(n.parked ?? []), i.milestone])];
+    return { parked };
+  });
+  return {
+    parked,
+    hints: [
+      `push the full question to the owner now (PushNotification): ${i.milestone}: ${i.question}`,
+      `continue with the milestones and runs that do not depend on ${i.milestone}; when the owner answers, call answer(run, "${i.milestone}", <their answer>)`,
+      ...hints,
+    ],
+  };
+}
+
+/** `answer`: records the owner's answer and unparks the milestone. */
+export async function answer(
+  deps: Deps,
+  i: { run: string; milestone: string; answer: string },
+): Promise<{ milestone: string; parked: string[]; hints?: string[] }> {
+  const run = findRun(i.run);
+  assertId("milestone", i.milestone);
+  const open = openQuestions(run).some((q) => q.milestone === i.milestone);
+  // answered already, but the state save that unparks it failed: this call only unparks
+  const stillParked = !open && (readNotes(run).parked ?? []).includes(i.milestone);
+  if (!open && !stillParked)
+    throw new CatherdError("E_INPUT_INVALID", `${i.milestone} has no open question`, {
+      fix: "status(run) lists the open questions; park(run, milestone, question) opens one",
+    });
+  if (open)
+    append(run, {
+      at: new Date(deps.now()).toISOString(),
+      milestone: i.milestone,
+      kind: "answer",
+      text: i.answer,
+    });
+  let parked: string[] = [];
+  const { hints } = await refreshState(run, (n: Notes) => {
+    parked = (n.parked ?? []).filter((m) => m !== i.milestone);
+    return { parked, next: `${i.milestone}: the owner answered; continue it` };
+  });
+  return { milestone: i.milestone, parked, ...(hints.length ? { hints } : {}) };
+}

package/src/services/reconcile.ts

@@ -0,0 +1,130 @@
+import { readFileSync, statSync } from "node:fs";
+import { errorMessage } from "../domain/errors.ts";
+import { dispatchPaths } from "../infra/dispatch-dir.ts";
+import { log } from "../infra/log.ts";
+import { writeJsonAtomic } from "../infra/store.ts";
+import { settle, stallPoll, unsettledLimits, watching } from "./dispatch-service.ts";
+import { type Dispatch, listDispatches, pendingDispatches } from "./dispatches.ts";
+import { finalizeDispatch, waitForFinish } from "./finalize.ts";
+import type { Deps } from "./ports.ts";
+import { listRuns, type Run } from "./run-store.ts";
+import { ownsRun } from "./sessions.ts";
+
+/**
+ * Builds before the spec.json fix (plan-2 review I1) wrote every env value of the MCP server into
+ * spec.json, readable by others. A spec is read once, when its supervisor starts, so such a file loses
+ * its env and becomes 0600. Returns how many it scrubbed.
+ */
+function scrubOldSpecs(run: Run): number {
+  let n = 0;
+  for (const d of listDispatches(run)) {
+    const file = dispatchPaths(d.dir).spec;
+    try {
+      if ((statSync(file).mode & 0o077) === 0) continue;
+      const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+      writeJsonAtomic(file, { ...doc, env: {} }, { mode: 0o600 });
+      n++;
+    } catch {
+      // no spec.json, or one that cannot be read: nothing to scrub
+    }
+  }
+  return n;
+}
+
+export interface ReconcileReport {
+  finalized: string[];
+  watching: string[];
+  warnings: string[];
+  /** settles once every watched dispatch is finalized */
+  done: Promise<void>;
+}
+
+/**
+ * Waits for a live dispatch this process did not start, then finalizes and settles it (plan 10). A state.md
+ * refresh that fails rejects, after the record is written, with a message that says so.
+ */
+async function watchAndFinalize(deps: Deps, run: Run, d: Dispatch): Promise<void> {
+  watching.add(d.admit.dispatchId);
+  try {
+    await waitForFinish(d, { pollMs: deps.pollMs, now: deps.now, onPoll: stallPoll(run, d) });
+    const record = await finalizeDispatch(run, d);
+    // a limit of a run this session does not own waits, unread, for the session that claims the run
+    if (record.status === "limit" && !ownsRun(deps, run)) return;
+    const s = await settle(deps, run, d, record);
+    if (s.stateHints[0]) throw new Error(s.stateHints[0]);
+  } finally {
+    watching.delete(d.admit.dispatchId);
+  }
+}
+
+/**
+ * Spec §4.7: on server start, finalize and settle each finished dispatch that has no record, settle each
+ * unread usage limit that was never failed over (its server died between the two), and watch each live one
+ * until it finishes. A run that cannot be read is skipped with a warning; it never stops the server.
+ *
+ * Plan 10 fix-round ruling: a usage limit fails over here only in a run this session owns. A limit of a run
+ * another session owns, or no session does (a 1.0 run, a run started outside Claude Code), is only recorded:
+ * the session that claims the run settles it then (`claim`), so no stale run starts a stand-in on its own.
+ */
+export async function reconcileAll(deps: Deps): Promise<ReconcileReport> {
+  const { runs, corrupt } = listRuns();
+  const report: Omit<ReconcileReport, "done"> = {
+    finalized: [],
+    watching: [],
+    warnings: corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`),
+  };
+  const watchers: Promise<void>[] = [];
+  const warn = (run: Run, e: unknown): void => {
+    const w = `${run.id}: ${errorMessage(e)}`;
+    if (!report.warnings.includes(w)) report.warnings.push(w);
+  };
+  for (const run of runs) {
+    let pending;
+    try {
+      const scrubbed = scrubOldSpecs(run);
+      if (scrubbed) log("warn", "reconcile", { run: run.id, scrubbedSpecs: scrubbed });
+      pending = pendingDispatches(run, deps.now());
+    } catch (e) {
+      warn(run, e);
+      continue;
+    }
+    const mine = ownsRun(deps, run);
+    for (const d of pending) {
+      if (d.state !== "finished") {
+        report.watching.push(d.admit.dispatchId);
+        watchers.push(watchAndFinalize(deps, run, d).catch((e: unknown) => warn(run, e)));
+        continue;
+      }
+      let hints: string[] = [];
+      try {
+        const record = await finalizeDispatch(run, d);
+        if (record.status !== "limit" || mine) hints = (await settle(deps, run, d, record)).stateHints;
+      } catch (e) {
+        warn(run, e);
+        continue;
+      }
+      report.finalized.push(d.admit.dispatchId);
+      for (const h of hints) warn(run, h);
+    }
+    let limits: ReturnType<typeof unsettledLimits> = [];
+    try {
+      if (mine) limits = unsettledLimits(run);
+    } catch (e) {
+      warn(run, e);
+    }
+    for (const { d, record } of limits) {
+      try {
+        for (const h of (await settle(deps, run, d, record)).stateHints) warn(run, h);
+      } catch (e) {
+        warn(run, e);
+      }
+    }
+  }
+  log("info", "reconcile", {
+    runs: runs.length,
+    finalized: report.finalized.length,
+    watching: report.watching.length,
+    warnings: report.warnings,
+  });
+  return { ...report, done: Promise.all(watchers).then(() => undefined) };
+}

package/src/services/reentry.ts

@@ -0,0 +1,22 @@
+import { latestVerifierStep, type VerifierStep } from "./gate-service.ts";
+import { protocolView } from "./protocol.ts";
+import { type OpenQuestion, openQuestions } from "./questions.ts";
+import type { Run } from "./run-store.ts";
+import { readNotes } from "./state.ts";
+
+// Spec 1.1 §8, §7 and §10: what a session re-entering a run needs first, as peek returns it: the owner questions still open, the protocol's next step with its checklist,
+// and the verifier's latest step.
+
+export interface Reentry {
+  questions: OpenQuestion[];
+  protocol: { next: string; checklist: string[] };
+  verifier: VerifierStep | null;
+}
+
+export function reentry(run: Run, now?: number): Reentry {
+  return {
+    questions: openQuestions(run),
+    protocol: protocolView(run, readNotes(run).parked ?? [], now),
+    verifier: latestVerifierStep(run),
+  };
+}