@erclx/canon 5.67.0 → 5.69.0

package/src/pr/evidence.ts

@@ -1,3 +1,5 @@
+import { isPainted, type PaintedPatterns } from '@/pr/painted'
+
 /** The path segment that marks an image as evidence a pull request should compare. */
 const EVIDENCE_SEGMENT = 'evidence'
 
@@ -16,9 +18,22 @@ const PREVIEW_PREFIX = '**Preview:**'
 /** How the address line names the branch's server on the operator's own machine, after any hosted segment. */
 const LOCAL_PREFIX = '**Local preview:**'
 
+/** How the reel line under the addresses opens. */
+const REEL_PREFIX = '**Reel** filmed at'
+
+/** The reel line as `renderEvidenceBody` writes it, read back for the link and the head label. */
+const REEL_LINE =
+  /^\*\*Reel\*\* filmed at `([0-9a-f]{7,40})`:<br><img src="([^"]+)"/
+
+/** The width a reel is filmed at, which it asks for in the comment. */
+const REEL_WIDTH = 960
+
 /** What joins the hosted and local segments on the one address line. */
 const ADDRESS_SEPARATOR = ' · '
 
+/** The summary of the block holding every case whose pixels matched its base. */
+const FOLDED_SUMMARY = 'Within tolerance'
+
 /** The heading every body opens with. */
 const EVIDENCE_HEADING = '## Evidence'
 
@@ -61,6 +76,8 @@ export interface EvidenceItem {
   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
 }
 
 export interface EvidenceState {
@@ -144,9 +161,9 @@ function rawUrl(repo: string, sha: string, path: string): string {
 }
 
 /**
- * The most pixels a screenshot asks for. GitHub sizes a comment table to its
- * content and clamps an image to its cell, so a width past any comment fills
- * the cell, where `width="100%"` leaves a narrow screenshot narrow. An image
+ * The most pixels a screenshot asks for. GitHub clamps an image to the comment
+ * column, so a width past any comment fills the column, where `width="100%"`
+ * would stretch a narrow screenshot to fill it too. An image
  * asks for the smaller of its own width and this ceiling, so a small crop
  * shows at its true size and is never scaled up. An image whose width was not
  * read asks for the ceiling.
@@ -171,7 +188,7 @@ export function readPngWidth(bytes: Uint8Array): number | undefined {
   return width > 0 ? width : undefined
 }
 
-/** A table cell and an attribute value share one escape, since a stem is a path segment placed in both. */
+/** A label and an attribute value share one escape, since a stem is a path segment placed in both. The pipe stays escaped, since a label once sat in a table cell. */
 function escapeCell(text: string): string {
   return text
     .replaceAll('&', '&amp;')
@@ -238,14 +255,21 @@ function commitLink(repo: string, sha: string): string {
   return `[\`${sha.slice(0, SHORT_SHA_LENGTH)}\`](https://github.com/${repo}/commit/${sha})`
 }
 
-function baseImage(item: EvidenceItem, repo: string, base: string): string {
-  return item.added
-    ? '*(new)*'
-    : evidenceImage(
-        rawUrl(repo, base, item.path),
-        `${escapeCell(item.stem)} base`,
-        item.baseWidth,
-      )
+/** The base folded under its head, so a reviewer reads the new state first and opens the old one on a click. */
+function baseFold(item: EvidenceItem, repo: string, base: string): string[] {
+  return [
+    '<details>',
+    '<summary>Base</summary>',
+    '',
+    evidenceImage(
+      rawUrl(repo, base, item.path),
+      `${escapeCell(item.stem)} base`,
+      item.baseWidth,
+    ),
+    '',
+    '</details>',
+    '',
+  ]
 }
 
 function headImage(item: EvidenceItem, repo: string, head: string): string {
@@ -256,25 +280,45 @@ function headImage(item: EvidenceItem, repo: string, head: string): string {
   )
 }
 
+/**
+ * One case as a label line, its head image on a line of its own, and its base
+ * folded beneath. An added case has no base, so it shows its head alone, and
+ * its label carries the new mark only where the block also holds a base for
+ * the mark to set it apart from.
+ */
+function caseLines(
+  label: string,
+  item: EvidenceItem,
+  hasBase: boolean,
+  repo: string,
+  base: string,
+  head: string,
+): string[] {
+  const mark = item.added && hasBase ? ' *(new)*' : ''
+  return [
+    `**${label}**${mark}`,
+    '',
+    headImage(item, repo, head),
+    '',
+    ...(item.added ? [] : baseFold(item, repo, base)),
+  ]
+}
+
 function block(
   opener: string,
   summary: string,
-  header: readonly string[],
-  rows: readonly string[],
+  cases: readonly string[][],
 ): string {
   return [
     opener,
     `<summary>${summary}</summary>`,
     '',
-    `| ${header.join(' | ')} |`,
-    `| ${header.map(() => '---').join(' | ')} |`,
-    ...rows,
-    '',
+    ...cases.flat(),
     '</details>',
   ].join('\n')
 }
 
-/** One block for the cases of a state that did not name a view, one case per row. */
+/** One block for the cases of a state that did not name a view, each labeled by its name. */
 function renderFlat(
   label: string,
   items: readonly EvidenceItem[],
@@ -284,22 +328,13 @@ function renderFlat(
   opener: string,
 ): string {
   const hasBase = items.some((item) => !item.added)
-  const rows = items.map((item) => {
-    const stem = escapeCell(item.stem)
-    const after = headImage(item, repo, head)
-    return hasBase
-      ? `| ${stem} | ${baseImage(item, repo, base)} | ${after} |`
-      : `| ${stem} | ${after} |`
-  })
-  return block(
-    opener,
-    `${label} (${items.length})`,
-    hasBase ? ['Case', 'Base', 'Head'] : ['Case', 'Head'],
-    rows,
+  const cases = items.map((item) =>
+    caseLines(escapeCell(item.stem), item, hasBase, repo, base, head),
   )
+  return block(opener, `${label} (${items.length})`, cases)
 }
 
-/** One block for a view, a width per row and a theme per column, each theme taking a base column when the view already exists at the base. */
+/** One block for a view, its cases by width and then dark before light, each labeled by width and theme, so a theme missing at a width renders nothing. */
 function renderView(
   label: string,
   cases: readonly ViewCase[],
@@ -308,38 +343,29 @@ function renderView(
   head: string,
   opener: string,
 ): string {
-  const themes = THEMES.filter((theme) =>
-    cases.some((entry) => entry.theme === theme),
-  )
   const hasBase = cases.some((entry) => !entry.item.added)
-  const widths = [...new Set(cases.map((entry) => entry.width))].sort(
-    compareWidths,
+  const ordered = [...cases].sort(
+    (a, b) =>
+      compareWidths(a.width, b.width) ||
+      THEMES.indexOf(a.theme) - THEMES.indexOf(b.theme),
   )
-  const header = [
-    'Width',
-    ...themes.flatMap((theme) => {
-      const name = theme === 'dark' ? 'Dark' : 'Light'
-      return hasBase ? [`${name} base`, `${name} head`] : [name]
-    }),
-  ]
-  const rows = widths.map((width) => {
-    const cells = themes.flatMap((theme) => {
-      const found = cases.find(
-        (entry) => entry.theme === theme && entry.width === width,
-      )
-      if (found === undefined) return hasBase ? ['', ''] : ['']
-      const after = headImage(found.item, repo, head)
-      return hasBase ? [baseImage(found.item, repo, base), after] : [after]
-    })
-    return `| ${[width, ...cells].join(' | ')} |`
-  })
-  return block(opener, `${label} (${cases.length})`, header, rows)
+  const lines = ordered.map((entry) =>
+    caseLines(
+      `${entry.width} · ${entry.theme}`,
+      entry.item,
+      hasBase,
+      repo,
+      base,
+      head,
+    ),
+  )
+  return block(opener, `${label} (${cases.length})`, lines)
 }
 
 /**
  * Renders the blocks of one state: a block per view the case names split
  * into, then one flat block for the names that did not. Nothing is dropped,
- * so a state of unparsed names reads as the flat table it always was.
+ * so a state of unparsed names reads as one flat block.
  */
 function renderState(
   entry: EvidenceState,
@@ -387,18 +413,57 @@ function renderState(
   return blocks
 }
 
+/** A folded case's label, naming its state and view, since the block gathers cases from every state. */
+function foldedLabel(state: string, item: EvidenceItem): string {
+  const name = readCaseName(item.stem)
+  const caseLabel =
+    name === undefined
+      ? escapeCell(item.stem)
+      : `${escapeCell(name.view)} · ${name.width} · ${name.theme}`
+  return state === '' ? caseLabel : `${escapeCell(state)} / ${caseLabel}`
+}
+
+/** One closed block for every case whose pixels matched its base, so the open blocks hold only what visibly moved. */
+function renderFolded(
+  states: readonly EvidenceState[],
+  repo: string,
+  base: string,
+  head: string,
+): string {
+  const cases = states.flatMap((entry) =>
+    entry.items.map((item) =>
+      caseLines(foldedLabel(entry.state, item), item, false, repo, base, head),
+    ),
+  )
+  return block('<details>', `${FOLDED_SUMMARY} (${cases.length})`, cases)
+}
+
+/** A reel embedded in the comment, and the head it was filmed at. */
+export interface EvidenceReel {
+  readonly link: string
+  readonly head: string
+}
+
+function reelLine(reel: EvidenceReel): string {
+  const head = reel.head.slice(0, SHORT_SHA_LENGTH)
+  return `${REEL_PREFIX} \`${head}\`:<br><img src="${escapeCell(reel.link)}" width="${REEL_WIDTH}" alt="reel filmed at ${head}">`
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
 
 /**
  * Renders the whole comment body: one `<details>` block per view within each
- * state, a width per row with a column per theme, a flat Base/Head table for
- * the case names that do not split into a view, and the trailing marker naming
- * the head this body describes.
+ * state, a flat block for the case names that do not split into a view, and
+ * the trailing marker naming the head this body describes. Each case shows its
+ * head at the comment's width with its base folded beneath, since a table
+ * split the column between the two and shrank both to a quarter of their size.
  * Every state opens while the comment carries at most `EVIDENCE_OPEN_LIMIT`
- * images, one per row for the head plus one per row not added, and every state
- * closes past it, so a comment is never half open. A visible line under
+ * head images, and every state closes past it, so a comment is never half
+ * open. A folded base takes no room until opened, so it is not counted. A case
+ * whose pixels matched its base moves to one closed `Within tolerance` block
+ * after the states, still named and embedded, and is not counted either. A visible line under
  * `## Evidence` names the base and head as short shas, each linking its commit. Every image URL is
  * pinned to a commit sha rather than a branch, so the comment keeps showing
  * what it claimed even after the branch moves.
@@ -412,6 +477,9 @@ export function evidenceMarker(head: string): string {
  *
  * A checklist closes the body, below the comparison it annotates, so one
  * comment carries the addresses, the screenshots, and what to look at.
+ *
+ * A reel sits on its own line under the addresses, labeled with the head it
+ * was filmed at, so a reel carried past a later push never reads as current.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -421,6 +489,7 @@ export function renderEvidenceBody(
   preview?: string,
   checklist?: string,
   local?: string,
+  reel?: EvidenceReel,
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -430,6 +499,7 @@ export function renderEvidenceBody(
     EVIDENCE_HEADING,
     '',
     ...(segments.length === 0 ? [] : [segments.join(ADDRESS_SEPARATOR), '']),
+    ...(reel === undefined ? [] : [reelLine(reel), '']),
   ]
   const closing =
     checklist === undefined
@@ -439,17 +509,21 @@ export function renderEvidenceBody(
     return [...opening, ...closing, evidenceMarker(head)].join('\n')
   }
 
-  const imageCount = states.reduce(
-    (total, entry) =>
-      total + entry.items.reduce((sum, item) => sum + (item.added ? 1 : 2), 0),
-    0,
-  )
+  const split = (keep: (item: EvidenceItem) => boolean): EvidenceState[] =>
+    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 headCount = open.reduce((total, entry) => total + entry.items.length, 0)
   const opener =
-    imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
+    headCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
 
-  const sections = states.flatMap((entry) =>
-    renderState(entry, repo, base, head, opener),
-  )
+  const sections = [
+    ...open.flatMap((entry) => renderState(entry, repo, base, head, opener)),
+    ...(folded.length === 0 ? [] : [renderFolded(folded, repo, base, head)]),
+  ]
 
   return [
     ...opening,
@@ -464,18 +538,18 @@ export function renderEvidenceBody(
 
 /**
  * How many cases a rendered body carries. Every case has exactly one head
- * image, so a row counts the head images it holds, which is one in the flat
- * table and up to two in a view's row. A row from before the alt text named
- * its head image counts as one case when it matches the old row shape, so a
- * comment posted before the change still counts its cases and the
- * `would-empty` guard holds.
+ * image, so the count is the head images on any line, whether a table row
+ * holding one or two or a line of its own. A table row from before the alt
+ * text named its head image counts as one case when it matches the old row
+ * shape, so a comment posted in any earlier layout still counts its cases and
+ * the `would-empty` guard holds.
  */
 export function countEvidenceCases(body: string): number {
   let total = 0
   for (const line of body.split('\n')) {
-    if (!line.startsWith('| ')) continue
     const heads = line.match(HEAD_IMAGE_PATTERN)?.length ?? 0
-    total += heads > 0 ? heads : LEGACY_ROW_PATTERN.test(line) ? 1 : 0
+    if (heads > 0) total += heads
+    else if (line.startsWith('| ') && LEGACY_ROW_PATTERN.test(line)) total += 1
   }
   return total
 }
@@ -529,6 +603,34 @@ export function readOwed(input: OwedInput): OwedStep[] {
   return owed
 }
 
+/**
+ * Design references are redrawn rather than captured, so recapturing them
+ * neither owes nor stands in for an evidence capture.
+ */
+const DESIGN_FOLDER = 'canon/design/'
+
+/**
+ * The painted paths a pull request changed while no evidence image did, in a
+ * project whose base keeps captures. Undefined when the base keeps none or
+ * was not read, since an empty list reads as checked and clean. Any changed
+ * evidence image clears the list, since this names a skipped capture rather
+ * than judging which views a capture covered.
+ */
+export function readUncaptured(
+  changed: readonly string[],
+  patterns: PaintedPatterns,
+  keepsCaptures: boolean | undefined,
+): string[] | undefined {
+  if (keepsCaptures !== true) return undefined
+  if (changed.some(isEvidencePath)) return []
+  return changed.filter(
+    (path) =>
+      evidencePosition(path) === -1 &&
+      !path.startsWith(DESIGN_FOLDER) &&
+      isPainted(path, patterns),
+  )
+}
+
 /**
  * The REST id of the comment this module already posted, read off its `url`
  * field, since `gh pr view --json comments` reports only a GraphQL id there
@@ -639,6 +741,34 @@ export function findEvidenceLocal(
   return marked === undefined ? undefined : readAddresses(marked.body).local
 }
 
+/** The reel the marked comment already embeds, with the head it was filmed at. */
+export function findEvidenceReel(
+  comments: readonly EvidenceComment[],
+): EvidenceReel | undefined {
+  const marked = findMarked(comments)
+  if (marked === undefined) return undefined
+  for (const line of marked.body.split('\n')) {
+    const match = REEL_LINE.exec(line.trim())
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      return { link: match[2].replaceAll('&amp;', '&'), head: match[1] }
+    }
+  }
+  return undefined
+}
+
+/**
+ * The reel a render embeds: a passed link, filmed at this head, replaces
+ * whatever the comment carries, and with none passed the posted reel carries
+ * forward under the head it was filmed at.
+ */
+export function nextEvidenceReel(
+  link: string | undefined,
+  head: string,
+  comments: readonly EvidenceComment[],
+): EvidenceReel | undefined {
+  return link === undefined ? findEvidenceReel(comments) : { link, head }
+}
+
 /**
  * The checklist the marked comment already carries, read back out of its
  * delimiters. The handoff file is deleted once posted, so every later render

package/src/pr/frames.ts

@@ -9,6 +9,16 @@ export const LEGACY_FRAMES_BRANCH = 'canon-frames'
 /** The eight bytes every PNG opens with. A frame that lacks them embeds as a broken image. */
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
 
+/** A WebP opens on `RIFF`, four bytes of size, then `WEBP`. */
+const RIFF = [0x52, 0x49, 0x46, 0x46]
+const WEBP = [0x57, 0x45, 0x42, 0x50]
+
+/**
+ * The largest reel an add takes, GitHub's cap on an image in a comment, so a
+ * reel that would not render is refused before it reaches the branch.
+ */
+export const REEL_MAX_BYTES = 10_000_000
+
 const SHORT_HEAD_LENGTH = 7
 
 const HEAD_PATTERN = /^[0-9a-f]{7,40}$/
@@ -86,9 +96,16 @@ export interface FrameInput {
   readonly box?: number
   readonly reference?: string
   readonly theme?: FrameTheme
+  /** The pass's reel, in place of a box or a reference. */
+  readonly reel?: boolean
   readonly bytes: Uint8Array
 }
 
+export type ReelRead =
+  | { readonly kind: 'read'; readonly bytes: Uint8Array }
+  | { readonly kind: 'unreadable' }
+  | { readonly kind: 'too-large'; readonly size: number }
+
 export type PushResult =
   | {
       readonly kind: 'pushed'
@@ -206,6 +223,25 @@ export function referencePath(
   return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/ref-${slug}.png`
 }
 
+/** Where a pass's reel lands, one per pass beside its box frames. */
+export function reelPath(number: number, head: string, pass: string): string {
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/reel.webp`
+}
+
+/** The reel's bytes, refusing a file that is absent, not a WebP, or past the cap. */
+export async function readReel(path: string): Promise<ReelRead> {
+  const bytes = await readFile(path).catch(() => undefined)
+  if (bytes === undefined || bytes.length <= 12) return { kind: 'unreadable' }
+  const webp =
+    RIFF.every((byte, index) => bytes[index] === byte) &&
+    WEBP.every((byte, index) => bytes[index + 8] === byte)
+  if (!webp) return { kind: 'unreadable' }
+  if (bytes.length > REEL_MAX_BYTES) {
+    return { kind: 'too-large', size: bytes.length }
+  }
+  return { kind: 'read', bytes: new Uint8Array(bytes) }
+}
+
 /** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
 export async function readFrame(path: string): Promise<Uint8Array | undefined> {
   const bytes = await readFile(path).catch(() => undefined)
@@ -227,8 +263,9 @@ export async function pushFrame(
   api: FramesApi,
   input: FrameInput,
 ): Promise<PushResult> {
-  const path =
-    input.reference === undefined
+  const path = input.reel
+    ? reelPath(input.number, input.head, input.pass)
+    : input.reference === undefined
       ? framePath(
           input.number,
           input.head,
@@ -241,8 +278,9 @@ export async function pushFrame(
   const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
   if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
   const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
-  const message =
-    input.reference === undefined
+  const message = input.reel
+    ? `chore(frames): add reel of #${input.number}`
+    : input.reference === undefined
       ? `chore(frames): add box ${input.box} of #${input.number}`
       : `chore(frames): add reference ${input.reference} of #${input.number}`
 

package/src/pr/pixels.ts

@@ -0,0 +1,44 @@
+import pixelmatch from 'pixelmatch'
+import { PNG } from 'pngjs'
+
+/** How different two colors must be for a pixel to count, where 1 is black against white. Playwright's 0.2 passed a real contrast fix. */
+const COLOR_THRESHOLD = 0.1
+
+/** The side of the square the count is taken over, so noise scattered across the image never adds up while a compact change does. */
+const WINDOW_SIZE = 16
+
+/** The most differing pixels any window may hold and still read as noise. Measured on Frameboard, noise counted 2 or fewer and real changes 14 or more. */
+const MAX_WINDOW_PIXELS = 6
+
+function decode(bytes: Uint8Array): PNG | undefined {
+  try {
+    return PNG.sync.read(Buffer.from(bytes))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether two PNG captures differ by no more than sub-visual noise. Anti-aliased
+ * pixels are counted rather than skipped, since antialias detection reads a
+ * changed 1px border as an edge artifact, and the windowed count separates
+ * scattered edge noise from a compact change on its own. A pair that does not decode or differs in size reads as changed, so
+ * nothing the comparison cannot read is ever folded.
+ */
+export function isWithinTolerance(base: Uint8Array, head: Uint8Array): boolean {
+  const before = decode(base)
+  const after = decode(head)
+  if (before === undefined || after === undefined) return false
+  if (before.width !== after.width || before.height !== after.height) {
+    return false
+  }
+  const count = pixelmatch(
+    before.data,
+    after.data,
+    null,
+    before.width,
+    before.height,
+    { threshold: COLOR_THRESHOLD, includeAA: true, windowSize: WINDOW_SIZE },
+  )
+  return count <= MAX_WINDOW_PIXELS
+}

package/src/records/backup.ts

@@ -104,6 +104,17 @@ export const EXCLUDED_ENTRIES = [
   RECORDS_GIT_NAME,
 ] as const
 
+/** Media under a video workspace, remade from its plan and composition, so never backed up. */
+export const MEDIA_PATHSPECS = [
+  ':(exclude,glob)video/*/takes/**',
+  ':(exclude,glob)video/**/renders/**',
+  ':(exclude,glob)video/**/snapshots/**',
+  ':(exclude,glob)video/**/node_modules/**',
+  ':(exclude,glob,icase)video/**/*.mp4',
+  ':(exclude,glob,icase)video/**/*.webm',
+  ':(exclude,glob,icase)video/**/*.mov',
+] as const
+
 /**
  * Whether a top-level name stays out of every push, at either root.
  *
@@ -598,8 +609,8 @@ async function pendingFiles(
   if (scope.length === 0) return { added: [], pending: [] }
 
   const [others, modified] = await Promise.all([
-    records(root, ['ls-files', '-z', '-o', '--', ...scope]),
-    records(root, ['ls-files', '-z', '-m', '--', ...scope]),
+    records(root, ['ls-files', '-z', '-o', '--', ...scope, ...MEDIA_PATHSPECS]),
+    records(root, ['ls-files', '-z', '-m', '--', ...scope, ...MEDIA_PATHSPECS]),
   ])
   if (!others.ok) return failed('ls-files', others)
   if (!modified.ok) return failed('ls-files', modified)
@@ -699,7 +710,14 @@ export async function pushRecords(root: string): Promise<PushOutcome> {
     // enclosing repository, and the pathspecs are the whole list, so nothing
     // outside them can enter the index however the ignore rules read. An
     // excluded name never reaches the list, whatever the records index holds.
-    const staged = await records(root, ['add', '-A', '-f', '--', ...scope])
+    const staged = await records(root, [
+      'add',
+      '-A',
+      '-f',
+      '--',
+      ...scope,
+      ...MEDIA_PATHSPECS,
+    ])
     if (!staged.ok) return failed('add', staged)
   }
 
@@ -837,7 +855,13 @@ export async function pullRecords(root: string): Promise<PullOutcome> {
   const { scope } = await scopedFolders(root)
 
   if (scope.length > 0) {
-    const dirty = await records(root, ['status', '--porcelain', '--', ...scope])
+    const dirty = await records(root, [
+      'status',
+      '--porcelain',
+      '--',
+      ...scope,
+      ...MEDIA_PATHSPECS,
+    ])
     if (!dirty.ok) return failed('status', dirty)
 
     if (dirty.text.length > 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',

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" "$@"