@erclx/canon 5.45.0 → 5.47.0

package/src/commands/pr.ts

@@ -93,7 +93,13 @@ import {
   servesChange,
   type WorkflowFile,
 } from '@/pr/preview'
-import { type TickRefusal, tickBoxes } from '@/pr/tick'
+import {
+  readUiPassHead,
+  type TickRefusal,
+  tickBoxes,
+  type UiPassSummary,
+  writeUiPassLine,
+} from '@/pr/tick'
 import {
   commentRowOf,
   identityOf,
@@ -157,9 +163,16 @@ interface TickOptions extends ReadOptions {
   readonly head?: string
 }
 
-type TickReason = TickRefusal | 'stale-head' | 'bad-boxes' | 'no-comment'
+type TickReason =
+  | TickRefusal
+  | 'stale-head'
+  | 'bad-boxes'
+  | 'no-comment'
+  | 'body-refused'
 
 const TICK_REFUSALS: Record<TickReason | 'gh-failed', string> = {
+  'body-refused':
+    'The boxes are ticked on the evidence comment, but gh could not edit the pull request body, so its UI pass line still shows the earlier result. Re-run the tick to retry the body.',
   'stale-head':
     'The head named is not the branch tip on the remote, so a tick would claim a pass on a commit that is no longer the pull request. Re-drive the checklist at the tip.',
   'bad-boxes':
@@ -736,6 +749,11 @@ export function register(program: Command): void {
         'comment. Together with --checklist the link and the checklist land in',
         'one comment.',
         '',
+        "A render at a new head also resets the pull request body's UI pass",
+        'line, the one `canon pr tick` writes under ## Testing, to unchecked',
+        'naming that head. It touches no other body text, leaves a line already',
+        'naming this head alone, and reports `uiPass` as reset or reset-refused.',
+        '',
         'Both reasons carry what the marked comment already posted, each field',
         'present only when that comment holds it:',
         '  preview    the hosted **Preview:** address the comment carries',
@@ -1024,8 +1042,17 @@ export function register(program: Command): void {
         'it. A later render at another head clears a tick whose stamp names',
         'a different commit.',
         '',
+        "It also keeps one marked line in the pull request body's ## Testing,",
+        'such as `- [x] UI pass, 17 of 17 boxes passed at <short sha>, 1 taste',
+        'box left to the operator`. The line is ticked only when every box a',
+        'driver can run is ticked, counts taste boxes apart, and is the only',
+        'body text this verb writes, so hand edits elsewhere survive.',
+        '',
         'Read `reason` on the JSON record:',
-        '  ticked       the boxes were ticked, with the tip in `head`',
+        '  ticked       the boxes were ticked and the body line written, with the',
+        '               tip in `head`',
+        '  body-refused the comment is ticked but gh could not edit the body,',
+        '               exit 1 with `commentTicked`. Re-run to retry the body.',
         '  stale-head   --head is not the remote branch tip, nothing written',
         '  taste-box    a named box ends in (taste), nothing written',
         '  no-box       a named number is past the checklist, nothing written',
@@ -2437,10 +2464,30 @@ async function runEvidence(
     return 1
   }
 
+  // A UI pass line stamped at an earlier head describes a tree that is gone,
+  // so a render at a new head puts it back to unchecked. A line already
+  // naming this head is left alone, since each body edit reruns the label gate.
+  const priorBody = identity.body ?? ''
+  const stampedHead = readUiPassHead(priorBody)
+  let uiPass: 'reset' | 'reset-refused' | undefined
+  if (stampedHead !== undefined && !identity.head.startsWith(stampedHead)) {
+    const reset = writeUiPassLine(priorBody, {
+      kind: 'reset',
+      head: identity.head,
+    })
+    uiPass = (await patchPullBody(root, identity.number, reset))
+      ? 'reset'
+      : 'reset-refused'
+  }
+
   logStep('Scope')
   logInfo(
     `${plural(caseCount, 'case')} across ${plural(states.length, 'state')}`,
   )
+  if (uiPass === 'reset') logInfo('UI pass line reset to the new head')
+  if (uiPass === 'reset-refused') {
+    logWarn('gh could not edit the body, so its UI pass line names an old head')
+  }
   if (sized.unread.length > 0) {
     logWarn(
       `width unread for ${plural(sized.unread.length, 'image')}, rendered at 1000: ${sized.unread.join(', ')}`,
@@ -2469,6 +2516,7 @@ async function runEvidence(
         body,
         states,
         ...(sized.unread.length > 0 && { widthUnread: sized.unread }),
+        ...(uiPass !== undefined && { uiPass }),
         ...(commentId !== undefined && { commentId }),
         ...carried,
       })}\n`,
@@ -2941,9 +2989,53 @@ async function runTick(
     if (patched === null) return refuseTick('gh-failed')
   }
 
+  const boxes = readChecklistBoxes(
+    findEvidenceChecklist([{ body: result.body }]) ?? '',
+  )
+  const driven = boxes.filter((box) => !box.isTaste)
+  const summary: UiPassSummary = {
+    kind: 'passed',
+    // A tick counts as this pass's only when stamped at the tip, since an
+    // unstamped one is the author's claim and an older stamp names another head.
+    passed: driven.filter(
+      (box) =>
+        box.isTicked &&
+        box.stamp !== undefined &&
+        reading.tip.startsWith(box.stamp),
+    ).length,
+    total: driven.length,
+    taste: boxes.length - driven.length,
+    head: reading.tip,
+  }
+  const priorBody = identity.body ?? ''
+  const nextBody = writeUiPassLine(priorBody, summary)
+  if (
+    nextBody !== priorBody &&
+    !(await patchPullBody(root, identity.number, nextBody))
+  ) {
+    logStep('Partly ticked')
+    logWarn(TICK_REFUSALS['body-refused'])
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: 'body-refused',
+          message: TICK_REFUSALS['body-refused'],
+          commentTicked: true,
+          head: reading.tip,
+          boxes: numbers.map(Number),
+          commentId,
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
   logStep('Ticked')
   logInfo(
-    `${plural(numbers.length, 'box')} at ${reading.tip.slice(0, 7)} on comment ${commentId}`,
+    `${plural(numbers.length, 'box')} at ${reading.tip.slice(0, 7)} on comment ${commentId}, UI pass line on the body`,
   )
   outro()
   if (emitJson) {
@@ -2961,6 +3053,23 @@ async function runTick(
   return 0
 }
 
+/** Replaces a pull request's body, which `gh` takes through the REST pulls endpoint a cloud proxy serves. */
+async function patchPullBody(
+  root: string,
+  number: number,
+  body: string,
+): Promise<boolean> {
+  const patched = await gh(root, [
+    'api',
+    '-X',
+    'PATCH',
+    `repos/{owner}/{repo}/pulls/${number}`,
+    '-f',
+    `body=${body}`,
+  ])
+  return patched !== null
+}
+
 /** One `gh api` call, keeping the HTTP status of a failure so a refused write can be told from a missing ref. */
 type ApiCall =
   | { readonly ok: true; readonly data: unknown }

package/src/commands/sessions.ts

@@ -3,6 +3,7 @@ import type { Command } from 'commander'
 import { checkClaim, type ClaimReport } from '@/sessions/claim'
 import {
   callerIdentity,
+  confidenceOf,
   repositoryOf,
   type ResolvedSession,
   resolveSessions,
@@ -134,9 +135,23 @@ export function register(program: Command): void {
         '',
         'The confidence field says how the liveness of a row was decided.',
         '"confirmed" matched the running process against the start time the',
-        'record stamped. "unverified" means only that the pid answers, which',
-        'cannot rule out a pid handed to an unrelated process, so a roster',
-        'reported that way is a candidate list rather than an identity.',
+        'record stamped, and reads "via": "pid". "unverified" means only that the',
+        'pid answers, which cannot rule out a pid handed to an unrelated',
+        'process, so a roster reported that way is a candidate list rather than',
+        'an identity. Where the start time cannot be read, a row whose messaging',
+        'socket accepts a connection is confirmed instead and reads "via":',
+        '"listener". The probe connects and closes without writing. Each row',
+        'carries its own "confidence", and the top-level field is the weakest of',
+        'the rows listed, so --branch is not weakened by a row it dropped.',
+        '',
+        'A reader in another pid namespace, such as a sandboxed shell, cannot',
+        'see the pid of a record stamped elsewhere. That row is judged on its',
+        'messaging socket instead: it stays on the roster as "unverified" with',
+        '"via": "socket", since a crashed session leaves its socket behind. A',
+        'foreign record whose socket accepts a connection is confirmed as',
+        '"listener". One whose socket is gone is left off the roster and',
+        'counted in "foreignDead", so an empty roster beside a count above zero',
+        'is one this reader could not check, not one whose sessions ended.',
         '',
         'The JSON record also carries "statusUpdatedAt" (the stamp the client',
         'wrote beside "status", or null where its record carries none) and',
@@ -463,8 +478,14 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     : null
 
   intro('canon sessions list')
-  reportConfidence(report)
-  reportSessions(shown, opts.branch, repository, own !== null)
+  reportConfidence(shown, report)
+  reportSessions(
+    shown,
+    opts.branch,
+    repository,
+    own !== null,
+    report.foreignDead,
+  )
   if (claim) reportClaim(claim)
   outro()
 
@@ -472,7 +493,9 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     process.stdout.write(
       `${JSON.stringify({
         dir: report.dir,
-        confidence: report.confidence,
+        // Over the rows shown, so an unrelated row --branch dropped cannot weaken it.
+        confidence: confidenceOf(shown),
+        foreignDead: report.foreignDead,
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
@@ -513,6 +536,7 @@ function selfRefusal(own: Extract<SelfReport, { kind: 'unresolved' }>): string {
  * addresses a session directly and the second opens by asking to be corrected.
  */
 function reportConfidence(
+  shown: readonly ResolvedSession[],
   report: Extract<SessionReport, { kind: 'resolved' }>,
 ): void {
   logStep('Liveness')
@@ -520,16 +544,30 @@ function reportConfidence(
   // A roster of none decided nothing, so the confirmed line would claim a check
   // over rows that do not exist. The registry is never pruned and holds a record
   // per session ever run, which is what makes the empty result worth stating.
-  if (report.sessions.length === 0) {
+  if (shown.length === 0) {
     logInfo(
-      'No row to decide. Every record belongs to a session that has ended.',
+      report.foreignDead > 0 || report.sessions.length > 0
+        ? 'No row to decide.'
+        : 'No row to decide. Every record belongs to a session that has ended.',
     )
     return
   }
 
-  if (report.confidence === 'confirmed') {
+  if (confidenceOf(shown) === 'confirmed') {
+    const listened = shown.filter(
+      (session) => session.via === 'listener',
+    ).length
     logInfo(
-      'Every row matched a running process against the start time its record stamped.',
+      listened === 0
+        ? 'Every row matched a running process against the start time its record stamped.'
+        : `Every row is confirmed, ${listened} of them because their messaging socket accepted a connection and the rest by start time.`,
+    )
+    return
+  }
+
+  if (shown.some((session) => session.via === 'socket')) {
+    logWarn(
+      'This reader sits in another pid namespace than some records, so those rows rest on a messaging socket existing alone. A crashed session leaves its socket behind, so treat the mapping as inferred and open by asking to be corrected.',
     )
     return
   }
@@ -544,6 +582,7 @@ function reportSessions(
   branch: string | undefined,
   repository: string | null,
   scoped: boolean,
+  foreignDead: number,
 ): void {
   logStep('Sessions')
 
@@ -567,7 +606,9 @@ function reportSessions(
     }
 
     logInfo(
-      'No live session. Every record in the registry belongs to a session that has ended.',
+      foreignDead > 0
+        ? `No live session could be confirmed. ${foreignDead} of the records come from another pid namespace and no socket answers for them, so this reader could not check whether they ended.`
+        : 'No live session. Every record in the registry belongs to a session that has ended.',
     )
     return
   }
@@ -630,6 +671,12 @@ function reportClaim(claim: ClaimReport): void {
     )
   }
 
+  if (claim.foreignDead > 0) {
+    logWarn(
+      `${claim.foreignDead} records from another pid namespace have no answering socket, so a session holding this branch may be missing. Treat it as unverified rather than clear.`,
+    )
+  }
+
   if (!claim.refsReadable) {
     logWarn(
       'The ref read failed, so this cannot say whether the branch already exists. Treat it as unverified rather than clear.',

package/src/commands/tasks.ts

@@ -33,6 +33,7 @@ import {
   claimLabel,
   nextLabel,
 } from '@/tasks/label'
+import { type ClosureOutcome, readClosure } from '@/tasks/closes'
 import { listTasks } from '@/tasks/list'
 import {
   type Claim,
@@ -142,6 +143,13 @@ interface OutcomeCommandOptions {
   readonly root?: string
 }
 
+interface ClosesCommandOptions {
+  readonly branch?: string
+  readonly json?: boolean
+  readonly plan?: string
+  readonly root?: string
+}
+
 interface ListCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -635,6 +643,57 @@ export function register(program: Command): void {
       process.exitCode = await runOutcome(task, opts)
     })
 
+  tasks
+    .command('closes')
+    .description('Name the issues the branch pull request closes')
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option(
+      '--branch <name>',
+      'Branch to treat as this pull request, defaulting to the checked-out one',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  a task and a plan both named, or neither',
+        '',
+        'Exit codes:',
+        '  0  the task is read, whether or not it closes',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Reads the `Issue:` lines, each `#NNN` or a comma list, and reports',
+        '`issues` and `closing`. The pull request closes them only when it is',
+        "the task's last slice, the condition the merge-time archive applies:",
+        'no open outcome and no other branch on `Pending branch:`. The branch',
+        'and the names it carried before a rename count as this one. Read off',
+        '`reason` when `closing` is false:',
+        '  no-issues       the task carries no `Issue:` number',
+        '  earlier-slice   this branch has a pull request on the task that is not',
+        '                  the last listed, so a later number closes the issue',
+        '  lookup-failed   the pull request lookup failed while the task already',
+        '                  lists a pull request, so an earlier slice cannot be ruled out',
+        '  open-outcomes   an outcome is still open, so a later slice closes it',
+        '  pending-branch  another branch is on `Pending branch:`',
+        '  no-outcomes     the task carries no outcomes',
+        '',
+        'Examples:',
+        '  canon tasks closes --plan closing-issue-references --json',
+        '  canon tasks closes v28.1-trigger-escalation --branch feat/x',
+        '',
+      ].join('\n'),
+    )
+    .action(async (task: string | undefined, opts: ClosesCommandOptions) => {
+      process.exitCode = await runCloses(task, opts)
+    })
+
   tasks
     .command('next-label')
     .description(
@@ -1196,6 +1255,67 @@ async function branchPullNumbers(
   }
 }
 
+/**
+ * The pull request numbers whose head is `branch`, read over REST because a
+ * cloud session's GitHub proxy refuses the GraphQL `gh pr list` runs on.
+ * Unlike `branchPullNumbers`, a failed or unreadable answer is null rather
+ * than an empty list, since the closing decision must not read a failure as
+ * a branch with no pull request.
+ */
+async function branchPullNumbersRest(
+  branch: string | undefined,
+): Promise<readonly number[] | null> {
+  if (branch === undefined) return []
+
+  const owner = await execa(
+    'gh',
+    ['api', 'repos/{owner}/{repo}', '--jq', '.owner.login'],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (owner.exitCode !== 0 || owner.stdout.trim() === '') return null
+
+  const result = await execa(
+    'gh',
+    [
+      'api',
+      '-X',
+      'GET',
+      'repos/{owner}/{repo}/pulls',
+      '-f',
+      `head=${owner.stdout.trim()}:${branch}`,
+      '-f',
+      'state=all',
+      '--jq',
+      '[.[].number]',
+    ],
+    {
+      cwd: process.cwd(),
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) return null
+
+  try {
+    const numbers: unknown = JSON.parse(result.stdout)
+    if (!Array.isArray(numbers)) return null
+
+    return numbers.every((number) => Number.isInteger(number))
+      ? (numbers as number[])
+      : null
+  } catch {
+    return null
+  }
+}
+
 async function runPlanLink(
   task: string,
   plan: string,
@@ -1381,6 +1501,66 @@ function reportPlanLink(
   return 0
 }
 
+async function runCloses(
+  task: string | undefined,
+  opts: ClosesCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord('canon tasks closes', selector, emitJson, process.cwd())
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const branch = opts.branch ?? (await workingBranch())
+  const branches = branch ? [branch, ...(await formerNames(branch))] : []
+  const outcome = await readClosure(
+    root,
+    selector,
+    branches,
+    await branchPullNumbersRest(branch),
+  )
+
+  return reportCloses(outcome, emitJson, root)
+}
+
+function reportCloses(
+  outcome: ClosureOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks closes', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        issues: outcome.issues,
+        closing: outcome.closing,
+        reason: outcome.reason,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks closes')
+  logStep(outcome.closing ? 'Closes' : 'Closes nothing')
+  logInfo(
+    outcome.issues.length > 0
+      ? `${outcome.stem} names ${outcome.issues.map((n) => `#${n}`).join(', ')}, ${outcome.reason}`
+      : `${outcome.stem} names no issue`,
+  )
+  outro()
+
+  return 0
+}
+
 function reportOutcome(
   outcome: CloseOutcome,
   emitJson: boolean,
@@ -2015,6 +2195,7 @@ function report(
     logInfo('retargeted the Ready: line')
   }
   if (outcome.priorityRowRemoved) logInfo('cleared the ordering row')
+  if (outcome.backlogRowRemoved) logInfo('cleared the backlog row')
   logRelinked(outcome.relinked, outcome.relinkFailed, root)
   if (outcome.indexRegenerated) logInfo('regenerated index.md')
   if (outcome.cut > 0) logInfo(`${outcome.cut} outcome(s) cut`)
@@ -2097,6 +2278,7 @@ function recordFor(
     from: relative(root, outcome.from),
     to: relative(root, outcome.to),
     priorityRowRemoved: outcome.priorityRowRemoved,
+    backlogRowRemoved: outcome.backlogRowRemoved,
     indexRegenerated: outcome.indexRegenerated,
     plans: planMovesFor(outcome.plans, root),
     ready: outcome.ready

package/src/commands/worktrees.ts

@@ -109,6 +109,8 @@ const UNREADABLE: Record<Unreadable, string> = {
     'The pull request read failed, so every worktree would report as unmerged whatever its real state. Authenticate gh and run this again.',
   'sessions-unreadable':
     'The session roster could not be read, so nothing was read about which worktrees are still held.',
+  'sessions-unchecked':
+    'Some session records come from another pid namespace and no socket answers for them, so a live holder may be missing from the roster. Run this from the namespace the sessions run in.',
 }
 
 const CONDITIONS = [