rvlib-shipkit 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 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.
+
+- **A new cross-repo page, `/insights`, and its console twin `sk insights`.** It shows a grid of boxes, each with tags, and a tag row filters which boxes show. Dependency usage lists every package by how many repos use it. Click a row to list each repo and the range it asks. Version drift lists the packages asked at more than one range. Script names lists every package.json script with its commands. The scope is the house repos or every folder of `~/dev`, and one filter searches every box.
+
+- **Every widget card has a refresh button.** It renders the widget now, off its clock, and passes `render({ force: true })`, so a widget that samples another machine can skip its cache or backoff. A widget that ignores the argument simply renders again.
+
+- **The traced audit groups files under a dir the task listed.** A build that lists an asset folder and stats each image in it proposed one `ignoredInputs` line per image. The files now group under the outermost dir the task also listed, keyed by content once more than three fall under it.
+
 ## 1.6.0
 
 - **lint, typecheck, test and every task that declares nothing are cached now.** Such a task is keyed on the whole work tree, plus the gitignored paths the new `ignoredInputs` lists for it (`{ test: ['dist/**'] }`, `'*'` for every task; a path by content, `dir/**` by the names under it), and the lockfile, the installed packages, the bun and node versions and the toolkit code behind it. `sk trace-audit` runs each gate task once under a file tracer and names the gitignored paths it reads that its key misses. Tracing is on wherever it can run (Apple silicon macOS): SK031 audits about daily, `sk trace-audit --disable` opts a machine out and `SHIPKIT_TRACE=0` one run, and each finding joins the key of the task that read it at once, in every worktree of the repo. SK032 and the fix pass of `sk ci` then write the findings into their own block of `repo.config.ts`, once the repo pins 1.6.0 or later. The tracer never decides a verdict. It needs Apple silicon macOS: on Linux and in CI nothing audits, and SK030's daily sample is the only net there.
@@ -10,8 +36,6 @@
 
 - **SK030 audits the cache.** About once a day, while somebody works in the repo, it re-runs a sample of the checks the cache would answer right now, fresh, and compares. A cached green that a fresh run disagrees with fails, naming the check whose key misses a path its body reads, and the stale answer is dropped so it is never served again. `sk cache-audit` is the same audit on demand (`--sample <n>`, `--only <id>`, `--json`).
 
-## Unreleased (patch)
-
 - **The hub tree groups assets by kit category.** Under media, each category is a row that folds, and its label opens the category page. An asset row reads by its kit label (`mon/brindon/front`), never its file id.
 
 - **SK001 no longer asks a comfy repo for a `comfy:up` script.** The box is a global process that `sk gp start comfyui` starts from any repo, so a per-repo script only copied that command. A `.shipkit/comfy/` folder now asks for nothing, and SK001 no longer probes it.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "1.6.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/cmd_Insights.ts

@@ -0,0 +1,78 @@
+// shipkit insights: the insights page in the console. The boxes come from
+// insightsOf, the one computation the daemon's route serves the page; this
+// file only renders them as text. It reads the manifests directly and needs no
+// daemon.
+import { homedir } from 'os'
+import { Command, Option } from 'clipanion'
+import { devRepos, insightsOf, placeWords, rowMatches, SCOPES, tagsOf, type InsightsAnswer, type Scope } from '../home/insights.ts'
+
+/** the boxes as text: a heading per box, then its rows, top `top` of each */
+export function renderInsights(a: InsightsAnswer, o: { tag?: string | null; query?: string; top: number; uses: boolean }): string[] {
+    const out: string[] = []
+    for (const b of a.boxes) {
+        if (o.tag != null && !b.tags.includes(o.tag)) continue
+        const rows = b.rows.filter((r) => rowMatches(b, r, o.query ?? ''))
+        out.push(`${b.title}  [${b.tags.join(', ')}]  ${rows.length} ${b.noun}${rows.length === 1 ? '' : 's'}`)
+        const width = Math.max(0, ...rows.slice(0, o.top).map((r) => r.key.length))
+        for (const r of rows.slice(0, o.top)) {
+            out.push(`  ${r.key.padEnd(width)}  ${String(r.repos).padStart(3)} repos  ${r.values.slice(0, 3).join('  ')}${r.values.length > 3 ? `  +${r.values.length - 3}` : ''}`)
+            if (o.uses) for (const u of r.uses) out.push(`      ${placeWords(u)}  ${u.value}${u.dev ? '  (dev)' : ''}`)
+        }
+        if (rows.length > o.top) out.push(`  … ${rows.length - o.top} more`)
+        out.push('')
+    }
+    out.push(`${a.repos} repos, ${a.files} package.json, read in ${a.ms}ms`)
+    for (const e of a.errors) out.push(`WARN ${e}`)
+    return out
+}
+
+export class InsightsCommand extends Command {
+    static override paths = [['insights']]
+
+    static override usage = Command.Usage({
+        category: 'Home',
+        description: 'the insights page as text: boxes about every repo, like which packages they use and by how many',
+        details: 'every package.json the house repos track (or every folder of ~/dev with --scope dev), turned into boxes: dependency usage sorted by how many repos use each package, version drift, script names. The same computation the page reads, no daemon needed',
+        examples: [
+            ['every box, the house repos', 'sk insights'],
+            ['every repo of ~/dev', 'sk insights --scope dev'],
+            ['where a package is used, and at which range', 'sk insights --scope dev --tag deps --query zod --uses'],
+            ['the whole list of one tag', 'sk insights --tag deps --top 1000'],
+            ['the route\'s exact payload', 'sk insights --json'],
+        ],
+    })
+
+    scope = Option.String('--scope', 'house', { description: 'house (the project list) or dev (every folder of ~/dev)' })
+    tag = Option.String('--tag', { required: false, description: 'only the boxes carrying this tag' })
+    query = Option.String('--query', { required: false, description: 'only the rows whose key or a value holds this text' })
+    top = Option.String('--top', '20', { description: 'rows shown per box' })
+    uses = Option.Boolean('--uses', false, { description: 'list every use under each row' })
+    json = Option.Boolean('--json', false, { description: 'the daemon route\'s exact payload: { now, scope, repos, files, boxes, errors, ms }' })
+
+    async execute(): Promise<number> {
+        if (!(SCOPES as readonly string[]).includes(this.scope)) {
+            this.context.stderr.write(`--scope must be one of ${SCOPES.join(', ')}, got ${JSON.stringify(this.scope)}\n`)
+            return 2
+        }
+        const scope = this.scope as Scope
+        const top = Number(this.top)
+        if (!(top >= 1)) {
+            this.context.stderr.write(`--top must be a number from 1, got ${JSON.stringify(this.top)}\n`)
+            return 2
+        }
+        const home = process.env.HOME || homedir()
+        // the hub route module draws app icons, so it loads only when this runs
+        const repos = scope === 'dev' ? devRepos(home) : (await import('../serve/project-gutter-route.ts')).railRepos(process.cwd(), home)
+        const a = await insightsOf(repos, scope)
+        if (this.json) {
+            this.context.stdout.write(`${JSON.stringify(a, null, 2)}\n`)
+            return 0
+        }
+        if (this.tag != null && !tagsOf(a.boxes).includes(this.tag)) {
+            this.context.stderr.write(`--tag must be one of ${tagsOf(a.boxes).join(', ')}, got ${JSON.stringify(this.tag)}\n`)
+            return 2
+        }
+        for (const l of renderInsights(a, { tag: this.tag ?? null, query: this.query, top, uses: this.uses })) this.context.stdout.write(`${l}\n`)
+        return 0
+    }
+}

package/src/cli.ts

@@ -11,8 +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'
@@ -97,8 +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/core/trace-audit.ts

@@ -47,18 +47,27 @@ function covered(p: string, listing: boolean, extras: string[]): boolean {
     return extras.some((e) => (isNamesInput(e) ? listing && under(p, e.slice(0, -3)) : under(p, e)))
 }
 
-/** the fewest entries that cover what was read: each file by itself, or its
- *  dir once more than three files there were read; each listed dir as
- *  `dir/**`, the outermost one only */
+/** the fewest entries that cover what was read: each file by itself, or a
+ *  dir by content once more than three files under it were read (its own
+ *  dir, or the outermost dir the task also listed); each listed dir as
+ *  `dir/**`, the outermost one only, unless a content entry covers it */
 export function proposeInputs(content: string[], listed: string[]): string[] {
-    const byDir = new Map<string, string[]>()
-    for (const f of content) byDir.set(posix.dirname(f), [...(byDir.get(posix.dirname(f)) ?? []), f])
-    const bytes = [...byDir].flatMap(([dir, files]) => (files.length > 3 && dir !== '.' ? [dir] : files))
     const minimal = (xs: string[]): string[] => {
         const sorted = [...new Set(xs)].sort()
         return sorted.filter((x) => !sorted.some((y) => y !== x && under(x, y)))
     }
-    return [...minimal(bytes), ...minimal(listed).map((d) => `${d}/**`)].sort()
+    const tops = minimal(listed)
+    const byDir = new Map<string, string[]>()
+    for (const f of content) {
+        const d = tops.find((t) => under(f, t)) ?? posix.dirname(f)
+        byDir.set(d, [...(byDir.get(d) ?? []), f])
+    }
+    // a listed dir holding three or fewer: each file under its own dir
+    const regroup = [...byDir].flatMap(([dir, files]) => (tops.includes(dir) && files.length <= 3 ? files.map((f) => [posix.dirname(f), f] as const) : files.map((f) => [dir, f] as const)))
+    const again = new Map<string, string[]>()
+    for (const [d, f] of regroup) again.set(d, [...(again.get(d) ?? []), f])
+    const bytes = minimal([...again].flatMap(([dir, files]) => (files.length > 3 && dir !== '.' ? [dir] : files)))
+    return [...bytes, ...tops.filter((d) => !bytes.some((b) => under(d, b))).map((d) => `${d}/**`)].sort()
 }
 
 /** trace every gate task of the repo once and report what its key misses */

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 }),
+    }
+}