rvlib-shipkit 1.3.0 → 1.5.0

package/src/home/gui-app.ts

@@ -1,90 +1,122 @@
-// the macOS app `shipkit gui` opens windows through: a bundle built once from
-// ShipkitGui.swift with swiftc, carrying the house repo's own icon, so the
-// dock and cmd-tab show it and never a second Chrome. Rebuilt only when the
-// source or the icon changed (a stamp in the bundle). No compiler, or not
-// macOS: the caller falls back to a Chrome app window.
+// the macOS apps shipkit opens web pages in: ONE source, ShipkitGui.swift,
+// built with swiftc into a bundle per page it serves. `shipkit gui` is that
+// app pointed at the home; each global process with a url gets its own, named
+// 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.
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { LAYOUT } from '../core/layout.ts'
 
 const SOURCE = fileURLToPath(new URL('./gui-app/ShipkitGui.swift', import.meta.url))
 
 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 house repo's own mark, largest first. Only a
+/** the icon the app wears: the repo's own mark, largest first. Only a
  *  png can become an icns */
-export const APP_ICON_FILES = ['.shipkit/identity/icon.png', 'public/logo.png', 'public/favicon.png']
+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
 }
 
-export function infoPlist(o: { version: string }): string {
+/** 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 */
+    name: string
+    bundleId: string
+    /** the page a launch with no url opens; null opens the home */
+    url: string | null
+    icon: string | null
+    /** where the bundle lands */
+    app: string
+    version: string
+}
+
+const xml = (s: string): string => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/** plain http to a host that is not local needs its own ATS exception; the
+ *  local network is allowed to every app */
+function atsOf(url: string | null): string {
+    let u: URL | null = null
+    try { u = url == null ? null : new URL(url) } catch { /* not a url: the local network only */ }
+    const host = u?.protocol === 'http:' ? u.hostname : null
+    const local = host == null || host === 'localhost' || /^[\d.]+$/.test(host) || !host.includes('.') || host.endsWith('.local')
+    const exception = local ? '' : `<key>NSExceptionDomains</key><dict><key>${xml(host)}</key><dict><key>NSExceptionAllowsInsecureHTTPLoads</key><true/></dict></dict>`
+    return `<dict><key>NSAllowsLocalNetworking</key><true/>${exception}</dict>`
+}
+
+export function infoPlist(o: Omit<AppSpec, 'app' | 'icon'>): 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">
 <dict>
-\t<key>CFBundleName</key><string>shipkit</string>
-\t<key>CFBundleDisplayName</key><string>shipkit</string>
-\t<key>CFBundleIdentifier</key><string>${BUNDLE_ID}</string>
+\t<key>CFBundleName</key><string>${xml(o.name)}</string>
+\t<key>CFBundleDisplayName</key><string>${xml(o.name)}</string>
+\t<key>CFBundleIdentifier</key><string>${xml(o.bundleId)}</string>
 \t<key>CFBundleExecutable</key><string>shipkit-gui</string>
 \t<key>CFBundleIconFile</key><string>AppIcon</string>
 \t<key>CFBundlePackageType</key><string>APPL</string>
-\t<key>CFBundleShortVersionString</key><string>${o.version}</string>
-\t<key>CFBundleVersion</key><string>${o.version}</string>
-\t<key>LSMinimumSystemVersion</key><string>12.0</string>
+\t<key>CFBundleShortVersionString</key><string>${xml(o.version)}</string>
+\t<key>CFBundleVersion</key><string>${xml(o.version)}</string>
+${o.url == null ? '' : `\t<key>ShipkitStartURL</key><string>${xml(o.url)}</string>\n`}\t<key>LSMinimumSystemVersion</key><string>12.0</string>
 \t<key>NSHighResolutionCapable</key><true/>
-\t<key>NSAppTransportSecurity</key><dict><key>NSAllowsLocalNetworking</key><true/></dict>
+\t<key>NSAppTransportSecurity</key>${atsOf(o.url)}
 </dict>
 </plist>
 `
 }
 
-type Run = (cmd: string[]) => { code: number; err: string }
+export type Run = (cmd: string[]) => { code: number; err: string }
 const runSync: Run = (cmd) => {
     const p = Bun.spawnSync(cmd, { stdout: 'ignore', stderr: 'pipe' })
     return { code: p.exitCode ?? 1, err: p.stderr.toString().trim() }
 }
 
-/** the stamp a built bundle carries: what it was built from */
-export function stampOf(source: string, icon: string | null): string {
-    const h = new Bun.CryptoHasher('sha256').update(source)
+/** 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 {
+    const h = new Bun.CryptoHasher('sha256').update(source).update(identity)
     if (icon != null) h.update(readFileSync(icon))
     return h.digest('hex').slice(0, 16)
 }
 
-/** the app, built or rebuilt when stale. Throws with the step that failed.
+/** 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 ensureGuiApp(o: { root: string; version: string; app?: string; run?: Run }): { app: string; rebuilt: boolean } {
-    const app = o.app ?? guiAppPath()
+export function ensureApp(spec: AppSpec, o: { run?: Run; source?: string } = {}): { app: string; rebuilt: boolean } {
+    const { app, icon } = spec
     const run = o.run ?? runSync
-    const icon = appIconOf(o.root)
-    const stamp = stampOf(readFileSync(SOURCE, 'utf8'), icon)
+    const source = o.source ?? SOURCE
+    const stamp = stampOf(readFileSync(source, 'utf8'), icon, JSON.stringify([spec.name, spec.bundleId, spec.url]))
     const stampFile = join(app, 'Contents', 'Resources', 'stamp')
     if (existsSync(stampFile) && readFileSync(stampFile, 'utf8') === stamp) return { app, rebuilt: false }
     const tmp = `${app}.building-${process.pid}`
+    const fail = (msg: string): never => { rmSync(tmp, { recursive: true, force: true }); throw new Error(msg) }
     rmSync(tmp, { recursive: true, force: true })
     const res = join(tmp, 'Contents', 'Resources')
     mkdirSync(join(tmp, 'Contents', 'MacOS'), { recursive: true })
     mkdirSync(res, { recursive: true })
-    writeFileSync(join(tmp, 'Contents', 'Info.plist'), infoPlist({ version: o.version }))
-    const built = run(['swiftc', '-O', '-o', join(tmp, 'Contents', 'MacOS', 'shipkit-gui'), SOURCE])
-    if (built.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`swiftc could not build the gui app: ${built.err.slice(0, 400)}`) }
+    writeFileSync(join(tmp, 'Contents', 'Info.plist'), infoPlist(spec))
+    const built = run(['swiftc', '-O', '-o', join(tmp, 'Contents', 'MacOS', 'shipkit-gui'), source])
+    if (built.code !== 0) fail(`swiftc could not build ${spec.name}.app: ${built.err.slice(0, 400)}`)
     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', '-z', String(px), String(px), icon, '--out', join(set, `icon_${n}x${n}${scale}.png`)])
-                if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`sips could not size the icon ${icon}: ${r.err.slice(0, 200)}`) }
+                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 r = run(['iconutil', '-c', 'icns', set, '-o', join(res, 'AppIcon.icns')])
         rmSync(set, { recursive: true, force: true })
-        if (r.code !== 0) { rmSync(tmp, { recursive: true, force: true }); throw new Error(`iconutil could not build the icon: ${r.err.slice(0, 200)}`) }
+        if (r.code !== 0) fail(`iconutil could not build the icon: ${r.err.slice(0, 200)}`)
     }
     writeFileSync(join(res, 'stamp'), stamp)
     mkdirSync(dirname(app), { recursive: true })
@@ -95,5 +127,36 @@ export function ensureGuiApp(o: { root: string; version: string; app?: string; r
     return { app, rebuilt: true }
 }
 
+/** 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 })
+}
+
+/** 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
+
+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`)
+
+/** the spec of a process's own app: its label, its declared image icon or
+ *  else its repo's mark, in its repo's `.shipkit/wrapper/`. Throws for a
+ *  process with no url: there is no page to wrap */
+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 }
+}
+
+export const ensureWrapperApp = (d: WrapperOf, o: { version: string; run?: Run }): { app: string; rebuilt: boolean; bundleId: string } => {
+    const spec = wrapperSpec(d, o.version)
+    return { ...ensureApp(spec, { run: o.run }), bundleId: spec.bundleId }
+}
+
+/** quits a running copy of an app, and launches nothing when none runs */
+export const quitCmd = (bundleId: string): string[] => ['osascript', '-e', `if application id "${bundleId}" is running then quit application id "${bundleId}"`]
+
 /** true when this machine can build the app */
 export const canBuildGui = (platform = process.platform): boolean => platform === 'darwin' && Bun.which('swiftc') != null && Bun.which('iconutil') != null

package/src/home/home-launchd.ts

@@ -2,7 +2,7 @@
 // dies. macOS only; launchd is the one supervisor of the one process that must
 // always run, and pm supervises everything else (the daemon, the web, the
 // machine resources).
-import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { homeDir, pmLog } from './home-paths.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>
@@ -55,7 +60,15 @@ ${args}
 `
 }
 
-type Launchctl = (args: string[]) => Promise<{ code: number; out: string }>
+/** the house repo the installed pm runs from, read back from its agent: the
+ *  one answer to "which house" that does not depend on cwd */
+export function installedHouseRoot(file = plistPath()): string | null {
+    if (!existsSync(file)) return null
+    const m = /<key>WorkingDirectory<\/key>\s*<string>([^<]*)<\/string>/.exec(readFileSync(file, 'utf8'))
+    return m == null ? null : m[1]!.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+}
+
+type Launchctl =(args: string[]) => Promise<{ code: number; out: string }>
 
 const launchctl: Launchctl = async (args) => {
     const p = Bun.spawn(['launchctl', ...args], { stdout: 'pipe', stderr: 'pipe' })
@@ -65,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
@@ -81,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,13 +176,22 @@ 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() ?? [] }
             return Response.json(view, { headers: { 'cache-control': 'no-store' } })
         }
         if (path === '/api/home/widgets.json') {
-            const out: WidgetsAnswer = { widgets: d.widgets?.views() ?? [], errors: d.widgets?.errors ?? [] }
+            if (d.widgets != null && repos.length === 0) await refresh()
+            const out: WidgetsAnswer = { widgets: (await d.widgets?.look(repos.map((r) => ({ name: r.name, path: r.path })))) ?? [], errors: d.widgets?.errors ?? [] }
             return Response.json(out)
         }
         if (path === '/api/home.json') {

package/src/home/home-start.ts

@@ -6,8 +6,8 @@ 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 } from './gui-app.ts'
-import { LABEL, plistPath } from './home-launchd.ts'
+import { BUNDLE_ID, canBuildGui, ensureGuiApp, ensureWrapperApp, quitCmd, type WrapperOf } from './gui-app.ts'
+import { installedHouseRoot, LABEL, plistPath } from './home-launchd.ts'
 import { childLog, daemonPort, daemonUp, homeDir, homePort, homeUp, pmLog } from './home-paths.ts'
 
 /** the pm LaunchAgent is installed: on this machine no hub runs outside the home */
@@ -65,7 +65,11 @@ export function houseRootOf(cwd: string): string | null {
     return gitRoot(dirname(index))?.top ?? null
 }
 
-export const CHROME = process.env.CHROME ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+/** the house the shipkit app wears the mark of: the one cwd sits in, else the
+ *  one the installed pm runs from. Never cwd itself, which carries no mark */
+export const guiRoot = (cwd: string, plist = plistPath()): string | null => houseRootOf(cwd) ?? installedHouseRoot(plist)
+
+export const CHROME =process.env.CHROME ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
 /** the window's own Chrome profile: its own dock icon and cookies, apart from the everyday browser */
 export const guiProfile = (): string => join(homeDir(), 'gui-profile')
 const GUI_DISK_CACHE = 32 * 1024 * 1024
@@ -87,9 +91,9 @@ export function windowCmd(url: string, o: { chrome?: string; platform?: string }
 export function openWindow(url: string, o: { root?: string | null; version?: string; warn?: (l: string) => void } = {}): string[] {
     if (canBuildGui()) {
         try {
-            const { app, rebuilt } = ensureGuiApp({ root: o.root ?? houseRootOf(process.cwd()) ?? process.cwd(), version: o.version ?? '0' })
+            const { app, rebuilt } = 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(['osascript', '-e', `quit app id "${BUNDLE_ID}"`], { stdout: 'ignore', stderr: 'ignore' })
+            if (rebuilt) Bun.spawnSync(quitCmd(BUNDLE_ID), { stdout: 'ignore', stderr: 'ignore' })
             const cmd = ['open', '-a', app, url]
             Bun.spawn(cmd, { stdio: ['ignore', 'ignore', 'ignore'] })
             return cmd
@@ -97,6 +101,30 @@ export function openWindow(url: string, o: { root?: string | null; version?: str
             o.warn?.(`WARN the shipkit app could not be built, so this window is a Chrome one: ${(e as Error).message}`)
         }
     }
+    return chromeWindow(url)
+}
+
+/** a global process's own app: built on first use in its repo's
+ *  `.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[] {
+    if (d.url == null) throw new Error(`${d.id} declares no url: there is no page to open as an app`)
+    if (canBuildGui()) {
+        try {
+            const { app, rebuilt, bundleId } = 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' })
+            return cmd
+        } catch (e) {
+            o.warn?.(`WARN the app for ${d.id} could not be built, so this window is a Chrome one: ${(e as Error).message}`)
+        }
+    }
+    return chromeWindow(d.url)
+}
+
+function chromeWindow(url: string): string[] {
     mkdirSync(guiProfile(), { recursive: true })
     const cmd = windowCmd(url)
     // detached: the window outlives the command that opened it

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/machine-stores.ts

@@ -91,8 +91,9 @@ export const BOOT_SWEEP_DELAY_MS = 10_000
 export type Sweeper = { stop: () => void; once: () => Promise<void> }
 
 /** the daemon's one retention sweep: every repo it loads, then the machine,
- *  on boot and every hour. A store whose sweep throws is one printed line */
-export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (l: string) => void; everyMs?: number; bootDelayMs?: number; now?: () => number }): Sweeper {
+ *  then `also` (the machine's batched writes), on boot and every hour. A
+ *  store whose sweep throws is one printed line */
+export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (l: string) => void; everyMs?: number; bootDelayMs?: number; now?: () => number; also?: (now: number) => void }): Sweeper {
     let running = false
     const once = async (): Promise<void> => {
         if (running) return
@@ -103,6 +104,7 @@ export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (
                 for (const r of await sweepStores(repoStores(root), now)) if (r.error != null) o.printErr(`WARN retention sweep of ${r.id} in ${root} failed: ${r.error}`)
             }
             for (const r of await sweepStores(machineStores(o.dir), now)) if (r.error != null) o.printErr(`WARN retention sweep of ${r.id} failed: ${r.error}`)
+            o.also?.(now)
         } finally {
             running = false
         }

package/src/home/open-app.ts

@@ -1,16 +1,29 @@
-// opens one shipkit app window on a url, in its own short process, so pm
-// never loads what building the app needs:
+// opens one shipkit app window, in its own short process, so pm never loads
+// what building an app needs:
 //
-//   bun open-app.ts <url>
+//   bun open-app.ts <url>                 one more shipkit window on a url
+//   bun open-app.ts --process <json>      a global process's own app (WrapperOf)
 import { LIB_VERSION } from '../core/lib-version.ts'
-import { openWindow } from './home-start.ts'
+import type { WrapperOf } from './gui-app.ts'
+import { openProcessApp, openWindow } from './home-start.ts'
 
 if (import.meta.main) {
-    const url = process.argv[2]
-    if (url == null) {
-        console.error('usage: bun open-app.ts <url>')
-        process.exit(2)
+    const [first, second] = process.argv.slice(2)
+    const warn = (l: string): void => console.error(l)
+    try {
+        if (first === '--process' && second != null) {
+            const d = JSON.parse(second) as WrapperOf
+            const cmd = 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 })
+            console.log(`shipkit: opened ${first} as an app window: ${cmd.join(' ')}`)
+        } else {
+            console.error('usage: bun open-app.ts <url> | --process <json>')
+            process.exit(2)
+        }
+    } catch (e) {
+        console.error(`shipkit: could not open the app: ${(e as Error).message}`)
+        process.exit(1)
     }
-    const cmd = openWindow(url, { version: LIB_VERSION, warn: (l) => console.error(l) })
-    console.log(`shipkit: opened ${url} as an app window: ${cmd.join(' ')}`)
 }

package/src/home/pm-config.ts

@@ -2,18 +2,14 @@
 // and the global processes every house repo declares in its `.shipkit.ts`
 // files), read in a short child process so pm itself never imports a repo
 // file. That graph would make pm large and reload it on every edit there.
+// The answer names the paths it read (`inputs`) and their stamp, so pm runs
+// the child again only once a stat of one of them moved.
 //
-//   bun pm-config.ts <root>   prints { index, processes, errors } as json on stdout
+//   bun pm-config.ts <root>   prints a PmConfig as json on stdout
 import { homedir } from 'os'
-import type { GlobalProcessDecl } from './global-units.ts'
+import { houseInputs, stampOf, type PmConfig } from './pm-inputs.ts'
 
-export type PmConfig = {
-    /** the house wiki index the repo includes, null when it includes none */
-    index: string | null
-    processes: GlobalProcessDecl[]
-    /** the unit files that would not load */
-    errors: string[]
-}
+export type { PmConfig }
 
 if (import.meta.main) {
     const root = process.argv[2]
@@ -22,14 +18,22 @@ if (import.meta.main) {
         process.exit(2)
     }
     const { houseRepos } = await import('../serve/project-gutter.ts')
+    const { repoUnitFiles } = await import('../core/discover-checks.ts')
     const house = houseRepos(root, homedir())
-    const out: PmConfig = { index: house.index, processes: [], errors: [] }
+    const repos = house.index == null ? [] : house.repos
+    const files = new Map<string, string[]>()
+    const inputs = houseInputs(house.home, house.index, repos.map((r) => r.path), (r, dirs) => {
+        const f = repoUnitFiles(r, dirs)
+        files.set(r, f)
+        return f
+    })
+    const out: PmConfig = { index: house.index, processes: [], errors: [], inputs, stamp: stampOf(inputs) }
     if (house.index != null) {
         // a unit file imports the lib by name: this copy, like the daemon's
         const { useOneLib } = await import('../core/one-lib.ts')
         const { scanGlobalUnits } = await import('./global-units.ts')
         useOneLib()
-        const u = await scanGlobalUnits(house.repos.map((r) => ({ name: r.name, path: r.path })))
+        const u = await scanGlobalUnits(repos.map((r) => ({ name: r.name, path: r.path })), { files: (r) => files.get(r) ?? [] })
         out.processes = u.processes
         out.errors = u.errors
     }

package/src/home/pm-inputs.ts

@@ -0,0 +1,76 @@
+// what pm stamps to know whether the house side moved, without running the
+// child that reads it (pm-config.ts): the answer's shape, the paths it
+// depends on, and their stamp. Imports nothing a repo file does, so pm's own
+// graph stays small.
+import { readdirSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { UNIT_SUFFIX } from '../core/check-file-names.ts'
+import type { GlobalProcessDecl } from './global-units.ts'
+
+export type PmConfig = {
+    /** the house wiki index the repo includes, null when it includes none */
+    index: string | null
+    processes: GlobalProcessDecl[]
+    /** the unit files that would not load */
+    errors: string[]
+    /** every path whose stat can change this answer (houseInputs) */
+    inputs: string[]
+    /** stampOf(inputs), taken before the unit files were imported */
+    stamp: string
+}
+
+/** the files a repo carries its includes in. Here, not in project-gutter.ts
+ *  which reads them, so pm stamps them without loading that graph */
+export const CLAUDE_FILES = ['CLAUDE.md', 'CLAUDE.local.md']
+
+/** what the answer depends on, as paths to stat: the dir holding the repos
+ *  (a repo added or removed), every sibling's CLAUDE files (a repo starting
+ *  to include the house), the index, each house repo's config (archived),
+ *  and every dir and unit file the unit walk read. A helper a unit file
+ *  imports is not in it: an edit there shows once the unit file moves */
+export function houseInputs(home: string, index: string | null, repos: string[], unitFiles: (root: string, dirs: string[]) => string[]): string[] {
+    const parent = dirname(home)
+    const out = [parent]
+    let names: string[] = []
+    try { names = readdirSync(parent) } catch { /* the stat of parent says when it appears */ }
+    for (const n of names.sort()) if (!n.startsWith('.')) for (const f of CLAUDE_FILES) out.push(join(parent, n, f))
+    if (index != null) out.push(index)
+    for (const r of repos) {
+        out.push(join(r, 'repo.config.ts'))
+        const dirs: string[] = []
+        const files = unitFiles(r, dirs)
+        out.push(...dirs, ...files)
+    }
+    return out
+}
+
+/** a dir's entries that can change the answer: its subdirs and its unit
+ *  files. A temp file coming and going moves the dir's mtime, not this */
+const listings = new Map<string, { mtime: number; names: string }>()
+function dirNames(dir: string, mtime: number): string {
+    const hit = listings.get(dir)
+    if (hit?.mtime === mtime) return hit.names
+    let names = ''
+    try {
+        names = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.name.startsWith('.') && (e.isDirectory() || e.name.endsWith(UNIT_SUFFIX)))
+            .map((e) => e.name)
+            .sort()
+            .join('/')
+    } catch { /* gone between the stat and the read: the next stat says so */ }
+    listings.set(dir, { mtime, names })
+    return names
+}
+
+/** every path as one string: a file by its mtime, a dir by the entries
+ *  that matter (read again only when its mtime moved), -1 when missing */
+export function stampOf(paths: string[]): string {
+    return paths.map((p) => {
+        try {
+            const st = statSync(p)
+            return st.isDirectory() ? dirNames(p, st.mtimeMs) : st.mtimeMs
+        } catch {
+            return -1
+        }
+    }).join(',')
+}