@erclx/canon 4.68.0 → 4.69.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.68.0",
+  "version": "4.69.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/commands.md

@@ -68,6 +68,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon claude skills reach`      | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one                                                                                                                                                                                             |
 | `canon claude skills rank`       | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)                                                                                                                                                                        |
 | `canon claude routing`           | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)                                                                                                                                                                                         |
+| `canon claude plugin-update`     | Match the installed marketplace plugin against `claude/.claude-plugin/plugin.json`'s own name and run `claude plugin update` on it, reading the version back off `claude plugin list --json` since the update call reports none of its own (`--json`)                                                                  |
 | `canon gov test-order`           | Report where an implementation reached history ahead of the test covering it (`--json`)                                                                                                                                                                                                                                |
 | `canon gov superseded`           | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`)                                                                                                                                                  |
 | `canon gov restated`             | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)                                                                                                                                                   |

package/docs/agents/sandbox.md

@@ -22,17 +22,18 @@ Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` s
 `canon sandbox check <category>:<command> [arm]` scores a provisioned sandbox against the arm's `expect.toml`, printing a verdict on stderr and, with `--json`, the same verdict as a record on stdout.
 
 ```bash
-canon sandbox check claude:docs drift --json
+canon sandbox check claude:docs-fold drift --json
 ```
 
-| Flag                | Effect                                                                      |
-| ------------------- | --------------------------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text                   |
-| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope                  |
-| `--escapes <file>`  | Newline-delimited paths written to a watched toolkit root, for escape scope |
-| `--escapes-watched` | At least one watched root held a target this run                            |
-| `--json`            | Emit the verdict record on stdout                                           |
-| `--strict`          | Exit 1 on `unchecked` instead of 0                                          |
+| Flag                           | Effect                                                                                                            |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `--envelope <file>`            | Read `is_error`, `num_turns`, denials, and the reply text                                                         |
+| `--writes <file>`              | Newline-delimited paths the session wrote, for write scope                                                        |
+| `--escapes <file>`             | Newline-delimited paths written to a watched toolkit root, for escape scope                                       |
+| `--escapes-watched`            | At least one watched root held a target this run                                                                  |
+| `--concurrent-sessions <file>` | Newline-delimited sessions live in the registry both before and after this run, a witness for an unbounded escape |
+| `--json`                       | Emit the verdict record on stdout                                                                                 |
+| `--strict`                     | Exit 1 on `unchecked` instead of 0                                                                                |
 
 The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
 
@@ -70,4 +71,6 @@ A skill pairs to a scenario by filename, `<category>-<command>` first and bare `
 
 `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/sandbox-runs/<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, and `reap` for what the run found in the session's process group afterwards. Neither field fails a run on its own.
+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.
+
+`run.sh` passes `concurrent` through `--concurrent-sessions` to `sandbox check`, and `checkEscapeScope` appends a witness count to an `unbounded escape:` message rather than lets it soften the verdict.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.68.0",
+  "version": "4.69.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/lib/sandbox-dispatch.sh

@@ -162,6 +162,14 @@ sessions_between() {
   comm -13 "$1" "$2"
 }
 
+# The side `sessions_between` drops. A record present on both sides is a session
+# that was already running before this run started and still was after, which
+# rules it out as this run's own dispatch and rules it in as a witness able to
+# explain a write the escape watch attributes to nobody.
+sessions_concurrent() {
+  comm -12 "$1" "$2"
+}
+
 # Turns a record name into a line a person can act on. The file can be gone by
 # the time this reads it, since a session that started and exited inside the run
 # takes its record with it, so an unreadable record still reports its name rather

package/src/claude/plugin-update.ts

@@ -0,0 +1,48 @@
+/** One row of `claude plugin list --json`, the fields this module reads. */
+export interface PluginInstall {
+  readonly id: string
+  readonly version: string
+}
+
+/**
+ * The plugin's own name, out of a `plugin.json` buffer. `undefined` on
+ * anything that fails to parse or carries no string `name`, so a caller
+ * refuses rather than matching against `undefined@`.
+ */
+export function readPluginName(manifest: string): string | undefined {
+  try {
+    const parsed = JSON.parse(manifest) as { name?: unknown }
+    return typeof parsed.name === 'string' ? parsed.name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export type MatchResult =
+  | { readonly kind: 'matched'; readonly install: PluginInstall }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'many'; readonly installs: readonly PluginInstall[] }
+
+/**
+ * `id` is `<name>@<marketplace>`, so a name alone can match more than one row
+ * when the same plugin is installed from two marketplaces at once. Refusing
+ * that case rather than picking a row is the same move `readPluginName`
+ * makes: nothing here guesses at an ambiguity the caller can see plainly.
+ */
+export function matchInstall(
+  name: string,
+  installs: readonly PluginInstall[],
+): MatchResult {
+  const prefix = `${name}@`
+  const matches = installs.filter((install) => install.id.startsWith(prefix))
+
+  if (matches.length === 0) return { kind: 'none' }
+  if (matches.length > 1) return { kind: 'many', installs: matches }
+  return { kind: 'matched', install: matches[0] as PluginInstall }
+}
+
+export function updatedMessage(before: string, after: string): string {
+  return after === before
+    ? `Reinstalled ${after}, unchanged.`
+    : `Updated ${before} to ${after}.`
+}

package/src/commands/claude.ts

@@ -3,7 +3,16 @@ import { chmod, readFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
+import { execa } from 'execa'
+import { singleLine } from '@/commands/upgrade'
+import { gitEnv } from '@/git-env'
 import { claudeChain, pendingEntries, planGitignore } from '@/claude/gitignore'
+import {
+  matchInstall,
+  type PluginInstall,
+  readPluginName,
+  updatedMessage,
+} from '@/claude/plugin-update'
 import {
   applySeeds,
   countByScope,
@@ -90,6 +99,37 @@ interface SkillsDriftOptions {
   readonly json?: boolean
 }
 
+interface PluginUpdateOptions {
+  readonly json?: boolean
+}
+
+/**
+ * `no-claude` and `no-plugin` name permanent conditions on a machine that
+ * never carries the marketplace plugin at all, matching the `gh-missing` and
+ * `no-repository` reasons `.husky/post-merge`'s other two steps already stay
+ * quiet on forever rather than nagging a project that will never fix them.
+ * Every other reason is a real defect and prints.
+ */
+type PluginUpdateReason =
+  | 'no-claude'
+  | 'no-manifest'
+  | 'no-name'
+  | 'list-failed'
+  | 'no-plugin'
+  | 'ambiguous'
+  | 'update-failed'
+  | 'after-list-failed'
+
+interface PluginUpdateRecord {
+  readonly root: string
+  readonly id?: string
+  readonly before?: string
+  readonly after?: string
+  readonly state: 'updated' | 'current' | 'refused'
+  readonly reason?: PluginUpdateReason
+  readonly message: string
+}
+
 interface SkillsReachOptions {
   readonly json?: boolean
 }
@@ -111,11 +151,24 @@ const SEEDED_FILES: readonly string[] = [
 const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
 const USER_DIR = join('tooling', 'claude', 'user')
 const STATUSLINE = 'statusline-command.sh'
+const PLUGIN_MANIFEST = join('claude', '.claude-plugin', 'plugin.json')
+
+/** A local cache read, not a network round trip, matching reclaim.ts's own bound for `claude agents --json`. */
+const PLUGIN_LIST_TIMEOUT_MS = 10_000
+
+/**
+ * `claude plugin update` fetches a marketplace archive over the network, so a
+ * stalled fetch should not hang the caller, which is a git hook on the
+ * ordinary path.
+ */
+const PLUGIN_UPDATE_TIMEOUT_MS = 60_000
 
 export function register(program: Command): void {
   const claude = program
     .command('claude')
-    .description('Claude workflow (init, seeds, sync, setup, routing)')
+    .description(
+      'Claude workflow (init, seeds, sync, setup, routing, plugin-update)',
+    )
     .helpOption('-h, --help', 'Show this help message')
     .addHelpText(
       'after',
@@ -227,6 +280,39 @@ export function register(program: Command): void {
       process.exitCode = runRouting(path, opts)
     })
 
+  claude
+    .command('plugin-update')
+    .description(
+      'Update the installed marketplace plugin cache to match this CLI',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Mechanics:',
+        '  Reads the plugin name out of claude/.claude-plugin/plugin.json,',
+        '  matches it against an installed row from `claude plugin list',
+        '  --json` by id prefix (<name>@), then runs `claude plugin update',
+        '  <id> -y`. There is no --json on the update call itself, so the',
+        '  version is read back off `claude plugin list --json` again and',
+        '  compared to what it was before.',
+        '',
+        'Exit codes:',
+        '  0  current already, or the update ran',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon claude plugin-update',
+        '  canon claude plugin-update --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PluginUpdateOptions) => {
+      process.exitCode = await runPluginUpdate(opts)
+    })
+
   const skills = claude
     .command('skills')
     .description('Plugin skill catalog (list, audit, drift, reach, rank)')
@@ -830,6 +916,200 @@ function reportRouting(
   )
 }
 
+/**
+ * Reads the plugin name off the manifest, matches it against an installed row,
+ * runs the update, and reads the version back off the same list rather than
+ * trusting the update call's own report, since `claude plugin update` carries
+ * no `--json` to answer with. `canon upgrade` makes the identical move for the
+ * package managers it drives.
+ */
+async function runPluginUpdate(opts: PluginUpdateOptions): Promise<number> {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  intro('canon claude plugin-update')
+  if (mismatch !== undefined) logWarn(mismatch)
+
+  const manifestPath = join(PROJECT_ROOT, PLUGIN_MANIFEST)
+  let manifestText: string
+  try {
+    manifestText = await readFile(manifestPath, 'utf8')
+  } catch {
+    return refusePluginUpdate(
+      opts,
+      'no-manifest',
+      `No manifest at ${manifestPath}, so there is no plugin name to update.`,
+    )
+  }
+
+  const name = readPluginName(manifestText)
+  if (name === undefined) {
+    return refusePluginUpdate(
+      opts,
+      'no-name',
+      `No name field in ${manifestPath}, so there is nothing to match against an installed plugin.`,
+    )
+  }
+
+  logStep('Manifest')
+  logInfo(`${name}, from ${manifestPath}`)
+
+  const before = await listPluginInstalls()
+  if (before.kind === 'missing') {
+    return refusePluginUpdate(
+      opts,
+      'no-claude',
+      'claude is not on PATH, so no installed plugin could be read.',
+    )
+  }
+  if (before.kind === 'failed') {
+    return refusePluginUpdate(
+      opts,
+      'list-failed',
+      `\`claude plugin list --json\` failed. ${before.detail}`,
+    )
+  }
+
+  const match = matchInstall(name, before.installs)
+  if (match.kind === 'none') {
+    return refusePluginUpdate(
+      opts,
+      'no-plugin',
+      `No installed plugin carries the id prefix "${name}@". Install it with \`claude plugin install\` first.`,
+    )
+  }
+  if (match.kind === 'many') {
+    return refusePluginUpdate(
+      opts,
+      'ambiguous',
+      `Multiple installed plugins share the name "${name}": ${match.installs
+        .map((install) => install.id)
+        .join(', ')}. Refusing rather than picking one.`,
+    )
+  }
+
+  const { install } = match
+  logStep('Installed')
+  logInfo(`${install.id} ${install.version}`)
+
+  logStep('Updating')
+  const result = await execa('claude', ['plugin', 'update', install.id, '-y'], {
+    reject: false,
+    timeout: PLUGIN_UPDATE_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.exitCode !== 0) {
+    return refusePluginUpdate(
+      opts,
+      'update-failed',
+      `\`claude plugin update ${install.id} -y\` exited ${result.exitCode}. ${(result.stderr || result.stdout).trim()}`,
+      install.id,
+      install.version,
+    )
+  }
+
+  const after = await listPluginInstalls()
+  if (after.kind !== 'ok') {
+    return refusePluginUpdate(
+      opts,
+      'after-list-failed',
+      '`claude plugin update` ran, but `claude plugin list --json` failed to read the version back.',
+      install.id,
+      install.version,
+    )
+  }
+
+  const afterVersion =
+    after.installs.find((row) => row.id === install.id)?.version ??
+    install.version
+  const state = afterVersion === install.version ? 'current' : 'updated'
+
+  logStep('Installed')
+  logInfo(
+    afterVersion === install.version
+      ? `${afterVersion}, unchanged`
+      : `${install.version} to ${afterVersion}`,
+  )
+  outro()
+
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    id: install.id,
+    before: install.version,
+    after: afterVersion,
+    state,
+    message: updatedMessage(install.version, afterVersion),
+  })
+  return 0
+}
+
+type ListInstallsResult =
+  | { readonly kind: 'ok'; readonly installs: readonly PluginInstall[] }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'failed'; readonly detail: string }
+
+/**
+ * `missing` separates a `claude` binary that is not on PATH from every other
+ * failure, since only that condition is permanent enough for the hook to
+ * silence forever. execa reports it as `ENOENT` on the result rather than by
+ * throwing, because the call runs with `reject: false`.
+ */
+async function listPluginInstalls(): Promise<ListInstallsResult> {
+  const result = await execa('claude', ['plugin', 'list', '--json'], {
+    reject: false,
+    timeout: PLUGIN_LIST_TIMEOUT_MS,
+    env: gitEnv(),
+    extendEnv: false,
+  })
+
+  if (result.code === 'ENOENT') return { kind: 'missing' }
+  if (result.exitCode !== 0) {
+    return { kind: 'failed', detail: (result.stderr || result.stdout).trim() }
+  }
+
+  try {
+    return {
+      kind: 'ok',
+      installs: JSON.parse(result.stdout) as readonly PluginInstall[],
+    }
+  } catch {
+    return {
+      kind: 'failed',
+      detail: '`claude plugin list --json` did not print valid JSON.',
+    }
+  }
+}
+
+function refusePluginUpdate(
+  opts: PluginUpdateOptions,
+  reason: PluginUpdateReason,
+  message: string,
+  id?: string,
+  before?: string,
+): number {
+  outro()
+  frameError(message)
+  emitPluginUpdate(opts, {
+    root: PROJECT_ROOT,
+    ...(id === undefined ? {} : { id }),
+    ...(before === undefined ? {} : { before }),
+    state: 'refused',
+    reason,
+    message,
+  })
+  return 1
+}
+
+function emitPluginUpdate(
+  opts: PluginUpdateOptions,
+  record: PluginUpdateRecord,
+): void {
+  if (opts.json !== true) return
+  process.stdout.write(
+    `${JSON.stringify({ ...record, message: singleLine(record.message) })}\n`,
+  )
+}
+
 /** What a reader does about the one way the corpus fails to build. */
 const REACH_REFUSALS: Record<ReachRefusal, string> = {
   'no-skills':

package/src/commands/feedback.ts

@@ -7,11 +7,11 @@ import {
   missingField,
   missingFieldMessage,
 } from '@/commands/feedback-format'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
 import { issueFailureMessage } from '@/github-format'
-import { frameError, frameSuccess, palette } from '@/ui'
+import { frameError, frameSuccess, logWarn, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
   return new Promise((resolveStream, rejectStream) => {
@@ -45,7 +45,7 @@ function isToolkitSource(): boolean {
  * hand, so each writes under its own name and the enclosing folder keeps the
  * single ignore entry and the single backed-folder entry it already had.
  */
-function writeLocal(body: string): string {
+function writeLocal(body: string, mismatch: string | undefined): string {
   // Resolved against the same root the write joins onto, so a checkout that has
   // not migrated its records writes this beside the ones already there rather
   // than opening a second root nothing reads.
@@ -55,7 +55,16 @@ function writeLocal(body: string): string {
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
   const filePath = join(reviewDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
-  frameSuccess('canon feedback', join(relativeDir, filename))
+
+  // Manual frame rather than `frameSuccess`, since the mismatch warning is a
+  // frame-interior line landing between the opener and the command title,
+  // matching the convention `#1587` set at its other six sites.
+  const { GREEN, GREY, NC, WHITE } = palette(process.stderr)
+  process.stderr.write(`${GREY}┌${NC}\n`)
+  if (mismatch !== undefined) logWarn(mismatch)
+  process.stderr.write(
+    `${GREY}│${NC} ${WHITE}canon feedback${NC}\n${GREY}│${NC}\n${GREY}│${NC} ${GREEN}✓${NC} ${join(relativeDir, filename)}\n${GREY}└${NC}\n`,
+  )
   return filePath
 }
 
@@ -124,7 +133,8 @@ export function register(program: Command): void {
         return
       }
 
-      const filePath = writeLocal(body)
+      const mismatch = checkoutMismatchWarning(process.cwd())
+      const filePath = writeLocal(body, mismatch)
       process.stdout.write(`${filePath}\n`)
     })
 }

package/src/commands/gate.ts

@@ -12,7 +12,7 @@ import {
   summarize,
 } from '@/gate/sequencer'
 import { STAGES } from '@/gate/stages'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   intro,
   logError,
@@ -89,6 +89,7 @@ export function register(program: Command): void {
 
 async function runGate(opts: RunCommandOptions): Promise<number> {
   const root = PROJECT_ROOT
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const emitJson = opts.json ?? false
   const nested = opts.nested ?? false
   const write = opts.write ?? true
@@ -102,6 +103,7 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
     ? { scoped: false, files: [] }
     : await collectChangedFiles(run)
   if (!emitJson && changed.notice !== undefined) logWarn(changed.notice)
+  if (mismatch !== undefined) logWarn(mismatch)
 
   const ctx: GateContext = {
     root,

package/src/commands/sandbox.ts

@@ -78,6 +78,7 @@ interface CheckOptions {
   readonly writes?: string
   readonly escapes?: string
   readonly escapesWatched?: boolean
+  readonly concurrentSessions?: string
   readonly json?: boolean
   readonly strict?: boolean
 }
@@ -349,7 +350,7 @@ function runCheck(
 
   const parsed = parseTarget(target)
   if (parsed === undefined) {
-    logError('Invalid target. Use <category>:<command>, e.g. claude:docs.')
+    logError('Invalid target. Use <category>:<command>, e.g. claude:docs-fold.')
     outro()
     process.exitCode = 1
     return
@@ -376,6 +377,7 @@ function runCheck(
         options.escapes === undefined
           ? undefined
           : options.escapesWatched === true,
+      concurrentSessions: readPathList(options.concurrentSessions),
       envelope: readEnvelope(options.envelope),
     },
   )
@@ -414,7 +416,10 @@ export function register(program: Command): void {
   sandbox
     .command('check')
     .description('Check a provisioned sandbox against a scenario expectation')
-    .argument('<target>', 'Scenario as <category>:<command>, e.g. claude:docs')
+    .argument(
+      '<target>',
+      'Scenario as <category>:<command>, e.g. claude:docs-fold',
+    )
     .argument('[arm]', 'Named scenario arm, e.g. drift')
     .helpOption('-h, --help', 'Show this help message')
     .option('--envelope <file>', 'Run envelope JSON from claude -p')
@@ -427,6 +432,10 @@ export function register(program: Command): void {
       '--escapes-watched',
       'At least one watched root held a target this run, so a zero-escape file is a clean watch rather than one with nothing to watch',
     )
+    .option(
+      '--concurrent-sessions <file>',
+      'Newline-delimited sessions live in the registry both before and after this run, a witness for an unbounded escape',
+    )
     .option('--json', 'Emit the verdict as JSON on stdout')
     .option('--strict', 'Exit non-zero when the arm declares no expectation')
     .addHelpText(
@@ -434,8 +443,8 @@ export function register(program: Command): void {
       [
         '',
         'Examples:',
-        '  canon sandbox check claude:docs drift',
-        '  canon sandbox check claude:docs drift --envelope run.json --json',
+        '  canon sandbox check claude:docs-fold drift',
+        '  canon sandbox check claude:docs-fold drift --envelope run.json --json',
         '',
         'Exit codes: 0 on pass or unchecked, 1 on failure.',
         'With --strict, unchecked exits 1 as well.',

package/src/design/components.ts

@@ -998,6 +998,18 @@ h2 .count {
   line-height: 1.55;
 }
 
+.gloss-group {
+  margin: 1.1rem 0 0.4rem;
+  font-family: var(--teach-sans);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--color-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.gloss-group:first-of-type { margin-top: 0; }
+
 .gterm b { font-weight: 700; }
 /* The markdown source separates a term from its definition with a colon,
    and the house standard bans an em dash outright, so the view mirrors

package/src/gate/measures.ts

@@ -110,6 +110,17 @@ export const GOV_EXPECTED_UNREFERENCED = ['260-shadcn', '320-tanstack-query']
  */
 export const SANDBOX_UNDECLARED_CEILING = 47
 
+/**
+ * Skills the sandbox skill census reports `asserted`, taken from `canon
+ * sandbox coverage --skills` against a clean tree. A dropped pairing lowers
+ * this directly, unlike the ceiling above, which a rename can starve without
+ * moving: fourteen arms drifted off their skill's name in one branch and the
+ * scenario-level ceiling stayed green throughout, since it counts scenarios
+ * declaring an expectation rather than skills a scenario reaches. Lowering
+ * this floor is a deliberate edit that says which skill lost its arm and why.
+ */
+export const SANDBOX_ASSERTED_FLOOR = 26
+
 /**
  * The retained counts the audit stage compares each run against. Spelled here
  * rather than derived, because this stage only ever names the file in a remedy
@@ -740,10 +751,45 @@ export const sandboxCoverage: Measure = async (ctx) => {
     }
   }
 
+  const scenarioEmission = info(
+    `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+  )
+
+  const skillsRun = await ctx.cli(['sandbox', 'coverage', '--skills', '--json'])
+
+  if (skillsRun.exitCode !== 0) {
+    return {
+      emissions: [scenarioEmission],
+      unmeasured: `The skill census did not report (exit ${skillsRun.exitCode}). It ships in the checkout beside the scenario report, so a run that does not report is a broken command rather than an absent census.`,
+    }
+  }
+
+  const skillsRecord = parseJson(skillsRun.stdout) as
+    | { asserted?: unknown; totalSkills?: unknown }
+    | undefined
+  const asserted = skillsRecord?.asserted
+  const totalSkills = skillsRecord?.totalSkills
+
+  if (typeof asserted !== 'number' || typeof totalSkills !== 'number') {
+    return {
+      emissions: [scenarioEmission],
+      failure:
+        'The skill census carried no asserted total, so the stage measured nothing. Run bun src/cli.ts sandbox coverage --skills --json.',
+    }
+  }
+
+  if (asserted < SANDBOX_ASSERTED_FLOOR) {
+    return {
+      emissions: [scenarioEmission],
+      failure: `${asserted} of ${totalSkills} skills asserted, under the floor of ${SANDBOX_ASSERTED_FLOOR}. A rename or a moved arm likely dropped a skill's pairing; repair the arm's filename against its skill and say which skill lost its arm, or lower SANDBOX_ASSERTED_FLOOR in src/gate/measures.ts.`,
+    }
+  }
+
   return {
     emissions: [
+      scenarioEmission,
       info(
-        `${armed} of ${total} scenarios declare expectations, ${undeclared} undeclared against a ceiling of ${SANDBOX_UNDECLARED_CEILING}`,
+        `${asserted} of ${totalSkills} skills asserted, against a floor of ${SANDBOX_ASSERTED_FLOOR}`,
       ),
     ],
   }

package/src/sandbox/expect.ts

@@ -78,6 +78,14 @@ export interface CheckInput {
    * nothing to watch, both of which produce the same empty `escapes` list.
    */
   readonly escapesWatched?: boolean
+  /**
+   * Names of sessions the client's own registry carried both before and after
+   * the run, so present rather than dispatched by it. Undefined when the
+   * caller supplied none, which is not the same as a run that had no witness:
+   * the registry carries no contract, so a client that stops writing a record
+   * per session makes this list empty regardless of who else was live.
+   */
+  readonly concurrentSessions?: readonly string[]
   readonly envelope?: RunEnvelope
 }
 
@@ -386,11 +394,19 @@ function checkWriteScope(
  * 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
  * had the target to take.
+ *
+ * A witnessed concurrent session never softens the verdict. `concurrentSessions`
+ * is evidence a reader can act on without a second lookup, appended to the
+ * message on an unbounded escape, never a reason to pass or skip one: a session
+ * merely alive throughout the run proves someone else was busy, not that a
+ * given file is theirs, and a real dispatch escape reads identically to an
+ * innocent sibling's write either way.
  */
 function checkEscapeScope(
   expectation: Expectation,
   escapes: readonly string[] | undefined,
   watched: boolean | undefined,
+  concurrentSessions: readonly string[] | undefined,
 ): KindOutcome {
   if (expectation.escapeScope === undefined) return { results: [], skipped: [] }
 
@@ -416,12 +432,20 @@ function checkEscapeScope(
   }
 
   const globs = expectation.escapeScope.map((glob) => new Bun.Glob(glob))
+  const witnessCount = concurrentSessions?.length ?? 0
+  const witnessSuffix =
+    witnessCount > 0
+      ? ` (${witnessCount} session${witnessCount === 1 ? '' : 's'} live throughout the run)`
+      : ''
 
   return {
     results: escapes.map((path) =>
       globs.some((glob) => glob.match(path))
         ? { ok: true, message: `declared escape: ${path}` }
-        : { ok: false, message: `unbounded escape: ${path}` },
+        : {
+            ok: false,
+            message: `unbounded escape: ${path}${witnessSuffix}`,
+          },
     ),
     skipped: [],
   }
@@ -514,6 +538,7 @@ export function checkExpectation(
     expectation,
     input.escapes,
     input.escapesWatched,
+    input.concurrentSessions,
   )
   const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)

package/src/teach/nav.ts

@@ -109,6 +109,17 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
   var input = document.getElementById("gfilter");
   var list = document.getElementById("gloss");
   if (!input || !list) return;
+  function updateGroups() {
+    list.querySelectorAll(".gloss-group").forEach(function (heading) {
+      var el = heading.nextElementSibling;
+      var any = false;
+      while (el && !el.classList.contains("gloss-group")) {
+        if (el.style.display !== "none") any = true;
+        el = el.nextElementSibling;
+      }
+      heading.style.display = any ? "" : "none";
+    });
+  }
   input.addEventListener("input", function () {
     var q = input.value.toLowerCase();
     var n = 0;
@@ -118,6 +129,7 @@ const GLOSSARY_FILTER_SCRIPT = `<script>
       if (match) n++;
     });
     list.classList.toggle("none", n === 0);
+    updateGroups();
   });
   var clear = list.querySelector(".clear");
   if (clear) {
@@ -457,8 +469,90 @@ function renderGlossaryEntry(entry: string): string {
   return `<div class="gterm"><b>${escapeHtml(term)}</b><span>${escapeHtml(definition)}</span></div>`
 }
 
-function renderGlossarySection(entries: readonly string[]): string {
-  const rendered = entries.map(renderGlossaryEntry).join('')
+const FIRST_SEEN_PATTERN = / First seen in (.+)\.$/
+
+/**
+ * The lesson or reference page an entry's own "First seen in" sentence
+ * names, absent when the entry predates that citation convention.
+ */
+function firstSeenFile(entry: string): string | undefined {
+  return FIRST_SEEN_PATTERN.exec(entry)?.[1]
+}
+
+/**
+ * `firstSeenFile` names a page free-form, per the `--first-seen` flag it
+ * comes from, so it may carry a directory prefix a lesson's own `file` does
+ * not. Comparing basenames is what keeps `lessons/0001-x.html` and
+ * `0001-x.html` resolving to the same lesson without a suffix match risking
+ * a false hit across two differently-prefixed filenames.
+ */
+function matchingLesson(
+  file: string,
+  metas: readonly LessonMeta[],
+): LessonMeta | undefined {
+  const basename = file.split('/').pop()
+  return metas.find((meta) => meta.file === basename)
+}
+
+interface GlossaryGroup {
+  readonly heading: string
+  readonly entries: readonly string[]
+}
+
+const OTHER_TERMS_HEADING = 'Other terms'
+
+/**
+ * Groups already-alphabetical glossary entries by the lesson their own
+ * "First seen in" sentence names, in lesson order. An entry naming a
+ * reference page instead, or carrying no citation at all, cannot be
+ * attributed to a lesson and trails in its own group, keeping the
+ * alphabetical order the source entries already carry.
+ */
+function groupGlossaryEntries(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): readonly GlossaryGroup[] {
+  const byLesson = new Map<string, string[]>()
+  const other: string[] = []
+
+  for (const entry of entries) {
+    const file = firstSeenFile(entry)
+    const lesson = file ? matchingLesson(file, metas) : undefined
+
+    if (lesson) {
+      const list = byLesson.get(lesson.file) ?? []
+      list.push(entry)
+      byLesson.set(lesson.file, list)
+    } else {
+      other.push(entry)
+    }
+  }
+
+  const groups: GlossaryGroup[] = []
+  for (const meta of metas) {
+    const list = byLesson.get(meta.file)
+    if (list) groups.push({ heading: meta.title, entries: list })
+  }
+  if (other.length > 0) {
+    groups.push({ heading: OTHER_TERMS_HEADING, entries: other })
+  }
+
+  return groups
+}
+
+function renderGlossaryGroup(group: GlossaryGroup): string {
+  const entries = group.entries.map(renderGlossaryEntry).join('')
+
+  return `<h3 class="gloss-group">${escapeHtml(group.heading)}</h3>${entries}`
+}
+
+function renderGlossarySection(
+  entries: readonly string[],
+  metas: readonly LessonMeta[],
+): string {
+  const rendered = groupGlossaryEntries(entries, metas)
+    .map(renderGlossaryGroup)
+    .join('')
 
   return `<h2>Glossary <span class="count">${entries.length}</span></h2>
 <input class="filter" type="search" id="gfilter" aria-label="Filter glossary terms" aria-controls="gloss" placeholder="term">
@@ -610,7 +704,7 @@ async function renderContentsPage(
     referenceRows
       ? `<h2>Reference pages</h2>\n<ul class="toc">${referenceRows}</ul>`
       : '',
-    renderGlossarySection(detail.glossary),
+    renderGlossarySection(detail.glossary, metas),
   ]
     .filter((section) => section !== '')
     .join('\n\n')

package/standards/glossary.md

@@ -58,6 +58,14 @@ A glossary failing these is non-conforming even when it satisfies every shape ru
 - Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
 - State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
 
+## Rendered grouping
+
+Applies to a rendered glossary page, never to the source file above, which stays the flat alphabetical list the `## Grouping` rules above govern.
+
+- Group a rendered glossary by the lesson its own "First seen in" citation names, ordered by lesson order, under a sub-heading naming the lesson's title rather than its filename.
+- Trail with an "Other terms" group holding any entry the citation cannot attribute to a lesson, whether it names a reference page instead or carries no citation at all. Keep it in the alphabetical order the source file already carries.
+- Keep the workspace-wide term filter matching against every group, and drop a group's own heading once filtering leaves nothing under it.
+
 ## Template
 
 ```markdown