catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/services/run-service.ts

@@ -4,7 +4,8 @@ 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 { ROLES, type Role } from "../domain/roles.ts";
+import { rulesFor, tagNames } from "../domain/rules.ts";
 import { awaitsCollect, dispatchPaths, endCollect, tryCollect } from "../infra/dispatch-dir.ts";
 import { withFileLock } from "../infra/filelock.ts";
 import { git, gitToplevel } from "../infra/git.ts";
@@ -19,6 +20,7 @@ import {
 } from "./dispatches.ts";
 import type { Deps } from "./ports.ts";
 import { assertNativeHost } from "./backends.ts";
+import { writeRunIndex } from "./catalog-service.ts";
 import {
   type AgentRun,
   appendAgentRun,
@@ -27,6 +29,7 @@ import {
   findRun,
   knowledgeFor,
   readRecords,
+  removeKnowledgeLine,
   runFile,
   type Run,
   runPaths,
@@ -109,7 +112,7 @@ async function supersededHints(run: Run, by: string): Promise<{ hints?: string[]
 
 export async function startRun(
   deps: Deps,
-  i: { repo: string; title: string; aLines: string[]; from?: string },
+  i: { repo: string; title: string; aLines: string[]; from?: string; base?: string },
 ): Promise<{
   run: string;
   dir: string;
@@ -121,6 +124,18 @@ 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",
     });
+  // a run starts only when every enabled role has an indexed rung; the index it checked is the one it pins
+  const start = await deps.routing.checkStart(deps.profiles.forRepo(top), top);
+  if (start.unusable.length > 0) {
+    const roles = start.unusable.join(", ");
+    throw new CatherdError(
+      "E_CONFIG_INVALID",
+      `the ${roles} role${start.unusable.length === 1 ? " has" : "s have"} no usable rung on the Slopalytics index`,
+      {
+        fix: `catherd profile validate, then pick indexed pairs: catherd catalog list --role ${start.unusable[0]}`,
+      },
+    );
+  }
   // 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> => {
@@ -130,11 +145,13 @@ export async function startRun(
       aLines: i.aLines,
       version: deps.version,
       startHead: head.kind === "ok" ? head.out.trim() || null : null,
+      ...(i.base ? { base: i.base } : {}),
       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);
+    writeRunIndex(run.dir, start.index);
     await claimRun(deps, run);
     return run;
   };
@@ -164,8 +181,19 @@ export function writeRunFile(i: { run: string; path: string; content: string }):
 } {
   const run = findRun(i.run);
   const file = runFile(run, i.path, "write");
+  const rel = relative(run.dir, file).split(sep).join("/");
+  // macOS disks ignore case, so Plan-Input/ is the same folder
+  const low = rel.toLowerCase();
+  if (low === "plan-approved.md" || low === "plan-input" || low.startsWith("plan-input/"))
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      `${rel} holds the owner's approved plan; roles never write it`,
+      {
+        fix: "write plan.md or a lane file",
+      },
+    );
   // 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("/"));
+  const lane = /^lanes\/([^/]+)\.md$/.exec(rel);
   if (lane) assertLaneValues(i.content, `lanes/${lane[1]}.md`);
   writeTextAtomic(file, i.content);
   return { path: file, bytes: Buffer.byteLength(i.content) };
@@ -350,12 +378,33 @@ export async function knowledgeLines(repo: string): Promise<{ repo: string; path
 /** The source a line added by hand carries, where a landing puts its run's title and milestone. */
 const BY_HAND = "by hand";
 
-/** Appends one line of the user's own to the repo's knowledge.md, as `land`'s `learned` does; returns it. */
-export async function addKnowledge(repo: string, text: string, now: Date = new Date()): Promise<string> {
+/** The repo's standing rules for `role`: its knowledge.md as `rulesFor` gives it, "" when missing or blank. */
+export async function standingRules(repo: string, role: Role): Promise<string> {
+  const { lines } = await knowledgeLines(repo);
+  return rulesFor(lines.join("\n"), role);
+}
+
+/** Appends one line to the repo's knowledge.md (a hand-written one by default), as `land`'s `learned` does; returns it. */
+export async function addKnowledge(
+  repo: string,
+  text: string,
+  now: Date = new Date(),
+  source = BY_HAND,
+): Promise<string> {
   const top = await repoTop(repo);
   if (!text.trim())
     throw new CatherdError("E_INPUT_INVALID", "the knowledge line is empty", {
       fix: 'pass one line of text, e.g. catherd knowledge add "the targeted test is bun test <file>"',
     });
-  return appendKnowledge(top, now, BY_HAND, text);
+  const bad = (tagNames(text) ?? []).find((n) => !(ROLES as readonly string[]).includes(n));
+  if (bad !== undefined)
+    throw new CatherdError("E_INPUT_INVALID", `"${bad}" is not a role: tag a rule with ${ROLES.join(", ")}`, {
+      fix: 'catherd knowledge add "[worker, reviewer] <rule>"',
+    });
+  return appendKnowledge(top, now, source, text);
+}
+
+/** Removes the one line of the repo's knowledge.md that contains `match`; returns it. */
+export async function removeKnowledge(repo: string, match: string): Promise<string> {
+  return removeKnowledgeLine(await repoTop(repo), match);
 }

package/src/services/run-store.ts

@@ -2,10 +2,17 @@ import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync, renameSync
 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 { OutcomeRouteRow, OutcomeRow, RoleRouteRow, 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 { gitOrigin } from "../infra/git.ts";
 import { dataDir, originDir, repoDir, runsDir } from "../infra/paths.ts";
@@ -14,6 +21,7 @@ import {
   ensureJsonlHeader,
   ensurePrivateDir,
   PRIVATE_DIR,
+  PRIVATE_FILE,
   appendPrivate,
   nonBlankLines,
   readJsonl,
@@ -43,6 +51,8 @@ const RunMetaSchema = z.looseObject({
   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>;
 
@@ -80,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. */
@@ -93,6 +102,8 @@ export function createRun(o: {
   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;
@@ -145,6 +156,7 @@ export function createRun(o: {
     ...(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 };
@@ -260,11 +272,18 @@ export function readOutcomeRoutes(run: Run): OutcomeRouteRow[] {
 /** 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",
+    (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): void {
+export function appendRoute(
+  run: Run,
+  row: RouteRow | RoleRouteRow | OutcomeRouteRow | FailoverRouteRow,
+): void {
   const file = runPaths(run.dir).routes;
   ensureJsonlHeader(file, "routes");
   appendJsonl(file, row);
@@ -350,7 +369,7 @@ export async function knowledgeFor(toplevel: string): Promise<string> {
 
 /**
  * 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 async function appendKnowledge(
   toplevel: string,
@@ -359,10 +378,38 @@ export async function appendKnowledge(
   text: string,
 ): Promise<string> {
   const line = `- ${at.toISOString().slice(0, 10)} ${source}: ${cell(text)}`;
-  appendPrivate(await knowledgeFor(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>;

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