rvlib-shipkit 1.4.0 → 1.6.0

package/src/fleet/update-fleet.ts

@@ -7,7 +7,7 @@ import { join } from 'path'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import { detectPackageManager, isRefusal } from '../core/package-manager.ts'
 import { ALLOW_MAJOR_ENV, breakingAdvice } from '../core/update-policy.ts'
-import { installedVersion, isBehind, updateRefusal, type FleetRepo } from './scan-fleet.ts'
+import { isBehind, judgedVersion, updateRefusal, type FleetRepo } from './scan-fleet.ts'
 
 
 export const short = (name: string): string => name.replace(/^rvlib-/, '')
@@ -64,15 +64,15 @@ export async function updateFleet(behind: FleetRepo[], o: FleetUpdateOpts): Prom
         const env: Record<string, string> = Object.fromEntries(Object.entries(process.env).filter((e): e is [string, string] => e[1] != null && e[0] !== 'SHIPKIT_SELF_UPDATED' && e[0] !== ALLOW_MAJOR_ENV))
         if (o.major) env[ALLOW_MAJOR_ENV] = '1'
         const res = await spawnWithTimeout(['bun', cli, 'check', '--fresh'], { cwd: r.dir, env, timeoutMs: o.timeoutMs ?? 600_000 })
-        // judge by what node_modules carries now, never by the exit code or a
-        // printed line: the code covers every rule in that repo, and the line
-        // format belongs to whatever version that repo runs
+        // judge by what node_modules carries now (the pin, for a linked dep),
+        // never by the exit code or a printed line: the code covers every rule
+        // in that repo, and the line format belongs to whatever version that repo runs
         const stuck = wanted.filter((d) => {
-            const now = installedVersion(r.dir, d.name)
+            const now = judgedVersion(r.dir, d.name)
             return now == null || isBehind(now, d.latest!)
         })
         if (stuck.length === 0) {
-            w(`ok: ${r.name} — ${wanted.map((d) => `${short(d.name)} ${d.installed} → ${installedVersion(r.dir, d.name)}`).join(', ')}`)
+            w(`ok: ${r.name} — ${wanted.map((d) => `${short(d.name)}${d.linkedInstall ? ' pin' : ''} ${d.at} → ${judgedVersion(r.dir, d.name)}`).join(', ')}`)
             continue
         }
         failed++

package/src/home/gui-app.ts

@@ -4,12 +4,15 @@
 // and iconed after it, in its repo's `.shipkit/wrapper/`. The bundle's
 // Info.plist carries what differs (name, bundle id, start url), so a fix to
 // the window (find, the inspector, zoom) lands in every app at its next
-// build. Rebuilt only when the source, the icon or the start url changed (a
-// stamp in the bundle). No compiler, or not macOS: the caller falls back.
+// build. The icon is core/app-icon.ts: the repo's mark, its margin cut, on
+// a plate in the repo's colour. Rebuilt only when the source, the icon, the
+// colours or the start url changed (a stamp in the bundle). No compiler, or not macOS: the caller falls back.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { appIconOf, appIconPngs, identityOfRoot } from '../core/app-icon.ts'
+import { identityOfName, type Identity } from '../core/identity-color.ts'
 import { LAYOUT } from '../core/layout.ts'
 
 const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.url))
@@ -17,15 +20,6 @@ const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.u
 export const BUNDLE_ID = 'dev.shipkit.gui'
 export const guiAppPath = (): string => process.env.SHIPKIT_GUI_APP ?? join(homedir(), 'Applications', 'Shipkit.app')
 
-/** the icon the app wears: the repo's own mark, largest first. Only a
- *  png can become an icns */
-export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
-
-export function appIconOf(root: string): string | null {
-    for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
-    return null
-}
-
 /** what one app bundle is: the rest comes from the shared source */
 export type AppSpec = {
     /** CFBundleName: the dock, cmd-tab and the app menu say it */
@@ -34,6 +28,8 @@ export type AppSpec = {
     /** the page a launch with no url opens; null opens the home */
     url: string | null
     icon: string | null
+    /** the repo's colours: the plate behind the icon's mark */
+    identity: Identity
     /** where the bundle lands */
     app: string
     version: string
@@ -52,7 +48,7 @@ function atsOf(url: string | null): string {
     return `<dict><key>NSAllowsLocalNetworking</key><true/>${exception}</dict>`
 }
 
-export function infoPlist(o: Omit<AppSpec, 'app' | 'icon'>): string {
+export function infoPlist(o: Omit<AppSpec, 'app' | 'icon' | 'identity'>): string {
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -79,6 +75,9 @@ const runSync: Run = (cmd) => {
     return { code: p.exitCode ?? 1, err: p.stderr.toString().trim() }
 }
 
+/** bumped when the icon drawing changes, so every built app redraws its icon */
+const ICON_DRAWING = 'plate-1'
+
 /** the stamp a built bundle carries: what it was built from. The version is
  *  left out, so a shipkit release rebuilds nothing */
 export function stampOf(source: string, icon: string | null, identity = ''): string {
@@ -89,11 +88,11 @@ export function stampOf(source: string, icon: string | null, identity = ''): str
 
 /** one app, built or rebuilt when stale. Throws with the step that failed.
  *  `rebuilt` tells the caller a running copy is now the old one */
-export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): { app: string; rebuilt: boolean } {
+export async function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): Promise<{ app: string; rebuilt: boolean }> {
     const { app, icon } = spec
     const run = o.run ?? runSync
     const source = o.source ?? SOURCE
-    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url]))
+    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url, spec.identity, ICON_DRAWING]))
     const stampFile = join(app, 'Contents', 'Resources', 'stamp')
     if (existsSync(stampFile) && readFileSync(stampFile, 'utf8') === stamp) return { app, rebuilt: false }
     const tmp = `${app}.building-${process.pid}`
@@ -108,12 +107,10 @@ export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {})
     if (icon != null) {
         const set = join(res, 'AppIcon.iconset')
         mkdirSync(set, { recursive: true })
-        for (const n of [16, 32, 128, 256, 512]) {
-            for (const [scale, px] of [['', n], ['@2x', n * 2]] as const) {
-                const r = run(['sips', '-s', 'format', 'png', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
-                if (r.code !== 0) fail(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`)
-            }
-        }
+        const files = [16, 32, 128, 256, 512].flatMap((n) => [[`icon_${n}x${n}.png`, n], [`icon_${n}x${n}@2x.png`, n * 2]] as const)
+        const pngs = await appIconPngs(readFileSync(icon), spec.identity, files.map(([, px]) => px))
+            .catch((e: Error) => fail(`could not draw the icon from ${icon}: ${e.message}`))
+        files.forEach(([file], i) => writeFileSync(join(set, file), pngs[i]!))
         const r = run(['iconutil', '-c', 'icns', set, '-o', join(res, 'AppIcon.icns')])
         rmSync(set, { recursive: true, force: true })
         if (r.code !== 0) fail(`iconutil could not build the icon: ${r.err.slice(0, 200)}`)
@@ -128,15 +125,15 @@ export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {})
 }
 
 /** the shipkit app: the shared source on the home, the house repo's icon */
-export function ensureGuiApp(o: { root: string | null; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
-    return ensureApp({ name: 'shipkit', bundleId: BUNDLE_ID, url: null, icon: o.root == null ? null : appIconOf(o.root), app: o.app ?? guiAppPath(), version: o.version }, { run: o.run })
+export function ensureGuiApp(o: { root: string | null; version: string; app?: string; run?: Run }): Promise<{ app: string; rebuilt: boolean }> {
+    return ensureApp({ name: 'shipkit', bundleId: BUNDLE_ID, url: null, icon: o.root == null ? null : appIconOf(o.root), identity: o.root == null ? identityOfName('shipkit') : identityOfRoot(o.root), app: o.app ?? guiAppPath(), version: o.version }, { run: o.run })
 }
 
 /** what a global process gives its app */
 export type WrapperOf = { id: string; label: string; url: string | null; icon: string | null; root: string }
 
-/** the image icons sips reads; an emoji or an svg leaves the repo's mark */
-const RASTER = /\.(png|jpe?g|gif|webp|bmp|tiff?)$/i
+/** the images the icon renderer reads; an emoji or an svg leaves the repo's mark */
+const RASTER = /\.(png|jpe?g|gif|webp)$/i
 
 export const wrapperBundleId = (id: string): string => `dev.shipkit.app.${id.replace(/[^A-Za-z0-9-]+/g, '-')}`
 export const wrapperPath = (root: string, id: string): string => join(root, LAYOUT.wrapper, `${id.replace(/[^A-Za-z0-9._-]+/g, '-')}.app`)
@@ -147,12 +144,12 @@ export const wrapperPath = (root: string, id: string): string => join(root, LAYO
 export function wrapperSpec(d: WrapperOf, version: string): AppSpec {
     if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
     const declared = d.icon != null && RASTER.test(d.icon) && existsSync(join(d.root, d.icon)) ? join(d.root, d.icon) : null
-    return { name: d.label, bundleId: wrapperBundleId(d.id), url: d.url, icon: declared ?? appIconOf(d.root), app: wrapperPath(d.root, d.id), version }
+    return { name: d.label, bundleId: wrapperBundleId(d.id), url: d.url, icon: declared ?? appIconOf(d.root), identity: identityOfRoot(d.root), app: wrapperPath(d.root, d.id), version }
 }
 
-export const ensureWrapperApp = (d: WrapperOf, o: { version: string; run?: Run }): { app: string; rebuilt: boolean; bundleId: string } => {
+export const ensureWrapperApp = async (d: WrapperOf, o: { version: string; run?: Run }): Promise<{ app: string; rebuilt: boolean; bundleId: string }> => {
     const spec = wrapperSpec(d, o.version)
-    return { ...ensureApp(spec, { run: o.run }), bundleId: spec.bundleId }
+    return { ...(await ensureApp(spec, { run: o.run })), bundleId: spec.bundleId }
 }
 
 /** quits a running copy of an app, and launches nothing when none runs */

package/src/home/home-launchd.ts

@@ -22,7 +22,10 @@ const esc = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;'
  *  every command, so any edit would restart pm. pm,
  *  the daemon and the web each watch their own code and restart in place on
  *  it (lib-watch.ts). PATH is the installing shell's, since launchd starts
- *  with almost none and the daemon needs bun, git, ps, lsof and ssh */
+ *  with almost none and the daemon needs bun, git, ps, lsof and ssh.
+ *  ProcessType Interactive: with none, launchd throttles the agent's disk
+ *  reads under load, every child inherits it, and a busy disk left the
+ *  daemon's boot reads minutes long while its port was already open */
 export function renderPlist(o: { bun: string; cli: string; root: string; path: string; log: string }): string {
     const args = [o.bun, o.cli, 'pm'].map((a) => `\t\t<string>${esc(a)}</string>`).join('\n')
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -42,6 +45,8 @@ ${args}
 \t\t<key>PATH</key>
 \t\t<string>${esc(o.path)}</string>
 \t</dict>
+\t<key>ProcessType</key>
+\t<string>Interactive</string>
 \t<key>RunAtLoad</key>
 \t<true/>
 \t<key>KeepAlive</key>
@@ -73,7 +78,13 @@ const launchctl: Launchctl = async (args) => {
 
 const domain = (): string => `gui/${process.getuid?.() ?? 501}`
 
-export async function installHome(o: { root: string; cli: string; print: (l: string) => void; run?: Launchctl }): Promise<number> {
+/** `bootout` returns before launchd lets go of the label, and a bootstrap in
+ *  that window fails (exit 5, EIO) with the old agent already gone: retried
+ *  this many times, BOOTSTRAP_STEP_MS apart, before the install fails */
+export const BOOTSTRAP_TRIES = 20
+const BOOTSTRAP_STEP_MS = 250
+
+export async function installHome(o: { root: string; cli: string; print: (l: string) => void; run?: Launchctl; sleep?: (ms: number) => Promise<void> }): Promise<number> {
     if (process.platform !== 'darwin') {
         o.print(`FAIL: the pm LaunchAgent is macOS only. Run \`shipkit pm\` under your own supervisor on ${process.platform}`)
         return 1
@@ -89,9 +100,14 @@ export async function installHome(o: { root: string; cli: string; print: (l: str
     await run(['bootout', `${domain()}/${LABEL}`])
     await run(['bootout', `${domain()}/${LEGACY_LABEL}`])
     rmSync(plistPath(homedir(), LEGACY_LABEL), { force: true })
-    const r = await run(['bootstrap', domain(), file])
+    const sleep = o.sleep ?? Bun.sleep
+    let r = await run(['bootstrap', domain(), file])
+    for (let i = 1; i < BOOTSTRAP_TRIES && r.code !== 0; i++) {
+        await sleep(BOOTSTRAP_STEP_MS)
+        r = await run(['bootstrap', domain(), file])
+    }
     if (r.code !== 0) {
-        o.print(`FAIL: launchctl bootstrap refused ${file} (exit ${r.code}): ${r.out}`)
+        o.print(`FAIL: launchctl bootstrap refused ${file} (exit ${r.code}, ${BOOTSTRAP_TRIES} tries): ${r.out}. pm is not loaded now: run \`shipkit pm install\` again`)
         return 1
     }
     o.print(`ok: pm runs now and at every login, from ${o.root}, and runs the daemon and the web`)

package/src/home/home-routes.ts

@@ -16,8 +16,11 @@ import { tailLines } from './supervise.ts'
 import { Hubs, type WorkerView } from './hubs.ts'
 import type { Planner, PlanRow } from '../plan/planner.ts'
 import type { Widgets, WidgetView } from './widgets.ts'
-import { ActivityCache, windowMinutes } from './activity.ts'
+import { ActivityCache, repoActivity, windowMinutes } from './activity.ts'
 import { HouseRuns } from '../serve/house-runs.ts'
+
+/** how far back a repo's git page lists its commits */
+export const GIT_PAGE_MS = 7 * 24 * 3600_000
 import type { HouseView } from '../ledger/house-runs.ts'
 
 /** how often the daemon looks at every repo */
@@ -173,6 +176,14 @@ export function homeRoutes(d: HomeDeps) {
             const q = new URL(req.url).searchParams
             return Response.json(await activity.get(repos, windowMinutes(q.get('m')), { fresh: q.get('fresh') === '1' }))
         }
+        // one repo's git for its git page: a week of commits, and HEAD's last
+        // one past that, whatever window the activity page shows
+        if (path === '/api/home/git.json') {
+            if (repos.length === 0) await refresh()
+            const r = find(new URL(req.url).searchParams.get('repo'))
+            if (r == null) return new Response('not a house repo', { status: 404 })
+            return Response.json(await repoActivity(r, Date.now() - GIT_PAGE_MS, (n) => d.plan?.declared(n) ?? null, (n) => d.plan?.titles(n) ?? null))
+        }
         if (path === '/api/house-runs.json') {
             if (repos.length === 0) await refresh()
             const view: HouseView = { ...house.view(), held: d.plan?.held() ?? [] }

package/src/home/home-start.ts

@@ -6,7 +6,11 @@ import { homedir } from 'os'
 import { dirname, join, resolve } from 'path'
 import { gitRoot } from '../core/git-root.ts'
 import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
-import { BUNDLE_ID, canBuildGui, ensureGuiApp, ensureWrapperApp, quitCmd, type WrapperOf } from './gui-app.ts'
+import type { WrapperOf } from './gui-app.ts'
+
+// the app builder draws icons with canvas: loaded when a window opens, never
+// at the startup of every command that imports this module
+const gui = (): Promise<typeof import('./gui-app.ts')> => import('./gui-app.ts')
 import { installedHouseRoot, LABEL, plistPath } from './home-launchd.ts'
 import { childLog, daemonPort, daemonUp, homeDir, homePort, homeUp, pmLog } from './home-paths.ts'
 
@@ -88,10 +92,11 @@ export function windowCmd(url: string, o: { chrome?: string; platform?: string }
 /** one more home window: the native app where it can be built (its own
  *  dock icon, the house mark), else a Chrome app window. `warn` hears why the
  *  native one was not used */
-export function openWindow(url: string, o: { root?: string | null; version?: string; warn?: (l: string) => void } = {}): string[] {
+export async function openWindow(url: string, o: { root?: string | null; version?: string; warn?: (l: string) => void } = {}): Promise<string[]> {
+    const { BUNDLE_ID, canBuildGui, ensureGuiApp, quitCmd } = await gui()
     if (canBuildGui()) {
         try {
-            const { app, rebuilt } = ensureGuiApp({ root: o.root ?? guiRoot(process.cwd()),version: o.version ?? '0' })
+            const { app, rebuilt } = await ensureGuiApp({ root: o.root ?? guiRoot(process.cwd()),version: o.version ?? '0' })
             // a running copy is the old build: it quits, and the new one opens the window
             if (rebuilt) Bun.spawnSync(quitCmd(BUNDLE_ID), { stdout: 'ignore', stderr: 'ignore' })
             const cmd = ['open', '-a', app, url]
@@ -108,11 +113,12 @@ export function openWindow(url: string, o: { root?: string | null; version?: str
  *  `.shipkit/wrapper/`, then opened with no url, so a running copy comes to
  *  the front instead of stacking windows. Where no app can be built, a
  *  Chrome app window on its url */
-export function openProcessApp(d: WrapperOf, o: { version: string; warn?: (l: string) => void }): string[] {
+export async function openProcessApp(d: WrapperOf, o: { version: string; warn?: (l: string) => void }): Promise<string[]> {
     if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
+    const { canBuildGui, ensureWrapperApp, quitCmd } = await gui()
     if (canBuildGui()) {
         try {
-            const { app, rebuilt, bundleId } = ensureWrapperApp(d, { version: o.version })
+            const { app, rebuilt, bundleId } = await ensureWrapperApp(d, { version: o.version })
             if (rebuilt) Bun.spawnSync(quitCmd(bundleId), { stdout: 'ignore', stderr: 'ignore' })
             const cmd = ['open', '-a', app]
             Bun.spawnSync(cmd, { stdout: 'ignore', stderr: 'ignore' })

package/src/home/hubs.ts

@@ -132,7 +132,7 @@ export class Hubs {
                 const rt = await this.o.load(e.repo, io, { fresh: fresh || e.loads > 0 })
                 // a stop by hand came while it loaded, and wins
                 if (e.held) {
-                    rt.stop({ procs: true })
+                    rt.stop()
                     this.set(e, 'down', 'stopped by hand')
                     return
                 }
@@ -158,7 +158,7 @@ export class Hubs {
         const names = new Set(repos.map((r) => r.name))
         for (const [name, e] of this.entries) {
             if (names.has(name)) continue
-            e.rt?.stop({ procs: true })
+            e.rt?.stop()
             this.entries.delete(name)
         }
         for (const r of repos) {
@@ -179,7 +179,7 @@ export class Hubs {
     stop(repo: WiredRepo): WorkerView {
         const e = this.entry(repo)
         e.held = true
-        e.rt?.stop({ procs: true })
+        e.rt?.stop()
         e.rt = null
         this.set(e, 'down', 'stopped by hand')
         return this.view(e)
@@ -190,7 +190,7 @@ export class Hubs {
         const e = this.entry(repo)
         await e.loading
         e.held = false
-        e.rt?.stop({ procs: true })
+        e.rt?.stop()
         e.rt = null
         await this.schedule(e, true)
         return this.view(e)
@@ -279,7 +279,7 @@ export class Hubs {
         return repos.map((r) => this.view(this.entry(r)))
     }
 
-    /** every hub stops, its processes left running for the next home to adopt */
+    /** every hub stops */
     stopAll(): void {
         for (const e of this.entries.values()) e.rt?.stop()
     }

package/src/home/open-app.ts

@@ -13,10 +13,10 @@ if (import.meta.main) {
     try {
         if (first === '--process' && second != null) {
             const d = JSON.parse(second) as WrapperOf
-            const cmd = openProcessApp(d, { version: LIB_VERSION, warn })
+            const cmd = await openProcessApp(d, { version: LIB_VERSION, warn })
             console.log(`shipkit: opened ${d.id} as its own app: ${cmd.join(' ')}`)
         } else if (first != null && first !== '--process') {
-            const cmd = openWindow(first, { version: LIB_VERSION, warn })
+            const cmd = await openWindow(first, { version: LIB_VERSION, warn })
             console.log(`shipkit: opened ${first} as an app window: ${cmd.join(' ')}`)
         } else {
             console.error('usage: bun open-app.ts <url> | --process <json>')

package/src/home/pm.ts

@@ -27,6 +27,10 @@ export type ChildView = ProcView & { tail: string[] }
 /** where pm, the daemon and the web listen */
 export type CorePorts = { pm: number; daemon: number; web: number }
 
+/** a child whose pid lives but has not answered for this long is hung and
+ *  gets killed: a healthy daemon answers within about 20 s of its start */
+export const CHILD_HANG_MS = 90_000
+
 /** how many log lines each of shipkit's own processes hands the page */
 const CORE_TAIL = 20
 
@@ -61,6 +65,8 @@ export type PmDeps = {
     /** runs a stop or restart of the web once its answer is out: the web
      *  proxies that very request (default: 200 ms later) */
     later?: (f: () => void) => void
+    /** where pm says what it did on its own, a hung child killed */
+    say?: (line: string) => void
 }
 
 const WEB_ANSWER_MS = 200
@@ -79,6 +85,8 @@ export class Pm {
             probe: () => d.probe(role),
             // a crash loop while its code is being edited heals itself
             neverGiveUp: true,
+            hangMs: CHILD_HANG_MS,
+            say: d.say,
         }, d.deps ?? realDeps)]))
     }
 

package/src/home/run-pm.ts

@@ -100,6 +100,7 @@ export async function runPm(root: string, io: HomeIo, o: { port?: number } = {})
         cmd: (role) => [process.execPath, CLI, role],
         probe: roleAnswers,
         resources: new Resources(c.processes, dir),
+        say: io.printErr,
     })
     let server: Bun.Server<unknown>
     try {

package/src/home/serve-web.ts

@@ -51,8 +51,8 @@ export const REPO_ANSWER_MS = 30_000
 export const LIST_EVERY_MS = 30_000
 export const LIST_RETRY_MS = 1_000
 
-/** the one home answer that can wait on git: the activity page's first read of a window */
-export const readsGit = (path: string): boolean => path === '/api/home/activity.json'
+/** the home answers that can wait on git: the activity page's first read of a window, and a repo's git page */
+export const readsGit = (path: string): boolean => path === '/api/home/activity.json' || path === '/api/home/git.json'
 
 /** a run or a check run streams for minutes, and a silent one is never cut */
 export const streams = (path: string): boolean => /\/api\/(run|check\/run)$/.test(path)

package/src/home/supervise.ts

@@ -29,6 +29,12 @@ export type ProcSpec = {
     /** never left down after CRASH_LIMIT crashes: it keeps retrying at the
      *  longest backoff, so a code fix brings it back with no hand */
     neverGiveUp?: boolean
+    /** a pid that lives but has not answered its probe for this long is hung
+     *  (a main thread stuck in one synchronous step still holds its port):
+     *  killed, then started again after the crash backoff. None = never */
+    hangMs?: number
+    /** a line for every act the supervisor takes on its own */
+    say?: (line: string) => void
 }
 
 export type ProcView = {
@@ -137,6 +143,8 @@ export class Proc {
     private retryAt: number | null = null
     private killAt: number | null = null
     private probing = false
+    /** why the kill in flight was a hang kill, for the crash note */
+    private hung: string | null = null
     /** a restart: start again once the stop landed */
     private again = false
     /** it answers its probe with no pid of ours behind it */
@@ -275,6 +283,8 @@ export class Proc {
         const now = this.d.now()
         if (this.pid != null && !this.d.alive(this.pid)) {
             this.gone()
+            const hung = this.hung
+            this.hung = null
             if (this.again) {
                 this.again = false
                 this.want = 'up'
@@ -287,7 +297,7 @@ export class Proc {
                     this.set('crashed', `exited ${this.crashes.length} times in ${Math.round(CRASH_WINDOW_MS / 60_000)} min, left down: see the log`)
                 } else {
                     this.retryAt = now + BACKOFF_MS[Math.min(this.crashes.length - 1, BACKOFF_MS.length - 1)]!
-                    this.set('crashed', `exited, restart in ${Math.round((this.retryAt - now) / 1000)}s`)
+                    this.set('crashed', `${hung != null ? `${hung}, killed` : 'exited'}, restart in ${Math.round((this.retryAt - now) / 1000)}s`)
                 }
             }
         }
@@ -318,6 +328,19 @@ export class Proc {
         } finally {
             this.probing = false
         }
+        this.killIfHung(now)
+    }
+
+    /** a pid that lives and still has not answered, hangMs after it last
+     *  changed status, is stopped: the crash path starts it again */
+    private killIfHung(now: number): void {
+        const hang = this.spec.hangMs
+        if (hang == null || this.status !== 'starting' || this.pid == null || this.want !== 'up' || now - this.since < hang) return
+        this.hung = `did not answer its probe for ${Math.round((now - this.since) / 1000)}s`
+        this.spec.say?.(`WARN ${this.spec.id} (pid ${this.pid}) ${this.hung}: killed, it starts again`)
+        this.d.kill(this.pid, 'SIGTERM')
+        this.killAt = now + KILL_AFTER_MS
+        this.set('stopping', `${this.hung}, killing it`)
     }
 
     view(): ProcView {

package/src/home/via-hub.ts

@@ -17,6 +17,18 @@ import { daemonUp, daemonUrl, hubBase, WORKER_ENV } from './home-paths.ts'
 import { homeWanted, startHome } from './home-start.ts'
 import { RUN_EXIT, RUN_JOB } from './home-words.ts'
 import { followJob, type FollowOpts } from '../core/job-follow.ts'
+import { TRACE_ENV } from '../trace/tracer.ts'
+import { FRESH_ENV } from '../ledger/store.ts'
+import { LEDGER_ENV } from '../ledger/ledger.ts'
+import { PARALLEL_ENV } from '../core/parallel.ts'
+
+/** the env switches a gate reads, which a terminal may set for one run: the
+ *  job the home starts runs with the daemon's env, so they travel with it */
+export const FORWARDED_ENV = [TRACE_ENV, FRESH_ENV, LEDGER_ENV, PARALLEL_ENV] as const
+
+/** the forwarded switches this env sets */
+export const forwardedEnv = (env: Env = process.env): Record<string, string> =>
+    Object.fromEntries(FORWARDED_ENV.filter((k) => env[k] != null && env[k] !== '').map((k) => [k, env[k]!]))
 
 type Env = Record<string, string | undefined>
 const set = (v: string | undefined): boolean => v != null && v !== ''
@@ -46,10 +58,12 @@ export async function runViaHub(root: string, kind: 'ci' | 'check', opts: Record
     }
     // what the terminal knows and the hub does not: its tier and whether it is a terminal
     const full = process.env.SHIPKIT_TEST_FULL === '1'
+    const env = forwardedEnv()
     const sent = {
         ...opts,
         ...(full ? (kind === 'ci' ? { tests: opts.tests ?? 'full' } : { tier: opts.tier ?? 'full' }) : {}),
         color: process.stdout.isTTY === true && process.env.NO_COLOR == null,
+        ...(Object.keys(env).length > 0 ? { env } : {}),
     }
     // the home waits for a hub still loading before it answers
     const post = (): Promise<Response> => fetch(`${daemonUrl()}${hubBase(name)}/api/run`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind, opts: sent }) })

package/src/hooks/run-hooks.ts

@@ -14,6 +14,11 @@ import { gitRoot } from '../core/git-root.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { gitBin } from '../core/git-bin.ts'
+import { discoverChecks } from '../core/discover-checks.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
+import { runCheckBody, type CheckDef } from '../check.ts'
+import { repoOff } from '../core/when.ts'
+import { formatLine } from '../core/wire.ts'
 
 export type HooksConfig = {
     /** repo-specific commands run in the pre-commit gate, after the built-ins.
@@ -210,7 +215,7 @@ export function blockedStaged(staged: string[], config: RepoConfig): string[] {
 const draftsOpen = (c: RepoConfig): boolean => c.visibility === 'private'
 
 /** the pre-commit gate: built-in leak guard, then the repo's own commands.
- *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
+ *  A commit takes ~1s (build/shipkit/commit-gates.md): the gate times itself, and going
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
 export async function runPreCommit(root: string, config: RepoConfig): Promise<GateOutcome[]> {
     const started = performance.now()
@@ -273,6 +278,7 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             ],
         })
     }
+    out.push(...(await runPreCommitChecks(root, config)))
     for (const c of h.preCommit ?? []) {
         const r = await spawnWithTimeout(c.cmd, { cwd: root, timeoutMs: 120_000 })
         out.push({
@@ -282,15 +288,52 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
         })
     }
     const elapsed = performance.now() - started
-    if (elapsed > 1500)
+    if (elapsed > HOOK_BUDGET_MS)
         out.push({
             id: 'hook-budget',
             ok: true,
-            lines: [`WARN pre-commit took ${(elapsed / 1000).toFixed(1)}s (budget ~1s) — move slow preCommit commands to ci tasks (build/shipkit.md)`],
+            lines: [`WARN pre-commit took ${(elapsed / 1000).toFixed(1)}s (budget ${HOOK_BUDGET_MS / 1000}s) — move slow preCommit commands to ci tasks, or a check off onPreCommit (build/shipkit/runs.md)`],
         })
     return out
 }
 
+/** the whole hook, boot included, past which it warns */
+export const HOOK_BUDGET_MS = 1_000
+
+/** the checks that declare `onPreCommit` and apply here, with their budget */
+export type PreCommitCheck = { id: string; title: string; owner: string; budgetMs: number; run: NonNullable<CheckDef['run']>; repair: unknown }
+
+export async function preCommitChecks(root: string, config: RepoConfig): Promise<PreCommitCheck[]> {
+    const out: PreCommitCheck[] = []
+    for (const u of await discoverChecks(root)) {
+        const p = u.def.runs.onPreCommit
+        if (p === false || u.def.run == null) continue
+        if (repoOff(config, u.id) != null) continue
+        if (typeof u.def.applies === 'function') {
+            try { if (u.def.applies({ root, config }) != null) continue } catch (e) { console.error(`WARN ${u.id} applies threw, so it applies: ${(e as Error).message}`) }
+        }
+        out.push({ id: u.id, title: u.title, owner: u.owner, budgetMs: p.budgetMs, run: u.def.run, repair: u.def.repair })
+    }
+    return out
+}
+
+/** every `onPreCommit` check, run RAW on the working tree: no ledger, no
+ *  cache, no repair. A failure refuses the commit, a pass over its budget
+ *  warns by name and never blocks on time */
+async function runPreCommitChecks(root: string, config: RepoConfig): Promise<GateOutcome[]> {
+    const out: GateOutcome[] = []
+    for (const k of await preCommitChecks(root, config)) {
+        const c = CheckCtx.open({ root, config })
+        const t = performance.now()
+        await runCheckBody({ id: k.id, title: k.title, owner: k.owner, run: k.run, fix: k.repair }, c)
+        const ms = performance.now() - t
+        const lines = c.failed ? c.lines.map((l) => formatLine(l, false)) : [`ok: ${k.id} (${Math.round(ms)}ms)`]
+        if (ms > k.budgetMs) lines.push(`WARN ${k.id} took ${Math.round(ms)}ms at commit, over its ${k.budgetMs}ms onPreCommit budget — make it cheaper, or move it off onPreCommit`)
+        out.push({ id: k.id, ok: !c.failed, lines })
+    }
+    return out
+}
+
 /** the commit-msg gate: the shared message predicate, then the repo's own. */
 export async function runCommitMsg(root: string, config: RepoConfig, messageFile: string): Promise<GateOutcome[]> {
     const h = config.hooks ?? {}
@@ -339,7 +382,7 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
 }
 
 /** what blocks a commit here, the enumeration hand-rolled hooks never had. */
-export function listGates(config: RepoConfig, root = process.cwd()): string[] {
+export function listGates(config: RepoConfig, root = process.cwd(), checks: { id: string; budgetMs: number }[] = []): string[] {
     const h = config.hooks ?? {}
     const off = new Set(h.disable ?? [])
     const kw = h.keywordFile ?? KEYWORD_FILE
@@ -354,6 +397,7 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
         `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.shipkit/private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git${draftsOpen(config) && blockedStaged([COMFY_DRAFTS], config).length === 0 && h.blockedPaths!.some((p) => COMFY_DRAFTS.startsWith(p)) ? `, except ${COMFY_DRAFTS} (declared private)` : ''}`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
+        ...checks.map((c) => `pre-commit  ${c.id} — the check, onPreCommit, budget ${c.budgetMs}ms`),
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
         off.has('commit-message')
             ? `commit-msg  commit-message (DISABLED by config) — dash punctuation + French; ai-attribution stays on, never disabled`

package/src/init-repo.ts

@@ -100,7 +100,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
         // its .gitignore policy block (same fixer as `check --fix SK004`),
         // with the repo's own contributed lines honored
         const cfg = await loadRepoConfig(root)
-        const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: cfg }))
+        const g = await gitignorePolicy.repair!(CheckCtx.open({ root, config: cfg }))
         p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
         // the repos that need ONE WAY IN most are the ones that already exist,
         // so a re-run REPAIRS rather than only seeding a fresh checkout
@@ -136,7 +136,7 @@ export async function initRepo(root: string, opts: InitOpts = {}): Promise<numbe
     }
     // the .gitignore policy block (contract git policy) — same fixer as
     // `shipkit check --fix SK004`, one code path
-    const g = await gitignorePolicy.fix!(CheckCtx.open({ root, config: defineRepo({ name }) }))
+    const g = await gitignorePolicy.repair!(CheckCtx.open({ root, config: defineRepo({ name }) }))
     p(`ok: .gitignore policy block ${g.changed ? 'written' : 'already current'}`)
     await repairOneWayIn(root, defineRepo({ name }), p)
     await furnishEditor(root, { name }, p)
@@ -194,7 +194,7 @@ async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?
             // a file SK017 cannot read is still the repo's own: it is never
             // reported as missing, and it is never rewritten
             let hub: { changed: boolean; summary: string }
-            try { hub = await vscodeHubTask.fix!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
+            try { hub = await vscodeHubTask.repair!(CheckCtx.open({ root, config: defineRepo({ name }) })) } catch (e) {
                 p('ok: .vscode/ is this repo\'s own, left untouched')
                 return void p(`WARN .vscode/tasks.json does not parse (${e instanceof Error ? e.message : String(e)}): the hub task gets no problem matcher until it does`)
             }
@@ -208,14 +208,14 @@ async function furnishEditor(root: string, cfg: { name?: string; serve?: { port?
 }
 
 /** ONE WAY IN, both halves, through the SAME fixers `shipkit check --fix` runs
- *  (build/shipkit.md). Nothing here is a second implementation: rule SK001
+ *  (build/shipkit/one-way-in.md). Nothing here is a second implementation: rule SK001
  *  routes the package.json scripts, rule SK013 writes the harness policy, and
  *  init just calls them so a wired repo is born enforced and a re-run repairs
  *  one that was not. The deny is a RESTRICTION, which is why it lands
  *  unconditionally where the scaffold's allow list stays opt in. */
 async function repairOneWayIn(root: string, config: Parameters<typeof defineRepo>[0], p: (line: string) => void): Promise<void> {
-    const pkg = await packageJsonShape.fix!(CheckCtx.open({ root, config }))
+    const pkg = await packageJsonShape.repair!(CheckCtx.open({ root, config }))
     if (pkg.changed) p(`ok: package.json — ${pkg.summary}`)
-    const policy = await oneWayInPolicy.fix!(CheckCtx.open({ root, config }))
+    const policy = await oneWayInPolicy.repair!(CheckCtx.open({ root, config }))
     p(policy.changed ? `ok: ${policy.summary}` : `ok: .claude/settings.json already closes every raw runner`)
 }