rvlib-shipkit 1.8.0 → 2.0.0

package/src/cli/cmd_Hooks.ts

@@ -4,9 +4,13 @@ import { Command, Option } from 'clipanion'
 import { hookBinInvocation, installHooks, listGates, preCommitChecks, runCommitMsg, runPreCommit, type GateOutcome } from '../hooks/run-hooks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
+// a gate that passed prints only what still needs a reader (a WARN, a waived
+// hit), so a clean commit costs one line, not one per gate
 const report = (out: GateOutcome[], write: (s: string) => void): number => {
-    for (const g of out) for (const l of g.lines) write(`${l}\n`)
-    return out.every((g) => g.ok) ? 0 : 1
+    for (const g of out) for (const l of g.lines) if (!g.ok || !l.startsWith('ok: ')) write(`${l}\n`)
+    const ok = out.every((g) => g.ok)
+    if (ok) write(`ok: ${out.length} commit gate(s) clean\n`)
+    return ok ? 0 : 1
 }
 
 export class HooksInstallCommand extends Command {

package/src/cli/cmd_Init.ts

@@ -8,7 +8,7 @@ export class InitCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'wire the current directory as a shipkit repo, like git init',
+        description: 'wire this dir as a shipkit repo, like git init: a private github repo and a push unless --no-github',
         details: 'wire THE CURRENT DIRECTORY as a shipkit repo, like git init: cwd only, never creates a project dir. scaffolds repo.config.ts + ci/check/contracts package.json scripts + the create-only .vscode/ that starts the watchers and the hub on folder open, prints how the floor resolved, and runs the bootstrap chain around it: git init, then first commit + PRIVATE github repo + push once the scaffold is in. Idempotent on an already-wired repo. To create or adopt ~/dev/<name> from anywhere: `shipkit start <name>`',
         examples: [
             ['wire the repo you are standing in', 'sk init'],

package/src/cli/cmd_Serve.ts

@@ -1,5 +1,4 @@
-// shipkit serve — the ONE hub server per repo (one vscode folder-open task,
-// clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
+// shipkit serve — the ONE hub server per repo (clickable URLs). Thin clipanion surface; logic in serve/run-serve.ts.
 import { Command, Option } from 'clipanion'
 
 export class ServeCommand extends Command {

package/src/cli/cmd_Start.ts

@@ -9,7 +9,7 @@ export class StartCommand extends Command {
 
     static override usage = Command.Usage({
         category: 'Setup',
-        description: 'create or enter ~/dev/<name> from anywhere, ready to work in',
+        description: 'create or enter ~/dev/<name>, ready to work in: a private github repo and a push unless --no-github',
         details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],

package/src/cli.ts

@@ -26,7 +26,6 @@ import { KeysCommand } from './cli/cmd_Keys.ts'
 import { MvCommand } from './cli/cmd_Mv.ts'
 import { NeedsCommand } from './cli/cmd_Needs.ts'
 import { PbCollectionCommand } from './cli/cmd_Pb.ts'
-import { ProseCommand } from './cli/cmd_Prose.ts'
 import { ReflectCommand } from './cli/cmd_Reflect.ts'
 import { ReleaseCommand } from './cli/cmd_Release.ts'
 import { ReleasesCommand } from './cli/cmd_Releases.ts'
@@ -91,7 +90,6 @@ export function buildCli(): Cli {
     cli.register(NeedsCommand)
     cli.register(FleetCommand)
     cli.register(PbCollectionCommand)
-    cli.register(ProseCommand)
     cli.register(SmokeCommand)
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
@@ -125,8 +123,8 @@ if (import.meta.main) {
     const argv = aliasArgs(process.argv.slice(2))
     const { handoff } = await import('./home/handoff.ts')
     handoff(argv)
-    const { useOneLib } = await import('./core/one-lib.ts')
-    useOneLib()
+    const { installOneLib } = await import('./core/one-lib.ts')
+    installOneLib()
     const { autostart } = await import('./home/autostart.ts')
     await autostart(argv)
     void buildCli().runExit(argv)

package/src/collections/providers.ts

@@ -413,7 +413,7 @@ export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit |
         contractsCollection(root, c),
         asksCollection(root, c),
         credsCollection(root, c, { verdicts: () => verdictsOf(checks) }),
-        mediaKitCollection(root, kit),
+        mediaKitCollection(root, c.serve?.assets === false ? null : kit),
         socialPostsCollection(root),
         reflectionsCollection(root),
         testsCollection(root, c),

package/src/core/budget.ts

@@ -6,16 +6,14 @@
 import { availableParallelism, loadavg } from 'os'
 import type { MachineLoad } from '../suite/judge-suites.ts'
 
-/** an in process body, a rule or a page check. Read off a run record of 64
- *  such checks: the median rule answers in under 50ms, 55 of them stay under
- *  2s at their 90th percentile, and the few past it shell out to a tool */
-export const IN_PROCESS_BUDGET_MS = 2_000
+/** an in process body, a rule or a page check: the house bar is under 1 s
+ *  (identity/how-we-work.md, Velocity). The median rule answers in under 50ms */
+export const IN_PROCESS_BUDGET_MS = 1_000
 
 /** a subprocess (a build step, a test suite, a `cmd` check) or a world probe
- *  (a `ttl` check, or a `never:` one, whose answer lives outside the repo).
- *  Read off the same record: every typecheck stays under 6s at its 90th
- *  percentile, and the quick test suites under 6s but one */
-export const SUBPROCESS_BUDGET_MS = 10_000
+ *  (a `ttl` check, or a `never:` one, whose answer lives outside the repo):
+ *  the house ceiling is 5 s, and one over it is a defect to fix */
+export const SUBPROCESS_BUDGET_MS = 5_000
 
 /** what a check declares about itself that picks its default. `world`: it
  *  declares `ttl` or `never`, so it reads the world rather than the repo */

package/src/core/bun-builtins.ts

@@ -0,0 +1,36 @@
+// bun's own linter as the default lint slot, and bun's formatter as the
+// manual `bun fmt` (never a gate step). A repo opts in by declaring the tool's
+// section in bunfig.toml: the section is where its config lives.
+//
+// bun before 1.4.4 has neither command, and there `bun lint` falls through to
+// the package.json `lint` script. A script that calls `bun lint` then calls
+// itself forever, so an old bun gets a loud refusal instead of a spawn. The
+// lint slot runs through core/bun-tool-cli.ts, which keeps a same-named script out.
+import { fileURLToPath } from 'url'
+
+export type BunTool = 'lint' | 'fmt'
+
+export const BUN_TOOLS_SINCE = '1.4.4'
+
+/** does the bun running shipkit ship `bun lint` and `bun fmt` */
+export const bunHasTools = (version: string = Bun.version): boolean => Bun.semver.order(version.replace(/-.*$/, ''), BUN_TOOLS_SINCE) >= 0
+
+const header = (tool: BunTool): RegExp => new RegExp(`^\\s*\\[${tool}(?:\\.[^\\]]+)?\\]\\s*(?:#.*)?$`)
+
+/** does this bunfig.toml text declare `[lint]` / `[fmt]` (or a subtable of it) */
+export function bunfigDeclares(bunfig: string | null, tool: BunTool): boolean {
+    return bunfig != null && bunfig.split('\n').some((l) => header(tool).test(l))
+}
+
+/** why this bun cannot run the tool, or null when it can */
+export function bunToolRefusal(tool: BunTool, version: string = Bun.version): string | null {
+    return bunHasTools(version) ? null : `bunfig.toml declares [${tool}] and bun ${version} has no \`bun ${tool}\` (it ships in ${BUN_TOOLS_SINCE}): run \`bun upgrade --canary\``
+}
+
+/** the argv the lint slot runs: the built-in, through the runner that keeps a
+ *  same-named package.json script out of its way. The repo's vendored dirs
+ *  are never walked */
+export function bunLintCmd(vendored: readonly string[] = []): string[] {
+    const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/core/bun-tool-cli.ts'))
+    return [process.execPath, cli, 'lint', '--format', 'unix', ...vendored.map((d) => `--ignore-pattern=${d}/**`)]
+}

package/src/core/bun-tool-cli.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+// runs `bun lint` as the BUILT-IN, whatever package.json holds.
+// bun runs a script of the same name in its place, flags and all, unless the
+// call says it is that script: `npm_lifecycle_event` names the tool, and
+// `npm_package_json` is absent or names this manifest by its resolved path.
+// A run started under another package's `bun run` inherits that package's
+// path, so it is dropped here (measured, bun 1.4.4).
+import { bunToolRefusal } from './bun-builtins.ts'
+
+const [tool, ...args] = process.argv.slice(2)
+if (tool !== 'lint') {
+    console.error(`bun-tool-cli: expected lint, got ${tool ?? 'nothing'}`)
+    process.exit(2)
+}
+const refused = bunToolRefusal(tool)
+if (refused != null) {
+    console.error(refused)
+    process.exit(1)
+}
+const env: Record<string, string | undefined> = { ...process.env, npm_lifecycle_event: tool }
+delete env.npm_package_json
+const p = Bun.spawnSync([process.execPath, tool, ...args], { stdio: ['inherit', 'inherit', 'inherit'], env })
+process.exit(p.exitCode ?? 1)

package/src/core/canonical-scripts.ts

@@ -36,10 +36,12 @@ export function conditionalBodies(_opts: ScriptStyle = {}): Record<string, strin
 // used to hold moves to `<name>:raw`, which is what shipkit itself runs and
 // what an agent uses to iterate on one repro file.
 //
-// only these three. `imports:check` and `cycles` are shipkit's own vocabulary
-// (nobody reaches for them by reflex) and `fmt` is the slot shipkit's fix pass
-// invokes, so routing it would make the fixer call itself.
-export const ROUTED_SCRIPTS = ['test', 'lint', 'typecheck'] as const
+// only these two. `imports:check` and `cycles` are shipkit's own vocabulary
+// (nobody reaches for them by reflex), `fmt` is a manual tool no gate runs,
+// and `lint` is
+// `bun lint` itself: a `lint` script would shadow the built-in, which lints a
+// whole repo in well under a second, with nothing for a cache to save.
+export const ROUTED_SCRIPTS = ['test', 'typecheck'] as const
 
 export const RAW_SUFFIX = ':raw'
 

package/src/core/check-ctx.ts

@@ -1,7 +1,8 @@
 // CheckCtx — the ONE parameter a check body receives, and its only door to the
 // repo. Four parts:
 //
-//   report  c.ok / note / warn / fail / unreachable, the wire lines (wire.ts)
+//   report  c.ok / note / warn / fail / unreachable, the wire lines (wire.ts),
+//           a finding with its site, which an in-file directive can waive
 //   where   c.root, c.config, c.frozen
 //   reads   c.read / json / exists / isLink / list / entries, each recorded with what it saw, and
 //           c.use(scan) for a scan every check of the pass shares (scan.ts)
@@ -27,7 +28,12 @@ import { normalizeInput, WHOLE_TREE } from '../ledger/git-scan.ts'
 import { shipkitRoot } from './git-root.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Scan } from '../scan.ts'
-import type { Line } from './wire.ts'
+import { siteText, type Line, type Site } from './wire.ts'
+import { DIRECTIVE_MARK, parseDirectives, reaches, spell, type Directive } from './waivers.ts'
+
+/** what `c.warn` and `c.fail` take after the message: the fix pointer alone,
+ *  or the pointer and the site the finding sits at */
+export type FindingMore = string | { fix?: string; at?: Site }
 
 // thrown by t.fetch on 429: no answer, so the body runner (check.ts
 // runCheckBody) reports it as unreachable, never as a FAIL. It knows it by
@@ -56,6 +62,16 @@ export class CheckCtx {
     /** why the reads cannot describe this answer (it reached the world), null
      *  while they can */
     untracked: string | null = null
+    /** the check this context reports for, set by the body runner. A
+     *  directive waives a site only when it names this id */
+    checkId: string | null = null
+    /** the text of every repo file read here that carries a directive mark,
+     *  by path: what a waiver and the unused directive scan parse */
+    readonly marked = new Map<string, string>()
+    private readonly parsed = new Map<string, Directive[]>()
+    private readonly siteFiles = new Set<string>()
+    private readonly waived: { text: string; at: Site; by: string; reason: string }[] = []
+    private readonly usedDirectives = new Set<string>()
 
     constructor(
         /** the runner pass this body runs in. Absent for a context that only
@@ -73,19 +89,94 @@ export class CheckCtx {
     note(msg: string): void { this.lines.push({ kind: 'note', text: msg }) }
     /** a WARN that came back from something we could not reach — no answer, so
      *  nothing to remember */
-    unreachable(msg: string, fix?: string): void {
+    unreachable(msg: string, more?: FindingMore): void {
         this.unmeasured = true
-        this.warn(msg, fix)
+        this.warn(msg, more)
     }
-    warn(msg: string, fix?: string): void {
+    /** a defect that does not stop you. `more` is the fix pointer, or
+     *  `{ fix, at }` with the site, which a directive in that file can waive */
+    warn(msg: string, more?: FindingMore): void {
+        const f = this.finding(msg, more)
+        if (f == null) return
         this.warned = true
-        this.lines.push({ kind: 'warn', text: msg })
-        if (fix != null) this.lines.push({ kind: 'fix-warn', text: fix })
+        this.lines.push({ kind: 'warn', text: f.text, ...(f.at == null ? {} : { at: f.at }) })
+        if (f.fix != null) this.lines.push({ kind: 'fix-warn', text: f.fix })
     }
-    fail(msg: string, fix?: string): void {
+    /** broken. `more` is the fix pointer, or `{ fix, at }` with the site,
+     *  which a directive in that file can waive */
+    fail(msg: string, more?: FindingMore): void {
+        const f = this.finding(msg, more)
+        if (f == null) return
         this.failed = true
-        this.lines.push({ kind: 'fail', text: msg })
-        if (fix != null) this.lines.push({ kind: 'fix-fail', text: fix })
+        this.lines.push({ kind: 'fail', text: f.text, ...(f.at == null ? {} : { at: f.at }) })
+        if (f.fix != null) this.lines.push({ kind: 'fix-fail', text: f.fix })
+    }
+
+    // ── waivers (core/waivers.ts owns the grammar) ────────────────────────
+    /** the finding as it prints, or null when a directive waived its site.
+     *  A message that does not name its file gets the site in front */
+    private finding(msg: string, more: FindingMore | undefined): { text: string; fix?: string; at?: Site } | null {
+        const { fix, at } = typeof more === 'object' ? more : { fix: more, at: undefined }
+        if (at == null) return { text: msg, fix }
+        const text = msg.includes(at.file) ? msg : `${siteText(at)}: ${msg}`
+        const by = this.waiverFor(at)
+        if (by == null) return { text, fix, at }
+        this.waived.push({ text, at, by: `${at.file}:${by.line}`, reason: by.reason ?? '' })
+        return null
+    }
+    /** the directive that waives this site for this check. The file is read
+     *  through `c`, so it joins the answer's key: a directive added or
+     *  removed afterwards asks the question again */
+    private waiverFor(at: Site): Directive | null {
+        if (this.checkId == null || this.pass == null || isAbsolute(at.file)) return null
+        let rel: string
+        try { rel = this.rel(at.file) } catch { return null }
+        this.siteFiles.add(rel)
+        this.read(rel)
+        for (const d of this.directivesIn(rel)) {
+            if (d.reason == null || !d.ids.includes(this.checkId) || !reaches(d, at.line)) continue
+            this.usedDirectives.add(`${rel}:${d.line}`)
+            return d
+        }
+        return null
+    }
+    private directivesIn(file: string): Directive[] {
+        const text = this.marked.get(file)
+        if (text == null) return []
+        let ds = this.parsed.get(file)
+        if (ds == null) this.parsed.set(file, (ds = this.pass?.directives(file, text) ?? parseDirectives(file, text)))
+        return ds
+    }
+    /** after the body, once: count the waived sites, and WARN on every
+     *  directive naming this check, in a file it read, that waived nothing
+     *  or gave no reason. A directive for a retired id, or in a file no
+     *  check reads any more, is nobody's to report */
+    settleWaivers(): void {
+        const id = this.checkId
+        if (id == null) return
+        const loud = (at: Site, text: string, fix: string): void => {
+            this.warned = true
+            this.lines.push({ kind: 'warn', text: `${siteText(at)}: ${text}`, at }, { kind: 'fix-warn', text: fix })
+        }
+        // a site, not a finding: one line can hold several findings
+        const n = new Set(this.waived.map((w) => siteText(w.at))).size
+        if (n > 0) this.lines.push({ kind: 'skip', text: `${n === 1 ? '1 site waived in its file' : `${n} sites waived in their files`} (--verbose lists them)`, waiver: 'count' })
+        for (const w of this.waived) this.lines.push({ kind: 'skip', text: `waived by ${w.by} (${w.reason}): ${w.text}`, at: w.at, waiver: 'site' })
+        for (const file of this.marked.keys())
+            for (const d of this.directivesIn(file)) {
+                if (!d.ids.includes(id)) continue
+                const at = { file, line: d.line }
+                if (d.reason == null) loud(at, `\`${spell(d, id)}\` gives no reason after \` -- \`, so it waives nothing`, `say why the site is fine: \`${spell(d, id)} -- <reason>\``)
+                else if (!this.usedDirectives.has(`${file}:${d.line}`))
+                    loud(at, `\`${spell(d, id)}\` waives nothing ${d.scope === 'file' ? 'in this file' : `on line ${d.scope === 'line' ? d.line : d.line + 1}`}`, 'delete the directive, or move it onto the site it was written for')
+            }
+    }
+    /** every file whose directives this answer depends on: the files of its
+     *  findings, and the files carrying a directive that names it */
+    waiverFiles(): string[] {
+        const id = this.checkId
+        const named = id == null ? [] : [...this.marked.keys()].filter((f) => this.directivesIn(f).some((d) => d.ids.includes(id)))
+        return [...new Set([...this.siteFiles, ...named])].sort()
     }
 
     // ── where ─────────────────────────────────────────────────────────────
@@ -99,6 +190,7 @@ export class CheckCtx {
      *  it and none that did not */
     get config(): RepoConfig {
         const p = this.repo('config')
+        if (!p.recordsConfig) return p.config
         const deps = p.configReads()
         for (const [f, oid] of deps.files) this.reads.file(f, oid)
         if (deps.untracked != null && this.untracked == null) {
@@ -150,6 +242,7 @@ export class CheckCtx {
             return null
         }
         this.reads.file(p, blobOid(bytes))
+        if (!isAbsolute(p) && bytes.includes(DIRECTIVE_MARK)) this.marked.set(p, bytes.toString('utf8'))
         return bytes
     }
     /** a repo-relative json file, parsed. null when absent, and a parse error
@@ -206,6 +299,7 @@ export class CheckCtx {
         const s = pass.scan(scan, () => new CheckCtx(pass))
         const value = await s.value
         this.reads.merge(s.ctx.reads)
+        for (const [f, text] of s.ctx.marked) this.marked.set(f, text)
         if (s.ctx.untracked != null) this.untrack(s.ctx.untracked)
         return value
     }

package/src/core/check-file-names.ts

@@ -83,9 +83,8 @@ export type LegacyCheck = {
 
 // read without importing: checks run as subprocesses, and discovery must stay
 // pure-fs. `export const blocking = true` (or false), nothing cleverer.
-// the tail is the gate's OWN formatter: oxfmt terminates every statement, and
-// the fix pass runs it, so a reader that refuses a semicolon refuses the shape
-// the gate itself just wrote.
+// the tail takes what a formatter on its defaults writes: it terminates every
+// statement, so a reader that refuses a semicolon refuses a formatted file.
 const TAIL = String.raw`(?:\s+as\s+const)?\s*;?\s*$`
 const BLOCKING_RE = new RegExp(String.raw`^\s*export\s+const\s+blocking\s*(?::\s*boolean\s*)?=\s*(true|false)` + TAIL, 'm')
 // `export const inputs = ['a', 'b']`, single or multi line. Anything cleverer

package/src/core/check-pass.ts

@@ -12,9 +12,10 @@ import { importClosure } from '../ts/source-graph.ts'
 import { LIB_ROOT } from './lib-root.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Scan } from '../scan.ts'
+import { parseDirectives, type Directive } from './waivers.ts'
 
 /** a scan's context, and what it recorded while the scan ran */
-type ScanRecorder = ScanCtx & { readonly reads: Reads; readonly untracked: string | null }
+type ScanRecorder = ScanCtx & { readonly reads: Reads; readonly untracked: string | null; readonly marked: ReadonlyMap<string, string> }
 
 /** the config file every check that consults `c.config` depends on */
 export const CONFIG_FILE = 'repo.config.ts'
@@ -27,6 +28,7 @@ export class CheckPass {
     private readonly scans = new Map<string, { value: Promise<unknown>; ctx: ScanRecorder }>()
     private viewMemo: RepoView | null = null
     private configMemo: { files: Map<string, string | null>; untracked: string | null } | null = null
+    private readonly directiveMemo = new Map<string, { text: string; directives: Directive[] }>()
 
     constructor(
         readonly root: string,
@@ -34,6 +36,10 @@ export class CheckPass {
         /** where the file list comes from: the run's ledger shares its own,
          *  so a listing and its validation read one snapshot */
         private readonly openView: () => RepoView = () => RepoView.open(root),
+        /** false for a pass whose answers nothing stores (the pre-commit
+         *  gate): listing what the config imports is then pure cost, measured
+         *  at 12 to 70ms on the first check that reads `c.config` */
+        readonly recordsConfig = true,
     ) {
         this.configOid = oidOnDisk(join(root, CONFIG_FILE))
     }
@@ -61,6 +67,16 @@ export class CheckPass {
         return this.configMemo
     }
 
+    /** the directives of a file as read, parsed once per pass however many
+     *  checks read it */
+    directives(path: string, text: string): Directive[] {
+        const hit = this.directiveMemo.get(path)
+        if (hit != null && hit.text === text) return hit.directives
+        const directives = parseDirectives(path, text)
+        this.directiveMemo.set(path, { text, directives })
+        return directives
+    }
+
     view(): RepoView {
         this.viewMemo ??= this.openView()
         return this.viewMemo

package/src/core/check-runner.ts

@@ -248,6 +248,12 @@ export function testsRan(lastLine: string): number | null {
     return m == null ? null : Number(m[1])
 }
 
+/** the command the suite runner says it ran, read off the same headline
+ *  (`…, as \`bun test --parallel=8\` (added --parallel=8)`, judge-suites ranAs) */
+export function testsCommand(lastLine: string): string | null {
+    return /, (as `[^`]+`(?: \(added [^)]+\))?)/.exec(lastLine)?.[1] ?? null
+}
+
 export type Selection = {
     /** what this run measures */
     selected: RunnableCheck[]
@@ -444,6 +450,8 @@ type Live = RunnableCheck & CheckResult & {
     reads: ReadSet | null
     /** why its answer cannot be stored on its reads, in its own words */
     untracked: string | null
+    /** the files whose in-file directives its answer depends on */
+    waiverFiles: string[]
     /** it printed nothing of its own, so its one line is the headline below */
     synthetic: boolean
     /** what the headline carries after the id: a failure's last line, or the
@@ -500,7 +508,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const runDir = openRunDir(o.logDir)
     const checks: Live[] = sel.selected.map((u) => ({
         ...u,
-        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, untracked: null, synthetic: false, tail: '', extra: [],
+        status: 'skip', advisory: false, replayed: false, ms: 0, exitCode: null, lines: [], problems: [], lastLine: '', note: '', startedAt: 0, endedAt: 0, unmeasured: false, attached: false, reads: null, untracked: null, waiverFiles: [], synthetic: false, tail: '', extra: [],
         logPath: u.body.cmd != null ? join(runDir, `${u.id.replace(/[^a-zA-Z0-9-]/g, '_')}.log`) : null,
     }))
     const selectedIds = new Set(checks.map((u) => u.id))
@@ -580,9 +588,12 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         const ran = u.status === 'pass' || u.status === 'warn' ? testsRan(u.lastLine) : null
         const counted = ran != null && head != null && head.kind === 'ok' && (head.text === u.id || head.text.startsWith(`${u.id} (`))
         const id = counted ? `${u.id} ${ran} test${ran === 1 ? '' : 's'}` : u.id
+        // and the command the suite runner ran, which can differ from the script's body
+        const how = counted ? testsCommand(u.lastLine) : null
+        const as = how == null ? '' : ` ${how}`
         const composed = u.synthetic && !u.replayed && head != null
-            ? [{ ...head, text: `${id} ${ranStamp(u.ms)}${u.tail}` }, ...u.lines.slice(1)]
-            : counted ? [{ ...head, text: `${id}${head.text.slice(u.id.length)}` }, ...u.lines.slice(1)] : u.lines
+            ? [{ ...head, text: `${id} ${ranStamp(u.ms)}${u.tail}${as}` }, ...u.lines.slice(1)]
+            : counted ? [{ ...head, text: `${id}${head.text.slice(u.id.length)}${as}` }, ...u.lines.slice(1)] : u.lines
         // every line says where its answer came from: a replay carries its
         // cached stamp already, so one that ran here says so and what it cost
         const shown = u.synthetic || u.replayed || u.attached || u.startedAt === 0 || composed[0] == null
@@ -590,8 +601,9 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             : [ranHere(composed[0], u.ms), ...composed.slice(1)]
         // a caller printing its own verdict wants one line per green check and
         // only the warnings of a warned one; a failure prints whole
+        // a waived site is detail whatever the verdict, and its count never is
         const quiet = (l: Line, i: number): boolean =>
-            o.detail != null && (u.status === 'pass' ? i > 0 : u.status === 'warn' || u.advisory ? l.kind === 'ok' || l.kind === 'note' || l.kind === 'skip' : false)
+            o.detail != null && l.waiver !== 'count' && (l.waiver === 'site' || (u.status === 'pass' ? i > 0 : u.status === 'warn' || u.advisory ? l.kind === 'ok' || l.kind === 'note' || l.kind === 'skip' : false))
         for (const [i, l] of shown.entries()) if (quiet(l, i)) o.detail!(formatLine(l, color)); else emit(l)
         if (u.status === 'fail' && !u.advisory && u.logPath != null)
             emit({ kind: 'fix-fail', text: `full log: ${u.logPath}` })
@@ -632,6 +644,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             await runCheckBody({ id: u.id, title: u.title, owner: u.owner, run: u.body.run, fix: u.fix }, t)
             u.reads = t.untracked == null ? t.reads.snapshot() : null
             u.untracked = t.untracked
+            u.waiverFiles = t.waiverFiles()
             u.lines = t.lines
             u.problems = findings(u, t.lines)
             u.unmeasured = t.unmeasured
@@ -709,6 +722,13 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             let i = parsed.length
             while (i > 0 && (parsed[i - 1]!.kind === 'fail' || parsed[i - 1]!.kind === 'fix-fail')) i--
             u.extra = parsed.slice(i).filter((l) => !(l.kind === 'fail' && `FAIL: ${l.text}` === u.lastLine)).slice(-MAX_EXTRA)
+            // a tool that speaks no wire (a linter, tsc) ends on a recap, and
+            // its errors are the findings its output parsed into
+            if (!u.extra.some((l) => l.kind === 'fail'))
+                u.extra = u.problems
+                    .filter((p) => p.severity === 'error' && !u.lastLine.includes(p.message))
+                    .slice(0, MAX_EXTRA)
+                    .map((p) => ({ kind: 'fail', text: `${p.file}:${p.line}:${p.col}: ${p.message}` }))
         }
     }
 
@@ -723,9 +743,9 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
 
     /** what an attached asker adopts: the verdict and the lines BEFORE this
      *  run's own demotion, which the asker applies from its own declaration */
-    type Answer = Pick<Live, 'status' | 'lines' | 'problems' | 'lastLine' | 'exitCode' | 'logPath' | 'synthetic' | 'tail'> & { measuredMs: number }
+    type Answer = Pick<Live, 'status' | 'lines' | 'problems' | 'lastLine' | 'exitCode' | 'logPath' | 'synthetic' | 'tail' | 'waiverFiles'> & { measuredMs: number }
     const answerOf = (u: Live): Answer => ({
-        status: u.status, lines: u.lines, problems: u.problems, lastLine: u.lastLine, exitCode: u.exitCode, logPath: u.logPath,
+        status: u.status, lines: u.lines, problems: u.problems, lastLine: u.lastLine, exitCode: u.exitCode, logPath: u.logPath, waiverFiles: u.waiverFiles,
         synthetic: u.synthetic, tail: u.tail, measuredMs: (u.endedAt > 0 ? u.endedAt : clock()) - u.startedAt,
     })
     // only a GREEN is ever stored. A pass is one whatever the check blocks. A
@@ -768,7 +788,7 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         u.lines = head == null ? [] : [{ ...head, text: `${head.text}${stamp}` }, ...a.lines.slice(1)]
         u.problems = feeds(u) ? a.problems ?? [] : []
         if (o.ledger != null && storable(u))
-            o.ledger.record(u.id, { status: u.status, lines: a.lines, lastLine: a.lastLine, problems: u.problems, measuredMs: a.measuredMs })
+            o.ledger.record(u.id, { status: u.status, lines: a.lines, lastLine: a.lastLine, problems: u.problems, measuredMs: a.measuredMs }, undefined, undefined, a.waiverFiles)
     }
 
     /** ONE measurement per in flight question: an asker whose exact key
@@ -798,11 +818,11 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         // attached wait runs nothing, so it holds none
         const slot = pool == null ? null : await takeSlot(pool, { repo: o.config.name, check: u.id }, {
             abort: () => interrupted || bailed,
-            onWait: (held) => {
+            onWait: (held, why) => {
                 if (slotWaitSaid) return
                 slotWaitSaid = true
                 const who = held.slice(0, 3).map((h) => `${h.repo}/${h.check} pid ${h.pid}`).join(', ')
-                emit({ kind: 'ok', text: `waiting for a machine slot: ${held.length} of ${pool.size} held${who === '' ? '' : ` (${who}${held.length > 3 ? ', …' : ''})`}` })
+                emit({ kind: 'ok', text: `waiting for a machine slot: ${held.length} held, ${why}${who === '' ? '' : ` (${who}${held.length > 3 ? ', …' : ''})`}` })
             },
         })
         if (pool != null && slot == null) { u.status = 'skip'; u.note = bailed ? 'bailed' : 'interrupted'; u.lines = []; u.unmeasured = true; return }
@@ -826,12 +846,14 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
             u.lines = rememberWorld(o.cache, u.id, worldKey(u), u.ttlMs, {
                 lines: u.lines,
                 clean,
+                // a waiver count is a skip line: a world key cannot see the
+                // waiving file, so a waived world answer is never kept
                 unmeasured: u.unmeasured || u.lines.some((l) => l.kind === 'skip'),
                 keepNegative: u.blocking === false,
             })
         }
         if (o.ledger != null && keep)
-            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads, u.untracked)
+            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads, u.untracked, u.waiverFiles)
     }
 
     const start = (u: Live): void => {

package/src/core/config-rewrite.ts

@@ -13,7 +13,7 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 import { atomicWrite } from './locked-write.ts'
-import { dropConfigKey } from './legacy-shapes.ts'
+import { dropConfigEntry, dropConfigKey } from './legacy-shapes.ts'
 import { writeGateBlock } from './when-block.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 
@@ -25,6 +25,12 @@ export type ConfigPlan = {
     drop: { key: string; why: string; phase?: 'first' | 'afterOff' }[]
     /** the config's `name` before the rewrite: what the read back must still say */
     name: string
+    /** entries of an object key to lift into `off` (`hooks.disable`, a
+     *  `defaults` slot set to false), dropped once the block took them. The
+     *  comment written right above an entry becomes the reason of every id it
+     *  carries, since it is the author's own words; `reason` is the honest
+     *  fallback when there is none */
+    lift?: { parent: string; entry: string; value: string; ids: string[]; reason: Record<string, string> }[]
 }
 
 export type ConfigRewrite = {
@@ -48,17 +54,23 @@ export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<Con
     let first = before
     for (const d of plan.drop.filter((x) => x.phase === 'first')) first = drop(first, d)
     if (first !== before) atomicWrite(path, first)
+    // each lifted entry's reason, read off the text before anything moves
+    const off = { ...plan.off }
+    for (const l of plan.lift ?? []) {
+        const seen = dropConfigEntry(first, l.parent, l.entry, l.value)
+        for (const id of l.ids) off[id] ??= seen?.comment ?? l.reason[id] ?? ''
+    }
     let offWritten = false
-    if (Object.keys(plan.off).length > 0) {
+    if (Object.keys(off).length > 0) {
         try {
-            await writeGateBlock(root, { off: plan.off })
+            await writeGateBlock(root, { off })
             offWritten = true
-            did.push(`${Object.keys(plan.off).length} off entr(ies) written into the managed block`)
+            did.push(`${Object.keys(off).length} off entr(ies) written into the managed block`)
         } catch (e) {
             // a key dropped first held these entries: without the block they
             // would be gone, so the file goes back as it was
-            if (first !== before) { atomicWrite(path, before); return { did: [], hand, restored: `the managed block refused off ${JSON.stringify(plan.off)}: ${String(e).slice(0, 160)}` } }
-            hand.push(`the managed block refused the rewrite (${String(e).slice(0, 160)}) — write off: ${JSON.stringify(plan.off)} into it by hand`)
+            if (first !== before) { atomicWrite(path, before); return { did: [], hand, restored: `the managed block refused off ${JSON.stringify(off)}: ${String(e).slice(0, 160)}` } }
+            hand.push(`the managed block refused the rewrite (${String(e).slice(0, 160)}) — write off: ${JSON.stringify(off)} into it by hand`)
         }
     }
     const mid = readFileSync(path, 'utf8')
@@ -67,11 +79,20 @@ export async function rewriteConfig(root: string, plan: ConfigPlan): Promise<Con
         if (d.phase === 'afterOff' && !offWritten) continue
         text = drop(text, d)
     }
+    // a lifted entry goes only once the block holds it, so it is never lost
+    for (const l of offWritten ? plan.lift ?? [] : []) {
+        const next = dropConfigEntry(text, l.parent, l.entry, l.value)
+        if (next == null) { hand.push(`repo.config.ts \`${l.parent}.${l.entry}\` is \`off\` now, and the entry could not be read mechanically — delete it by hand`); continue }
+        did.push(`repo.config.ts drops \`${l.parent}.${l.entry}\``)
+        text = next.text
+    }
     if (text !== mid) atomicWrite(path, text)
     if (text !== before) {
         try {
             const after = await loadRepoConfig(root, { fresh: true })
             if (after.name !== plan.name) throw new Error(`the config reads as '${String(after.name)}'`)
+            const lost = Object.keys(off).filter((id) => after.off?.[id] == null)
+            if (offWritten && lost.length > 0) throw new Error(`the config no longer turns ${lost.join(', ')} off`)
         } catch (e) {
             atomicWrite(path, before)
             return { did, hand, restored: String(e).slice(0, 160) }