@erclx/canon 5.45.0 → 5.47.0

package/src/markdown/scope.ts

@@ -36,12 +36,27 @@ const DENSITY_SCOPE = [
   /^(?:README|CONTRIBUTING)\.md$/,
 ]
 
+/**
+ * The roots `canon init` gates in a new project when each passes at init time:
+ * every density surface a target authors itself, leaving out the toolkit's own
+ * `claude/skills/` and `tooling/` trees.
+ */
+export const GATED_SCOPE_ROOTS: readonly string[] = [
+  'canon/context/',
+  'docs/',
+  '.claude/skills/',
+  'wiki/',
+  'README.md',
+  'CONTRIBUTING.md',
+]
+
 /**
  * The path prefixes whose density findings fail a run, each added by the
  * rewrite batch that brought its folders to zero.
  *
  * It describes this repository's rewrite progress and nothing about a target's
- * corpus, which is why the audit reads it only inside a canon checkout.
+ * corpus, which is why the audit reads it only inside a canon checkout. A
+ * target keeps its own list in the file `src/markdown/gated.ts` reads.
  */
 export const GATED_PATHS: readonly string[] = [
   'canon/context/surfaces/',
@@ -50,8 +65,10 @@ export const GATED_PATHS: readonly string[] = [
   'canon/context/features/',
   'canon/context/context-model.md',
   'canon/context/index.md',
+  'claude/skills/api-design/REQUIREMENT.md',
   'claude/skills/api-design/SKILL.md',
   'claude/skills/api-design/references/adopted.md',
+  'claude/skills/auto-ship/REQUIREMENT.md',
   'claude/skills/auto-ship/SKILL.md',
   'claude/skills/auto-ship/references/draft-mark.md',
   'claude/skills/auto-ship/references/failure-recovery.md',
@@ -60,33 +77,45 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/auto-ship/references/ui-checklist.md',
   'claude/skills/auto-ship/references/verb-absent.md',
   'claude/skills/auto-ship/references/worktree-name.md',
+  'claude/skills/backlog-triage/REQUIREMENT.md',
   'claude/skills/backlog-triage/SKILL.md',
   'claude/skills/backlog-triage/references/apply.md',
+  'claude/skills/build-in-slices/REQUIREMENT.md',
   'claude/skills/build-in-slices/SKILL.md',
   'claude/skills/build-in-slices/references/adopted.md',
+  'claude/skills/canon-cli/REQUIREMENT.md',
   'claude/skills/canon-cli/SKILL.md',
+  'claude/skills/canon-feedback-triage/REQUIREMENT.md',
   'claude/skills/canon-feedback-triage/SKILL.md',
+  'claude/skills/canon-feedback/REQUIREMENT.md',
   'claude/skills/canon-feedback/SKILL.md',
   'claude/skills/canon-feedback/references/template.md',
+  'claude/skills/canvas-board/REQUIREMENT.md',
   'claude/skills/canvas-board/SKILL.md',
   'claude/skills/canvas-board/references/canvas.md',
   'claude/skills/canvas-board/references/design.md',
+  'claude/skills/ci-workflow/REQUIREMENT.md',
   'claude/skills/ci-workflow/SKILL.md',
   'claude/skills/ci-workflow/references/workflows.md',
+  'claude/skills/code-craft/REQUIREMENT.md',
   'claude/skills/code-craft/SKILL.md',
   'claude/skills/code-craft/references/adopted.md',
+  'claude/skills/codebase-layout/REQUIREMENT.md',
   'claude/skills/codebase-layout/SKILL.md',
   'claude/skills/codebase-layout/references/adopted.md',
   'claude/skills/codebase-layout/references/frontend.md',
   'claude/skills/codebase-layout/references/tests.md',
+  'claude/skills/context-fold/REQUIREMENT.md',
   'claude/skills/context-fold/SKILL.md',
   'claude/skills/context-fold/references/classify.md',
   'claude/skills/context-fold/references/completion-report.md',
   'claude/skills/context-fold/references/context-refresh.md',
   'claude/skills/context-fold/references/context.md',
   'claude/skills/context-fold/references/unusable-baseline.md',
+  'claude/skills/create-rule/REQUIREMENT.md',
   'claude/skills/create-rule/SKILL.md',
   'claude/skills/create-rule/references/rule.md',
+  'claude/skills/create-skill/REQUIREMENT.md',
   'claude/skills/create-skill/SKILL.md',
   'claude/skills/create-skill/references/skill-disclosure.md',
   'claude/skills/create-skill/references/skill-frontmatter.md',
@@ -95,12 +124,16 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/create-skill/references/skill-reference.md',
   'claude/skills/create-skill/references/skill-requirement.md',
   'claude/skills/create-skill/references/skill.md',
+  'claude/skills/decision-escalate/REQUIREMENT.md',
   'claude/skills/decision-escalate/SKILL.md',
+  'claude/skills/deploy-app/REQUIREMENT.md',
   'claude/skills/deploy-app/SKILL.md',
   'claude/skills/deploy-app/references/cloudflare.md',
   'claude/skills/deploy-app/references/vercel.md',
+  'claude/skills/deprecation-migration/REQUIREMENT.md',
   'claude/skills/deprecation-migration/SKILL.md',
   'claude/skills/deprecation-migration/references/adopted.md',
+  'claude/skills/design-taste/REQUIREMENT.md',
   'claude/skills/design-taste/SKILL.md',
   'claude/skills/design-taste/references/adopted.md',
   'claude/skills/design-taste/references/craft.md',
@@ -109,14 +142,27 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/design-taste/references/systems.md',
   'claude/skills/design-taste/references/tells.md',
   'claude/skills/design-taste/references/vocabulary.md',
+  'claude/skills/docs-sync/REQUIREMENT.md',
   'claude/skills/docs-sync/SKILL.md',
   'claude/skills/docs-sync/references/docs.md',
   'claude/skills/docs-sync/references/readme.md',
+  'claude/skills/document-health/REQUIREMENT.md',
   'claude/skills/document-health/SKILL.md',
   'claude/skills/document-health/references/axes.md',
+  'claude/skills/document-repair/REQUIREMENT.md',
+  'claude/skills/document-repair/SKILL.md',
+  'claude/skills/document-repair/references/batches.md',
+  'claude/skills/draft-and-pick/REQUIREMENT.md',
+  'claude/skills/draft-doc/REQUIREMENT.md',
+  'claude/skills/draft-figure/REQUIREMENT.md',
+  'claude/skills/draft-identity/REQUIREMENT.md',
+  'claude/skills/draft-ready/REQUIREMENT.md',
+  'claude/skills/draft-screencast/REQUIREMENT.md',
+  'claude/skills/draft-slides/REQUIREMENT.md',
   'claude/skills/pick-by-eye/REQUIREMENT.md',
   'claude/skills/pick-by-eye/SKILL.md',
   'claude/skills/pick-by-eye/references/live-arms.md',
+  'claude/skills/write-doc/REQUIREMENT.md',
   'claude/skills/write-doc/SKILL.md',
   'claude/skills/write-doc/references/context.md',
   'claude/skills/write-doc/references/docs.md',
@@ -129,76 +175,102 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/write-doc/references/requirements.md',
   'claude/skills/write-doc/references/wiki-kind.md',
   'claude/skills/write-doc/references/wiki.md',
+  'claude/skills/draw-figure/REQUIREMENT.md',
   'claude/skills/draw-figure/SKILL.md',
   'claude/skills/draw-figure/references/architecture-set.md',
   'claude/skills/draw-figure/references/figures.md',
   'claude/skills/draw-figure/references/hand-drawn.md',
   'claude/skills/draw-figure/references/mermaid-path.md',
   'claude/skills/draw-figure/references/mermaid.md',
+  'claude/skills/design-identity/REQUIREMENT.md',
   'claude/skills/design-identity/SKILL.md',
   'claude/skills/design-identity/references/card-route.md',
+  'claude/skills/plan-ready/REQUIREMENT.md',
   'claude/skills/plan-ready/SKILL.md',
   'claude/skills/plan-ready/references/assembly.md',
   'claude/skills/plan-ready/references/ready.md',
+  'claude/skills/script-screencast/REQUIREMENT.md',
   'claude/skills/script-screencast/SKILL.md',
   'claude/skills/script-screencast/references/beats-template.md',
+  'claude/skills/make-deck/REQUIREMENT.md',
   'claude/skills/make-deck/SKILL.md',
   'claude/skills/make-deck/references/deck.md',
+  'claude/skills/git-branch/REQUIREMENT.md',
   'claude/skills/git-branch/SKILL.md',
   'claude/skills/git-branch/references/branch.md',
   'claude/skills/git-branch/references/slug.md',
+  'claude/skills/git-commit/REQUIREMENT.md',
   'claude/skills/git-commit/SKILL.md',
   'claude/skills/git-commit/references/commit.md',
   'claude/skills/git-commit/references/versioning.md',
+  'claude/skills/git-followup/REQUIREMENT.md',
   'claude/skills/git-followup/SKILL.md',
+  'claude/skills/git-issue/REQUIREMENT.md',
   'claude/skills/git-issue/SKILL.md',
   'claude/skills/git-issue/references/issue.md',
+  'claude/skills/git-pr/REQUIREMENT.md',
   'claude/skills/git-pr/SKILL.md',
   'claude/skills/git-pr/references/final-command.md',
   'claude/skills/git-pr/references/labels.md',
   'claude/skills/git-pr/references/pr.md',
   'claude/skills/git-pr/references/publish.md',
   'claude/skills/git-pr/references/task-number.md',
+  'claude/skills/git-ship/REQUIREMENT.md',
   'claude/skills/git-ship/SKILL.md',
   'claude/skills/git-ship/references/ci-watch.md',
+  'claude/skills/git-split/REQUIREMENT.md',
   'claude/skills/git-split/SKILL.md',
   'claude/skills/git-split/references/independent.md',
   'claude/skills/git-split/references/stacked.md',
+  'claude/skills/git-stage/REQUIREMENT.md',
   'claude/skills/git-stage/SKILL.md',
+  'claude/skills/git-worktree/REQUIREMENT.md',
   'claude/skills/git-worktree/SKILL.md',
   'claude/skills/git-worktree/references/cleanup.md',
+  'claude/skills/markdown-craft/REQUIREMENT.md',
   'claude/skills/markdown-craft/SKILL.md',
   'claude/skills/markdown-craft/references/markdown.md',
+  'claude/skills/plan-feature/REQUIREMENT.md',
   'claude/skills/plan-feature/SKILL.md',
   'claude/skills/plan-feature/references/batches.md',
   'claude/skills/plan-feature/references/plan-lifecycle.md',
   'claude/skills/plan-feature/references/plan.md',
+  'claude/skills/plan-groundwork/REQUIREMENT.md',
   'claude/skills/plan-groundwork/SKILL.md',
   'claude/skills/plan-groundwork/references/groundwork-spikes.md',
   'claude/skills/plan-groundwork/references/groundwork.md',
   'claude/skills/plan-groundwork/references/output.md',
+  'claude/skills/plan-intake-answer/REQUIREMENT.md',
   'claude/skills/plan-intake-answer/SKILL.md',
+  'claude/skills/plan-intake/REQUIREMENT.md',
   'claude/skills/plan-intake/SKILL.md',
   'claude/skills/plan-intake/references/intake.md',
+  'claude/skills/pr-evidence/REQUIREMENT.md',
   'claude/skills/pr-evidence/SKILL.md',
   'claude/skills/pr-evidence/references/evidence.md',
+  'claude/skills/read-frames/REQUIREMENT.md',
   'claude/skills/read-frames/SKILL.md',
+  'claude/skills/record-screencast/REQUIREMENT.md',
   'claude/skills/record-screencast/SKILL.md',
+  'claude/skills/review-address/REQUIREMENT.md',
   'claude/skills/review-address/SKILL.md',
   'claude/skills/review-address/references/post-review-findings.md',
   'claude/skills/review-address/references/rebase-conflicts.md',
   'claude/skills/review-address/references/rebase-only.md',
   'claude/skills/review-address/references/rest-reads.md',
+  'claude/skills/review-craft/REQUIREMENT.md',
   'claude/skills/review-craft/SKILL.md',
   'claude/skills/review-craft/references/adopted.md',
   'claude/skills/review-craft/references/security.md',
   'claude/skills/review-craft/references/ui.md',
+  'claude/skills/review-pr/REQUIREMENT.md',
   'claude/skills/review-pr/SKILL.md',
   'claude/skills/review-pr/references/body-variants.md',
   'claude/skills/review-pr/references/close-out.md',
   'claude/skills/review-pr/references/key-changes.md',
   'claude/skills/review-pr/references/post.md',
   'claude/skills/review-pr/references/scope.md',
+  'claude/skills/review-ui/REQUIREMENT.md',
   'claude/skills/review-ui/SKILL.md',
   'claude/skills/review-ui/references/close-out.md',
   'claude/skills/review-ui/references/driving.md',
@@ -225,38 +297,51 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/role-orchestrator/references/orchestrator-watch.md',
   'claude/skills/role-planner/REQUIREMENT.md',
   'claude/skills/role-planner/SKILL.md',
+  'claude/skills/role-reviewer/REQUIREMENT.md',
   'claude/skills/role-reviewer/SKILL.md',
   'claude/skills/role-worker/REQUIREMENT.md',
   'claude/skills/role-worker/SKILL.md',
+  'claude/skills/search-craft/REQUIREMENT.md',
   'claude/skills/search-craft/SKILL.md',
   'claude/skills/search-craft/references/adopted.md',
+  'claude/skills/session-compact/REQUIREMENT.md',
   'claude/skills/session-compact/SKILL.md',
   'claude/skills/session-compact/references/handoff-note.md',
+  'claude/skills/session-map/REQUIREMENT.md',
   'claude/skills/session-map/SKILL.md',
   'claude/skills/session-map/references/session.md',
+  'claude/skills/session-relay/REQUIREMENT.md',
   'claude/skills/session-relay/SKILL.md',
+  'claude/skills/session-resume/REQUIREMENT.md',
   'claude/skills/session-resume/SKILL.md',
+  'claude/skills/session-worktree/REQUIREMENT.md',
   'claude/skills/session-worktree/SKILL.md',
   'claude/skills/session-worktree/references/install-command.md',
   'claude/skills/session-worktree/references/main-root-writes.md',
+  'claude/skills/systematic-debugging/REQUIREMENT.md',
   'claude/skills/systematic-debugging/SKILL.md',
   'claude/skills/systematic-debugging/references/adopted.md',
+  'claude/skills/target-check/REQUIREMENT.md',
   'claude/skills/target-check/SKILL.md',
   'claude/skills/target-check/references/domains.md',
+  'claude/skills/target-setup/REQUIREMENT.md',
   'claude/skills/target-setup/SKILL.md',
   'claude/skills/target-setup/references/detect.md',
   'claude/skills/target-setup/references/indexes.md',
   'claude/skills/target-setup/references/verify.md',
+  'claude/skills/task-board/REQUIREMENT.md',
   'claude/skills/task-board/SKILL.md',
   'claude/skills/task-board/references/board.md',
   'claude/skills/task-board/references/create-report.md',
   'claude/skills/task-board/references/decline.md',
   'claude/skills/task-board/references/tasks-decline.md',
   'claude/skills/task-board/references/tasks.md',
+  'claude/skills/task-complete/REQUIREMENT.md',
   'claude/skills/task-complete/SKILL.md',
   'claude/skills/task-complete/references/archive.md',
   'claude/skills/task-complete/references/receipt-sweep.md',
   'claude/skills/task-complete/references/unusable-baseline.md',
+  'claude/skills/teach-workspace/REQUIREMENT.md',
   'claude/skills/teach-workspace/SKILL.md',
   'claude/skills/teach-workspace/references/glossary.md',
   'claude/skills/teach-workspace/references/lesson-build.md',
@@ -266,23 +351,43 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/teach-workspace/references/promotion.md',
   'claude/skills/teach-workspace/references/revisit.md',
   'claude/skills/teach-workspace/references/teach.md',
+  'claude/skills/test-craft/REQUIREMENT.md',
   'claude/skills/test-craft/SKILL.md',
   'claude/skills/test-craft/references/adopted.md',
   'claude/skills/test-craft/references/component.md',
   'claude/skills/test-craft/references/e2e.md',
   'claude/skills/test-craft/references/unit.md',
+  'claude/skills/test-first/REQUIREMENT.md',
   'claude/skills/test-first/SKILL.md',
   'claude/skills/test-first/references/adopted.md',
+  'claude/skills/ui-checklist/REQUIREMENT.md',
   'claude/skills/ui-checklist/SKILL.md',
+  'claude/skills/ux-audit/REQUIREMENT.md',
   'claude/skills/ux-audit/SKILL.md',
+  'claude/skills/ux-measure/REQUIREMENT.md',
   'claude/skills/ux-measure/SKILL.md',
+  'claude/skills/video-craft/REQUIREMENT.md',
   'claude/skills/video-craft/SKILL.md',
   'claude/skills/video-craft/references/adopted.md',
+  'claude/skills/write-human/REQUIREMENT.md',
   'claude/skills/write-human/SKILL.md',
   'claude/skills/write-human/references/adopted.md',
   'claude/skills/write-human/references/density.md',
   'claude/skills/write-human/references/machine-tells.md',
+  'claude/skills/youtube-transcripts/REQUIREMENT.md',
   'claude/skills/youtube-transcripts/SKILL.md',
+  '.claude/skills/internal-canvas/REQUIREMENT.md',
+  '.claude/skills/internal-claude/REQUIREMENT.md',
+  '.claude/skills/internal-docs/REQUIREMENT.md',
+  '.claude/skills/internal-governance/REQUIREMENT.md',
+  '.claude/skills/internal-rule-audit/REQUIREMENT.md',
+  '.claude/skills/internal-sandbox-check/REQUIREMENT.md',
+  '.claude/skills/internal-scripts/REQUIREMENT.md',
+  '.claude/skills/internal-shipped-reference/REQUIREMENT.md',
+  '.claude/skills/internal-teach/REQUIREMENT.md',
+  '.claude/skills/internal-tooling/REQUIREMENT.md',
+  '.claude/skills/internal-upstream-digest/REQUIREMENT.md',
+  '.claude/skills/internal-web/REQUIREMENT.md',
   '.claude/skills/internal-',
   'docs/',
   'tooling/',
@@ -307,15 +412,23 @@ export function inDensityScope(rel: string): boolean {
   return DENSITY_SCOPE.some((pattern) => pattern.test(rel))
 }
 
-/** Whether a density finding of this kind on this path fails the run. */
+/**
+ * Whether a density finding of this kind on this path fails the run.
+ *
+ * `alwaysGated` is off for a target's list, since no stage of a target's ever
+ * failed a push on a bullet run, and gating one unlisted would fail an older
+ * project's push on prose it has not touched since the limit landed.
+ */
 export function densityGates(
   rel: string,
   kind: DensityKind,
   gated: readonly string[] = GATED_PATHS,
+  alwaysGated = true,
 ): boolean {
   if (!inDensityScope(rel)) return false
   if (REQUIREMENT_SCOPE.test(rel)) return gated.includes(rel)
   if (
+    alwaysGated &&
     ALWAYS_GATED.includes(kind) &&
     BULLET_RUN_SCOPE.some((pattern) => pattern.test(rel))
   )

package/src/migrate/rename.ts

@@ -12,6 +12,12 @@
  * sweeps sharing a module constant would have to agree on a single map, and
  * the second rename this repository needed shares nothing with the first
  * except the scanning discipline above.
+ *
+ * Two misses survive a clean run. The sweep reads spelled text only, so a path
+ * assembled as `join('.claude', ...)` is never joined back into a token and
+ * keeps its old spelling. And rewriting a test's fixtures can collapse a
+ * fallback test into a copy of its neighbor, which keeps passing while it
+ * covers nothing, so read the rewritten fixtures rather than trusting the run.
  */
 
 /**

package/src/pr/evidence.ts

@@ -5,7 +5,7 @@ const EVIDENCE_SEGMENT = 'evidence'
 const EVIDENCE_OPEN_LIMIT = 6
 
 /** Length of the commit names the visible line shows, the width `git` abbreviates to. */
-const SHORT_SHA_LENGTH = 7
+export const SHORT_SHA_LENGTH = 7
 
 /** Prefix of the trailing marker this module writes and reads back. */
 const MARKER_PREFIX = '<!-- pr-evidence:'

package/src/pr/rest.ts

@@ -42,6 +42,7 @@ export interface PullIdentity {
   readonly head?: string
   readonly base?: string
   readonly mergeState?: string
+  readonly body?: string
 }
 
 export type BranchPull =
@@ -70,6 +71,7 @@ export function identityOf(row: RestPull): PullIdentity {
     ...(row.head?.sha !== undefined && { head: row.head.sha }),
     ...(row.base?.ref !== undefined && { base: row.base.ref }),
     ...(mergeState !== undefined && { mergeState }),
+    ...(typeof row.body === 'string' && { body: row.body }),
   }
 }
 

package/src/pr/tick.ts

@@ -3,9 +3,98 @@ import {
   CHECKLIST_START,
   parseBoxLine,
   readChecklistBoxes,
+  SHORT_SHA_LENGTH,
   writeBoxLine,
 } from '@/pr/evidence'
 
+const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
+const TESTING_HEADING = /^## Testing\s*$/
+const SECTION_HEADING = /^## /
+const REVIEWER_HEADING = /^## For the reviewer\s*$/
+const UI_PASS_HEAD = /at `([0-9a-f]+)`/
+
+/** What the UI pass line reports, either a pass or a reset to a head nobody has driven. */
+export type UiPassSummary =
+  | {
+      readonly kind: 'passed'
+      /** Driven boxes ticked, taste boxes excluded. */
+      readonly passed: number
+      /** Boxes a driver can run, taste boxes excluded. */
+      readonly total: number
+      readonly taste: number
+      readonly head: string
+    }
+  | { readonly kind: 'reset'; readonly head: string }
+
+/**
+ * The one `## Testing` line a UI pass owns. It is ticked only when every box
+ * a driver can run passed, so a failed box never reads as done, and taste
+ * boxes are counted apart so a full pass never reads as one box failed.
+ */
+export function uiPassLine(summary: UiPassSummary): string {
+  const at = `\`${summary.head.slice(0, SHORT_SHA_LENGTH)}\``
+  if (summary.kind === 'reset') {
+    return `- [ ] UI pass, not run at ${at} ${UI_PASS_MARKER}`
+  }
+  const taste =
+    summary.taste === 0
+      ? ''
+      : `${summary.taste} taste ${summary.taste === 1 ? 'box' : 'boxes'} left to the operator`
+  if (summary.total === 0) {
+    return `- [ ] UI pass, no box a driver can run, ${taste} at ${at} ${UI_PASS_MARKER}`
+  }
+  const box = summary.passed === summary.total ? 'x' : ' '
+  const tail = taste === '' ? '' : `, ${taste}`
+  return `- [${box}] UI pass, ${summary.passed} of ${summary.total} boxes passed at ${at}${tail} ${UI_PASS_MARKER}`
+}
+
+/** The short sha the marked line names, absent when the body carries no such line. */
+export function readUiPassHead(body: string): string | undefined {
+  const line = body.split('\n').find((row) => row.includes(UI_PASS_MARKER))
+  return line === undefined ? undefined : UI_PASS_HEAD.exec(line)?.[1]
+}
+
+/**
+ * Puts the UI pass line in a pull request body and touches nothing else.
+ * The marked line is replaced where it stands, else appended to the end of
+ * `## Testing`, which is created ahead of `## For the reviewer` when absent.
+ */
+export function writeUiPassLine(body: string, summary: UiPassSummary): string {
+  const line = uiPassLine(summary)
+  const lines = body.split('\n')
+
+  const marked = lines.findIndex((row) => row.includes(UI_PASS_MARKER))
+  if (marked !== -1) {
+    lines[marked] = line
+    return lines.join('\n')
+  }
+
+  const heading = lines.findIndex((row) => TESTING_HEADING.test(row))
+  if (heading === -1) {
+    const reviewer = lines.findIndex((row) => REVIEWER_HEADING.test(row))
+    if (reviewer === -1) {
+      return `${body.trimEnd()}\n\n## Testing\n\n${line}\n`
+    }
+    lines.splice(reviewer, 0, '## Testing', '', line, '')
+    return lines.join('\n')
+  }
+
+  const next = lines.findIndex(
+    (row, index) => index > heading && SECTION_HEADING.test(row),
+  )
+  let last = next === -1 ? lines.length - 1 : next - 1
+  while (last > heading && lines[last]?.trim() === '') last -= 1
+
+  if (last > heading) {
+    lines.splice(last + 1, 0, line)
+  } else if (lines[heading + 1] === '') {
+    lines.splice(heading + 2, 0, line)
+  } else {
+    lines.splice(heading + 1, 0, '', line)
+  }
+  return lines.join('\n')
+}
+
 export type TickRefusal = 'no-checklist' | 'no-box' | 'taste-box'
 
 export type TickResult =

package/src/sessions/claim.ts

@@ -19,6 +19,12 @@ export interface ClaimReport {
   readonly refs: readonly string[]
   /** False when the session roster could not be read, so `claimed` covers the readings around it alone and cannot be trusted as a clean "unclaimed". */
   readonly sessionsReadable: boolean
+  /**
+   * Foreign-namespace records whose socket is gone. They read dead, so a branch
+   * one of them holds can read unclaimed, which a caller with a count above
+   * zero should treat as unverified.
+   */
+  readonly foreignDead: number
   /** False when the ref read failed, which is the same false clean under a different reading. */
   readonly refsReadable: boolean
 }
@@ -80,6 +86,7 @@ export async function checkClaim(
     sessions,
     refs: refs.refs,
     sessionsReadable: report.kind === 'resolved',
+    foreignDead: report.kind === 'resolved' ? report.foreignDead : 0,
     refsReadable: refs.readable,
   }
 }

package/src/sessions/live.ts

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync, readlinkSync } from 'node:fs'
+import { createConnection } from 'node:net'
 import type { SessionRecord } from '@/sessions/registry'
 
 /**
@@ -7,13 +8,19 @@ import type { SessionRecord } from '@/sessions/registry'
  * `confirmed` means the running process was matched against the start time the
  * record stamped, so the pid belongs to the session that wrote the file.
  * `unverified` means the pid answers a signal probe and nothing more, which
- * cannot separate the original session from whatever inherited its pid.
+ * cannot separate the original session from whatever inherited its pid, or,
+ * for a `foreign` row, that its messaging socket still exists.
  */
 export type Confidence = 'confirmed' | 'unverified'
 
 export interface Liveness {
   readonly alive: boolean
   readonly confidence: Confidence
+  /**
+   * Set only when the record belongs to another pid namespace, so the pid was
+   * never probed. Absent rather than false on every other path.
+   */
+  readonly foreign?: true
 }
 
 export interface LivenessProbes {
@@ -21,6 +28,20 @@ export interface LivenessProbes {
   readonly procStartOf: (pid: number) => string | null
   /** Whether the pid answers at all, ignoring which process holds it. */
   readonly responds: (pid: number) => boolean
+  /**
+   * The reader's own pid namespace in `pid:[inode]` form, or null where it
+   * cannot be read. Optional so a caller with no use for the foreign branch,
+   * such as the gate's lock, states nothing and takes the pid path.
+   */
+  readonly ownDomain?: () => string | null
+  /** Whether the messaging socket a foreign record names still exists. */
+  readonly socketExists?: (path: string) => boolean
+  /**
+   * Whether something accepts a connection on the socket within the timeout.
+   * Async, so `liveness()` never calls it and a caller with no use for it, such
+   * as the gate's lock, states nothing.
+   */
+  readonly listens?: (path: string, timeoutMs: number) => Promise<boolean>
 }
 
 /**
@@ -51,7 +72,40 @@ function responds(pid: number): boolean {
   }
 }
 
-export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
+/** The link target reads `pid:[inode]`, which a record's `pidDomain` ends with. */
+function ownDomain(): string | null {
+  try {
+    return readlinkSync('/proc/self/ns/pid')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Connects and closes without writing, so the peer sees no bytes. The socket is
+ * destroyed on connect rather than waited on, since a listener that accepts and
+ * never closes would otherwise hold the probe open past its timeout.
+ */
+function listens(path: string, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(path)
+    const settle = (accepted: boolean): void => {
+      socket.destroy()
+      resolve(accepted)
+    }
+    socket.setTimeout(timeoutMs, () => settle(false))
+    socket.once('connect', () => settle(true))
+    socket.once('error', () => settle(false))
+  })
+}
+
+export const SYSTEM_PROBES: LivenessProbes = {
+  procStartOf,
+  responds,
+  ownDomain,
+  socketExists: existsSync,
+  listens,
+}
 
 /**
  * Decides whether a record describes a session that is still running.
@@ -62,13 +116,32 @@ export const SYSTEM_PROBES: LivenessProbes = { procStartOf, responds }
  * probe alone stands, and every surviving row is marked so a caller never reads
  * a recycled pid as a confirmed identity.
  *
- * It reads two fields and asks for no more, so a record that is not a session,
- * such as the gate's machine lock, carries the same proof.
+ * A record from another pid namespace is judged first, on its messaging
+ * socket, because its pid names nothing in this namespace and either probe
+ * would read an unrelated process or none. That answer is always `unverified`,
+ * since a crashed session leaves its socket behind.
+ *
+ * The pid and start time are the only fields the rest needs, so a record that
+ * is not a session, such as the gate's machine lock, carries the same proof and
+ * takes the pid path for want of a `pidDomain`.
  */
 export function liveness(
-  record: Pick<SessionRecord, 'pid' | 'procStart'>,
+  record: Pick<SessionRecord, 'pid' | 'procStart'> &
+    Partial<Pick<SessionRecord, 'pidDomain' | 'messagingSocketPath'>>,
   probes: LivenessProbes = SYSTEM_PROBES,
 ): Liveness {
+  const own = probes.ownDomain?.() ?? null
+  if (
+    own !== null &&
+    record.pidDomain !== undefined &&
+    !record.pidDomain.endsWith(own)
+  ) {
+    const socket = record.messagingSocketPath
+    const alive =
+      socket !== undefined && (probes.socketExists?.(socket) ?? false)
+    return { alive, confidence: 'unverified', foreign: true }
+  }
+
   const started = record.procStart
 
   if (started !== undefined && started.length > 0) {

package/src/sessions/registry.ts

@@ -45,6 +45,17 @@ export interface SessionRecord {
    * been handed to something else.
    */
   readonly procStart: string | undefined
+  /**
+   * The pid namespace the client stamped, ending in the `pid:[inode]` form that
+   * `/proc/self/ns/pid` reads as. A reader in another namespace cannot see the
+   * record's pid, so this is what tells a foreign row from a dead one.
+   */
+  readonly pidDomain: string | undefined
+  /**
+   * The socket the session listens on for messages. It is the only evidence of
+   * life a foreign-namespace reader can reach, since the pid is out of sight.
+   */
+  readonly messagingSocketPath: string | undefined
 }
 
 /**