sawbuck 0.1.30 → 0.1.31

package/CONTRACT.md

@@ -25,7 +25,7 @@ The per-turn signal a loop consumes. The check (`run`) exits:
 | `0` | `pass` | The win is real: it survived a source-only re-proof and no guard regressed. | Keep the change. |
 | `1` | `fail` | A guarded metric regressed beyond the measured noise band. | Revert. |
 | `2` | `gamed` | A metric improved only by editing the goalposts (test, grader, golden, config), not the source. | Revert and flag. |
-| `3` | `inconclusive` | Nothing could be certified: a guard measured nothing, or the delta sat inside noise. | Do not trust the green; do not keep on this signal alone. |
+| `3` | `inconclusive` | Nothing could be certified: a guard never ran (inert) and no metric was measured to improve, or a win's source-only re-run could not be applied, so the win could not be re-proved either way. | Do not trust the green; do not keep on this signal alone. |
 
 The agent consumes this as a per-turn reward it cannot inflate. The harness consumes the same exit as a merge gate the agent cannot self-clear.
 
@@ -67,7 +67,7 @@ Fixed vocabularies (a conforming implementation uses exactly these):
 - `metric.status` ∈ `improved | regressed | unchanged | inconclusive | unmeasurable`
 - `direction` ∈ `up | down | pass` (the direction that counts as better; `pass` means a 0/1 gate)
 
-`retained` is the fraction of a metric's gain that survived the source-only re-run (§3). `noise` is the measured jitter band as a single number, across the top-level `repeat` runs; a delta inside it is `inconclusive`, never a regression. `confidence` (`unverified | low | medium | high`) and `sourceOnly` (the metric's value when only source edits are replayed, §3) are informational fields the reference implementation adds; a minimal conforming report may omit them. A consumer validates a report with `conformsToContract()` from the `promptwheel` package (see INTEGRATE.md) or `promptwheel conformance`.
+`retained` is the fraction of a metric's gain that survived the source-only re-run (§3). `noise` is the measured jitter band as a single number, across the top-level `repeat` runs; a delta inside it leaves that metric `inconclusive` (neither a win nor a regression; the verdict is not failed by it). `confidence` (`none | unverified | low | medium | high`, `none` for an unmeasurable metric) and `sourceOnly` (the metric's value when only source edits are replayed, §3) are informational fields the reference implementation adds; a minimal conforming report may omit them. A consumer validates a report with `conformsToContract()` from the `promptwheel` package (see INTEGRATE.md) or `promptwheel conformance`.
 
 `gate` (optional) is the gate-integrity record. `gate.fingerprint` is a truncated SHA-256 of the normalized gate definition at `base` and `head`, so a changed gate is visible in the audit record. `gate.weakened`, present only when it happened, lists guards the change dropped (removed, or set to `guard:false`) that would have failed at `head`. A non-empty `gate.weakened` forces `verdict: gamed`: an agent cannot earn a pass by disabling the guard it is being judged by.
 

package/debt.mjs

@@ -33,7 +33,11 @@ const bare = live.filter((it) => !it.documented && it.content).length;
 if (since && typeof since === 'string') {
   const norm = (s) => String(s).trim().replace(/\s+/g, ' ');
   // the delta base: the raw suppression set at REF (the adapter's ref mode), subtracted from HEAD.
-  const base = new Set((memDebt(repo, { ref: since }) || []).map((r) => r.file + '\u0000' + norm(r.content)));
+  // null = the ref could not be read (not fetched, a typo): unmeasurable is NOT an empty base, or
+  // every pre-existing suppression would read as newly added and a --fail-on gate would fail falsely.
+  const baseRows = memDebt(repo, { ref: since });
+  if (baseRows === null) { console.error(`sawbuck debt: could not read the suppression ledger at ${since} (is the ref fetched? in GitHub Actions use actions/checkout with fetch-depth: 0)`); process.exit(1); }
+  const base = new Set(baseRows.map((r) => r.file + '\u0000' + norm(r.content)));
   const added = live.filter((it) => it.content && !base.has(it.file + '\u0000' + norm(it.content)));
   const skips = added.filter((it) => it.testSkip).length, undoc = added.filter((it) => !it.documented).length;
   // the gate: fail (exit 1) when the branch adds the kind of debt --fail-on names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "Sign your agent to a contract: a deterministic, zero-LLM check re-proves every win from the agent's source edits alone, so a green that came from editing the test, grader, or config is caught and sent back. Works in Claude Code, Codex, git hooks, and CI.",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@promptwheel/logbook": "^0.9.6",
-    "promptwheel": "^0.7.5"
+    "promptwheel": "^0.7.9"
   },
   "files": [
     "sawbuck.mjs",

package/reflect.mjs

@@ -30,6 +30,7 @@ const repo = flag('--repo', process.cwd());
 const base = flag('--base', 'HEAD~1');
 const head = flag('--head', 'HEAD');
 const by = flag('--by', '');   // the agent that authored the change (Claude-first: the Claude hook passes 'claude'); empty = unattributed (raw-git path)
+const noAuto = process.argv.includes('--no-auto');   // user-level wiring: measure only where a contract exists, never auto-gate a stranger's suite
 
 const git = (...a) => execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim();
 // backstop so the check can never hang a commit/turn; generous default, overridable.
@@ -42,7 +43,7 @@ const runNode = (file, a) => execFileSync(process.execPath, [file, ...a], { cwd:
 function check() {
   const parse = (out) => { const i = out.indexOf('{'); return i < 0 ? null : JSON.parse(out.slice(i)); };
   try {
-    return parse(runNode(PW, ['run', '--base', base, '--head', head, '--json']));
+    return parse(runNode(PW, ['run', '--base', base, '--head', head, '--json', ...(noAuto ? ['--no-auto'] : [])]));
   } catch (e) {
     return parse((e.stdout || '').toString());
   }
@@ -52,6 +53,20 @@ const report = check();
 if (!report || !report.verdict) process.exit(0);          // couldn't measure → nothing to learn
 const verdict = report.verdict;                            // engine contract: 'gamed' | 'fail' | ...
 appendActivity(verdict, report);   // the event feed logs EVERY measurable check, so you can watch it work (verified too, not only catches)
+// the results record, and the base this run measured from (a full sha), so a gamed verdict can be
+// held against the SAME span until it re-proves: the hook re-runs base..HEAD, not last-commit..HEAD
+const recDir = join(repo, '.sawbuck');
+const recPath = join(recDir, 'results.json');
+let rec = { regressions: 0, gamed: 0, latest: null };
+try { if (existsSync(recPath)) rec = JSON.parse(readFileSync(recPath, 'utf8')); } catch {}
+let baseSha = ''; try { baseSha = git('rev-parse', `${base}^{commit}`); } catch {}
+const standing = !!(rec.latest && rec.latest.kind === 'gamed' && rec.latest.base && rec.latest.base === baseSha);
+const writeRec = () => { try { mkdirSync(recDir, { recursive: true }); writeFileSync(recPath, JSON.stringify(rec, null, 2) + '\n'); } catch {} };
+if (verdict === 'pass' && standing) {
+  // the span the gamed verdict was measured over now passes from the source: the wall comes down
+  rec.latest = { sha: git('rev-parse', head).slice(0, 8), kind: 'verified', base: baseSha, file: rec.latest.file, reason: 'the source earned the green over the span the gamed verdict was measured on', at: new Date().toISOString(), by: by || null };
+  writeRec();
+}
 if (verdict !== 'gamed' && verdict !== 'fail') process.exit(0);   // only breakage is worth recording
 
 // map the engine verdict to Sawbuck's plain outcome words
@@ -73,17 +88,15 @@ const reason = kind === 'gamed'
 // --- 3) record the finding in memory (unreviewed, machine-authored note) ----
 // The Memory Contract's `record` capability, through the adapter (no direct engine shell here).
 // Kept simple: a commit-attached digest note. A later pass could add --span grounding
-// and true coupling (the fix diff -> "change X also needs Y").
-memRecord(repo, { sha, reason: reason.slice(0, 280), side: 'diff', evidenceFile, by: 'sawbuck' });
+// and true coupling (the fix diff -> "change X also needs Y"). A gamed verdict still standing
+// over the same span is the same catch, not a new one: no second note, no second tick.
+const repeatOfStanding = standing && kind === 'gamed';
+if (!repeatOfStanding) memRecord(repo, { sha, reason: reason.slice(0, 280), side: 'diff', evidenceFile, by: 'sawbuck' });
 
 // --- 4) tick the results record (the visible proof-of-work) -----------------
-const recDir = join(repo, '.sawbuck');
-const recPath = join(recDir, 'results.json');
-let rec = { regressions: 0, gamed: 0, latest: null };
-try { if (existsSync(recPath)) rec = JSON.parse(readFileSync(recPath, 'utf8')); } catch {}
-if (kind === 'gamed') rec.gamed += 1; else rec.regressions += 1;
-rec.latest = { sha: sha.slice(0, 8), kind, file: evidenceFile, reason: reason.replace(/^sawbuck: /, '').slice(0, 140), at: new Date().toISOString(), by: by || null };
-try { mkdirSync(recDir, { recursive: true }); writeFileSync(recPath, JSON.stringify(rec, null, 2) + '\n'); } catch {}
+if (!repeatOfStanding) { if (kind === 'gamed') rec.gamed += 1; else rec.regressions += 1; }
+rec.latest = { sha: sha.slice(0, 8), kind, base: baseSha || null, file: evidenceFile, reason: reason.replace(/^sawbuck: /, '').slice(0, 140), at: new Date().toISOString(), by: by || null };
+writeRec();
 
 // --- 5) quiet by default (dispatch surfaces on cadence); one line to stderr -
 process.stderr.write(`sawbuck: ${kind} recorded on ${evidenceFile}\n`);

package/sawbuck-hook.mjs

@@ -6,20 +6,26 @@
 
 import { execFileSync } from 'node:child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 import { mandateHits, hashOf, protectedDirty, protectedAmong } from './contract.mjs';
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
-const repo = flag('--repo', process.cwd());
 const by = flag('--by', '');   // attribution from the harness wiring: the Claude hook passes 'claude', the raw-git hook passes nothing
 const stop = process.argv.includes('--stop');   // wired as the Claude Code Stop hook: enforce the contract on a gamed turn
+// user-level wiring passes no --repo: the hook runs in whatever cwd the session has, so it resolves the
+// repository root itself (a subdirectory belongs to its repo) and leaves a non-repository alone: no
+// state, no exclude block, nothing written where there is nothing to verify.
+const userMode = !process.argv.includes('--repo');
+const sh = (cwd, ...a) => { try { return execFileSync('git', ['-C', cwd, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+const repo = flag('--repo', '') || sh(process.cwd(), 'rev-parse', '--show-toplevel') || process.cwd();
+const git = (...a) => sh(repo, ...a);
+if (!git('rev-parse', '--git-dir')) process.exit(0);
 let hookInput = {};
 if (stop) { try { hookInput = JSON.parse(readFileSync(0, 'utf8') || '{}'); } catch {} }   // the Stop hook's JSON on stdin (stop_hook_active, prompt_id, ...)
 ensureExcluded(repo);   // keep the record out of git status under ANY attach mode (incl. --user)
 
-const git = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
 const CHECK_TIMEOUT = +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 600000;   // never hang a turn
 const node = (f, a) => { try { return execFileSync(process.execPath, [f, ...a], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: CHECK_TIMEOUT, killSignal: 'SIGKILL' }); } catch (e) { return (e.stdout || '').toString(); } };
 
@@ -33,17 +39,23 @@ const stPath = join(stDir, 'state.json');
 let st = { lastSha: '', turns: 0, shownTotal: 0 };
 try { if (existsSync(stPath)) st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
 
-// 1) new commit(s) since last turn → run the check on them
+// 1) new commit(s) since last turn → run the check on them. A gamed verdict stands until the span it
+// was measured over re-proves verified: while the latest record is gamed, the re-run keeps that
+// record's base, so a follow-up commit (an amend, an empty commit, unrelated work) cannot clear the
+// wall without the source fix the re-proof demands. Under user-level wiring the check runs only where
+// a contract exists (--no-auto): nobody's whole test suite runs three times in a repo they never set up.
 const head = git('rev-parse', 'HEAD');
+const readRec = () => { try { return JSON.parse(readFileSync(join(stDir, 'results.json'), 'utf8')); } catch { return null; } };
+let rec = readRec();
 if (head && st.lastSha && head !== st.lastSha) {
-  node(join(HERE, 'reflect.mjs'), ['--repo', repo, '--base', st.lastSha, '--head', head, ...(by ? ['--by', by] : [])]);
+  const standing = !!(rec && rec.latest && rec.latest.kind === 'gamed' && rec.latest.base && rec.latest.sha !== head.slice(0, 8));
+  node(join(HERE, 'reflect.mjs'), ['--repo', repo, '--base', standing ? rec.latest.base : st.lastSha, '--head', head, ...(by ? ['--by', by] : []), ...(userMode ? ['--no-auto'] : [])]);
+  rec = readRec();
 }
 st.lastSha = head || st.lastSha;
 st.turns += 1;
 
-// 2) read the record of what the check has charted
-let rec = null;
-try { rec = JSON.parse(readFileSync(join(stDir, 'results.json'), 'utf8')); } catch {}
+// 2) the record of what the check has charted (read above, after any re-run)
 const total = rec ? (rec.regressions || 0) + (rec.gamed || 0) : 0;
 const saveState = () => { try { mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n'); } catch {} };
 
@@ -67,17 +79,22 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
   const leftAlone = dirty.filter(untouched);
   const hits = changed.length ? mandateHits(repo, changed) : [];
   st.lastStopAt = now;   // the next prompt may take a fresh baseline only because this stop happened
+  st.lastStopHead = head || null;   // and where HEAD stood: a commit between turns is the person's, not the agent's
   if (hits.length) {
-    // remember EVERY changed protected path (dirty or committed since the baseline) and what it holds,
-    // uncapped, and the commit the baseline stood at, so the next prompt cannot adopt any of it
-    const files = protectedDirty(repo);
-    for (const f of protectedAmong(repo, committedSince)) if (!Object.prototype.hasOwnProperty.call(files, f)) files[f] = hashOf(repo, f);
+    // remember EVERY protected path THIS TURN changed (dirty past the baseline, or committed since
+    // it) and what it holds, uncapped, plus the commit the baseline stood at, so the next prompt
+    // cannot adopt any of it. Only the turn's own changes: a person's file the baseline spared stays
+    // spared, or the next clean turn would be blocked over work that was never the agent's.
+    const files = {};
+    for (const f of protectedAmong(repo, changed)) files[f] = hashOf(repo, f);
     st.lastViolation = { at: now, sha: (base && base.sha) || null, files };
   } else if (st.lastViolation) { delete st.lastViolation; }
   saveState();
   if (hits.length) {
     const MAX_BLOCKS = +(cfg.enforce?.maxBlocks) || 3;
-    const promptId = hookInput.prompt_id || 'none';
+    // the budget is per prompt: prompt_id when the harness sends one, else the prompt's own timestamp
+    // (written by `sawbuck turn --hook`), never a constant that would spend the budget for good
+    const promptId = hookInput.prompt_id || st.lastPromptAt || 'none';
     if (st.mandatePromptId !== promptId) { st.mandatePromptId = promptId; st.mandateBlocks = 0; }
     const desc = hits.map((h) => `"${h.name}"${h.reason ? ' (' + h.reason + ')' : ''}: ${h.files.join(', ')}${h.committed ? ' [this rule is in the committed contract; editing promptwheel.config.json in the working tree does not lift it]' : ''}`).join('; ');
     const spared = leftAlone.length ? ` Edits that were already there before this prompt were left out of this check and must stay as they are: ${leftAlone.join(', ')}.` : '';
@@ -102,7 +119,7 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
 const gamedThisTurn = rec && rec.latest && rec.latest.kind === 'gamed' && rec.latest.sha === (head || '').slice(0, 8);
 if (stop && gamedThisTurn && !process.env.SAWBUCK_NO_ENFORCE) {
   const MAX_BLOCKS = +(cfg.enforce?.maxBlocks) || 3;
-  const promptId = hookInput.prompt_id || 'none';
+  const promptId = hookInput.prompt_id || st.lastPromptAt || 'none';
   if (st.blockPromptId !== promptId) { st.blockPromptId = promptId; st.blockCount = 0; }
   st.shownTotal = total;
   const where = rec.latest.file;
@@ -134,8 +151,10 @@ saveState();
 // per-repo `detach` removes them.
 function ensureExcluded(r) {
   try {
-    if (!existsSync(join(r, '.git'))) return;
-    const f = join(r, '.git', 'info', 'exclude');
+    // the repository's own exclude file, wherever its git dir is (a worktree or submodule keeps it elsewhere)
+    const rel = sh(r, 'rev-parse', '--git-path', 'info/exclude');
+    if (!rel) return;
+    const f = resolve(r, rel);
     // the record dirs + the logbook's root ledger cache (events.jsonl). Rewrite the block to
     // the CURRENT set rather than bail on presence, so a grown set retrofits existing repos.
     const WANT = '# >>> sawbuck >>>\n.sawbuck/\n.promptwheel/\nevents.jsonl\nannotations.jsonl\nannotation-reviews.jsonl\ndecision-cards.jsonl\nLOGBOOK.md\nJOURNEY.md\n# <<< sawbuck <<<\n';

package/sawbuck.mjs

@@ -101,6 +101,15 @@ Usage:
 Engines: promptwheel (the check) + @promptwheel/logbook (memory). Zero-LLM, offline, free.`;
 
 const die = (msg) => { process.stderr.write(`sawbuck: ${msg}\n`); process.exit(1); };
+const usage = (msg) => { process.stderr.write(`sawbuck: ${msg}\n`); process.exit(64); };   // could not run: never a verdict code
+// the repository a path belongs to (its toplevel), so a command run from a subdirectory lands at the
+// root: hooks pinned to the root, the receipt and the exclude under its git dir. '' outside a repo.
+function gitTop(p) { try { return execFileSync('git', ['-C', p, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } }
+const repoRoot = () => gitTop(repoArg()) || repoArg();
+// paths inside the repository's git dir, asked of git: a worktree or a submodule keeps its git dir
+// elsewhere (.git is a FILE there), so join(repo, '.git', ...) is wrong in exactly the repos where it hurts
+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');
 
 if (cmd === '--version' || cmd === '-v') { console.log(version); process.exit(0); }
@@ -214,7 +223,8 @@ switch (cmd) {
     // taken only when the previous turn actually reached a Stop (an interrupt, a crash, or a re-run of
     // this command mid-turn leaves the last one standing, so nothing the agent left behind is adopted);
     // a file still carrying the content the last violation flagged is never baselined; and the
-    // baseline's commit does not advance past a flagged commit until a clean stop.
+    // baseline's commit does not advance past a flagged commit until a clean stop or a commit the
+    // person made between turns.
     let hookEvent = '';
     if (flags.has('--hook') && !process.stdin.isTTY) { try { hookEvent = String(JSON.parse(readFileSync(0, 'utf8') || '{}').hook_event_name || ''); } catch {} }
     if (hookEvent === 'UserPromptSubmit') {
@@ -231,7 +241,12 @@ switch (cmd) {
             const files = protectedDirty(repo);
             for (const f of Object.keys(files)) if (flagged[f] === files[f]) delete files[f];   // the agent's un-reverted edit stays on the wall
             let sha = ''; try { sha = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch {}
-            st.turnBaseline = { at: now, sha: (st.lastViolation && st.lastViolation.sha) || sha, files };
+            // HEAD moved since the last Stop: the agent was not running, so the commits between turns
+            // are the person's (accepting a change, a pull, a branch switch) and the baseline starts
+            // there. Otherwise the baseline's commit does not advance past a flagged commit.
+            const moved = !!(sha && st.lastStopHead && sha !== st.lastStopHead);
+            if (moved && st.lastViolation) delete st.lastViolation.sha;
+            st.turnBaseline = { at: now, sha: (!moved && st.lastViolation && st.lastViolation.sha) || sha, files };
           }
           st.lastPromptAt = now;
           mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
@@ -273,8 +288,11 @@ switch (cmd) {
     break;
   }
   case 'attach': {
-    const repo = repoArg();
-    if (flags.has('--user')) { wireClaude(repo, { user: true }); if (!dry) verifyAttach(repo); break; }
+    const user = flags.has('--user');
+    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();
+    if (user) { wireClaude(repo, { user: true }); if (!dry) verifyAttach(repo); break; }
     if (flags.has('--claude')) { wireClaude(repo, { shared: flags.has('--shared') }); if (!dry) verifyAttach(repo); break; }
     wireGit(repo);
     if (!dry) verifyAttach(repo);
@@ -283,7 +301,7 @@ switch (cmd) {
   case 'detach': {
     const purge = flags.has('--purge');
     if (flags.has('--all')) { detachAll(purge); break; }
-    const repo = repoArg();
+    const repo = repoRoot();
     if (flags.has('--user')) unwireClaude(repo, { user: true });
     else if (flags.has('--claude')) unwireClaude(repo, {});
     else {
@@ -298,8 +316,8 @@ switch (cmd) {
     if (flags.has('--verify')) verifyClean(repo);
     break;
   }
-  case 'trace': { traceRepo(repoArg()); break; }
-  case 'doctor': { if (flags.has('--all')) doctorAll(); else doctorRepo(repoArg()); break; }
+  case 'trace': { traceRepo(repoRoot()); break; }
+  case 'doctor': { if (flags.has('--all')) doctorAll(); else doctorRepo(repoRoot()); break; }
   case 'where': { whereAttached(); break; }
   case 'statusline': {
     // compact status-line segment for the cwd repo. Never throws; fast.
@@ -362,7 +380,8 @@ function contextBlock(repo, speak) {
 // run the gate on the last commit and say what it can or cannot measure, so you never attach
 // into silent nothing. Best-effort and bounded; the wire already succeeded regardless.
 function verifyAttach(repo) {
-  const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
+  // stderr ignored: a benign failing probe (rev-parse HEAD~1 on a one-commit repo) must not leak a "fatal:" line
+  const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
   if (!g('rev-parse', 'HEAD')) { out('   attached. Make a commit, then run `sawbuck check` to see it work.'); return; }
   out('   verifying I can measure here (one-time)...');
   const base = g('rev-parse', '--verify', 'HEAD~1') ? 'HEAD~1' : 'HEAD';
@@ -373,7 +392,7 @@ function verifyAttach(repo) {
 }
 
 // --- the attach receipt (out of the worktree, inside .git) ------------------
-function manifestPath(repo) { return join(repo, '.git', 'sawbuck', 'attach.json'); }
+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 writeManifest(p, m) {
@@ -388,7 +407,7 @@ function rmIfEmptyDir(d) { try { if (existsSync(d) && readdirSync(d).length ===
 // --- .git/info/exclude: keep the worktree clean without touching .gitignore --
 // Rewrites a single marked block to the union of excludes the current
 // attachments need. Never deletes the file (an empty one is git's own default).
-function excludeFile(repo) { return join(repo, '.git', 'info', 'exclude'); }
+function excludeFile(repo) { return gitPath(repo, 'info/exclude'); }
 function syncExclude(repo, manifest) {
   const need = new Set();
   const a = manifest.attachments || {};
@@ -418,8 +437,8 @@ function hookBlock(repo) {
   return `${S_START}\nunset 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}; else node ${JSON.stringify(SELF)} __hook --repo ${r}; fi || true\n${S_END}\n`;
 }
 function wireGit(repo) {
-  if (!existsSync(join(repo, '.git'))) die(`${repo} is not a git repo (no .git)`);
-  const pc = join(repo, '.git', 'hooks', 'post-commit');
+  if (!gitTop(repo)) usage(`${repo} is not a git repository`);
+  const pc = gitPath(repo, 'hooks/post-commit');
   const existed = existsSync(pc);
   let body = existed ? readFileSync(pc, 'utf8') : '#!/bin/sh\n';
   if (body.includes(S_START)) { out(`sawbuck: already attached (git) in ${repo}`); return; }
@@ -443,7 +462,7 @@ function wireGit(repo) {
   out(`sawbuck: attached (git post-commit) in ${repo}`);
 }
 function unwireGit(repo) {
-  const pc = join(repo, '.git', 'hooks', 'post-commit');
+  const pc = gitPath(repo, 'hooks/post-commit');
   const m = readManifest(manifestPath(repo));
   const hasReceipt = !!m.attachments?.git;
   if (!existsSync(pc) && !hasReceipt) { out('sawbuck: nothing to detach'); return; }
@@ -560,7 +579,7 @@ function isTrivialSettings(cfg) { return Object.keys(cfg).length === 0; }
 // --- trace / verify / doctor / purge: show, prove, and clean the footprint --
 function footprint(repo) {
   const items = [];
-  const pc = join(repo, '.git', 'hooks', 'post-commit');
+  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 {}
@@ -601,7 +620,7 @@ function onPath() {
 function extractBaked(text) { const m = text.match(/node "([^"]+)"/); return m ? m[1] : null; }
 function doctorRepo(repo) {
   const checks = [];
-  const pc = join(repo, '.git', 'hooks', 'post-commit');
+  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 {}

package/status.mjs

@@ -35,6 +35,10 @@ const seen = feed.length;
 const catchesAllTime = (results.regressions || 0) + (results.gamed || 0);
 const latest = results.latest || (feed.length ? feed[feed.length - 1] : null);
 const since = feed.length ? (feed[0].at || '').slice(0, 10) : null;
+// the steer rate, if the reins judge has been scoring turns here (an OFFLINE read of its file; the
+// recent-window average over roughly the last twenty scored turns, as the band and statusline show it)
+const steerRec = readJSON(join(repo, '.sawbuck', 'steer.json'));
+const steer = steerRec && steerRec.scored ? { rate: Math.round(((steerRec.ema != null ? steerRec.ema : steerRec.steeringRate) || 0) * 100), scored: steerRec.scored } : null;
 
 // --- 2) the armed state: what it can measure here (mirror of statusline) ---
 const isGit = !!existsSync(join(repo, '.git'));
@@ -65,6 +69,7 @@ if (asJson) {
     git: isGit,
     config: hasConfig,
     outcomes: { seen, caughtAllTime: catchesAllTime, gamedAllTime: results.gamed || 0, regressionsAllTime: results.regressions || 0, recent: tally, latest, since },
+    steer,
     debt: debt ? { total: debt.total, testSkips: debt.testSkips, undocumented: debt.undocumented, filesOnFragileCode: debt.filesOnFragileCode, top: (debt.files || []).slice(0, 5) } : null,
     debtError: debtErr,
   }, null, 2));
@@ -105,6 +110,12 @@ if (seen || catchesAllTime) {
   out.push(`   Caught for you  ·  nothing recorded yet (the check logs here on each commit/turn)`);
 }
 
+// Steering (only when the judge has scored turns here)
+if (steer) {
+  out.push('');
+  out.push(`   Steer rate  ·  ${steer.rate}% of your recent turns redirected the agent (${steer.scored} scored, recent-window average)`);
+}
+
 // Debt
 out.push('');
 if (debt && debt.total) {