catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/adapters/opencode/index.ts

@@ -155,6 +155,20 @@ function finalize(run: FinishedRun): Outcome {
   const f = foldOpencodeEvents(run.eventLines);
   const stopped = run.exit.reason;
   const tooOld = f.tooOld || OPENCODE_TOO_OLD.some((r) => r.test(run.stderr));
+  // plan 23: the provider kept failing; failover takes it as a usage limit, onto the next backend
+  if (stopped === "provider-unavailable")
+    return {
+      status: "limit",
+      thread: f.thread ?? run.request.thread,
+      tokens: f.tokens,
+      costUsd: f.costUsd,
+      images: [],
+      error: {
+        code: "provider-unavailable",
+        message: f.error?.message ?? "the provider retried with no progress",
+      },
+      reply: f.reply,
+    };
   const status: RunStatus =
     stopped === "cancelled"
       ? "cancelled"
@@ -201,6 +215,8 @@ function parse(line: string): EventDelta {
   const activity = opencodeActivity(e);
   if (activity) d.activity = activity;
   if (typeof e.sessionID === "string") d.thread = e.sessionID;
+  // plan 23: each provider retry starts a step again with nothing between; the supervisor counts them
+  if (e.type === "step_start") d.step = true;
   if (e.type === "step_finish") {
     d.tokens = opencodeTokens(e.part?.tokens);
     d.requestInput = d.tokens.input;
@@ -220,6 +236,21 @@ function parse(line: string): EventDelta {
  * older messages keep their errors, so only the newest assistant message counts, and with `sinceMs` only
  * if this run wrote it.
  */
+/**
+ * Plan 23: the provider retry the newest assistant message this run wrote is waiting out (a 503, an
+ * overloaded backend), by its attempt number; null when it is not retrying.
+ */
+function providerRetryOf(messages: unknown, sinceMs: number): number | null {
+  if (!Array.isArray(messages)) return null;
+  const m = messages.find((x) => x?.type === "assistant") as Record<string, any> | undefined;
+  if (!m?.retry || !(m.time?.created >= sinceMs)) return null;
+  return typeof m.retry.attempt === "number" ? m.retry.attempt : 1;
+}
+
+async function providerRetry(thread: string, sinceMs: number): Promise<number | null> {
+  return providerRetryOf((await opencodeApi("GET", `/api/session/${thread}/message`))?.data, sinceMs);
+}
+
 function limitRetry(messages: unknown, sinceMs?: number): string | null {
   if (!Array.isArray(messages)) return null;
   const m = messages.find((x) => x?.type === "assistant") as Record<string, any> | undefined;
@@ -265,7 +296,12 @@ async function isBusy(thread: string, sinceMs?: number): Promise<boolean> {
   const active = (await opencodeApi("GET", "/api/session/active"))?.data;
   if (!active || typeof active !== "object" || !(thread in active)) return false;
   const messages = (await opencodeApi("GET", `/api/session/${thread}/message`))?.data;
-  return Array.isArray(messages) && limitRetry(messages, sinceMs) === null;
+  // plan 23: a session only retrying its provider is not busy, so the idle timeout still runs
+  return (
+    Array.isArray(messages) &&
+    limitRetry(messages, sinceMs) === null &&
+    providerRetryOf(messages, sinceMs ?? 0) === null
+  );
 }
 
 /** Killing the v2 client does not stop its session; the service must be told (research §2.4). */
@@ -327,6 +363,7 @@ export const opencodeAdapter: BackendAdapter = {
   resume: { supported: true, sameAccessOnly: false, threadPattern: THREAD },
   interrupt: (thread) => interrupt(thread),
   isBusy: (thread, _cwd, sinceMs) => isBusy(thread, sinceMs),
+  providerRetry: (thread, _cwd, sinceMs) => providerRetry(thread, sinceMs),
   failoverFor,
   graceAfterFinalMs: null,
   reportsCost: true,

package/src/cli.ts

@@ -20,29 +20,23 @@ const { VERSION } = await import("./infra/version.ts");
 
 type Command = ReturnType<typeof defineCommand>;
 
-/** The dashboard's flags, typed as any command's args so `main` stays a plain `Command`. */
-const dashboardArgs: ArgsDef = {
-  ...HOST_ARG,
-  plain: {
-    type: "boolean",
-    description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
-  },
-  "reduced-motion": { type: "boolean", description: "the dashboard without animation" },
-};
+/** HOST_ARG typed as any command's args, so `main` stays a plain `Command`. */
+const MAIN_ARGS: ArgsDef = HOST_ARG;
 
 /**
- * Spec §8. Every subcommand loads lazily, so `mcp`, `lock` and `_supervise` never load OpenTUI or React
- * (spec §3.1); a bare `catherd` opens the TUI.
+ * Spec §8. Every subcommand loads lazily, so `mcp`, `lock` and `_supervise` never load the panel (spec §3.1);
+ * a bare `catherd` runs `catherd panel`.
  */
 export const main: Command = defineCommand({
   meta: {
     name: "catherd",
     version: VERSION,
-    description: "Herds coding agents",
+    description: "Herds coding agents. catherd (or catherd panel) opens the panel in your browser.",
   },
-  args: dashboardArgs,
+  args: MAIN_ARGS,
   subCommands: {
     init: () => import("./entry/init-command.ts").then((m) => m.initCommand),
+    panel: () => import("./entry/panel-command.ts").then((m) => m.panelCommand),
     status: () => import("./entry/runs-command.ts").then((m) => m.statusCommand),
     watch: () => import("./entry/runs-command.ts").then((m) => m.watchCommand),
     runs: () => import("./entry/runs-command.ts").then((m) => m.runsCommand),
@@ -50,17 +44,19 @@ export const main: Command = defineCommand({
     doctor: () => import("./entry/doctor-command.ts").then((m) => m.doctorCommand),
     catalog: () => import("./entry/catalog-command.ts").then((m) => m.catalogCommand),
     knowledge: () => import("./entry/knowledge-command.ts").then((m) => m.knowledgeCommand),
+    workspace: () => import("./entry/workspace-command.ts").then((m) => m.workspaceCommand),
     lock: () => import("./entry/lock-command.ts").then((m) => m.lockCommand),
+    "run-file": () => import("./entry/role-cli-command.ts").then((m) => m.runFileCommand),
+    gate: () => import("./entry/role-cli-command.ts").then((m) => m.gateCommand),
+    answer: () => import("./entry/answer-command.ts").then((m) => m.answerCommand),
+    pause: () => import("./entry/pause-command.ts").then((m) => m.pauseCommand),
+    resume: () => import("./entry/pause-command.ts").then((m) => m.resumeCommand),
     "capture-fixtures": () =>
       import("./entry/capture-fixtures-command.ts").then((m) => m.captureFixturesCommand),
+    scorecard: () => import("./entry/scorecard-command.ts").then((m) => m.scorecardCommand),
     mcp: () => import("./entry/mcp/command.ts").then((m) => m.mcpCommand),
     _supervise: () => import("./entry/supervise-command.ts").then((m) => m.superviseCommand),
   },
-  // citty runs this after any subcommand too; only a bare `catherd` loads and opens the dashboard
-  async run(ctx) {
-    if (ctx.args._.length > 0) return;
-    await (await import("./entry/tui/run.tsx")).tuiRun(ctx);
-  },
 });
 
 const resolve = async <T>(v: T | Promise<T> | (() => T | Promise<T>)): Promise<T> =>
@@ -136,13 +132,10 @@ export async function runCli(argv: string[]): Promise<number> {
     return EXIT.ok;
   }
   try {
-    const command = parseArgs(own, dashboardArgs)._[0];
-    // a bare `catherd` opens the dashboard, which takes only its own flags: a typo is not a terminal problem
+    const command = parseArgs(own, HOST_ARG)._[0];
+    // a bare `catherd` takes only --host: a typo is a usage error
     const flag = (a: string) => (a.startsWith("--") ? (a.slice(2).split("=")[0] ?? "") : "");
-    // citty negates a boolean as `--no-<name>`
-    const known = (name: string) =>
-      Object.hasOwn(dashboardArgs, name) ||
-      (name.startsWith("no-") && dashboardArgs[name.slice(3)]?.type === "boolean");
+    const known = (name: string) => Object.hasOwn(HOST_ARG, name);
     const unknown =
       command === undefined
         ? own.find((a, i) => a.startsWith("-") && !known(flag(a)) && own[i - 1] !== "--host")
@@ -152,9 +145,11 @@ export async function runCli(argv: string[]): Promise<number> {
       return EXIT.usage;
     }
     // `lock` forwards signals to its command itself; everything else stops at once on Ctrl-C. The command is
-    // the first word that is not a flag: `catherd --plain lock -- …` is `lock` too.
-    if (command !== "lock") process.once("SIGINT", () => process.exit(EXIT.interrupted));
-    const parsed = parseArgs(own, dashboardArgs);
+    // the first word that is not a flag: `catherd --host codex lock -- …` is `lock` too.
+    // the panel stops itself on Ctrl-C
+    if (command !== "lock" && command !== undefined)
+      process.once("SIGINT", () => process.exit(EXIT.interrupted));
+    const parsed = parseArgs(own, HOST_ARG);
     if (parsed.host !== undefined) {
       const forwarded = own.filter(
         (a, i) => a !== "--host" && own[i - 1] !== "--host" && !a.startsWith("--host="),
@@ -168,6 +163,11 @@ export async function runCli(argv: string[]): Promise<number> {
         ...(dashdash < 0 ? [] : argv.slice(dashdash)),
       );
     }
+    if (command === undefined) {
+      const { runPanel } = await import("./entry/panel-command.ts");
+      await runPanel({ port: 4317, open: true, host: parsed.host });
+      return EXIT.ok;
+    }
     await runCommand(main, { rawArgs });
     return Number(process.exitCode ?? EXIT.ok);
   } catch (e) {

package/src/domain/agents.ts

@@ -1,7 +1,7 @@
 import { parseRung, tryParseRung } from "./ids.ts";
 import { agentName, type Profile } from "./profile.ts";
 import type { Access } from "./record.ts";
-import { nativeDisallowedTools, rolePrompt } from "./role-prompts.ts";
+import { NOT_THE_ORCHESTRATOR, nativeDisallowedTools, rolePrompt } from "./role-prompts.ts";
 import { ROLES, type Role } from "./roles.ts";
 
 export interface AgentFile {
@@ -32,6 +32,8 @@ export function renderAgent(o: {
     "",
     rolePrompt(o.role, o.version),
     "",
+    NOT_THE_ORCHESTRATOR,
+    "",
   ].join("\n");
 }
 

package/src/domain/bars.ts

@@ -1,36 +1,33 @@
-import { type Dim, DIMS, type Score } from "./catalog.ts";
-import { DIFFICULTIES, type Difficulty, KINDS, type Kind } from "./lane.ts";
-
-/**
- * Spec 1.2 §5.1: the dimensions each kind's default bars span, for Track A (`copy`, `build`) and Track B
- * (`logic`, `hard`). `steer` has no default bar: it is shown, and a user may set one.
- */
-export const DEFAULT_BAR_DIMS: Record<Kind, { A: Dim[]; B: Dim[] }> = {
-  repo_code: { A: ["repo_code"], B: ["repo_code", "honesty", "agentic"] },
-  terminal: { A: ["terminal"], B: ["terminal", "honesty", "agentic"] },
-  ui: { A: ["frontend", "repo_code"], B: ["frontend", "repo_code", "honesty", "agentic"] },
-  prose: { A: ["repo_code"], B: ["repo_code", "honesty"] },
-  research: { A: ["repo_code"], B: ["repo_code", "honesty"] },
-};
-
-/** The dimensions a difficulty's default bar spans for a kind. */
-export const barDimsOf = (kind: Kind, d: Difficulty): Dim[] =>
-  d === "copy" || d === "build" ? DEFAULT_BAR_DIMS[kind].A : DEFAULT_BAR_DIMS[kind].B;
-
-/** Every dimension some default bar uses: the values an enabled rung needs (spec 1.2 §6.1). */
-export const BAR_DIMS: Dim[] = DIMS.filter((d) =>
-  KINDS.some((k) => DIFFICULTIES.some((x) => barDimsOf(k, x).includes(d))),
-);
-
-/** Spec 1.2 §5.2: the percentile of the scored rungs each difficulty's threshold sits at. */
-export const BAR_PERCENTILE: Record<Difficulty, number> = { copy: 25, build: 50, logic: 60, hard: 75 };
-
-const PERCENTILE_WORD: Record<Difficulty, string> = {
-  copy: "the 25th percentile",
-  build: "the median",
-  logic: "the 60th percentile",
-  hard: "the 75th percentile",
-};
+import { z } from "zod";
+import type { Catalog } from "./catalog.ts";
+import { DIFFICULTIES, type Difficulty } from "./lane.ts";
+
+/** The percentile of the shipped models' intelligences each difficulty's bar sits at. */
+export const BAR_PERCENTILE: Record<Difficulty, number> = { copy: 20, build: 45, logic: 60, hard: 65 };
+
+/** A profile's or a role's own percentiles (0 to 100), one difficulty at a time; a difficulty left out keeps its shipped percentile. */
+export const BarsSchema = z.partialRecord(z.enum(DIFFICULTIES), z.number().min(0).max(100));
+export type Bars = z.infer<typeof BarsSchema>;
+
+/** The percentiles in force as stored: the shipped ones, with `p.bars` laid over them; they may decrease. */
+export const effectiveBars = (p: { bars?: Bars }): Record<Difficulty, number> => ({
+  ...BAR_PERCENTILE,
+  ...p.bars,
+});
+
+/** Each pair `[easier, harder]` of neighbouring difficulties whose percentile goes down. */
+export const barInversions = (at: Record<Difficulty, number>): [Difficulty, Difficulty][] =>
+  DIFFICULTIES.slice(1).flatMap((d, i): [Difficulty, Difficulty][] =>
+    at[d] < at[DIFFICULTIES[i] as Difficulty] ? [[DIFFICULTIES[i] as Difficulty, d]] : [],
+  );
+
+/** The percentiles a route reads: the effective ones made non-decreasing, so a harder lane never routes weaker. */
+export function percentilesOf(p: { bars?: Bars }): Record<Difficulty, number> {
+  const at = effectiveBars(p);
+  let floor = 0;
+  for (const d of DIFFICULTIES) at[d] = floor = Math.max(at[d], floor);
+  return at;
+}
 
 /** The `p`th percentile of `xs`, interpolated linearly between the closest ranks; NaN for none. */
 export function percentile(xs: readonly number[], p: number): number {
@@ -42,78 +39,7 @@ export function percentile(xs: readonly number[], p: number): number {
   return (s[lo] as number) + ((s[hi] as number) - (s[lo] as number)) * (pos - lo);
 }
 
-/**
- * Spec 1.2 §5.2 "measured or better": a value published for this exact rung in the anchor's unit. That is a
- * `verified` or `measured` value, and a hand-typed `secondary` one (no `source`: the 1.0 word for a value
- * published by someone other than the vendor, which is 1.2's `measured`). Plan 14 Ruling 1.
- */
-export const measuredOrBetter = (s: Score): boolean =>
-  s.confidence === "verified" ||
-  s.confidence === "measured" ||
-  (s.confidence === "secondary" && s.source === undefined);
-
-/** Each dimension's values that bars are derived from: one per canonical rung, measured or better. */
-export function barPool(scores: readonly Score[]): Record<Dim, number[]> {
-  const out = Object.fromEntries(DIMS.map((d) => [d, [] as number[]])) as Record<Dim, number[]>;
-  const seen = new Set<string>();
-  for (const s of scores) {
-    const key = `${s.rung} ${s.dim}`;
-    if (!measuredOrBetter(s) || seen.has(key)) continue;
-    seen.add(key);
-    out[s.dim].push(s.value);
-  }
-  return out;
-}
-
-/** A bar value, kept to four significant digits (DeepSWE 60.95, an Arena rating 1668, agentic 0.08622). */
-const tidy = (v: number): number => Number(v.toPrecision(4));
-
-export type Bars = Record<Kind, Record<Difficulty, Partial<Record<Dim, number>>>>;
-/** `scores.json` `barsWhy`: per dimension and difficulty, where its threshold came from. */
-export type BarsWhy = Partial<Record<Dim, Partial<Record<Difficulty, string>>>>;
-
-/**
- * Spec 1.2 §5.1–§5.2: the default bars. Each dimension's threshold at a difficulty is that difficulty's
- * percentile of the pool (`barPool`), the same in every kind whose bar spans the dimension. A dimension with
- * no pooled value gets no threshold (and a `barsWhy` line saying so). `benchmark` names each dimension's unit
- * and `date` the day the data was read.
- */
-export function deriveBars(
-  pool: Record<Dim, number[]>,
-  benchmark: (d: Dim) => string,
-  date: string,
-): { bars: Bars; barsWhy: BarsWhy } {
-  const value: Partial<Record<Dim, Partial<Record<Difficulty, number>>>> = {};
-  const barsWhy: BarsWhy = {};
-  for (const dim of BAR_DIMS)
-    for (const d of DIFFICULTIES) {
-      if (!KINDS.some((k) => barDimsOf(k, d).includes(dim))) continue;
-      const xs = pool[dim];
-      const why = (barsWhy[dim] ??= {});
-      if (xs.length === 0) {
-        why[d] = `no rung is measured or better on ${benchmark(dim)} (${date}): no threshold`;
-        continue;
-      }
-      const v = tidy(percentile(xs, BAR_PERCENTILE[d]));
-      (value[dim] ??= {})[d] = v;
-      why[d] =
-        `${PERCENTILE_WORD[d]} of ${xs.length} rungs measured or better on ${benchmark(dim)} (${date}): ${v}`;
-    }
-  const bars = Object.fromEntries(
-    KINDS.map((k) => [
-      k,
-      Object.fromEntries(
-        DIFFICULTIES.map((d) => [
-          d,
-          Object.fromEntries(
-            barDimsOf(k, d).flatMap((dim) => {
-              const v = value[dim]?.[d];
-              return v === undefined ? [] : [[dim, v]];
-            }),
-          ),
-        ]),
-      ),
-    ]),
-  ) as Bars;
-  return { bars, barsWhy };
+/** A difficulty's bar: an intelligence percentile of the catalog's pool, 0 when there is no index. */
+export function barOf(c: Catalog, d: Difficulty, at: Record<Difficulty, number> = BAR_PERCENTILE): number {
+  return c.pool.length === 0 ? 0 : percentile(c.pool, at[d]);
 }

package/src/domain/blocked.ts

@@ -0,0 +1,72 @@
+/** Why a role stopped without finishing (spec 2.0 decision 3); the machine maps each to a transition. */
+export const BLOCKED_REASONS = [
+  "needs_user",
+  "too_hard",
+  "provider_error",
+  "no_access",
+  "check_broken",
+  "out_of_scope",
+] as const;
+export type BlockedReason = (typeof BLOCKED_REASONS)[number];
+
+export type StopAction = "climb" | "failover" | "park" | "wait";
+
+/** What the machine does with each reason (spec 2.0 decision 8): climb, retry then fail over, park, or wait. */
+export const REASON_ACTION: Readonly<Record<BlockedReason, StopAction>> = {
+  needs_user: "park",
+  too_hard: "climb",
+  provider_error: "failover",
+  no_access: "park",
+  check_broken: "wait",
+  out_of_scope: "park",
+};
+
+const REASON_AT_START = /^[`*\s]*([a-z][a-z_-]*)[`*]*\s*(?:[:—–-]\s*)?([\s\S]*)$/i;
+
+/** The reason a `STATUS: blocked — <reason>: <why>` line names, and its why; null when it names none. */
+export function parseBlockedReason(why: string | null): { reason: BlockedReason; why: string } | null {
+  const m = why === null ? null : REASON_AT_START.exec(why.trim());
+  if (!m) return null;
+  const word = (m[1] as string).toLowerCase().replace(/-/g, "_");
+  const reason = BLOCKED_REASONS.find((r) => r === word);
+  return reason ? { reason, why: (m[2] ?? "").trim() } : null;
+}
+
+/** The reply contract's blocked line, ported from t3herd `prompts/_no_questions.md`. */
+export const BLOCKED_LINE = `Nobody reads your thread until you finish: never ask a question and never wait for an answer. When you cannot finish, leave the finished work in place, say what is left, and end with STATUS: blocked — <reason>: <why>, where <reason> is one of: ${[
+  "needs_user (only the user can decide; <why> is the question)",
+  "too_hard (you tried and cannot solve it; a stronger model should)",
+  "provider_error (your model, tools or sandbox failed)",
+  "no_access (you cannot reach what you need: the running app, a service, credentials)",
+  "check_broken (the check cannot pass for a reason outside your task; name each failing file:line)",
+  "out_of_scope (the task needs changes outside the files you own)",
+].join(", ")}.`;
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+
+/** An `Owns:` entry as a path: cut at the first glob, trailing slashes dropped. */
+const pathOf = (entry: string): string => entry.replace(/[*?[{].*$/, "").replace(/\/+$/, "");
+
+/**
+ * The sibling `Owns:` entries a failed check blames, or [] when it blames none, or also blames one of the lane's
+ * own. Output names a file by its tail (`pkg/x.go:3`, `src/a.tsx(4,2)`), so a sibling's entry counts from two
+ * path segments, and an own entry already from its base name (t3herd `foreignFailure`).
+ */
+export function foreignFailure(log: string, own: string[], siblings: string[]): string[] {
+  const lines = log
+    .replace(ANSI, "")
+    .split("\n")
+    .filter((l) => !/^\s*(✓|ok\s|PASS\b)/.test(l));
+  const named = (p: string, min: number): boolean => {
+    const parts = p.split("/");
+    for (let i = 0; i <= parts.length - min; i++) {
+      const tail = parts.slice(i).join("/");
+      if (lines.some((l) => l.includes(tail))) return true;
+    }
+    return false;
+  };
+  const mine = own.map(pathOf).filter(Boolean);
+  if (mine.some((f) => named(f, 1))) return [];
+  const theirs = siblings.map(pathOf).filter((f) => f && !mine.includes(f));
+  return [...new Set(theirs.filter((f) => named(f, Math.min(2, f.split("/").length))))];
+}

package/src/domain/branch.ts

@@ -0,0 +1,51 @@
+import { headerLine } from "./lane.ts";
+import { slug } from "./util.ts";
+import { BaseRefSchema } from "./workspace.ts";
+
+/** The run title as a folder and branch stem: at most 40 characters, `run` when nothing is left. */
+export const runSlug = (title: string): string => slug(title).slice(0, 40) || "run";
+
+/** A milestone's branch: the run's slug and the milestone, lower case (`wallet-split-m1`). */
+export const milestoneBranch = (title: string, m: string): string => `${runSlug(title)}-${m.toLowerCase()}`;
+
+/** A branch on origin as `run_start`'s base: a plain name, never a remote ref (`origin/…`) or a full ref. */
+export const BaseBranchSchema = BaseRefSchema.refine(
+  (s) => !s.startsWith("origin/") && !s.startsWith("refs/"),
+);
+
+/**
+ * The `Setup:` command in the lines right under plan.md's `# ` title, up to the first blank line or heading
+ * (backticks stripped); null without one. A blank line after the title ends the header, so body prose never counts.
+ */
+export function planSetup(planText: string): string | null {
+  const lines = planText.split("\n");
+  const start = lines.findIndex((l) => /^#\s+/.test(l)) + 1;
+  let end = start;
+  while (end < lines.length && (lines[end] ?? "").trim() !== "" && !(lines[end] ?? "").startsWith("#")) end++;
+  const re = headerLine("setup");
+  for (const line of lines.slice(start, end)) {
+    const m = re.exec(line);
+    if (m)
+      return (
+        (m[1] ?? "")
+          .trim()
+          .replace(/^`+|`+$/g, "")
+          .trim() || null
+      );
+  }
+  return null;
+}
+
+/** Whether the owner's answer to a landed milestone's question is the word that has catherd push its branch. */
+export const isPushAnswer = (answer: string): boolean => answer.trim().toLowerCase() === "push";
+
+/** The command that opens a milestone's MR, for the origin's host: gh on github.com, else glab. */
+export function mrCommand(o: { originUrl: string; base: string; branch: string; body: string }): string {
+  return /(^|[@/.])github\.com[:/]/.test(o.originUrl)
+    ? `gh pr create --base ${o.base} --head ${o.branch} --body-file ${o.body}`
+    : `glab mr create --source-branch ${o.branch} --target-branch ${o.base} --description-file ${o.body}`;
+}
+
+/** The milestone a unit (`run`, `M1`, `M1.L2`) belongs to; null for the run itself. */
+export const unitMilestone = (unit: string): string | null =>
+  unit === "run" ? null : (unit.split(".")[0] ?? null);

package/src/domain/brief.ts

@@ -0,0 +1,106 @@
+import { replyContract, roleSections } from "./role-prompts.ts";
+import { ROLE_MCP_SERVER, roleMcpTools } from "./role-tools.ts";
+import type { Role } from "./roles.ts";
+
+/** What admission adds to a role's brief, besides its reply contract (spec 1.5 plan 21). */
+export interface BriefContext {
+  run: string;
+  name: string;
+  role: Role;
+  /** the lane file as it stands at admission, header and body */
+  lane: { id: string; text: string } | null;
+  /** the role's scratch folder, its TMPDIR, on a backend that grants it */
+  scratch: string | null;
+  /** whether the role's harness lists the catherd_role tools */
+  roleServer: boolean;
+  /** the catherd version whose `lock` a worker's text names */
+  version: string;
+  /** the plan's preamble, which applies to every task (plan 32); null when the run has none for this role */
+  context: string | null;
+}
+
+/** The CLI form of each role server tool, which any role can run from its shell. */
+function cliForm(tool: string, run: string): string {
+  switch (tool) {
+    case "read_run_file":
+      return `catherd run-file read ${run} <path>`;
+    case "write_run_file":
+      return `catherd run-file write ${run} <path> (the content on stdin)`;
+    case "read_knowledge":
+      return "catherd knowledge show";
+    case "gate_check":
+      return `catherd gate check ${run} --milestone <M> --item <item> --command <command> --paths <path,…>`;
+    case "gate_pass":
+      return `catherd gate pass ${run} --item <item> --command <command> --paths <path,…> --evidence <evidence>`;
+    case "gate_run":
+      return `catherd gate run ${run} --milestone <M> --command <command> [--at <base checkout>]`;
+    default:
+      return tool;
+  }
+}
+
+const LANE_OPEN = (id: string) => `<lane-file path="lanes/${id}.md">`;
+const LANE_CLOSE = "</lane-file>";
+
+/**
+ * The lane file inlined (spec 1.5 plan 21): an isolated headless worker cannot read the run folder, so its Owns,
+ * fast check and body travel in the brief itself.
+ */
+export function laneBlock(id: string, text: string): string {
+  return [
+    `Your lane file, lanes/${id}.md, as it stood when you were dispatched:`,
+    LANE_OPEN(id),
+    text.trimEnd(),
+    LANE_CLOSE,
+  ].join("\n");
+}
+
+/** Who the role is, where its temp files go, and how it reaches its run's files and gate. */
+export function roleNotes(c: BriefContext): string {
+  const tools = roleMcpTools(c.role);
+  const lines = [`catherd: you are ${c.name} of run ${c.run}.`];
+  if (c.scratch)
+    lines.push(
+      `Your scratch folder is ${c.scratch}, which is your $TMPDIR: put temporary files, logs and builds there, never in /tmp. catherd removes it with the run, so anything the orchestrator must keep goes in your reply.`,
+    );
+  const cli = tools.map((t) => cliForm(t, c.run)).join("; ");
+  lines.push(
+    c.roleServer
+      ? `Your catherd tools: ${tools.map((t) => `mcp__${ROLE_MCP_SERVER}__${t}`).join(", ")}. If they are not listed, run the same from your shell: ${cli}.`
+      : `Your catherd commands, from your shell: ${cli}.`,
+  );
+  return lines.join("\n");
+}
+
+const TASK_OPEN = "<task>\n";
+const TASK_CLOSE = "\n</task>";
+
+/**
+ * The brief admission writes: the role's sections around its task (the daemon's text, the lane file and the
+ * role's notes), each once. A failover stand-in that reruns an earlier brief gets the lane file as it stands now and
+ * its own notes, never two copies.
+ */
+export function composeBrief(brief: string, c: BriefContext): string {
+  const contract = replyContract(c.role);
+  let body = brief.trimEnd();
+  const open = body.indexOf(TASK_OPEN);
+  const close = body.lastIndexOf(TASK_CLOSE);
+  if (open >= 0 && close > open) body = body.slice(open + TASK_OPEN.length, close).trim();
+  // a 1.5-era brief rerun ends with its contract
+  if (body.endsWith(contract)) body = body.slice(0, -contract.length).trimEnd();
+  if (c.lane) {
+    const open = LANE_OPEN(c.lane.id);
+    const start = body.lastIndexOf(open);
+    const end = body.indexOf(LANE_CLOSE, start);
+    if (start >= 0 && end >= 0) {
+      const lead = body.lastIndexOf("\n\n", start);
+      body = `${body.slice(0, lead >= 0 ? lead : start)}${body.slice(end + LANE_CLOSE.length)}`.trimEnd();
+    }
+  }
+  const notesStart = body.lastIndexOf("\n\ncatherd: you are ");
+  if (notesStart >= 0) body = body.slice(0, notesStart).trimEnd();
+  const task = [body, ...(c.lane ? [laneBlock(c.lane.id, c.lane.text)] : []), roleNotes(c)]
+    .filter(Boolean)
+    .join("\n\n");
+  return `${roleSections(c.role, c.version, { context: c.context, task })}\n`;
+}