@oneie/claude 0.8.0 → 0.10.0

package/scripts/factory-executor-check.mjs

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// classification: portable
+// Red proof for factory-executor.js — the trace, the slug and the close.
+//
+// WHY THIS IS DIFFERENT FROM factory-review-check.mjs: that checker defines OLD
+// and NEW as two inline string copies and never opens the executor, so it stays
+// green whether or not the file is fixed. It proves a shape. THIS one READS THE
+// FILE for every assertion, and lifts the two behavioural tables (slugFor, the
+// close status re-parse) OUT of the source with new Function so they cannot
+// drift from what ships. Revert any one of the three fixes and this goes red.
+//
+// Usage:  node .claude/scripts/factory-executor-check.mjs [path]
+// Exit 0 = all green. Exit 1 = at least one assertion failed.
+
+import { readFileSync } from 'node:fs'
+
+const F = process.argv[2] || '.claude/workflows/factory-executor.js'
+const src = readFileSync(F, 'utf8')
+
+const fails = []
+function check(name, pass, detail) {
+  if (!pass) fails.push(name)
+  console.log(`  ${pass ? ' ok ' : 'RED '}  ${name}${detail ? `  — ${detail}` : ''}`)
+}
+
+// Lift a `const <name> = ...` block out of the source by balanced braces, so the
+// behavioural tables below exercise THE FILE and not a copy of it.
+function lift(startPat) {
+  const i = src.search(startPat)
+  if (i < 0) return null
+  const open = src.indexOf('{', i)
+  if (open < 0) return null
+  let depth = 0
+  for (let j = open; j < src.length; j++) {
+    if (src[j] === '{') depth++
+    else if (src[j] === '}') { depth--; if (depth === 0) return src.slice(i, j + 1) }
+  }
+  return null
+}
+
+console.log(`factory-executor-check: ${F}\n`)
+
+// ── 1. THE TRACE — the emit is issued at both boundaries of all six stages ──
+//
+// ON THE NUMBER: the brief asked for "12 factory-emit.sh occurrences". That is
+// the plan's RUNTIME boundary count per job (6 stages × start/end, minus Ready's
+// start, minus Prove's when the review refutes, plus the repair's build+review
+// pair) mis-stated as a static grep. Statically there is exactly ONE
+// `factory-emit.sh` literal — inside the emitStage helper — and N emitStage CALL
+// SITES. Inlining the curl twelve times to satisfy a grep would reintroduce the
+// very divergence the slugFor fix removes: one command, many renderings. So the
+// count is reported, and COVERAGE is what is asserted.
+console.log('1. the trace — stage emit coverage')
+
+const EMIT_CALL = /emitStage\(\s*[^,]+,\s*'(\w+)'\s*,\s*([\s\S]*?),\s*\{/g
+
+// COVERAGE IS PER CODE PATH, NOT PER STAGE NAME. A union over the stage name
+// scores `build` as covered when the MAIN path has lost its fail emit but the
+// REPAIR path still carries one — absent evidence defaulting to benign, in the
+// checker written to stop that. So each emitting path gets its own lane, keyed
+// off the options object: `repair:` (the repair build), `pass: N` (review pass 1
+// vs 2), else `main`. Every lane must carry both boundaries.
+function optionsAfter(idx) {
+  let depth = 0
+  for (let j = idx; j < src.length; j++) {
+    if (src[j] === '{') depth++
+    else if (src[j] === '}') { depth--; if (depth === 0) return src.slice(idx, j + 1) }
+  }
+  return ''
+}
+const lanes = new Map()
+let m
+while ((m = EMIT_CALL.exec(src))) {
+  const [, stage, statusExpr] = m
+  const opts = optionsAfter(src.lastIndexOf('{', EMIT_CALL.lastIndex))
+  const lane = /\brepair:/.test(opts) ? 'repair' : (opts.match(/\bpass:\s*(\d+)/) || [, null])[1] ? `pass${opts.match(/\bpass:\s*(\d+)/)[1]}` : 'main'
+  const key = `${stage}:${lane}`
+  if (!lanes.has(key)) lanes.set(key, new Set())
+  for (const st of (statusExpr.match(/'(start|ok|fail)'/g) || []).map((q) => q.slice(1, -1))) lanes.get(key).add(st)
+}
+
+// FAIL CLOSED on a partial parse. If the regex misses a call, coverage would be
+// computed from a subset and a missing boundary could read as present-elsewhere.
+const rawCalls = (src.match(/emitStage\(/g) || []).length - 1 // minus the definition
+const parsedCalls = (src.match(EMIT_CALL) || []).length
+check(
+  'every emitStage call site was parsed (a partial parse cannot score coverage)',
+  rawCalls > 0 && parsedCalls === rawCalls,
+  `${parsedCalls} parsed of ${rawCalls} call site(s)`,
+)
+
+// The invariant is one EXECUTED rendering, not one mention: the name also
+// appears in a comment, a schema description and the operator hint in EMITS
+// DARK. What must never be duplicated is the line that BUILDS AND RUNS the
+// command — two of those is the slugFor disease with a different subject.
+const runSites = (src.match(/factory-emit\.sh \$\{parts\.join/g) || []).length
+check('exactly one EXECUTED factory-emit.sh rendering — one command, one builder', runSites === 1,
+  `${runSites} executed of ${(src.match(/factory-emit\.sh/g) || []).length} total mention(s) (the rest are comments, a schema description and the DARK hint)`)
+
+// Every lane the pipeline actually has. Named explicitly so a lane that
+// DISAPPEARS is red too — a missing key cannot be scored by iterating what is
+// present.
+const REQUIRED_LANES = [
+  ['claim:main', 'the claim'],
+  ['build:main', 'the first build'],
+  ['build:repair', 'the repair build'],
+  ['review:pass1', 'review pass 1'],
+  ['review:pass2', 'review pass 2 (after the repair)'],
+  ['prove:main', 'the walk'],
+  ['close:main', 'the close'],
+]
+for (const [key, what] of REQUIRED_LANES) {
+  const s = lanes.get(key)
+  check(`${key}: start + ok + fail  (${what})`, !!s && s.has('start') && s.has('ok') && s.has('fail'), s ? `[${[...s].sort().join(' ')}]` : 'LANE ABSENT')
+}
+// Ready is the deliberate asymmetry: the read happens BEFORE any tid is known,
+// so a per-job `start` would be invented rather than observed.
+const ready = lanes.get('ready:main') || new Set()
+check('ready: ok, and NO start (a start before any tid is known is invented, not observed)', ready.has('ok') && !ready.has('start'), `[${[...ready].sort().join(' ')}]`)
+
+// A stage that did not run must be ABSENT — there is no `skip` in the vocabulary.
+const refutedBranch = lift(/if \(review\.refuted\) \{/)
+check('the refuted-review branch emits NO prove frame (absent, never "skipped")', refutedBranch !== null && !refutedBranch.includes('emitStage'))
+
+check('EMITS DARK is keyed on attempts, not only on failures', /emitStats\.pushed === 0/.test(src) && /EMITS DARK/.test(src),
+  'zero pushed and zero failed must not read as a clean turn')
+
+// ── 2. THE CLOSE — status is a copy out of a script line, never a belief ────
+console.log('\n2. the close — status is read back, not asserted')
+
+const closeSchema = lift(/const CLOSE_SCHEMA = /)
+check('CLOSE_SCHEMA exists', closeSchema !== null)
+check("CLOSE_SCHEMA requires 'checkLine'", !!closeSchema && /required:\s*\[[^\]]*'checkLine'[^\]]*\]/.test(closeSchema))
+check('CLOSE_SCHEMA still requires tagged + status (no field lost)',
+  !!closeSchema && /'tagged'/.test(closeSchema) && /'status'/.test(closeSchema))
+check('closePrompt tells the agent to run factory-close-check.sh', /factory-close-check\.sh/.test(src))
+
+// A stage agent that THROWS propagates out of the stage; the item is then dropped
+// by `out.filter(Boolean)` and lands in NEITHER results NOR skipped — a job that
+// built, reviewed and walked disappears from the turn's own summary. Both agents
+// that can throw after work has been done must be caught.
+check('the Close agent is .catch()-guarded (a thrown Close must not vanish the job)',
+  /schema: CLOSE_SCHEMA \}\)\s*\n\s*\.catch\(\(\) => null\)/.test(src))
+check('the repair agent is .catch()-guarded (a thrown repair must not leave the row picked with no close)',
+  /repairPrompt\(t, b, r1\.findings\)[\s\S]{0,220}?\.catch\(\(\) => null\)/.test(src))
+
+// Lift the executor's OWN four-line derivation and drive it. The first factory
+// run is the fixture: task:01a07591e5c350a306c93933 is still `picked` while the
+// Close agent returned {"status":"done"}.
+const deriveSrc = src.match(/ +const line = c &&[\s\S]*?const status = [^\n]*\n/)
+check('the status derivation is present in the file and liftable', deriveSrc !== null)
+if (deriveSrc) {
+  const NEW = new Function('c', `${deriveSrc[0]}\nreturn status`)
+  const OLD = (c) => (c && c.status) || 'unknown' // the pre-fix line
+  const cases = [
+    ['THE BUG: agent said done, board said picked', { status: 'done', checkLine: 'CLOSE tid=task:01a07591e5c350a306c93933 lane=none verdict=red status=picked' }, 'unverified'],
+    ['an honest close: both say done', { status: 'done', checkLine: 'CLOSE tid=x lane=fast verdict=ok status=done' }, 'done'],
+    ['the script failed, no CLOSE line', { status: 'unverified', checkLine: 'factory-close-check.sh: row not found' }, 'unverified'],
+    ['checkLine absent entirely', { status: 'done' }, 'unverified'],
+    ['the close agent was lost', null, 'unverified'],
+  ]
+  let oldFails = 0, newFails = 0
+  for (const [name, input, want] of cases) {
+    const o = OLD(input), n = NEW(input)
+    if (o !== want) oldFails++
+    if (n !== want) newFails++
+    console.log(`         ${name.padEnd(46)} want=${String(want).padEnd(11)} OLD=${String(o).padEnd(11)} NEW=${n}${n === want ? '' : '   <-- NEW WRONG'}`)
+  }
+  check('the pre-fix line fails the cases this fix exists for', oldFails > 0, `OLD: ${oldFails} failure(s) — must be > 0 or the proof is worthless`)
+  check("the file's own derivation passes every case", newFails === 0, `NEW: ${newFails} failure(s)`)
+}
+
+// ── 3. THE SLUG — one function, zero re-derivations ────────────────────────
+console.log('\n3. the slug — one function, no second sanitiser')
+
+check('exactly one slugFor definition', (src.match(/const slugFor\s*=/g) || []).length === 1)
+// NOTE THE SCOPING: `${t.tid}` legitimately appears in labels, receiver payloads
+// and prompt prose. What must be zero is the RENDERED SLUG — the git/branch/
+// worktree/receipt-path shape the first run's builder had to hand-patch.
+const rawSlugSites = (src.match(/task-\$\{t\.tid\}/g) || []).length
+check('zero raw `task-${t.tid}` renderings in the git/branch/worktree lines', rawSlugSites === 0, `${rawSlugSites} found (was 8 across 6 lines)`)
+check('the prompts render the slug through slugFor', (src.match(/\$\{slugFor\(t\.tid\)\}/g) || []).length >= 8)
+
+const slugSrc = lift(/const slugFor = /)
+check('slugFor is liftable from the file', slugSrc !== null)
+if (slugSrc) {
+  const slugFor = new Function(`${slugSrc}\nreturn slugFor`)()
+  const cases = [
+    // The directory the first run ACTUALLY built in.
+    ['task:01a07591e5c350a306c93933', 'task-01a07591e5c350a306c93933', 'the first run’s own tid'],
+    ['01a07591e5c350a306c93933', 'task-01a07591e5c350a306c93933', 'a bare id gets the prefix once'],
+    ['task/abc', 'task-abc', 'a slash separator'],
+    ['task:a b:c', 'task-a-b-c', 'spaces and colons collapse'],
+  ]
+  let bad = 0
+  for (const [tid, want, why] of cases) {
+    const got = slugFor(tid)
+    if (got !== want) bad++
+    console.log(`         slugFor(${JSON.stringify(tid).padEnd(30)}) = ${String(got).padEnd(30)} want ${want}${got === want ? '' : '   <-- WRONG'}   (${why})`)
+  }
+  check('slugFor maps every case to the directory the walk will be told to check', bad === 0)
+  // Empty is a stop, not a default: `task-` shared by N jobs is one worktree,
+  // one branch and one receipt for all of them, silently.
+  let threw = false
+  try { slugFor(':::') } catch { threw = true }
+  check('a tid with no slug-safe characters THROWS (it must not collapse to `task-`)', threw)
+}
+
+// ── 4. THE ARITHMETIC — one site, and this workstream did not move it ──────
+// The hoist is the point: pass 1 and pass 2 must not be able to disagree.
+console.log('\n4. the review jury — one arithmetic site, so two passes cannot drift')
+const arith = src.match(/const refuted = votes[^\n]*/g) || []
+check('exactly one vote-arithmetic site', arith.length === 1, arith.length === 1 ? arith[0].trim() : `${arith.length} sites`)
+
+// ── 5. THE CLOSE STATUS TABLE — the board status the close ASKED FOR ───────
+// `closeOk = w.verdict === 'ok' && status !== 'unverified'` accepted ANY board
+// status the read-back reported honestly. The shape that got through: a NON-UI
+// task, verdict ok, `tasks:status` refused, factory-close-check.sh prints
+// `status=picked`, the agent copies `picked`, both words agree → closeOk true →
+// close emits `ok` → event.ts writes **workflow:done** on a row the board reads
+// `picked`. The expected status is a function of (verdict, t.ui) and is known at
+// the call site, so this drives THE FILE's own derivation against that table.
+console.log('\n5. the close — expected status is derived from (verdict, ui), and tagged:false is not a close')
+
+// Lifted through `const closeOk`, and it returns ONLY closeOk on purpose: a body
+// that returns {status, expectedStatus, tagged} would THROW on the pre-fix file
+// (`expectedStatus is not defined`) and the RED rows would arrive as a crash
+// instead of as a wrong answer. A crash is not a red proof; a wrong answer is.
+const closeSrc = src.match(/ +const line = c &&[\s\S]*?\n +const closeOk = [^\n]*\n/)
+check('the closeOk derivation is liftable from the file (a lift miss must be RED, never skipped)', closeSrc !== null)
+if (closeSrc) {
+  const NEW = new Function('c', 'w', 't', `${closeSrc[0]}\nreturn closeOk`)
+  // The pre-fix line, verbatim from a60084d09.
+  const OLD = (c, w) => {
+    const line = c && typeof c.checkLine === 'string' ? c.checkLine : ''
+    const m = /\bstatus=([a-z]+)\b/.exec(line)
+    const claimed = (c && typeof c.status === 'string' && c.status) || ''
+    const status = m && m[1] === claimed ? m[1] : 'unverified'
+    return w.verdict === 'ok' && status !== 'unverified'
+  }
+  const cl = (st) => ({ status: st, checkLine: `CLOSE tid=x lane=fast verdict=ok status=${st}`, tagged: true })
+  const cases = [
+    // THE FINDING, as reported: non-UI, walk ok, board still picked.
+    ['non-UI ok, board says picked — tasks:status was refused', cl('picked'), { verdict: 'ok' }, { ui: false }, false],
+    // A UI task is SUPPOSED to stay picked: a person has not looked yet.
+    ['UI ok, board says picked — that is the asked-for status', cl('picked'), { verdict: 'ok' }, { ui: true }, true],
+    // tagged:false is tasks:notes refusing — the row carries no lane/verdict.
+    ['non-UI ok, board says done, but tagged:false', { status: 'done', checkLine: 'CLOSE tid=x lane=fast verdict=ok status=done', tagged: false }, { verdict: 'ok' }, { ui: false }, false],
+    // The honest close, which must stay green or the fix has broken the loop.
+    ['non-UI ok, board says done, tagged true', cl('done'), { verdict: 'ok' }, { ui: false }, true],
+    // A UI task must never be counted closed on `done`: nobody looked.
+    ['UI ok, board says done — nobody looked, so that is wrong too', cl('done'), { verdict: 'ok' }, { ui: true }, false],
+    // A red verdict closes `fail` whatever the row says (event.ts: a close ok is
+    // workflow:done, so a red that emits ok makes the trace contradict the board).
+    ['red verdict, board says picked', cl('picked'), { verdict: 'red' }, { ui: false }, false],
+    // `tagged` unsaid is not `tagged:false` — it must not read as a refusal.
+    ['non-UI ok, done, tagged unsaid (agent omitted it)', { status: 'done', checkLine: 'CLOSE tid=x lane=fast verdict=ok status=done' }, { verdict: 'ok' }, { ui: false }, true],
+    // The original divergence fixture: the words disagree → status unverified.
+    ['agent said done, board said picked', { status: 'done', checkLine: 'CLOSE tid=task:01a07591e5c350a306c93933 lane=none verdict=red status=picked', tagged: true }, { verdict: 'ok' }, { ui: false }, false],
+    // A lost Close agent: no line, nothing known.
+    ['the close agent was lost', null, { verdict: 'ok' }, { ui: false }, false],
+  ]
+  let oldFails = 0, newFails = 0
+  for (const [name, c, w, t, want] of cases) {
+    let o, n
+    try { o = OLD(c, w) } catch (e) { o = `threw:${e.message}` }
+    try { n = NEW(c, w, t) } catch (e) { n = `threw:${e.message}` }
+    if (o !== want) oldFails++
+    if (n !== want) newFails++
+    console.log(`         ${name.padEnd(58)} want=${String(want).padEnd(6)} OLD=${String(o).padEnd(6)} NEW=${n}${n === want ? '' : '   <-- NEW WRONG'}`)
+  }
+  check('the pre-fix closeOk line fails the rows this fix exists for', oldFails > 0,
+    `OLD: ${oldFails} failure(s) — must be > 0 or the proof is worthless`)
+  check("the file's own closeOk derivation passes every row", newFails === 0, `NEW: ${newFails} failure(s)`)
+}
+
+// The reason line has to NAME the two words, or a `fail` frame is unactionable.
+check('the close fail reason names expected vs actual board status',
+  /expected \$\{expectedStatus\}/.test(src), 'the frame must say which status it wanted')
+check('status, expectedStatus, tagged and closeOk are carried into the result',
+  /status, expectedStatus, tagged, closeOk, checkLine: line,/.test(src))
+check('the turn line counts closeOk, not the walk verdict',
+  /const ok = results\.filter\(\(r\) => r\.closeOk\)\.length/.test(src),
+  'a green walk whose close was refused is not an ok job')
+check('a walked-ok-but-unclosed job is counted, not lost between ok and red',
+  /const held = results\.filter\(\(r\) => r\.verdict === 'ok' && !r\.closeOk\)\.length/.test(src))
+
+// ── 6. THE LOST JURY — zero survivors is not a green review step ───────────
+// `runReview` does `.filter(Boolean)`, so a lens that throws leaves lenses:0 —
+// and the vote line computes `0 * 2 > Math.max(1, 0)` = false, i.e. NOT refuted
+// (measured; a repair-pass finding asserted the opposite). The review emit then
+// recorded `step:done` with reason undefined and detail {lenses:0, attempted:1}.
+// Fixed at the emit, both passes, without touching the arithmetic (§4).
+console.log('\n6. the review emit — a jury with zero survivors emits fail, both passes')
+
+const lostSites = src.match(/'review',\s*r(\d)\.refuted \|\| r\1\.lenses === 0 \? 'fail' : 'ok'/g) || []
+check('both review emit sites fail closed on lenses === 0', lostSites.length === 2,
+  `${lostSites.length} of 2 site(s) — pass 1 and pass 2 must not disagree about what a lost jury is`)
+const lostReasons = src.match(/no lens survived \(\$\{r\d\.attempted\} attempted\)/g) || []
+check("the reason names the lost jury — 'no lens survived (N attempted)'", lostReasons.length === 2,
+  `${lostReasons.length} of 2 reason(s)`)
+// The arithmetic itself FAILS CLOSED: zero survivors ⇒ refuted, `>=` on the tie.
+// The previous version of this check asserted the line was UNTOUCHED — a scope
+// guard that kept `0*2 > 1` fail-open through two merges on 2026-09-06. The
+// behavioural proof lives in factory-review-check.mjs, which lifts this line
+// out of the file; here we only assert the fail-open shape is gone.
+const arith2 = src.match(/const refuted = votes[^\n]*/g) || []
+check('the vote arithmetic fails closed (zero survivors ⇒ refuted; no Math.max(1, …) fail-open shape)',
+  arith2.length === 1 && /votes\.length === 0 \? true/.test(arith2[0]) && !/Math\.max\(1, votes\.length\)/.test(arith2[0]),
+  arith2[0] || 'no `const refuted = votes…` line found')
+
+// ── 7. THE EMIT CONTRACT — factory-emit.sh takes --detail k=v, not JSON ────
+// Measured 2026-09-06 against the merged script: `--detail '{"slug":"x"}'` dies
+// `--detail wants k=v` at EXIT 2, because its parser is
+// `case "$kv" in *=*)` and a JSON blob carries no `=`. Every emit with a detail
+// object — Build, Review, Prove, Close — wrote NO frame and was counted as a
+// receiver rejection. A newline inside a value splits the script's own
+// newline-joined heredoc and kills the whole emit the same way.
+console.log('\n7. the emit contract — read off .claude/scripts/factory-emit.sh')
+
+check('no JSON blob is passed to --detail (the script refuses it, exit 2)',
+  !/--detail \$\{shq\(JSON\.stringify/.test(src))
+check('--detail is rendered as repeated k=v pairs', /--detail \$\{shq\(`\$\{k\}=\$\{val\}`\)\}/.test(src))
+check('detail values are whitespace-collapsed (a newline splits the script\'s heredoc and kills the emit)',
+  src.includes("String(v).replace(/\\s+/g, ' ').trim()"))
+check('an empty detail value is dropped, not posted as `k=`', /if \(!val\) continue/.test(src))
+check('a detail key that would mis-split is dropped BY NAME, not silently',
+  /dropped detail key/.test(src))
+check('the header comment states the real flag set, not `--detail <json>`',
+  /\[--detail k=v\]\.\.\./.test(src) && !/\[--detail <json>\]/.test(src))
+check('EMIT_SCHEMA names factory-emit.sh\'s own exit codes', /0 emitted · 2 bad arguments · 3 no credential · 4 the receiver refused/.test(src))
+
+// ── 8. READY — one frame per turn, and the slug guard runs first ───────────
+// The emits were pushed one per row, before round 1 and before the slugFor
+// guard: `agent()` is eager and these sit outside `parallel`, so a full page
+// (200 rows) spawned 200 haiku agents ahead of the barrier that prices memory —
+// and a turn about to throw on a malformed tid had already written N `ready ok`
+// frames for jobs that never started.
+console.log('\n8. ready — one frame per turn, after the slug guard')
+
+const readyCalls = src.match(/emitStage\([^\n]*'ready'[^\n]*/g) || []
+check('exactly one ready emit site', readyCalls.length === 1, `${readyCalls.length} site(s)`)
+check('the ready emit is NOT inside a per-row loop', readyCalls.length === 1 && !/^for \(/.test(readyCalls[0].trim()),
+  readyCalls.length === 1 ? readyCalls[0].trim().slice(0, 80) : 'unparsed')
+check('the ready frame carries the row count', readyCalls.length === 1 && /count: tasks\.length/.test(readyCalls[0]))
+const guardIdx = src.indexOf('for (const t of tasks) slugFor(t.tid)')
+const readyIdx = readyCalls.length === 1 ? src.indexOf(readyCalls[0]) : -1
+check('the slugFor guard runs BEFORE the ready emit (a turn that throws must not have emitted first)',
+  guardIdx > 0 && readyIdx > guardIdx, `guard@${guardIdx} ready@${readyIdx}`)
+
+console.log(`\nfactory-executor-check: ${fails.length ? `${fails.length} RED` : 'all green'}`)
+if (fails.length) for (const f of fails) console.log(`  RED  ${f}`)
+process.exit(fails.length ? 1 : 0)

package/scripts/factory-peak.sh

@@ -0,0 +1,301 @@
+#!/usr/bin/env bash
+# factory-peak.sh — the resident price of a running tree, measured.
+#
+# manifest: portable
+#
+# WHAT IT IS. Width is an assumption until something reads the bill.
+# factory-width.sh DIVIDES the free memory by an assumed price per cycle; this
+# script MEASURES that price. Point it at the root pid of anything that forks —
+# a parked preview server, a gate, a fleet worktree — and it samples the
+# resident set of the whole process TREE until the job ends or the clock runs
+# out, then prints the peak.
+#
+#   bash .claude/scripts/factory-peak.sh --pid 12163 --seconds 30
+#   bash .claude/scripts/factory-peak.sh --pid "$!" --until /tmp/run.done --interval 5
+#   bash .claude/scripts/factory-peak.sh --self-test
+#
+# Output — one line per sample, then the verdict:
+#
+#   t=0 procs=4 rss_mb=91
+#   t=2 procs=4 rss_mb=104
+#   PEAK rss_mb=104 at t=2 procs=4
+#
+# WHAT THE NUMBER IS. The SUM of every process's RSS in the tree. RSS
+# double-counts pages that processes share — a node parent and its workerd child
+# share libraries and mapped files — so the figure is an UPPER BOUND on what the
+# tree costs the box. That is the conservative direction for a budget, and it is
+# the same rough arithmetic gate_headroom already prices a cycle with.
+#
+# RSS IS A LIVE QUANTITY, NOT A CONSTANT. The OS reclaims and compresses idle
+# anonymous pages, so an idle tree's resident set DECAYS while you watch it: the
+# same parked preview server, untouched, read PEAK 138 MB in one 30s window and
+# 87 MB in another. Neither is wrong — a peak is what the tree held while it was
+# watched. Price a cycle from a window in which the tree is DOING the work being
+# priced, and read an idle tree's number as its floor, not its cost under load.
+#
+# THE TREE. Descendants via `pgrep -P`, walked breadth-first with a seen-set and
+# a depth cap (a live tree reshapes between levels; a pid must be counted once).
+# If the root pid is its own process-group leader, the group's other members are
+# added too (mode=children+pgid). When it is NOT — a server forked by a wrapper
+# shell inherits the WRAPPER's group — that group belongs to somebody else and is
+# left alone (mode=children). The mode is printed, so the number is interpretable.
+#
+# FAILS CLOSED. A tree that is not there is never a cheap tree:
+#
+#   exit 2   the root pid is not alive at start      nothing was measured
+#   exit 3   the root exited mid-run                 TRUNCATED, peak still printed
+#   exit 4   every sample read 0 MB                  the sampler is broken, not the tree free
+#   exit 5   --self-test failed
+#
+# `PEAK rss_mb=0` is never printed as a pass — that is the benign default this
+# instrument exists to refuse.
+set -uo pipefail
+
+PID=""
+INTERVAL=2
+UNTIL_FILE=""
+SECONDS_CAP=""
+DO_SELFTEST=0
+MAX_DEPTH=6
+HARD_CAP="${FACTORY_PEAK_HARD_CAP:-3600}"
+
+die() { printf '%s\n' "$*" >&2; }
+
+usage() {
+  die "usage: factory-peak.sh --pid <root pid> [--interval 2] [--until <file>|--seconds N]"
+  die "       factory-peak.sh --self-test"
+}
+
+# RED-PROOF SEAM — --self-test's red half neuters exactly this line and asserts
+# the green half then fails. Keep it a one-liner.
+_children() { pgrep -P "$1" 2>/dev/null; }
+
+_alive() { kill -0 "$1" 2>/dev/null; }
+
+# Every descendant of $1, breadth-first, each pid once, depth-capped.
+_tree_pids() {
+  local root="$1" seen=" $1 " d=0 p c
+  local -a frontier=("$root") next=()
+  printf '%s\n' "$root"
+  while [ "${#frontier[@]}" -gt 0 ] && [ "$d" -lt "$MAX_DEPTH" ]; do
+    next=()
+    for p in "${frontier[@]}"; do
+      while read -r c; do
+        [ -n "$c" ] || continue
+        case "$seen" in *" $c "*) continue ;; esac
+        seen="$seen$c "
+        printf '%s\n' "$c"
+        next+=("$c")
+      done < <(_children "$p")
+    done
+    frontier=(${next[@]+"${next[@]}"})
+    d=$((d + 1))
+  done
+}
+
+# echoes "<rss_mb> <procs>"; 0 0 when nothing in the tree answered.
+_sample() {
+  local pids list
+  pids="$(_tree_pids "$PID" | sort -un)"
+  if [ "$MODE" = "children+pgid" ]; then
+    pids="$(printf '%s\n%s\n' "$pids" \
+      "$(ps -axo pid=,pgid= | awk -v g="$PID" '$2 == g { print $1 }')" | sort -un)"
+  fi
+  list="$(printf '%s' "$pids" | tr '\n' ',' | sed 's/,$//')"
+  [ -n "$list" ] && [ "$list" != "," ] || { printf '0 0\n'; return; }
+  ps -o rss= -p "$list" 2>/dev/null \
+    | awk '{ s += $1; n++ } END { printf "%d %d\n", s / 1024, n }'
+}
+
+measure() {
+  local start now t mb n samples=0 truncated=0
+  local peak=0 peak_t=0 peak_n=0
+
+  _alive "$PID" || { die "root pid $PID is not alive — nothing to measure"; return 2; }
+
+  MODE=children
+  local rpgid
+  rpgid="$(ps -o pgid= -p "$PID" 2>/dev/null | tr -d ' ')"
+  [ -n "$rpgid" ] && [ "$rpgid" = "$PID" ] && MODE="children+pgid"
+  printf '# pid=%s mode=%s interval=%s%s%s\n' "$PID" "$MODE" "$INTERVAL" \
+    "${SECONDS_CAP:+ seconds=$SECONDS_CAP}" "${UNTIL_FILE:+ until=$UNTIL_FILE}"
+
+  start="$(date +%s)"
+  while :; do
+    now="$(date +%s)"; t=$((now - start))
+    if ! _alive "$PID"; then
+      truncated=1
+      die "# root pid $PID exited at t=${t}s — the tree is gone"
+      break
+    fi
+    read -r mb n <<EOS
+$(_sample)
+EOS
+    printf 't=%s procs=%s rss_mb=%s\n' "$t" "$n" "$mb"
+    samples=$((samples + 1))
+    if [ "$mb" -gt "$peak" ]; then peak="$mb"; peak_t="$t"; peak_n="$n"; fi
+
+    if [ -n "$UNTIL_FILE" ] && [ -e "$UNTIL_FILE" ]; then break; fi
+    if [ -n "$SECONDS_CAP" ] && [ "$t" -ge "$SECONDS_CAP" ]; then break; fi
+    if [ "$t" -ge "$HARD_CAP" ]; then break; fi
+    sleep "$INTERVAL"
+  done
+
+  if [ "$samples" -eq 0 ]; then
+    die "no sample was taken — root pid $PID died before the first read"
+    return 3
+  fi
+  if [ "$peak" -le 0 ]; then
+    die "every one of $samples sample(s) read 0 MB — the sampler could not see the tree,"
+    die "which is not the same as the tree being free. Refusing to print a peak."
+    return 4
+  fi
+  printf 'PEAK rss_mb=%s at t=%s procs=%s\n' "$peak" "$peak_t" "$peak_n"
+  if [ "$truncated" -eq 1 ]; then
+    printf 'TRUNCATED — the root exited before the window closed; the peak is a lower bound\n'
+    return 3
+  fi
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# --self-test: a tree whose allocation is KNOWN, then the red half.
+# ---------------------------------------------------------------------------
+self_test() {
+  local rt alloc_mb=50 base_mb expected measured delta rc
+  local tmpdir child root out
+
+  command -v python3 >/dev/null 2>&1 || {
+    die "SELF-TEST unrun — no python3 on this box to build a known tree"
+    return 5
+  }
+  rt=python3
+
+  tmpdir="$(mktemp -d -t factory-peak)" || { die "SELF-TEST unrun — mktemp failed"; return 5; }
+  child="$tmpdir/hold.py"
+  # The child must KEEP its pages hot, not merely allocate them. macOS compresses
+  # idle anonymous pages: a bytearray touched once and then slept on falls out of
+  # the resident set within seconds (measured — a 133MB tree read 20MB at t=3s),
+  # so a self-test that allocates and sleeps asserts against a number the OS has
+  # already taken back. Re-touching every page is what makes the allocation a
+  # thing the sampler can be held to.
+  cat > "$child" <<PY
+import time
+b = bytearray(${alloc_mb} * 1024 * 1024)
+end = time.time() + 25
+while time.time() < end:
+    for i in range(0, len(b), 4096):
+        b[i] = 1                  # keep every page RESIDENT, not just allocated
+    time.sleep(0.05)
+PY
+
+  # Baseline: what one interpreter costs holding nothing. Measured, never guessed —
+  # it is what makes the 30% tolerance mean something.
+  "$rt" -c 'import time; time.sleep(6)' &
+  local bpid=$!
+  sleep 2
+  base_mb="$(ps -o rss= -p "$bpid" 2>/dev/null | awk '{ printf "%d", $1 / 1024 }')"
+  kill "$bpid" 2>/dev/null; wait "$bpid" 2>/dev/null
+  case "${base_mb:-}" in ''|*[!0-9]*) base_mb=0 ;; esac
+  if [ "$base_mb" -le 0 ]; then
+    die "SELF-TEST unrun — could not read the baseline interpreter's RSS"
+    rm -rf "$tmpdir"; return 5
+  fi
+
+  # The known tree: one sh, two children each holding alloc_mb resident.
+  sh -c "\"$rt\" \"$child\" & \"$rt\" \"$child\" & wait" &
+  root=$!
+  sleep 2   # let both children reach the plateau
+
+  out="$(PID="$root" INTERVAL=1 SECONDS_CAP=8 UNTIL_FILE="" measure 2>&1)"
+  rc=$?
+  kill -- -"$root" 2>/dev/null
+  pkill -P "$root" 2>/dev/null
+  kill "$root" 2>/dev/null
+  wait "$root" 2>/dev/null
+  rm -rf "$tmpdir"
+
+  if [ "$rc" -ne 0 ]; then
+    printf '%s\n' "$out"
+    die "SELF-TEST FAIL — the sampler exited $rc against a known-live tree"
+    return 5
+  fi
+  measured="$(printf '%s\n' "$out" | awk -F'rss_mb=' '/^PEAK /{ split($2, a, " "); print a[1] }')"
+  case "${measured:-}" in ''|*[!0-9]*)
+    printf '%s\n' "$out"
+    die "SELF-TEST FAIL — no PEAK line to read"
+    return 5 ;;
+  esac
+
+  # The KNOWN quantity is the allocation: 2 x alloc_mb, page-touched, resident.
+  # The interpreter baseline is measured, but it is the unstable term (it swings
+  # with how far the interpreter has loaded when it is sampled), so it is never
+  # allowed into the FLOOR — only into the ceiling, as headroom. Asserting the
+  # symmetric "expected = 2*alloc + 2*baseline" would put a term that moves 36%
+  # between runs inside a 30% budget.
+  local known floor ceiling
+  known=$(( 2 * alloc_mb ))
+  floor=$(( known * 70 / 100 ))
+  ceiling=$(( known * 130 / 100 + 2 * base_mb ))
+  delta="$(awk -v m="$measured" -v k="$known" 'BEGIN { printf "%+.1f", (m - k) * 100 / k }')"
+  printf 'SELF-TEST known=%sMB (2x%s alloc) measured=%sMB delta=%s%% window=[%s,%s] (ceiling carries 2x%s baseline)\n' \
+    "$known" "$alloc_mb" "$measured" "$delta" "$floor" "$ceiling" "$base_mb"
+  if [ "$measured" -lt "$floor" ] || [ "$measured" -gt "$ceiling" ]; then
+    die "SELF-TEST FAIL — measured peak ${measured}MB is outside [${floor},${ceiling}] for a known ${known}MB allocation"
+    return 5
+  fi
+  printf 'SELF-TEST green half ok — tree measured within 30%% of a known allocation\n'
+
+  # --- red half: gut the recursion, assert the green half then goes RED --------
+  if [ "${FACTORY_PEAK_NO_RED:-0}" = "1" ]; then return 0; fi
+  local gutted
+  gutted="$(mktemp -t factory-peak-red)" || { die "SELF-TEST unrun — mktemp failed"; return 5; }
+  sed 's/^_children() { pgrep -P "\$1" 2>\/dev\/null; }$/_children() { :; }/' "$0" > "$gutted"
+  if ! grep -q '^_children() { :; }$' "$gutted"; then
+    rm -f "$gutted"
+    die "SELF-TEST unrun — could not neuter the recursion seam; the red proof did not run"
+    return 5
+  fi
+  FACTORY_PEAK_NO_RED=1 bash "$gutted" --self-test >/dev/null 2>&1
+  rc=$?
+  rm -f "$gutted"
+  if [ "$rc" -eq 0 ]; then
+    die "SELF-TEST FAIL — a copy with the child recursion REMOVED still passed."
+    die "The green half proves nothing; it is not reading the tree."
+    return 5
+  fi
+  printf 'SELF-TEST red-proof ok — recursion removed => exit %s (root only, tree unseen)\n' "$rc"
+  printf 'SELF-TEST PASS\n'
+  return 0
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pid)       PID="${2:-}"; shift 2 ;;
+    --interval)  INTERVAL="${2:-}"; shift 2 ;;
+    --until)     UNTIL_FILE="${2:-}"; shift 2 ;;
+    --seconds)   SECONDS_CAP="${2:-}"; shift 2 ;;
+    --self-test) DO_SELFTEST=1; shift ;;
+    -h|--help)   usage; exit 0 ;;
+    *)           die "unknown argument: $1"; usage; exit 64 ;;
+  esac
+done
+
+if [ "$DO_SELFTEST" -eq 1 ]; then
+  self_test
+  exit $?
+fi
+
+case "${PID:-}" in
+  ''|*[!0-9]*) usage; exit 64 ;;
+esac
+case "$INTERVAL" in ''|*[!0-9]*) die "--interval must be whole seconds"; exit 64 ;; esac
+[ "$INTERVAL" -lt 1 ] && INTERVAL=1
+if [ -n "$SECONDS_CAP" ]; then
+  case "$SECONDS_CAP" in *[!0-9]*) die "--seconds must be a whole number"; exit 64 ;; esac
+fi
+# Neither stop condition given: bound the run rather than sample forever.
+[ -z "$SECONDS_CAP" ] && [ -z "$UNTIL_FILE" ] && SECONDS_CAP=30
+
+measure
+exit $?