@erclx/canon 5.68.0 → 5.70.0

package/src/records/validate.ts

@@ -250,6 +250,7 @@ const PLAN_SECTIONS = [
   'Constraints',
   'Files to touch',
   'Design references',
+  'Reference images',
   'Verification',
   'Risks',
   'Review focus',
@@ -806,6 +807,13 @@ const STRUCTURE_FILES: Readonly<
   intake: (file) => file !== INTAKE_INDEX && file !== INTAKE_HANDOFF,
 }
 
+/**
+ * An app drive's log, which sits under an intake folder's `evidence/` and
+ * holds findings as headings and fields rather than items, so it reads on the
+ * plain criteria rather than the cluster exemptions.
+ */
+const DRIVE_LOG = 'evidence/drive-log.md'
+
 async function folderStructure(
   dir: string,
   kind: RecordKind,
@@ -816,9 +824,14 @@ async function folderStructure(
 
   const report = kind === 'intake' ? intakeStructure : structureFindings
   const files = (await listMarkdown(dir)).filter(reads)
+  const reports = files.map((file) => ({ file, read: report }))
+  if (kind === 'intake' && existsSync(join(dir, DRIVE_LOG))) {
+    reports.push({ file: DRIVE_LOG, read: structureFindings })
+  }
+
   const perFile = await Promise.all(
-    files.map(async (file) =>
-      report(await readFile(join(dir, file), 'utf8')).map((entry) => ({
+    reports.map(async ({ file, read }) =>
+      read(await readFile(join(dir, file), 'utf8')).map((entry) => ({
         ...entry,
         record: slug,
         subject: file,

package/src/sandbox/expect.ts

@@ -44,7 +44,15 @@ export interface AssertionResult {
  */
 export interface RunEnvelope {
   readonly isError: boolean
+  /** The runner cap ended the run, read from `subtype` rather than `turns`. */
+  readonly isTruncated: boolean
   readonly turns: number
+  /**
+   * The cap the run ran under. `num_turns` counts more than the cap does, so
+   * an untruncated run can report past it, and a ceiling at or above the cap
+   * is held by `isTruncated` instead. A non-finite value reads as absent.
+   */
+  readonly turnCap?: number
   readonly denials: number
   readonly reply?: string
 }
@@ -487,6 +495,23 @@ function checkReply(
   }
 }
 
+function isFiniteCap(turnCap: number | undefined): turnCap is number {
+  return turnCap !== undefined && Number.isFinite(turnCap)
+}
+
+function capped(turnCap: number | undefined): string {
+  return isFiniteCap(turnCap) ? ` of ${turnCap} turns` : ''
+}
+
+/**
+ * A ceiling below the cap was declared in `num_turns` and is compared in it. One
+ * at or above the cap skips with no result, since emitting a pass would let the
+ * envelope pass a run.
+ */
+function isBelowCap(maxTurns: number, turnCap: number | undefined): boolean {
+  return !isFiniteCap(turnCap) || maxTurns < turnCap
+}
+
 /**
  * The envelope never determines a pass. It can only fail a run the expectations
  * would otherwise have passed. Under `bypassPermissions` the denial count is
@@ -516,8 +541,15 @@ function checkEnvelope(
       message: `envelope: ${envelope.denials} permission denials`,
     })
   }
+  if (envelope.isTruncated) {
+    results.push({
+      ok: false,
+      message: `envelope: truncated by the runner cap${capped(envelope.turnCap)}`,
+    })
+  }
   if (
     expectation.maxTurns !== undefined &&
+    isBelowCap(expectation.maxTurns, envelope.turnCap) &&
     envelope.turns > expectation.maxTurns
   ) {
     results.push({

package/src/sandbox/headless/dispatch-shim.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Run by the claude wrapper installDispatchShim writes in src/sandbox/headless/dispatch.ts.
+# $1 is the real claude binary, and everything after it is the caller's arguments.
+real="$1"
+shift
+
+for arg in "$@"; do
+  case "$arg" in
+  --bg | --background)
+    echo "canon sandbox harness: refusing $arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2
+    exit 64
+    ;;
+  esac
+done
+exec "$real" "$@"

package/src/sandbox/headless/dispatch.ts

@@ -8,6 +8,11 @@ import {
 } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const DISPATCH_SHIM = fileURLToPath(
+  new URL('dispatch-shim.sh', import.meta.url),
+)
 
 /*
  * The bound on a nested background dispatch, and the recording behind it.
@@ -31,9 +36,11 @@ import { join } from 'node:path'
  * The prevention. Writes a `claude` that refuses a background dispatch by flag
  * name and delegates everything else, for the runner to place first on the PATH
  * of the session it spawns. It stays a bash file, since it stands in for a
- * binary any shell in the session may exec.
+ * binary any shell in the session may exec. The refusal lives in
+ * `dispatch-shim.sh`, so the shell gate lints it, and the `claude` written here
+ * is a two-line wrapper that runs it with the real binary as its first argument.
  *
- * The real binary is baked into the file rather than passed through the
+ * The real binary is baked into the wrapper rather than passed through the
  * environment. An env var carrying it would sit in the spawned session's own
  * environment, which hands any arm the exact string that walks around the shim.
  *
@@ -46,22 +53,13 @@ import { join } from 'node:path'
  * backstops.
  */
 export function installDispatchShim(dir: string, real: string): void {
-  const shim = [
+  const wrapper = [
     '#!/usr/bin/env bash',
-    '# Generated by installDispatchShim in src/sandbox/headless/dispatch.ts.',
-    'for arg in "$@"; do',
-    '  case "$arg" in',
-    '  --bg | --background)',
-    '    echo "canon sandbox harness: refusing $arg. A sandbox run may not dispatch a background session, so this shim stands first on PATH in place of the real claude binary. Drive the refusal the fixture asks for, or run this outside the harness." >&2',
-    '    exit 64',
-    '    ;;',
-    '  esac',
-    'done',
-    `exec ${shellQuote(real)} "$@"`,
+    `exec bash ${shellQuote(DISPATCH_SHIM)} ${shellQuote(real)} "$@"`,
     '',
   ].join('\n')
 
-  writeFileSync(join(dir, 'claude'), shim, 'utf8')
+  writeFileSync(join(dir, 'claude'), wrapper, 'utf8')
   chmodSync(join(dir, 'claude'), 0o755)
 }
 

package/src/sandbox/headless/run.ts

@@ -45,9 +45,12 @@ import {
  *
  * `maxTurns` is the only budget. `max_turns` in an arm's `expect.toml` is a
  * ceiling asserted after the run, not a cap enforced during it, so a
- * declaration cannot raise what it runs under. An arm needing more than this
- * truncates, and a truncated run fails the same assertions a reasoning miss
- * does with nothing to separate them.
+ * declaration cannot raise what it runs under. A truncated run exits 1 with
+ * `subtype` `error_max_turns`, which `canon sandbox check` fails by name.
+ * `num_turns` counts more than this cap does, so a ceiling at or above it is
+ * held by the cap and compares nothing. The check reads the cap from its own
+ * environment, so a run under a raised cap, checked later by hand without the
+ * variable, reads the default.
  *
  * `bypassPermissions` is the only mode that lets a run write under `.claude/`,
  * which most arms need. The scoping the permission layer would have given

package/src/sandbox/stub-gh.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# stub gh
+dir="$STUB_GH_DIR"
+line="$(printf '%q ' "$@")"
+line="${line% }"
+printf '%s\n' "$line" >>"$dir/gh.log"
+
+case "$1" in
+api) exit 0 ;;
+pr)
+  case "$2" in
+  create)
+    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
+    count=$((count + 1))
+    echo "$count" >"$dir/pr-count"
+    echo "https://github.com/$GITHUB_ORG/$STUB_GH_REPO/pull/$count"
+    exit 0
+    ;;
+  close | list) exit 0 ;;
+  esac
+  ;;
+esac
+
+printf '%s\n' "$line" >>"$dir/gh-unknown.log"
+echo "stub gh: unknown call: $line" >&2
+exit 1

package/src/sandbox/stub-remote.ts

@@ -1,14 +1,15 @@
 import { execFileSync } from 'node:child_process'
 import {
   chmodSync,
+  copyFileSync,
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   rmSync,
-  writeFileSync,
 } from 'node:fs'
 import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 const STUB_ORG = 'stub-org'
 const ANCHOR_REPO = 'canon-sandbox'
@@ -26,34 +27,11 @@ const PINNED_DATE = '2026-01-01T00:00:00Z'
  * Answers the `gh` calls the git scenarios make and fails on any other, so a new
  * call reaches a reader as a red arm rather than a silent pass. Every call is
  * logged as one line, quoted so an argument holding a space stays one argument.
+ * The pull request URL it prints reads `GITHUB_ORG` and `STUB_GH_REPO` from the
+ * environment `createStubRemote` returns, so it follows `STUB_ORG` and
+ * `ANCHOR_REPO`.
  */
-const STUB_GH = `#!/usr/bin/env bash
-# stub gh
-dir="$STUB_GH_DIR"
-line="$(printf '%q ' "$@")"
-line="\${line% }"
-printf '%s\\n' "$line" >>"$dir/gh.log"
-
-case "$1" in
-api) exit 0 ;;
-pr)
-  case "$2" in
-  create)
-    count="$(cat "$dir/pr-count" 2>/dev/null || echo 0)"
-    count=$((count + 1))
-    echo "$count" >"$dir/pr-count"
-    echo "https://github.com/${STUB_ORG}/${ANCHOR_REPO}/pull/$count"
-    exit 0
-    ;;
-  close | list) exit 0 ;;
-  esac
-  ;;
-esac
-
-printf '%s\\n' "$line" >>"$dir/gh-unknown.log"
-echo "stub gh: unknown call: $line" >&2
-exit 1
-`
+const STUB_GH = fileURLToPath(new URL('stub-gh.sh', import.meta.url))
 
 /**
  * Builds a local bare repository and a stub `gh` under `stubDir` and returns the
@@ -75,13 +53,14 @@ export function createStubRemote(stubDir: string): Record<string, string> {
   )
 
   const gh = join(bin, 'gh')
-  writeFileSync(gh, STUB_GH)
+  copyFileSync(STUB_GH, gh)
   chmodSync(gh, 0o755)
 
   return {
     PATH: `${bin}:${process.env.PATH ?? ''}`,
     STUB_GH_DIR: stubDir,
     GITHUB_ORG: STUB_ORG,
+    STUB_GH_REPO: ANCHOR_REPO,
     GIT_CONFIG_COUNT: '1',
     GIT_CONFIG_KEY_0: `url.${remotes}/.insteadOf`,
     GIT_CONFIG_VALUE_0: `https://github.com/${STUB_ORG}/`,

package/src/sync/engine.ts

@@ -545,7 +545,7 @@ function reportCoverage(coverage: readonly RuleCoverage[]): void {
   for (const entry of coverage) {
     logInfo(describeCoverage(entry))
     if (entry.ui) {
-      logInfo('  Audit those files with /canon:ux-audit.')
+      logInfo('  Audit those files with /canon:ui-audit.')
     }
   }
 }

package/src/take/camera.ts

@@ -1,5 +1,6 @@
 import {
   type Box,
+  CLIP_SIZES,
   type LogEvent,
   type Point,
   type TakeLog,
@@ -20,8 +21,8 @@ import {
 
 /**
  * Turns a take's log into one camera per frame, preset O4 from groundwork
- * track `193-ui-record`: OpenScreen's timing aimed at each click, a fixed
- * depth, a focus that holds still until a click leaves the inner part of the
+ * track `193-ui-record`, a folder name kept as written (canon-keep-retired).
+ * The preset is OpenScreen's timing aimed at each click, a fixed depth the clip's resolution caps, a focus that holds still until a click leaves the inner part of the
  * view, and a dead zone that keeps the cursor in frame. HyperFrames renders the
  * track as it stands, so it carries no curve a renderer would have to agree on.
  */
@@ -31,6 +32,13 @@ export const CAMERA_VERSION = 1
 /** The depth every click zooms to, unless its target already fills the view. */
 const DEPTH = 1.8
 
+/**
+ * How far a clip with one pixel per CSS pixel zooms before it goes soft, which
+ * caps a screencast's depth well under `DEPTH` and leaves the stepper's 4K
+ * clip at it.
+ */
+const SHARP_DEPTH = 1.35
+
 /** How much of the zoomed view a target may fill, which caps the depth for a big one. */
 const FILL = 0.8
 
@@ -57,6 +65,13 @@ const EDGE = 0.9
 /** How long the click ring the edit draws takes to expand. */
 const RING_MS = 450
 
+/**
+ * How far a drag's ring grows before it holds for the drag, then runs on to 1
+ * from the release. A held value keeps the ring's one field, so every reader
+ * drawing a growing ring draws a held press with no change.
+ */
+const GRAB_RING = 0.3
+
 export interface CameraFrame {
   readonly ms: number
   /** How far the view is zoomed, 1 being the whole page. */
@@ -91,16 +106,30 @@ interface Window {
   readonly aims: Aim[]
 }
 
-export function cameraTrack(log: TakeLog): CameraTrack {
+export interface CameraOptions {
+  /**
+   * How much faster the edit plays the clip, so the track is built on the
+   * playback clock and a zoom settles at the speed a viewer sees. 1 by default.
+   */
+  readonly rate?: number
+}
+
+export function cameraTrack(
+  source: TakeLog,
+  options: CameraOptions = {},
+): CameraTrack {
+  const log = atRate(source, options.rate ?? 1)
   const { width, height } = log.viewport
+  const clip = log.clip ?? CLIP_SIZES[log.route]
+  const deepest = Math.min(DEPTH, (SHARP_DEPTH * clip.width) / width)
   const depthFor = (box: Box): number =>
     Math.min(
-      DEPTH,
+      deepest,
       (width * FILL) / Math.max(box.width, 1),
       (height * FILL) / Math.max(box.height, 1),
     )
 
-  const aims: Aim[] = log.events
+  const aims: Aim[] = (log.push === false ? [] : log.events)
     .flatMap((event): Aim[] => {
       if (event.kind === 'click') {
         return [
@@ -112,6 +141,19 @@ export function cameraTrack(log: TakeLog): CameraTrack {
           },
         ]
       }
+      if (event.kind === 'drag') {
+        // One aim over both ends, held to the release, so a short drag stays
+        // framed whole and a long one asks for a depth under MIN_ZOOM.
+        const box = union(event.box, event.drop)
+        return [
+          {
+            t: event.t,
+            until: event.t + event.ms,
+            at: { x: box.x + box.width / 2, y: box.y + box.height / 2 },
+            depth: depthFor(box),
+          },
+        ]
+      }
       if (event.kind === 'type') {
         const box = event.box
         return [
@@ -129,9 +171,26 @@ export function cameraTrack(log: TakeLog): CameraTrack {
     .sort((a, b) => a.t - b.t)
 
   const scrolls = log.events.filter((event) => event.kind === 'scroll')
-  // Read off every click rather than off the aims, which drop a click too large
+  // Read off every press rather than off the aims, which drop a click too large
   // to zoom and add a typing burst that is no press.
-  const clicks = log.events.filter((event) => event.kind === 'click')
+  const presses = log.events.flatMap((event) =>
+    event.kind === 'click'
+      ? [{ t: event.t, release: event.t }]
+      : event.kind === 'drag'
+        ? [{ t: event.t, release: event.t + event.ms }]
+        : [],
+  )
+  const ringAt = (ms: number): number | null => {
+    for (const press of presses) {
+      if (ms < press.t) continue
+      const grown = (ms - press.t) / RING_MS
+      if (ms <= press.release) return Math.min(GRAB_RING, grown)
+      const held = Math.min(GRAB_RING, (press.release - press.t) / RING_MS)
+      const ring = held + (ms - press.release) / RING_MS
+      if (ring <= 1) return ring
+    }
+    return null
+  }
   const windows = zoomWindows(aims, scrolls)
 
   const targetAt = (ms: number) => {
@@ -196,16 +255,14 @@ export function cameraTrack(log: TakeLog): CameraTrack {
       cursor.y + half.y * EDGE,
     )
 
-    const ring = clicks.find(
-      (click) => ms >= click.t && ms - click.t <= RING_MS,
-    )
+    const ring = ringAt(ms)
     frames.push({
       ms: round(ms, 2),
       scale: round(scale, 4),
       x: round(clamp(springs.x.value, half.x, width - half.x) - half.x, 2),
       y: round(clamp(springs.y.value, half.y, height - half.y) - half.y, 2),
       cursor: roundPoint(cursor),
-      ring: ring ? round((ms - ring.t) / RING_MS, 3) : null,
+      ring: ring === null ? null : round(ring, 3),
     })
   }
 
@@ -217,6 +274,27 @@ export function cameraTrack(log: TakeLog): CameraTrack {
   }
 }
 
+/** Reads a playback rate off a flag, which has to be a positive number. */
+export function readRate(value: string): number | undefined {
+  const rate = Number(value)
+  return Number.isFinite(rate) && rate > 0 ? rate : undefined
+}
+
+/** The log as a clip played `rate` times faster shows it, every time divided. */
+function atRate(log: TakeLog, rate: number): TakeLog {
+  if (rate === 1) return log
+  return {
+    ...log,
+    frames: Math.round(log.frames / rate),
+    events: log.events.map((event): LogEvent => {
+      const t = event.t / rate
+      return 'ms' in event
+        ? { ...event, t, ms: event.ms / rate }
+        : { ...event, t }
+    }),
+  }
+}
+
 /**
  * Groups aims into zooms. One holds from its first aim to the last plus the
  * hold, a scroll ends it since the content moves under the camera, and the next
@@ -295,6 +373,17 @@ function focusAt(
   return focus
 }
 
+function union(a: Box, b: Box): Box {
+  const x = Math.min(a.x, b.x)
+  const y = Math.min(a.y, b.y)
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  }
+}
+
 function clamp(value: number, low: number, high: number): number {
   return Math.min(Math.max(value, low), high)
 }

package/src/take/film.ts

@@ -4,6 +4,7 @@ import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
 import { cameraTrack } from '@/take/camera'
 import { FfmpegMissing, requireFfmpeg } from '@/take/encode'
 import {
+  CLIP_SIZES,
   FPS,
   LOG_VERSION,
   type LogEvent,
@@ -60,6 +61,10 @@ export type TakeResult =
       readonly reason: TakeRefusal
       readonly message: string
       readonly beat?: string
+      /** Why the refused beat had fallen back to a screencast, when it had. */
+      readonly fallback?: string
+      /** The page as the failing step met it, relative to the take's folder. */
+      readonly still?: string
     }
 
 export interface TakeRequest {
@@ -67,6 +72,8 @@ export interface TakeRequest {
   readonly plan: TakePlan
   readonly out: string
   readonly env?: NodeJS.ProcessEnv
+  /** How long one stepped frame may take before its beat falls back to a screencast. */
+  readonly stallMs?: number
 }
 
 const REACH_TIMEOUT_MS = 5000
@@ -108,9 +115,26 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
     const dir = `${String(index + 1).padStart(2, '0')}-${slug(beat.name)}`
     mkdirSync(join(out, dir), { recursive: true })
     try {
-      beats.push(await filmBeat(request.url, beat, out, dir, executable))
+      beats.push(
+        await filmBeat(
+          request.url,
+          beat,
+          out,
+          dir,
+          executable,
+          request.stallMs,
+        ),
+      )
     } catch (error) {
-      return failed(classify(error), error, beat.name)
+      const cause = error instanceof FellBack ? error.error : error
+      const shot = cause instanceof TargetMissing ? cause.still : undefined
+      const still = shot ? join(dir, 'still.jpg') : undefined
+      if (shot && still) writeFileSync(join(out, still), shot)
+      return {
+        ...failed(classify(cause), cause, beat.name),
+        ...(error instanceof FellBack ? { fallback: error.fallback } : {}),
+        ...(still ? { still } : {}),
+      }
     }
   }
 
@@ -127,6 +151,7 @@ async function filmBeat(
   out: string,
   dir: string,
   executable: string,
+  stallMs: number | undefined,
 ): Promise<FilmedBeat> {
   const clip = join(dir, 'clip.mp4')
   const target = join(out, clip)
@@ -136,12 +161,22 @@ async function filmBeat(
   let filmed: { frames: number; events: readonly LogEvent[]; still: Buffer }
   if (beat.route === 'step') {
     try {
-      filmed = await filmStepped({ executable, url, beat, clip: target })
+      filmed = await filmStepped({
+        executable,
+        url,
+        beat,
+        clip: target,
+        stallMs,
+      })
     } catch (error) {
       if (!(error instanceof StepperStalled)) throw error
       route = 'screencast'
       fallback = error.message
-      filmed = await filmScreencast({ url, beat, clip: target })
+      try {
+        filmed = await filmScreencast({ url, beat, clip: target })
+      } catch (cause) {
+        throw new FellBack(cause, fallback)
+      }
     }
   } else {
     filmed = await filmScreencast({ url, beat, clip: target })
@@ -152,6 +187,8 @@ async function filmBeat(
     viewport: VIEWPORT,
     fps: FPS,
     route,
+    clip: CLIP_SIZES[route],
+    ...(beat.push === false ? { push: false as const } : {}),
     frames: filmed.frames,
     events: filmed.events,
   }
@@ -178,6 +215,20 @@ async function filmBeat(
   }
 }
 
+/**
+ * A beat that failed in the screencast it fell back to, carrying why it fell
+ * back, since the fallback loads the page a second time and a single-use link
+ * is spent by then.
+ */
+class FellBack extends Error {
+  constructor(
+    readonly error: unknown,
+    readonly fallback: string,
+  ) {
+    super(error instanceof Error ? error.message : String(error))
+  }
+}
+
 function classify(error: unknown): TakeRefusal {
   if (error instanceof TargetMissing) return 'target-missing'
   if (error instanceof ShellMissing || isBrowserMissing(error)) {