rvlib-shipkit 1.7.0 → 1.9.0

package/src/core/discover-checks.ts

@@ -158,13 +158,28 @@ function unloadable(path: string, message: string): CheckDef {
     }
 }
 
+/** a built-in that does not load, as a repo that only CONSUMES the toolkit
+ *  sees it: one warning, never a red gate, since only the toolkit's own repo
+ *  can fix the file, and its gate stays red on it */
+function brokenBuiltin(path: string, message: string): CheckDef {
+    return {
+        ...unloadable(path, message),
+        blocking: false,
+        run: (c) => c.warn(`${basename(path)} does not load, so this gate skips it: ${message.replace(`${path}: `, '')}`, 'the toolkit repo owns the file, and its own gate fails on it'),
+    }
+}
+
+const BUILTIN_OWNER = 'build/shipkit/built-in-checks.md'
+
 /** every check this repo can run: its own files, plus the toolkit's. Throws
  *  on a registration nobody can act on (a duplicate id, a repo check squatting
  *  the reserved prefix, a built-in with no owner page), so a broken
- *  declaration dies at load rather than half way through a gate. */
-export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
+ *  declaration dies at load rather than half way through a gate. A broken
+ *  built-in is that only in the toolkit's own repo: elsewhere it warns.
+ *  `builtinDir` is the toolkit's checks dir, a parameter for tests only */
+export async function discoverChecks(root: string, builtinDir: string = BUILTIN_CHECK_DIR): Promise<DiscoveredCheck[]> {
     const builtins: string[] = []
-    walk(BUILTIN_CHECK_DIR, builtins)
+    walk(builtinDir, builtins)
     const found: string[] = []
     walk(root, found)
     const units = repoUnitFiles(root)
@@ -173,6 +188,9 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
     // because a consumer reaches the same files through a linked node_modules
     const real = (f: string): string => { try { return realpathSync(f) } catch { return f } }
     const shipped = new Set(builtins.map(real))
+    // its own source, never an install of it
+    const inRoot = relative(real(root), real(builtinDir))
+    const hostsToolkit = !inRoot.startsWith('..') && !inRoot.split(/[\\/]/).includes('node_modules')
     const all = found.filter((f) => !shipped.has(real(f))).sort()
     builtins.sort()
     const names = fallbackNames(root, all)
@@ -185,23 +203,34 @@ export async function discoverChecks(root: string): Promise<DiscoveredCheck[]> {
     for (const f of [...builtins, ...own, ...units]) {
         const isBuiltin = builtins.includes(f)
         let def: CheckDef | null
+        let loadError: string | null = null
         try {
             def = await load(f)
         } catch (e) {
             // a file that does not load is ONE red row, never a dead inventory:
             // every other check still runs, and this one says why in every run
-            def = unloadable(f, (e as Error).message)
+            loadError = (e as Error).message
+            def = unloadable(f, loadError)
         }
         if (def == null) continue
         const rel = isBuiltin ? null : relative(root, f).replace(/\\/g, '/')
         const fallback = isBuiltin
             ? (BUILTIN_ID_RE.exec(base(f))?.[1] ?? base(f))
             : f.endsWith(UNIT_SUFFIX) ? unitBase(f) : names.get(f)!
-        const id = def.id ?? fallback
+        let id = def.id ?? fallback
         if (isBuiltin) {
-            if (id !== fallback) throw new Error(`${f}: declares id '${id}' but its file name says '${fallback}' — a built-in id is its file name`)
-            if ((def.owner ?? '') === '') throw new Error(`${f}: a built-in check names the page that OWNS the invariant`)
-            if (RETIRED_CHECK_IDS[id] != null) throw new Error(`${f}: id '${id}' is retired (${RETIRED_CHECK_IDS[id]}), and an id is never reused`)
+            const refused = loadError != null ? null
+                : id !== fallback ? `${f}: declares id '${id}' but its file name says '${fallback}' — a built-in id is its file name`
+                : (def.owner ?? '') === '' ? `${f}: a built-in check names the page that OWNS the invariant`
+                : RETIRED_CHECK_IDS[id] != null ? `${f}: id '${id}' is retired (${RETIRED_CHECK_IDS[id]}), and an id is never reused`
+                : null
+            // the toolkit's own repo dies on a refused built-in, a consumer
+            // only warns: it cannot fix the file, and must not lose its gate
+            if (refused != null && hostsToolkit) throw new Error(refused)
+            if (refused != null || loadError != null) {
+                def = hostsToolkit ? { ...def, owner: BUILTIN_OWNER } : { ...brokenBuiltin(f, refused ?? loadError!), owner: BUILTIN_OWNER }
+                id = fallback
+            }
         } else if (id.startsWith('SK')) {
             throw new Error(`${rel}: id '${id}' uses the reserved SK prefix — a repo check picks its own (e.g. RV${id.slice(-3)}) or plain words`)
         }

package/src/core/fix-scope.ts

@@ -0,0 +1,5 @@
+// does a gate run its repair pass (core/run-fixers.ts). A leaf, so the hub's
+// run lanes read the same answer the gate acts on without loading the gate.
+
+/** `fix` named wins. Unnamed: a whole gate repairs, a narrowed run does not */
+export const fixPassRuns = (o: { fix?: boolean; onlyIds?: readonly string[] }): boolean => o.fix ?? (o.onlyIds ?? []).length === 0

package/src/core/floor-resolve.ts

@@ -20,6 +20,7 @@ import type { CheckCtx } from './check-ctx.ts'
 import { checkUnitReader, type UnitReader } from '../release/unit-resolve.ts'
 import { parseJsonc } from '../ts/jsonc.ts'
 import { resolveTypecheckProjects } from '../ts/tsconfig-resolve.ts'
+import { gateBuildInfoArgs } from '../ts/typecheck-cache.ts'
 import { parseBunTestScript, suiteFlags } from '../suite/judge-suites.ts'
 import { declaredTestUnits, siblingUnits, testCheckId, unitIgnores, unitTestBody, unitTsconfig, type TestUnitDecl } from '../suite/test-units.ts'
 import { describeFirst, type TaskDef } from '../check.ts'
@@ -194,7 +195,7 @@ function builtinFloorTask(id: string, root: string, io: FloorReader): { task: Ta
             const projects = resolveTypecheckProjects(tsconfig, io, root)
             plain = projects.projects.length === 1 && projects.projects[0] === tsconfig && projects.missing.length === 0
         } catch { plain = false }
-        if (plain) return { task: { id, cmd: [tsc, '--noEmit'] }, source: 'built-in (tsc)' }
+        if (plain) return { task: { id, cmd: [tsc, '--noEmit', ...gateBuildInfoArgs(tsconfig)] }, source: 'built-in (tsc)' }
         const cli = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/ts/typecheck-cli.ts'))
         return { task: { id, cmd: ['bun', cli, tsc, tsconfig] }, source: 'built-in (tsc)' }
     }

package/src/core/git-root.ts

@@ -58,14 +58,23 @@ export function probeGitRoot(at: string): Probe {
     return p
 }
 
-/** the variables that let git find a repo with no `.git` in reach */
+/** the variables that let git find a repo with no `.git` in reach. They name
+ *  ONE repo for the whole process (git sets GIT_DIR for every hook in a linked
+ *  worktree), so they only answer for a directory with no `.git` of its own:
+ *  any other directory is asked with them stripped, or the hook's repo would
+ *  claim the house and every repo the process looks at */
 const LOCATING_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR']
+const locatingEnvSet = (): boolean => LOCATING_ENV.some((k) => (process.env[k] ?? '') !== '')
+const discoveryEnv = (): Record<string, string | undefined> => {
+    const env = { ...process.env }
+    for (const k of LOCATING_ENV) delete env[k]
+    return env
+}
 
-/** git's discovery walks up looking for `.git`. With none at or above and no
- *  variable pointing elsewhere, its answer is already known, and a gate or a
- *  test suite that probes fresh temp dirs would spawn a process per dir for it */
+/** git's discovery walks up looking for `.git`. With none at or above, its
+ *  answer is already known, and a gate or a test suite that probes fresh temp
+ *  dirs would spawn a process per dir for it */
 function nothingInReach(dir: string): boolean {
-    if (LOCATING_ENV.some((k) => (process.env[k] ?? '') !== '')) return false
     let cur: string
     try {
         cur = realpathSync(dir)
@@ -81,12 +90,11 @@ function nothingInReach(dir: string): boolean {
 }
 
 /** the common case answered from the disk: `.git` is a plain directory right
- *  at `dir`, which git describes as exactly that. Anything unusual (a locating
- *  variable, a gitfile or a symlinked `.git`, a shared common dir, a config
- *  that relocates the work tree, marks it bare or includes another file, a
- *  `.git` owned by someone else) is left to git */
+ *  at `dir`, which git describes as exactly that. Anything unusual (a gitfile
+ *  or a symlinked `.git`, a shared common dir, a config that relocates the
+ *  work tree, marks it bare or includes another file, a `.git` owned by
+ *  someone else) is left to git */
 function plainRoot(dir: string): GitRoot | null {
-    if (LOCATING_ENV.some((k) => (process.env[k] ?? '') !== '')) return null
     try {
         const top = realpathSync(dir)
         const gitDir = join(top, '.git')
@@ -102,8 +110,9 @@ function plainRoot(dir: string): GitRoot | null {
 }
 
 function ask(dir: string): Probe {
-    if (nothingInReach(dir)) return { root: null, error: 'fatal: not a git repository (or any of the parent directories): .git' }
-    const plain = plainRoot(dir)
+    const none = nothingInReach(dir)
+    if (none && !locatingEnvSet()) return { root: null, error: 'fatal: not a git repository (or any of the parent directories): .git' }
+    const plain = none ? null : plainRoot(dir)
     if (plain != null) return { root: plain, error: '' }
     let p: ReturnType<typeof Bun.spawnSync>
     try {
@@ -111,6 +120,7 @@ function ask(dir: string): Probe {
             cwd: dir,
             stdout: 'pipe',
             stderr: 'pipe',
+            env: none ? { ...process.env } : discoveryEnv(),
         })
     } catch (e) {
         return { root: null, error: e instanceof Error ? e.message : String(e) }

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/one-lib.ts

@@ -119,7 +119,9 @@ export function useOneLib(root: string = LIB_ROOT): void {
             build.onLoad({ filter: /\/(node_modules\/rvlib-shipkit|install\/cache\/rvlib-shipkit@[^/]*)\// }, (a) => {
                 const loader = LOADERS[extname(a.path)] ?? 'ts'
                 const sub = foreignLibPath(a.path, root)
-                if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader }
+                // the host copy itself lives under node_modules when it is an
+                // install: its path can carry importFresh's `?v=` stamp
+                if (sub == null) return { contents: readFileSync(a.path.replace(/\?.*$/, ''), 'utf8'), loader }
                 return reexport(join(root, sub))
             })
             for (const name of SHARED) {
@@ -131,7 +133,7 @@ export function useOneLib(root: string = LIB_ROOT): void {
                 const skip = [...new Set([host, real(host)])].map((h) => `(?!${esc(h)}/)`).join('')
                 build.onLoad({ filter: new RegExp(`^${skip}.*/node_modules/${esc(name)}/`) }, (a) => {
                     const sub = foreignSharedPath(a.path, name, host)
-                    if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader: LOADERS[extname(a.path)] ?? 'js' }
+                    if (sub == null) return { contents: readFileSync(a.path.replace(/\?.*$/, ''), 'utf8'), loader: LOADERS[extname(a.path)] ?? 'js' }
                     return reexport(sharedTarget(a.path, sub, name, host))
                 })
             }

package/src/core/run-ci.ts

@@ -10,6 +10,7 @@ import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { passScope, runCheckPass, type CheckOpts } from './run-check.ts'
 import { poolLines } from './slots.ts'
+import { fixPassRuns } from './fix-scope.ts'
 import { runFixPass } from './run-fixers.ts'
 import { formatLine } from './wire.ts'
 import { outcomeCounts } from './outcome-words.ts'
@@ -29,8 +30,9 @@ export type CiOpts = {
     onlyIds?: string[]
     /** refresh STATUS.md after the run (default true — O4: every repo gets it) */
     status?: boolean
-    /** repair the mechanical slots before gating. default on locally, verify
-     *  mode under CI. core/run-fixers.ts owns the scope. */
+    /** repair the mechanical slots before gating, verify mode under CI.
+     *  Unset: on for a whole gate, off for a narrowed one (core/fix-scope.ts).
+     *  core/run-fixers.ts owns the scope. */
     fix?: boolean
     /** also apply the repairs of the checks declaring `fix: 'ci'` during the
      *  fix pass */
@@ -138,15 +140,14 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     let c = o.config ?? (await loadRepoConfig(root))
     // mechanical failures are not information, so they never cost a round trip
     let fixFailed = false
-    // a NARROWED run repairs only the mechanical slots. The structural rule
-    // fixers rewrite package.json and repo config, and arming rewrites hooks/:
-    // that is the right price for the full gate and the wrong one for
-    // `bun run test`, which routes here and must answer the one question its
-    // name promises without leaving files in the agent's diff that it never
-    // wrote. Under CI it is worse than surprising: a formatting rewrite comes
-    // back as a test failure.
+    // a NARROWED run repairs nothing unless --fix asks, and even then only the
+    // mechanical slots. `bun run test` routes here and must answer the one
+    // question its name promises without leaving files in the agent's diff
+    // that it never wrote: in a shared tree the formatter rewrites every other
+    // agent's files too. The structural rule fixers rewrite package.json and
+    // repo config, and arming rewrites hooks/: the full gate's price alone
     const narrowed = (o.onlyIds ?? []).length > 0
-    if (o.fix !== false) {
+    if (fixPassRuns(o)) {
         const pass = await runFixPass(root, c, { rules: !narrowed && o.fixRules !== false, armHooks: !narrowed && o.armHooks === true, print: sink, detail })
         fixFailed = pass.failed
         // a fixer that rewrote the config or moved a check file leaves the
@@ -158,7 +159,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
                 return 1
             }
         }
-    } else detail('skip: fix pass (--no-fix)')
+    } else detail(o.fix === false ? 'skip: fix pass (--no-fix)' : 'skip: fix pass (a --only run leaves the tree alone, --fix repairs first)')
     const tier: TestTier = o.tests ?? envTier()
     // announced BEFORE the run (under --verbose, and in every release log),
     // so a log that died mid-way still says which tier it was asking for

package/src/core/slots.ts

@@ -4,6 +4,11 @@
 // mutate lease's non blocking form (locked-write.ts tryLease): a slot whose
 // holder died is free at once, and a live holder heartbeats it.
 //
+// A slot is a check, and a check is often a whole multi core tool (bun test
+// workers, oxlint threads, tsc), so slots alone never bound the CPU. Past the
+// cores the pool admits fewer slots in proportion to the 1 minute load, never
+// fewer than one (admittedSlots). A slot already held is never taken back.
+//
 // The one constraint a reader breaks first: a process started BY a check
 // (SHIPKIT_SLOT_HELD=1 in its environment) takes no slot. It already runs on
 // its parent's, and a parent waiting on a child that waits for a slot the
@@ -12,6 +17,8 @@ import { mkdirSync, readdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { leaseHolder, tryLease } from './locked-write.ts'
+import { machineLoad } from './budget.ts'
+import type { MachineLoad } from '../suite/judge-suites.ts'
 import { PARALLEL_ENV, parallelCap, parallelCapInfo } from './parallel.ts'
 
 /** where the slots live, for a test that must not touch the machine's pool */
@@ -19,7 +26,9 @@ export const SLOTS_DIR_ENV = 'SHIPKIT_SLOTS_DIR'
 /** set for every process a check spawns: it runs on its parent's slot */
 export const SLOT_HELD_ENV = 'SHIPKIT_SLOT_HELD'
 
-export type SlotPool = { dir: string; size: number }
+/** `load`: the reading that scales what the pool admits. Omitted: the whole
+ *  size, whatever the machine runs (a test's own pool) */
+export type SlotPool = { dir: string; size: number; load?: () => MachineLoad }
 
 export type SlotHolder = { slot: number; pid: number; repo: string; check: string; since: number }
 
@@ -37,9 +46,18 @@ export const autoGatePool = (): SlotPool => ({ dir: `${poolDir()}-auto-gate`, si
 
 /** this process's pool, or null when it runs inside a check that holds one */
 export function machinePool(): SlotPool | null {
-    return process.env[SLOT_HELD_ENV] === '1' ? null : { dir: poolDir(), size: parallelCap() }
+    return process.env[SLOT_HELD_ENV] === '1' ? null : { dir: poolDir(), size: parallelCap(), load: machineLoad }
 }
 
+/** how many of `size` slots a machine at this load admits: all of them up to
+ *  a load of one per core, then size × cores / load, never below one. At 20
+ *  on 8 cores a pool of 8 admits 3, at 81 it admits 1 */
+export const admittedSlots = (size: number, m: MachineLoad): number =>
+    Math.max(1, Math.min(size, Math.floor((size * m.cores) / Math.max(m.cores, m.load1))))
+
+const admitWords = (size: number, admitted: number, m: MachineLoad): string =>
+    `the pool admits ${admitted} of its ${size} slots at load ${m.load1.toFixed(1)} on ${m.cores} cores`
+
 /** who holds which slot right now, dead holders left out. Every slot file in
  *  the dir is read, so a slot taken under a larger size still shows. */
 export function poolOccupancy(pool: SlotPool = { dir: poolDir(), size: parallelCap() }): { size: number; dir: string; held: SlotHolder[] } {
@@ -64,25 +82,37 @@ export function poolLines(): string[] {
         ...(info.problem == null ? [] : [`WARN ${info.problem}`]),
         pool == null
             ? `ok: parallel: inside a check that holds a machine slot, so this run takes none (up to ${info.cap} at once in this process)`
-            : `ok: parallel: one machine pool of ${info.cap} slot(s) shared by every shipkit process, ${poolOccupancy(pool).held.length} held now (${why})`,
+            : `ok: parallel: one machine pool of ${info.cap} slot(s) shared by every shipkit process, ${poolOccupancy(pool).held.length} held now (${why})${loadNote(pool)}`,
     ]
 }
 
+const loadNote = (pool: SlotPool): string => {
+    const m = pool.load?.()
+    if (m == null) return ''
+    const admitted = admittedSlots(pool.size, m)
+    return admitted < pool.size ? `; ${admitWords(pool.size, admitted, m)}` : ''
+}
+
 /** wait for a free slot and hold it until release(). null = abort said stop. */
 export async function takeSlot(
     pool: SlotPool,
     who: { repo: string; check: string },
-    o: { abort?: () => boolean; pollMs?: number; onWait?: (held: SlotHolder[]) => void } = {},
+    o: { abort?: () => boolean; pollMs?: number; onWait?: (held: SlotHolder[], why: string) => void } = {},
 ): Promise<{ slot: number; release: () => void } | null> {
     mkdirSync(pool.dir, { recursive: true })
     let heard = false
     for (;;) {
-        for (let slot = 0; slot < pool.size; slot++) {
+        const m = pool.load?.() ?? null
+        const admitted = m == null ? pool.size : admittedSlots(pool.size, m)
+        for (let slot = 0; slot < admitted; slot++) {
             const lease = tryLease(join(pool.dir, `slot-${slot}`), who.check, { repo: who.repo, check: who.check })
             if (lease != null) return { slot, release: lease.release }
         }
         if (o.abort?.() === true) return null
-        if (!heard) { heard = true; o.onWait?.(poolOccupancy(pool).held) }
+        if (!heard) {
+            heard = true
+            o.onWait?.(poolOccupancy(pool).held, m != null && admitted < pool.size ? admitWords(pool.size, admitted, m) : `all ${pool.size} slots are held`)
+        }
         await Bun.sleep(o.pollMs ?? SLOT_POLL_MS)
     }
 }

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