@erclx/canon 5.41.0 → 5.43.0

package/src/commands/pr.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { readdir, readFile, readlink, realpath } from 'node:fs/promises'
+import { readFile, realpath } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
@@ -72,15 +72,13 @@ import {
   readBaseStanding,
   readChangedPaths,
 } from '@/pr/lift'
+import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import {
   dropAddressLine,
   findLocalServer,
-  type Listener,
   type LocalRefusal,
   type LocalRunner,
-  parseLsofListeners,
-  parseProcNetTcp,
 } from '@/pr/local'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
@@ -107,7 +105,12 @@ import {
   reviewRowOf,
   selectBranchPull,
 } from '@/pr/rest'
-import { resolveReviewScope } from '@/pr/review-scope'
+import {
+  readReviewState,
+  type ReviewStateApi,
+  type ReviewStateRecord,
+  waitForReviews,
+} from '@/pr/review-state'
 import { PROJECT_ROOT } from '@/roots/project'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/cli/ui'
 
@@ -140,6 +143,10 @@ interface LiftCommandOptions extends ReadOptions {
   readonly wait?: string
 }
 
+interface ReviewStateOptions extends ReadOptions {
+  readonly wait?: string
+}
+
 interface LocalOptions extends ReadOptions {
   readonly remove?: boolean
 }
@@ -561,11 +568,17 @@ export function register(program: Command): void {
     })
 
   pr.command('review-state')
-    .description('Report the commit and instant the last review pass covered')
+    .description(
+      'Report what the last code review and UI review passes covered at the tip',
+    )
     .argument('[number]', 'Pull request to read, defaulting to this branch')
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
     .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--wait <seconds>',
+      `Hold until a pass covers the tip in every bound family, default ${DEFAULT_WAIT_SECONDS}`,
+    )
     .addHelpText(
       'after',
       [
@@ -587,6 +600,31 @@ export function register(program: Command): void {
         '  fallback  a pass posted before the marker shipped, off GitHub stamps',
         '  none      the thread carries no pass, so the next one is a first pass',
         '',
+        'Those code review fields stay at the top level of the record. Beside',
+        'them, `head` is the branch tip read from the remote, and `review` and',
+        '`ui` carry each family at that tip:',
+        '  reason     the refusal `canon pr lift` gives the family, absent when',
+        '             its gate passes, read through the same gate function',
+        '  isCovered  a pass covers the tip: the gate passes, or the newest pass,',
+        '             open or unmarked, names the tip',
+        '',
+        '`ui` also carries the newest `## UI review` pass (`heading`, `state`,',
+        '`commit`, `source`), `isBound`, which is whether the evidence comment',
+        'carries a checklist, and `carriedFrom` or `paintedPaths` when the lift',
+        'carried a close forward or refused to. An unbound family reads covered.',
+        '',
+        'Both families post as pull request reviews, so this reads',
+        '`pulls/<n>/reviews` alone, as the lift does. Issue comments are not',
+        'read: neither review skill posts there, and a heading found only in a',
+        'comment would let a worker move on a pass the lift then refuses.',
+        '',
+        '`--wait <seconds>` holds until `isCovered` reads true in both families',
+        'or the deadline passes, re-reading the tip every 30 seconds so a push',
+        'moves what a pass must cover. The evidence is read once at the start.',
+        'The record then adds `reason`, `covered` or `timeout`, and',
+        '`waitedSeconds`. A wait past 600 seconds outlasts a foreground shell',
+        'call, so run it in the background.',
+        '',
         'Refusals, read off `reason`:',
         '  ambiguous-pull    two open pull requests share the branch against',
         '                    different bases, so name a number',
@@ -599,18 +637,22 @@ export function register(program: Command): void {
         '  gh-missing        `gh` is not on the path, so no pull request resolved',
         '  gh-failed         `gh` could not answer for this branch, so name a number',
         '  no-object-head    the pull request object reported no head commit',
+        '  bad-wait          --wait takes a whole number of seconds',
         '',
         'Exit codes:',
-        '  0  the thread was read, whether it carries a pass or not',
-        '  1  refused, with the reason on stderr or in the JSON record',
+        '  0  the thread was read, whether it carries a pass or not, or the',
+        '     wait ended covered',
+        '  1  refused, with the reason on stderr or in the JSON record, or the',
+        '     wait reached its deadline as `timeout`',
         '',
         'Examples:',
         '  canon pr review-state',
         '  canon pr review-state 1341 --json',
+        '  canon pr review-state 1341 --wait 1200 --json',
         '',
       ].join('\n'),
     )
-    .action(async (number: string | undefined, opts: ReadOptions) => {
+    .action(async (number: string | undefined, opts: ReviewStateOptions) => {
       process.exitCode = await runReviewState(number, opts)
     })
 
@@ -1818,13 +1860,21 @@ async function runChecks(
 
 async function runReviewState(
   number: string | undefined,
-  opts: ReadOptions,
+  opts: ReviewStateOptions,
 ): Promise<number> {
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
 
   intro('canon pr review-state')
 
+  let waitSeconds: number | undefined
+  if (opts.wait !== undefined) {
+    if (!/^\d+$/.test(opts.wait)) {
+      return refuseWith('bad-wait', LIFT_REFUSALS['bad-wait'], emitJson, root)
+    }
+    waitSeconds = Number(opts.wait)
+  }
+
   if (Bun.which('gh') === null) {
     return refuseWith('gh-missing', PULL_REFUSALS['gh-missing'], emitJson, root)
   }
@@ -1841,20 +1891,84 @@ async function runReviewState(
     )
   }
 
-  const reviews = await listReviews(root, resolved.number)
-  if (reviews.kind === 'refused') {
-    const reason =
-      reviews.reason === 'gh-failed' ? 'gh-failed' : 'reviews-unreadable'
-    return refuseWith(reason, PULL_REFUSALS[reason], emitJson, root)
+  const read = await readIdentity(root, resolved.number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
+  }
+
+  // The module refuses every failed read as `gh-failed`. The api keeps each
+  // read's own reason, so a caller still tells an unreadable thread from an
+  // unreadable remote.
+  let failure: PullRefusal | HeadRefusal = 'gh-failed'
+  const git = gitRunner(root)
+  const api: ReviewStateApi = {
+    readTip: async () => {
+      const tip = await resolveTip(read.identity.branch, refReader(root))
+      if (tip.kind === 'read') return tip.tip
+      failure = tip.reason
+      return undefined
+    },
+    readReviews: async () => {
+      const reviews = await listReviews(root, resolved.number)
+      if (reviews.kind === 'read') return reviews.rows.map(reviewRowOf)
+      failure =
+        reviews.reason === 'gh-failed' ? 'gh-failed' : 'reviews-unreadable'
+      return undefined
+    },
+    readEvidence: () => readEvidenceGate(root, resolved.number),
+    readChanged: (from, to) => readChangedPaths(git, from, to),
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: () => Date.now(),
   }
 
-  const listing = { number: Number(resolved.number) }
-  const scope = resolveReviewScope({
-    reviews: reviews.rows.map(reviewRowOf),
-  })
+  const painted = loadPaintedPatterns(root)
+  const wait =
+    waitSeconds === undefined
+      ? undefined
+      : await waitForReviews(api, { waitSeconds, painted })
+  const state = wait ?? (await readReviewState(api, painted))
+  if (state.kind === 'refused') {
+    return refuseWith(failure, PULL_REFUSALS[failure], emitJson, root)
+  }
+
+  const { record } = state
+  const pull = Number(resolved.number)
+  logReviewState(pull, record)
+  const waited =
+    wait?.kind === 'read'
+      ? { reason: wait.reason, waitedSeconds: wait.waitedSeconds }
+      : undefined
+  if (waited !== undefined) {
+    logStep(waited.reason === 'covered' ? 'Covered' : 'Timeout')
+    logInfo(
+      waited.reason === 'covered'
+        ? `a pass covers ${record.head.slice(0, 8)} in every bound family after ${waited.waitedSeconds}s`
+        : `no pass covered ${record.head.slice(0, 8)} in every bound family within ${waited.waitedSeconds}s`,
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    const { scope, ...families } = record
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        number: pull,
+        ...scope,
+        ...families,
+        ...waited,
+      })}\n`,
+    )
+  }
+
+  return waited?.reason === 'timeout' ? 1 : 0
+}
 
+function logReviewState(number: number, record: ReviewStateRecord): void {
+  const { scope } = record
   logStep('Scope')
-  logInfo(`#${listing.number}`)
+  logInfo(`#${number} at ${record.head.slice(0, 8)}`)
 
   if (scope.source === 'none') {
     logStep('First pass')
@@ -1874,19 +1988,17 @@ async function runReviewState(
     )
   }
 
-  outro()
-
-  if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({
-        root,
-        number: listing.number,
-        ...scope,
-      })}\n`,
-    )
+  for (const [name, family] of [
+    ['review', record.review],
+    ['ui', record.ui],
+  ] as const) {
+    const line = `${name}: ${family.reason ?? 'clear'}, ${family.isCovered ? 'a pass covers the tip' : 'no pass covers the tip'}`
+    if (family.isCovered) logInfo(line)
+    else logWarn(line)
+  }
+  if (!record.ui.isBound) {
+    logInfo('ui: the evidence carries no checklist, so the family is unbound')
   }
-
-  return 0
 }
 
 interface PullFiles {
@@ -2616,81 +2728,10 @@ async function runPreviewCheck(
   return reading.reason === 'fresh' ? 0 : 1
 }
 
-async function readText(path: string): Promise<string | undefined> {
-  return readFile(path, 'utf8').catch(() => undefined)
-}
-
-/**
- * Every listening socket's owning pid, read from `/proc`. Only a process this
- * user owns exposes its `fd` table, which is also the only process whose
- * server this user's worktree could have started.
- */
-async function readProcListeners(): Promise<Listener[] | undefined> {
-  const tables = await Promise.all(
-    ['/proc/net/tcp', '/proc/net/tcp6'].map(readText),
-  )
-  if (tables.every((text) => text === undefined)) return undefined
-  const byInode = new Map(
-    tables.flatMap((text) =>
-      text === undefined
-        ? []
-        : parseProcNetTcp(text).map((s) => [s.inode, s.port] as const),
-    ),
-  )
-
-  const processIds = (await readdir('/proc').catch(() => [])).filter((name) =>
-    /^\d+$/.test(name),
-  )
-  const listeners: Listener[] = []
-  for (const pid of processIds) {
-    const fds = await readdir(`/proc/${pid}/fd`).catch(() => [])
-    for (const fd of fds) {
-      const target = await readlink(`/proc/${pid}/fd/${fd}`).catch(() => '')
-      const inode = /^socket:\[(\d+)\]$/.exec(target)?.[1]
-      const port = inode === undefined ? undefined : byInode.get(inode)
-      if (port !== undefined) listeners.push({ pid: Number(pid), port })
-    }
-  }
-  return listeners
-}
-
-/**
- * The machine half of a detection: `/proc` wherever it exists, lsof on a
- * machine without it, and no reader anywhere else.
- */
+/** The listener reads come from the machine, and the HTML probe from here. */
 function machineLocalRunner(): LocalRunner {
-  const hasLsof = Bun.which('lsof') !== null
   return {
-    async listListeners() {
-      // lsof 4.95 drops every process whose kernel-truncated name holds an
-      // unmatched `(`, which Next's `next-server (vX.Y.Z)` title cuts down to,
-      // so `/proc` goes first despite costing several times what lsof does.
-      if (existsSync('/proc/net/tcp')) {
-        const listeners = await readProcListeners()
-        if (listeners !== undefined) return listeners
-      }
-      if (hasLsof) {
-        const result = await $`lsof -nP -iTCP -sTCP:LISTEN -Fpn`
-          .quiet()
-          .nothrow()
-        // lsof exits 1 both when it matched nothing and when it could not
-        // read some process, and the rows it did print are real either way.
-        if (result.exitCode <= 1) return parseLsofListeners(result.text())
-      }
-      return undefined
-    },
-    async cwdOf(pid) {
-      if (existsSync(`/proc/${pid}/cwd`)) {
-        return readlink(`/proc/${pid}/cwd`).catch(() => undefined)
-      }
-      if (!hasLsof) return undefined
-      const result = await $`lsof -a -p ${pid} -d cwd -Fn`.quiet().nothrow()
-      const line = result
-        .text()
-        .split('\n')
-        .find((row) => row.startsWith('n'))
-      return line?.slice(1)
-    },
+    ...machineListenerReader(),
     // An HTML page rather than any answer, since a test runner's server or a
     // reload socket in the same tree answers too, and a reviewer opening one
     // gets a bare 404 instead of the branch.

package/src/commands/tooling.ts

@@ -18,7 +18,7 @@ import {
 } from '@/tooling/manifest'
 import { readReference, resolveReference } from '@/tooling/read'
 import { scan, type ScanResult } from '@/tooling/scan'
-import { recordedStacks, recordToolingChain } from '@/tooling/stamp'
+import { recordToolingChain } from '@/tooling/stamp'
 import { subfolderPath } from '@/tooling/subfolder'
 import { verifyStack } from '@/tooling/verify-stack'
 import {
@@ -513,8 +513,8 @@ async function stampChain(chain: Manifest[], target: string): Promise<void> {
     new Date(),
   )
 
-  if (recorded) {
-    logInfo(`Recorded chain: ${recordedStacks(chain).join(' < ')}`)
+  if (recorded !== undefined) {
+    logInfo(`Recorded chain: ${recorded.join(' < ')}`)
     return
   }
 

package/src/commands/worktrees.ts

@@ -17,7 +17,9 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/git/worktree'
+import { machineListenerReader } from '@/listeners/machine'
 import { repairBareFlag } from '@/worktrees/bare-flag'
+import { type StopReport, stopListeners } from '@/worktrees/stop'
 import {
   removeReclaimable,
   type RemovalOutcome,
@@ -57,6 +59,12 @@ export interface ReclaimRecord {
   readonly removed: number
   readonly failed: number
   readonly pruned: boolean
+  /**
+   * Processes signaled, or that a dry run would signal, for listening inside a
+   * reclaimed worktree. Null when the machine offered no way to read
+   * listeners, which says nothing about what is still running.
+   */
+  readonly stopped: number | null
   readonly outcomes: readonly RemovalOutcome[]
 }
 
@@ -79,6 +87,8 @@ export type ReclaimSource =
        * from a run that was asked not to act.
        */
       readonly removal: RemovalReport | null
+      /** Null when no stop ran, which is a reading with nothing reclaimable. */
+      readonly stop?: StopReport | null
     }
 
 const REFUSALS: Record<Refusal, string> = {
@@ -198,6 +208,14 @@ export function register(program: Command): void {
         'deletes its branch, and a run carrying a directory that is already',
         'gone sweeps stale registrations once before the branch deletes.',
         '',
+        'Ahead of each removal it sends SIGTERM to every process listening from',
+        'inside a reclaimable worktree, so no dev server outlives the tree it',
+        'serves. A listener in the main checkout, in a refused worktree, or in',
+        'a worktree nested under another is left alone. A dry run signals',
+        'nothing and still reports what it would stop. "stopped" in the record',
+        'counts those processes, and reads null on a machine with neither lsof',
+        'nor /proc, where no listener could be read.',
+        '',
         'It deletes only what a reading called reclaimable. A worktree a live',
         'session holds is refused rather than removed here. `claude rm <id>`',
         'is meant to remove the session and its worktree together, but its',
@@ -324,11 +342,13 @@ export function reclaimRecord(source: ReclaimSource): ReclaimRecord {
       removed: 0,
       failed: 0,
       pruned: false,
+      stopped: 0,
       outcomes: [],
     }
   }
 
   const outcomes = source.removal?.outcomes ?? []
+  const stop = source.stop ?? null
 
   return {
     reason: null,
@@ -338,10 +358,30 @@ export function reclaimRecord(source: ReclaimSource): ReclaimRecord {
     removed: outcomes.filter((outcome) => outcome.removed).length,
     failed: outcomes.filter((outcome) => !outcome.removed).length,
     pruned: source.removal?.pruned ?? false,
+    stopped: stop === null ? 0 : countStopped(stop),
     outcomes,
   }
 }
 
+function countStopped(stop: StopReport): number | null {
+  if (stop.kind === 'unread') return null
+  return stop.stopped.reduce((sum, server) => sum + server.pids.length, 0)
+}
+
+/** Names each server a stop took, or would take on a dry run, and says when none could be read. */
+function reportStop(stop: StopReport, dryRun: boolean): void {
+  if (stop.kind === 'unread') {
+    logWarn(
+      'This machine offers neither lsof nor /proc, so listening servers were not read and none was stopped.',
+    )
+    return
+  }
+  const verb = dryRun ? 'Would stop' : 'Stopped'
+  for (const { path, ports } of stop.stopped) {
+    logInfo(`${verb} the server on ${ports.join(', ')} in ${path}`)
+  }
+}
+
 function emitReclaim(opts: ReclaimCommandOptions, source: ReclaimSource): void {
   if (opts.json !== true) return
   process.stdout.write(`${JSON.stringify(reclaimRecord(source))}\n`)
@@ -381,8 +421,14 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   logInfo(plural(reclaimable.length, 'worktree'))
   pipeOutput(reclaimable.map(describe).join('\n'))
 
+  const stop = await stopListeners(
+    reclaimable.map((entry) => entry.path),
+    { reader: machineListenerReader(), dryRun },
+  )
+
   if (dryRun) {
     logStep('Dry run')
+    reportStop(stop, dryRun)
     logWarn('Nothing was removed. Run this again without --dry-run to remove.')
     outro()
     emitReclaim(opts, {
@@ -390,6 +436,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
       dryRun,
       reclaimable: reclaimable.length,
       removal: null,
+      stop,
     })
     return 0
   }
@@ -403,6 +450,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
   })
 
   logStep('Removed')
+  reportStop(stop, dryRun)
   for (const outcome of removal.outcomes) reportOutcome(outcome)
   if (removal.pruned) {
     logInfo(
@@ -423,6 +471,7 @@ async function runReclaim(opts: ReclaimCommandOptions): Promise<number> {
     dryRun,
     reclaimable: reclaimable.length,
     removal,
+    stop,
   })
   return failed.length > 0 ? 1 : 0
 }

package/src/gate/stages.ts

@@ -380,6 +380,21 @@ export const STAGES: readonly Stage[] = [
     ],
     success: 'Rule citations resolve',
   },
+  {
+    // Reads the whole rule corpus and fails only on a folder the verb lists as
+    // gated, so the finding count prints on every push while the rewrite moves
+    // folder by folder toward zero.
+    id: 'rule-shape',
+    label: 'Rule shape',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['gov', 'audit', '--gate'],
+        failure:
+          'A rule in a gated folder is past a shape limit or short of its ledger. Run bun src/cli.ts gov audit.',
+      },
+    ],
+  },
   {
     // A citation naming the old record root resolves to nothing once the
     // folders have moved, and the sweep that would repoint it only runs when a