catherd-cli 1.3.0 → 1.5.0

package/src/entry/tui/state.ts

@@ -1,3 +1,4 @@
+import type { OrchestrationHost } from "../../domain/host.ts";
 import {
   applyPatch,
   diffProfiles,
@@ -21,6 +22,7 @@ interface Snapshot {
 
 /** Spec §9.2: edits are staged per profile and touch nothing on disk until a save. */
 export interface Draft extends Snapshot {
+  host: OrchestrationHost;
   name: string;
   /** the document as it was read, which a save diffs against */
   base: ProfileDoc;
@@ -118,18 +120,28 @@ export const ARM_MS: Record<Armed["what"], number> = { interrupt: 1_500, delete:
 export const HISTORY_LIMIT = 100;
 
 export interface AppState {
+  host: OrchestrationHost;
   tab: Tab;
   /** the profile the Profiles tab shows; null until one is read */
   profile: string | null;
   drafts: Record<string, Draft>;
   /** the open dialogs; only the top one is drawn and takes keys */
   dialogs: Dialog[];
-  /** spec §4: the session the Runs tab has open (`key` null: "earlier runs"); null shows the sessions */
-  session: { key: string | null } | null;
+  /**
+   * spec §4: the session the Runs tab has open (`key` null: "earlier runs"); null shows the sessions. `run`: the
+   * run it was opened for (a recent run on the Status tab), whose first row the cursor starts on
+   */
+  session: { key: string | null; run?: string } | null;
   /** the role the open session shows, by its dispatch */
   role: { run: string; dispatchId: string } | null;
   /** spec 1.1 §10: the milestone the open session shows, its digest */
   milestone: { run: string; name: string } | null;
+  /** where esc lands: the last session opened, and the last role or milestone opened in it */
+  back: {
+    session: string | null;
+    role: { run: string; dispatchId: string } | null;
+    milestone: { run: string; name: string } | null;
+  } | null;
   paused: boolean;
   armed: Armed | null;
 }
@@ -153,8 +165,8 @@ export type Action =
   | { type: "saving"; name: string; on: boolean }
   | { type: "input"; value: string }
   | { type: "invalid"; error: string | null }
-  /** opens a session of the Runs tab (`key` null: "earlier runs") */
-  | { type: "session"; key: string | null }
+  /** opens a session of the Runs tab (`key` null: "earlier runs"), on `run`'s first row when given */
+  | { type: "session"; key: string | null; run?: string }
   /** opens one role of the open session */
   | { type: "role"; run: string; dispatchId: string }
   /** opens one milestone of the open session, on its digest */
@@ -165,7 +177,8 @@ export type Action =
   | { type: "arm"; what: Armed["what"]; target: string; at: number }
   | { type: "disarm" };
 
-export const initialState = (tab: Tab = "status"): AppState => ({
+export const initialState = (tab: Tab = "status", host: OrchestrationHost = "unknown"): AppState => ({
+  host,
   tab,
   profile: null,
   drafts: {},
@@ -173,11 +186,13 @@ export const initialState = (tab: Tab = "status"): AppState => ({
   session: null,
   role: null,
   milestone: null,
+  back: null,
   paused: false,
   armed: null,
 });
 
-const fresh = (name: string, doc: ProfileDoc): Draft => ({
+const fresh = (name: string, doc: ProfileDoc, host: OrchestrationHost): Draft => ({
+  host,
   name,
   base: doc,
   doc,
@@ -195,7 +210,10 @@ export const currentDraft = (s: AppState): Draft | null => (s.profile ? (s.draft
 const isStaged = (d: Draft | undefined): boolean => d !== undefined && dirtyCount(d) > 0;
 
 export function dirtyCount(d: Draft): number {
-  const fields = diffProfiles(resolveProfile(d.base, d.name), resolveProfile(d.doc, d.name)).length;
+  const fields = diffProfiles(
+    resolveProfile(d.base, d.name, d.host),
+    resolveProfile(d.doc, d.name, d.host),
+  ).length;
   return fields + Object.keys(d.treatLikes).length;
 }
 
@@ -239,7 +257,9 @@ export function reduce(s: AppState, a: Action): AppState {
         tab: "profiles",
         profile: a.name,
         // Keep only a draft with staged changes; a clean one restarts from the file just read.
-        drafts: isStaged(s.drafts[a.name]) ? s.drafts : { ...s.drafts, [a.name]: fresh(a.name, a.doc) },
+        drafts: isStaged(s.drafts[a.name])
+          ? s.drafts
+          : { ...s.drafts, [a.name]: fresh(a.name, a.doc, s.host) },
       };
     case "edit":
       return withDraft(s, s.profile, (d) =>
@@ -302,13 +322,16 @@ export function reduce(s: AppState, a: Action): AppState {
       const d = s.drafts[a.name];
       const from = a.from;
       if (!from || !d || (same(d.doc, from.doc) && same(d.treatLikes, from.treatLikes)))
-        return { ...s, drafts: { ...s.drafts, [a.name]: fresh(a.name, a.doc) } };
+        return { ...s, drafts: { ...s.drafts, [a.name]: fresh(a.name, a.doc, s.host) } };
       // edited while the save wrote: the saved file is the new base, and the newer edits stay staged over it
       const treatLikes = Object.fromEntries(
         Object.entries(d.treatLikes).filter(([rung, like]) => from.treatLikes[rung] !== like),
       );
       const doc = applyPatch(a.doc, patchBetween(from.doc, d.doc));
-      return { ...s, drafts: { ...s.drafts, [a.name]: { ...fresh(a.name, a.doc), doc, treatLikes } } };
+      return {
+        ...s,
+        drafts: { ...s.drafts, [a.name]: { ...fresh(a.name, a.doc, s.host), doc, treatLikes } },
+      };
     }
     case "forget": {
       const { [a.name]: _gone, ...drafts } = s.drafts;
@@ -341,12 +364,29 @@ export function reduce(s: AppState, a: Action): AppState {
       else if (top.kind === "save" && a.type === "invalid") next = { ...top, error: a.error };
       return next === top ? s : { ...s, dialogs: [...s.dialogs.slice(0, -1), next] };
     }
-    case "session":
-      return { ...s, session: { key: a.key }, role: null, milestone: null, armed: null };
-    case "role":
-      return { ...s, role: { run: a.run, dispatchId: a.dispatchId }, milestone: null, armed: null };
-    case "milestone":
-      return { ...s, milestone: { run: a.run, name: a.name }, role: null, armed: null };
+    case "session": {
+      // a run asked for starts the cursor on that run; reopening the same session keeps the row esc lands on
+      const back =
+        !a.run && s.back?.session === a.key ? s.back : { session: a.key, role: null, milestone: null };
+      return {
+        ...s,
+        session: { key: a.key, ...(a.run ? { run: a.run } : {}) },
+        role: null,
+        milestone: null,
+        back,
+        armed: null,
+      };
+    }
+    case "role": {
+      const role = { run: a.run, dispatchId: a.dispatchId };
+      const back = { session: s.session?.key ?? null, role, milestone: null };
+      return { ...s, role, milestone: null, back, armed: null };
+    }
+    case "milestone": {
+      const milestone = { run: a.run, name: a.name };
+      const back = { session: s.session?.key ?? null, role: null, milestone };
+      return { ...s, milestone, role: null, back, armed: null };
+    }
     case "up":
       if (s.milestone) return { ...s, milestone: null, armed: null };
       return s.role ? { ...s, role: null, armed: null } : { ...s, session: null, armed: null };

package/src/entry/tui/stories.ts

@@ -1,3 +1,4 @@
+import { sessionKey } from "../../domain/host.ts";
 import type { ProfilePatch } from "../../domain/profile.ts";
 import type { CommandId } from "./commands.ts";
 import type { FixtureOptions } from "./fixtures.ts";
@@ -58,19 +59,25 @@ export const STORIES: Story[] = [
   {
     name: "session",
     title: "Runs: one session with two runs, one continued elsewhere",
-    steps: [{ command: "tab.runs" }, { action: { type: "session", key: "s-auth" } }],
+    steps: [
+      { command: "tab.runs" },
+      { action: { type: "session", key: sessionKey({ host: "claude-code", sessionId: "s-auth" }) } },
+    ],
   },
   {
     name: "session-live",
     title: "Runs: a live session with three live roles",
-    steps: [{ command: "tab.runs" }, { action: { type: "session", key: "s-jobs" } }],
+    steps: [
+      { command: "tab.runs" },
+      { action: { type: "session", key: sessionKey({ host: "claude-code", sessionId: "s-jobs" }) } },
+    ],
   },
   {
     name: "role",
     title: "Runs: a role opened",
     steps: [
       { command: "tab.runs" },
-      { action: { type: "session", key: "s-jobs" } },
+      { action: { type: "session", key: sessionKey({ host: "claude-code", sessionId: "s-jobs" }) } },
       { action: { type: "role", run: "20260926-114800-jobs-screen", dispatchId: "d1" } },
     ],
   },
@@ -79,7 +86,7 @@ export const STORIES: Story[] = [
     title: "Runs: a milestone opened on its digest",
     steps: [
       { command: "tab.runs" },
-      { action: { type: "session", key: "s-jobs" } },
+      { action: { type: "session", key: sessionKey({ host: "claude-code", sessionId: "s-jobs" }) } },
       { action: { type: "milestone", run: "20260926-114800-jobs-screen", name: "M0" } },
     ],
   },

package/src/entry/tui/views/profile-actions.ts

@@ -1,6 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { errorMessage, isCatherdError } from "../../../domain/errors.ts";
-import { PROFILE_NAME, patchBetween, type ProfileDoc } from "../../../domain/profile.ts";
+import { PROFILE_NAME, patchBetween, resolveProfile, type ProfileDoc } from "../../../domain/profile.ts";
 import { CHANGED_ON_DISK } from "../effects.ts";
 import { type AppApi, useApp, useDialogHandler } from "../providers/app.tsx";
 import { type Data, useData } from "../providers/data.tsx";
@@ -16,7 +16,9 @@ const fail = (app: AppApi, e: unknown) => app.toast(errorToast(e));
  */
 export function showProfile(app: AppApi, name: string, o: { quiet?: boolean } = {}): unknown {
   try {
-    app.dispatch({ type: "show", name, doc: app.effects.readProfile(name) });
+    const doc = app.effects.readProfile(name);
+    resolveProfile(doc, name, app.getState().host);
+    app.dispatch({ type: "show", name, doc });
     return null;
   } catch (e) {
     if (!o.quiet) fail(app, e);

package/src/entry/tui/views/profiles.tsx

@@ -100,7 +100,7 @@ export function ProfilesView(props: { width: number; height: number }) {
           },
     );
   }, [app.state.profile, here, app, polledAt, openTries]);
-  const profile = useMemo(() => (draft ? resolveProfile(draft.doc, draft.name) : null), [draft]);
+  const profile = useMemo(() => (draft ? resolveProfile(draft.doc, draft.name, draft.host) : null), [draft]);
   const billingKey = JSON.stringify(profile?.billing ?? {});
   // read again after every save too, by the identity of the base it reads back (the same bytes when only
   // treat-likes changed): a save writes the staged treat-likes to the catalog override and clears them
@@ -185,7 +185,7 @@ export function ProfilesView(props: { width: number; height: number }) {
   /** the draft as it is now: two keys in one tick must not both edit the profile this render drew */
   const current = () => {
     const d = currentDraft(app.getState());
-    return d ? resolveProfile(d.doc, d.name) : null;
+    return d ? resolveProfile(d.doc, d.name, d.host) : null;
   };
   const edit = (patch: ReturnType<typeof patchFor>) => patch && app.dispatch({ type: "edit", patch });
   const toggleOpen = (r: Row, open?: boolean) =>
@@ -267,7 +267,7 @@ export function ProfilesView(props: { width: number; height: number }) {
             value: v.dim,
             title: `${v.dim} ${v.value}`,
             group: "values",
-            detail: `${v.inferred ? `inferred from ${v.from}` : v.confidence} · ${v.source} ${v.benchmark} · ${v.date}`,
+            detail: `${v.lent === "treat-like" ? `like ${v.from}` : v.inferred ? `inferred from ${v.from}` : v.confidence} · ${v.source} ${v.benchmark} · ${v.date}`,
           })),
           {
             value: "runs",

package/src/entry/tui/views/runs.tsx

@@ -1,4 +1,5 @@
-import { type MutableRefObject, useEffect, useRef, useState } from "react";
+import { type MutableRefObject, useEffect, useMemo, useRef, useState } from "react";
+import { waitingLine } from "../../../services/orchestrator-wait.ts";
 import { useApp, useBack, useNow } from "../providers/app.tsx";
 import { useData, usePoll } from "../providers/data.tsx";
 import { useCommandLayer } from "../providers/keymap.tsx";
@@ -7,7 +8,7 @@ import { useUi } from "../providers/theme.tsx";
 import { isArmed } from "../state.ts";
 import { ago, clock, plural, shortRung, wrap, wrapHanging } from "../text.ts";
 import { glyph, mascot, type Token } from "../theme.ts";
-import type { RoleRow, SessionRow, SessionRun } from "../effects.ts";
+import type { RoleRow, SessionDetail, SessionRow, SessionRun } from "../effects.ts";
 import { Line, type Part } from "../widgets/line.tsx";
 import { List, type ListItem, useSelected } from "../widgets/list.tsx";
 
@@ -166,6 +167,8 @@ function roleMark(r: RoleRow, plain: boolean): Part {
 function runHeading(r: SessionRun, now: number, plain: boolean): Part[] {
   const bits = [r.repo, `started ${ago(now - Date.parse(r.createdAt))}`];
   if (r.budget !== null) bits.push(`budget ${Math.round(r.budget * 100)}%`);
+  const waiting = waitingLine(r.waiting, now);
+  if (waiting) bits.push(waiting);
   const moved =
     r.continued === "here" ? "continued here" : r.continuedIn ? `continued in ${r.continuedIn}` : null;
   return [
@@ -181,8 +184,11 @@ function useLiveRead<T extends { dirs: string[] }>(read: () => T, key: string) {
   const app = useApp();
   const [watching, setWatching] = useState(false);
   const polled = usePoll(read, watching ? WATCHED_EVERY_MS : RUN_EVERY_MS, { paused: app.state.paused, key });
+  // the watch calls the latest refresh; the ref moves after each commit, never during a render
   const refresh = useRef(polled.refresh);
-  refresh.current = polled.refresh;
+  useEffect(() => {
+    refresh.current = polled.refresh;
+  });
   const dirs = polled.value?.dirs.join("\n") ?? "";
   useEffect(() => {
     if (app.state.paused || dirs === "") {
@@ -196,8 +202,26 @@ function useLiveRead<T extends { dirs: string[] }>(read: () => T, key: string) {
   return { ...polled, watching };
 }
 
+/**
+ * The row a session's screen starts on before the cursor moves: the first row of the run it was opened for,
+ * else its first live role (live roles can sit below many landed milestones), else its first row.
+ */
+function startRow(d: SessionDetail, run: string | undefined): string | null {
+  const rows = (r: SessionDetail["runs"][number]) => [
+    ...r.milestones.map((m) => milestoneKey(r.id, m.name)),
+    ...r.roles.map((x) => roleKey(x.run, x.dispatchId)),
+  ];
+  const asked = run === undefined ? undefined : d.runs.find((r) => r.id === run);
+  const first = asked ? rows(asked)[0] : undefined;
+  if (first) return first;
+  const live = d.runs.flatMap((r) => r.roles).find((x) => x.live);
+  if (live) return roleKey(live.run, live.dispatchId);
+  return d.runs.flatMap(rows)[0] ?? null;
+}
+
 function SessionView(props: {
   sessionKey: string | null;
+  run: string | undefined;
   width: number;
   height: number;
   initial: string | null;
@@ -206,17 +230,26 @@ function SessionView(props: {
   const app = useApp();
   const ui = useUi();
   const now = useNow(1_000);
-  const [selected, setSelected, selectedNow] = useSelection(props.initial);
+  const [chosen, setSelected, chosenNow] = useSelection(props.initial);
   const polled = useLiveRead(() => app.effects.session(props.sessionKey), String(props.sessionKey));
   useRefresher(props.refresher, polled.refresh);
   useBack(true, "view", () => app.dispatch({ type: "up" }));
   const d = polled.value;
-  const roleAt = (key: string | null) =>
-    d?.runs.flatMap((r) => r.roles).find((x) => key === roleKey(x.run, x.dispatchId)) ?? null;
-  const milestoneAt = (key: string | null) =>
-    d?.runs
-      .flatMap((r) => r.milestones.map((m) => ({ run: r.id, name: m.name })))
-      .find((x) => key === milestoneKey(x.run, x.name)) ?? null;
+  // each row's role or milestone by its key, built once per read rather than on every key
+  const byKey = useMemo(() => {
+    const roles = new Map<string, RoleRow>();
+    const milestones = new Map<string, { run: string; name: string }>();
+    for (const r of d?.runs ?? []) {
+      for (const m of r.milestones) milestones.set(milestoneKey(r.id, m.name), { run: r.id, name: m.name });
+      for (const x of r.roles) roles.set(roleKey(x.run, x.dispatchId), x);
+    }
+    return { roles, milestones, start: d ? startRow(d, props.run) : null };
+  }, [d, props.run]);
+  // until the cursor moves, it stands on the start row
+  const selected = chosen ?? byKey.start;
+  const selectedNow = () => chosenNow() ?? byKey.start;
+  const roleAt = (key: string | null) => (key === null ? null : (byKey.roles.get(key) ?? null));
+  const milestoneAt = (key: string | null) => (key === null ? null : (byKey.milestones.get(key) ?? null));
   useCommandLayer("row.runs", {
     "runs.open": () => {
       const k = selectedNow();
@@ -275,7 +308,7 @@ function SessionView(props: {
                 : { text: `${glyph("waiting", ui.plain)} ${m.name}`, tone: "muted" },
               m.landed
                 ? { text: m.what ? `  ${m.what}` : "", tone: "muted" }
-                : { text: "  not landed", tone: "muted" },
+                : { text: `  not landed${m.what ? ` · ${m.what}` : ""}`, tone: "muted" },
             ]}
           />
         ),
@@ -349,10 +382,17 @@ function RoleView(props: {
   const app = useApp();
   const ui = useUi();
   const [selected, setSelected] = useSelection();
+  // a role with its record is finished for good: nothing on its screen changes, so it is read no more
+  // (r still reads it again)
+  const [done, setDone] = useState(false);
   const polled = usePoll(() => app.effects.role(props.run, props.dispatchId), RUN_EVERY_MS, {
-    paused: app.state.paused,
+    paused: app.state.paused || done,
     key: `${props.run}/${props.dispatchId}`,
   });
+  const recorded = polled.value?.record != null;
+  useEffect(() => {
+    if (recorded) setDone(true);
+  }, [recorded]);
   useRefresher(props.refresher, polled.refresh);
   useBack(true, "view", () => app.dispatch({ type: "up" }));
   const d = polled.value;
@@ -532,13 +572,16 @@ export function RunsView(props: { width: number; height: number }) {
       app.toast({ variant: "info", message: app.getState().paused ? "Updates paused" : "Updates resumed" });
     },
   });
-  const { milestone, role, session } = app.state;
+  const { milestone, role, session, back } = app.state;
   // esc lands on the row it came from: the last session opened, and the last milestone or role opened in it
-  const back = useRef<{ session: string | null; row: string | null }>({ session: null, row: null });
-  if (session && back.current.session !== keyOf(session.key))
-    back.current = { session: keyOf(session.key), row: null };
-  if (milestone) back.current.row = milestoneKey(milestone.run, milestone.name);
-  if (role) back.current.row = roleKey(role.run, role.dispatchId);
+  const backRow =
+    back && session && back.session === session.key
+      ? back.milestone
+        ? milestoneKey(back.milestone.run, back.milestone.name)
+        : back.role
+          ? roleKey(back.role.run, back.role.dispatchId)
+          : null
+      : null;
   if (milestone)
     return (
       <MilestoneView
@@ -563,11 +606,14 @@ export function RunsView(props: { width: number; height: number }) {
     return (
       <SessionView
         sessionKey={session.key}
+        run={session.run}
         width={props.width}
         height={props.height}
-        initial={back.current.row}
+        initial={backRow}
         refresher={refresher}
       />
     );
-  return <SessionList width={props.width} height={props.height} initial={back.current.session} />;
+  return (
+    <SessionList width={props.width} height={props.height} initial={back ? keyOf(back.session) : null} />
+  );
 }

package/src/entry/tui/views/save-dialog.tsx

@@ -48,11 +48,11 @@ export interface SavePreview {
  */
 function previewSave(
   d: Draft,
-  fx: Pick<Effects, "catalog" | "validate" | "agents" | "readProfile">,
+  fx: Pick<Effects, "catalog" | "validate" | "agents" | "readProfile" | "profiles">,
   now: ProfileDoc = fx.readProfile(d.name),
 ): SavePreview {
-  const before = resolveProfile(now, d.name);
-  const after = resolveProfile(applyPatch(now, patchBetween(d.base, d.doc)), d.name);
+  const before = resolveProfile(now, d.name, d.host);
+  const after = resolveProfile(applyPatch(now, patchBetween(d.base, d.doc)), d.name, d.host);
   const { catalog } = fx.catalog(after.billing);
   const a = new Set(fx.agents(before));
   const b = new Set(fx.agents(after));
@@ -62,7 +62,11 @@ function previewSave(
     changes: diffProfiles(before, after),
     treatLikes: Object.entries(d.treatLikes),
     validation,
-    repair: validation.errors.length > 0 && repairs(fx.validate(before, staged), validation),
+    // as the ProfileService rules: a profile with no stored file has no errors a save could repair (1.2 minor)
+    repair:
+      validation.errors.length > 0 &&
+      fx.profiles().names.includes(d.name) &&
+      repairs(fx.validate(before, staged), validation),
     agentsAdded: [...b].filter((x) => !a.has(x)),
     agentsRemoved: [...a].filter((x) => !b.has(x)),
   };

package/src/entry/tui/views/status.tsx

@@ -1,4 +1,5 @@
 import type { Check } from "../../../services/doctor-checks.ts";
+import { waitingLine } from "../../../services/orchestrator-wait.ts";
 import { useApp, useNow } from "../providers/app.tsx";
 import { useData } from "../providers/data.tsx";
 import { useCommandLayer } from "../providers/keymap.tsx";
@@ -19,6 +20,8 @@ function stateParts(state: Check["state"], word: string, plain: boolean): Part[]
 /** A run in one line: its state word first, then title, repo and progress (research C4). */
 export function runParts(r: RunRow, now: number, plain: boolean): Part[] {
   const bits = [plural(r.roleRuns, "role run"), `${r.landed} landed`];
+  const waiting = waitingLine(r.waiting, now);
+  if (waiting) bits.push(waiting);
   if (r.budget !== null) bits.push(`${Math.round(r.budget * 100)}% budget`);
   return [
     r.live
@@ -189,10 +192,11 @@ export function StatusView(props: { width: number; height: number }) {
       if (name !== null) {
         showProfile(app, name);
       } else if (selected?.startsWith("run:")) {
-        // spec §4: a run opens in its session's screen, which shows it with the session's other runs
+        // spec §4: a run opens in its session's screen, which shows it with the session's other runs; the
+        // cursor starts on that run
         const row = runs.find((r) => `run:${r.id}` === selected);
         app.dispatch({ type: "tab", tab: "runs" });
-        if (row) app.dispatch({ type: "session", key: row.session });
+        if (row) app.dispatch({ type: "session", key: row.session, run: row.id });
       }
     },
   });

package/src/entry/workspace-command.ts

@@ -0,0 +1,44 @@
+import { resolve } from "node:path";
+import { defineCommand } from "citty";
+import { inspectWorkspace, workspaceStatus } from "../services/workspace-service.ts";
+import { JSON_ARG, printJson } from "./cli-kit.ts";
+import { defaultDeps } from "./deps.ts";
+
+const inspect = defineCommand({
+  meta: { name: "inspect", description: "Read the explicit repositories in a workspace manifest" },
+  args: {
+    root: { type: "positional", description: "workspace root (default: current directory)" },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    const view = await inspectWorkspace(resolve(args.root ?? process.cwd()));
+    if (args.json) return printJson(view);
+    console.log(view.root);
+    for (const [name, path] of Object.entries(view.repos)) console.log(`${name}: ${path}`);
+  },
+});
+
+const status = defineCommand({
+  meta: { name: "status", description: "Read a workspace run's children, dependencies and budget" },
+  args: {
+    workspace: { type: "positional", required: true, description: "workspace run id" },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    const view = await workspaceStatus(defaultDeps(), args.workspace);
+    if (args.json) return printJson(view);
+    console.log(`${view.workspace.id}: ${view.workspace.title}`);
+    for (const step of view.steps) {
+      const blocked = step.blockedBy.length ? ` (waiting for ${step.blockedBy.join(", ")})` : "";
+      console.log(`${step.id}: ${step.repo} ${step.state}${step.run ? ` ${step.run}` : ""}${blocked}`);
+    }
+    console.log(
+      `spend: ${view.spend.tokens} tokens, ${view.spend.minutes.toFixed(2)} min, $${view.spend.usd.toFixed(2)}`,
+    );
+  },
+});
+
+export const workspaceCommand = defineCommand({
+  meta: { name: "workspace", description: "Inspect workspace members and coordinated runs" },
+  subCommands: { inspect, status },
+});

package/src/infra/boot-lock.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+import { tryLock } from "./filelock.ts";
+import { log } from "./log.ts";
+import { locksDir } from "./paths.ts";
+import { ensurePrivateDir } from "./store.ts";
+
+/** The machine-wide lock the MCP server that runs the boot sync and reconcile holds for its life. */
+export const bootLockTarget = (): string => join(locksDir(), "mcp-boot");
+
+/**
+ * Plan 22 (the three MCP servers of one Codex session): boot sync and reconcile are single-flight across
+ * processes. The first server takes this lock (its pid and start time in it; a dead holder's is reclaimed) and
+ * keeps it until it closes; a second server finds it held and skips both. Returns the release, or null while
+ * another live server holds it. A lock that cannot be taken for another reason never costs a reconcile: the
+ * server runs the boot work, with nothing to release.
+ */
+export function takeBootLock(): (() => void) | null {
+  try {
+    ensurePrivateDir(locksDir());
+    return tryLock(bootLockTarget());
+  } catch (e) {
+    log("warn", "boot", { lock: bootLockTarget(), error: e instanceof Error ? e.message : String(e) });
+    return () => {};
+  }
+}

package/src/infra/cli.ts

@@ -0,0 +1,65 @@
+import { scrubSecrets } from "./env.ts";
+import { log } from "./log.ts";
+import { killGroup } from "./proc.ts";
+
+export interface CliResult {
+  ok: boolean;
+  out: string;
+  err: string;
+}
+
+/** Process groups of CLI calls still running: an exiting catherd (Ctrl-C is exit 130) kills them. */
+const live = new Set<number>();
+let hooked = false;
+function track(pid: number): void {
+  live.add(pid);
+  if (hooked) return;
+  hooked = true;
+  // a detached group gets no terminal SIGINT, and process.exit skips the timeout, so kill it on the way out
+  process.on("exit", () => {
+    for (const g of live) killGroup(g, "SIGKILL");
+  });
+}
+
+/**
+ * Runs `bin <args>` without catherd's secrets and with no stdin; null when `bin` is not on PATH. A call
+ * past `timeoutMs` is killed with every process it started (it runs in its own process group) and is
+ * reported as failed, so neither a wedged CLI nor a child holding its pipes stalls the caller.
+ */
+export async function runCli(
+  bin: string,
+  args: string[],
+  o: { timeoutMs: number; env?: Record<string, string>; cwd?: string; logArgs?: string[] },
+): Promise<CliResult | null> {
+  if (!Bun.which(bin, { PATH: process.env.PATH ?? "" })) return null;
+  const logArgs = o.logArgs ?? args;
+  log("debug", "spawn", { argv: [bin, ...logArgs], env: scrubSecrets(o.env ?? {}) });
+  const p = Bun.spawn([bin, ...args], {
+    cwd: o.cwd,
+    env: scrubSecrets({ ...process.env, ...o.env }),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    detached: true,
+  });
+  track(p.pid);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), o.timeoutMs);
+  });
+  try {
+    const done = await Promise.race([
+      Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]),
+      late,
+    ]);
+    if (!done) {
+      killGroup(p.pid, "SIGKILL");
+      return { ok: false, out: "", err: `${bin} ${logArgs.join(" ")} timed out after ${o.timeoutMs} ms` };
+    }
+    const [code, out, err] = done;
+    return { ok: code === 0, out, err };
+  } finally {
+    clearTimeout(timer);
+    live.delete(p.pid);
+  }
+}