@erclx/canon 5.14.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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.14.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

package/scripts/lib/sandbox-fixtures.sh

@@ -6,7 +6,7 @@
 FIXTURE_SUFFIX=".fixture"
 
 # The tree mirrors the scenario path, so `category` and `scenario` together match
-# `scripts/sandbox/<category>/<scenario>.sh`. Both segments are load-bearing:
+# `sandbox/<category>/<scenario>.sh`. Both segments are load-bearing:
 # four scenario basenames repeat across categories (`claude`, `docs`, `review`,
 # `sync`), and `docs` is also a category of its own.
 fixture_stage_dir() {
@@ -14,7 +14,7 @@ fixture_stage_dir() {
   local scenario="$2"
   local arm="$3"
   local stage="$4"
-  echo "$PROJECT_ROOT/scripts/sandbox/fixtures/$category/$scenario/$arm/$stage"
+  echo "$PROJECT_ROOT/sandbox/fixtures/$category/$scenario/$arm/$stage"
 }
 
 list_fixture_files() {

package/scripts/lib/sandbox-path.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-# The sandbox tree lives outside the toolkit worktree. `scripts/sandbox/run.sh`
+# The sandbox tree lives outside the toolkit worktree. `sandbox/run.sh`
 # sets cwd to it for `claude -p`, and every `CLAUDE.md` between that cwd and the
 # filesystem root loads into the session. Under the repository the toolkit's own
 # instructions join that chain beside the seeded copy the scenario installed,

package/scripts/manage-sandbox.sh

@@ -40,7 +40,7 @@ show_help() {
   exit 0
 }
 
-ANCHOR_FIXTURE_DIR="$PROJECT_ROOT/scripts/sandbox/fixtures/anchor/create"
+ANCHOR_FIXTURE_DIR="$PROJECT_ROOT/sandbox/fixtures/anchor/create"
 
 # Where an anchor scenario's tree comes from and where its remote points are two
 # concerns, and only the remote needs a network. Taking the tree from a fixture
@@ -438,7 +438,7 @@ main() {
   fi
 
   SANDBOX="$(resolve_sandbox_dir)"
-  SANDBOX_DIR="$PROJECT_ROOT/scripts/sandbox"
+  SANDBOX_DIR="$PROJECT_ROOT/sandbox"
 
   local unsafe
   if ! unsafe="$(assert_sandbox_dir_safe "$SANDBOX" "$PROJECT_ROOT")"; then

package/src/commands/sandbox.ts

@@ -34,13 +34,13 @@ import {
   select,
 } from '@/ui'
 
-const SANDBOX_DIR = join(PROJECT_ROOT, 'scripts', 'sandbox')
+const SANDBOX_DIR = join(PROJECT_ROOT, 'sandbox')
 
 /**
  * Reports that the scenario tree does not ship, and answers whether it reported,
  * so a caller that sees `true` returns without touching the tree.
  *
- * `scripts/sandbox` is excluded from the published package, so an installed
+ * `sandbox` sits outside the published package, so an installed
  * `canon` resolves `SANDBOX_DIR` to a directory that is not there. Both entry
  * points that walk the tree ask here rather than carrying a check each, because
  * absence is a property of the install rather than of a verb, and a second copy

package/src/context/citations.ts

@@ -60,7 +60,7 @@ function ignoredCitations(line: string): IgnoredCitations | undefined {
  * eval harness names paths in its target project. Neither is a reference into
  * this repository, so an unresolved path there is correct rather than stale.
  */
-const FIXTURE_TREES: readonly string[] = ['scripts/sandbox/', 'scripts/eval/']
+const FIXTURE_TREES: readonly string[] = ['sandbox/', 'scripts/eval/']
 
 const FIXTURE_SEGMENTS: readonly string[] = ['fixtures', '__fixtures__']
 

package/src/sandbox/census.ts

@@ -134,7 +134,7 @@ export function parseExemptions(source: string): Map<string, string> {
 }
 
 function readExemptions(root: string): Map<string, string> {
-  const path = join(root, 'scripts', 'sandbox', EXEMPT_FILE)
+  const path = join(root, 'sandbox', EXEMPT_FILE)
   if (!existsSync(path)) return new Map()
 
   return parseExemptions(readFileSync(path, 'utf8'))

package/src/sandbox/coverage.ts

@@ -88,7 +88,7 @@ function armsFor(
  * a suite that proves something from one that runs.
  */
 export function collectCoverage(root: string): CoverageReport {
-  const sandboxDir = join(root, 'scripts', 'sandbox')
+  const sandboxDir = join(root, 'sandbox')
   const fixturesDir = join(sandboxDir, FIXTURES_DIR)
 
   const scenarios = listScenarios(sandboxDir).map((scenario) => ({

package/src/sandbox/expect.ts

@@ -138,7 +138,6 @@ export function expectFilePath(
 ): string {
   return join(
     root,
-    'scripts',
     'sandbox',
     'fixtures',
     category,

package/src/shipped/references.ts

@@ -36,13 +36,10 @@ export const SHIPPED_CORPORA = [
 
 /**
  * Trees inside a corpus above that no target receives, matching the negations
- * the `files` field already makes. A number under either names something its
- * only reader can already resolve.
+ * the `files` field already makes. A number under one names something its only
+ * reader can already resolve.
  */
-export const SHIPPED_EXCLUSIONS = [
-  /^scripts\/sandbox\//,
-  /^scripts\/eval\//,
-] as const
+export const SHIPPED_EXCLUSIONS = [/^scripts\/eval\//] as const
 
 /** Whether a repository-relative path sits in the gated corpus. */
 export function isShippedCorpus(path: string): boolean {
@@ -97,10 +94,11 @@ const PULL_REQUEST = /(?<![0-9A-Za-z_])#([0-9]+)(?![0-9A-Za-z_])/g
  * The third is the one a later author meets. Admitting an all-digit sha admits
  * every run of seven or more decimal digits with it, so a date written without
  * separators, a large count, or a float artifact reads as a commit reference.
- * The corpus carries no instance and that is the exclusions rather than luck:
- * twelve such runs sit under the seven roots, eleven of them under
- * `scripts/sandbox/`, `scripts/eval/`, or a test file, and the twelfth is the
- * genuine sha in `orchestrator-poll.md`. Write a seven-digit measurement into a
+ * The corpus carries no instance and that is the corpus bounds rather than luck:
+ * twelve such runs were counted when the scenario tree still sat under
+ * `scripts/`, eleven of them under that tree, `scripts/eval/`, or a test file,
+ * all now outside the corpus, and the twelfth is the genuine sha in
+ * `orchestrator-poll.md`. Write a seven-digit measurement into a
  * shipped page and the push fails on it, which the marker answers and no
  * narrowing can, since requiring a letter loses the all-digit sha above.
  */

package/src/targets/pulls.ts

@@ -8,7 +8,7 @@ const GH_TIMEOUT_MS = 30_000
  * The two headings a review pass posts under.
  *
  * Owned by `review-pr`, which states the full set once, and pinned here
- * the way `role-orchestrator/scripts/poll.sh` pins them. All three surfaces
+ * the way `role-orchestrator/scripts/poll.ts` pins them. All three surfaces
  * ship separately, so a heading added in that skill goes stale here with
  * nothing comparing the copies.
  */
@@ -139,7 +139,7 @@ export function rollup(checks: readonly RawCheck[]): ChecksState | null {
 
 /**
  * Reads the heading of the newest pass carrying one, matching on the first line
- * alone the way `poll.sh` does.
+ * alone the way `poll.ts` does.
  *
  * The reviews arrive oldest first, so the last match is the current state of
  * the thread. A pass carrying neither heading is somebody reviewing by hand and

package/tsconfig.json

@@ -11,5 +11,5 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "claude/skills/*/scripts/**/*.ts"]
 }