@erclx/canon 5.26.0 → 5.28.0

package/src/sandbox/headless/watch.ts

@@ -0,0 +1,145 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/** Path to content hash, one entry per regular file. */
+export type Manifest = ReadonlyMap<string, string>
+
+/**
+ * Hashes every regular file under `base`, keyed by its path relative to it, for
+ * the top-level entries `keep` admits. A symlink is neither followed nor
+ * hashed, matching `find -type f`.
+ */
+function hashFiles(base: string, keep: (name: string) => boolean): Manifest {
+  const manifest = new Map<string, string>()
+  const pending = readdirSync(base, { withFileTypes: true })
+    .filter((entry) => keep(entry.name))
+    .map((entry) => ({ entry, dir: base }))
+
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    const path = join(next.dir, next.entry.name)
+    if (next.entry.isDirectory()) {
+      for (const entry of readdirSync(path, { withFileTypes: true }))
+        pending.push({ entry, dir: path })
+    } else if (next.entry.isFile()) {
+      const hash = createHash('sha1').update(readFileSync(path)).digest('hex')
+      manifest.set(relative(base, path), hash)
+    }
+  }
+
+  return new Map([...manifest].sort(([a], [b]) => (a < b ? -1 : 1)))
+}
+
+/**
+ * Records a hash per file so the post-run comparison can name what the session
+ * wrote. A diff against `refs/sandbox/baseline` cannot stand in for this: an arm
+ * that sets SANDBOX_SKIP_AUTO_COMMIT leaves its last stage uncommitted, so the
+ * fixtures the harness staged would read as session writes.
+ */
+export function snapshotTree(dir: string): Manifest {
+  return hashFiles(dir, (name) => name !== '.git')
+}
+
+/**
+ * Reports both sides of a change, so a deletion is a write. Reporting only the
+ * after side would let a file removed outside the declared scope produce no
+ * assertion at all, which is the one way this check stayed weaker than the
+ * permission scoping it replaced. A modified file differs on both sides and
+ * reports once.
+ */
+export function writesBetween(before: Manifest, after: Manifest): string[] {
+  const paths = new Set([...before.keys(), ...after.keys()])
+
+  return [...paths]
+    .filter((path) => before.get(path) !== after.get(path))
+    .sort()
+}
+
+/**
+ * The roots a run must not write shared session scratch to. `snapshotTree`
+ * reads the sandbox alone, so before this a session that resolved that scratch
+ * against a toolkit root wrote where no manifest looked: the run reported
+ * success, the write list came back empty, and `write_scope` had nothing to
+ * assert against.
+ *
+ * It makes an escape visible rather than impossible. A session can write to a
+ * home directory, to a sibling worktree, or to any path outside these roots, and
+ * none of that is watched. The standing limits in
+ * `canon/context/sandbox/overview.md` carry what stays invisible.
+ *
+ * A linked worktree is the normal place to develop this repository, and the
+ * rule an escaping session follows sends scratch to the main root rather than to
+ * the worktree it was launched from, so the main root joins the list whenever it
+ * differs.
+ */
+export function escapeRoots(projectRoot: string): string[] {
+  const listing = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+  })
+  const line = (listing.stdout ?? '')
+    .split('\n')
+    .find((l) => l.startsWith('worktree '))
+  const mainRoot = line?.slice('worktree '.length)
+
+  return mainRoot === undefined || mainRoot === '' || mainRoot === projectRoot
+    ? [projectRoot]
+    : [projectRoot, mainRoot]
+}
+
+/**
+ * The four directories the seed's shared-scratch rule names, and the whole of
+ * where an escape lands. A session that resolves that rule against a toolkit
+ * root writes here and nowhere else, so watching these rather than the whole
+ * root costs no detection.
+ *
+ * It buys the difference between a signal and noise. Nothing distinguishes the
+ * spawned session's writes from the operator's own, so a watch over the whole
+ * root reports ordinary editing during a run as an escape. Measured 2026-08-02:
+ * three runs against the relocated sandbox all wrote their report to the right
+ * place, and two of the three still reported an escape under the wide watch,
+ * naming a context entry being edited in the session that launched them.
+ *
+ * The scope stated for an arm author: `escapeRoots` times two, these times four.
+ * This watch reaches nothing past those eight destinations, so a nested run's
+ * own escape is invisible here whether or not an arm declares `escape_scope`. A
+ * nested background dispatch reports through `sessions` instead, from
+ * `dispatch.ts`, so the key defined against this file-write watch keeps one
+ * meaning. An arm whose skill is meant to reach past the sandbox tree declares
+ * `escape_scope` in its `expect.toml`, which bounds a legitimate write rather
+ * than the run. Read `canon/context/sandbox/isolation.md` and
+ * `canon/context/sandbox/coverage/workflow-arms.md` before writing a claim past
+ * that.
+ */
+export const ESCAPE_SCRATCH_DIRS = [
+  '.canon/plans',
+  '.canon/review',
+  '.canon/memory',
+  '.canon/tasks',
+] as const
+
+export interface RootSnapshot {
+  readonly manifest: Manifest
+  /**
+   * The root held at least one of the four directories. A root with none of
+   * them contributes no manifest and no diff, which reads identically to a watch
+   * that ran clean, so `checkEscapeScope` needs this to tell "watched and clean"
+   * from "nothing to watch" apart.
+   */
+  readonly isWatched: boolean
+}
+
+export function snapshotRoot(dir: string): RootSnapshot {
+  const targets = ESCAPE_SCRATCH_DIRS.filter((sub) =>
+    existsSync(join(dir, sub)),
+  )
+  if (targets.length === 0) return { manifest: new Map(), isWatched: false }
+
+  const manifest = new Map<string, string>()
+  for (const sub of targets)
+    for (const [path, hash] of hashFiles(join(dir, sub), () => true))
+      manifest.set(`${sub}/${path}`, hash)
+
+  return { manifest, isWatched: true }
+}

package/src/sandbox/hooks.ts

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 
 /**
  * The bash entry a scenario's hooks run through. Scenarios and the library they

package/src/sandbox/provision.ts

@@ -4,13 +4,21 @@ import {
   copyFileSync,
   existsSync,
   mkdirSync,
-  readdirSync,
   rmSync,
-  statSync,
   writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
 import { probeScenario, stageScenario } from '@/sandbox/hooks'
+import {
+  FIXTURE_SUFFIX,
+  FIXTURES_DIR,
+  listFixtureFiles,
+  loadScenario,
+  resolveScenarioFile,
+  type ScenarioDefinition,
+  scenarioExports,
+  stageScenarioInProcess,
+} from '@/sandbox/scenario'
 import { assertSandboxDirSafe, sandboxRoots, sandboxTree } from '@/sandbox/tree'
 import {
   intro,
@@ -26,16 +34,16 @@ import {
 
 /**
  * Provisions one scenario into the sandbox tree, and resets or cleans that tree.
- * Each scenario's hooks run in bash through `sandbox-hook.sh`, and everything
- * between them runs here, in the order the retired bash dispatcher held.
+ * A bash scenario's hooks run through `sandbox-hook.sh` and a TypeScript one's
+ * arm runs in process through `scenario.ts`, and everything between them runs
+ * here, in the order the retired bash dispatcher held.
  *
  * Narration is part of the contract. `canon sandbox equivalence` compares the
  * log line for line against the bash harness, so every message, its frame
  * glyph, and its position in the order stays as that harness wrote it.
  */
 
-const ANCHOR_FIXTURE_PARTS = ['sandbox', 'fixtures', 'anchor', 'create']
-const FIXTURE_SUFFIX = '.fixture'
+const ANCHOR_FIXTURE_PARTS = ['sandbox', FIXTURES_DIR, 'anchor', 'create']
 const SKILL_PATHSPEC = 'claude/skills/**/SKILL.md'
 
 /**
@@ -98,15 +106,6 @@ function finish(message: string): void {
   process.stderr.write(`\n${GREEN}${message}${NC}\n`)
 }
 
-function listFixtureFiles(dir: string): string[] {
-  if (!existsSync(dir)) return []
-
-  return (readdirSync(dir, { recursive: true, encoding: 'utf8' }) as string[])
-    .map((path) => join(dir, path))
-    .filter((path) => statSync(path).isFile())
-    .sort()
-}
-
 function stageAnchorTree(
   root: string,
   sandbox: string,
@@ -273,12 +272,22 @@ function setupAssets(
  * tree, so a scenario exercises the branch's skill rather than the installed
  * plugin's. The merge base against `origin/main` comes first, so a local `main`
  * trailing the remote does not pull in skills other merged branches changed.
+ * A headless run skips it, since a copied body alone shadows the plugin's whole
+ * skill folder and its relative citations then resolve to nothing.
  */
 export function injectChangedSkills(
   root: string,
   sandbox: string,
   isSkipAutoCommit: boolean,
+  isSkipInject = false,
 ): string[] {
+  if (isSkipInject) {
+    logInfo(
+      'Skipped dev skill injection: the run resolves skills through --plugin-dir',
+    )
+    return []
+  }
+
   const base = (
     readGit(root, ['merge-base', 'HEAD', 'origin/main']) ??
     readGit(root, ['merge-base', 'HEAD', 'main']) ??
@@ -392,12 +401,57 @@ interface Scenario {
   readonly arm: string | undefined
 }
 
-function provisionScenario(
+/**
+ * Reads what a scenario declares ahead of provisioning: its config exports and
+ * whether it stages from the anchor. A bash scenario answers through the probe,
+ * and a TypeScript one from its module, which is also what its stage runs.
+ */
+function declareScenario(
+  root: string,
+  scenario: Scenario,
+  env: NodeJS.ProcessEnv,
+):
+  | { kind: 'sh'; file: string; isAnchor: boolean }
+  | { kind: 'ts'; definition: ScenarioDefinition; isAnchor: boolean } {
+  const name = `${scenario.category}/${scenario.command}`
+  const resolved = resolveScenarioFile(
+    join(root, 'sandbox'),
+    scenario.category,
+    scenario.command,
+  )
+  if (!resolved.ok && resolved.reason === 'ambiguous')
+    fail(
+      `Sandbox script ${name} exists as both .sh and .ts. Delete the one the port replaced.`,
+    )
+  if (!resolved.ok) fail(`Sandbox script not found: ${name}`)
+
+  if (resolved.kind === 'sh') {
+    const probe = probeScenario(resolved.file, env)
+    if (!probe.ok) throw new Halt(probe.status)
+    Object.assign(env, probe.exports)
+
+    return { kind: 'sh', file: resolved.file, isAnchor: probe.isAnchor }
+  }
+
+  let definition: ScenarioDefinition
+  try {
+    definition = loadScenario(resolved.file)
+  } catch (error) {
+    fail(
+      `Could not load scenario ${name}: ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+  Object.assign(env, scenarioExports(definition, root, env))
+
+  return { kind: 'ts', definition, isAnchor: definition.anchor === true }
+}
+
+async function provisionScenario(
   root: string,
   sandbox: string,
   scenario: Scenario,
   baseEnv: NodeJS.ProcessEnv,
-): void {
+): Promise<void> {
   const env: NodeJS.ProcessEnv = { ...baseEnv }
   if (scenario.arm !== undefined) {
     env.SANDBOX_SCENARIO = scenario.arm
@@ -405,13 +459,7 @@ function provisionScenario(
   }
 
   const sandboxDir = join(root, 'sandbox')
-  const file = join(sandboxDir, scenario.category, `${scenario.command}.sh`)
-  if (!existsSync(file) || !statSync(file).isFile())
-    fail(`Sandbox script not found: ${scenario.category}/${scenario.command}`)
-
-  const probe = probeScenario(file, env)
-  if (!probe.ok) throw new Halt(probe.status)
-  Object.assign(env, probe.exports)
+  const declared = declareScenario(root, scenario, env)
 
   if (!existsSync(sandboxDir))
     fail(`Sandbox directory not found at: ${sandboxDir}`)
@@ -425,20 +473,33 @@ function provisionScenario(
   }
 
   logStep(`Provisioning ${scenario.category}:${scenario.command}`)
-  if (probe.isAnchor) stageAnchorTree(root, sandbox, env)
+  if (declared.isAnchor) stageAnchorTree(root, sandbox, env)
   else initEmptyTree(sandbox, env)
   configureCredentials(sandbox, env)
   setupAssets(root, sandbox, env)
 
   // A scenario that execs a verb as its last step hands the run to that verb,
-  // whose own frame is the last one written, so nothing follows it here.
-  const staged = stageScenario(file, env)
+  // whose own frame is the last one written, so nothing follows it here. An
+  // in-process arm writes its exports straight into `env`.
+  const staged =
+    declared.kind === 'sh'
+      ? stageScenario(declared.file, env)
+      : {
+          ...(await stageScenarioInProcess(declared.definition, {
+            root,
+            dir: sandbox,
+            env,
+            arm: scenario.arm,
+          })),
+          exports: {},
+        }
   if (staged.ending === 'replaced') throw new Halt(staged.status, false)
   if (staged.ending === 'exited') throw new Halt(staged.status)
   Object.assign(env, staged.exports)
 
   const isSkipAutoCommit = (env.SANDBOX_SKIP_AUTO_COMMIT ?? '') !== ''
-  injectChangedSkills(root, sandbox, isSkipAutoCommit)
+  const isSkipInject = (env.SANDBOX_SKIP_SKILL_INJECT ?? '') !== ''
+  injectChangedSkills(root, sandbox, isSkipAutoCommit, isSkipInject)
   must(commitScenarioChanges(sandbox, isSkipAutoCommit, env))
   tagBaseline(sandbox, env)
 
@@ -579,7 +640,7 @@ export async function runSandbox(
     }
 
     const { category, command } = parseTarget(request.target)
-    provisionScenario(
+    await provisionScenario(
       root,
       sandbox,
       { category, command, arm: request.arm },