rvlib-shipkit 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 1.8.0
+
+- **The quick tier can run only the suites a change reaches** (opt in: `tests: { select: true }`, or `SHIPKIT_TEST_SELECT=1` for one run). It keeps the snapshot of the last run and its red suites, and runs those plus every suite whose import closure, or whose recorded runtime reads, a change since then reaches. What it cannot see it runs: an unclaimed change under a code root, a spawn it does not know, a module that threw while loading, a run config file. The full tier still runs every suite.
+
+- **Runs of one repo in the home share, then overlap.** A terminal `sk ci` or `sk check` identical to one in flight on the same tree attaches to it, prints its lines and exits with its code. Runs without the repair pass start at once beside the runs in flight, bounded by the machine slot pool. A run with the repair pass still goes alone. Before, every run of a repo queued behind the one in flight, so a one second gate could wait minutes.
+
+- **The house context: one generated file every house agent loads.** `sk global-context` builds `generated/global-context.md` beside the house index. It lists every global process with the commands that drive it, every house repo, and each repo's `agent/global-contribution.md`. The daemon rewrites it within a minute of a source moving. A process or repo description joins by its first line only, and every item is scanned with the banned keywords of the commit leak guard: a hit leaves it out and says so. It exists only for a house whose index includes `@generated/global-context.md`. `--write` writes it and `--check` fails when it is stale.
+
+- **SK033: every house repo carries `agent/global-contribution.md`.** It is what the repo offers every other agent, capped at 40 lines and 3 KB with no heading above `####`, and `sk ci` writes a comment-only stub when it is missing. It applies only where the house index loads the generated context. It is cached on the file, so the check body runs again only when the file moves. SK027 no longer calls the file an orphan, because the house index links it.
+
+- **`sk gp open <id>` opens a global process's url** in the default browser, in Chrome (`--chrome`) or as its own app (`--app`), the overview's open buttons in the console. A process that is down starts first.
+
+- **The quick tier honours the worker count a repo names.** A `--parallel=<n>` in the repo's own `bun test` body is now a ceiling over the machine pool's share: the parallel phase takes the smaller of the two, as the one `--parallel` on its line. Before, the runner appended its own count after the body, and bun reads the last one, so a repo that measured fewer workers as faster still ran on every core of an idle machine. A bare `--parallel` keeps the pool's count.
+
+- **Declared serial suites and the full tier stay one at a time when the repo's body names `--parallel`.** The runner passed the body as written to the serial phase, to the full tier and to a suspect's alone rerun. So a body naming `--parallel=7` ran its declared serial suites, the ones that cannot share a run, in seven workers, and its full tier too, which runs one suite at a time because its suites spawn git and whole gates. Only the quick tier's parallel phase names a worker count now, and the runner keeps the body's `--parallel` off every other line.
+
 ## 1.7.0
 
 - **Cmd-F in the shipkit app shows a find bar now.** Since the app shipped, the Find menu did nothing visible: NSTextFinder never shows its bar for a web view. The app now draws its own bar on WebKit's find API. Return and cmd-G go to the next match, shift-return and shift-cmd-G to the previous one, Esc closes the bar, and it says "no match" when the page does not hold the text. Rebuilt apps pick it up at their next launch.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.7.0",
+    "version": "1.8.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/checks/SK027-agent-wiki-links.check.ts

@@ -3,9 +3,11 @@
 // a dangling ref there fails. A link that leaves agent/ but stays in the repo
 // is checked on disk; a pointer out of the repo (a house wiki) is backticked,
 // never a bare → or @. A repo without agent/index.md skips.
+// agent/global-contribution.md is no orphan: the house index links it (SK033).
 import { existsSync, readFileSync } from 'fs'
 import { basename, join } from 'path'
 import { check } from '../check.ts'
+import { CONTRIBUTION_FILE } from '../core/global-contribution.ts'
 import { lintMd } from '../wiki/lint-md.ts'
 
 export const agentWikiLinks = check({
@@ -22,8 +24,10 @@ export const agentWikiLinks = check({
     run: (c) => {
         if (!existsSync(join(c.root, 'agent/index.md'))) return void c.lines.push({ kind: 'skip', text: 'no agent/ wiki in this repo' })
         const lint = lintMd({ root: join(c.root, 'agent'), index: 'index.md', boundary: c.root })
-        const linked = lint.pages.filter((p) => !lint.orphans.includes(p))
-        for (const f of lint.orphans) {
+        // the global contribution is the house index's to link (SK033), never agent/'s
+        const orphans = lint.orphans.filter((f) => `agent/${f}` !== CONTRIBUTION_FILE)
+        const linked = lint.pages.filter((p) => !orphans.includes(p))
+        for (const f of orphans) {
             const by = namingPage(c.root, f, linked)
             const where = by != null ? `${by}, which already names it (turn that mention into the link)` : 'agent/index.md or the page of its topic'
             c.fail(`agent/${f}: orphan, unreachable from agent/index.md: add a markdown link to it from ${where}; delete it only if the page is dead`)

package/src/checks/SK033-global-contribution.check.ts

@@ -0,0 +1,47 @@
+// SK033 global contribution (meta/agent-folder.md): every house repo carries
+// agent/global-contribution.md, what it offers every agent of every house
+// repo (a house whose index loads @generated/global-context.md), which the house concatenates into the context each session loads
+// (home/global-context.ts). A new one is a comment only, so it contributes
+// nothing until an agent writes to it. Keyed on the file itself: once it is
+// there, the body runs again only when the file moves. Its page is linked from
+// the house index, never from agent/index.md, so SK027 leaves it out.
+import { homedir } from 'os'
+import { check, type FixResult } from '../check.ts'
+import { CONTRIBUTION_FILE, CONTRIBUTION_STUB, CONTEXT_INCLUDE, contributionBody, contributionOver, loadsContext } from '../core/global-contribution.ts'
+import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
+
+/** why a repo gives SK033 nothing to do, or null in a repo whose house
+ *  index loads the generated context */
+export function notHouse(root: string, home: string = homedir()): string | null {
+    const index = houseIndex(homeRepo(root), home)
+    if (index == null) return 'this repo includes no house index, so no house context reads it'
+    if (!loadsContext(index)) return `its house index does not load the generated context (no ${CONTEXT_INCLUDE} line), so nothing reads a contribution`
+    return null
+}
+
+export const globalContribution = check({
+    id: 'SK033',
+    blocking: true,
+    title: 'global contribution',
+    description: 'agent/global-contribution.md exists and fits in the house context',
+    owner: 'meta/agent-folder.md',
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'files', inputs: [CONTRIBUTION_FILE], key: null },
+    fix: 'ci',
+    applies: (env) => notHouse(env.root),
+    run: (c) => {
+        const text = c.read(CONTRIBUTION_FILE)
+        if (text == null) return void c.fail(`${CONTRIBUTION_FILE} is missing: every house repo carries one, empty until it has something to offer`, 'shipkit ci writes the empty one')
+        const body = contributionBody(text)
+        const over = contributionOver(body)
+        if (over != null) return void c.fail(`${CONTRIBUTION_FILE} is ${over}: every session of every house repo loads it, so the house context cuts it`, 'keep what another repo\'s agent can act on, move the rest to agent/')
+        c.ok(body === '' ? `${CONTRIBUTION_FILE} is there, contributing nothing yet` : `${CONTRIBUTION_FILE} contributes ${body.split('\n').length} line(s)`)
+    },
+    repair: (c): FixResult => {
+        if (c.read(CONTRIBUTION_FILE) != null) return { changed: false, summary: `${CONTRIBUTION_FILE} is there: its size is the author's to fix` }
+        c.write(CONTRIBUTION_FILE, CONTRIBUTION_STUB)
+        return { changed: true, summary: `wrote the empty ${CONTRIBUTION_FILE}` }
+    },
+})
+
+export default globalContribution

package/src/cli/cmd_GlobalContext.ts

@@ -0,0 +1,47 @@
+// shipkit global-context: the house's generated context, printed, written, or
+// checked against the file on disk. houseContext is the one computation, the
+// daemon's writer calls it too.
+import { existsSync, readFileSync } from 'fs'
+import { Command, Option } from 'clipanion'
+import { houseContext, writeIfChanged } from '../home/global-context.ts'
+
+export class GlobalContextCommand extends Command {
+    static override paths = [['global-context']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the context every house agent loads: global processes, house repos, each repo\'s global contribution',
+        details: 'one md file beside the house index (generated/global-context.md), which the index includes, gitignored. The daemon rewrites it when a source moves; this command prints it, writes it, or fails when the file on disk is stale',
+        examples: [
+            ['print what the file would hold', 'sk global-context'],
+            ['write it beside the house index', 'sk global-context --write'],
+            ['fail when the file on disk is stale', 'sk global-context --check'],
+        ],
+    })
+
+    write = Option.Boolean('--write', false, { description: 'write it beside the house index, only when it changed' })
+    check = Option.Boolean('--check', false, { description: 'exit 1 when the file on disk differs from what the sources give' })
+
+    async execute(): Promise<number> {
+        const c = await houseContext(process.cwd())
+        if (c == null) {
+            this.context.stderr.write('FAIL: this repo includes no house index in its CLAUDE.md, so there is no house to read\n')
+            return 1
+        }
+        if (this.check) {
+            const now = existsSync(c.path) ? readFileSync(c.path, 'utf8') : null
+            if (now === c.text) {
+                this.context.stdout.write(`ok: ${c.path} is current\n`)
+                return 0
+            }
+            this.context.stdout.write(`FAIL: ${c.path} is ${now == null ? 'missing' : 'stale'}\n      fix: shipkit global-context --write\n`)
+            return 1
+        }
+        if (this.write) {
+            this.context.stdout.write(writeIfChanged(c.path, c.text) ? `ok: wrote ${c.path}\n` : `ok: ${c.path} unchanged\n`)
+            return 0
+        }
+        this.context.stdout.write(c.text)
+        return 0
+    }
+}

package/src/cli/cmd_GlobalProcesses.ts

@@ -161,7 +161,7 @@ export type SwitchAct = 'start' | 'stop' | 'restart'
 
 export type SwitchDeps = {
     /** pm's answer to the switch: null when it took it, else why not */
-    post: (id: string, act: SwitchAct) => Promise<string | null>
+    post: (id: string, act: SwitchAct | 'open' | 'chrome' | 'app') => Promise<string | null>
     /** the process as pm sees it now, null when pm does not answer */
     view: (id: string) => Promise<ResourceView | null>
     sleep: (ms: number) => Promise<void>
@@ -266,3 +266,40 @@ export class GlobalProcessRestartCommand extends SwitchCommand {
         examples: [['restart ComfyUI, so it rescans its models', 'sk gp restart comfyui']],
     })
 }
+
+/** where `sk gp open` sends the url, by flag, as pm's resource api names it */
+export const openAct = (o: { chrome: boolean; app: boolean }): 'open' | 'chrome' | 'app' => (o.app ? 'app' : o.chrome ? 'chrome' : 'open')
+
+export class GlobalProcessOpenCommand extends Command {
+    static override paths = [['global-processes', 'open'], ['gp', 'open']]
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'open a global process\'s url in the browser, Chrome or its app, starting it first when down',
+        details: 'the overview\'s open buttons in the console. pm opens the url at once while the process answers, else starts it and opens once its probe answers. Exit 1 when pm refuses (no such process, no url declared)',
+        examples: [
+            ['the comfy panel in the default browser', 'sk gp open comfy-panel'],
+            ['in Chrome', 'sk gp open comfy-panel --chrome'],
+            ['as its own app in the dock', 'sk gp open comfy-panel --app'],
+        ],
+    })
+
+    id = Option.String({ required: true, name: 'id' })
+    chrome = Option.Boolean('--chrome', false, { description: 'open it in Chrome' })
+    app = Option.Boolean('--app', false, { description: 'open it as its own app, built on first use' })
+
+    async execute(): Promise<number> {
+        if (this.chrome && this.app) {
+            this.context.stderr.write('--chrome and --app name two places: pick one\n')
+            return 2
+        }
+        const act = openAct(this)
+        const refused = await pmSwitchDeps(() => {}).post(this.id, act)
+        if (refused != null) {
+            this.context.stdout.write(`FAIL open ${this.id}: ${refused}\n`)
+            return 1
+        }
+        const where = act === 'app' ? 'as its own app' : act === 'chrome' ? 'in Chrome' : 'in the default browser'
+        this.context.stdout.write(`ok: ${this.id} opens ${where}; a process that was down starts first (shipkit gp shows it)\n`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -11,9 +11,10 @@ import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
 import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
+import { GlobalProcessesCommand, GlobalProcessOpenCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
 import { PlannedCommand } from './cli/cmd_Planned.ts'
 import { InsightsCommand } from './cli/cmd_Insights.ts'
+import { GlobalContextCommand } from './cli/cmd_GlobalContext.ts'
 import { OverviewCommand } from './cli/cmd_Overview.ts'
 import { CiCommand } from './cli/cmd_Ci.ts'
 import { ContractsCommand } from './cli/cmd_Contracts.ts'
@@ -98,9 +99,11 @@ export function buildCli(): Cli {
     cli.register(GlobalProcessStartCommand)
     cli.register(GlobalProcessStopCommand)
     cli.register(GlobalProcessRestartCommand)
+    cli.register(GlobalProcessOpenCommand)
     cli.register(CrossRepoActivityCommand)
     cli.register(PlannedCommand)
     cli.register(InsightsCommand)
+    cli.register(GlobalContextCommand)
     cli.register(OverviewCommand)
     cli.register(ChecksCommand)
     cli.register(WhenCommand)

package/src/core/global-contribution.ts

@@ -0,0 +1,42 @@
+// a house repo's global contribution: `agent/global-contribution.md`, what the
+// repo offers every agent of every house repo (commands, how to run them).
+// The house's generated context (home/global-context.ts) concatenates them,
+// and every session of every house repo loads it, so each line costs tokens
+// everywhere: CONTRIBUTION_MAX_LINES and CONTRIBUTION_MAX_BYTES bound it.
+
+import { readFileSync } from 'fs'
+
+export const CONTRIBUTION_FILE = 'agent/global-contribution.md'
+/** the line a house index carries to load the generated context */
+export const CONTEXT_INCLUDE = '@generated/global-context.md'
+export const CONTRIBUTION_MAX_LINES = 40
+export const CONTRIBUTION_MAX_BYTES = 3_000
+
+/** what a new repo gets: a comment only, so it contributes nothing yet */
+export const CONTRIBUTION_STUB = `<!-- global contribution: what this repo offers every agent in every house repo, such as the commands another repo can run and what they produce. The house concatenates every repo's file into one context loaded in every session, so keep it to what another repo's agent can act on: at most ${CONTRIBUTION_MAX_LINES} lines, no heading above ####. Empty contributes nothing. This comment is dropped. -->
+`
+
+/** the text that joins the context: html comments dropped, trimmed */
+export const contributionBody = (text: string): string => text.replace(/<!--[\s\S]*?-->/g, '').trim()
+
+/** whether a house index loads the generated context: only then does a
+ *  contribution reach anyone */
+export function loadsContext(index: string): boolean {
+    try {
+        return readFileSync(index, 'utf8').split('\n').some((l) => l.trim() === CONTEXT_INCLUDE)
+    } catch {
+        return false
+    }
+}
+
+/** why a body breaks the house context, or null: over its bounds, or a
+ *  heading that would outrank the `### <repo>` it sits under */
+export function contributionOver(body: string): string | null {
+    const lines = body === '' ? 0 : body.split('\n').length
+    const heading = body.replace(/^```[\s\S]*?^```/gm, '').split('\n').find((l) => /^#{1,3}\s/.test(l))
+    if (heading != null) return `holding the heading "${heading.slice(0, 40)}", above ####`
+    const bytes = Buffer.byteLength(body)
+    if (lines > CONTRIBUTION_MAX_LINES) return `${lines} lines, over the ${CONTRIBUTION_MAX_LINES} line cap`
+    if (bytes > CONTRIBUTION_MAX_BYTES) return `${bytes} bytes, over the ${CONTRIBUTION_MAX_BYTES} byte cap`
+    return null
+}

package/src/home/global-context.ts

@@ -0,0 +1,145 @@
+// the house's generated context: every global process with the commands that
+// drive it, every house repo, and each repo's global contribution, as ONE md
+// file the house index includes, so every agent of every house repo loads it.
+// It lives beside the index (`generated/global-context.md`), gitignored: its
+// sources are the repos on this disk, so it is this machine's, never history.
+//
+// the one constraint a reader breaks first: it is in every session's context,
+// so a contribution over its cap is cut here, and SK033 fails in its repo.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { CONTRIBUTION_FILE, CONTRIBUTION_MAX_BYTES, CONTRIBUTION_MAX_LINES, contributionBody, contributionOver, loadsContext } from '../core/global-contribution.ts'
+import { KEYWORD_FILE } from '../core/layout.ts'
+import { evaluateLeak, globalKeywordFile, maskPattern, parsePatterns } from '../hooks/leak-guard.ts'
+import { homeRepo, houseRepos } from '../serve/project-gutter.ts'
+import { scanGlobalUnits, type GlobalProcessDecl } from './global-units.ts'
+
+/** how often the daemon looks whether a source moved */
+export const GLOBAL_CONTEXT_EVERY_MS = 60_000
+
+export type ContextRepo = { name: string; path: string; description: string | null; contribution: string }
+export type ContextProcess = Pick<GlobalProcessDecl, 'id' | 'label' | 'repo' | 'url' | 'description'>
+
+/** the banned keyword a text matches, masked, or null: every item is
+ *  scanned before it joins, since every session everywhere loads the file */
+export type Leak = (text: string) => string | null
+
+/** a repo description's longest form here: the rest is the repo's own */
+export const DESCRIPTION_MAX = 160
+
+/** where a house keeps it: beside its index */
+export const globalContextPath = (index: string): string => join(dirname(index), 'generated', 'global-context.md')
+
+/** a body cut to the caps, with the line that says so */
+function capped(r: ContextRepo, body: string): string {
+    const over = contributionOver(body)
+    if (over == null) return body
+    // a heading above #### would outrank the `### <repo>` it sits under
+    let cut = body.replace(/^#{1,3}(?=\s)/gm, '####').split('\n').slice(0, CONTRIBUTION_MAX_LINES).join('\n')
+    while (Buffer.byteLength(cut) > CONTRIBUTION_MAX_BYTES) cut = cut.slice(0, cut.lastIndexOf('\n'))
+    return `${cut}\n\n(cut: ${r.name}/${CONTRIBUTION_FILE} is ${over}, and SK033 fails there until it fits)`
+}
+
+/** a description's first line, at most DESCRIPTION_MAX characters */
+const short = (d: string): string => {
+    const l = d.split('\n')[0]!.trim()
+    return l.length <= DESCRIPTION_MAX ? l : `${l.slice(0, DESCRIPTION_MAX - 1)}…`
+}
+
+const cell = (s: string): string => s.replace(/\|/g, '\\|').replace(/\n/g, ' ')
+
+/** a description's first line only: the rest (a login, a how to) is the
+ *  hub's to show, never every session's */
+const firstLine = (d: string | null): string => {
+    const l = d?.split('\n')[0]?.trim() ?? ''
+    return l === '' ? '' : `: ${cell(l)}`
+}
+
+/** the file's text. Pure: the same sources always give the same bytes, so a
+ *  write happens only when a source moved */
+export function globalContextText(o: { repos: ContextRepo[]; processes: ContextProcess[]; errors: string[]; leak?: Leak }): string {
+    const left: string[] = []
+    /** the item when it matches no banned keyword, else null and a line saying so */
+    const clean = (where: string, text: string): string | null => {
+        const hit = o.leak?.(text) ?? null
+        if (hit == null) return text
+        left.push(`- ${where}: matches the banned keyword ${hit}`)
+        return null
+    }
+    const out: string[] = [
+        '# global context: this machine, for every agent',
+        '',
+        `Generated by \`sk global-context --write\` from every house repo (the daemon rewrites it when a source moves). Never edit it: a repo adds to it through its own \`${CONTRIBUTION_FILE}\`.`,
+        '',
+        '## Global processes',
+        '',
+    ]
+    if (o.processes.length === 0) out.push('No house repo declares one.')
+    else {
+        out.push('Drive each by id: `sk gp start|stop|restart <id>` waits for its probe, `sk gp open <id> [--chrome|--app]` opens its url and starts it first when it is down, `sk gp` shows where each stands.', '')
+        out.push('| id | process | repo | url |', '|---|---|---|---|')
+        for (const p of [...o.processes].sort((a, b) => a.repo.localeCompare(b.repo) || a.id.localeCompare(b.id))) {
+            const row = clean(`${p.repo} process ${p.id}`, `| \`${p.id}\` | ${cell(p.label)}${firstLine(p.description)} | ${p.repo} | ${p.url ?? 'no url: start, stop, restart only'} |`)
+            if (row != null) out.push(row)
+        }
+    }
+    out.push('', '## House repos', '')
+    for (const r of o.repos) {
+        const line = clean(`${r.name} repo line`, `- **${r.name}** \`${r.path}\`${r.description == null ? '' : `: ${short(r.description)}`}`)
+        if (line != null) out.push(line)
+    }
+    const given = o.repos
+        .map((r) => ({ r, body: contributionBody(r.contribution) }))
+        .filter((x) => x.body !== '' && clean(`${x.r.name}/${CONTRIBUTION_FILE}`, x.body) != null)
+    out.push('', '## What each repo offers', '')
+    if (given.length === 0) out.push(`No repo contributes yet: each writes its own \`${CONTRIBUTION_FILE}\`.`)
+    for (const { r, body } of given) out.push(`### ${r.name}`, '', capped(r, body), '')
+    if (left.length > 0) out.push('', '## Left out', '', ...left)
+    if (o.errors.length > 0) out.push('', '## Could not read', '', ...o.errors.map((e) => `- ${e}`))
+    return `${out.join('\n').trimEnd()}\n`
+}
+
+/** one repo's line and contribution, read from disk */
+export function contextRepo(r: { name: string; path: string }, home: string = homedir()): ContextRepo {
+    let description: string | null = null
+    try {
+        const d = (JSON.parse(readFileSync(join(r.path, 'package.json'), 'utf8')) as { description?: unknown }).description
+        if (typeof d === 'string' && d.trim() !== '') description = d.trim()
+    } catch { /* no package.json, or one that does not parse: no line */ }
+    const f = join(r.path, CONTRIBUTION_FILE)
+    return { name: r.name, path: r.path.startsWith(`${home}/`) ? `~${r.path.slice(home.length)}` : r.path, description, contribution: existsSync(f) ? readFileSync(f, 'utf8') : '' }
+}
+
+/** writes the text when it differs from what the file holds; true when it wrote */
+export function writeIfChanged(path: string, text: string): boolean {
+    if (existsSync(path) && readFileSync(path, 'utf8') === text) return false
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, text)
+    return true
+}
+
+/** the leak scan over the machine's banned keywords and the house repo's own,
+ *  the lists the commit leak guard reads; null when neither exists */
+export function houseLeak(houseRoot: string): Leak | null {
+    const files = [globalKeywordFile(), join(houseRoot, KEYWORD_FILE)].filter((f): f is string => f != null && existsSync(f))
+    if (files.length === 0) return null
+    const patterns = parsePatterns(files.map((f) => readFileSync(f, 'utf8')).join('\n'))
+    return (text) => {
+        const hit = evaluateLeak([{ where: 'global context', content: text }], patterns, []).hits[0]
+        return hit == null ? null : maskPattern(hit.pattern)
+    }
+}
+
+/** THE computation, for the house the repo at `root` belongs to: where the
+ *  file goes and what it holds. The cli and the daemon both call it. Null
+ *  when `root` includes no house index, or one that does not load the file */
+export async function houseContext(root: string, home: string = homedir()): Promise<{ path: string; text: string } | null> {
+    const h = houseRepos(homeRepo(root), home)
+    if (h.index == null || !loadsContext(h.index)) return null
+    const units = await scanGlobalUnits(h.repos.map((r) => ({ name: r.name, path: r.path })))
+    return {
+        path: globalContextPath(h.index),
+        text: globalContextText({ repos: h.repos.map((r) => contextRepo(r, home)), processes: units.processes, errors: units.errors, leak: houseLeak(h.home) ?? undefined }),
+    }
+}

package/src/home/home-routes.ts

@@ -18,6 +18,7 @@ import type { Planner, PlanRow } from '../plan/planner.ts'
 import type { Widgets, WidgetView } from './widgets.ts'
 import { ActivityCache, repoActivity, windowMinutes } from './activity.ts'
 import { devRepos, InsightsCache, type Scope } from './insights.ts'
+import { GLOBAL_CONTEXT_EVERY_MS, houseContext, writeIfChanged } from './global-context.ts'
 import { HouseRuns } from '../serve/house-runs.ts'
 
 /** how far back a repo's git page lists its commits */
@@ -126,6 +127,7 @@ export function homeRoutes(d: HomeDeps) {
     }
 
     let active = new Set<string>()
+    let contextAt = -Infinity
     if (d.plan != null) d.plan.active = (name) => active.has(name)
 
     async function tick(): Promise<void> {
@@ -133,6 +135,14 @@ export function homeRoutes(d: HomeDeps) {
         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()
+        // the house's generated context: rewritten only when a source moved,
+        // and never held on
+        if (Date.now() - contextAt >= GLOBAL_CONTEXT_EVERY_MS) {
+            contextAt = Date.now()
+            void houseContext(d.root)
+                .then((c) => { if (c != null && writeIfChanged(c.path, c.text)) console.log(`ok: wrote ${c.path}`) })
+                .catch((e) => console.error(`WARN the global context could not be written: ${(e as Error).message}`))
+        }
         // a widget render never holds the tick back
         void d.widgets?.tick(repos.map((r) => ({ name: r.name, path: r.path }))).catch((e) => console.error(`WARN the widgets broke: ${(e as Error).message}`))
         await d.hubs.tick(active)

package/src/serve/hub-runtime.ts

@@ -41,6 +41,7 @@ import { autoGatePool, takeSlot } from '../core/slots.ts'
 import { liveJobs, startJob } from '../core/jobs.ts'
 import { followJob } from '../core/job-follow.ts'
 import { RUN_JOB } from '../home/home-words.ts'
+import { RunLanes, runKey, treeStamp, writesTree } from './run-lanes.ts'
 import { OtherRepos } from './other-repos.ts'
 import { HouseRuns } from './house-runs.ts'
 import { recordStamp } from './project-gutter.ts'
@@ -185,9 +186,11 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
     const port = o?.port ?? c.serve?.port ?? defaultHubPort(c.name)
     // every run this process has going, whoever started it
     let active = 0
-    // ONE run at a time, whoever asked: two gates over one tree would measure
-    // the same checks twice and race each other's repair pass
-    let chain: Promise<unknown> = Promise.resolve()
+    // every run, whoever asked: an identical one attaches, a repair pass goes
+    // alone, the rest overlap under the machine slot pool (run-lanes.ts)
+    const lanes = new RunLanes(() => treeStamp(root))
+    // the gate jobs this runtime started: one beside another is the lanes' call
+    const mine = new Set<string>()
     // the latest verdict of every check, printed as one problem frame after
     // each run for the vscode problems pane (problems/problem-line.ts)
     const board = new ProblemBoard()
@@ -215,13 +218,22 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
             }
         }
         // a job still running here, started before this image or by a terminal's --detach
-        while (liveJobs(root).length > 0) await Bun.sleep(jobs.pollMs ?? 250)
+        const foreign = (): boolean => liveJobs(root).some((j) => !mine.has(j.id))
+        if (foreign()) tap.line('note: a gate job this hub did not start is running here, so this one starts when it ends')
+        while (foreign()) await Bun.sleep(jobs.pollMs ?? 250)
         const j = startJob(root, { cli: jobs.cli, kind, args: [], job: { opts, oneLib: true, turn: background, ...(env == null ? {} : { env }) } })
+        mine.add(j.id)
         tap.job?.(j.id)
-        return (await followJob(root, j.id, tap, { pollMs: jobs.pollMs })) ?? 1
+        try {
+            return (await followJob(root, j.id, tap, { pollMs: jobs.pollMs })) ?? 1
+        } finally {
+            mine.delete(j.id)
+        }
     }
     const runChecks: HubDeps['runChecks'] = (tap, o) => {
-        const run = chain.then(async () => {
+        // only a whole gate the hub was asked for runs the repair pass (hubGateOpts)
+        const writes = o?.auto !== true && o?.gate === true && (o.only == null || o.only.length === 0)
+        return lanes.submit({ key: null, writes, print: tap.line }, async () => {
             active++
             // a run the hub starts on its own takes the machine's background
             // turn, once it is this hub's turn, never while it queues
@@ -243,27 +255,25 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
                 for (const l of board.frame()) io.print(l)
             }
         })
-        chain = run.catch(() => {})
-        return run
     }
     // a `shipkit ci` or `shipkit check` from a terminal, run HERE (home/via-hub.ts):
-    // in the same one-at-a-time chain as the hub's own runs, feeding the same
-    // problems frame, recorded as the cli's
+    // in the same lanes as the hub's own runs, feeding the same problems
+    // frame, recorded as the cli's
     const runCli: HubDeps['runCli'] = (kind, opts, print) => {
-        // never on a --json run: its output is the json and nothing else
-        if ((active > 0 || (jobs != null && liveJobs(root).length > 0)) && opts.json !== true) print('note: this hub has a run in flight, so this one starts when it ends')
-        const run = chain.then(async () => {
+        // a --json run prints the json and nothing else, so it never shares
+        const key = opts.json === true ? null : runKey(kind, opts)
+        // `check --fix` runs in process (home/via-hub.ts), so a check here never repairs
+        const writes = kind === 'ci' && writesTree(opts)
+        return lanes.submit({ key, writes, print, quiet: opts.json === true }, async (tee) => {
             active++
             try {
                 await refresh()
-                return await exec(kind, { ...opts, invokedBy: 'cli' }, { line: print, check: onBoard, job: (id) => print(`${RUN_JOB}${id}`) }, false)
+                return await exec(kind, { ...opts, invokedBy: 'cli' }, { line: tee, check: onBoard, job: (id) => tee(`${RUN_JOB}${id}`) }, false)
             } finally {
                 active--
                 for (const l of board.frame()) io.print(l)
             }
         })
-        chain = run.catch(() => {})
-        return run
     }
     const runIn = async (tap: CheckTap, o: Parameters<HubDeps['runChecks']>[1], background: boolean): Promise<number> => {
         const only = o?.only != null && o.only.length > 0 ? o.only : undefined
@@ -287,11 +297,11 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
         if (adopted.length > 0) {
             io.print(`ok: following ${adopted.length} gate job(s) still running: ${adopted.map((j) => j.id).join(', ')}`)
             active++
-            const run = Promise.all(adopted.map((j) => followJob(root, j.id, { line: () => {}, check: onBoard }, { pollMs: jobs.pollMs }))).finally(() => {
-                active--
-                for (const l of board.frame()) io.print(l)
-            })
-            chain = run.catch(() => {})
+            void lanes.submit({ key: null, writes: true, print: () => {} }, () =>
+                Promise.all(adopted.map((j) => followJob(root, j.id, { line: () => {}, check: onBoard }, { pollMs: jobs.pollMs }))).then(() => 0).finally(() => {
+                    active--
+                    for (const l of board.frame()) io.print(l)
+                })).catch(() => {})
         }
     }
     // resolved once: it shells out to git, and the page asks on every poll