@erclx/canon 5.74.0 → 5.76.0

package/src/migrate/session-defaults.ts

@@ -1,7 +1,8 @@
 /**
  * Adds the session defaults the seeded `.claude/settings.json` carries to a
- * target that was seeded before them: the subagent deny, the memory default, and
- * the merge deny entries.
+ * target that was seeded before them: the subagent deny, the memory default,
+ * the merge deny entries, the lease push allow entries, and the plan guard's
+ * PreToolUse wiring where the project holds the guard script.
  *
  * `canon claude init` copies a seed only when the file is absent, so a target
  * holding its own settings never sees a later seed change. This verb adds each
@@ -28,6 +29,37 @@ export const MERGE_DENIED: readonly string[] = [
   'Bash(gh pr merge:*)',
 ]
 
+/**
+ * The two lease pushes a worker runs after rebasing onto a merged pull request,
+ * each pushing the current branch to its own name. An allow rule resolves
+ * before auto mode's classifier, so each entry is exact: a wildcard would also
+ * approve a refspec, a remote, or a flag that reaches the default branch.
+ */
+export const PUSH_ALLOWED: readonly string[] = [
+  'Bash(git push --force-with-lease)',
+  'Bash(git push --force-with-lease origin HEAD)',
+]
+
+/** The command the seed wires, as the seeded settings spell it. */
+export const PLAN_GUARD_COMMAND =
+  '"$CLAUDE_PROJECT_DIR"/.claude/hooks/plan-guard.sh'
+
+const PLAN_GUARD_SCRIPT = 'plan-guard.sh'
+
+/**
+ * Each tool the guard acts on, beside the seeded matcher that carries it. A
+ * guard wired by hand under any matcher covering the tool counts as wired.
+ */
+const PLAN_GUARD_WIRING: readonly { tool: string; matcher: string }[] = [
+  { tool: 'Bash', matcher: 'Bash' },
+  { tool: 'Write', matcher: 'Write|Edit' },
+]
+
+export interface SessionDefaultsOptions {
+  /** True when the project holds `.claude/hooks/plan-guard.sh` to wire. */
+  readonly planGuard?: boolean
+}
+
 export interface SessionDefaultsPlan {
   readonly keys: readonly SettingsKey[]
   readonly next: SettingsRecord
@@ -40,6 +72,8 @@ export interface SessionDefaultsPlan {
   readonly predates: boolean
   /** True when the deny list lacks any merge entry, whatever else it holds. */
   readonly lacksMergeDeny: boolean
+  /** True when the allow list lacks any lease push entry. */
+  readonly lacksPushAllow: boolean
 }
 
 export type SessionDefaultsRead =
@@ -66,24 +100,41 @@ function isRecord(value: unknown): value is SettingsRecord {
  */
 export function planSessionDefaults(
   current: SettingsRecord,
+  { planGuard = false }: SessionDefaultsOptions = {},
 ): SessionDefaultsPlan {
   const next: SettingsRecord = { ...current }
   const permissions = isRecord(current.permissions) ? current.permissions : {}
   const deny = Array.isArray(permissions.deny) ? permissions.deny : []
+  const allow = Array.isArray(permissions.allow) ? permissions.allow : []
 
   const subagentsMissing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
   const mergeMissing = MERGE_DENIED.filter((entry) => !deny.includes(entry))
   const missing = [...subagentsMissing, ...mergeMissing]
-  if (missing.length > 0) {
-    next.permissions = { ...permissions, deny: [...deny, ...missing] }
+  const allowMissing = PUSH_ALLOWED.filter((entry) => !allow.includes(entry))
+
+  const nextPermissions: SettingsRecord = { ...permissions }
+  if (missing.length > 0) nextPermissions.deny = [...deny, ...missing]
+  if (allowMissing.length > 0) {
+    nextPermissions.allow = [...allow, ...allowMissing]
+  }
+  if (missing.length + allowMissing.length > 0) {
+    next.permissions = nextPermissions
   }
 
   const memoryAbsent = !('autoMemoryEnabled' in current)
   if (memoryAbsent) next.autoMemoryEnabled = false
 
+  const preToolUse = planGuard ? wirePlanGuard(current.hooks) : undefined
+  if (preToolUse !== undefined) {
+    const hooks = isRecord(current.hooks) ? current.hooks : {}
+    next.hooks = { ...hooks, PreToolUse: preToolUse }
+  }
+
   const keys: SettingsKey[] = [
     { label: 'permissions.deny', changed: missing.length > 0 },
+    { label: 'permissions.allow', changed: allowMissing.length > 0 },
     { label: 'autoMemoryEnabled', changed: memoryAbsent },
+    { label: 'hooks.PreToolUse', changed: preToolUse !== undefined },
   ]
   return {
     keys,
@@ -94,13 +145,76 @@ export function planSessionDefaults(
       subagentsMissing.length === DENIED_TOOLS.length &&
       mergeMissing.length === MERGE_DENIED.length,
     lacksMergeDeny: mergeMissing.length > 0,
+    lacksPushAllow: allowMissing.length > 0,
+  }
+}
+
+/**
+ * Claude Code reads an absent, empty, or `*` matcher as every tool, one of
+ * only name characters as exact names split on `|` or `,`, and any other as
+ * an unanchored regular expression, per its hooks reference.
+ */
+function matcherCovers(matcher: unknown, tool: string): boolean {
+  if (matcher === undefined || matcher === '' || matcher === '*') return true
+  if (typeof matcher !== 'string') return false
+  if (/^[\w\s,|-]+$/.test(matcher)) {
+    return matcher.split(/[|,]/).some((name) => name.trim() === tool)
+  }
+  try {
+    return new RegExp(matcher).test(tool)
+  } catch {
+    return false
+  }
+}
+
+function runsPlanGuard(group: unknown, tool: string): boolean {
+  if (!isRecord(group) || !Array.isArray(group.hooks)) return false
+  if (!matcherCovers(group.matcher, tool)) return false
+  return group.hooks.some(
+    (hook) =>
+      isRecord(hook) &&
+      typeof hook.command === 'string' &&
+      hook.command.includes(PLAN_GUARD_SCRIPT),
+  )
+}
+
+/**
+ * Returns the PreToolUse list with the guard appended to each seeded matcher
+ * lacking it, or undefined when every tool already runs it. An existing group
+ * under the seeded matcher takes the entry, keeping its own hooks first.
+ */
+function wirePlanGuard(hooks: unknown): unknown[] | undefined {
+  const current =
+    isRecord(hooks) && Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []
+  const lacking = PLAN_GUARD_WIRING.filter(
+    ({ tool }) => !current.some((group) => runsPlanGuard(group, tool)),
+  )
+  if (lacking.length === 0) return undefined
+
+  const entry = { type: 'command', command: PLAN_GUARD_COMMAND }
+  const next = [...current]
+  for (const { matcher } of lacking) {
+    const at = next.findIndex(
+      (group) =>
+        isRecord(group) &&
+        group.matcher === matcher &&
+        Array.isArray(group.hooks),
+    )
+    const group = next[at]
+    if (isRecord(group) && Array.isArray(group.hooks)) {
+      next[at] = { ...group, hooks: [...group.hooks, entry] }
+    } else {
+      next.push({ matcher, hooks: [entry] })
+    }
   }
+  return next
 }
 
 /**
  * Refuses rather than plans whenever a write could replace something the
  * person owns: the toolkit's own settings, a file `JSON.parse` cannot read,
- * or a `permissions` or `deny` value of an unexpected shape.
+ * or a `permissions`, `deny`, `hooks`, or `PreToolUse` value of an
+ * unexpected shape.
  */
 export async function readSessionDefaults(
   root: string,
@@ -131,10 +245,34 @@ export async function readSessionDefaults(
   if (permissions !== undefined && !isRecord(permissions)) {
     return { kind: 'refused', reason: `${path}: permissions is not an object` }
   }
-  if (permissions?.deny !== undefined && !Array.isArray(permissions.deny)) {
+  for (const list of ['deny', 'allow'] as const) {
+    if (
+      permissions?.[list] !== undefined &&
+      !Array.isArray(permissions[list])
+    ) {
+      return {
+        kind: 'refused',
+        reason: `${path}: permissions.${list} is not a list`,
+      }
+    }
+  }
+
+  const planGuard = existsSync(
+    join(root, '.claude', 'hooks', PLAN_GUARD_SCRIPT),
+  )
+  const { hooks } = read.value
+  if (planGuard && hooks !== undefined && !isRecord(hooks)) {
+    return { kind: 'refused', reason: `${path}: hooks is not an object` }
+  }
+  if (
+    planGuard &&
+    isRecord(hooks) &&
+    hooks.PreToolUse !== undefined &&
+    !Array.isArray(hooks.PreToolUse)
+  ) {
     return {
       kind: 'refused',
-      reason: `${path}: permissions.deny is not a list`,
+      reason: `${path}: hooks.PreToolUse is not a list`,
     }
   }
 
@@ -142,7 +280,7 @@ export async function readSessionDefaults(
     kind: 'planned',
     path,
     indent: read.indent,
-    plan: planSessionDefaults(read.value),
+    plan: planSessionDefaults(read.value, { planGuard }),
   }
 }
 

package/src/take/encode.ts

@@ -97,11 +97,17 @@ export function openFrameEncoder(out: string, fps: number): FrameEncoder {
   }
 }
 
-/** Re-encodes a recorded clip to the same H.264 output at a constant `fps`. */
+/**
+ * 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',
@@ -111,6 +117,8 @@ export async function transcode(
       'error',
       '-i',
       input,
+      '-t',
+      (ms / 1000).toFixed(3),
       '-r',
       String(fps),
       ...OUTPUT,

package/src/take/film.ts

@@ -11,7 +11,7 @@ import {
   type TakeLog,
   VIEWPORT,
 } from '@/take/log'
-import { TargetMissing } from '@/take/perform'
+import { TargetMissing, TargetOffscreen, TargetRefused } from '@/take/perform'
 import type { Beat, Route, TakePlan } from '@/take/plan'
 import { filmScreencast } from '@/take/screencast'
 import { ShellMissing, findShell } from '@/take/shell'
@@ -30,6 +30,8 @@ export type TakeRefusal =
   | 'browser-missing'
   | 'server-unreachable'
   | 'target-missing'
+  | 'target-offscreen'
+  | 'over-cap'
   | 'take-failed'
 
 export interface FilmedBeat {
@@ -74,6 +76,8 @@ export interface TakeRequest {
   readonly env?: NodeJS.ProcessEnv
   /** How long one stepped frame may take before its beat falls back to a screencast. */
   readonly stallMs?: number
+  /** The filmed seconds the beats may sum to, past which the take refuses. */
+  readonly maxSeconds?: number
 }
 
 const REACH_TIMEOUT_MS = 5000
@@ -127,7 +131,7 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
       )
     } catch (error) {
       const cause = error instanceof FellBack ? error.error : error
-      const shot = cause instanceof TargetMissing ? cause.still : undefined
+      const shot = cause instanceof TargetRefused ? cause.still : undefined
       const still = shot ? join(dir, 'still.jpg') : undefined
       if (shot && still) writeFileSync(join(out, still), shot)
       return {
@@ -136,6 +140,16 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
         ...(still ? { still } : {}),
       }
     }
+    // Checked after each beat rather than once at the end, so a take refused
+    // on its first beat films nothing past it.
+    const frames = beats.reduce((sum, filmed) => sum + filmed.frames, 0)
+    if (request.maxSeconds !== undefined && frames > request.maxSeconds * FPS) {
+      return failed(
+        'over-cap',
+        `the beats through ${beat.name} run ${(frames / FPS).toFixed(2)} s, past the ${request.maxSeconds} s cap`,
+        beat.name,
+      )
+    }
   }
 
   writeFileSync(
@@ -231,6 +245,7 @@ class FellBack extends Error {
 
 function classify(error: unknown): TakeRefusal {
   if (error instanceof TargetMissing) return 'target-missing'
+  if (error instanceof TargetOffscreen) return 'target-offscreen'
   if (error instanceof ShellMissing || isBrowserMissing(error)) {
     return 'browser-missing'
   }

package/src/take/fixtures/busy.html

@@ -0,0 +1,107 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Busy</title>
+    <!--
+      A hero canvas that redraws every frame and spends busy=<ms> of main
+      thread work on each, so a frame takes about that long to render. A card
+      sits about 2900px down, below the window, and the rail link scrolls to it.
+      With timed=1 each frame spins on performance.now() instead, as the
+      groundwork page did, which never ends once the stepper pauses virtual
+      time.
+    -->
+    <style>
+      html {
+        scroll-behavior: smooth;
+      }
+
+      body {
+        margin: 0;
+        font-family: sans-serif;
+      }
+
+      nav {
+        position: fixed;
+        top: 10px;
+        right: 10px;
+        z-index: 2;
+      }
+
+      nav a {
+        display: block;
+        padding: 12px 20px;
+        background: #fff;
+      }
+
+      canvas {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+      }
+
+      section {
+        height: 900px;
+        border-top: 1px solid #ccc;
+        padding: 40px;
+      }
+
+      .card {
+        width: 400px;
+        height: 240px;
+        background: #ddd;
+      }
+
+      .card:hover {
+        background: #f60;
+      }
+    </style>
+  </head>
+  <body>
+    <nav><a id="rail" href="#cards">Cards</a></nav>
+    <canvas id="hero"></canvas>
+    <section>one</section>
+    <section>two</section>
+    <section id="cards"><div class="card" id="card">card</div></section>
+    <section>four</section>
+    <script>
+      const params = new URLSearchParams(location.search)
+      const busy = Number(params.get('busy') || 0)
+      const timed = params.get('timed') === '1'
+      const hero = document.getElementById('hero')
+      hero.width = innerWidth
+      hero.height = innerHeight
+      const context = hero.getContext('2d')
+      // The work is a count calibrated in real time on load, since a loop
+      // timed by performance.now() never ends under a paused virtual clock.
+      let sink = 0
+      const spin = (count) => {
+        for (let i = 0; i < count; i += 1) sink += Math.sqrt(i)
+      }
+      const measure = (ms) => {
+        let count = 0
+        const start = performance.now()
+        while (performance.now() - start < ms) {
+          spin(10000)
+          count += 10000
+        }
+        return count / ms
+      }
+      // Warmed first, so the count matches the optimized loop a frame runs.
+      measure(100)
+      const work = Math.round(busy * measure(200))
+      const draw = (time) => {
+        if (timed) {
+          const start = performance.now()
+          while (performance.now() - start < busy) {}
+        } else {
+          spin(work)
+        }
+        context.fillStyle = `hsl(${(time / 10) % 360}, 60%, 50%)`
+        context.fillRect(0, 0, hero.width, hero.height)
+        requestAnimationFrame(draw)
+      }
+      requestAnimationFrame(draw)
+    </script>
+  </body>
+</html>

package/src/take/perform.ts

@@ -3,6 +3,7 @@ import {
   FPS,
   type LogEvent,
   type Point,
+  VIEWPORT,
   along,
   travelMs,
 } from '@/take/log'
@@ -74,13 +75,40 @@ export interface Stage {
   evaluate<T>(expression: string): Promise<T>
 }
 
-/** A target that resolved to nothing, which refuses rather than films a guess. */
-export class TargetMissing extends Error {
+/** A target the pointer cannot reach, which refuses rather than films a guess. */
+export class TargetRefused extends Error {
   /** The page as it stood when the lookup failed, as a JPEG, when the route caught one. */
   still?: Buffer
 
-  constructor(readonly target: string) {
-    super(`nothing on the page matches ${target}`)
+  constructor(
+    readonly target: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** A target that resolved to nothing. */
+export class TargetMissing extends TargetRefused {
+  constructor(target: string) {
+    super(target, `nothing on the page matches ${target}`)
+  }
+}
+
+/**
+ * A target whose center lies outside the window, so the pointer would aim at
+ * a point the clip never shows, or for a scroll, a target with no part inside
+ * it. A setup step brings it into view first.
+ */
+export class TargetOffscreen extends TargetRefused {
+  constructor(
+    target: string,
+    readonly at: Point,
+  ) {
+    super(
+      target,
+      `${target} is centered at (${Math.round(at.x)}, ${Math.round(at.y)}), outside the ${VIEWPORT.width}x${VIEWPORT.height} window, so a setup step must bring it into view first`,
+    )
   }
 }
 
@@ -155,19 +183,12 @@ export async function performSteps(
         break
       }
       case 'scroll': {
-        const at = center(await boxOf(stage, step.target))
+        const at = await scrollPoint(stage, step.target)
         await moveTo(stage, state, at)
         const frames = Math.round(SCROLL_MS / FRAME_MS)
-        state.log?.push({
-          t: stage.now(),
-          kind: 'scroll',
-          at,
-          dx: 0,
-          dy: step.dy,
-          ms: frames * FRAME_MS,
-        })
+        const start = stage.now()
         let sent = 0
-        for (let frame = 1; frame <= frames; frame += 1) {
+        await paced(stage, frames, async (frame) => {
           const want = along(
             { x: 0, y: 0 },
             { x: 0, y: step.dy },
@@ -175,7 +196,15 @@ export async function performSteps(
           ).y
           await stage.pointer({ type: 'wheel', ...at, dy: want - sent })
           sent = want
-        }
+        })
+        state.log?.push({
+          t: start,
+          kind: 'scroll',
+          at,
+          dx: 0,
+          dy: step.dy,
+          ms: stage.now() - start,
+        })
         break
       }
       case 'wait':
@@ -194,21 +223,35 @@ async function moveTo(
   const from = state.pointer
   if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
   const frames = Math.max(1, Math.round(travelMs(from, to) / FRAME_MS))
-  state.log?.push({
-    t: stage.now(),
-    kind: 'move',
-    from,
-    to,
-    ms: frames * FRAME_MS,
-  })
   const pressed = held
     ? { held: true as const, ...withModifiers(held.modifiers) }
     : {}
-  for (let frame = 1; frame <= frames; frame += 1) {
+  const start = stage.now()
+  await paced(stage, frames, async (frame) => {
     state.pointer = along(from, to, frame / frames)
     await stage.pointer({ type: 'move', ...state.pointer, ...pressed })
-  }
+  })
   state.pointer = to
+  state.log?.push({ t: start, kind: 'move', from, to, ms: stage.now() - start })
+}
+
+/**
+ * Runs a motion planned as `frames` inputs, sending each at the frame the
+ * stage's clock has reached, so a page slower than a frame per input skips the
+ * points it is behind on and the motion still ends near its planned length. A
+ * clock advancing one frame per input, as the stepper's does, gets every frame.
+ */
+async function paced(
+  stage: Stage,
+  frames: number,
+  input: (frame: number) => Promise<void>,
+): Promise<void> {
+  const start = stage.now()
+  for (let frame = 0; frame < frames;) {
+    const reached = Math.round((stage.now() - start) / FRAME_MS)
+    frame = Math.min(frames, Math.max(frame + 1, reached + 1))
+    await input(frame)
+  }
 }
 
 async function click(
@@ -315,12 +358,43 @@ function center(box: Box): Point {
   return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
 }
 
-async function boxOf(stage: Stage, target: string): Promise<Box> {
+function inWindow(at: Point): boolean {
+  return (
+    at.x >= 0 && at.x <= VIEWPORT.width && at.y >= 0 && at.y <= VIEWPORT.height
+  )
+}
+
+async function foundBox(stage: Stage, target: string): Promise<Box> {
   const box = await stage.evaluate<Box | null>(boxExpression(target))
   if (!box) throw new TargetMissing(target)
   return box
 }
 
+async function boxOf(stage: Stage, target: string): Promise<Box> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (!inWindow(at)) throw new TargetOffscreen(target, at)
+  return box
+}
+
+/**
+ * Aims a wheel at the target's center, or, when that lies outside the window,
+ * at the center of the part the window shows. A wheel scrolls whatever sits
+ * under it, so any visible point of the target serves, and a page-tall element
+ * such as `body` has a center no setup step can bring into view.
+ */
+async function scrollPoint(stage: Stage, target: string): Promise<Point> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (inWindow(at)) return at
+  const left = Math.max(box.x, 0)
+  const right = Math.min(box.x + box.width, VIEWPORT.width)
+  const top = Math.max(box.y, 0)
+  const bottom = Math.min(box.y + box.height, VIEWPORT.height)
+  if (right <= left || bottom <= top) throw new TargetOffscreen(target, at)
+  return { x: (left + right) / 2, y: (top + bottom) / 2 }
+}
+
 /**
  * Finds a target's box in CSS pixels, reading `text=<words>` as the first
  * innermost element with a size whose whole text is those words, so a hidden

package/src/take/screencast.ts

@@ -7,7 +7,7 @@ import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
   type Stage,
-  TargetMissing,
+  TargetRefused,
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
@@ -92,13 +92,14 @@ export async function filmScreencast(request: {
       log: events,
     })
     await recording.hold(HOLD_MS)
+    const filmedMs = recording.now()
     await page.screencast.stop()
 
-    await transcode(webm, request.clip, FPS)
+    await transcode(webm, request.clip, FPS, filmedMs)
     const frames = await probeFrames(request.clip)
     return { frames, events, still: await lastFrame(request.clip, frames) }
   } catch (error) {
-    if (error instanceof TargetMissing && still) error.still = await still()
+    if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     await browser.close()