@erclx/canon 5.77.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/take.ts

@@ -114,6 +114,9 @@ export function register(program: Command): void {
         'WebP at 960 wide and 20 fps, keeping every third frame, with the cursor',
         'and click ring drawn from each camera track. It carries no zoom, so a',
         "reviewer sees the whole page. clip.mp4 stays each beat's raw take.",
+        'The reel is lossless, so a fade-out leaves no ghost, and it falls back',
+        'to lossy past 10 MB so a long reel still posts. The record says which',
+        'in `lossless`.',
         '',
         '  {',
         '    "beats": [',
@@ -127,7 +130,8 @@ export function register(program: Command): void {
         '  }',
         '',
         'Step kinds:',
-        '  move <target>|<x,y>    glide the pointer to a target or a point',
+        '  move <target>|<x,y>    glide the pointer to a target or a point, and',
+        '                         with hold <ms>, zoom onto its end for that long',
         '  click <target>         glide to the target and press it',
         '  dblclick <target>      glide to the target and press it twice',
         '  drag <from> <to>       press the from target, glide held, release on to',
@@ -143,6 +147,13 @@ export function register(program: Command): void {
         'PageDown, the four arrows as ArrowUp and the like, and F1 to F12. A key',
         'moves no pointer, so the camera neither aims at it nor ends a zoom.',
         '',
+        'A take paces each press on its own: the pointer rests 300 ms on the',
+        'target before a click, dblclick, or drag, and holds 500 ms on the',
+        'result before the next step. A fill waits 400 ms between pressing the',
+        'field and its first key, and holds 500 ms after its last. Setup steps',
+        'run unpaced. The camera zooms in over the glide reaching a target and',
+        'out over the glide leaving it, scaling about the target.',
+        '',
         'drag drives pointer events, the kind a canvas board listens for. It',
         'starts no native HTML5 drag of a draggable element on the stepped route,',
         'so a beat needing one films the same only on the screencast route.',

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/design/components.ts

@@ -15,6 +15,8 @@
  * names out of that record and says they live in code, which is here.
  */
 
+import { readTemplate } from '@/design/template'
+
 export interface Component {
   readonly name: string
   /** Why the component exists, carried into the emitted stylesheet as a comment. */
@@ -43,30 +45,7 @@ const STATUS: Component = {
     '--color-muted',
     '--radius-marker',
   ],
-  rules: `.status {
-  display: inline-flex;
-  align-items: center;
-  gap: 0.42rem;
-  font-size: 0.75rem;
-  font-weight: 500;
-  letter-spacing: 0;
-  text-transform: none;
-  color: var(--color-muted);
-  white-space: nowrap;
-}
-
-.status::before {
-  content: '';
-  width: 6px;
-  height: 6px;
-  flex: none;
-  border-radius: var(--radius-marker);
-  background: var(--color-border);
-}
-
-.status.is-done::before {
-  background: var(--color-accent);
-}`,
+  rules: readTemplate('status.css'),
 }
 
 /**
@@ -84,35 +63,7 @@ const SCROLLBAR: Component = {
     'so the two engines cannot drift apart.',
   ].join('\n   '),
   reads: ['--color-border', '--color-muted', '--color-background'],
-  rules: `* {
-  scrollbar-width: thin;
-  scrollbar-color: var(--color-border) transparent;
-}
-
-*::-webkit-scrollbar {
-  width: 10px;
-  height: 10px;
-}
-
-*::-webkit-scrollbar-track {
-  background: transparent;
-}
-
-*::-webkit-scrollbar-thumb {
-  border-radius: var(--radius-marker);
-  background: var(--color-border);
-  /* Inset by painting a border in the page color, which is what keeps the
-     thumb off the edges without a second element. */
-  border: 3px solid var(--color-background);
-}
-
-*::-webkit-scrollbar-thumb:hover {
-  background: var(--color-muted);
-}
-
-*::-webkit-scrollbar-corner {
-  background: transparent;
-}`,
+  rules: readTemplate('scrollbar.css'),
 }
 
 /**
@@ -130,60 +81,7 @@ const HAND_DRAWN_FIGURE: Component = {
     'reading measure and cleared past an outline rail on a wide viewport.',
   ].join('\n   '),
   reads: ['--color-muted', '--figure-hand', '--figure-wide'],
-  rules: `/* ---- Figures: hand-drawn, and wider than the measure ---- */
-
-:root {
-  --figure-hand: 'Virgil', 'Excalifont', cursive;
-  --figure-wide: 64rem;
-}
-
-figure {
-  margin: 2.75rem 0;
-  width: var(--figure-wide);
-  max-width: 92vw;
-  margin-left: 50%;
-  transform: translateX(-50%);
-}
-
-figure svg {
-  width: 100%;
-  height: auto;
-  display: block;
-}
-
-/* CSS beats an SVG presentation attribute, so the diagrams pick up the
-   hand face without editing a single lesson. */
-figure svg text {
-  font-family: var(--figure-hand);
-}
-
-figcaption {
-  font-family: var(--figure-hand);
-  font-size: 1rem;
-  color: var(--color-muted);
-  margin: 1rem auto 0;
-  line-height: 1.5;
-  max-width: 52rem;
-}
-
-/* A figure breaks the measure and must still clear an outline rail. Deriving
-   the ceiling from the viewport does not hold, since a rail positioned from
-   the centre keeps overlapping as the window widens, so the ceiling is fixed
-   instead. */
-@media (min-width: 1421px) {
-  figure {
-    max-width: 54rem;
-  }
-}
-
-@media (max-width: 640px) {
-  figure {
-    width: 100%;
-    max-width: 100%;
-    margin-left: 0;
-    transform: none;
-  }
-}`,
+  rules: readTemplate('hand-drawn-figure.css'),
 }
 
 export const COMPONENTS: readonly Component[] = [

package/src/design/favicon.ts

@@ -1,3 +1,6 @@
+// Relative, since web/ bundles this module for FAVICON_COLORS and its `@` means web/src.
+import { fillTemplate, readTemplate } from './template'
+
 export interface ThemePair {
   readonly light: string
   readonly dark: string
@@ -68,23 +71,24 @@ export function renderFavicon(mark: string, colors: FaviconColors): string {
   const inset = EDGE_WIDTH / 2
   const shapes = markShapes(mark)
 
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${left} ${top} ${round(side)} ${round(side)}">
-  <style>
-    .tile { fill: ${colors.tile.dark}; stroke: ${colors.tile.dark}; }
-    .c { fill: ${colors.c.dark}; }
-    .pip { fill: ${colors.pip.dark}; }
-    @media (prefers-color-scheme: light) {
-      .tile { fill: ${colors.tile.light}; stroke: ${colors.edge}; }
-      .c { fill: ${colors.c.light}; }
-      .pip { fill: ${colors.pip.light}; }
-    }
-  </style>
-  <rect class="tile" x="${round(left + inset)}" y="${round(top + inset)}" width="${round(side - EDGE_WIDTH)}" height="${round(side - EDGE_WIDTH)}" rx="${round(side * TILE_RADIUS - inset)}" stroke-width="${EDGE_WIDTH}" />
-  <g class="c">
-  ${shapes.replace(/\n\s*/g, '\n  ')}
-  </g>
-</svg>
-`
+  return fillTemplate(readTemplate('favicon.svg'), {
+    left: String(left),
+    top: String(top),
+    side: String(round(side)),
+    tileX: String(round(left + inset)),
+    tileY: String(round(top + inset)),
+    tileSide: String(round(side - EDGE_WIDTH)),
+    tileRadius: String(round(side * TILE_RADIUS - inset)),
+    edgeWidth: String(EDGE_WIDTH),
+    tileDark: colors.tile.dark,
+    tileLight: colors.tile.light,
+    edge: colors.edge,
+    cDark: colors.c.dark,
+    cLight: colors.c.light,
+    pipDark: colors.pip.dark,
+    pipLight: colors.pip.light,
+    shapes: shapes.replace(/\n\s*/g, '\n  '),
+  })
 }
 
 /**

package/src/design/render.ts

@@ -6,6 +6,7 @@ import { fontFaceBlock } from '@/design/css'
 import { faviconLink } from '@/design/favicon'
 import type { FontFace } from '@/design/fonts'
 import { FONT_FACES } from '@/design/fonts'
+import { fillTemplate, readTemplate } from '@/design/template'
 import { colorValue } from '@/design/tokens'
 
 export interface RenderResult {
@@ -239,33 +240,14 @@ function buildHtml(
   const summary = tagged
     ? `\n<p class="note">${total - tagged} of ${total} cells are anchored to a source. The other ${tagged} ${verb} <code>? verify</code>, so nothing anchors them yet.</p>`
     : ''
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">${favicon === undefined ? '' : `\n${faviconLink(favicon)}`}
-<title>Design tokens</title>
-<link rel="stylesheet" href="design.css">
-<style>
-${previewChrome()}
-  body { font-family: ${bodyStack}; margin: 2rem; max-width: 960px; color: var(--preview-ink); background: var(--preview-paper); }
-  h1 { margin-top: 0; }
-  h2 { margin-top: 2rem; border-bottom: 1px solid var(--preview-rule); padding-bottom: 0.25rem; }
-  table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; }
-  th, td { text-align: left; padding: 0.5rem 0.75rem; border-bottom: 1px solid var(--preview-rule); font-size: 14px; }
-  th { background: var(--preview-panel); font-weight: 600; }
-  .swatch { display: inline-block; width: 1.5rem; height: 1.5rem; border-radius: 4px; border: 1px solid var(--preview-rule); vertical-align: middle; margin-right: 0.5rem; }
-  .bar { display: inline-block; height: 1rem; background: var(--preview-muted); border-radius: 2px; vertical-align: middle; }
-  .note { color: var(--preview-muted); font-size: 13px; margin-top: 0.5rem; }
-  .empty { color: var(--preview-muted); font-style: italic; }${verifyStyle}
-</style>
-</head>
-<body>
-<h1>Design tokens</h1>
-<p class="note">Generated from <code>canon/DESIGN.md</code> by <code>bun run web:previews</code>. Token preview only, not a screen mock.</p>${summary}
-${sections.join('\n')}
-</body>
-</html>
-`
+  return fillTemplate(readTemplate('preview.html'), {
+    favicon: favicon === undefined ? '' : `\n${faviconLink(favicon)}`,
+    chrome: previewChrome(),
+    bodyStack,
+    verifyStyle,
+    summary,
+    sections: sections.join('\n'),
+  })
 }
 
 function sectionPersonality(text: string): string {

package/src/design/template.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs'
+
+/**
+ * A file under `templates/`, resolved from this module so the published CLI
+ * finds it wherever the package is installed. Each file ends on one newline
+ * that the emitted text does not carry, so that newline is dropped.
+ *
+ * The folder is outside the formatter, since a reflowed template changes the
+ * bytes every generator emits.
+ */
+export function readTemplate(file: string): string {
+  return readFileSync(
+    new URL(`./templates/${file}`, import.meta.url),
+    'utf8',
+  ).replace(/\n$/, '')
+}
+
+const SLOT = /\{\{(\w+)\}\}/g
+
+/**
+ * Fills each `{{name}}` slot from `values`. A slot with no value, or a value no
+ * slot asks for, throws, so a template and its caller cannot drift apart
+ * silently.
+ */
+export function fillTemplate(
+  template: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  const used = new Set<string>()
+  const filled = template.replace(SLOT, (_, name: string) => {
+    const value = values[name]
+    if (value === undefined)
+      throw new Error(`template slot {{${name}}} has no value`)
+    used.add(name)
+    return value
+  })
+  const unused = Object.keys(values).filter((name) => !used.has(name))
+  if (unused.length > 0) {
+    throw new Error(`template has no slot for ${unused.join(', ')}`)
+  }
+  return filled
+}

package/src/design/templates/favicon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="{{left}} {{top}} {{side}} {{side}}">
+  <style>
+    .tile { fill: {{tileDark}}; stroke: {{tileDark}}; }
+    .c { fill: {{cDark}}; }
+    .pip { fill: {{pipDark}}; }
+    @media (prefers-color-scheme: light) {
+      .tile { fill: {{tileLight}}; stroke: {{edge}}; }
+      .c { fill: {{cLight}}; }
+      .pip { fill: {{pipLight}}; }
+    }
+  </style>
+  <rect class="tile" x="{{tileX}}" y="{{tileY}}" width="{{tileSide}}" height="{{tileSide}}" rx="{{tileRadius}}" stroke-width="{{edgeWidth}}" />
+  <g class="c">
+  {{shapes}}
+  </g>
+</svg>
+

package/src/design/templates/hand-drawn-figure.css

@@ -0,0 +1,54 @@
+/* ---- Figures: hand-drawn, and wider than the measure ---- */
+
+:root {
+  --figure-hand: 'Virgil', 'Excalifont', cursive;
+  --figure-wide: 64rem;
+}
+
+figure {
+  margin: 2.75rem 0;
+  width: var(--figure-wide);
+  max-width: 92vw;
+  margin-left: 50%;
+  transform: translateX(-50%);
+}
+
+figure svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* CSS beats an SVG presentation attribute, so the diagrams pick up the
+   hand face without editing a single lesson. */
+figure svg text {
+  font-family: var(--figure-hand);
+}
+
+figcaption {
+  font-family: var(--figure-hand);
+  font-size: 1rem;
+  color: var(--color-muted);
+  margin: 1rem auto 0;
+  line-height: 1.5;
+  max-width: 52rem;
+}
+
+/* A figure breaks the measure and must still clear an outline rail. Deriving
+   the ceiling from the viewport does not hold, since a rail positioned from
+   the centre keeps overlapping as the window widens, so the ceiling is fixed
+   instead. */
+@media (min-width: 1421px) {
+  figure {
+    max-width: 54rem;
+  }
+}
+
+@media (max-width: 640px) {
+  figure {
+    width: 100%;
+    max-width: 100%;
+    margin-left: 0;
+    transform: none;
+  }
+}