@erclx/canon 5.13.0 → 5.14.1

package/claude/skills/role-orchestrator/scripts/watch.ts

@@ -0,0 +1,267 @@
+// Reports worker and pull request transitions as they happen. Reads only.
+//
+// The poll answers "what moved since the last run" on a schedule the session
+// holds. This answers "what just changed" on a loop of its own, and it exists
+// because the two readings a dispatch needs are not one reading: a worker that
+// finishes goes idle and a worker that crashes vanishes, so a watch matching
+// only the pull request list stays silent through the second. A third case is
+// neither: a worker that stops on a question or a prompt neither finishes nor
+// crashes, and sits reading "waiting" until something reports it, which is the
+// WORKER-STOPPED line below, or WORKER-UNMEASURABLE for a "waiting" row too old
+// to carry a stamp this reads.
+//
+// Run as `bun watch.ts`. A failed read never ends the loop, since it runs for
+// hours and one transient `gh` failure aborting it is a silent stop. Every read
+// states its own failure instead.
+import { baseBranch, baseRef, gitPath, mainRoot, run } from './repo'
+
+// Seconds between passes. A pass costs two cheap reads and the transitions it
+// watches take minutes, so the number trades staleness against little. Raise it
+// in a project whose workers run long.
+const INTERVAL_S = 60
+
+// Seconds a worker can sit in "waiting" before this reports it as stopped
+// rather than folding it into the ordinary status-change lines. "busy" and
+// "idle" resolve on their own; "waiting" does not, so a dwell that keeps
+// growing there is a session blocked on something outside itself. The number
+// sits well above INTERVAL_S, so a handful of passes confirm the row before it
+// reports, and well inside the ten-to-thirty-minute span a dispatched build
+// ordinarily runs. A permission prompt clears the moment a person approves it
+// and a question can sit legitimately, and one number serves both.
+export const STALL_THRESHOLD_S = 300
+
+export type Read<T> = { isOk: false } | { isOk: true; value: T }
+
+export interface Worker {
+  branch: string
+  dwellMs: number
+  name: string
+  status: string
+}
+
+export interface WatchState {
+  /** Names currently reported as stalled, so a stall prints once. */
+  stalled: ReadonlySet<string>
+  /** Null until a read succeeds, so each source keeps its own baseline flag. */
+  pulls: null | readonly string[]
+  workers: null | readonly Worker[]
+}
+
+export const initialState = (): WatchState => ({
+  pulls: null,
+  stalled: new Set(),
+  workers: null,
+})
+
+// `sort` orders by byte, so a title with a non-ASCII first character prints in
+// the order it always did rather than in UTF-16 code unit order.
+const byBytes = (a: string, b: string): number =>
+  Buffer.compare(Buffer.from(a), Buffer.from(b))
+
+const rowOf = (worker: Worker): string =>
+  [worker.name, worker.branch, worker.status, String(worker.dwellMs)].join('\t')
+
+// Identity leaves the dwell out. It grows every second, so keying on it
+// reported every worker as new on every pass.
+const identityOf = (worker: Worker): string =>
+  JSON.stringify([worker.name, worker.branch, worker.status])
+
+const unseen = <T>(
+  current: readonly T[],
+  previous: readonly T[],
+  key: (item: T) => string,
+): T[] => {
+  const known = new Set(previous.map(key))
+
+  return current.filter((item) => !known.has(key(item)))
+}
+
+const stallLines = (
+  workers: readonly Worker[],
+  previous: ReadonlySet<string>,
+  thresholdS: number,
+): { lines: string[]; stalled: Set<string> } => {
+  const stalled = new Set(previous)
+  const lines: string[] = []
+
+  for (const worker of workers) {
+    if (worker.name === '') continue
+
+    if (worker.status !== 'waiting') {
+      stalled.delete(worker.name)
+      continue
+    }
+
+    if (worker.dwellMs === -1) {
+      if (!stalled.has(worker.name)) {
+        lines.push(`WORKER-UNMEASURABLE ${worker.name} ${worker.branch}`)
+        stalled.add(worker.name)
+      }
+      continue
+    }
+
+    const dwellS = Math.trunc(worker.dwellMs / 1000)
+    if (dwellS < thresholdS) {
+      stalled.delete(worker.name)
+    } else if (!stalled.has(worker.name)) {
+      lines.push(`WORKER-STOPPED ${worker.name} ${worker.branch} ${dwellS}s`)
+      stalled.add(worker.name)
+    }
+  }
+
+  return { lines, stalled }
+}
+
+/**
+ * One pass over two reads. A failed read is reported and the previous baseline
+ * kept, since reading an empty result as the current state would report every
+ * worker gone and every pull request new on the pass after.
+ */
+export const pass = (
+  state: WatchState,
+  pulls: Read<string[]>,
+  workers: Read<Worker[]>,
+  thresholdS = STALL_THRESHOLD_S,
+): { lines: string[]; state: WatchState } => {
+  const lines: string[] = []
+
+  if (!pulls.isOk) {
+    lines.push(
+      'watch: the open pull request list failed to load, so none is classified this pass',
+    )
+  }
+  if (!workers.isOk) {
+    lines.push(
+      'watch: the session roster failed to load, so no worker is classified this pass',
+    )
+  }
+
+  if (pulls.isOk && state.pulls !== null) {
+    lines.push(
+      ...unseen(pulls.value, state.pulls, (line) => line).sort(byBytes),
+    )
+  }
+
+  let stalled = state.stalled
+  if (workers.isOk) {
+    const sorted = [...workers.value].sort((a, b) =>
+      byBytes(rowOf(a), rowOf(b)),
+    )
+    if (state.workers !== null) {
+      const changed = unseen(sorted, state.workers, identityOf)
+      lines.push(...changed.map((worker) => `WORKER ${rowOf(worker)}`))
+
+      const names = new Set(sorted.map((worker) => worker.name))
+      const gone = [...new Set(state.workers.map((worker) => worker.name))]
+        .filter((name) => !names.has(name))
+        .sort(byBytes)
+      lines.push(...gone.map((name) => `WORKER-GONE ${name}`))
+    }
+
+    const stalls = stallLines(sorted, stalled, thresholdS)
+    lines.push(...stalls.lines)
+    stalled = stalls.stalled
+  }
+
+  return {
+    lines,
+    state: {
+      pulls: pulls.isOk ? pulls.value : state.pulls,
+      stalled,
+      workers: workers.isOk ? workers.value : state.workers,
+    },
+  }
+}
+
+const readPulls = (): Read<string[]> => {
+  const listed = run('gh', [
+    'pr',
+    'list',
+    '--state',
+    'open',
+    '--json',
+    'number,headRefName,title',
+    '--jq',
+    '.[] | "PR-OPEN #\\(.number) \\(.headRefName) \\(.title)"',
+  ])
+  if (!listed.isOk) return { isOk: false }
+
+  return {
+    isOk: true,
+    value: listed.stdout.split('\n').filter((l) => l !== ''),
+  }
+}
+
+const asText = (value: unknown, fallback: string): string =>
+  typeof value === 'string' ? value : fallback
+
+/**
+ * Every session in this repository holding a branch other than the base one is
+ * a worker, whoever launched it. A match on the `orchestrator-` name prefix
+ * reads a dispatched worker and misses every hand-launched one. The name stays whole, since one
+ * this client writes carries spaces.
+ */
+const readWorkers = (repository: string, base: string): Read<Worker[]> => {
+  const listed = run('canon', ['sessions', 'list', '--json'])
+  if (!listed.isOk) return { isOk: false }
+
+  const last = listed.stdout.trimEnd().split('\n').at(-1) ?? ''
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(last)
+  } catch {
+    return { isOk: false }
+  }
+
+  const sessions =
+    typeof parsed === 'object' &&
+    parsed !== null &&
+    Array.isArray((parsed as { sessions?: unknown }).sessions)
+      ? (parsed as { sessions: unknown[] }).sessions
+      : []
+
+  const workers: Worker[] = []
+  for (const session of sessions) {
+    if (typeof session !== 'object' || session === null) continue
+    const row = session as Record<string, unknown>
+    if (row.repository !== repository) continue
+    if (
+      row.branch === null ||
+      row.branch === undefined ||
+      row.branch === base
+    ) {
+      continue
+    }
+
+    workers.push({
+      branch: asText(row.branch, ''),
+      dwellMs: typeof row.statusDwellMs === 'number' ? row.statusDwellMs : -1,
+      name: asText(row.name, ''),
+      status: asText(row.status, ''),
+    })
+  }
+
+  return { isOk: true, value: workers }
+}
+
+const main = async (): Promise<number> => {
+  const root = mainRoot()
+  if (root === null) {
+    console.error('watch: not a git repository, so nothing is watched')
+
+    return 1
+  }
+
+  const repository = gitPath(root)
+  const base = baseBranch(baseRef())
+  let state = initialState()
+
+  for (;;) {
+    const result = pass(state, readPulls(), readWorkers(repository, base))
+    for (const line of result.lines) console.log(line)
+    state = result.state
+    await new Promise((resolve) => setTimeout(resolve, INTERVAL_S * 1000))
+  }
+}
+
+if (import.meta.main) process.exitCode = await main()

package/docs/agents/commands.md

@@ -103,7 +103,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `worktrees`, in `worktrees.md`: `list`, `reclaim`
 - `hooks`, in `hooks.md`: `post-merge`
 - `autoship`, in `review-classification.md`: `classify`
-- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`
+- `pr`, in `pr-reads.md`: `key-changes`, `head`, `checks`, `review-state`, `evidence`, `preview`, `local`, `frames`
 - `audits`, in `audits.md`: `run`, `list`
 - `gate`, in `gate.md`: `run`
 - `secrets`, in `state-scoped-risk.md`: `scan`

package/docs/agents/index.md

@@ -36,6 +36,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
+- [The pull request frame store](pr-frames.md): How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
 - [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs

package/docs/agents/markdown-audit.md

@@ -89,7 +89,7 @@ A hit the closed set could not separate from correct prose was the case with no
 
 Five surfaces apply the ban set and four of them go through this verb. `.claude/hooks/standards-audit.sh` runs it against a single file after each markdown edit, the seed copy a project installs does the same, the `Markdown bans` stage in `canon gate run` runs it across the whole corpus before this repository's own push, and the same-named stage in the one verify runner every stack shares, `scripts/verify.ts`, runs it across a scaffolded project's tracked markdown before its own push. Each hook parsed its own copy of the word bans in awk before that, which left a British spelling passing at edit time and failing the push with nothing in between explaining the difference.
 
-The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. `scripts/core/check-seed-independence.sh` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
+The seed copy moved onto the verb when the sets became data, since its awk had nothing left to parse. It resolves one runner where the toolkit copy resolves two, looking for no checkout source, and a machine carrying no `canon` gets a report naming the binary to install rather than a silent pass. The Seed independence stage of `bun run check` scopes its walk to markdown and leaves the seed hooks outside it, which its own comment records as deliberate.
 
 The target push stage reads the same exit codes `canon gate run`'s own stage reads: 0 passes, 1 is a refusal logged as a skip, 2 is a finding, and 3 is a shipped-empty ban set. It skips and logs rather than failing when no `canon` binary is on the machine's PATH, since a scaffolded project is not guaranteed the toolkit is installed, and its skip line names the install command.
 

package/docs/agents/pr-evidence.md

@@ -83,6 +83,11 @@ them means the thread is read before the `no-evidence` answer too, so an
 unreadable thread refuses as `gh-failed` on both reasons rather than
 reporting the fields absent.
 
+`ok` also carries `states`, the comparison the body renders as data: each
+state's name and its items, each with its `path`, `stem`, and whether it was
+`added`. `review-ui` matches a frame against it so it publishes no image the
+worker's evidence already shows. `canon docs pr-frames` covers that store.
+
 ## What `[number]` selects, and what it does not
 
 Naming a number picks the pull request the whole record describes: its head

package/docs/agents/pr-frames.md

@@ -0,0 +1,112 @@
+---
+title: The pull request frame store
+description: How canon pr frames pushes a UI review frame to a never-merged branch through the GitHub API and returns a branch-path link, which ref it writes, the pass segment that keeps an earlier image fixed, the refusal reasons it names, and how --drop and --prune rewrite the branch so a dropped frame leaves history
+---
+
+# The pull request frame store
+
+`canon pr frames` gives a review comment an image it can embed. `review-ui`
+drives a pull request's checklist and captures a frame per box, and a frame
+on the reviewer's disk resolves for nobody else. The verb pushes one frame to
+the `canon-frames` branch and returns a link to its path there.
+
+```bash
+canon pr frames 1341 --add frames/3.png --box 3 --head <sha> --pass 20261002T154450Z --json
+canon pr frames 1341 --drop --json
+canon pr frames --prune 30 --json
+```
+
+## What it writes
+
+The verb writes `refs/heads/canon-frames` and no other ref. Every call goes
+through the GitHub git data API, being blobs, trees, commits, and that one ref,
+so nothing is checked out, no worktree is entered, and neither `main` nor any
+branch a pull request holds is touched. The branch never merges.
+
+A frame lands at `pr-<number>/<short-head>/<pass>/box-<n>.png`. `--head` names
+the commit the pass drove, 7 to 40 lowercase hex characters, and defaults to
+the head the pull request object reports. `--pass` is the instant the pass
+started, in compact UTC as `date -u +%Y%m%dT%H%M%SZ` prints it, which
+`review-ui` records once at its first step. A second pass at the same head and
+box therefore writes a new file rather than replacing the image an earlier
+comment shows, which matters when a preview is minted again at one head.
+
+`link` uses the same `blob/<ref>/<path>?raw=true` form as the evidence comment,
+naming the `canon-frames` branch rather than a commit. Every drop rewrites the
+branch, and a link pinned to a commit would stop resolving for every other pull
+request's frames once GitHub collects the commit it names. A path link lives
+exactly as long as its file, so it survives every rewrite that drops another
+pull request and ends only when its own is dropped.
+
+The first `--add` creates the branch with a root commit holding the
+frame, so a project needs no setup. An add only fast-forwards the ref. When
+another writer moved it between the read and the move, the add rebuilds on the
+new tip, up to three times, before refusing as `ref-conflict`.
+
+Only a frame of the address the pass drove belongs here. The branch is as
+public as the repository, so a frame of a private or pre-release state would
+be published with it.
+
+## What the record carries
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason             | What it means                                                                    |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `ok`               | An add pushed, or a drop or prune finished, including one that removed nothing.  |
+| `bad-mode`         | Not exactly one of `--add`, `--drop`, `--prune`, or a number with `--prune`.     |
+| `no-number`        | `--add` or `--drop` named no pull request.                                       |
+| `bad-box`          | `--add` carried no positive `--box`.                                             |
+| `bad-head`         | `--head`, or the head the pull request reported, is not a 7 to 40 character sha. |
+| `bad-pass`         | `--add` carried no `--pass` stamp in compact UTC.                                |
+| `bad-days`         | `--prune` carried no positive number of days.                                    |
+| `unreadable-frame` | The `--add` file is missing, empty, or not a PNG. Nothing is called.             |
+| `read-only`        | GitHub refused a write with 403 or 404, which is what a fork's token gets.       |
+| `unreadable-tip`   | The branch exists and could not be read.                                         |
+| `push-failed`      | A write failed partway and the ref did not move.                                 |
+| `ref-conflict`     | Another writer kept moving the ref through every attempt.                        |
+| `no-object-head`   | No `--head` and the pull request reported none.                                  |
+| `gh-missing`       | `gh` is not on the path.                                                         |
+| `gh-failed`        | `gh` could not name the repository or read the pull request.                     |
+
+An add's `ok` record carries `link`, `commit`, `path`, `box`, `head`, `pass`,
+and `created`, which is true when the add made the branch. A drop's carries
+`removed`, the pull requests whose folders went, plus `commit` for the rewrite
+or `deleted` when it emptied the branch. A prune adds `kept` and `unread`.
+
+`review-ui` reads every reason but `ok` as a cue to describe the frame in words
+and name the reason, so a refused push never fails the pass.
+
+## Dropping frames
+
+A plain delete commit would keep every image reachable through history, so
+`--drop` and `--prune` write one root commit holding everything else and
+force-move the ref to it. A rewrite that leaves the branch empty deletes it,
+and the next add recreates it. Dropping a pull request with no frames, or on a
+missing branch, reports `ok` with nothing removed, so a scheduled run never
+fails on an empty branch.
+
+`--prune <days>` reads every `pr-<n>/` folder, asks GitHub for each pull
+request's state, and drops every one reading closed with a close date more
+than that many days ago, in a single rewrite. It keeps one still open, one
+reopened after closing, one closed exactly the given days ago, and one whose
+state could not be read, listing that last kind under `unread`.
+
+This repository runs `--prune 30` daily from
+`.github/workflows/pr-frames-cleanup.yml`. A frame's file stays on the branch
+until its own pull request has been closed for 30 days, so a link in a review
+comment keeps resolving for about a month after its pull request closes,
+whatever other pull requests the branch drops in between. A target project
+carries no such workflow yet and keeps its frames until someone runs `--drop`.
+
+## What a rewrite does not do
+
+A force-move leaves the old commits unreachable without purging them. GitHub
+serves an unreachable commit by sha until it collects it, so a dropped frame
+stays reachable to anyone holding a sha from an earlier record, and a frame
+holding sensitive content needs a purge request to GitHub. Its path link stops
+resolving at the drop, since the branch no longer carries the file.
+
+A drop racing an add can lose the add's frame, since GitHub's ref update has no
+compare-and-swap for a force-move. The drop builds from the tip it reads, and
+the window is the length of one rewrite.

package/docs/agents/pr-reads.md

@@ -52,7 +52,7 @@ Both values are taken at the top of the pass rather than at the post, so the com
 
 The last non-empty line is where it has to sit, and the reader looks nowhere else. Searching a body for the last match instead reads a marker the body was displaying rather than claiming, since a fenced block showing the format on its own line trims to exactly the pattern, and a pass carrying no marker of its own would then hand the next reader a commit taken from an illustration. That is the same defect through a second door, so position rather than shape is what separates a claim from a quotation.
 
-`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's jq, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
+`canon pr review-state` is the only parser of that format. Two parsers was the alternative, one in the shipped skill body and one in the orchestrator poll's own filters, and those two ship on different cadences, so a format change to either would leave the other reading a reviewed commit as unreviewed.
 
 `source` on the record says which reading answered, and a caller checks it before trusting the rest:
 

package/docs/agents/sandbox.md

@@ -9,7 +9,7 @@ description: Scenario routing, the expectation scoring surface, and the coverage
 
 ## Scenarios
 
-Scenarios live under `scripts/sandbox/`, one folder per category. `scripts/sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. `files` in `package.json` excludes that tree, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
+Scenarios live under `sandbox/`, one folder per category. `sandbox/fixtures/` is the exception, holding file content that scenarios stage rather than scenarios of its own, so both pickers filter it out. That tree sits outside `files` in `package.json`, so an installed `canon` carries the command, reports it as toolkit-only on one line, and exits 1 rather than failing on the missing directory. Route non-interactively with `SANDBOX_SCENARIO`:
 
 ```bash
 SANDBOX_SCENARIO=sync canon sandbox infra:tooling
@@ -67,9 +67,9 @@ The record carries every scenario with the arms that declare, plus `totalScenari
 
 A skill pairs to a scenario by filename, `<category>-<command>` first and bare `<command>` second, so `claude/target-setup.sh` reaches the `target-setup` skill. `should-be-asserted` is the default rather than a queue to drain, and which of those skills earns an arm is a project decision the census does not make.
 
-`exempt` means no arm should be written and holds only with a reason, declared in `scripts/sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
+`exempt` means no arm should be written and holds only with a reason, declared in `sandbox/exempt.toml` and limited to a harness limit the checker cannot reach past or a skill that writes no artifact. An armed arm outranks an exemption. An exemption naming no shipped skill, or naming one an arm now asserts, exits 1 without `--strict`. Each armed arm reports as `<category>:<command>/<arm>`, so two same-named arms under different scenarios stay distinct.
 
-`scripts/sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
+`sandbox/run.sh` calls this after a headless run and merges the verdict into the envelope it prints. It also writes that merged record to `.canon/tmp/runs/sandbox/<target>-<arm>-<timestamp>.json` with a `writes` array appended, and logs the path on stderr. Both fields are what a later re-score needs, since `--envelope` and `--writes` read files the run deletes on exit.
 
 Two more fields ride alongside the verdict rather than inside it. `escapes` lists what the run wrote under a watched toolkit root, which the verdict cannot assert over because those files sit outside the sandbox tree. `sessions` reports the nested-dispatch bound, carrying `watched` for whether the client's session registry was there to read, `new` for the records that appeared while the run was in flight, `concurrent` for the records present both before and after, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
 

package/docs/agents/state-scoped-risk.md

@@ -22,7 +22,7 @@ canon secrets scan --json
 canon secrets scan ../my-app
 ```
 
-The corpus is the package's own `files` field rather than a list the check keeps. That field is the single statement of which trees leave this repository, so a second list beside it would answer the same question and drift. It also carries the negations the publish already makes, which is what puts the sandbox tree, the eval tree, and every test file out of scope by the rule that keeps them out of the tarball rather than by an exclusion this check invented.
+The corpus is the package's own `files` field rather than a list the check keeps. That field is the single statement of which trees leave this repository, so a second list beside it would answer the same question and drift. It also carries the negations the publish already makes, which is what puts the eval tree and every test file out of scope by the rule that keeps them out of the tarball rather than by an exclusion this check invented. The sandbox tree sits under no `files` entry at all, so the same field leaves it out without a negation.
 
 The plugin reaches a target by a different route, loading live from `claude/` rather than from a tarball. That folder is a `files` entry too, and its `standards` symlink resolves into a tree the field lists in its own right, so both routes land inside the same corpus.
 
@@ -30,7 +30,7 @@ Three root files are read whether or not the field names them, being `package.js
 
 ### What the corpus leaves out
 
-The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, and every test file. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
+The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/eval/` and every test file. The scenario tree was a third negation at that reading and now sits at `sandbox/` under no `files` entry, so it stays unread. `src/capture/` was a fourth negation when that reading was taken and is not one now. The folder holds 5 tracked files, 2 of them tests the publish still excludes, so the corpus is 3 wider than the numbers above describe and the unread count is 3 smaller.
 
 A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the toolkit's rule that content leaving the repository gates harder than content that stays.
 

package/docs/workflow/skill-map.md

@@ -38,20 +38,21 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Build the feature
 
-| Skill                        | When to use                                                                                                |
-| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `canon:session-worktree`     | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
-| `canon:auto-ship`            | After plan approval, to chain implement, verify, review, draft PR                                          |
-| `canon:project-commands`     | When the project's own command needs running                                                               |
-| `canon:test-first`           | Before implementing a planned change, to run its test red, green, then refactor                            |
-| `canon:test-craft`           | When writing or changing any test, to pick its layer and filter what it asserts                            |
-| `canon:build-in-slices`      | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
-| `canon:api-design`           | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
-| `canon:code-craft`           | Before writing a function, class, or module, to pick the shape the next change needs                       |
-| `canon:review-craft`         | When reviewing a change, for what to look for and how much evidence a finding needs                        |
-| `canon:systematic-debugging` | When a test fails or a bug surfaces, to force root cause first                                             |
-| `canon:design-taste`         | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
-| `canon:ui-checklist`         | After a UI change, to write what to look at and name what ships untested                                   |
+| Skill                         | When to use                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `canon:session-worktree`      | At the plan-to-execute boundary, to get an isolated tree and branch, or to route a refused main-root write |
+| `canon:auto-ship`             | After plan approval, to chain implement, verify, review, draft PR                                          |
+| `canon:project-commands`      | When the project's own command needs running                                                               |
+| `canon:test-first`            | Before implementing a planned change, to run its test red, green, then refactor                            |
+| `canon:test-craft`            | When writing or changing any test, to pick its layer and filter what it asserts                            |
+| `canon:build-in-slices`       | While building a plan, to commit each tested slice and note out-of-scope defects rather than fix them      |
+| `canon:api-design`            | When changing what a caller sees, being an export, a flag, an output shape, or a retried write             |
+| `canon:deprecation-migration` | When deleting or replacing code something may still call, to migrate its callers and prove none remain     |
+| `canon:code-craft`            | Before writing a function, class, or module, to pick the shape the next change needs                       |
+| `canon:review-craft`          | When reviewing a change, for what to look for and how much evidence a finding needs                        |
+| `canon:systematic-debugging`  | When a test fails or a bug surfaces, to force root cause first                                             |
+| `canon:design-taste`          | When drafting or judging an interface, or when output reads generic, to settle which decision comes first  |
+| `canon:ui-checklist`          | After a UI change, to write what to look at and name what ships untested                                   |
 
 ## Check the work before it leaves the branch
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.13.0",
+  "version": "5.14.1",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -17,7 +17,6 @@
     "docs",
     "tsconfig.json",
     "assets/brand/mark.svg",
-    "!scripts/sandbox",
     "!scripts/eval",
     "!**/*.test.ts",
     "!**/*.test.tsx"
@@ -27,9 +26,9 @@
   },
   "scripts": {
     "check:spell": "cspell '**' '.*/**' '.*' --no-progress --color --show-context",
-    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ tooling/ claude/",
-    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ tooling/ claude/",
-    "check:shell": "find scripts tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
+    "format": "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/ sandbox/ tooling/ claude/",
+    "check:format": "prettier --check --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --diff --indent 2 scripts/ sandbox/ tooling/ claude/",
+    "check:shell": "find scripts sandbox tooling claude .claude/hooks -name '*.sh' -exec shellcheck --severity=warning {} + && find .husky -maxdepth 1 -type f -exec shellcheck --severity=warning --shell=sh {} +",
     "check:types": "tsc --noEmit",
     "check:install": "./scripts/core/install-check.sh",
     "test": "bun --bun vitest run",

package/scripts/core/check-color-source.sh

@@ -6,6 +6,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
+SANDBOX_ROOT="$PROJECT_ROOT/sandbox"
 PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
 
 # `find` writes to stderr and returns non-zero for a missing root, inside a
@@ -16,6 +17,15 @@ if [ ! -f "$PALETTE_SOURCE" ]; then
   exit 1
 fi
 
+# The same silence follows a root that moved, so a walked root that is gone
+# fails here rather than shrinking the corpus with no message.
+for root in "$SCRIPTS_ROOT" "$SANDBOX_ROOT"; do
+  if [ ! -d "$root" ]; then
+    echo "No shell root at ${root#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
+    exit 1
+  fi
+done
+
 # Any SGR sequence in either spelling. The cursor and erase sequences an
 # interactive prompt writes end in a letter instead, and they run only where a
 # terminal already exists, so they are not what this measures.
@@ -31,7 +41,7 @@ while IFS= read -r file; do
   if grep -qE "$SGR" "$file"; then
     offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
   fi
-done < <(find "$SCRIPTS_ROOT" -type f -name '*.sh')
+done < <(find "$SCRIPTS_ROOT" "$SANDBOX_ROOT" -type f -name '*.sh')
 
 if [ -n "$offenders" ]; then
   echo "A color escape is defined outside the shared library:" >&2

package/scripts/core/install-check.sh

@@ -22,7 +22,7 @@ Usage: scripts/core/install-check.sh [--keep]
 
 Verifies the published install path end to end:
   1. Packs this repo into a tarball at .canon/tmp/install-check/pack
-  2. Extracts it and asserts scripts/sandbox is absent from the tree
+  2. Extracts it and asserts sandbox is absent from the tree
   3. Runs bun install --production in the extracted tree
   4. Runs the CLI with --help from the extracted tree to confirm it resolves
   5. Scaffolds a fresh project in .canon/tmp/install-check/target
@@ -51,6 +51,15 @@ mkdir -p "$PACK_DIR" "$EXTRACT_DIR"
 
 open_timeline "Install verification"
 
+# An absence check over a path the source tree no longer holds passes on
+# nothing, so the excluded tree has to exist here before its absence below can
+# mean the publish left it out.
+log_step "Assert excluded path exists in source"
+if [ ! -f "$PROJECT_ROOT/sandbox/run.sh" ]; then
+  log_error "sandbox/run.sh is missing from the source tree, so the absence check below would pass on nothing"
+fi
+log_info "Present: sandbox/run.sh"
+
 log_step "Pack"
 TARBALL_PATH="$(cd "$PROJECT_ROOT" && bun pm pack --quiet --ignore-scripts --destination "$PACK_DIR" | tail -n 1)"
 log_info "Packed to $TARBALL_PATH"
@@ -60,10 +69,10 @@ tar -xzf "$TARBALL_PATH" -C "$EXTRACT_DIR" --strip-components=1
 log_info "Extracted to $EXTRACT_DIR"
 
 log_step "Assert excluded path is absent"
-if [ -e "$EXTRACT_DIR/scripts/sandbox" ]; then
-  log_error "scripts/sandbox shipped in the tarball, and the files field in package.json excludes it"
+if [ -e "$EXTRACT_DIR/sandbox" ]; then
+  log_error "sandbox shipped in the tarball, and the files field in package.json leaves it out"
 fi
-log_info "Absent: scripts/sandbox"
+log_info "Absent: sandbox"
 
 log_step "Install dependencies (production)"
 (cd "$EXTRACT_DIR" && bun install --production --ignore-scripts --silent 2>&1 | pipe_output) || log_error "bun install --production failed"

package/scripts/lib/sandbox-dispatch.sh

@@ -9,7 +9,7 @@
 # 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.
 #
-# Three mechanisms sit here rather than in `scripts/sandbox/run.sh`, which is the
+# Three mechanisms sit here rather than in `sandbox/run.sh`, which is the
 # only caller. Each is reachable from a test that never launches a session:
 # `src/sandbox-dispatch.test.ts` drives the shim against a stub binary and the
 # reap against a `sleep`, where proving either through `run.sh` would mean