@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/stored-text/skills/render-stored-text/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: render-stored-text
+description: Use when a page shows text from a database, when markdown, code or line endings look wrong on a page, or when stored-text checks refuse a write.
+---
+
+# Build and prove the one renderer for stored text
+
+<constraints>
+Always do:
+1. Look for `stored-text.*` first. If it exists, call it.
+2. Otherwise create it, choosing the libraries with `latest-versions`. Next.js or React: one `<StoredText source={...} />` server component (a markdown component with sanitize and highlight plugins), so no `dangerouslySetInnerHTML` is needed. Server-rendered templates: `renderStored(text): string`, inserted with the template's explicit raw form.
+3. Keep the steps in order: `text.replace(/\r\n?/g, '\n')`; markdown with raw HTML off; highlight; sanitize last, allowing the highlighter's classes and spans, and no `style`, `script` or event attribute. Links get `rel="noopener noreferrer"`, and only `http`, `https` and `mailto` survive.
+4. For a tool's or terminal's output, give the renderer a second mode: a fenced plain block, where each line keeps only what follows its last `\r`.
+5. Give the code block its look in the stylesheet: a highlight theme from the design tokens, `overflow-x: auto`, and `white-space: pre-wrap` for prose that keeps its breaks.
+6. Prove it with one fixture row, in a test and on the rendered page:
+   - `a\r\nb\rc` shows three lines and no stray character;
+   - `**bold**` and a list render as markup;
+   - a ```` ```ts ```` block has token spans, and a ```` ```nosuchlang ```` block is plain and escaped;
+   - `<script>alert(1)</script>`, `<img src=x onerror=alert(1)>` and `[x](javascript:alert(1))` come out harmless.
+
+Never do:
+- Add a second path for "just this one page".
+- Call a page done without opening it with the fixture row.
+</constraints>

package/packs/synth-creator/checks/timing-from-synthcore.json

@@ -0,0 +1,24 @@
+{
+  "id": "timing-from-synthcore",
+  "why": "Tempo, MIDI clock and transport are written once, in synthcore. A unit that reads the play head or counts clock bytes itself is a second clock, and two clocks drift. Go through core::CoreHost.",
+  "rule": ".claude/rules/timing-from-synthcore.md",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/probes/**",
+    "**/build/**",
+    "**/_deps/**",
+    "**/JUCE/**"
+  ],
+  "pattern": "\\bgetPlayHead\\s*\\(\\s*\\)\\s*(?:->|\\.)|\\bisMidiClock\\s*\\(",
+  "code": true,
+  "bad": "const auto pos = getPlayHead()->getPosition();",
+  "good": "host.readTransport (getPlayHead(), midi, n);"
+}

package/packs/synth-creator/checks/ui-drawn-in-code.json

@@ -0,0 +1,23 @@
+{
+  "id": "ui-drawn-in-code",
+  "why": "Nothing is pre-rendered: the UI is drawn in code, so it scales to any size and a control changes in one place. No images, sprites or embedded assets.",
+  "globs": [
+    "**/*.cpp",
+    "**/*.cc",
+    "**/*.h",
+    "**/*.hpp",
+    "**/*.mm"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/probes/**",
+    "**/build/**",
+    "**/_deps/**",
+    "**/JUCE/**"
+  ],
+  "pattern": "\\bdrawImage(?:At|Within|Transformed)?\\s*\\(|\\bImageCache::|\\bBinaryData::|\\bImageFileFormat::",
+  "code": true,
+  "bad": "g.drawImageAt (ImageCache::getFromMemory (BinaryData::knob_png, BinaryData::knob_pngSize), 0, 0);",
+  "good": "g.fillEllipse (bounds.reduced (2.0f));"
+}

package/packs/synth-creator/hooks/build-guard.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// build-guard (PreToolUse, Bash): no heavy job takes the whole machine.
+//
+// "nothing should be able to take the entire system". Five agents each compiling with -j18 at once put
+// ~90 jobs on 18 cores and every build took hours. Every compile and test run goes through the machine-wide queue
+// ~/.claude/bin/buildq (two at a time). This refuses (exit 2) a heavy command started any other way, a polling loop, an
+// agent's build or test run of everything, and any build from an agent started as `KIND: light`
+// (~/.claude/agent-cap-state.json keeps the kinds).
+//
+// Allowed: a command run as `buildq <cmd>` (or `~/.claude/bin/buildq <cmd>`), or through a project's own wrapper that
+// calls buildq (for example `bash tools/build.sh ...`, the `build` and `test` commands in .claude/layout.json).
+// Configuring (`cmake -B build`) is light and allowed. Text that only MENTIONS a command (inside a heredoc, a quoted
+// string, a commit message) is never read as running it. A project with its own PreToolUse dispatcher
+// (.claude/hooks/pre.js) is left to it.
+//
+//   node build-guard.mjs --selftest
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const WRAPPERS = ['buildq', 'build.sh'];
+const base = (p) => p.split('/').pop();
+
+export function heavy(w) {
+  const exe = base(w[0]);
+  // A PROGRAM RUN STRAIGHT FROM A BUILD FOLDER (a probe, a prototype, a test binary): one bank render took ~8 cores
+  if (/(^|\/)(build[^/]*|[^/]*_artefacts)\//.test(w[0]) || /^[A-Z]\w*(Probe|Proto|Tests?)$/.test(exe)) return true;
+  if (exe === 'cmake') return w.includes('--build');
+  if (exe === 'ninja' && w.slice(1).some((x) => ['-t', '--version', '-n'].includes(x) || x.startsWith('-t'))) return false; // a question to the build graph
+  if (exe === 'ctest' && w.slice(1).some((x) => ['--version', '-N', '--show-only'].includes(x) || x.startsWith('--show-only'))) return false; // listing tests
+  if (['ctest', 'ninja', 'xcodebuild', 'msbuild', 'gradle', 'gradlew', 'mvn', 'make', 'gmake'].includes(exe)) return true;
+  if (['cargo', 'swift', 'go', 'bazel', 'bazelisk'].includes(exe)) return w.length > 1 && ['build', 'test', 'bench', 'run', 'install'].includes(w[1]);
+  return false;
+}
+
+// Heredoc bodies are text written to a file or fed to a program, never commands of this shell.
+export function stripHeredocs(cmd) {
+  const out = [];
+  const lines = cmd.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    out.push(lines[i]);
+    const m = lines[i].match(/<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/);
+    if (m) { i += 1; while (i < lines.length && lines[i].trim() !== m[1]) i += 1; }
+  }
+  return out.join('\n');
+}
+
+const blankQuotes = (s) => s.replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+// Quoted text (a commit note, a bug title) keeps its length but loses its words, so a note naming the test runner is not a test run
+const maskQuotes = (s) => s.replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, (q) => q[0] + ' '.repeat(q.length - 2) + q[q.length - 1]);
+const words = (part) => part.replace(/(^|\s)#.*$/, '').trim().split(/\s+/).filter(Boolean);
+
+export function offending(cmd) {
+  for (const part of blankQuotes(stripHeredocs(cmd)).split(/&&|\|\||;|\||\n|\(|\)|`|\$\(/)) {
+    let w = words(part);
+    if ((w.length >= 2 && ['command', 'type', 'which', 'whence', 'hash'].includes(w[0]) && ['-v', '-V', '-p', '-a'].includes(w[1])) || ['which', 'type', 'whence'].includes(w[0])) continue;
+    while (w.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w[0]) || ['env', 'time', 'nice', 'caffeinate', 'exec', 'nohup', 'command', 'sudo'].includes(w[0]))) {
+      w = w.slice(1);
+      while (w.length && w[0].startsWith('-')) w = w.slice(1);
+    }
+    if (!w.length) continue;
+    if (WRAPPERS.includes(base(w[0])) || (['bash', 'sh', 'zsh'].includes(w[0]) && w.length > 1 && WRAPPERS.includes(base(w[1])))) continue;
+    if (heavy(w)) return w.slice(0, 3).join(' ');
+  }
+  return null;
+}
+
+// A sleep loop or a long sleep, in the commands this shell runs.
+export function polling(cmd) {
+  const body = blankQuotes(stripHeredocs(cmd));
+  if (/\b(until|while)\b[^\n]*\bdo\b[\s\S]*\bsleep\b/.test(body) || /\b(until|while)\b[\s\S]*;\s*do\b[\s\S]*\bsleep\b/.test(body)) return 'a loop that sleeps';
+  for (const m of body.matchAll(/(?:^|[;&|(\n]|\bdo\b|\bthen\b)\s*sleep\s+([0-9.]+)/g)) if (Number(m[1]) > 5) return `sleep ${m[1]}`;
+  if (/for\s+\w+\s+in\s+\$\(seq[^)]*\)[\s\S]*\bsleep\b/.test(body)) return 'a loop that sleeps';
+  if (/\btail\s+(-\S*\s+)*-[a-zA-Z]*[fF]\b/.test(body)) return 'tail -f on a log (watching, not working)';
+  return null;
+}
+
+// Opening an .app or running the binary inside one (kept for the agent-jobs rule; the refusal itself is off: The user,
+// 2026-10-11, agents may open the app; the fault was one agent doing it on repeat).
+export function launchesApp(cmd) {
+  return /(^|[;&|(\s])open\s+(-[a-zA-Z]+\s+)*[^\s;&|]*\.app\b|(^|[;&|(\s])open\s+-a\s|\.app\/Contents\/MacOS\//.test(blankQuotes(stripHeredocs(cmd)));
+}
+
+// A build of everything, or a test run with no -R or one matching more than 30 tests. null when the scope is named.
+export function tooWide(cmd, cwd = process.cwd(), countTests = ctestCount) {
+  const body = stripHeredocs(cmd);
+  const bare = maskQuotes(body);
+  const cd = body.match(/cd\s+(\S+)\s*&&/)?.[1];
+  const from = cd ? cd.replace(/^~(?=\/|$)/, homedir()) : cwd;
+  if (/(cmake\s+--build|tools\/build\.sh\s+build)\b/.test(bare)) {
+    // `build.sh build <one word>`: a build folder (`build.sh build <dir> [target ...]`) builds everything; a target name
+    // (`build.sh build [target ...]`) builds one (KWB-14: one target was read as a folder)
+    const one = body.match(/tools\/build\.sh\s+build\s+(\S+)\s*($|[;&|])/)?.[1];
+    if (/--target\s+all\b/.test(body) || (/cmake\s+--build/.test(body) && !body.includes('--target')) || (one && isFolder(one, from))) {
+      return 'a build of every target is refused.';
+    }
+  }
+  const m = bare.match(/(?:\bctest\b|tools\/build\.sh\s+test)([^;&|\n]*)/);
+  if (m) {
+    const end = m.index + m[0].length;
+    const args = body.slice(end - m[1].length, end);
+    if (args.includes('--full-gate') || args.includes('--changed')) return null;
+    const r = args.match(/-R\s+('([^']*)'|"([^"]*)"|(\S+))/);
+    if (!r) return 'a test run with no -R pattern runs the whole suite.';
+    const pat = r[2] ?? r[3] ?? r[4] ?? '';
+    const tdir = args.match(/--test-dir\s+(\S+)/)?.[1] ?? 'build';
+    const n = countTests(isAbsolute(tdir) ? tdir : join(from, tdir), pat);
+    if (n > 30) return `the -R pattern '${pat}' matches ${n} tests.`;
+  }
+  return null;
+}
+
+function isFolder(word, from) {
+  const p = word.replace(/^~(?=\/|$)/, homedir());
+  try { return word.includes('/') || statSync(isAbsolute(p) ? p : join(from, p)).isDirectory(); } catch { return false; }
+}
+
+function ctestCount(dir, pat) {
+  try {
+    const out = execFileSync('ctest', ['--test-dir', dir, '-N', '-R', pat], { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] });
+    return Number(out.match(/Total Tests:\s*(\d+)/)?.[1] ?? 0);
+  } catch {
+    return 0;
+  }
+}
+
+function lightAgent(ev) {
+  try {
+    const st = JSON.parse(readFileSync(join(homedir(), '.claude/agent-cap-state.json'), 'utf8'));
+    return st[ev.session_id ?? 'default']?.kinds?.[ev.agent_id] === 'light';
+  } catch {
+    return false;
+  }
+}
+
+function refuse(msg) {
+  process.stderr.write(`build-guard: ${msg}\n`);
+  return 2;
+}
+
+function main(text) {
+  let ev;
+  try { ev = JSON.parse(text); } catch { return 0; }
+  const project = process.env.CLAUDE_PROJECT_DIR ?? ev.cwd ?? '';
+  if (project && existsSync(join(project, '.claude', 'hooks', 'pre.js'))) return 0; // a project's own dispatcher wins
+  if (ev.tool_name !== 'Bash') return 0;
+  const cmd = String(ev.tool_input?.command ?? '');
+  const aid = ev.agent_id;
+  // AN AGENT BUILDS AND TESTS ONLY WHAT ITS CHANGE NEEDS (one agent ran all 425 tests on 1 core)
+  if (aid) {
+    const scope = tooWide(cmd, ev.cwd ?? process.cwd());
+    if (scope) {
+      return refuse(`${scope} Build only the targets your change needs (\`--target X --target Y\`), and run only its tests (\`-R 'pattern'\`, at most 30). ` +
+        'The whole suite runs once, as the gate before landing, never while working.');
+    }
+  }
+  // NO POLLING (agents ran `until grep -q done log; do sleep 10` for minutes on end)
+  const poll = polling(cmd);
+  if (poll) {
+    return refuse(`polling refused (${poll}). Waiting in a sleep loop hides what you are doing and burns turns. Run the job in the FOREGROUND ` +
+      'through the queue (buildq / tools/build.sh wait for a slot themselves; the Bash tool allows up to 10 minutes), or start it with ' +
+      'run_in_background and you are notified when it ends.');
+  }
+  // A light agent may RUN an already-built program through the queue (a render), never compile or run a test suite
+  if (aid && /(cmake\s+--build|\bctest\b|\bmake\b|\bninja\b|xcodebuild|tools\/build\.sh\s+(build|test))/.test(maskQuotes(stripHeredocs(cmd))) && lightAgent(ev)) {
+    return refuse('this agent was started as KIND: light, and light agents do not build or run tests (at most 3 build agents run at once, ' +
+      '). Do the light part, and say in your report what needs building.');
+  }
+  const what = offending(cmd);
+  if (!what) return 0;
+  return refuse(`\`${what}\` straight from the shell is refused. Nothing may take the whole machine. Run it through the ` +
+    `machine-wide build queue, which runs two at a time and waits for a free slot by itself:\n    buildq ${what} ...        ` +
+    '(~/.claude/bin/buildq; buildq --status shows the slots)\nor the project\'s own wrapper if it has one (the build and test commands in ' +
+    '.claude/layout.json). Do not wrap it in a loop.');
+}
+
+function selftest() {
+  const bad = [];
+  const check = (name, fn, cases) => { for (const [cmd, want] of cases) if ((fn(cmd) !== null && fn(cmd) !== false) !== want) bad.push(`${name}: ${cmd.replace(/\n/g, ' / ')}`); };
+  check('offending', offending, [
+    ['cmake --build build --target X -j18', true], ['cd x && cmake --build build', true], ['ctest --test-dir build', true],
+    ['make -j8', true], ['ninja -C out', true], ['cargo build --release', true], ['xcodebuild -scheme A', true],
+    ['(cd w && ctest -j6)', true], ['FOO=1 time make', true],
+    ['buildq cmake --build build -j18', false], ['~/.claude/bin/buildq ctest --test-dir b', false],
+    ['bash tools/build.sh build build Synth_Standalone', false], ['cmake -B build -DX=1', false],
+    ['./build/SynthBankProbe_artefacts/RelWithDebInfo/SynthBankProbe --starter', true],
+    ['cd w && build/SynthFaceProbe_artefacts/RelWithDebInfo/SynthFaceProbe --pad', true],
+    ['buildq ./build/SynthBankProbe_artefacts/RelWithDebInfo/SynthBankProbe --starter', false],
+    ['ls build/', false], ['command -v ninja', false], ['ninja -C build -t inputs X', false], ['/opt/homebrew/bin/ninja --version', false],
+    ['ninja -C build X', true], ['ctest --test-dir build -N', false], ['ctest --test-dir build --show-only=json-v1', false], ['ctest --version', false],
+    ['which ninja', false], ['cargo fmt', false], ['go vet ./...', false], ["grep -n 'cmake --build' f.md", false], ["git commit -m 'make it'", false],
+    ["cat > f.py <<'EOF'\ncases = [(\"cmake --build b\", True)]\nmake -j8\nEOF\npython3 f.py", false],
+    ['python3 - <<EOF\nctest --test-dir b\nEOF', false], ['echo "run ctest later"', false],
+  ]);
+  check('polling', polling, [
+    ["until grep -qE 'done' log; do sleep 10; done", true], ['for i in $(seq 1 55); do grep -q x f && break; sleep 20; done', true],
+    ['while true; do\n  sleep 15\ndone', true], ['sleep 180', true], ['sleep 2 && ls', false], ['echo sleep 60', false],
+    ["cat > f.sh <<'EOF'\nwhile true; do sleep 9; done\nEOF", false], ["grep -n 'sleep 30' x.sh", false],
+    ['timeout 585 tail -f /tmp/x.log', true], ['tail -F build.log', true], ['tail -20 build.log', false], ['tail -n 5 f', false],
+  ]);
+  check('launchesApp', launchesApp, [
+    ['open build/Synth_artefacts/RelWithDebInfo/Standalone/Synth.app', true], ['open -a Synth', true],
+    ['python3 tools/record_app_probe.py build/x/Synth.app/Contents/MacOS/Synth', true],
+    ['cd w && build/T.app/Contents/MacOS/Synth --record /tmp/x.mov &', true],
+    ['ls build/Synth_artefacts', false], ['open docs/report.md', false], ["echo 'open X.app'", false],
+  ]);
+  const dir = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), 'build-guard-'));
+  mkdirSync(join(dir, 'build'));
+  const wide = (cmd) => tooWide(cmd, dir, (_, pat) => (pat === 'record' ? 4 : 99));
+  check('tooWide', wide, [
+    ['cmake --build build --target all -j6', true], ['cd w && cmake --build build -j6', true], ['bash tools/build.sh build build', true],
+    // one word after build: a folder that exists (or a path) builds everything; a target name builds one (WB-90/95)
+    ['bash tools/build.sh build synth_block_probe', false], ['bash tools/build.sh build out/', true],
+    ['bash tools/build.sh build synth_slots_probe && echo ok', false],
+    ['bash tools/build.sh build build SynthFaceProbe Synth_Standalone', false], ['cmake --build build --target SynthBankProbe -j5', false],
+    ['bash tools/build.sh test build --output-on-failure', true], ['ctest --test-dir build -j3', true],
+    ["bash tools/build.sh test build -R 'record' --output-on-failure", false], ["ctest --test-dir build -R 'gate'", true],
+    // a note or title that names the test runner is not a test run; a real bare run after a quoted note still is
+    ['python3 tools/step.py save "the look gate hung inside ctest"', false], ["python3 tools/next_number.py wb --take 'ctest holds the turn'", false],
+    ['git commit -m "ctest: fix"', false], ['python3 tools/step.py save "note" && bash tools/build.sh test build', true],
+    ['bash tools/build.sh test build --full-gate', false], ['bash tools/build.sh test build --changed', false],
+  ]);
+  rmSync(dir, { recursive: true, force: true });
+  for (const b of bad) console.error(`build-guard selftest FAILED: ${b}`);
+  if (!bad.length) console.log('build-guard selftest: OK');
+  return bad.length ? 1 : 0;
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('build-guard', main));

package/packs/synth-creator/hooks/build-sweep.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// build-sweep (SessionStart, SubagentStop): an agent worktree's build output is removed once the worktree has gone quiet.
+//
+// The user, 2026-11-01: "we should make [something] in claude-packs that automatically removes old build artifacts that are no
+// longer needed". Every agent works in its own worktree under .claude/worktrees and builds the whole project there (3 to 15 GB);
+// nothing removed them after the agent's work was merged, and two projects filled a 2 TB disk (283 GB in 88 worktrees and
+// 642 GB in 178), until every command failed with ENOSPC.
+//
+// What goes: only the build output (layout.json "buildOutput", default build/**) of a worktree under .claude/worktrees that
+// has been quiet for QUIET_MIN: no source file at depth 3 or less changed, and nothing written at the top of its build folder
+// (.ninja_log, CMakeCache.txt: a build in progress writes there). Never the main checkout's build, never a source file, never a
+// worktree itself (it may hold uncommitted work), never the worktree with the newest build (the one most likely being played),
+// never a worktree named in layout.json "keepWorktrees". A build can always be made again; that is why only the build goes.
+// At SessionStart it also says when the disk is low, so the next agent's build does not fill it.
+//   node build-sweep.mjs                 the hook (reads the event on stdin; sweeps in the background)
+//   node build-sweep.mjs --now [--dry-run]   sweep this project now and say what went
+//   node build-sweep.mjs --selftest
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, statfsSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const QUIET_MIN = Number(process.env.BUILD_SWEEP_QUIET_MIN ?? 120);
+const LOW_GB = Number(process.env.BUILD_SWEEP_LOW_GB ?? 40);
+
+/** the top-level folder name patterns of the build output, from layout.json "buildOutput" (default build/**) */
+/** worktrees a project never sweeps (layout.json "keepWorktrees": names under .claude/worktrees, e.g. the build the user plays) */
+export function keptNames(root) {
+  try { return JSON.parse(readFileSync(join(root, '.claude/layout.json'), 'utf8')).keepWorktrees ?? []; } catch { return []; }
+}
+
+export function buildNames(root) {
+  let globs = ['build/**'];
+  try { globs = JSON.parse(readFileSync(join(root, '.claude/layout.json'), 'utf8')).buildOutput ?? globs; } catch { /* no layout: the default */ }
+  return globs.map((g) => g.split('/')[0]).filter((n) => n && n !== '**')
+    .map((n) => new RegExp(`^${n.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`));
+}
+
+// the newest change in a worktree: its source files to depth 3 (build folders and .git left out), and the top of each build folder
+function lastChange(dir, isBuild) {
+  let newest = 0;
+  const walk = (d, depth) => {
+    let entries = [];
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = join(d, e.name);
+      if (depth === 0 && isBuild(e.name)) {
+        if (!e.isDirectory()) continue;
+        try { for (const f of readdirSync(p)) newest = Math.max(newest, statSync(join(p, f)).mtimeMs); } catch { /* gone */ }
+        continue;
+      }
+      if (e.name === '.git' || e.name === 'node_modules') continue;
+      try { newest = Math.max(newest, statSync(p).mtimeMs); } catch { continue; }
+      if (e.isDirectory() && depth < 2) walk(p, depth + 1);
+    }
+  };
+  walk(dir, 0);
+  return newest;
+}
+
+function sizeGb(p) {
+  try { return Number(execFileSync('du', ['-sk', p], { encoding: 'utf8', timeout: 120000 }).split('\t')[0]) / 1048576; } catch { return 0; }
+}
+
+/** sweep a project's quiet worktrees; returns [{worktree, folder, gb}] of what went (or would go, with dryRun) */
+export function sweep(root, { now = Date.now(), quietMin = QUIET_MIN, dryRun = false, measure = sizeGb } = {}) {
+  const wts = join(root, '.claude/worktrees');
+  if (!existsSync(wts)) return [];
+  const names = buildNames(root);
+  const isBuild = (n) => names.some((r) => r.test(n));
+  const gone = [], keep = new Set(keptNames(root));
+  // the newest finished build (of the quiet worktrees) is always kept: the one the user is most likely to open (a sweep once removed
+  // the build being played); a worktree still being worked on is kept anyway
+  const built = readdirSync(wts, { withFileTypes: true }).filter((w) => w.isDirectory()).map((w) => {
+    const dir = join(wts, w.name); let t = 0;
+    for (const b of readdirSync(dir, { withFileTypes: true })) if (b.isDirectory() && isBuild(b.name)) try { t = Math.max(t, statSync(join(dir, b.name)).mtimeMs, ...readdirSync(join(dir, b.name)).map((f) => statSync(join(dir, b.name, f)).mtimeMs)); } catch { /* gone */ }
+    return { name: w.name, t };
+  }).filter((w) => w.t > 0 && now - lastChange(join(wts, w.name), isBuild) >= quietMin * 60000).sort((a, b) => b.t - a.t);
+  if (built.length) keep.add(built[0].name);
+  for (const w of readdirSync(wts, { withFileTypes: true })) {
+    if (!w.isDirectory() || keep.has(w.name)) continue;
+    const dir = join(wts, w.name);
+    if (now - lastChange(dir, isBuild) < quietMin * 60000) continue;
+    for (const b of readdirSync(dir, { withFileTypes: true })) {
+      if (!b.isDirectory() || !isBuild(b.name)) continue;
+      const p = join(dir, b.name);
+      gone.push({ worktree: w.name, folder: b.name, gb: measure(p) });
+      if (!dryRun) rmSync(p, { recursive: true, force: true });
+    }
+  }
+  return gone;
+}
+
+function freeGb(root) {
+  try { const s = statfsSync(root); return (s.bavail * s.bsize) / 1e9; } catch { return Infinity; }
+}
+
+function main(text) {
+  const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+  if (process.argv.includes('--now')) {
+    const dry = process.argv.includes('--dry-run');
+    const gone = sweep(root, { dryRun: dry });
+    for (const g of gone) console.log(`${dry ? 'would remove' : 'removed'} .claude/worktrees/${g.worktree}/${g.folder} (${g.gb.toFixed(1)} GB)`);
+    console.log(`build-sweep: ${gone.length} build folder(s), ${gone.reduce((a, g) => a + g.gb, 0).toFixed(1)} GB ${dry ? 'would go' : 'freed'}; ${freeGb(root).toFixed(0)} GB free`);
+    return 0;
+  }
+  let event = {};
+  try { event = JSON.parse(text || '{}'); } catch { /* no event */ }
+  // the sweep runs on its own, so a session's start or an agent's stop never waits on a large delete
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--now'], { cwd: root, detached: true, stdio: 'ignore', env: process.env });
+  child.unref();
+  const free = freeGb(root);
+  if (event.hook_event_name === 'SessionStart' && free < LOW_GB) {
+    console.log(`build-sweep: the disk has ${free.toFixed(0)} GB free (under ${LOW_GB}). Quiet agent worktrees' builds are being removed; ` +
+      'if it stays low, see what else holds the space before starting agents that build.');
+  }
+  return 0;
+}
+
+function selftest() {
+  const root = mkdtempSync(join(tmpdir(), 'build-sweep-'));
+  const put = (p, t) => { mkdirSync(join(root, p, '..'), { recursive: true }); writeFileSync(join(root, p), 'x'); utimesSync(join(root, p), t / 1000, t / 1000); };
+  const now = Date.now(), old = now - 5 * 3600e3, fresh = now - 10 * 60e3;
+  mkdirSync(join(root, '.claude'), { recursive: true });
+  writeFileSync(join(root, '.claude/layout.json'), JSON.stringify({ buildOutput: ['out/**', 'build-*/**'], keepWorktrees: ['night'] }));
+  put('out/app.o', old);                                                          // the main checkout's build: never swept
+  put('.claude/worktrees/done/src/a.cpp', old); put('.claude/worktrees/done/out/x.o', old); put('.claude/worktrees/done/build-proof/y.o', old);
+  put('.claude/worktrees/editing/src/a.cpp', fresh); put('.claude/worktrees/editing/out/x.o', old);
+  put('.claude/worktrees/building/src/a.cpp', old); put('.claude/worktrees/building/out/.ninja_log', fresh);
+  put('.claude/worktrees/done/outside/z.txt', old);                               // a folder that only looks like a build name
+  put('.claude/worktrees/night/src/a.cpp', old - 3600e3); put('.claude/worktrees/night/out/app.o', old - 3600e3);   // named in keepWorktrees
+  put('.claude/worktrees/latest/src/a.cpp', old); put('.claude/worktrees/latest/out/app.o', old + 60e3);          // the newest build, quiet
+  for (const d of ['done', 'editing', 'building', 'night', 'latest']) for (const p of [join(root, '.claude/worktrees', d), join(root, '.claude/worktrees', d, 'src')]) utimesSync(p, old / 1000, old / 1000);
+  for (const p of ['out', 'build-proof', 'outside']) if (existsSync(join(root, '.claude/worktrees/done', p))) utimesSync(join(root, '.claude/worktrees/done', p), old / 1000, old / 1000);
+  utimesSync(join(root, '.claude/worktrees/editing/out'), old / 1000, old / 1000);
+  utimesSync(join(root, '.claude/worktrees/building/out'), old / 1000, old / 1000);
+  utimesSync(join(root, '.claude/worktrees/night/out'), (old - 3600e3) / 1000, (old - 3600e3) / 1000);
+  utimesSync(join(root, '.claude/worktrees/latest/out'), (old + 60e3) / 1000, (old + 60e3) / 1000);
+  const dry = sweep(root, { now, measure: () => 0, dryRun: true });
+  const dryKept = existsSync(join(root, '.claude/worktrees/done/out'));
+  const gone = sweep(root, { now, measure: () => 0 });
+  const has = (p) => existsSync(join(root, p));
+  const cases = [
+    ['a dry run names the two folders and removes nothing', dry.length === 2 && dryKept, JSON.stringify(dry)],
+    ['a quiet worktree loses its out/', !has('.claude/worktrees/done/out')],
+    ['and its build-proof/ (a build-* pattern)', !has('.claude/worktrees/done/build-proof')],
+    ['but keeps its sources', has('.claude/worktrees/done/src/a.cpp')],
+    ['and a folder that only starts like a build name', has('.claude/worktrees/done/outside/z.txt')],
+    ['a worktree whose sources changed 10 min ago keeps its build', has('.claude/worktrees/editing/out/x.o')],
+    ['a worktree whose build is running keeps it', has('.claude/worktrees/building/out/.ninja_log')],
+    ['the main checkout keeps its build', has('out/app.o')],
+    ['a worktree named in keepWorktrees keeps its build', has('.claude/worktrees/night/out/app.o')],
+    ['the newest build is kept though quiet', has('.claude/worktrees/latest/out/app.o')],
+    ['exactly two folders went', gone.length === 2],
+  ];
+  rmSync(root, { recursive: true, force: true });
+  const bad = cases.filter(([, ok]) => !ok);
+  for (const [what, , why] of bad) console.log(`build-sweep selftest FAILED: ${what}${why ? ' ' + why : ''}`);
+  console.log(bad.length ? `build-sweep selftest: FAIL (${bad.length} of ${cases.length})` : `build-sweep selftest: OK (${cases.length} cases)`);
+  return bad.length ? 1 : 0;
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : process.argv.includes('--now') ? main('') : await asHook('build-sweep', main));

package/packs/synth-creator/hooks/frozen-files.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): files on the frozen list cannot change, by any route
+// (a tool, or the shell writing, copying, moving or deleting them; lib/writes.mjs).
+// While a fix is in progress, the test that proves it, the golden renders and the sound
+// fingerprints are frozen, so the fix can't be "made to pass" by moving the target.
+// The list lives in .claude/state/frozen.json and is set by `node .claude/tools/freeze.mjs`.
+// `--selftest` proves it.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { matchesAny } from './lib/glob.mjs';
+import { insideProject, checkoutRoot } from './lib/project.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { fileURLToPath } from 'node:url';
+import { bashOf, editOf, runHook, scratchProject, verdicts } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+const STATE = join(ROOT, '.claude', 'state', 'frozen.json');
+
+function main(text) {
+  if (!existsSync(STATE)) return 0;
+  let payload;
+  let state;
+  try {
+    payload = JSON.parse(text);
+    state = JSON.parse(readFileSync(STATE, 'utf8'));
+  } catch {
+    return 0;
+  }
+  if (!Array.isArray(state.files) || state.files.length === 0) return 0;
+  const hit = writesOf(payload, payload.cwd ?? process.cwd()).map((w) => w.path).filter((f) => insideProject(f)).map((f) => relative(checkoutRoot(f), f))
+    .find((rel) => rel === '.claude/state/frozen.json' || matchesAny(rel, state.files));
+  if (!hit) return 0;
+  const rel = hit;
+  process.stderr.write(
+    `BLOCKED by frozen-files: ${rel} is frozen (${state.reason ?? 'a fix is in progress'}).\n` +
+      'Fix the code, not the test or the golden file. Unfreeze (node .claude/tools/freeze.mjs off) only when the\n' +
+      'fix is green, or after the user agrees the target itself is wrong.\n',
+  );
+  return 2;
+}
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const frozen = JSON.stringify({ files: ['tests/bug_7*', 'goldens/**'], reason: 'bug 7' });
+  const dir = scratchProject({ '.claude/state/frozen.json': frozen });
+  const idle = scratchProject();
+  const e = (root, file) => runHook(hook, root, editOf(join(root, file)));
+  return verdicts('frozen-files', [
+    ['the test that proves the fix', e(dir, 'tests/bug_7_test.cpp'), 2],
+    ['a golden render', e(dir, 'goldens/pad.wav'), 2],
+    ['the code being fixed', e(dir, 'src/dsp/Svf.cpp'), 0],
+    ['the frozen list itself', e(dir, '.claude/state/frozen.json'), 2],
+    ['nothing frozen', e(idle, 'tests/bug_7_test.cpp'), 0],
+    ['another project is not ours', runHook(hook, dir, editOf(join(dirname(dir), 'elsewhere/tests/bug_7.cpp'))), 0],
+    ['the shell writing the frozen test', runHook(hook, dir, bashOf("cat > tests/bug_7_test.cpp <<'EOF'\nEXPECT (true);\nEOF", dir)), 2],
+    ['the shell deleting a golden', runHook(hook, dir, bashOf('rm -f goldens/pad.wav', dir)), 2],
+    ['the shell writing the code', runHook(hook, dir, bashOf('echo x >> src/dsp/Svf.cpp', dir)), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) process.exit(process.argv.includes('--selftest') ? selftest() : await asHook('frozen-files', main));

package/packs/synth-creator/hooks/idle-wake.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// idle-wake: a proposed next step is started when the user has gone quiet ("If I havent said anything for
+// 15min I am probably in bed. And unless there is no logical reason for you to not start the next thing ... then you
+// obviously should start"; later: "maybe you also need to check memory at this time?").
+//
+// A Stop hook with `asyncRewake`: it runs in the background after the main session ends ANY turn, so the turn ends and
+// The user can type. It watches the session's transcript; anything written to it (the user typing, an agent reporting, the session
+// working) ends the watch quietly. After WAIT_MIN minutes of silence it exits 2, which wakes the session with the message
+// below and EVERY ASK the user made in the last day, word for word (user-asks.mjs). A turn that ends with the words NOTHING OPEN
+// starts no watch, so a finished night does not wake itself every 15 minutes.
+//   node idle-wake.mjs --selftest
+import { appendFileSync, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { asks, render } from './user-asks.mjs';
+
+const WAIT_MIN = Number(process.env.IDLE_WAKE_MIN ?? 15);
+const LOOK_S = Number(process.env.IDLE_WAKE_LOOK_S ?? 10);
+
+const PROPOSES = new RegExp([
+  "\\bnext,?\\s+(?:I(?:'d|\\s+would|\\s+will|'ll)|is|up|step|on\\s+my\\s+list|comes?)\\b",
+  '\\b(?:shall|should|can|may)\\s+I\\b', '\\b(?:want|like)\\s+me\\s+to\\b', '\\bwould\\s+you\\s+like\\b', '\\bdo\\s+you\\s+want\\b',
+  "\\bI(?:'d|\\s+would)?\\s+(?:recommend|suggest|propose)\\b", '\\bmy\\s+recommendation\\b',
+  "\\bI'll\\s+(?:start|begin|continue|carry\\s+on|pick\\s+up|move\\s+on)\\b", "\\bthen\\s+I(?:'ll|\\s+will)\\b", '\\bready\\s+to\\s+(?:start|begin|go)\\b',
+].join('|'), 'i');
+
+const WAKE = (m, what) => `idle-wake: The user has said nothing for ${m.toFixed(0)} minutes since you ${what}. They are probably away. First go through their asks ` +
+  "below and build.md's In progress: anything not done and proved is open work. Then, unless there is a logical reason not to (it needs their eyes, " +
+  'ears or hands, it is destructive or outward-facing, or it waits on something unfinished), START the next thing NOW, so what was started is ' +
+  'finished when they are back. If there is such a reason, say it in one line and take the next thing instead. If truly nothing is left that you ' +
+  'can do, end your turn with the words NOTHING OPEN.';
+
+export function proposes(text) {
+  if (!text) return false;
+  const tail = text.trim().slice(-1500);
+  return PROPOSES.test(tail) || tail.trimEnd().endsWith('?');
+}
+
+const sizeOf = (path) => { try { const s = statSync(path); return `${s.size}:${s.mtimeMs}`; } catch { return null; } };
+const nap = (s) => new Promise((done) => setTimeout(done, s * 1000));
+
+// [0, ''] when there is nothing to do or activity was seen; [2, words] after silence for waitS.
+export async function watch(event, waitS, lookS, sleep = nap) {
+  if (event.hook_event_name !== undefined && event.hook_event_name !== 'Stop') return [0, ''];
+  const msg = event.last_assistant_message ?? '';
+  if (msg.includes('NOTHING OPEN')) return [0, ''];
+  const path = event.transcript_path;
+  if (!path) return [0, ''];
+  const first = sizeOf(path);
+  for (let waited = 0; waited < waitS; waited += lookS) {
+    await sleep(lookS);
+    if (sizeOf(path) !== first) return [0, ''];
+  }
+  let words = WAKE(waitS / 60, proposes(msg) ? 'proposed or asked about a next step' : 'ended a turn');
+  try { const listed = render(asks(path)); if (listed) words += `\n\n${listed}`; } catch { /* the wake still goes */ }
+  return [2, words];
+}
+
+async function selftest() {
+  let bad = 0;
+  const expect = (name, got, want) => { if (got !== want) { bad += 1; console.error(`FAIL  ${name}: exit ${got}`); } };
+  const d = mkdtempSync(join(tmpdir(), 'idle-wake-'));
+  const t = join(d, 't.jsonl');
+  writeFileSync(t, '{}\n');
+  const ev = (m) => ({ hook_event_name: 'Stop', transcript_path: t, last_assistant_message: m });
+  const still = async () => {};
+  expect("silence after 'Next I'd build P4'", (await watch(ev("Done. Next I'd build P4 PAD SETUP."), 3, 1, still))[0], 2);
+  expect("silence after 'Shall I start the bank?'", (await watch(ev('All green. Shall I start the bank?'), 3, 1, still))[0], 2);
+  expect("silence after 'My recommendation'", (await watch(ev('My recommendation: the cache first.'), 3, 1, still))[0], 2);
+  expect('the user types during the wait', (await watch(ev("Next I'd build P4."), 3, 1, async () => appendFileSync(t, '{"type":"user"}\n')))[0], 0);
+  expect('silence after a plain report (every turn arms)', (await watch(ev('K10 is landed as fb67cbb3. 46 of 46 green.'), 3, 1, still))[0], 2);
+  expect('a turn ending NOTHING OPEN', (await watch(ev('All asks done and proved. NOTHING OPEN'), 3, 1, still))[0], 0);
+  expect('another hook event', (await watch({ hook_event_name: 'PostToolUse', transcript_path: t, last_assistant_message: 'Shall I?' }, 3, 1, still))[0], 0);
+  if (!proposes('Shall I go on?') || proposes('Landed.')) { bad += 1; console.error('FAIL  proposes'); }
+  rmSync(d, { recursive: true, force: true });
+  console.log(`idle-wake selftest: ${bad ? `${bad} wrong` : 'OK'}`);
+  return bad ? 1 : 0;
+}
+
+async function main() {
+  if (process.argv.includes('--selftest')) return selftest();
+  let event;
+  try { event = JSON.parse(readFileSync(0, 'utf8')); } catch { return 0; }
+  const [code, words] = await watch(event, WAIT_MIN * 60, LOOK_S);
+  if (code === 2) process.stderr.write(`${words}\n`);
+  return code;
+}
+
+process.exit(await main());