sawbuck 0.1.46 → 0.1.48

package/sawbuck.mjs

@@ -1,47 +1,66 @@
 #!/usr/bin/env node
 // sawbuck, the CLI. Zero-dep.
-// `attach` wires the Claude Code hooks into a repo; `detach` removes them and leaves the repo exactly as it was. The
+// `attach` wires the Claude Code hooks into a repo; `detach` removes them, and the record stays until `--purge`. The
 // repo never imports Sawbuck. Rides two engines: promptwheel (the check) + @promptwheel/logbook.
 //
 // attach writes a receipt to .git/sawbuck/attach.json recording every file it created or modified. detach reads it and
-// reverses exactly that; `detach --verify` proves the repo came back clean; `doctor` checks the attachment still resolves.
+// reverses exactly that, and still takes our hooks out when the receipt is lost; `detach --verify` proves the wiring is
+// gone and names what is left; `doctor` runs what each hook runs.
 
+import './pipe.mjs';
 import { execFileSync } from 'node:child_process';
 import { erasedBlock, erasedCommits } from './rewrites.mjs';
 import { steersReport } from './steers.mjs';
 import { rulesCli } from './rules.mjs';
 import { shapeCli } from './shape.mjs';
 import { ensureExcluded, clearExcluded, EXCLUDED, RECORD_DIRS } from './exclude.mjs';
-import { repoState } from './repo-state.mjs';
-import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, unlinkSync, rmdirSync, rmSync, readdirSync } from 'node:fs';
-import { basename, join, dirname, resolve } from 'node:path';
+import { repoState, hooksIn, OURS, S_START } from './repo-state.mjs';
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, rmdirSync, rmSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, dirname, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { PW } from './bins.mjs';
-import { frameBlock, mandatesInForce, protectedDirty, blobAt, lockState } from './contract.mjs';
+import { frameBlock, mandatesInForce, protectedDirty, protectedAmong, blobAt, lockState } from './contract.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
 const HOOK = join(HERE, 'sawbuck-hook.mjs');
 // run the engine and parse its JSON verdict (it prints JSON even when it exits nonzero)
+// A commit message is not a person: an agent can write a Sawbuck-Allow trailer, so no sawbuck path honors one
+// (the Stop hook and the git hook do the same through reflect). `--allow` is the declared override.
 function gateReport(repo, a) {
-  let o = '', code = 0;
-  try { o = execFileSync(process.execPath, [PW, ...a, '--no-record', '--json'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 120000 }); }
-  catch (e) { o = (e.stdout || '').toString(); code = e.status || 0; }
+  let o = '', err = '', code = 0;
+  try { o = execFileSync(process.execPath, [PW, ...a, '--no-record', '--json'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, PROMPTWHEEL_NO_ALLOW_TRAILER: '1' }, timeout: +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 120000 }); }
+  catch (e) { o = (e.stdout || '').toString(); err = e.signal ? 'the check timed out' : (e.stderr || '').toString(); code = e.status || 0; }
   let rep = null; try { rep = JSON.parse(o.slice(o.indexOf('{'))); } catch {}
-  return { rep, code };
+  // the engine's own reason, without its zero-config notice
+  const why = err.split('\n').filter((l) => l.trim() && !/^no promptwheel\.config\.json, auto-gating/.test(l)).join(' ').trim();
+  return { rep, code, why };
+}
+// why nothing could be measured, in words that match the case: no test command, tests red on both sides, or a
+// win the source-only re-run could not apply. `sawbuck init` only where there is no config to edit yet.
+function inconclusiveWhy(rep, repo) {
+  const ms = (rep && rep.metrics) || [];
+  const m = ms.find((x) => x.inert) || ms[0];
+  if (ms.some((x) => x.unprovable)) return 'a win here could not be re-proved, because the source-only re-run did not apply. Do not trust this green on its own.';
+  const hasCfg = existsSync(join(repo, 'promptwheel.config.json'));
+  let cmd = '';
+  try { cmd = String((JSON.parse(readFileSync(join(repo, 'promptwheel.config.json'), 'utf8')).metrics || []).find((x) => x && x.name === (m && m.name))?.cmd || ''); } catch {}
+  const placeholder = /set your test command/.test(cmd) || (!hasCfg && !detectedTests(repo));
+  const where = hasCfg ? 'in promptwheel.config.json' : 'with `sawbuck init`, then in promptwheel.config.json';
+  if (placeholder) return `there is no test command here, so nothing was measured. It finds npm, pytest, cargo and go tests on its own. Set yours ${where} (the cmd of "${(m && m.name) || 'tests_pass'}").`;
+  return `"${(m && m.name) || 'tests_pass'}" failed before and after this change, so there was no win or loss to measure. If your tests are red, fix them first. If they pass for you, the clean copy the check runs in is missing something: set setup or linkDirs ${where}.`;
+}
+// the test commands the engine finds with no config (promptwheel's detectTestCmd)
+function detectedTests(repo) {
+  const has = (f) => existsSync(join(repo, f));
+  if (['go.mod', 'Cargo.toml', 'pyproject.toml', 'setup.py', 'pytest.ini'].some(has)) return true;
+  try { return !!JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8')).scripts?.test; } catch { return false; }
 }
 // is the metric live (actually ran), or inert (never ran in isolation)?
 const metricLive = (m) => !!m && !m.inert && m.status !== 'unmeasurable' && m.before != null;
-const S_START = '# >>> sawbuck >>>';
 const S_END = '# <<< sawbuck <<<';
-const BLOCK_RE = new RegExp(`\\n?${S_START}[\\s\\S]*?${S_END}\\n?`, 'g');
-// the record/state dirs the engines write into the worktree; excluded locally so
-// attach never dirties `git status`.
-// The record Sawbuck keeps on disk but must never let dirty git status: the engine records
-// plus the logbook's root working-set (ledger cache, digests, annotation planes). It is
-// memory, not the user's source, a user who wants LOGBOOK.md committed still can explicitly
-// (exclude only affects UNtracked files).
+const BLOCK_RE = new RegExp(`${S_START}[\\s\\S]*?${S_END}\\n?`, 'g');   // exactly what attach --git puts in, so taking it out leaves the bytes that were there
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -62,24 +81,38 @@ Usage:
                             Verify your latest change right now (working tree if dirty, else the last
                             commit, or the range you name). Zero-config, no attach, no hook. The
                             fastest way to see it work. Every promptwheel run flag passes through.
-                            Exit 0 verified · 1 regression · 2 gamed · 3 inconclusive · 64 could not run
-  sawbuck init [--yes] [--wizard] [--no-investigate] [--no-agent-block]
-                            Customize the rules (promptwheel.config.json), with notes from what your
-                            git history shows actually breaks, plus a short guide in AGENTS.md
-                            (--no-agent-block to skip). Wizard in a terminal, non-interactive in a pipe/CI (or --yes).
-  sawbuck attach [repo]     Check every Claude Code turn in this repo. --user for every repo. --dry-run prints the footprint
-  sawbuck detach [repo] [--user] [--verify] [--purge]
-                            Remove it and restore the repo (no flag: whatever is attached here); --verify
-                            proves it came back clean; --purge also deletes the record (.sawbuck/)
+                            Exit 0 pass (verified, held, or allowed) · 1 sent back (a regression or a
+                            protected path) · 2 gamed · 3 inconclusive · 64 could not run
+                            (--working with nothing uncommitted is 64 too)
+  sawbuck init [--yes] [--wizard] [--no-investigate] [--no-agent-block] [--force]
+                            Write promptwheel.config.json: your detected tests and the tripwires, with
+                            notes from what your git history shows actually breaks, plus a short guide in
+                            AGENTS.md (--no-agent-block to skip). Wizard in a terminal, non-interactive in
+                            a pipe/CI (or --yes). An existing config needs --force.
+  sawbuck attach [repo] [--user | --shared | --git] [--dry-run]
+                            Watch every Claude Code turn in this repo: protected paths at the end of each
+                            turn, a source-only re-run on each commit. --user: every repo that has a
+                            promptwheel.config.json. --shared: a tracked settings file a team commits.
+                            --git: a post-commit hook, for any other agent or none (commits in a linked
+                            worktree are not checked). --dry-run prints every file it would write
+  sawbuck detach [repo] [--user] [--all] [--verify] [--purge] [--dry-run]
+                            Remove the hooks (no flag: whatever is wired here; --all: every repo). The
+                            record stays, kept out of git status; --purge deletes it. --verify proves the
+                            wiring is gone and names what is left. --dry-run lists what would go
   sawbuck status [repo]     The inventory: caught over time + debt accruing now + whether it is armed. --json
                             --log [-n N] for the recent checks, newest first
   sawbuck debt [repo] [--since REF] [--fail-on undocumented|test|any|N]
                             The live suppression debt in HEAD, risk-ranked, undocumented flagged. --since REF
-                            shows only what a branch adds; --fail-on exits nonzero (a CI gate)
+                            shows only what a branch adds; --fail-on exits 1 when that debt (or, without
+                            --since, any live debt of that kind) is there (a CI gate)
   sawbuck context [repo]    Relevant history for the files you are changing (reverts, weakened tests, hot spots)
-  sawbuck doctor [repo]     Check the attachment still resolves to a live sawbuck
-  sawbuck contract          Give this repo its rules: protected paths, your tests (--dry-run to preview)
-                            --full adds supply-chain guards, the repo lock and a CI check; --strict makes them block
+  sawbuck doctor [repo]     Run what each hook runs (project and user level) and say if it still works,
+                            is incomplete, or is gone. --all lists every repo it is attached to and checks each
+  sawbuck contract [--dry-run] [--full] [--strict]
+                            Give this repo its rules: protected paths, the written rule, and your detected
+                            tests when there is no config yet (--dry-run to preview). --full adds supply-chain
+                            guards, the repo lock, and a CI check on a github.com repo with a real test
+                            command; --strict makes them block
   sawbuck rules --prepare   Gather your messages on this machine so an agent can propose the rules you never wrote
   sawbuck rules --check F   Keep only proposed rules with 2 quotes that are really yours
   sawbuck shape --prepare   Gather a sample of your messages so an agent can label what you push on
@@ -102,6 +135,11 @@ const repoRoot = () => gitTop(repoArg()) || repoArg();
 function gitPath(repo, rel) { try { return resolve(repo, execFileSync('git', ['-C', repo, 'rev-parse', '--git-path', rel], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()); } catch { return join(repo, '.git', rel); } }
 function gitDir(repo) { try { return resolve(repo, execFileSync('git', ['-C', repo, 'rev-parse', '--git-dir'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()); } catch { return join(repo, '.git'); } }
 const out = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
+// `detach --dry-run` walks the same path as the real detach and lists what it would touch, so the two cannot drift.
+// What a dry run "removed" reads as gone for the rest of the walk, so the steps that follow decide as they would for real.
+const planned = { lines: new Map(), gone: new Set(), receipts: new Map(), registry: null };
+const there = (p) => existsSync(p) && !planned.gone.has(p);
+const say = (s) => { if (!dry) out(s); };
 
 if (cmd === '--version' || cmd === '-v') { console.log(version); process.exit(0); }
 if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -109,17 +147,36 @@ if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
 
   sawbuck contract   give this repo its rules: protected paths, your tests
   sawbuck check      verify your latest change right now
+  sawbuck attach     make it automatic in Claude Code: protected paths each turn, every commit re-proved
   sawbuck status     what it has caught here
 
   sawbuck help --all   everything else`);
   process.exit(0);
 }
 
+// `sawbuck <command> --help`: that command's lines from the help, and nothing runs. Internal commands get the whole help.
+if (rest.includes('--help') || rest.includes('-h')) {
+  const own = []; let cur = null;
+  for (const l of help.split('\n')) { const m = l.match(/^  sawbuck (\S+)/); if (m) cur = m[1]; else if (!/^ {20,}\S/.test(l)) cur = null; if (cur === cmd) own.push(l); }
+  if (own.length || ['rank', 'frame', 'turn', '__hook'].includes(cmd)) { out(own.length ? `sawbuck ${version}\n\n${own.join('\n')}` : help); process.exit(0); }
+}
+// a flag a command does not know is an error, never a silent no-op. `check` is not here: it passes its flags to the
+// engine, which refuses the ones it does not know. --claude is what older installs pass: taken, not listed.
+const KNOWN = {
+  contract: ['--dry-run', '--full', '--strict'],
+  init: ['--yes', '-y', '--wizard', '--no-investigate', '--no-agent-block', '--force', '--preset'],
+  attach: ['--user', '--shared', '--git', '--dry-run', '--claude'],
+  detach: ['--user', '--all', '--verify', '--purge', '--dry-run', '--claude'],
+  doctor: ['--all'],
+  status: ['--json', '--log', '-n'],
+};
+if (KNOWN[cmd]) { const bad = rest.filter((a) => a.startsWith('-') && !KNOWN[cmd].includes(a)); if (bad.length) usage(`unknown flag ${bad.join(' ')} for ${cmd} (it takes ${KNOWN[cmd].filter((f) => f !== '--claude').join(', ')})`); }
+
 switch (cmd) {
   case 'contract': {
     const top = gitTop(repoArg());
     if (!top) usage(`${repoArg()} is not a git repository (run it inside your project)`);
-    try { execFileSync(process.execPath, [join(HERE, 'contract-cmd.mjs'), top, ...rest.filter((a) => ['--dry-run', '--full', '--strict'].includes(a))], { stdio: 'inherit' }); }
+    try { execFileSync(process.execPath, [join(HERE, 'contract-cmd.mjs'), top, ...rest.filter((a) => KNOWN.contract.includes(a))], { stdio: 'inherit' }); }
     catch (e) { process.exit(e.status || 1); }
     break;
   }
@@ -131,14 +188,14 @@ switch (cmd) {
   case 'status': {
     // the inventory: one view unioning what the check has caught over time, what debt is accruing
     // now, and whether it is armed here. The "show me everything" face. --log is the recent feed.
-    if (flags.has('--log')) { logReport(repoArg(), rest); break; }
-    try { execFileSync(process.execPath, [join(HERE, 'status.mjs'), '--repo', repoArg(), ...rest.filter((a) => a.startsWith('--'))], { stdio: 'inherit' }); }
+    if (flags.has('--log')) { logReport(repoRoot(), rest); break; }
+    try { execFileSync(process.execPath, [join(HERE, 'status.mjs'), '--repo', repoRoot(), ...rest.filter((a) => a.startsWith('--'))], { stdio: 'inherit' }); }
     catch (e) { process.exit(e.status || 1); }
     break;
   }
   case 'check': {
     // one-shot: gate your latest change right now (working tree if dirty, else the last commit),
-    // zero-config (the engine auto-detects your test command), and say plainly whether the win was
+    // zero-config (the engine finds npm, pytest, cargo and go tests), and say plainly whether the win was
     // earned. No attach, no hook, no record. The try-it-first on-ramp.
     // `sawbuck check` IS `promptwheel run` with a plain-spoken verdict: every engine flag passes
     // through (--base/--head/--repeat/--allow/--json/--no-detect-gaming), so there is one entry
@@ -148,7 +205,7 @@ switch (cmd) {
     for (let i = 0; i < rest.length; i++) {
       const a = rest[i];
       if (a === '--json') { json = true; continue; }
-      if (VALUE_FLAGS.has(a)) { const v = rest[++i]; if (v == null) die(`${a} needs a value`); if (a === '--base') base = v; else if (a === '--head') head = v; else pass.push(a, v); continue; }
+      if (VALUE_FLAGS.has(a)) { const v = rest[++i]; if (v == null) usage(`${a} needs a value`); if (a === '--base') base = v; else if (a === '--head') head = v; else pass.push(a, v); continue; }
       if (a.startsWith('--')) { pass.push(a); continue; }
       pos.push(a);
     }
@@ -159,24 +216,40 @@ switch (cmd) {
     // 64 (EX_USAGE) for every "could not run" below, never a verdict code: a script or CI must not read it as gamed (2).
     if (!g('rev-parse', '--git-dir')) { out(`🐴 sawbuck: ${repo} is not a git repo. The check re-proves a change against git history, so run it inside one (git init, then commit).`); process.exit(64); }
     if (!g('rev-parse', '--verify', 'HEAD')) { out('🐴 sawbuck: no commit yet. Make one, then `sawbuck check` verifies your next change against it.'); process.exit(64); }
-    const dirty = !base && !head && g('status', '--porcelain').length > 0;
+    const uncommitted = g('status', '--porcelain').length > 0;
+    const dirty = !base && !head && uncommitted;
+    // --working on a clean tree would read the tree against the commit it already is, and call that held
+    if (pass.includes('--working') && !uncommitted) { out('🐴 sawbuck: nothing uncommitted to check, the working tree is clean. `sawbuck check` verifies the last commit.'); process.exit(64); }
     // nothing to verify yet: a clean tree with no previous commit to diff against (a fresh repo). Say so
     // plainly instead of the generic "could not run" below, so the first run is not a dead end.
     if (!dirty && !base && !g('rev-parse', '--verify', 'HEAD~1')) { out('🐴 sawbuck: nothing to verify yet, the working tree is clean and this is the only commit. Make a change (or add one more commit), then `sawbuck check` re-proves the win from your source edits alone.'); process.exit(64); }
     const where = dirty ? 'working' : (base || head) ? `${base || 'HEAD~1'}..${head || 'HEAD'}` : 'last';
     const args = dirty ? ['run', '--working'] : ['run', '--base', base || 'HEAD~1', '--head', head || 'HEAD'];
-    const { rep, code } = gateReport(repo, [...args, ...pass]);
-    if (!rep || !rep.verdict) { out('🐴 sawbuck: could not run the check here. Make sure this is a git repo with a commit, and a test command (or run `sawbuck init`).'); process.exit(64); }
+    const { rep, code, why } = gateReport(repo, [...args, ...pass]);
+    if (!rep || !rep.verdict) { out(`🐴 sawbuck: could not run the check here: ${why || 'the engine gave no verdict'}`); process.exit(64); }
     if (json) { out(JSON.stringify(rep)); process.exit(code); }
     const m = (rep.metrics || [])[0];
     for (const md of rep.mandates || []) out(`🐴 ⛔ protected path "${md.name}" touched${md.reason ? ': ' + md.reason : ''}  (touched: ${(md.files || []).join(', ')})${md.removed ? '  [deleted in this same change; the rule stays in force for the change that removes it]' : ''}`);
     const win = (rep.metrics || []).find((x) => x.status === 'improved' && !x.tripwire);
-    if (rep.verdict === 'pass' && win) out(`🐴 ✓ verified: your ${where} change earned it. "${win.name}" improved, and the source carried the win (it survives a source-only re-run).`);
+    const noDetect = pass.includes('--no-detect-gaming');
+    if (rep.verdict === 'pass' && rep.allowed) out(`🐴 ✎ allowed with --allow: "${rep.allowed.reason}". That is a person's call, not a proof: ${(rep.allowed.cleared || []).join(', ') || 'the change'} was let through without a source-only re-proof.`);
+    else if (rep.verdict === 'pass' && win && noDetect) out(`🐴 ✓ passed: "${win.name}" improved, but gaming detection is off (--no-detect-gaming), so the win was not re-proved from the source.`);
+    else if (rep.verdict === 'pass' && win) out(`🐴 ✓ verified: your ${where} change earned it. "${win.name}" improved, and the source carried the win (it survives a source-only re-run).`);
     else if (rep.verdict === 'pass') out(`🐴 ✓ held: nothing got worse in your ${where} change, and there was no win to re-prove.`);
-    else if (rep.verdict === 'gamed') out('🐴 🚩 gamed: a win here came from editing the test, config, or grader, not the source. It does NOT survive a source-only re-run, so it does not count.');
-    else if (rep.verdict === 'fail' && (rep.mandates || []).length) out('🐴 ✗ sent back: a rule in the contract was broken, however green the rest is.');
+    else if (rep.verdict === 'gamed') {
+      out('🐴 🚩 gamed: a win here came from editing the test, config, or grader, not the source. It does NOT survive a source-only re-run, so it does not count.');
+      if (!dirty && /^(Sawbuck|Promptwheel)-Allow:/im.test(g('log', '--format=%B', `${base || 'HEAD~1'}..${head || 'HEAD'}`))) out('🐴 note: a Sawbuck-Allow trailer does not clear this, because an agent can write a commit message. A person passes --allow "<reason>".');
+    }
+    else if (rep.verdict === 'fail' && (rep.mandates || []).length) {
+      out('🐴 ✗ sent back: a protected path changed, however green the rest is.');
+      // the way through, for a person who meant it: two of the default rules take a reason, the rest are lifted first
+      const names = (l) => l.map((x) => `"${x.name}"`).join(', ');
+      const soft = rep.mandates.filter((x) => x.allowable), hard = rep.mandates.filter((x) => !x.allowable);
+      if (soft.length) out(`🐴 if a person meant this: sawbuck check --allow "<reason>" accepts ${names(soft)}, and the result shows the reason.`);
+      if (hard.length) out(`🐴 ${names(hard)} ${hard.length > 1 ? 'take' : 'takes'} no --allow. To change that path on purpose, remove that rule from promptwheel.config.json in a commit of its own (that edit takes --allow), then make the change.`);
+    }
     else if (rep.verdict === 'fail') out('🐴 ✗ sent back: this change made something worse.');
-    else out('🐴 ≈ inconclusive: the check ran but could not measure your metric (it did not run in isolation). Point it at your real test command: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json.');
+    else out(`🐴 ≈ inconclusive: ${inconclusiveWhy(rep, repo)}`);
     if ((rep.metrics || []).some((x) => x.heldByTestEdit)) out('🐴 ⚠ your tests changed too, and the old tests fail on this source. Fine for an intended change. Otherwise check the tests were not weakened: a green that stays green is not proved.');
     for (const x of rep.explained || []) out(`🐴 ${x.noted ? 'note' : 'needs a look'}: ${x.what}${x.items ? ': ' + x.items.join(', ') : ''}${!x.noted && x.allowable ? '. If you meant this: --allow "<reason>", or on a pull request comment sawbuck-allow: <reason>' : ''}`);
     if (rep.gate && rep.gate.changed) out(`🐴 ⚠ the gate definition changed in this change (fingerprint ${rep.gate.fingerprint.base} -> ${rep.gate.fingerprint.head}): a metric, guard, evaluatorPath or mandate was added, removed or edited.`);
@@ -233,7 +306,9 @@ switch (cmd) {
         {   // a baseline even with no rules yet: a turn that signs a contract is judged by the contract it began with
           const prev = st.turnBaseline && typeof st.turnBaseline === 'object' ? st.turnBaseline : null;
           const stoppedSince = st.lastStopAt && st.lastPromptAt && Date.parse(st.lastStopAt) >= Date.parse(st.lastPromptAt);
-          const unfinished = !!prev && !!st.lastPromptAt && !stoppedSince;
+          // a baseline attach wrote is not a prompt: it covers the turn that ran attach, if there was one. Set up from
+          // a terminal, nothing is in flight, and the commits made before this prompt are the person's.
+          const unfinished = !!prev && !!st.lastPromptAt && !stoppedSince && prev.by !== 'attach';
           if (!unfinished) {
             const flagged = (st.lastViolation && st.lastViolation.files && typeof st.lastViolation.files === 'object') ? st.lastViolation.files : {};
             const before = (st.lastViolation && st.lastViolation.before && typeof st.lastViolation.before === 'object') ? st.lastViolation.before : {};
@@ -272,32 +347,41 @@ switch (cmd) {
     break;
   }
   case 'attach': {
-    const user = flags.has('--user');
+    const user = flags.has('--user'), shared = flags.has('--shared'), git = flags.has('--git');
+    if (user + shared + git > 1) usage('attach takes one of --user, --shared or --git');
     const top = gitTop(repoArg());
     if (!top && !user) usage(`${repoArg()} is not a git repository (attach wires one; run it inside your project, or name its path)`);
     const repo = top || repoArg();
-    wireClaude(repo, { user });
+    if (git) wireGit(repo); else wireClaude(repo, { user, shared });
     if (!dry) verifyAttach(repo);
     break;
   }
   case 'detach': {
     const purge = flags.has('--purge');
-    const repo = repoRoot();
-    if (flags.has('--user')) unwireClaude(repo, { user: true });
-    else if (flags.has('--claude')) unwireClaude(repo, {});
+    if (flags.has('--all')) detachAll(purge);
     else {
-      // no flag: reverse whatever this repo's receipt says is attached, older git hooks included,
-      // so a bare `detach` is always the inverse of the `attach` you ran.
-      const a = readManifest(manifestPath(repo)).attachments || {};
-      const hasClaude = !!(a.claude || a['claude-shared']);
-      if (hasClaude) unwireClaude(repo, {});
-      if (a.git || !hasClaude) unwireGit(repo);
+      const repo = repoRoot();
+      if (flags.has('--user')) unwireClaude(repo, { user: true });
+      else if (flags.has('--claude')) unwireClaude(repo, {});
+      else {
+        // no flag: take out whatever is wired in this repo, older git hooks included. The receipt says what attach
+        // wrote; our hooks in the project settings or the post-commit hook count without one, so a lost receipt or a
+        // teammate's clone of a --shared repo is not left wired.
+        const a = readManifest(manifestPath(repo)).attachments || {};
+        const hasClaude = !!(a.claude || a['claude-shared']) || [false, true].some((shared) => hooksIn(claudeFile(repo, { shared }).f));
+        if (hasClaude) unwireClaude(repo, {});
+        if (a.git || hasBlock(repo) || !hasClaude) unwireGit(repo);
+      }
+      if (purge) purgeRecord(repo);
+      syncExclude(repo, readManifest(manifestPath(repo)));   // after a purge the exclude lines go too
+      const left = recordLeft(repo);
+      if (left.length) say(`sawbuck: still on disk: ${left.join(', ')}. It is the record, kept out of git status; \`sawbuck detach --purge\` removes it.`);
+      if (flags.has('--verify') && !dry) verifyClean(repo);
     }
-    if (purge) purgeRecord(repo);
-    if (flags.has('--verify')) verifyClean(repo);
+    if (dry) out(dryText([...planned.lines.values()], 'remove'));
     break;
   }
-  case 'doctor': { doctorRepo(repoRoot()); break; }
+  case 'doctor': { if (flags.has('--all')) doctorAll(); else doctorRepo(repoRoot()); break; }
   case 'rules': { out(rulesCli(rest)); break; }
   case 'shape': { out(shapeCli(rest)); break; }
   case 'steers': { out(steersReport({ json: flags.has('--json') })); break; }
@@ -388,51 +472,139 @@ function verifyAttach(repo) {
   const { rep } = gateReport(repo, ['run', '--base', base, '--head', 'HEAD']);
   const m = rep && (rep.metrics || [])[0];
   if (metricLive(m)) out(`   ✓ I can measure "${m.name}" here. On each commit I'll verify a win survived a source-only re-run, and flag it if it did not.`);
-  else out('   ⚠ I could not measure anything here yet (your test command did not run in isolation). Point me at it: `sawbuck init`, or set setup/linkDirs in promptwheel.config.json. I stay quiet until then.');
+  else out(`   ⚠ I could not measure anything here yet: ${rep ? inconclusiveWhy(rep, repo) : 'the check did not run'}`);
 }
 
 // --- the attach receipt (out of the worktree, inside .git) ------------------
 function manifestPath(repo) { return join(gitDir(repo), 'sawbuck', 'attach.json'); }
 function userManifestPath() { return join(homedir(), '.sawbuck', 'user-attach.json'); }
-function readManifest(p) { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return { version: 1, attachments: {} }; } }
+function readManifest(p) { if (planned.receipts.has(p)) return planned.receipts.get(p); try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return { version: 1, attachments: {} }; } }
 function writeManifest(p, m) {
-  if (!Object.keys(m.attachments || {}).length) { delFile(p); rmIfEmptyDir(dirname(p)); return; }
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, JSON.stringify(m, null, 2) + '\n');
+  if (dry) planned.receipts.set(p, m);
+  if (!Object.keys(m.attachments || {}).length) { dropFile(p, 'the attach receipt'); rmIfEmptyDir(dirname(p)); return; }
+  putFile(p, JSON.stringify(m, null, 2) + '\n', 'the attach receipt');
 }
 
-function delFile(p) { try { if (existsSync(p)) unlinkSync(p); } catch {} }
-function rmIfEmptyDir(d) { try { if (existsSync(d) && readdirSync(d).length === 0) rmdirSync(d); } catch {} }
-
+// Every write and removal on the detach path goes through these two: under --dry-run each is listed instead of done.
+function putFile(f, text, what) {
+  if (dry) { planned.lines.set(f, `modify  ${f}  (${what})`); return; }
+  mkdirSync(dirname(f), { recursive: true });
+  writeFileSync(f, text);
+}
+function dropFile(p, what) {
+  if (!there(p)) return;
+  if (dry) { planned.lines.set(p, `delete  ${p}  (${what})`); planned.gone.add(p); return; }
+  try { rmSync(p, { recursive: true, force: true }); } catch {}
+}
+function rmIfEmptyDir(d) { if (dry) return; try { if (existsSync(d) && readdirSync(d).length === 0) rmdirSync(d); } catch {} }
 // --- .git/info/exclude: keep the worktree clean without touching .gitignore --
 // Any attachment keeps the block, the last one out takes it. Returns whether the file changed.
 function excludeFile(repo) { return gitPath(repo, 'info/exclude'); }
-function syncExclude(repo, manifest) { return Object.keys(manifest.attachments || {}).length ? ensureExcluded(repo) : clearExcluded(repo); }
+// The lines stay while the record they hide is still on disk: clearing them would put .sawbuck/ in git status and a
+// signed repo would fail its own hooks-frozen rule over Sawbuck's record. --purge deletes the record, then the lines.
+function syncExclude(repo, manifest) {
+  const changed = Object.keys(manifest.attachments || {}).length ? ensureExcluded(repo, dry) : hiddenLeft(repo).length ? false : clearExcluded(repo, dry);
+  if (dry && changed) planned.lines.set(excludeFile(repo), `modify  ${excludeFile(repo)}  (the lines that keep the record out of git status)`);
+  return changed;
+}
+// the record paths still on disk and not tracked (a committed LOGBOOK.md is the person's file)
+function recordLeft(repo) {
+  const tracked = (p) => { try { return !!execFileSync('git', ['-C', repo, 'ls-files', '--', p], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return false; } };
+  return ['.sawbuck/', '.promptwheel/outcomes.jsonl', 'events.jsonl', 'annotations.jsonl', 'LOGBOOK.md', 'JOURNEY.md'].filter((p) => there(join(repo, p)) && !tracked(p));
+}
+// what the block hides that is still there: the record, and a settings.local.json the person keeps
+function hiddenLeft(repo) {
+  const local = join(repo, '.claude', 'settings.local.json');
+  let own = false; try { own = there(local) && !execFileSync('git', ['-C', repo, 'ls-files', '--', '.claude/settings.local.json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+  return [...recordLeft(repo), ...(own ? ['.claude/settings.local.json'] : [])];
+}
 
-// --- git post-commit --------------------------------------------------------
-// Older versions could attach here. Nothing wires it now; detach still takes it out.
+// --- git post-commit (attach --git) -----------------------------------------
+// For any agent or none: every commit is checked, whatever made it. The hook prefers a `sawbuck` on PATH (so it
+// survives a reinstall), then the absolute path of the sawbuck that attached, then the same version through npx.
+function hookBlock(repo) {
+  const r = JSON.stringify(repo);
+  // git exports GIT_DIR / GIT_INDEX_FILE / GIT_WORK_TREE into its hooks. The check shells out to git and would
+  // inherit them, operate on the wrong repo, and silently catch nothing. Clear them first, in a subshell: the block
+  // sits above the person's own hook lines, and those keep what git gave them.
+  return `${S_START}\n(unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX GIT_OBJECT_DIRECTORY GIT_COMMON_DIR\nif command -v sawbuck >/dev/null 2>&1; then sawbuck __hook --repo ${r}; elif [ -f ${JSON.stringify(SELF)} ]; then ${nodeCmd()} ${JSON.stringify(SELF)} __hook --repo ${r}; else npx -y sawbuck@${version} __hook --repo ${r}; fi) || true\n${S_END}\n`;
+}
+// The first commit after attach is checked only if there is a commit to check it from: HEAD as it stands now.
+// A baseline other hooks are keeping (Claude hooks wired here or at user level, a turn in flight) is left alone;
+// one left behind by an attachment that is gone is not, or commits made while nothing watched would be laid on the next one.
+function gitBaseline(repo) {
+  let sha = ''; try { sha = execFileSync('git', ['-C', repo, 'rev-parse', '--verify', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+  const path = join(repo, '.sawbuck', 'state.json');
+  let st = {}; try { st = JSON.parse(readFileSync(path, 'utf8')); } catch {}
+  const kept = (st.lastSha || (st.turnBaseline && st.turnBaseline.sha)) && (Object.keys(readManifest(manifestPath(repo)).attachments || {}).length || hooksIn(claudeFile(repo, { user: true }).f));
+  return { path, st, sha: kept ? '' : sha };
+}
+function wireGit(repo) {
+  const pc = gitPath(repo, 'hooks/post-commit');
+  // core.hooksPath inside the work tree (the husky way): the team tracks those files or a hook tool rewrites them, and
+  // our block pins this machine's paths. Refuse, and give the portable line a person can add.
+  if (!relative(repo, pc).startsWith('..') && relative(gitDir(repo), pc).startsWith('..')) usage(`git hooks here live in ${relative(repo, dirname(pc))}/, inside the work tree (core.hooksPath), where the team or a hook tool owns the files, so attach --git writes nothing. Use plain \`sawbuck attach\`, or add this line by hand to the post-commit hook kept there (with husky: .husky/post-commit): (unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX GIT_OBJECT_DIRECTORY GIT_COMMON_DIR; npx -y sawbuck@${version} __hook --repo "$PWD") || true`);
+  const existed = existsSync(pc);
+  const was = existed ? readFileSync(pc, 'utf8') : '';
+  if (was.includes(S_START)) { out(`sawbuck: already attached (git) in ${repo}`); return; }
+  // our block is shell, and git only runs an executable hook: a hook in another language, or one git is not running,
+  // is left exactly as it is
+  if (existed && was.startsWith('#!') && !/^#!\s*\S*\/(env\s+)?(ba|da|z|k)?sh\b/.test(was.split('\n')[0])) usage(`the post-commit hook here is not a shell script (${was.split('\n')[0]}). Add this line to it by hand: npx -y sawbuck@${version} __hook`);
+  if (existed && process.platform !== 'win32') { let x = false; try { x = !!(statSync(pc).mode & 0o111); } catch {} if (!x) usage(`the post-commit hook here is not executable, so git does not run it. Make it executable (chmod +x ${relative(repo, pc)}) or remove it, then run attach --git again.`); }
+  // Our block goes right after the shebang line, so a hook that ends in `exit 0` still reaches it. The receipt notes
+  // the shebang or the newline we had to add, so detach leaves a hook that was here before byte for byte as it was.
+  const shebang = !was.startsWith('#!'), nl = !shebang && !was.includes('\n');
+  const body = (shebang ? '#!/bin/sh\n' : '') + was + (nl ? '\n' : '');
+  const at = body.indexOf('\n') + 1;
+  const mp = manifestPath(repo), base = gitBaseline(repo);
+  if (dry) {
+    out(dryText([
+      `${existed ? 'modify' : 'create'}  ${pc}  (post-commit hook block)`,
+      ensureExcluded(repo, true) ? `exclude ${excludeFile(repo)}  (${EXCLUDED.join(', ')})` : null,
+      `${existsSync(mp) ? 'modify' : 'create'}  ${mp}  (attach receipt)`,
+      base.sha ? `write   ${base.path}  (the commit to check from, so the first commit after this is checked)` : null,
+      `write   ${regPath()}  (the list of attached repos, for detach --all)`,
+    ].filter(Boolean)));
+    return;
+  }
+  writeFileSync(pc, body.slice(0, at) + hookBlock(repo) + body.slice(at));
+  chmodSync(pc, 0o755);
+  const m = readManifest(mp);
+  m.attachments = { ...m.attachments, git: { pc: { created: !existed, ...(existed && shebang ? { shebang } : {}), ...(nl ? { nl } : {}) } } };
+  syncExclude(repo, m);
+  writeManifest(mp, m);
+  if (base.sha) { try { mkdirSync(dirname(base.path), { recursive: true }); writeFileSync(base.path, JSON.stringify({ turns: 0, shownTotal: 0, ...base.st, lastSha: base.sha }, null, 2) + '\n'); } catch {} }
+  regAdd(repo, 'git');
+  out(`sawbuck: attached (git post-commit) in ${repo}. Every commit is checked, whatever made it.`);
+}
+function hasBlock(repo) { try { return readFileSync(gitPath(repo, 'hooks/post-commit'), 'utf8').includes(S_START); } catch { return false; } }
 function unwireGit(repo) {
   const pc = gitPath(repo, 'hooks/post-commit');
   const m = readManifest(manifestPath(repo));
-  const hasReceipt = !!m.attachments?.git;
+  const rec = m.attachments?.git;
+  const wired = hasBlock(repo);
   // signing with no attach still hides the record, so a repo with no receipt can have a block to take back
-  if (!existsSync(pc) && !hasReceipt) { out(syncExclude(repo, m) ? `sawbuck: removed the record lines from ${excludeFile(repo)}` : 'sawbuck: nothing to detach'); return; }
-  if (existsSync(pc)) {
-    const stripped = readFileSync(pc, 'utf8').replace(BLOCK_RE, '\n').replace(/\n{3,}/g, '\n\n');
-    const created = m.attachments?.git?.pc?.created;
+  if (!wired && !rec) { say(syncExclude(repo, m) ? `sawbuck: removed the record lines from ${excludeFile(repo)}` : 'sawbuck: nothing to detach'); return; }
+  if (wired) {
+    // take out what attach put in, and nothing else: a hook that was here before is the same bytes again
+    let rest = readFileSync(pc, 'utf8').replace(BLOCK_RE, '');
+    if (rec?.pc?.shebang && rest.startsWith('#!/bin/sh\n')) rest = rest.slice('#!/bin/sh\n'.length);
+    if (rec?.pc?.nl && rest.endsWith('\n')) rest = rest.slice(0, -1);
     // true inverse: if we created this hook and it is trivial again, remove it
-    if ((created || !hasReceipt) && isTrivialHook(stripped)) delFile(pc);
-    else writeFileSync(pc, stripped);
+    if ((rec?.pc?.created || !rec) && isTrivialHook(rest)) dropFile(pc, 'the post-commit hook attach created');
+    else putFile(pc, rest, 'our block in the post-commit hook');
   }
-  if (hasReceipt) { delete m.attachments.git; syncExclude(repo, m); writeManifest(manifestPath(repo), m); }
-  out(`sawbuck: detached (git) from ${repo}`);
+  if (rec) { delete m.attachments.git; syncExclude(repo, m); writeManifest(manifestPath(repo), m); }
+  regRemove(repo, 'git');
+  say(`sawbuck: detached (git) from ${repo}`);
 }
 function isTrivialHook(text) { return text.replace(/^#!.*\n?/, '').trim() === ''; }
 
 // --- Claude Code hooks ------------------------------------------------------
 // user-level hooks (~/.claude) target the repo by cwd; project hooks pin the repo.
-// Project default writes the gitignored settings.local.json; --shared writes the
-// tracked settings.json on purpose. Safe merge; refuses malformed JSON; idempotent.
+// Project default writes the gitignored settings.local.json. --shared writes the tracked settings.json for a team:
+// its hooks run the pinned version through npx and find the repo from where they run, so the file holds no path from
+// this machine, and removing the hooks shows in git. Safe merge; refuses malformed JSON; idempotent.
 function claudeFile(repo, { user, shared }) {
   const dir = join(user ? homedir() : repo, '.claude');
   const name = user || shared ? 'settings.json' : 'settings.local.json';
@@ -446,12 +618,12 @@ export function nodeCmd(execPath = process.execPath, platform = process.platform
   return `"$(command -v node || echo ${JSON.stringify(execPath).replace(/^"|"$/g, "'")})"`;
 }
 function wireClaude(repo, opts) {
-  const { user } = opts;
+  const { user, shared } = opts;
   // user-level hooks already cover every repo; a second set would run each check twice and spend the
   // send-back budget twice as fast. --shared is a deliberate team file, so it is written anyway.
-  if (!user) {
+  if (!user && !shared) {
     const uf = claudeFile(repo, { user: true }).f;
-    try { if (readFileSync(uf, 'utf8').includes('sawbuck.mjs')) { out(`sawbuck: already watching here through your user-level hooks (${uf}); nothing to add`); return; } } catch {}
+    try { if (OURS.test(readFileSync(uf, 'utf8'))) { out(`sawbuck: already watching here through your user-level hooks (${uf}); nothing to add${existsSync(join(repo, 'promptwheel.config.json')) ? '' : '. The check runs here once this repo has its rules: sawbuck contract'}`); return; } } catch {}
   }
   const { dir, f } = claudeFile(repo, opts);
   const dirExisted = existsSync(dir);
@@ -461,30 +633,41 @@ function wireClaude(repo, opts) {
   // run through npx, the installed path lives in a cache that can be cleared, and a missing hook fails quietly and
   // leaves the wall off: fall back to fetching the same version
   const run = (args) => {
+    if (shared) return `npx -y sawbuck@${version} ${args}`;
     const direct = `${nodeCmd()} ${JSON.stringify(SELF)} ${args}`;
     return process.platform !== 'win32' && SELF.includes('/_npx/') ? `if [ -f ${JSON.stringify(SELF)} ]; then ${direct}; else npx -y sawbuck@${version} ${args}; fi` : direct;
   };
-  const ctx = run(user ? 'turn --hook' : `turn --hook ${JSON.stringify(repo)}`);
-  const chk = run(user ? '__hook --by claude --stop' : `__hook --repo ${JSON.stringify(repo)} --by claude --stop`);
+  const here = user || shared;   // no repo path in the command: the hook works out the repo from where it runs
+  const ctx = run(here ? 'turn --hook' : `turn --hook ${JSON.stringify(repo)}`);
+  const chk = run(here ? '__hook --by claude --stop' : `__hook --repo ${JSON.stringify(repo)} --by claude --stop`);
   // attached already? "already attached" only when every hook of THIS version is present; an older
   // attachment (say, without the SessionStart[compact] hook) is upgraded in place, never left stale.
   let upgrading = false;
-  if (JSON.stringify(cfg).includes('sawbuck.mjs')) {
+  if (OURS.test(JSON.stringify(cfg))) {
     const has = (event, command, matcher) => ((cfg.hooks || {})[event] || []).some((h) => h && (matcher ? h.matcher === matcher : !h.matcher) && Array.isArray(h.hooks) && h.hooks.some((x) => x && x.command === command));
-    if (has('UserPromptSubmit', ctx) && has('SessionStart', ctx, 'compact') && has('Stop', chk)) { out(`sawbuck: already attached (${user ? 'user' : 'claude'}) in ${f}`); return; }
+    if (has('UserPromptSubmit', ctx) && has('SessionStart', ctx, 'compact') && has('Stop', chk)) { out(`sawbuck: already attached (${user ? 'user' : shared ? 'shared' : 'claude'}) in ${f}`); return; }
     upgrading = true;
   }
+  const mode = user ? 'user' : shared ? 'claude-shared' : 'claude';
+  const mp = user ? userManifestPath() : manifestPath(repo);
+  const stPath = join(repo, '.sawbuck', 'state.json');
+  let st = {}; try { st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
+  // attach often runs inside a turn (saying yes to the offer), and that turn's Stop hook then has no baseline, so the
+  // files signing just wrote would read as the agent's violations. What is here now is the baseline; anything after it counts.
+  const baseline = !user && existsSync(join(repo, 'promptwheel.config.json')) && !st.turnBaseline;
   if (dry) {
     out(dryText([
       `${upgrading ? 'update' : fileExisted ? 'modify' : 'create'}  ${f}  (UserPromptSubmit + SessionStart[compact] + Stop hooks: the per-turn block, and the check)`,
-      user ? null : `exclude ${excludeFile(repo)}  (${EXCLUDED.join(', ')})`,
-      `create  ${user ? userManifestPath() : manifestPath(repo)}  (attach receipt)`,
+      !user && ensureExcluded(repo, true) ? `exclude ${excludeFile(repo)}  (${EXCLUDED.join(', ')})` : null,
+      `${existsSync(mp) ? 'modify' : 'create'}  ${mp}  (attach receipt)`,
+      baseline ? `write   ${stPath}  (the turn baseline, so this turn's own signing is not read as the agent's)` : null,
+      `write   ${regPath()}  (the list of attached repos, for detach --all)`,
     ].filter(Boolean)));
     return;
   }
   cfg.hooks = cfg.hooks || {};
   const put = (event, command, matcher) => {
-    cfg.hooks[event] = (cfg.hooks[event] || []).filter((h) => !JSON.stringify(h).includes('sawbuck.mjs'));
+    cfg.hooks[event] = (cfg.hooks[event] || []).filter((h) => !OURS.test(JSON.stringify(h)));
     cfg.hooks[event].push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command }] });
   };
   put('UserPromptSubmit', ctx);
@@ -494,30 +677,25 @@ function wireClaude(repo, opts) {
   put('Stop', chk);
   mkdirSync(dir, { recursive: true });
   writeFileSync(f, JSON.stringify(cfg, null, 2) + '\n');
-  // attach often runs inside a turn (saying yes to the offer), and that turn's Stop hook then has no baseline, so the
-  // files signing just wrote would read as the agent's violations. What is here now is the baseline; anything after it counts.
-  if (!user && existsSync(join(repo, 'promptwheel.config.json'))) {
+  if (baseline) {
     try {
       ensureExcluded(repo);
-      const stPath = join(repo, '.sawbuck', 'state.json');
-      let st = {}; try { st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
-      if (!st.turnBaseline) {
-        let sha = ''; try { sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
-        st.turnBaseline = { sha, files: protectedDirty(repo, { store: true }) };
-        st.lastPromptAt = new Date().toISOString();
-        mkdirSync(dirname(stPath), { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
-      }
+      let sha = ''; try { sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
+      st.turnBaseline = { sha, files: protectedDirty(repo, { store: true }), by: 'attach' };
+      st.lastPromptAt = new Date().toISOString();
+      mkdirSync(dirname(stPath), { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
     } catch {}
   }
-  const mode = user ? 'user' : 'claude';
-  const mp = user ? userManifestPath() : manifestPath(repo);
   const m = readManifest(mp);
   const prev = (m.attachments || {})[mode];   // an upgrade keeps the receipt of what the first attach created
   m.attachments = { ...m.attachments, [mode]: { file: f, fileCreated: prev ? !!prev.fileCreated : !fileExisted, dirCreated: prev ? !!prev.dirCreated : !dirExisted } };
   if (!user) syncExclude(repo, m);
   writeManifest(mp, m);
-  out(upgrading ? `sawbuck: updated the ${user ? 'USER-LEVEL' : 'project'} Claude Code hooks in ${f} to this version`
-                : `sawbuck: wired ${user ? 'USER-LEVEL' : 'project'} Claude Code hooks in ${f}`);
+  regAdd(repo, mode);
+  const kind = user ? 'USER-LEVEL' : shared ? 'shared project' : 'project';
+  out(upgrading ? `sawbuck: updated the ${kind} Claude Code hooks in ${f} to this version` : `sawbuck: wired ${kind} Claude Code hooks in ${f}`);
+  if (shared) out(`  commit ${relative(repo, f)} so the team gets the check. It runs sawbuck ${version} through npx on every machine.`);
+  if (shared && protectedAmong(repo, [relative(repo, f)]).length) out(`  That file is a protected path in this repo, so the check on its commit reads "sent back" unless a person passes --allow "team hooks" (on a pull request: a comment, sawbuck-allow: team hooks).`);
   if (!user && !existsSync(join(repo, 'AGENTS.md')) && !existsSync(join(repo, 'CLAUDE.md'))) out('  no written rule here yet, and that is what changes the agent: run sawbuck contract.');
   if (user) out('  profile-switches by cwd: memory in any git repo, the check where a promptwheel.config.json exists.');
 }
@@ -531,13 +709,13 @@ function unwireClaude(repo, { user }) {
     const f = rec?.file || claudeFile(repo, { user, shared: mode === 'claude-shared' }).f;
     if (existsSync(f)) {
       let raw = ''; try { raw = readFileSync(f, 'utf8'); } catch {}
-      if (raw.includes('sawbuck.mjs')) {
+      if (OURS.test(raw)) {
         let cfg = null; try { cfg = JSON.parse(raw); } catch {}
         if (cfg) {
           removeClaudeEntries(cfg);
-          if ((rec?.fileCreated || !rec) && isTrivialSettings(cfg)) { delFile(f); if (rec?.dirCreated) rmIfEmptyDir(dirname(f)); }
-          else writeFileSync(f, JSON.stringify(cfg, null, 2) + '\n');
-          out(`sawbuck: removed Claude Code hooks from ${f}`);
+          if ((rec?.fileCreated || !rec) && isTrivialSettings(cfg)) { dropFile(f, 'our Claude Code hooks were all it held'); if (rec?.dirCreated) rmIfEmptyDir(dirname(f)); }
+          else putFile(f, JSON.stringify(cfg, null, 2) + '\n', 'our Claude Code hooks');
+          say(`sawbuck: removed Claude Code hooks from ${f}`);
           did = true;
         }
       }
@@ -545,77 +723,120 @@ function unwireClaude(repo, { user }) {
     if (rec) { delete m.attachments[mode]; touched = true; }
   }
   if (touched) { if (!user) syncExclude(repo, m); writeManifest(mp, m); }
-  if (!did && !touched) out('sawbuck: no Claude attachment found to detach');
+  for (const mode of modes) regRemove(repo, mode);
+  if (!did && !touched) say('sawbuck: no Claude attachment found to detach');
 }
 function removeClaudeEntries(cfg) {
   if (!cfg.hooks) return;
   for (const ev of ['UserPromptSubmit', 'SessionStart', 'Stop']) {
     if (!Array.isArray(cfg.hooks[ev])) continue;
-    cfg.hooks[ev] = cfg.hooks[ev].filter((h) => !JSON.stringify(h).includes('sawbuck.mjs'));
+    cfg.hooks[ev] = cfg.hooks[ev].filter((h) => !OURS.test(JSON.stringify(h)));
     if (!cfg.hooks[ev].length) delete cfg.hooks[ev];     // no empty [] residue
   }
   if (cfg.hooks && !Object.keys(cfg.hooks).length) delete cfg.hooks;
 }
 function isTrivialSettings(cfg) { return Object.keys(cfg).length === 0; }
 
-// --- trace / verify / doctor / purge: show, prove, and clean the footprint --
+// --- verify / doctor / purge: prove and clean the footprint ----------------
 function footprint(repo) {
   const items = [];
   const pc = gitPath(repo, 'hooks/post-commit');
   try { if (existsSync(pc) && readFileSync(pc, 'utf8').includes(S_START)) items.push({ what: pc, state: 'git hook' }); } catch {}
   for (const f of [join(repo, '.claude', 'settings.local.json'), join(repo, '.claude', 'settings.json'), join(homedir(), '.claude', 'settings.json')]) {
-    try { if (existsSync(f) && readFileSync(f, 'utf8').includes('sawbuck.mjs')) items.push({ what: f, state: 'claude hooks' }); } catch {}
+    try { if (existsSync(f) && OURS.test(readFileSync(f, 'utf8'))) items.push({ what: f, state: 'claude hooks' }); } catch {}
   }
   const xf = excludeFile(repo);
-  try { if (existsSync(xf) && readFileSync(xf, 'utf8').includes(S_START)) items.push({ what: xf, state: 'local exclude' }); } catch {}
-  for (const d of RECORD_DIRS) if (existsSync(join(repo, d))) items.push({ what: join(repo, d), state: 'record dir (ignored)' });
+  // the exclude lines are part of the record while it is on disk (syncExclude), wiring only once it is gone
+  try { if (existsSync(xf) && readFileSync(xf, 'utf8').includes(S_START) && !hiddenLeft(repo).length) items.push({ what: xf, state: 'local exclude' }); } catch {}
   const mp = manifestPath(repo);
   if (existsSync(mp)) { const m = readManifest(mp); items.push({ what: mp, state: `receipt: ${Object.keys(m.attachments || {}).join(', ') || 'empty'}` }); }
   return items;
 }
 function verifyClean(repo) {
-  // the record dirs may stay (your data, unless --purge); the mechanism must be gone.
-  const left = footprint(repo).filter((it) => !/record dir/.test(it.state));
-  if (!left.length) out('sawbuck: verified, the repo is back to how it was (mechanism fully removed).');
+  // the record may stay (your data, unless --purge, and named above); the mechanism must be gone.
+  const left = footprint(repo);
+  if (!left.length) out('sawbuck: verified, the hooks and the receipt are gone.');
   else { out('sawbuck: NOT clean, these remain:'); for (const it of left) out(`  ${it.state.padEnd(22)} ${it.what}`); process.exitCode = 1; }
 }
 function purgeRecord(repo) {
   let n = 0;
+  const purge = (p) => { if (!there(p)) return; dropFile(p, 'the record'); n++; say(`sawbuck: purged ${p}`); };
   for (const d of RECORD_DIRS) {
-    const p = join(repo, d);
     // a committed LOGBOOK.md or JOURNEY.md is the person's file, not our record
     try { if (execFileSync('git', ['-C', repo, 'ls-files', '--', d], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()) continue; } catch {}
-    try { if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); n++; out(`sawbuck: purged ${p}`); } } catch {}
+    purge(join(repo, d));
   }
-  const outcomes = join(repo, '.promptwheel', 'outcomes.jsonl');   // the rest of .promptwheel/ is the signed contract: yours to keep or delete
-  try { if (existsSync(outcomes)) { rmSync(outcomes, { force: true }); n++; out(`sawbuck: purged ${outcomes}`); } } catch {}
-  if (!n) out('sawbuck: no record to purge');
-}
-// is `sawbuck` resolvable on PATH? (SAWBUCK_NO_PATH_CHECK forces the strict/offline answer)
-function onPath() {
-  if (process.env.SAWBUCK_NO_PATH_CHECK) return false;
-  try { execFileSync('sh', ['-c', 'command -v sawbuck'], { stdio: 'ignore' }); return true; } catch { return false; }
+  purge(join(repo, '.promptwheel', 'outcomes.jsonl'));   // the rest of .promptwheel/ is the signed contract: yours to keep or delete
+  if (!n) say('sawbuck: no record to purge');
 }
 // the path a hook bakes in: the quoted one ending in sawbuck.mjs, in a shell hook or in JSON, where the quotes are escaped
 function extractBaked(text) { const m = text.match(/"([^"]*sawbuck\.mjs)\\?"/); return m ? m[1] : null; }
+// Does the hook still work? Run exactly what it runs, with --version in place of the hook's arguments: the same
+// node lookup, the same baked path, the same npx fallback. A hook never looks sawbuck up on PATH, so neither does this.
+function hookRuns(command) {
+  const probe = command.replace(/(sawbuck\.mjs"?|sawbuck@[\w.-]+) [^;]*/g, '$1 --version');
+  if (process.platform === 'win32') { const b = extractBaked(JSON.stringify(command)); return !!b && existsSync(b); }
+  try { return /^\d+\.\d+\.\d+/.test(execFileSync('sh', ['-c', probe], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 60000 }).trim()); } catch { return false; }
+}
 function doctorRepo(repo) {
   const checks = [];
+  // the git hook tries a sawbuck on PATH first, then the baked path, then npx
   const pc = gitPath(repo, 'hooks/post-commit');
-  try { if (existsSync(pc)) { const b = readFileSync(pc, 'utf8'); if (b.includes(S_START)) checks.push({ mode: 'git', file: pc, baked: extractBaked(b) }); } } catch {}
-  for (const [mode, f] of [['claude', join(repo, '.claude', 'settings.local.json')], ['claude-shared', join(repo, '.claude', 'settings.json')]]) {
-    try { if (existsSync(f)) { const b = readFileSync(f, 'utf8'); if (b.includes('sawbuck.mjs')) checks.push({ mode, file: f, baked: extractBaked(b) }); } } catch {}
+  try { if (existsSync(pc)) { const b = readFileSync(pc, 'utf8'); if (b.includes(S_START)) { const baked = extractBaked(b); let onPath = false; try { onPath = !!execFileSync('sh', ['-c', 'command -v sawbuck'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {} checks.push({ mode: 'git', file: pc, ok: onPath || (!!baked && existsSync(baked)) || /npx -y sawbuck@/.test(b) }); } } } catch {}
+  for (const [mode, f] of [['claude', join(repo, '.claude', 'settings.local.json')], ['claude-shared', join(repo, '.claude', 'settings.json')], ['user', join(homedir(), '.claude', 'settings.json')]]) {
+    let cfg = null; try { cfg = JSON.parse(readFileSync(f, 'utf8')); } catch { continue; }
+    const ours = (list) => (Array.isArray(list) ? list : []).flatMap((h) => (h && Array.isArray(h.hooks) ? h.hooks : [])).map((x) => x && x.command).filter((c) => typeof c === 'string' && OURS.test(c));
+    const cmds = ours(Object.values((cfg && cfg.hooks) || {}).flat());
+    if (!cmds.length) continue;
+    // the set attach writes, each under its own event: the rule on a prompt and after a compaction, the check on Stop
+    const at = (event, re, matcher) => ours(((cfg.hooks || {})[event] || []).filter((h) => !matcher || (h && h.matcher === matcher))).some((c) => re.test(c));
+    const missing = [at('UserPromptSubmit', /\bturn --hook\b/) ? '' : 'UserPromptSubmit', at('SessionStart', /\bturn --hook\b/, 'compact') ? '' : 'SessionStart[compact]', at('Stop', /__hook\b.*--stop\b/) ? '' : 'Stop with --stop'].filter(Boolean);
+    checks.push({ mode, file: f, ok: !missing.length && [...new Set(cmds)].every(hookRuns), missing });
   }
-  if (!checks.length) { out(`sawbuck: no attachment in ${repo}, nothing to check.`); return; }
-  const pathOk = onPath();
-  let bad = 0;
+  // the receipt says hooks were wired here, and they are gone: a removal git status cannot show (the file is excluded, or under .git)
+  const receipt = Object.keys(readManifest(manifestPath(repo)).attachments || {}).filter((m) => !checks.some((c) => c.mode === m));
+  if (!checks.length && !receipt.length) { out(`sawbuck: no attachment in ${repo}, nothing to check.`); return; }
+  let bad = receipt.length;
+  const again = (m) => `sawbuck attach${{ git: ' --git', 'claude-shared': ' --shared', user: ' --user' }[m] || ''} again`;
   out(`sawbuck doctor, ${repo}:`);
   for (const c of checks) {
-    const ok = pathOk || (c.baked ? existsSync(c.baked) : false);
-    if (!ok) bad++;
-    out(`  ${ok ? 'OK   ' : 'STALE'} ${c.mode.padEnd(14)} ${c.file}${ok ? '' : `  (baked path gone: ${c.baked || '?'} and sawbuck not on PATH, re-attach or install it)`}`);
+    if (!c.ok) bad++;
+    const why = c.ok ? '' : c.missing && c.missing.length ? `  (the hook set is incomplete, missing: ${c.missing.join(', ')}; run ${again(c.mode)})` : `  (the hook does not run: what it calls is gone; run ${again(c.mode)})`;
+    out(`  ${c.ok ? 'OK   ' : c.missing && c.missing.length ? 'PART ' : 'STALE'} ${c.mode.padEnd(14)} ${c.file}${why}`);
   }
-  out(pathOk ? '\n  sawbuck resolves on PATH, attachments survive a reinstall.' : '\n  tip: `npm i -g sawbuck` so hooks resolve by PATH and survive an upgrade.');
+  for (const m of receipt) out(`  GONE  ${m.padEnd(14)} the receipt says ${m === 'git' ? 'a post-commit hook was wired here, but our block is gone' : 'hooks were wired here, but the hooks are gone'}. Run ${again(m)}, or sawbuck detach to drop the receipt.`);
   if (bad) process.exitCode = 1;
 }
+function doctorAll() {
+  const r = regRead();
+  if (!r.repos.length) { out('sawbuck: not attached anywhere.'); return; }
+  out('sawbuck is attached to:');
+  for (const x of r.repos) out(`  ${x.mode.padEnd(14)} ${x.repo}`);
+  for (const repo of new Set(r.repos.map((x) => x.repo))) doctorRepo(repo);
+}
+
+// --- every attachment, in one list, so there is one way out of all of them ---
+function regPath() { return join(homedir(), '.sawbuck', 'registry.json'); }
+function regRead() { if (planned.registry) return { ...planned.registry }; try { const r = JSON.parse(readFileSync(regPath(), 'utf8')); r.repos = (r.repos || []).filter((x) => existsSync(x.repo)); return r; } catch { return { repos: [] }; } }   // a repo that is gone is not attached
+function regWrite(r) {
+  const f = regPath();
+  if (dry) planned.registry = r;
+  if (!r.repos.length) { dropFile(f, 'the list of attached repos'); rmIfEmptyDir(dirname(f)); return; }
+  putFile(f, JSON.stringify(r, null, 2) + '\n', 'the list of attached repos');
+}
+function regAdd(repo, mode) { const r = regRead(); r.repos = r.repos.filter((x) => !(x.repo === repo && x.mode === mode)); r.repos.push({ repo, mode, at: new Date().toISOString() }); regWrite(r); }
+function regRemove(repo, mode) { const r = regRead(); const keep = r.repos.filter((x) => !(x.mode === mode && (mode === 'user' || x.repo === repo))); if (keep.length !== r.repos.length) regWrite({ ...r, repos: keep }); }
+function detachAll(purge) {
+  const r = regRead();
+  if (!r.repos.length) { say('sawbuck: nothing to detach: not attached anywhere.'); return; }
+  for (const x of [...r.repos]) {
+    if (x.mode === 'git') unwireGit(x.repo);
+    else if (x.mode === 'user') unwireClaude(x.repo, { user: true });
+    else unwireClaude(x.repo, {});
+    if (purge) purgeRecord(x.repo);
+    syncExclude(x.repo, readManifest(manifestPath(x.repo)));
+  }
+  say('sawbuck: detached everywhere.');
+}
 // --- shared helpers ---------------------------------------------------------
-function dryText(plan) { return ['sawbuck --dry-run: would leave this footprint (writing nothing):', ...plan.map((p) => '  ' + p), '  all of it reversible with `detach`.'].join('\n'); }
+function dryText(plan, verb = 'leave') { return verb === 'remove' ? ['sawbuck --dry-run: would remove (changing nothing):', ...(plan.length ? plan.map((p) => '  ' + p) : ['  nothing: no wiring here'])].join('\n') : ['sawbuck --dry-run: would leave this footprint (writing nothing):', ...plan.map((p) => '  ' + p), '  all of it reversible with `detach`.'].join('\n'); }