rvlib-shipkit 1.0.0 → 1.1.0

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

package/src/collections/comfy.ts

@@ -10,6 +10,7 @@ export function comfyCollection(root: string): Collection {
     return {
         id: 'comfy',
         title: 'comfy',
+        kind: 'workflow',
         media: 'data',
         list: async () =>
             scanComfyWorkflows(root).map((w): Instance => ({

package/src/collections/posts.ts

@@ -58,6 +58,7 @@ export function socialPostsCollection(root: string): Collection {
     return {
         id: 'posts',
         title: 'posts',
+        kind: 'post',
         media: 'text',
         list: async () => {
             const bySlug = new Map<string, PostFile[]>()

package/src/collections/providers.ts

@@ -25,11 +25,13 @@ import { activeContracts, contractsConfigFrom } from '../contracts/apply-contrac
 import type { CheckFacts, Collection, Instance } from './collection-types.ts'
 import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
-import { assetState, secretState, type SecretProbe } from './state-rules.ts'
+import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
 import { reflectionsCollection } from './reflections.ts'
 import { testsCollection } from './tests.ts'
 import { checksCollection } from './checks.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { isBudgetLine } from '../core/budget.ts'
+import { GH_LOGIN_CRED } from '../checks/SK021-github-login.check.ts'
 
 const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? LAYOUT.asks)
 // read path must not mint an asks/ dir (listAsks mkdirs on read)
@@ -101,10 +103,9 @@ export function probeOf(name: string, probedBy: string | undefined, verdicts: Ma
         const why = lines.find((l) => l.kind === 'fail') ?? lines.find((l) => l.kind === 'warn')
         return { probe: 'fail', words: `its probe ${probedBy} failed${why != null ? `: ${why.text}` : ''}`, md }
     }
-    if (v.status === 'warn') {
-        const why = lines.find((l) => l.kind === 'warn')
-        return { probe: 'warn', words: `its probe ${probedBy} warned${why != null ? `: ${why.text}` : ''}`, md }
-    }
+    // a probe that only ran slow still proved the secret works
+    const why = lines.find((l) => l.kind === 'warn' && !isBudgetLine(l.text))
+    if (v.status === 'warn' && why != null) return { probe: 'warn', words: `its probe ${probedBy} warned: ${why.text}`, md }
     const at = v.measuredAt ?? v.lastAt ?? now
     if (v.keepsUntil != null && now > v.keepsUntil)
         return { probe: 'stale', words: `last checked ${ago(now - at)} by ${probedBy}, older than its ${v.ttl} ttl`, md }
@@ -122,6 +123,7 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
     return {
         id: 'asks',
         title: 'asks',
+        kind: 'ask',
         media: 'text',
         list: async () => {
             const rel = c.asks?.dir ?? LAYOUT.asks
@@ -183,9 +185,10 @@ const named = (name: string, service: string | undefined): string => (service !=
 
 /** repo-declared secrets (repo.config `creds:`) plus every secret a check
  *  proved missing. The tile carries the mint artifact as data. EVERY declared
- *  cred is listed. Missing + unclaimed = red with the set verb + artifact;
- *  missing + ask-covered = STILL red (never hidden), no verbs: the text
- *  points at the ask that owns the action. The line that proved it missing
+ *  cred is listed, coloured by its level (state-rules.ts secretState).
+ *  Missing + unclaimed = the set verb + artifact; missing + ask-covered =
+ *  STILL listed (never hidden), no verbs: the text points at the ask that
+ *  owns the action. The line that proved it missing
  *  (+ its fix: pointers) rides the instance's md, never a health line.
  *  A present secret wears the verdict of the check that probes it
  *  (`probedBy`), read from the run record (state-rules.ts secretState) */
@@ -193,6 +196,7 @@ export function credsCollection(root: string, c: RepoConfig, o: CredsOpts = {}):
     return {
         id: 'creds',
         title: 'secrets',
+        kind: 'secret',
         media: 'pointer',
         list: async () => {
             const rel = c.asks?.dir ?? LAYOUT.asks
@@ -203,19 +207,27 @@ export function credsCollection(root: string, c: RepoConfig, o: CredsOpts = {}):
             const now = (o.now ?? Date.now)()
             const missing = missingFrom(verdicts)
             const byId = new Map(verdicts.map((v) => [v.checkId, v]))
+            // a toolkit credential joins the repo's own once its probe ran here
+            const builtins = BUILTIN_CREDS.filter((b) => byId.get(b.probedBy)?.status != null &&!(c.creds ?? []).some((d) => d.name === b.name))
+            const declared = [...builtins, ...(c.creds ?? [])]
             const out: Instance[] = []
             for (const [name, line] of missing) {
-                const decl = (c.creds ?? []).find((d) => d.name === name)
+                const builtin = builtins.find((b) => b.name === name)
+                if (builtin != null) {
+                    out.push({ ...builtinMissing(builtin, line.fixes[0]), md: wireMd([`FAIL: ${line.text}`, ...line.fixes.map((f) => `fix: ${f}`)]) })
+                    continue
+                }
+                const decl = declared.find((d) => d.name === name)
                 const md = wireMd([`FAIL: ${line.text}`, ...line.fixes.map((f) => `fix: ${f}`)])
                 const ask = coveringAsk(name)
                 if (ask != null)
                     // dedup = acted-on once, never hidden: the ask keeps the
-                    // verbs and the ping; the cred still shows RED here
+                    // verbs and the ping; the cred still shows here
                     out.push({
                         id: `cred:${name}`,
-                        text: `${named(name, decl?.service)} missing, ask ${rel}/${ask.file} owns this`,
-                        ...credPlace(name, true),
-                        severity: 'red',
+                        text: `${named(name, decl?.service)} missing, ask ${rel}/${ask.file} owns this${minorWord(decl?.level)}`,
+                        ...credPlace(name, true, decl?.level),
+                        ...secretState({ missing: true, probe: 'none', level: decl?.level }),
                         md,
                         askOwned: true,
                     })
@@ -224,14 +236,14 @@ export function credsCollection(root: string, c: RepoConfig, o: CredsOpts = {}):
             // every declared cred not proven missing is present: no copy
             // command (nothing to run), the mint pointer when one is declared,
             // and the colour of what its probe last proved
-            for (const d of c.creds ?? []) {
+            for (const d of declared) {
                 if (missing.has(d.name)) continue
                 const p = probeOf(d.name, d.probedBy, byId, now)
                 out.push({
                     id: `cred:${d.name}`,
-                    text: `${named(d.name, d.service)} present, ${p.words}`,
-                    ...credPlace(d.name, false),
-                    ...secretState({ missing: false, probe: p.probe }),
+                    text: `${named(d.name, d.service)} present, ${p.words}${minorWord(d.level)}`,
+                    ...credPlace(d.name, false, d.level),
+                    ...secretState({ missing: false, probe: p.probe, level: d.level }),
                     md: p.md,
                     artifact: d.mintUrl != null ? { url: d.mintUrl } : undefined,
                 })
@@ -245,15 +257,35 @@ export function credsCollection(root: string, c: RepoConfig, o: CredsOpts = {}):
 // never names any particular secret manager
 // a secret has no file: the name is already slash shaped, so a virtual root
 // groups it by vendor for free
-const credPlace = (name: string, missing: boolean): Pick<Instance, 'type' | 'path' | 'virtual' | 'label' | 'slot'> =>
-    // the tree row is the NAME, and present or missing is the slot beside it
-    ({ type: 'secret', path: `secrets/${name}`, virtual: true, label: name, slot: missing ? 'missing' : 'present' })
+const credPlace = (name: string, missing: boolean, level?: SecretLevel): Pick<Instance, 'type' | 'path' | 'virtual' | 'label' | 'slot'> =>
+    // the tree row is the NAME, and present or missing is the slot beside
+    // it. A minor secret nobody minted says minor there: missing is the
+    // expected state of a key nothing uses yet
+    ({ type: 'secret', path: `secrets/${name}`, virtual: true, label: name, slot: missing ? (level === 'minor' ? 'minor' : 'missing') : 'present' })
+
+/** a minor secret says so in its sentence, since its colour says nothing */
+const minorWord = (level: SecretLevel | undefined): string => (level === 'minor' ? ', minor' : '')
+
+/** credentials the toolkit itself runs on, which no secrets manager holds
+ *  (gh keeps its own login). The repo's `creds` entry of the same name wins */
+const BUILTIN_CREDS = [GH_LOGIN_CRED]
+type BuiltinCred = (typeof BUILTIN_CREDS)[number]
 
-const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { service?: string; mintUrl?: string; steps?: string[] }): Instance => ({
+/** a missing toolkit credential: its fix is a command to run, never a value
+ *  to store, so it carries no `set` verb and copies the probe's own fix */
+const builtinMissing = (b: BuiltinCred, fix: string | undefined): Instance => ({
+    id: `cred:${b.name}`,
+    text: `${named(b.name, b.service)} missing`,
+    ...credPlace(b.name, true, b.level),
+    ...secretState({ missing: true, probe: 'none', level: b.level }),
+    artifact: { copy: fix != null && !/\s(then|and)\s/.test(fix) ? fix : b.command, url: b.mintUrl },
+})
+
+const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { service?: string; mintUrl?: string; steps?: string[]; level?: SecretLevel }): Instance => ({
     id: `cred:${name}`,
-    text: `${named(name, decl?.service)} missing`,
-    ...credPlace(name, true),
-    severity: 'red',
+    text: `${named(name, decl?.service)} missing${minorWord(decl?.level)}`,
+    ...credPlace(name, true, decl?.level),
+    ...secretState({ missing: true, probe: 'none', level: decl?.level }),
     artifact: { copy: cmdTemplate?.replaceAll('{name}', name), url: decl?.mintUrl, steps: decl?.steps },
     verbs: ['set'],
 })
@@ -269,6 +301,7 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
     return {
         id: 'media',
         title: 'assets',
+        kind: 'asset',
         media: 'image',
         list: async () => {
             const idn = await heal(root)
@@ -332,30 +365,25 @@ const assetNotes = (root: string): Map<string, string[]> => {
     return map
 }
 
-/** repo health — what belongs to no check and no other collection: contract
- *  FAIL/WARN lines and hub process staleness. Every check, rule and task of
- *  the gate is its own resource now (collections/checks.ts), so re-parsing
- *  STATUS.md into one row per wire line would state the same verdicts a
- *  second time, under ids that are whole sentences, and the two would
- *  disagree the moment one run narrowed. Cred probe FAIL lines (+ their
- *  fixes) stay routed to the secrets collection. */
-export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVersion?: string; libVersion?: () => string }): Collection {
+/** the release contracts: one row per FAIL/WARN line of a venue contract.
+ *  Every check, rule and task of the gate is its own resource
+ *  (collections/checks.ts), so STATUS.md is never re-parsed into rows here.
+ *  Cred probe FAIL lines (+ their fixes) stay routed to the secrets
+ *  collection. The hub's own state (a stale process) is no row at all: the
+ *  hub restarts itself (serve/stale-restart.ts) */
+export function contractsCollection(root: string, c: RepoConfig): Collection {
     return {
-        id: 'health',
-        title: 'repo health',
+        id: 'contracts',
+        title: 'release contracts',
+        kind: 'contract',
         media: 'health',
         list: async () => {
             const out: Instance[] = []
-            if (o?.bootVersion != null && o.libVersion != null) {
-                const now = o.libVersion()
-                if (now !== o.bootVersion)
-                    out.push({ id: 'health:stale-hub', type: 'health', path: 'health/stale-hub', virtual: true, severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
-            }
             const disk = CheckCtx.open({ root, config: c })
             const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, disk), disk)
             for (const l of r.lines) {
-                if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, type: 'contract', path: `health/contracts/${slug(l.text)}`, virtual: true, severity: 'red', text: l.text })
-                else if (l.kind === 'warn') out.push({ id: `health:contractwarn:${l.text}`, type: 'contract', path: `health/contracts/${slug(l.text)}`, virtual: true, severity: 'yellow', text: l.text })
+                if (l.kind === 'fail') out.push({ id: `contract:${l.text}`, type: 'contract', path: `contracts/${slug(l.text)}`, virtual: true, severity: 'red', text: l.text })
+                else if (l.kind === 'warn') out.push({ id: `contractwarn:${l.text}`, type: 'contract', path: `contracts/${slug(l.text)}`, virtual: true, severity: 'yellow', text: l.text })
             }
             return out
         },
@@ -372,11 +400,11 @@ const sharedList = (col: Collection): Collection => {
     }
 }
 
-export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit | null, o?: { bootVersion?: string; libVersion?: () => string }): Collection[] {
+export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit | null): Collection[] {
     const checks = sharedList(checksCollection(root, c))
     return [
         checks,
-        repoHealthCollection(root, c, o),
+        contractsCollection(root, c),
         asksCollection(root, c),
         credsCollection(root, c, { verdicts: () => verdictsOf(checks) }),
         mediaKitCollection(root, kit),

package/src/collections/reflections.ts

@@ -12,6 +12,7 @@ export function reflectionsCollection(root: string): Collection {
     return {
         id: 'reflections',
         title: 'reflections',
+        kind: 'reflection',
         media: 'text',
         list: async () =>
             listReflections(root).map((r): Instance => {

package/src/collections/state-rules.ts

@@ -36,19 +36,35 @@ export const assetState = (f: AssetFacts): StateRule => {
  *  none        no check probes this secret */
 export type SecretProbe = 'pass' | 'fail' | 'warn' | 'stale' | 'unmeasured' | 'none'
 
-/** THE secret rule. Being there is half the answer and working is the other
- *  half, so present plus a probe that passed is the only green. A value that
- *  is there and fails its probe is red on the tree, and its feed line stays
- *  yellow: the probing check does not block, and its own row already carries
- *  the same failure. A pass past its ttl, or a probe that never measured, is
- *  plain: nothing is known to be wrong. A secret no check probes is dim,
- *  because there is no verdict to wait for. Missing while a page requires it
- *  is the broken case, whatever any probe said */
-export const secretState = (f: { missing: boolean; probe: SecretProbe }): StateRule => {
-    if (f.missing) return { severity: 'red' }
-    if (f.probe === 'pass') return { state: 'ok' }
-    if (f.probe === 'fail') return { state: 'red', severity: 'yellow' }
-    if (f.probe === 'warn') return { severity: 'yellow' }
+/** how much breaks without a secret, declared once per secret like
+ *  `blocking` for a check. `core`: the toolkit's own features stop (a push,
+ *  creating a repo, a release). `used`: a feature this repo uses today.
+ *  `minor`: proactive, for something nothing uses yet */
+export type SecretLevel = 'core' | 'used' | 'minor'
+
+/** a secret that declares no level */
+export const DEFAULT_SECRET_LEVEL: SecretLevel = 'used'
+
+/** THE secret rule. Red means this repo is broken, so only a `core` secret
+ *  goes red: missing, or present with a probe that failed. Only a missing
+ *  one is red in the feed, which pings once: a failed probe is often the
+ *  service, and its own check row already carries the failure. A `used` one
+ *  is orange in both cases, a feed line that never pings. A `minor` one is dim
+ *  and stays out of the feed, whatever its probe said, and its row carries
+ *  the words. Present plus a probe that passed is green at every level. A
+ *  pass past its ttl, or a probe that never measured, is plain: nothing is
+ *  known to be wrong. A secret no check probes is dim, because there is no
+ *  verdict to wait for */
+export const secretState = (f: { missing: boolean; probe: SecretProbe; level?: SecretLevel }): StateRule => {
+    const level = f.level ?? DEFAULT_SECRET_LEVEL
+    const broken = f.missing || f.probe === 'fail'
+    if (!f.missing && f.probe === 'pass') return { state: 'ok' }
+    if (broken || f.probe === 'warn') {
+        if (level === 'minor') return { state: 'quiet' }
+        if (level === 'core' && f.missing) return { severity: 'red' }
+        if (level === 'core' && broken) return { state: 'red', severity: 'yellow' }
+        return { severity: 'yellow' }
+    }
     if (f.probe === 'none') return { state: 'quiet' }
     return { state: 'idle' }
 }

package/src/collections/tests.ts

@@ -63,6 +63,7 @@ export function testsCollection(root: string, c: RepoConfig, o: TestsOpts = {}):
     return {
         id: 'tests',
         title: 'tests',
+        kind: 'test',
         media: 'health',
         list: async () => {
             let files = o.files

package/src/collections/wikis.ts

@@ -25,6 +25,7 @@ export function wikisCollection(mounts: GraphMount[], root: string | null = null
     return {
         id: 'wikis',
         title: 'wikis',
+        kind: 'wiki',
         media: 'data',
         list: async () =>
             mounts.map((m): Instance => {

package/src/core/budget.ts

@@ -0,0 +1,60 @@
+// A CHECK'S TIME BUDGET: what a healthy run of it takes, distinct from its
+// ceiling (`timeoutMs`), which is where it is killed. A check that PASSES over
+// its budget is a warn, never a failure: slow is a defect to fix, not a broken
+// repo. Judged on the wall time of a run that measured, at the quick tier
+// only, and the one owner of the defaults, the line and the load reading.
+import { availableParallelism, loadavg } from 'os'
+import type { MachineLoad } from '../suite/judge-suites.ts'
+
+/** an in process body, a rule or a page check. Read off a run record of 64
+ *  such checks: the median rule answers in under 50ms, 55 of them stay under
+ *  2s at their 90th percentile, and the few past it shell out to a tool */
+export const IN_PROCESS_BUDGET_MS = 2_000
+
+/** a subprocess (a build step, a test suite, a `cmd` check) or a world probe.
+ *  Read off the same record: every typecheck stays under 6s at its 90th
+ *  percentile, and the quick test suites under 6s but one */
+export const SUBPROCESS_BUDGET_MS = 10_000
+
+/** what a check declares about itself that picks its default */
+export type BudgetKind = { build: boolean; cmd: boolean; world: boolean }
+
+export const defaultBudget = (k: BudgetKind): number => (k.build || k.cmd || k.world ? SUBPROCESS_BUDGET_MS : IN_PROCESS_BUDGET_MS)
+
+/** the budget one check runs under: the repo's `budgets` entry, then what the
+ *  check file declares, then the default for its kind */
+export const budgetOf = (id: string, declared: number | undefined, kind: BudgetKind, budgets: Record<string, number> | undefined): number =>
+    budgets?.[id] ?? declared ?? defaultBudget(kind)
+
+/** the `budgets` ids of a repo config that name no check it has */
+export const unknownBudgetIds = (ids: readonly string[], budgets: Record<string, number> | undefined): string[] => {
+    const known = new Set(ids)
+    return Object.keys(budgets ?? {}).filter((id) => !known.has(id))
+}
+
+/** what a budget value must be, or null when it is one */
+export const budgetValueProblem = (v: unknown): string | null =>
+    typeof v === 'number' && Number.isInteger(v) && v > 0 ? null : `must be a whole number of milliseconds above 0, got ${JSON.stringify(v)}`
+
+export const machineLoad = (): MachineLoad => ({ load1: loadavg()[0] ?? 0, cores: availableParallelism() })
+
+/** `10s` for a whole second count, `150ms` otherwise */
+export const fmtBudget = (ms: number): string => (ms % 1000 === 0 ? `${ms / 1000}s` : `${ms}ms`)
+
+/** a line budgetLine wrote, read back off the wire: a slow pass says
+ *  nothing about what the check checks (a secret, a service), so a reader of
+ *  the verdict tells the two apart */
+export const isBudgetLine = (text: string): boolean => /^\S+ (passed|warned) in \d+\.\ds,(?: under load [^,]+,)? over its \d+m?s budget: /.test(text.replace(/^\[[^\]]+\] /, ''))
+
+/** a test check sends the reader to the page that breaks its time down */
+const isTestCheck = (id: string): boolean => id === 'test' || id.startsWith('test:')
+
+/** the WARN a pass over its budget prints, or null inside it. A loaded
+ *  machine is named, because wall time is what the reader waits on and load
+ *  is the first thing to rule out */
+export function budgetLine(id: string, ms: number, budgetMs: number, load: MachineLoad, verb: 'passed' | 'warned' = 'passed'): string | null {
+    if (ms <= budgetMs) return null
+    const loaded = load.load1 >= load.cores ? ` under load ${load.load1.toFixed(1)} on ${load.cores} cores,` : ''
+    const where = isTestCheck(id) ? 'see the tests page for where the time goes' : 'its page in the hub shows every run'
+    return `${id} ${verb} in ${(ms / 1000).toFixed(1)}s,${loaded} over its ${fmtBudget(budgetMs)} budget: ${where}`
+}

package/src/core/check-ctx.ts

@@ -230,7 +230,8 @@ export class CheckCtx {
      *  global never shadows the one a repo pins */
     tool(name: string, candidates: string[] = []): string | null {
         this.world('tool')
-        return candidates.find((p) => existsSync(p)) ?? Bun.which(name)
+        // the PATH as it stands NOW: Bun.which alone reads the one the process started with
+        return candidates.find((p) => existsSync(p)) ?? Bun.which(name, { PATH: process.env['PATH'] ?? '' })
     }
 
     // fetch with a default timeout; 429 → RateLimited → WARN upstream

package/src/core/check-runner.ts

@@ -28,8 +28,8 @@
 //   you failed" and a page can still show the red.
 // - ONE tap fires per check, with what the wire lines cannot say: the real
 //   status, whether it replayed, whether it can block, what it cost.
-import { closeSync, mkdirSync, openSync, readdirSync, rmSync, writeSync } from 'fs'
-import { basename, join } from 'path'
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, rmSync, writeSync } from 'fs'
+import { basename, isAbsolute, join, relative } from 'path'
 import { shareRun } from './attach.ts'
 import { CheckCtx } from './check-ctx.ts'
 import { CheckPass } from './check-pass.ts'
@@ -37,6 +37,7 @@ import type { ReadSet } from './read-set.ts'
 import { RepoView } from '../ledger/repo-view.ts'
 import { parallelCap } from './parallel.ts'
 import { machinePool, SLOT_HELD_ENV, takeSlot, type SlotPool } from './slots.ts'
+import { budgetLine, machineLoad } from './budget.ts'
 import { killTree, spawnWithTimeout } from './spawn-timeout.ts'
 import { formatLine, parseWireOutput, type Line } from './wire.ts'
 import { offLine, type WhenDecl } from './when.ts'
@@ -81,6 +82,10 @@ export type RunnableCheck = {
     deps: string[]
     group: string | null
     timeoutMs: number
+    /** what a healthy run takes, in ms (core/budget.ts): a run that passes
+     *  over it warns. Absent: never judged, which is what a build step gets
+     *  at the full tier, where it runs every slow suite on purpose */
+    budgetMs?: number
     /** the declared world TTL in ms, 0 when this check is not a world probe */
     ttlMs: number
     /** the rotation half of a world key (a secret hash, a config switch) */
@@ -638,6 +643,28 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     // unrelated edit moved the tree
     const storable = (u: Live): u is Live & { status: 'pass' | 'warn' } => u.status === 'pass' || (u.status === 'warn' && u.blocking !== false)
 
+    /** a check that passed or warned past its budget says so in a warn line,
+     *  judged on the wall time of the run that just measured */
+    const judgeBudget = (u: Live): void => {
+        if (u.budgetMs == null || (u.status !== 'pass' && u.status !== 'warn')) return
+        const text = budgetLine(u.id, u.endedAt - u.startedAt, u.budgetMs, machineLoad(), u.status === 'pass' ? 'passed' : 'warned')
+        if (text == null) return
+        u.lines = [...u.lines, { kind: 'warn', text }]
+        u.status = 'warn'
+        if (feeds(u)) u.problems = [...u.problems, { file: budgetAnchor(u), line: 1, col: 1, severity: 'warning', check: u.id, message: text }]
+    }
+
+    /** where a budget warning sits in the problems pane: the check's own
+     *  file, else the package its command runs in, else the repo config that
+     *  declares the repo's checks */
+    const budgetAnchor = (u: Live): string => {
+        const cwd = u.body.cwd == null ? null : relative(o.root, u.body.cwd)
+        const candidates = [u.owner, cwd == null || cwd === '' ? null : join(cwd, 'package.json')]
+        for (const f of candidates)
+            if (f != null && !isAbsolute(f) && !f.startsWith('..') && existsSync(join(o.root, f))) return f.replace(/\\/g, '/')
+        return 'repo.config.ts'
+    }
+
     const adopt = (u: Live, a: Answer, pid: number): void => {
         const stamp = ` ${attachedStamp(pid, a.measuredMs)}`
         u.status = a.status
@@ -695,11 +722,16 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
         // whose result is stored empty replays as a line nobody can tell
         // from a measurement
         if (u.lines.length === 0) headlineOf(u)
+        // what may be kept is decided on the verdict BEFORE the budget line:
+        // slow is not a negative about the world, so a slow pass keeps as long
+        // as a quick one, and replays with the warn it earned
+        const keep = storable(u)
+        const clean = u.status === 'pass'
+        judgeBudget(u)
         // what may be remembered, and for how long, is ONE policy
         // (ledger/world-cache.ts): a clean answer keeps for the declared
         // TTL, a measured negative only long enough to stop a re-ask storm
         if (o.cache != null && u.ttlMs > 0) {
-            const clean = u.status === 'pass'
             u.lines = rememberWorld(o.cache, u.id, worldKey(u), u.ttlMs, {
                 lines: u.lines,
                 clean,
@@ -707,8 +739,8 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
                 keepNegative: u.blocking === false,
             })
         }
-        if (o.ledger != null && storable(u))
-            o.ledger.record(u.id, { status: u.status, lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads)
+        if (o.ledger != null && keep)
+            o.ledger.record(u.id, { status: u.status as 'pass' | 'warn', lines: u.lines, lastLine: u.lastLine, problems: u.problems, measuredMs: clock() - u.startedAt }, u.reads)
     }
 
     const start = (u: Live): void => {
@@ -783,7 +815,12 @@ export async function runChecks(o: RunChecksOpts): Promise<RunChecksSummary> {
     const skipped = results.filter((r) => r.status === 'skip' && r.note !== '' && r.note !== 'off')
     if (blocked.length > 0) emit({ kind: 'fail', text: `${blocked.length}/${results.length} failed: ${blocked.map((r) => r.id).join(', ')}` })
     if (skipped.length > 0) emit({ kind: 'note', text: `skip: ${skipped.map((r) => `${r.id} (${r.note})`).join(', ')}` })
-    if (blocked.length === 0 && !interrupted && results.length > 0) emit({ kind: 'ok', text: `all ${results.filter((r) => r.status !== 'skip').length} check(s) green` })
+    // a warn is not green: a gate whose every check passed but some warned
+    // says which, so the summary never reads cleaner than the lines above it
+    const warned = results.filter((r) => r.status === 'warn' || (r.status === 'fail' && r.advisory))
+    const ran = results.filter((r) => r.status !== 'skip').length
+    if (blocked.length === 0 && !interrupted && results.length > 0)
+        emit({ kind: 'ok', text: warned.length === 0 ? `all ${ran} check(s) green` : `all ${ran} check(s) passed, ${warned.length} with a warning: ${warned.map((r) => r.id).join(', ')}` })
     return {
         ok: blocked.length === 0 && !interrupted,
         interrupted,

package/src/core/fd-table.ts

@@ -0,0 +1,37 @@
+// how full this process's file table is. macOS posix_spawn refuses any fd at
+// or past OPEN_MAX (10240) with EBADF, and a new pipe takes the lowest free
+// number, so a table that full fails every spawn that pipes. bun 1.4.2
+// `--watch` opens each watched file without close on exec, so every in place
+// restart keeps the previous image's copies (fixed in 1.4.3). A clean re-exec
+// (process.execve) carries none of them, which is how a long lived process
+// sheds the leak. This heal dies once every machine runs bun 1.4.3 or later.
+import { readdirSync } from 'fs'
+
+/** past this many open files a process is leaking, not working: a hub on a
+ *  large repo holds about 1000 */
+export const FD_LEAK_LIMIT = 4096
+/** set by a restart that sheds a leak: when it comes back still over the
+ *  limit, a restart is not what the table needs */
+export const FD_HEALED_ENV = 'SHIPKIT_FD_HEALED_AT'
+const HEAL_GRACE_MS = 60_000
+
+/** open fds of this process, null where the platform lists none */
+export const openFdCount = (): number | null => {
+    try { return readdirSync('/dev/fd').length } catch { return null }
+}
+
+/** why this process's file table is leaking, null while it is not */
+export function fdTableLeak(o: { count?: () => number | null; limit?: number } = {}): string | null {
+    const n = (o.count ?? openFdCount)()
+    const limit = o.limit ?? FD_LEAK_LIMIT
+    if (n == null || n <= limit) return null
+    return `this process holds ${n} open files, past the ${limit} it ever needs (a bun --watch restart leaks them), and at 10240 every spawn fails with EBADF`
+}
+
+/** throws when a restart already shed a leak moments ago and the table is
+ *  full again: that is a need, not a leak, and restarting would loop */
+export function assertLeakHealable(env: Record<string, string | undefined> = process.env, now = Date.now()): void {
+    const at = Number(env[FD_HEALED_ENV])
+    if (Number.isFinite(at) && at > 0 && now - at < HEAL_GRACE_MS)
+        throw new Error(`a clean restart ${Math.round((now - at) / 1000)}s ago came back still over the limit, so a restart does not shed it`)
+}