@erclx/canon 5.76.0 → 5.77.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [5.77.0](https://github.com/erclx/canon/compare/v5.76.0...v5.77.0) (2026-10-31)
+
+
+### Features
+
+* **targets:** keep only real projects in the target index ([#2867](https://github.com/erclx/canon/issues/2867)) ([340cbff](https://github.com/erclx/canon/commit/340cbff8edda3987af6d4933aa27391e07b312a2))
+* **tooling:** bound and retry the shipped playwright installs ([#2865](https://github.com/erclx/canon/issues/2865)) ([842d5f9](https://github.com/erclx/canon/commit/842d5f957602136d8bbbdfba524fbba1340df76a))
+
+
+### Bug Fixes
+
+* **tooling:** turn off the card toolbar and narrow the exclusion check ([#2864](https://github.com/erclx/canon/issues/2864)) ([188c1e9](https://github.com/erclx/canon/commit/188c1e950c83cd00ad22e07c43d5232bf01e6ad8))
+
 ## [5.76.0](https://github.com/erclx/canon/compare/v5.75.0...v5.76.0) (2026-10-31)
 
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.76.0",
+  "version": "5.77.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -9,12 +9,18 @@ description: Scope boundary for pipeline structure against job contents, and the
 
 Without this skill, a session chains jobs with `needs` to express reading order rather than a data dependency, so the pipeline costs the sum of its jobs. The same session splits a one-minute gate into parallel jobs, each repaying checkout, install, and toolchain setup, so the gate gets slower while reporting no earlier.
 
-The rest surface as flakes. A moving action ref changes under the project, a static cache key serves a stale toolchain, artifacts never expire, a broad default token grants unneeded writes, and a missing manual trigger leaves a run reproducible only by pushing a commit. A Linux-only pin also flags a supported macOS job as a departure.
+The rest surface as flakes or stalls:
+
+- A moving action ref changes under the project, and a static cache key serves a stale toolchain
+- Artifacts never expire, and a broad default token grants unneeded writes
+- A missing manual trigger leaves a run reproducible only by pushing a commit
+- A Linux-only pin flags a supported macOS job as a departure
+- A Playwright install calling apt directly hangs on a stalled mirror and, with no step bound, holds the runner until the six-hour job default
 
 ## Must
 
 - A job is gated only on a data dependency or a cost that justifies the wait, and checks sharing setup stay in one job until a run log puts the gate past roughly two minutes
-- Every action is pinned to a tag that cannot cross a major version, and every cache is keyed on the version of what it caches
+- Every action is pinned to a tag that cannot cross a major version, every cache is keyed on the version of what it caches, and every Playwright install is bounded and retried
 - Every workflow carries a manual trigger beside its primary one, except one that commits back
 - The token defaults to read-only, with a write scope granted only on the job that needs it, and artifact upload is bounded to failures and expires
 - A job runs on Linux unless the project states a platform for a layer that differs by platform

package/claude/skills/ci-workflow/SKILL.md

@@ -60,6 +60,8 @@ Linux stays the default. A job leaves it only for a layer whose result differs b
 - Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
 - Install with `bun install --frozen-lockfile`.
 - Cache Playwright browsers keyed on the Playwright version string, never a static key.
+- Bound each Playwright install step, 10 minutes on the system packages and 5 on the browser. A stalled apt mirror hangs rather than fails, and an unbounded job waits out the six-hour default.
+- Install the system packages through a script that kills and retries a stalled attempt, never a direct `install-deps` or `--with-deps`, since a bound alone turns the hang red.
 
 ## Commit-back
 
@@ -106,3 +108,4 @@ Before responding, also verify:
 Before responding, also verify:
 
 - No `run:` step passes five lines or carries more than one exit-or-output guard, a loop, a trap, or a function. A step that does calls a script, with its inputs as arguments or `env`.
+- Every Playwright install step carries `timeout-minutes`, and the system packages install through a retried script.

package/docs/agents/targets.md

@@ -9,7 +9,9 @@ kind: reference
 `canon targets list` reports the projects this toolkit installed into. `canon targets pulls [paths…]` reports each target's open pull requests, or every target's when none is named. Both take `--json`. Read the record's fields, since a wrapping shell function can flatten the exit.
 
 - `list` takes `--sweep <path…>`, `--depth <n>` (default 4), and `--record`, which seeds the index from swept stamps and needs `--sweep`
-- Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, and no row is removed
+- Each stamping sync records its target in `$XDG_STATE_HOME/canon/targets.json`, except a folder under the OS temp folder, the state folder, `~/.claude/jobs/`, or any `.canon/tmp/`
+- Every write drops a row whose folder is gone or sits under one of those, and `list` leaves the same rows out. A target on an unmounted drive drops until its next sync records it again.
+- `--record` counts a swept checkout under one of those folders as skipped, not failed
 - A sweep finds installs the index never held
 
 `canon changelog` prints the releases a target has not seen, from the `CHANGELOG.md` the installed package ships. It reads no registry and needs no `gh`.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.76.0",
+  "version": "5.77.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
-    "canon": "./src/cli.ts"
+    "canon": "src/cli.ts"
   },
   "files": [
     "src",

package/src/commands/targets.ts

@@ -267,6 +267,8 @@ function refuseDepth(opts: ListOptions): number {
 interface BackfillSummary {
   readonly recorded: number
   readonly skipped: number
+  /** Skipped too, but for sitting under a scratch root, so its line names that cause. */
+  readonly scratch: number
   readonly failed: number
 }
 
@@ -285,16 +287,18 @@ async function runBackfill(
 
   let recorded = 0
   let skipped = 0
+  let scratch = 0
   let failed = 0
 
   for (const path of paths) {
     const outcome = backfillTarget({ path, stampedAt: stampedAtOf(path) })
     if (outcome === 'recorded') recorded++
     else if (outcome === 'no-stamp') skipped++
+    else if (outcome === 'scratch') scratch++
     else failed++
   }
 
-  return { recorded, skipped, failed }
+  return { recorded, skipped, scratch, failed }
 }
 
 /**
@@ -340,6 +344,12 @@ function reportBackfill(summary: BackfillSummary): void {
     )
   }
 
+  if (summary.scratch > 0) {
+    logWarn(
+      `${plural(summary.scratch, 'target')} skipped, sitting under a scratch folder the index never records.`,
+    )
+  }
+
   if (summary.failed > 0) {
     logError(
       `${plural(summary.failed, 'target')} failed to write, so its row is unchanged.`,

package/src/targets/registry.ts

@@ -2,11 +2,12 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   writeFileSync,
 } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 /**
  * One project the toolkit has installed into, as the install recorded it.
@@ -116,15 +117,90 @@ function isRecord(value: Partial<TargetRecord>): value is TargetRecord {
 }
 
 /**
- * Reads every recorded target, sorted by path.
+ * The folders whose contents are never a project, resolved at call time so a
+ * test's `CANON_STATE_DIR` override moves the state root with it.
+ *
+ * Sandbox runs and replays live under the state folder, background jobs keep
+ * their scratch under `~/.claude/jobs/`, and unit tests stamp into the OS temp
+ * folder. Each one passes through a stamping sync, so without this list every
+ * run leaves a row behind for a folder that is gone a minute later.
+ */
+export function scratchRoots(): readonly string[] {
+  return [tmpdir(), stateDir(), join(homedir(), '.claude', 'jobs')]
+}
+
+/**
+ * Whether a path sits under a scratch root or inside any `.canon/tmp/` folder.
+ *
+ * Both sides are compared in their given and their real form, since macOS
+ * hands out its temp folder as `/var/folders/...` while a path that went
+ * through a symlink resolution reads `/private/var/folders/...`. A
+ * `.claude/worktrees/` checkout is not scratch: it is a real checkout of a real
+ * project, and only a root on the list or a `.canon/tmp/` segment refuses it.
+ */
+export function isScratchPath(
+  target: string,
+  roots: readonly string[] = scratchRoots(),
+): boolean {
+  const forms = bothForms(resolve(target))
+  const rootForms = roots.flatMap((root) => bothForms(resolve(root)))
+
+  return forms.some(
+    (form) =>
+      hasCanonTmpSegment(form) ||
+      rootForms.some((root) => isWithin(form, root)),
+  )
+}
+
+function bothForms(path: string): readonly string[] {
+  try {
+    const real = realpathSync(path)
+    return real === path ? [path] : [path, real]
+  } catch {
+    return [path]
+  }
+}
+
+function hasCanonTmpSegment(path: string): boolean {
+  const segments = path.split(sep)
+  return segments.some(
+    (segment, index) => segment === '.canon' && segments[index + 1] === 'tmp',
+  )
+}
+
+function isWithin(path: string, root: string): boolean {
+  const rel = relative(root, path)
+  return (
+    rel === '' ||
+    (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+  )
+}
+
+/**
+ * Whether a row still names a project worth listing: a folder that exists and
+ * sits under no scratch root. The read filter and the write prune both call
+ * this, so the two can never disagree on a row.
+ */
+function isLive(row: TargetRecord, roots: readonly string[]): boolean {
+  return existsSync(row.path) && !isScratchPath(row.path, roots)
+}
+
+/**
+ * Reads every recorded target that is still live, sorted by path.
  *
  * A row missing either field is dropped rather than reported. This module is
  * the file's only writer, so a malformed row is a hand edit or a truncated
  * write and neither is a finding the caller can act on. What a caller can act
  * on is the file being absent, which is its own kind above.
+ *
+ * A row whose folder is gone or under a scratch root is left out too, so the
+ * list is right on a machine whose file predates the prune, before any sync
+ * rewrites it. A target on a drive that is unmounted reads as gone here, and
+ * its next sync records it again.
  */
 export function readTargetRegistry(
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): TargetRegistry {
   let text: string
   try {
@@ -150,38 +226,46 @@ export function readTargetRegistry(
     .filter((row): row is TargetRecord =>
       isRecord(row as Partial<TargetRecord>),
     )
+    .filter((row) => isLive(row, roots))
     .sort((a, b) => a.path.localeCompare(b.path))
 
   return { kind: 'read', path, targets }
 }
 
-/** Why a record attempt did not land, so a caller can say so rather than assume it did. */
-export type RecordOutcome = 'recorded' | 'unwritten'
+/**
+ * Why a record attempt did not land, so a caller can say so rather than assume
+ * it did. `scratch` is a deliberate refusal of a path under a scratch root,
+ * not a failure.
+ */
+export type RecordOutcome = 'recorded' | 'unwritten' | 'scratch'
 
 /**
  * Records one target, keyed by its resolved path and replacing any row already
- * held for it.
+ * held for it, and refuses a path under a scratch root.
  *
  * The write is a temp file plus a rename, so a reader never meets a half
  * written file. Two syncs finishing together still resolve last-writer-wins on
  * the merged set, which can drop the row the loser added. That is left rather
  * than locked: the authoritative record of an install is the stamp inside the
  * target, this index is a cache over those, and the next sync of the dropped
- * target restores its row.
+ * target restores its row. The prune reads the same merged set the write
+ * already reads, so it adds no second read and does not widen that window.
  *
- * Nothing removes a row either, so a target that was deleted or that dropped
- * the toolkit stays here and the count drifts upward. `canon targets pulls`
- * meets that on use, since it refuses a path it cannot open rather than
- * reading it as a target with no work, but `canon targets list` does not: it
- * never opens a recorded path, and the count is its whole output.
+ * Every write also drops the rows `readTargetRegistry` leaves out, being a
+ * folder that is gone or one under a scratch root, so the file shrinks back to
+ * the live projects rather than growing with every sandbox run. A target on a
+ * drive that is unmounted drops with them, and its next sync restores it.
  */
 export function recordTarget(
   target: string,
   now: Date,
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): RecordOutcome {
   const resolved = resolve(target)
-  const current = readTargetRegistry(path)
+  if (isScratchPath(resolved, roots)) return 'scratch'
+
+  const current = readTargetRegistry(path, roots)
   const existing = current.kind === 'read' ? current.targets : []
 
   const targets = [
@@ -220,7 +304,8 @@ export type BackfillOutcome = RecordOutcome | 'no-stamp'
 export function backfillTarget(
   target: BackfillTarget,
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): BackfillOutcome {
   if (target.stampedAt === null) return 'no-stamp'
-  return recordTarget(target.path, new Date(target.stampedAt), path)
+  return recordTarget(target.path, new Date(target.stampedAt), path, roots)
 }

package/src/targets/resolve.ts

@@ -45,6 +45,8 @@ export interface ResolveTargetsOptions extends SweepOptions {
   /** Roots to walk, supplementing the record rather than replacing it. */
   readonly sweep?: readonly string[]
   readonly registryFile?: string
+  /** Folders whose recorded rows are left out, defaulting to `scratchRoots()`. */
+  readonly scratchRoots?: readonly string[]
 }
 
 /**
@@ -71,7 +73,7 @@ export async function resolveTargets(
   }
 
   const file = opts.registryFile ?? registryPath()
-  const registry = readTargetRegistry(file)
+  const registry = readTargetRegistry(file, opts.scratchRoots)
 
   const recorded: KnownTarget[] =
     registry.kind === 'read'

package/tooling/astro/configs/card.config.mjs

@@ -14,7 +14,11 @@ const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
 // The base port sits outside the band `astro.config.mjs` serves from, so a card
 // server and a dev server of one worktree never contend, and two worktrees
 // separate here the way they separate there.
+//
+// The dev toolbar is off because this server exists to be captured, and the
+// toolbar paints over the viewport the capture cuts the card from.
 export default defineConfig({
+  devToolbar: { enabled: false },
   srcDir: './card-src',
   outDir: './card-dist',
   publicDir: './public',

package/tooling/astro/configs/scripts/check-card-exclusion.sh

@@ -50,8 +50,13 @@ if grep -rl "$MARKER" "$DIST" >/dev/null 2>&1; then
   exit 1
 fi
 
-if find "$DIST" -iname '*og-card*' | grep -q .; then
-  echo "A file named for the card route reached $DIST. See card.config.mjs's srcDir." >&2
+# Built pages only, since an image or font may carry the route's name without
+# being the route. The path test covers both formats Astro emits, being
+# og-card/index.html under build.format 'directory' and og-card.html under
+# 'file'. The search runs from inside dist so a project checked out under a
+# directory like blog-card-site cannot match on its own prefix.
+if (cd "$DIST" && find . -ipath '*og-card*' -name '*.html' | grep -q .); then
+  echo "A page named for the card route reached $DIST. See card.config.mjs's srcDir." >&2
   exit 1
 fi
 

package/tooling/astro/reference.md

@@ -64,7 +64,7 @@ The astro stack covers Astro + TypeScript projects, being content sites, marketi
 ## Social card route
 
 - Keep the social card as a route the project owns, so a re-render after a rename is one string edit and a re-capture rather than another `design-identity` pick loop
-- Expect `canon:design-identity` to write the picked composition into the route and capture it through the card server
+- Expect `canon:design-identity` to write the picked composition into the route and capture it through the card server, which runs with Astro's dev toolbar off so it never paints over the card
 - `card.config.mjs` is a second Astro config whose `srcDir` points at `./card-src`, which the main page router never reads, so the published build excludes the card structurally
 - It serves on base port `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a worktree's card and dev servers never contend
 - `bun run card:dev` serves the route and `bun run card:check` runs the exclusion check, which base's `scripts/verify.ts` also runs after its build stage
@@ -72,6 +72,7 @@ The astro stack covers Astro + TypeScript projects, being content sites, marketi
 ## Card exclusion and size
 
 - `scripts/check-card-exclusion.sh` fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and when the route dropped the tag the leak test reads
+- The filename test reads built HTML pages only, under an `og-card` path in either build format, so an image or font may carry the route's name
 - Keep the exclusion a check rather than a convention, since the card server and the capture read the route and the published build must not carry it
 - Declare `.card` at 600x315, half the 1200x630 target, since `canon capture` shoots at a fixed 2x device scale and 1200x630 would capture at 2400x1260
 

package/tooling/web/configs/.github/workflows/readme-screenshot.yml

@@ -74,10 +74,12 @@ jobs:
         # Unconditional: the cache holds browser binaries and nothing apt
         # wrote, so gating this on a cache hit leaves a warm run launching
         # chromium without the libraries it needs.
-        run: bunx playwright install-deps chromium
+        timeout-minutes: 10
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Install Playwright Browser
         if: steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Capture README Screenshot

package/tooling/web/configs/.github/workflows/verify.yml

@@ -72,7 +72,7 @@ jobs:
       - name: Install Playwright System Dependencies
         if: steps.browser.outputs.enabled == 'true'
         timeout-minutes: 10
-        run: bunx playwright install-deps chromium
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Cache Playwright Browsers
         id: playwright-cache
@@ -84,6 +84,7 @@ jobs:
 
       - name: Install Playwright Chromium
         if: steps.browser.outputs.enabled == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Run Tests
@@ -151,7 +152,8 @@ jobs:
           path: dist/
 
       - name: Install Playwright System Dependencies
-        run: bunx playwright install-deps chromium
+        timeout-minutes: 10
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Cache Playwright Browsers
         id: playwright-cache
@@ -162,6 +164,7 @@ jobs:
 
       - name: Install Playwright Chromium
         if: steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Run E2E Tests

package/tooling/web/configs/scripts/install-playwright-deps.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Installs the Playwright system packages for the named browsers, killing an
+# attempt that outlives its bound and retrying it. A degraded apt mirror hangs
+# one connection rather than failing it, so a step timeout alone turns the
+# hang into a red check and never recovers it, while a fresh attempt usually
+# lands on a healthy backend.
+#
+# Usage: install-playwright-deps.sh [--package <spec>] <browser>...
+# Exits 0 on the first success, 2 when no browser is named, and the last
+# attempt's code when every attempt fails.
+set -e
+
+package=playwright
+if [ "$1" = "--package" ]; then
+  package=$2
+  shift 2
+fi
+
+if [ $# -eq 0 ]; then
+  echo "Usage: install-playwright-deps.sh [--package <spec>] <browser>..." >&2
+  exit 2
+fi
+
+attempts=3
+bound=${INSTALL_ATTEMPT_SECONDS:-150}
+
+# The runner image sets these, yet a stalled log shows gaps of minutes, so
+# print what apt actually reads to settle whether they took effect
+apt-config dump | grep -E '^Acquire::(Retries|http::Timeout) ' || true
+
+status=0
+for attempt in $(seq 1 "$attempts"); do
+  if [ "$attempt" -gt 1 ]; then
+    # timeout runs as the runner user, and Linux drops its signal to the root
+    # apt-get playwright spawns through sudo. sudo relays it only to its own
+    # child shell, so a root apt-get or dpkg can outlive the kill and hold the
+    # lock the next attempt needs.
+    sudo pkill -KILL -x 'apt-get|dpkg' || true
+    # A kill during unpack leaves dpkg interrupted, which refuses the next
+    # install. Its own failure must not end the loop.
+    sudo dpkg --configure -a || echo "dpkg --configure -a failed before attempt ${attempt}" >&2
+  fi
+
+  status=0
+  timeout --kill-after=10 "$bound" bunx "$package" install-deps "$@" || status=$?
+  if [ "$status" -eq 0 ]; then
+    exit 0
+  fi
+  echo "attempt ${attempt}/${attempts} failed with exit ${status}" >&2
+done
+
+exit "$status"

package/tooling/web/reference.md

@@ -88,6 +88,11 @@ The starter `e2e/home.spec.ts` is seeded once. Sync copies it into a project tha
 - `.github/workflows/verify.yml` runs `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests`. `unit-tests` installs Chromium and runs `test:browser` only when the project defines that script.
 - Read `governance/rules/tooling/ci-workflow.md` for when a workflow's commit-back is right and when a report is
 
+## Playwright installs in CI
+
+- Both workflows install Playwright's system packages through `scripts/install-playwright-deps.sh`, which sits beside `worktree-port.sh` and retries an attempt a stalled apt mirror hangs
+- Expect each system install bounded at 10 minutes and each browser download at 5, while the jobs carry no bound, since test and build time differs per project
+
 ## Design references
 
 - Expect a seeded `canon/design/index.md` stub carrying `auto: false`, copied only when missing, so a project's own index is never replaced