sawbuck 0.1.29 → 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/contract.mjs

@@ -53,6 +53,12 @@ export function mandatesInForce(repo, ref = 'HEAD') {
   return [...wt, ...committed];
 }
 
+// the paths among `paths` that a mandate in force covers (any rule, working tree or committed)
+export function protectedAmong(repo, paths) {
+  const res = mandatesInForce(repo).flatMap((m) => pathsOf(m).map(globToRe));
+  return paths.filter((f) => res.some((re) => re.test(f)));
+}
+
 // a working-tree file's content hash as git would store it; 'deleted' when it is gone
 export function hashOf(repo, file) {
   try { return gitOut(repo, ['hash-object', '--', file]).trim(); } catch { return 'deleted'; }

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.29",
+  "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 } from './contract.mjs';
+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,36 +39,25 @@ 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 {} };
-// when the last prompt of this session was typed, from the transcript the hook names (null when unknown):
-// the newest user row that carries text, not a tool result; the tail of the file is enough
-function lastPromptTime(transcriptPath) {
-  try {
-    if (!transcriptPath || !existsSync(transcriptPath)) return null;
-    const text = readFileSync(transcriptPath, 'utf8'); const tail = text.length > 524288 ? text.slice(-524288) : text;
-    const lines = tail.split('\n');
-    for (let i = lines.length - 1; i >= 0; i--) {
-      let o; try { o = JSON.parse(lines[i]); } catch { continue; }
-      if (!o || o.type !== 'user' || !o.timestamp) continue;
-      const c = o.message && o.message.content;
-      const isText = typeof c === 'string' || (Array.isArray(c) && c.some((p) => p && p.type === 'text') && !c.some((p) => p && p.type === 'tool_result'));
-      if (isText) { const t = Date.parse(o.timestamp); return Number.isFinite(t) ? t : null; }
-    }
-  } catch {}
-  return null;
-}
 
 // 2b) THE WALL AT TURN LEVEL (Claude Code Stop hook only): a mandate is checked against the WORKING
 // tree on every stop, not only on commits, because an agent usually ends a turn with uncommitted
@@ -70,34 +65,45 @@ function lastPromptTime(transcriptPath) {
 // and send the agent back to undo its protected edits and make the fix elsewhere. The rules are the
 // working tree's AND the committed contract's (editing the config in the same turn lifts nothing),
 // and a protected file that was already dirty with the same content when the prompt began (the
-// baseline `sawbuck turn` recorded) is the person's own work and does not count.
+// baseline `sawbuck turn --hook` recorded) is the person's own work and does not count. A protected
+// edit COMMITTED since the baseline's commit counts too: a commit mid-turn does not walk through.
 if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
+  const now = new Date().toISOString();
   const dirty = [...new Set([...git('diff', '--name-only', 'HEAD').split('\n'), ...git('ls-files', '--others', '--exclude-standard').split('\n')].filter(Boolean))];
-  // the baseline `sawbuck turn --hook` recorded when the prompt began; one recorded well AFTER the
-  // transcript's last prompt was not the prompt's (something re-ran `turn` mid-turn) and is ignored
-  let baseline = (st.turnBaseline && st.turnBaseline.files && typeof st.turnBaseline.files === 'object') ? st.turnBaseline.files : {};
-  const promptAt = lastPromptTime(hookInput.transcript_path);
-  const baseAt = Date.parse(st.turnBaseline && st.turnBaseline.at);
-  if (promptAt && baseAt && baseAt > promptAt + 30000) baseline = {};
+  const base = (st.turnBaseline && typeof st.turnBaseline === 'object') ? st.turnBaseline : null;
+  const baseline = (base && base.files && typeof base.files === 'object') ? base.files : {};
+  const committedSince = (base && base.sha && head && base.sha !== head) ? git('diff', '--name-only', base.sha, 'HEAD').split('\n').filter(Boolean) : [];
   const hashNow = {}; for (const f of dirty) if (Object.prototype.hasOwnProperty.call(baseline, f)) hashNow[f] = hashOf(repo, f);
   const untouched = (f) => Object.prototype.hasOwnProperty.call(baseline, f) && hashNow[f] === baseline[f];
-  const changed = dirty.filter((f) => !untouched(f));
+  const changed = [...new Set([...dirty.filter((f) => !untouched(f)), ...committedSince])];
   const leftAlone = dirty.filter(untouched);
   const hits = changed.length ? mandateHits(repo, changed) : [];
-  // remember what was flagged and what it held, so the next prompt's baseline cannot adopt it
-  if (hits.length) { const files = {}; for (const h of hits) for (const f of h.files) files[f] = hashOf(repo, f); st.lastViolation = { at: new Date().toISOString(), files }; }
-  else if (st.lastViolation) { delete st.lastViolation; saveState(); }
+  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 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(', ')}.` : '';
+    const upgrade = base ? '' : ' (No prompt baseline is recorded in this repo, so edits a person made before the prompt cannot be told apart from yours: ask them to run sawbuck attach --claude again, which upgrades the hooks.)';
     try { mkdirSync(stDir, { recursive: true }); appendFileSync(join(stDir, 'activity.jsonl'), JSON.stringify({ at: new Date().toISOString(), kind: 'mandate', file: hits[0].files[0], reason: `mandate ${hits[0].name} violated in the working tree`, by: by || 'hook' }) + '\n'); } catch {}
     if ((st.mandateBlocks || 0) < MAX_BLOCKS) {
       st.mandateBlocks = (st.mandateBlocks || 0) + 1;
       saveState();
-      process.stdout.write(JSON.stringify({ decision: 'block', reason: `Sawbuck: a mandate in the contract was violated, the turn is not done. Protected paths changed in this turn: ${desc}. Undo the changes YOU made under the protected paths and make the fix elsewhere; do not revert anything you did not change (the rule is a wall, not a reminder; the gate fails any change that touches them).${spared}` }));
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: `Sawbuck: a mandate in the contract was violated, the turn is not done. Protected paths changed in this turn: ${desc}. Undo the changes YOU made under the protected paths and make the fix elsewhere; do not revert anything you did not change (the rule is a wall, not a reminder; the gate fails any change that touches them).${spared}${upgrade}` }));
       process.exit(0);
     }
     saveState();
@@ -113,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;
@@ -145,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); }
@@ -210,9 +219,12 @@ switch (cmd) {
     // fires mid-turn), remember which protected paths were already dirty and what they held, so the
     // Stop hook's wall counts only what this turn changes and leaves a person's own edits alone.
     // Only under --hook (the wiring passes it) is stdin read for the hook's JSON, so a plain
-    // `sawbuck turn` never waits on a pipe. Two rules keep the baseline honest: a file still carrying
-    // the content the last violation flagged is the agent's, not the person's, and is never
-    // baselined; and the Stop hook ignores a baseline recorded well after the prompt began.
+    // `sawbuck turn` never waits on a pipe. Three rules keep the baseline honest: a new baseline is
+    // 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 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') {
@@ -220,10 +232,23 @@ switch (cmd) {
         if (mandatesInForce(repo).length) {
           const stDir = join(repo, '.sawbuck'); const stPath = join(stDir, 'state.json');
           let st = {}; try { st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
-          const flagged = (st.lastViolation && st.lastViolation.files && typeof st.lastViolation.files === 'object') ? st.lastViolation.files : {};
-          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
-          st.turnBaseline = { at: new Date().toISOString(), files };
+          const now = new Date().toISOString();
+          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;
+          if (!unfinished) {
+            const flagged = (st.lastViolation && st.lastViolation.files && typeof st.lastViolation.files === 'object') ? st.lastViolation.files : {};
+            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 {}
+            // 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');
         }
       } catch { /* the frame never fails a prompt */ }
@@ -263,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);
@@ -273,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 {
@@ -288,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.
@@ -352,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';
@@ -363,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) {
@@ -378,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 || {};
@@ -408,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; }
@@ -433,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; }
@@ -550,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 {}
@@ -591,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) {