@erclx/canon 4.31.1 → 4.32.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.31.1",
+  "version": "4.32.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/references/orchestrator-handoff.md

@@ -17,6 +17,8 @@ Name the planner as the case always in this set, and scope the act no narrower.
 
 Retire what this session dispatched. Report a hand-launched session and leave the act to the operator, since the knowledge making the act safe is a delivery this session received and it received nothing from a session it never launched. The `worker-` and `planner-` name prefixes separate the two populations, per `orchestrator-dispatch.md`.
 
+A capability gap sits beside the knowledge gap, and it holds even where delivery is somehow known. A hand-launched session is as often interactive as background, and `claude rm <id>` has no id to take for an interactive one at all, so the command cannot reach it whatever this session learned about its delivery.
+
 ### Telling a delivered session from a blocked one
 
 No status field carries the difference. `status` reads `busy` or `waiting` straight off the client record, and both describe the last turn rather than the work, so `waiting` is the ordinary answer for a session that reported and stopped, which is what a correct delivery looks like. The `statusDwellMs` beside it separates a long idle from a short one and separates nothing else.
@@ -25,7 +27,7 @@ The read is the report this session is holding. Retire a session whose delivery
 
 ### The act, and the order it runs in
 
-`claude rm <id>` removes a background session and its worktree together, and it takes one target per call, so a wave costs one call per session. The argument is the id rather than the name, which `claude agents --json` carries beside the name on every row, so a session read off a roster by name is matched to its id there before the call. Both readings are from 2026-09-02, where the name form answered `No job matching`.
+`claude rm <id>` is meant to remove a background session and its worktree together, though its own report is not reliable, so `canon worktrees list` is the reading to trust afterward. It takes one target per call, so a wave costs one call per session. The argument is the id rather than the name, which `claude agents --json` carries beside the name on every row, so a session read off a roster by name is matched to its id there before the call. Both readings are from 2026-09-02, where the name form answered `No job matching`.
 
 The command belongs to the client rather than to this toolkit, so a target running another client performs whatever removal that client offers.
 

package/docs/agents/worktrees.md

@@ -89,11 +89,14 @@ The read is one `gh pr list --state merged` for the whole repository rather than
 
 `route` names which one applies rather than choosing it, since picking wrong strands state.
 
-- `session`: a live session holds the directory, and `claude rm <id>` removes the session and its worktree together. The `sessions` field carries names rather than ids, and a name is whatever string the session was launched under, spaces included, so quote it and match it against `claude agents --json`, which carries the id beside the name on every row.
+- `session`: a live session holds the directory, and the `sessions` field carries `{name, kind, id}` per holder rather than a bare name, since `claude rm <id>` takes the id and never the name. `kind` reads `bg` or `interactive` off this repository's session registry.
+  - A resolved background holder: `id` carries the value `claude agents --json` reports, so `claude rm <id>` is the command to run. Its own report is not reliable: two runs under matched conditions on 2026-09-03 both printed `kept`, and one of them had already removed the worktree, so read `canon worktrees list` again afterward rather than trust what the command printed.
+  - An unresolved background holder: `id` is `null` because the binary is missing, fails, or has not reported that pid yet, so its id has to come from a manual read of `claude agents --json` instead.
+  - An interactive holder: `id` is always `null`, since no id exists for one at all, and nothing removes it until a person closes its terminal.
 - `worktree`: the session has ended, and `canon worktrees reclaim` is what runs the remove and the branch delete.
 - `null`: the main worktree, which no removal shape reaches.
 
-A held worktree is refused rather than reported reclaimable, and its route is reported for whoever decides to act on it. Deleting a directory underneath a live session is the case that has to refuse.
+A held worktree is refused rather than reported reclaimable, and its route is reported for whoever decides to act on it. Deleting a directory underneath a live session is the case that has to refuse, and an interactive holder is the one shape inside that refusal with no removal route at all.
 
 ## What an unreadable input does
 

package/package.json

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

package/src/client-commands.ts

@@ -0,0 +1,99 @@
+import { escapeForPattern, isMarked } from '@/exempt-marker'
+
+/**
+ * A client command this repository quotes, with the argument spelling every
+ * quotation of it has to carry.
+ *
+ * `source` is the fact grounding `canonicalArgument`, so a reader correcting a
+ * flagged line can see why the flagged form is wrong rather than taking the
+ * table on faith.
+ */
+export interface ClientCommand {
+  readonly command: string
+  readonly canonicalArgument: string
+  readonly source: string
+}
+
+export const CLIENT_COMMANDS: readonly ClientCommand[] = [
+  {
+    command: 'claude rm',
+    canonicalArgument: 'id',
+    source:
+      '`claude rm <id>` takes the session id `claude agents --json` carries beside a name, never the name itself, confirmed against `claude rm --help` on 2026-09-02.',
+  },
+]
+
+export const CLIENT_COMMAND_MARKER = 'canon-allow-client-command'
+
+/**
+ * A bracketed placeholder or a template interpolation, each optionally
+ * single-quoted, which is the one call form this scanner reads. A sentence
+ * naming the command with no bracketed argument carries no placeholder at all
+ * and never matches, which is deliberate: the defect this closes is a wrong
+ * argument shown as an invocation, not a sentence that never showed one.
+ *
+ * The interpolation half admits a dotted path, since a property access is the
+ * ordinary shape a real call site interpolates, such as `${session.id}`, and a
+ * bare `${id}` is the rarer one that only a fixture writes. A capture stopping
+ * at the first `.` matched the command literal and missed the property access
+ * beside it entirely, which is how the check went unable to read the one call
+ * form this repository's own worktree listing writes.
+ */
+const PLACEHOLDER = `'?(?:<([\\w-]+)>|\\$\\{(\\w+(?:\\.\\w+)*)\\})'?`
+
+export interface ClientCommandCitation {
+  readonly file: string
+  /** One-based, matching the `file:line` form a reader clicks. */
+  readonly line: number
+  readonly command: string
+  /** The invocation as written, so a report names the text to correct. */
+  readonly text: string
+  readonly argument: string
+}
+
+/**
+ * Every quotation of a listed command in one file whose argument disagrees
+ * with the table, and no marker mutes.
+ *
+ * `commands` defaults to the shipped table and takes a narrower one only for
+ * the empty-table case a measure guards against, since production code never
+ * has a reason to check against anything else.
+ */
+export function clientCommandCitationsIn(
+  file: string,
+  text: string,
+  commands: readonly ClientCommand[] = CLIENT_COMMANDS,
+): ClientCommandCitation[] {
+  const lines = text.split('\n')
+  const citations: ClientCommandCitation[] = []
+
+  for (const { command, canonicalArgument } of commands) {
+    const pattern = new RegExp(
+      `${escapeForPattern(command)}\\s+${PLACEHOLDER}`,
+      'g',
+    )
+
+    for (const [index, line] of lines.entries()) {
+      if (isMarked(lines, index, CLIENT_COMMAND_MARKER)) continue
+
+      for (const match of line.matchAll(pattern)) {
+        const dotted = match[2]
+        const argument =
+          dotted !== undefined
+            ? (dotted.split('.').at(-1) ?? dotted)
+            : (match[1] ?? '')
+        if (argument === canonicalArgument) continue
+
+        citations.push({
+          file,
+          line: index + 1,
+          command,
+          text: match[0],
+          argument,
+        })
+      }
+    }
+  }
+
+  return citations
+}

package/src/commands/worktrees.ts

@@ -145,10 +145,12 @@ export function register(program: Command): void {
         ...CONDITIONS,
         '',
         'This reports and removes nothing. "route" names which removal shape',
-        'applies: "session" when a live session holds the directory, where',
-        '`claude rm <id>` takes the session and its worktree together, and',
-        '"worktree" when the session has ended, where `canon worktrees',
-        'reclaim` is the pair of a remove and a branch delete.',
+        'applies: "session" when a live session holds the directory,',
+        'where `claude rm <id>` is meant to remove it and its worktree',
+        'together, but its own report is not reliable, so run this command',
+        'again afterward to see what happened. "worktree" is the shape once',
+        'the session has ended, where `canon worktrees reclaim` is the pair',
+        'of a remove and a branch delete.',
         '',
         'Examples:',
         '  canon worktrees list',
@@ -185,8 +187,10 @@ export function register(program: Command): void {
         'gone sweeps stale registrations once before the branch deletes.',
         '',
         'It deletes only what a reading called reclaimable. A worktree a live',
-        'session holds is refused rather than removed, since `claude rm <id>`',
-        'is what takes a session and its worktree together.',
+        'session holds is refused rather than removed here. `claude rm <id>`',
+        'is meant to remove the session and its worktree together, but its',
+        'own report is not reliable, so run `canon worktrees list` again',
+        'afterward to see what happened.',
         '',
         'The stale-registration sweep is the one step that reaches wider, since',
         'git takes no path to scope it. It clears the bookkeeping for every',
@@ -429,20 +433,27 @@ function reportWorktrees(worktrees: readonly WorktreeVerdict[]): void {
  * what to remove, so a row phrased for the first alone leaves the second
  * removing a directory on a conclusion it cannot check.
  */
-function describe(verdict: WorktreeVerdict): string {
+export function describe(verdict: WorktreeVerdict): string {
   const held = verdict.branch ?? 'detached'
   const head = `${verdict.path}  ${held}`
 
   if (!verdict.reclaimable) {
     const reasons = verdict.refusals.map((refusal) => REFUSALS[refusal])
-    // A name is quoted because a session carries whatever string it was
-    // launched under, spaces included, and one command per name because a
-    // joined list reads as a single argument.
+    // Three cases rather than one line, since only a resolved background
+    // holder has a real command to print. An interactive holder has no id to
+    // look up at all, and an unresolved background one has an id somewhere in
+    // `claude agents --json` that this reading could not cross-reference.
     const routes =
       verdict.route === 'session'
-        ? verdict.sessions.map(
-            (name) => `\n  Removal there goes through: claude rm '${name}'`,
-          )
+        ? verdict.sessions.map((session) => {
+            if (session.kind === 'interactive') {
+              return `\n  ${session.name}: interactive, so nothing removes it until its terminal closes.`
+            }
+            if (session.id === null) {
+              return `\n  ${session.name}: match it against claude agents --json for its id, then claude rm '<id>'.`
+            }
+            return `\n  Removal there goes through: claude rm '${session.id}'`
+          })
         : []
     return `${head}\n  Refused: ${reasons.join('; ')}.${routes.join('')}`
   }

package/src/exempt-marker.ts

@@ -7,7 +7,7 @@
  * wrong lines and one holding a parenthesis throws, and neither failure is the
  * caller's to anticipate.
  */
-function escapeForPattern(token: string): string {
+export function escapeForPattern(token: string): string {
   return token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 }
 

package/src/gate/measures.ts

@@ -1,6 +1,13 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import {
+  CLIENT_COMMAND_MARKER,
+  CLIENT_COMMANDS,
+  type ClientCommand,
+  clientCommandCitationsIn,
+} from '@/client-commands'
+import { listRepositoryFiles } from '@/git-files'
 import {
   isShippedCorpus,
   REFERENCE_MARKER,
@@ -532,6 +539,69 @@ export const shippedReferences: Measure = async (ctx) => {
   }
 }
 
+/**
+ * Every git-tracked file quoting a listed client command with the wrong
+ * argument, over the whole tree rather than one corpus, since a wrong
+ * quotation can land in any file this repository writes.
+ *
+ * `commands` defaults to the shipped table and takes a narrower one only to
+ * cover the case where that table ships empty, which is a broken check rather
+ * than a clean tree, exactly as an empty ban set is for `markdownBans`.
+ */
+export const clientCommandCitations = async (
+  ctx: MeasureContext,
+  commands: readonly ClientCommand[] = CLIENT_COMMANDS,
+): Promise<MeasureReport> => {
+  if (commands.length === 0) {
+    return {
+      emissions: [],
+      failure:
+        'The client command table is empty, so the corpus was walked and nothing was looked for. Check src/client-commands.ts.',
+    }
+  }
+
+  const files = await listRepositoryFiles(ctx.root)
+  if (files === undefined) {
+    return {
+      emissions: [],
+      unmeasured:
+        'The tracked file list could not be read, so no client command citation was checked.',
+    }
+  }
+
+  const found = files.flatMap((file) => {
+    let text: string
+    try {
+      text = readFileSync(join(ctx.root, file), 'utf8')
+    } catch {
+      return []
+    }
+    return clientCommandCitationsIn(file, text, commands)
+  })
+
+  if (found.length === 0) {
+    return {
+      emissions: [
+        info(
+          `No client command carries a wrong argument across ${files.length} tracked files`,
+        ),
+      ],
+    }
+  }
+
+  return {
+    emissions: found.map((citation) =>
+      warn(
+        `${citation.file}:${citation.line} carries ${citation.text}, which quotes \`${citation.command}\` with the wrong argument`,
+      ),
+    ),
+    failure:
+      found.length === 1
+        ? `One tracked citation quotes a client command with the wrong argument. Match it against the canonical form in src/client-commands.ts, or mark the line ${CLIENT_COMMAND_MARKER}: <reason> where the argument differs on purpose.`
+        : `${found.length} tracked citations quote a client command with the wrong argument. Match each against the canonical form in src/client-commands.ts, or mark the line ${CLIENT_COMMAND_MARKER}: <reason> where the argument differs on purpose.`,
+  }
+}
+
 /**
  * `canon sandbox coverage` moves only when a person runs it, so a scenario added
  * with no expectation ships unnoticed.

package/src/gate/stages.ts

@@ -1,6 +1,7 @@
 import {
   auditSet,
   captureStamps,
+  clientCommandCitations,
   markdownBans,
   type Measure,
   pluginManifests,
@@ -370,6 +371,13 @@ export const STAGES: readonly Stage[] = [
     label: 'Markdown bans',
     checks: [{ kind: 'measure', measure: markdownBans }],
   },
+  {
+    // Unscoped, since a wrong quotation of a client command can land in any
+    // tracked file rather than in one corpus.
+    id: 'client-command-citations',
+    label: 'Client command citations',
+    checks: [{ kind: 'measure', measure: clientCommandCitations }],
+  },
   {
     // Scoped to the corpora it reads rather than run unconditionally, so a
     // branch touching only `src/` or `.claude/` skips it and says so. The

package/src/worktrees/reclaim.ts

@@ -16,6 +16,9 @@ import {
 
 const GH_TIMEOUT_MS = 30_000
 
+/** A local binary read, not a network round trip, so the bound is tighter. */
+const CLAUDE_AGENTS_TIMEOUT_MS = 10_000
+
 /**
  * How many merged pull requests one read covers. A worktree older than this
  * many merges reads as having none and is refused, which is the safe direction:
@@ -47,6 +50,21 @@ export type Route = 'session' | 'worktree'
 /** No removal shape reaches the main worktree, which is what `null` says. */
 export type RemovalRoute = Route | null
 
+/**
+ * One live session holding a worktree, enriched with the id `claude rm` takes.
+ *
+ * `id` is null on two occasions a caller cannot tell apart from the name
+ * alone: an interactive holder, which carries no id at all since nothing but a
+ * person closing its terminal removes it, and a background holder whose id
+ * `claude agents --json` could not resolve, whether the binary is missing,
+ * failing, or simply has not reported that pid.
+ */
+export interface HeldSession {
+  readonly name: string
+  readonly kind: string
+  readonly id: string | null
+}
+
 export interface WorktreeVerdict {
   readonly path: string
   readonly branch: string | null
@@ -55,12 +73,8 @@ export interface WorktreeVerdict {
   readonly refusals: readonly Refusal[]
   /** The pull request that retired the branch, so a report can name what it read. */
   readonly pullRequest: number | null
-  /**
-   * The names of the live sessions holding this worktree. `claude rm` takes an
-   * id rather than a name, so a caller acting on this matches each name to the
-   * id `claude agents --json` carries beside it.
-   */
-  readonly sessions: readonly string[]
+  /** The live sessions holding this worktree. */
+  readonly sessions: readonly HeldSession[]
   readonly route: RemovalRoute
   /**
    * True when the directory is already gone and only the registration remains,
@@ -107,6 +121,9 @@ export interface ReclaimOptions {
   readonly mergedPullRequests?: (cwd: string) => Promise<MergedReport>
   readonly worktreeStatus?: (path: string) => Promise<StatusReport>
   readonly resolve?: () => Promise<SessionReport>
+  readonly claudeAgentIds?: (
+    cwd: string,
+  ) => Promise<ReadonlyMap<number, string>>
 }
 
 /**
@@ -170,6 +187,45 @@ async function mergedPullRequests(cwd: string): Promise<MergedReport> {
   }
 }
 
+/**
+ * Reads every live agent's session id, keyed by its process id, from `claude
+ * agents --json`.
+ *
+ * Guarded like `mergedPullRequests`, reading the same way, but degrading
+ * rather than refusing: the id enriches a caller's report and is never an
+ * input the reclaim logic depends on, where the merge state decides whether a
+ * removal is safe at all. A missing or failing binary leaves every entry
+ * unresolved instead of refusing the whole reading.
+ */
+async function claudeAgentIds(
+  cwd: string,
+): Promise<ReadonlyMap<number, string>> {
+  if (Bun.which('claude') === null) return new Map()
+
+  try {
+    const result = await execa('claude', ['agents', '--json'], {
+      cwd,
+      timeout: CLAUDE_AGENTS_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    const rows = JSON.parse(result.stdout) as readonly {
+      pid?: unknown
+      id?: unknown
+    }[]
+
+    const ids = new Map<number, string>()
+    for (const row of rows) {
+      if (typeof row.pid === 'number' && typeof row.id === 'string') {
+        ids.set(row.pid, row.id)
+      }
+    }
+    return ids
+  } catch {
+    return new Map()
+  }
+}
+
 /**
  * Reports whether a worktree holds work no history is behind.
  *
@@ -214,16 +270,14 @@ function holders(
   entry: WorktreeEntry,
   sessions: readonly ResolvedSession[],
   repository: string | null,
-): readonly string[] {
-  return sessions
-    .filter(
-      (candidate) =>
-        candidate.worktree === entry.path ||
-        (entry.branch !== null &&
-          candidate.branch === entry.branch &&
-          candidate.repository === repository),
-    )
-    .map((candidate) => candidate.name)
+): readonly ResolvedSession[] {
+  return sessions.filter(
+    (candidate) =>
+      candidate.worktree === entry.path ||
+      (entry.branch !== null &&
+        candidate.branch === entry.branch &&
+        candidate.repository === repository),
+  )
 }
 
 function verdict(
@@ -234,8 +288,20 @@ function verdict(
   merged: ReadonlyMap<string, number>,
   sessions: readonly ResolvedSession[],
   repository: string | null,
+  agentIds: ReadonlyMap<number, string>,
 ): WorktreeVerdict {
   const held = holders(entry, sessions, repository)
+  // An interactive holder carries no id to look up at all, so the branch is
+  // explicit rather than relying on `claude agents --json` never reporting one
+  // for a pid this repository's own registry marked interactive.
+  const heldSessions: HeldSession[] = held.map((session) => ({
+    name: session.name,
+    kind: session.kind,
+    id:
+      session.kind === 'interactive'
+        ? null
+        : (agentIds.get(session.pid) ?? null),
+  }))
   const pullRequest =
     entry.branch === null ? null : (merged.get(entry.branch) ?? null)
   const refusals: Refusal[] = []
@@ -262,7 +328,7 @@ function verdict(
     reclaimable: refusals.length === 0,
     refusals,
     pullRequest,
-    sessions: held,
+    sessions: heldSessions,
     // No removal shape reaches the main worktree, and reporting one there
     // offers a command whose only effect is to break the checkout. Deciding it
     // here rather than in the reporter keeps the record and the framed output
@@ -301,14 +367,17 @@ export async function reclaimReport(
   const readMerged = opts.mergedPullRequests ?? mergedPullRequests
   const readStatus = opts.worktreeStatus ?? worktreeStatus
   const resolve = opts.resolve ?? resolveSessions
-
-  const [entries, merged, sessions, repository, current] = await Promise.all([
-    listAll(cwd),
-    readMerged(cwd),
-    resolve(),
-    repositoryOf(cwd),
-    currentWorktreeRoot(cwd),
-  ])
+  const readAgentIds = opts.claudeAgentIds ?? claudeAgentIds
+
+  const [entries, merged, sessions, repository, current, agentIds] =
+    await Promise.all([
+      listAll(cwd),
+      readMerged(cwd),
+      resolve(),
+      repositoryOf(cwd),
+      currentWorktreeRoot(cwd),
+      readAgentIds(cwd),
+    ])
 
   if (merged.kind === 'unreadable') {
     return {
@@ -344,6 +413,7 @@ export async function reclaimReport(
       byBranch,
       sessions.sessions,
       repository,
+      agentIds,
     ),
   )