@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

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));

package/packs/synth-creator/hooks/user-asks.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// user-asks: everything the user asked, back in front of the session, so nothing discussed is forgotten (2026-10-11:
+// "Sometimes you 'forget' certain things we had discussed ... maybe you also need to check memory at this time?").
+//
+// Every message the user sends is in the session's transcript: a turn of their own (type `user`, their text) or a message sent
+// while the session was working (a `queue-operation` enqueue). This reads them back, with their times, two ways:
+//   - a SessionStart hook on `compact`: their asks of the last HOURS hours go back into the context, word for word;
+//   - idle-wake.mjs: the wake after their silence carries the same list.
+// THE LEDGER: each ask has a status and its evidence, beside the project's own memory folder
+// (~/.claude/projects/<the project's path, every character not a letter or digit made a dash>/asks-ledger.json), outside
+// git, so compaction cannot touch it. Only OPEN asks come back word for word; done or answered ones are a count; needs-user
+// and planned ones are one line each. Marking takes evidence (a commit, a bug number, a build.md step, or where it is planned):
+//   node user-asks.mjs --transcript <path> [--hours 24] [--all]
+//   node user-asks.mjs --mark <id> done|answered|planned|needs-user|not-an-ask "<evidence>"
+//   node user-asks.mjs --selftest
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { asHook, isMain } from './lib/hook-log.mjs';
+
+export const HOURS = Number(process.env.TIMS_ASKS_HOURS ?? 24);
+const STATUSES = new Set(['done', 'answered', 'planned', 'needs-user', 'not-an-ask', 'open']);
+const QUIET = new Set(['done', 'answered', 'not-an-ask']);
+const HEAD = (h, n) => `TIM'S ASKS from the last ${h.toFixed(0)} hours (${n} messages). Compaction may have dropped some of them from what you remember; ` +
+  'the ledger below holds which are done, with evidence. Every OPEN one is work: check it is not already done (then mark it with the evidence), ' +
+  'finish it, or if it needs the user say so in one line and mark it needs-user. Do not wait to be reminded.';
+
+const mainRoot = (p) => p.replace(/\/\.claude\/worktrees\/[^/]+(\/.*)?$/, '');
+export const ledgerFor = (root) => join(homedir(), '.claude', 'projects', mainRoot(resolve(root)).replace(/[^A-Za-z0-9]/g, '-'), 'asks-ledger.json');
+export const LEDGER = process.env.TIMS_ASKS_LEDGER || ledgerFor(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+
+// The user's own words in a transcript entry, or null (a tool's result, a hook's or the system's text, an agent's report).
+function textOf(e) {
+  if (e.type === 'queue-operation' && e.operation === 'enqueue') return typeof e.content === 'string' ? e.content : null;
+  if (e.type === 'user' && !e.isMeta && !e.isSidechain) {
+    let c = e.message?.content;
+    if (Array.isArray(c)) c = c.filter((b) => b && b.type === 'text').map((b) => b.text ?? '').join('\n');
+    return typeof c === 'string' ? c : null;
+  }
+  return null;
+}
+const isSystem = (t) => { const s = t.trimStart(); return !s || /^(<|\[SYSTEM|\[Subagent|idle-wake:|This session is being continued|Caveat:)/.test(s); };
+const squash = (t) => t.split(/\s+/).filter(Boolean).join(' ');
+
+export function asks(transcript, hours = HOURS, now = Date.now() / 1000) {
+  let text;
+  try { text = readFileSync(transcript, 'utf8'); } catch { return []; }
+  const out = [];
+  const seen = new Set();
+  for (const line of text.split('\n')) {
+    if (!line.includes('"queue-operation"') && !line.includes('"type":"user"') && !line.includes('"type": "user"')) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    const t = textOf(e);
+    if (!t || isSystem(t)) continue;
+    const when = e.timestamp ? Date.parse(e.timestamp) / 1000 : null;
+    if (when !== null && !Number.isNaN(when) && now - when > hours * 3600) continue;
+    const key = squash(t);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push([Number.isNaN(when) ? null : when, t.trim()]);
+  }
+  return out;
+}
+
+export const askId = (t) => createHash('sha1').update(squash(t)).digest('hex').slice(0, 8);
+export function loadLedger(path = LEDGER) { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; } }
+
+export function mark(id, status, evidence = '', path = LEDGER) {
+  if (!STATUSES.has(status)) throw new Error(`status is one of ${[...STATUSES].sort().join(', ')}`);
+  if (status !== 'open' && !evidence.trim()) throw new Error('evidence is required: a commit, a bug number, a build.md step, or where it is planned');
+  const led = loadLedger(path);
+  led[id] = { status, evidence: evidence.trim(), marked: new Date().toISOString().slice(0, 19) };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(`${path}.tmp`, JSON.stringify(led, null, 1));
+  renameSync(`${path}.tmp`, path);
+}
+
+export function render(items, hours = HOURS, ledger = null, every = false) {
+  if (!items.length) return '';
+  const led = ledger ?? loadLedger();
+  const stamp = (w) => (w ? new Date(w * 1000).toISOString().slice(5, 16).replace('T', ' ') : '     ?     ');
+  const rows = items.map(([w, t]) => { const id = askId(t); return { w, t, id, st: led[id]?.status ?? 'open', ev: led[id]?.evidence ?? '' }; });
+  const open = rows.filter((r) => r.st === 'open');
+  const waits = rows.filter((r) => r.st === 'needs-user' || r.st === 'planned');
+  const quiet = rows.filter((r) => QUIET.has(r.st));
+  const lines = [HEAD(hours, items.length),
+    `LEDGER (${LEDGER}): ${quiet.length} done or answered, ${waits.length} waiting on the user or planned, ${open.length} OPEN. Only the open ones are work; ` +
+    'do not redo a done one. When one is done, mark it with its evidence: node .claude/hooks/user-asks.mjs --mark <id> done "<commit / bug / step>" ' +
+    '(or answered, planned, needs-user, not-an-ask).'];
+  if (open.length) { lines.push('OPEN, word for word:'); for (const r of open) lines.push(`- ${r.id} [${stamp(r.w)}] ${squash(r.t).slice(0, 1200)}`); }
+  if (waits.length) { lines.push('WAITING (one line each):'); for (const r of waits) lines.push(`- ${r.id} [${stamp(r.w)}] ${r.st}: ${r.ev.slice(0, 160)} <- ${squash(r.t).slice(0, 90)}`); }
+  if (every && quiet.length) { lines.push('DONE / ANSWERED:'); for (const r of quiet) lines.push(`- ${r.id} [${stamp(r.w)}] ${r.st}: ${r.ev.slice(0, 120)} <- ${squash(r.t).slice(0, 90)}`); }
+  return lines.join('\n');
+}
+
+function selftest() {
+  const now = Date.now() / 1000;
+  const iso = (dt) => new Date((now - dt) * 1000).toISOString();
+  const rows = [
+    { type: 'user', timestamp: iso(3600), message: { content: 'add 20 80s bass arps' } },
+    { type: 'queue-operation', operation: 'enqueue', timestamp: iso(1800), content: 'and make a hook for chrome' },
+    { type: 'queue-operation', operation: 'remove', timestamp: iso(1799), content: 'and make a hook for chrome' },
+    { type: 'user', timestamp: iso(1700), message: { content: [{ type: 'tool_result', content: 'ok' }] } },
+    { type: 'user', timestamp: iso(1600), message: { content: '<task-notification>done</task-notification>' } },
+    { type: 'user', timestamp: iso(1500), isMeta: true, message: { content: 'a meta line' } },
+    { type: 'user', timestamp: iso(90000), message: { content: 'an ask from two days ago' } },
+    { type: 'user', timestamp: iso(60), message: { content: [{ type: 'text', text: 'is it correct the agents still run?' }] } },
+    { type: 'assistant', timestamp: iso(30), message: { content: "Next I'd build P4." } },
+  ];
+  const t = join(tmpdir(), `user-asks-${process.pid}.jsonl`);
+  writeFileSync(t, rows.map((r) => JSON.stringify(r)).join('\n'));
+  const items = asks(t, 24, now);
+  rmSync(t, { force: true });
+  const led = `${t}.ledger.json`;
+  mark(askId('add 20 80s bass arps'), 'done', 'commit abc123', led);
+  const out = render(items, 24, loadLedger(led));
+  rmSync(led, { force: true });
+  const checks = [
+    ['a done ask is counted, not listed; the open ones are listed word for word', out.includes('1 done or answered') && out.includes('2 OPEN') && !out.includes('add 20 80s bass arps') && out.includes('and make a hook for chrome')],
+    ['done without evidence is refused', (() => { try { mark('x', 'done', '', led); return false; } catch { return true; } })()],
+    ["the user's own words, mid-turn ones too, no tool results, system text, meta lines, their old asks or the assistant",
+      JSON.stringify(items.map(([, x]) => x)) === JSON.stringify(['add 20 80s bass arps', 'and make a hook for chrome', 'is it correct the agents still run?'])],
+    ["the ledger is the project's own, beside its memory, and a worktree's is its project's",
+      ledgerFor('/Users/dev/projects/my_synth') === join(homedir(), '.claude/projects/-Users-dev-projects-my-synth/asks-ledger.json') &&
+      ledgerFor('/Users/dev/projects/my_synth/.claude/worktrees/agent-x') === ledgerFor('/Users/dev/projects/my_synth')],
+  ];
+  for (const [name, ok] of checks) if (!ok) console.error(`FAIL  ${name}`);
+  const bad = checks.filter(([, ok]) => !ok).length;
+  console.log(`user-asks selftest: ${bad ? 'FAIL' : 'OK'}`);
+  return bad ? 1 : 0;
+}
+
+function main(argv) {
+  if (argv.includes('--selftest')) return selftest();
+  const i = argv.indexOf('--mark');
+  if (i >= 0) {
+    try { mark(argv[i + 1], argv[i + 2], argv[i + 3] ?? ''); } catch (e) { console.error(e.message); return 1; }
+    console.log(`marked ${argv[i + 1]} ${argv[i + 2]}`);
+    return 0;
+  }
+  const ti = argv.indexOf('--transcript');
+  if (ti >= 0) {
+    const h = argv.includes('--hours') ? Number(argv[argv.indexOf('--hours') + 1]) : HOURS;
+    console.log(render(asks(argv[ti + 1], h), h, null, argv.includes('--all')));
+    return 0;
+  }
+  // A HOOK (SessionStart on compact): what it prints is added to the session's context
+  return asHook('user-asks', hookMain);
+}
+
+function hookMain(input) {
+  let event;
+  try { event = JSON.parse(input); } catch { return 0; }
+  const text = render(asks(event.transcript_path ?? ''));
+  if (text) console.log(text);
+  return 0;
+}
+export const hook = hookMain; // run-hooks.mjs calls it with the event's text (KWB-24)
+
+// Run as a hook or a command (not imported by idle-wake). Real paths: /var and /private/var are one folder on a Mac.
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) process.exit(await main(process.argv.slice(2)));

package/packs/synth-creator/pack.json

@@ -0,0 +1,136 @@
+{
+  "name": "synth-creator",
+  "version": "1.0.0",
+  "description": "The synth-creator configuration's own laws, installed with it and never by another: the build queue (build-guard), the time watch, the spec lock, frozen fixes, read-only vendored code and copy trees, staging by name, the session watches (idle-wake, user-asks, build-sweep), and the rules and skill a synth build lives by.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/synth-creator"
+  },
+  "keywords": [
+    "synth",
+    "build"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "configurationPack": true,
+  "folders": {},
+  "concepts": {},
+  "skillsIn": null,
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/frozen-files.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-vendor.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-lock.mjs\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/stage-guard.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/time-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/time-guard.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/idle-wake.mjs\"",
+            "asyncRewake": true,
+            "timeout": 1000
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/user-asks.mjs\"",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-sweep.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/build-sweep.mjs\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ]
+  },
+  "optIn": [
+    "hooks/user-asks.mjs",
+    "hooks/idle-wake.mjs",
+    "hooks/build-sweep.mjs",
+    "checks/ui-drawn-in-code.json"
+  ]
+}

package/packs/synth-creator/rules/copy-trees-read-only.md

@@ -0,0 +1,25 @@
+---
+# concepts: copy-trees
+paths:
+  - "placeholder"
+---
+
+# Copy trees: copied, pinned, read-only
+
+A copy tree is a folder of kind `"copy"` in `.claude/layout.json`: another project's code, copied unchanged and proved
+identical (the `copy-and-prove` skill). This rule loads in every copy tree and in `layout.json`, where one is declared.
+
+<constraints>
+Always do:
+- Treat every file here as a copy of another project's file at a named commit. It changes only through the project's copy tools (`guards.copy.tools` in `layout.json`): from its source, unchanged, or as a pinned change the user said yes to and null tests proved.
+- Give every file its origin before it comes in (repo, path, commit, SHA-256, licence row). The licence row in `docs/licences.md` comes first.
+- Prove the copy before anything uses it: the source's own render fingerprinted, the copy IDENTICAL, one coefficient changed in the copy seen DIFFERENT.
+- Fix the code that uses the copy. If the copy itself must change, ask the user and pin the change.
+- Start a new copy tree only in `.claude/layout.json`, as a folder with `"kind": "copy"`. The guard, this rule and the checks then cover it with no other change.
+- Change a file that measured identical only after it is promoted out of the copy tree into the project's own code (a folder of kind `"own"`), with its origin record kept.
+
+Never do:
+- Edit, write, move or delete a file here by hand or by shell. The `protect-vendor` hook refuses it; only git and the sanctioned copy tools get through.
+- Put a file here without its origin.
+- Copy hardware, brand or machine names into anything that reaches the product: a program name, a label, a string in the binary.
+</constraints>

package/packs/synth-creator/rules/debug-by-measurement.md

@@ -0,0 +1,20 @@
+---
+# concepts: cpp, tests
+paths:
+  - "placeholder"
+---
+
+# Debug by measuring, one hypothesis at a time
+
+<constraints>
+Always do:
+- Reproduce first, then measure: render the case offline, read the numbers (`measure-tone`, a probe, a sanitizer, a log), and only then form a cause.
+- State one falsifiable hypothesis ("the click is the filter state reset at voice steal, because the click lines up with sample N of the steal") and test it with one change.
+- Treat "the host is wrong", "it's JUCE", "it's the driver" as a hypothesis to disprove with a minimal probe, never as the answer. Assume our code is wrong until a probe proves otherwise.
+- After three fixes that didn't work, stop changing code. Report what was tried, what each measurement showed, and whether the design itself is the problem.
+
+Never do:
+- Change several things at once, then listen.
+- Tweak constants until it "sounds right" without a measurement before and after.
+- Start a fourth fix attempt on the same symptom without telling the user.
+</constraints>