catherd-cli 1.3.0 → 1.5.0

package/src/services/run-service.ts

@@ -1,37 +1,115 @@
 import { existsSync, readFileSync } from "node:fs";
-import { relative } from "node:path";
+import { relative, sep } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId, parseRung } from "../domain/ids.ts";
+import { assertLaneValues } from "../domain/lane.ts";
 import type { RunRecord } from "../domain/record.ts";
 import type { Role } from "../domain/roles.ts";
 import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
-import { gitToplevel } from "../infra/git.ts";
-import { writeTextAtomic } from "../infra/store.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { git, gitToplevel } from "../infra/git.ts";
+import { writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
 import {
   dispatchState,
   type DispatchState,
   latestDispatch,
   listDispatches,
+  liveDispatches,
   recordHints,
 } from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
+import { assertNativeHost } from "./backends.ts";
 import {
   type AgentRun,
   appendAgentRun,
   appendKnowledge,
   createRun,
   findRun,
-  knowledgeFile,
+  knowledgeFor,
   readRecords,
   runFile,
+  type Run,
+  runPaths,
+  supersededBy,
+  supersededFile,
 } from "./run-store.ts";
-import { protocolView } from "./protocol.ts";
+import { protocolNext, protocolView } from "./protocol.ts";
+import { writePin } from "./run-pin.ts";
 import { claimRun, currentSession } from "./sessions.ts";
-import { refreshState } from "./state.ts";
+import { readNotes, refreshState } from "./state.ts";
+
+/** The run `id` was superseded by, or undefined: an open run, or one that cannot be found. */
+function nextInChain(id: string): string | undefined {
+  try {
+    return supersededBy(findRun(id))?.by;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `runs supersede <run> --by <run>`: closes `run` with a pointer to the run that took it over (a planning
+ * run handed to the execution run in a worktree). Status hides it; dispatch refuses it. A run with live
+ * roles is refused: cancel them, or let them finish, first.
+ */
+export async function supersedeRun(
+  deps: Deps,
+  i: { run: string; by: string },
+): Promise<{ run: string; by: string; at: string; hints?: string[] }> {
+  const run = findRun(i.run);
+  const by = findRun(i.by);
+  if (run.id === by.id)
+    throw new CatherdError("E_INPUT_INVALID", `run ${run.id} cannot supersede itself`, {
+      fix: "pass the run that took over as --by",
+    });
+  // walk the chain the new pointer would join: any run it reaches back to `run` closes a cycle
+  const seen = new Set<string>([by.id]);
+  for (let hop = supersededBy(by)?.by; hop !== undefined && !seen.has(hop);) {
+    if (hop === run.id)
+      throw new CatherdError("E_INPUT_INVALID", `run ${by.id} is itself superseded by ${run.id}`, {
+        fix: "supersede the older run by the newer one",
+      });
+    seen.add(hop);
+    hop = nextInChain(hop);
+  }
+  // under the run's admission lock: a dispatch admitted meanwhile is either live here, or sees the pointer
+  const at = await withFileLock(runPaths(run.dir).admission, () => {
+    assertNoLiveRoles(
+      deps,
+      run,
+      `cancel them (cancel(run, name)) or let them finish, then supersede ${run.id}`,
+    );
+    return writeSuperseded(deps, run, by.id);
+  });
+  return { run: run.id, by: by.id, at, ...(await supersededHints(run, by.id)) };
+}
+
+/** Held under `run`'s admission lock: no role of it may be live when it closes. */
+function assertNoLiveRoles(deps: Deps, run: Run, fix: string): void {
+  const live = liveDispatches(run, deps.now());
+  if (live.length)
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `run ${run.id} still has live roles: ${live.map((d) => d.admit.name).join(", ")}`,
+      { fix },
+    );
+}
+
+/** Held under `run`'s admission lock: the pointer to the run that took it over; its time. */
+function writeSuperseded(deps: Deps, run: Run, by: string): string {
+  const when = new Date(deps.now()).toISOString();
+  writeJsonAtomic(supersededFile(run), { schema: 1, by, at: when });
+  return when;
+}
+
+async function supersededHints(run: Run, by: string): Promise<{ hints?: string[] }> {
+  const { hints } = await refreshState(run, { next: `superseded by ${by}: continue there` });
+  return hints.length ? { hints } : {};
+}
 
 export async function startRun(
   deps: Deps,
-  i: { repo: string; title: string; aLines: string[] },
+  i: { repo: string; title: string; aLines: string[]; from?: string },
 ): Promise<{
   run: string;
   dir: string;
@@ -43,17 +121,39 @@ export async function startRun(
     throw new CatherdError("E_IO_PATH", `${i.repo} is not inside a git repository`, {
       fix: "pass the path of the repository to work in",
     });
-  const run = createRun({
-    repo: top,
-    title: i.title,
-    aLines: i.aLines,
-    version: deps.version,
-    now: new Date(deps.now()),
-    startedBy: currentSession(deps),
-  });
-  await claimRun(deps, run);
+  // where the first milestone's commit range starts; a repo with no commit yet has none
+  const head = await git(top, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  const open = async (): Promise<Run> => {
+    const run = createRun({
+      repo: top,
+      title: i.title,
+      aLines: i.aLines,
+      version: deps.version,
+      startHead: head.kind === "ok" ? head.out.trim() || null : null,
+      now: new Date(deps.now()),
+      startedBy: currentSession(deps),
+    });
+    // spec 1.5 "Pinned per run": what the run starts on stays what it dispatches on
+    writePin(deps, run);
+    await claimRun(deps, run);
+    return run;
+  };
+  // the run this one takes over must be free to close before anything is created, and stay so until its pointer
+  // is written: its admission lock is held from the check to the pointer, so no dispatch gets in between and
+  // leaves the new run open beside it (PR #50). It is the only lock taken first: the new run's are uncontended.
+  const from = i.from === undefined ? null : findRun(i.from);
+  const run = from
+    ? await withFileLock(runPaths(from.dir).admission, async () => {
+        assertNoLiveRoles(deps, from, `cancel them or let them finish, then run_start with from: ${from.id}`);
+        const opened = await open();
+        writeSuperseded(deps, from, opened.id);
+        return opened;
+      })
+    : await open();
+  const superseded = from ? await supersededHints(from, run.id) : {};
   // 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);
+  hints.push(...(superseded.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 } : {}) };
 }
@@ -62,7 +162,11 @@ export function writeRunFile(i: { run: string; path: string; content: string }):
   path: string;
   bytes: number;
 } {
-  const file = runFile(findRun(i.run), i.path, "write");
+  const run = findRun(i.run);
+  const file = runFile(run, i.path, "write");
+  // spec 1.5 "Lane editing": a lane's header values are checked when it is written, not first at preflight
+  const lane = /^lanes\/([^/]+)\.md$/.exec(relative(run.dir, file).split(sep).join("/"));
+  if (lane) assertLaneValues(i.content, `lanes/${lane[1]}.md`);
   writeTextAtomic(file, i.content);
   return { path: file, bytes: Buffer.byteLength(i.content) };
 }
@@ -98,6 +202,28 @@ function capReply(reply: string, path: string): string {
   return `${head.slice(0, CAP_CHARS)}\n[capped: the full reply is ${path}]`;
 }
 
+/** Whether `text` names `token` (a role name or lane id) as a whole word, a full stop after it allowed. */
+export function names(text: string, token: string): boolean {
+  const t = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?<![\\w.-])${t}(?![\\w-]|\\.\\w)`).test(text);
+}
+
+/**
+ * Plan 22: state.md's Next never outlives the step it names. When it names a role whose record `result` returns
+ * (by its name or its lane), it moves on to the protocol's next step. A refresh that fails comes back as hints.
+ */
+async function advanceNext(run: Run, record: RunRecord): Promise<string[]> {
+  const stale = (next: string) =>
+    names(next, record.name) || (record.lane !== null && names(next, record.lane));
+  if (!stale(readNotes(run).next)) return [];
+  const { hints } = await refreshState(run, (n) =>
+    stale(n.next)
+      ? { next: `after ${record.name} (${record.status}): ${protocolNext(run, n.parked ?? [])}` }
+      : {},
+  );
+  return hints;
+}
+
 /**
  * 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);
@@ -133,6 +259,7 @@ export async function result(
     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);
+  if (record) for (const h of await advanceNext(run, record)) if (!hints.includes(h)) hints.push(h);
   const reply = dispatchPaths(d.dir).reply;
   const text = existsSync(reply) ? readFileSync(reply, "utf8") : "";
   return {
@@ -158,6 +285,10 @@ export function recordAgentRun(
     durationMs?: number;
     status?: AgentRun["status"];
     lane?: string;
+    /** plan 23: a native verifier's first reply line, so a VERDICT: BLOCKED: environment is told from a FAIL */
+    verdict?: string;
+    /** plan 23: the STATUS word of the subagent's reply */
+    replyStatus?: NonNullable<AgentRun["replyStatus"]>;
   },
 ): AgentRun {
   const run = findRun(i.run);
@@ -167,6 +298,7 @@ export function recordAgentRun(
     throw new CatherdError("E_ADMIT_RUNG", `${i.rung} is not a native Claude rung`, {
       fix: "record_agent_run is for Agent subagents; dispatch records every other run itself",
     });
+  assertNativeHost(i.rung, deps.host.conflict ? "unknown" : deps.host.host);
   const row: AgentRun = {
     at: new Date(deps.now()).toISOString(),
     name: i.name,
@@ -178,6 +310,8 @@ export function recordAgentRun(
     secs: i.durationMs === undefined ? null : Math.round(i.durationMs / 1000),
     status: i.status ?? "ok",
     lane: i.lane ?? null,
+    ...(i.verdict ? { verdict: i.verdict.trim().split("\n")[0] } : {}),
+    ...(i.replyStatus ? { replyStatus: i.replyStatus } : {}),
   };
   appendAgentRun(run, row);
   return row;
@@ -195,7 +329,7 @@ async function repoTop(repo: string): Promise<string> {
 
 /** What past runs of the repo learned; `repo` may be any path inside it. */
 export async function readKnowledge(repo: string): Promise<string> {
-  const file = knowledgeFile(await repoTop(repo));
+  const file = await knowledgeFor(await repoTop(repo));
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
   return text.trim() ? text : "catherd: no knowledge recorded yet for this repo";
 }
@@ -203,7 +337,7 @@ export async function readKnowledge(repo: string): Promise<string> {
 /** Where the repo's knowledge.md is (it may not exist yet); `repo` may be any path inside it. */
 export async function knowledgePath(repo: string): Promise<{ repo: string; path: string }> {
   const top = await repoTop(repo);
-  return { repo: top, path: knowledgeFile(top) };
+  return { repo: top, path: await knowledgeFor(top) };
 }
 
 /** The repo's knowledge.md as its lines, none when it is missing or blank; `repo` may be any path inside it. */

package/src/services/run-store.ts

@@ -1,19 +1,21 @@
-import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId } from "../domain/ids.ts";
 import { type RunRecord, RunRecordSchema } from "../domain/record.ts";
-import type { OutcomeRow, RouteRow } from "../domain/route.ts";
+import type { OutcomeRouteRow, OutcomeRow, RoleRouteRow, RouteRow } from "../domain/route.ts";
 import { cell, slug } from "../domain/util.ts";
 import { withFileLock } from "../infra/filelock.ts";
-import { dataDir, repoDir, runsDir } from "../infra/paths.ts";
+import { gitOrigin } from "../infra/git.ts";
+import { dataDir, originDir, repoDir, runsDir } from "../infra/paths.ts";
 import {
   appendJsonl,
   ensureJsonlHeader,
   ensurePrivateDir,
   PRIVATE_DIR,
   appendPrivate,
+  nonBlankLines,
   readJsonl,
   readVersioned,
   writeJsonAtomic,
@@ -21,7 +23,8 @@ import {
 } 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({
+const StartedBySchema = z.looseObject({
+  host: z.enum(["claude-code", "codex"]).default("claude-code"),
   sessionId: z.string(),
   hostSessionId: z.string().nullable(),
   name: z.string().nullable(),
@@ -37,6 +40,9 @@ const RunMetaSchema = z.looseObject({
   createdAt: z.string(),
   catherdVersion: z.string(),
   startedBy: StartedBySchema.nullable().optional(),
+  workspace: z.strictObject({ id: z.string(), step: z.string() }).optional(),
+  /** the repo's HEAD when run_start ran: where the first milestone's commit range starts (absent before 1.5) */
+  startHead: z.string().optional(),
 });
 type RunMeta = z.infer<typeof RunMetaSchema>;
 
@@ -65,6 +71,8 @@ export function runPaths(dir: string) {
     sessions: join(dir, "sessions.jsonl"),
     roles: join(dir, "roles"),
     shots: join(dir, "shots"),
+    /** per dispatch name, the role's TMPDIR (spec 1.5 plan 21): `scratch/<name>/` */
+    scratch: join(dir, "scratch"),
     /** the admission lock's target: `admission.lock` guards dispatch admission */
     admission: join(dir, "admission"),
   };
@@ -82,8 +90,19 @@ export function createRun(o: {
   aLines: string[];
   version: string;
   now?: Date;
-  startedBy?: StartedBy | null;
+  workspace?: { id: string; step: string };
+  /** the repo's full HEAD at the start, when it has a commit */
+  startHead?: string | null;
+  startedBy?: {
+    host?: StartedBy["host"];
+    sessionId: string;
+    hostSessionId: string | null;
+    name: string | null;
+  } | null;
 }): Run {
+  const workspace = o.workspace
+    ? { id: assertId("workspace", o.workspace.id), step: assertId("workspace step", o.workspace.step) }
+    : undefined;
   const now = o.now ?? new Date();
   const root = runsDir(o.repo);
   ensurePrivateDir(root);
@@ -123,7 +142,9 @@ export function createRun(o: {
     aLines: o.aLines,
     createdAt: now.toISOString(),
     catherdVersion: o.version,
-    ...(o.startedBy ? { startedBy: o.startedBy } : {}),
+    ...(o.startedBy ? { startedBy: StartedBySchema.parse(o.startedBy) } : {}),
+    ...(workspace ? { workspace } : {}),
+    ...(o.startHead ? { startHead: o.startHead } : {}),
   };
   writeJsonAtomic(p.meta, meta);
   return { id, dir, meta };
@@ -135,14 +156,18 @@ export interface RunListing {
   corrupt: { id: string; dir: string; reason: string }[];
 }
 
-/** Every run of every repo, newest first. */
-export function listRuns(): RunListing {
+/** Every run, newest first; an explicit repo scope avoids reading unrelated histories. */
+export function listRuns(repos?: readonly string[]): RunListing {
   const root = join(dataDir(), "repos");
   const out: RunListing = { runs: [], corrupt: [] };
   if (!existsSync(root)) return out;
-  for (const repo of readdirSync(root, { withFileTypes: true })) {
-    const runs = join(root, repo.name, "runs");
-    if (!repo.isDirectory() || !existsSync(runs)) continue;
+  const directories = repos
+    ? [...new Set(repos.map(runsDir))]
+    : readdirSync(root, { withFileTypes: true })
+        .filter((repo) => repo.isDirectory())
+        .map((repo) => join(root, repo.name, "runs"));
+  for (const runs of directories) {
+    if (!existsSync(runs)) continue;
     for (const e of readdirSync(runs, { withFileTypes: true })) {
       if (!e.isDirectory()) continue;
       const dir = join(runs, e.name);
@@ -196,7 +221,7 @@ export function readRecords(run: Run): { records: RunRecord[]; corrupt: number }
     if (!r.success) bad++;
     else if (!seen.has(r.data.dispatchId)) {
       seen.add(r.data.dispatchId);
-      records.push(r.data);
+      records.push(r.data.sessionId && !r.data.host ? { ...r.data, host: "claude-code" } : r.data);
     }
   }
   return { records, corrupt: bad };
@@ -214,13 +239,32 @@ export function appendRecord(run: Run, r: RunRecord): Promise<RunRecord> {
   });
 }
 
+/** The run's lane rows (routes and climbs); a role's rows outside a lane are left out (`readRoleRoutes`). */
 export function readRoutes(run: Run): RouteRow[] {
   return readJsonl<RouteRow>(runPaths(run.dir).routes).rows.filter(
-    (r) => typeof r?.lane === "string" && Array.isArray(r.ladder) && typeof r.rung === "string",
+    (r) =>
+      typeof r?.lane === "string" &&
+      (r.source === "route" || r.source === "climb") &&
+      Array.isArray(r.ladder) &&
+      typeof r.rung === "string",
   );
 }
 
-export function appendRoute(run: Run, row: RouteRow): void {
+/** Spec 1.5 plan 24: the lanes' outcome rows of routes.jsonl, oldest first (the last per lane wins). */
+export function readOutcomeRoutes(run: Run): OutcomeRouteRow[] {
+  return readJsonl<OutcomeRouteRow>(runPaths(run.dir).routes).rows.filter(
+    (r) => typeof r?.lane === "string" && r.source === "outcome",
+  );
+}
+
+/** Spec 1.5 plan 24: the run's role decisions outside a lane, oldest first. */
+export function readRoleRoutes(run: Run): RoleRouteRow[] {
+  return readJsonl<RoleRouteRow>(runPaths(run.dir).routes).rows.filter(
+    (r) => r?.lane === null && typeof r.role === "string" && typeof r.rung === "string",
+  );
+}
+
+export function appendRoute(run: Run, row: RouteRow | RoleRouteRow | OutcomeRouteRow): void {
   const file = runPaths(run.dir).routes;
   ensureJsonlHeader(file, "routes");
   appendJsonl(file, row);
@@ -249,13 +293,22 @@ const AgentRunSchema = z.looseObject({
   status: z.enum(["ok", "failed", "cancelled"]),
   /** the lane the subagent worked, so catalog timings count it under that lane's kind; rows before it lack it */
   lane: z.string().nullable().optional(),
+  /** plan 23: a native verifier's verdict line (VERDICT: BLOCKED: environment — <probe>); rows before it lack it */
+  verdict: z.string().optional(),
+  /** plan 23: the STATUS word of the subagent's reply (a reviewer's partial is no review); rows before it lack it */
+  replyStatus: z.enum(["complete", "partial", "blocked", "refused", "flaky"]).optional(),
 });
 export type AgentRun = z.infer<typeof AgentRunSchema>;
 
 /** Native Claude subagent runs, as the orchestrator reported them through record_agent_run. */
-export function readAgentRuns(run: Run): AgentRun[] {
-  return readJsonl<unknown>(runPaths(run.dir).agents).rows.flatMap((row) => {
+export function readAgentRuns(run: Run, strict = false): AgentRun[] {
+  const { rows, corrupt } = readJsonl<unknown>(runPaths(run.dir).agents);
+  if (strict && corrupt)
+    throw new CatherdError("E_RUN_CORRUPT", `run ${run.id} has unreadable native cost records`);
+  return rows.flatMap((row) => {
     const r = AgentRunSchema.safeParse(row);
+    if (strict && !r.success)
+      throw new CatherdError("E_RUN_CORRUPT", `run ${run.id} has invalid native cost records`);
     return r.success ? [r.data] : [];
   });
 }
@@ -270,20 +323,67 @@ export function appendLedger(run: Run, row: string): void {
   appendPrivate(runPaths(run.dir).ledger, `${row}\n`);
 }
 
-/** Spec §4.7: what past runs of a repo learned, keyed by its git toplevel. */
+/** Spec §4.7: what past runs of a repo learned, keyed by its git toplevel (before 1.5, and with no origin). */
 export const knowledgeFile = (toplevel: string): string => join(repoDir(toplevel), "knowledge.md");
 
+/**
+ * Spec 1.5 "Knowledge keyed by git origin": the knowledge.md every worktree and clone of one repository
+ * shares, keyed by its `origin` remote, else by its toplevel. A toplevel-keyed file this worktree left before
+ * is migrated on read: its lines not there yet are appended, and it is renamed `knowledge.md.migrated`.
+ */
+export async function knowledgeFor(toplevel: string): Promise<string> {
+  const origin = await gitOrigin(toplevel);
+  const legacy = knowledgeFile(toplevel);
+  if (!origin) return legacy;
+  const file = join(originDir(origin), "knowledge.md");
+  if (!existsSync(legacy)) return file;
+  ensurePrivateDir(dirname(file));
+  await withFileLock(file, () => {
+    if (!existsSync(legacy)) return;
+    const have = new Set(existsSync(file) ? nonBlankLines(file) : []);
+    const add = nonBlankLines(legacy).filter((l) => !have.has(l));
+    if (add.length) appendPrivate(file, `${add.join("\n")}\n`);
+    renameSync(legacy, `${legacy}.migrated`);
+  });
+  return file;
+}
+
 /**
  * Appends one line to the repo's knowledge.md, `- <date> <source>: <text>` with `text` on one line, and returns
  * it. The single writer of knowledge.md: `land`'s `learned` and `catherd knowledge add` both come through here.
  */
-export function appendKnowledge(toplevel: string, at: Date, source: string, text: string): string {
+export async function appendKnowledge(
+  toplevel: string,
+  at: Date,
+  source: string,
+  text: string,
+): Promise<string> {
   const line = `- ${at.toISOString().slice(0, 10)} ${source}: ${cell(text)}`;
-  appendPrivate(knowledgeFile(toplevel), `${line}\n`);
+  appendPrivate(await knowledgeFor(toplevel), `${line}\n`);
   return line;
 }
 
+/** Spec 1.5 "runs supersede": the run that took over a closed one, and when. */
+const SupersededSchema = z.looseObject({ schema: z.literal(1), by: z.string(), at: z.string() });
+export type Superseded = z.infer<typeof SupersededSchema>;
+
+export const supersededFile = (run: Run): string => join(run.dir, "superseded.json");
+
+/** The pointer `runs supersede` left, or null: an open run, or a pointer that cannot be read. */
+export function supersededBy(run: Run): Superseded | null {
+  const file = supersededFile(run);
+  if (!existsSync(file)) return null;
+  try {
+    return readVersioned(file, SupersededSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
 const SERVER_OWNED = new Set([
+  "superseded.json",
+  "pin.json",
+  "workspace-contract.md",
   "meta.json",
   "state.md",
   "state.json",

package/src/services/runs-page.ts

@@ -1,3 +1,4 @@
+import { sessionKey } from "../domain/host.ts";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { budgetStatus } from "../domain/budget.ts";
@@ -11,6 +12,7 @@ import { lastActivity } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
 import { findRun, listRuns, readRecords, type Run, runPaths } from "./run-store.ts";
 import { groupRuns, type SessionGroup } from "./session-view.ts";
+import { orchestratorWait, type OrchestratorWait } from "./orchestrator-wait.ts";
 
 /**
  * Spec §4: what the Runs tab shows. The top level is the sessions; a session's screen holds its runs, each with its
@@ -50,11 +52,12 @@ export interface RoleRow {
 export interface Milestone {
   name: string;
   landed: boolean;
-  /** the ledger's "what" once landed */
+  /** the ledger's "what" once landed; before that, plan.md's line for the milestone ("" when it has none) */
   what: string;
 }
 
 export interface SessionRun {
+  waiting?: OrchestratorWait | null;
   id: string;
   title: string;
   repo: string;
@@ -98,7 +101,7 @@ export interface MilestoneDetail {
   digest: string | null;
 }
 
-const keyOf = (g: SessionGroup): string | null => g.session?.sessionId ?? null;
+const keyOf = (g: SessionGroup): string | null => (g.session ? sessionKey(g.session) : null);
 
 /** The runs that live on in a session now (it owns them): each run's live roles and landings count once. */
 const ownRuns = (g: SessionGroup): Run[] => g.runs.filter((x) => x.current).map((x) => x.run);
@@ -125,18 +128,50 @@ export function sessionRows(deps: Deps): { rows: SessionRow[]; warnings: string[
   };
 }
 
-/** The ledger's landed milestones, then each milestone a lane file names that has not landed. */
+/**
+ * A milestone's line in plan.md: a heading, list item or plain line that opens with its id and a separator
+ * (`## M1 — the jobs list`, `- **M2:** export`). The id stops at the separator, so `M1.L1 — …` is a lane's.
+ */
+const PLAN_LINE =
+  /^\s*(?:#{1,6}\s+|[-*]\s+|\d+[.)]\s+)?(?:\*\*)?([A-Za-z0-9_-]+)(?::\*\*|(?:\*\*)?\s*(?:—|–|:|-))\s*(.+?)\s*$/;
+
+/** The description plan.md gives each of `names`, from the first line that opens with it; none for the rest. */
+function planWhat(run: Run, names: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const file = runPaths(run.dir).plan;
+  if (names.length === 0 || !existsSync(file)) return out;
+  for (const line of readFileSync(file, "utf8").split("\n")) {
+    const m = PLAN_LINE.exec(line);
+    const name = m?.[1];
+    if (m && name && names.includes(name) && !out.has(name)) out.set(name, (m[2] ?? "").trim());
+  }
+  return out;
+}
+
+const byNumber = (a: string, b: string) => a.localeCompare(b, "en", { numeric: true });
+
+/**
+ * The ledger's landed milestones, then each milestone a lane file names that has not landed, whatever its id:
+ * lane `<milestone>.<lane>` belongs to the milestone before its first dot, as protocol.ts reads it. An open
+ * milestone's description is plan.md's line for it, when there is one.
+ */
 function milestonesOf(run: Run): Milestone[] {
   const landed = nonBlankLines(runPaths(run.dir).ledger)
     .slice(1)
     .map((l) => l.split(" | "))
     .map(([name, what]) => ({ name: (name ?? "").trim(), landed: true, what: (what ?? "").trim() }));
   const lanes = existsSync(runPaths(run.dir).lanes) ? readdirSync(runPaths(run.dir).lanes) : [];
-  const open = [...new Set(lanes.map((f) => /^(M\d+)\./.exec(f)?.[1]).filter((m): m is string => !!m))]
-    .filter((m) => !landed.some((l) => l.name === m))
-    .map((name) => ({ name, landed: false, what: "" }));
-  const n = (m: string) => Number(/\d+/.exec(m)?.[0] ?? 0);
-  return [...landed, ...open.sort((a, b) => n(a.name) - n(b.name))];
+  const names = [
+    ...new Set(
+      lanes
+        .filter((f) => f.endsWith(".md") && f.slice(0, -".md".length).includes("."))
+        .map((f) => f.split(".")[0] as string),
+    ),
+  ]
+    .filter((m) => m !== "" && !landed.some((l) => l.name === m))
+    .sort(byNumber);
+  const what = planWhat(run, names);
+  return [...landed, ...names.map((name) => ({ name, landed: false, what: what.get(name) ?? "" }))];
 }
 
 /** Each role's latest dispatch, live ones first, then the newest finished first. */
@@ -174,7 +209,7 @@ function sessionRun(deps: Deps, x: SessionGroup["runs"][number]): SessionRun {
   try {
     const b = budgetStatus(
       spendOf(run, readRecords(run).records, liveDispatches(run, deps.now()), deps.now()),
-      deps.profiles.forRepo(run.meta.repo).budget,
+      deps.profiles.budgetFor?.(run.meta.repo) ?? deps.profiles.forRepo(run.meta.repo).budget,
     );
     budget = b?.fraction ?? null;
   } catch {
@@ -182,6 +217,7 @@ function sessionRun(deps: Deps, x: SessionGroup["runs"][number]): SessionRun {
   }
   return {
     id: run.id,
+    waiting: orchestratorWait(run, deps.now()),
     title: run.meta.title,
     repo: run.meta.repo,
     createdAt: run.meta.createdAt,