@erclx/canon 5.78.0 → 5.79.0

package/src/commands/sessions.ts

@@ -11,6 +11,7 @@ import {
   type SessionReport,
   selfOf,
 } from '@/sessions/resolve'
+import { readStop, type StopReading } from '@/sessions/stop'
 import {
   type Behind,
   exportSession,
@@ -32,8 +33,11 @@ interface ListCommandOptions {
   readonly branch?: string
   readonly repository?: string
   readonly self?: boolean
+  readonly stopped?: boolean
 }
 
+type ListedSession = ResolvedSession & StopReading
+
 const REASONS: Record<string, string> = {
   'not-a-repository': 'working outside any git repository',
   'detached-head': 'detached HEAD, so the worktree holds no branch name',
@@ -67,6 +71,7 @@ export function register(program: Command): void {
       '--self',
       "Report the caller's own row, and refuse where the roster holds none",
     )
+    .option('--stopped', 'Report only the sessions a usage limit stopped')
     .addHelpText(
       'after',
       [
@@ -161,12 +166,30 @@ export function register(program: Command): void {
         'framed listing renders the same dwell beside the status, at the',
         'coarsest unit that keeps it a whole number.',
         '',
+        'Each row also carries "stopped" and "stopResets", read from the tail of',
+        'the session transcript. "stopped" is "usage-limit" when the last',
+        'assistant entry is a limit stop, passing over a synthetic entry with no',
+        'error, such as the one a client restart writes. "stopResets" holds the',
+        'text the client wrote after "resets", or null when it wrote none.',
+        '"stopped" is "unknown" when the transcript could not be read or a',
+        'limit-worded entry has another shape, so the row may be stopped, and',
+        'null otherwise. A "busy" row reads',
+        'null without opening its transcript, since a turn is running.',
+        '',
+        '--stopped keeps the "usage-limit" rows after --branch and --self apply.',
+        'It drops "unknown" rows, and "stopsUnread" counts them before it does,',
+        'so a count above zero means a row here may be stopped and is not listed.',
+        '"foreignDead" above zero leaves the same doubt about a session this',
+        'reader could not check, and an empty result says so on stderr.',
+        'An empty result exits 0. "claimed" still reads the whole roster.',
+        '',
         'Examples:',
         '  canon sessions list',
         '  canon sessions list --json',
         '  canon sessions list --branch feat/parser --json',
         '  canon sessions list --branch chore/agents --repository ../caret --json',
         '  canon sessions list --self --json',
+        '  canon sessions list --stopped --json',
         '',
       ].join('\n'),
     )
@@ -477,15 +500,37 @@ async function runList(opts: ListCommandOptions): Promise<number> {
     ? await checkClaim(opts.branch, { cwd: at, resolve: async () => report })
     : null
 
+  const read: readonly ListedSession[] = shown.map((session) => ({
+    ...session,
+    ...readStop(session),
+  }))
+  const stopsUnread = read.filter(
+    (session) => session.stopped === 'unknown',
+  ).length
+  const listed = opts.stopped
+    ? read.filter((session) => session.stopped === 'usage-limit')
+    : read
+
   intro('canon sessions list')
-  reportConfidence(shown, report)
+  reportConfidence(listed, report)
   reportSessions(
-    shown,
+    listed,
     opts.branch,
     repository,
     own !== null,
     report.foreignDead,
+    opts.stopped ? stopsUnread : null,
   )
+  if (opts.stopped && stopsUnread > 0) {
+    logWarn(
+      `${plural(stopsUnread, 'row')} could not be read and may be stopped, so this list can be short.`,
+    )
+  }
+  if (opts.stopped && own === null && report.foreignDead > 0) {
+    logWarn(
+      `${report.foreignDead} records from another pid namespace have no answering socket, so a stopped session may be missing from this list.`,
+    )
+  }
   if (claim) reportClaim(claim)
   outro()
 
@@ -494,8 +539,9 @@ async function runList(opts: ListCommandOptions): Promise<number> {
       `${JSON.stringify({
         dir: report.dir,
         // Over the rows shown, so an unrelated row --branch dropped cannot weaken it.
-        confidence: confidenceOf(shown),
+        confidence: confidenceOf(listed),
         foreignDead: report.foreignDead,
+        stopsUnread,
         branch: opts.branch ?? null,
         repository,
         worktree: claim?.worktree ?? null,
@@ -503,7 +549,7 @@ async function runList(opts: ListCommandOptions): Promise<number> {
         claimed: claim?.claimed ?? null,
         sessionsReadable: claim?.sessionsReadable ?? null,
         refsReadable: claim?.refsReadable ?? null,
-        sessions: shown,
+        sessions: listed,
       })}\n`,
     )
   }
@@ -578,11 +624,12 @@ function reportConfidence(
 }
 
 function reportSessions(
-  sessions: readonly ResolvedSession[],
+  sessions: readonly ListedSession[],
   branch: string | undefined,
   repository: string | null,
   scoped: boolean,
   foreignDead: number,
+  stopsUnread: number | null,
 ): void {
   logStep('Sessions')
 
@@ -596,6 +643,11 @@ function reportSessions(
   // was narrowed to one row before the branch filter ran. Reporting the wider
   // answer there would claim a reading this run never took.
   if (sessions.length === 0) {
+    if (stopsUnread !== null) {
+      logInfo(noneStopped(branch, scoped, foreignDead, stopsUnread))
+      return
+    }
+
     if (branch) {
       logInfo(
         scoped
@@ -630,12 +682,42 @@ function reportSessions(
           `unresolved: ${REASONS[session.unresolved ?? ''] ?? 'unknown'}`
         const dwell = formatDwell(session.statusDwellMs)
         const status = dwell ? `${session.status} ${dwell}` : session.status
-        return `${session.name}  ${status}  ${held}\n  ${session.cwd}`
+        return [
+          `${session.name}  ${status}  ${held}`,
+          `  ${session.cwd}`,
+          ...stopLine(session),
+        ].join('\n')
       })
       .join('\n'),
   )
 }
 
+/**
+ * Words an empty `--stopped` result by what was read, since "no session is
+ * stopped" is a claim about the machine that a row this run could not read, or
+ * a record it could not check, leaves open.
+ */
+function noneStopped(
+  branch: string | undefined,
+  scoped: boolean,
+  foreignDead: number,
+  stopsUnread: number,
+): string {
+  if (stopsUnread > 0 || (!scoped && foreignDead > 0)) {
+    return 'No session this reader could check is stopped.'
+  }
+  if (scoped) return 'This session is not stopped.'
+  return branch
+    ? `No session holding ${branch} is stopped.`
+    : 'No session is stopped.'
+}
+
+function stopLine(session: StopReading): string[] {
+  if (session.stopped === null) return []
+  const resets = session.stopResets ? `, resets ${session.stopResets}` : ''
+  return [`  stopped: ${session.stopped}${resets}`]
+}
+
 /**
  * Renders the dwell at the coarsest unit that keeps it a whole number, since a
  * reader scanning a roster wants an age at a glance rather than a millisecond

package/src/commands/tasks.ts

@@ -72,6 +72,7 @@ import {
   type ValidateOutcome,
   validateBoard,
 } from '@/tasks/validate'
+import { liveReaders } from '@/tasks/holders'
 import {
   intro,
   logAdd,
@@ -110,6 +111,7 @@ interface DeclineCommandOptions {
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
+  readonly live?: boolean
 }
 
 interface CitationsCommandOptions {
@@ -323,6 +325,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
     .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .option(
+      '--live',
+      'Also read the session roster and open pull requests for held rows',
+    )
     .addHelpText(
       'after',
       [
@@ -338,6 +344,12 @@ export function register(program: Command): void {
         `  no Waiting on cell renders past ${WAITING_LIMIT} characters`,
         '  a blocker citing a bare vNNN.N label settles like a linked one',
         '  a file two Run now rows share is listed, never failed',
+        '  with --live, no Up next or Needs a plan row is held by a live session',
+        "  or an open pull request on its plan's branch",
+        '',
+        'The `live` field states each --live source as read, unread, or not-asked.',
+        'A source that fails reads as unread and moves no exit code, so read that',
+        'field rather than taking exit 0 as clean. A run without --live reads neither.',
         '',
         'Refusals, read off `reason`:',
         '  no-board     the repository holds no `.canon/tasks/` board',
@@ -356,6 +368,7 @@ export function register(program: Command): void {
         'Examples:',
         '  canon tasks validate',
         '  canon tasks validate --json',
+        '  canon tasks validate --live --json',
         '',
       ].join('\n'),
     )
@@ -1911,7 +1924,10 @@ function reportNextLabel(
 
 async function runValidate(opts: ValidateCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
-  const outcome = await validateBoard(root)
+  const outcome = await validateBoard(
+    root,
+    opts.live ? { live: liveReaders(root) } : {},
+  )
 
   return reportValidation(outcome, opts.json ?? false, root)
 }
@@ -2390,8 +2406,30 @@ function reportValidation(
     } else {
       for (const task of outcome.unplaced) logWarn(describeUnplaced(task))
     }
-    outro()
+
+    if (outcome.live.sessions !== 'not-asked') {
+      logStep('Held rows')
+      if (
+        outcome.live.sessions === 'read' &&
+        outcome.live.pulls === 'read' &&
+        !outcome.findings.some((finding) => finding.kind === 'row-held')
+      ) {
+        logInfo('no row outside run now is held by a session or a pull request')
+      }
+    }
+  }
+
+  // Unread is a warning in both modes, since diagnostics reach stderr with --json too.
+  if (outcome.live.sessions === 'unread') {
+    logWarn('the session roster could not be read, so no session was checked')
   }
+  if (outcome.live.pulls === 'unread') {
+    logWarn(
+      'pull requests could not be read, so a hold may be missed or already merged',
+    )
+  }
+
+  if (!emitJson) outro()
 
   if (emitJson) {
     process.stdout.write(
@@ -2408,6 +2446,7 @@ function reportValidation(
         shared: outcome.shared,
         wide: outcome.wide,
         unplaced: outcome.unplaced,
+        live: outcome.live,
       })}\n`,
     )
   }

package/src/git/files.ts

@@ -56,15 +56,18 @@ export async function listChangedFiles(
   root: string,
   base: string,
 ): Promise<string[] | undefined> {
-  const changed = await git(root, ['diff', '--name-only', base])
+  // NUL-separated, since newline output C-quotes a path holding a quote or a
+  // non-ASCII character and the quoted spelling names no file.
+  const changed = await git(root, ['diff', '--name-only', '-z', base])
   const untracked = await git(root, [
     'ls-files',
+    '-z',
     '--others',
     '--exclude-standard',
   ])
   if (changed === undefined || untracked === undefined) return undefined
 
-  const paths = [...changed.split('\n'), ...untracked.split('\n')]
+  const paths = [...changed.split('\0'), ...untracked.split('\0')]
   return [...new Set(paths.filter(Boolean))].sort()
 }
 

package/src/indexes/frontmatter.ts

@@ -17,22 +17,43 @@ export interface Frontmatter {
  * missing block instead of ending the caller's whole run.
  */
 export function parseFrontmatter(source: string): Frontmatter | undefined {
+  const reading = readFrontmatterSource(source)
+  return reading.kind === 'parsed' ? reading.frontmatter : undefined
+}
+
+export type FrontmatterReading =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'invalid'; readonly message: string }
+  | { readonly kind: 'parsed'; readonly frontmatter: Frontmatter }
+
+/**
+ * Tells a source with no block from one whose block failed to parse, which
+ * `parseFrontmatter` folds into one undefined. A block that parses to a list
+ * or a scalar reads as invalid, since no field can be read off it.
+ */
+export function readFrontmatterSource(source: string): FrontmatterReading {
   const match = source.match(FRONTMATTER)
-  if (!match) return undefined
+  if (!match) return { kind: 'absent' }
 
   let parsed: unknown
   try {
     parsed = Bun.YAML.parse(match[1])
-  } catch {
-    return undefined
+  } catch (error) {
+    return {
+      kind: 'invalid',
+      message: error instanceof Error ? error.message : String(error),
+    }
   }
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    return undefined
+    return { kind: 'invalid', message: 'frontmatter is not a mapping' }
   }
 
   return {
-    raw: match[0],
-    fields: parsed as Record<string, unknown>,
+    kind: 'parsed',
+    frontmatter: {
+      raw: match[0],
+      fields: parsed as Record<string, unknown>,
+    },
   }
 }
 

package/src/indexes/render.ts

@@ -1,5 +1,9 @@
 import { basename, dirname, resolve } from 'node:path'
-import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import {
+  readField,
+  readFrontmatter,
+  readFrontmatterSource,
+} from '@/indexes/frontmatter'
 import { INDEX_FILE, listIndexes } from '@/indexes/walk'
 
 export interface IndexEntry {
@@ -81,8 +85,19 @@ export async function collectEntries(
   const entries: IndexEntry[] = []
   const errors: string[] = []
 
+  let invalid = 0
+
   for (const path of paths) {
-    const frontmatter = await readFrontmatter(path)
+    const reading = readFrontmatterSource(await Bun.file(path).text())
+    if (reading.kind === 'invalid') {
+      invalid += 1
+      errors.push(
+        `frontmatter is not valid YAML in ${path}: ${reading.message}`,
+      )
+      continue
+    }
+    const frontmatter =
+      reading.kind === 'parsed' ? reading.frontmatter : undefined
     const title = readField(frontmatter, 'title')
     const description = readField(frontmatter, 'description')
 
@@ -101,7 +116,10 @@ export async function collectEntries(
   }
 
   if (errors.length > 0) {
-    errors.push(`${errors.length} missing frontmatter field(s) in ${dir}`)
+    const missing = errors.length - invalid
+    if (missing > 0) {
+      errors.push(`${missing} missing frontmatter field(s) in ${dir}`)
+    }
     return { ok: false, errors }
   }
 

package/src/markdown/colons.ts

@@ -30,6 +30,12 @@ const BOLD_LABEL = /^(\*\*|__)[^*_]+\1$/
 /** What may stand in a lead once its code spans and links are masked. */
 const CONNECTIVE = /\b(?:and|or|to)\b|,/g
 
+/** Words and apostrophes or hyphens between them, with no sentence punctuation. */
+const PLAIN_LEAD = /^[\p{L}\p{N}][\p{L}\p{N}'’ -]*$/u
+
+/** The longest plain lead a line may open on and still read as a label. */
+const LEAD_WORDS = 3
+
 /** Blanks a span while holding its width, so a column stays where it was. */
 function blank(match: string): string {
   return ' '.repeat(match.length)
@@ -38,16 +44,20 @@ function blank(match: string): string {
 /**
  * Whether the text before a line's first colon is a label rather than a
  * clause: the lead of a list item, or a prefix that is only emphasis and a
- * masked code span. A list item's lead also reads as a label at any length
- * when only code spans, links, commas, and `and`, `or`, or `to` stand in it,
- * which is a file entry naming several paths.
+ * masked code span. A line, after any quote marker, also reads as a label when
+ * its lead is at most three plain words, such as `Issue` or `Test strategy`.
+ * A list item's lead also reads as a label at any length when only code spans,
+ * links, commas, and `and`, `or`, or `to` stand in it, which is a file entry
+ * naming several paths.
  */
 function isLabel(prefix: string, listItem: boolean): boolean {
   if (BOLD_LABEL.test(prefix.trim())) return true
 
   const words = prefix.replace(/[*_]/g, ' ').trim()
   if (words === '') return true
-  if (!listItem) return false
+  if (!listItem) {
+    return PLAIN_LEAD.test(words) && words.split(/\s+/).length <= LEAD_WORDS
+  }
   if (words.replace(CONNECTIVE, ' ').trim() === '') return true
   return words.split(/\s+/).length <= 4
 }

package/src/markdown/heading-case.ts

@@ -14,15 +14,22 @@ const TITLE = /^title:\s*(["']?)(.*?)\1\s*$/
 const CODE_SPAN = /(`+)(?:(?!\1).)*\1/g
 const CAPITALIZED = /^[A-Z][a-z]/
 
+/** A task's phase label, `v` and dotted digits, which the template fixes. */
+const PHASE_LABEL = /^v\d+\.\d+:\s+/
+
 /**
  * The words of `text` that break sentence case.
  *
  * A code span stands for one lowercase word, so a heading opening on one
  * counts that span as its first word. The first word with a letter in it is
- * exempt, which keeps a leading numeral from promoting the next word.
+ * exempt, which keeps a leading numeral from promoting the next word. A
+ * leading phase label is not a word of the heading, so the first word is the
+ * one after it.
  */
 function capitalizedAfterFirst(text: string): string[] {
-  const masked = maskDisplayed(text.replace(CODE_SPAN, 'code'))
+  const masked = maskDisplayed(
+    text.replace(PHASE_LABEL, '').replace(CODE_SPAN, 'code'),
+  )
     .replace(/\s+/g, ' ')
     .trim()
   const words = masked === '' ? [] : masked.split(' ')

package/src/pr/bijection.ts

@@ -1,4 +1,5 @@
 import type { RenamePair } from '@/git/files'
+import { findMislinked, type Mislinked } from '@/pr/links'
 import { extractKeyChangePaths, KEY_CHANGES, type PathClaim } from '@/pr/paths'
 
 /**
@@ -62,6 +63,12 @@ export interface BijectionReport {
    * comparison has no way to tell a stale claim from one it could not check.
    */
   readonly evidenceUnread: boolean
+  /**
+   * Links in the section whose anchor hashes a path other than the one their
+   * label names, which open the wrong file's diff. Empty for a body that links
+   * nothing, since an unlinked path is the ordinary form.
+   */
+  readonly mislinked: readonly Mislinked[]
 }
 
 export type Bijection =
@@ -231,6 +238,7 @@ export function compareKeyChanges(input: BijectionInput): Bijection {
     unnamed: reached.filter((path) => !owesNoBullet(path)),
     incidental: reached.filter(owesNoBullet),
     evidenceUnread,
+    mislinked: findMislinked(input.body, input.changed),
   }
 }
 

package/src/pr/evidence.ts

@@ -46,6 +46,9 @@ const FOLDED_SUMMARY = 'Within tolerance'
 /** The heading every body opens with. */
 const EVIDENCE_HEADING = '## Evidence'
 
+/** How the line counting renamed images whose pixels did not change opens. */
+const MOVED_PREFIX = '**Moved unchanged:**'
+
 /** How the visible commit line opens. */
 const BASE_PREFIX = '**Base:**'
 
@@ -82,14 +85,18 @@ const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp|avif|svg)$/i
 export interface EvidenceItem {
   readonly path: string
   readonly stem: string
-  /** True when `path` did not exist at the comparison's base commit. */
+  /** True when `path` did not exist at the comparison's base commit and was not renamed from a path that did. */
   readonly added: boolean
+  /** Where a renamed image sat at the base, which its before image reads from. Absent for any image that was not renamed. */
+  readonly basePath?: string
   /** Pixel width of the head image, read from its PNG header. Absent when unread. */
   readonly width?: number
   /** Pixel width of the base image, absent for an added case or an unread header. */
   readonly baseWidth?: number
   /** Whether the head differs from its base by no more than sub-visual noise. Absent when the pair was not compared. */
   readonly withinTolerance?: boolean
+  /** Whether the head and base files hold the same bytes. Read only for a renamed image, where it alone lets the listing drop the pair, since a small edit also passes the tolerance. */
+  readonly identical?: boolean
 }
 
 export interface EvidenceState {
@@ -131,11 +138,13 @@ function splitEvidencePath(path: string): {
 /**
  * Groups every evidence path in `changed` by its state, keying each entry
  * inside a state by filename stem so a before/after pair sharing a name
- * across two states can be read as one case.
+ * across two states can be read as one case. A path in `renamedFrom` was moved
+ * from the path it maps to, so it is not added and its base reads from there.
  */
 export async function groupEvidence(
   changed: readonly string[],
   existsAtBase: ExistsAtBase,
+  renamedFrom: ReadonlyMap<string, string> = new Map(),
 ): Promise<EvidenceReading> {
   const paths = changed.filter(isEvidencePath)
   if (paths.length === 0) return { kind: 'refused', reason: 'no-evidence' }
@@ -143,14 +152,20 @@ export async function groupEvidence(
   const resolved = await Promise.all(
     paths.map(async (path) => {
       const { state, stem } = splitEvidencePath(path)
-      const added = !(await existsAtBase(path))
-      return { path, state, stem, added }
+      const basePath = renamedFrom.get(path)
+      const added = basePath === undefined && !(await existsAtBase(path))
+      return { path, state, stem, added, basePath }
     }),
   )
 
   const byState = new Map<string, EvidenceItem[]>()
-  for (const { path, state, stem, added } of resolved) {
-    const item: EvidenceItem = { path, stem, added }
+  for (const { path, state, stem, added, basePath } of resolved) {
+    const item: EvidenceItem = {
+      path,
+      stem,
+      added,
+      ...(basePath !== undefined && { basePath }),
+    }
     const items = byState.get(state)
     if (items === undefined) byState.set(state, [item])
     else items.push(item)
@@ -283,7 +298,7 @@ function baseFold(item: EvidenceItem, repo: string, base: string): string[] {
     '<summary>Base</summary>',
     '',
     evidenceImage(
-      rawUrl(repo, base, item.path),
+      rawUrl(repo, base, item.basePath ?? item.path),
       `${escapeCell(item.stem)} base`,
       item.baseWidth,
     ),
@@ -576,8 +591,16 @@ export function renderEvidenceBody(
     states
       .map((entry) => ({ ...entry, items: entry.items.filter(keep) }))
       .filter((entry) => entry.items.length > 0)
-  const open = split((item) => item.withinTolerance !== true)
-  const folded = split((item) => item.withinTolerance === true)
+  const isMoved = (item: EvidenceItem): boolean =>
+    item.basePath !== undefined && item.identical === true
+  const open = split((item) => !isMoved(item) && item.withinTolerance !== true)
+  const folded = split(
+    (item) => !isMoved(item) && item.withinTolerance === true,
+  )
+  const movedCount = states.reduce(
+    (total, entry) => total + entry.items.filter(isMoved).length,
+    0,
+  )
 
   const headCount = open.reduce((total, entry) => total + entry.items.length, 0)
   const opener =
@@ -592,6 +615,12 @@ export function renderEvidenceBody(
     ...opening,
     `${BASE_PREFIX} ${commitLink(repo, base)} · **Head:** ${commitLink(repo, head)}`,
     '',
+    ...(movedCount === 0
+      ? []
+      : [
+          `${MOVED_PREFIX} ${movedCount} ${movedCount === 1 ? 'image' : 'images'}`,
+          '',
+        ]),
     ...sections,
     '',
     ...closing,