@erclx/canon 5.25.0 → 5.27.0

package/src/sandbox/headless/dispatch.ts

@@ -0,0 +1,264 @@
+import { spawnSync } from 'node:child_process'
+import {
+  chmodSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/*
+ * The bound on a nested background dispatch, and the recording behind it.
+ *
+ * An arm invoked without the narration its fixture states dispatched a real
+ * `claude --bg` session against the machine's own process table, and nothing in
+ * the harness noticed. The write and escape watches in `watch.ts` read the
+ * sandbox and four scratch directories, and a dispatched session writes into
+ * none of them, so the escape watch reported clean throughout and was right to.
+ * The run spent real cost until a person found it, and `SIGTERM` alone did not
+ * end it.
+ *
+ * The three mechanisms sit here rather than in `run.ts`, the only caller, so
+ * each is reachable from a test that never launches a session: `dispatch.test.ts`
+ * drives the shim against a stub binary and the reap against a `sleep`, where
+ * proving either through the runner would mean spawning the thing the bound
+ * exists to prevent.
+ */
+
+/**
+ * The prevention. Writes a `claude` that refuses a background dispatch by flag
+ * name and delegates everything else, for the runner to place first on the PATH
+ * of the session it spawns. It stays a bash file, since it stands in for a
+ * binary any shell in the session may exec.
+ *
+ * The real binary is baked into the file rather than passed through the
+ * environment. An env var carrying it would sit in the spawned session's own
+ * environment, which hands any arm the exact string that walks around the shim.
+ *
+ * It names itself in its refusal. No arm shells to `claude` today, and one
+ * written tomorrow would meet this and read it as the harness being broken
+ * unless the text says which layer refused and why.
+ *
+ * It is not the whole bound. A dispatch reaching the binary by an absolute path
+ * never resolves through PATH at all, which is what `reapProcessGroup`
+ * backstops.
+ */
+export function installDispatchShim(dir: string, real: string): void {
+  const shim = [
+    '#!/usr/bin/env bash',
+    '# Generated by installDispatchShim in src/sandbox/headless/dispatch.ts.',
+    'for arg in "$@"; do',
+    '  case "$arg" in',
+    '  --bg | --background)',
+    '    echo "canon sandbox harness: refusing $arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2',
+    '    exit 64',
+    '    ;;',
+    '  esac',
+    'done',
+    `exec ${shellQuote(real)} "$@"`,
+    '',
+  ].join('\n')
+
+  writeFileSync(join(dir, 'claude'), shim, 'utf8')
+  chmodSync(join(dir, 'claude'), 0o755)
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`
+}
+
+/** The process group `pid` belongs to, or undefined once it has exited. */
+export function processGroupOf(pid: number): string | undefined {
+  const ps = spawnSync('ps', ['-o', 'pgid=', '-p', String(pid)], {
+    encoding: 'utf8',
+  })
+  const pgid = (ps.stdout ?? '').trim()
+
+  return pgid === '' ? undefined : pgid
+}
+
+/**
+ * True while any live process still carries this group id. Reads the whole
+ * table rather than `ps -g`, which selects by session on some builds.
+ *
+ * A zombie does not count. A leader this process spawned and has not yet
+ * waited on stays in the table as one after the signal lands, and the wait
+ * below blocks the event loop that would collect it, so signal 0 alone reports
+ * a group that is already dead as a survivor.
+ */
+function processGroupAlive(pgid: number): boolean {
+  const ps = spawnSync('ps', ['-eo', 'pgid=,stat='], { encoding: 'utf8' })
+
+  return (ps.stdout ?? '').split('\n').some((line) => {
+    const [group, stat] = line.trim().split(/\s+/)
+    return group === String(pgid) && stat !== undefined && !stat.startsWith('Z')
+  })
+}
+
+/**
+ * Five seconds per signal. A shorter window reports a survivor for a process
+ * that was already exiting, and a longer one stalls a run whose verdict is
+ * already taken.
+ */
+function waitForGroupExit(pgid: number): void {
+  for (let waited = 0; waited < 20 && processGroupAlive(pgid); waited++)
+    Bun.sleepSync(250)
+}
+
+export type ReapState =
+  | 'clear'
+  | 'reaped-term'
+  | 'reaped-kill'
+  | 'survived'
+  | 'refused-own-group'
+
+/**
+ * The backstop. Signals a process group the runner created, escalating rather
+ * than sending one signal and reporting success, since the dispatch that
+ * produced this bound took two signals to reap.
+ *
+ * Returns its outcome and never throws. A survivor is something to report
+ * rather than a reason to abandon the verdict the run already took.
+ *
+ * The group has to be one the run created, and the refusal below is what makes
+ * that property travel with the function rather than living in one caller. The
+ * runner reports `inherited` when the session failed to lead a group of its
+ * own, which is a diagnosis; this is the floor under it, and under every caller
+ * after it, because the cost of getting the argument wrong is the operator's
+ * own shell.
+ *
+ * Synchronous, so a signal handler can run it before the process exits.
+ *
+ * What it cannot reach is a dispatch that called `setsid` on its way out, which
+ * leaves the group before this reads it. That is the half the shim covers.
+ */
+export function reapProcessGroup(pgid: number): ReapState {
+  if (String(pgid) === processGroupOf(process.pid)) return 'refused-own-group'
+  if (!processGroupAlive(pgid)) return 'clear'
+
+  signalGroup(pgid, 'SIGTERM')
+  waitForGroupExit(pgid)
+  if (!processGroupAlive(pgid)) return 'reaped-term'
+
+  signalGroup(pgid, 'SIGKILL')
+  waitForGroupExit(pgid)
+
+  return processGroupAlive(pgid) ? 'survived' : 'reaped-kill'
+}
+
+function signalGroup(pgid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(-pgid, signal)
+  } catch {
+    // The group emptied between the liveness read and the signal.
+  }
+}
+
+/**
+ * The client's own session registry, which is the only surface a nested
+ * dispatch leaves a trace on that this harness can read. It is client-owned and
+ * carries no contract, so a client that stops writing a record per session
+ * breaks the detection silently. That is why what reads it reports rather than
+ * asserts.
+ */
+export function sessionsDir(env: NodeJS.ProcessEnv = process.env): string {
+  const config = env.CLAUDE_CONFIG_DIR
+  const base =
+    config !== undefined && config !== ''
+      ? config
+      : join(env.HOME || homedir(), '.claude')
+
+  return join(base, 'sessions')
+}
+
+export interface SessionSnapshot {
+  /** Record names, sorted. */
+  readonly names: readonly string[]
+  /**
+   * The registry directory existed. An absent registry produces the same empty
+   * list a quiet run does, and the two mean opposite things, so the report
+   * carries this rather than letting an unwatched run read as a clean one.
+   */
+  readonly isWatched: boolean
+}
+
+/**
+ * Record names only, never hashes. A live session rewrites its own record on
+ * every status change, so a content manifest would name every session running
+ * beside this one, which is the noise the escape watch was already narrowed to
+ * avoid. A record that appears between the two snapshots is a session that
+ * started during the run, and that is the whole question.
+ */
+export function snapshotSessions(dir: string): SessionSnapshot {
+  if (!existsSync(dir)) return { names: [], isWatched: false }
+
+  const names = readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort()
+
+  return { names, isWatched: true }
+}
+
+/**
+ * The new side alone, unlike `writesBetween`. A record that vanished is a
+ * session that ended and a record that changed is one that was already
+ * running, and neither is a dispatch this run made.
+ */
+export function sessionsBetween(
+  before: SessionSnapshot,
+  after: SessionSnapshot,
+): string[] {
+  const seen = new Set(before.names)
+
+  return after.names.filter((name) => !seen.has(name))
+}
+
+/**
+ * The side `sessionsBetween` drops. A record present on both sides is a
+ * session that was already running before this run started and still was
+ * after, which rules it out as this run's own dispatch and rules it in as a
+ * witness able to explain a write the escape watch attributes to nobody.
+ */
+export function sessionsConcurrent(
+  before: SessionSnapshot,
+  after: SessionSnapshot,
+): string[] {
+  const seen = new Set(before.names)
+
+  return after.names.filter((name) => seen.has(name))
+}
+
+/**
+ * Turns a record name into a line a person can act on. The file can be gone by
+ * the time this reads it, since a session that started and exited inside the
+ * run takes its record with it, so an unreadable record still reports its name
+ * rather than dropping out of the list.
+ *
+ * One record is one line. The name is written by whatever peer claimed the
+ * session, so a newline inside it would split one record across two entries in
+ * a list every reader takes as one line each.
+ */
+export function describeSession(dir: string, name: string): string {
+  let record: unknown
+  try {
+    record = JSON.parse(readFileSync(join(dir, name), 'utf8'))
+  } catch {
+    return `${name}: record already gone`
+  }
+  if (typeof record !== 'object' || record === null || Array.isArray(record))
+    return `${name}: record already gone`
+
+  const fields = record as Record<string, unknown>
+  const label = (value: unknown, fallback: string): string =>
+    value === undefined || value === null || value === false
+      ? fallback
+      : typeof value === 'string'
+        ? value
+        : JSON.stringify(value)
+  const desc = `${label(fields.name, 'unnamed')} in ${label(fields.cwd, 'an unrecorded directory')}`
+
+  return `${name}: ${desc.replace(/\s+/g, ' ')}`
+}