pi-crew 0.9.66 → 0.9.67

package/scripts/resource-sampler.mjs

@@ -0,0 +1,482 @@
+/**
+ * pi-crew resource sampler — external process monitor.
+ *
+ * Samples RSS / heap / CPU% for a PID and all its descendants, writing one
+ * JSONL line per PID per tick. Runs as a standalone external process so it
+ * works regardless of pi-crew's bundle/runtime (no src/ instrumentation).
+ *
+ * Modes:
+ *   --watch-parent <pid> [--run-id <id>] [--interval 2000] [--out <path>]
+ *       Polls <pid> + children until SIGINT/SIGTERM.
+ *   --wrap <cmd...> [--run-id <id>] [--interval 2000] [--out <path>]
+ *       Spawns <cmd>, samples it + children until exit, exits with child code.
+ *
+ * Output JSONL line: {ts,pid,ppid,label,rssBytes,heapBytes,cpuPct}
+ *
+ * Linux path uses /proc; non-Linux falls back to `ps -o rss=,pcpu=`.
+ *
+ * Run: node scripts/resource-sampler.mjs --wrap pi --version
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync, existsSync, mkdirSync, appendFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ---------- CLI parsing ----------
+// Known options may appear ANYWHERE (before or after --wrap). Everything
+// after --wrap that is NOT a known option becomes the wrapped command.
+const KNOWN_FLAGS = new Set(["--watch-parent", "--watch-run", "--crew-root", "--wrap", "--interval", "--run-id", "--out", "--no-live-warn", "-h", "--help"]);
+
+function parseArgs(argv) {
+	const args = { interval: 2000, mode: null, parentPid: null, wrap: [], runId: null, out: null, watchRun: null, crewRoot: null, liveWarn: true };
+	let wrapStarted = false;
+	for (let i = 2; i < argv.length; i++) {
+		const a = argv[i];
+		// Once --wrap is seen, collect non-flag tokens as the command. A known
+		// flag is still parsed as an option (so `--wrap sleep 5 --interval 500`
+		// works), but an unknown token is treated as part of the command.
+		if (wrapStarted && !KNOWN_FLAGS.has(a)) {
+			args.wrap.push(a);
+			continue;
+		}
+		if (a === "--watch-parent") {
+			args.mode = "watch";
+			args.parentPid = Number.parseInt(argv[++i], 10);
+		} else if (a === "--watch-run") {
+			// auto-resolve the run's leader/runner PID from pi-crew state (no manual
+			// pgrep). Reads async.pid / manifest.async.pid / heartbeat.json.
+			args.mode = "watch";
+			args.watchRun = argv[++i];
+			if (!args.runId) args.runId = args.watchRun;
+		} else if (a === "--crew-root") {
+			args.crewRoot = argv[++i];
+		} else if (a === "--wrap") {
+			args.mode = "wrap";
+			wrapStarted = true;
+		} else if (a === "--interval") {
+			// R13 (audit): reject NaN and clamp tiny intervals — setInterval(fn, 0)
+			// or setInterval(fn, NaN) spins ~60-130×/s, writing huge files and
+			// burning CPU (each tick also scans all of /proc).
+			const raw = argv[++i];
+			const parsed = Number.parseInt(raw, 10);
+			if (Number.isNaN(parsed)) {
+				process.stderr.write(`Error: --interval must be a number (ms), got "${raw}"\n`);
+				process.exit(1);
+			}
+			if (parsed < 100) {
+				process.stderr.write(`[resource-sampler] --interval ${parsed}ms < 100ms; clamping to 100ms\n`);
+				args.interval = 100;
+			} else {
+				args.interval = parsed;
+			}
+		} else if (a === "--run-id") {
+			args.runId = argv[++i];
+		} else if (a === "--out") {
+			args.out = argv[++i];
+		} else if (a === "--no-live-warn") {
+			args.liveWarn = false;
+		} else if (a === "-h" || a === "--help") {
+			printHelp();
+			process.exit(0);
+		} else if (wrapStarted) {
+			// unknown token after --wrap → part of the command
+			args.wrap.push(a);
+		}
+	}
+	if (!args.mode) {
+		printHelp();
+		process.exit(1);
+	}
+	return args;
+}
+
+function printHelp() {
+	process.stderr.write(
+		[
+			"Usage:",
+			"  resource-sampler.mjs --watch-parent <pid> [--run-id <id>] [--interval 2000] [--out <path>]",
+			"  resource-sampler.mjs --wrap <cmd...> [--run-id <id>] [--interval 2000] [--out <path>]",
+			"",
+		].join("\n"),
+	);
+}
+
+// ---------- /proc readers (Linux) ----------
+const CLK_TCK = 100; // sysconf(_SC_CLK_TCK) on essentially all Linux/x86/arm
+
+function readProcStat(pid) {
+	// /proc/<pid>/stat — comm (field 2) may contain spaces inside parens.
+	let raw;
+	try {
+		raw = readFileSync(`/proc/${pid}/stat`, "utf8");
+	} catch {
+		return null;
+	}
+	const open = raw.indexOf("(");
+	const close = raw.lastIndexOf(")");
+	if (open < 0 || close < 0) return null;
+	const comm = raw.slice(open + 1, close);
+	const rest = raw.slice(close + 2).trim().split(/\s+/);
+	// rest[0] = field3 (state), rest[1] = field4 (ppid), rest[11] = utime(f14), rest[12] = stime(f15), rest[19] = starttime(f22)
+	return {
+		pid,
+		comm,
+		state: rest[0],
+		ppid: Number.parseInt(rest[1], 10) || 0,
+		utime: Number.parseInt(rest[11], 10) || 0,
+		stime: Number.parseInt(rest[12], 10) || 0,
+		starttime: Number.parseInt(rest[19], 10) || 0,
+	};
+}
+
+function readProcStatus(pid) {
+	let raw;
+	try {
+		raw = readFileSync(`/proc/${pid}/status`, "utf8");
+	} catch {
+		return null;
+	}
+	let rssKb = 0;
+	let dataKb = 0;
+	for (const line of raw.split("\n")) {
+		if (line.startsWith("VmRSS:")) rssKb = Number.parseInt(line.slice(6).trim(), 10) || 0;
+		else if (line.startsWith("VmData:")) dataKb = Number.parseInt(line.slice(7).trim(), 10) || 0;
+	}
+	return { rssKb, dataKb };
+}
+
+// ---------- fallback via ps (non-Linux) ----------
+function readPs(pid) {
+	const res = spawnSync("ps", ["-o", "rss=,pcpu=", "-p", String(pid)], { encoding: "utf8" });
+	if (res.status !== 0 || !res.stdout.trim()) return null;
+	const parts = res.stdout.trim().split(/\s+/);
+	return {
+		pid,
+		ppid: 0,
+		rssKb: Number.parseInt(parts[0], 10) || 0,
+		dataKb: 0,
+		cpuPct: Number.parseFloat(parts[1]) || 0,
+		ps: true,
+	};
+}
+
+// ---------- child discovery ----------
+function findDescendants(rootPid) {
+	// BFS over /proc to find all PIDs whose ppid chain leads to rootPid.
+	if (!existsSync("/proc")) return [rootPid];
+	const all = [];
+	try {
+		for (const name of readdirSync("/proc")) {
+			if (/^\d+$/.test(name)) all.push(Number.parseInt(name, 10));
+		}
+	} catch {
+		return [rootPid];
+	}
+	const ppidOf = new Map();
+	for (const pid of all) {
+		const s = readProcStat(pid);
+		if (s) ppidOf.set(pid, s.ppid);
+	}
+	const result = new Set([rootPid]);
+	let frontier = [rootPid];
+	while (frontier.length) {
+		const next = [];
+		for (const [pid, ppid] of ppidOf) {
+			if (result.has(ppid) && !result.has(pid)) {
+				result.add(pid);
+				next.push(pid);
+			}
+		}
+		frontier = next;
+	}
+	return [...result];
+}
+
+// ---------- sampling ----------
+const cpuPrev = new Map(); // pid -> {ticks, ts}
+
+// ---- live anomaly warnings (stderr, rate-limited) ----
+// Emitted DURING sampling so the user sees resource anomalies in real time,
+// not only in the post-hoc analyze-run report. Rate-limited per (pid,category)
+// so a sustained spike doesn't spam every tick.
+const rssPrev = new Map(); // pid -> { rss, ts } (for one-interval RSS jump)
+const rssHist = new Map(); // pid -> number[] (recent rssBytes, for slow-leak trend)
+const warnCooldown = new Map(); // `${pid}:${cat}` -> last emit ts
+const LIVE_CPU_PCT = 300; // single-process CPU% (multi-core: 300% = 3 cores)
+const LIVE_RSS_JUMP = 200_000_000; // +200MB in one interval (fast spike)
+const LIVE_RSS_HIGH = 1_000_000_000; // 1GB absolute
+const LIVE_LEAK_WINDOW = 30; // samples to evaluate slow-leak trend (30s at 1s interval)
+const LIVE_LEAK_GROWTH = 100_000_000; // +100MB net over the window = leak
+const LIVE_LEAK_MONOTONIC = 0.75; // ≥75% of pairs increasing = monotonic-ish
+const WARN_COOLDOWN_MS = 10_000;
+let liveWarnEnabled = true;
+function liveWarn(pid, label, cat, msg) {
+	if (!liveWarnEnabled) return;
+	const key = `${pid}:${cat}`;
+	const now = Date.now();
+	if (now - (warnCooldown.get(key) || 0) < WARN_COOLDOWN_MS) return;
+	warnCooldown.set(key, now);
+	process.stderr.write(`[resource-sampler] ⚠️ LIVE ${new Date(now).toISOString().slice(11, 19)} ${cat} pid=${pid}${label ? ` (${label})` : ""}: ${msg}\n`);
+}
+
+function samplePid(pid, rootPid) {
+	// Linux /proc path
+	if (existsSync(`/proc/${pid}/stat`)) {
+		const stat = readProcStat(pid);
+		const status = readProcStatus(pid);
+		if (!stat) return null;
+		const now = Date.now();
+		const ticks = stat.utime + stat.stime;
+		let cpuPct = 0;
+		const prev = cpuPrev.get(pid);
+		// firstSample: no usable baseline yet (first-ever sample OR PID reused).
+		// cpuPct is 0 here by construction — consumers should exclude it from CPU
+		// averages so short-lived subagents aren't dragged down by the first tick.
+		const firstSample = !prev || prev.starttime !== stat.starttime;
+		// PID-reuse guard: if starttime changed, a NEW process recycled this PID
+		// (common under respawn churn) — the old cpuPrev ticks are stale and would
+		// underreport. Treat as a first sample (cpuPct=0) and reset the baseline.
+		if (!firstSample) {
+			const dtick = ticks - prev.ticks;
+			const dsec = (now - prev.ts) / 1000;
+			if (dsec > 0) cpuPct = (dtick / CLK_TCK / dsec) * 100;
+		}
+		cpuPrev.set(pid, { ticks, ts: now, starttime: stat.starttime });
+		return {
+			ts: now,
+			pid,
+			ppid: stat.ppid,
+			label: pid === rootPid ? "root" : "child",
+			rssBytes: status ? status.rssKb * 1024 : 0,
+			heapBytes: status ? status.dataKb * 1024 : 0,
+			cpuPct: Math.max(0, Math.round(cpuPct * 10) / 10),
+			firstSample,
+		};
+	}
+	// fallback: ps
+	const ps = readPs(pid);
+	if (!ps) return null;
+	return {
+		ts: Date.now(),
+		pid,
+		ppid: ps.ppid,
+		label: pid === rootPid ? "root" : "child",
+		rssBytes: ps.rssKb * 1024,
+		heapBytes: 0,
+		cpuPct: Math.round(ps.cpuPct * 10) / 10,
+	};
+}
+
+function tick(rootPid, outPath) {
+	const pids = findDescendants(rootPid);
+	const seen = new Set(pids);
+	for (const pid of pids) {
+		const sample = samplePid(pid, rootPid);
+		if (sample) {
+			appendFileSync(outPath, JSON.stringify(sample) + "\n");
+			// live anomaly checks (rate-limited, stderr) — real-time observability
+			// zombie/dead child still in /proc (parent not reaping) — flag it live
+			if (pid !== rootPid && !isAlive(pid)) liveWarn(pid, sample.label, "proc_zombie", "process zombie/dead (state Z/X) — parent not reaping child");
+			if (sample.cpuPct >= LIVE_CPU_PCT) liveWarn(pid, sample.label, "high_cpu", `CPU ${sample.cpuPct}% (≥${LIVE_CPU_PCT}%)`);
+			const rp = rssPrev.get(pid);
+			if (rp) {
+				const jump = sample.rssBytes - rp.rss;
+				if (jump >= LIVE_RSS_JUMP) liveWarn(pid, sample.label, "rss_jump", `RSS +${(jump / 1024 / 1024).toFixed(0)}MB (${(rp.rss / 1024 / 1024).toFixed(0)}→${(sample.rssBytes / 1024 / 1024).toFixed(0)}MB) in one interval`);
+			}
+			rssPrev.set(pid, { rss: sample.rssBytes, ts: sample.ts });
+			if (sample.rssBytes >= LIVE_RSS_HIGH) liveWarn(pid, sample.label, "rss_high", `RSS ${(sample.rssBytes / 1024 / 1024).toFixed(0)}MB (≥1GB)`);
+			// slow-leak trend: gradual monotonic growth that no single-interval jump
+			// catches (e.g. +5MB/interval × 50). LONG window (30 samples) so warmup
+			// growth (V8 heap fill ~10-15s then plateau) does NOT fire — only
+			// SUSTAINED growth (30s+) is a leak signal. Validated on real e2e data:
+			// subagent warmup plateaus (no fire), long-lived session growth fires.
+			const h = rssHist.get(pid) || [];
+			h.push(sample.rssBytes);
+			if (h.length > LIVE_LEAK_WINDOW) h.shift();
+			rssHist.set(pid, h);
+			if (h.length >= LIVE_LEAK_WINDOW) {
+				const growth = h[h.length - 1] - h[0];
+				let inc = 0;
+				for (let i = 1; i < h.length; i++) if (h[i] > h[i - 1]) inc++;
+				if (growth >= LIVE_LEAK_GROWTH && inc / (h.length - 1) >= LIVE_LEAK_MONOTONIC) {
+					liveWarn(pid, sample.label, "rss_leak", `slow RSS leak +${(growth / 1024 / 1024).toFixed(0)}MB over ${h.length} samples (${(h[0] / 1024 / 1024).toFixed(0)}→${(h[h.length - 1] / 1024 / 1024).toFixed(0)}MB, monotonic) — possible memory leak`);
+				}
+			}
+		} else {
+			rssPrev.delete(pid);
+			rssHist.delete(pid);
+		}
+	}
+	// F4 (audit): prune cpuPrev entries for PIDs no longer alive — prevents the
+	// Map from accumulating stale entries for short-lived children over a long
+	// sampling session.
+	for (const pid of cpuPrev.keys()) {
+		if (!seen.has(pid)) {
+			cpuPrev.delete(pid);
+			rssPrev.delete(pid);
+			rssHist.delete(pid);
+		}
+	}
+	// prune warnCooldown for gone PIDs (keep rootPid entry)
+	for (const key of warnCooldown.keys()) {
+		const pid = Number(key.split(":")[0]);
+		if (!seen.has(pid) && pid !== rootPid) warnCooldown.delete(key);
+	}
+}
+
+// R4/sampler-test (audit): robust liveness — a process that exited but whose
+// parent can't reap it yet is a ZOMBIE, and /proc/<pid>/stat still exists for
+// zombies. Checking only file existence would never detect death in that
+// case. Treat state 'Z' (zombie) and 'X' (dead) as not-alive.
+function isAlive(pid) {
+	if (existsSync("/proc")) {
+		const stat = readProcStat(pid);
+		if (!stat) return false;
+		return stat.state !== "Z" && stat.state !== "X";
+	}
+	return readPs(pid) != null;
+}
+// Resolve a run's leader/runner PID from pi-crew state. Tries async.pid (a
+// dedicated JSON file), manifest.async.pid, and heartbeat.json.pid. Polls
+// briefly (the file may not exist the instant the run starts).
+function resolveRunnerPid(runDir) {
+	const readJsonSafe = (p) => {
+		try {
+			return JSON.parse(readFileSync(p, "utf8"));
+		} catch {
+			return null;
+		}
+	};
+	for (let i = 0; i < 20; i++) {
+		const asyncPid = readJsonSafe(join(runDir, "async.pid"));
+		if (asyncPid && typeof asyncPid.pid === "number") return asyncPid.pid;
+		const manifest = readJsonSafe(join(runDir, "manifest.json"));
+		if (manifest && manifest.async && typeof manifest.async.pid === "number") return manifest.async.pid;
+		const hb = readJsonSafe(join(runDir, "heartbeat.json"));
+		if (hb && typeof hb.pid === "number") return hb.pid;
+		// R7 (audit): block-wait instead of spawning a throwaway node process
+		// every poll. Atomics.wait on the main thread is permitted in Node.
+		const waitBuf = new Int32Array(new SharedArrayBuffer(4));
+		Atomics.wait(waitBuf, 0, 0, 500);
+	}
+	return null;
+}
+function main() {
+	const args = parseArgs(process.argv);
+	liveWarnEnabled = args.liveWarn;
+	const outDir = join(process.cwd(), "bench", "results");
+	mkdirSync(outDir, { recursive: true });
+	const outFile =
+		args.out ||
+		join(outDir, `${args.runId || "wrap-" + Date.now()}.resources.jsonl`);
+	process.stderr.write(`[resource-sampler] writing → ${outFile}\n`);
+
+	if (args.mode === "wrap") {
+		if (args.wrap.length === 0) {
+			process.stderr.write("--wrap requires a command\n");
+			process.exit(1);
+		}
+		const child = spawn(args.wrap[0], args.wrap.slice(1), { stdio: "inherit" });
+		const rootPid = child.pid;
+		let exited = false;
+		// sample immediately, then on interval
+		tick(rootPid, outFile);
+		const handle = setInterval(() => tick(rootPid, outFile), args.interval);
+		const cleanup = () => {
+			clearInterval(handle);
+			// F3 (audit): kill the wrapped child so it is not orphaned when the
+			// sampler is signalled (SIGINT/SIGTERM). tryKill is best-effort.
+			try {
+				if (!exited) child.kill("SIGTERM");
+			} catch {
+				/* already gone */
+			}
+		};
+		process.on("SIGINT", () => {
+			cleanup();
+			process.exit(130);
+		});
+		process.on("SIGTERM", () => {
+			cleanup();
+			process.exit(143);
+		});
+		child.on("exit", (code, signal) => {
+			exited = true;
+			clearInterval(handle);
+			// final sample
+			tick(rootPid, outFile);
+			process.stderr.write(`[resource-sampler] child exited code=${code} signal=${signal}\n`);
+			process.exit(code ?? 1);
+		});
+	} else {
+		// watch-parent (or --watch-run, which resolves the runner PID from state)
+		let rootPid = args.parentPid;
+		if (args.watchRun) {
+			const crew = args.crewRoot || join(process.env.HOME || "/home/bom", ".crew");
+			const runDir = join(crew, "state", "runs", args.watchRun);
+			rootPid = resolveRunnerPid(runDir);
+			if (!rootPid) {
+				process.stderr.write(`--watch-run: could not resolve runner PID for ${args.watchRun} in ${runDir} (async.pid / manifest.async.pid / heartbeat.json)\n`);
+				process.exit(1);
+			}
+			process.stderr.write(`[resource-sampler] --watch-run ${args.watchRun} → runner PID ${rootPid}\n`);
+		}
+		if (!rootPid) {
+			process.stderr.write("--watch-parent requires a PID\n");
+			process.exit(1);
+		}
+		// R4 (audit): auto-stop when the watched tree dies. Previously the sampler
+		// kept ticking forever (writing nothing) after rootPid exited, until the
+		// user remembered to Ctrl-C. Now: if rootPid is not alive for 3
+		// consecutive ticks, stop cleanly. rootPid (the team leader) outlives the
+		// whole run, so its death = run over.
+		// PLUS (perf-obs): in --watch-run mode the runner PID may be the
+		// long-lived foreground pi process (sync runs) — it stays alive after the
+		// run, so ALSO stop when the run's manifest.json reaches a terminal
+		// status (completed/failed/cancelled/blocked).
+		const runDir = args.watchRun ? join(args.crewRoot || join(process.env.HOME || "/home/bom", ".crew"), "state", "runs", args.watchRun) : null;
+		const runIsTerminal = () => {
+			if (!runDir) return false;
+			try {
+				const m = JSON.parse(readFileSync(join(runDir, "manifest.json"), "utf8"));
+				return ["completed", "failed", "cancelled", "blocked"].includes(m.status);
+			} catch {
+				return false;
+			}
+		};
+		let deadTicks = 0;
+		const tickWatch = () => {
+			const alive = isAlive(rootPid);
+			if (alive) {
+				deadTicks = 0;
+				if (runIsTerminal()) {
+					if (handle) clearInterval(handle);
+					process.stderr.write(`[resource-sampler] run ${args.watchRun} reached terminal status — stopping\n`);
+					process.exit(0);
+				}
+				tick(rootPid, outFile);
+			} else {
+				deadTicks++;
+				if (deadTicks === 1) liveWarn(rootPid, "root", "proc_died", `watched PID ${rootPid} no longer alive`);
+				if (deadTicks >= 3) {
+					clearInterval(handle);
+					process.stderr.write(`[resource-sampler] watched PID ${rootPid} gone — stopping\n`);
+					process.exit(0);
+				}
+			}
+		};
+		let handle;
+		tickWatch();
+		handle = setInterval(tickWatch, args.interval);
+		const shutdown = () => {
+			clearInterval(handle);
+			tick(rootPid, outFile);
+			process.stderr.write("[resource-sampler] stopped\n");
+			process.exit(0);
+		};
+		process.on("SIGINT", shutdown);
+		process.on("SIGTERM", shutdown);
+	}
+}
+
+main();

package/skills/real-test-pi-crew/SKILL.md

@@ -110,7 +110,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 
 ---
 
-## Tier 1 — Critical unit tests (~21s, 97 tests, the only suite you need for broker/UI changes)
+## Tier 1 — Critical unit tests (~25s, 101 tests, the only suite you need for broker/UI changes)
 
 **What**: run the curated 14-file fast subset.
 
@@ -122,7 +122,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 time npm run test:critical
 ```
 
-Expected output: `# tests 97 # pass 97 # fail 0 # duration_ms ~21000`.
+Expected output: `# tests 101 # pass 101 # fail 0 # duration_ms ~26000`. (Count was 97 at v0.9.46; 101 since the model-routing merge — verify with the actual run; the skill's hard-coded numbers drift between releases.)
 
 **References**:
 
@@ -162,7 +162,7 @@ PI_CREW_BROKER=0 npm run test:critical
 PI_CREW_BROKER=1 npm run test:critical
 ```
 
-All three must show `# pass 97 # fail 0`. Measured times in this session: ~20s for default and `PI_CREW_BROKER=0`, ~21s for `PI_CREW_BROKER=1` (varies ±1s run-to-run).
+All three must show `# pass 101 # fail 0`. Measured times in this session (2026-08-11): ~26s for default, ~26s for `PI_CREW_BROKER=0`, ~26s for `PI_CREW_BROKER=1` (varies ±1-2s run-to-run).
 
 **References**:
 
@@ -202,7 +202,7 @@ Compare the printed md5 against what the user's Pi session loaded. If they diffe
 | Bundle builder | `scripts/build-bundle.mjs` (esbuild-based, bundles `index.bundle.ts` → `dist/index.mjs`) |
 | Bundle resolution rule | `index.ts:5-22` (entrypoint docstring); also `scripts/build-bundle.mjs:14-20` (entrypoint preference); **symlink is live for source files but the bundled `dist/index.mjs` is loaded** |
 | Postinstall hook | `scripts/postinstall.mjs:43` — best-effort bundle rebuild; falls back to strip-types if esbuild missing |
-| Bundle md5 after Phase-4 commit | `1cc4d55e18add7b9a036c569143320b6` (~2.78 MB at the time; bundle size drifts ±5% between releases, check current `ls -la dist/index.mjs`) |
+| Bundle md5 after Phase-4 commit | `1cc4d55e18add7b9a036c569143320b6` (~2.78 MB at the time; **check current**: `md5sum dist/index.mjs`. As of v0.9.66 I-batch 2026-08-11: `16e29d053bd370e24f40df147dadcb79` ~2.81 MB) |
 
 ---
 
@@ -454,7 +454,7 @@ If the two md5s match → session is on the latest code. If not → user must `/
 
 **Real measured outcome** (this session, after the v0.9.57 schema fix): 9a (15 team actions) + 9b (4 subagent tools / 3 run paths) exercised; all green; the two silent-failure modes that motivated this tier (`Unknown type` from `Type.Unsafe` without Kind, and `Validation failed for tool team` from empty-string-strict schema) were caught ONLY by this battery — Tier 1-8 all passed while the team tool was broken live. The session also surfaced the unauthorized-agent-edit anti-pattern (a chain-run agent edited `chain-runner.ts` mid-smoke) — see Anti-patterns.
 
-**Not covered by the cheap battery above** — the actions below need extra setup, cost, or user confirmation. Run them only when the change touches their code path, and prefer a throwaway cwd / config so you don't mutate the user's real state. Organised by cost/safety:
+**Not covered by the cheap battery above** — the actions below need extra setup, cost, or user confirmation. Run them only when the change touches their code path, and prefer a throwaway cwd / config so you don't mutate the user's real state. Organised by cost/safety. **As of 2026-08-11 (extended battery, run report `real-test-2026-08-11-scratchpad-I-batch.md`), 9c/9e/9f have been exercised live once each — they are no longer unproven, but still require explicit scope+confirmation to re-run.**
 
 **9c. Lifecycle / recovery** (needs a *running* run — start an async run, then exercise these against its runId):
 - `team action='wait' runId='...'` — block until completion
@@ -508,9 +508,10 @@ If the two md5s match → session is on the latest code. If not → user must `/
 | `makeFakeCtx({ flagOn: false })` without `brokerEnv: "0"` | `makeFakeCtx` deletes `PI_CREW_BROKER` env if `brokerEnv` is undefined | `612e18b` (test fix) | `test/unit/crew-broker-server-gate.test.ts:78` — pass `brokerEnv: "0"` to preserve env |
 | Trust green CI on one OS | macOS/Windows regressions slip through | n/a (permanent) | `.crew/knowledge.md` — "CI runs 3 OSes ... A flake on one OS IS a real bug" |
 | Trusting a team-run agent not to edit the repo under test | Agents spawned by `team`/`Agent`/`crew_agent` inherit the session cwd and have `edit`/`write` tools — a proactive LLM (observed with deepseek) will make **unauthorized source edits** to pi-crew during a trivial smoke run (e.g. "improving" `chain-runner.ts` while parsing a chain string). The edit can be correct + green-tested yet still be unintended scope creep that silently lands in your commit. | n/a (permanent) | After EVERY team/subagent run: `git status` and verify each changed file was authored by you. Diff + review any surprise change before staging. Consider `workspaceMode: 'worktree'` for parallel/risky runs to isolate mutations. |
+| **Armed-role tool-surface bug (found live 2026-08-11)**: an opt-in tool (e.g. `scratchpad`) is armed via `ROLE_TOOL_CONFIGS[role].scratchpad=true` AND env `PI_CREW_SCRATCHPAD=1`, but NEVER appears in the worker surface. Root cause: `resolveToolPolicy` (`src/agents/agent-config.ts:165`) falls back `roleConfig.tools ?? agent.tools` when the role has no `tools` allowlist, and the builtin `agents/{executor,verifier,test-engineer}.md` frontmatter `tools:` did not list `scratchpad` → pi got `--tools read,grep,find,ls,bash,edit,write` and **hard-filtered** scratchpad. Env was correct; the tool was silently dropped by the `--tools` allowlist. Reproduce: `pi -p --tools read,grep,find,ls,bash,edit,write "list tools"` → no scratchpad; with scratchpad added → present. | `f753be30` | **Fix**: keep armed-role `agents/*.md` frontmatter `tools:` lists in sync with `ROLE_TOOL_CONFIGS` (QW17 pins the pinned roles; add the new tool to BOTH frontmatter AND role config for pinned roles, frontmatter-only for vacuous roles). A smoke run that claims the tool is "not available" in the worker is a REAL signal — verify the worker's actual `--tools` allowlist, not just env vars. |
 | `Type.Unsafe({ anyOf/type })` schema field **without** `[TypeBox.Kind]` symbol | `Value.Check` throws `Unknown type` the first time a model emits that field (e.g. `skill`, `config`) — every team action returns `isError:true` text `"Unknown type"`. Tier 1-8 stay green because unit tests never send the offending field. | v0.9.57 | `src/schema/team-tool-schema.ts` — `SkillOverride`/`FreeformConfig` switched from `Type.Unsafe` to TypeBox-native `Type.Union`/`Type.Record`. See Tier 9. |
 | Schema too strict for model-emitted empty strings (`runId:""`, `workspaceMode:""`, `budgetTotal:0`) | pi-ai `validateToolArguments` runs BEFORE the pi-crew handler and rejects `""` against Literal unions / patterns → `Validation failed for tool team` → model loops. | v0.9.57 | `src/schema/team-tool-schema.ts` — added `Literal("")` to unions, `^$|` pattern for runId, `""` to action enum, `0`/Boolean allowances. Handler-side `normalizeTeamParams` drops the empties. |
-| Claiming "all 9 tiers pass" while 9c–9f were never run | Overclaim — once reported "9 tiers pass" when only 9a (8/10) + 9b (4/5) had actually run; 9c–9f were skipped. Past runs then become unverifiable ("did it really pass 9 tiers?"). | n/a (process) | Fill `REPORT-TEMPLATE.md` per-tier DURING the run. "Tier 9 pass" = 9a AND 9b AND the applicable 9c–9f, each with evidence. Round-up-to-pass is the anti-pattern this row exists to prevent. |
+| Claiming "all 9 tiers pass" while 9c–9f were never run | Overclaim — once reported "9 tiers pass" when only 9a (8/10) + 9b (4/5) had actually run; 9c–9f were skipped. Past runs then become unverifiable ("did it really pass 9 tiers?"). **2026-08-11 repeat**: an initial report said "9c–9f skipped" yet the summary read as full coverage until the gap was called out. | n/a (process) | Fill `REPORT-TEMPLATE.md` per-tier DURING the run. "Tier 9 pass" = 9a AND 9b AND the applicable 9c–9f, each with evidence. Round-up-to-pass is the anti-pattern this row exists to prevent. If 9c–9f are skipped, SAY SO in the verdict and do not phrase it as "all pass". |
 | chain run with `workflow:"chain"` forwarded to steps | Every chain step fails in ~58ms with an EMPTY error string — looks like a parse failure but isn't. `chain-dispatch` forwards `params.workflow` ("chain") into executor overrides; each step then runs the "chain" workflow via the normal `executeTeamRun` path and fails fast + silently. | Open (issue #44) | Omit `workflow` when invoking `action:'run' chain=...` — chain then runs 2/2 success (~308s). See `docs/bugs/chain-workflow-forward-quirk.md`. |
 
 ---
@@ -648,7 +649,7 @@ The skill does NOT need to be updated for every commit — only when the cited l
 ## Quick reference — exact commands
 
 ```bash
-# Tier 1 (critical unit, ~21s, 97 tests)
+# Tier 1 (critical unit, ~25s, 101 tests)
 npm run test:critical
 # Tier 2 (3-path proof, broker changes only)
 PI_CREW_BROKER=0 npm run test:critical
@@ -687,14 +688,14 @@ md5sum "$(npm root -g)"/pi-crew/dist/index.mjs 2>/dev/null \
 
 Before claiming "tested":
 
-- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, 101 after the model-routing merge; record the actual count in the report.
+- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, **101 since the model-routing merge (v0.9.66)**; record the actual count in the report.
 - [ ] Tier 2: 3-path proof all pass — **required if you touched `src/config/defaults.ts` or `src/extension/registration/lifecycle-handlers.ts`**
 - [ ] Tier 3: `npm run typecheck` exit 0, `npm run build:bundle` exit 0
 - [ ] Tier 4: bundle md5 matches what the session loaded (or user has `/quit`-ed + reopened)
 - [ ] Tier 5/6: live TUI smoke for any `src/ui/` change — keystroke reached `handleInput`
 - [ ] Tier 7: smoke team run for any `src/runtime/plan-templates.ts` or `workflows/*.workflow.md` change — completed, no hang, verifier output under 60s
 - [ ] Tier 8: final md5 sync check passed
-- [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, or any `Type.Unsafe({...})` schema**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
+- [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, any `Type.Unsafe({...})` schema, or any armed-role tool list (`agents/*.md` / `src/config/role-tools.ts`)**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; **at least one full 9c/9e/9f sweep per release is recommended so the battery stays proven** (see `real-test-2026-08-11-scratchpad-I-batch.md`); 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
 - [ ] **Output report**: save `docs/real-test/reports/real-test-<YYYY-MM-DD>-<slug>.md` from `skills/real-test-pi-crew/REPORT-TEMPLATE.md`, filled DURING the run with per-tier evidence (counts/md5/runId) — not reconstructed from memory afterward. This is what makes past runs verifiable instead of trust-the-summary.
 
 **"All 9 tiers pass" is a claim that needs per-row evidence.** Tier 9 means 9a **and** 9b **and** whichever of 9c–9f applies to the change — not "9a passed, therefore 9 passed". If any required item above is unchecked or lacks concrete evidence (a number, an md5, a runId), the answer to "is it tested?" is **no** — say so explicitly instead of rounding up to "pass".

package/src/config/role-tools.ts

@@ -84,7 +84,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// agents/verifier.md). Tool-set keeps bash but excludes edit/write so source
 	// integrity is preserved during verification. Mirrors cold-verifier behavior.
 	verifier: {
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", "bash", "scratchpad"],
 		excludeTools: ["edit", "write", "web"],
 		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
 		scratchpad: true,
@@ -92,7 +92,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
-		tools: ["read", "edit", "write", "bash", "ls"],
+		tools: ["read", "edit", "write", "bash", "ls", "scratchpad"],
 		excludeTools: ["web"],
 		// Phase 1 scratchpad: build/run test suites with state across cells.
 		scratchpad: true,

package/src/extension/knowledge-injection.ts

@@ -301,6 +301,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
 			}
 			knowledgeCache.set(p, { key: cacheKey, content });
+			enforceKnowledgeCacheCap(knowledgeCache);
 			return content;
 		}
 
@@ -325,6 +326,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 				conventions: parsed.conventions,
 				sessionLog: parsed.sessionLog,
 			});
+			enforceKnowledgeCacheCap(sectionCache);
 		}
 
 		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
@@ -382,6 +384,21 @@ interface CachedSections {
 }
 const sectionCache = new Map<string, CachedSections>();
 
+// H6 (2026-08-10): FIFO cap — mirrors the discover-* caches
+// (TEAM_DISCOVERY_MAX_ENTRIES = 32, WORKFLOW_DISCOVERY_MAX_ENTRIES = 32).
+// Without this, the caches grow with every distinct project root seen by the
+// process; each entry can be KB-scale (full knowledge.md content + parsed
+// sections). Eviction is safe: a cache miss falls through to a fresh
+// readFileSync + parse, same as the first call for that path.
+const KNOWLEDGE_CACHE_MAX_ENTRIES = 64;
+
+function enforceKnowledgeCacheCap(cache: Map<string, unknown>): void {
+	if (cache.size > KNOWLEDGE_CACHE_MAX_ENTRIES) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== undefined) cache.delete(oldest);
+	}
+}
+
 /** Head cap for the no-query (legacy / main-session) path. */
 const MAX_KNOWLEDGE_HEAD_BYTES = 2_000;
 

package/src/extension/pi-api.ts

@@ -38,19 +38,3 @@ export type {
 } from "@earendil-works/pi-coding-agent";
 
 export { createBashTool, defineTool } from "@earendil-works/pi-coding-agent";
-
-/**
- * @deprecated Drift detector removed in Phase 5 follow-up to H1.
- *
- * History: this constant was meant to surface version-drift between
- * dev-time type-check and runtime peer-dep version. pi-crew declares
- * peer deps as `*` so the runtime version is set by whatever host pi
- * install the user has — pinning this constant to a specific devDep
- * range was a false invariant that did not reflect how extensions
- * actually consume peer packages.
- *
- * Kept exported (now `"0.0.0-unset"`) only for any downstream consumers
- * that may import it via re-exports. No diagnostic uses it anymore.
- * Will be removed in a future major version.
- */
-export const BUILT_AGAINST_PI_VERSION = "0.0.0-unset";