catherd-cli 1.3.0 → 1.5.0

package/src/services/doctor-docker.ts

@@ -0,0 +1,221 @@
+import {
+  accessSync,
+  constants,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statfsSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { realTmpdir, toolchainCaches } from "../adapters/access.ts";
+import { runCli } from "../adapters/cli.ts";
+import { probeTwice } from "../infra/host-probe.ts";
+import { probeTargets } from "./doctor-access.ts";
+import type { Check } from "./doctor-checks.ts";
+
+// Plan 23: the rows that catch what cost the identity and payment runs their verifier rounds: a Docker client
+// that injects proxies into every container, a compose network whose services cannot reach each other by
+// name, a Docker disk about to fill, and the toolchain caches a sandboxed worker writes.
+
+/** Under this much free space in Docker's data root, doctor warns: image builds start failing near it (tests raise it). */
+export const dockerDisk = { minFreeBytes: 10 * 1024 ** 3 };
+
+/** How long the compose probe may take, an image pull included. */
+export const composeProbe = { timeoutMs: 120_000 };
+
+/** The Docker client's config file: $DOCKER_CONFIG/config.json, else ~/.docker/config.json. */
+export const dockerConfigFile = (env = process.env): string =>
+  join(env.DOCKER_CONFIG || join(env.HOME || homedir(), ".docker"), "config.json");
+
+/** The keys of a proxies entry the Docker client turns into container environment variables. */
+const PROXY_KEYS = ["httpProxy", "httpsProxy", "noProxy", "ftpProxy", "allProxy"];
+
+/** The Docker client's default daemon host, which its proxies block may key an entry by. */
+const DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock";
+
+/**
+ * A `proxies` block in the Docker client's config that sets a value: every container then gets HTTP_PROXY and its
+ * siblings. The Docker client applies the current daemon host's entry, else `default`; an entry with no value
+ * (or an empty block) injects nothing.
+ */
+export function proxiesCheck(
+  file = dockerConfigFile(),
+  env: Record<string, string | undefined> = process.env,
+): Check | null {
+  let config: { proxies?: unknown };
+  try {
+    config = JSON.parse(readFileSync(file, "utf8")) as { proxies?: unknown };
+  } catch {
+    return null;
+  }
+  const proxies = config.proxies;
+  if (!proxies || typeof proxies !== "object") return null;
+  const entries = proxies as Record<string, unknown>;
+  const host = env.DOCKER_HOST || DEFAULT_DOCKER_HOST;
+  const entry = Object.hasOwn(entries, host) ? entries[host] : entries.default;
+  const sets =
+    !!entry &&
+    typeof entry === "object" &&
+    PROXY_KEYS.some((k) => {
+      const v = (entry as Record<string, unknown>)[k];
+      return typeof v === "string" && v.trim() !== "";
+    });
+  if (!sets) return null;
+  return {
+    id: "docker-proxies",
+    label: "Docker client proxies",
+    state: "warn",
+    word: "injects proxies",
+    detail: `${file} has a proxies block: every container gets HTTP_PROXY, so compose services cannot reach each other by name and a loopback health check goes to the proxy`,
+    fix: `remove the proxies block from ${file}, or add the compose service names and 127.0.0.1 to its noProxy`,
+  };
+}
+
+/** Two busybox services: `web` serves on 8080 with a loopback health check, `probe` fetches it by name. */
+const COMPOSE = `services:
+  web:
+    image: busybox:1.36
+    command: ["httpd", "-f", "-p", "8080", "-h", "/etc"]
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/hostname"]
+      interval: 1s
+      retries: 30
+  probe:
+    image: busybox:1.36
+    depends_on:
+      web:
+        condition: service_healthy
+    command: ["wget", "-q", "-O", "/dev/null", "http://web:8080/hostname"]
+`;
+
+/** `docker compose up` on the two-service file, then `down`; the result of the up. */
+async function composeUp(docker: string): Promise<{ ok: boolean; why: string }> {
+  const dir = mkdtempSync(join(realTmpdir(), "catherd-compose-"));
+  const file = join(dir, "compose.yaml");
+  writeFileSync(file, COMPOSE);
+  const project = ["compose", "-p", `catherd-doctor-${process.pid}`, "-f", file];
+  try {
+    const up = await runCli(
+      docker,
+      [...project, "up", "--abort-on-container-exit", "--exit-code-from", "probe"],
+      {
+        timeoutMs: composeProbe.timeoutMs,
+        cwd: dir,
+      },
+    );
+    const lines = `${up?.err ?? ""}\n${up?.out ?? ""}`
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean);
+    return { ok: up?.ok === true, why: lines.at(-1) ?? "no output" };
+  } finally {
+    await runCli(docker, [...project, "down", "-v", "--remove-orphans"], { timeoutMs: 30_000, cwd: dir });
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Free bytes in Docker's data root, when it is on this machine's disk; null when Docker runs in a VM. */
+async function dockerFree(docker: string): Promise<{ root: string; free: number } | null> {
+  const r = await runCli(docker, ["info", "--format", "{{.DockerRootDir}}"], { timeoutMs: 15_000 });
+  const root = r?.ok ? r.out.trim() : "";
+  if (!root || !existsSync(root)) return null;
+  try {
+    const s = statfsSync(root);
+    return { root, free: Number(s.bavail) * Number(s.bsize) };
+  } catch {
+    return null;
+  }
+}
+
+const gb = (bytes: number): string => `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+
+/**
+ * The Docker rows: the client's proxies, read from its config file; with `probe` (`catherd doctor --docker`), when
+ * a daemon answers, the compose network probe (retried once after 5 s before it calls the host blocked) and the
+ * free space in Docker's data root. The probes pull busybox and start containers, so a plain doctor skips them.
+ */
+export async function dockerChecks(o: { probe: boolean }): Promise<Check[]> {
+  const docker = probeTargets.docker;
+  const checks: Check[] = [];
+  const proxies = proxiesCheck();
+  if (proxies) checks.push(proxies);
+  if (!o.probe) return checks;
+  const version = await runCli(docker, ["version"], { timeoutMs: 15_000 });
+  if (!version?.ok) return checks;
+  const compose = await runCli(docker, ["compose", "version"], { timeoutMs: 15_000 });
+  if (compose?.ok) {
+    const { result, attempts } = await probeTwice(
+      () => composeUp(docker),
+      (r) => r.ok,
+    );
+    checks.push(
+      result.ok
+        ? {
+            id: "docker-network",
+            label: "compose network",
+            state: "ok",
+            word: "ready",
+            detail: "two services reach each other by name, and a loopback health check passes",
+          }
+        : {
+            id: "docker-network",
+            label: "compose network",
+            state: "warn",
+            word: "blocked",
+            detail: `a compose service could not reach another by name, or its loopback health check failed (${attempts} tries, 5 s apart): ${result.why}`,
+            fix: proxies
+              ? (proxies.fix as string)
+              : "check the Docker client's proxies, a VPN or socket filter on the Docker bridge, and that busybox can be pulled",
+          },
+    );
+  }
+  const free = await dockerFree(docker);
+  if (free && free.free < dockerDisk.minFreeBytes)
+    checks.push({
+      id: "docker-disk",
+      label: "Docker disk",
+      state: "warn",
+      word: "low",
+      detail: `${gb(free.free)} free in Docker's data root ${free.root}; builds fail with no space left on device`,
+      fix: "docker image prune -f, then docker builder prune -f",
+    });
+  return checks;
+}
+
+/** Whether this user may write `dir`. */
+const writable = (dir: string): boolean => {
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The toolchain caches present on the machine (Go's build and module caches, the pnpm store, Bun's and npm's
+ * caches), which join every workspace-write worker's writable roots; a warning for one this user cannot write.
+ */
+export function cachesCheck(caches = toolchainCaches()): Check {
+  const base = { id: "caches", label: "toolchain caches" };
+  if (caches.length === 0)
+    return { ...base, state: "skip", word: "none", detail: "no Go, pnpm, Bun or npm cache on this machine" };
+  const blocked = caches.filter((c) => !writable(c));
+  return blocked.length
+    ? {
+        ...base,
+        state: "warn",
+        word: "not writable",
+        detail: `${blocked.join(", ")}: a worker's checks cannot write it, even with it in their writable roots`,
+        fix: `chown -R "$(id -un)" ${blocked.join(" ")}`,
+      }
+    : {
+        ...base,
+        state: "ok",
+        word: "ready",
+        detail: `in every workspace-write worker's writable roots: ${caches.join(", ")}`,
+      };
+}

package/src/services/doctor-push.ts

@@ -1,109 +1,88 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import type { HostContext } from "../domain/host.ts";
 import { envelope } from "../domain/notice.ts";
 import { readSessionEnv, sessionFileFor } from "../infra/claude-session.ts";
-import { claudeHome } from "../infra/paths.ts";
+import { sendToCodexQueue } from "../infra/codex-queue.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 type PushOutcome = "ok" | "no-session" | "unconfirmed" | "failed";
 export interface PushProbe {
   outcome: PushOutcome;
   detail: string;
+  enqueue: "accepted" | "ambiguous" | "not-submitted" | "no-session";
+  processing: "observed" | "unconfirmed";
+  msgId: string | null;
 }
 
-/** 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")
+/** Explicit smoke only: native receipts prove acceptance, never model processing or result collection. */
+export async function probePush(
+  host: HostContext,
+  env: Record<string, string | undefined>,
+): Promise<PushProbe> {
+  const target = host.session;
+  if (host.conflict || !target || host.host === "unknown" || target.host !== host.host)
     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})`,
+      enqueue: "no-session",
+      processing: "unconfirmed",
+      msgId: null,
+      detail:
+        "No validated live host session; run doctor --test-push from the original conversation. Terminal --host selects checks only. Use peek/result.",
     };
-  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":
+  const content = envelope(`catherd doctor: push test ${crypto.randomUUID().slice(0, 8)}, no action needed`);
+  let enqueue: PushProbe["enqueue"];
+  let msgId: string | null = null;
+  if (host.host === "codex") {
+    const sent = await sendToCodexQueue(target, content, env);
+    enqueue = sent.outcome;
+    if (sent.outcome === "accepted") msgId = sent.msgId;
+  } else {
+    const s = readSessionEnv(env);
+    const liveId = s ? (sessionFileFor(s)?.sessionId ?? s.sessionId) : null;
+    if (!s || liveId !== target.sessionId)
       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`,
+        outcome: "no-session",
+        enqueue: "no-session",
+        processing: "unconfirmed",
+        msgId: null,
+        detail: "Claude inbox identity does not match the validated live session; use peek/result.",
       };
-    case "unconfirmed":
-      return { ...base, state: "warn", word: "not confirmed" };
-    case "failed":
+    const sent = await sendToInbox(s, content, "later");
+    if (sent.outcome === "no-session" || sent.outcome === "refused")
       return {
-        ...base,
-        state: "fail",
-        word: "failed",
-        fix: "update catherd (and Claude Code); meanwhile peek(run) shows each role and each unread record",
+        outcome: "no-session",
+        enqueue: "not-submitted",
+        processing: "unconfirmed",
+        msgId: null,
+        detail:
+          "This session's inbox is not reachable; run doctor --test-push from a live Claude Code session. Use peek/result.",
       };
+    enqueue = sent.outcome === "sent" && sent.msgId ? "accepted" : "ambiguous";
+    if (enqueue === "accepted") msgId = sent.msgId ?? null;
   }
+  return {
+    outcome: enqueue === "accepted" ? "ok" : enqueue === "ambiguous" ? "unconfirmed" : "failed",
+    enqueue,
+    processing: "unconfirmed",
+    msgId,
+    detail:
+      enqueue === "accepted"
+        ? "Smoke enqueue accepted; processing unconfirmed. Unloaded, interrupted or restarted hosts may retain queued input. Use peek/result for durable unread results."
+        : enqueue === "ambiguous"
+          ? "Smoke has no verified queue receipt; processing unconfirmed. Retrying may duplicate input. Use peek/result."
+          : "Smoke was not submitted; check native queue support and the existing endpoint. Use peek/result.",
+  };
+}
+
+export function pushCheck(p: PushProbe): Check {
+  const base = { id: "push", label: "host completion push", detail: p.detail };
+  if (p.enqueue === "accepted") return { ...base, state: "ok", word: "enqueue accepted" };
+  if (p.outcome === "no-session") return { ...base, state: "skip", word: "no session" };
+  if (p.enqueue === "ambiguous") return { ...base, state: "warn", word: "ambiguous" };
+  return {
+    ...base,
+    state: "fail",
+    word: "not submitted",
+    fix: "Check native host transport; peek/result keeps the unread record available.",
+  };
 }

package/src/services/doctor-role-mcp.ts

@@ -0,0 +1,65 @@
+import { tryParseRung } from "../domain/ids.ts";
+import type { Profile } from "../domain/profile.ts";
+import { roleMcpTools } from "../domain/role-tools.ts";
+import { ROLES } from "../domain/roles.ts";
+import { ROLE_MCP_STARTUP_SEC, type RoleServerStart } from "../infra/role-mcp.ts";
+import { standInFor } from "./backends.ts";
+import type { Check } from "./doctor-checks.ts";
+
+/**
+ * The active profile's role server, per backend that runs one (codex, claude-code), isolated or not (spec 1.5
+ * plan 21, #42 finding 6): the roles that get it and their tools, and, when doctor probed it, how long a cold
+ * start took against Codex's startup timeout. A start past half that timeout warns: on a loaded machine Codex,
+ * which requires the server, would abort the role.
+ */
+export function roleMcpChecks(profile: Profile | null, start?: RoleServerStart): Check[] {
+  if (!profile) return [];
+  const checks: Check[] = [];
+  for (const backend of ["codex", "claude-code"] as const) {
+    const uses = (rung: string) => tryParseRung(rung)?.backend === backend;
+    const roles = ROLES.filter((role) => {
+      const configured = profile.roles[role];
+      return (
+        configured.enabled &&
+        configured.rungs.some((rung) => {
+          const failover = standInFor(profile.failover, rung);
+          return uses(rung) || (failover !== null && uses(failover));
+        })
+      );
+    });
+    if (!roles.length) continue;
+    const base = { id: `role-mcp:${profile.name}:${backend}`, label: `${profile.name} ${backend} role MCP` };
+    const tools = [...new Set(roles.flatMap(roleMcpTools))];
+    const configured = `${roles.join(", ")}: scoped catherd_role exposes ${tools.join(", ")}; ${backend === "codex" ? "per-tool approval_mode=approve" : "exact MCP tool allowlist"}. Model invocation not tested; managed policy may still deny tools.`;
+    const limit = ROLE_MCP_STARTUP_SEC * 1000;
+    if (start && !start.ok) {
+      checks.push({
+        ...base,
+        state: "fail",
+        word: "no start",
+        detail: `the role server did not start: ${start.error}`,
+        fix: "reinstall catherd at this version, then run catherd doctor again",
+      });
+      continue;
+    }
+    if (start?.ok && start.ms > limit / 2) {
+      checks.push({
+        ...base,
+        state: "warn",
+        word: "slow start",
+        detail: `the role server took ${Math.round(start.ms)} ms to start; Codex gives it ${ROLE_MCP_STARTUP_SEC} s and stops the role when it misses`,
+        fix: "install catherd globally (catherd init) so roles start it without resolving a package, and check the machine's load",
+      });
+      continue;
+    }
+    checks.push({
+      ...base,
+      state: "info",
+      word: "configured",
+      detail: start?.ok
+        ? `${configured} Starts in ${Math.round(start.ms)} ms (limit ${ROLE_MCP_STARTUP_SEC} s).`
+        : configured,
+    });
+  }
+  return checks;
+}