catherd-cli 0.2.1 → 1.1.0

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/proc.ts

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { scrubSecrets } from "./env.ts";
+
+/** A string that differs between two processes that held the same pid: /proc starttime, else `ps lstart`. */
+export function processStartTime(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // Field 22 (starttime); the command name in field 2 may hold spaces, so split after its ')'.
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return fields[19] ?? null;
+  } catch {
+    return psStartTime(pid);
+  }
+}
+
+let ownStart: string | null = null;
+/**
+ * This process's own identity for the leases and claims it writes. The start time is read once and kept:
+ * on macOS `ps` can fail for a moment, and a second read must never make a process a stranger to itself.
+ */
+export function selfIdentity(): { pid: number; startTime: string | null } {
+  ownStart ??= processStartTime(process.pid);
+  return { pid: process.pid, startTime: ownStart };
+}
+
+/** `ps` by absolute path where it lives, so a caller with a narrow PATH (a test, a sandbox) still finds it. */
+const PS = existsSync("/bin/ps") ? "/bin/ps" : "ps";
+
+/** `ps lstart` for a pid, or null when ps is missing or fails (macOS has no /proc). */
+export function psStartTime(
+  pid: number,
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  try {
+    // lstart is printed in the local time zone and locale: pin both so every process agrees.
+    const ps = Bun.spawnSync([PS, "-o", "lstart=", "-p", String(pid)], {
+      stdout: "pipe",
+      stderr: "ignore",
+      env: { ...scrubSecrets(env), LC_ALL: "C", TZ: "UTC" },
+    });
+    const out = ps.success ? ps.stdout.toString("utf8").trim() : "";
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Only an integer >= 1 names one real process: 0 and negatives address groups. Pid 1 is valid
+ * (catherd may be a container's entrypoint); only killGroup refuses it, since kill(-1) signals everything.
+ */
+export const isValidPid = (pid: unknown): pid is number => Number.isInteger(pid) && (pid as number) >= 1;
+
+/**
+ * Whether a live pid is still the process recorded with `recorded`. A start time that cannot be read now
+ * (`ps` fails for a moment on macOS) counts as the same process: a live lock holder or worker is never
+ * taken for dead, and the worst case is a lock that times out with E_IO_LOCK instead.
+ */
+export const sameProcess = (recorded: string | null, current: string | null): boolean =>
+  recorded === null || current === null || current === recorded;
+
+/**
+ * For a signal only: the pid is live and its start time reads back exactly as recorded. An unreadable or
+ * unrecorded start time is not a match, since the pid may belong to another process by now.
+ */
+export const surelySame = (recorded: string | null, current: string | null): boolean =>
+  recorded !== null && current !== null && current === recorded;
+
+export function isSurelyAlive(pid: number, startTime: string | null): boolean {
+  return isAlive(pid, startTime) && surelySame(startTime, processStartTime(pid));
+}
+
+/** Whether /proc shows the pid as a zombie: dead, only never reaped (a pid 1 that reaps no orphans). */
+function isZombie(pid: number): boolean {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3) === "Z";
+  } catch {
+    return false;
+  }
+}
+
+export function isAlive(pid: number, startTime: string | null): boolean {
+  if (!isValidPid(pid)) return false;
+  try {
+    process.kill(pid, 0);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EPERM") return false;
+  }
+  if (isZombie(pid)) return false;
+  return startTime === null || sameProcess(startTime, processStartTime(pid));
+}
+
+/**
+ * Signals the process group a detached child leads (pgid === pid), falling back to the pid alone. No
+ * group (ESRCH) means its leader is gone too, and that pid may belong to another process by now.
+ */
+export function killGroup(pid: number, signal: NodeJS.Signals = "SIGTERM"): void {
+  if (!isValidPid(pid) || pid === 1) return;
+  try {
+    process.kill(-pid, signal);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ESRCH") return;
+    try {
+      process.kill(pid, signal);
+    } catch {
+      // already gone
+    }
+  }
+}

package/src/infra/store.ts

@@ -0,0 +1,229 @@
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  existsSync,
+  fchmodSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { dirname, sep } from "node:path";
+import { z } from "zod";
+import { CatherdError, UPGRADE } from "../domain/errors.ts";
+import { configDir, dataDir } from "./paths.ts";
+
+// Audit S2: catherd's dirs hold briefs, argv, stderr tails and logs, so they are 0700 and its files 0600.
+export const PRIVATE_DIR = 0o700;
+export const PRIVATE_FILE = 0o600;
+
+const tightened = new Set<string>();
+/** Once per process per dir: `dir` at 0700, if an older catherd left it open to others. */
+function tighten(dir: string): void {
+  if (tightened.has(dir)) return;
+  tightened.add(dir);
+  try {
+    if (statSync(dir).mode & 0o077) chmodSync(dir, PRIVATE_DIR);
+  } catch {
+    // not ours to fix (another owner, a read-only mount): the files inside are still 0600
+  }
+}
+
+/**
+ * `dir` and any missing parent, created 0700. `mkdirSync` leaves an existing dir as it is, so under
+ * catherd's config or data dir, `dir` and every dir up to that root are tightened to 0700 (a 0.x install).
+ */
+export function ensurePrivateDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR });
+  for (const root of [configDir(), dataDir()]) {
+    if (dir !== root && !dir.startsWith(root + sep)) continue;
+    for (let d = dir; d.length >= root.length; d = dirname(d)) {
+      tighten(d);
+      if (d === root) break;
+    }
+  }
+}
+
+/** `file` at 0600 when it exists and others may read it: a file another program wrote into catherd's dirs. */
+export function makePrivate(file: string): void {
+  try {
+    if (statSync(file).mode & 0o077) chmodSync(file, PRIVATE_FILE);
+  } catch {
+    // missing, or not ours: its dir is 0700 all the same
+  }
+}
+
+/** `mode` (0600 by default) is the file's exact permission bits (umask aside), set before any byte is written. */
+export function writeTextAtomic(file: string, text: string, o: { mode?: number } = {}): void {
+  const mode = o.mode ?? PRIVATE_FILE;
+  ensurePrivateDir(dirname(file));
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  const fd = openSync(tmp, "w", mode);
+  try {
+    fchmodSync(fd, mode);
+    writeSync(fd, text);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, file);
+}
+
+export const writeJsonAtomic = (file: string, value: unknown, o: { mode?: number } = {}): void =>
+  writeTextAtomic(file, `${JSON.stringify(value, null, 2)}\n`, o);
+
+function newer(file: string, found: number, current: number): CatherdError {
+  return new CatherdError(
+    "E_CONFIG_NEWER_SCHEMA",
+    `${file} has schema ${found}, newer than this catherd (${current})`,
+    {
+      fix: `upgrade catherd: ${UPGRADE}`,
+    },
+  );
+}
+
+/**
+ * The parsed content of a JSON file catherd keeps. The error never carries the parser's message: it
+ * quotes the offending text, which for a key pasted into credentials.json is the key itself (audit B1).
+ */
+export function readJsonFile(file: string, fix = `fix or delete ${file}`): unknown {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code ?? "an I/O error";
+    throw new CatherdError("E_CONFIG_INVALID", `${file} cannot be read (${code})`, { fix });
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is not valid JSON`, { fix });
+  }
+}
+
+/**
+ * Reads a `"schema": n` JSON file. Schemas are loose objects, so unknown fields survive a rewrite.
+ * `fix` replaces the default fix of an unreadable or invalid file.
+ */
+export function readVersioned<T>(
+  file: string,
+  schema: z.ZodType<T>,
+  current: number,
+  o: { fix?: string } = {},
+): T {
+  const fix = o.fix ?? `fix or delete ${file}`;
+  const raw = readJsonFile(file, fix);
+  const found = (raw as { schema?: unknown } | null)?.schema;
+  if (typeof found === "number" && found > current) throw newer(file, found, current);
+  const r = schema.safeParse(raw);
+  if (!r.success)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is invalid:\n${z.prettifyError(r.error)}`, { fix });
+  return r.data;
+}
+
+/** True when `file` exists, is non-empty and does not end in a newline (a crash-truncated tail). */
+function endsMidLine(file: string): boolean {
+  let size: number;
+  try {
+    size = statSync(file).size;
+  } catch {
+    return false;
+  }
+  if (size === 0) return false;
+  const fd = openSync(file, "r");
+  try {
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last[0] !== 0x0a;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * One `appendFileSync` per row, so a crash can only ever truncate the last line. A truncated
+ * tail left by an earlier crash is ended first, in the same write, so the new row stays whole.
+ */
+export function appendJsonl(file: string, value: unknown): void {
+  ensurePrivateDir(dirname(file));
+  const prefix = endsMidLine(file) ? "\n" : "";
+  appendPrivate(file, `${prefix}${JSON.stringify(value)}\n`);
+}
+
+const madePrivate = new Set<string>();
+/**
+ * Appends `text` to `file`, created 0600. `appendFileSync`'s mode only applies to a new file, so one
+ * an older catherd left open to others is tightened first, once per process.
+ */
+export function appendPrivate(file: string, text: string): void {
+  ensurePrivateDir(dirname(file));
+  if (!madePrivate.has(file)) {
+    makePrivate(file);
+    madePrivate.add(file);
+  }
+  appendFileSync(file, text, { mode: PRIVATE_FILE });
+}
+
+export function ensureJsonlHeader(file: string, kind: string): void {
+  ensurePrivateDir(dirname(file));
+  try {
+    // O_APPEND: a row another process appends between the create and this write is kept, not overwritten
+    const fd = openSync(file, "ax", PRIVATE_FILE);
+    try {
+      writeSync(fd, `${JSON.stringify({ schema: 1, kind })}\n`);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+  }
+}
+
+const isHeader = (v: unknown): v is { schema: number; kind: string } =>
+  typeof v === "object" &&
+  v !== null &&
+  Object.keys(v).length === 2 &&
+  typeof (v as { schema?: unknown }).schema === "number" &&
+  typeof (v as { kind?: unknown }).kind === "string";
+
+/** The non-blank lines of `file`; none when it cannot be read (missing, or not written yet). */
+export function nonBlankLines(file: string): string[] {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return [];
+  }
+  return text.split("\n").filter((l) => l.trim());
+}
+
+export function readJsonl<T>(file: string, current = 1): { kind: string | null; rows: T[]; corrupt: number } {
+  if (!existsSync(file)) return { kind: null, rows: [], corrupt: 0 };
+  const rows: T[] = [];
+  let kind: string | null = null;
+  let corrupt = 0;
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line) => {
+    if (!line.trim()) return;
+    let v: unknown;
+    try {
+      v = JSON.parse(line);
+    } catch {
+      corrupt++;
+      return;
+    }
+    // the header is first unless another writer's row won the race to a new file (ensureJsonlHeader)
+    if (kind === null && isHeader(v)) {
+      if (v.schema > current) throw newer(file, v.schema, current);
+      kind = v.kind;
+      return;
+    }
+    rows.push(v as T);
+  });
+  return { kind, rows, corrupt };
+}