@erclx/canon 4.31.0 → 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.0",
+  "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.0",
+  "version": "4.32.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/check-capability-seeding.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+shopt -s nullglob
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+TOOLING_ROOT="$PROJECT_ROOT/tooling"
+MARKER="canon-no-seed:"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports every capability seeded having never read one.
+if [ ! -d "$TOOLING_ROOT" ]; then
+  echo "No tooling root at ${TOOLING_ROOT#"$PROJECT_ROOT/"}, capability seeding unverifiable." >&2
+  exit 1
+fi
+
+failures=""
+
+# A comment naming the marker anywhere in the source file is the recorded
+# reason a capability withholds itself from every destination it was compared
+# against. The reason's own prose is free-form, so only the marker is tested.
+has_reason() {
+  grep -q "$MARKER" "$1"
+}
+
+# Compares one source directory's files against the basenames already
+# expanded from a set of destination paths. Presence on either side clears a
+# name; a source file reaching neither the destination nor a marked reason is
+# a capability answered on one side of the seed or config boundary and not
+# the other.
+check_capability() {
+  local label="$1" src_dir="$2"
+  shift 2
+
+  [ -d "$src_dir" ] || return 0
+
+  local dest_names=" "
+  local dest
+  for dest in "$@"; do
+    [ -f "$dest" ] || continue
+    dest_names="$dest_names$(basename "$dest") "
+  done
+
+  local src_file name
+  for src_file in "$src_dir"/*; do
+    [ -f "$src_file" ] || continue
+    name=$(basename "$src_file")
+    case "$dest_names" in
+    *" $name "*) continue ;;
+    esac
+    has_reason "$src_file" && continue
+    failures="$failures  $label: ${src_file#"$PROJECT_ROOT/"} reaches no seed or config and carries no $MARKER reason"$'\n'
+  done
+}
+
+check_capability "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT"/tooling/claude/seeds/.claude/hooks/*
+
+check_capability "Workflows" "$PROJECT_ROOT/.github/workflows" \
+  "$PROJECT_ROOT"/tooling/*/configs/.github/workflows/*
+
+check_capability "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT"/tooling/base/configs/.husky/*
+
+# The reverse direction: a destination file whose source here is gone reaches
+# neither check_capability above nor the wiring pass below, both of which read
+# forward from the source, and it ships a target a hook, workflow, or husky
+# script this repository has already deleted. A destination carrying the same
+# marker clears just as a source does, which is the escape hatch a target-only
+# capability needs, such as a stack-specific workflow with no root counterpart
+# by design.
+check_orphans() {
+  local label="$1" src_dir="$2" dest_dir="$3"
+
+  [ -d "$dest_dir" ] || return 0
+
+  local dest_file name
+  for dest_file in "$dest_dir"/*; do
+    [ -f "$dest_file" ] || continue
+    name=$(basename "$dest_file")
+    [ -f "$src_dir/$name" ] && continue
+    has_reason "$dest_file" && continue
+    failures="$failures  $label: ${dest_file#"$PROJECT_ROOT/"} is seeded or configured with no source at ${src_dir#"$PROJECT_ROOT/"}/$name"$'\n'
+  done
+}
+
+check_orphans "Hooks" "$PROJECT_ROOT/.claude/hooks" \
+  "$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+
+for dir in "$PROJECT_ROOT"/tooling/*/configs/.github/workflows; do
+  check_orphans "Workflows" "$PROJECT_ROOT/.github/workflows" "$dir"
+done
+
+check_orphans "Husky" "$PROJECT_ROOT/.husky" \
+  "$PROJECT_ROOT/tooling/base/configs/.husky"
+
+# A hook that reached the seed tree with no wiring in the seeded settings.json
+# is installed dead, which fails the same way an unseeded hook does.
+SEED_HOOKS_DIR="$PROJECT_ROOT/tooling/claude/seeds/.claude/hooks"
+SEED_SETTINGS="$PROJECT_ROOT/tooling/claude/seeds/.claude/settings.json"
+
+if [ -d "$SEED_HOOKS_DIR" ]; then
+  if [ ! -f "$SEED_SETTINGS" ]; then
+    failures="$failures  Seed settings: no settings.json at ${SEED_SETTINGS#"$PROJECT_ROOT/"} to confirm a seeded hook is wired"$'\n'
+  elif ! command -v jq >/dev/null 2>&1; then
+    failures="$failures  Seed settings: jq is not installed, seeded-hook wiring unverifiable"$'\n'
+  else
+    # Every wired command as its own path segment set, rather than a substring
+    # search over the raw file, so a hook name that is a substring of another
+    # hook's filename (`log.sh` inside `pr-create-log.sh`) cannot pass on a
+    # neighbor's wiring.
+    wired=" $(jq -r '.. | .command? // empty' "$SEED_SETTINGS" | tr '/\n' '  ') "
+    for hook_file in "$SEED_HOOKS_DIR"/*.sh; do
+      [ -f "$hook_file" ] || continue
+      name=$(basename "$hook_file")
+      case "$wired" in
+      *" $name "*) continue ;;
+      esac
+      failures="$failures  Seed settings: $name is seeded and wired into no command in ${SEED_SETTINGS#"$PROJECT_ROOT/"}"$'\n'
+    done
+  fi
+fi
+
+if [ -n "$failures" ]; then
+  echo "A capability reaches one side of the seed or config boundary and not the other:" >&2
+  printf '%s' "$failures" >&2
+  echo "Seed or configure the capability, or mark the source line with # $MARKER <reason>." >&2
+  exit 1
+fi

package/scripts/lib/sandbox-git.sh

@@ -112,6 +112,14 @@ ensure_sandbox_anchor_repo() {
   log_info "Created ${GITHUB_ORG}/${repo_name} as a private repository."
 }
 
+# Mirrors the merge-base resolution the diff-baseline port already carries
+# across five skill bodies, so a checkout whose local main trails origin/main
+# does not pull in skill bodies other merged branches changed.
+resolve_sandbox_skill_diff_base() {
+  git -C "$PROJECT_ROOT" merge-base HEAD origin/main 2>/dev/null ||
+    git -C "$PROJECT_ROOT" merge-base HEAD main 2>/dev/null
+}
+
 # A remote is useless without an author, so the scenarios that reach one always
 # configure both. configure_sandbox_git_identity stays callable on its own for
 # the scenarios that never push. The probe runs first so an absent remote is

package/scripts/manage-sandbox.sh

@@ -283,8 +283,12 @@ tag_sandbox_baseline() {
 }
 
 inject_changed_skills() {
+  local base
+  base=$(resolve_sandbox_skill_diff_base)
+  base="${base:-main}"
+
   local changed untracked
-  changed=$(git -C "$PROJECT_ROOT" diff main --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
+  changed=$(git -C "$PROJECT_ROOT" diff "$base" --name-only -- 'claude/skills/**/SKILL.md' 2>/dev/null)
   untracked=$(git -C "$PROJECT_ROOT" ls-files --others --exclude-standard -- 'claude/skills/**/SKILL.md' 2>/dev/null)
 
   local combined
@@ -293,8 +297,8 @@ inject_changed_skills() {
   [ -z "$combined" ] && return
 
   while IFS= read -r skill_path; do
-    # The diff against main lists a deleted skill alongside a changed one, and
-    # there is nothing left to inject for a name this branch removed.
+    # The diff against the base lists a deleted skill alongside a changed one,
+    # and there is nothing left to inject for a name this branch removed.
     [ -f "$PROJECT_ROOT/$skill_path" ] || continue
 
     local skill_name
@@ -302,6 +306,9 @@ inject_changed_skills() {
     local target_dir="$SANDBOX/.claude/skills/$skill_name"
     mkdir -p "$target_dir"
     cp "$PROJECT_ROOT/$skill_path" "$target_dir/SKILL.md"
+    if [ -n "$SANDBOX_SKIP_AUTO_COMMIT" ]; then
+      echo ".claude/skills/$skill_name/SKILL.md" >>"$SANDBOX/.git/info/exclude"
+    fi
     log_info "Injected dev skill: $skill_name"
   done <<<"$combined"
 }

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,
@@ -296,6 +297,20 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Seed prose cites no toolkit CLI',
   },
+  {
+    // A hook, a workflow, or a husky script reaching one side of the seed or
+    // config boundary and not the other is a capability withheld with no
+    // recorded reason, per the criterion in .claude/ARCHITECTURE.md.
+    id: 'capability-seeding',
+    label: 'Capability seeding',
+    checks: [
+      script(
+        'check-capability-seeding.sh',
+        'A capability reaches one side of the seed or config boundary and not the other.',
+      ),
+    ],
+    success: 'Capability seeding clean',
+  },
   {
     // A stack entry naming a rule folder takes every rule in it, which is what
     // stops a new rule from needing a second edit to reach a target. The
@@ -356,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,
     ),
   )
 

package/tooling/claude/seeds/.claude/hooks/pr-create-log.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# Reminds a worker session of the pull-request announcement it owes and logs
+# the creation as a denominator for the miss rate `claude-worker` cannot
+# measure on its own. Follows path-form.sh's precedent: a PostToolUse hook
+# returning hookSpecificOutput.additionalContext is the shipped route back
+# into a session's own turn.
+#
+# The hook cannot know whether the announcement went out, only that a pull
+# request now exists to announce. It states the obligation and counts the
+# creation, and claims nothing about the send.
+
+# Claude Code sends a payload and closes stdin. A bare read with nothing
+# feeding it blocks forever and holds the session open, so the read is
+# bounded. `read` rather than `timeout cat`, which macOS does not ship.
+IFS= read -r -d '' -t 2 input
+[ -n "$input" ] || {
+  printf '%s reads a Claude Code hook payload on stdin and cannot be run by hand.\n' "${0##*/}" >&2
+  exit 1
+}
+
+command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
+case "$command" in
+*"gh pr create"*) ;;
+*) exit 0 ;;
+esac
+
+# gh pr create prints the new pull request's URL to stdout on success, so
+# matching it is what tells a creation apart from a failed or refused call.
+stdout=$(printf '%s' "$input" | jq -r '.tool_response.stdout // empty')
+url=$(printf '%s' "$stdout" | grep -Eo 'https://github\.com/[^[:space:]]+/pull/[0-9]+' | tail -1)
+[ -n "$url" ] || exit 0
+
+# CLAUDE_PROJECT_DIR is the session's own worktree rather than the main root,
+# so a worker building in a linked worktree would log into a folder that dies
+# with the worktree. The log is a denominator across a wave rather than a
+# per-session record, so strip back to the main root the way tasks-index.sh
+# and memory-index.sh already derive theirs, off a path suffix.
+root="${CLAUDE_PROJECT_DIR:-.}"
+case "$root" in
+*/.claude/worktrees/*) root="${root%/.claude/worktrees/*}" ;;
+esac
+# The log is scratch, so it follows the scratch folder to whichever record root
+# the project carries rather than creating a second one beside it.
+if [ -d "$root/.canon" ]; then
+  log_dir="$root/.canon/tmp/pr-create-log"
+else
+  log_dir="$root/.claude/.tmp/pr-create-log"
+fi
+mkdir -p "$log_dir"
+session=$(printf '%s' "$input" | jq -r '.session_id // "unknown"')
+printf -- '- %s session=%s pr=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session" "$url" >>"$log_dir/log.md"
+
+msg="Pull request $url just opened. If this session holds a worker's channel obligation, announce it to the controller now, per claude-worker."
+jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'

package/tooling/claude/seeds/.claude/settings.json

@@ -41,6 +41,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-form.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pr-create-log.sh"
+          }
+        ]
       }
     ]
   }