rvlib-shipkit 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,3 +1,60 @@
+## 1.1.1
+
+- **The project rail reads `.shipkit/identity/icon.png` first.** A repo with no public surface has no favicon, so the rail showed its initial. `ICON_FILES` now starts with `.shipkit/identity/icon.png`, ahead of `public/favicon.png`, so a repo can carry a rail icon without shipping a public folder.
+
+## 1.1.0
+
+- **`shipkit ask` scaffolds a walkthrough, not a one line body.** A new ask used to carry `**Ask**: <title>` and nothing a human could follow. A step ask (every kind but `decision`) now starts with numbered `## N.` sections, each opening with a bold link slot and a `field | value` table, and ends with a `Tell the agent "done"` section. A `decision` ask starts with numbered options, the recommended one first. An HTML comment, invisible in the hub, states the shape, and `shipkit ask` reminds the author to fill every `{{placeholder}}` (braces, since the hub markdown hides an unknown `<tag>`). The `**Why**` line and `--why` are unchanged.
+
+- **A gate asks git less about things the disk already answers.** `probeGitRoot` answers a plain repository root (a `.git` directory at the root, no locating variable, no relocating or including config, owned by the caller) from the disk, and leaves every other case to `git rev-parse`. The layout migration reads `core.hooksPath` only when the moved hooks folder exists and the old one does not. `detectPackageManager` asks git which locks it tracks only when a lock file is present, and its `tracked` argument is optional.
+
+- **The suite runner's own tests hold on a loaded machine.** Their burner fixtures spun on the wall clock, so beside another gate they burned a fraction of the CPU they stand for (0.2s instead of 0.7s), came in under the 300ms budget, and four full tier tests of the runner failed while the runner was right. The fixtures now spin until the process has burned its CPU, and a test stops one with SIGSTOP mid spin to prove it still burns it.
+
+- **`c.list` sees the files of a nested repo.** In a `repo.config.ts` folder inside a larger git work tree, the file listing ran `git ls-tree` on the folder's own subtree from inside the folder, and git filtered that listing by the folder's path, which the subtree does not contain: every glob listed nothing, so a glob check there passed on an empty tree. The listing passes `--full-tree`.
+
+- **A gate reads each toolkit source file once while it decides what can be cached.** Every undeclared check's import closure was walked and scanned for raw disk access with its own reads, and the closures share most of their files: 300 reads of 58 files per gate. `rawAccessInClosure` takes a per pass `texts` map and `importClosure` a `read` function, so one pass reads each file once. `composeChecks` 10.8ms to 6.8ms per gate.
+
+- **A check's own code is hashed in process.** `hashFiles` spawned `git hash-object --stdin-paths` on every gate for the import closures of the checks it runs. It now hashes the bytes on disk with the same blob id the read recorder uses (`blobOid`), which equals git's for any file no clean filter rewrites and is only stricter where one does: a filter-only change is a miss, never a false hit. A warm narrowed gate now spawns no git at all. Stored answers keyed on a filtered file re-measure once.
+
+- **A scan that asks for no path writes no tree.** A run whose checks all key on their reads declares no input, and the scan still ran `git write-tree` for a tree id nothing reads. It validates the repo and returns an empty result.
+
+- **SK021 github login: a lost gh login is red.** `shipkit init` and `start` create a private repo with the gh login, and every push, release and SK007 use it, yet nothing probed it. The new built-in SK021 asks `gh auth status --hostname github.com --active --json hosts` (the text answer on a gh without `--json`; neither carries the token) in the health pass, cached 1h. Logged out, a refused token, no `repo` scope or no gh FAILs with `cred gh/github/login missing: …` and its fix (`gh auth login`, `gh auth refresh -h github.com -s repo`). That line makes `gh/github/login` a built-in `core` credential on the secrets page (`GH_LOGIN_CRED`), red there and red in `shipkit needs`, listed once SK021 has run in the repo. The check never blocks a gate. github.com unreachable is an unmeasured WARN, and a token with no oauth scopes (fine grained) WARNs. `SHIPKIT_NO_GITHUB` skips it.
+
+- **`c.tool` reads the PATH as it stands now.** `Bun.which` alone searched the PATH the process started with, so a PATH set later (a test seam, a wrapper) never reached it while `c.exec` did.
+
+- **A 0.x minor is a breaking jump.** `isBreaking` now draws the line npm's caret draws: a changed major, or on a `0.x` package a changed minor (`^0.2.0` means `<0.3.0`). SK005, the startup self-update and `fleet --update` WARN on such a jump and leave package.json alone, and `shipkit fleet --update --major` takes it. A `0.x` patch still updates by itself. The `--major` help says so.
+
+- **A hub under `bun --watch` no longer loses every spawn to EBADF after a day of saves.** bun 1.4.2 `--watch` keeps the previous image's watch fds on each in place restart (about 160 per restart on a large repo), and macOS `posix_spawn` refuses any fd at or past 10240, so once the table filled, every git call failed with `EBADF: bad file descriptor, posix_spawn`. `process.execve` carries none of them, so `StaleRestart` now also restarts the hub in place when its file table passes 4096 open files (`fdTableLeak`, `openFdCount`, `FD_LEAK_LIMIT` in `core/fd-table.ts`), at boot and every 2s, once no run is in flight. A table still full within a minute of such a restart is said as a hub problem instead of looping. **Type change**: `StaleRestartOpts.restart` receives the reason as `why`, and `leak` is a new optional option.
+
+- **The run record is written through the handle that already holds it.** A gate opened the record once for its live row and again for its final write, and each close checkpoints the WAL. The final write now reuses the live row's handle with the normal busy timeout. About 8ms to 3.5ms per gate.
+
+- **A replay scans the whole tree only when a glob needs it.** Validating a stored read set took a whole tree git scan on every replay and every store, and only a `c.list` glob ever reads that listing: file content, existence and directory entries are checked on disk. The view is now taken on the first glob that asks for it, the same snapshot as before. A gate whose checks list nothing makes no `git add` at all.
+
+- **A narrowed gate scans only what it runs.** `shipkit ci --only <check>` hashed and git-scanned the inputs and code of every check in the repo, then used one of them. The ledger is now opened on the ids the run executes (`passScope` in `core/run-check.ts`, the same selection the runner makes, built once by `selectionOf`), and `KeyLayer.open` takes a `scope`: a check outside it gets no key, with the reason on the line. The keys of the checks in scope are unchanged. A warm narrowed gate went from 5 git calls to 3.
+
+- **The file listing no longer asks git what it ignores.** A whole tree scan read `git ls-files --others -i` and never used the answer: it only feeds force-adds and the excluded list, and `git add -- .` leaves ignored files out by itself. `scanPaths` takes `{ treeOnly: true }`, which `RepoView` passes, and refuses it for anything but the whole tree. One git call less per gate that lists files.
+
+- **A suite run cleans up whatever its tests forget in the temp dir.** The suite runner hands `bun test` a `TMPDIR` of the run's own, deleted when the run ends. Suites that left their fixtures behind had put 90k dirs in the machine temp dir, and bun reads that whole listing the first time a process imports a file from a fixture there, 50 to 110ms per test process.
+
+- **No automatic update crosses a major.** SK005 moved `rvlib-pb-mobx` 1.0.0 → 2.0.0 in an unfrozen `ci`, while `fleet --update` refused the same jump without `--major`. SK005, the startup self-update and `fleet --update` now share one policy (`isBreaking`, `breakingAdvice`, `ALLOW_MAJOR_ENV` in `core/update-policy.ts`; `isBreaking` moved there from `fleet/scan-fleet.ts`): a changed major WARNs `<lib> <v> available (breaking): run \`shipkit fleet --update --major --only <repo>\`` and leaves package.json alone, a minor beside it still updates, and `SHIPKIT_ALLOW_MAJOR=1`, which `fleet --update --major` sets, is the one way through. **Type change**: `planSelfUpdate` takes `allowMajor` and `repo`.
+
+- **`fleet --update` performs the update.** It ran the repo's `check --fix SK005`, which every binary refuses (SK005 has no autofix), and a plain `check` would have replayed SK005's clean pass cached for 24h. It now runs `check --fresh` with the re-exec guard stripped, and judges by the versions node_modules carries after the run rather than by a printed line. A breaking dep no longer holds back a minor one in the same repo. The loop lives in `fleet/update-fleet.ts` (`updateFleet`).
+
+- **The first `check --fresh` after a release no longer exits 1.** The startup self-update decided on its 24h cached latest, then SK005 updated `node_modules/rvlib-shipkit` under the running process, and a check file loaded after the swap met modules of two versions ("layoutSummary export not found"). A fresh run now makes the startup self-update ask the registry, so it updates and restarts before any check loads (`maybeSelfUpdateAndRestart(root, { fresh })`, `latestCached`). SK005 never updates the copy that is running it (`isRunningCopy`): it stores the answer for the next startup (`rememberLatest`) and WARNs. `SHIPKIT_SELF_UPDATE_CACHE` overrides the cache file.
+
+- **A version bump restarts a hub under `bun --watch`.** The hub read its own version from package.json with fs, which keeps the file out of the module graph the watch follows, so a bump (which changes nothing but the version) left the hub running and its tree showed a red row asking for a restart. `LIB_VERSION` in `core/lib-version.ts` is a json module import now, and the cli `--version` and the motherhome row read it too. `diskLibVersion()` reads the file at call time.
+
+- **A plain `shipkit serve` whose lib moved under it restarts itself.** It compares its boot version with the package.json on disk every 2s and, once no run is in flight, re-executes in place: same pid, argv and port (`StaleRestart` in `serve/stale-restart.ts`, `reexecSelf` and `reexecBlocker` in `core/reexec.ts`, which the self-update restart also uses). A restart that cannot happen is said in the page header and on the problems frame, never as a tree row.
+
+- **No `health` kind.** `RESOURCE_TYPES` and `TYPE_MARK` lose `health`, the `health/` virtual folder is gone, and `repoHealthCollection` is `contractsCollection` (id `contracts`, rows under `contracts/`, ids `contract:` and `contractwarn:`). A check with no file of its own is filed under `checks/<id>`. `buildCollections` takes no version options. **Type change**: `Collection` requires `kind`, the kind of its rows, and a collection whose listing throws is one red row of that kind at `<collection>/collector` (`brokenRow`).
+
+- **The hub task's problem frame counts the hub's own problems.** A collection the hub could not list and a restart it could not do (`HubProblems` in `serve/hub-problems.ts`) print on the frame at once as `repo.config.ts:1:1: error hub: <text>`, which the existing matcher reads, so `shipkit problems: end, N error(s)` agrees with the page. `ProblemBoard.setHub`, `hubProblemLine` and `HUB_ANCHOR` carry it; `/api/resources.json` sends the list as `hub` and the header shows one chip per problem. `projectResources` and `projectNeeds` take an optional per collection callback. A page that cannot reach its server says so in the header instead of a fake tree row.
+
+
+- **A check that passes over its time budget warns.** Every check has a budget, what a healthy run takes, distinct from its `timeoutMs` ceiling: 2000ms for an in process body, 10000ms for a build step, a `cmd` check or a world probe (`IN_PROCESS_BUDGET_MS`, `SUBPROCESS_BUDGET_MS` in `core/budget.ts`). A pass over it prints `WARN <id> passed in 35.2s, over its 10s budget: see the tests page for where the time goes`, reads yellow in the hub, and lands in the problems pane as a warning; it never blocks and never fails the gate. It is judged on the wall time of a run that measured; a build step at the full tier carries no budget (it runs every slow suite on purpose, under its own cache key), and a check doing the same work at both tiers is judged at both. The line says `under load N on C cores` when the 1 minute load reached the core count. A cached answer keeps the warn it earned, and a slow pass is still remembered as long as a quick one. A check file declares `budgetMs`, and `repo.config.ts` `budgets: { <id>: ms }` wins over it, the way `when` does; an id there naming no check fails the run, like a `when` entry. The check page's timings row shows the budget, durations are toned against it, and "slowest checks" flags `over its budget` when the mean of a check's quick tier runs passes it. A check that only ran slow reads yellow but asks nothing of `shipkit needs`, and a probe that only ran slow still proves its secret (`isBudgetLine`). `CheckRow.budgetMs` and `RunnableCheck.budgetMs` carry the resolved value, `CheckRun` gains `unknownBudgets`, and `durationTone` takes the budget as a third argument. The run summary no longer says `all N check(s) green` when a check warned: it says `all N check(s) passed, M with a warning: <ids>`.
+
+- **A secret declares how much breaks without it: `creds[].level`.** `core` (the toolkit's own features stop: a push, creating a repo, a release) is red when it is missing or its probe fails, and a missing one reaches `shipkit needs` as red (a failed probe keeps a yellow needs line: its own check row carries the failure). `used`, the default (a feature the repo uses today), is orange with a yellow needs line that never pings. `minor` (proactive, nothing uses it yet) is dim, says `minor` in its tree slot and its sentence, and stays out of `shipkit needs`. Before, every missing secret was red and every failed probe was red on the tree, so a key for a service nobody uses yet shouted as loud as the one every release needs. `secretState` takes the level, `SecretLevel` and `DEFAULT_SECRET_LEVEL` are exported from `collections/state-rules.ts`. Present and probed green stays green at every level.
+
 ## 1.0.1
 
 - **A layout move lands once, and its commit says what it moved.** A tracked root `STATUS.md` that named an old folder was dropped and then written back by the text sweep in the same pass, so the move commit kept it, and the next run landed a second commit, titled as a move, that moved nothing and reported `moved  under .shipkit/`. A legacy generated file is now only dropped, never swept. The commit title is built from what the pass did (`chore(machine): move asks/ and .rv-identity/ under .shipkit/, and drop the root STATUS.md, which shipkit writes under .shipkit/`), so a pass that moves no folder never carries the move title, and the fix pass and SK004 print the same words (`layoutSummary` in `core/migrate-layout.ts`, which replaces `MIGRATION_MESSAGE`).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.0.1",
+    "version": "1.1.1",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/asks/asks-queue.ts

@@ -88,6 +88,32 @@ function checkAsksBody(dir: string, print: (line: string) => void): { closed: nu
     return { closed }
 }
 
+// the hub renders ask markdown, so a new ask starts as the page the human
+// follows: one section per step, a link that opens the exact page, values
+// to copy. Every {{placeholder}} is the author's to fill (braces, since markdown hides an unknown <tag>) before the ask ships
+const STEPS_BODY = `<!-- one "## N." section per step, in order. Each opens with ONE bold link you have seen work, ids filled in; with none, link the nearest known page and name the one click from there. Values in the table, buttons in bold, a why line only where skipping breaks something. -->
+
+## 1. {{verb}} {{thing}}
+
+Open **[{{page name}}]({{url, ids filled in}})**, then click **{{button}}**.
+
+| field | value |
+|---|---|
+| {{field}} | \`{{value}}\` |
+
+## 2. Tell the agent "done"
+
+{{what the agent does next, and what the human clicks during it}}
+`
+
+const DECISION_BODY = `<!-- a decision: numbered options, the recommended one first, each with what it costs and what it changes. -->
+
+1. **{{option}} (recommended)**: {{what it changes, what it costs}}
+2. **{{option}}**: {{what it changes, what it costs}}
+
+Reply with the number.
+`
+
 export function createAsk(dir: string, title: string, opts?: CreateOpts): string {
     mkdirSync(dir, { recursive: true })
     // max numeric prefix across BOTH live and archived asks — numbers are never reused
@@ -102,6 +128,7 @@ export function createAsk(dir: string, title: string, opts?: CreateOpts): string
     // "TODO" that never gets filled (the ask itself is the record).
     const why = opts?.why?.trim()
     const whyBlock = why != null && why !== '' ? `**Why**: ${why}\n\n` : ''
+    const doneWhen = check != null ? `\`${check}\` exits 0` : 'status flipped to done'
     writeFileSync(join(dir, file), `---
 status: open
 kind: ${opts?.kind ?? 'action'}
@@ -111,11 +138,10 @@ blocks: ${opts?.blocks ?? '-'}${check != null ? `\ncheck: ${check}` : ''}
 
 # ${title}
 
-**Ask**: ${title}
-
-${whyBlock}**Answer**: _(fill in / check off, or just do it — the check probe auto-closes when it passes)_
+${whyBlock}${opts?.kind === 'decision' ? DECISION_BODY : STEPS_BODY}
+**Answer**: _(fill in / check off, or just do it — the check probe auto-closes when it passes)_
 
-**Done when**: ${check != null ? `\`${check}\` exits 0` : 'status flipped to done'}
+**Done when**: ${doneWhen}
 `)
     return file
 }

package/src/check.ts

@@ -122,6 +122,12 @@ export type CheckDef = {
     /** wall clock ceiling in ms. A `cmd` check is killed with its whole
      *  process tree at the ceiling. */
     timeoutMs?: number
+    /** what a healthy run takes, in ms, distinct from the ceiling: a run that
+     *  passes over it prints a WARN and reads yellow, and never blocks.
+     *  Judged on the wall time of a run that measured, at the quick tier.
+     *  Default 2000 for an in process body, 10000 for a build step, a `cmd`
+     *  or a world probe (core/budget.ts). The repo's `budgets` wins over it. */
+    budgetMs?: number
     /** a label several checks share, so `--skip <group>` parks all of them
      *  and `--only <group>` runs all of them. */
     group?: string

package/src/checks/SK005-rvlib-versions.check.ts

@@ -10,7 +10,12 @@
 // Per rvlib-* dep:
 //   link:   → the symlink must resolve (a broken link dies cryptically at
 //             import time otherwise) — nothing to update, code is live
-//   semver  → installed vs npm latest; NEWER LIVE → this lint updates the
+//   semver  → installed vs npm latest; a BREAKING jump (a new major, or a
+//             new 0.x minor) is never taken by itself
+//             (src/core/update-policy.ts: WARN naming `fleet --update --major`,
+//             package.json untouched); the rvlib-shipkit tree running this
+//             process is never swapped mid run, the startup self-update owns
+//             it (src/core/self-update.ts); NEWER LIVE → this lint updates the
 //             dep itself, loudly, with the manager the repo's own lock files
 //             name (src/core/package-manager.ts), guarded:
 //             - SHIPKIT_FROZEN=1 (`check --frozen`, `ci --frozen`) → WARN,
@@ -39,8 +44,10 @@
 // are NOT scanned: keeping a published lib's peer ranges consistent after
 // a bump stays the agent's job.
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { basename, join } from 'path'
 import type { CheckCtx } from '../core/check-ctx.ts'
+import { allowMajor, breakingAdvice, isBreaking } from '../core/update-policy.ts'
+import { isRunningCopy, rememberLatest } from '../core/self-update.ts'
 import { mutateLease, withMutateLease } from '../core/locked-write.ts'
 import { detectPackageManager, isRefusal, LOCK_FILES } from '../core/package-manager.ts'
 import { check, type CheckEnv } from '../check.ts'
@@ -107,7 +114,15 @@ export const rvlibVersions = check({
             const cmp = Bun.semver.order(latest, installed)
             if (cmp === 0) c.ok(`${name} ${installed} (latest)`)
             else if (cmp < 0) c.ok(`${name} ${installed} ahead of npm latest ${latest} (prerelease or dist-tag lag) — not touching`)
-            else stale.push({ name, installed, latest })
+            else if (isBreaking(installed, latest) && !allowMajor()) c.warn(breakingAdvice(name, latest, basename(c.root)))
+            else if (name === 'rvlib-shipkit' && isRunningCopy(c.root)) {
+                // swapping this tree under the running process is how a run
+                // meets modules of two versions. The startup self-update owns
+                // it: handing it the answer makes the next run update and
+                // restart before any check loads
+                rememberLatest(latest)
+                c.warn(`${name} ${installed} → ${latest} is the toolkit running this check, so it is not swapped mid run: the next shipkit run updates it and restarts before any check`)
+            } else stale.push({ name, installed, latest })
         }
         if (stale.length === 0) return
 

package/src/checks/SK021-github-login.check.ts

@@ -0,0 +1,123 @@
+// SK021: the gh login the toolkit itself runs on: `init` and `start` create
+// a PRIVATE repo with it, every push and release goes through it, SK007 reads
+// visibility with it. gh keeps that login outside any secrets manager, so this
+// probe is the only place a lost one shows. It is a `core` credential: red on
+// the secrets page and in `shipkit needs` (collections/providers.ts reads the
+// `cred <name> missing` line), while the check itself is about the world, so
+// it never blocks a gate and runs in the health pass only.
+//
+// A private repo needs the classic `repo` scope. The token itself is never
+// asked for: `gh auth status --json` carries no token field, and the text
+// answer masks it. github.com unreachable is `unreachable`, a WARN that
+// measured nothing, never a lost login.
+import { carveGhJson, firstGhLine } from '../git-bootstrap.ts'
+import { check } from '../check.ts'
+
+const HOST = 'github.com'
+
+/** the secrets page row this check proves: a built-in `core` credential
+ *  every repo has, shown once SK021 has run there */
+export const GH_LOGIN_CRED = {
+    name: 'gh/github/login',
+    service: 'gh login',
+    level: 'core' as const,
+    probedBy: 'SK021',
+    mintUrl: 'https://cli.github.com/manual/gh_auth_login',
+    /** what the row offers to copy when no failing line names a better fix */
+    command: 'gh auth login',
+}
+
+/** what gh said about the github.com login, whichever output shape it used */
+export type GhLogin =
+    | { state: 'none' }
+    | { state: 'ok'; login: string; scopes: string[] | null }
+    | { state: 'refused'; source: string; why: string }
+    | { state: 'unreachable'; why: string }
+    | { state: 'unreadable'; why: string }
+
+const NETWORK = /dial tcp|no such host|connection refused|network is unreachable|i\/o timeout|timeout|tls handshake|connection reset|\bEOF\b/i
+
+type HostEntry = { state?: string; login?: string; scopes?: string; error?: string; tokenSource?: string; active?: boolean }
+
+const scopesOf = (raw: string | undefined): string[] | null => {
+    const list = (raw ?? '').split(',').map((s) => s.trim().replace(/^'|'$/g, '')).filter((s) => s !== '')
+    return list.length === 0 ? null : list
+}
+
+/** `gh auth status --json hosts`, the shape gh 2.7x and later print */
+export function readGhJson(out: string): GhLogin {
+    const parsed = carveGhJson<{ hosts?: Record<string, HostEntry[]> }>(out)
+    if (parsed?.hosts == null) return { state: 'unreadable', why: firstGhLine(out) }
+    const entries = parsed.hosts[HOST] ?? []
+    const e = entries.find((x) => x.active === true) ?? entries[0]
+    if (e == null) return { state: 'none' }
+    if (e.state === 'success') return { state: 'ok', login: e.login ?? '?', scopes: scopesOf(e.scopes) }
+    const why = firstGhLine(e.error ?? e.state ?? 'unknown')
+    if (e.state === 'timeout' || NETWORK.test(why)) return { state: 'unreachable', why }
+    // `non-200 OK status code: 401 Unauthorized body: "{...}"` → `401 Unauthorized, Bad credentials`
+    const status = why.match(/\b(\d{3} [A-Za-z][A-Za-z ]*?)(?: body:|$)/)?.[1]
+    const message = why.match(/message\W+([^"\\]+)/)?.[1]
+    return { state: 'refused', source: e.tokenSource ?? 'its token', why: status == null ? why : [status, message].filter((s) => s != null).join(', ') }
+}
+
+/** the plain text answer, for a gh too old to print json */
+export function readGhText(out: string): GhLogin {
+    if (/not logged in/i.test(out)) return { state: 'none' }
+    const failed = out.match(/Failed to log in to \S+ (?:using token \(([^)]+)\)|account \S+ \(([^)]+)\))/)
+    if (failed != null) {
+        const why = out.split('\n').map((l) => l.trim().replace(/^- /, '')).find((l) => /invalid|expired|revoked|401/i.test(l)) ?? 'the token was refused'
+        if (NETWORK.test(out)) return { state: 'unreachable', why: firstGhLine(why) }
+        return { state: 'refused', source: failed[1] ?? failed[2] ?? 'its token', why }
+    }
+    if (NETWORK.test(out) && !/Logged in to/.test(out)) return { state: 'unreachable', why: firstGhLine(out) }
+    const login = out.match(/Logged in to \S+ (?:account|as) (\S+)/)
+    if (login == null) return { state: 'unreadable', why: firstGhLine(out) }
+    const scopes = out.match(/Token scopes: (.*)$/m)
+    return { state: 'ok', login: login[1]!, scopes: scopesOf(scopes?.[1]) }
+}
+
+export const githubLogin = check({
+    id: 'SK021',
+    // about the world, never this repo: a lost login warns in a gate and is
+    // red on the secrets page and in needs, through the core credential row
+    blocking: false,
+    title: 'github login',
+    description: 'gh is logged in to github.com with the repo scope shipkit creates repos with',
+    owner: 'build/shipkit/built-in-checks.md',
+    when: 'health',
+    ttl: '1h',
+    run: async (c) => {
+        const cred = GH_LOGIN_CRED.name
+        // the switch that keeps every github step off (git-bootstrap.ts), which every test suite sets
+        if ((process.env['SHIPKIT_NO_GITHUB'] ?? '') !== '') return void c.lines.push({ kind: 'skip', text: 'gh login not probed, SHIPKIT_NO_GITHUB is set' })
+        const gh = c.tool('gh')
+        if (gh == null)
+            return c.fail(`cred ${cred} missing: gh is not installed, so shipkit cannot create a repo, push or release`, 'install gh (https://cli.github.com), then run `gh auth login`')
+
+        let r = await c.exec([gh, 'auth', 'status', '--hostname', HOST, '--active', '--json', 'hosts'], { cwd: c.root, timeoutMs: 20_000 })
+        let seen: GhLogin
+        if (r.code !== 0 && /unknown flag/i.test(r.out)) {
+            r = await c.exec([gh, 'auth', 'status', '--hostname', HOST], { cwd: c.root, timeoutMs: 20_000 })
+            seen = readGhText(r.out)
+        } else seen = r.timedOut ? { state: 'unreachable', why: 'gh auth status timed out' } : readGhJson(r.out)
+
+        switch (seen.state) {
+            case 'none':
+                return c.fail(`cred ${cred} missing: gh is not logged in to ${HOST}, so shipkit cannot create a repo, push or release`, 'gh auth login')
+            case 'refused':
+                return c.fail(`cred ${cred} missing: the gh login from ${seen.source} was refused by ${HOST} (${seen.why.slice(0, 120)})`, 'gh auth login')
+            case 'unreachable':
+                return c.unreachable(`gh login unverified: ${HOST} unreachable (${seen.why.slice(0, 120)})`)
+            case 'unreadable':
+                return c.unreachable(`gh login unverified: gh answered something unreadable (${seen.why})`)
+            case 'ok':
+                if (seen.scopes == null)
+                    return c.warn(`gh is logged in to ${HOST} as ${seen.login}, but its token lists no oauth scopes (a fine grained or app token), so creating a private repo is unverified`, 'gh auth login')
+                if (!seen.scopes.includes('repo'))
+                    return c.fail(`cred ${cred} missing: the gh login ${seen.login} lacks the repo scope (it has ${seen.scopes.join(', ')}), so shipkit cannot create a private repo`, `gh auth refresh -h ${HOST} -s repo`)
+                return c.ok(`gh is logged in to ${HOST} as ${seen.login}, with the repo scope`)
+        }
+    },
+})
+
+export default githubLogin

package/src/cli/cmd_Asks.ts

@@ -75,7 +75,7 @@ export class AskNewCommand extends Command {
         try {
             const dir = await asksDir(process.cwd())
             const file = createAsk(dir, this.title, { kind: this.kind, blocks: this.blocks, check: this.check, why: this.why })
-            this.context.stdout.write(`created ${dir}/${file}\n`)
+            this.context.stdout.write(`created ${dir}/${file}\nfill every {{placeholder}} in it: the hub shows the body as written\n`)
             return 0
         } catch (e) {
             this.context.stderr.write(`FAIL: ${e instanceof Error ? e.message : String(e)}\n`)

package/src/cli/cmd_Check.ts

@@ -31,7 +31,7 @@ export class CheckCommand extends Command {
     async execute(): Promise<number> {
         // a stale toolkit updates itself and restarts this exact invocation
         // (loop-guarded, skipped under CI/frozen/source consumption)
-        await maybeSelfUpdateAndRestart(process.cwd())
+        await maybeSelfUpdateAndRestart(process.cwd(), { fresh: this.fresh })
         try {
             if (this.fixIds.length > 0 && !this.fix) {
                 this.context.stderr.write(`FAIL: check ids need --fix (shipkit check --fix ${this.fixIds.join(' ')})\n`)

package/src/cli/cmd_Ci.ts

@@ -70,7 +70,7 @@ export class CiCommand extends Command {
     private async gate(root: string): Promise<number> {
         // a stale toolkit updates itself and restarts this exact invocation
         // (loop-guarded, skipped under CI/frozen/source consumption)
-        await maybeSelfUpdateAndRestart(root)
+        await maybeSelfUpdateAndRestart(root, { fresh: this.fresh })
         try {
             return await runCi(root, {
                 bail: this.bail,

package/src/cli/cmd_Fleet.ts

@@ -3,19 +3,9 @@
 // each repo's OWN shipkit, so rule SK005 performs the update with the lease,
 // the dirty-tree guard and the frozen guard it already owns.
 import { Command, Option } from 'clipanion'
-import { existsSync } from 'fs'
 import { join } from 'path'
-import { npmLatest, resolveLatest, scanFleet, updateRefusal, type FleetRepo } from '../fleet/scan-fleet.ts'
-import { spawnWithTimeout } from '../core/spawn-timeout.ts'
-import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
-
-const short = (name: string): string => name.replace(/^rvlib-/, '')
-// the hand-run fallback speaks the manager THAT repo installs with: telling
-// an npm consumer to run bun leaves its package-lock.json behind
-const manualUpdate = (r: FleetRepo): string => {
-    const pm = detectPackageManager(r.dir)
-    return isRefusal(pm) ? `<its package manager> update ${r.behind.map((d) => d.name).join(' ')} (${pm.refused})` : pm.update(r.behind.map((d) => d.name)).join(' ')
-}
+import { npmLatest, resolveLatest, scanFleet, type FleetRepo } from '../fleet/scan-fleet.ts'
+import { short, updateFleet } from '../fleet/update-fleet.ts'
 
 export class FleetCommand extends Command {
     static override paths = [['fleet']]
@@ -36,7 +26,7 @@ export class FleetCommand extends Command {
     update = Option.Boolean('--update', false, { description: "run each behind repo's own `shipkit check`, which is where rule SK005 performs the guarded update" })
     only = Option.Array('--only', { description: 'limit to these repo directory names (repeatable)' })
     offline = Option.Boolean('--offline', false, { description: 'skip the registry: report what is installed, never what is current' })
-    major = Option.Boolean('--major', false, { description: 'let --update cross a breaking boundary too. Default off: a major (or a 0.x minor) is a porting job, not a bump' })
+    major = Option.Boolean('--major', false, { description: 'let --update cross a breaking boundary too. Default off: a major (or a 0.x minor, as npm caret reads it) is a porting job, not a bump, and no automatic update path takes one' })
     json = Option.Boolean('--json', false, { description: 'machine-readable FleetRepo[]' })
 
     async execute(): Promise<number> {
@@ -69,7 +59,8 @@ export class FleetCommand extends Command {
             w(`WARN ${behind.length}/${repos.length} repo(s) behind — rerun with --update, which runs each repo's own gate so SK005 does the write`)
             return 0
         }
-        return await this.runUpdates(behind, w)
+        await updateFleet(behind, { major: this.major, print: w })
+        return 0
     }
 
     private row(r: FleetRepo): string {
@@ -83,47 +74,4 @@ export class FleetCommand extends Command {
         const flag = r.linked ? 'source' : r.breaking.length > 0 ? `${r.breaking.length} BREAKING` : r.behind.length > 0 ? `${r.behind.length} behind` : 'current'
         return `  ${r.name.padEnd(24)} ${flag.padEnd(10)} ${cells.join(', ')}`
     }
-
-    /** the update is NOT performed here. Each repo runs its own binary, which
-     *  is the only copy whose SK005 matches the rules that repo is pinned to,
-     *  and the only one holding that repo's mutate lease. */
-    private async runUpdates(behind: FleetRepo[], w: (l: string) => void): Promise<number> {
-        let failed = 0
-        for (const r of behind) {
-            if (r.breaking.length > 0 && !this.major) {
-                w(`WARN ${r.name}: ${r.breaking.map((d) => `${short(d.name)} ${d.installed} → ${d.latest}`).join(', ')} crosses a breaking boundary — that is a porting job. Rerun with --major once somebody owns it`)
-                failed++
-                continue
-            }
-            const refused = updateRefusal(r)
-            if (refused != null) {
-                w(`WARN ${r.name}: not updating: ${refused}`)
-                failed++
-                continue
-            }
-            const cli = join(r.dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')
-            if (!existsSync(cli)) {
-                w(`WARN ${r.name}: no shipkit installed, so it cannot update itself — run: cd ${r.dir} && ${manualUpdate(r)}`)
-                failed++
-                continue
-            }
-            // `check --fix SK005` is the narrow form: a bare rule id is refused,
-            // and a full `check` pays for every world probe to reach one rule
-            const res = await spawnWithTimeout(['bun', cli, 'check', '--fix', 'SK005'], { cwd: r.dir, timeoutMs: 180_000 })
-            // judge by what SK005 SAID, never by the exit code: that code covers
-            // every rule in that repo, and a repo can be red for a reason this
-            // command neither caused nor owns
-            const line = res.out.split('\n').find((l) => /\brvlib-/.test(l) && (l.startsWith('ok:') || l.startsWith('WARN') || l.startsWith('FAIL')))
-            if (line?.startsWith('ok:') === true) w(`ok: ${r.name} — ${line.slice(4)}`)
-            else {
-                failed++
-                w(`WARN ${r.name} did not move — ${line ?? `check exited ${res.code} with no rvlib line`}`)
-                w(`      fix: cd ${r.dir} && ${manualUpdate(r)}`)
-            }
-        }
-        // a repo whose gate refused (dirty tree, frozen, a lease held elsewhere)
-        // is a REPORT, not a failure of this command: SK005 defers on purpose
-        w(failed === 0 ? `ok: ${behind.length} repo(s) updated through their own gate` : `WARN ${failed}/${behind.length} repo(s) did not update — each line above says why`)
-        return 0
-    }
 }

package/src/cli.ts

@@ -2,7 +2,7 @@
 // shipkit — clipanion entry: one command FAMILY per file in cli/ (cmd_<Name>.ts),
 // logic in plain modules the commands call. runExit sets the exit code
 // without force-exiting, so serve commands keep the process alive.
-import { readFileSync } from 'fs'
+import { LIB_VERSION } from './core/lib-version.ts'
 import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
 import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
@@ -31,7 +31,6 @@ import { StartCommand } from './cli/cmd_Start.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
-const version = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
 
 /** the registry, built but NOT run: a test drives the real binary in process
  *  instead of paying a cold bun start per assertion (~250ms each), and the
@@ -40,7 +39,7 @@ export function buildCli(): Cli {
     const cli = new Cli({
         binaryLabel: 'shipkit — repo toolkit',
         binaryName: 'shipkit',
-        binaryVersion: version,
+        binaryVersion: LIB_VERSION,
         enableCapture: true, // console output pipes into the command streams (testable)
         enableColors: true,
     })

package/src/collections/checks.ts

@@ -26,6 +26,7 @@ import { NEGATIVE_TTL_CAP_MS } from '../ledger/world-cache.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import type { Collection, Instance, NeedSeverity, ResourceState, CheckFacts, RecentRun } from './collection-types.ts'
 import { checkVerdictWords, plural } from '../core/outcome-words.ts'
+import { isBudgetLine } from '../core/budget.ts'
 
 /** what a check is killed at when it names no `timeoutMs`: a build step runs a
  *  whole tool chain, everything else answers one question */
@@ -61,6 +62,7 @@ export function checksCollection(root: string, c: RepoConfig, o: ChecksOpts = {}
     return {
         id: 'checks',
         title: 'gate checks',
+        kind: 'check',
         media: 'health',
         list: async () => {
             const rows = await gateInventory(root, c)
@@ -129,6 +131,7 @@ function instanceOf(root: string, c: RepoConfig, row: CheckRow, stat: CheckStat
         never: row.decl.never ?? undefined,
         reads: row.decl.reads === true ? true : undefined,
         timeoutMs: row.timeoutMs ?? (row.build ? BUILD_TIMEOUT_MS : CHECK_TIMEOUT_MS),
+        budgetMs: row.budgetMs,
         status,
         replayed,
         lastMs: stat?.last == null || replayed ? null : stat.last.ms,
@@ -231,16 +234,23 @@ function stateOf(f: CheckFacts): ResourceState {
  *  notification at night. */
 function severityOf(f: CheckFacts): NeedSeverity | undefined {
     if (f.status === 'fail') return f.advisory ? 'yellow' : 'red'
-    if (f.status === 'warn') return 'yellow'
+    // a check that only ran over its time budget is work for whoever makes it
+    // faster, never a line asking for his hands: yellow on the tree, no feed
+    if (f.status === 'warn') return onlySlow(f) ? undefined : 'yellow'
     return undefined
 }
 
+const onlySlow = (f: CheckFacts): boolean => {
+    const warns = f.lastLines.filter((l) => l.startsWith('WARN '))
+    return warns.length > 0 && warns.every((l) => isBudgetLine(l.slice('WARN '.length)))
+}
+
 /** where the check lives on the tree. A check that IS a file in this repo, or
  *  whose owner page is one, sits beside everything else in that folder, which
  *  is the whole payoff of pathing resources. A build step is a command, so it
  *  has no file and says so under a virtual root. */
 function place(root: string, c: RepoConfig, row: CheckRow): Pick<Instance, 'path' | 'virtual'> {
-    const virtual = { path: `health/check/${row.decl.id}`, virtual: true as const }
+    const virtual = { path: `checks/${row.decl.id}`, virtual: true as const }
     if (row.owner == null || ownerIsCommand(row)) return virtual
     const rel = repoRelative(root, row.owner) ?? repoRelative(root, `${c.docsBase ?? ''}${row.owner}`)
     return rel == null ? virtual : { path: rel }

package/src/collections/collection-types.ts

@@ -26,9 +26,10 @@ export const testId = (file: string): string => `test:${file}`
 export const NO_CHECK = 'in no check'
 
 /** the resource KIND, never the collection it came from: one folder holds
- *  several kinds, which is what makes the path tree worth having. `health`
- *  is what belongs to no check (the hub's own staleness line) */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'health', 'check', 'test', 'reflection'] as const
+ *  several kinds, which is what makes the path tree worth having. There is no
+ *  catch all kind: a row belongs to an owner, and what belongs to the hub
+ *  itself is its status (serve/hub-problems.ts), never a row */
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection'] as const
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 
@@ -97,6 +98,8 @@ export type CheckFacts = {
     /** where it is killed: a check creeping toward its ceiling is visible
      *  before it trips */
     timeoutMs: number
+    /** what a healthy run takes (core/budget.ts): a pass over it warns */
+    budgetMs: number
     status: 'pass' | 'warn' | 'fail' | 'skip' | null
     replayed: boolean
     /** what the last run cost, ms. null on a replay: it measured nothing */
@@ -248,6 +251,9 @@ export type Instance = {
 export type Collection = {
     id: string
     title: string
+    /** the kind of the rows it lists, which is also the kind of the one row
+     *  that says its listing broke */
+    kind: ResourceType
     media: 'image' | 'audio' | 'text' | 'data' | 'pointer' | 'health'
     /** wire tone when any needing instance is only yellow */
     list: () => Promise<Instance[]>
@@ -263,7 +269,7 @@ export type Resource = Instance & { collection: string; title: string; state: Re
 
 /** PROACTIVE kinds: work waiting on a human, which is not the same thing as
  *  something being broken. Red is reserved for broken (a blocking check that
- *  failed, a secret a page needs and does not have, a collector that threw),
+ *  failed, a `core` secret missing or refused, a collector that threw),
  *  so these read as taste pending on the tree. Their `severity` is untouched,
  *  because that is the axis `shipkit needs` and the once ever ping read */
 const PROACTIVE: ReadonlySet<ResourceType> = new Set<ResourceType>(['ask'])
@@ -277,25 +283,33 @@ export async function listResources(c: Collection): Promise<Resource[]> {
     return (await c.list()).map((i) => ({ ...i, collection: c.id, title: i.label ?? i.text, state: stateOf(i) }))
 }
 
+/** the ONE row a collection whose listing threw is reduced to: its own kind,
+ *  filed in its own folder, red */
+export const brokenRow = (c: Collection, e: unknown): Instance => ({
+    id: `${c.id}:broken`,
+    type: c.kind,
+    path: `${c.id}/collector`,
+    virtual: true,
+    text: `collector broke: ${(e as Error).message}`,
+    severity: 'red',
+})
+
+/** told, per collection, whether its listing broke (the message) or not
+ *  (null), so the hub can carry it in its own status */
+export type OnCollector = (collection: string, error: string | null) => void
+
 /** every resource of every collection, failure-isolated per collection: a
  *  broken source reports itself as ONE red row, never blanks the tree */
-export async function projectResources(collections: Collection[]): Promise<Resource[]> {
+export async function projectResources(collections: Collection[], onCollector?: OnCollector): Promise<Resource[]> {
     const out: Resource[] = []
     for (const c of collections) {
         try {
             out.push(...(await listResources(c)))
+            onCollector?.(c.id, null)
         } catch (e) {
-            out.push({
-                collection: c.id,
-                id: `${c.id}:broken`,
-                type: 'health',
-                path: `health/${c.id}-collector`,
-                virtual: true,
-                title: `collector broke: ${(e as Error).message}`,
-                text: `collector broke: ${(e as Error).message}`,
-                severity: 'red',
-                state: 'red',
-            })
+            const row = brokenRow(c, e)
+            out.push({ ...row, collection: c.id, title: row.text, state: 'red' })
+            onCollector?.(c.id, (e as Error).message)
         }
     }
     return out
@@ -303,13 +317,15 @@ export async function projectResources(collections: Collection[]): Promise<Resou
 
 /** the flat needs projection — failure-isolated per collection: a broken
  *  source reports itself as ONE red item, never blanks the feed */
-export async function projectNeeds(collections: Collection[]): Promise<NeedItem[]> {
+export async function projectNeeds(collections: Collection[], onCollector?: OnCollector): Promise<NeedItem[]> {
     const out: NeedItem[] = []
     for (const c of collections) {
         try {
             for (const i of await c.list()) if (i.severity != null) out.push({ ...i, collection: c.id })
+            onCollector?.(c.id, null)
         } catch (e) {
-            out.push({ collection: c.id, id: `${c.id}:broken`, type: 'health', path: `health/${c.id}-collector`, virtual: true, text: `collector broke: ${(e as Error).message}`, severity: 'red' })
+            out.push({ ...brokenRow(c, e), collection: c.id })
+            onCollector?.(c.id, (e as Error).message)
         }
     }
     return out