rvlib-shipkit 1.2.0 → 1.3.0

package/src/home/activity-shape.ts

@@ -0,0 +1,135 @@
+// the activity page's shapes and its few pure rules, apart from the git
+// reader so the page bundle takes them without node's modules. The words
+// here are what the page and `shipkit cross-repo-activity` both print.
+import type { CheckState } from '../serve/project-gutter.ts'
+
+/** the windows the page offers, in minutes */
+export const WINDOW_MINUTES = [10, 30, 60, 180, 720, 1440, 4320, 10080] as const
+export const DEFAULT_MINUTES = 30
+/** the most commits the daemon lists per repo, and the most uncommitted paths it names */
+export const MAX_COMMITS = 100
+export const MAX_FILES = 80
+
+export type FileKind = 'staged' | 'modified' | 'untracked'
+
+export type ActivityCommit = {
+    sha: string
+    /** committer time, epoch ms */
+    at: number
+    title: string
+    author: string
+    /** the branch it sits on when it is not on the checked out one, else null */
+    branch: string | null
+    /** a remote holds it; false on a branch with no upstream */
+    pushed: boolean
+}
+
+export type ActivityRow = {
+    name: string
+    /** the checked out branch; null when detached (see `detached`) */
+    branch: string | null
+    /** the short sha HEAD sits on when detached */
+    detached: string | null
+    /** the upstream as configured, null when the branch has none */
+    upstream: string | null
+    /** the upstream is configured but no longer exists */
+    gone: boolean
+    /** commits ahead of and behind the upstream, null without one */
+    ahead: number | null
+    behind: number | null
+    counts: Record<FileKind, number>
+    /** the uncommitted paths, at most MAX_FILES; a path both staged and
+     *  modified is listed once, as modified */
+    files: { kind: FileKind; path: string }[]
+    /** in the window, newest first */
+    commits: ActivityCommit[]
+    /** HEAD's latest commit when nothing was committed in the window, shown
+     *  grey; null when the window holds a commit, or the repo has none */
+    last: ActivityCommit | null
+    /** its checks as its run record last saw them, only the ids it declares
+     *  today when that is known; null when shipkit never ran there */
+    status: CheckState
+    /** the checks behind a red or orange status, failing first: what the
+     *  status column lists on hover and on click */
+    failing?: StatusCheck[]
+    /** why git could not answer, else null */
+    error: string | null
+}
+
+/** one failing or warning check as the run record last saw it */
+export type StatusCheck = {
+    id: string
+    /** its title as the repo declares it, else its id */
+    title: string
+    status: 'fail' | 'warn'
+    /** when that outcome was recorded, epoch ms */
+    at: number | null
+    /** the first line it printed about the problem, '' when it printed none */
+    line: string
+}
+
+export type ActivityAnswer = { now: number; minutes: number; rows: ActivityRow[]; ms: number }
+
+export type ActivityRepo = { name: string; path: string }
+
+/** the window a request names, when it is one the page offers */
+export function windowMinutes(v: string | null): number {
+    const n = Number(v)
+    return (WINDOW_MINUTES as readonly number[]).includes(n) ? n : DEFAULT_MINUTES
+}
+
+/** every house repo ships from main: shown green, any other orange, a
+ *  leftover master included so the repo still to rename stands out */
+export const isMainBranch = (b: string | null): boolean => b === 'main'
+
+/** nothing committed in the window and nothing uncommitted: it sits below the busy repos */
+export const idleRow = (r: ActivityRow): boolean =>
+    r.error == null && r.commits.length === 0 && r.counts.staged + r.counts.modified + r.counts.untracked === 0
+
+/** the most commits a repo shows: a number from CAP_MIN to CAP_MAX */
+export const CAP_MIN = 1
+export const CAP_MAX = 15
+export const DEFAULT_CAP = 3
+
+/** a window's label on the toggle: `10m`, `3h`, `3d` */
+export const windowWords = (m: number): string => (m < 60 ? `${m}m` : m < 4320 ? `${m / 60}h` : `${m / 1440}d`)
+
+/** a typed cap, as a whole number in CAP_MIN..CAP_MAX; the default when it is no number */
+export function clampCap(v: unknown): number {
+    const n = Math.round(Number(v))
+    return Number.isFinite(n) && String(v).trim() !== '' ? Math.min(CAP_MAX, Math.max(CAP_MIN, n)) : DEFAULT_CAP
+}
+
+/** an age in one short unit: `now`, `4m`, `2h`, `3d` */
+export function ageShort(at: number, now: number): string {
+    const s = Math.max(0, Math.round((now - at) / 1000))
+    if (s < 60) return 'now'
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** the uncommitted work in one line: `3 modified, 1 untracked`; '' when clean */
+export function dirtWords(r: ActivityRow): string {
+    const c = r.counts
+    return [c.staged > 0 ? `${c.staged} staged` : '', c.modified > 0 ? `${c.modified} modified` : '', c.untracked > 0 ? `${c.untracked} untracked` : '']
+        .filter((x) => x !== '')
+        .join(', ')
+}
+
+/** where the branch stands against its upstream, for the branch's hover */
+export function upstreamWords(r: ActivityRow): string {
+    if (r.upstream == null) return 'no upstream: nothing on this branch is pushed'
+    if (r.gone) return `${r.upstream} is gone`
+    const a = r.ahead ?? 0
+    const b = r.behind ?? 0
+    if (a === 0 && b === 0) return `even with ${r.upstream}`
+    return [a > 0 ? `${a} unpushed` : '', b > 0 ? `${b} behind` : ''].filter((x) => x !== '').join(', ') + ` against ${r.upstream}`
+}
+
+/** the uncommitted paths, one per line, for the hover */
+export const filesWords = (r: ActivityRow): string => {
+    const mark = { staged: 'S', modified: 'M', untracked: '?' } as const
+    const shown = r.files.map((f) => `${mark[f.kind]} ${f.path}`)
+    return (r.files.length >= MAX_FILES ? [...shown, '…'] : shown).join('\n')
+}

package/src/home/activity.ts

@@ -0,0 +1,249 @@
+// the activity page's data: for every house repo, its branch, how far it is
+// from its upstream, what it holds uncommitted and what it committed in a
+// window. Plain local git, never a fetch, so "ahead" is against the upstream
+// as this disk last saw it.
+//
+// the one constraint a reader breaks first: this runs only when the page asks
+// (no tick). A pass reads ACTIVITY_CONCURRENCY repos at once, and an answer is
+// shared for ACTIVITY_TTL_MS per window, never served past it, so a page left
+// open costs about one pass a minute however many tabs show it, and a closed
+// one costs nothing.
+import { gitBin } from '../core/git-bin.ts'
+import { readLastStatusReadonly } from '../ledger/run-log.ts'
+import { checkStateOf, recordOf } from '../serve/project-gutter.ts'
+import type { Line } from '../core/wire.ts'
+import { MAX_COMMITS, MAX_FILES, type ActivityAnswer, type ActivityCommit, type ActivityRepo, type ActivityRow, type FileKind, type StatusCheck } from './activity-shape.ts'
+
+export * from './activity-shape.ts'
+
+/** how long one window's answer is shared between readers: half the page's
+ *  60s cadence, so tabs a few seconds apart share a pass and none is shown
+ *  an answer older than this */
+export const ACTIVITY_TTL_MS = 30_000
+
+export type ParsedStatus = Pick<ActivityRow, 'branch' | 'detached' | 'upstream' | 'gone' | 'ahead' | 'behind' | 'counts' | 'files'>
+
+/** `git status --porcelain=v2 --branch`, read */
+export function parseStatus(text: string): ParsedStatus {
+    const out: ParsedStatus = { branch: null, detached: null, upstream: null, gone: false, ahead: null, behind: null, counts: { staged: 0, modified: 0, untracked: 0 }, files: [] }
+    let oid = ''
+    const add = (kind: FileKind, path: string): void => {
+        if (out.files.length < MAX_FILES) out.files.push({ kind, path })
+    }
+    for (const line of text.split('\n')) {
+        if (line.startsWith('# branch.oid ')) oid = line.slice(13)
+        else if (line.startsWith('# branch.head ')) {
+            const h = line.slice(14)
+            if (h !== '(detached)') out.branch = h
+        } else if (line.startsWith('# branch.upstream ')) out.upstream = line.slice(18)
+        else if (line.startsWith('# branch.ab ')) {
+            const m = /^\+(\d+) -(\d+)$/.exec(line.slice(12))
+            if (m != null) {
+                out.ahead = Number(m[1])
+                out.behind = Number(m[2])
+            }
+        } else if (line.startsWith('1 ') || line.startsWith('2 ')) {
+            // `1 XY sub mH mI mW hH hI path`, `2 … Xscore path<TAB>orig`
+            const f = line.split(' ')
+            const xy = f[1] ?? '..'
+            const path = f.slice(line.startsWith('1 ') ? 8 : 9).join(' ').split('\t')[0]!
+            if (xy[0] !== '.') out.counts.staged++
+            if (xy[1] !== '.') out.counts.modified++
+            add(xy[1] !== '.' ? 'modified' : 'staged', path)
+        } else if (line.startsWith('u ')) {
+            out.counts.modified++
+            add('modified', line.split(' ').slice(10).join(' '))
+        } else if (line.startsWith('? ')) {
+            out.counts.untracked++
+            add('untracked', line.slice(2))
+        }
+    }
+    if (out.branch == null && oid !== '' && oid !== '(initial)') out.detached = oid.slice(0, 7)
+    if (out.upstream != null && out.ahead == null) out.gone = true
+    return out
+}
+
+const SEP = '\x1f'
+const END = '\x1e'
+const FORMAT = `--format=%h${SEP}%ct${SEP}%an${SEP}%S${SEP}%s${SEP}%H${END}`
+
+/** `git log` in FORMAT, read; `unpushed` holds the full shas no remote has */
+export function parseLog(text: string, onHead: boolean, unpushed: (full: string) => boolean = () => false): ActivityCommit[] {
+    const out: ActivityCommit[] = []
+    for (const rec of text.split(END)) {
+        const f = rec.replace(/^\n/, '').split(SEP)
+        if (f.length < 6) continue
+        const src = f[3]!.replace(/^refs\/heads\//, '')
+        out.push({ sha: f[0]!, at: Number(f[1]) * 1000, author: f[2]!, branch: onHead || src === '' ? null : src, title: f[4]!, pushed: !unpushed(f[5]!) })
+    }
+    return out
+}
+
+async function git(cwd: string, args: string[]): Promise<{ code: number; out: string; err: string }> {
+    // no optional locks: a look never takes the index lock an agent's commit needs
+    const p = Bun.spawn([gitBin(), ...args], { cwd, stdout: 'pipe', stderr: 'pipe', env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })
+    const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    return { code, out, err: err.trim() }
+}
+
+/** which check ids a repo declares today: the daemon's plan; null = not
+ *  known, every recorded check counts */
+export type Declared = (name: string) => ReadonlySet<string> | null
+
+/** each declared check's title by id; null = not known, the id stands in */
+export type Titles = (name: string) => ReadonlyMap<string, string> | null
+
+/** the line a check printed about its problem: its first line of the same
+ *  weight (a fail for a failure, a warning for a warning), else its first
+ *  line that is not a pass, without the id its line leads with */
+export function findingOf(lines: string, status: 'fail' | 'warn', id: string): string {
+    let parsed: Line[]
+    try {
+        parsed = JSON.parse(lines) as Line[]
+    } catch {
+        return ''
+    }
+    if (!Array.isArray(parsed)) return ''
+    const kinds = status === 'fail' ? ['fail', 'fix-fail'] : ['warn', 'fix-warn']
+    const hit = parsed.find((l) => kinds.includes(l.kind)) ?? parsed.find((l) => l.kind !== 'ok' && l.kind !== 'skip')
+    if (hit == null) return ''
+    const t = hit.text.trim()
+    // `[ID] text`, and a runner line's `ID — text`: the list names the id already
+    for (const lead of [`[${id}]`, `${id} —`]) if (t.startsWith(lead)) return t.slice(lead.length).trim()
+    return t
+}
+
+/** a repo's checks as its run record last saw them, counted over what it
+ *  declares, and the failing and warning ones with what each said */
+export function statusOf(repo: ActivityRepo, declared: Declared | null = null, titles: Titles | null = null): Pick<ActivityRow, 'status' | 'failing'> {
+    const record = recordOf(repo.path)
+    if (record == null) return { status: null, failing: [] }
+    const rows = readLastStatusReadonly(record, { lines: true })
+    const status = checkStateOf(rows, declared?.(repo.name) ?? null)
+    if (status == null) return { status, failing: [] }
+    const byId = new Map(rows.map((r) => [r.id, r]))
+    const named = titles?.(repo.name) ?? null
+    const one = (id: string, st: 'fail' | 'warn'): StatusCheck => {
+        const r = byId.get(id)
+        return { id, title: named?.get(id) ?? id, status: st, at: status.since[id] ?? null, line: r == null ? '' : findingOf(r.lines, st, id) }
+    }
+    return { status, failing: [...status.reds.map((id) => one(id, 'fail')), ...status.warns.map((id) => one(id, 'warn'))] }
+}
+
+/** one repo, from `since` (epoch ms) to now */
+export async function repoActivity(repo: ActivityRepo, since: number, declared: Declared | null = null, titles: Titles | null = null): Promise<ActivityRow> {
+    const empty = parseStatus('')
+    const row: ActivityRow = { name: repo.name, ...empty, commits: [], last: null, ...statusOf(repo, declared, titles), error: null }
+    try {
+        const iso = new Date(since).toISOString()
+        const range = [`--since=${iso}`, `--max-count=${MAX_COMMITS}`, '--no-show-signature', FORMAT]
+        // every ask that needs no other answer goes at once: git calls are
+        // ~5ms each but queue behind a busy daemon, so waiting for them one
+        // by one multiplies the wait. The upstream diff and the last commit
+        // are cheap enough to ask even when the answer goes unused
+        const [st, up, head, refs, one] = await Promise.all([
+            git(repo.path, ['status', '--porcelain=v2', '--branch']),
+            git(repo.path, ['rev-list', `--max-count=${MAX_COMMITS}`, '@{upstream}..HEAD']),
+            // a repo with no commit yet has no HEAD to walk: nothing committed
+            git(repo.path, ['log', ...range, 'HEAD']),
+            // the other local branches (an agent's worktree) whose tip moved in
+            // the window, minus what HEAD has: a repo with hundreds of branches
+            // walks only the few that moved
+            git(repo.path, ['for-each-ref', '--format=%(refname:short)%09%(committerdate:unix)%09%(upstream:short)%09%(upstream:track)', 'refs/heads']),
+            git(repo.path, ['log', '-1', '--no-show-signature', FORMAT, 'HEAD']),
+        ])
+        if (st.code !== 0) return { ...row, error: st.err || `git status exited ${st.code}` }
+        Object.assign(row, parseStatus(st.out))
+        // HEAD's unpushed commits: all of them without an upstream, else the
+        // `ahead` ones
+        const headAway = row.upstream == null || row.gone
+        const away = !headAway && (row.ahead ?? 0) > 0 && up.code === 0 ? new Set(up.out.split('\n').filter((l) => l !== '')) : new Set<string>()
+        const own = head.code === 0 ? parseLog(head.out, true, (h) => headAway || away.has(h)) : []
+        const moved = (refs.code === 0 ? refs.out.split('\n') : [])
+            .map((l) => l.split('\t'))
+            .filter((f) => f.length >= 2 && f[0] !== row.branch && Number(f[1]) * 1000 >= since)
+            // an upstream that is gone holds nothing
+            .map((f) => (f[3] === '[gone]' ? [f[0]!, f[1]!, ''] : f))
+        let other: ActivityCommit[] = []
+        if (moved.length > 0) {
+            const side = await git(repo.path, ['log', ...range, '--source', ...moved.map((f) => `refs/heads/${f[0]}`), '--not', 'HEAD', '--'])
+            // a side branch's commit is pushed once its own upstream holds it;
+            // on a failed ask every one reads unpushed, never pushed
+            const tracked = moved.filter((f) => (f[2] ?? '') !== '')
+            let sideAway = new Set<string>()
+            if (tracked.length > 0) {
+                const r = await git(repo.path, ['rev-list', `--since=${iso}`, ...tracked.map((f) => `refs/heads/${f[0]}`), '--not', ...tracked.map((f) => f[2]!), '--'])
+                if (r.code === 0) sideAway = new Set(r.out.split('\n').filter((l) => l !== ''))
+                else sideAway = new Set(['*'])
+            }
+            const untracked = new Set(moved.filter((f) => (f[2] ?? '') === '').map((f) => f[0]!))
+            other = side.code === 0 ? parseLog(side.out, false, (h) => sideAway.has('*') || sideAway.has(h)).map((c) => (c.branch != null && untracked.has(c.branch) ? { ...c, pushed: false } : c)) : []
+        }
+        row.commits = [...own, ...other].sort((a, b) => b.at - a.at).slice(0, MAX_COMMITS)
+        // an empty window still says what came last on HEAD
+        if (row.commits.length === 0) {
+            row.last = one.code === 0 ? parseLog(one.out, true, (h) => headAway || away.has(h))[0] ?? null : null
+        }
+        return row
+    } catch (e) {
+        return { ...row, error: (e as Error).message }
+    }
+}
+
+/** how many repos a pass reads at once: five git calls each, so a pass
+ *  never has more than 30 git processes alive */
+export const ACTIVITY_CONCURRENCY = 6
+
+/** every repo, ACTIVITY_CONCURRENCY at a time, rows in the order given.
+ *  THE computation: the daemon's route and `shipkit cross-repo-activity`
+ *  both call it, and only render it differently */
+export async function activityOf(repos: ActivityRepo[], minutes: number, now = Date.now(), declared: Declared | null = null, titles: Titles | null = null): Promise<ActivityAnswer> {
+    const t0 = performance.now()
+    const rows: ActivityRow[] = new Array(repos.length)
+    let next = 0
+    const worker = async (): Promise<void> => {
+        while (next < repos.length) {
+            const i = next++
+            rows[i] = await repoActivity(repos[i]!, now - minutes * 60_000, declared, titles)
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(ACTIVITY_CONCURRENCY, repos.length) }, worker))
+    return { now, minutes, rows, ms: Math.round(performance.now() - t0) }
+}
+
+/** one answer per window, shared for ttlMs. Past it a read waits for a new
+ *  pass: an old answer is never served as current. Callers during a pass
+ *  share it. */
+export class ActivityCache {
+    private kept = new Map<number, ActivityAnswer>()
+    private running = new Map<number, Promise<ActivityAnswer>>()
+    private ttlMs: number
+    private now: () => number
+    private declared: Declared | null
+    private titles: Titles | null
+
+    constructor(o: { ttlMs?: number; now?: () => number; declared?: Declared; titles?: Titles } = {}) {
+        this.ttlMs = o.ttlMs ?? ACTIVITY_TTL_MS
+        this.now = o.now ?? Date.now
+        this.declared = o.declared ?? null
+        this.titles = o.titles ?? null
+    }
+
+    private pass(repos: ActivityRepo[], minutes: number): Promise<ActivityAnswer> {
+        const going = this.running.get(minutes)
+        if (going != null) return going
+        const p = activityOf(repos, minutes, this.now(), this.declared, this.titles)
+            .then((a) => { this.kept.set(minutes, a); return a })
+            .finally(() => this.running.delete(minutes))
+        this.running.set(minutes, p)
+        return p
+    }
+
+    /** the kept answer while it is younger than the ttl, else a new pass.
+     *  `fresh` always waits for a pass: the page's refresh button */
+    get(repos: ActivityRepo[], minutes: number, o: { fresh?: boolean } = {}): Promise<ActivityAnswer> {
+        const k = this.kept.get(minutes)
+        if (k == null || o.fresh === true || this.now() - k.now >= this.ttlMs) return this.pass(repos, minutes)
+        return Promise.resolve(k)
+    }
+}

package/src/home/global-units.ts

@@ -21,7 +21,8 @@ export type GlobalProcessDecl = {
     cwd: string
     url: string | null
     probe: string | null
-    app: boolean
+    /** as declared: an emoji, or an image path relative to root */
+    icon: string | null
     actions: ActionDecl[]
     /** the repo that declares it, and the file, repo-relative */
     repo: string
@@ -51,7 +52,7 @@ export function toDecl(u: GlobalProcessUnit, repo: RepoRef, file: string): Globa
         cwd: resolve(repo.path, u.cwd ?? '.'),
         url: u.url ?? null,
         probe: u.probe ?? u.url ?? null,
-        app: u.app === true,
+        icon: u.icon ?? null,
         actions: Object.entries(u.actions ?? {}).map(([id, a]) => ({ id, label: a.label, cmd: a.cmd ?? null })),
         repo: repo.name,
         root: repo.path,

package/src/home/home-routes.ts

@@ -16,6 +16,9 @@ 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 { HouseRuns } from '../serve/house-runs.ts'
+import type { HouseView } from '../ledger/house-runs.ts'
 
 /** how often the daemon looks at every repo */
 export const TICK_MS = 2_000
@@ -76,10 +79,13 @@ export const runModernize = async (repo: WiredRepo, root: string, log: string):
     }
 }
 
-/** active = an agent works in it, VS Code has it open, or it is flagged by hand */
-export function activeSet(rows: ProjectRow[], flagged: string[]): Set<string> {
+/** active = an agent works in it, VS Code has it open, or it is flagged by
+ *  hand. The house repo is active whenever any repo is: its checks serve
+ *  every repo (a login, a shared key), so they follow the machine's work */
+export function activeSet(rows: ProjectRow[], flagged: string[], house?: string): Set<string> {
     const out = new Set(flagged)
     for (const r of rows) if ((r.sessions != null && r.sessions > 0) || r.vscode === true) out.add(r.name)
+    if (house != null && out.size > 0) out.add(house)
     return out
 }
 
@@ -87,13 +93,24 @@ export function activeSet(rows: ProjectRow[], flagged: string[]): Set<string> {
 export type WidgetsAnswer = { widgets: WidgetView[]; errors: string[] }
 
 /** the planned page's data: every row of the machine's plan */
-export type PlannedAnswer = { now: number; rows: PlanRow[]; errors: { repo: string; error: string }[]; running: boolean }
+export type PlannedAnswer = {
+    now: number
+    rows: PlanRow[]
+    errors: { repo: string; error: string }[]
+    running: boolean
+    /** what holds work back, one line each (Planner.held) */
+    held: string[]
+}
 
 export function homeRoutes(d: HomeDeps) {
     let repos: WiredRepo[] = []
     let rows: ProjectRow[] = []
     const modernizing = new Map<string, ModernizeView & { log: string }>()
+    // read only while the activity page asks, never on the tick
+    const activity = new ActivityCache({ declared: (name) => d.plan?.declared(name) ?? null, titles: (name) => d.plan?.titles(name) ?? null })
     const modernizeLog = (repo: string): string => join(d.dir, 'modernize', `${repo}.log`)
+    // the dock: every loaded repo's recent runs, read only while a page asks
+    const house = new HouseRuns(() => repos)
 
     async function refresh(): Promise<void> {
         const a = await d.gutter.answer()
@@ -107,7 +124,7 @@ export function homeRoutes(d: HomeDeps) {
 
     async function tick(): Promise<void> {
         await refresh()
-        active = activeSet(rows, d.state.data.active)
+        active = activeSet(rows, d.state.data.active, rows.find((r) => r.path === d.root)?.name ?? d.name)
         // the plan's clock: one look per tick, and it starts at most one batch
         d.plan?.tick()
         // a widget render never holds the tick back
@@ -148,9 +165,19 @@ export function homeRoutes(d: HomeDeps) {
         }
         if (path === '/api/home/planned.json') {
             if (repos.length === 0) await refresh()
-            const out: PlannedAnswer = { now: Date.now(), rows: d.plan?.rows() ?? [], errors: d.plan?.errors() ?? [], running: d.plan?.busy() === true }
+            const out: PlannedAnswer = { now: Date.now(), rows: d.plan?.rows() ?? [], errors: d.plan?.errors() ?? [], running: d.plan?.busy() === true, held: d.plan?.held() ?? [] }
             return Response.json(out)
         }
+        if (path === '/api/home/activity.json') {
+            if (repos.length === 0) await refresh()
+            const q = new URL(req.url).searchParams
+            return Response.json(await activity.get(repos, windowMinutes(q.get('m')), { fresh: q.get('fresh') === '1' }))
+        }
+        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 ?? [] }
             return Response.json(out)

package/src/home/pm.ts

@@ -7,9 +7,12 @@
 // the one constraint a reader breaks first: pm never takes a child down with
 // it. A reload of pm, or pm killed, leaves both running, and the next pm
 // adopts them from their pid records. Only a stop asked of pm stops them.
+import { existsSync } from 'fs'
+import { join } from 'path'
 import { LIB_VERSION } from '../core/lib-version.ts'
+import { iconImageType } from '../shipkit-files.ts'
 import { sameOrigin } from '../serve/same-origin.ts'
-import { childLog, childPid } from './home-paths.ts'
+import { childLog, childPid, daemonPort, homePort, pmLog, pmPort } from './home-paths.ts'
 import type { Resources, ResourceView } from './resources.ts'
 import { capLog, Proc, realDeps, tailLines, type ProcView, type SuperviseDeps } from './supervise.ts'
 
@@ -21,10 +24,22 @@ export const PM_TICK_MS = 2_000
 
 export type ChildView = ProcView & { tail: string[] }
 
+/** where pm, the daemon and the web listen */
+export type CorePorts = { pm: number; daemon: number; web: number }
+
+/** how many log lines each of shipkit's own processes hands the page */
+const CORE_TAIL = 20
+
 export type PmAnswer = {
     pm: 'shipkit-pm'
     pid: number
+    /** epoch ms this pm started; absent from a pm older than the field */
+    since?: number
     version: string
+    /** where pm and its children listen; absent from a pm older than the field */
+    ports?: CorePorts
+    /** the last lines of pm's own log; absent from a pm older than the field */
+    tail?: string[]
     children: ChildView[]
     resources: ResourceView[]
     /** the `.shipkit.ts` files that would not load, as pm last read them */
@@ -35,6 +50,8 @@ export type PmDeps = {
     dir: string
     /** the house repo: where the children run */
     root: string
+    /** the port pm serves on (default: SHIPKIT_PM_PORT, else 4797) */
+    port?: number
     /** the command that runs one role, e.g. [bun, cli.ts, 'daemon'] */
     cmd: (role: Role) => string[]
     /** true once the role serves */
@@ -50,6 +67,7 @@ const WEB_ANSWER_MS = 200
 
 export class Pm {
     readonly children: Map<Role, Proc>
+    private readonly startedAt = Date.now()
 
     constructor(private d: PmDeps) {
         this.children = new Map(ROLES.map((role) => [role, new Proc({
@@ -90,14 +108,30 @@ export class Pm {
     }
 
     answer(): PmAnswer {
-        const children = [...this.children.values()].map((p) => ({ ...p.view(), tail: p.status === 'up' ? [] : tailLines(p.spec.log, 20) }))
-        return { pm: 'shipkit-pm', pid: process.pid, version: LIB_VERSION, children, resources: this.d.resources.views(), unitErrors: this.d.resources.errors }
+        // up: since its pid started, so a pm reload never resets its uptime
+        const children = [...this.children.values()].map((p) => {
+            const v = p.view()
+            return { ...v, since: (v.status === 'up' ? p.startedAt() : null) ?? v.since, tail: tailLines(p.spec.log, CORE_TAIL) }
+        })
+        const ports = { pm: this.d.port ?? pmPort(), daemon: daemonPort(), web: homePort() }
+        return { pm: 'shipkit-pm', pid: process.pid, since: this.startedAt, version: LIB_VERSION, ports, tail: tailLines(pmLog(this.d.dir), CORE_TAIL), children, resources: this.d.resources.views(), unitErrors: this.d.resources.errors }
+    }
+
+    /** the image a global process declares as its icon, and no other file */
+    private icon(id: string): Response {
+        const d = this.d.resources.get(id)?.decl
+        const type = d?.icon == null ? null : iconImageType(d.icon)
+        if (d?.icon == null || type == null) return new Response(`no image icon for '${id}'`, { status: 404 })
+        const file = join(d.root, d.icon)
+        if (!existsSync(file)) return new Response(`${d.repo}/${d.icon} does not exist: the icon of '${id}'`, { status: 404 })
+        return new Response(Bun.file(file), { headers: { 'content-type': type, 'cache-control': 'no-cache' } })
     }
 
     async handle(req: Request): Promise<Response> {
         const path = new URL(req.url).pathname
         if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
         if (path === '/api/pm/status.json') return Response.json(this.answer())
+        if (path.startsWith('/api/pm/icon/') && req.method === 'GET') return this.icon(decodeURIComponent(path.slice('/api/pm/icon/'.length)))
         if (req.method !== 'POST') return new Response('not found', { status: 404 })
         const b = (await req.json().catch(() => ({}))) as Record<string, unknown>
         if (path === '/api/pm/child') {
@@ -122,7 +156,6 @@ export class Pm {
             else if (act === 'restart') report(r.restart())
             else if (act === 'open' || act === 'app') {
                 if (r.decl.url == null) return new Response(`${r.decl.id} declares no url to open`, { status: 400 })
-                if (act === 'app' && !r.decl.app) return new Response(`${r.decl.id} does not declare app: true, so it has no app window`, { status: 400 })
                 report(r.open(act === 'app' ? 'app' : 'browser'))
             } else if (act === 'takeover') {
                 const v = r.takeOverView