catherd-cli 1.0.0 → 1.1.0

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

@@ -60,14 +60,15 @@ export function step(items: readonly { selectable: boolean }[], from: number, by
 
 /**
  * A view's selected row: `selected` is what this render draws, `current()` what a key handler must read
- * (a key in the same tick may have moved it already).
+ * (a key in the same tick may have moved it already). `initial`: the row it starts on (a list snaps a key it
+ * does not hold to its first row).
  */
-export function useSelected(): {
+export function useSelected(initial: string | null = null): {
   selected: string | null;
   select(key: string): void;
   current(): string | null;
 } {
-  const [selected, setSelected] = useState<string | null>(null);
+  const [selected, setSelected] = useState<string | null>(initial);
   const ref = useRef<string | null>(null);
   ref.current = selected;
   return {

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

@@ -31,11 +31,19 @@ export function dispatchPaths(dir: string) {
     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 launch until a `wait` hands the dispatch's record to the orchestrator */
+    /** exists from admission until the orchestrator reads the record (`result`, `cancel`): "not yet read" */
     collect: join(dir, "collect"),
-    /** while a `wait` hands the record back: names that wait's process, so a crash leaves it reclaimable */
+    /** 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"),
   };
 }
 
@@ -81,7 +89,7 @@ export function readClaimant(dir: string): { pid: number; startTime: string | nu
   }
 }
 
-/** Marks a dispatch as one a `wait` is to hand back; written before its launch. */
+/** 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 });
 }
@@ -130,8 +138,8 @@ function leaseDead(file: string): boolean {
 }
 
 /**
- * Whether a `wait` still has this dispatch's record to hand back: it has the mark, or a lease whose
- * collector died before handing the record back.
+ * 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);
@@ -188,7 +196,7 @@ async function reviveDeadLease(dir: string): Promise<void> {
 
 /**
  * Collects the dispatch as a lease naming this process: true for the one caller that got it, so each
- * record reaches one `wait` only. The common path takes no lock: the lease is created exclusively, and
+ * 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`

package/src/infra/env.ts

@@ -1,5 +1,16 @@
-/** catherd's own secrets; the user's backend credentials (OPENAI_API_KEY, …) stay, workers need them. */
-const SECRET_ENV = new Set(["TYPESAFE_API_KEY"]);
+/**
+ * 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> {
@@ -8,6 +19,19 @@ export function scrubSecrets(base: Record<string, string | undefined>): Record<s
   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>,

package/src/infra/peer-inbox.ts

@@ -0,0 +1,92 @@
+import { createConnection } from "node:net";
+
+/**
+ * Spec §3.4: one frame to a Claude Code session's peer inbox (docs/research/2026-09-28-cross-session-messaging.md).
+ * The auth line (the child token the session gave its children), then one `user` frame, in one write; the socket
+ * is closed 150 ms later, as the native client does on macOS. No `session_id` (a stale one drops the frame) and no
+ * `from-mode` (a wrong one holds it).
+ */
+
+export type SendOutcome = "sent" | "no-session" | "refused" | "error";
+
+export interface SendResult {
+  outcome: SendOutcome;
+  /** the frame's msg_id, when one was written */
+  msgId?: string;
+  /** why it was not sent */
+  reason?: string;
+}
+
+export interface InboxTarget {
+  socketPath: string | null;
+  token: string | null;
+}
+
+/** How long a connection may take, and how long after the write the socket is closed; tests shorten them. */
+export const inboxLimits = { connectMs: 2_000, closeAfterMs: 150 };
+
+/** The two lines one send writes: the auth line (when there is a token) and the user frame. */
+export function frameText(
+  content: string,
+  priority: "later" | "next",
+  token: string | null,
+  msgId: string,
+): string {
+  const frame = { msgV: 1, msg_id: msgId, type: "user", message: { role: "user", content }, priority };
+  return `${token ? `${JSON.stringify({ type: "auth", token })}\n` : ""}${JSON.stringify(frame)}\n`;
+}
+
+/** Sends one message; never throws: every failure is an outcome with its reason. */
+export function sendToInbox(
+  target: InboxTarget,
+  content: string,
+  priority: "later" | "next",
+): Promise<SendResult> {
+  if (!target.socketPath)
+    return Promise.resolve({
+      outcome: "no-session",
+      reason: "no messaging socket in this session's environment",
+    });
+  const msgId = crypto.randomUUID();
+  const socketPath = target.socketPath;
+  return new Promise<SendResult>((resolve) => {
+    let settled = false;
+    const done = (r: SendResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(r);
+    };
+    let s: ReturnType<typeof createConnection>;
+    try {
+      s = createConnection({ path: socketPath });
+    } catch (e) {
+      return done({ outcome: "error", reason: (e as Error).message });
+    }
+    const timer = setTimeout(() => {
+      s.destroy();
+      done({ outcome: "error", reason: `no connection within ${inboxLimits.connectMs} ms` });
+    }, inboxLimits.connectMs);
+    s.on("error", (e: NodeJS.ErrnoException) => {
+      clearTimeout(timer);
+      s.destroy();
+      if (e.code === "ENOENT")
+        done({ outcome: "no-session", reason: `the session's socket is gone (${socketPath})` });
+      else if (e.code === "ECONNREFUSED")
+        done({ outcome: "refused", reason: "the session's socket refused it" });
+      else done({ outcome: "error", reason: e.code ?? e.message });
+    });
+    s.on("connect", () => {
+      clearTimeout(timer);
+      s.write(frameText(content, priority, target.token, msgId), (err) => {
+        if (err) {
+          s.destroy();
+          return done({ outcome: "error", reason: err.message });
+        }
+        setTimeout(() => {
+          s.end();
+          done({ outcome: "sent", msgId });
+        }, inboxLimits.closeAfterMs);
+      });
+    });
+  });
+}

package/src/infra/supervisor.ts

@@ -189,13 +189,19 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
     const started = Date.now();
     let lastActivity = started;
     let finalAt: number | null = null;
+    // spec §3.6: a quiet stretch of half the idle timeout, not busy, is a stall, reported once per dispatch
+    let stalled = false;
+    let stallChecked = false;
     const open = new Set<string>();
     const stream = { offset: 0, rest: "", decoder: new TextDecoder("utf-8") };
 
     while (!done && reason === null) {
       await Bun.sleep(spec.pollMs);
       const lines = readNew(p.events, stream);
-      if (lines.length) lastActivity = Date.now();
+      if (lines.length) {
+        lastActivity = Date.now();
+        stallChecked = false;
+      }
       for (const line of lines) {
         let d: LineInfo | undefined;
         try {
@@ -222,8 +228,32 @@ async function superviseHeld(spec: SuperviseSpec, hooks: SuperviseHooks): Promis
         // the busy check can take up to hookMs: a worker that ended meanwhile is recorded as it ended, read
         // from the child itself too, since `done` is set by a callback that may not have run yet
         if (done || child.exitCode !== null || child.signalCode !== null) break;
-        if (busy) lastActivity = Date.now();
-        else reason = "idle-timeout";
+        if (busy) {
+          // a new quiet stretch starts: it gets its own stall check
+          lastActivity = Date.now();
+          stallChecked = false;
+        } else reason = "idle-timeout";
+      } else if (!stalled && !stallChecked && now - lastActivity >= spec.idleMs / 2) {
+        // asked once per quiet stretch: a busy answer starts a new quiet stretch, with its own half-way check,
+        // so a worker busy here and idle later is reported stalled before the idle check ends it
+        stallChecked = true;
+        const busy = open.size > 0 || (await bounded(() => hooks.isBusy?.(thread, started), hookMs, false));
+        if (busy) {
+          lastActivity = Date.now();
+          stallChecked = false;
+        } else if (!done) {
+          stalled = true;
+          // advisory: a write that fails is logged and never ends a healthy worker
+          try {
+            writeJsonAtomic(p.stall, {
+              schema: 1,
+              at: new Date().toISOString(),
+              quietMs: Date.now() - lastActivity,
+            });
+          } catch (e) {
+            log("warn", "stall", { dispatch: spec.dispatchDir, error: errorMessage(e) });
+          }
+        }
       }
     }
   } catch (e) {

package/src/services/admission.ts

@@ -2,14 +2,17 @@ import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { BackendAdapter } from "../adapters/backend.ts";
 import { budgetStatus, formatBudget } from "../domain/budget.ts";
-import { CatherdError } from "../domain/errors.ts";
+import { CatherdError, errorMessage } from "../domain/errors.ts";
 import { assertId, formatRung, newDispatchId, parseRung } from "../domain/ids.ts";
-import { overlaps, parseLaneHeader } from "../domain/lane.ts";
+import { assertLaneHeader, overlaps } from "../domain/lane.ts";
+import type { RunRecord } from "../domain/record.ts";
+import { withReplyContract } from "../domain/role-prompts.ts";
 import type { Role } from "../domain/roles.ts";
 import { dispatchPaths, markForCollect } from "../infra/dispatch-dir.ts";
 import { withFileLock } from "../infra/filelock.ts";
 import { statusSnapshot } from "../infra/git.ts";
 import { launchSupervisor } from "../infra/launch.ts";
+import { log } from "../infra/log.ts";
 import { processStartTime } from "../infra/proc.ts";
 import { ensurePrivateDir, PRIVATE_FILE, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
 import { readyAdapter, standInFor } from "./backends.ts";
@@ -28,6 +31,7 @@ import {
 import { finalizeDispatch } from "./finalize.ts";
 import type { Deps } from "./ports.ts";
 import { readRecords, recordsOnThread, type Run, runPaths } from "./run-store.ts";
+import { currentSession } from "./sessions.ts";
 
 export interface AdmitInput {
   role: Role;
@@ -39,6 +43,8 @@ export interface AdmitInput {
   failoverFrom: string | null;
   /** the dispatch id of the limited dispatch this stand-in replaces */
   failoverOf?: string;
+  /** the dispatching session (spec §3.3); absent means the session this process serves */
+  sessionId?: string | null;
 }
 
 /** Spec §3.3: SIGTERM, then SIGKILL this long after. */
@@ -52,7 +58,7 @@ function laneOwns(run: Run, lane: string): string[] {
     throw new CatherdError("E_LANE_INVALID", `no lane file lanes/${lane}.md`, {
       fix: "write it with write_run_file first",
     });
-  const owns = parseLaneHeader(readFileSync(file, "utf8")).owns;
+  const owns = assertLaneHeader(readFileSync(file, "utf8"), `lanes/${lane}.md`).owns;
   if (owns.length === 0)
     throw new CatherdError("E_LANE_INVALID", `lanes/${lane}.md has no Owns: line`, {
       fix: "add `Owns: <paths>` below the lane's title",
@@ -60,18 +66,29 @@ function laneOwns(run: Run, lane: string): string[] {
   return owns;
 }
 
+/** What a caller of `admit` does with each record `admit` itself writes (dispatch settles it). */
+export type OnRecorded = (d: Dispatch, record: RunRecord) => Promise<unknown>;
+
 /**
  * Records each finished dispatch of the run that has none yet, as reconcile does, so one whose waiter died
- * never blocks its name or lane. Before the admission lock: a finalize may wait on another's claim. One that
- * throws is skipped and stays pending, so the refusal still names it.
+ * never blocks its name or lane, and hands each record to `onRecorded` (the caller settles it, so its owner is
+ * told). Before the admission lock: a finalize may wait on another's claim. One that throws is skipped and
+ * stays pending, so the refusal still names it; an `onRecorded` that throws never fails the admit.
  */
-async function finalizeFinished(run: Run, now: number): Promise<void> {
+async function finalizeFinished(run: Run, now: number, onRecorded?: OnRecorded): Promise<void> {
   for (const d of pendingDispatches(run, now)) {
     if (d.state !== "finished") continue;
+    let record: RunRecord;
     try {
-      await finalizeDispatch(run, d);
+      record = await finalizeDispatch(run, d);
     } catch {
       // stays pending: admission refuses its name and lane, and names it
+      continue;
+    }
+    try {
+      await onRecorded?.(d, record);
+    } catch (e) {
+      log("warn", "admit", { run: run.id, name: d.admit.name, error: errorMessage(e) });
     }
   }
 }
@@ -109,7 +126,12 @@ async function prepared(adapter: BackendAdapter, req: Parameters<NonNullable<Bac
  * Spec §4.4 step 1. The checks that read shared state and the write that makes the dispatch live
  * happen under the run's admission lock, so parallel dispatches always see each other (audit C1).
  */
-export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: Dispatch; specPath: string }> {
+export async function admit(
+  deps: Deps,
+  run: Run,
+  i: AdmitInput,
+  onRecorded?: OnRecorded,
+): Promise<{ d: Dispatch; specPath: string }> {
   assertId("role name", i.name);
   if (i.lane !== null) assertId("lane", i.lane);
   const rung = parseRung(i.rung);
@@ -151,6 +173,7 @@ export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: D
   const plan = adapter.plan({
     rung,
     access: rc.access,
+    network: rc.network !== false,
     thread: i.thread,
     isolated,
     repo: run.meta.repo,
@@ -159,7 +182,8 @@ export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: D
     dispatchDir: dir,
   });
 
-  await finalizeFinished(run, deps.now());
+  await finalizeFinished(run, deps.now(), onRecorded);
+  const sessionId = i.sessionId !== undefined ? i.sessionId : (currentSession(deps)?.sessionId ?? null);
   return withFileLock(runPaths(run.dir).admission, async () => {
     // A dispatch blocks until its record is written, not only while it runs: its finalizer diffs the
     // tree after the exit, so a later dispatch's writes must not land in between. A finished one here
@@ -179,7 +203,7 @@ export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: D
           fix:
             same.state === "finished"
               ? `its record could not be written; see ${same.dir}, and retry`
-              : `wait for it, or cancel(run, "${i.name}")`,
+              : `its record is announced when it finishes; or cancel(run, "${i.name}")`,
         },
       );
     for (const d of pending) {
@@ -219,9 +243,11 @@ export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: D
       admittedAt: new Date(deps.now()).toISOString(),
       repo: run.meta.repo,
       before: await statusSnapshot(run.meta.repo),
+      ...(sessionId ? { sessionId } : {}),
     };
     ensurePrivateDir(dir);
-    writeTextAtomic(p.brief, i.brief);
+    // spec 1.1 §6: every brief ends with its role's reply contract, failover stand-ins' included
+    writeTextAtomic(p.brief, withReplyContract(i.role, i.brief));
     // Spec §10.4: the adapter's overrides only; the supervisor adds its own inherited env at spawn
     // time (src/entry/supervise-command.ts), so no credential is ever written to disk. 0600 all the same.
     writeJsonAtomic(
@@ -244,7 +270,7 @@ export async function admit(deps: Deps, run: Run, i: AdmitInput): Promise<{ d: D
       { mode: 0o600 },
     );
     // the collect mark before admit.json: no admitted dispatch ever exists without it, so a process that
-    // dies before launching it still leaves a record (lost, once its start grace passes) for a `wait`
+    // dies before launching it still leaves a record (lost, once its start grace passes), unread
     markForCollect(dir);
     writeJsonAtomic(admitPath(dir), admitted);
     setLatest(run, i.name, id);