@erclx/canon 5.27.0 → 5.28.0

package/src/gate/measures.ts

@@ -37,7 +37,7 @@ import {
   SHIPPED_CORPORA,
   type ShippedReference,
 } from '@/shipped/references'
-import { surfaceDir } from '@/surface-root'
+import { surfaceDir } from '@/roots/surface'
 import { seedRoots } from '@/tooling/seeds'
 import { plural } from '@/ui'
 import {

package/src/gate/sequencer.ts

@@ -7,8 +7,13 @@ import type {
   RunCommand,
 } from '@/gate/measures'
 import type { Check, Stage } from '@/gate/stages'
+import {
+  acquireSuiteLock,
+  type LockHolder,
+  machineLockPath,
+} from '@/gate/suite-lock'
 import { gitEnv } from '@/git/env'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 
 export type StageStatus =
   /** Every check ran and none found a fact. */
@@ -27,8 +32,16 @@ export interface StageResult {
   readonly emissions: readonly Emission[]
   /** The remedy line a failed stage prints, naming what to do about it. */
   readonly failure?: string
-  /** Wall time the stage's checks took, including every process spawn. */
+  /**
+   * Wall time the stage took, including every process spawn and, on a stage
+   * holding a machine lock, the time it queued behind another worktree.
+   */
   readonly ms: number
+  /**
+   * The part of `ms` spent queued behind another worktree's hold on the stage's
+   * machine lock. Absent where the stage never waited.
+   */
+  readonly queuedMs?: number
 }
 
 export interface GateContext extends MeasureContext {
@@ -39,6 +52,12 @@ export interface GateContext extends MeasureContext {
    * scoping is off and every stage runs.
    */
   readonly changed?: readonly string[]
+  /**
+   * Told when a stage starts queuing on its machine lock. A stage prints only
+   * once it returns, so without this a queued gate is silent for the whole
+   * wait and reads as a hung suite.
+   */
+  readonly onQueue?: (label: string, holder: LockHolder) => void
 }
 
 export interface ChangedSet {
@@ -157,7 +176,40 @@ async function executeStage(
     }
   }
 
-  const emissions: Emission[] = []
+  // CI runs one suite per runner, so a lock there queues behind nothing.
+  if (stage.lock === undefined || ctx.ci) return runChecks(stage, ctx, [])
+
+  const held = await acquireSuiteLock({
+    path: machineLockPath(stage.lock),
+    root: ctx.root,
+    onWait: (holder) => ctx.onQueue?.(stage.label, holder),
+  })
+  const queued: Emission[] =
+    held.waitedOn === undefined
+      ? []
+      : [
+          {
+            kind: 'info',
+            text: `Waited ${Math.round(held.waitedMs / 1000)}s for the ${stage.label} stage another worktree held, at ${held.waitedOn.root}`,
+          },
+        ]
+
+  try {
+    const outcome = await runChecks(stage, ctx, queued)
+    return held.waitedOn === undefined
+      ? outcome
+      : { ...outcome, queuedMs: held.waitedMs }
+  } finally {
+    held.release()
+  }
+}
+
+async function runChecks(
+  stage: Stage,
+  ctx: GateContext,
+  leading: readonly Emission[],
+): Promise<StageOutcome> {
+  const emissions: Emission[] = [...leading]
 
   for (const check of stage.checks) {
     const outcome = await runCheck(check, ctx)

package/src/gate/stages.ts

@@ -88,6 +88,11 @@ export interface Stage {
    */
   readonly when?: (options: { readonly write: boolean }) => boolean
   readonly checks: readonly Check[]
+  /**
+   * The machine lock this stage holds while its checks run, so one box runs it
+   * for one worktree at a time. Absent means the stage never queues.
+   */
+  readonly lock?: string
   /** The line a clean stage prints, where the checks emit none of their own. */
   readonly success?: string
 }
@@ -579,6 +584,9 @@ export const STAGES: readonly Stage[] = [
     label: 'Tests',
     scope: TESTS_SCOPE,
     skipped: 'Skipped, no TypeScript or asserted-corpus changes',
+    // Concurrent suites from a wave of worktrees starve each other's spawn
+    // and browser tests past their timeouts, so the box runs one at a time.
+    lock: 'tests',
     checks: [
       {
         kind: 'command',

package/src/gate/suite-lock.ts

@@ -0,0 +1,214 @@
+import {
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+import { liveness, type LivenessProbes, SYSTEM_PROBES } from '@/sessions/live'
+import { stateDir } from '@/targets/registry'
+
+/**
+ * Who holds a machine lock, as the file records it.
+ *
+ * The start time is what separates the holder from whatever inherits its pid
+ * after a crash, so a takeover never waits on a recycled number.
+ */
+export interface LockHolder {
+  readonly pid: number
+  readonly procStart: string | undefined
+  /** The worktree whose gate holds the lock, which the wait line names. */
+  readonly root: string
+}
+
+export interface SuiteLockOptions {
+  readonly path: string
+  readonly root: string
+  readonly pid?: number
+  readonly probes?: LivenessProbes
+  readonly pollMs?: number
+  readonly sleep?: (ms: number) => Promise<void>
+  /** Called once, when the first poll finds a live holder, so a wait is never silent. */
+  readonly onWait?: (holder: LockHolder) => void
+}
+
+export interface HeldLock {
+  readonly release: () => void
+  /** The holder this acquirer queued behind, absent when it never waited. */
+  readonly waitedOn?: LockHolder
+  readonly waitedMs: number
+}
+
+export type AcquireOutcome =
+  | { readonly acquired: true; readonly release: () => void }
+  | { readonly acquired: false; readonly holder: LockHolder | undefined }
+
+/**
+ * The file a named machine lock lives at, resolved at call time so a test run
+ * that redirects the state folder never touches the real one.
+ */
+export function machineLockPath(name: string): string {
+  return join(stateDir(), 'locks', `${name}.lock`)
+}
+
+function isHolder(value: unknown): value is LockHolder {
+  if (typeof value !== 'object' || value === null) return false
+  const fields = value as Record<string, unknown>
+  return typeof fields.pid === 'number' && typeof fields.root === 'string'
+}
+
+function readText(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+function parseHolder(text: string): LockHolder | undefined {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isHolder(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function isCode(error: unknown, code: string): boolean {
+  return (error as NodeJS.ErrnoException).code === code
+}
+
+/**
+ * Publishes the holder's file whole or not at all.
+ *
+ * `link` refuses an existing name the way an exclusive open does, and the
+ * linked file is already written, so no reader meets an empty lock and mistakes
+ * a holder mid-write for a corrupt file it may take over.
+ */
+function publish(path: string, text: string, pid: number): boolean {
+  const staged = `${path}.${pid}.tmp`
+  writeFileSync(staged, text)
+  try {
+    linkSync(staged, path)
+    return true
+  } catch (error) {
+    if (isCode(error, 'EEXIST')) return false
+    throw error
+  } finally {
+    unlinkSync(staged)
+  }
+}
+
+/**
+ * Moves a dead holder's file aside, or puts back one that changed under it.
+ *
+ * Unlink then create is two calls, and two acquirers judging one stale file
+ * would both get through. A rename moves the file to a name only this acquirer
+ * uses, so only one of them gets it, and comparing what moved against what was
+ * judged catches the case where another acquirer already replaced it.
+ *
+ * One interleaving still gets through. A third acquirer publishing between the
+ * rename and the restore leaves the moved holder's file with nowhere to go, so
+ * two suites run at once. That costs one oversubscribed run and never a hang,
+ * and closing it needs a lock the kernel releases, which `node:fs` does not
+ * offer.
+ */
+function displace(path: string, judged: string, pid: number): void {
+  const aside = `${path}.${pid}.stale`
+  try {
+    renameSync(path, aside)
+  } catch (error) {
+    if (isCode(error, 'ENOENT')) return
+    throw error
+  }
+
+  if (readText(aside) !== judged) {
+    try {
+      linkSync(aside, path)
+    } catch (error) {
+      if (!isCode(error, 'EEXIST')) throw error
+    }
+  }
+  unlinkSync(aside)
+}
+
+/**
+ * One attempt at the lock: take it free, take it over from a dead holder, or
+ * report who holds it.
+ */
+export function tryAcquire(options: SuiteLockOptions): AcquireOutcome {
+  const pid = options.pid ?? process.pid
+  const probes = options.probes ?? SYSTEM_PROBES
+  const own: LockHolder = {
+    pid,
+    procStart: probes.procStartOf(pid) ?? undefined,
+    root: options.root,
+  }
+  const text = JSON.stringify(own)
+
+  mkdirSync(dirname(options.path), { recursive: true })
+
+  if (publish(options.path, text, pid)) {
+    return { acquired: true, release: () => release(options.path, text) }
+  }
+
+  const judged = readText(options.path)
+  if (judged === undefined) return { acquired: false, holder: undefined }
+
+  const holder = parseHolder(judged)
+  if (holder !== undefined && liveness(holder, probes).alive) {
+    return { acquired: false, holder }
+  }
+
+  displace(options.path, judged, pid)
+
+  if (publish(options.path, text, pid)) {
+    return { acquired: true, release: () => release(options.path, text) }
+  }
+  return { acquired: false, holder: parseHolder(readText(options.path) ?? '') }
+}
+
+/** Removes the file only while it is still this holder's own. */
+function release(path: string, text: string): void {
+  if (readText(path) !== text) return
+  try {
+    unlinkSync(path)
+  } catch (error) {
+    if (!isCode(error, 'ENOENT')) throw error
+  }
+}
+
+const wait = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+/**
+ * Waits for the lock with no deadline while its holder lives. A deadline would
+ * turn a long queue back into the intermittent failure the lock removes, and a
+ * dead holder is taken over on the next poll rather than waited out.
+ */
+export async function acquireSuiteLock(
+  options: SuiteLockOptions,
+): Promise<HeldLock> {
+  const sleep = options.sleep ?? wait
+  const pollMs = options.pollMs ?? 500
+  const startedAt = performance.now()
+  let waitedOn: LockHolder | undefined
+
+  for (;;) {
+    const outcome = tryAcquire(options)
+    if (outcome.acquired) {
+      return {
+        release: outcome.release,
+        waitedOn,
+        waitedMs: waitedOn === undefined ? 0 : performance.now() - startedAt,
+      }
+    }
+    if (waitedOn === undefined && outcome.holder !== undefined) {
+      options.onWait?.(outcome.holder)
+    }
+    waitedOn = outcome.holder ?? waitedOn
+    await sleep(pollMs)
+  }
+}

package/src/intake/folder.ts

@@ -9,7 +9,7 @@ import {
   readItems,
   writeAnswerLine,
 } from '@/intake/items'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 
 export const INTAKE_REFUSALS = [
   'no-intake',

package/src/labels/map.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { resolveExisting } from '@/legacy-path'
+import { resolveExisting } from '@/roots/legacy'
 
 /**
  * Where a project declares its pull request label map.

package/src/labels/phase.ts

@@ -1,6 +1,6 @@
 import { linesOutsideFences, maskCodeSpans } from '@/markdown/scan'
-import { RECORD_ENTRIES, RECORD_ROOTS } from '@/record-root'
-import type { RecordRoot } from '@/record-root'
+import { RECORD_ENTRIES, RECORD_ROOTS } from '@/roots/record'
+import type { RecordRoot } from '@/roots/record'
 
 /**
  * The two version namespaces `standards/versioning.md` keeps apart, and why a
@@ -114,7 +114,7 @@ const ROOT_READING: Record<RecordRoot, 'whole' | 'entries'> = {
  * `.claude/` is tracked and holds `rules`, `skills`, `hooks`, and `context`,
  * so a rule path resolves in any clone and is not a board reference, and only
  * the entries the record move relocated are unreadable there. Reading the
- * roots and the relocated entries from `src/record-root.ts` is what makes a
+ * roots and the relocated entries from `src/roots/record.ts` is what makes a
  * folder added there matched here without an edit, and the list above is what
  * covers the one thing that module deliberately does not carry.
  *

package/src/migrate/record-layout.ts

@@ -40,7 +40,7 @@ import {
   slugOf,
 } from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
-import { recordDir, SCRATCH, spell, type RecordRoot } from '@/record-root'
+import { recordDir, SCRATCH, spell, type RecordRoot } from '@/roots/record'
 
 const CANON: RecordRoot = '.canon'
 const CLAUDE: RecordRoot = '.claude'

package/src/migrate/records.ts

@@ -15,7 +15,7 @@ import {
   RECORD_ENTRIES,
   RECORD_ROOTS,
   spell,
-} from '@/record-root'
+} from '@/roots/record'
 
 /** The root the entries below leave, exported so the writer can prune it. */
 export const FROM_ROOT: RecordRoot = '.claude'
@@ -26,7 +26,7 @@ const TO_ROOT: RecordRoot = '.canon'
 /**
  * Every entry the move relocates, at the name `.claude/` gave it.
  *
- * The list is `RECORD_ENTRIES`, which `record-root.ts` owns because a seed
+ * The list is `RECORD_ENTRIES`, which `roots/record.ts` owns because a seed
  * destination and a superseded-layout report ask the same question. Restating
  * it here would let the sweep and the resolver disagree about what moved.
  */
@@ -76,12 +76,12 @@ function escape(value: string): string {
  * paths a session actually opened. Rewriting either makes it testify to
  * something that never happened.
  *
- * This module and `src/record-root.ts` are two of the sources that state the old
- * root on purpose. Sweeping them turns every citation this expression is built
- * from into its own replacement, leaving a rewriter that maps `.canon/` to
- * `.canon/` and matches nothing. `src/surface-root.ts` joins the list a release
- * early, for the same reason: it spells `.claude` as data the moment it
- * exists, and excluding it later would leave one release where a records
+ * This module and `src/roots/record.ts` are two of the sources that state the
+ * old root on purpose. Sweeping them turns every citation this expression is
+ * built from into its own replacement, leaving a rewriter that maps `.canon/`
+ * to `.canon/` and matches nothing. `src/roots/surface.ts` joins the list a
+ * release early, for the same reason: it spells `.claude` as data the moment
+ * it exists, and excluding it later would leave one release where a records
  * migration in a target could rewrite the resolver that migration itself
  * depends on.
  *
@@ -112,8 +112,8 @@ const EXCLUDED_PREFIXES: readonly string[] = [
 
 const EXCLUDED_PATHS: readonly string[] = [
   'CHANGELOG.md',
-  'src/record-root.ts',
-  'src/surface-root.ts',
+  'src/roots/record.ts',
+  'src/roots/surface.ts',
 ]
 
 const EXCLUDED_SUFFIXES: readonly string[] = ['.test.ts']
@@ -171,7 +171,7 @@ export const RECORD_ONLY_ROOTS: readonly RecordRoot[] = RECORD_ROOTS.filter(
  * under `.claude/`, and a target's installed `.claude/rules/canon/core/035-tasks.md`
  * is the file the sweep exists to repoint, so a bare `.claude/` prefix strands
  * it silently. The old root is therefore entry-scoped, through `spell` so the
- * one naming variant stays decided in `record-root.ts`.
+ * one naming variant stays decided in `roots/record.ts`.
  *
  * Joined with a literal separator rather than through `join`, the way
  * `EXCLUDED_PREFIXES` already is. These are matched against what `git ls-files`

package/src/migrate/scratch-evidence.ts

@@ -34,7 +34,7 @@ import {
   slugOf,
 } from '@/migrate/evidence-ordinal'
 import { presentFolders } from '@/records/backup'
-import { recordDir, SCRATCH } from '@/record-root'
+import { recordDir, SCRATCH } from '@/roots/record'
 
 /**
  * Every folder this promotion moves, at the name it carries under scratch.

package/src/migrate/surface-roots.ts

@@ -9,7 +9,7 @@
  */
 
 import { join } from 'node:path'
-import { SURFACE_ENTRIES, spell, type SurfaceRoot } from '@/surface-root'
+import { SURFACE_ENTRIES, spell, type SurfaceRoot } from '@/roots/surface'
 
 /** The root the entries below leave. */
 export const FROM_ROOT: SurfaceRoot = '.claude'
@@ -80,8 +80,8 @@ function escape(value: string): string {
  *
  * The changelog is release history, and an eval result is a transcript of
  * paths a session actually opened; rewriting either makes it testify to
- * something that never happened. `src/surface-root.ts` and
- * `src/record-root.ts` are the two sources that spell the old root as data on
+ * something that never happened. `src/roots/surface.ts` and
+ * `src/roots/record.ts` are the two sources that spell the old root as data on
  * purpose, so sweeping either would turn the very literals this verb reads
  * into their own replacement. A hook is the third such source, guarding on a
  * `case` carrying an arm per root, so `.claude/hooks/` and the seed's copy of
@@ -102,8 +102,8 @@ const EXCLUDED_PREFIXES: readonly string[] = [
 
 const EXCLUDED_PATHS: readonly string[] = [
   'CHANGELOG.md',
-  'src/surface-root.ts',
-  'src/record-root.ts',
+  'src/roots/surface.ts',
+  'src/roots/record.ts',
 ]
 
 export function isExcludedPath(path: string): boolean {
@@ -380,7 +380,7 @@ export interface SurfaceRootsPlan {
  * moved entry, and whether its content cites one. Either alone is enough to
  * produce an entry, and a file excluded from the citation rewrite still moves
  * when its path itself is inside a moved entry, since the two entries excluded
- * today, `src/surface-root.ts` and `src/record-root.ts`, both sit outside
+ * today, `src/roots/surface.ts` and `src/roots/record.ts`, both sit outside
  * every moved entry and never take that branch in practice.
  */
 export function planSurfaceRootsMove(