rvlib-shipkit 1.2.0 → 1.3.0

package/src/core/discover-checks.ts

@@ -17,6 +17,7 @@
 //
 // Skipped dirs: node_modules, dist, tmp, references (templates for other
 // repos), and every dot-dir.
+import { RETIRED_CHECK_IDS } from './retired-checks.ts'
 import { readdirSync, readFileSync, realpathSync, statSync } from 'fs'
 import { basename, join, relative } from 'path'
 import { check, type CheckDef, type CheckFrom } from '../check.ts'
@@ -176,6 +177,7 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
         if (isBuiltin) {
             if (id !== fallback) throw new Error(`${f}: declares id '${id}' but its file name says '${fallback}' — a built-in id is its file name`)
             if ((def.owner ?? '') === '') throw new Error(`${f}: a built-in check names the page that OWNS the invariant`)
+            if (RETIRED_CHECK_IDS[id] != null) throw new Error(`${f}: id '${id}' is retired (${RETIRED_CHECK_IDS[id]}), and an id is never reused`)
         } else if (id.startsWith('SK')) {
             throw new Error(`${rel}: id '${id}' uses the reserved SK prefix — a repo check picks its own (e.g. RV${id.slice(-3)}) or plain words`)
         }

package/src/core/file-stamp.ts

@@ -0,0 +1,20 @@
+// the content of a file no tree id reaches (outside the repo, gitignored, an
+// install), as one short hash for a check's `cacheKey`. `absent` when nothing
+// stands there, so a file appearing or vanishing moves the key too.
+import { createHash } from 'crypto'
+import { readFileSync } from 'fs'
+import { homedir } from 'os'
+import { isAbsolute, join } from 'path'
+
+export function fileStamp(abs: string): string {
+    try {
+        return createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 16)
+    } catch {
+        return 'absent'
+    }
+}
+
+/** a path as a config declares it (`~/...`, absolute, or repo relative), absolute */
+export function configPath(root: string, p: string): string {
+    return p.startsWith('~/') ? join(homedir(), p.slice(2)) : isAbsolute(p) ? p : join(root, p)
+}

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/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
@@ -197,10 +200,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 +214,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,16 +272,23 @@ 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
+    // 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)
     // 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

package/src/core/run-fix.ts

@@ -17,6 +17,9 @@ export type FixOpts = {
      *  not wire-shaped, which the frozen output contract forbids */
     quiet?: boolean
     print?: (line: string) => void
+    /** where a fix that changed nothing reports, since the run after it says
+     *  the same about that check. Default: print */
+    detail?: (line: string) => void
     /** the config as it stands on disk now, when the caller holds one: a
      *  second load of a rewritten repo.config.ts can hit the module cache */
     config?: RepoConfig
@@ -75,7 +78,8 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
         // it is an ok, not a warning. It carries a frozen wire prefix like
         // every other line the fix pass emits: `shipkit ci` promises its whole
         // output is parseable, and a bare line breaks that for every reader.
-        print(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `ok: [${rule.id}] fix changed nothing — ${f.summary}`)
+        const say = f.changed ? print : o.detail ?? print
+        say(f.changed ? `ok: [${rule.id}] fixed: ${f.summary}` : `ok: [${rule.id}] fix changed nothing — ${f.summary}`)
         // a fixer may rewrite repo.config.ts, and the re-run below and every
         // fixer after it must read what is on disk now, never the config this
         // pass loaded before the rewrite
@@ -89,7 +93,8 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
         await runCheckBody(rule, after)
         // the fix already ran: advertising it again on surviving findings
         // would send an agent in a loop
-        for (const l of after.lines) print(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix \S+$/, '') }, color))
+        // inside the ci fix pass the run below reports this check's end state
+        for (const l of after.lines) (o.quiet === true ? o.detail ?? print : say)(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix \S+$/, '') }, color))
         if (after.failed) exit = 1
     }
     const unfixable = all.filter((r) => r.fix == null).length

package/src/core/run-fixers.ts

@@ -140,6 +140,9 @@ export type FixPassOpts = {
      *  mutate the tree they are about to ship) */
     armHooks?: boolean
     print: (line: string) => void
+    /** where the lines nobody acts on go (a clean pass, an unfilled slot).
+     *  Default: print. `shipkit ci` shows them only under --verbose */
+    detail?: (line: string) => void
 }
 
 export type FixPassResult = {
@@ -220,12 +223,13 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
     if (o.armHooks === true && !verify) {
         const armed = armHooks(root, config)
         if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the .shipkit/hooks/ dir`)
-        else if (armed.state === 'foreign' || armed.state === 'not-root') o.print(`skip: hooks (${armed.detail})`)
+        else if (armed.state === 'foreign' || armed.state === 'not-root') (o.detail ?? o.print)(`skip: hooks (${armed.detail})`)
         else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
+    const detail = o.detail ?? o.print
     const { slots, unfilled, disabled } = resolveFixers(root, config)
-    for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)
-    for (const d of disabled) o.print(`skip: ${d.id} (${d.reason})`)
+    for (const u of unfilled) detail(`skip: ${u.id} (${u.reason})`)
+    for (const d of disabled) detail(`skip: ${d.id} (${d.reason})`)
     const before = treeState(root)
 
     for (const s of slots) {
@@ -236,7 +240,7 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
             o.print(`WARN fix ${s.id} failed (exit ${r.code}) — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}; the gate below still ran`)
     }
     // structural repo-config repair is never implicit, and never in verify mode
-    if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print, config })
+    if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print, detail: o.detail, config })
 
     const after = treeState(root)
     const reshaped = shapeStamp(root) !== shapeBefore
@@ -257,11 +261,11 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
     }
     const list = `${touched.slice(0, 8).join(' ')}${touched.length > 8 ? ` … +${touched.length - 8}` : ''}`
     if (before == null) {
-        o.print(`ok: fix pass ran, ${slots.length} fixer(s) (not a git repo — rewritten files cannot be listed)`)
+        detail(`ok: fix pass ran, ${slots.length} fixer(s) (not a git repo — rewritten files cannot be listed)`)
         return { ran: true, touched, failed: false, reshaped }
     }
     if (touched.length === 0) {
-        o.print(`ok: ${verify ? 'fixers verified' : 'fix pass'} clean (${slots.length} fixer(s), nothing to rewrite)`)
+        detail(`ok: ${verify ? 'fixers verified' : 'fix pass'} clean (${slots.length} fixer(s), nothing to rewrite)`)
         return { ran: true, touched, failed: false, reshaped }
     }
     if (verify) {

package/src/core/wire.ts

@@ -49,6 +49,17 @@ export function parseDuration(d: string | number): number {
     return Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3600_000, d: 86400_000 }[m[2] as 'ms' | 's' | 'm' | 'h' | 'd']
 }
 
+/** `ttl: 'forever'`: a DECIDED fact (a repo's visibility, an account that
+ *  exists). It moves only when someone decides to move it, and that decision
+ *  is the declared value in its key, so a clean answer never expires */
+export const FOREVER = 'forever'
+
+/** what a forever answer keeps for: no clock ends it, no sweep drops it */
+export const FOREVER_MS = Number.MAX_SAFE_INTEGER
+
+/** how long a clean answer keeps, from a declared ttl. 0 = none declared */
+export const ttlMsOf = (ttl: string | undefined): number => (ttl == null || ttl === '' ? 0 : ttl === FOREVER ? FOREVER_MS : parseDuration(ttl))
+
 /** absolute local stamp (2026-08-05 09:12:34), never a relative age: a
  *  relative render changes every run and turns committed STATUS.md
  *  checkpoints into noise diffs */

package/src/fleet/scan-fleet.ts

@@ -12,6 +12,7 @@
 // `shipkit check`, so the fix travels through that one code path.
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import { join } from 'path'
+import { isArchived } from '../core/archived.ts'
 import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
 import { isBreaking } from '../core/update-policy.ts'
 
@@ -84,7 +85,7 @@ export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[
             continue
         }
         const pkg = readPkg(dir)
-        if (pkg == null) continue
+        if (pkg == null || isArchived(dir)) continue
         const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
         const names = Object.keys(all).filter((n) => n.startsWith(prefix))
         if (names.length === 0) continue