catherd-cli 1.3.0 → 1.5.0

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/session-view.ts

@@ -1,3 +1,4 @@
+import { sessionKey, type KnownHost } from "../domain/host.ts";
 import { statSync } from "node:fs";
 import { liveSessionFile, readSessionFiles, type SessionFile } from "../infra/claude-session.ts";
 import { type Run, runPaths } from "./run-store.ts";
@@ -14,6 +15,7 @@ import { readSessionRows } from "./sessions.ts";
 
 /** A session as the runs page shows it: its name read live while it runs, else the last one recorded. */
 export interface RunSession {
+  host: KnownHost;
   sessionId: string;
   hostSessionId: string | null;
   name: string;
@@ -56,10 +58,11 @@ export function runActivity(run: Run): number {
 /** The sessions each run has had, oldest first: its starter, then each one that took it over. */
 function trailOf(
   run: Run,
-): { sessionId: string; hostSessionId: string | null; name: string | null; at: string }[] {
+): { host: KnownHost; sessionId: string; hostSessionId: string | null; name: string | null; at: string }[] {
   const rows = readSessionRows(run);
   const s = run.meta.startedBy;
-  if (s && !rows.some((r) => r.sessionId === s.sessionId)) return [{ ...s, at: run.meta.createdAt }, ...rows];
+  if (s && !rows.some((r) => sessionKey(r) === sessionKey(s)))
+    return [{ ...s, at: run.meta.createdAt }, ...rows];
   return rows;
 }
 
@@ -70,21 +73,23 @@ export function groupRuns(runs: Run[], files: SessionFile[] = readSessionFiles()
   const trails = new Map(runs.map((r) => [r.id, trailOf(r)]));
   for (const t of trails.values())
     for (const row of t) {
-      const was = recorded.get(row.sessionId);
+      const was = recorded.get(sessionKey(row));
       if (!was || row.at >= was.at)
-        recorded.set(row.sessionId, {
+        recorded.set(sessionKey(row), {
           name: row.name ?? was?.name ?? null,
           host: row.hostSessionId ?? was?.host ?? null,
           at: row.at,
         });
     }
   const sessionOf = (id: string): RunSession => {
-    const live = liveSessionFile(id, files);
+    const [host, sessionId] = JSON.parse(id) as [KnownHost, string];
+    const live = host === "claude-code" ? liveSessionFile(sessionId, files) : null;
     const rec = recorded.get(id);
     return {
-      sessionId: id,
+      host,
+      sessionId,
       hostSessionId: live?.hostSessionId ?? rec?.host ?? null,
-      name: live?.name ?? rec?.name ?? `session ${id.slice(0, 8)}`,
+      name: live?.name ?? rec?.name ?? `session ${sessionId.slice(0, 8)}`,
       live: live !== null,
     };
   };
@@ -101,13 +106,13 @@ export function groupRuns(runs: Run[], files: SessionFile[] = readSessionFiles()
   for (const run of runs) {
     const at = runActivity(run);
     const trail = trails.get(run.id) ?? [];
-    const starter = run.meta.startedBy?.sessionId ?? null;
+    const starter = run.meta.startedBy ? sessionKey(run.meta.startedBy) : null;
     // the run lives on in its current owner: the last session that took it (a run can come back to its starter)
-    const owner = trail.at(-1)?.sessionId ?? starter;
+    const owner = trail.at(-1) ? sessionKey(trail.at(-1)!) : starter;
     const moved = owner !== starter && owner !== null;
     // a run that lives on elsewhere counts, in a session it left, from when that session last took it
     const tookAt = (id: string | null): number =>
-      Date.parse(trail.findLast((t) => t.sessionId === id)?.at ?? run.meta.createdAt) || 0;
+      Date.parse(trail.findLast((t) => sessionKey(t) === id)?.at ?? run.meta.createdAt) || 0;
     add(
       starter,
       {
@@ -118,7 +123,7 @@ export function groupRuns(runs: Run[], files: SessionFile[] = readSessionFiles()
       },
       moved ? tookAt(starter) : at,
     );
-    for (const id of new Set(trail.map((t) => t.sessionId)))
+    for (const id of new Set(trail.map(sessionKey)))
       if (id !== starter)
         add(
           id,
@@ -146,7 +151,7 @@ export function sessionFacts(
   run: Run,
   files: SessionFile[] = readSessionFiles(),
 ): { session: RunSession | null; continuedIn: string | null } {
-  const starter = run.meta.startedBy?.sessionId ?? null;
-  const own = groupRuns([run], files).find((g) => (g.session?.sessionId ?? null) === starter);
+  const starter = run.meta.startedBy ? sessionKey(run.meta.startedBy) : null;
+  const own = groupRuns([run], files).find((g) => (g.session ? sessionKey(g.session) : null) === starter);
   return { session: own?.session ?? null, continuedIn: own?.runs[0]?.continuedIn ?? null };
 }

package/src/services/sessions.ts

@@ -1,3 +1,4 @@
+import { sessionKey, type HostSessionRef } from "../domain/host.ts";
 import { z } from "zod";
 import { sessionFileFor } from "../infra/claude-session.ts";
 import { withFileLock } from "../infra/filelock.ts";
@@ -6,27 +7,34 @@ import type { Deps } from "./ports.ts";
 import { type Run, runPaths } from "./run-store.ts";
 import { readNotes } from "./state.ts";
 
-/** Spec §4: a Claude Code session as catherd records it. */
-export interface SessionRef {
-  sessionId: string;
-  hostSessionId: string | null;
-  name: string | null;
-}
+/** Spec §4: a host session as catherd records it. */
+export type SessionRef = HostSessionRef;
 
 /**
  * The session this process serves (spec §3.3), read live: its registry file's id and name when it has one (the
- * id in the environment goes stale after /clear), else the environment's. Null outside Claude Code.
+ * id in the environment goes stale after /clear), else the environment's. Null without known, consistent host identity.
  */
 export function currentSession(deps: Deps): SessionRef | null {
+  if (deps.host.host === "unknown" || deps.host.conflict) return null;
+  if (deps.host.host === "codex") return deps.host.session;
   const env = deps.session;
-  if (!env) return null;
+  if (!env) return deps.host.session;
   const file = sessionFileFor(env);
   const sessionId = file?.sessionId ?? env.sessionId;
   if (!sessionId) return null;
-  return { sessionId, hostSessionId: file?.hostSessionId ?? env.hostSessionId, name: file?.name ?? null };
+  return {
+    host: "claude-code",
+    sessionId,
+    hostSessionId: file?.hostSessionId ?? env.hostSessionId,
+    name: file?.name ?? null,
+  };
 }
 
-const OwnerSchema = z.object({ sessionId: z.string(), since: z.string() });
+const OwnerSchema = z.looseObject({
+  host: z.enum(["claude-code", "codex"]).default("claude-code"),
+  sessionId: z.string(),
+  since: z.string(),
+});
 export type Owner = z.infer<typeof OwnerSchema>;
 
 /** The run's owner session (state.json `owner`), or null for a run no session has owned (1.0, a terminal). */
@@ -38,10 +46,12 @@ export function runOwner(run: Run): Owner | null {
 /** Whether this process serves a session and that session owns the run now. */
 export function ownsRun(deps: Deps, run: Run): boolean {
   const me = currentSession(deps);
-  return me !== null && runOwner(run)?.sessionId === me.sessionId;
+  const owner = runOwner(run);
+  return me !== null && owner !== null && sessionKey(owner) === sessionKey(me);
 }
 
 const SessionRowSchema = z.looseObject({
+  host: z.enum(["claude-code", "codex"]).default("claude-code"),
   sessionId: z.string(),
   hostSessionId: z.string().nullable(),
   name: z.string().nullable(),
@@ -59,10 +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. Outside
- * Claude Code 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);
@@ -70,6 +81,7 @@ export async function claimRun(deps: Deps, run: Run): Promise<boolean> {
   const row = (since: string): void => {
     ensureJsonlHeader(p.sessions, "sessions");
     appendJsonl(p.sessions, {
+      host: me.host,
       sessionId: me.sessionId,
       hostSessionId: me.hostSessionId,
       name: me.name,
@@ -78,14 +90,20 @@ export async function claimRun(deps: Deps, run: Run): Promise<boolean> {
   };
   // the trail row goes in under the same lock: the trail's last row is the owner (session-view reads it so)
   return withFileLock(p.stateJson, () => {
+    const live = currentSession(deps);
+    if (!live || sessionKey(live) !== sessionKey(me)) return false;
     const notes = readNotes(run);
     const owner = runOwner(run);
-    if (owner?.sessionId === me.sessionId) {
+    if (owner && sessionKey(owner) === sessionKey(me)) {
       // a crash between the state.json write and the append left the trail without its owner: repaired here
-      if (readSessionRows(run).at(-1)?.sessionId !== me.sessionId) row(owner.since);
+      const last = readSessionRows(run).at(-1);
+      if (!last || sessionKey(last) !== sessionKey(me)) row(owner.since);
       return false;
     }
-    writeJsonAtomic(p.stateJson, { ...notes, owner: { sessionId: me.sessionId, since: at } });
+    writeJsonAtomic(p.stateJson, {
+      ...notes,
+      owner: { ...owner, host: me.host, sessionId: me.sessionId, since: at },
+    });
     row(at);
     return true;
   });

package/src/services/setup.ts

@@ -1,3 +1,6 @@
+import { ADAPTER_IDS } from "../domain/ids.ts";
+import { usedBackends } from "./doctor-backends.ts";
+import type { HostContext } from "../domain/host.ts";
 import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { Issue } from "../domain/profile-rules.ts";
@@ -5,7 +8,14 @@ import { configDir } from "../infra/paths.ts";
 import { type Refreshed, refreshDiscovery } from "./catalog-service.ts";
 import type { Synced } from "./agent-links.ts";
 import { activate, resetProfile, withProfilesLock } from "./profile-service.ts";
-import { configFile, profilesDir, projectsFile } from "./profile-store.ts";
+import {
+  activeName,
+  configFile,
+  getProfile,
+  profilesDir,
+  projectsFile,
+  readProjects,
+} from "./profile-store.ts";
 import { ensurePrivateDir } from "../infra/store.ts";
 
 /** True when profile `name` has a file (`default` exists as a name even before it has one). */
@@ -65,23 +75,34 @@ export interface InitResult {
 /**
  * Spec §8 `catherd init`, the setup half: moves 0.x files aside, writes the default profile (spec §7.2)
  * unless a 1.0 one exists and `overwrite` is not set, makes it active and links its agents, and lists
- * every backend's models. It never throws for a default profile that does not validate here: it writes
- * nothing, returns the errors, and activates the profile only when it has a file.
+ * backend models, skipping unused headless Claude on a Codex host. Defaults that do not validate return
+ * errors without a write; the profile becomes active only when it has a file.
  */
-export async function initSetup(
-  o: { profile?: string; overwrite?: boolean; now?: Date } = {},
-): Promise<InitResult> {
+export async function initSetup(o: {
+  profile?: string;
+  repo?: string | null;
+  overwrite?: boolean;
+  now?: Date;
+  host: HostContext;
+}): Promise<InitResult> {
   const moved = moveLegacy(o.now);
-  const profile = o.profile ?? "default";
+  const profile = o.profile ?? activeName(o.repo);
   let created = false;
   let errors: Issue[] = [];
   if (!hasProfileFile(profile) || o.overwrite === true) {
-    const saved = resetProfile(profile);
+    const saved = resetProfile(profile, o.host.host);
     created = saved.saved;
     errors = saved.errors;
   }
   const active = hasProfileFile(profile);
-  const synced = active ? activate(profile) : null;
-  const refreshed = await refreshDiscovery();
+  const repo =
+    o.profile === undefined && o.repo && readProjects().bindings[o.repo] !== undefined ? o.repo : null;
+  const synced = active ? activate(profile, repo, o.host.host) : null;
+  const used = usedBackends(active ? [getProfile(profile, o.host.host)] : []);
+  const backends =
+    o.host.host === "codex" && !used.has("claude-code")
+      ? ADAPTER_IDS.filter((id) => id !== "claude-code")
+      : undefined;
+  const refreshed = await refreshDiscovery({ backends });
   return { moved, profile, created, errors, active, synced, refreshed };
 }

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.