catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/run-store.ts

@@ -1,19 +1,29 @@
-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 { runSlug } from "../domain/branch.ts";
 import { assertId } from "../domain/ids.ts";
 import { type RunRecord, RunRecordSchema } from "../domain/record.ts";
-import type { OutcomeRow, RouteRow } from "../domain/route.ts";
-import { cell, slug } from "../domain/util.ts";
+import type {
+  FailoverRouteRow,
+  OutcomeRouteRow,
+  OutcomeRow,
+  RoleRouteRow,
+  RouteRow,
+} from "../domain/route.ts";
+import { cell } 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,
+  PRIVATE_FILE,
   appendPrivate,
+  nonBlankLines,
   readJsonl,
   readVersioned,
   writeJsonAtomic,
@@ -38,6 +48,11 @@ 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(),
+  /** plan 35: the branch on origin each milestone's own branch starts from; absent for a run in the repo itself */
+  base: z.string().optional(),
 });
 type RunMeta = z.infer<typeof RunMetaSchema>;
 
@@ -66,6 +81,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"),
   };
@@ -73,7 +90,6 @@ export function runPaths(dir: string) {
 
 export const LEDGER_HEADER = "milestone | what | commit | minutes | evidence";
 
-const runSlug = (title: string) => slug(title).slice(0, 40) || "run";
 const stamp = (d: Date) => d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
 
 /** Creates a run folder under the repo's runs dir. `repo` is a git toplevel; meta.json is written last. */
@@ -83,6 +99,11 @@ 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;
+  /** plan 35: the branch on origin each milestone's branch starts from */
+  base?: string;
   startedBy?: {
     host?: StartedBy["host"];
     sessionId: string;
@@ -90,6 +111,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 +154,9 @@ export function createRun(o: {
     createdAt: now.toISOString(),
     catherdVersion: o.version,
     ...(o.startedBy ? { startedBy: StartedBySchema.parse(o.startedBy) } : {}),
+    ...(workspace ? { workspace } : {}),
+    ...(o.startHead ? { startHead: o.startHead } : {}),
+    ...(o.base ? { base: o.base } : {}),
   };
   writeJsonAtomic(p.meta, meta);
   return { id, dir, meta };
@@ -141,14 +168,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 +251,39 @@ 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 &&
+      (r.source === "route" || r.source === "dispatch") &&
+      typeof r.role === "string" &&
+      typeof r.rung === "string",
+  );
+}
+
+export function appendRoute(
+  run: Run,
+  row: RouteRow | RoleRouteRow | OutcomeRouteRow | FailoverRouteRow,
+): void {
   const file = runPaths(run.dir).routes;
   ensureJsonlHeader(file, "routes");
   appendJsonl(file, row);
@@ -255,13 +312,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 +342,95 @@ 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.
+ * it. `land`'s `learned` and `catherd knowledge add` both come through here; `removeKnowledgeLine` is the other writer.
  */
-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`);
+  const file = await knowledgeFor(toplevel);
+  ensurePrivateDir(dirname(file));
+  await withFileLock(file, () => appendPrivate(file, `${line}\n`));
   return line;
 }
 
+/** Removes the one line of the repo's knowledge.md that contains `match`, and returns it. */
+export async function removeKnowledgeLine(toplevel: string, match: string): Promise<string> {
+  const file = await knowledgeFor(toplevel);
+  const needle = match.trim();
+  ensurePrivateDir(dirname(file));
+  return withFileLock(file, () => {
+    const lines = existsSync(file) ? nonBlankLines(file) : [];
+    const hits = needle ? lines.filter((l) => l.includes(needle)) : [];
+    if (hits.length === 0)
+      throw new CatherdError("E_INPUT_INVALID", `no line of knowledge.md contains "${match}"`, {
+        fix: "catherd knowledge show",
+      });
+    if (hits.length > 1)
+      throw new CatherdError(
+        "E_INPUT_INVALID",
+        `${hits.length} lines contain "${match}": quote more of the one to remove`,
+        {
+          fix: "catherd knowledge show",
+        },
+      );
+    const rest = lines.filter((l) => l !== hits[0]);
+    writeTextAtomic(file, rest.length ? `${rest.join("\n")}\n` : "", { mode: PRIVATE_FILE });
+    return hits[0] as string;
+  });
+}
+
+/** 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/scorecard-metrics.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sessionKey } from "../domain/host.ts";
+import { type Interventions, interventionTotal } from "../domain/scorecard.ts";
+import type { RunEvent } from "../domain/run-events.ts";
+import { coveredMs } from "../domain/util.ts";
+import { landedMilestones } from "./milestones.ts";
+import { pauseSpans } from "./pause.ts";
+import { runMilestones } from "./protocol.ts";
+import { parkedSpans, questionCounts } from "./questions.ts";
+import { replay } from "../domain/run-state.ts";
+import { isDaemonRun, readEvents } from "./run-events-store.ts";
+import { listRuns, readAgentRuns, readRecords, type Run, supersededBy } from "./run-store.ts";
+import { readSessionRows } from "./sessions.ts";
+
+// Plan 28: what a finished run's own files say about how much it needed a person. Read-only.
+
+/**
+ * A daemon run's own events (plan 36, ruling 12): the owner's answers and the questions still open are parks (a
+ * judge's answer is not), every answer is shown, and an owner's cancel or plan approval each count.
+ */
+function eventCounts(run: Run): { parks: number; answers: number; cancels: number; approvals: number } {
+  const events = readEvents(run);
+  const n = (f: (e: RunEvent) => boolean) => events.filter(f).length;
+  // one snapshot: an answer written between two reads would otherwise count nowhere
+  const open = Object.keys(replay(events, run.id).questions).length;
+  return {
+    parks: n((e) => e.type === "question.answered" && e.by === "owner") + open,
+    answers: n((e) => e.type === "question.answered"),
+    cancels: n((e) => e.type === "cancel.requested"),
+    approvals: n((e) => e.type === "plan.approved" && e.by === "owner"),
+  };
+}
+
+/** A 1.5 run keeps its questions in questions.jsonl and has no cancel or plan approval to count. */
+const oldCounts = (run: Run) => {
+  const { questions, answers } = questionCounts(run);
+  return { parks: questions, answers, cancels: 0, approvals: 0 };
+};
+
+/** The interventions a run needed by `end` (epoch ms), counted from its records (plan 28, ruling 4). */
+export function interventionsOf(run: Run, end: number, chat: number): Interventions {
+  const daemon = isDaemonRun(run);
+  const { parks, answers, cancels, approvals } = daemon ? eventCounts(run) : oldCounts(run);
+  const keys = [...(run.meta.startedBy ? [run.meta.startedBy] : []), ...readSessionRows(run)].map(sessionKey);
+  const takeovers = keys.filter((k, i) => i > 0 && k !== keys[i - 1]).length;
+  // a daemon run admits every dispatch without a session
+  const manualDispatches = daemon ? readRecords(run).records.filter((r) => r.sessionId).length : 0;
+  const from = Date.parse(run.meta.createdAt);
+  const pauses = pauseSpans(run).filter((s) => s.from >= from && s.from <= end).length;
+  const superseded = listRuns([run.meta.repo]).runs.filter((r) => supersededBy(r)?.by === run.id).length;
+  const i = { parks, answers, takeovers, manualDispatches, pauses, superseded, chat, cancels, approvals };
+  return { ...i, total: interventionTotal(i) };
+}
+
+/** When the run ended, in epoch ms: its last landing, else its last record or native agent run, else its start. */
+export function runEnd(run: Run): number {
+  const last = landedMilestones(run).at(-1);
+  if (last) {
+    const file = join(run.dir, "digests", `${last}.md`);
+    const at = existsSync(file) ? / · landed (\S+)\s*$/m.exec(readFileSync(file, "utf8"))?.[1] : undefined;
+    const ms = at ? Date.parse(at) : NaN;
+    if (!Number.isNaN(ms)) return ms;
+  }
+  const times = [...readRecords(run).records.map((r) => r.endedAt), ...readAgentRuns(run).map((a) => a.at)]
+    .map((t) => Date.parse(t))
+    .filter((t) => !Number.isNaN(t));
+  return times.length ? Math.max(...times) : Date.parse(run.meta.createdAt);
+}
+
+/** The ms of the run, up to `end`, that it spent parked on the owner or paused; overlaps once. */
+export const pausedMs = (run: Run, end: number): number =>
+  coveredMs(Date.parse(run.meta.createdAt), end, [
+    ...runMilestones(run).flatMap((m) => parkedSpans(run, m)),
+    ...pauseSpans(run),
+  ]);
+
+/** A failover stand-in (failoverFrom set) ended ok and was not blocked or refused. */
+export const failoverRecovered = (run: Run): boolean =>
+  readRecords(run).records.some(
+    (r) =>
+      r.failoverFrom !== null &&
+      r.status === "ok" &&
+      r.replyStatus !== "blocked" &&
+      r.replyStatus !== "refused",
+  );