catherd-cli 1.4.0 → 1.5.0

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,
@@ -38,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>;
 
@@ -66,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"),
   };
@@ -83,6 +90,9 @@ export function createRun(o: {
   aLines: string[];
   version: string;
   now?: Date;
+  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;
@@ -90,6 +100,9 @@ export function createRun(o: {
     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);
@@ -130,6 +143,8 @@ export function createRun(o: {
     createdAt: now.toISOString(),
     catherdVersion: o.version,
     ...(o.startedBy ? { startedBy: StartedBySchema.parse(o.startedBy) } : {}),
+    ...(workspace ? { workspace } : {}),
+    ...(o.startHead ? { startHead: o.startHead } : {}),
   };
   writeJsonAtomic(p.meta, meta);
   return { id, dir, meta };
@@ -141,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);
@@ -220,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);
@@ -255,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] : [];
   });
 }
@@ -276,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

@@ -12,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
@@ -51,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;
@@ -126,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. */
@@ -183,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,

package/src/services/scratch.ts

@@ -0,0 +1,60 @@
+import { existsSync, lstatSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tryLock } from "../infra/filelock.ts";
+import { liveDispatches } from "./dispatches.ts";
+import { findRun, listRuns, type Run, runPaths } from "./run-store.ts";
+
+export interface ScratchCleaned {
+  /** the runs whose scratch folder was removed, with what it held */
+  removed: { run: string; bytes: number }[];
+  /** the runs left alone, and why: a role still writes there */
+  kept: { run: string; why: string }[];
+}
+
+/** The bytes under `dir`, links not followed; 0 for what cannot be read. */
+function sizeOf(dir: string): number {
+  let total = 0;
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      total += e.isDirectory() ? sizeOf(p) : (lstatSync(p, { throwIfNoEntry: false })?.size ?? 0);
+    }
+  } catch {
+    // gone or unreadable: counts as nothing
+  }
+  return total;
+}
+
+/**
+ * Spec 1.5 plan 21: `catherd runs clean [run]` removes the roles' scratch folders (`<run>/scratch/`, each role's
+ * TMPDIR) of a run with no live role, or of every such run. The run's own files, records and replies stay. A run
+ * whose admission is in progress is kept: that admission may have just created a role's scratch.
+ */
+export function cleanScratch(o: { run?: string; now?: number } = {}): ScratchCleaned {
+  const runs: Run[] = o.run ? [findRun(o.run)] : listRuns().runs;
+  const out: ScratchCleaned = { removed: [], kept: [] };
+  for (const run of runs) {
+    const dir = runPaths(run.dir).scratch;
+    if (!existsSync(dir)) continue;
+    // admission creates a role's scratch and admits its dispatch under this lock, so while cleanup holds it no
+    // scratch is half-admitted, and one an admission holds now belongs to a dispatch about to go live
+    const release = tryLock(runPaths(run.dir).admission);
+    if (!release) {
+      out.kept.push({ run: run.id, why: "a dispatch is being admitted" });
+      continue;
+    }
+    try {
+      const live = liveDispatches(run, o.now ?? Date.now());
+      if (live.length) {
+        out.kept.push({ run: run.id, why: `${live.map((d) => d.admit.name).join(", ")} still running` });
+        continue;
+      }
+      const bytes = sizeOf(dir);
+      rmSync(dir, { recursive: true, force: true });
+      out.removed.push({ run: run.id, bytes });
+    } finally {
+      release();
+    }
+  }
+  return out;
+}

package/src/services/sessions.ts

@@ -69,9 +69,11 @@ export function readSessionRows(run: Run): SessionRow[] {
 
 /**
  * Spec §3.3: `run_start`, `dispatch` and `peek` make the calling session the run's owner when it is not, and
- * append it to `R/sessions.jsonl`: that is how a run moves when it is continued from another session. Without host session identity it changes nothing. Returns whether the owner changed.
+ * append it to `R/sessions.jsonl`: that is how a run moves when it is continued from another session. Without host session identity it changes nothing, and neither does a role's process (`deps.role`, spec 1.5 plan 21). Returns whether the owner changed.
  */
 export async function claimRun(deps: Deps, run: Run): Promise<boolean> {
+  // spec 1.5 plan 21: a role's process never becomes the run's owner, whatever host identity it has
+  if (deps.role) return false;
   const me = currentSession(deps);
   if (!me) return false;
   const p = runPaths(run.dir);

package/src/services/source-derive.ts

@@ -8,9 +8,11 @@ import {
   type ModelsFile,
   outranks,
   type Score,
+  ScoreSchema,
   type ScoresFile,
 } from "../domain/catalog.ts";
 import {
+  EFFORT_ORDER,
   defaultEffortOf,
   type Derived,
   familyEfforts,
@@ -55,6 +57,18 @@ interface Keyed {
   row: SourceRow;
 }
 
+/**
+ * (1.2 minor) the fields where less is better: when two of a source's rows land on one rung, the lower one
+ * stands for it. Every other field keeps the higher.
+ */
+export const LOWER_IS_BETTER: ReadonlySet<string> = new Set([
+  "cost_per_task",
+  "median_time_to_first_token_seconds",
+]);
+
+/** Whether `a` should stand for a rung over `b` on `field`. */
+const better = (field: string, a: number, b: number): boolean => (LOWER_IS_BETTER.has(field) ? a < b : a > b);
+
 /** The score sources' rows, by source (spec 1.2 §3.3). */
 function scoreRows(raw: RawAnswers): [SourceId, SourceRow[]][] {
   const out: [SourceId, SourceRow[]][] = [];
@@ -93,7 +107,7 @@ export function derive(raw: RawAnswers, ctx: DeriveContext): Derived {
       const at = table.get(field) ?? new Map<string, Keyed>();
       table.set(field, at);
       const had = at.get(key);
-      if (!had || row.value > had.row.value)
+      if (!had || better(row.field, row.value, had.row.value))
         at.set(key, {
           key,
           family,
@@ -171,15 +185,19 @@ export function derive(raw: RawAnswers, ctx: DeriveContext): Derived {
       const family = map.family(id);
       if (family && effort !== null) shipped.add(`${family.id}#${effort}|${s.dim}`);
     }
+  // (1.2 minor) a sync carries a value only up to a stronger effort: a low effort never takes a high one's
   scores.push(
-    ...adjacent(ctx.models.families, scores, shipped, ctx.now, (f) => defaultEffortOf(ctx.sources, f)),
+    ...adjacent(ctx.models.families, scores, shipped, ctx.now, (f) => defaultEffortOf(ctx.sources, f), {
+      upwardOnly: true,
+    }),
   );
 
   const { facts, warnings } = factsOf(raw, ctx, map);
   return {
     schema: 1,
     builtAt: new Date(ctx.now).toISOString(),
-    scores,
+    // (1.2 minor) readDerived validates every score: one bad row would make the whole file unreadable
+    scores: scores.filter((s) => ScoreSchema.safeParse(s).success),
     facts,
     fits,
     unmatched: Object.fromEntries(Object.entries(unmatched).map(([s, ids]) => [s, [...ids].sort()])),
@@ -212,7 +230,8 @@ function aaFeatures(table: Map<string, Map<string, Keyed>>): Derived["features"]
 /**
  * Spec 1.2 §4.3 `adjacent`: for each family effort a dimension has no value at (neither one in `direct` nor
  * one `shipped` names, as `<family>#<effort>|<dim>`), the best value in `direct` at the nearest effort that
- * has one (the weaker on a tie). A sync spreads only its own values, and never onto a value the shipped file
+ * has one (the weaker on a tie); with `upwardOnly` (a sync's values, 1.2 minor), only a weaker effort's value
+ * is carried, so Luna none never takes Luna max's. A sync spreads only its own values, and never onto a value the shipped file
  * carries; `rebuildShipped` spreads the shipped file's published values, with an empty `shipped`. A family that
  * one backend runs without an effort (Cursor's bare slug, spec 1.3 §7.1) also gets `#default`, carried from the
  * value nearest `defaultEffort(family)`.
@@ -223,7 +242,9 @@ export function adjacent(
   shipped: ReadonlySet<string>,
   now: number,
   defaultEffort: (f: Family) => string = () => "high",
+  o: { upwardOnly?: boolean } = {},
 ): Score[] {
+  const rank = (e: string) => (EFFORT_ORDER as readonly string[]).indexOf(e);
   const out: Score[] = [];
   for (const f of families)
     for (const dim of DIMS) {
@@ -239,7 +260,9 @@ export function adjacent(
       const bare = efforts.length > 0 && Object.values(f.on).some((o) => o && o.efforts.length === 0);
       for (const e of bare ? [...efforts, "default"] : efforts) {
         if (byEffort.has(e) || shipped.has(`${f.id}#${e}|${dim}`)) continue;
-        const near = nearestEffort(e === "default" ? defaultEffort(f) : e, [...byEffort.keys()]);
+        const target = e === "default" ? defaultEffort(f) : e;
+        const from_ = [...byEffort.keys()].filter((x) => !o.upwardOnly || rank(x) <= rank(target));
+        const near = nearestEffort(target, from_);
         const from = near ? byEffort.get(near) : undefined;
         if (!near || !from) continue;
         out.push({

package/src/services/source-sync.ts

@@ -49,6 +49,8 @@ export interface SyncOptions {
   force?: boolean;
   /** the MCP server's boot sync: skips when another sync runs, and gives a failing source an hour's rest */
   background?: boolean;
+  /** false: answer `busy` at once when another sync holds the lock (the catalog_sync tool), never wait */
+  wait?: boolean;
   /** how every source is fetched; tests replace it */
   transport?: SourceTransport;
   /** the Artificial Analysis key; default: the env's, else the saved one */
@@ -129,7 +131,7 @@ export function cachedAnswers(): RawAnswers {
  */
 export async function syncSources(o: SyncOptions = {}): Promise<SyncReport> {
   const now = o.now ?? Date.now;
-  const release = await takeLock(o.background === true);
+  const release = await takeLock(o.background === true || o.wait === false);
   if (!release)
     return {
       busy: true,
@@ -177,16 +179,19 @@ export async function syncSources(o: SyncOptions = {}): Promise<SyncReport> {
           lastAttemptAt: iso(at),
           error: null,
           rateLimitRemaining: limit,
+          rateLimitAt: limit === null ? null : iso(at),
         };
         outcomes.set(id, { source: id, state: "fetched", fetchedAt: iso(at) });
       } catch (e) {
         const error = errorMessage(e);
         const limit = e instanceof SourceError ? rateLimitRemaining(e.headers) : null;
+        // (1.2 minor) a failure with no header keeps the last count with the time that count was read
         state.sources[id] = {
           fetchedAt: prev?.fetchedAt ?? null,
           lastAttemptAt: iso(at),
           error,
           rateLimitRemaining: limit ?? prev?.rateLimitRemaining ?? null,
+          rateLimitAt: limit === null ? (prev?.rateLimitAt ?? null) : iso(at),
         };
         outcomes.set(id, { source: id, state: "failed", fetchedAt: prev?.fetchedAt ?? null, error });
         log(o.background ? "debug" : "warn", "sources", { source: id, error });
@@ -300,6 +305,8 @@ export function sourcesStatus(): {
     })),
     aaKey: aaKey() !== null,
     rateLimitRemaining: aa?.rateLimitRemaining ?? null,
-    rateLimitAt: aa?.rateLimitRemaining === null || aa === undefined ? null : aa.lastAttemptAt,
+    // a state written before 1.5 has no rateLimitAt: its last attempt is the best guess
+    rateLimitAt:
+      aa?.rateLimitRemaining === null || aa === undefined ? null : (aa.rateLimitAt ?? aa.lastAttemptAt),
   };
 }

package/src/services/standins.ts

@@ -22,6 +22,13 @@ export type Features = Record<string, number | string>;
 /** Spec 1.2 §6.3: a pair sharing fewer features than this is not suggested. */
 export const MIN_SHARED_FEATURES = 3;
 
+/**
+ * Spec 1.5 plan 24: a rung stands in only when it has values of its own on at least this many dimensions. A
+ * sparse row (GPT-6.1 Sol's one honesty figure) ranks near everything, for it has few features to differ on,
+ * and would lend that one value to unrelated rungs.
+ */
+export const MIN_STANDIN_DIMS = 3;
+
 export interface Suggestion {
   /** the canonical rung that would stand in */
   like: string;
@@ -132,7 +139,11 @@ export function missingDims(c: Catalog, canonical: string, dims: readonly Dim[]
   return dims.filter((d) => !own[d] && !lent[d]);
 }
 
-/** Every dimension some bar of the catalog (the defaults, with the user's override) has a threshold on. */
+/**
+ * Every dimension some bar of the catalog (the defaults, with the user's override) has a threshold on: the
+ * dimensions a stand-in fills. No shipped bar uses `steer`, so it is never inferred by default; a user's steer
+ * bar makes it one (plan 14 Ruling 7, as the code has always read it; spec 1.5 plan 24 aligns the words).
+ */
 export function barDimsIn(c: Catalog): Dim[] {
   const used = new Set<string>();
   for (const kind of Object.values(c.bars))
@@ -148,13 +159,17 @@ class Ranker {
     for (const r of canonicalRungs(c)) this.all.set(r, featuresOf(c, r));
     this.z = scales([...this.all.values()]);
   }
-  /** The rungs with an own value on any of `dims`, nearest first; each with what it would lend. */
+  /**
+   * The rungs with an own value on any of `dims` (and on at least MIN_STANDIN_DIMS dimensions in all), nearest
+   * first; each with what it would lend.
+   */
   rank(canonical: string, dims: readonly Dim[]): Suggestion[] {
     const mine = this.all.get(canonical) ?? featuresOf(this.c, canonical);
     const out: Suggestion[] = [];
     for (const [other, f] of this.all) {
       if (other === canonical) continue;
       const own = ownValues(this.c, other);
+      if (Object.keys(own).length < MIN_STANDIN_DIMS) continue;
       const lends = dims.filter((d) => own[d] !== undefined);
       if (lends.length === 0) continue;
       const got = distance(mine, f, this.z);
@@ -173,10 +188,24 @@ export function suggestStandIns(c: Catalog, canonical: string, limit = 3): Sugge
   return new Ranker(c).rank(canonical, lacking.length ? lacking : DIMS).slice(0, limit);
 }
 
+/**
+ * Spec 1.5 plan 24: the same effort of the family's predecessor (`Family.predecessor`), when it has a value on
+ * `d` of its own; null otherwise.
+ */
+function predecessorOf(c: Catalog, canonical: string, d: Dim): { like: string; value: number } | null {
+  const pred = family(c, canonical)?.predecessor;
+  if (!pred) return null;
+  const like = `${pred}${canonical.slice(canonical.lastIndexOf("#"))}`;
+  const s = c.scores[like]?.[d];
+  return s ? { like, value: s.value } : null;
+}
+
 /**
  * Spec 1.2 §6.1: for every rung the catalog can name, per dimension the bars use that it has no value for
  * (of its own or through a treat-like), its nearest stand-in with a value there. A rung no rung is near
- * enough to (fewer than MIN_SHARED_FEATURES shared) gets none on that dimension.
+ * enough to (fewer than MIN_SHARED_FEATURES shared) gets none on that dimension. Spec 1.5 plan 24: a new
+ * release of a family line takes at least its predecessor's value at the same effort, so a guess never puts it
+ * below the model it replaces (the identity run's GPT-6.1 Sol at 37.2, under GPT-6 Luna).
  */
 export function inferStandIns(c: Catalog): Catalog["inferred"] {
   const dims = barDimsIn(c);
@@ -186,9 +215,14 @@ export function inferStandIns(c: Catalog): Catalog["inferred"] {
     const lacking = missingDims(c, canonical, dims);
     for (const d of lacking) {
       const best = ranker.rank(canonical, [d])[0];
-      if (!best) continue;
-      const entry: InferredStandIn = { like: best.like, distance: best.distance, features: best.features };
-      (out[canonical] ??= {})[d] = entry;
+      const pred = predecessorOf(c, canonical, d);
+      const nearest = best ? c.scores[best.like]?.[d]?.value : undefined;
+      let entry: InferredStandIn | null = best
+        ? { like: best.like, distance: best.distance, features: best.features }
+        : null;
+      if (pred && (nearest === undefined || pred.value >= nearest))
+        entry = { like: pred.like, distance: 0, features: ["predecessor"] };
+      if (entry) (out[canonical] ??= {})[d] = entry;
     }
   }
   return out;

package/src/services/state.ts

@@ -19,6 +19,8 @@ const NotesSchema = z.looseObject({
   lastLandedAt: z.string().nullable(),
   /** spec 1.1 §8: the milestones waiting on the owner */
   parked: z.array(z.string()).optional(),
+  /** spec 1.5: what changed since the run's pin, as dispatch last saw it */
+  pinChanges: z.array(z.string()).optional(),
 });
 export type Notes = z.infer<typeof NotesSchema>;
 export type NotesPatch = Partial<Omit<Notes, "schema">>;
@@ -68,6 +70,7 @@ export function updateState(run: Run, change: NotesPatch | ((n: Notes) => NotesP
         brief: relative(run.dir, dispatchPaths(d.dir).brief),
       })),
       lastCheck: next.lastCheck,
+      pinChanges: next.pinChanges ?? [],
       next: next.next,
       protocol: protocolNext(run, next.parked ?? []),
     });
@@ -76,6 +79,24 @@ export function updateState(run: Run, change: NotesPatch | ((n: Notes) => NotesP
   });
 }
 
+/**
+ * Writes state.json's notes only, with no git, under the state lock; for a writer that must not wait on git
+ * while it holds another lock (`land` in a workspace, #43 finding 5). It waits out a refresh's git (15 s).
+ */
+export function patchNotes(run: Run, change: (n: Notes) => NotesPatch): Promise<Notes> {
+  const stateJson = runPaths(run.dir).stateJson;
+  return withFileLock(
+    stateJson,
+    () => {
+      const notes = readNotes(run);
+      const next = parkedNext({ ...notes, ...change(notes) });
+      writeJsonAtomic(stateJson, next);
+      return next;
+    },
+    { timeoutMs: 30_000 },
+  );
+}
+
 /**
  * Ruling (b): a failed state.md refresh (git broken) never fails the call. The notes still go to state.json
  * under the state lock (state.md stays as it was), and the message comes back as a hint.