@erclx/canon 5.78.0 → 5.80.0

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
+}

package/src/take/perform.ts

@@ -472,6 +472,12 @@ async function scrollPoint(stage: Stage, target: string): Promise<Point> {
  * innermost element with a size whose whole text is those words, so a hidden
  * copy earlier in the page cannot shadow a visible one, and anything else as a
  * CSS selector.
+ * The document is searched first and every open shadow root after it in tree
+ * order, so a document-tree match wins, except that innermost reads containment
+ * through a shadow root to its host and a `text=` match holding a sized match
+ * inside its subtree's roots gives way to it. A selector matches within one
+ * root and never across a shadow boundary. A closed root and a frame stay
+ * unreachable.
  * It runs inside the page so both routes resolve a target the same way, and a
  * match with no size counts as missing, since a click on it would land on
  * whatever sits behind.
@@ -479,19 +485,38 @@ async function scrollPoint(stage: Stage, target: string): Promise<Point> {
 export function boxExpression(target: string): string {
   return `(() => {
     const target = ${JSON.stringify(target)}
+    const roots = []
+    const collect = (root) => {
+      roots.push(root)
+      for (const node of root.querySelectorAll('*')) {
+        if (node.shadowRoot) collect(node.shadowRoot)
+      }
+    }
+    collect(document)
+    const within = (outer, inner) => {
+      for (let node = inner; node; node = node.parentNode ?? node.host ?? null) {
+        if (node === outer) return true
+      }
+      return false
+    }
     let element = null
     if (target.startsWith('text=')) {
       const want = target.slice(5).trim()
-      const matches = [...document.querySelectorAll('body *')].filter(
-        (node) => node.textContent.trim() === want,
+      const matches = roots.flatMap((root) =>
+        [...root.querySelectorAll(root === document ? 'body *' : '*')].filter(
+          (node) => node.textContent.trim() === want,
+        ),
       )
-      const innermost = matches.filter((node) => !matches.some((other) => other !== node && node.contains(other)))
+      const innermost = matches.filter((node) => !matches.some((other) => other !== node && within(node, other)))
       element = innermost.find((node) => {
         const rect = node.getBoundingClientRect()
         return rect.width > 0 && rect.height > 0
       }) ?? null
     } else {
-      element = document.querySelector(target)
+      for (const root of roots) {
+        element = root.querySelector(target)
+        if (element) break
+      }
     }
     if (!element) return null
     const rect = element.getBoundingClientRect()

package/src/take/screencast.ts

@@ -1,8 +1,8 @@
-import { mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { chromium } from 'playwright-core'
-import { lastFrame, probeFrames, transcode } from '@/take/encode'
+import { lastFrame, openFrameEncoder, probeFrames } from '@/take/encode'
+import { frameStamp, slotFrames } from '@/take/frame-clock'
 import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
@@ -51,8 +51,13 @@ export async function filmScreencast(request: {
   readonly beat: Beat
   readonly clip: string
 }): Promise<ScreencastTake> {
-  const scratch = mkdtempSync(join(tmpdir(), 'canon-take-cast-'))
-  const browser = await chromium.launch()
+  // Ahead of the launch, so a folder that refuses leaves no browser holding the
+  // process open past its refusal.
+  const scratch = openSpool(request.clip)
+  const browser = await chromium.launch().catch((error: unknown) => {
+    scratch.remove()
+    throw error
+  })
   let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     const page = await browser.newPage({ viewport: VIEWPORT })
@@ -97,9 +102,33 @@ export async function filmScreencast(request: {
     if (request.beat.setup.length > 0) await live.hold(1000)
     const lag = await calibrate(page)
 
-    const webm = join(scratch, 'take.webm')
     const events: LogEvent[] = []
-    await page.screencast.start({ path: webm, size: VIEWPORT, fps: FPS })
+    const spool: SpooledFrame[] = []
+    let spoolFailure: unknown
+    await page.screencast.start({
+      size: VIEWPORT,
+      // The docs tie this to `path`, but 1.64.1 still reads it here, where it
+      // doubles the frames Chromium may hold unacknowledged.
+      fps: FPS,
+      // Spooled rather than held, since a busy page sends about 19 MB a second.
+      // The write stays synchronous, so the acknowledgement Chromium paces its
+      // frames on waits for no encoder. Playwright calls this from a listener
+      // nothing awaits, so a throw here would surface as an unhandled rejection.
+      onFrame: ({ data, timestamp }) => {
+        const stamp = frameStamp({
+          presentedWall: timestamp,
+          wallNow: Date.now(),
+          monoNow: performance.now(),
+        })
+        const path = join(scratch.folder, `${spool.length}.jpg`)
+        try {
+          writeFileSync(path, data)
+          spool.push({ path, stamp })
+        } catch (error) {
+          spoolFailure ??= error
+        }
+      },
+    })
     const started = performance.now()
     const recording = stageOn(() => performance.now() - started)
     await recording.hold(HOLD_MS)
@@ -110,8 +139,9 @@ export async function filmScreencast(request: {
     await recording.hold(HOLD_MS)
     const filmedMs = recording.now()
     await page.screencast.stop()
+    if (spoolFailure !== undefined) throw spoolFailure
 
-    await transcode(webm, request.clip, FPS, filmedMs)
+    await encodeSpool(spool, request.clip, started, filmedMs)
     const frames = await probeFrames(request.clip)
     const closing = await lastFrame(request.clip, frames)
     if (lag === undefined) return { frames, events, still: closing }
@@ -126,13 +156,86 @@ export async function filmScreencast(request: {
     throw error
   } finally {
     await browser.close()
-    rmSync(scratch, { recursive: true, force: true })
+    scratch.remove()
   }
 }
 
 type Page = import('playwright-core').Page
 type Mouse = import('playwright-core').Mouse
 
+interface SpooledFrame {
+  readonly path: string
+  /** When the frame was presented, on the monotonic clock. */
+  readonly stamp: number
+}
+
+/**
+ * Opens the folder holding one take's frames, beside its clip rather than in a
+ * temp folder nothing sweeps, since a 34 s beat on a busy page spools about
+ * 650 MB. A take killed outright runs no handler, so it leaves the folder where
+ * its owner looks, and the next take of that beat clears it.
+ */
+function openSpool(clip: string): { folder: string; remove: () => void } {
+  const folder = join(dirname(clip), 'spool')
+  rmSync(folder, { recursive: true, force: true })
+  mkdirSync(folder, { recursive: true })
+  const remove = (): void => {
+    process.off('exit', remove)
+    process.off('SIGINT', interrupt)
+    process.off('SIGTERM', interrupt)
+    rmSync(folder, { recursive: true, force: true })
+  }
+  // A signal skips the exit event, so it removes the folder and then re-raises
+  // itself with this handler gone, ending the process as it would have.
+  const interrupt = (signal: NodeJS.Signals): void => {
+    remove()
+    process.kill(process.pid, signal)
+  }
+  process.on('exit', remove)
+  process.once('SIGINT', interrupt)
+  process.once('SIGTERM', interrupt)
+  return { folder, remove }
+}
+
+/**
+ * Writes the clip from the spool, one frame per slot of the stage clock, so its
+ * length is the take's rather than whatever the frames span. Refuses when no
+ * frame arrived, since there is nothing true to show.
+ */
+async function encodeSpool(
+  spool: readonly SpooledFrame[],
+  clip: string,
+  startMs: number,
+  lengthMs: number,
+): Promise<void> {
+  const slots = slotFrames(
+    spool.map((frame) => frame.stamp),
+    { startMs, lengthMs, frameMs: FRAME_MS },
+  )
+  if (slots.length === 0) {
+    throw new Error(
+      `the screencast delivered no frame in ${(lengthMs / 1000).toFixed(2)} s of filming`,
+    )
+  }
+  const encoder = openFrameEncoder(clip, FPS)
+  try {
+    let shown = -1
+    let jpeg = Buffer.alloc(0)
+    for (const index of slots) {
+      const frame = spool[index]
+      if (frame && index !== shown) {
+        jpeg = readFileSync(frame.path)
+        shown = index
+      }
+      await encoder.write(jpeg)
+    }
+    await encoder.close()
+  } catch (error) {
+    encoder.abort()
+    throw error
+  }
+}
+
 /**
  * The page time of its next animation frame, or undefined when none comes
  * within `capMs`, as on a hidden page, or the page closed first.
@@ -155,7 +258,7 @@ const PAINTED = '__canonTakePainted'
  * How long a move takes to show in the clip, measured by sending one aligned
  * move to `START` and reading the animation frame after its handler against
  * the frame it was aligned to. Both readings are page time, so no clock mapping
- * is needed. The recorder captures a frame once it is presented, one page
+ * is needed. The screencast captures a frame once it is presented, one page
  * frame after that frame begins, so the lag counts one page frame past the
  * readings, read off two consecutive animation frames rather than assumed from
  * the clip's rate. That held a dragged box within 7 px on every run where the