catherd-cli 1.3.0 → 1.5.0

package/src/services/pause.ts

@@ -0,0 +1,161 @@
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import type { Span } from "../domain/util.ts";
+import { dataDir } from "../infra/paths.ts";
+import { appendJsonl, ensureJsonlHeader, readJsonl } from "../infra/store.ts";
+/** What a pause is checked against: a run, or a workspace step about to start one. */
+type Covered = { meta: { workspace?: { id: string; step: string } } };
+import { findWorkspace, workspaceDirectory } from "./workspace-store.ts";
+
+// Spec 1.5 plan 25, "Group pause": one environment blocker (a VPN, Docker down) pauses every run on the
+// machine, or every child of a workspace, at once: admission refuses with the reason until it is resumed.
+
+/** One row per pause or resume, oldest first; `reason` null is a resume. */
+interface PauseRow {
+  at: string;
+  reason: string | null;
+}
+
+/** A pause in force: whose (the machine, or one workspace), why and since when. */
+export interface Pause {
+  scope: "machine" | "workspace";
+  /** the workspace id, for a workspace pause */
+  workspace?: string;
+  reason: string;
+  since: string;
+}
+
+/** A stretch of time something was paused; `to` null while it still is. */
+export interface PauseInterval {
+  from: string;
+  to: string | null;
+}
+
+export const machinePauseFile = (): string => join(dataDir(), "pauses.jsonl");
+export const workspacePauseFile = (id: string): string => join(workspaceDirectory(id), "pauses.jsonl");
+
+const rows = (file: string): PauseRow[] =>
+  readJsonl<PauseRow>(file).rows.filter(
+    (r) => typeof r?.at === "string" && (r.reason === null || typeof r.reason === "string"),
+  );
+
+/** The pause in force in `file`, or null: its last row, when that row pauses. */
+function current(file: string): { reason: string; since: string } | null {
+  const last = rows(file).at(-1);
+  return last && last.reason !== null ? { reason: last.reason, since: last.at } : null;
+}
+
+/** Every paused stretch `file` records, oldest first. */
+export function pauseIntervals(file: string): PauseInterval[] {
+  const out: PauseInterval[] = [];
+  for (const r of rows(file)) {
+    const open = out.at(-1);
+    if (r.reason !== null && (!open || open.to !== null)) out.push({ from: r.at, to: null });
+    else if (r.reason === null && open && open.to === null) open.to = r.at;
+  }
+  return out;
+}
+
+function append(file: string, row: PauseRow): void {
+  ensureJsonlHeader(file, "pauses");
+  appendJsonl(file, row);
+}
+
+const PAUSE_HINT = "push the reason to the owner once (PushNotification); every run it covers waits on it";
+
+/** `catherd pause --machine <reason>`: every dispatch on this machine is refused until resumed. */
+export function pauseMachine(now: number, reason: string): { pause: Pause; hints: string[] } {
+  if (!reason.trim())
+    throw new CatherdError("E_INPUT_INVALID", "a pause needs a reason", {
+      fix: 'catherd pause --machine "the VPN takes the default route"',
+    });
+  const at = new Date(now).toISOString();
+  append(machinePauseFile(), { at, reason });
+  return { pause: { scope: "machine", reason, since: at }, hints: [PAUSE_HINT] };
+}
+
+/** `catherd resume --machine`: lifts the machine pause; the previous one, or null when none was in force. */
+export function resumeMachine(now: number): { resumed: Pause | null } {
+  const was = current(machinePauseFile());
+  if (was) append(machinePauseFile(), { at: new Date(now).toISOString(), reason: null });
+  return { resumed: was ? { scope: "machine", ...was } : null };
+}
+
+/** `workspace_pause(workspace, reason)`: every child of the workspace is refused admission until resumed. */
+export function pauseWorkspace(
+  now: number,
+  i: { workspace: string; reason: string },
+): { pause: Pause; hints: string[] } {
+  const workspace = findWorkspace(i.workspace);
+  if (!i.reason.trim())
+    throw new CatherdError("E_INPUT_INVALID", "a pause needs a reason", {
+      fix: 'workspace_pause(workspace, "the VPN takes the default route")',
+    });
+  const at = new Date(now).toISOString();
+  append(workspacePauseFile(workspace.id), { at, reason: i.reason });
+  return {
+    pause: { scope: "workspace", workspace: workspace.id, reason: i.reason, since: at },
+    hints: [PAUSE_HINT],
+  };
+}
+
+/** `workspace_resume(workspace)`: lifts the workspace's pause; the previous one, or null. */
+export function resumeWorkspace(now: number, i: { workspace: string }): { resumed: Pause | null } {
+  const workspace = findWorkspace(i.workspace);
+  const file = workspacePauseFile(workspace.id);
+  const was = current(file);
+  if (was) append(file, { at: new Date(now).toISOString(), reason: null });
+  return { resumed: was ? { scope: "workspace", workspace: workspace.id, ...was } : null };
+}
+
+/** The pauses in force over `run`: the machine's, then its workspace's. */
+export function pausesFor(run: Covered | null): Pause[] {
+  const out: Pause[] = [];
+  const machine = current(machinePauseFile());
+  if (machine) out.push({ scope: "machine", ...machine });
+  const id = run?.meta.workspace?.id;
+  const ws = id ? current(workspacePauseFile(id)) : null;
+  if (id && ws) out.push({ scope: "workspace", workspace: id, ...ws });
+  return out;
+}
+
+/** Every stretch the machine, or the run's workspace, was paused, in epoch ms: `land` leaves them out. */
+export function pauseSpans(run: Covered): Span[] {
+  const id = run.meta.workspace?.id;
+  const files = [machinePauseFile(), ...(id ? [workspacePauseFile(id)] : [])];
+  return files.flatMap((f) =>
+    pauseIntervals(f).map((p) => ({ from: Date.parse(p.from), to: p.to === null ? null : Date.parse(p.to) })),
+  );
+}
+
+/** The pauses in force over any of `runs`, each once, the machine's first. */
+export function pausesOver(runs: Covered[]): Pause[] {
+  const seen = new Set<string>();
+  const out: Pause[] = [];
+  for (const p of [pausesFor(null), ...runs.map(pausesFor)].flat()) {
+    const key = `${p.scope} ${p.workspace ?? ""}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+const describe = (p: Pause): string =>
+  `${p.scope === "machine" ? "the machine" : `workspace ${p.workspace}`} is paused since ${p.since}: ${p.reason}`;
+
+/** One line per pause, for status and the admission refusal. */
+export const pauseLine = describe;
+
+/** Admission refuses while a pause covers the run, naming its reason and how to lift it. */
+export function assertNotPaused(run: Covered): void {
+  const [p] = pausesFor(run);
+  if (!p) return;
+  throw new CatherdError("E_ADMIT_PAUSED", describe(p), {
+    fix:
+      p.scope === "machine"
+        ? "when the blocker is gone, the owner runs: catherd resume --machine"
+        : `when the blocker is gone, call workspace_resume(${p.workspace})`,
+  });
+}

package/src/services/peek.ts

@@ -1,5 +1,9 @@
+import type { HostContext, HostSessionRef, KnownHost } from "../domain/host.ts";
 import { assertId } from "../domain/ids.ts";
 import { noticeHeader } from "../domain/notice.ts";
+import { knownQueueCapability, type QueueCapability } from "../infra/codex-queue.ts";
+import type { DeliveryState } from "../infra/delivery.ts";
+import { inspectionHost, inspectDelivery, inspectDeliveries, type DeliveryInspection } from "./run-debug.ts";
 import { awaitsCollect } from "../infra/dispatch-dir.ts";
 import { claim } from "./dispatch-service.ts";
 import { type Dispatch, type DispatchState, listDispatches, liveDispatches } from "./dispatches.ts";
@@ -8,7 +12,7 @@ import { finishedNotice } from "./notifier.ts";
 import type { Deps } from "./ports.ts";
 import { type Reentry, reentry } from "./reentry.ts";
 import { findRun, listRuns, readAgentRuns, readRecords, type Run } from "./run-store.ts";
-import { currentSession, runOwner } from "./sessions.ts";
+import { ownsRun, runOwner } from "./sessions.ts";
 import { readNotes } from "./state.ts";
 
 export interface PeekRole {
@@ -28,13 +32,62 @@ export interface PeekRun extends Reentry {
   title: string;
   /** the session that owns the run now, null when none has */
   owner: string | null;
+  ownerHost: KnownHost | null;
   live: PeekRole[];
+  /** Stalled notices are separate from unread finished role results. */
+  delivery: (DeliveryInspection & { name: string; dispatchId: string })[];
   /** each finished record not yet read, as the first line of its message */
-  unread: { name: string; dispatchId: string; header: string }[];
+  unread: {
+    name: string;
+    dispatchId: string;
+    header: string;
+    eventId: string;
+    delivery: Exclude<DeliveryState, "collected">;
+    receipt: { msgId: string; target: HostSessionRef; at: string } | null;
+  }[];
   /** the latest native Claude run recorded with record_agent_run */
   native: { name: string; role: string; rung: string; status: string; at: string } | null;
   /** the run's next step (state.md's last line) */
   next: string;
+  /** plan 22, goal mode: whether anything in this run is the coordinator's to do now, and why (not) */
+  actionable: boolean;
+  reason: string;
+}
+
+/**
+ * Plan 22, goal mode: whether the run holds anything for the coordinator. An unread record is its to read; with
+ * roles live, a protocol step one of them is doing (lanes running, the reviewer or verifier step with that role
+ * live, the plan while an architect or researcher runs) or the owner's question is nobody's to act on, so the
+ * coordinator ends its turn with no tool call and the next catherd message wakes it.
+ */
+export function actionability(
+  live: { name: string; role: string }[],
+  unread: { name: string }[],
+  protocolNext: string,
+): { actionable: boolean; reason: string } {
+  if (unread.length)
+    return {
+      actionable: true,
+      reason: `unread: ${unread.map((u) => `result(run, "${u.name}")`).join(", ")}`,
+    };
+  if (protocolNext.endsWith(" parked: wait for the owner"))
+    return {
+      actionable: false,
+      reason: `${protocolNext.replace(/: wait for the owner$/, "")}: the owner's answer comes first; end the turn with no tool call`,
+    };
+  const running = (role: string) => live.some((l) => l.role === role);
+  const covered =
+    /: lanes running \(/.test(protocolNext) ||
+    (protocolNext.endsWith(": reviewer") && running("reviewer")) ||
+    (protocolNext.endsWith(": verifier") && running("verifier")) ||
+    (protocolNext.startsWith("plan:") && (running("architect") || running("researcher"))) ||
+    (protocolNext.startsWith("finish:") && (running("verifier") || running("writer")));
+  if (live.length && covered)
+    return {
+      actionable: false,
+      reason: `only roles are live (${live.map((l) => l.name).join(", ")}): their results arrive as catherd messages; end the turn with no tool call`,
+    };
+  return { actionable: true, reason: protocolNext };
 }
 
 function peekRun(deps: Deps, run: Run, name: string | undefined): PeekRun {
@@ -43,36 +96,64 @@ function peekRun(deps: Deps, run: Run, name: string | undefined): PeekRun {
   const records = new Map(readRecords(run).records.map((r) => [r.dispatchId, r]));
   const agents = readAgentRuns(run).filter((a) => name === undefined || a.name === name);
   const native = agents.at(-1);
-  const r = reentry(run, now);
+  const notes = readNotes(run);
+  const re = reentry(run, now, notes);
+  const live = liveDispatches(run, now);
+  // the whole run decides it, whatever `name` narrows the view to
+  const act = actionability(
+    live.map((d) => ({ name: d.admit.name, role: d.admit.role })),
+    listDispatches(run).flatMap((d) =>
+      records.has(d.admit.dispatchId) && awaitsCollect(d.dir) ? [{ name: d.admit.name }] : [],
+    ),
+    re.protocol.next,
+  );
   return {
-    questions: r.questions,
+    questions: re.questions,
     run: run.id,
     title: run.meta.title,
     owner: runOwner(run)?.sessionId ?? null,
-    live: liveDispatches(run, now)
+    ownerHost: runOwner(run)?.host ?? null,
+    live: live.filter(mine).map((d) => ({
+      name: d.admit.name,
+      role: d.admit.role,
+      rung: d.admit.rung,
+      state: d.state,
+      secs: Math.max(0, Math.round((now - Date.parse(d.admit.admittedAt)) / 1000)),
+      lastEvent: lastActivity(d),
+    })),
+    delivery: listDispatches(run)
       .filter(mine)
-      .map((d) => ({
-        name: d.admit.name,
-        role: d.admit.role,
-        rung: d.admit.rung,
-        state: d.state,
-        secs: Math.max(0, Math.round((now - Date.parse(d.admit.admittedAt)) / 1000)),
-        lastEvent: lastActivity(d),
-      })),
+      .flatMap((d) =>
+        inspectDeliveries(run, d, false).map((inspection) => ({
+          name: d.admit.name,
+          dispatchId: d.admit.dispatchId,
+          ...inspection,
+        })),
+      ),
     unread: listDispatches(run)
       .filter(mine)
       .flatMap((d) => {
         const r = records.get(d.admit.dispatchId);
-        return r && awaitsCollect(d.dir)
-          ? [{ name: r.name, dispatchId: r.dispatchId, header: noticeHeader(finishedNotice(run, d, r)) }]
-          : [];
+        if (!r || !awaitsCollect(d.dir)) return [];
+        const delivery = inspectDelivery(run, d, true);
+        if (delivery.delivery === "collected") return [];
+        return [
+          {
+            ...delivery,
+            delivery: delivery.delivery,
+            name: r.name,
+            dispatchId: r.dispatchId,
+            header: noticeHeader(finishedNotice(run, d, r)),
+          },
+        ];
       }),
     native: native
       ? { name: native.name, role: native.role, rung: native.rung, status: native.status, at: native.at }
       : null,
-    next: readNotes(run).next,
-    protocol: r.protocol,
-    verifier: r.verifier,
+    next: notes.next,
+    protocol: re.protocol,
+    verifier: re.verifier,
+    ...act,
   };
 }
 
@@ -84,7 +165,15 @@ function peekRun(deps: Deps, run: Run, name: string | undefined): PeekRun {
 export async function peek(
   deps: Deps,
   i: { run?: string; name?: string },
-): Promise<{ runs: PeekRun[]; hints: string[] }> {
+): Promise<{
+  /** plan 22, goal mode: false when no run holds anything for the coordinator; `reason` says why either way */
+  actionable: boolean;
+  reason: string;
+  runs: PeekRun[];
+  hints: string[];
+  host: HostContext;
+  queue: QueueCapability | null;
+}> {
   if (i.name !== undefined) assertId("role name", i.name);
   let runs: Run[];
   if (i.run) {
@@ -94,10 +183,20 @@ export async function peek(
     runs = [run];
   } else {
     const all = listRuns().runs;
-    const me = currentSession(deps);
-    const owned = me ? all.filter((r) => runOwner(r)?.sessionId === me.sessionId) : [];
+    const owned = all.filter((r) => ownsRun(deps, r));
     runs = owned.length ? owned : all.slice(0, 1);
   }
   const hints = runs.length === 0 ? ["no runs yet: run_start(repo, title, a_lines) starts one"] : [];
-  return { runs: runs.map((r) => peekRun(deps, r, i.name)), hints };
+  const views = runs.map((r) => peekRun(deps, r, i.name));
+  const doing = views.filter((v) => v.actionable);
+  const shown = (vs: PeekRun[]) =>
+    vs.map((v) => (views.length > 1 ? `${v.title}: ${v.reason}` : v.reason)).join("; ");
+  return {
+    actionable: views.length === 0 || doing.length > 0,
+    reason: views.length === 0 ? "no runs yet" : shown(doing.length ? doing : views),
+    runs: views,
+    hints,
+    host: inspectionHost(deps.host),
+    queue: deps.host.host === "codex" && !deps.host.conflict ? knownQueueCapability(process.env) : null,
+  };
 }

package/src/services/ports.ts

@@ -1,3 +1,4 @@
+import type { HostContext } from "../domain/host.ts";
 import type { Provenance } from "./provenance.ts";
 import type { Budget } from "../domain/budget.ts";
 import type { SessionEnv } from "../infra/claude-session.ts";
@@ -6,7 +7,8 @@ import type { Verdict } from "../domain/jev.ts";
 import type { Difficulty, Kind } from "../domain/lane.ts";
 import type { Access } from "../domain/record.ts";
 import type { Role } from "../domain/roles.ts";
-import type { Change, ProfilePatch } from "../domain/profile.ts";
+import type { RoleScope } from "../domain/role-scope.ts";
+import type { Change, ProfileDoc, ProfilePatch } from "../domain/profile.ts";
 import type { Issue } from "../domain/profile-rules.ts";
 import type { RouteJev, RouteSource } from "../domain/route.ts";
 import type { SyncReport } from "./source-sync.ts";
@@ -17,7 +19,18 @@ export interface ProfileView {
   objective: "cost" | "speed";
   /** `defaultRung`, when set, is where a lane starts without a kind and difficulty (spec §5.4) */
   roles: Partial<
-    Record<Role, { enabled: boolean; access: Access; rungs: string[]; defaultRung?: string; network?: false }>
+    Record<
+      Role,
+      {
+        enabled: boolean;
+        access: Access;
+        rungs: string[];
+        defaultRung?: string;
+        network?: false;
+        /** plan 23: the role's own timeouts over the profile's */
+        timeouts?: { idleMin?: number; wallMin?: number };
+      }
+    >
   >;
   /** per billing key (spec §7.1); a missing key bills as DEFAULT_BILLING */
   billing: Partial<Record<string, BillingMode>>;
@@ -46,6 +59,9 @@ export interface ProfileSaved {
 }
 
 export interface ProfilePort {
+  withHost?(host: () => HostContext): ProfilePort;
+  budgetFor?(repo: string | null): Budget;
+  raw?(name?: string, repo?: string | null): ProfileDoc;
   /** The profile bound to `repo` (a git toplevel), else the active one; null asks for the active one. */
   forRepo(repo: string | null): ProfileView;
   /** Without a name (get, validate, set): the profile `repo`, a repository's toplevel, runs on. */
@@ -69,6 +85,7 @@ export interface ProfilePort {
 }
 
 export interface RouteRequest {
+  host?: HostContext["host"];
   runDir: string;
   repo: string;
   profile: ProfileView;
@@ -77,6 +94,8 @@ export interface RouteRequest {
   lane: string | null;
   laneText: string | null;
   spentFraction: number;
+  /** spec 1.5 plan 24: the run's dispatches so far per quota, for a tie between rungs of equal scores */
+  usage?: Record<string, number>;
 }
 
 export interface RouteAnswer {
@@ -88,6 +107,14 @@ export interface RouteAnswer {
   /** the Jev question set asked, and its summed probabilities, for outcomes.jsonl (spec §5.6) */
   questionSet: string | null;
   jev: RouteJev | null;
+  /** spec 1.5 plan 24: where Jev disagreed with a declared lane header (`Jev said logic/hard`), else null */
+  jevSaid: string | null;
+  /** spec 1.5 plan 24: no rung clears the lane's bar, and the closest one */
+  noClear?: string;
+  /** spec 1.5 plan 24: rungs of equal scores on other quotas competed for the start, and what decided */
+  tie?: string;
+  /** spec 1.5 plan 24: the decision in one line, for the coordinator */
+  why: string;
   /** spec 1.2 §5.3, §8: the chosen rung's thresholds, values, sources, facts and run evidence */
   provenance?: Provenance;
 }
@@ -106,6 +133,8 @@ export interface CatalogFilter {
 
 export interface RoutingPort {
   route(req: RouteRequest): Promise<RouteAnswer>;
+  /** spec 1.5 plan 24: the lanes of one role in one call; Jev is asked about all of them at once */
+  routeMany(reqs: RouteRequest[]): Promise<RouteAnswer[]>;
   /** `use` is the repo profile's `jev.use`: "off" answers with the rule's default and never asks Jev */
   finding(
     runDir: string,
@@ -128,14 +157,20 @@ export interface RoutingPort {
 
 /** Everything a service needs from outside it; the entry layer builds one, tests build fakes. */
 export interface Deps {
+  host: HostContext;
   profiles: ProfilePort;
   routing: RoutingPort;
   version: string;
   /** how often the supervisor and the dispatch watchers poll, in ms */
   pollMs: number;
-  /** the Claude Code session this process serves (spec §3.3), from its environment; null outside one */
+  /** Claude transport credentials and registry refresh; host identity lives in `host`. */
   session: SessionEnv | null;
   now: () => number;
   /** spec 1.2 §3.2 `catalog_sync`; default: the real sync (tests inject one that never reaches the network) */
-  sync?: (o: { force: boolean }) => Promise<SyncReport>;
+  sync?: (o: { force: boolean; wait?: boolean }) => Promise<SyncReport>;
+  /**
+   * Spec 1.5 plan 21: the role this process works for (CATHERD_ROLE, or a role's scratch TMPDIR); null or
+   * absent for the orchestrator's own server. A role never claims a run and never reaches a coordinator tool.
+   */
+  role?: RoleScope | null;
 }