@erclx/canon 5.65.0 → 5.67.0

package/src/pr/drive-copy.ts

@@ -1,8 +1,12 @@
-import { createHash } from 'node:crypto'
-import { cpSync, existsSync, readFileSync, rmSync, statSync } from 'node:fs'
-import { isAbsolute, join } from 'node:path'
-import { $ } from 'bun'
-import { gitEnv } from '@/git/env'
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs'
+import { isAbsolute, join, relative, sep } from 'node:path'
 
 /** Where a project names the folders its running preview saves into. */
 export const PREVIEW_CONFIG_REL = join('canon', 'config', 'preview.json')
@@ -28,6 +32,8 @@ const BRANCH_TYPES = new Set([
 export interface PreviewConfig {
   readonly writes: readonly string[]
   readonly env: string
+  /** Paths inside a declared path that a rebuild leaves as the server wrote them. */
+  readonly keep: readonly string[]
 }
 
 export type PreviewConfigRead =
@@ -39,13 +45,6 @@ export type PreviewConfigRead =
       readonly detail: string
     }
 
-export interface StatusEntry {
-  readonly path: string
-  readonly status: string
-  /** The content digest, or null where no regular file stands at the path. */
-  readonly digest: string | null
-}
-
 /**
  * The branch-to-slug transform every branch-derived name shares: a leading
  * type segment comes off when a further segment follows it, and each
@@ -68,12 +67,25 @@ function isContained(path: string): boolean {
   )
 }
 
+/** Whether `path` is `parent` or stands below it, both relative to one root. */
+function isWithin(path: string, parent: string): boolean {
+  const rel = relative(join('/', parent), join('/', path))
+  return (
+    rel === '' ||
+    (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+  )
+}
+
 /**
- * Reads `canon/config/preview.json` as `{ "writes": [...], "env": "<NAME>" }`.
+ * Reads `canon/config/preview.json` as
+ * `{ "writes": [...], "keep": [...], "env": "<NAME>" }`.
  * A file that does not parse refuses rather than reading as absent, since a
  * typo there would otherwise drive the real folders while the pass reports a
- * copy. A `writes` path that is absolute or climbs with `..` refuses, so the
- * copy never reads or writes outside its two roots.
+ * copy. A `writes` or `keep` path that is absolute or climbs with `..`
+ * refuses, so the copy never reads or writes outside its two roots, and a
+ * `keep` path outside every `writes` path refuses, since the rebuild would
+ * never reach it, and so does one equal to a `writes` path, which would be
+ * declared both reset and kept.
  */
 export function loadPreviewConfig(worktree: string): PreviewConfigRead {
   const path = join(worktree, PREVIEW_CONFIG_REL)
@@ -97,7 +109,7 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
-  const { writes, env } = parsed as Record<string, unknown>
+  const { writes, env, keep = [] } = parsed as Record<string, unknown>
   if (
     !Array.isArray(writes) ||
     !writes.every((item): item is string => typeof item === 'string')
@@ -108,6 +120,16 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
       detail: `${PREVIEW_CONFIG_REL} carries no "writes" list of paths.`,
     }
   }
+  if (
+    !Array.isArray(keep) ||
+    !keep.every((item): item is string => typeof item === 'string')
+  ) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} names a "keep" that is not a list of paths.`,
+    }
+  }
   if (env !== undefined && (typeof env !== 'string' || env === '')) {
     return {
       kind: 'refused',
@@ -116,7 +138,7 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
-  const unsafe = writes.find((item) => !isContained(item))
+  const unsafe = [...writes, ...keep].find((item) => !isContained(item))
   if (unsafe !== undefined) {
     return {
       kind: 'refused',
@@ -125,94 +147,85 @@ export function loadPreviewConfig(worktree: string): PreviewConfigRead {
     }
   }
 
+  const stray = keep.find(
+    (item) => !writes.some((path) => isWithin(item, path)),
+  )
+  if (stray !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} keeps "${stray}", which no "writes" path holds.`,
+    }
+  }
+
+  const clash = keep.find((item) =>
+    writes.some((path) => isWithin(item, path) && isWithin(path, item)),
+  )
+  if (clash !== undefined) {
+    return {
+      kind: 'refused',
+      reason: 'bad-config',
+      detail: `${PREVIEW_CONFIG_REL} keeps "${clash}", which is also a "writes" path, so the rebuild would never reset it.`,
+    }
+  }
+
   return {
     kind: 'read',
-    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV },
+    config: { writes, env: env ?? DEFAULT_PREVIEW_ENV, keep },
   }
 }
 
 /**
- * Replaces the copy root with a fresh copy of each declared path, so the last
- * pass's drives never reach the next one. A path the worktree does not hold
- * is named rather than failing the copy.
+ * Removes `target` except the `keep` paths at or below it, where `rel` is
+ * `target` relative to the root `keep` is read against. A folder holding a
+ * kept path is emptied around it rather than removed.
+ */
+function clearAround(
+  target: string,
+  rel: string,
+  keep: readonly string[],
+): void {
+  if (keep.includes(rel)) return
+  const stat = lstatSync(target, { throwIfNoEntry: false })
+  if (stat === undefined) return
+  if (!stat.isDirectory() || !keep.some((path) => isWithin(path, rel))) {
+    rmSync(target, { recursive: true, force: true })
+    return
+  }
+  for (const entry of readdirSync(target)) {
+    clearAround(join(target, entry), join(rel, entry), keep)
+  }
+}
+
+/**
+ * Resets each declared path in the copy from the worktree, so the last pass's
+ * drives never reach the next one, and leaves everything else under the copy
+ * root as it is. A `keep` path inside a declared path is neither cleared nor
+ * copied, since the server running on the copy owns it. A path the worktree
+ * does not hold has its stale copy removed and is named rather than failing
+ * the copy.
  */
 export function buildDriveCopy(
   worktree: string,
   copyRoot: string,
   writes: readonly string[],
+  keep: readonly string[] = [],
 ): { readonly copied: readonly string[]; readonly missing: readonly string[] } {
-  rmSync(copyRoot, { recursive: true, force: true })
+  const kept = keep.map((path) => relative(worktree, join(worktree, path)))
   const copied: string[] = []
   const missing: string[] = []
   for (const path of writes) {
     const source = join(worktree, path)
+    clearAround(join(copyRoot, path), relative(worktree, source), kept)
     if (!existsSync(source)) {
       missing.push(path)
       continue
     }
-    cpSync(source, join(copyRoot, path), { recursive: true })
+    cpSync(source, join(copyRoot, path), {
+      recursive: true,
+      filter: (item) => !kept.includes(relative(worktree, item)),
+    })
     copied.push(path)
   }
   return { copied, missing }
 }
-
-function digestOf(path: string): string | null {
-  try {
-    if (!statSync(path).isFile()) return null
-    return createHash('sha1').update(readFileSync(path)).digest('hex')
-  } catch {
-    return null
-  }
-}
-
-/**
- * Every entry `git status` reports, untracked files listed one by one so a
- * file a drive adds inside a tracked folder names itself, each with a content
- * digest so a file already dirty at the baseline still reads as changed when
- * a drive writes it again. Undefined when git cannot read the tree.
- */
-export async function readWorktreeStatus(
-  worktree: string,
-): Promise<readonly StatusEntry[] | undefined> {
-  const result =
-    await $`git -C ${worktree} status --porcelain=v1 -z --untracked-files=all`
-      .env(gitEnv())
-      .quiet()
-      .nothrow()
-  if (result.exitCode !== 0) return undefined
-
-  const tokens = result.stdout.toString().split('\0')
-  const entries: StatusEntry[] = []
-  for (let index = 0; index < tokens.length; index++) {
-    const token = tokens[index] ?? ''
-    if (token.length < 4) continue
-    const status = token.slice(0, 2)
-    const path = token.slice(3)
-    // A rename or copy carries its source as the next token.
-    if (status.includes('R') || status.includes('C')) index++
-    entries.push({ path, status, digest: digestOf(join(worktree, path)) })
-  }
-  return entries
-}
-
-/**
- * The paths whose status or content differs from the baseline, in the order
- * git reports them. An entry gone since the baseline is not reported, since a
- * worker committing its own edit mid-pass clears it the same way.
- */
-export function changedSince(
-  baseline: readonly StatusEntry[],
-  current: readonly StatusEntry[],
-): readonly string[] {
-  const before = new Map(baseline.map((entry) => [entry.path, entry]))
-  return current
-    .filter((entry) => {
-      const prior = before.get(entry.path)
-      return (
-        prior === undefined ||
-        prior.status !== entry.status ||
-        prior.digest !== entry.digest
-      )
-    })
-    .map((entry) => entry.path)
-}

package/src/pr/health.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Where a project declares what `canon pr local` checks beyond the page. */
+export const LOCAL_CONFIG_REL = join('canon', 'config', 'local.toml')
+
+/**
+ * The health paths a project declared. `none` is an absent file or an empty
+ * `health = []`. `invalid` is a declaration that exists and cannot be used,
+ * which refuses rather than falling back to the page-only probe, since that
+ * fallback is the failure the declaration exists to catch.
+ */
+export type HealthDeclaration =
+  | { readonly kind: 'paths'; readonly paths: readonly string[] }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+
+/**
+ * A path on the page's own host. A second leading slash would read as a
+ * protocol-relative host, so it is refused to keep the probe on localhost.
+ */
+function isLocalPath(entry: unknown): entry is string {
+  return (
+    typeof entry === 'string' &&
+    entry.startsWith('/') &&
+    !entry.startsWith('//') &&
+    !entry.startsWith('/\\')
+  )
+}
+
+export function readHealthPaths(root: string): HealthDeclaration {
+  const path = join(root, LOCAL_CONFIG_REL)
+  if (!existsSync(path)) return { kind: 'none' }
+
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+      string,
+      unknown
+    >
+  } catch {
+    return { kind: 'invalid', reason: `${LOCAL_CONFIG_REL} is not valid TOML` }
+  }
+
+  const declared = parsed.health
+  if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
+    return {
+      kind: 'invalid',
+      reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+    }
+  }
+
+  return declared.length === 0
+    ? { kind: 'none' }
+    : { kind: 'paths', paths: declared }
+}

package/src/pr/local.ts

@@ -2,27 +2,62 @@ import { belongsTo } from '@/listeners/belongs'
 import type { ListenerReader } from '@/listeners/machine'
 import { readAddresses } from '@/pr/evidence'
 
-export type LocalRefusal = 'no-server' | 'no-listener-reader'
+export type LocalRefusal = 'no-server' | 'no-listener-reader' | 'unhealthy'
 
-/** The listener reads a detection makes plus an HTML probe, injected so it can be driven without binding a socket. */
+/** The listener reads a detection makes plus two HTTP probes, injected so it can be driven without binding a socket. */
 export interface LocalRunner extends ListenerReader {
   /** Whether the port serves an HTML page at its root inside the runner's timeout. */
   probe(port: number): Promise<boolean>
+  /** The final status a path on the port answers after redirects, or null when nothing answers inside the timeout. */
+  check(port: number, path: string): Promise<number | null>
 }
 
 export type LocalResult =
   | { readonly kind: 'found'; readonly port: number; readonly url: string }
-  | { readonly kind: 'refused'; readonly reason: LocalRefusal }
+  | {
+      readonly kind: 'refused'
+      readonly reason: Exclude<LocalRefusal, 'unhealthy'>
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'unhealthy'
+      readonly port: number
+      readonly path: string
+      readonly status: number | null
+    }
+
+interface HealthFailure {
+  readonly path: string
+  readonly status: number | null
+}
+
+async function firstFailingPath(
+  port: number,
+  healthPaths: readonly string[],
+  runner: LocalRunner,
+): Promise<HealthFailure | undefined> {
+  for (const path of healthPaths) {
+    const status = await runner.check(port, path)
+    if (status === null || status < 200 || status >= 300) {
+      return { path, status }
+    }
+  }
+  return undefined
+}
 
 /**
  * Finds the server this worktree is running: the lowest port whose listening
- * process runs inside the worktree and answers an HTTP probe. A port rather
- * than a process is the unit, since one dev server often holds a second
- * socket for its reload channel, and the lower one is the page by convention.
+ * process runs inside the worktree, answers an HTTP probe, and passes every
+ * declared health path. A port rather than a process is the unit, since one
+ * dev server often holds a second socket for its reload channel, and the
+ * lower one is the page by convention. Health is read on the page's own port,
+ * since that is the address a reviewer drives, and a page whose backend fails
+ * refuses as `unhealthy` naming the lowest page port's first failing path.
  */
 export async function findLocalServer(
   worktreeRoot: string,
   runner: LocalRunner,
+  healthPaths: readonly string[] = [],
 ): Promise<LocalResult> {
   const listeners = await runner.listListeners()
   if (listeners === undefined) {
@@ -37,12 +72,18 @@ export async function findLocalServer(
     if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
   }
 
+  let unhealthy: (HealthFailure & { readonly port: number }) | undefined
   for (const port of [...ports].sort((a, b) => a - b)) {
-    if (await runner.probe(port)) {
+    if (!(await runner.probe(port))) continue
+    const failure = await firstFailingPath(port, healthPaths, runner)
+    if (failure === undefined) {
       return { kind: 'found', port, url: `http://localhost:${port}` }
     }
+    unhealthy ??= { port, ...failure }
   }
-  return { kind: 'refused', reason: 'no-server' }
+  return unhealthy === undefined
+    ? { kind: 'refused', reason: 'no-server' }
+    : { kind: 'refused', reason: 'unhealthy', ...unhealthy }
 }
 
 /**

package/src/pr/rest.ts

@@ -15,8 +15,16 @@ export interface RestPull {
   readonly number?: number
   readonly title?: string
   readonly body?: string | null
-  readonly head?: { readonly ref?: string; readonly sha?: string }
-  readonly base?: { readonly ref?: string }
+  readonly head?: {
+    readonly ref?: string
+    readonly sha?: string
+    /** Null when the fork the head lived in was deleted. */
+    readonly repo?: { readonly full_name?: string } | null
+  }
+  readonly base?: {
+    readonly ref?: string
+    readonly repo?: { readonly full_name?: string }
+  }
   readonly mergeable_state?: string
   readonly state?: string
   readonly draft?: boolean

package/src/records/session-map.ts

@@ -0,0 +1,75 @@
+import { bodyLines, wordCount } from '@/markdown/scan'
+
+/** The pre-compaction handoff takes one file per session, so its stems vary. */
+export const SESSION_MAP_PREFIX = 'session-'
+
+/**
+ * The most words a session map holds, which `session.md` states as
+ * `at most 350 words`. It lives here rather than being read off the standard
+ * because a consumer project loads skills from the plugin cache and carries no
+ * `session.md` to read, so a test pins the two to one number instead.
+ */
+export const SESSION_MAP_WORD_CAP = 350
+
+/**
+ * The closing block a role mandates, read by the resuming session rather than
+ * written from what this one learned, so it is left out of the count by name.
+ */
+const RESUME_HEADING = '## Resume'
+
+const TITLE = /^#[ \t]+\S/
+const H2 = /^##[ \t]+\S/
+
+export interface SessionMapLength {
+  /** The map's filename inside the tasks folder. */
+  readonly record: string
+  readonly words: number
+  readonly cap: number
+  readonly over: boolean
+}
+
+export function isSessionMap(name: string): boolean {
+  return name.startsWith(SESSION_MAP_PREFIX) && name.endsWith('.md')
+}
+
+/**
+ * Counts what a resuming reader has to read: the body below the title, with
+ * frontmatter and a `## Resume` section left out. A fenced block counts the way
+ * it does in the requirements record, since a reader reads it too, and a
+ * heading inside one neither opens nor closes a section.
+ */
+export function sessionMapWords(source: string): number {
+  const kept: string[] = []
+  let titled = false
+  let resuming = false
+
+  for (const line of bodyLines(source)) {
+    const text = line.text.trim()
+
+    if (!line.fenced && H2.test(text)) resuming = text === RESUME_HEADING
+    if (resuming) continue
+
+    if (!titled && !line.fenced && TITLE.test(text)) {
+      titled = true
+      continue
+    }
+
+    kept.push(line.text)
+  }
+
+  return wordCount(kept.join('\n'))
+}
+
+export function measureSessionMap(
+  record: string,
+  source: string,
+): SessionMapLength {
+  const words = sessionMapWords(source)
+
+  return {
+    record,
+    words,
+    cap: SESSION_MAP_WORD_CAP,
+    over: words > SESSION_MAP_WORD_CAP,
+  }
+}

package/src/records/validate.ts

@@ -3,6 +3,11 @@ import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { linesOutsideFences } from '@/markdown/scan'
+import {
+  isSessionMap,
+  measureSessionMap,
+  type SessionMapLength,
+} from '@/records/session-map'
 import {
   intakeStructure,
   type StructureEntry,
@@ -13,7 +18,12 @@ import {
   recordDirs as resolveRecordDirs,
 } from '@/roots/record'
 
-export const RECORD_KINDS = ['plans', 'groundwork', 'intake'] as const
+export const RECORD_KINDS = [
+  'plans',
+  'groundwork',
+  'intake',
+  'sessions',
+] as const
 
 export type RecordKind = (typeof RECORD_KINDS)[number]
 
@@ -79,6 +89,12 @@ export interface ValidateReport {
   readonly records: number
   readonly findings: readonly Finding[]
   readonly structure: readonly StructureFinding[]
+  /**
+   * Each session map's words against its cap, carried by the sessions kind
+   * alone. It never sets the exit, since a map refused near a compaction loses
+   * the reasoning it was written to save.
+   */
+  readonly length?: readonly SessionMapLength[]
 }
 
 export interface ValidateRefused {
@@ -89,9 +105,20 @@ export interface ValidateRefused {
 
 export type ValidateOutcome = ValidateReport | ValidateRefused
 
+/**
+ * The record folder each kind reads. Session maps sit on the task board beside
+ * the tasks rather than in a folder of their own.
+ */
+const KIND_FOLDER: Readonly<Record<RecordKind, string>> = {
+  plans: 'plans',
+  groundwork: 'groundwork',
+  intake: 'intake',
+  sessions: 'tasks',
+}
+
 /** Every folder a kind would accept, whether or not it is on disk. */
 export function recordDirs(root: string, kind: RecordKind): string[] {
-  return resolveRecordDirs(root, kind)
+  return resolveRecordDirs(root, KIND_FOLDER[kind])
 }
 
 /**
@@ -100,7 +127,7 @@ export function recordDirs(root: string, kind: RecordKind): string[] {
  * the location the kind would be written to.
  */
 export function recordsDir(root: string, kind: RecordKind): string {
-  return resolveRecordDir(root, kind)
+  return resolveRecordDir(root, KIND_FOLDER[kind])
 }
 
 export function isRecordKind(value: string): value is RecordKind {
@@ -758,7 +785,7 @@ async function checkDump(dir: string, slug: string): Promise<Finding[]> {
  */
 const FOLDER_CHECK: Readonly<
   Record<
-    Exclude<RecordKind, 'plans'>,
+    Exclude<RecordKind, 'plans' | 'sessions'>,
     (dir: string, slug: string) => Promise<Finding[]>
   >
 > = {
@@ -836,6 +863,37 @@ async function validateFiles(
   }
 }
 
+/**
+ * The walk for session maps, which measures length alone. Their shape is not
+ * checked, so `findings` stays empty and the exit stays clean whatever the
+ * count reads.
+ */
+async function validateSessionMaps(
+  dir: string,
+  files: readonly string[],
+): Promise<ValidateReport> {
+  const length = await Promise.all(
+    files.map(async (file) =>
+      measureSessionMap(file, await readFile(join(dir, file), 'utf8')),
+    ),
+  )
+
+  return {
+    ok: true,
+    kind: 'sessions',
+    records: files.length,
+    findings: [],
+    structure: [],
+    length,
+  }
+}
+
+async function listRecords(dir: string, kind: RecordKind): Promise<string[]> {
+  if (kind === 'plans') return listMarkdown(dir)
+  if (kind === 'sessions') return (await listMarkdown(dir)).filter(isSessionMap)
+  return listFolders(dir)
+}
+
 /**
  * Narrows a listing to the one record a caller named, by a plan's stem or a
  * folder's slug, so a writing skill reads its own record and not every old one.
@@ -867,16 +925,14 @@ export async function validateRecords(
     )
   }
 
-  const names = narrow(
-    kind === 'plans' ? await listMarkdown(dir) : await listFolders(dir),
-    record,
-  )
+  const names = narrow(await listRecords(dir, kind), record)
 
   if (record !== undefined && names.length === 0) {
     return refuse('no-record', `No ${kind} record named ${record} in ${dir}.`)
   }
 
   if (kind === 'plans') return validateFiles(dir, kind, names, checkPlan)
+  if (kind === 'sessions') return validateSessionMaps(dir, names)
 
   const check = FOLDER_CHECK[kind]
   const perFolder = await Promise.all(

package/src/sandbox/replay/run.ts

@@ -81,6 +81,35 @@ function isCopied(rel: string): boolean {
   return rel.split('/').at(-1) !== 'node_modules' && rel !== '.claude/worktrees'
 }
 
+/**
+ * Git's background maintenance creates and removes files such as
+ * `.git/objects/maintenance.lock` while a copy walks the checkout, and a file
+ * listed then gone throws ENOENT. A short bound covers every transient name
+ * git uses, where a filter on `*.lock` would cover one.
+ */
+const COPY_ATTEMPTS = 3
+
+export function copyCheckout(
+  source: ReplaySource,
+  tree: string,
+  copy: typeof cpSync = cpSync,
+): void {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      copy(source.path, tree, {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: (from) => isCopied(relative(source.path, from)),
+      })
+      return
+    } catch (error) {
+      const vanished = (error as NodeJS.ErrnoException).code === 'ENOENT'
+      if (!vanished || attempt === COPY_ATTEMPTS) throw error
+      rmSync(tree, { recursive: true, force: true })
+    }
+  }
+}
+
 /**
  * Copies a source into `tree`. A snapshot's files lose their `.fixture`
  * suffix and its recorded expectation stays behind, and a checkout copies whole rather than cloning, since a clone
@@ -88,11 +117,7 @@ function isCopied(rel: string): boolean {
  */
 export function copySource(source: ReplaySource, tree: string): void {
   if (source.kind === 'checkout') {
-    cpSync(source.path, tree, {
-      recursive: true,
-      verbatimSymlinks: true,
-      filter: (from) => isCopied(relative(source.path, from)),
-    })
+    copyCheckout(source, tree)
     return
   }