@erclx/canon 5.78.0 → 5.79.0

package/src/pr/health.ts

@@ -1,18 +1,26 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
+/** The key listing folders whose listeners skip the health paths. */
+export const PAGE_ONLY_KEY = 'page-only'
+
 /** Where a project declares what `canon pr local` checks beyond the page. */
 export const LOCAL_CONFIG_REL = join('canon', 'config', 'local.toml')
 
 /**
- * The health paths a project declared. `none` is an absent file or an empty
- * `health = []`. `invalid` is a declaration that exists and cannot be used,
- * which refuses rather than falling back to the page-only probe, since that
- * fallback is the failure the declaration exists to catch.
+ * The health paths a project declared, with the folders whose listeners skip
+ * them. `none` is an absent file or an empty `health = []`. `invalid` is a
+ * declaration that exists and cannot be used, which refuses rather than
+ * falling back to the page-only probe, since that fallback is the failure the
+ * declaration exists to catch.
  */
 export type HealthDeclaration =
-  | { readonly kind: 'paths'; readonly paths: readonly string[] }
-  | { readonly kind: 'none' }
+  | {
+      readonly kind: 'paths'
+      readonly paths: readonly string[]
+      readonly pageOnly: readonly string[]
+    }
+  | { readonly kind: 'none'; readonly pageOnly: readonly string[] }
   | { readonly kind: 'invalid'; readonly reason: string }
 
 /**
@@ -28,9 +36,24 @@ function isLocalPath(entry: unknown): entry is string {
   )
 }
 
+/**
+ * A repository-relative folder as whole segments, or undefined when the entry
+ * is not one. Absolute paths, drive letters, backslashes, and `..` refuse,
+ * since each would name a place outside the repository. A leading `./` and
+ * trailing slashes are dropped so the match compares segments alone.
+ */
+function toFolder(entry: unknown): string | undefined {
+  if (typeof entry !== 'string') return undefined
+  if (entry.startsWith('/') || entry.includes('\\')) return undefined
+  if (/^[A-Za-z]:/.test(entry)) return undefined
+  const segments = entry.split('/').filter((s) => s !== '' && s !== '.')
+  if (segments.length === 0 || segments.includes('..')) return undefined
+  return segments.join('/')
+}
+
 export function readHealthPaths(root: string): HealthDeclaration {
   const path = join(root, LOCAL_CONFIG_REL)
-  if (!existsSync(path)) return { kind: 'none' }
+  if (!existsSync(path)) return { kind: 'none', pageOnly: [] }
 
   let parsed: Record<string, unknown>
   try {
@@ -42,15 +65,40 @@ export function readHealthPaths(root: string): HealthDeclaration {
     return { kind: 'invalid', reason: `${LOCAL_CONFIG_REL} is not valid TOML` }
   }
 
-  const declared = parsed.health
-  if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
-    return {
-      kind: 'invalid',
-      reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+  const hasHealth = 'health' in parsed
+  const hasPageOnly = PAGE_ONLY_KEY in parsed
+  if (!hasHealth && !hasPageOnly) return invalidHealth()
+
+  let paths: readonly string[] = []
+  if (hasHealth) {
+    const declared = parsed.health
+    if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
+      return invalidHealth()
     }
+    paths = declared
   }
 
-  return declared.length === 0
-    ? { kind: 'none' }
-    : { kind: 'paths', paths: declared }
+  let pageOnly: readonly string[] = []
+  if (hasPageOnly) {
+    const declared = parsed[PAGE_ONLY_KEY]
+    const folders = Array.isArray(declared) ? declared.map(toFolder) : []
+    if (!Array.isArray(declared) || folders.includes(undefined)) {
+      return {
+        kind: 'invalid',
+        reason: `${LOCAL_CONFIG_REL} needs ${PAGE_ONLY_KEY} as a list of folders relative to the repository, with no leading / and no ..`,
+      }
+    }
+    pageOnly = folders as string[]
+  }
+
+  return paths.length === 0
+    ? { kind: 'none', pageOnly }
+    : { kind: 'paths', paths, pageOnly }
+}
+
+function invalidHealth(): HealthDeclaration {
+  return {
+    kind: 'invalid',
+    reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+  }
 }

package/src/pr/links.ts

@@ -0,0 +1,160 @@
+import { createHash } from 'node:crypto'
+import { findBacktickSpans } from '@/markdown/backticks'
+import { KEY_CHANGES, LINE_SUFFIX, readSectionAt } from '@/pr/paths'
+
+/** A Key changes link whose anchor hashes a path other than its label's. */
+export interface Mislinked {
+  readonly path: string
+  readonly anchor: string
+}
+
+/**
+ * The fragment GitHub gives a file's diff in a pull request's Files tab, being
+ * `diff-` and the SHA-256 of the raw path. Read off a merged pull request's
+ * rendered page, so a path holding a space or a bracket hashes as written.
+ */
+export function diffAnchor(path: string): string {
+  return `diff-${createHash('sha256').update(path).digest('hex')}`
+}
+
+interface Located {
+  readonly text: string
+  readonly offset: number
+  readonly whole: string
+}
+
+/** The section's text and where it starts, in the body with line endings normalized. */
+function locateSection(body: string, title: string): Located | undefined {
+  const whole = body.replace(/\r\n/g, '\n')
+  const found = readSectionAt(whole, title)
+  return found === undefined ? undefined : { ...found, whole }
+}
+
+/** Blanks every code span, keeping offsets, so a bracket inside a path never reads as link syntax. */
+function maskSpans(text: string): string {
+  let out = text
+  for (const span of findBacktickSpans(text)) {
+    out =
+      out.slice(0, span.start) +
+      ' '.repeat(span.end - span.start) +
+      out.slice(span.end)
+  }
+  return out
+}
+
+/**
+ * An inline link: a destination bare or in angle brackets, then an optional
+ * quoted title. A form this misses reads as no link, and a span inside it then
+ * gets a second link nested in the first.
+ */
+const LINK =
+  /\[[^\]]*\]\(\s*(<[^>]*>|[^)\s]*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/dg
+const DIFF_DESTINATION = /#diff-[0-9a-f]{64}$/
+
+interface Edit {
+  readonly start: number
+  readonly end: number
+  readonly text: string
+}
+
+/**
+ * Writes each code span in `## Key changes` that names a changed file as a link
+ * to that file's diff, keeping the span as the label.
+ *
+ * Only an exact changed path is linked. A partial spelling or a folder names no
+ * single row in the Files tab, and a link to a guessed row is worse than none.
+ *
+ * A span that is the whole label of an existing diff link has its destination
+ * rewritten, which is how a wrong anchor clears. A span anywhere else inside a
+ * link's brackets is left alone, since a link nested in a link breaks the
+ * bullet, and the rewrite stays idempotent.
+ *
+ * `filesUrl` is the pull request's `/files` address, absolute because the body
+ * becomes the squash commit message, where a relative link resolves nowhere.
+ */
+export function linkKeyChanges(
+  body: string,
+  changed: readonly string[],
+  filesUrl: string,
+): string {
+  const located = locateSection(body, KEY_CHANGES)
+  if (located === undefined) return body
+
+  const { text } = located
+  const known = new Set(changed)
+  const links = [...maskSpans(text).matchAll(LINK)].map((match) => ({
+    start: match.index ?? 0,
+    end: (match.index ?? 0) + match[0].length,
+    destination: match[1] ?? '',
+    destinationStart: match.indices?.[1]?.[0] ?? 0,
+  }))
+
+  const edits: Edit[] = []
+  for (const span of findBacktickSpans(text)) {
+    const path = span.content.replace(LINE_SUFFIX, '')
+    if (!known.has(path)) continue
+    const target = `${filesUrl}#${diffAnchor(path)}`
+
+    const link = links.find((l) => l.start < span.start && span.end <= l.end)
+    if (link === undefined) {
+      edits.push({
+        start: span.start,
+        end: span.end,
+        text: `[${text.slice(span.start, span.end)}](${target})`,
+      })
+      continue
+    }
+
+    const wholeLabel =
+      span.start === link.start + 1 && text.startsWith('](', span.end)
+    if (!wholeLabel || !DIFF_DESTINATION.test(link.destination)) continue
+    edits.push({
+      start: link.destinationStart,
+      end: link.destinationStart + link.destination.length,
+      text: target,
+    })
+  }
+
+  let out = ''
+  let cursor = 0
+  for (const edit of edits) {
+    out += text.slice(cursor, edit.start) + edit.text
+    cursor = edit.end
+  }
+  out += text.slice(cursor)
+
+  return (
+    located.whole.slice(0, located.offset) +
+    out +
+    located.whole.slice(located.offset + text.length)
+  )
+}
+
+const DIFF_LINK = /\[(`+)([^`]+)\1\]\([^)\s]*#(diff-[0-9a-f]{64})\)/g
+
+/**
+ * Every Key changes link whose label is a changed path and whose anchor hashes
+ * another path.
+ *
+ * A label that is no changed path, such as a bare file name or a function, is
+ * left unjudged: it can open the right file under a spelling this cannot map
+ * back to a row, and an accusation needs the row.
+ */
+export function findMislinked(
+  body: string,
+  changed: readonly string[],
+): Mislinked[] {
+  const located = locateSection(body, KEY_CHANGES)
+  if (located === undefined) return []
+
+  const known = new Set(changed)
+  const out: Mislinked[] = []
+  for (const match of located.text.matchAll(DIFF_LINK)) {
+    const path = (match[2] ?? '').trim().replace(LINE_SUFFIX, '')
+    const anchor = match[3] ?? ''
+    if (known.has(path) && diffAnchor(path) !== anchor) {
+      out.push({ path, anchor })
+    }
+  }
+  return out
+}

package/src/pr/local.ts

@@ -45,6 +45,11 @@ async function firstFailingPath(
   return undefined
 }
 
+/** Whether `cwd` is `folder` or inside it, compared on whole path segments. */
+function isUnder(cwd: string, folder: string): boolean {
+  return cwd === folder || cwd.startsWith(`${folder}/`)
+}
+
 /**
  * Finds the server this worktree is running: the lowest port whose listening
  * process runs inside the worktree, answers an HTTP probe, and passes every
@@ -53,11 +58,14 @@ async function firstFailingPath(
  * lower one is the page by convention. Health is read on the page's own port,
  * since that is the address a reviewer drives, and a page whose backend fails
  * refuses as `unhealthy` naming the lowest page port's first failing path.
+ * A port whose listener runs under a `pageOnly` folder, matched on whole
+ * segments, is found on the page probe alone.
  */
 export async function findLocalServer(
   worktreeRoot: string,
   runner: LocalRunner,
   healthPaths: readonly string[] = [],
+  pageOnly: readonly string[] = [],
 ): Promise<LocalResult> {
   const listeners = await runner.listListeners()
   if (listeners === undefined) {
@@ -65,17 +73,22 @@ export async function findLocalServer(
   }
 
   const cwdByPid = new Map<number, string | undefined>()
-  const ports = new Set<number>()
+  const ports = new Map<number, boolean>()
+  const folders = pageOnly.map((folder) => `${worktreeRoot}/${folder}`)
   for (const { pid, port } of listeners) {
     if (!cwdByPid.has(pid)) cwdByPid.set(pid, await runner.cwdOf(pid))
     const cwd = cwdByPid.get(pid)
-    if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
+    if (cwd === undefined || !belongsTo(cwd, worktreeRoot)) continue
+    const skipsHealth = folders.some((folder) => isUnder(cwd, folder))
+    ports.set(port, (ports.get(port) ?? false) || skipsHealth)
   }
 
   let unhealthy: (HealthFailure & { readonly port: number }) | undefined
-  for (const port of [...ports].sort((a, b) => a - b)) {
+  for (const [port, skipsHealth] of [...ports].sort(([a], [b]) => a - b)) {
     if (!(await runner.probe(port))) continue
-    const failure = await firstFailingPath(port, healthPaths, runner)
+    const failure = skipsHealth
+      ? undefined
+      : await firstFailingPath(port, healthPaths, runner)
     if (failure === undefined) {
       return { kind: 'found', port, url: `http://localhost:${port}` }
     }

package/src/pr/paths.ts

@@ -77,7 +77,7 @@ const HEADING = /^(#{1,6})\s+(.+?)\s*$/
  * A `file.ts:42` or `file.ts:42-58` suffix, which is a reader's click target
  * rather than part of the name.
  */
-const LINE_SUFFIX = /:\d+(?:-\d+)?$/
+export const LINE_SUFFIX = /:\d+(?:-\d+)?$/
 
 /**
  * A span that carries a line suffix and nothing else, such as `:642` beside
@@ -214,6 +214,21 @@ function disclaimsChange(bullet: string): boolean {
  * reports rather than reading as an empty section.
  */
 export function readSection(body: string, title: string): string | undefined {
+  return readSectionAt(body, title)?.text
+}
+
+/**
+ * The section's text and the character offset it starts at, counted in the body
+ * with its line endings normalized to `\n`.
+ *
+ * The offset is what lets a caller rewrite the section in place. Searching the
+ * body for the text instead finds the first copy, so an identical block above
+ * the heading would take the edit.
+ */
+export function readSectionAt(
+  body: string,
+  title: string,
+): { readonly text: string; readonly offset: number } | undefined {
   const lines = body.replace(/\r\n/g, '\n').split('\n')
   const wanted = title.toLowerCase()
 
@@ -246,7 +261,10 @@ export function readSection(body: string, title: string): string | undefined {
     out.push(line)
   }
 
-  return out.join('\n')
+  const offset = lines
+    .slice(0, start)
+    .reduce((sum, line) => sum + line.length + 1, 0)
+  return { text: out.join('\n'), offset }
 }
 
 /**

package/src/sessions/stop.ts

@@ -0,0 +1,145 @@
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+import type { ResolvedSession } from '@/sessions/resolve'
+import { locateTranscript, projectsDir } from '@/sessions/transcript'
+
+export interface StopReading {
+  /**
+   * `usage-limit` means the last assistant entry is a limit stop, passing over
+   * a `<synthetic>` entry with no error, such as the one a client restart
+   * writes. `unknown` means the read failed or found a limit-worded entry of
+   * another shape, so the row may be stopped and nothing here can say.
+   */
+  readonly stopped: 'usage-limit' | 'unknown' | null
+  readonly stopResets: string | null
+}
+
+const NOT_STOPPED: StopReading = { stopped: null, stopResets: null }
+const UNREADABLE: StopReading = { stopped: 'unknown', stopResets: null }
+
+/**
+ * The largest measured distance from a final stop to the end of its file is
+ * under 4 KiB, while a live transcript reaches hundreds of megabytes, so the
+ * read stays positional and never loads the file.
+ */
+const WINDOW_BYTES = 1024 * 1024
+
+function readTail(path: string): {
+  readonly text: string
+  readonly cut: boolean
+} {
+  const fd = openSync(path, 'r')
+  try {
+    const { size } = fstatSync(fd)
+    const length = Math.min(size, WINDOW_BYTES)
+    const start = size - length
+    const buffer = Buffer.alloc(length)
+    let filled = 0
+    while (filled < length) {
+      const read = readSync(fd, buffer, filled, length - filled, start + filled)
+      if (read === 0) break
+      filled += read
+    }
+    return {
+      text: buffer.subarray(0, filled).toString('utf8'),
+      cut: start > 0,
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+function parseEntry(line: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(line)
+    return typeof parsed === 'object' && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : null
+  } catch {
+    return null
+  }
+}
+
+function entryText(message: Record<string, unknown>): string {
+  if (!Array.isArray(message.content)) return ''
+  return message.content
+    .map((block: { text?: unknown } | null) =>
+      typeof block?.text === 'string' ? block.text : '',
+    )
+    .join('\n')
+}
+
+/**
+ * Walks back to the entry that decides the row. No published contract describes
+ * the stop entry, so this rests on a measured shape: `error: "rate_limit"`, a
+ * `<synthetic>` model, `isApiErrorMessage`, and text naming the limit and its
+ * reset.
+ *
+ * A generated entry with limit wording and any other shape reads `unknown`,
+ * since a release renaming the field or the type still parses cleanly and would
+ * otherwise read as a session that never stopped. A `<synthetic>` entry with no
+ * error and no limit wording is passed over, since a client restart writes one
+ * reading `No response requested.` with no model turn behind it.
+ */
+function readEntries(text: string, cut: boolean): StopReading {
+  const lines = text.split('\n')
+  // The first line of a cut window usually starts mid-entry, and one that
+  // happens to parse cannot be told apart from it.
+  const first = cut ? 1 : 0
+
+  for (let index = lines.length - 1; index >= first; index -= 1) {
+    const entry = parseEntry(lines[index] ?? '')
+    if (entry === null || entry.isSidechain === true) continue
+
+    const message =
+      typeof entry.message === 'object' && entry.message !== null
+        ? (entry.message as Record<string, unknown>)
+        : {}
+    const synthetic = message.model === '<synthetic>'
+    const generated = synthetic || entry.isApiErrorMessage === true
+    const entryWords = generated ? entryText(message) : ''
+    const worded = /hit your .* limit/.test(entryWords)
+
+    if (entry.type !== 'assistant') {
+      if (worded) return UNREADABLE
+      continue
+    }
+
+    if (entry.error === 'rate_limit') {
+      return {
+        stopped: 'usage-limit',
+        stopResets: /resets (.+)/.exec(entryText(message))?.[1]?.trim() ?? null,
+      }
+    }
+    if (worded) return UNREADABLE
+    if (synthetic && entry.error === undefined) continue
+
+    return NOT_STOPPED
+  }
+
+  return cut ? UNREADABLE : NOT_STOPPED
+}
+
+/**
+ * Reads whether a usage limit stopped one roster row, from the tail of its
+ * transcript. A `busy` row reads nothing, since a turn is running and a resume
+ * may be in flight.
+ */
+export function readStop(
+  row: Pick<ResolvedSession, 'status' | 'sessionId'>,
+  dir: string = projectsDir(),
+): StopReading {
+  if (row.status === 'busy') return NOT_STOPPED
+  if (row.sessionId === null) return UNREADABLE
+
+  const located = locateTranscript(row.sessionId, dir)
+  if (located === null) return UNREADABLE
+
+  let tail: ReturnType<typeof readTail>
+  try {
+    tail = readTail(located.transcript)
+  } catch {
+    return UNREADABLE
+  }
+
+  return readEntries(tail.text, tail.cut)
+}

package/src/sessions/transfer/bundle.ts

@@ -21,7 +21,7 @@ import {
   readSideFolder,
   readTranscript,
   transcriptFacts,
-} from '@/sessions/transfer/transcript'
+} from '@/sessions/transcript'
 
 /** Bumped when a field changes meaning, so an older import refuses a newer bundle. */
 export const BUNDLE_FORMAT = 1

package/src/take/encode.ts

@@ -75,18 +75,24 @@ export function openFrameEncoder(out: string, fps: number): FrameEncoder {
   // Held so a failure while frames are still being written surfaces at close
   // rather than as an unhandled rejection.
   done.catch(() => {})
+  // Rejects once FFmpeg is gone, since a full pipe with no reader never drains.
+  const stopped = done.then(() => {
+    throw new Error('ffmpeg stopped reading frames')
+  })
+  stopped.catch(() => {})
+  // A write to the dead process's pipe fails here, and `stopped` reports it.
+  proc.stdin?.on('error', () => {})
 
   return {
-    write: (jpeg) =>
-      new Promise((resolve, reject) => {
-        const stdin = proc.stdin
-        if (!stdin || stdin.destroyed) {
-          reject(new Error('ffmpeg stopped reading frames'))
-          return
-        }
-        if (stdin.write(jpeg)) resolve()
-        else stdin.once('drain', resolve)
-      }),
+    write: async (jpeg) => {
+      const stdin = proc.stdin
+      if (!stdin || stdin.destroyed) return stopped
+      if (stdin.write(jpeg)) return
+      await Promise.race([
+        new Promise<void>((resolve) => stdin.once('drain', resolve)),
+        stopped,
+      ])
+    },
     close: async () => {
       proc.stdin?.end()
       await done
@@ -97,38 +103,6 @@ export function openFrameEncoder(out: string, fps: number): FrameEncoder {
   }
 }
 
-/**
- * Re-encodes a recorded clip to the same H.264 output at a constant `fps`, cut
- * at `ms`. Playwright's recorder pads its webm past the last frame by at least
- * a second, so the cut is what ends the clip where the take's clock stopped.
- * A shorter input stays as it is, since `-t` never extends one.
- */
-export async function transcode(
-  input: string,
-  out: string,
-  fps: number,
-  ms: number,
-): Promise<void> {
-  const proc = spawn(
-    'ffmpeg',
-    [
-      '-y',
-      '-loglevel',
-      'error',
-      '-i',
-      input,
-      '-t',
-      (ms / 1000).toFixed(3),
-      '-r',
-      String(fps),
-      ...OUTPUT,
-      out,
-    ],
-    { stdio: ['ignore', 'ignore', 'pipe'] },
-  )
-  await finished(proc)
-}
-
 /**
  * Counts a clip's frames, which a real-time take cannot know in advance and a
  * camera track has to match one for one.

package/src/take/frame-clock.ts

@@ -0,0 +1,46 @@
+/**
+ * Places a screencast's frames on the take's monotonic clock. Playwright stamps
+ * a frame in wall time, and a time service can step the wall clock mid-take, so
+ * a stamp is only ever read against the wall clock of the moment it arrives.
+ */
+
+/**
+ * A frame's time on the monotonic clock. A step between the frame's swap and its
+ * arrival cannot be told apart from latency, so a forward one lands that frame
+ * early and a backward one is capped at the arrival, the latest it can be.
+ */
+export function frameStamp(reading: {
+  readonly presentedWall: number
+  readonly wallNow: number
+  readonly monoNow: number
+}): number {
+  const { presentedWall, wallNow, monoNow } = reading
+  return Math.min(monoNow, presentedWall - (wallNow - monoNow))
+}
+
+/**
+ * Which frame fills each slot of a clip, as indexes into `stamps`, which holds
+ * the frames in arrival order. A slot takes the newest frame stamped at or
+ * before it, and slot 0 takes the first frame whenever it was presented. The
+ * indexes never fall, so an early stamp cannot reorder the clip. Empty when no
+ * frame arrived.
+ */
+export function slotFrames(
+  stamps: readonly number[],
+  clip: {
+    readonly startMs: number
+    readonly lengthMs: number
+    readonly frameMs: number
+  },
+): number[] {
+  if (stamps.length === 0) return []
+  const slots = Math.round(clip.lengthMs / clip.frameMs)
+  const filled: number[] = []
+  let at = 0
+  for (let slot = 0; slot < slots; slot += 1) {
+    const clock = clip.startMs + slot * clip.frameMs
+    while ((stamps[at + 1] ?? Infinity) <= clock) at += 1
+    filled.push(at)
+  }
+  return filled
+}