rvlib-shipkit 1.2.0 → 1.4.0

package/src/{checks/SK021-github-login.check.ts → core/gh-login.ts}

@@ -1,27 +1,30 @@
-// 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.
+// 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 the
+// house repo's one `github-login` check (a machine fact, asked once, never in
+// every repo) runs `probeGhLogin`. It is a `core` credential: red on the
+// secrets page and in `shipkit needs` (collections/providers.ts reads the
+// `cred <name> missing` line).
 //
 // 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'
+import type { CheckCtx } from './check-ctx.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 */
+/** the id of the house check that runs `probeGhLogin` */
+export const GH_LOGIN_CHECK = 'github-login'
+
+/** the secrets page row the probe proves: a built-in `core` credential, shown
+ *  in the repo where the `github-login` check has run */
 export const GH_LOGIN_CRED = {
     name: 'gh/github/login',
     service: 'gh login',
     level: 'core' as const,
-    probedBy: 'SK021',
+    probedBy: GH_LOGIN_CHECK,
     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',
@@ -76,48 +79,36 @@ export function readGhText(out: string): GhLogin {
     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)
+/** the probe: logged in to github.com, with the repo scope */
+export async function probeGhLogin(c: CheckCtx): Promise<void> {
+    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`')
 
-        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`)
-        }
-    },
-})
+    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)
 
-export default githubLogin
+    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`)
+    }
+}

package/src/core/identity-color.ts

@@ -116,7 +116,7 @@ const KEY_RE = /(?:^|[{,])\s*(['"]?)identity\1\s*:\s*/gm
 
 /** per char of the text: the object depth inside `defineRepo({` after that
  *  char (1 on the top level keys), or -1 inside a string or a comment */
-function configDepths(text: string): Int32Array {
+export function configDepths(text: string): Int32Array {
     const depth = new Int32Array(text.length).fill(0)
     const open = /defineRepo\(\s*\{/.exec(text)
     if (open == null) return depth

package/src/core/layout.ts

@@ -32,6 +32,8 @@ export const LAYOUT = {
     reviews: sk('reviews'),
     // scratch: plans, logs, leases, detached runs, screenshots
     tmp: sk('tmp'),
+    // built app bundles, one per global process opened as an app (home/gui-app.ts)
+    wrapper: sk('wrapper'),
     // generated on every run
     status: sk('STATUS.md'),
     statusFull: sk('STATUS.full.md'),

package/src/core/motherhome.ts

@@ -1,15 +1,20 @@
-// Report to the motherhome — upsert this repo's row into the docsBase
-// wiki's `build/shipkit/local-projects.md`, when that page ALREADY EXISTS
-// on this disk. The lib NEVER creates the page and never writes into a
-// relative or URL docsBase: the page is a tracked wiki file, so a real
-// docs checkout has it, and a consumer that merely set docsBase as a
-// fix-pointer prefix must never find surprise files in its docs tree.
-// The whole read-modify-write runs under the shared file lock
-// (core/locked-write) — concurrent reporters never lose rows or tear the
-// file; the loser skips and self-heals on its next run. Rows whose repo
-// path no longer exists are pruned on every write. Churn control: a row
-// rewrites only when its DATA changes or its last-seen day is older than
-// 7 days. Never fails the calling command.
+// Report to the motherhome: a repo's row in the docsBase wiki's
+// `build/shipkit/local-projects.md`, in two halves.
+//
+// - `reportToMotherhome` (every ci/check/init) files the row in the MACHINE
+//   DB and nothing else. A gate answers about its own repo, so it never
+//   writes, let alone commits, in the docs repo.
+// - `landMotherhome` (the daemon's hourly sweep) renders every filed row into
+//   its page and lands the page as ONE commit, at most once per LAND_GAP_MS
+//   per page, only when a row's data changed or its last-seen day is older
+//   than STALE_DAYS.
+//
+// The lib NEVER creates the page and never reads a relative or URL docsBase:
+// the page is a tracked wiki file, so a real docs checkout has it, and a
+// consumer that merely set docsBase as a fix-pointer prefix must never find
+// surprise files in its docs tree. The page's read-modify-write runs under
+// the shared file lock (core/locked-write). Rows whose repo path no longer
+// exists are pruned from the page and from the machine db.
 import { existsSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
@@ -17,46 +22,31 @@ import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
 import { isLinkedWorktree } from './git-root.ts'
 import { machineCommit } from './machine-commit.ts'
+import { machineDelete, machineGet, machineList, machineSet } from './machine-db.ts'
 import { LIB_VERSION } from './lib-version.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
 const END = '<!-- <<< shipkit local-projects -->'
 const STALE_DAYS = 7
+/** the longest the page waits for a changed row: one commit a day at most */
+export const LAND_GAP_MS = 24 * 60 * 60 * 1000
+/** a row filed in the machine db, by its repo's path */
+const ROW = 'motherhome:'
+/** when a page last landed, by its path */
+const LANDED = 'motherhome-landed:'
 
 type Row = { name: string; root: string; version: string; mode: string; seen: string }
+type Filed = Row & { page: string }
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
-/**
- * Commit the row we just wrote, and ONLY that file.
- *
- * This page is machine written and rewrites whenever a repo's shipkit version
- * or consumption mode changes, so left alone it dirties the docs repo from a
- * gate run nobody associates with it, and the dirt then rides into an unrelated
- * commit or blocks a release. The row is not worth a human's attention in
- * either direction, so the machine that writes it also lands it.
- *
- * The scoping, the refusals and the escape hatch live in `core/machine-commit`,
- * which every machine written path commits through. This one fires only when
- * the row's DATA changed, not on every gate, so the hooks it runs are affordable.
- */
-function autoCommitRow(page: string, name: string): string {
-    const landed = machineCommit({
-        anchor: resolve(page, '..'),
-        message: `chore(machine): refresh local-projects row (${name})`,
-        paths: [page],
-    })
-    return landed ? ' + committed' : ''
-}
-
 const parseRow = (line: string): Row | null => {
     const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
 }
 
-
-// how this repo consumes the lib — `?` on an unreadable package.json (a
-// read failure must never be rendered as the fact 'path')
+// how this repo consumes the lib: `?` on an unreadable package.json (a read
+// failure must never be rendered as the fact 'path')
 function consumptionMode(root: string): string {
     try {
         const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -70,47 +60,79 @@ function consumptionMode(root: string): string {
 
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
+/** file this repo's row in the machine db. `wrote` says the filed row changed */
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
     try {
         if (config.docsBase == null) return { wrote: false }
         const base = config.docsBase.startsWith('~/') ? join(homedir(), config.docsBase.slice(2)) : config.docsBase
-        // absolute local paths only — a relative docsBase would resolve
+        // absolute local paths only: a relative docsBase would resolve
         // against CWD, a URL is a display prefix
         if (!base.startsWith('/')) return { wrote: false }
         const page = join(base, 'build/shipkit/local-projects.md')
         if (!existsSync(page)) return { wrote: false }
-        // a gate run inside a linked worktree must not write the MAIN
-        // checkout's tracked page: the row it would add describes a temporary
-        // side checkout, and the write lands as unexplained dirt in a tree
-        // somebody else is working in. The worktree's own runs are covered
-        // when its branch merges.
+        // a linked worktree is a temporary side checkout: its runs are
+        // covered when its branch merges
         if (isLinkedWorktree(root)) return { wrote: false, note: `motherhome: skipped (${config.name} is a linked worktree — its row belongs to the main checkout)` }
-
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version
-        // string names — disclose it
+        // string names: disclose it
         const version = mode === 'npm' ? LIB_VERSION : `${LIB_VERSION}+src`
-        const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
-
-        const r = withFileLock(page, (): MotherhomeOutcome => {
-            const lines = readFileSync(page, 'utf8').split('\n')
-            const b = lines.indexOf(BEGIN)
-            const e = lines.indexOf(END)
-            if (b === -1 || e === -1 || e < b) return { wrote: false, note: `WARN motherhome upsert skipped — markers missing/corrupted in ${page}` }
-            const rows = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
-            const cur = rows.find((row) => row.root === me.root)
-            const dataSame = cur != null && cur.name === me.name && cur.version === me.version && cur.mode === me.mode
-            const fresh = cur != null && (Date.parse(today) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
-            if (dataSame && fresh) return { wrote: false }
-            // prune rows for repos that no longer exist at their recorded path
-            const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
-            atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
-            const committed = autoCommitRow(page, me.name)
-            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})${committed}` }
-        })
-        // lock lost to a racing reporter — self-heals on the next run
-        return r.ok ? r.value : { wrote: false }
+        const me: Filed = { page, name: config.name, root: resolve(root), version, mode, seen: today }
+        const key = `${ROW}${me.root}`
+        if (JSON.stringify(machineGet<Filed>(key)) === JSON.stringify(me)) return { wrote: false }
+        return machineSet(key, me) ? { wrote: true } : { wrote: false, note: 'WARN motherhome row not filed: the machine db could not be written' }
     } catch (err) {
-        return { wrote: false, note: `WARN motherhome upsert failed (${String(err).slice(0, 120)}) — registry may be stale` }
+        return { wrote: false, note: `WARN motherhome row not filed (${String(err).slice(0, 120)})` }
+    }
+}
+
+/** a page's rows once the filed ones are merged in: a filed row replaces the
+ *  page's only when its data changed or the page's day is STALE_DAYS old,
+ *  and a row whose repo path is gone is pruned */
+function mergeRows(onPage: Row[], filed: Row[]): Row[] {
+    const by = new Map(onPage.map((r) => [r.root, r]))
+    for (const f of filed) {
+        const cur = by.get(f.root)
+        const same = cur != null && cur.name === f.name && cur.version === f.version && cur.mode === f.mode
+        const fresh = cur != null && (Date.parse(f.seen) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
+        if (!(same && fresh)) by.set(f.root, { name: f.name, root: f.root, version: f.version, mode: f.mode, seen: f.seen })
+    }
+    return [...by.values()].filter((r) => existsSync(r.root)).sort((a, z) => a.name.localeCompare(z.name) || a.root.localeCompare(z.root))
+}
+
+/** render every filed row into its page and land each changed page as one
+ *  commit, at most once per LAND_GAP_MS. Returns what to print */
+export function landMotherhome(o: { now?: number; gapMs?: number } = {}): string[] {
+    const now = o.now ?? Date.now()
+    const notes: string[] = []
+    const filed = machineList<Filed>(ROW)
+    for (const f of filed) if (!existsSync(f.value.root)) machineDelete(f.name)
+    const pages = new Map<string, Row[]>()
+    for (const f of filed) if (existsSync(f.value.root)) pages.set(f.value.page, [...(pages.get(f.value.page) ?? []), f.value])
+    for (const [page, rows] of pages) {
+        try {
+            if (!existsSync(page)) continue
+            const last = machineGet<number>(`${LANDED}${page}`)
+            if (last != null && now - last < (o.gapMs ?? LAND_GAP_MS)) continue
+            const r = withFileLock(page, (): boolean => {
+                const text = readFileSync(page, 'utf8')
+                const lines = text.split('\n')
+                const b = lines.indexOf(BEGIN)
+                const e = lines.indexOf(END)
+                if (b === -1 || e === -1 || e < b) { notes.push(`WARN motherhome: markers missing or out of order in ${page}, rows not written`); return false }
+                const onPage = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
+                const next = [...lines.slice(0, b + 1), ...mergeRows(onPage, rows).map(rowLine), ...lines.slice(e)].join('\n')
+                if (next === text) return false
+                atomicWrite(page, next)
+                return true
+            })
+            if (!r.ok || !r.value) continue
+            machineSet(`${LANDED}${page}`, now)
+            const landed = machineCommit({ anchor: resolve(page, '..'), message: 'chore(machine): refresh local-projects rows', paths: [page] })
+            notes.push(`motherhome: ${page} rows refreshed${landed ? ' + committed' : ', not committed'}`)
+        } catch (err) {
+            notes.push(`WARN motherhome: ${page} not refreshed (${String(err).slice(0, 120)})`)
+        }
     }
+    return notes
 }

package/src/core/repo-facts.ts

@@ -0,0 +1,14 @@
+// what a repo declares about itself and its root unit, read from its config.
+// Its own module, free of any fs import, so a check that asks it stays keyed
+// on what it read.
+import type { RepoConfig } from '../repo-config.ts'
+
+/** the github visibility this repo declares (absent = 'private') */
+export const declaredVisibility = (c: RepoConfig): 'private' | 'public' => c.visibility ?? 'private'
+
+/** declared public: strangers read the tracked tree */
+export const declaredPublic = (c: RepoConfig): boolean => c.visibility === 'public'
+
+/** the root unit declares an npm target. Declared, never inferred from a
+ *  missing `private` flag, so an app that forgot the flag is still an app */
+export const rootPublishesNpm = (c: RepoConfig): boolean => c.release?.npm === true

package/src/core/retention.ts

@@ -1,8 +1,8 @@
 // NOTHING GROWS UNBOUND: every store shipkit writes declares a cap here (an
 // age, a count, a size), and one sweep enforces all of them. The daemon runs
-// it on boot and hourly for every repo it loads and for the machine; rule
-// SK023 fails when a store is past its cap, so a sweep that stopped running
-// is loud. Each store's sweep lives beside the code that writes it, so a gate
+// it on boot and hourly for every repo it loads and for the machine; the
+// house repo's one `stores-under-cap` check fails when a store is past its
+// cap, so a sweep that stopped running is loud. Each store's sweep lives beside the code that writes it, so a gate
 // on a machine with no daemon still keeps its own stores in bounds.
 //
 // The one constraint a reader breaks first: a sweep never removes what a live
@@ -45,8 +45,8 @@ export type Store = {
     sweep(now: number): void | Promise<void>
 }
 
-/** how far past its cap a store may drift between two sweeps before SK023
- *  calls it over: the daemon sweeps hourly, and gates write in between */
+/** how far past its cap a store may drift between two sweeps before the
+ *  house check calls it over: the daemon sweeps hourly, and gates write in between */
 export const SLACK = { factor: 2, ageMs: 2 * 60 * 60 * 1000 }
 
 /** why a store is past its cap (with the drift a sweep interval allows), or
@@ -59,6 +59,15 @@ export function overCap(use: Use, cap: Cap, now: number, slack = SLACK): string
     return null
 }
 
+/** a cap in words: `200 entries, 30d, 5.0 MB a file` */
+export const capWords = (s: Store): string =>
+    [
+        s.cap.maxCount != null ? `${s.cap.maxCount} entries` : null,
+        s.cap.maxAgeMs != null ? fmtAge(s.cap.maxAgeMs) : null,
+        s.cap.maxFileBytes != null ? `${fmtBytes(s.cap.maxFileBytes)} a file` : null,
+        s.cap.maxBytes != null ? fmtBytes(s.cap.maxBytes) : null,
+    ].filter((x) => x != null).join(', ')
+
 export const fmtBytes = (n: number): string => (n >= 1 << 20 ? `${(n / (1 << 20)).toFixed(1)} MB` : n >= 1024 ? `${Math.round(n / 1024)} KB` : `${n} B`)
 export const fmtAge = (ms: number): string => (ms >= 86_400_000 ? `${Math.round(ms / 86_400_000)}d` : ms >= 3_600_000 ? `${Math.round(ms / 3_600_000)}h` : `${Math.round(ms / 60_000)}m`)
 

package/src/core/retired-checks.ts

@@ -0,0 +1,7 @@
+// built-in check ids that no longer exist, and where their question went. An
+// id is never reused, so a doc or a changelog may still name one, and
+// discovery refuses a built-in that takes one again.
+export const RETIRED_CHECK_IDS: Readonly<Record<string, string>> = {
+    SK021: "the gh login is a machine fact: the house repo's github-login check runs src/core/gh-login.ts",
+    SK023: "the store caps are the machine daemon's health: the house repo's stores-under-cap check",
+}

package/src/core/run-check.ts

@@ -37,6 +37,9 @@ export type CheckOpts = {
     status?: boolean
     /** line sink — commands pass their context stream; defaults to console */
     print?: (line: string) => void
+    /** where the lines nobody acts on go: the parked list and the green
+     *  summary. `shipkit ci` shows them only under --verbose. Default: print */
+    detail?: (line: string) => void
     /** per-CHECK completion tap: the real status, whether it replayed, what it
      *  cost. The demotion of a non-blocking failure happens in the LINES (a
      *  FAIL is rewritten to a warn before anything sees it), so `status` here
@@ -84,11 +87,8 @@ export type CheckOpts = {
     /** the gate binary that own ledger is keyed on (default: the one running
      *  it). Ignored when `ledger` is passed, which carries its own. */
     cliEntry?: string
-    /** refresh the motherhome registry row. runCi passes false and does it
-     *  ITSELF, after the ledger has committed: that row is a TRACKED file under
-     *  `wiki/`, so writing it before the post-run re-hash makes the gate look
-     *  like an agent editing the tree and throws away every result the run just
-     *  measured. */
+    /** file the motherhome row in the machine db (core/motherhome.ts). runCi
+     *  passes false and does it ITSELF, once, after its verdict. */
     reportHome?: boolean
 }
 
@@ -197,10 +197,11 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
         bail: o.bail,
         color: o.color,
         print: sink,
+        detail: o.detail,
         onCheck: (e) => { collected.push(...e.lines); o.onCheck?.(e) },
     })
     const lines: Line[] = []
-    const say = (l: Line): void => { lines.push(l); print(formatLine(l, false)) }
+    const say = (l: Line, to: (line: string) => void = print): void => { lines.push(l); to(formatLine(l, false)) }
     // a declaration in a shape the check file replaced is reported by check
     // SK016, which also carries the fixer that rewrites it: one owner, one
     // line, one command, rather than a warning per surface.
@@ -210,7 +211,7 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     // page just replaced
     if (summary.parked.length > 0) {
         const head = summary.parked.slice(0, 8).join(', ')
-        say({ kind: 'skip', text: `${summary.parked.length} check(s) not in this run (health only, release only at the quick tier, or a skipped group): ${head}${summary.parked.length > 8 ? `, and ${summary.parked.length - 8} more` : ''}` })
+        say({ kind: 'skip', text: `${summary.parked.length} check(s) not in this run (health only, release only at the quick tier, or a skipped group): ${head}${summary.parked.length > 8 ? `, and ${summary.parked.length - 8} more` : ''}` }, o.detail ?? print)
     }
     // the survey dies with the run that made it, and only the run that made it
     if (inherited == null || inherited === '') for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }

package/src/core/run-ci.ts

@@ -12,6 +12,7 @@ import { passScope, runCheckPass, type CheckOpts } from './run-check.ts'
 import { poolLines } from './slots.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
+import { outcomeCounts } from './outcome-words.ts'
 import { writeStatus } from './write-status.ts'
 import { allTasks, composeChecks, envTier, FULL_TESTS_ENV, type TestTier } from '../ledger/gate-checks.ts'
 import { CHECK_TABLE_FILE, writeCheckTable } from '../ledger/check-table.ts'
@@ -85,6 +86,10 @@ export type CiOpts = {
     tests?: TestTier
     /** who started this run, as the run record files it */
     invokedBy?: InvokedBy
+    /** print every line, the ones nobody acts on included: the clean fix
+     *  pass, the pool, the tier, the cache declarations, the parked checks,
+     *  the cache counts. STATUS.md always holds them all */
+    verbose?: boolean
 }
 
 export type { TestTier } from '../ledger/gate-checks.ts'
@@ -107,10 +112,26 @@ function ciScope(o: CiOpts): { command: string; fullGate: boolean } {
     return { command: parts.length === 0 ? 'shipkit ci' : `shipkit ci ${parts.join(' ')}`, fullGate: narrowing.length === 0 }
 }
 
+/** `ok: 12 checks green`, or which ones warned. A whole gate adds its tier
+ *  and where its answers came from */
+export function verdictLine(results: CheckResult[], whole: { tier: TestTier; cache: { hit: number; miss: number; attached: number; uncacheable: number } | null } | null): string | null {
+    const ran = results.filter((r) => r.status !== 'skip').length
+    if (ran === 0) return null
+    const warned = results.filter((r) => r.status === 'warn' || (r.status === 'fail' && r.advisory)).map((r) => r.id)
+    const head = warned.length === 0 ? `${ran} check${ran === 1 ? '' : 's'} green` : `${ran} check${ran === 1 ? '' : 's'} passed, ${warned.length} with a warning: ${warned.join(', ')}`
+    if (whole == null) return `ok: ${head}`
+    const c = whole.cache
+    const cache = c == null ? '' : `; ${outcomeCounts({ cached: c.hit, ran: c.miss, attached: c.attached, neverCached: c.uncacheable })}`
+    return `ok: ${head}; ${whole.tier} tier${cache}`
+}
+
 export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const collected: string[] = []
     const sink = (l: string): void => { collected.push(l); print(l) }
+    // what the reader never acts on: kept for STATUS.md and --verbose, never
+    // printed on a default run, where every line costs a reader tokens
+    const detail = (l: string): void => { collected.push(l); if (o.verbose === true) print(l) }
     let c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
@@ -123,7 +144,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // back as a test failure.
     const narrowed = (o.onlyIds ?? []).length > 0
     if (o.fix !== false) {
-        const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink })
+        const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail })
         fixFailed = pass.failed
         // a fixer that rewrote the config or moved a check file leaves the
         // config above describing a repo that is gone, so the gate reads the
@@ -134,20 +155,22 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
                 return 1
             }
         }
-    } else sink('skip: fix pass (--no-fix)')
+    } else detail('skip: fix pass (--no-fix)')
     const tier: TestTier = o.tests ?? envTier()
-    // announced BEFORE the run, so a log that died mid-way still says which
-    // tier it was asking for
-    sink(tier === 'full'
+    // announced BEFORE the run (under --verbose, and in every release log),
+    // so a log that died mid-way still says which tier it was asking for
+    detail(tier === 'full'
         ? `ok: test tier FULL — every suite, the slow ones included (${FULL_TESTS_ENV}=1)`
         : `skip: full test tier (quick run — \`shipkit ci --full\` or ${FULL_TESTS_ENV}=1 includes it)`)
-    for (const l of poolLines()) sink(l)
+    for (const l of poolLines()) (l.startsWith('WARN') ? sink : detail)(l)
     // a floor slot nothing could fill is VISIBLE — a thin gate must never look
     // like a full one (the fresh-repo floor gap)
     const floor = await allTasks(c, root)
-    for (const n of floor.notes ?? []) sink(n)
+    // a narrowed run says nothing about the slots it never asked about
+    const asked = (id: string): boolean => !narrowed || (o.onlyIds ?? []).includes(id)
+    for (const n of floor.notes ?? []) (narrowed ? detail : sink)(n)
     for (const u of floor.unfilled) {
-        sink(`skip: ${u.id} (${u.reason})`)
+        (asked(u.id) ? sink : detail)(`skip: ${u.id} (${u.reason})`)
         // asked for BY NAME and unfillable: this is where an agent lands after
         // the harness refused it the raw runner, so the line says what to add
         // rather than leaving it with `unknown check id` and no next move
@@ -210,7 +233,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         // visible as a shrinking undeclared one.
         const decided = reg.checks - reg.burnDown.length - reg.declared
         if (reg.burnDown.length > 0 || decided > 0)
-            sink(`skip: cache declarations — ${reg.declared}/${reg.checks} declared, ${decided} never cached on purpose, ${reg.burnDown.length} undeclared, so those run every time (shipkit keys --burn-down)`)
+            detail(`skip: cache declarations — ${reg.declared}/${reg.checks} declared, ${decided} never cached on purpose, ${reg.burnDown.length} undeclared, so those run every time (shipkit keys --burn-down)`)
         if (ledger.layer.failure != null)
             sink(`WARN the git scan failed, so NOTHING comes from the cache and nothing is stored this run — ${ledger.layer.failure}`)
     } catch (e) {
@@ -225,13 +248,14 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         onCheck: o.onCheck,
         reportHome: false,
         print: sink,
+        detail,
     })
     // what the suite ACTUALLY ran, from its own headline. A flag that was set
     // proves the intent; the count proves the tests
     // proves the intent; the count proves the tests. Every test check counts,
     // one per unit
     const counts = run.results.map((r) => /Ran (\d+) tests?/.exec(r.lastLine)?.[1]).filter((n) => n != null).map(Number)
-    if (counts.length > 0) sink(`ok: test tier ${tier}: ${counts.reduce((a, b) => a + b, 0)} tests ran${counts.length > 1 ? ` in ${counts.length} test checks` : ''}`)
+    if (counts.length > 0) detail(`ok: test tier ${tier}: ${counts.reduce((a, b) => a + b, 0)} tests ran${counts.length > 1 ? ` in ${counts.length} test checks` : ''}`)
     for (const u of run.undeclared) {
         sink(`FAIL: ${u} does not declare whether it blocks`)
         sink(`      fix: add \`blocking: true\` (about this repo) or \`false\` (about the world) to that check`)
@@ -248,19 +272,26 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
             advisoryFatal = true
             sink(`FAIL: ${run.advisoryFailures.length} non-blocking check(s) failing and release.requireHealthy is on: ${run.advisoryFailures.join(', ')}`)
             sink('      fix: shipkit check')
-        } else sink(`WARN ${run.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${run.advisoryFailures.join(', ')}`)
+        } else detail(`WARN ${run.advisoryFailures.length} non-blocking check(s) failing, about the world rather than this repo: ${run.advisoryFailures.join(', ')}`)
     }
     // the post-run re-hash, then the store. NOTHING was written while the gate
     // ran: a check whose inputs moved under it answered about a tree that no
     // longer exists, and this is where that result is thrown away instead of
     // stored under a key that describes the file as it was before the edit.
-    if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
+    // the counts line folds into the verdict; what else it says (a store
+    // that failed, answers thrown away) is printed as it is
+    if (ledger != null) for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
     // one write for the whole gate, after everything has finished
     for (const l of runLog.flush()) sink(formatLine(l, false))
     const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
-    // motherhome row (docsBase wiki on this disk) — never affects the gate,
-    // and never fires under frozen: a bump/release gate must not re-dirty the
-    // tree it just proved clean
+    // THE VERDICT, one line and only on a pass: a red run already said so in
+    // its FAIL lines. The whole gate adds the tier and the cache counts, which
+    // a narrowed run asked no question about
+    const verdict = code === 0 && !run.interrupted ? verdictLine(run.results, scope.fullGate ? { tier, cache: ledger?.counts ?? null } : null) : null
+    if (verdict != null) sink(verdict)
+    // the motherhome row, filed in the machine db and landed in the docsBase
+    // page by the daemon (core/motherhome.ts): never affects the gate, never
+    // writes in another repo, and a frozen run files nothing
     if (o.frozen !== true) {
         const mh = reportToMotherhome(root, c)
         if (mh.note != null) print(mh.note)