catherd-cli 1.0.0 → 1.1.0

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

@@ -3,11 +3,12 @@ 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 { refreshState } from "./state.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
@@ -39,19 +40,31 @@ export interface ReconcileReport {
 }
 
 /**
- * Waits for a live dispatch this process did not start, then finalizes it. A state.md refresh that
- * fails rejects, after the record is written, with a message that says so.
+ * 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> {
-  await waitForFinish(d, { pollMs: deps.pollMs, tickMs: Number.POSITIVE_INFINITY, now: deps.now });
-  await finalizeDispatch(run, d);
-  const { hints } = await refreshState(run);
-  if (hints[0]) throw new Error(hints[0]);
+  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 each finished dispatch that has no record, and watch each live
- * one until it finishes. A run that cannot be read is skipped with a warning; it never stops the server.
+ * 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();
@@ -75,20 +88,36 @@ export async function reconcileAll(deps: Deps): Promise<ReconcileReport> {
       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 {
-        await finalizeDispatch(run, d);
+        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 (await refreshState(run)).hints) warn(run, h);
+      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", {

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),
+  };
+}

package/src/services/run-service.ts

@@ -4,10 +4,16 @@ import { CatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
 import type { RunRecord } from "../domain/record.ts";
 import type { Role } from "../domain/roles.ts";
-import { dispatchPaths } from "../infra/dispatch-dir.ts";
+import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
 import { gitToplevel } from "../infra/git.ts";
 import { writeTextAtomic } from "../infra/store.ts";
-import { dispatchState, type DispatchState, latestDispatch } from "./dispatches.ts";
+import {
+  dispatchState,
+  type DispatchState,
+  latestDispatch,
+  listDispatches,
+  recordHints,
+} from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
 import {
   type AgentRun,
@@ -18,12 +24,19 @@ import {
   readRecords,
   runFile,
 } from "./run-store.ts";
+import { protocolView } from "./protocol.ts";
+import { claimRun, currentSession } from "./sessions.ts";
 import { refreshState } from "./state.ts";
 
 export async function startRun(
   deps: Deps,
   i: { repo: string; title: string; aLines: string[] },
-): Promise<{ run: string; dir: string; hints?: string[] }> {
+): Promise<{
+  run: string;
+  dir: string;
+  protocol: { next: string; checklist: string[] };
+  hints?: string[];
+}> {
   const top = await gitToplevel(i.repo);
   if (!top)
     throw new CatherdError("E_IO_PATH", `${i.repo} is not inside a git repository`, {
@@ -35,10 +48,13 @@ export async function startRun(
     aLines: i.aLines,
     version: deps.version,
     now: new Date(deps.now()),
+    startedBy: currentSession(deps),
   });
+  await claimRun(deps, run);
   // a failed state.md refresh never fails the start: the run exists and is usable, so a retry would orphan it
   const { hints } = await refreshState(run);
-  return { run: run.id, dir: run.dir, ...(hints.length ? { hints } : {}) };
+  // spec 1.1 §10: the milestone loop, so the orchestrator starts on the protocol
+  return { run: run.id, dir: run.dir, protocol: protocolView(run, []), ...(hints.length ? { hints } : {}) };
 }
 
 export function writeRunFile(i: { run: string; path: string; content: string }): {
@@ -81,17 +97,23 @@ function capReply(reply: string, path: string): string {
   return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
 }
 
-/** A role's latest dispatch: its record once finished, and its capped reply. Reads only. */
-export function result(
+/**
+ * A role's latest dispatch: its record once finished, its capped reply and its hints. Spec §3.7: reading a
+ * finished record marks it read, with the collect lease (each record is marked read once, whoever reads it);
+ * an earlier record of the same name still unread (a usage limit its stand-in replaced) is marked read with it,
+ * and its hints come first.
+ */
+export async function result(
   deps: Deps,
   i: { run: string; name: string },
-): {
+): Promise<{
   name: string;
   state: DispatchState | null;
   record: RunRecord | null;
   reply: string;
   replyPath: string | null;
-} {
+  hints: string[];
+}> {
   const run = findRun(i.run);
   assertId("role name", i.name);
   const d = latestDispatch(run, i.name);
@@ -99,7 +121,17 @@ export function result(
     throw new CatherdError("E_RUN_NOT_FOUND", `${i.name} was never dispatched in this run`, {
       fix: "status(run) lists the roles",
     });
-  const record = readRecords(run).records.find((r) => r.dispatchId === d.admit.dispatchId) ?? null;
+  const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
+  const record = records.get(d.admit.dispatchId) ?? null;
+  const hints: string[] = [];
+  for (const x of listDispatches(run).filter((x) => x.admit.name === i.name)) {
+    const r = records.get(x.admit.dispatchId);
+    if (!r || !awaitsCollect(x.dir) || !(await tryCollect(x.dir))) continue;
+    // read at once: the lease ends as the record goes out
+    endCollect(x.dir);
+    if (x.admit.dispatchId !== d.admit.dispatchId) hints.push(...recordHints(run, x, r));
+  }
+  if (record) for (const h of recordHints(run, d, record)) if (!hints.includes(h)) hints.push(h);
   const reply = dispatchPaths(d.dir).reply;
   const text = existsSync(reply) ? readFileSync(reply, "utf8") : "";
   return {
@@ -108,6 +140,7 @@ export function result(
     record,
     reply: capReply(text, relative(run.dir, reply)),
     replyPath: relative(run.dir, reply),
+    hints,
   };
 }
 

package/src/services/run-store.ts

@@ -20,6 +20,14 @@ import {
   writeTextAtomic,
 } from "../infra/store.ts";
 
+/** Spec §3.3: the Claude Code session that started a run; absent on 1.0 runs and outside Claude Code. */
+const StartedBySchema = z.object({
+  sessionId: z.string(),
+  hostSessionId: z.string().nullable(),
+  name: z.string().nullable(),
+});
+export type StartedBy = z.infer<typeof StartedBySchema>;
+
 const RunMetaSchema = z.looseObject({
   schema: z.literal(1),
   id: z.string(),
@@ -28,6 +36,7 @@ const RunMetaSchema = z.looseObject({
   aLines: z.array(z.string()),
   createdAt: z.string(),
   catherdVersion: z.string(),
+  startedBy: StartedBySchema.nullable().optional(),
 });
 type RunMeta = z.infer<typeof RunMetaSchema>;
 
@@ -52,6 +61,8 @@ export function runPaths(dir: string) {
     outcomes: join(dir, "outcomes.jsonl"),
     agents: join(dir, "agents.jsonl"),
     harness: join(dir, "harness.jsonl"),
+    /** every session that has owned the run, in order (spec §3.3) */
+    sessions: join(dir, "sessions.jsonl"),
     roles: join(dir, "roles"),
     shots: join(dir, "shots"),
     /** the admission lock's target: `admission.lock` guards dispatch admission */
@@ -71,6 +82,7 @@ export function createRun(o: {
   aLines: string[];
   version: string;
   now?: Date;
+  startedBy?: StartedBy | null;
 }): Run {
   const now = o.now ?? new Date();
   const root = runsDir(o.repo);
@@ -111,6 +123,7 @@ export function createRun(o: {
     aLines: o.aLines,
     createdAt: now.toISOString(),
     catherdVersion: o.version,
+    ...(o.startedBy ? { startedBy: o.startedBy } : {}),
   };
   writeJsonAtomic(p.meta, meta);
   return { id, dir, meta };
@@ -270,7 +283,10 @@ const SERVER_OWNED = new Set([
   "jev.jsonl",
   "agents.jsonl",
   "harness.jsonl",
+  "verifier.jsonl",
+  "questions.jsonl",
   "outcomes.jsonl",
+  "sessions.jsonl",
 ]);
 
 const present = (p: string) => {
@@ -299,6 +315,8 @@ export function runFile(run: Run, path: string, mode: "read" | "write"): string
     (SERVER_OWNED.has(folded) ||
       folded === "roles" ||
       folded.startsWith(`roles${sep}`) ||
+      folded === "digests" ||
+      folded.startsWith(`digests${sep}`) ||
       folded.endsWith(".lock"))
   )
     throw new CatherdError("E_IO_PATH", `${rel} is written by catherd itself`, {