rvlib-shipkit 1.3.0 → 1.4.0

package/src/serve/hub-app/palette-st.ts

@@ -1,8 +1,8 @@
-// the one picker of the page (cmd+k, keys.ts), a node of the root: the
-// home's places (home, planned, activity) first, then the shown repo's own jump
+// the one picker of the page (cmd+j, keys.ts), a node of the root: the
+// home's places (home, activity, planned, in the list's order) first, then the shown repo's own jump
 // targets, then every other house repo as a place to go. Another repo's
 // resources are never listed: a jump to a repo selects it in place, and its
-// own targets are one more cmd+k away.
+// own targets are one more cmd+j away.
 import { makeAutoObservable } from 'mobx'
 import type { HomeSt } from './home-st.ts'
 import type { Jump } from './repo-st.ts'
@@ -25,8 +25,8 @@ export class PaletteSt {
         if (st.machine == null) return []
         return [
             { id: 'place:home', label: 'home', section: 'place', face: { place: 'home' }, run: () => st.navigate('/') },
-            { id: 'place:planned', label: 'planned', section: 'place', face: { place: 'planned' }, run: () => st.navigate('/planned') },
             { id: 'place:activity', label: 'activity', section: 'place', face: { place: 'activity' }, run: () => st.navigate('/activity') },
+            { id: 'place:planned', label: 'planned', section: 'place', face: { place: 'planned' }, run: () => st.navigate('/planned') },
             { id: 'place:archived', label: 'archived', section: 'place', face: { place: 'archived' }, run: () => st.navigate('/archived') },
         ]
     }
@@ -45,7 +45,7 @@ export class PaletteSt {
     }
 
     /** ranked: prefix matches first, then substring. With no query, home,
-     *  planned and activity, then the shown repo's first targets, then every other repo,
+     *  activity and planned, then the shown repo's first targets, then every other repo,
      *  so a jump elsewhere is always in reach */
     get results(): Jump[] {
         const q = this.query.trim().toLowerCase()

package/src/serve/hub-app/palette-view.tsx

@@ -1,4 +1,4 @@
-// the one picker, cmd+k (palette-st.ts): home, planned, activity and
+// the one picker, cmd+j (palette-st.ts): home, activity, planned and
 // archived, the shown repo's targets, then every other repo. A place wears
 // its button's icon, a repo its own icon, as the project list shows them.
 import { observer } from 'mobx-react-lite'

package/src/serve/hub-app/project-list.tsx

@@ -14,7 +14,7 @@
 // in), archived shows or hides the archived repos just above the foot
 // (names only, no ⌘ number, a row opens the archived page, nothing loads),
 // the foot never moving. On the home a section of four lines on top, in the
-// repo rows' style, opens the overview, the picker, the activity and the
+// repo rows' style, opens the picker, the overview, the activity and the
 // plan, each with its shortcut at the line's end, the page shown lit. It
 // renders from the first paint with the list this browser kept, so a load
 // moves nothing.
@@ -30,11 +30,11 @@ import { cardModel, faceOf, hueOf, SORTS, type Place, type Project, type Project
 /** what the list needs of its page: the hub and the home both carry one */
 export type ListHost = { projects: ProjectsSvc }
 
-/** the lines on top of the list, in their order: the overview, the picker,
+/** the lines on top of the list, in their order: the picker, the overview,
  *  then the places, their shortcuts ⌘J ⌘K ⌘L ⌘' top to bottom */
 const PLACES: { id: Place | 'picker'; label: string; title: string }[] = [
-    { id: 'overview', label: 'overview', title: 'the overview: shipkit, every global process and every repo on this machine' },
     { id: 'picker', label: 'jump to…', title: 'jump to a page, a repo or one of its resources' },
+    { id: 'overview', label: 'overview', title: 'the overview: shipkit, every global process and every repo on this machine' },
     { id: 'activity', label: 'activity', title: 'what every repo committed lately, what it holds uncommitted, its branch and whether it is pushed' },
     { id: 'planned', label: 'planned', title: 'every check the machine runs on its own: now, next, late, and why' },
 ]

package/src/serve/hub-app/repo-st.ts

@@ -27,7 +27,7 @@ import type { HomeSt } from './home-st.ts'
 
 export type Sel = HashSel | null
 
-/** one picker target (cmd+k): run() fires the SAME action clicking would */
+/** one picker target (cmd+j): run() fires the SAME action clicking would */
 /** what a picker entry wears: a repo's own icon, or a place's button icon */
 export type JumpFace = { repo: string } | { place: 'home' | 'planned' | 'activity' | 'archived' }
 /** `key`: the shortcut that does the same, printed at the entry's end */

package/src/serve/hub-app/runs-tabs.ts

@@ -7,7 +7,7 @@ export type RunsTab = 'runs' | 'files' | 'slowest' | 'longest'
 
 /** the four lists, in tab order. `key` is what the address carries */
 export const RUNS_TABS: { key: RunsTab; label: string; help: string }[] = [
-    { key: 'runs', label: 'runs', help: `every run on record, newest first: shipkit ci, shipkit check, the hub's buttons, and the runs the plan starts. One line per run: when, who started it, what ran, its wall time, how many checks ${RAN}, how many were ${CACHED} (answered from the cache, nothing ran), and its reds. Unfold a run for one line per check, named by its title with its id as the small tag, in a box that scrolls: its reds first, then what ${RAN}, slowest first, then what was ${CACHED}. Click a check for its page. Every run in time, and how many ran at once, is the chart over the tabs: press fit for the whole record` },
+    { key: 'runs', label: 'runs', help: `every run on record, newest first: shipkit ci, shipkit check, the hub's buttons, and the runs the plan starts. One line per run: when, who started it, what ran, its wall time, how many checks ${RAN}, how many were ${CACHED} (answered from the cache, nothing ran), and its reds. Unfold a run for one line per check, named by its title with its id as the small tag, in a box that scrolls: its reds first, then what ${RAN}, slowest first, then what was ${CACHED}. Click a check for its page. Every run in time, and how many ran at once, is the chart under this list: press fit for the whole record` },
     { key: 'files', label: 'test files to fix', help: "bun test files, not checks: each file's last recorded run inside the check that ran it (test, test:<unit>), kept when a test in it failed or when it broke the quick tier budget per file. The same verdict colours the file in the tree under tests. Click a file for its page, the check tag for the check" },
     { key: 'slowest', label: 'slowest checks', help: 'the checks that cost the most when they really run: the mean and the worst of the runs that ran. A check whose worst run passed half its ceiling is flagged, because the next slow machine trips it' },
     { key: 'longest', label: 'longest runs', help: 'the invocations on record that took the longest, start to end, whatever ran them' },

package/src/serve/hub-app/timeline-view.tsx

@@ -5,9 +5,10 @@
 // Every line sits on a grid of fixed columns (the .rline grids in hub.css):
 // numbers right aligned in tabular figures, ran and cached each a column of
 // their own told apart by colour, and no separator glyph on any line. The
-// shaping is the server's (ledger/run-timeline.ts). Over the tabs, the one run
-// chart (timeline-chart.tsx) draws this repo's whole record in time; what
-// runs now in every repo is the dock at the bottom of the page.
+// shaping is the server's (ledger/run-timeline.ts). The tabs come first.
+// Under the runs tab's list, and only there, the one run chart
+// (timeline-chart.tsx) draws this repo's whole record in time; what runs now
+// in every repo is the dock at the bottom of the page.
 import { observer } from 'mobx-react-lite'
 import { useEffect } from 'react'
 import { CACHED, RAN } from '../../core/outcome-words.ts'
@@ -129,7 +130,10 @@ const RunChecks = observer(({ app, bars }: { app: RepoSt; bars: TimelineBar[] })
 })
 
 const Runs = ({ app, rows }: { app: RepoSt; rows: TimelineInvocation[] }) => (
-    rows.length === 0 ? <div className="rempty">no run on record yet</div> : <>{rows.map((inv, n) => <RunLine key={inv.runId} app={app} inv={inv} n={n} />)}</>
+    <>
+        {rows.length === 0 ? <div className="rempty">no run on record yet</div> : rows.map((inv, n) => <RunLine key={inv.runId} app={app} inv={inv} n={n} />)}
+        <RecordChart app={app} />
+    </>
 )
 
 /** what a test file to fix did: `red`, or its time against the budget */
@@ -224,7 +228,7 @@ const Tabs = observer(({ app, on }: { app: RepoSt; on: RunsTab }) => {
     )
 })
 
-/** what the chart over the tabs is, behind its (?) */
+/** what the chart under the runs list is, behind its (?) */
 export const RECORD_HELP = 'every check this repo ran, on record: the run bands, the time axis, and over the lanes how many checks ran at once, with the cap dashed and the stretches past it in orange. It opens on the last ten minutes and follows now: the right edge is the present. The wheel zooms and a drag pans; leaving the right edge stops the view where it is so a bar can be read, and ● live, the k key or panning back to the right edge follows now again. While a tooltip is open the view stands still. fit shows every run on record, and a click on a bar opens its check. What runs in every repo right now is the dock at the bottom of the page'
 
 /** this repo's whole record in time, its height held so it never jumps
@@ -246,17 +250,16 @@ export const TimelineView = observer(({ app }: { app: RepoSt }) => {
     const on = runsTab(app.sel?.t === 'item' ? app.sel.id : null)
     return (
         <div className="colcard tlcard">
-            <RecordChart app={app} />
             <Tabs app={app} on={on} />
             {t.error !== '' ? <div className="warnline">{t.error}</div> : null}
-            {d == null ? <div className="dim twait"><span className="spin" />reading the run record…</div> : (
-                <div className={`rlist ${on}`}>
-                    {on === 'runs' ? <Runs app={app} rows={d.invocations} />
+            {/* the wait line sits where the list will, so the list never moves in */}
+            <div className={`rlist ${on}`}>
+                {d == null ? <div className="dim twait"><span className="spin" />reading the run record…</div>
+                    : on === 'runs' ? <Runs app={app} rows={d.invocations} />
                         : on === 'files' ? <TestFiles app={app} rows={d.testFiles} recorded={d.suitesRecorded} />
                             : on === 'slowest' ? <Slowest app={app} rows={d.slowest} />
                                 : <Longest app={app} rows={d.longest} />}
-                </div>
-            )}
+            </div>
         </div>
     )
 })

package/src/serve/project-gutter.ts

@@ -14,11 +14,10 @@ import { DB_FILE } from '../ledger/db.ts'
 import { defaultHubPort } from './hub-port.ts'
 import { LAYOUT } from '../core/layout.ts'
 import { isArchived } from '../core/archived.ts'
+import { CLAUDE_FILES } from '../home/pm-inputs.ts'
 
 export type WiredRepo = { name: string; path: string; icon: string | null }
 
-/** the files a repo carries its includes in */
-const CLAUDE_FILES = ['CLAUDE.md', 'CLAUDE.local.md']
 
 /** the absolute md file of every `@<path>.md` include line a repo's CLAUDE
  *  files carry, in order. A sentence that mentions a path is no include */

package/src/serve/warm-cell.ts

@@ -1,12 +1,21 @@
 // one answer of a hub kept warm in memory: computed when the hub loads,
 // recomputed in the background when something says it moved (a save, a
-// stamp, its age), and served from memory. A request never pays for the
-// walk behind it, except the very first one and one that asks for `fresh`.
+// stamp, its age) while a page reads it, and served from memory. A cell
+// nobody read for WARM_WATCH_MS computes nothing on a save: its next reader
+// waits on one compute instead, so an unwatched repo costs no cpu per save.
 //
-// the one constraint a reader breaks first: `get()` answers what is in
-// memory even when it is known stale. Whoever just changed the truth (an
-// act, the end of a run) asks for `fresh`, which waits on a compute that
-// started after its call.
+// the one constraint a reader breaks first: `get()` from a watched cell
+// answers what is in memory even when it is known stale. Whoever just
+// changed the truth (an act, the end of a run) asks for `fresh`, which waits
+// on a compute that started after its call.
+
+/** a cell read within this long has a reader: a save recomputes it in the
+ *  background. Past it, nothing recomputes until a reader asks */
+export const WARM_WATCH_MS = 30_000
+
+/** a background recompute waits this many times the last compute's length
+ *  after it ended: a 1.5s answer at most every 15s, a 50ms one at once */
+export const WARM_SPACING = 10
 
 export type WarmCellOpts = {
     /** a cheap fingerprint of what the answer reads (file stats): a new one
@@ -20,6 +29,10 @@ export type WarmCellOpts = {
 
 export class WarmCell<T> {
     private value: { v: T; at: number; stamp: string } | null = null
+    /** when a reader last asked, null before any */
+    private readAt: number | null = null
+    /** when the last compute ended and how long it took */
+    private last: { end: number; ms: number } | null = null
     private running: Promise<T> | null = null
     /** bumped by invalidate: a compute that started before it is stale */
     private gen = 0
@@ -37,6 +50,7 @@ export class WarmCell<T> {
         const gen = this.gen
         const stamp = this.o.stamp?.() ?? ''
         this.runGen = gen
+        const start = this.now()
         const p = (async (): Promise<T> => {
             try {
                 // never synchronously: `running` is set before this settles
@@ -44,6 +58,8 @@ export class WarmCell<T> {
                 this.value = { v, at: this.now(), stamp }
                 return v
             } finally {
+                const end = this.now()
+                this.last = { end, ms: end - start }
                 this.running = null
                 // what said it moved while this ran is not in this answer
                 if (this.gen !== gen) this.kick()
@@ -53,11 +69,19 @@ export class WarmCell<T> {
         return p
     }
 
-    /** a compute in the background: on a failure the last answer stays */
+    /** a compute in the background, at most once per WARM_SPACING times the
+     *  last one: a kick too soon is dropped, and the next read past the gap
+     *  kicks again. On a failure the last answer stays */
     private kick(): void {
+        if (this.last != null && this.now() < this.last.end + WARM_SPACING * this.last.ms) return
         void this.run().catch(() => {})
     }
 
+    /** a reader asked within WARM_WATCH_MS */
+    private get watched(): boolean {
+        return this.readAt != null && this.now() - this.readAt < WARM_WATCH_MS
+    }
+
     get stale(): boolean {
         const v = this.value
         if (v == null) return true
@@ -68,23 +92,32 @@ export class WarmCell<T> {
     /** the answer in memory, a stale one kicking a recompute behind it. With
      *  nothing in memory yet, or `fresh`, it waits on a compute */
     async get(o: { fresh?: boolean } = {}): Promise<T> {
-        if (o.fresh === true) {
-            // a compute that started before this call may miss what the
-            // caller just changed: wait for it, then for one of our own
-            if (this.running != null) await this.running.catch(() => {})
-            return this.run()
-        }
+        const watched = this.watched
+        this.readAt = this.now()
+        if (o.fresh === true) return this.fresh()
         const v = this.value
         // nothing in memory, a failed compute included: wait on a new one
         if (v == null) return this.run()
-        if (this.running == null && (this.stale || this.gen !== this.runGen)) this.kick()
+        const moved = this.stale || this.gen !== this.runGen
+        // the first reader in a while: what is in memory may be hours old,
+        // and no save recomputed it meanwhile
+        if (moved && !watched) return this.running != null && this.runGen === this.gen ? this.running : this.fresh()
+        if (this.running == null && moved) this.kick()
         return v.v
     }
 
-    /** something this answer reads moved: recompute in the background */
+    /** a compute that started after this call: one that started before may
+     *  miss what the caller just changed, so wait for it, then for our own */
+    private async fresh(): Promise<T> {
+        if (this.running != null) await this.running.catch(() => {})
+        return this.run()
+    }
+
+    /** something this answer reads moved: recompute in the background while
+     *  a reader watches, else leave it to the next reader */
     invalidate(): void {
         this.gen++
-        if (this.running == null) this.kick()
+        if (this.running == null && this.watched) this.kick()
     }
 
     /** compute now unless an answer is already in memory: the hub's load */

package/src/suite/judge-suites.ts

@@ -18,7 +18,7 @@ export type SerialSuite = {
     why: string
 }
 export type TestsConfig = {
-    /** per suite time in the quick tier (default 2000). A suite whose wall time goes over it under the parallel run is run again alone, and fails when that run burns more CPU than this, or waits more than twice this while the machine is idle. A suite whose CPU inside the parallel run, children included, plus all its worker burned before it stays under it skips that run, unless it may wait on an idle machine or ended with a child not yet reaped. The full tier fails nothing on time */
+    /** per suite time in the quick tier (default 2000). A suite whose wall time goes over it under the parallel run is run again alone, and fails when the smaller of its CPU and its wall passes this, grown with the load share by up to half, or when its wall passes twice this, an allowance that grows with the square of the load share and has no end on a saturated machine. A suite whose CPU inside the parallel run, children included, plus all its worker burned before it stays under it skips that run, unless its wall is past that allowance or it ended with a child not yet reaped. The full tier fails nothing on time */
     budgetMs?: number
     /** suites that break the budget on purpose: the full tier runs them, the quick tier does not */
     slow?: SlowSuite[]
@@ -190,32 +190,58 @@ export const WAIT_FACTOR = 2
 /** how much more CPU the same suite burns on a saturated machine. CPU time is
  *  not load free: measured on 8 cores, one suite went from 1.0s of CPU idle to
  *  1.35 to 1.5s with the cores saturated (load 7 to 19), and did not grow past
- *  that. So a loaded machine fails a suite past the budget times this */
+ *  that. So the CPU allowance grows with the load share up to this factor */
 export const LOADED_CPU_FACTOR = 1.5
+
+/** how much of the machine the other processes took, 0 idle to 1 saturated:
+ *  the one load measure every verdict here reads, so no verdict has a step */
+export const loadShare = (load: MachineLoad): number => (load.cores > 0 ? Math.min(1, Math.max(0, load.load1 / load.cores)) : 0)
+/** the CPU a suite may burn at this load: the budget, plus the measured
+ *  inflation in proportion to how saturated the machine is */
+export const cpuAllowance = (budgetMs: number, load: MachineLoad): number => budgetMs * (1 + (LOADED_CPU_FACTOR - 1) * loadShare(load))
+/** the wall a suite may take before it reads as a WAIT: WAIT_FACTOR times
+ *  the budget on an idle machine, grown with the square of the load share,
+ *  and without end once the machine is saturated. A wall on a busy machine
+ *  is the machine's (measured: 11 to 19s for suites burning 1s of CPU at
+ *  load 20.5 on 8 cores, far past any fair share), so only a quiet machine
+ *  can show a suite that sleeps; the ramp keeps the verdict continuous */
+export const waitAllowance = (budgetMs: number, load: MachineLoad): number => {
+    const free = 1 - loadShare(load) ** 2
+    return free <= 0 ? Infinity : (budgetMs * WAIT_FACTOR) / free
+}
 /** `ms` is the time the verdict used: cpu, or wall for a wait or when no cpu figure exists */
 export type Confirmed = { file: string; ms: number; wallMs: number; cpuMs: number | null; over: 'cpu' | 'wait' | 'wall' | null }
 
-/** the verdict on each suspect once it ran alone. A wall time carries the load
- *  of every other process on the machine, and another gate can triple it, so
- *  the budget judges CPU: what the suite itself burned, which load moves by
- *  a bounded factor only (LOADED_CPU_FACTOR). Wall time still fails a suite
- *  far over the budget while the machine was idle, because only then is the
- *  wait the suite's own */
+/** the verdict on each suspect once it ran alone, continuous in the load.
+ *  A wall time carries the load of every other process on the machine, so
+ *  the budget judges CPU, against an allowance that grows with the load share
+ *  (cpuAllowance). A suite is charged the SMALLER of its CPU and its wall:
+ *  JS runs on one thread, so CPU above the wall is bun's GC and JIT threads
+ *  or children running side by side, time nobody waits on. A wall past its
+ *  wait allowance fails as a wait (waitAllowance), never on a busy machine */
 export function confirmOver(suspects: Timed[], alone: Record<string, AloneRun>, budgetMs: number, load: MachineLoad): { over: Confirmed[]; cleared: Confirmed[] } {
     const byFile = new Map(Object.entries(alone).map(([f, run]) => [normSuitePath(f), run]))
-    const idle = load.load1 < load.cores
     const judged = suspects.map((t): Confirmed => {
         const run = byFile.get(t.file)
         const wallMs = run?.wallMs ?? t.ms
         const cpuMs = run?.cpuMs ?? null
         if (cpuMs == null) return { file: t.file, ms: wallMs, wallMs, cpuMs, over: wallMs > budgetMs ? 'wall' : null }
-        if (cpuMs > budgetMs * (idle ? 1 : LOADED_CPU_FACTOR)) return { file: t.file, ms: cpuMs, wallMs, cpuMs, over: 'cpu' }
-        if (idle && wallMs > budgetMs * WAIT_FACTOR) return { file: t.file, ms: wallMs, wallMs, cpuMs, over: 'wait' }
-        return { file: t.file, ms: cpuMs, wallMs, cpuMs, over: null }
+        const charged = Math.min(cpuMs, wallMs)
+        if (charged > cpuAllowance(budgetMs, load)) return { file: t.file, ms: charged, wallMs, cpuMs, over: 'cpu' }
+        if (wallMs > waitAllowance(budgetMs, load)) return { file: t.file, ms: wallMs, wallMs, cpuMs, over: 'wait' }
+        return { file: t.file, ms: charged, wallMs, cpuMs, over: null }
     })
     return { over: judged.filter((c) => c.over != null), cleared: judged.filter((c) => c.over == null) }
 }
 
+const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
+
+/** the line a confirmed suite fails with */
+export const overWords = (c: Confirmed, load: MachineLoad, budgetMs: number = DEFAULT_BUDGET_MS): string =>
+    c.over === 'cpu' ? `${c.file} ${secs(c.cpuMs ?? c.ms)} of CPU (${secs(c.wallMs)} wall)`
+        : c.over === 'wait' ? `${c.file} ${secs(c.wallMs)} wall at load ${load.load1.toFixed(1)} on ${load.cores} cores, past its ${secs(waitAllowance(budgetMs, load))} wait allowance, with ${secs(c.cpuMs ?? 0)} of CPU: it waits (a timer, a sleep, a poll)`
+            : `${c.file} ${secs(c.wallMs)} wall (no CPU figure)`
+
 /** how the parallel phase's workers hand the runner the CPU of each suite
  *  (suite-cpu-preload.ts writes it, readPhaseCpu reads it) */
 export const SUITE_CPU_ENV = 'SHIPKIT_SUITE_CPU'
@@ -253,16 +279,15 @@ export function readPhaseCpu(text: string, cwd: string): { ran: string[]; cpu: R
  *  what the worker computed by the suite's end, its whole CPU before the
  *  suite (priorMs) plus what the suite burned, and sharing the machine only
  *  raises CPU, so a suspect whose sum is inside the budget is inside it alone
- *  too. A suspect with no figure (a child not yet reaped) runs alone. Only the alone run can see a WAIT, so a
- *  suite past WAIT_FACTOR times the budget in wall time still gets it while
- *  the machine is idle */
+ *  too. A suspect with no figure (a child not yet reaped) runs alone. Only the
+ *  alone run can see a WAIT, so a suite whose wall is past its wait
+ *  allowance still gets it */
 export function aloneRunsNeeded(suspects: Timed[], parallelCpu: Record<string, PhaseCpu>, budgetMs: number, load: MachineLoad): { rerun: Timed[]; cleared: Confirmed[] } {
-    const idle = load.load1 < load.cores
     const rerun: Timed[] = []
     const cleared: Confirmed[] = []
     for (const t of suspects) {
         const f = parallelCpu[t.file]
-        const mayWait = idle && t.ms > budgetMs * WAIT_FACTOR
+        const mayWait = t.ms > waitAllowance(budgetMs, load)
         if (f != null && f.cpuMs + f.priorMs <= budgetMs && !mayWait) cleared.push({ file: t.file, ms: f.cpuMs, wallMs: t.ms, cpuMs: f.cpuMs, over: null })
         else rerun.push(t)
     }

package/src/suite/suite-cli.ts

@@ -16,7 +16,7 @@ import { killTree } from '../core/spawn-timeout.ts'
 import { parallelCap } from '../core/parallel.ts'
 import { poolDir, poolOccupancy } from '../core/slots.ts'
 import { keepTimings, seedTimings, timingsHome } from './kept-timings.ts'
-import { aloneRunsNeeded, bunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, WAIT_FACTOR, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers } from './judge-suites.ts'
+import { aloneRunsNeeded, bunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, overWords, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers } from './judge-suites.ts'
 
 type Phase = { code: number; signal: string | null; stalled: boolean; out: string; timings: Record<string, number>; cpuMs: number | null }
 
@@ -63,11 +63,6 @@ const CPU_PRELOAD = join(import.meta.dir, 'suite-cpu-preload.ts')
 
 const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
 
-const overWords = (c: Confirmed): string =>
-    c.over === 'cpu' ? `${c.file} ${secs(c.ms)} of CPU (${secs(c.wallMs)} wall)`
-        : c.over === 'wait' ? `${c.file} ${secs(c.wallMs)} wall on an idle machine, more than ${WAIT_FACTOR}x the budget, with ${secs(c.cpuMs ?? 0)} of CPU: it waits (a timer, a sleep, a poll)`
-            : `${c.file} ${secs(c.wallMs)} wall (no CPU figure)`
-
 /** the suite FILES a phase names: a flag is not a file, and the repo's own
  *  `bun test` arguments are not files this runner put there */
 const phaseFiles = (phase: string[], rawArgs: string[]): string[] => phase.filter((a) => !a.startsWith('-') && !rawArgs.includes(a))
@@ -117,6 +112,9 @@ export async function suiteCli(argv: string[]): Promise<number> {
         const kept = timed && parallel ? timingsHome(process.cwd(), unit) : null
         if (kept != null) seedTimings(kept, join(dir, 'parallel.json'))
         const cpuFile = timed && parallel ? join(dir, 'cpu.tsv') : null
+        // the load BEFORE this run: read after it, the one minute average
+        // carries this run's own parallel phase, which is no other process
+        const load = machineLoad()
         const p1At = Date.now()
         const p1 = await runPhase(plan.parallel, timed ? join(dir, 'parallel.json') : null, ceilingMs, tmp, true, cpuFile)
         const p1Ms = Date.now() - p1At
@@ -148,7 +146,6 @@ export async function suiteCli(argv: string[]): Promise<number> {
         // before it can fail the task. One at a time: four alone runs side by
         // side each burned about 40% more CPU than one alone (8 cores)
         const aloneRuns: Record<string, AloneRun> = {}
-        const load = machineLoad()
         const parallelCpu = phaseCpu.cpu
         const { rerun, cleared: clearedInPhase } = aloneRunsNeeded(judged.over, parallelCpu, budget, load)
         const aloneAt = Date.now()
@@ -224,7 +221,7 @@ export async function suiteCli(argv: string[]): Promise<number> {
             ...(!vacuous && (failedTests > 0 || (phases.some((p) => p.code !== 0 && p.signal == null) && killed.length === 0))
                 ? [`FAIL: ${failedTests} test(s) failed, Ran ${ran} tests${slowest}`] : []),
             ...(over.length > 0
-                ? [`FAIL: ${over.length} suite(s) over the ${budget}ms budget: ${over.map(overWords).join(', ')} (run alone, load ${load.load1.toFixed(1)} on ${load.cores} cores). Make each fast, or declare it in ${declaredIn}.slow with what it catches and why it cannot be fast`]
+                ? [`FAIL: ${over.length} suite(s) over the ${budget}ms budget: ${over.map((c) => overWords(c, load, budget)).join(', ')} (run alone, load ${load.load1.toFixed(1)} on ${load.cores} cores before the run). Make each fast, or declare it in ${declaredIn}.slow with what it catches and why it cannot be fast`]
                 : []),
         ]
         // the most actionable failure prints LAST, where the gate reads its headline

package/src/wiki/lint-md.ts

@@ -6,6 +6,7 @@ import { scanMd, type MdDanglingRef, type ScanMdConfig } from 'rvlib-shipkit/src
 export type MdLintReport = {
     index: string | null // resolved entrypoint (null = neither index.md nor README.md found)
     files: number
+    pages: string[] // every scanned .md file, scan-root relative
     orphans: string[] // .md files with no path from the entrypoint
     dangling: MdDanglingRef[] // refs whose target does not exist in the scan
     ok: boolean
@@ -17,6 +18,7 @@ export function lintMd(cfg: ScanMdConfig): MdLintReport {
     return {
         index: scan.index,
         files: scan.graph.nodes.length,
+        pages: scan.graph.nodes.map((n) => n.id),
         orphans,
         dangling: scan.dangling,
         ok: scan.index != null && orphans.length === 0 && scan.dangling.length === 0,

package/src/wiki/scan-md.ts

@@ -4,10 +4,14 @@
 //   → path.md          lazy  — resolved from the scan root, then file-relative
 //   [text](path.md)    lazy  — file-relative
 //   `path.md`          lazy  — file-relative, then from the scan root
+//   [text](dir/)       lazy  — a folder: an edge to every page under it
+//   `dir/`             lazy  — the same, from a backtick mention
+// A ref that leaves the scan root but stays under `boundary` is checked on
+// disk: no edge, and dangling only when the target is really missing.
 // Depth = 0-1 BFS from the index (eager edge keeps depth, lazy adds 1);
 // unreachable files stay in the graph with no depth (lint-md.ts turns those,
 // plus dangling refs, into failures — the graph itself is a viewer).
-import { readdirSync, readFileSync, statSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { basename, dirname, join, relative, resolve } from 'path'
 import type { MdEdge, MdGraph, MdNode } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
@@ -15,6 +19,7 @@ export type ScanMdConfig = {
     root: string // absolute dir to scan
     index?: string // root-relative entry the BFS starts from (default: index.md AND README.md, both)
     skipDirs?: string[] // dir names to skip on top of node_modules/.git/dist/tmp
+    boundary?: string // absolute dir enclosing root (a repo): refs leaving root but staying here resolve on disk
 }
 
 export type MdDanglingRef = { from: string; token: string } // an @/→/[](…) ref whose target is not in the scan
@@ -46,13 +51,33 @@ export function scanMd(cfg: ScanMdConfig): MdScan {
     // writers inside a scanned dir often name paths from the REPO root
     // ("agent/architecture.md" while scanning agent/) — accept that form too
     const rootBase = `${basename(cfg.root)}/`
-    const resolveRef = (fromRel: string, token: string): string | null => {
-        const cands = [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]
-        if (token.startsWith(rootBase)) cands.push(resolve(cfg.root, token.slice(rootBase.length)))
-        for (const cand of cands) {
+    const cands = (fromRel: string, token: string): string[] => {
+        const out = [resolve(join(cfg.root, dirname(fromRel)), token), resolve(cfg.root, token)]
+        if (token.startsWith(rootBase)) out.push(resolve(cfg.root, token.slice(rootBase.length)))
+        return out
+    }
+    // pages a ref reaches: one file, every page under a folder (never the
+    // root itself), or none. `onDisk` = the target exists in the boundary
+    // outside the scan, which is resolved but carries no edge.
+    type Hit = { to: string[]; onDisk: boolean }
+    const resolveRef = (fromRel: string, token: string): Hit | null => {
+        const folder = token.endsWith('/')
+        for (const cand of cands(fromRel, token)) {
             const rel = relative(cfg.root, cand)
-            if (!rel.startsWith('..') && inGraph.has(rel)) return rel
+            if (rel.startsWith('..')) continue
+            if (!folder && inGraph.has(rel)) return { to: [rel], onDisk: false }
+            if (folder && rel === '') return { to: [], onDisk: false }
+            if (folder) {
+                const under = files.filter((f) => f.startsWith(`${rel}/`))
+                if (under.length > 0) return { to: under, onDisk: false }
+                if (existsSync(cand)) return { to: [], onDisk: true }
+            }
         }
+        if (cfg.boundary == null) return null
+        const cand = resolve(join(cfg.root, dirname(fromRel)), token)
+        const inRoot = !relative(cfg.root, cand).startsWith('..')
+        const inBoundary = !relative(cfg.boundary, cand).startsWith('..')
+        if (!inRoot && inBoundary && existsSync(cand)) return { to: [], onDisk: true }
         return null
     }
     const edgesOf = (rel: string): MdEdge[] => {
@@ -64,14 +89,16 @@ export function scanMd(cfg: ScanMdConfig): MdScan {
         // strict: @/→/[](…) are deliberate wiki refs — a miss is a dangling ref.
         // Backtick spans mention paths casually (other repos, deleted examples) — resolve or ignore, never fail.
         const push = (token: string, eager: boolean, strict: boolean) => {
-            const to = resolveRef(rel, token)
-            if (to != null && to !== rel) out.push({ from: rel, to, eager })
-            else if (to == null && strict) dangling.push({ from: rel, token })
+            const hit = resolveRef(rel, token)
+            if (hit == null) { if (strict) dangling.push({ from: rel, token }); return }
+            for (const to of hit.to) if (to !== rel) out.push({ from: rel, to, eager })
         }
-        for (const m of prose.matchAll(/(?:^|[\s(])@([\w][\w./-]*\.md)/gm)) push(m[1]!, true, true)
+        for (const m of prose.matchAll(/(?:^|[\s(])@((?:\.{1,2}\/)*[\w][\w./-]*\.md)/gm)) push(m[1]!, true, true)
         for (const m of prose.matchAll(/→\s*([\w][\w./-]*\.md)\b/g)) push(m[1]!, false, true)
         for (const m of prose.matchAll(/\]\(([^)\s:]+\.md)\)/g)) push(m[1]!, false, true)
+        for (const m of prose.matchAll(/\]\(([^)\s:]*\/)\)/g)) push(m[1]!, false, true)
         for (const s of spans) for (const m of s.matchAll(/[\w][\w./-]*\.md/g)) push(m[0], false, false)
+        for (const s of spans) for (const m of s.matchAll(/(?:^|\s)([\w.][\w./-]*\/)(?=$|[\s<*])/g)) push(m[1]!, false, false)
         return out
     }
     const dangling: MdDanglingRef[] = []