@erclx/canon 5.26.0 → 5.28.0

package/src/records/size.ts

@@ -1,7 +1,7 @@
 import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
-import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
+import { RECORD_ROOTS, recordDir, SCRATCH } from '@/roots/record'
 import { candidateFolders } from '@/records/backup'
 
 /**

package/src/records/stale-canonical.ts

@@ -2,9 +2,9 @@ import { $ } from 'bun'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { readReviewed } from '@/records/stale'
-import { surfaceDir } from '@/surface-root'
+import { surfaceDir } from '@/roots/surface'
 
 /** The two records whose drift is identity rather than a stale path. */
 const CANONICAL_DOCS = ['REQUIREMENTS.md', 'ARCHITECTURE.md'] as const

package/src/records/stale.ts

@@ -8,7 +8,7 @@ import {
   recordDir,
   SCRATCH,
   spell,
-} from '@/record-root'
+} from '@/roots/record'
 
 /** The window after which a reviewed entry is due again, in days. */
 export const DEFAULT_REVIEW_DAYS = 30

package/src/records/validate.ts

@@ -6,7 +6,7 @@ import { linesOutsideFences } from '@/markdown/scan'
 import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
-} from '@/record-root'
+} from '@/roots/record'
 import { ATTRIBUTE_MARKER, governedPaths, readScope } from '@/standards/scope'
 import {
   TEACH_GLOSSARY,
@@ -39,7 +39,7 @@ export type RecordKind = (typeof RECORD_KINDS)[number]
  * the second, so one order serves both.
  *
  * Every other kind is a session record and takes the record roots instead,
- * resolved by `@/record-root`. Standards is the one kind that is tracked, so it
+ * resolved by `@/roots/record`. Standards is the one kind that is tracked, so it
  * does not move and spells its own two candidates here.
  */
 const STANDARDS_FOLDERS: readonly string[] = [

package/src/{project-root.ts → roots/project.ts}

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url'
  */
 export const PROJECT_ROOT = resolve(
   dirname(fileURLToPath(import.meta.url)),
-  '..',
+  '../..',
 )
 
 const readPackageName = (root: string): string | undefined => {

package/src/{record-root.ts → roots/record.ts}

@@ -57,7 +57,7 @@ const CANON_SCRATCH = 'tmp'
  * record root, which is the rule the move ran on. `rules`, `skills`, and
  * `hooks` stay under `.claude/` because the vendor reads them there, while
  * `context`, `wireframes`, and the loose documents are tracked surfaces that
- * `surface-root.ts` resolves under `canon/` instead. A seed and a
+ * `surface.ts` resolves under `canon/` instead. A seed and a
  * superseded-layout report each ask this rather than assuming a root.
  */
 export const RECORD_ENTRIES: readonly string[] = [

package/src/sandbox/coverage.ts

@@ -1,5 +1,10 @@
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import {
+  FIXTURES_DIR,
+  listCategories,
+  listScenarioFiles,
+} from '@/sandbox/scenario'
 
 /**
  * The arm a scenario declares when it carries no named arm. `expectFilePath`
@@ -8,9 +13,6 @@ import { join } from 'node:path'
  */
 export const DEFAULT_ARM = '(default)'
 
-/** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
-const FIXTURES_DIR = 'fixtures'
-
 export interface ScenarioCoverage {
   readonly category: string
   readonly command: string
@@ -41,15 +43,12 @@ function directories(path: string): string[] {
 function listScenarios(sandboxDir: string): ScenarioCoverage[] {
   const scenarios: ScenarioCoverage[] = []
 
-  for (const category of directories(sandboxDir)) {
-    if (category === FIXTURES_DIR) continue
-
-    const commands = readdirSync(join(sandboxDir, category), {
-      withFileTypes: true,
-    })
-      .filter((entry) => entry.isFile() && entry.name.endsWith('.sh'))
-      .map((entry) => entry.name.replace(/\.sh$/, ''))
-      .sort()
+  for (const category of listCategories(sandboxDir)) {
+    // A stem in both forms counts once, and provisioning refuses it by name.
+    const { scenarios: files, ambiguous } = listScenarioFiles(
+      join(sandboxDir, category),
+    )
+    const commands = [...files.map((f) => f.command), ...ambiguous].sort()
 
     for (const command of commands) {
       scenarios.push({ category, command, armed: [] })

package/src/sandbox/equivalence.ts

@@ -17,11 +17,15 @@ import {
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { collectCoverage, DEFAULT_ARM } from '@/sandbox/coverage'
+import {
+  armNames,
+  listCategories,
+  listScenarioFiles,
+  loadScenario,
+  type ScenarioKind,
+} from '@/sandbox/scenario'
 import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
-/** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
-const FIXTURES_DIR = 'fixtures'
-
 /** One arm provisions inside this budget on each side, or reads as a failed run. */
 const PROVISION_TIMEOUT_MS = 120_000
 
@@ -149,13 +153,6 @@ export function armKey(arm: Arm): string {
   return arm.arm === undefined ? scenario : `${scenario}/${arm.arm}`
 }
 
-function directories(path: string): string[] {
-  return readdirSync(path, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort()
-}
-
 /**
  * Reads the quoted arguments of `select_or_route_scenario`, joining a call that
  * continues across backslash-newline pairs. The first argument is the prompt and
@@ -201,6 +198,42 @@ function matchesArm(arm: Arm, targets: readonly string[]): boolean {
   return scoped.includes(armKey(arm))
 }
 
+/**
+ * Reads a scenario's arm names and anchor flag: off a bash file's source, and
+ * off a TypeScript module's own keys, which is what its stage routes on.
+ */
+function readArms(
+  file: string,
+  kind: ScenarioKind,
+):
+  | { ok: true; anchor: boolean; names: string[] }
+  | { ok: false; error: string } {
+  if (kind === 'sh') {
+    const source = readFileSync(file, 'utf8')
+
+    return {
+      ok: true,
+      anchor: /^use_anchor\s*\(\)/m.test(source),
+      names: parseArmNames(source),
+    }
+  }
+
+  try {
+    const definition = loadScenario(file)
+
+    return {
+      ok: true,
+      anchor: definition.anchor === true,
+      names: armNames(definition),
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
 /**
  * Lists every provision a target names, from the scenario source. An armed arm
  * that `canon sandbox coverage` reports and this list lacks is returned as an
@@ -216,25 +249,23 @@ export function enumerateArms(
   const errors: string[] = []
   const coverage = collectCoverage(root)
 
-  for (const category of directories(sandboxDir)) {
-    if (category === FIXTURES_DIR) continue
-
-    const commands = readdirSync(join(sandboxDir, category), {
-      withFileTypes: true,
-    })
-      .filter((f) => f.isFile() && f.name.endsWith('.sh'))
-      .map((f) => f.name.replace(/\.sh$/, ''))
-      .sort()
+  for (const category of listCategories(sandboxDir)) {
+    const { scenarios, ambiguous } = listScenarioFiles(
+      join(sandboxDir, category),
+    )
+    for (const command of ambiguous)
+      if (matchesTarget(category, command, targets))
+        errors.push(`${category}:${command} exists as both .sh and .ts`)
 
-    for (const command of commands) {
+    for (const { command, file, kind } of scenarios) {
       if (!matchesTarget(category, command, targets)) continue
 
-      const source = readFileSync(
-        join(sandboxDir, category, `${command}.sh`),
-        'utf8',
-      )
-      const anchor = /^use_anchor\s*\(\)/m.test(source)
-      const names = parseArmNames(source)
+      const declared = readArms(file, kind)
+      if (!declared.ok) {
+        errors.push(`${category}:${command} did not load: ${declared.error}`)
+        continue
+      }
+      const { anchor, names } = declared
 
       const found: Arm[] =
         names.length === 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, ' ')}`
+}