@erclx/canon 5.45.0 → 5.47.0

package/src/sessions/resolve.ts

@@ -22,6 +22,19 @@ export interface ResolvedSession {
   readonly cwd: string
   readonly kind: string
   readonly status: string
+  /**
+   * What decided the row was live. `pid` is a start time matched or a pid that
+   * answered, `socket` means the record belongs to another pid namespace and
+   * only its messaging socket file existed, so the row can be a crashed
+   * session's leftover, and `listener` means the messaging socket accepted a
+   * connection, which confirms the row wherever the start time cannot be read.
+   */
+  readonly via: 'pid' | 'socket' | 'listener'
+  /**
+   * How this row alone was decided, so a caller scoping the roster derives its
+   * confidence over the rows it keeps rather than over the whole machine.
+   */
+  readonly confidence: Confidence
   readonly startedAt: string | null
   /**
    * The stamp the record carries beside `status`, kept alongside the dwell it
@@ -64,9 +77,32 @@ export type SessionReport =
        * tells a caller whether the roster can be trusted as an identity.
        */
       readonly confidence: Confidence
+      /**
+       * Foreign-namespace records whose socket is gone. They read dead, but the
+       * reader could not check their pid, so an empty roster beside a count
+       * above zero is a roster that could not be checked rather than one that
+       * ended.
+       */
+      readonly foreignDead: number
       readonly sessions: readonly ResolvedSession[]
     }
 
+/**
+ * The weakest confidence among the rows, so one read tells a caller whether
+ * every row it holds is an identity. A caller scoping the roster calls this on
+ * the rows it keeps, since one unrelated row it dropped must not weaken it.
+ */
+export function confidenceOf(
+  sessions: readonly Pick<ResolvedSession, 'confidence'>[],
+): Confidence {
+  return sessions.every((session) => session.confidence === 'confirmed')
+    ? 'confirmed'
+    : 'unverified'
+}
+
+/** A live socket here accepted in 2 ms, and every probe runs in parallel. */
+const LISTEN_TIMEOUT_MS = 250
+
 export interface ResolveOptions {
   readonly dir?: string
   readonly probes?: LivenessProbes
@@ -167,6 +203,8 @@ function present(
   record: SessionRecord,
   located: Located,
   now: number,
+  via: ResolvedSession['via'],
+  confidence: Confidence,
 ): ResolvedSession {
   return {
     name: record.name,
@@ -175,6 +213,8 @@ function present(
     cwd: record.cwd,
     kind: record.kind ?? 'unknown',
     status: record.status ?? 'unknown',
+    via,
+    confidence,
     startedAt:
       record.startedAt === undefined
         ? null
@@ -213,21 +253,59 @@ export async function resolveSessions(
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
 
-  const live: SessionRecord[] = []
-  let confidence: Confidence = 'confirmed'
+  const live: {
+    record: SessionRecord
+    via: ResolvedSession['via']
+    confidence: Confidence
+  }[] = []
+  let foreignDead = 0
 
   for (const record of registry.records) {
     const state = liveness(record, probes)
-    if (!state.alive) continue
-    if (state.confidence === 'unverified') confidence = 'unverified'
-    live.push(record)
+    if (!state.alive) {
+      if (state.foreign) foreignDead += 1
+      continue
+    }
+    live.push({
+      record,
+      via: state.foreign ? 'socket' : 'pid',
+      confidence: state.confidence,
+    })
   }
 
+  // Only a row the start time left unverified is probed, so a machine that reads
+  // /proc pays nothing. An accept proves the session is running where a pid
+  // answering or a socket file existing does not.
+  const upgraded = await Promise.all(
+    live.map(async (row) => {
+      const socket = row.record.messagingSocketPath
+      if (
+        row.confidence === 'confirmed' ||
+        socket === undefined ||
+        probes.listens === undefined
+      ) {
+        return row
+      }
+      const accepted = await probes.listens(socket, LISTEN_TIMEOUT_MS)
+      return accepted
+        ? { ...row, via: 'listener' as const, confidence: 'confirmed' as const }
+        : row
+    }),
+  )
+
   const sessions = await Promise.all(
-    live.map(async (record) => present(record, await find(record.cwd), now)),
+    upgraded.map(async ({ record, via, confidence }) =>
+      present(record, await find(record.cwd), now, via, confidence),
+    ),
   )
 
-  return { kind: 'resolved', dir: registry.dir, confidence, sessions }
+  return {
+    kind: 'resolved',
+    dir: registry.dir,
+    confidence: confidenceOf(sessions),
+    foreignDead,
+    sessions,
+  }
 }
 
 /** The environment slice the caller's own identity is read from. */

package/src/tasks/archive.ts

@@ -107,6 +107,7 @@ export interface ArchiveSuccess {
   readonly from: string
   readonly to: string
   readonly priorityRowRemoved: boolean
+  readonly backlogRowRemoved: boolean
   readonly indexRegenerated: boolean
   /** Every live plan the task cited that no other live task still holds, in line order. */
   readonly plans: readonly PlanMove[]
@@ -556,7 +557,7 @@ function isRowFor(line: string, target: string): boolean {
 }
 
 /**
- * Drops the declined task's bullet from the backlog. A backlog line is a
+ * Drops the task's bullet from the backlog. A backlog line is a
  * bullet carrying a link rather than a table row, so the match is a bullet
  * prefix and the link target rather than `isRowFor`'s pipe-delimited cell.
  */
@@ -571,9 +572,17 @@ export function removeBacklogRow(
   return { text: kept.join('\n'), removed: kept.length !== lines.length }
 }
 
+/**
+ * A bullet is about a task when its first link targets it. A later link is a
+ * reference, such as a note on what the bullet waits for, and matching anywhere
+ * would drop that other task's line from a file no history backs.
+ */
 function isBulletFor(line: string, target: string): boolean {
   const trimmed = line.trimStart()
-  return /^[-*]\s/.test(trimmed) && trimmed.includes(target)
+  if (!/^[-*]\s/.test(trimmed)) return false
+
+  const first = trimmed.indexOf('](')
+  return first !== -1 && trimmed.startsWith(target, first)
 }
 
 /**
@@ -896,8 +905,8 @@ async function resolveStem(
 }
 
 /**
- * Archives one task as a single unit: the move, the ordering-row removal, and
- * the index regen. The hook and `task-complete` both call this, so every gate
+ * Archives one task as a single unit: the move, the ordering-row and backlog
+ * bullet removal, and the index regen. The hook and `task-complete` both call this, so every gate
  * refuses rather than reports. A caller with nobody watching cannot act on a
  * warning, and two callers gating differently is the drift this exists to stop.
  */
@@ -996,6 +1005,7 @@ export async function archiveTask(
 
   const { relinked, failed } = await repointInboundLinks(root, from, to)
   const priorityRowRemoved = await clearPriorityRow(dir, stem)
+  const backlogRowRemoved = await clearBacklogRow(dir, stem)
   const regen = await regenOne(dir, { dryRun: false })
 
   return {
@@ -1004,6 +1014,7 @@ export async function archiveTask(
     from,
     to,
     priorityRowRemoved,
+    backlogRowRemoved,
     indexRegenerated: regen.action === 'written',
     plans: plans.moves,
     ready: ready || undefined,

package/src/tasks/closes.ts

@@ -0,0 +1,136 @@
+import { readFile } from 'node:fs/promises'
+import {
+  fenceMask,
+  readOutcomes,
+  readPendingBranches,
+  readPullRequest,
+} from '@/tasks/archive'
+import {
+  openTask,
+  type RecordRefused,
+  type RecordSelector,
+} from '@/tasks/record'
+
+/**
+ * Why a task does or does not close its issues. `last-slice` is the only
+ * reason that closes. The rest mirror the conditions `archiveTask` applies at
+ * merge time, so an issue closes exactly when the task archives.
+ */
+export type ClosingReason =
+  | 'earlier-slice'
+  | 'last-slice'
+  | 'lookup-failed'
+  | 'no-issues'
+  | 'no-outcomes'
+  | 'open-outcomes'
+  | 'pending-branch'
+
+export interface Closure {
+  readonly issues: readonly number[]
+  readonly closing: boolean
+  readonly reason: ClosingReason
+}
+
+export interface TaskClosure extends Closure {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+}
+
+export type ClosureOutcome = TaskClosure | RecordRefused
+
+const ISSUE_LINE = /^Issue:[ \t]*(#\d+(?:[ \t]*,[ \t]*#\d+)*)[ \t]*$/
+
+/**
+ * Reads every `Issue:` line outside a fence, each a bare `#NNN` or a comma
+ * list of them. A line carrying anything else, such as the older bare-path
+ * form, names no issue rather than the numbers that happened to parse, since a
+ * wrong number would close an unrelated issue.
+ */
+export function readIssues(text: string): readonly number[] {
+  const lines = text.split('\n')
+  const fenced = fenceMask(lines)
+  const issues = new Set<number>()
+
+  for (const [index, line] of lines.entries()) {
+    if (fenced[index]) continue
+
+    const match = ISSUE_LINE.exec(line)
+    if (!match) continue
+
+    for (const entry of match[1].split(',')) {
+      issues.add(Number(entry.trim().slice(1)))
+    }
+  }
+
+  return [...issues]
+}
+
+/**
+ * Decides whether the pull request for `branches` closes the task's issues.
+ * `branches` is the working branch and every name it carried, since a rename
+ * leaves the `Pending branch:` marker under the old one. Any other pending
+ * branch is a slice still to ship, so the task stays open behind it.
+ */
+export function decideClosing(
+  text: string,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Closure {
+  const issues = readIssues(text)
+  if (issues.length === 0) {
+    return { issues, closing: false, reason: 'no-issues' }
+  }
+
+  const listed = readPullRequest(text)
+  const last = listed.at(-1)
+
+  // A failed lookup cannot rule out that this branch is an earlier slice, and
+  // closing early is the unsafe direction. With nothing recorded yet there is
+  // no earlier slice to confuse it with, so that case still closes.
+  if (pulls === null && listed.length > 0) {
+    return { issues, closing: false, reason: 'lookup-failed' }
+  }
+
+  if (
+    last !== undefined &&
+    pulls !== null &&
+    !pulls.includes(last) &&
+    pulls.some((number) => listed.includes(number))
+  ) {
+    return { issues, closing: false, reason: 'earlier-slice' }
+  }
+
+  const others = readPendingBranches(text).filter(
+    (branch) => !branches.includes(branch),
+  )
+  if (others.length > 0) {
+    return { issues, closing: false, reason: 'pending-branch' }
+  }
+
+  const { open, closed, cut } = readOutcomes(text)
+  if (open.length > 0) {
+    return { issues, closing: false, reason: 'open-outcomes' }
+  }
+
+  if (closed.length === 0 && cut.length === 0) {
+    return { issues, closing: false, reason: 'no-outcomes' }
+  }
+
+  return { issues, closing: true, reason: 'last-slice' }
+}
+
+/** Resolves the task through the same selector `pull-request` takes. */
+export async function readClosure(
+  root: string,
+  selector: RecordSelector,
+  branches: readonly string[],
+  pulls: readonly number[] | null = [],
+): Promise<ClosureOutcome> {
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const text = await readFile(opened.path, 'utf8')
+
+  return { ok: true, ...opened, ...decideClosing(text, branches, pulls) }
+}

package/src/tasks/record.ts

@@ -400,7 +400,7 @@ async function resolveStem(
   return matched[0]
 }
 
-async function openTask(
+export async function openTask(
   root: string,
   selector: RecordSelector,
 ): Promise<{ readonly stem: string; readonly path: string } | RecordRefused> {

package/src/worktrees/reclaim.ts

@@ -37,7 +37,11 @@ export type Refusal =
   | 'held-by-session'
 
 /** Why the whole reading was refused, so no verdict was produced at all. */
-export type Unreadable = 'gh-missing' | 'gh-failed' | 'sessions-unreadable'
+export type Unreadable =
+  | 'gh-missing'
+  | 'gh-failed'
+  | 'sessions-unreadable'
+  | 'sessions-unchecked'
 
 /**
  * Which removal shape applies. `session` removes the background session and its
@@ -395,6 +399,17 @@ export async function reclaimReport(
     }
   }
 
+  // A foreign-namespace record whose socket is gone reads dead, but a reader
+  // that cannot see the pid may also be unable to see the socket, so it may be
+  // a live holder. The roster drops it, and a removal on that reading is final.
+  if (sessions.foreignDead > 0) {
+    return {
+      kind: 'unreadable',
+      reason: 'sessions-unchecked',
+      detail: `${sessions.foreignDead} session records come from another pid namespace and no socket answers for them, so nothing was read about whether they still hold a worktree.`,
+    }
+  }
+
   const byBranch = new Map(
     merged.merged.map((request) => [request.branch, request.number]),
   )

package/tooling/base/configs/scripts/verify.ts

@@ -323,7 +323,7 @@ function checkMarkdownBans(): void {
     case 2:
       pipeOutput(output)
       fail(
-        'Markdown prose carries a banned character, or a relative link resolves to nothing on disk',
+        'Markdown prose carries a banned character, a relative link resolves to nothing on disk, or a gated path breaks a density limit',
       )
       break
     case 3:

package/tooling/base/seeds/.github/pull_request_template.md

@@ -8,7 +8,7 @@
 - <Verb> <specific component/file/function>
 
 <!-- ## Technical context (optional, omit for docs/config/trivial changes) -->
-<!-- - <Why this approach was taken, not what changed> -->
+<!-- **<Decision in a few words>.** <Why this approach, what the code can't show, and any shortcoming> -->
 
 ## Testing
 

package/tooling/claude/seeds/.claude/hooks/board-validate.sh

@@ -51,7 +51,7 @@ fi
 # Exit 2 carries findings, so the status is read off the record rather than
 # the exit code.
 record=$(canon tasks validate --json --root "$root" 2>/dev/null)
-ok=$(printf '%s' "$record" | jq -r '.ok // empty' 2>/dev/null)
+ok=$(printf '%s' "$record" | jq -r '.ok | tostring' 2>/dev/null)
 
 if [ "$ok" = false ]; then
   report "canon tasks validate refused the board after this edit: $(printf '%s' "$record" | jq -r '.message // .reason')"

package/tooling/claude/seeds/CLAUDE.md

@@ -4,14 +4,14 @@
 
 ## Context
 
-- Before non-trivial work in a domain read `canon/context/<domain>.md`. Pick which from the index anchor below.
+- Before non-trivial work in a domain, read its entry under `canon/context/`. Find it from the index anchor below.
 
 @canon/REQUIREMENTS.md
 @canon/context/index.md
 
 ## Commands
 
-- [Command to run before committing]
+- Run `bun run check` to verify and `bun run format` to fix before committing. The pre-push hook runs `check`, which writes nothing.
 
 ## Key paths
 

package/governance/rules/canon/task-scope.md

@@ -1,12 +0,0 @@
----
-description: Scope, size, and link a task file correctly
----
-
-# Tasks standards
-
-## Task files
-
-- Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
-- Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- Write a plan in `.canon/plans/` when a task needs execution detail beyond its own file, and link it from the task's intro paragraph.
-- Write that plan in the same session as the task, since the executing session would otherwise re-derive the reasoning behind it.