@erclx/canon 5.32.0 → 5.33.0

package/src/records/validate.ts

@@ -22,7 +22,6 @@ export const RECORD_KINDS = [
   'plans',
   'groundwork',
   'intake',
-  'memory',
   'standards',
   'teach',
 ] as const
@@ -60,7 +59,6 @@ export type ValidateRefusal = (typeof VALIDATE_REFUSALS)[number]
 export const FINDING_KINDS = [
   'name-malformed',
   'title-missing',
-  'title-is-slug',
   'section-missing',
   'scope-unanchored',
   'entry-unreasoned',
@@ -72,7 +70,6 @@ export const FINDING_KINDS = [
   'state-missing',
   'closing-partial',
   'item-incomplete',
-  'category-mismatch',
   'operator-call-phrasing',
   'batch-unsplit',
   'source-unquoted',
@@ -81,22 +78,12 @@ export const FINDING_KINDS = [
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
 
-/**
- * The transforms `migrate.ts` carries. Most finding kinds have none, since a
- * transform is only safe where the old shape is recoverable from the file
- * itself, so this stays optional on `Finding` rather than required.
- */
-export const FINDING_REMEDIES = ['category-from-name'] as const
-
-export type FindingRemedy = (typeof FINDING_REMEDIES)[number]
-
 export interface Finding {
   readonly kind: FindingKind
   /** The record the finding sits in, relative to the validated folder. */
   readonly record: string
   readonly subject: string
   readonly message: string
-  readonly remedy?: FindingRemedy
 }
 
 export interface ValidateReport {
@@ -214,9 +201,8 @@ function finding(
   record: string,
   subject: string,
   message: string,
-  remedy?: FindingRemedy,
 ): Finding {
-  return { kind, record, subject, message, remedy }
+  return { kind, record, subject, message }
 }
 
 async function listMarkdown(dir: string): Promise<string[]> {
@@ -934,169 +920,6 @@ async function checkWorkspace(dir: string, slug: string): Promise<Finding[]> {
   ]
 }
 
-const MEMORY_INDEX = 'index.md'
-const MEMORY_FIELDS = ['title', 'description', 'category'] as const
-
-/**
- * The filename prefix and the `category` field are one fact in two spellings,
- * so the map is the whole type list and the comparison against it is what
- * catches a prefix outside the set, a field disagreeing with the prefix, and a
- * casing drift that would open a second group in the catalog.
- */
-export const CATEGORY_BY_TYPE = {
-  feedback: 'Feedback',
-  project: 'Project',
-  user: 'User',
-  reference: 'Reference',
-} as const
-
-export type MemoryType = keyof typeof CATEGORY_BY_TYPE
-
-const MEMORY_TYPES = Object.keys(CATEGORY_BY_TYPE) as readonly MemoryType[]
-
-export const MEMORY_NAME = /^([a-z]+)-[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
-
-/** The two markers a rule-bearing body carries, on top of the rule line itself. */
-const MEMORY_MARKERS = ['**Why:**', '**How to apply:**'] as const
-
-export function memoryType(value: string): MemoryType | undefined {
-  return MEMORY_TYPES.find((type) => type === value)
-}
-
-/**
- * The one missing-field shape `migrate.ts` can repair: `category` alone,
- * recoverable from the same filename prefix `checkMemory` already read it
- * from. `title` and `description` are prose nobody wrote down, so a finding
- * naming either carries no remedy.
- */
-function memoryRemedy(
-  missing: readonly string[],
-  named: MemoryType | undefined,
-): FindingRemedy | undefined {
-  return named && missing.length === 1 && missing[0] === 'category'
-    ? 'category-from-name'
-    : undefined
-}
-
-export function checkMemory(name: string, text: string): Finding[] {
-  const findings: Finding[] = []
-  const match = MEMORY_NAME.exec(name)
-  const named = match ? memoryType(match[1]) : undefined
-
-  if (!named) {
-    findings.push(
-      finding(
-        'name-malformed',
-        name,
-        name,
-        `is not named <type>-<slug>.md with a type of ${MEMORY_TYPES.join(', ')}.`,
-      ),
-    )
-  }
-
-  const frontmatter = parseFrontmatter(text)
-  const missing = MEMORY_FIELDS.filter(
-    (field) => !readField(frontmatter, field),
-  )
-
-  if (missing.length > 0) {
-    findings.push(
-      finding(
-        'frontmatter-incomplete',
-        name,
-        name,
-        `carries no ${missing.join(' and no ')}.`,
-        memoryRemedy(missing, named),
-      ),
-    )
-  }
-
-  // Its own kind rather than `title-missing`, which means an absent heading on a
-  // plan. One kind covering both leaves a caller filtering the JSON unable to
-  // tell a record with no title from one whose title is its own slug.
-  if (readField(frontmatter, 'title') === name.replace(/\.md$/, '')) {
-    findings.push(
-      finding(
-        'title-is-slug',
-        name,
-        name,
-        'is titled with its own filename, so the catalog renders a slug where the rule belongs.',
-      ),
-    )
-  }
-
-  const category = readField(frontmatter, 'category')
-
-  // Reported against the prefix alone. A name the prefix rule already failed
-  // has no type to compare against, and reporting it twice names one defect as
-  // two.
-  if (named && category && category !== CATEGORY_BY_TYPE[named]) {
-    findings.push(
-      finding(
-        'category-mismatch',
-        name,
-        category,
-        `is not ${CATEGORY_BY_TYPE[named]}, which the filename prefix declares.`,
-      ),
-    )
-  }
-
-  return [
-    ...findings,
-    ...checkMemoryBody(
-      name,
-      text.slice(frontmatter?.raw.length ?? 0),
-      named ?? category,
-    ),
-  ]
-}
-
-/**
- * A `user` or `reference` entry is a single sentence by design, so the markers
- * are checked only where a rule is being stated. The type is read off the
- * prefix, falling back to the category so a misnamed file is still checked
- * against the shape it claims.
- */
-function checkMemoryBody(
-  name: string,
-  text: string,
-  claimed: string | undefined,
-): Finding[] {
-  const type = claimed && memoryType(claimed.toLowerCase())
-  if (type !== 'feedback' && type !== 'project') return []
-
-  const body = linesOutsideFences(text).filter((line) => line.trim().length > 0)
-
-  const findings: Finding[] = []
-  const opening = body[0]
-
-  if (!opening || MEMORY_MARKERS.some((marker) => opening.startsWith(marker))) {
-    findings.push(
-      finding(
-        'section-missing',
-        name,
-        'the rule line',
-        'is absent, so the entry carries a rationale with no rule to apply.',
-      ),
-    )
-  }
-
-  for (const marker of MEMORY_MARKERS) {
-    if (!body.some((line) => line.startsWith(marker))) {
-      findings.push(
-        finding(
-          'section-missing',
-          name,
-          marker,
-          `is required on a ${type} entry and the body carries no such line.`,
-        ),
-      )
-    }
-  }
-
-  return findings
-}
-
 const STANDARD_INDEX = 'index.md'
 const STANDARD_FIELDS = ['title', 'description'] as const
 
@@ -1225,7 +1048,7 @@ export function checkStandard(name: string, text: string): Finding[] {
  */
 const FOLDER_CHECK: Readonly<
   Record<
-    Exclude<RecordKind, 'plans' | 'memory' | 'standards'>,
+    Exclude<RecordKind, 'plans' | 'standards'>,
     (dir: string, slug: string) => Promise<Finding[]>
   >
 > = {
@@ -1279,15 +1102,6 @@ export async function validateRecords(
 
   if (kind === 'plans') return validateFiles(dir, kind, checkPlan)
 
-  if (kind === 'memory') {
-    return validateFiles(
-      dir,
-      kind,
-      checkMemory,
-      (file) => file === MEMORY_INDEX,
-    )
-  }
-
   // The walk stays flat, matching install and the catalog.
   if (kind === 'standards') {
     return validateFiles(

package/src/sandbox/census.ts

@@ -71,7 +71,7 @@ export function listSkills(root: string): string[] {
  *
  * `<category>-<command>` is the rule `canon/context/sandbox/coverage/census.md` states, and it
  * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
- * rest: `claude/target-setup.sh` drives the `target-setup` skill, not a `claude-target-setup` that
+ * rest: `claude/target-setup.ts` drives the `target-setup` skill, not a `claude-target-setup` that
  * does not exist. Stating one spelling and shipping two is what let the audit
  * report a paired skill as unpaired.
  *

package/src/sandbox/coverage.ts

@@ -44,13 +44,9 @@ function listScenarios(sandboxDir: string): ScenarioCoverage[] {
   const scenarios: ScenarioCoverage[] = []
 
   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()
+    const { scenarios: files } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const command of commands) {
+    for (const { command } of files) {
       scenarios.push({ category, command, armed: [] })
     }
   }

package/src/sandbox/equivalence.ts

@@ -22,7 +22,6 @@ import {
   listCategories,
   listScenarioFiles,
   loadScenario,
-  type ScenarioKind,
 } from '@/sandbox/scenario'
 import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
@@ -153,28 +152,6 @@ export function armKey(arm: Arm): string {
   return arm.arm === undefined ? scenario : `${scenario}/${arm.arm}`
 }
 
-/**
- * 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
- * the rest are arm names. A call this cannot see returns no arms, which the
- * coverage cross-check in `enumerateArms` turns into an error rather than a
- * smaller list.
- */
-export function parseArmNames(source: string): string[] {
-  const start = source.search(/select_or_route_scenario\b/)
-  if (start === -1) return []
-
-  const call = source
-    .slice(start)
-    .replace(/\\\n/g, ' ')
-    .split('\n')[0]
-    ?.replace(/^select_or_route_scenario/, '')
-
-  return [...(call ?? '').matchAll(/"([^"]*)"/g)]
-    .map((match) => match[1] ?? '')
-    .slice(1)
-}
-
 function matchesTarget(
   category: string,
   command: string,
@@ -199,25 +176,14 @@ function matchesArm(arm: Arm, targets: readonly string[]): boolean {
 }
 
 /**
- * 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.
+ * Reads a scenario's arm names and anchor flag off its 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)
 
@@ -250,17 +216,12 @@ export function enumerateArms(
   const coverage = collectCoverage(root)
 
   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`)
+    const { scenarios } = listScenarioFiles(join(sandboxDir, category))
 
-    for (const { command, file, kind } of scenarios) {
+    for (const { command, file } of scenarios) {
       if (!matchesTarget(category, command, targets)) continue
 
-      const declared = readArms(file, kind)
+      const declared = readArms(file)
       if (!declared.ok) {
         errors.push(`${category}:${command} did not load: ${declared.error}`)
         continue

package/src/sandbox/expect.ts

@@ -354,7 +354,7 @@ function checkWriteScope(
   // none, and without this the declaration vanishes from the verdict entirely:
   // no result, no skipped entry, and no contribution to the unchecked count that
   // exists to surface exactly this. The `undefined` branch above cannot stand in,
-  // since `run.sh` always passes `--writes` and `readPathList` returns `[]` for an
+  // since `canon sandbox run` always passes `--writes` and `readPathList` returns `[]` for an
   // empty file. An arm whose output escaped the snapshot reads as a clean run,
   // which is the vacuous pass the harness exists to remove.
   if (writes.length === 0) {
@@ -377,7 +377,7 @@ function checkWriteScope(
 }
 
 /**
- * `run.sh` watches two toolkit roots for a write to shared session scratch
+ * `canon sandbox run` watches two toolkit roots for a write to shared session scratch
  * during a run, and reports every one it finds as an unattributed escape with
  * no arm able to fail on it. An arm whose skill legitimately reaches outside
  * the sandbox tree declares the destinations here, and the harness asserts
@@ -388,8 +388,8 @@ function checkWriteScope(
  * nothing skips rather than passing on a fabricated zero. An escape-scope
  * declaration exists to bound a side effect nothing requires, so zero escapes
  * is the outcome a correct run produces and reports as a pass outright,
- * provided a watched root held something to watch. `run.sh`'s `snapshot_root`
- * returns an empty manifest both when a watch ran clean and when none of the
+ * provided a watched root held something to watch. `snapshotRoot` in
+ * `src/sandbox/headless/watch.ts` returns an empty manifest both when a watch ran clean and when none of the
  * four watched directories existed under a root, and the two produce the same
  * empty `escapes` list. `watched` is what tells them apart: a run that had
  * nothing to watch reports unmeasured rather than passing on a diff it never

package/src/sandbox/provision.ts

@@ -8,7 +8,6 @@ import {
   writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
-import { probeScenario, stageScenario } from '@/sandbox/hooks'
 import {
   FIXTURE_SUFFIX,
   FIXTURES_DIR,
@@ -34,9 +33,8 @@ import {
 
 /**
  * Provisions one scenario into the sandbox tree, and resets or cleans that tree.
- * 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.
+ * A scenario's arm runs in process through `scenario.ts`, and everything
+ * around it 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
@@ -403,36 +401,22 @@ interface Scenario {
 
 /**
  * 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.
+ * whether it stages from the anchor, 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 } {
+): { 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)
@@ -443,7 +427,7 @@ function declareScenario(
   }
   Object.assign(env, scenarioExports(definition, root, env))
 
-  return { kind: 'ts', definition, isAnchor: definition.anchor === true }
+  return { definition, isAnchor: definition.anchor === true }
 }
 
 async function provisionScenario(
@@ -481,21 +465,14 @@ async function provisionScenario(
   // 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. 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: {},
-        }
+  const staged = await stageScenarioInProcess(declared.definition, {
+    root,
+    dir: sandbox,
+    env,
+    arm: scenario.arm,
+  })
   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 ?? '') !== ''
   const isSkipInject = (env.SANDBOX_SKIP_SKILL_INJECT ?? '') !== ''
@@ -602,7 +579,7 @@ function parseTarget(target: string): { category: string; command: string } {
 }
 
 export interface SandboxRequest {
-  /** False where a caller already opened the frame, as `run.sh` and the picker do. */
+  /** False where a caller already opened the frame, as `canon sandbox run` and the picker do. */
   readonly isHeader: boolean
   /** `<category>:<command>`, `reset`, or `clean`. */
   readonly target: string

package/src/sandbox/scenario.ts

@@ -42,15 +42,13 @@ export const FIXTURE_SUFFIX = '.fixture'
 /** A scenario whose only arm carries this name routes none, as a bash file with no picker did. */
 export const DEFAULT_ARM_NAME = 'default'
 
-/** What a bash scenario passed to `select_or_route_scenario` unless it named another. */
+/** The picker's message unless a scenario names another. */
 const ROUTE_PROMPT = 'Which scenario?'
 
 /** Every scenario that sets the anchor pushes to this one throwaway repository. */
 export const SANDBOX_ANCHOR_REPO = 'canon-sandbox'
 
-const EXTENSIONS = ['.ts', '.sh'] as const
-
-export type ScenarioKind = 'ts' | 'sh'
+const EXTENSION = '.ts'
 
 export type ArmSetup = (ctx: StageContext) => void | Promise<void>
 
@@ -60,12 +58,12 @@ export interface ScenarioDefinition {
   /** Stages the tree from the anchor fixture and names the throwaway remote. */
   readonly anchor?: boolean
   /**
-   * Stages and narrates what the bash form did ahead of `select_or_route_scenario`,
-   * so the picker's echo lands after it on the frame. Runs before the arm is
+   * Stages and narrates ahead of the picker, so the picker's echo lands after
+   * it on the frame. Runs before the arm is
    * routed, which leaves `ctx.arm` undefined.
    */
   readonly prepare?: ArmSetup
-  /** The picker's message, for a bash scenario that passed something other than the default. */
+  /** The picker's message, for a scenario that asks something other than the default. */
   readonly prompt?: string
   /** In routing order, so the first arm is the one a headless caller gets. */
   readonly arms: Readonly<Record<string, ArmSetup>>
@@ -78,43 +76,27 @@ export function scenario(definition: ScenarioDefinition): ScenarioDefinition {
 export interface ScenarioFile {
   readonly command: string
   readonly file: string
-  readonly kind: ScenarioKind
 }
 
 /**
- * Lists the scenarios in one category folder, one per stem. A stem present in
- * both forms is reported apart rather than listed twice, since picking one
- * without saying so is the failure the refusal exists to prevent.
+ * Lists the scenarios in one category folder, one per `.ts` stem. A file in any
+ * other form is ignored rather than refused, so a hand-written leftover does not
+ * break the listing.
  */
 export function listScenarioFiles(categoryDir: string): {
   scenarios: ScenarioFile[]
-  ambiguous: string[]
 } {
-  const byStem = new Map<string, ScenarioFile[]>()
+  const scenarios: ScenarioFile[] = []
   for (const entry of readdirSync(categoryDir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue
-    const kind = EXTENSIONS.find((ext) => entry.name.endsWith(ext))
-    if (kind === undefined) continue
-    const command = entry.name.slice(0, -kind.length)
-    const found = byStem.get(command) ?? []
-    found.push({
-      command,
+    if (!entry.isFile() || !entry.name.endsWith(EXTENSION)) continue
+    scenarios.push({
+      command: entry.name.slice(0, -EXTENSION.length),
       file: join(categoryDir, entry.name),
-      kind: kind === '.ts' ? 'ts' : 'sh',
     })
-    byStem.set(command, found)
   }
+  scenarios.sort((a, b) => a.command.localeCompare(b.command))
 
-  const scenarios: ScenarioFile[] = []
-  const ambiguous: string[] = []
-  for (const [command, found] of [...byStem].sort(([a], [b]) =>
-    a.localeCompare(b),
-  )) {
-    if (found.length > 1) ambiguous.push(command)
-    else if (found[0] !== undefined) scenarios.push(found[0])
-  }
-
-  return { scenarios, ambiguous }
+  return { scenarios }
 }
 
 /** Every category folder under `sandbox/`, fixtures excluded. */
@@ -129,21 +111,18 @@ export function listCategories(sandboxDir: string): string[] {
 
 export type ResolvedScenario =
   | ({ readonly ok: true } & ScenarioFile)
-  | { readonly ok: false; readonly reason: 'missing' | 'ambiguous' }
+  | { readonly ok: false; readonly reason: 'missing' }
 
 export function resolveScenarioFile(
   sandboxDir: string,
   category: string,
   command: string,
 ): ResolvedScenario {
-  const found = EXTENSIONS.map((ext) =>
-    join(sandboxDir, category, `${command}${ext}`),
-  ).filter((path) => existsSync(path) && statSync(path).isFile())
-  if (found.length > 1) return { ok: false, reason: 'ambiguous' }
-  const file = found[0]
-  if (file === undefined) return { ok: false, reason: 'missing' }
-
-  return { ok: true, command, file, kind: file.endsWith('.ts') ? 'ts' : 'sh' }
+  const file = join(sandboxDir, category, `${command}${EXTENSION}`)
+  if (!existsSync(file) || !statSync(file).isFile())
+    return { ok: false, reason: 'missing' }
+
+  return { ok: true, command, file }
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -190,7 +169,7 @@ export function armNames(definition: ScenarioDefinition): string[] {
   return names.length === 1 && names[0] === DEFAULT_ARM_NAME ? [] : names
 }
 
-/** Twin of `scripts/config.sh`, which derives the organization from the toolkit's own remote. */
+/** Derives the organization from the toolkit's own remote unless `GITHUB_ORG` names one. */
 function deriveGithubOrg(root: string, env: NodeJS.ProcessEnv): string {
   if ((env.GITHUB_ORG ?? '') !== '') return env.GITHUB_ORG ?? ''
 
@@ -209,8 +188,8 @@ function deriveGithubOrg(root: string, env: NodeJS.ProcessEnv): string {
 }
 
 /**
- * What the bash probe reported for a scenario: its config, the organization
- * `config.sh` derives, and the anchor's repository name. These land in the one
+ * What provisioning reads off a scenario: its config, the derived organization,
+ * and the anchor's repository name. These land in the one
  * environment provisioning passes to every child, the seed and gov installs
  * included.
  */
@@ -447,8 +426,7 @@ export function createStageContext(options: ContextOptions): StageContext {
 
   /**
    * `gh` answers an absent repository and an unreachable host with one status,
-   * so the 404 alone separates them. Creating is the opt-in, for the reason
-   * `ensure_sandbox_anchor_repo` in `scripts/lib/sandbox-git.sh` records.
+   * so the 404 alone separates them. Creating is the opt-in.
    */
   const ensureAnchorRepo = (org: string, repo: string): void => {
     const probe = spawn(
@@ -503,7 +481,7 @@ export function createStageContext(options: ContextOptions): StageContext {
     git('remote', 'add', 'origin', `https://github.com/${org}/${repo}.git`)
   }
 
-  /** Twin of `stage_fixtures` in `scripts/lib/sandbox-fixtures.sh`. */
+  /** Copies a fixture folder into the tree. */
   const fixtures = (
     category: string,
     command: string,
@@ -602,7 +580,7 @@ export function createStageContext(options: ContextOptions): StageContext {
 }
 
 /**
- * Picks the arm the way `select_or_route_scenario` did: a routed name first,
+ * Picks the arm: a routed name first,
  * echoed on the frame, then the first arm for a headless caller, then a prompt.
  */
 async function routeArm(

package/src/sandbox/tree.ts

@@ -8,11 +8,9 @@ import { join } from 'node:path'
  * in `CANON_SANDBOX_RUN_ID` for the rest of this process, so a script that
  * spawns a child inheriting `process.env` — `canon sandbox run` calling
  * `canon sandbox` to provision and then `canon sandbox check` — resolves the same tree in every one
- * of them, as do the hook and installer children provisioning spawns. A process
+ * of them, as do the installer children provisioning spawns. A process
  * that already carries the variable, inherited from such a parent, reuses it
  * rather than minting a new one.
- *
- * Twin of `mint_sandbox_run_id` in `scripts/lib/sandbox-path.sh`.
  */
 export function mintSandboxRunId(): string {
   const existing = process.env.CANON_SANDBOX_RUN_ID
@@ -28,9 +26,7 @@ export function mintSandboxRunId(): string {
  * per-run default is unit-testable on its own rather than only through the
  * command's registration.
  *
- * Twin of `resolve_sandbox_dir` in `scripts/lib/sandbox-path.sh`. The exec
- * boundary rules out a shared constant, so a change to the default lands on
- * both sides. The fall-through used to be one path per machine, so two
+ * The fall-through used to be one path per machine, so two
  * sessions each resolving the default at once provisioned over each other
  * with neither told; `mintSandboxRunId` gives the path a per-run component
  * instead, which is what makes two such sessions land on two different trees.