rvlib-shipkit 1.8.0 → 2.0.0

package/src/hooks/staged.ts

@@ -0,0 +1,49 @@
+// what this commit changes against HEAD, listed ONCE for every git based
+// step of the pre-commit gate: each step spawning its own `git diff --cached`
+// costs a process start per step on every commit. Every call inherits the
+// environment, so a commit made under a private GIT_INDEX_FILE is read from
+// that same index, which is the one git is about to commit.
+import { gitBin } from '../core/git-bin.ts'
+import { gitRoot } from '../core/git-root.ts'
+
+/** one staged change: git's status letter (A, M, D, R, C, T, U), the path as
+ *  `--name-only` prints it, and for a rename or a copy the path it came from */
+export type StagedEntry = { status: string; path: string; from?: string }
+
+export type Staged = {
+    /** HEAD resolves: false on the first commit of a repo */
+    head: boolean
+    entries: StagedEntry[]
+    /** every staged path, in git's order */
+    names: string[]
+}
+
+/** `git diff --cached --name-status -z`: a status field, then one path, or
+ *  two for a rename or a copy. NUL separated, so no path is ever quoted */
+export function parseNameStatus(out: string): StagedEntry[] {
+    const f = out.split('\0')
+    const entries: StagedEntry[] = []
+    for (let i = 0; i < f.length; ) {
+        const status = f[i++] ?? ''
+        if (status === '') break
+        const letter = status[0]!
+        if (letter === 'R' || letter === 'C') {
+            const from = f[i++] ?? ''
+            entries.push({ status: letter, path: f[i++] ?? '', from })
+        } else entries.push({ status: letter, path: f[i++] ?? '' })
+    }
+    return entries
+}
+
+export function readStaged(root: string): Staged {
+    if (gitRoot(root) == null) return { head: false, entries: [], names: [] }
+    // the env is passed on purpose: Bun's default is the environment the
+    // process started with, never one a caller set since
+    const head = Bun.spawnSync([gitBin(), 'rev-parse', '--verify', '-q', 'HEAD'], { cwd: root, env: process.env, stdout: 'ignore', stderr: 'ignore' }).exitCode === 0
+    const p = Bun.spawnSync([gitBin(), 'diff', '--cached', '--name-status', '-z'], { cwd: root, env: process.env, maxBuffer: 64 * 1024 * 1024 })
+    // an unreadable index is no answer, and every gate below would read it as
+    // "nothing staged" and pass
+    if (p.exitCode !== 0) throw new Error(`git diff --cached exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n')[0] ?? ''}`)
+    const entries = parseNameStatus(p.stdout.toString())
+    return { head, entries, names: entries.map((e) => e.path) }
+}

package/src/hooks/tree-shrink.ts

@@ -0,0 +1,41 @@
+// a commit must not drop most of the tree.
+//
+// the failure this exists for: a commit made from a private GIT_INDEX_FILE
+// that was never filled with `git read-tree HEAD` holds only the files staged
+// into it, so git records every other file as deleted and the tree comes out
+// near empty. Every other gate passes, because nothing it reads is wrong.
+import type { Staged } from './staged.ts'
+import { gitBin } from '../core/git-bin.ts'
+
+export const ALLOW_MASS_DELETE = 'SHIPKIT_ALLOW_MASS_DELETE'
+
+export type ShrinkOutcome =
+    | { status: 'skipped'; reason: string }
+    | { status: 'clean' }
+    | { status: 'shrunk'; headFiles: number; stagedFiles: number; deleted: number }
+
+/** the decision, with no git in it. `headFiles` is asked for only when the
+ *  commit removes more files than it adds, so an ordinary commit pays nothing */
+export function shrinkVerdict(staged: Staged, headFiles: () => number): ShrinkOutcome {
+    if (!staged.head) return { status: 'skipped', reason: 'no HEAD yet, nothing to shrink' }
+    let deleted = 0
+    let added = 0
+    for (const e of staged.entries) {
+        if (e.status === 'D') deleted++
+        else if (e.status === 'A' || e.status === 'C') added++
+    }
+    if (deleted <= added) return { status: 'clean' }
+    const before = headFiles()
+    const after = before - deleted + added
+    if (after * 2 >= before) return { status: 'clean' }
+    if (process.env[ALLOW_MASS_DELETE] === '1') return { status: 'skipped', reason: `${ALLOW_MASS_DELETE}=1` }
+    return { status: 'shrunk', headFiles: before, stagedFiles: after, deleted }
+}
+
+export function headFileCount(root: string): number {
+    const p = Bun.spawnSync([gitBin(), 'ls-tree', '-r', '-z', '--name-only', '--full-tree', 'HEAD'], { cwd: root, env: process.env, maxBuffer: 256 * 1024 * 1024 })
+    if (p.exitCode !== 0) throw new Error(`git ls-tree HEAD exited ${p.exitCode}: ${p.stderr.toString().trim().split('\n')[0] ?? ''}`)
+    return p.stdout.toString().split('\0').filter(Boolean).length
+}
+
+export const runTreeShrink = (root: string, staged: Staged): ShrinkOutcome => shrinkVerdict(staged, () => headFileCount(root))

package/src/init-repo.ts

@@ -17,9 +17,6 @@ import { reportToMotherhome } from './core/motherhome.ts'
 import { ensureGitRepo, publishRepo, type Run } from './git-bootstrap.ts'
 import { defineRepo, loadRepoConfig, resolveFloor } from './repo-config.ts'
 import { gitignorePolicy } from './checks/SK004-gitignore-policy.check.ts'
-import { vscodeHubTask } from './checks/SK017-vscode-hub-task.check.ts'
-import { editorErgonomics } from './scaffold/project-scaffold.ts'
-import { defaultHubPort } from './serve/hub-port.ts'
 
 // This lands as SOURCE in the repo being wired, so its comments answer to that
 // repo's comment style, not to this file's. Dash punctuation is banned there
@@ -105,7 +102,6 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
         await repairOneWayIn(root, cfg, p)
-        await furnishEditor(root, cfg, p)
         const mh = reportToMotherhome(root, cfg)
         if (mh.note != null) p(mh.note)
         if (wired && opts.noPublish !== true) await publishRepo(root, { github: opts.github, gh: opts.gh, print: p })
@@ -139,7 +135,6 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     const g = await gitignorePolicy.repair!(CheckCtx.open({ root, config: defineRepo({ name }) }))
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
-    await furnishEditor(root, { name }, p)
     // what the gate actually runs, in ONE line: a thin floor must be seen at
     // init time rather than discovered after a bad commit slipped through.
     // The per-task resolution is diagnostics, and a `skip:` naming a script
@@ -170,43 +165,6 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     return 0
 }
 
-/** the folder-open story, on the adopt path as well as the start one.
- *
- *  `start` scaffolds the whole day-one shape, but only for a dir with no
- *  commit history, so every repo that already existed when it was wired got
- *  repo.config.ts and the scripts and no .vscode/ at all: opening the folder
- *  started nothing, and the hub the config advertises had no way in. These two
- *  files are the only half of that scaffold an adopted repo can be handed
- *  unasked, because they change no output of any command (project-scaffold.ts
- *  owns the line). Create-only, so a .vscode/ the repo brought with it wins. */
-async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?: number } }, p: (line: string) => void): Promise<void> {
-    // the least important thing init does, and it runs AFTER repo.config.ts is
-    // on disk: an unwritable .vscode (a read-only tree, a path that is a file),
-    // or a config with no name at all, must not abort the run before the
-    // publish chain, and must not pass in silence either. The port resolution
-    // is INSIDE the try for that reason: it reads a config nothing validates
-    try {
-        const name = repoName(root, undefined, cfg.name)
-        const port = cfg.serve?.port ?? defaultHubPort(name)
-        if (editorErgonomics(root, { name, port }).length === 0) {
-            // the repo's own file stays its own, except the hub task, which
-            // rule SK017 keeps feeding the problems pane
-            // a file SK017 cannot read is still the repo's own: it is never
-            // reported as missing, and it is never rewritten
-            let hub: { changed: boolean; summary: string }
-            try { hub = await vscodeHubTask.repair!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
-                p('ok: .vscode/ is this repo\'s own, left untouched')
-                return void p(`WARN .vscode/tasks.json does not parse (${e instanceof Error ? e.message : String(e)}): the hub task gets no problem matcher until it does`)
-            }
-            return void p(hub.changed ? `ok: ${hub.summary}` : 'ok: .vscode/ is this repo\'s own, left untouched')
-        }
-        p(`ok: .vscode/tasks.json written — opening the folder starts the hub on ${port}`)
-        p('      next: add this stack\'s own watchers (dev server, css) — build/vscode-tasks.md carries the shapes')
-    } catch (e) {
-        p(`WARN no .vscode/tasks.json here: ${e instanceof Error ? e.message : String(e)} — opening the folder starts nothing, everything else landed`)
-    }
-}
-
 /** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
  *  (build/shipkit/one-way-in.md). Nothing here is a second implementation: rule SK001
  *  routes the package.json scripts, rule SK013 writes the harness policy, and

package/src/ledger/check-table.ts

@@ -87,7 +87,7 @@ export function renderCheckTable(input: CheckTableInput): string {
     body.push('')
     body.push(`Everything \`shipkit ci\` and \`shipkit check\` know how to run: ${builds} build step(s) the gate alone runs, ${rows.length - builds} the health pass reports too. ${shipped} ship with the toolkit, ${rows.length - shipped} belong to this repo.`)
     body.push('')
-    body.push('- **runs in** — `always` means every `shipkit ci` runs it, so a red one says THIS change is broken. `release` means the quick gate leaves it out and `shipkit ci --full` plus the release path run it. `health` means only the health pass (`shipkit check`) runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit. `off` means this repo turned it off on purpose, and the reason is in `repo.config.ts when`.')
+    body.push('- **runs in** — `always` means every `shipkit ci` runs it, so a red one says THIS change is broken. `release` means the quick gate leaves it out and `shipkit ci --full` plus the release path run it. `health` means only the health pass (`shipkit check`) runs it: it reports the world (a box that is off, a cred nobody minted, a page nobody refreshed), it can sit red for months with nothing wrong, and it never stands between you and a commit. `commit` means a git hook runs it on every commit (`shipkit hooks list`). `off` means this repo turned it off on purpose, and the reason is in `repo.config.ts off`.')
     body.push('- **build** — `yes` means the gate alone runs it: it BUILDS (a compiler, a test suite, a bundler), so `shipkit check` leaves it out and reports everything else. A floor slot derives it from the package.json script behind it, and a `*.check.ts` declares it with `build: true`.')
     body.push('- **on failure** — `blocks` stops the run. `warns` prints and carries on. `UNDECLARED` is a defect, not a setting: the check never said and the repo set no default, so the runner treats it as fatal by guess.')
     body.push('- **cache** — `content` is cached while the files it reads are untouched. `world` is cached for its TTL, and a RED that ran is cached too, capped at one hour so the run after a fix sees the fix. `never` runs every time and somebody wrote down why. `UNDECLARED` runs every time and nobody has looked yet, which is the burn-down (`shipkit keys --burn-down`). `SHIPKIT_FRESH=1` busts all of it.')

package/src/ledger/gate-checks.ts

@@ -26,6 +26,7 @@ import { CHECK_TIMEOUT_MS, type RunnableCheck, type CheckBody } from '../core/ch
 import { FOREVER, ttlMsOf } from '../core/wire.ts'
 import { budgetOf } from '../core/budget.ts'
 import { repoOff, withRepoOff, whenSummary, type WhenDecl } from '../core/when.ts'
+import { HOOK_BUDGET_MS, HOOK_GATES, HOOK_GATES_OWNER, hookGateOff, type HookName } from '../hooks/hook-gates.ts'
 import { cacheText, filesText, NOWHERE, sourced, type CacheDecl, type ResolvedRuns, type Runs } from '../core/runs.ts'
 import { isNamesInput, type CheckDecl } from './git-key.ts'
 import { populationOf } from '../problems/problem-line.ts'
@@ -131,6 +132,9 @@ export type CheckRow = {
      *  `repo` = this repo declared it (a package.json script behind a floor
      *  slot, a task, a rule, a check file, a check file). */
     from: CheckFrom
+    /** a COMMIT GATE: the git hook that runs it (hooks/hook-gates.ts). The
+     *  runner never does, so every runner context reads false */
+    hook?: HookName
 }
 
 /** the one axis every check answers: who wrote the declaration */
@@ -348,15 +352,16 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
         // time is not judged and its answer never stands in for a quick one
         out.push({ row, runnable: runnableOf(row, taskBody(t), { unbudgeted: full }) })
     }
-    // a slot `defaults: { <id>: false }` turned off never resolves to a task,
-    // so without this it had no row at all: no `runs in` value, no reason, and
-    // a count of off checks that read zero while a gate step sat dark. It has
-    // no command, which is why it declares `never` rather than joining the
-    // burn-down of checks nobody has keyed yet.
+    // a slot the repo turned off never resolves to a task, so without this it
+    // had no row at all: no `runs in` value, no reason, and a count of off
+    // checks that read zero while a gate step sat dark. It has no command,
+    // which is why it declares `never` rather than joining the burn-down of
+    // checks nobody has keyed yet.
     for (const id of floor.disabled) {
-        const runs = sourced(NOWHERE, 'none', 'repo.config.ts', null, `defaults.${id}: false`)
+        const off = repoOff(c, id) ?? { reason: 'turned off', source: 'off' as const }
+        const runs = sourced(NOWHERE, 'none', 'repo.config.ts', null, off.reason)
         const row: CheckRow = {
-            decl: { id, never: `turned off by defaults.${id}: false, so there is no command to key` },
+            decl: { id, never: `the slot is off, so there is no command to key` },
             title: id,
             description: slotDescription(id, declaredTestUnits(c.units).length > 0),
             gate: false,
@@ -369,8 +374,8 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
             optIn: false,
             fixable: false,
             runs,
-            cache: `never: turned off by defaults.${id}: false`,
-            when: whenSummary(runs, { reason: `defaults.${id}: false`, source: 'defaults' }, false),
+            cache: `never: the slot is off`,
+            when: whenSummary(runs, off, false),
             deps: null,
             // the repo wrote the line that turned it off
             from: 'repo',
@@ -518,6 +523,37 @@ export async function composeChecks(root: string, c: RepoConfig, o: ComposeOpts
         const body: CheckBody = { cmd: ['bun', d.path], ...(task?.env == null ? {} : { env: task.env }), ...(task?.cwd == null ? {} : { cwd: resolve(root, task.cwd) }) }
         out.push({ row, runnable: runnableOf(row, body, { pointer: `bun ${rel}` }) })
     }
+    // THE COMMIT GATES: the git hooks run them (hooks/run-hooks.ts), never the
+    // runner, so a row here only makes them enumerable and `off` able to name
+    // them. They run in no runner context, and a run by name says where they run
+    for (const g of HOOK_GATES) {
+        const na = c.nested === true ? 'n/a here: a nested folder, the parent work tree owns the commit gates'
+            : g.id === 'blocked-paths' && (c.hooks?.blockedPaths ?? []).length === 0 ? 'n/a here: no hooks.blockedPaths declared' : null
+        const off = hookGateOff(c, g.id)
+        const hookWords = g.hook === 'both' ? 'the pre-commit and commit-msg hooks' : `the ${g.hook} hook`
+        const runs = withRepoOff(sourced(NOWHERE, 'none', 'derived', `a commit gate: ${hookWords} run it on every commit`, na), off)
+        const row: CheckRow = {
+            decl: { id: g.id, never: `a commit gate runs on the index at commit, never cached` },
+            title: g.title,
+            description: g.description,
+            gate: false,
+            build: false,
+            blocking: true,
+            owner: HOOK_GATES_OWNER,
+            group: null,
+            timeoutMs: null,
+            budgetMs: HOOK_BUDGET_MS,
+            optIn: false,
+            fixable: false,
+            runs,
+            cache: `never: ${hookWords}`,
+            when: whenSummary(runs, off, false, { hook: true }),
+            deps: null,
+            from: 'shipkit',
+            hook: g.hook,
+        }
+        out.push({ row, runnable: runnableOf(row, { run: (ctx) => ctx.note(`${g.id} runs in ${hookWords}, never in a gate: \`shipkit hooks list\` shows it`) }) })
+    }
     return out
 }
 

package/src/ledger/ledger.ts

@@ -273,9 +273,14 @@ export class Ledger {
     /** buffer what a check just measured. Nothing reaches the store until
      *  commit() has re-hashed the inputs (rule 2). A READS check with no read
      *  set (it reached the world) is never stored (rule 7). */
-    record(id: string, outcome: CheckOutcome, reads?: ReadSet | null, notKept?: string | null): void {
+    record(id: string, outcome: CheckOutcome, reads?: ReadSet | null, notKept?: string | null, waiverFiles: readonly string[] = []): void {
         const k = this.key(id)
         if (k.key == null) return
+        // a READS answer carries every waiving file in its read set. A
+        // CONTENT key moves only with its inputs, so a directive outside
+        // them could be added or removed under a stored answer
+        const outside = k.population === 'content' ? waiverFiles.find((f) => !k.inputOids.some(([p]) => p === '.' || f === p || f.startsWith(`${p}/`))) : undefined
+        if (outside != null) { this.ranWhy.set(id, { group: 'not kept', why: `a site in ${outside}, which an in-file directive can waive, sits outside its declared inputs` }); return }
         if (k.population === 'reads') {
             if (reads == null) { this.ranWhy.set(id, { group: 'not kept', why: notKept ?? 'it read outside what the cache can see' }); return }
             this.buffered.set(id, { ...outcome, reads, components: k.components })

package/src/ledger/repo-view.ts

@@ -7,8 +7,14 @@
 // Built once per run and shared: `c.list` in every check and the ledger's
 // replay check read the same snapshot, so a check never lists one tree and is
 // validated against another inside one run.
+//
+// A listing leaves out the repo's vendored dirs (core/vendored.ts), unless
+// its glob names a path inside one: a check never mistakes third party code
+// for the repo's own, and the replay check lists through the same filter.
 import { relative } from 'path'
 import { gitBin } from '../core/git-bin.ts'
+import { listingWithoutVendored } from '../core/vendored.ts'
+import { readVendored } from '../core/vendored-read.ts'
 import { GitScanError, scanPaths, WHOLE_TREE, type ScanResult } from './git-scan.ts'
 
 export class RepoView {
@@ -21,26 +27,30 @@ export class RepoView {
         readonly fallback: string | null,
         /** the scan it was read off, handed to the next open as its prior */
         readonly scan: ScanResult | null = null,
+        /** the repo's vendored dirs, as its config text declared them at open */
+        readonly vendored: readonly string[] = [],
     ) {}
 
     /** `prior`: an earlier view of the same root in this run. The tree is
      *  still staged and hashed fresh, so the list is today's, and an unchanged
      *  tree reuses the prior's answer */
     static open(root: string, prior?: RepoView | null): RepoView {
+        const vendored = readVendored(root)
         try {
             const scan = scanPaths(root, [WHOLE_TREE], prior?.scan ?? undefined, { treeOnly: true })
             const tree = scan.oidByPath.get(WHOLE_TREE)
             if (tree == null) throw new GitScanError('git could not name the work tree')
-            return new RepoView(filesOf(root, tree), null, scan)
+            return new RepoView(filesOf(root, tree), null, scan, vendored)
         } catch (e) {
-            return new RepoView(walk(root), e instanceof Error ? e.message : String(e))
+            return new RepoView(walk(root), e instanceof Error ? e.message : String(e), null, vendored)
         }
     }
 
-    /** the files matching `glob`, sorted */
+    /** the files matching `glob`, sorted, the vendored ones left out unless
+     *  the glob names a path inside one */
     list(glob: string): string[] {
         const g = new Bun.Glob(glob)
-        return this.files.filter((f) => g.match(f))
+        return listingWithoutVendored(this.files.filter((f) => g.match(f)), glob, this.vendored)
     }
 }
 

package/src/ledger/toolchain-identity.ts

@@ -328,8 +328,10 @@ export function toolchainIdentity(repoRoot: string, cliEntry: string): Toolchain
     // stands.
     const lib = new LibSource(cliEntry)
     const r = createHash('sha256')
-    // the runtime. Free, and a bun upgrade genuinely changes behaviour
-    r.update(`bun=${Bun.version}\n`)
+    // the runtime. Free, and a bun upgrade genuinely changes behaviour. The
+    // revision too: every canary of one version reports the same version,
+    // and a canary upgrade can change what `bun lint` reports
+    r.update(`bun=${Bun.version}+${Bun.revision}\n`)
     for (const l of runnerLines(lib, cliEntry)) r.update(`${l}\n`)
     return { id: r.digest('hex').slice(0, 16), install: installOf(root, lib), lib }
 }

package/src/mv/mv-md.ts

@@ -8,6 +8,8 @@
 import { execSync } from 'child_process'
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { basename, dirname, join, relative } from 'path'
+import { isVendored } from '../core/vendored.ts'
+import { vendoredAround } from '../core/vendored-read.ts'
 
 export type MvIo = { print: (l: string) => void; printErr: (l: string) => void }
 export type MvOpts = { write?: boolean; commit?: boolean }
@@ -130,8 +132,11 @@ export function movePage(root: string, oldRel: string, newRel: string, io: MvIo,
     const bound = (t: string): RegExp =>
         new RegExp('(?<![\\w-])' + t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (/[/.]$/.test(t) || t.endsWith('.ts') ? '' : '(?![\\w-])'), 'g')
 
+    // third party code keeps its own references, byte for byte
+    const repo = vendoredAround(root)
+    const vendored = (repo?.dirs ?? []).map((d) => posix(relative(root, join(repo!.root, d))))
     const tracked = sh('git ls-files', root).split('\n').filter(Boolean)
-        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|zip|gz|lockb|lock)$/i.test(f))
+        .filter((f) => !/\.(png|jpe?g|gif|webp|ico|woff2?|ttf|zip|gz|lockb|lock)$/i.test(f) && !isVendored(f, vendored))
 
     // every path this move relocates, old → new. The sibling dir carries its
     // whole subtree, and the probe is renamed after the page, so its own entry

package/src/plan/planner.ts

@@ -11,7 +11,8 @@
 //
 // what keeps it off the cpu: a save burst is asked about once the repo is
 // quiet (QUIET_MS, or MAX_WAIT_MS into a burst that never stops), a check a
-// save moved waits COST_FACTOR times its last measured run, and nothing it
+// save moved waits COST_FACTOR times its last measured run and GATED_HOLD_MS
+// after the latest gate someone else started in its repo, and nothing it
 // starts on its own starts while the load per core is above LOAD_MAX.
 import { availableParallelism, loadavg } from 'os'
 import { CATCH_UP_BEAT_MS, resumeCatchUp, type CatchUpStore } from './catch-up.ts'
@@ -39,6 +40,9 @@ export type PlanSource = {
     checks: () => Promise<PlanCheck[]>
     /** every check's last result on record */
     last: () => Record<string, LastResult>
+    /** when the latest run someone asked for started here (a terminal, an
+     *  agent, a click), never one the plan started; null when none did */
+    gatedAt?: () => number | null
     /** the checks a save moved: their answer would not replay */
     changed: () => Promise<string[]>
     /** run these checks now, in the background; resolves to the exit code */
@@ -88,6 +92,11 @@ export const MAX_WAIT_MS = 10 * 60_000
  *  measured run: a 30s suite at most every 10 minutes, a 200ms lint at once */
 export const COST_FACTOR = 20
 
+/** a save moved check waits this long after the latest run someone else
+ *  started in its repo (a terminal, an agent, a click): whoever gates that
+ *  tree is still at work, and its own gate measures what it changed */
+export const GATED_HOLD_MS = 10 * 60_000
+
 /** above this 1 minute load average per core, the plan starts nothing on its
  *  own: every core already has a process waiting for it */
 export const LOAD_MAX = 1
@@ -112,6 +121,7 @@ type Repo = {
     src: PlanSource
     checks: PlanCheck[]
     last: Record<string, LastResult>
+    gatedAt: number | null
     lastRead: number
     marks: Map<string, Mark>
     timer: unknown
@@ -169,7 +179,7 @@ export class Planner {
     async add(src: PlanSource): Promise<void> {
         const old = this.repos.get(src.repo)
         if (old?.timer != null) this.timers.clear(old.timer)
-        const r: Repo = { src, checks: [], last: {}, lastRead: -Infinity, marks: old?.marks ?? new Map(), timer: null, burstAt: null, settleAt: null, detecting: null, again: false, error: null }
+        const r: Repo = { src, checks: [], last: {}, gatedAt: null, lastRead: -Infinity, marks: old?.marks ?? new Map(), timer: null, burstAt: null, settleAt: null, detecting: null, again: false, error: null }
         this.repos.set(src.repo, r)
         await this.reload(src.repo)
         try {
@@ -223,6 +233,7 @@ export class Planner {
         r.lastRead = now
         try {
             r.last = r.src.last()
+            r.gatedAt = r.src.gatedAt?.() ?? null
         } catch (e) {
             this.fail(r.src.repo, e)
         }
@@ -315,7 +326,9 @@ export class Planner {
             // a check pays for its own runs: one save cannot run it again
             // before COST_FACTOR times its last measured run has passed
             const spaced = last?.cost != null ? last.cost.at + COST_FACTOR * last.cost.ms : -Infinity
-            const at = Math.max(m.changedAt, spaced)
+            // and it waits for whoever gates this tree by hand to stop
+            const gated = r.gatedAt != null ? r.gatedAt + GATED_HOLD_MS : -Infinity
+            const at = Math.max(m.changedAt, spaced, gated)
             return { ...base, state: at > now ? 'next' : 'due', reason: 'changed', dueAt: at }
         }
         const lastAt = Math.max(last?.at ?? -Infinity, m.attemptAt ?? -Infinity)
@@ -354,8 +367,12 @@ export class Planner {
     held(): string[] {
         const now = this.now()
         const out: string[] = []
-        for (const r of this.repos.values())
+        for (const r of this.repos.values()) {
             if (r.settleAt != null) out.push(`settling: ${r.src.repo}, ${Math.max(0, Math.ceil((r.settleAt - now) / 1_000))}s`)
+            const until = r.gatedAt == null ? null : r.gatedAt + GATED_HOLD_MS
+            if (until != null && until > now && [...r.marks.values()].some((m) => m.changedAt != null))
+                out.push(`deferred: ${r.src.repo}, a gate someone started there ${Math.floor((now - r.gatedAt!) / 60_000)}m ago, so what a save moved waits ${Math.ceil((until - now) / 60_000)}m`)
+        }
         if (this.holdReason != null) out.push(this.holdReason)
         return out
     }

package/src/plan/repo-source.ts

@@ -82,12 +82,15 @@ export function readLastCosts(path: string): Record<string, { at: number; ms: nu
     return out
 }
 
-/** when the latest run on record started, whoever ran it, or null */
-export function lastStarted(path: string): number | null {
+/** when the latest run on record started, or null. `asked`: only a run
+ *  someone asked for (a terminal, an agent, a click), never one the plan
+ *  started on its own */
+export function lastStarted(path: string, o: { asked?: boolean } = {}): number | null {
     const opened = openDb(path, { create: false })
     if (opened == null) return null
     try {
-        const r = opened.db.query('select max(started) as at from invocations').get() as { at: number | null } | null
+        const sql = o.asked === true ? "select max(started) as at from invocations where by != 'schedule'" : 'select max(started) as at from invocations'
+        const r = opened.db.query(sql).get() as { at: number | null } | null
         return r?.at == null ? null : Number(r.at)
     } catch {
         return null
@@ -144,6 +147,7 @@ export function repoSource(d: RepoSourceDeps): PlanSource {
             for (const [id, cost] of Object.entries(costs)) if (all[id] != null) all[id] = { ...all[id]!, cost }
             return all
         },
+        gatedAt: () => (d.record === '' ? null : lastStarted(d.record, { asked: true })),
         changed: async () => {
             const decls = rows.map((r) => r.decl)
             if (decls.length === 0) return []

package/src/problems/extract.ts

@@ -1,6 +1,8 @@
 // file:line findings out of what a check printed, one function per format the
-// floor meets: tsc, oxlint (both its piped and its graphical output), eslint's
-// stylish output, a failing bun test, and a shipkit wire line naming a file.
+// floor meets: tsc, bun lint (the unix format the built-in lint slot asks
+// for), oxlint (both its piped and its graphical output, kept while a repo
+// still lints with it: SK001 warns on one, and it dies with the last), eslint's stylish
+// output, a failing bun test, and a shipkit wire line naming a file.
 // Every one feeds the one Problem shape (problem-line.ts).
 //
 // a finding the source cannot anchor in a file is dropped rather than pinned
@@ -62,6 +64,20 @@ export function fromTsc(text: string, ctx: ExtractCtx): Problem[] {
     return out
 }
 
+const BUN_LINT_UNIX = /^(.+?):(\d+):(\d+): (.*) \[(Error|Warning)\/([^\]]+)\]$/
+
+/** bun lint `--format unix`: `src/a.ts:1:7: msg [Warning/no-unused-vars]` */
+export function fromBunLint(text: string, ctx: ExtractCtx): Problem[] {
+    const out: Problem[] = []
+    for (const raw of stripAnsi(text).split('\n')) {
+        const m = BUN_LINT_UNIX.exec(raw)
+        if (m == null) continue
+        const file = repoFile(ctx, m[1]!, false)
+        if (file != null) out.push({ file, line: Number(m[2]), col: Number(m[3]), severity: m[5] === 'Error' ? 'error' : 'warning', check: ctx.check, message: `${m[6]} ${m[4]!.trim()}` })
+    }
+    return out
+}
+
 const OXLINT_PIPED = /^(.+?):(\d+):(\d+): (error|warning) (\S+?): (.*)$/
 const OXLINT_HEAD = /^\s*(x|!|×|⚠)\s+(.+)$/
 const OXLINT_AT = /^\s*(?:,-|╭─)\[(.+):(\d+):(\d+)\]\s*$/
@@ -148,14 +164,20 @@ export function fromBunTest(text: string, ctx: ExtractCtx): Problem[] {
 
 const WIRE_REF = /((?:[\w@.~-]+\/)*[\w@.~-]+\.[A-Za-z0-9]+):(\d+)(?::(\d+))?/g
 
-/** a FAIL or WARN wire line naming `path:line` or `path:line:col`. The path
- *  must be a file this repo has: a url and a `host:port` look the same */
+/** a FAIL or WARN wire line: at the site the check reported when it gave one,
+ *  else at every `path:line` or `path:line:col` the text names. The path must
+ *  be a file this repo has: a url and a `host:port` look the same */
 export function fromWire(lines: Line[], ctx: ExtractCtx): Problem[] {
     const out: Problem[] = []
     for (const l of lines) {
         if (l.kind !== 'fail' && l.kind !== 'warn') continue
         const severity: Severity = l.kind === 'fail' ? 'error' : 'warning'
         const message = l.text.replace(/^\[[^\]]+\]\s*/, '').trim()
+        if (l.at != null) {
+            const file = repoFile(ctx, l.at.file, true)
+            if (file != null) out.push({ file, line: l.at.line ?? 1, col: l.at.col ?? 1, severity, check: ctx.check, message })
+            continue
+        }
         for (const m of l.text.matchAll(WIRE_REF)) {
             const before = l.text.slice(0, m.index)
             if (/[a-z]+:\/\/\S*$/i.test(before)) continue
@@ -173,7 +195,7 @@ export function extractProblems(src: { lines: Line[]; output?: string }, ctx: Ex
     const text = src.output ?? ''
     const all = [
         ...fromWire(src.lines, ctx),
-        ...(text === '' ? [] : [...fromTsc(text, ctx), ...fromOxlint(text, ctx), ...fromEslint(text, ctx), ...fromBunTest(text, ctx)]),
+        ...(text === '' ? [] : [...fromTsc(text, ctx), ...fromBunLint(text, ctx), ...fromOxlint(text, ctx), ...fromEslint(text, ctx), ...fromBunTest(text, ctx)]),
     ]
     const seen = new Set<string>()
     return all.filter((p) => {

package/src/problems/problem-line.ts

@@ -1,7 +1,6 @@
 // the ONE shape a problem takes on the hub terminal, and the vscode problem
-// matcher that reads it back. The printer and every tasks.json writer import
-// this file, so the line the hub prints and the regex the editor matches can
-// never drift apart.
+// matcher that reads it back, in one file so the two can never drift apart.
+// No house task carries the matcher any more (SK017 removes hub tasks).
 //
 // a run prints one FRAME: the begin line, one problem line per finding, the
 // end line. The matcher is a background one, so vscode clears the pane at the