catherd-cli 1.0.0 → 1.1.0

package/src/services/dispatches.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { z } from "zod";
+import { dispatchHints } from "../domain/hints.ts";
 import { ACCESS, type RunRecord } from "../domain/record.ts";
 import { ROLES } from "../domain/roles.ts";
 import { dispatchPaths, readExit, supervisorAlive } from "../infra/dispatch-dir.ts";
@@ -31,6 +32,8 @@ const AdmitSchema = z.looseObject({
   repo: z.string(),
   /** `git status` fingerprints when admitted, for changedOwned and violations */
   before: z.record(z.string(), z.string()),
+  /** the Claude Code session that dispatched it (spec §3.3); absent on 1.0 dispatches and outside Claude Code */
+  sessionId: z.string().optional(),
 });
 export type Admit = z.infer<typeof AdmitSchema>;
 
@@ -143,3 +146,29 @@ export function latestDispatch(run: Run, name: string): Dispatch | null {
   }
   return all.find((d) => d.admit.dispatchId === id) ?? all.at(-1) ?? null;
 }
+
+/** failover.json: what failover did for a limited dispatch (plan 10), written once, under its lock. */
+const FailoverSchema = z.looseObject({
+  schema: z.literal(1),
+  at: z.string(),
+  /** the stand-in it launched, if any */
+  standIn: z.object({ dispatchId: z.string(), rung: z.string() }).nullable(),
+  /** the limited record's hints, as failover left them ("limit: … failed over to …", "failover: …") */
+  hints: z.array(z.string()),
+  /** the pause it wrote to state.md, if any */
+  pause: z.string().nullable(),
+});
+export type FailoverFile = z.infer<typeof FailoverSchema>;
+
+export function readFailover(dir: string): FailoverFile | null {
+  try {
+    return readVersioned(dispatchPaths(dir).failover, FailoverSchema, 1);
+  } catch {
+    return null;
+  }
+}
+
+/** Spec §4.4: what to do next about one finished record; for a usage limit, the failover's own hints. */
+export function recordHints(run: Run, d: Dispatch, r: RunRecord): string[] {
+  return readFailover(d.dir)?.hints ?? dispatchHints(r, d.admit.owns, relative(run.dir, d.dir));
+}

package/src/services/doctor-access.ts

@@ -0,0 +1,231 @@
+import { realTmpdir } from "../adapters/access.ts";
+import type { AccessShell } from "../adapters/backend.ts";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { tryParseRung } from "../domain/ids.ts";
+import type { Profile } from "../domain/profile.ts";
+import { ROLES } from "../domain/roles.ts";
+import { locksDir } from "../infra/paths.ts";
+import { ensurePrivateDir } from "../infra/store.ts";
+import type { Check } from "./doctor-checks.ts";
+
+// Spec §5 and §12: the five access probes doctor runs per backend that serves a workspace-write role, each
+// in that backend's worker shell with the grants a worker gets, and the rows that report them.
+
+export type ProbeId = "lock" | "temp" | "loopback" | "https" | "docker";
+
+/**
+ * What the probes reach: npm's ping, through HTTPS_PROXY when it is set (Bun's fetch honours it), and
+ * `docker`. CATHERD_PROBE_URL and CATHERD_PROBE_DOCKER replace them (tests: a local server, no docker).
+ */
+export const probeTargets = {
+  get url(): string {
+    return process.env.CATHERD_PROBE_URL || "https://registry.npmjs.org/-/ping";
+  },
+  get docker(): string {
+    return process.env.CATHERD_PROBE_DOCKER || "docker";
+  },
+};
+
+interface ProbeDef {
+  id: ProbeId;
+  label: string;
+  /** off when the role's network is off (Docker access goes with the network) */
+  network: boolean;
+  script: string;
+  args: () => string[];
+}
+
+// every path and URL goes in as an argument, never into the script text
+const WRITE = 'f="$1/.catherd-doctor-$$" && touch "$f" && rm -f "$f"';
+const BUN_EVAL = '"$1" -e "$2"';
+const BIND = 'Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } }).stop(true)';
+// npm's ping answers 200; any 4xx or 5xx fails, so a proxy's 407 or 403 for a denied host is not a false green
+// a fetch that throws (no route, DNS, refused) prints its error code, not Bun's stack and version trailer
+const FETCH =
+  "let r; try { r = await fetch(process.argv[1], { method: 'HEAD' }) } catch (e) { console.error([e?.code, e?.message].filter(Boolean).join(': ') || String(e)); process.exit(1) } if (r.status >= 400) { console.error(`HTTP ${r.status}${r.status === 407 ? ' (proxy authentication required)' : r.status === 403 ? ' (refused: a proxy denying the host?)' : ''}`); process.exit(1) }";
+
+/** Why a probe failed: its last non-empty stderr line (Bun's version trailer skipped), else stdout's. */
+export function lastErrorLine(err: string, out: string): string | undefined {
+  const lines = (t: string) =>
+    t
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !/^Bun v\d/.test(l));
+  return lines(err).at(-1) ?? lines(out).at(-1);
+}
+
+const PROBES: ProbeDef[] = [
+  { id: "lock", label: "lock-dir write", network: false, script: WRITE, args: () => [locksDir()] },
+  { id: "temp", label: "temp write", network: false, script: WRITE, args: () => [realTmpdir()] },
+  {
+    id: "loopback",
+    label: "loopback bind",
+    network: true,
+    script: BUN_EVAL,
+    args: () => [process.execPath, BIND],
+  },
+  {
+    id: "https",
+    label: "outbound HTTPS",
+    network: true,
+    script: `${BUN_EVAL} "$3"`,
+    args: () => [process.execPath, FETCH, probeTargets.url],
+  },
+  {
+    id: "docker",
+    label: "docker version",
+    network: true,
+    script: '"$1" version',
+    args: () => [probeTargets.docker],
+  },
+];
+
+export interface ProbeResult {
+  id: ProbeId;
+  label: string;
+  /** "off": the role's network is off; "skip": docker is not installed */
+  state: "ok" | "failed" | "off" | "skip";
+  /** the last line the probe printed on failure */
+  why?: string;
+}
+
+/** Runs the five probes in `shell`; the network three (docker among them) only when granted, docker only when installed. */
+export async function runProbes(shell: AccessShell, network: boolean): Promise<ProbeResult[]> {
+  const out: ProbeResult[] = [];
+  let noLocks: string | null = null;
+  try {
+    ensurePrivateDir(locksDir());
+  } catch (e) {
+    noLocks = `cannot create ${locksDir()}: ${e instanceof Error ? e.message : String(e)}`;
+  }
+  for (const p of PROBES) {
+    if (p.id === "lock" && noLocks) {
+      out.push({ id: p.id, label: p.label, state: "failed", why: noLocks });
+      continue;
+    }
+    if (p.network && !network) {
+      out.push({ id: p.id, label: p.label, state: "off" });
+      continue;
+    }
+    if (p.id === "docker" && !Bun.which(probeTargets.docker, { PATH: process.env.PATH ?? "" })) {
+      out.push({ id: p.id, label: p.label, state: "skip" });
+      continue;
+    }
+    const r = await shell.run(p.script, p.args());
+    const last = lastErrorLine(r?.err ?? "", r?.out ?? "");
+    const late = last && / timed out after (\d+) ms$/.exec(last);
+    const why =
+      r === null
+        ? "the probe shell did not start"
+        : late
+          ? `timed out after ${Number(late[1]) / 1000} s`
+          : last;
+    out.push({
+      id: p.id,
+      label: p.label,
+      state: r?.ok ? "ok" : "failed",
+      ...(r?.ok ? {} : { why: why || "no output" }),
+    });
+  }
+  return out;
+}
+
+/** The fix for a failed probe, per backend: Codex's sandbox holds catherd's grants; the others run unsandboxed. */
+function fixFor(backend: string, id: ProbeId): string {
+  if (backend === "codex") {
+    const override =
+      "catherd passes this grant to Codex itself (with your top-level [sandbox_workspace_write] writable_roots added): check that no --profile or managed requirements.toml overrides it";
+    if (id === "docker")
+      return "the Codex sandbox cannot reach the Docker socket here: run the Docker checks in the verifier (full access), or give the role full access";
+    return override;
+  }
+  const FIX: Record<ProbeId, string> = {
+    lock: `chmod -R u+w ${locksDir()}`,
+    temp: `check that ${realTmpdir()} is writable`,
+    loopback: "something on this machine refuses a bind to 127.0.0.1: check the firewall",
+    https: "check the network, or set HTTPS_PROXY for this shell",
+    docker: `start Docker: ${probeTargets.docker} version fails`,
+  };
+  return FIX[id];
+}
+
+/** Every backend an enabled workspace-write role runs on or fails over to, with whether any of those roles has network. */
+export function workspaceWriteNetwork(profiles: Profile[]): Map<string, boolean> {
+  const out = new Map<string, boolean>();
+  for (const p of profiles)
+    for (const role of ROLES) {
+      const rc = p.roles[role];
+      if (!rc.enabled || rc.access !== "workspace-write") continue;
+      for (const r of [...rc.rungs, ...rc.rungs.flatMap((x) => p.failover[x] ?? [])]) {
+        const b = tryParseRung(r)?.backend;
+        if (b && b !== "claude") out.set(b, (out.get(b) ?? false) || rc.network !== false);
+      }
+    }
+  return out;
+}
+
+/**
+ * The `sandbox:codex` row (which `codex sandbox` form runs) and one `access:<backend>` row per backend; a
+ * backend not in `installed` (its CLI is not on PATH) is skipped without running a probe.
+ */
+export async function accessChecks(profiles: Profile[], installed: ReadonlySet<string>): Promise<Check[]> {
+  const checks: Check[] = [];
+  for (const [id, network] of workspaceWriteNetwork(profiles)) {
+    const a = adapterFor(id);
+    if (!a?.accessShell) continue;
+    if (!installed.has(id)) {
+      checks.push({
+        id: `access:${id}`,
+        label: `${id} worker access`,
+        state: "skip",
+        word: "not installed",
+        detail: `${id} is not installed: no worker runs on it here`,
+      });
+      continue;
+    }
+    const shell = await a.accessShell({ network }).catch((e: unknown) => String(e));
+    if (id === "codex")
+      checks.push(
+        typeof shell === "string"
+          ? { id: "sandbox:codex", label: "codex sandbox", state: "skip", word: "not tested", detail: shell }
+          : { id: "sandbox:codex", label: "codex sandbox", state: "ok", word: "ready", detail: shell.how },
+      );
+    const base = { id: `access:${id}`, label: `${id} worker access` };
+    if (typeof shell === "string") {
+      checks.push({ ...base, state: "skip", word: "not tested", detail: shell });
+      continue;
+    }
+    let results: ProbeResult[];
+    try {
+      results = await runProbes(shell, network);
+    } finally {
+      shell.close();
+    }
+    const failed = results.filter((r) => r.state === "failed");
+    const passed = results.filter((r) => r.state === "ok").map((r) => r.label);
+    const notes = [
+      ...(results.some((r) => r.state === "off") ? ["network off by profile"] : []),
+      ...(results.some((r) => r.state === "skip") ? ["no docker"] : []),
+      // only Codex's sandbox can take the network away; the others' shells keep it
+      ...(id !== "codex" && !network ? [`network: false is not enforced by ${id}'s shell`] : []),
+    ];
+    checks.push(
+      failed.length
+        ? {
+            ...base,
+            state: "warn",
+            word: "blocked",
+            detail: `in ${shell.how}, a worker cannot: ${failed.map((r) => `${r.label} (${r.why})`).join("; ")}`,
+            fix: failed.map((r) => `${r.label}: ${fixFor(id, r.id)}`).join("\n"),
+          }
+        : {
+            ...base,
+            state: "ok",
+            word: "ready",
+            detail: [`${passed.join(", ")} in ${shell.how}`, ...notes].join(" · "),
+          },
+    );
+  }
+  return checks;
+}

package/src/services/doctor-backends.ts

@@ -26,24 +26,6 @@ export function usedBackends(profiles: Profile[]): Map<string, "role" | "failove
   return used;
 }
 
-/**
- * Spec §10.3: the backends that run an enabled workspace-write role, or stand in for one of its rungs,
- * whose sandbox must let such a worker take the heavy lock.
- */
-export function workspaceWriteBackends(profiles: Profile[]): Set<string> {
-  const out = new Set<string>();
-  for (const p of profiles)
-    for (const role of ROLES) {
-      const rc = p.roles[role];
-      if (!rc.enabled || rc.access !== "workspace-write") continue;
-      for (const r of [...rc.rungs, ...rc.rungs.flatMap((x) => p.failover[x] ?? [])]) {
-        const b = backendOf(r);
-        if (b) out.add(b);
-      }
-    }
-  return out;
-}
-
 const PROBLEM_WORD: Record<string, string> = {
   E_BACKEND_MISSING: "missing",
   E_BACKEND_TOO_OLD: "too old",
@@ -98,9 +80,11 @@ export function moveRolesFix(install: string, id: string, to: string, profiles:
   ].join("\n");
 }
 
+/** One row per backend; `installed`, when given, collects the backends whose CLI is on PATH. */
 export async function backendChecks(
   used: Map<string, "role" | "failover">,
   profiles: Profile[],
+  installed?: Set<string>,
 ): Promise<Check[]> {
   const checks: Check[] = [];
   const ready: string[] = [];
@@ -116,6 +100,7 @@ export async function backendChecks(
         { code: "E_IO_UNEXPECTED" as const, message: errText(e), fix: `run ${id} --version to see why` },
       ],
     }));
+    if (probe.installed) installed?.add(id);
     const problem = probe.problems[0];
     const use = used.get(id);
     if (!problem) {

package/src/services/doctor-checks.ts

@@ -4,11 +4,13 @@ import { errorMessage, isCatherdError } from "../domain/errors.ts";
 import { claudeHome, locksDir } from "../infra/paths.ts";
 import { ensurePrivateDir, PRIVATE_FILE } from "../infra/store.ts";
 import { agentLinkState } from "./agent-links.ts";
+import type { Handshake } from "./doctor.ts";
 import { activeName } from "./profile-store.ts";
 
 // The rows of `catherd doctor` and the checks that stand alone; doctor.ts assembles the report.
 
-type CheckState = "ok" | "warn" | "fail" | "skip";
+/** `info`: worth knowing, nothing to fix (spec 1.1 §13: the shipped defaults' access) */
+type CheckState = "ok" | "warn" | "fail" | "skip" | "info";
 
 /** One row of `catherd doctor` (spec §10.3): its state, one word, the detail and the full fix. */
 export interface Check {
@@ -66,6 +68,49 @@ export function pluginCheck(version: string): Check {
   return { ...base, state: "ok", word: "ready", detail: installed };
 }
 
+/** What makes the plugin's launcher run this catherd without a resolve: a global install at this version. */
+export const reinstallCommand = (version: string): string => `bun add -g catherd-cli@${version}`;
+
+const MISSING_MODULE = /Cannot find (?:module|package) ['"]?([^'"\s]+)/;
+const NO_BUNX = /bunx: (?:command )?not found/;
+
+/**
+ * Spec 1.1 §12: the `mcp` row. The handshake starts the server the way the plugin does; a module it cannot
+ * load (a half-cleaned bunx cache, a broken global install) and a launcher that finds neither catherd nor
+ * bunx both say "reinstall: <command>".
+ */
+export function mcpCheck(h: Handshake, version: string): Check {
+  const base = { id: "mcp", label: "MCP server" };
+  if (h.ok && h.tools.includes("status"))
+    return { ...base, state: "ok", word: "ready", detail: `answers tools/list with ${h.tools.length} tools` };
+  const said = `${h.error ?? ""}\n${h.stderr ?? ""}`;
+  const reinstall = reinstallCommand(version);
+  const missing = MISSING_MODULE.exec(said)?.[1];
+  if (missing)
+    return {
+      ...base,
+      state: "fail",
+      word: "broken install",
+      detail: `cannot load ${missing}; reinstall: ${reinstall}`,
+      fix: reinstall,
+    };
+  if (NO_BUNX.test(said))
+    return {
+      ...base,
+      state: "fail",
+      word: "missing",
+      detail: `no catherd ${version} on PATH and no bunx to fetch it; reinstall: ${reinstall}`,
+      fix: reinstall,
+    };
+  return {
+    ...base,
+    state: "fail",
+    word: "no answer",
+    detail: h.error ?? "tools/list has no status tool",
+    fix: "run catherd mcp to see why it does not start",
+  };
+}
+
 export function locksCheck(): Check {
   const base = { id: "locks", label: "heavy-lock dir" };
   try {

package/src/services/doctor-push.ts

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { envelope } from "../domain/notice.ts";
+import { readSessionEnv, sessionFileFor } from "../infra/claude-session.ts";
+import { claudeHome } from "../infra/paths.ts";
+import { sendToInbox } from "../infra/peer-inbox.ts";
+import type { Check } from "./doctor-checks.ts";
+
+/**
+ * Spec §3.9 `doctor`'s `push` row: run from inside a Claude Code session (its Bash tool), send that session one
+ * `later` message and look for the enqueue line its transcript gets when the message is accepted
+ * (docs/research/2026-09-28-cross-session-messaging.md §7).
+ */
+
+export type PushOutcome = "ok" | "no-session" | "held" | "unconfirmed" | "failed";
+
+export interface PushProbe {
+  outcome: PushOutcome;
+  detail: string;
+}
+
+/** How long the probe looks for the enqueue line; tests shorten it. */
+export const pushLimits = { waitMs: 5_000, pollMs: 100 };
+
+/** The session's transcript, found by globbing `projects/*` (a git worktree logs under its main checkout's slug). */
+function transcriptOf(sessionId: string): string | null {
+  const projects = join(claudeHome(), "projects");
+  if (!existsSync(projects)) return null;
+  for (const d of readdirSync(projects)) {
+    const f = join(projects, d, `${sessionId}.jsonl`);
+    if (existsSync(f)) return f;
+  }
+  return null;
+}
+
+const enqueued = (file: string, nonce: string): boolean => {
+  try {
+    return readFileSync(file, "utf8")
+      .split("\n")
+      .some((l) => l.includes('"operation":"enqueue"') && l.includes(nonce));
+  } catch {
+    return false;
+  }
+};
+
+export async function probePush(env: Record<string, string | undefined> = process.env): Promise<PushProbe> {
+  const s = readSessionEnv(env);
+  if (!s?.socketPath)
+    return { outcome: "no-session", detail: "run catherd doctor from a Claude Code session to test push" };
+  const sessionId = sessionFileFor(s)?.sessionId ?? s.sessionId;
+  const nonce = crypto.randomUUID().slice(0, 8);
+  const r = await sendToInbox(s, envelope(`catherd doctor: push test ${nonce}, no action needed`), "later");
+  // a socket that is gone or refuses is a shell that outlived its session, not a protocol change
+  if (r.outcome === "no-session" || r.outcome === "refused")
+    return {
+      outcome: "no-session",
+      detail: `this session's inbox is not reachable (${r.reason ?? r.outcome}); run catherd doctor from a live Claude Code session to test push`,
+    };
+  if (r.outcome !== "sent")
+    return {
+      outcome: "failed",
+      detail: `catherd cannot notify this Claude Code version; peek still works (${r.reason ?? r.outcome})`,
+    };
+  const deadline = Date.now() + pushLimits.waitMs;
+  let file: string | null = null;
+  for (;;) {
+    file = sessionId ? transcriptOf(sessionId) : null;
+    if (file && enqueued(file, nonce))
+      return { outcome: "ok", detail: "a test message reached this session" };
+    if (Date.now() > deadline) break;
+    await Bun.sleep(pushLimits.pollMs);
+  }
+  return file
+    ? {
+        outcome: "held",
+        detail: `the test message was sent but not accepted within ${pushLimits.waitMs / 1000} s: a crossSessionInbound setting holds or refuses it`,
+      }
+    : {
+        outcome: "unconfirmed",
+        detail: "sent; no transcript of this session was found to confirm it arrived",
+      };
+}
+
+/** The probe as a `doctor` row. */
+export function pushCheck(p: PushProbe): Check {
+  const base = { id: "push", label: "push to Claude Code", detail: p.detail };
+  switch (p.outcome) {
+    case "ok":
+      return { ...base, state: "ok", word: "ready" };
+    case "no-session":
+      return { ...base, state: "skip", word: "no session" };
+    case "held":
+      return {
+        ...base,
+        state: "warn",
+        word: "held",
+        fix: `set "crossSessionInbound": "accept" in ${join(claudeHome(), "settings.json")}, or remove a project setting that sets it to hold or refuse`,
+      };
+    case "unconfirmed":
+      return { ...base, state: "warn", word: "not confirmed" };
+    case "failed":
+      return {
+        ...base,
+        state: "fail",
+        word: "failed",
+        fix: "update catherd (and Claude Code); meanwhile peek(run) shows each role and each unread record",
+      };
+  }
+}