rvlib-shipkit 1.1.0 → 1.2.0

package/src/home/resources.ts

@@ -0,0 +1,338 @@
+// the machine's global processes (ComfyUI, a TTS server, an app panel), each
+// declared once in a repo's `<name>.shipkit.ts` as `globalProcess({...})`
+// (shipkit-files.ts) and owned by pm: a switch, a restart, its log, its
+// action buttons, and for an app the window that opens on its url.
+//
+// two kinds: with no `down`, the command IS the service, supervised like a
+// hub (restarted on a crash, signalled on stop). With `down`, the command is
+// a bring-up that exits (an idempotent ladder script), `down` its reverse,
+// and the probe is the only truth.
+import { mkdirSync, openSync, closeSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import type { GlobalProcessDecl } from './global-units.ts'
+import { Proc, realDeps, tailLines, type ProcStatus, type SuperviseDeps } from './supervise.ts'
+import { resourceLog, resourcePid } from './home-paths.ts'
+import { groupOf, localPort, portHolders } from '../core/port-holders.ts'
+
+export type ResourceView = {
+    id: string
+    label: string
+    description: string | null
+    where: string | null
+    status: ProcStatus
+    /** what the owner last asked for */
+    want: 'up' | 'down'
+    note: string | null
+    /** a bring-up can always be taken down; a kept process not started by pm cannot */
+    canStop: boolean
+    /** it runs, started outside the supervisor: whether pm can stop that copy
+     *  and start its own (and why not). null while there is nothing to take over */
+    takeOver: { ok: true } | { ok: false; why: string } | null
+    /** the last lines of its log, what the page shows on hover */
+    tail: string[]
+    /** the repo and the file that declare it */
+    repo: string
+    file: string
+    url: string | null
+    /** opens as a shipkit app window on its url */
+    app: boolean
+    actions: { id: string; label: string }[]
+    /** the action running now, or null */
+    running: string | null
+}
+
+export type HttpProbe = (url: string) => Promise<boolean>
+
+export const probeUrl: HttpProbe = async (url) => {
+    try {
+        const r = await fetch(url, { signal: AbortSignal.timeout(2_000) })
+        return r.ok
+    } catch {
+        return false
+    }
+}
+
+/** runs a command to its end, output appended to the log; the exit code */
+export type RunOnce = (cmd: string[], cwd: string, log: string) => Promise<number>
+
+export const runOnce: RunOnce = async (cmd, cwd, log) => {
+    mkdirSync(dirname(log), { recursive: true })
+    const fd = openSync(log, 'a')
+    try {
+        const p = Bun.spawn(cmd, { cwd, stdio: ['ignore', fd, fd] })
+        return await p.exited
+    } catch (e) {
+        throw new Error(`could not run ${cmd.join(' ')}: ${(e as Error).message}`)
+    } finally {
+        closeSync(fd)
+    }
+}
+
+/** opens a shipkit app window on a url; what it did lands in the log */
+export type OpenApp = (url: string, log: string) => void
+
+/** its own process: what building the app needs never loads in pm */
+const OPEN_APP = fileURLToPath(new URL('./open-app.ts', import.meta.url))
+
+const openApp: OpenApp = (url, log) => {
+    mkdirSync(dirname(log), { recursive: true })
+    const fd = openSync(log, 'a')
+    try {
+        Bun.spawn([process.execPath, OPEN_APP, url], { stdio: ['ignore', fd, fd] })
+    } finally {
+        closeSync(fd)
+    }
+}
+
+/** opens a url in the default browser; what it did lands in the log */
+export type Browse = (url: string, log: string) => void
+
+const browse: Browse = (url, log) => {
+    mkdirSync(dirname(log), { recursive: true })
+    const fd = openSync(log, 'a')
+    try {
+        const cmd = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url]
+        Bun.spawn(cmd, { stdio: ['ignore', fd, fd] })
+    } finally {
+        closeSync(fd)
+    }
+}
+
+/** the function action runner: imports the unit file, calls the action */
+const ACTION_RUNNER = fileURLToPath(new URL('./run-unit-action.ts', import.meta.url))
+
+export type ResourceOpts = {
+    probe?: HttpProbe
+    run?: RunOnce
+    deps?: SuperviseDeps
+    /** the app window */
+    open?: OpenApp
+    /** the default browser */
+    browse?: Browse
+    /** the pids listening on a local port, and the process group of a pid */
+    holders?: (port: number) => number[]
+    groupOf?: (pid: number) => number | null
+    /** pm's own process group: never signalled by a take over */
+    ownGroup?: number
+    sleep?: (ms: number) => Promise<void>
+}
+
+/** where a process started elsewhere is found: the port of its url, else of its probe */
+const ownerPort = (d: GlobalProcessDecl): number | null => localPort(d.url) ?? localPort(d.probe)
+
+/** what pm's own group is, read once */
+let pmGroup: number | null | undefined
+
+/** one switchable process */
+export class Resource {
+    private proc: Proc | null = null
+    status: ProcStatus = 'down'
+    want: 'up' | 'down' = 'down'
+    note: string | null = null
+    running: string | null = null
+    /** how its last action ended, kept beside what the supervisor says */
+    private actionNote: string | null = null
+    private busy = false
+    /** the last bring-up exited non zero */
+    private failed = false
+    /** open it once it answers: in the default browser, or as an app window */
+    private openWhenUp: 'browser' | 'app' | null = null
+    readonly log: string
+
+    constructor(readonly decl: GlobalProcessDecl, dir: string, private o: ResourceOpts = {}) {
+        this.log = resourceLog(dir, decl.id)
+        if (decl.down == null)
+            this.proc = new Proc({ id: decl.id, cmd: decl.cmd, cwd: decl.cwd, log: this.log, pidKey: resourcePid(dir, decl.id), probe: decl.probe == null ? undefined : () => this.probe() }, o.deps ?? realDeps)
+    }
+
+    private probe(): Promise<boolean> {
+        return this.decl.probe == null ? Promise.resolve(true) : (this.o.probe ?? probeUrl)(this.decl.probe)
+    }
+
+    get canStop(): boolean {
+        return this.proc == null || !this.proc.external
+    }
+
+    /** null while it is ours or not running; else whether it can be taken over */
+    get takeOverView(): ResourceView['takeOver'] {
+        if (this.proc == null || !this.proc.external) return null
+        if (ownerPort(this.decl) == null) return { ok: false, why: 'it declares no local url or probe with a port, so the process that runs it cannot be found: stop it where it was started' }
+        return { ok: true }
+    }
+
+    /** it runs, started elsewhere: stop that copy (the process group that
+     *  listens on its port, SIGTERM then SIGKILL after the grace) and start
+     *  the supervised one, in one go */
+    async takeOver(): Promise<void> {
+        const p = this.proc
+        const v = this.takeOverView
+        if (p == null || v == null) throw new Error(`${this.decl.id} does not run outside the supervisor: nothing to take over`)
+        if (!v.ok) throw new Error(`${this.decl.id}: ${v.why}`)
+        const port = ownerPort(this.decl)!
+        const owners = (this.o.holders ?? portHolders)(port).filter((pid) => pid !== process.pid)
+        if (owners.length === 0) throw new Error(`${this.decl.id} answers, but no process listens on port ${port}: nothing to stop`)
+        const own = this.o.ownGroup ?? (pmGroup === undefined ? (pmGroup = groupOf(process.pid)) : pmGroup)
+        const targets = [...new Set(owners.map((pid) => {
+            const g = (this.o.groupOf ?? groupOf)(pid)
+            // a group of one's own (pm's, a shell's login group) is never signalled whole
+            return g != null && g > 1 && g !== own ? g : pid
+        }))]
+        this.want = 'up'
+        this.openWhenUp = null
+        await p.takeOver(owners, targets, this.o.sleep ?? ((ms) => Bun.sleep(ms)))
+        await this.tick()
+    }
+
+    /** switch it on or off. The bring-up kind reports its command's failure */
+    async set(want: 'up' | 'down'): Promise<void> {
+        this.want = want
+        if (want === 'down') this.openWhenUp = null
+        if (this.proc != null) {
+            if (want === 'up') await this.proc.ensure()
+            else this.proc.stop()
+            await this.tick()
+            return
+        }
+        if (this.busy) return
+        const cmd = want === 'up' ? this.decl.cmd : this.decl.down!
+        this.busy = true
+        this.status = want === 'up' ? 'starting' : 'stopping'
+        this.note = null
+        this.failed = false
+        try {
+            const code = await (this.o.run ?? runOnce)(cmd, this.decl.cwd, this.log)
+            if (code !== 0) {
+                this.failed = true
+                this.note = `\`${cmd.join(' ')}\` exited ${code}: see the log`
+            }
+        } catch (e) {
+            this.failed = true
+            this.note = (e as Error).message
+        } finally {
+            this.busy = false
+        }
+        await this.tick()
+    }
+
+    async restart(): Promise<void> {
+        if (this.proc != null) {
+            this.want = 'up'
+            this.proc.restart()
+            await this.tick()
+            return
+        }
+        await this.set('down')
+        await this.set('up')
+    }
+
+    /** its url in the default browser, or as a shipkit app window (app:
+     *  true only): at once while it answers, else it starts and opens once
+     *  it does */
+    async open(how: 'browser' | 'app'): Promise<void> {
+        if (this.decl.url == null) throw new Error(`${this.decl.id} declares no url to open`)
+        if (how === 'app' && !this.decl.app) throw new Error(`${this.decl.id} does not declare app: true, so it has no app window: open it in the browser`)
+        if (this.status === 'up') {
+            this.show(how, this.decl.url)
+            return
+        }
+        this.openWhenUp = how
+        await this.set('up')
+    }
+
+    private show(how: 'browser' | 'app', url: string): void {
+        if (how === 'app') (this.o.open ?? openApp)(url, this.log)
+        else (this.o.browse ?? browse)(url, this.log)
+    }
+
+    /** one declared button. A function action runs in its own bun process
+     *  that imports the unit file */
+    async action(id: string): Promise<void> {
+        const a = this.decl.actions.find((x) => x.id === id)
+        if (a == null) throw new Error(`${this.decl.id} declares no action '${id}'`)
+        if (this.running != null) throw new Error(`${this.decl.id} is already running its action '${this.running}'`)
+        const cmd = a.cmd ?? [process.execPath, ACTION_RUNNER, join(this.decl.root, this.decl.file), id]
+        this.running = id
+        this.actionNote = null
+        try {
+            const code = await (this.o.run ?? runOnce)(cmd, this.decl.root, this.log)
+            this.actionNote = code === 0 ? `${a.label}: done` : `${a.label} exited ${code}: see the log`
+        } catch (e) {
+            this.actionNote = `${a.label}: ${(e as Error).message}`
+        } finally {
+            this.running = null
+        }
+        this.note = this.actionNote
+    }
+
+    async tick(): Promise<void> {
+        if (this.proc != null) {
+            await this.proc.tick()
+            this.status = this.proc.status
+            this.note = this.proc.note ?? this.actionNote
+            this.want = this.proc.want
+        } else if (!this.busy) {
+            const up = await this.probe()
+            this.status = up ? 'up' : this.failed && this.want === 'up' ? 'crashed' : 'down'
+        }
+        if (this.openWhenUp != null && this.status === 'up' && this.decl.url != null) {
+            const how = this.openWhenUp
+            this.openWhenUp = null
+            this.show(how, this.decl.url)
+        }
+    }
+
+    view(): ResourceView {
+        const d = this.decl
+        return {
+            id: d.id,
+            label: d.label,
+            description: d.description,
+            where: d.where,
+            status: this.status,
+            want: this.want,
+            note: this.note,
+            canStop: this.canStop,
+            takeOver: this.takeOverView,
+            tail: tailLines(this.log, 20),
+            repo: d.repo,
+            file: d.file,
+            url: d.url,
+            app: d.app,
+            actions: d.actions.map((a) => ({ id: a.id, label: a.label })),
+            running: this.running,
+        }
+    }
+}
+
+export class Resources {
+    list: Resource[]
+    /** the unit files that would not load, as pm last read them */
+    errors: string[] = []
+
+    constructor(decls: GlobalProcessDecl[], private dir: string, private o: ResourceOpts = {}) {
+        this.list = decls.map((d) => new Resource(d, dir, o))
+    }
+
+    /** the declarations as they are now: an unchanged one keeps its state, a
+     *  changed or new one starts from its pid record, a dropped one leaves
+     *  its process running for whoever declares it next */
+    sync(decls: GlobalProcessDecl[], errors: string[] = []): void {
+        const key = (d: GlobalProcessDecl): string => JSON.stringify(d)
+        const had = new Map(this.list.map((r) => [key(r.decl), r]))
+        this.list = decls.map((d) => had.get(key(d)) ?? new Resource(d, this.dir, this.o))
+        this.errors = errors
+    }
+
+    get(id: string): Resource | null {
+        return this.list.find((r) => r.decl.id === id) ?? null
+    }
+
+    async tick(): Promise<void> {
+        await Promise.all(this.list.map((r) => r.tick()))
+    }
+
+    views(): ResourceView[] {
+        return this.list.map((r) => r.view())
+    }
+}

package/src/home/run-daemon.ts

@@ -0,0 +1,137 @@
+// `shipkit daemon`: resolve what the home needs from the repo it runs in (the
+// house repos around it), and serve its api on the
+// internal port. A second launch sees the first and leaves. Every house repo's
+// hub runs in this process (hubs.ts), on this process's copy of the lib
+// (one-lib.ts). Every gate runs as a detached job it follows (core/jobs.ts), so
+// it runs with no bun watch and an edit of its own code restarts it in place
+// at once (lib-watch.ts): the new image follows the jobs still running. The
+// machine resources are pm's.
+import { fileURLToPath } from 'url'
+import { useOneLib } from '../core/one-lib.ts'
+import { reclaimPreviousImage } from '../core/instance.ts'
+import { reloadOnOwnCode } from './lib-watch.ts'
+import { loadHub } from '../serve/hub-runtime.ts'
+import { houseRepos } from '../serve/project-gutter.ts'
+import { projectGutter } from '../serve/project-gutter-route.ts'
+import { loadRepoConfig } from '../repo-config.ts'
+import { ensureIdentity } from '../core/identity.ts'
+import { homedir } from 'os'
+import { daemonPort, homeDir, homePort, homeUp, hubBase, WORKER_ENV } from './home-paths.ts'
+import { HomeState } from './home-state.ts'
+import { Hubs } from './hubs.ts'
+import { Planner } from '../plan/planner.ts'
+import { serveDaemon } from './serve-daemon.ts'
+import { startSweeps } from './machine-stores.ts'
+import { Widgets } from './widgets.ts'
+
+const CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+
+/** SHIPKIT_DAEMON_ONLY=a,b loads those house repos alone */
+const onlyRepos = (): Set<string> | undefined => {
+    const v = process.env.SHIPKIT_DAEMON_ONLY
+    return v == null || v.trim() === '' ? undefined : new Set(v.split(',').map((x) => x.trim()).filter((x) => x !== ''))
+}
+
+export type HomeIo = { print: (l: string) => void; printErr: (l: string) => void }
+
+export async function runDaemon(root: string, io: HomeIo, o: { port?: number } = {}): Promise<number> {
+    const own = o.port ?? daemonPort()
+    // the port a page reaches every hub on: the web's
+    const port = homePort()
+    const house = houseRepos(root, homedir())
+    if (house.index == null) {
+        io.printErr(`FAIL: ${root} includes no house wiki index in its CLAUDE.md, so the daemon has no repos to load. Run it from the repo that hosts the house wiki`)
+        return 1
+    }
+    // before the first repo config loads: every one of them, and every check
+    // file, then imports this copy of the lib
+    useOneLib()
+    // a process this one starts runs its gate and its hub in process
+    process.env[WORKER_ENV] = '1'
+    // a restart in place keeps the pid: the check children its previous
+    // image spawned are still running, and die here
+    // a bun watch over this process follows every repo config it loads, so
+    // one repo's edit would restart every hub and kill every gate
+    if (process.execArgv.includes('--watch') || process.execArgv.includes('--hot'))
+        io.printErr(`WARN the daemon runs under bun --watch, so an edit of any repo config restarts every hub. Run \`shipkit pm install\` again for an agent without it`)
+    const reclaimed = reclaimPreviousImage()
+    if (reclaimed.killed.length > 0) io.print(`ok: the daemon restarted in place: killed ${reclaimed.killed.length} check process(es) its previous image left running`)
+    const c = await loadRepoConfig(root)
+    const dir = homeDir()
+    const gutter = projectGutter({ root, warn: (l) => io.printErr(l) })
+    const names = new Set(house.repos.map((r) => r.name))
+    // the machine's one plan: every repo and check pair, ticked by the daemon
+    const plan = new Planner({ onError: (repo, e) => io.printErr(`WARN the plan of ${repo} broke: ${e.message}`) })
+    const hubs = new Hubs({
+        dir,
+        port,
+        // every repo carries its identity colours: the first load writes the
+        // missing key, one line, and leaves the commit to the repo (SK024)
+        prepare: async (repo, hubIo) => {
+            const r = await ensureIdentity(repo.path)
+            if (r.changed && r.id != null) hubIo.print(`ok: ${repo.name}'s repo.config.ts gets identity ${r.id.colorLight} / ${r.id.colorDark}, from ${r.from}`)
+            else if (r.refused != null) hubIo.print(`note: ${repo.name} has no identity colours: ${r.refused}`)
+        },
+        load: async (repo, hubIo, o) => {
+            const rt = await loadHub(repo.path, hubIo, {
+                base: hubBase(repo.name),
+                port,
+                projects: gutter,
+                plan,
+                planName: repo.name,
+                gateAtStart: false,
+                ownTimers: false,
+                fresh: o.fresh,
+                // every gate is a detached job: a reload of this process never kills one
+                jobs: { cli: CLI },
+                // a lane click of the live strip opens that repo's page, on the page's own origin
+                repoHub: async (other) => (names.has(other) ? `${hubBase(other)}/` : null),
+            })
+            hubIo.print(`${rt.name} hub → http://localhost:${port}${hubBase(repo.name)}/`)
+            return { ...rt, uses: rt.deps.uses ?? [] }
+        },
+    })
+    try {
+        const home = serveDaemon({
+            root,
+            name: c.name,
+            port,
+            daemonPort: own,
+            dir,
+            hubs,
+            state: new HomeState(dir),
+            gutter,
+            plan,
+            only: onlyRepos(),
+            widgets: new Widgets(),
+        })
+        io.print(`daemon → http://127.0.0.1:${home.server.port} (the page: http://localhost:${port})`)
+        // nothing grows unbound: every store of every repo it loads, and the
+        // machine's, swept on boot and hourly (core/retention.ts)
+        const only = onlyRepos()
+        const sweeps = startSweeps({ roots: () => house.repos.filter((r) => only == null || only.has(r.name)).map((r) => r.path), dir, printErr: io.printErr })
+        const code = reloadOnOwnCode({ role: 'daemon', entry: fileURLToPath(import.meta.url), busy: () => hubs.busy(), before: () => { sweeps.stop(); home.stop() }, io })
+        io.print(`  ${house.repos.length} repos, state in ${dir}, reloads on ${code.files} lib files`)
+        for (const sig of ['SIGINT', 'SIGTERM'] as const)
+            process.on(sig, () => {
+                // the repo processes it started keep running: they are their
+                // own process groups, and the next daemon adopts them
+                code.stop()
+                sweeps.stop()
+                home.stop()
+                process.exit(0)
+            })
+        await new Promise(() => {})
+        return 0
+    } catch (e) {
+        if (e instanceof Error && /in use|EADDRINUSE/.test(e.message)) {
+            if (await homeUp(own)) {
+                io.print(`daemon → http://127.0.0.1:${own} (already running)`)
+                return 0
+            }
+            io.printErr(`FAIL: port ${own} is taken by another process. Set SHIPKIT_DAEMON_PORT to a free one`)
+            return 1
+        }
+        throw e
+    }
+}

package/src/home/run-pm.ts

@@ -0,0 +1,149 @@
+// `shipkit pm`: the one process launchd keeps alive. It runs the daemon and
+// the web as detached children, starts one again when it dies, owns the
+// machine's global processes, and serves its api on its own port. It restarts itself
+// in place on an edit of its own code, and adopts its children when it does.
+// It never loads the repo config itself (pm-config.ts), and it runs from this
+// file, never from cli.ts (execPm): cli.ts loads every command, about 170 MB
+// against pm's own 20.
+import { fileURLToPath } from 'url'
+import { daemonPort, homeDir, homePort, homeUp, homeUrl, pmPort, pmUp, WORKER_ENV } from './home-paths.ts'
+import { reloadOnOwnCode } from './lib-watch.ts'
+import { Pm, PM_TICK_MS, type Role } from './pm.ts'
+import { Resources } from './resources.ts'
+import type { HomeIo } from './run-daemon.ts'
+import type { PmConfig } from './pm-config.ts'
+
+const CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+const PM_CONFIG = fileURLToPath(new URL('./pm-config.ts', import.meta.url))
+
+const RUN_PM = fileURLToPath(import.meta.url)
+
+/** how often pm reads the house repos' global processes again */
+export const PM_RESCAN_MS = 15_000
+
+/** replace this process's image with pm run from this file: same pid, same
+ *  cwd, same env, none of cli.ts loaded. False when the runtime has no
+ *  execve, and the caller runs pm in process */
+export function execPm(o: { port?: number } = {}): boolean {
+    const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
+    if (typeof execve !== 'function') return false
+    const env = Object.fromEntries(Object.entries(process.env).filter((e): e is [string, string] => e[1] != null))
+    return execve.call(process, process.execPath, [process.execPath, RUN_PM, ...(o.port != null ? ['--port', String(o.port)] : [])], env)
+}
+
+/** the house repo's side of pm, read by a child process */
+export async function readPmConfig(root: string): Promise<PmConfig> {
+    const p = Bun.spawn([process.execPath, PM_CONFIG, root], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+    const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    if (code !== 0) throw new Error(`could not read the repo config of ${root} (exit ${code}): ${err.trim() || out.trim()}`)
+    return JSON.parse(out) as PmConfig
+}
+
+/** true when the role serves: the daemon as a home on its port, the web as
+ *  any http answer on the home port (it answers 502 while the daemon is down,
+ *  and still holds its port) */
+export async function roleAnswers(role: Role): Promise<boolean> {
+    if (role === 'daemon') return homeUp(daemonPort())
+    try {
+        await fetch(`${homeUrl(homePort())}/`, { signal: AbortSignal.timeout(400) })
+        return true
+    } catch {
+        return false
+    }
+}
+
+export async function runPm(root: string, io: HomeIo, o: { port?: number } = {}): Promise<number> {
+    const port = o.port ?? pmPort()
+    // every process pm starts runs its shipkit in process, and never starts pm
+    process.env[WORKER_ENV] = '1'
+    let c: PmConfig
+    try {
+        c = await readPmConfig(root)
+    } catch (e) {
+        io.printErr(`FAIL: ${(e as Error).message}`)
+        return 1
+    }
+    if (c.index == null) {
+        io.printErr(`FAIL: ${root} includes no house wiki index in its CLAUDE.md, so pm has no daemon to run. Run it from the repo that hosts the house wiki`)
+        return 1
+    }
+    if (await pmUp(port)) {
+        io.print(`pm → http://127.0.0.1:${port} (already running)`)
+        return 0
+    }
+    const dir = homeDir()
+    const pm = new Pm({
+        dir,
+        root,
+        cmd: (role) => [process.execPath, CLI, role],
+        probe: roleAnswers,
+        resources: new Resources(c.processes, dir),
+    })
+    let server: Bun.Server<unknown>
+    try {
+        server = Bun.serve({ port, hostname: '127.0.0.1', fetch: (req) => pm.handle(req) })
+    } catch (e) {
+        if (e instanceof Error && /in use|EADDRINUSE/.test(e.message)) {
+            io.printErr(`FAIL: port ${port} is taken by another process. Set SHIPKIT_PM_PORT to a free one`)
+            return 1
+        }
+        throw e
+    }
+    await pm.boot()
+    for (const p of pm.children.values()) {
+        const v = p.view()
+        io.print(`  ${v.id}: ${p.adopted ? 'adopted' : v.status}${v.pid != null ? ` pid ${v.pid}` : ''}${v.note != null ? ` (${v.note})` : ''}`)
+    }
+    pm.resources.errors = c.errors
+    for (const e of c.errors) io.printErr(`WARN ${e}`)
+    // a unit file added, edited or removed in any house repo: read again,
+    // in its child process, and the unchanged processes keep their state
+    let reading = false
+    const reread = setInterval(() => {
+        if (reading) return
+        reading = true
+        void readPmConfig(root)
+            .then((n) => pm.resources.sync(n.processes, n.errors))
+            .catch((e) => io.printErr(`WARN pm could not read the global processes again: ${(e as Error).message}`))
+            .finally(() => { reading = false })
+    }, PM_RESCAN_MS)
+    let ticking = false
+    const timer = setInterval(() => {
+        if (ticking) return
+        ticking = true
+        void pm.tick().catch((e) => io.printErr(`WARN the pm tick broke: ${(e as Error).message}`)).finally(() => { ticking = false })
+    }, PM_TICK_MS)
+    const code = reloadOnOwnCode({
+        role: 'pm',
+        entry: fileURLToPath(import.meta.url),
+        // the children keep running, and the next image adopts them
+        before: () => {
+            clearInterval(timer)
+            clearInterval(reread)
+            server.stop(true)
+        },
+        io,
+    })
+    io.print(`pm → http://127.0.0.1:${server.port} (the page: http://localhost:${homePort()}, the daemon: :${daemonPort()}), ${c.processes.length} global processes, logs in ${dir}, reloads on ${code.files} lib files`)
+    let stopping = false
+    for (const sig of ['SIGINT', 'SIGTERM'] as const)
+        process.on(sig, () => {
+            // a stop asked of pm stops its children; the global processes keep running,
+            // their own process groups, for the next pm to adopt
+            if (stopping) return
+            stopping = true
+            code.stop()
+            clearInterval(timer)
+            clearInterval(reread)
+            server.stop(true)
+            void pm.stopAll().finally(() => process.exit(0))
+        })
+    await new Promise(() => {})
+    return 0
+}
+
+if (import.meta.main) {
+    const i = process.argv.indexOf('--port')
+    const port = i < 0 ? undefined : Number(process.argv[i + 1])
+    process.exitCode = await runPm(process.cwd(), { print: (l) => console.log(l), printErr: (l) => console.error(l) }, { port })
+}

package/src/home/run-unit-action.ts

@@ -0,0 +1,25 @@
+// runs one function action of a global process, in its own bun process so a
+// slow or crashing action never touches pm:
+//
+//   bun run-unit-action.ts <unit file> <action id>
+//
+// the unit file imports the lib by name, so this copy is registered first.
+import type { GlobalProcessUnit } from '../shipkit-files.ts'
+
+if (import.meta.main) {
+    const [file, id] = process.argv.slice(2)
+    if (file == null || id == null) {
+        console.error('usage: bun run-unit-action.ts <unit file> <action id>')
+        process.exit(2)
+    }
+    const { useOneLib } = await import('../core/one-lib.ts')
+    useOneLib()
+    const u = ((await import(file)) as { default?: GlobalProcessUnit }).default
+    const run = u?.actions?.[id]?.run
+    if (run == null) {
+        console.error(`FAIL: ${file} has no function action '${id}'`)
+        process.exit(1)
+    }
+    console.log(`▶ ${u!.id}: ${u!.actions![id]!.label}`)
+    await run()
+}