catherd-cli 0.2.1 → 1.1.0

package/src/entry/tui/widgets/spinner.tsx

@@ -0,0 +1,49 @@
+// Adapted from anomalyco/opencode packages/tui/src/component/spinner.tsx and startup-loading.tsx
+// (MIT, © 2025 opencode); see THIRD_PARTY_NOTICES.md.
+import { useEffect, useState } from "react";
+import { useApp } from "../providers/app.tsx";
+import { useTone, useUi } from "../providers/theme.tsx";
+import { ascii } from "../text.ts";
+import { SPINNER } from "../theme.ts";
+
+/**
+ * Spec §9.3 motion: true once `active` has lasted SPINNER.showAfterMs, and then for at least
+ * SPINNER.minShowMs, so a quick check never flickers.
+ */
+export function useDelayedPresence(active: boolean): boolean {
+  const { clock } = useApp();
+  const [shownAt, setShownAt] = useState<number | null>(null);
+  useEffect(() => {
+    if (active && shownAt === null) {
+      const h = clock.setTimeout(() => setShownAt(clock.now()), SPINNER.showAfterMs);
+      return () => clock.clearTimeout(h);
+    }
+    if (!active && shownAt !== null) {
+      const left = SPINNER.minShowMs - (clock.now() - shownAt);
+      if (left <= 0) {
+        setShownAt(null);
+        return;
+      }
+      const h = clock.setTimeout(() => setShownAt(null), left);
+      return () => clock.clearTimeout(h);
+    }
+    return undefined;
+  }, [active, shownAt, clock]);
+  return shownAt !== null;
+}
+
+/** A braille spinner and what it waits on; a still `⋯` under reduced motion (spec §9.3). */
+export function Spinner(props: { label: string }) {
+  const { clock } = useApp();
+  const ui = useUi();
+  const tone = useTone();
+  const [frame, setFrame] = useState(0);
+  useEffect(() => {
+    if (ui.reducedMotion) return;
+    const h = clock.setInterval(() => setFrame((f) => f + 1), SPINNER.ms);
+    return () => clock.clearInterval(h);
+  }, [clock, ui.reducedMotion]);
+  const frames = ui.plain ? SPINNER.plainFrames : SPINNER.frames;
+  const g = ui.reducedMotion ? SPINNER.still[ui.plain ? 1 : 0] : frames[frame % frames.length];
+  return <text fg={tone("muted")}>{`${g} ${ui.plain ? ascii(props.label) : props.label}`}</text>;
+}

package/src/entry/tui/widgets/toast.tsx

@@ -0,0 +1,62 @@
+// Adapted from anomalyco/opencode packages/tui/src/ui/toast.tsx (MIT, © 2025 opencode);
+// see THIRD_PARTY_NOTICES.md.
+import { useTerminalDimensions } from "@opentui/react";
+import { useToasts } from "../providers/toast.tsx";
+import { useUi } from "../providers/theme.tsx";
+import { truncateEnd, wrap } from "../text.ts";
+import { glyph, type Token } from "../theme.ts";
+import { Line } from "./line.tsx";
+
+const TONE: Record<string, Token> = { info: "info", success: "success", warning: "warning", error: "error" };
+
+/** Lines of a toast's message kept before the rest is cut; a fix command always shows in full. */
+const MESSAGE_LINES = 3;
+
+/**
+ * Spec §9.3: the current toast at the top right, with a `┃` bar in its colour and the queue's length.
+ * The message wraps to three lines; a fix command wraps in full on muted lines under it.
+ */
+export function ToastHost() {
+  const { current, queued } = useToasts();
+  const ui = useUi();
+  const dims = useTerminalDimensions();
+  if (!current) return null;
+  const bar = glyph("bar", ui.plain);
+  const max = Math.max(1, Math.min(60, dims.width - 6) - 4);
+  const said = wrap(`${current.message}${queued ? `  +${queued} more` : ""}`, max);
+  const message = said.slice(0, MESSAGE_LINES);
+  if (said.length > MESSAGE_LINES)
+    message[MESSAGE_LINES - 1] = truncateEnd(
+      `${message[MESSAGE_LINES - 1]} ${said[MESSAGE_LINES]}`,
+      max,
+      ui.plain,
+    );
+  const fix = current.fix ? wrap(current.fix, max) : [];
+  const text = Math.max(...[...message, ...fix].map((l) => Bun.stringWidth(l)));
+  const w = text + 4;
+  const line = (t: string, muted: boolean, i: number) => (
+    <Line
+      key={i}
+      width={w}
+      opaque
+      parts={[
+        { text: `${bar} `, tone: TONE[current.variant] },
+        { text: t.padEnd(text + t.length - Bun.stringWidth(t)), tone: muted ? "muted" : undefined },
+        { text: ` ${bar}`, tone: TONE[current.variant] },
+      ]}
+    />
+  );
+  return (
+    <box
+      position="absolute"
+      top={1}
+      left={Math.max(0, dims.width - w - 2)}
+      zIndex={4000}
+      width={w}
+      height={message.length + fix.length}
+      flexDirection="column"
+    >
+      {[...message.map((t, i) => line(t, false, i)), ...fix.map((t, i) => line(t, true, message.length + i))]}
+    </box>
+  );
+}

package/src/infra/assets.ts

@@ -0,0 +1,4 @@
+import { fileURLToPath } from "node:url";
+
+/** A file shipped in the package, such as `catalog/models.json`; catherd ships its sources unbuilt. */
+export const assetPath = (rel: string): string => fileURLToPath(new URL(`../../${rel}`, import.meta.url));

package/src/infra/claude-session.ts

@@ -0,0 +1,98 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { claudeHome } from "./paths.ts";
+import { isAlive } from "./proc.ts";
+
+/**
+ * The Claude Code session catherd's MCP server runs in (spec §3.3; docs/research/2026-09-28-cross-session-messaging.md):
+ * what its environment says, and what the session's registry file (`<config>/sessions/<pid>.json`) says now.
+ */
+
+/** The four variables a Claude Code session hands its MCP servers; each may be absent. */
+export const SESSION_ENV_KEYS = {
+  sessionId: "CLAUDE_CODE_SESSION_ID",
+  hostSessionId: "CLAUDE_CODE_HOST_SESSION_ID",
+  socketPath: "CLAUDE_CODE_MESSAGING_SOCKET",
+  token: "CLAUDE_CODE_MESSAGING_TOKEN",
+} as const;
+
+export interface SessionEnv {
+  /** the id at spawn: it goes stale after /clear, so the registry's is preferred */
+  sessionId: string | null;
+  /** set only when a host (Desktop) launched the session */
+  hostSessionId: string | null;
+  socketPath: string | null;
+  token: string | null;
+}
+
+/** The session's environment, or null outside Claude Code (neither a session id nor a socket). */
+export function readSessionEnv(env: Record<string, string | undefined> = process.env): SessionEnv | null {
+  const get = (k: string) => env[k] || null;
+  const s: SessionEnv = {
+    sessionId: get(SESSION_ENV_KEYS.sessionId),
+    hostSessionId: get(SESSION_ENV_KEYS.hostSessionId),
+    socketPath: get(SESSION_ENV_KEYS.socketPath),
+    token: get(SESSION_ENV_KEYS.token),
+  };
+  return s.sessionId || s.socketPath ? s : null;
+}
+
+/** One live session's registry entry, as far as catherd reads it. */
+export interface SessionFile {
+  pid: number;
+  sessionId: string;
+  name: string | null;
+  hostSessionId: string | null;
+  messagingSocketPath: string | null;
+  /** busy | idle | waiting, when the session says */
+  status: string | null;
+}
+
+const str = (v: unknown): string | null => (typeof v === "string" && v ? v : null);
+
+/** Every readable registry file (`<config>/sessions/<pid>.json`); a torn or foreign one is skipped. */
+export function readSessionFiles(dir: string = join(claudeHome(), "sessions")): SessionFile[] {
+  if (!existsSync(dir)) return [];
+  const out: SessionFile[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!/^\d+\.json$/.test(f)) continue;
+    try {
+      const v = JSON.parse(readFileSync(join(dir, f), "utf8")) as Record<string, unknown>;
+      const sessionId = str(v.sessionId);
+      if (typeof v.pid !== "number" || !sessionId) continue;
+      out.push({
+        pid: v.pid,
+        sessionId,
+        name: str(v.name),
+        hostSessionId: str(v.hostSessionId),
+        messagingSocketPath: str(v.messagingSocketPath),
+        status: str(v.status),
+      });
+    } catch {
+      // written as we read it, or not Claude Code's
+    }
+  }
+  return out;
+}
+
+/**
+ * This server's session file: the one naming its socket, else its parent's pid (the MCP server is the session's
+ * child), else the one with its env's session id. Null when none is found.
+ */
+export function sessionFileFor(
+  s: SessionEnv,
+  files = readSessionFiles(),
+  ppid = process.ppid,
+): SessionFile | null {
+  return (
+    (s.socketPath ? files.find((f) => f.messagingSocketPath === s.socketPath) : undefined) ??
+    files.find((f) => f.pid === ppid) ??
+    (s.sessionId ? files.find((f) => f.sessionId === s.sessionId) : undefined) ??
+    null
+  );
+}
+
+/** The live session that has `sessionId` now, if one does: its file names it and its process is alive. */
+export function liveSessionFile(sessionId: string, files = readSessionFiles()): SessionFile | null {
+  return files.find((f) => f.sessionId === sessionId && isAlive(f.pid, null)) ?? null;
+}

package/src/infra/dispatch-dir.ts

@@ -0,0 +1,286 @@
+import {
+  closeSync,
+  existsSync,
+  linkSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { EXIT_REASONS, type ExitInfo } from "../domain/record.ts";
+import { lockHeld, withFileLock } from "./filelock.ts";
+import { isAlive, selfIdentity } from "./proc.ts";
+import { PRIVATE_FILE, readVersioned } from "./store.ts";
+
+export function dispatchPaths(dir: string) {
+  return {
+    brief: join(dir, "brief.md"),
+    spec: join(dir, "spec.json"),
+    proc: join(dir, "proc.json"),
+    events: join(dir, "events.jsonl"),
+    stderr: join(dir, "stderr"),
+    reply: join(dir, "reply.md"),
+    exit: join(dir, "exit.json"),
+    claim: join(dir, "claim"),
+    cancel: join(dir, "cancel"),
+    /** held by the one supervisor of this dispatch for its lifetime (filelock, dead holders reclaimed) */
+    supervisorLock: join(dir, "supervisor.lock"),
+    /** exists from admission until the orchestrator reads the record (`result`, `cancel`): "not yet read" */
+    collect: join(dir, "collect"),
+    /** while a reader takes the record: names that reader's process, so a crash leaves it reclaimable */
+    lease: join(dir, "collect.lease"),
+    supervisorLog: join(dir, "supervisor.log"),
+    /** what failover did for this limited dispatch, written once under `failover.lock` (plan 10) */
+    failover: join(dir, "failover.json"),
+    /** the message that announced this dispatch's record to its session, once sent (plan 10) */
+    notified: join(dir, "notified.json"),
+    /** written once by the supervisor when the worker went quiet for half its idle timeout, not busy (spec §3.6) */
+    stall: join(dir, "stall.json"),
+    /** the message that announced the stall, once sent */
+    stallNotified: join(dir, "stall-notified.json"),
+  };
+}
+
+/**
+ * Exclusive create: the first caller finalizes; every later caller reads the record it wrote. The claim
+ * names its claimant (pid and start time), so a later caller can tell a dead claimant from a slow one.
+ */
+export function tryClaim(dir: string): boolean {
+  let fd: number;
+  try {
+    fd = openSync(dispatchPaths(dir).claim, "wx", PRIVATE_FILE);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    return false;
+  }
+  try {
+    writeSync(fd, JSON.stringify(selfIdentity()));
+  } catch (e) {
+    // a claim that names no one would hold every other finalizer off until it is stale: drop it
+    closeSync(fd);
+    try {
+      unlinkSync(dispatchPaths(dir).claim);
+    } catch {
+      // already gone
+    }
+    throw e;
+  }
+  closeSync(fd);
+  return true;
+}
+
+/** Who holds the claim, or null when it names no one (an older build's empty claim, or one being written). */
+export function readClaimant(dir: string): { pid: number; startTime: string | null } | null {
+  try {
+    const c = JSON.parse(readFileSync(dispatchPaths(dir).claim, "utf8")) as {
+      pid?: unknown;
+      startTime?: unknown;
+    };
+    if (typeof c.pid !== "number") return null;
+    return { pid: c.pid, startTime: typeof c.startTime === "string" ? c.startTime : null };
+  } catch {
+    return null;
+  }
+}
+
+/** Marks a dispatch's record as not yet read; written before its launch. */
+export function markForCollect(dir: string): void {
+  writeFileSync(dispatchPaths(dir).collect, "", { mode: PRIVATE_FILE });
+}
+
+const errno = (e: unknown): string | undefined => (e as NodeJS.ErrnoException).code;
+
+/** Test seams: `beforeTakeover` runs after a collector judged a lease dead, before it takes the lock. */
+export const collectSeams = { beforeTakeover: async (_dir: string): Promise<void> => {} };
+/** The hard link a lease is made with; tests replace it to stand for a filesystem without hard links. */
+export const leaseFs = { link: linkSync };
+
+/** An ownerless lease this old was left by a crash mid-write (only the no-hard-link fallback can leave one). */
+const OWNERLESS_STALE_MS = 5_000;
+/** A lease temp file this old, or whose pid is dead, was left by a crash. */
+const TEMP_STALE_MS = 60_000;
+
+const self = selfIdentity;
+
+/** Who holds a collection lease, or null when none can be read. */
+function leaseOwner(file: string): { pid: number; startTime: string | null } | null {
+  try {
+    const c = JSON.parse(readFileSync(file, "utf8")) as { pid?: unknown; startTime?: unknown };
+    if (typeof c.pid !== "number") return null;
+    return { pid: c.pid, startTime: typeof c.startTime === "string" ? c.startTime : null };
+  } catch {
+    return null;
+  }
+}
+
+function olderThan(file: string, ms: number): boolean {
+  try {
+    return statSync(file).mtimeMs < Date.now() - ms;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A lease no live process holds: it exists, and its owner is dead, or it names none and is too old to be
+ * one still being written.
+ */
+function leaseDead(file: string): boolean {
+  if (!existsSync(file)) return false;
+  const who = leaseOwner(file);
+  return who ? !isAlive(who.pid, who.startTime) : olderThan(file, OWNERLESS_STALE_MS);
+}
+
+/**
+ * Whether this dispatch's record is still unread: it has the mark, or a lease whose reader died before the
+ * record went out.
+ */
+export function awaitsCollect(dir: string): boolean {
+  const p = dispatchPaths(dir);
+  return existsSync(p.collect) || leaseDead(p.lease);
+}
+
+/** Creates a lease naming this process, exclusively: true when it is now this process's. */
+function createLease(dir: string): boolean {
+  const p = dispatchPaths(dir);
+  const content = JSON.stringify(self());
+  const tmp = `${p.lease}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  writeFileSync(tmp, content, { mode: PRIVATE_FILE });
+  try {
+    // linked in whole: no reader ever sees a lease without its owner
+    leaseFs.link(tmp, p.lease);
+    return true;
+  } catch (e) {
+    if (errno(e) === "EEXIST") return false;
+    if (!["EPERM", "ENOTSUP", "EXDEV", "EOPNOTSUPP"].includes(errno(e) ?? "")) throw e;
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+  // no hard links here: an exclusive create, its owner written at once (an ownerless lease is young)
+  let fd: number;
+  try {
+    fd = openSync(p.lease, "wx", PRIVATE_FILE);
+  } catch (e) {
+    if (errno(e) === "EEXIST") return false;
+    throw e;
+  }
+  try {
+    writeSync(fd, content);
+  } finally {
+    closeSync(fd);
+  }
+  return true;
+}
+
+/**
+ * Turns a dead collector's lease back into the mark, serialized by a lock on the lease, and only after
+ * reading it again under the lock: the mark is written before the lease goes, so the record is never
+ * without both, and a lease that is not dead (gone, or a live collector's) is left alone. A moved lease
+ * is never linked back.
+ */
+async function reviveDeadLease(dir: string): Promise<void> {
+  const p = dispatchPaths(dir);
+  await withFileLock(p.lease, () => {
+    if (!leaseDead(p.lease)) return;
+    markForCollect(dir);
+    rmSync(p.lease, { force: true });
+    sweepLeaseTemps(dir);
+  });
+}
+
+/**
+ * Collects the dispatch as a lease naming this process: true for the one caller that got it, so each
+ * record is read (marked read) once. The common path takes no lock: the lease is created exclusively, and
+ * the record is this caller's only if the mark still exists then; the mark goes only once the lease
+ * exists. A dead collector's lease is first turned back into the mark (`reviveDeadLease`), then
+ * collected the same way; a live collector's is never taken. The caller ends the lease with `endCollect`
+ * once the record has gone out, or turns it back into the mark with `putBackCollect`.
+ */
+export async function tryCollect(dir: string): Promise<boolean> {
+  const p = dispatchPaths(dir);
+  if (!existsSync(p.collect)) {
+    if (!leaseDead(p.lease)) return false;
+    await collectSeams.beforeTakeover(dir);
+    await reviveDeadLease(dir);
+  }
+  if (!createLease(dir)) {
+    // a lease is there: collect it only if it is dead, and only by way of the mark
+    if (!leaseDead(p.lease)) return false;
+    await collectSeams.beforeTakeover(dir);
+    await reviveDeadLease(dir);
+    if (!createLease(dir)) return false;
+  }
+  // no lease was there when this one was made: the record is ours only if the mark still is
+  if (!existsSync(p.collect)) {
+    endCollect(dir);
+    return false;
+  }
+  rmSync(p.collect, { force: true });
+  return true;
+}
+
+/** Ends this process's lease (never another's): the record has gone out. Sweeps leftover temp files. */
+export function endCollect(dir: string): void {
+  const p = dispatchPaths(dir);
+  const who = leaseOwner(p.lease);
+  // the pid alone: while this process lives no other can hold its pid, so a lease naming it is its own
+  if (who?.pid === process.pid) rmSync(p.lease, { force: true });
+  sweepLeaseTemps(dir);
+}
+
+/** Turns this process's lease back into the mark: the record did not go out. */
+export function putBackCollect(dir: string): void {
+  markForCollect(dir);
+  endCollect(dir);
+}
+
+const LEASE_TEMP = /^collect\.lease\.(?:dead\.)?(\d+)\.[^.]+$/;
+
+/** Removes lease temp files a crash left behind: a dead pid's, or any older than a minute. */
+function sweepLeaseTemps(dir: string): void {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    const m = LEASE_TEMP.exec(n);
+    if (!m) continue;
+    const f = join(dir, n);
+    if (!isAlive(Number(m[1]), null) || olderThan(f, TEMP_STALE_MS)) rmSync(f, { force: true });
+  }
+}
+
+const ExitFileSchema = z.looseObject({
+  schema: z.literal(1),
+  code: z.number().nullable(),
+  signal: z.string().nullable(),
+  reason: z.enum(EXIT_REASONS),
+  endedAt: z.string(),
+});
+
+export function readExit(dir: string): ExitInfo | null {
+  try {
+    const e = readVersioned(dispatchPaths(dir).exit, ExitFileSchema, 1);
+    return { code: e.code, signal: e.signal, reason: e.reason, endedAt: e.endedAt };
+  } catch {
+    return null;
+  }
+}
+
+export function requestCancel(dir: string): void {
+  writeFileSync(dispatchPaths(dir).cancel, new Date().toISOString(), { mode: PRIVATE_FILE });
+}
+
+/** The target of the dispatch's supervisor lock (`supervisor.lock`, as `dispatchPaths` names it). */
+export const supervisorLockTarget = (dir: string): string => join(dir, "supervisor");
+
+/** Whether a live supervisor holds the dispatch: launch evidence even before launch.json or proc.json. */
+export const supervisorAlive = (dir: string): boolean => lockHeld(supervisorLockTarget(dir));

package/src/infra/env.ts

@@ -0,0 +1,67 @@
+/**
+ * catherd's own secrets; the user's backend credentials (OPENAI_API_KEY, …) stay, workers need them. The Claude Code
+ * session's messaging socket and token are the MCP server's alone (spec §3.2: it is the only sender), and so is the
+ * session's identity (a child that has it takes itself for that session: the doctor's MCP server would own its
+ * runs, a headless claude-code worker would inherit it): no process catherd starts gets them.
+ */
+const SECRET_ENV = new Set([
+  "TYPESAFE_API_KEY",
+  "CLAUDE_CODE_MESSAGING_SOCKET",
+  "CLAUDE_CODE_MESSAGING_TOKEN",
+  "CLAUDE_CODE_SESSION_ID",
+  "CLAUDE_CODE_HOST_SESSION_ID",
+]);
+
+/** `base` without catherd's own secrets and without unset keys; for every process catherd starts. */
+export function scrubSecrets(base: Record<string, string | undefined>): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(base)) if (v !== undefined && !SECRET_ENV.has(k)) env[k] = v;
+  return env;
+}
+
+/**
+ * Spec 1.1 §12: the plugin's launcher runs `bunx` with TMPDIR in catherd's cache, so macOS never half-cleans
+ * the package, and passes the user's own TMPDIR in CATHERD_USER_TMPDIR (empty when unset). The server and
+ * every worker it starts get the user's TMPDIR back.
+ */
+export function restoreTmpdir(env: Record<string, string | undefined>): void {
+  const mine = env.CATHERD_USER_TMPDIR;
+  if (mine === undefined) return;
+  if (mine) env.TMPDIR = mine;
+  else delete env.TMPDIR;
+  delete env.CATHERD_USER_TMPDIR;
+}
+
+export function workerEnv(
+  base: Record<string, string | undefined>,
+  overrides: Record<string, string>,
+  cwd: string,
+): Record<string, string> {
+  return { ...scrubSecrets(base), ...overrides, PWD: cwd };
+}
+
+/** What a preflight check may see; everything else, credentials included, stays out (spec §4.7). */
+const CHECK_ENV = new Set([
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "LANG",
+  "TZ",
+  "TERM",
+  "TMPDIR",
+  "CI",
+  "NODE_ENV",
+  "CATHERD_HOME",
+  "CATHERD_LOCK_SLOTS",
+]);
+const CHECK_ENV_PATTERN = /^(LC_[A-Z_]+|XDG_[A-Z_]+_(HOME|DIR|DIRS))$/;
+
+/** A strict allowlist of `base` plus PWD, for lane-authored shell text such as preflight checks. */
+export function checkEnv(base: Record<string, string | undefined>, cwd: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(base))
+    if (v !== undefined && (CHECK_ENV.has(k) || CHECK_ENV_PATTERN.test(k))) env[k] = v;
+  return { ...env, PWD: cwd };
+}