@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/synth-creator/hooks/protect-vendor.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): code this project did not write is read-only, to every
+// route that writes (WB-69): a tool, or a shell command that writes, copies, moves or deletes there.
+//  - Vendored and generated code (JUCE, third_party, _deps, build output) and the project's own read-only paths
+//    (.claude/layout.json "protected"). Agents "fixing" a bug inside JUCE is a reported
+//    failure mode; fix our code or wrap the library instead.
+//  - COPY TREES: every layout folder whose "kind" is "copy" (another project's code, copied unchanged and proved, from
+//    the copy-and-prove skill). Let through: git, and the project's sanctioned copy tools, run as `python3 <tool>`:
+//    .claude/layout.json "guards": { "copy": { "tools": ["tools/copy_x.py", ...] } }. A new copy tree is guarded the
+//    moment its folder is declared with "kind": "copy".
+// One law, read-only paths: the separate copy-tree guard (copy-tree-guard.py) is merged in here.
+// A path in an agent worktree (.claude/worktrees/<name>/...) is judged as the same path in the project.
+// A nested clone under build/_deps is vendored code too (Sub37 WB-2: checkoutRoot counts only this repo's worktrees).
+// `--selftest` plants a write into each kind of read-only path and lets the allowed ones through.
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { matchesAny } from './lib/glob.mjs';
+import { foldersOfKind, readLayout } from './lib/layout.mjs';
+import * as project from './lib/project.mjs';
+import { editOf, git, put, runHook, scratchProject, verdicts } from './lib/selftest.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const DEFAULT_GLOBS = ['JUCE/**', '**/JUCE/modules/**', 'JuceLibraryCode/**', 'libs/**', 'third_party/**', 'external/**', '_deps/**'];
+// The build output; a project whose build lives elsewhere names it in layout.json "buildOutput" (a build in out/, while build/
+// holds the report and the pictures, which agents write). Any nested clone under build/_deps stays vendored either way.
+const buildGlobs = (layout) => [...(layout.buildOutput ?? ['build/**']), 'build/_deps/**'];
+// What makes a write to this file wrong, or null. `p` is the project library (lib/project.mjs).
+// layout.json "writeOnce" globs (KWB-21): evidence a command leaves; a new file may be added, an existing one is never changed,
+// moved or deleted, so what a gate recorded stays what it recorded.
+function judge(p, file, base, op = 'write') {
+  const abs = resolve(base, file);
+  if (!p.insideProject(abs)) return null;
+  const rel = p.relInCheckout(abs).replace(/^\.claude\/worktrees\/[^/]+\//, '');
+  const layout = readLayout(p.claudeRoot(abs));
+  const tree = foldersOfKind(layout, 'copy').find((t) => rel === t || rel.startsWith(`${t}/`));
+  if (tree) return { rel, tree, layout };
+  if (matchesAny(rel, [...DEFAULT_GLOBS, ...buildGlobs(layout), ...(layout.protected ?? [])])) return { rel, layout };
+  if (matchesAny(rel, layout.writeOnce ?? []) && (op === 'delete' || existsSync(abs))) return { rel, layout, once: true };
+  return null;
+}
+
+// Every file the call writes, by any route (lib/writes.mjs): Write, Edit, MultiEdit, NotebookEdit, and the
+// shell's >, >>, tee, sed -i, perl -i, cp, mv (its source too), ln, rm, truncate, touch, dd of=, a heredoc.
+export function verdict(payload, p = project) {
+  for (const w of writesOf(payload, payload.cwd ?? p.ROOT)) {
+    const hit = judge(p, w.path, p.ROOT, w.op);
+    if (hit) return { ...hit, why: payload.tool_name === 'Bash' ? `the command writes ${hit.rel}` : hit.rel };
+  }
+  return null;
+}
+
+function message({ why, tree, layout, once }) {
+  if (once) {
+    return `BLOCKED by protect-vendor: ${why}, which already exists under a "writeOnce" path of .claude/layout.json: evidence is\n` +
+      'written once and never changed, moved or deleted. Write the new run to a new file name beside it.\n';
+  }
+  if (!tree) {
+    return `BLOCKED by protect-vendor: ${why} is vendored/generated code and is read-only.\n` +
+      'Fix our own code, wrap the library, or ask the user if the library itself must change.\n';
+  }
+  const tools = layout.guards?.copy?.tools ?? [];
+  return `BLOCKED by protect-vendor: ${why}, in the copy tree ${tree}. A copy tree (a folder of kind "copy" in .claude/layout.json) is read-only:\n` +
+    `its files come only from the project's copy tools${tools.length ? ` (${tools.map((t) => `python3 ${t}`).join(', ')})` : ''}, each with its origin line and licence row.\n` +
+    'Fix the code that uses the copy. If the copy itself must change, that is the user\'s to say, then a pinned change under null tests (.claude/rules/copy-trees-read-only.md).\n';
+}
+
+function main(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return 0;
+  }
+  const v = verdict(payload);
+  if (!v) return 0;
+  process.stderr.write(message(v));
+  return 2;
+}
+
+async function selftest() {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'pv-')));
+  mkdirSync(join(root, '.claude'));
+  writeFileSync(join(root, '.claude/layout.json'), JSON.stringify({
+    folders: { a: { path: 'lib/engines/src/tabula', kind: 'copy' }, b: { path: 'lib/app/tabula', kind: 'copy' }, c: { path: 'lib/effects/src/tabula', kind: 'copy' }, d: { path: 'lib/app' } },
+    protected: ['design/reference/**'],
+    guards: { copy: { tools: ['tools/copy_tabula.py', 'tools/copy_reimport.py', 'tools/copy_promote.py'] } },
+  }));
+  const saved = process.env.CLAUDE_PROJECT_DIR;
+  process.env.CLAUDE_PROJECT_DIR = root;
+  const p = await import(`${pathToFileURL(join(import.meta.dirname, 'lib', 'project.mjs')).href}?selftest`);
+  process.env.CLAUDE_PROJECT_DIR = saved;
+  const W = (f) => ({ tool_name: 'Write', tool_input: { file_path: join(root, f) } });
+  const E = (f) => ({ tool_name: 'Edit', tool_input: { file_path: join(root, f), old_string: 'a', new_string: 'b' } });
+  const N = (f) => ({ tool_name: 'NotebookEdit', tool_input: { notebook_path: join(root, f) } });
+  const B = (c) => ({ tool_name: 'Bash', tool_input: { command: c } });
+  const refused = [
+    W('lib/app/tabula/tabula/src/engine/PianoBridge.cpp'), E('lib/engines/src/tabula/tabula/src/engine/Voice.h'), W('lib/effects/src/tabula/x/New.h'),
+    W('.claude/worktrees/agent-x/lib/app/tabula/tabula/tools/p.cpp'), N('lib/app/tabula/n.ipynb'), W('JUCE/modules/juce_core/x.h'), E('design/reference/look.md'),
+    B("sed -i 's/0.5f/0.6f/' lib/app/tabula/tabula/src/engine/PianoBridge.cpp"), B('echo x > lib/engines/src/tabula/tabula/src/util/Dev.h'),
+    B('cp /tmp/x.h lib/app/tabula/tabula/src/engine/'), B("cd lib && perl -pi -e 's/a/b/' engines/src/tabula/dspblocks/include/dsp/Drive.h"), B('mv lib/app/tabula/a.h lib/app/src/a.h'), B("cat > build/x.h <<'EOF'\nx\nEOF"),
+    B('rm lib/app/tabula/tabula/tools/piano_prebuild.cpp'), B('cat a | tee -a lib/effects/src/tabula/x.h'),
+    B('python3 tools/my_copy_tabula.py; rm lib/app/tabula/tabula/tools/piano_prebuild.cpp'), B('python3 out/copy_promote.py && cp x lib/app/tabula/y.h'),
+    B('dd if=/dev/zero of=lib/app/tabula/z.bin bs=1 count=1'),
+  ];
+  const passed = [
+    W('lib/app/src/pianos.h'), E('lib/engines/src/engines.cpp'), W('lib/app/tabulax/y.h'), W('/elsewhere/lib/app/tabula/x.h'),
+    B('python3 tools/copy_tabula.py'), B('python3 tools/copy_reimport.py --no-proofs'), B('python3 tools/copy_promote.py lib/engines/src/tabula/tabula/src/engine/FireSaw.h --proof true'),
+    B('grep -rn loadFrom lib/app/tabula > out/grep.txt'), B('cp lib/app/tabula/tabula/src/engine/PianoBridge.h /tmp/x.h'),
+    B('git rm -q lib/app/tabula/tabula/tools/old.cpp'), B('cat lib/engines/src/tabula/tabula/src/engine/Voice.h 2>&1 | head'),
+    B('cmake --build build -j8 > out/log.txt'), B('cd /elsewhere/other && rm lib/app/tabula/x.h'), B("echo 'rm lib/app/tabula/x.h'"),
+  ];
+  const cwd = process.cwd();
+  process.chdir(root); // a hook runs in the project's folder
+  const bad = [...refused.filter((x) => !verdict(x, p)), ...passed.filter((x) => verdict(x, p))];
+  process.chdir(cwd);
+  for (const x of bad) console.error(`protect-vendor selftest FAILED on ${JSON.stringify(x.tool_input)}`);
+  rmSync(root, { recursive: true, force: true });
+  console.log(`protect-vendor routes: ${refused.length} writes into read-only paths refused, ${passed.length} others let through: ${bad.length ? 'FAIL' : 'PASS'}`);
+  return bad.length ? 1 : 0;
+}
+
+// A git project with FetchContent's JUCE clone under build/_deps and an agent worktree.
+function selftestRepo() {
+  const hook = fileURLToPath(import.meta.url);
+  const dir = scratchProject({ 'src/dsp/Svf.cpp': '// svf\n', 'design/ref.md': 'x\n' }, { folders: {}, concepts: {}, protected: ['design/**'] });
+  git(dir, 'init', '-q');
+  git(dir, 'add', 'src', '.claude');
+  git(dir, 'commit', '-qm', 'init');
+  git(dir, 'worktree', 'add', '-q', '.claude/worktrees/agent-x', '-b', 'work/x');
+  put(join(dir, 'build/_deps/juce-src/modules/juce_core/juce_core.h'), '// juce\n');
+  git(join(dir, 'build/_deps/juce-src'), 'init', '-q');
+  const wt = join(dir, '.claude/worktrees/agent-x');
+  const e = (file) => runHook(hook, dir, editOf(join(dir, file)));
+  return verdicts('protect-vendor', [
+    ['our own source', e('src/dsp/Svf.cpp'), 0],
+    ['JUCE modules', e('JUCE/modules/juce_core/juce_core.h'), 2],
+    ['a nested clone under build/_deps (Sub37 WB-2)', e('build/_deps/juce-src/modules/juce_core/juce_core.h'), 2],
+    ['a layout "protected" glob', e('design/ref.md'), 2],
+    ['a worktree file is judged in the worktree', runHook(hook, dir, editOf(join(wt, 'src/dsp/Svf.cpp'))), 0],
+    ['a worktree\'s vendored folder', runHook(hook, dir, editOf(join(wt, 'third_party/lib/lib.h'))), 2],
+    ['another project is not ours', runHook(hook, dir, editOf(join(dirname(dir), 'elsewhere/JUCE/x.h'))), 0],
+    ['build/ is the build output by default', e('build/report.md'), 2],
+  ]) | selftestBuildOutput(hook);
+}
+
+// A layout that names its build output as out/ may write build/ (a report, pictures); out/ and build/_deps stay read-only.
+function selftestBuildOutput(hook) {
+  const dir = scratchProject({ 'src/a.cpp': '//\n', 'build/evidence/s1/run.txt': 'measured\n' },
+    { folders: {}, concepts: {}, buildOutput: ['out/**'], writeOnce: ['build/evidence/**'] });
+  git(dir, 'init', '-q');
+  const e = (file) => runHook(hook, dir, editOf(join(dir, file)));
+  const w = (file) => runHook(hook, dir, { tool_name: 'Write', tool_input: { file_path: join(dir, file), content: 'x\n' } });
+  const b = (command) => runHook(hook, dir, { tool_name: 'Bash', tool_input: { command }, cwd: dir });
+  return verdicts('protect-vendor buildOutput', [
+    ['build/for-you.md under buildOutput out/**', e('build/for-you.md'), 0],
+    ['out/ under buildOutput out/**', e('out/lib/x.o'), 2],
+    ['build/_deps stays vendored', e('build/_deps/juce-src/x.h'), 2],
+    // KWB-21: evidence is written once
+    ['a new evidence file by Write', w('build/evidence/s2/new.txt'), 0],
+    ['a new evidence file by cp (KWB-21)', b('cp /tmp/sweep.txt build/evidence/s2/sweep.txt'), 0],
+    ['a probe writing new evidence', b('probe --bank > build/evidence/s2/bank.txt'), 0],
+    ['an existing evidence file overwritten', w('build/evidence/s1/run.txt'), 2],
+    ['an existing evidence file edited', e('build/evidence/s1/run.txt'), 2],
+    ['an existing evidence file appended', b('echo x >> build/evidence/s1/run.txt'), 2],
+    ['an evidence file deleted', b('rm build/evidence/s1/run.txt'), 2],
+    ['an evidence file moved away', b('mv build/evidence/s1/run.txt /tmp/'), 2],
+  ]);
+}
+
+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') ? ((await selftest()) | selftestRepo()) : await asHook('protect-vendor', main));

package/packs/synth-creator/hooks/spec-lock.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Spec lock: while a build runs, the spec it builds from cannot change under it.
+// State: .claude/spec-lock.json  { "locked": true, "globs": [...], "reason": "...", "since": "..." }
+//   node spec-lock.mjs lock "<reason>" [glob ...]   lock (Claude may do this when a build starts)
+//   node spec-lock.mjs unlock                       unlock (the USER runs this, e.g. `! node ...`)
+//   node spec-lock.mjs status
+//   node spec-lock.mjs --selftest                 proves the hook
+// As a PreToolUse hook (Write|Edit|MultiEdit|NotebookEdit|Bash) it blocks writes to locked files by any route
+// (lib/writes.mjs: a tool, or the shell's >, >>, tee, sed -i, cp, mv, a heredoc), writes to the lock file itself,
+// and Claude running "unlock". Words inside a heredoc body or quotes are text, never the unlock command.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { matchesAny } from './lib/glob.mjs';
+import { commandLeavesProject, insideProject, checkoutRoot, relInCheckout } from './lib/project.mjs';
+import { writesOf } from './lib/writes.mjs';
+import { fileURLToPath } from 'node:url';
+import { bashOf, runHook, scratchProject, verdicts, writeOf } 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', 'spec-lock.json');
+const DEFAULT_GLOBS = ['spec/**', 'specs/**', 'docs/stellix-*.md', '**/*-spec.md', '**/*.mmd', '**/panel.json', '**/build.md', '**/decisions*.md'];
+const WRITE_CMD = /(>|>>|\btee\b|\bsed\s+-i|\bperl\s+-i|\bmv\b|\bcp\b|\brm\b|\btruncate\b|\bgit\s+(checkout|restore)\b)/;
+
+const read = () => (existsSync(STATE) ? JSON.parse(readFileSync(STATE, 'utf8')) : { locked: false });
+const write = (s) => writeFileSync(STATE, JSON.stringify(s, null, 2) + '\n');
+
+function cli(args) {
+  const [cmd, reason, ...globs] = args;
+  if (cmd === 'lock') {
+    write({ locked: true, globs: globs.length ? globs : DEFAULT_GLOBS, reason: reason ?? 'build in progress', since: new Date().toISOString() });
+    console.log('Spec locked.');
+  } else if (cmd === 'unlock') {
+    write({ ...read(), locked: false });
+    console.log('Spec unlocked.');
+  } else console.log(JSON.stringify(read(), null, 2));
+  return 0;
+}
+
+function block(msg) {
+  process.stderr.write(`BLOCKED by spec-lock: ${msg}\n`);
+  return 2;
+}
+
+function main(text) {
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return 0;
+  }
+  const state = read();
+  const input = payload.tool_input ?? {};
+  const howTo = 'To change the spec, stop and ask the user. Only the user unlocks: `! node .claude/hooks/spec-lock.mjs unlock`.';
+
+  if (payload.tool_name === 'Bash') {
+    const cmd = input.command ?? '';
+    const bare = cmd.replace(/<<-?\s*(['"]?)(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2\s*(?:\n|$)/g, '\n').replace(/'[^']*'|"(?:\\.|[^"\\])*"/g, "''");
+    if (/spec-lock/.test(bare) && /\bunlock\b/.test(bare)) return block(`Claude may not unlock the spec. ${howTo}`);
+    if (/spec-lock\.json/.test(bare) && WRITE_CMD.test(bare)) return block(`the lock file can't be edited. ${howTo}`);
+    const routed = judgeWrites(payload, state, howTo);
+    if (routed) return routed;
+    if (!state.locked || commandLeavesProject(cmd)) return 0;
+    // Each word as a path in its own checkout, so a worktree's spec/ is the spec too.
+    const base = payload.cwd ?? ROOT;
+    const toRel = (t) => {
+      const abs = resolve(base, t.replace(/^['"]|['"]$/g, ''));
+      return insideProject(abs) ? relInCheckout(abs) : null;
+    };
+    const touched = cmd.split(/\s+/).filter((t) => {
+      const rel = t && toRel(t);
+      return rel && matchesAny(rel, state.globs);
+    });
+    if (touched.length && WRITE_CMD.test(cmd)) return block(`${touched.join(', ')} locked (${state.reason}). ${howTo}`);
+    return 0;
+  }
+
+  return judgeWrites(payload, state, howTo);
+}
+
+// Every file the call writes, whichever tool: the lock file never, a locked spec file not while locked.
+function judgeWrites(payload, state, howTo) {
+  for (const w of writesOf(payload)) {
+    if (!insideProject(w.path)) continue;
+    const rel = relative(checkoutRoot(w.path), w.path);
+    if (rel === join('.claude', 'spec-lock.json')) return block(`the lock file can't be edited. ${howTo}`);
+    if (state.locked && matchesAny(rel, state.globs)) return block(`${rel} is locked since ${state.since} (${state.reason}). ${howTo}`);
+  }
+  return 0;
+}
+
+function selftest() {
+  const hook = fileURLToPath(import.meta.url);
+  const state = (locked) => JSON.stringify({ locked, globs: DEFAULT_GLOBS, reason: 'build running', since: 'now' });
+  const dir = scratchProject({ '.claude/spec-lock.json': state(true), 'spec/plan.md': 'x\n' });
+  const open = scratchProject({ '.claude/spec-lock.json': state(false) });
+  const w = (root, file) => runHook(hook, root, writeOf(join(root, file)));
+  const sh = (root, cmd) => runHook(hook, root, bashOf(cmd, root));
+  return verdicts('spec-lock', [
+    ['a locked spec file', w(dir, 'spec/plan.md'), 2],
+    ['a panel.json anywhere', w(dir, 'panel/panel.json'), 2],
+    ['code while the spec is locked', w(dir, 'src/dsp/Svf.cpp'), 0],
+    ['the lock file', w(dir, '.claude/spec-lock.json'), 2],
+    ['Claude running unlock', sh(dir, 'node .claude/hooks/spec-lock.mjs unlock'), 2],
+    ['a shell edit of the spec', sh(dir, 'sed -i s/a/b/ spec/plan.md'), 2],
+    ['reading the spec', sh(dir, 'cat spec/plan.md'), 0],
+    ['the word unlock in a heredoc is text', sh(dir, "cat > notes.txt <<'EOF'\nnode .claude/hooks/spec-lock.mjs unlock\nEOF"), 0],
+    ['a heredoc into the spec', sh(dir, "cat > spec/plan.md <<'EOF'\nnew\nEOF"), 2],
+    ['an unlocked spec', w(open, 'spec/plan.md'), 0],
+  ]);
+}
+
+export const hook = main; // run-hooks.mjs calls it with the event's text (KWB-24)
+if (isMain(import.meta.url)) {
+  const args = process.argv.slice(2);
+  process.exit(args.includes('--selftest') ? selftest() : args.length ? cli(args) : await asHook('spec-lock', main));
+}

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// PreToolUse (Bash): stage files by name, never everything at once, and never secrets.
+// `git add -A`, `git add .`, `git add --all` and `git commit -a` sweep build output, renders,
+// scratch files and keys into history. Exit 2 refuses the command. `--selftest` proves it.
+import { readFileSync } from 'node:fs';
+import { verdicts } from './lib/selftest.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+const SECRET = /(^|[\s/])(\.env(\.[\w.-]+)?|[\w.-]+\.(pem|key|p12|pfx)|id_(rsa|ed25519)|credentials\.json)(\s|$)/;
+const SAFE_ENV = /\.env\.(example|sample|template)(\s|$)/;
+
+export function problem(command) {
+  for (const raw of command.split(/&&|\|\||;|\n/)) {
+    const seg = raw.trim();
+    const add = seg.match(/^git\s+(?:-C\s+\S+\s+)?add\s+(.*)$/);
+    if (add) {
+      const args = add[1];
+      if (/(^|\s)(-A|--all|-u|--update)(\s|$)/.test(args) || /(^|\s)(\.|\*|:\/)(\s|$)/.test(args)) {
+        return 'stage the files you changed by name (git add path/one path/two), never everything at once';
+      }
+      if (SECRET.test(` ${args} `) && !SAFE_ENV.test(` ${args} `)) return 'that looks like a secret or key file; it must never be committed';
+    }
+    if (/^git\s+(?:-C\s+\S+\s+)?commit\b/.test(seg) && /(^|\s)(-a|--all|-am|-a\w*m)(\s|$)/.test(seg)) {
+      return 'commit -a stages every tracked change; stage by name first, then commit';
+    }
+  }
+  return null;
+}
+
+function main(text) {
+  let payload;
+  try { payload = JSON.parse(text); } catch { return 0; }
+  const why = problem(payload.tool_input?.command ?? '');
+  if (!why) return 0;
+  process.stderr.write(`BLOCKED by stage-guard: ${why}.\nRun \`git status --short\` and add each intended file explicitly.\n`);
+  return 2;
+}
+
+function selftest() {
+  const cases = [
+    ['git add -A', true], ['git add .', true], ['cd x && git add --all', true], ['git commit -am "wip"', true],
+    ['git add .env', true], ['git add certs/server.key', true],
+    ['git add src/dsp/Svf.cpp tests/svf_test.cpp', false], ['git add .env.example', false],
+    ['git commit -m "fix: svf"', false], ['git status', false],
+  ];
+  return verdicts('stage-guard', cases.map(([cmd, block]) => [cmd, problem(cmd) !== null, block]));
+}
+
+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('stage-guard', main));

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

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+// time-guard: nothing is slow without someone being told (after a night of two-hour panel exports that
+// every agent, and the session watching them, took for normal).
+//
+// PreToolUse + PostToolUse on every tool, for the session and every agent it starts. After a call it tells the caller
+// (exit 2 on PostToolUse: the call has run, nothing is blocked, the words reach the agent) when:
+//   1. THE CALL ITSELF TOOK LONG: more than SLOW_CALL_MIN minutes (a question to the user never counts);
+//   2. SOMETHING ON THE MACHINE IS SLOW, whoever started it (looked at once a minute at most): a panel export older than
+//      EXPORT_MIN, more than CHROME_MAX headless Chromes or one older than CHROME_MIN, a build older than BUILD_MIN, a ctest
+//      run older than CTEST_MIN, a probe older than PROBE_MIN (guards.time.probePattern says what a probe is), a wait
+//      loop older than WAIT_LOOP_MIN;
+//   3. AN AGENT'S WORKTREE HAS NOT MOVED: work unsaved for SAVE_MIN, no commit for QUIET_MIN, or two agents in one;
+//   4. THE CONTROLLER sees every worktree holding work unsaved for long, every SCAN_MIN minutes;
+// and before a call it REFUSES a wait that can never end: `until ! pgrep -f "<words>"`, whose pgrep finds the loop's own
+// command line (a heredoc body is text, not a loop). A finding is said again only after REPEAT_MIN minutes.
+// Project values: .claude/layout.json "guards": { "time": { "probePattern", "saveCommand" } }.
+//   node time-guard.mjs --selftest
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readLayout } from './lib/layout.mjs';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+export const DEFAULTS = {
+  probePattern: '\\S*/\\w*(?:Probe|_probe)\\b', // the probe binary itself, never a shell that names one
+  saveCommand: 'git add <paths> && git commit -m "<note>" -- <paths>',
+};
+const CFG = { ...DEFAULTS };
+const SLOW_CALL_MIN = 10, EXPORT_MIN = 5, CHROME_MAX = 6, CHROME_MIN = 5, BUILD_MIN = 30, CTEST_MIN = 45, PROBE_MIN = 20;
+const QUIET_MIN = 60, SAVE_MIN = 30, SCAN_MIN = 15, WAIT_LOOP_MIN = 60, REPEAT_MIN = 10, LOOK_EVERY_S = 60;
+
+const projectRoot = resolve(process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replace(/\/\.claude\/worktrees\/[^/]+(\/.*)?$/, '');
+const STATE = join(process.env.TMPDIR ?? tmpdir(), `time-guard-${basename(projectRoot).replace(/[^\w.-]/g, '-') || 'project'}`);
+const sh = (cmd, args, cwd) => { try { return execFileSync(cmd, args, { cwd, encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }); } catch { return null; } };
+
+export function etimeS(s) {
+  const t = s.trim();
+  const dash = t.lastIndexOf('-');
+  const days = dash >= 0 ? Number(t.slice(0, dash)) : 0;
+  const parts = (dash >= 0 ? t.slice(dash + 1) : t).split(':').map(Number);
+  while (parts.length < 3) parts.unshift(0);
+  return days * 86400 + parts[0] * 3600 + parts[1] * 60 + parts[2];
+}
+
+function processes() {
+  const out = sh('ps', ['-axo', 'pid=,etime=,command=']) ?? '';
+  return out.split('\n').map((l) => l.match(/^\s*(\d+)\s+(\S+)\s+(.*)$/)).filter(Boolean).map((m) => [Number(m[1]), etimeS(m[2]), m[3]]);
+}
+
+export function machineFindings(rows) {
+  const f = [];
+  const mins = (s) => s / 60;
+  const headless = rows.filter((r) => /Google Chrome(?: for Testing)?(?:\.app\/Contents\/MacOS\/\S+)?\s.*--headless/.test(r[2]) && !r[2].includes('Helper'));
+  if (headless.length > CHROME_MAX) {
+    f.push(['chrome-count', `${headless.length} headless Chromes are running at once (more than ${CHROME_MAX}): something is starting one per picture again. ` +
+      'Find it (ps -axo pid,etime,command | grep -- --headless) and stop it; Chrome is started only by kit/synthpanel-creator/src/onechrome.js, for a whole batch']);
+  }
+  for (const [pid, age] of headless) {
+    if (mins(age) > CHROME_MIN) f.push([`chrome-old-${pid}`, `a headless Chrome (pid ${pid}) has run ${mins(age).toFixed(0)} min: it is stuck or leaked. Find who started it and why it never finished; stop it by its pid`]);
+  }
+  const probe = new RegExp(`^(?:${CFG.probePattern})`);
+  for (const [pid, age, cmd] of rows) {
+    const m = mins(age).toFixed(0);
+    if (/node \S*synthpanel\S*\.js export-native/.test(cmd) && mins(age) > EXPORT_MIN) {
+      f.push([`export-${pid}`, `a panel export (pid ${pid}) has run ${m} min; one takes seconds since B-382 (one Chrome, a cache of every picture). It is stuck: find why before waiting longer`]);
+    } else if (/^\S*ctest\b/.test(cmd) && mins(age) > CTEST_MIN) {
+      f.push([`ctest-${pid}`, `a ctest run (pid ${pid}) has run ${m} min (more than ${CTEST_MIN}): find the slow test (ctest prints each as it ends) instead of waiting for all of them`]);
+    } else if (/^\S*(?:cmake\s+--build|\/make|make|ninja)\b/.test(cmd) && mins(age) > BUILD_MIN) { // the build itself, not a shell naming it
+      f.push([`build-${pid}`, `a build (pid ${pid}) has run ${m} min (more than ${BUILD_MIN}): look at the load (uptime) and what else is building`]);
+    } else if (probe.test(cmd) && mins(age) > PROBE_MIN) {
+      f.push([`probe-${pid}`, `a probe (pid ${pid}: ${cmd.split(/\s+/)[0].split('/').pop()}) has run ${m} min (more than ${PROBE_MIN}): every probe has a time limit; find what it is waiting on`]);
+    } else if (/\buntil\b.*;\s*do\s+sleep\b/.test(cmd) && mins(age) > WAIT_LOOP_MIN) {
+      f.push([`waitloop-${pid}`, `a wait loop (pid ${pid}) has run ${m} min: whatever it waits for is finished or dead. Stop it (kill ${pid}); wait on a background command's own notification instead of a loop`]);
+    }
+  }
+  return f;
+}
+
+function lastCommitMin(cwd) {
+  const out = sh('git', ['log', '-1', '--format=%ct'], cwd)?.trim();
+  return out ? (Date.now() / 1000 - Number(out)) / 60 : null;
+}
+
+// Minutes since the OLDEST change not yet committed in a worktree (build folders left out); null when it is clean.
+function unsavedMin(wt) {
+  const out = sh('git', ['--no-optional-locks', '-C', wt, 'status', '--porcelain', '--untracked-files=all']);
+  if (out === null) return null;
+  let oldest = null;
+  for (const line of out.split('\n')) {
+    const f = line.slice(3).trim().replace(/^"|"$/g, '');
+    if (!f || /^(build|listen\/|screenshots\/)/.test(f) || f.includes('/build')) continue;
+    try { const t = statSync(join(wt, f)).mtimeMs / 1000; oldest = oldest === null ? t : Math.min(oldest, t); } catch { /* gone */ }
+  }
+  return oldest === null ? null : (Date.now() / 1000 - oldest) / 60;
+}
+
+function listWorktrees() {
+  const root = join(projectRoot, '.claude', 'worktrees');
+  try { return readdirSync(root).sort().map((d) => join(root, d)).filter((d) => { try { statSync(join(d, '.git')); return true; } catch { return false; } }); } catch { return []; }
+}
+
+// Is this agent still running, by the cap hook's count? Unknown state counts as running (the safe side).
+const CLAIM_LAPSE_MIN = 15;
+
+function agentRunning(aid) {
+  let st;
+  try { st = JSON.parse(readFileSync(join(homedir(), '.claude/agent-cap-state.json'), 'utf8')); } catch { return true; }
+  const sessions = Object.values(st).filter((s) => s && typeof s === 'object');
+  if (sessions.some((s) => aid in (s.running ?? {}))) return true;
+  return !sessions.some((s) => aid in (s.known ?? {}));
+}
+
+function sayOnce(key, msg, now, st) {
+  if (now - (st[key] ?? 0) < REPEAT_MIN * 60) return null;
+  st[key] = now;
+  return msg;
+}
+
+export function run(event, { now = Date.now() / 1000, rows = null, commitMin = null, state = null, worktrees = null, late = null } = {}) {
+  const st = state ?? loadState();
+  const said = [];
+  const tid = event.tool_use_id ?? '';
+  const input = event.tool_input ?? {};
+  if (event.hook_event_name === 'PreToolUse') {
+    let cmd = event.tool_name === 'Bash' ? String(input.command ?? '') : '';
+    cmd = cmd.replace(/<<-?\s*['"]?(\w+)['"]?[^\n]*\n[\s\S]*?\n\s*\1\s*(?:\n|$)/g, '\n'); // a heredoc body is text, not a loop
+    if (/until\s+!\s*pgrep\s+-[a-z]*f\s+(['"])(?!\[)/.test(cmd)) {
+      return ['REFUSED: `until ! pgrep -f "..."` never ends: pgrep -f finds the loop\'s own command line, which holds the same words. Run the work ' +
+        "with run_in_background and wait for its notification; or, if you must poll, make the pattern unable to match itself: pgrep -f '[T]abulaFaceProbe --x'"];
+    }
+    if (tid) (st.starts ??= {})[tid] = now;
+    if (!state) saveState(st);
+    return [];
+  }
+  // 1. the call itself
+  const started = tid ? st.starts?.[tid] : undefined;
+  if (tid && st.starts) delete st.starts[tid];
+  if (started !== undefined && event.tool_name !== 'AskUserQuestion' && (now - started) / 60 > SLOW_CALL_MIN) {
+    said.push(`this call took ${((now - started) / 60).toFixed(0)} min (more than ${SLOW_CALL_MIN}): \`${String(input.command ?? event.tool_name ?? '').slice(0, 80)}\`. Find what made it slow before running it again; never wait on it as normal`);
+  }
+  // 2. the machine, once a minute at most
+  if (now - (st.looked ?? 0) >= LOOK_EVERY_S || rows !== null) {
+    st.looked = now;
+    for (const [key, msg] of machineFindings(rows ?? processes())) { const m = sayOnce(key, msg, now, st); if (m) said.push(m); }
+  }
+  // 3. each agent's own worktree, learned from the commands it runs (.claude/worktrees/<name>)
+  const who = event.agent_id ?? 'main';
+  if (who !== 'main') (st.seen ??= {})[who] = now; // when each agent last ran anything: a finished agent's claim lapses (below)
+  const text = `${input.command ?? ''} ${input.file_path ?? ''}`;
+  for (const m of text.matchAll(/(\/[^\s'"]*?\/\.claude\/worktrees\/([\w.-]+))/g)) {
+    if (who === 'main') continue;
+    st.owner ??= {};
+    let prev = st.owner[m[2]];
+    // a claim lapses with its agent: known stopped, or quiet for CLAIM_LAPSE_MIN (the agent-cap state that said "stopped" is no
+    // longer written, so without the quiet rule a finished agent kept its worktree for ever and no successor could reuse its build)
+    if (prev && prev !== who && (!agentRunning(prev) || now - (st.seen?.[prev] ?? 0) > CLAIM_LAPSE_MIN * 60)) prev = null;
+    if (prev && prev !== who) {
+      const s = sayOnce(`shared-${m[2]}`, `the worktree .claude/worktrees/${m[2]} is already used by another agent (${prev}). Each agent works only in its own: ` +
+        'make yours (git worktree add --detach .claude/worktrees/<yours> main) and move your files there', now, st);
+      if (s) said.push(s);
+    } else {
+      st.owner[m[2]] = who;
+      (st.wt ??= {})[who] = m[1];
+    }
+  }
+  const mine = who !== 'main' ? st.wt?.[who] : null;
+  // its git status at most once a minute (KWB-24: two git commands on every call of every agent)
+  if (mine && (rows !== null || now - (st.checked?.[mine] ?? 0) >= LOOK_EVERY_S)) {
+    if (rows === null) (st.checked ??= {})[mine] = now;
+    const u = rows === null ? unsavedMin(mine) : null; // a selftest case: never git on a made-up path
+    const cmn = commitMin ?? lastCommitMin(mine);
+    if (u !== null && u > SAVE_MIN) {
+      const s = sayOnce(`unsaved-${mine}`, `your worktree (${mine.split('/').pop()}) holds work unsaved for ${u.toFixed(0)} min (more than ${SAVE_MIN}). Save it now: ${CFG.saveCommand}`, now, st);
+      if (s) said.push(s);
+    } else if (cmn !== null && cmn > QUIET_MIN) {
+      const s = sayOnce(`quiet-${mine}`, `your worktree's last commit was ${cmn.toFixed(0)} min ago (more than ${QUIET_MIN}). If you are waiting on something slow, find why it is slow; if the work moved, save it`, now, st);
+      if (s) said.push(s);
+    }
+  }
+  // 4. the controller sees every worktree: a git status in each runs in its own process, never in the hook (KWB-24: a synth's
+  // 125 worktrees took over a minute, the hook was killed at its timeout before it saved `scanned`, so every call scanned again)
+  const scan = worktrees ?? (rows !== null ? {} : null);
+  const tell = (list) => list.length && said.push(`worktrees holding work unsaved for more than ${SAVE_MIN} min: ${list.join(', ')}. Ask their agents to save (${CFG.saveCommand}), or find why they stall`);
+  if (who === 'main' && (now - (st.scanned ?? 0) >= SCAN_MIN * 60 || scan !== null)) {
+    st.scanned = now;
+    if (scan) tell(lateOf(scan));
+    else { saveState(st); scanLater(); }
+  }
+  const found = late ?? (rows === null ? readLate() : null);
+  if (who === 'main' && found && found.at > (st.lateTold ?? 0)) { st.lateTold = found.at; tell(found.list); }
+  st.starts = Object.fromEntries(Object.entries(st.starts ?? {}).filter(([, v]) => now - v < 86400));
+  if (!state) saveState(st);
+  return said;
+}
+
+const lateOf = (unsaved) => Object.entries(unsaved).filter(([, u]) => u !== null && u > SAVE_MIN).map(([wt, u]) => `${wt.split('/').pop()} (${u.toFixed(0)} min)`);
+const LATE = join(STATE, 'late.json');
+function readLate() { try { return JSON.parse(readFileSync(LATE, 'utf8')); } catch { return null; } }
+function scanLater() { try { spawn(process.execPath, [fileURLToPath(import.meta.url), '--scan-worktrees'], { cwd: projectRoot, detached: true, stdio: 'ignore', env: process.env }).unref(); } catch { /* next time */ } }
+function scanNow() {
+  const list = lateOf(Object.fromEntries(listWorktrees().map((wt) => [wt, unsavedMin(wt)])));
+  try { mkdirSync(STATE, { recursive: true }); writeFileSync(`${LATE}.${process.pid}`, JSON.stringify({ at: Date.now() / 1000, list })); renameSync(`${LATE}.${process.pid}`, LATE); } catch { /* next time */ }
+  return 0;
+}
+
+function loadState() { try { return JSON.parse(readFileSync(join(STATE, 'state.json'), 'utf8')); } catch { return {}; } }
+function saveState(st) {
+  try {
+    mkdirSync(STATE, { recursive: true });
+    const tmp = join(STATE, `state.${process.pid}.json`);
+    writeFileSync(tmp, JSON.stringify(st));
+    renameSync(tmp, join(STATE, 'state.json'));
+  } catch { /* the guard never stops work by failing itself */ }
+}
+
+function selftest() {
+  let bad = 0;
+  const expect = (name, said, want) => { if ((said.length > 0) !== want) { bad += 1; console.error(`FAIL  ${name}: ${said.length ? 'said' : 'quiet'}`); } };
+  const G = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome --headless=new --disable-gpu';
+  const post = (extra = {}) => ({ hook_event_name: 'PostToolUse', ...extra });
+  const at = (rows, extra = {}) => ({ now: 5000, state: {}, rows, commitMin: 1, ...extra });
+  const st = {};
+  run({ hook_event_name: 'PreToolUse', tool_use_id: 'a' }, { now: 1000, state: st, rows: [], commitMin: 1 });
+  expect('a call of 12 min', run(post({ tool_use_id: 'a', tool_input: { command: 'bash tools/build-panel.sh' } }), { now: 1720, state: st, rows: [], commitMin: 1 }), true);
+  run({ hook_event_name: 'PreToolUse', tool_use_id: 'b' }, { now: 2000, state: st, rows: [], commitMin: 1 });
+  expect('a call of 2 min', run(post({ tool_use_id: 'b' }), { now: 2120, state: st, rows: [], commitMin: 1 }), false);
+  const exp = 'node /x/kit/synthpanel-creator/bin/synthpanel.js export-native design/export-spec.json';
+  expect('an export of 7 min', run(post(), at([[1, 420, exp]])), true);
+  expect('an export of 30 s', run(post(), at([[1, 30, exp]])), false);
+  expect('12 headless Chromes', run(post(), at(Array.from({ length: 12 }, (_, i) => [i, 10, G]))), true);
+  expect('2 headless Chromes of 10 s', run(post(), at([[0, 10, G], [1, 10, G]])), false);
+  expect('a headless Chrome of a day', run(post(), at([[9, 93600, G]])), true);
+  expect('a ctest of an hour', run(post(), at([[3, 3600, 'ctest --test-dir build -j4']])), true);
+  expect('a probe of 25 min', run(post(), at([[4, 1500, '/x/build/SynthFaceProbe_artefacts/RelWithDebInfo/SynthFaceProbe --press-all']])), true);
+  const A = (command, who = 'a1') => post({ agent_id: who, tool_input: { command } });
+  expect("an agent's worktree quiet for 90 min", run(A('cd /x/.claude/worktrees/k2 && make'), at([], { commitMin: 90 })), true);
+  const s2 = {};
+  run(A('cd /x/.claude/worktrees/k2 && make'), { now: 5000, state: s2, rows: [], commitMin: 90 });
+  expect('the same said again a minute later', run(A('ls'), { now: 5060, state: s2, rows: [], commitMin: 90 }), false);
+  const s3 = {};
+  run(A('cd /x/.claude/worktrees/onechrome && ls', 'main-ish'), { now: 5000, state: s3, rows: [], commitMin: 1 });
+  expect('a second agent in the same worktree', run(A('cd /x/.claude/worktrees/onechrome && vi', 'a2'), { now: 5001, state: s3, rows: [], commitMin: 1 }), true);
+  const s4 = {};
+  run(A('cd /x/.claude/worktrees/handed && ls', 'first'), { now: 5000, state: s4, rows: [], commitMin: 1 });
+  expect('a successor after the first agent has been quiet 16 min takes the worktree', run(A('cd /x/.claude/worktrees/handed && ls', 'next'), { now: 5000 + 16 * 60, state: s4, rows: [], commitMin: 1 }), false);
+  expect('and the first agent coming back finds it taken', run(A('cd /x/.claude/worktrees/handed && ls', 'first'), { now: 5000 + 17 * 60, state: s4, rows: [], commitMin: 1 }), true);
+  expect('the controller told of a worktree unsaved for 45 min', run(post(), at([], { worktrees: { '/x/.claude/worktrees/guide': 45 } })), true);
+  expect('the controller, nothing unsaved', run(post(), at([], { worktrees: { '/x/.claude/worktrees/guide': 5 } })), false);
+  const told = {};
+  const found = { at: 4000, list: ['guide (45 min)'] };
+  expect('the background scan\'s finding is told', run(post(), at([], { state: told, late: found })), true);
+  expect('and told once', run(post(), { ...at([], { state: told, late: found }), now: 5100 }), false);
+  const pre = (command) => run({ hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command } }, { now: 5000, state: {} });
+  const loop = ['until', '!', 'pgrep', '-f', '"cmake --build"', '>/dev/null;', 'do', 'sleep', '5;', 'done'].join(' ');
+  expect('the endless wait loop inside a heredoc (text for a program) passes', pre(`python3 - <<'EOF'\nprint('${loop}')\nEOF\necho ok`), false);
+  expect('the same loop after a heredoc is still refused', pre(`cat > a.txt <<EOF\nx\nEOF\n${loop}`), true);
+  expect('REFUSED: the endless wait loop', pre(loop), true);
+  expect('a pgrep that cannot match itself passes', pre(loop.replace('"cmake --build"', "'[c]make --build'")), false);
+  expect('a shell that names a build is not a build', run(post(), at([[8, 3600, '/bin/zsh -c cmake --build build -j6 && ctest']])), false);
+  expect('a build of 40 min', run(post(), at([[8, 2400, 'cmake --build build -j6']])), true);
+  expect('a shell that names a probe is not a probe', run(post(), at([[9, 3000, '/bin/zsh -c ./build/SynthFaceProbe_artefacts/RelWithDebInfo/SynthFaceProbe --walk x']])), false);
+  expect('a quiet machine', run(post(), at([[5, 4000, '/bin/zsh'], [6, 20, 'cmake --build build -j4']], { commitMin: 5, worktrees: {} })), false);
+  const wait = "/bin/zsh -c eval 'until grep -q exit /tmp/x.log; do sleep 15; done'";
+  expect('a wait loop of a day', run(post(), at([[7, 90000, wait]])), true);
+  expect('a wait loop of 5 min', run(post(), at([[7, 300, wait]])), false);
+  expect('a question answered after 12 min is not a slow call (WB-22)', run(post({ tool_name: 'AskUserQuestion', tool_use_id: 'q1' }), { now: 5720, state: { starts: { q1: 5000 } }, rows: [] }), false);
+  expect('a Bash call of 12 min still is', run(post({ tool_name: 'Bash', tool_use_id: 'b1', tool_input: { command: 'x' } }), { now: 5720, state: { starts: { b1: 5000 } }, rows: [] }), true);
+  expect('a snake-case probe of 25 min', run(post(), at([[4, 1500, '/x/out/probes/engines/synth_engines_probe --only FIRESAW']])), true);
+  CFG.probePattern = '\\S*/bench_\\w+'; // a project's own probe pattern (guards.time.probePattern)
+  expect("a project's own probe pattern: its bench of 25 min", run(post(), at([[4, 1500, '/x/out/bench_voices --all']])), true);
+  expect("a project's own probe pattern: another program is no probe", run(post(), at([[4, 1500, '/x/out/synth_engines_probe']])), false);
+  Object.assign(CFG, DEFAULTS);
+  if (etimeS('1-02:03:04') !== 93784 || etimeS('05:06') !== 306) { bad += 1; console.error('FAIL  ps etime'); }
+  console.log(`time-guard selftest: ${bad ? `${bad} wrong` : 'OK'}`);
+  return bad ? 1 : 0;
+}
+
+function main(text) {
+  let event;
+  try { event = JSON.parse(text); } catch { return 0; }
+  Object.assign(CFG, DEFAULTS, readLayout(projectRoot).guards?.time ?? {});
+  let said;
+  try { said = run(event); } catch { return 0; } // the guard never stops work by failing itself
+  if (!said.length) return 0;
+  process.stderr.write(`time-guard: ${said.join('\n time-guard: ')}\n`);
+  return 2;
+}
+
+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('--scan-worktrees') ? scanNow() : await asHook('time-guard', main));