sawbuck 0.1.31 → 0.1.33

package/CONTRACT.md

@@ -77,7 +77,7 @@ This is the part that makes "moving the goalposts" objective rather than a judgm
 
 A win is **`gamed`** when it does not survive a **source-only re-run**: revert every non-source change the agent made, re-measure, and see how much of the gain remains (`retained`). If `retained` falls below `gamingThreshold` (default `0.5`), the verdict is `gamed`.
 
-- **Non-source** (reverted before the re-run): tests, specs, fixtures, snapshots and golden files, graders, config, lockfiles, CI definitions, build gates, and any path the repo opts into via `evaluatorPaths`.
+- **Non-source** (reverted before the re-run): tests, specs, fixtures, snapshots and golden files, graders, config, plus any path declared in `evaluatorPaths`.
 - **Source**: everything else, the code the change was supposed to be about.
 - **`evaluatorPaths`**: an opt-in allowlist a repo declares for its own gate files (a threshold file, a budget, a ruleset), because a generic name is a classifier risk and only the repo owner knows which files are the goalposts.
 

package/README.md

@@ -34,16 +34,16 @@ $ sawbuck check        # after fixing the source and restoring the test
 🐴 ✓ verified: your working change earned it. "tests_pass" held, and the source carried the win.
 ```
 
-Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `64` could not run (not a git repo, no commit, no test command).
+Exit codes: `0` verified · `1` regression · `2` gamed · `3` inconclusive · `64` could not run (not a git repo, no commit); no detectable test command reads `3` inconclusive.
 
 ## What it does
 
-- **Verifies the win.** `check` re-runs your metric from the source diff alone. A faked green (a deleted, weakened, or skipped test; a mocked grader; an edited golden file; a loosened config) reads `gamed`. Deterministic, zero-LLM, $0, and it cannot be argued with because it never reads the trajectory. Red-teamed across 9 language ecosystems and 26 adversarial scenarios ([promptwheel/bench/REDTEAM.md](https://github.com/promptwheel-ai/promptwheel/blob/main/bench/REDTEAM.md)).
+- **Verifies the win.** `check` re-runs your metric from the source diff alone. A faked green (a deleted, weakened, or skipped test; a mocked grader; an edited golden file; a loosened config) reads `gamed`. Deterministic, zero-LLM, $0, and it cannot be argued with because it never reads the trajectory. Red-teamed across 9 ecosystems and 26 adversarial scenarios ([promptwheel/bench/REDTEAM.md](https://github.com/promptwheel-ai/promptwheel/blob/main/bench/REDTEAM.md)).
 - **Says what it cannot see.** A cheat that lives inside the source itself (a value hardcoded to the one visible case, logic keyed to the test environment) is invisible to a source-only re-run, by construction. That limit is in [the contract](CONTRACT.md#3-the-integrity-boundary-what-counts-as-gaming), not hidden.
 - **Remembers what broke.** `context` surfaces the relevant history (reverts, fragile areas, test-weakening) for the files you are touching: a ranked trail guide, before you act.
 - **Shows you everything.** `status` is the inventory: what it has caught for you over time, the debt accruing now, and whether it is armed here, in one view. On-demand, so it is quiet until you go looking.
 - **Rides on, does not replace.** Sawbuck is the verify + memory layer. Your agent and your loop stay yours.
-- **Clean on and off.** `attach` touches nothing in your worktree (the hook lives in `.git/`, the record is excluded locally); `detach` is a true inverse. `trace` shows every byte it placed, and `detach --verify` proves the repo came back unchanged.
+- **Clean on and off.** the default `attach` touches nothing in your worktree (the hook lives in `.git/`, the record is excluded locally); `--claude` writes one git-excluded settings file; `detach` is a true inverse. `trace` shows every byte it placed, and `detach --verify` proves the repo came back unchanged.
 
 ## Commands
 

package/contract.mjs

@@ -1,7 +1,7 @@
 // contract.mjs: the contract's hard rules, read the way promptwheel reads them. Shared by the CLI
 // (frame / turn) and the Stop hook (the turn-level wall), so there is one resolver and one renderer.
 // Read-only, never throws, zero-dep.
-import { readFileSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname, resolve, isAbsolute, posix } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
@@ -59,24 +59,32 @@ export function protectedAmong(repo, paths) {
   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'; }
+// a working-tree file's content hash as git would store it; 'deleted' when it is gone. With `store`,
+// the content is also written into the object database (`hash-object -w`), so a person's edit that
+// the baseline recorded can be restored by hash later even after the agent overwrote the file.
+export function hashOf(repo, file, { store = false } = {}) {
+  try { return gitOut(repo, ['hash-object', ...(store ? ['-w'] : []), '--', file]).trim(); } catch { return 'deleted'; }
 }
 
 // the protected paths that are dirty right now, each with its content hash: the baseline `turn`
 // records when a prompt begins, so the Stop hook counts only what the turn itself changed and leaves
 // a person's own pre-existing edits alone. {} when nothing protected is dirty (or not a git repo).
-export function protectedDirty(repo) {
+// `store` keeps each file's content in the object database (see hashOf), which the baseline does.
+export function protectedDirty(repo, { store = false } = {}) {
   let changed = [];
   try { changed = [...new Set([...gitOut(repo, ['diff', '--name-only', 'HEAD']).split('\n'), ...gitOut(repo, ['ls-files', '--others', '--exclude-standard']).split('\n')].filter(Boolean))]; }
   catch { return {}; }
   const res = mandatesInForce(repo).flatMap((m) => pathsOf(m).map(globToRe));
   const out = {};
-  for (const f of changed) if (res.some((re) => re.test(f))) out[f] = hashOf(repo, f);
+  for (const f of changed) if (res.some((re) => re.test(f))) out[f] = hashOf(repo, f, { store });
   return out;
 }
 
+// the blob hash a tracked path has at `ref` ('' when the path is not there)
+export function blobAt(repo, ref, file) {
+  try { return gitOut(repo, ['rev-parse', `${ref}:${file}`]).trim(); } catch { return ''; }
+}
+
 // the same glob dialect as promptwheel's evaluatorPaths / mandates (ported verbatim): a bare name
 // matches that basename at any depth; a pattern with "/" is anchored at the repo root; "*" stops at
 // "/", "**" crosses it, "?" is one char; a leading "/" anchors to the root explicitly.
@@ -116,3 +124,13 @@ export function frameBlock(repo) {
   const lines = mandates.map((m) => `  ${m.paths.filter((s) => typeof s === 'string' && s.trim()).join(' · ')}${m.reason ? `  (${String(m.reason).slice(0, 160)})` : ''}`);
   return '▣ contract (sawbuck) · hard rules in force this session, enforced by the gate on every turn:\n  protected, do not touch:\n' + lines.join('\n');
 }
+
+// the repo's architecture lock, if the supply-chain preset is installed: structure the lock has not seen, and a
+// fingerprint of the resolved dependency tree. null when there is no lock here. Read-only, and fast (under 200 ms
+// on the largest repo tried), so it can run at every turn end.
+export function lockState(repo) {
+  const tool = join(repo, '.promptwheel', 'packs', 'supply-chain', 'lock.mjs');
+  if (!existsSync(tool) || !existsSync(join(repo, 'promptwheel.lock.json'))) return null;
+  const run = (...a) => execFileSync(process.execPath, [tool, ...a], { cwd: repo, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  try { return { drift: JSON.parse(run('drift', '.', '--json')), pins: run('pins', '.') }; } catch { return null; }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sawbuck",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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",
@@ -33,8 +33,8 @@
     "sawbuck": "sawbuck.mjs"
   },
   "dependencies": {
-    "@promptwheel/logbook": "^0.9.6",
-    "promptwheel": "^0.7.9"
+    "@promptwheel/logbook": "0.9.10",
+    "promptwheel": "0.7.11"
   },
   "files": [
     "sawbuck.mjs",

package/reflect.mjs

@@ -35,7 +35,10 @@ const noAuto = process.argv.includes('--no-auto');   // user-level wiring: measu
 const git = (...a) => execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim();
 // backstop so the check can never hang a commit/turn; generous default, overridable.
 const CHECK_TIMEOUT = +(process.env.SAWBUCK_CHECK_TIMEOUT_MS) || 600000;
-const runNode = (file, a) => execFileSync(process.execPath, [file, ...a], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: CHECK_TIMEOUT, killSignal: 'SIGKILL' });
+// a commit an agent made: its own Promptwheel-Allow trailer does not clear the verdict. An agent can write a
+// commit message, so the override for its work is a person running `sawbuck check --allow "<reason>"`.
+const childEnv = by ? { ...process.env, PROMPTWHEEL_NO_ALLOW_TRAILER: '1' } : process.env;
+const runNode = (file, a) => execFileSync(process.execPath, [file, ...a], { cwd: repo, encoding: 'utf8', env: childEnv, stdio: ['ignore', 'pipe', 'pipe'], timeout: CHECK_TIMEOUT, killSignal: 'SIGKILL' });
 
 // --- 1) the check: measure the commit, parse the structured result ----------
 // The check exits nonzero on fail/gamed/inconclusive, but still prints the JSON
@@ -52,7 +55,6 @@ function check() {
 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');
@@ -62,10 +64,23 @@ try { if (existsSync(recPath)) rec = JSON.parse(readFileSync(recPath, 'utf8'));
 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 };
+appendActivity(verdict, report, standing);   // the event feed logs EVERY measurable check, so you can watch it work (verified too, not only catches)
+if (standing) {
+  let headSha = ''; try { headSha = git('rev-parse', head); } catch {}
+  if (verdict === 'pass') {
+    // the span the gamed verdict was measured over now passes from the source: the wall comes down
+    rec.latest = { sha: headSha.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();
+    process.exit(0);
+  }
+  // gamed again, a regression on top, or a span that cannot be certified: the source has still not
+  // earned the green over the span the verdict was measured on, so the gamed record holds, advanced
+  // to this head (the Stop hook keeps the wall up), its file and attribution untouched (a commit
+  // the person made in between is not the catch), and nothing is counted or noted a second time
+  rec.latest = { ...rec.latest, sha: headSha.slice(0, 8), at: new Date().toISOString(), standingVerdict: verdict };
   writeRec();
+  process.stderr.write(`sawbuck: the gamed verdict on ${rec.latest.file} still stands (${verdict} over the same span)\n`);
+  process.exit(0);
 }
 if (verdict !== 'gamed' && verdict !== 'fail') process.exit(0);   // only breakage is worth recording
 
@@ -104,7 +119,7 @@ process.stderr.write(`sawbuck: ${kind} recorded on ${evidenceFile}\n`);
 // --- the activity feed: one line per check so you can watch it work, verified
 // included, not only catches. Capped, lives in the git-excluded .sawbuck/, opt
 // out with SAWBUCK_NO_LOG=1. `sawbuck log` reads it.
-function appendActivity(v, rep) {
+function appendActivity(v, rep, standing = false) {
   if (process.env.SAWBUCK_NO_LOG) return;
   const map = { pass: 'verified', gamed: 'gamed', fail: 'regression', inconclusive: 'inconclusive' };
   const k = (v === 'pass' && rep.allowed) ? 'allowed' : map[v];   // a declared override is logged distinctly, for the audit trail
@@ -118,7 +133,8 @@ function appendActivity(v, rep) {
     : k === 'allowed' ? ('declared intentional: ' + (rep.allowed?.reason || ''))
     : k === 'verified' ? 'the source earned the green'
     : 'could not certify a pass';
-  const ev = { at: new Date().toISOString(), kind: k, sha, file, reason: String(why).slice(0, 160), by: by || null };
+  // `standing`: this check re-proved the span of a gamed verdict that is still up, not a new catch
+  const ev = { at: new Date().toISOString(), kind: k, sha, file, reason: String(why).slice(0, 160), by: by || null, ...(standing ? { standing: true } : {}) };
   const dir = join(repo, '.sawbuck');
   const p = join(dir, 'activity.jsonl');
   try {

package/sawbuck-hook.mjs

@@ -10,7 +10,7 @@ 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';
+import { mandateHits, hashOf, protectedDirty, protectedAmong, lockState } from './contract.mjs';
 const flag = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d; };
 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
@@ -46,9 +46,21 @@ try { if (existsSync(stPath)) st = JSON.parse(readFileSync(stPath, 'utf8')); } c
 // 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; } };
+const writeRec = (r) => { try { mkdirSync(stDir, { recursive: true }); writeFileSync(join(stDir, 'results.json'), JSON.stringify(r, null, 2) + '\n'); } catch {} };
+const logActivity = (ev) => { try { mkdirSync(stDir, { recursive: true }); appendFileSync(join(stDir, 'activity.jsonl'), JSON.stringify({ at: new Date().toISOString(), ...ev }) + '\n'); } catch {} };
+const hasCommit = (ref) => { try { execFileSync('git', ['-C', repo, 'cat-file', '-e', `${ref}^{commit}`], { stdio: 'ignore' }); return true; } catch { return false; } };
 let rec = readRec();
 if (head && st.lastSha && head !== st.lastSha) {
-  const standing = !!(rec && rec.latest && rec.latest.kind === 'gamed' && rec.latest.base && rec.latest.sha !== head.slice(0, 8));
+  let standing = !!(rec && rec.latest && rec.latest.kind === 'gamed' && rec.latest.base && rec.latest.sha !== head.slice(0, 8));
+  if (standing && !hasCommit(rec.latest.base)) {
+    // the span can no longer be re-proved (a rebase, a squash, a pruned branch took its base away):
+    // say so in the feed, drop the record to unverified (never blocked on), and keep checking new
+    // commits from the last one seen, so the wall's loss is visible instead of a silent stop
+    logActivity({ kind: 'note', sha: head.slice(0, 8), file: rec.latest.file || '', reason: 'the base of the standing gamed verdict is gone from this clone (rebased or pruned); the record is cleared and new commits are checked from the last one seen', by: by || 'hook' });
+    rec.latest = { ...rec.latest, kind: 'unverified', at: new Date().toISOString(), reason: 'the base of the gamed verdict left the clone before the span re-proved from the source' };
+    writeRec(rec);
+    standing = false;
+  }
   node(join(HERE, 'reflect.mjs'), ['--repo', repo, '--base', standing ? rec.latest.base : st.lastSha, '--head', head, ...(by ? ['--by', by] : []), ...(userMode ? ['--no-auto'] : [])]);
   rec = readRec();
 }
@@ -87,7 +99,12 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
     // 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 };
+    // a flagged file the person had dirty before the prompt: keep the hash of THEIR content (the
+    // baseline stored it in the object database), so the block can name the exact restore and the
+    // next baseline can recognise the restored file as theirs
+    const before = {};
+    for (const f of Object.keys(files)) if (Object.prototype.hasOwnProperty.call(baseline, f) && baseline[f] && baseline[f] !== 'deleted') before[f] = baseline[f];
+    st.lastViolation = { at: now, sha: (base && base.sha) || null, files, ...(Object.keys(before).length ? { before } : {}) };
   } else if (st.lastViolation) { delete st.lastViolation; }
   saveState();
   if (hits.length) {
@@ -98,12 +115,16 @@ if (stop && !process.env.SAWBUCK_NO_ENFORCE) {
     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 before = (st.lastViolation && st.lastViolation.before) || {};
+    const restore = Object.keys(before).length ? ' To put back what you overwrote: ' + Object.entries(before).map(([f, h]) => `restore ${f} to the content it had when the prompt began: git cat-file -p ${h} > ${f}`).join('; ') + '.' : '';
+    const committedHit = hits.some((h) => h.files.some((f) => committedSince.includes(f)));
+    const accept = committedHit ? ' To accept this change on purpose, change the mandate in the contract or revert the path.' : '';
     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 {}
+    logActivity({ kind: 'mandate', file: hits[0].files[0], reason: `mandate ${hits[0].name} violated in the working tree`, by: by || 'hook' });
     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}${upgrade}` }));
+      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}${restore}${accept}${upgrade}` }));
       process.exit(0);
     }
     saveState();
@@ -135,6 +156,25 @@ if (stop && gamedThisTurn && !process.env.SAWBUCK_NO_ENFORCE) {
   process.exit(0);
 }
 
+// 3b) THE LOCK AT TURN LEVEL: tell the person the moment a turn changes the repo's structure or its resolved
+// dependencies. A notice, not a block: a person who asked for a new dependency should not fight the wall, and
+// the gate in CI is the hard stop, which needs their reason. Said once per change.
+if (stop && !process.env.SAWBUCK_NO_ENFORCE && st.turnBaseline && st.turnBaseline.lock) {
+  const was = st.turnBaseline.lock, now = lockState(repo);
+  if (now) {
+    const known = new Set(was.drift || []);
+    const fresh = (now.drift || []).filter((i) => !known.has(i));
+    const pinsMoved = !!now.pins && now.pins !== was.pins;
+    const key = JSON.stringify([fresh, pinsMoved ? now.pins : '']);
+    if ((fresh.length || pinsMoved) && st.lockNotice !== key) {
+      st.lockNotice = key; saveState();
+      const what = [...fresh.slice(0, 8), ...(pinsMoved ? ['the resolved dependency tree'] : [])].join(', ');
+      process.stdout.write(JSON.stringify({ systemMessage: `Sawbuck: this turn changed what the lock holds: ${what}${fresh.length > 8 ? `, and ${fresh.length - 8} more` : ''}. If you did not ask for that, look before you commit. The gate needs your reason to pass it: promptwheel run --allow "<reason>".` }));
+      process.exit(0);
+    }
+  }
+}
+
 // 4) otherwise, surface a catch on a fresh catch or on cadence (a flag; never blocks)
 const freshCatch = total > (st.shownTotal || 0);
 const cadenceHit = everyTurns > 0 && st.turns % everyTurns === 0;

package/sawbuck.mjs

@@ -19,7 +19,7 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { recall as memRecall, conform as memConform } from './memory.mjs';
 import { PW } from './bins.mjs';
-import { frameBlock, mandatesInForce, protectedDirty } from './contract.mjs';
+import { frameBlock, mandatesInForce, protectedDirty, blobAt, lockState } from './contract.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
 const HERE = dirname(SELF);
@@ -200,12 +200,12 @@ switch (cmd) {
     catch (e) { process.exit(e.status || 1); }
     break;
   }
-  case 'context': { const o = contextBlock(repoArg(), flags.has('--speak')); if (o) out(o); break; }
+  case 'context': { const o = contextBlock(repoRoot(), flags.has('--speak')); if (o) out(o); break; }
   case 'frame': {
     // the prompt face of the contract: re-impress the hard rules (mandates, resolved through `extends`)
     // as one compact block at the live end of the context, so a deep or freshly compacted session
     // cannot forget them. Silent without a contract; --speak explains instead.
-    const o = frameBlock(repoArg());
+    const o = frameBlock(repoRoot());
     if (o) out(o);
     else if (flags.has('--speak')) out('🐴 sawbuck frame: no mandates in promptwheel.config.json yet. Add one (a protected path) and this re-asserts it every turn and after every compaction, so a deep context cannot forget it.');
     break;
@@ -214,7 +214,10 @@ switch (cmd) {
     // the ONE per-prompt hook: the contract frame (forward: what must hold) and the relevant history
     // (backward: what broke here before) in a single block, one process per prompt. Silent when
     // there is nothing to say. Wired by `attach --claude` on UserPromptSubmit and after a compaction.
-    const repo = repoArg();
+    // the repository the way the Stop hook sees it: the root of the cwd under user-level wiring (a
+    // subdirectory belongs to its repo), the pinned path under project wiring; '' outside a repo
+    const top = gitTop(repoArg());
+    const repo = top || repoArg();
     // When a PROMPT begins (the UserPromptSubmit hook, never the SessionStart[compact] one, which
     // 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.
@@ -224,33 +227,40 @@ switch (cmd) {
     // 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.
+    // person made between turns that no longer carries the flagged content.
     let hookEvent = '';
     if (flags.has('--hook') && !process.stdin.isTTY) { try { hookEvent = String(JSON.parse(readFileSync(0, 'utf8') || '{}').hook_event_name || ''); } catch {} }
-    if (hookEvent === 'UserPromptSubmit') {
+    if (hookEvent === 'UserPromptSubmit' && top) {
       try {
+        const stDir = join(repo, '.sawbuck'); const stPath = join(stDir, 'state.json');
+        let st = {}; try { st = JSON.parse(readFileSync(stPath, 'utf8')); } catch {}
+        const now = new Date().toISOString();
         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 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
+            const before = (st.lastViolation && st.lastViolation.before && typeof st.lastViolation.before === 'object') ? st.lastViolation.before : {};
+            // the content is stored (hash-object -w), so a person's edit the agent later overwrites can
+            // be restored by hash; a file still carrying the flagged content is baselined at the content
+            // the person had before the agent touched it, or not at all
+            const files = protectedDirty(repo, { store: true });
+            for (const f of Object.keys(files)) if (flagged[f] === files[f]) { if (before[f] && before[f] !== 'deleted') files[f] = before[f]; else delete files[f]; }
             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.
+            // there, UNLESS HEAD still carries a flagged file's content: then the pin holds (a commit
+            // a background process landed after the Stop does not walk the agent's change through).
             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 };
+            const stillInHead = moved && Object.entries(flagged).some(([f, h]) => { const b = blobAt(repo, sha, f); return h === 'deleted' ? b === '' : (!!h && b === h); });
+            const pin = !!(st.lastViolation && st.lastViolation.sha);
+            if (moved && !stillInHead && st.lastViolation) delete st.lastViolation.sha;
+            st.turnBaseline = { at: now, sha: ((!moved || stillInHead) && pin && st.lastViolation.sha) || sha, files, lock: lockState(repo) };
           }
-          st.lastPromptAt = now;
-          mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
         }
+        st.lastPromptAt = now;   // every prompt, mandates or not: the walls key their block budgets on it when the harness sends no prompt_id
+        mkdirSync(stDir, { recursive: true }); writeFileSync(stPath, JSON.stringify(st, null, 2) + '\n');
       } catch { /* the frame never fails a prompt */ }
     }
     const o = [frameBlock(repo), contextBlock(repo, false)].filter(Boolean).join('\n');
@@ -260,8 +270,8 @@ switch (cmd) {
   case 'recall': {
     // the notes face: supplementary relevant notes for your current changes, from any non-git memory
     // provider (e.g. an Obsidian vault). On-demand. Git history + live debt come from context / debt.
-    const repo = repoArg();
-    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8' }).trim(); } catch { return ''; } };
+    const repo = repoRoot();
+    const g = (...a) => { try { return execFileSync('git', ['-C', repo, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
     let changed = g('diff', '--name-only', 'HEAD').split('\n').filter(Boolean);
     if (!changed.length) changed = g('diff', '--name-only', 'HEAD~1', 'HEAD').split('\n').filter(Boolean);
     if (!changed.length) { out('🐴 sawbuck: nothing changed to look up.'); break; }
@@ -434,7 +444,7 @@ function hookBlock(repo) {
   // git exports GIT_DIR / GIT_INDEX_FILE / GIT_WORK_TREE into its hooks. The check
   // shells out to git (worktrees, diffs) and would inherit them, operate on the wrong
   // repo, and silently catch nothing. Clear them so the reflex runs against `repo` clean.
-  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`;
+  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 ${nodeCmd()} ${JSON.stringify(SELF)} __hook --repo ${r}; fi || true\n${S_END}\n`;
 }
 function wireGit(repo) {
   if (!gitTop(repo)) usage(`${repo} is not a git repository`);
@@ -488,6 +498,13 @@ function claudeFile(repo, { user, shared }) {
   const name = user || shared ? 'settings.json' : 'settings.local.json';
   return { dir, f: join(dir, name) };
 }
+// hooks run under /bin/sh, which does not load nvm, so a bare `node` is missing on many machines and the
+// hook fails quietly, leaving the wall off. Use node from PATH when there is one (it follows an upgrade),
+// else the node that ran this attach. Windows keeps plain node: its hooks do not run under sh.
+export function nodeCmd(execPath = process.execPath, platform = process.platform) {
+  if (platform === 'win32') return 'node';
+  return `"$(command -v node || echo ${JSON.stringify(execPath).replace(/^"|"$/g, "'")})"`;
+}
 function wireClaude(repo, opts) {
   const { user, shared } = opts;
   const { dir, f } = claudeFile(repo, opts);
@@ -495,8 +512,8 @@ function wireClaude(repo, opts) {
   const fileExisted = existsSync(f);
   let cfg = {};
   if (fileExisted) { try { cfg = JSON.parse(readFileSync(f, 'utf8')); } catch { die(`${f} exists but is not valid JSON; I will not overwrite it. Add the hooks by hand.`); } }
-  const ctx = user ? `node ${JSON.stringify(SELF)} turn --hook` : `node ${JSON.stringify(SELF)} turn --hook ${JSON.stringify(repo)}`;
-  const chk = user ? `node ${JSON.stringify(SELF)} __hook --by claude --stop` : `node ${JSON.stringify(SELF)} __hook --repo ${JSON.stringify(repo)} --by claude --stop`;
+  const ctx = user ? `${nodeCmd()} ${JSON.stringify(SELF)} turn --hook` : `${nodeCmd()} ${JSON.stringify(SELF)} turn --hook ${JSON.stringify(repo)}`;
+  const chk = user ? `${nodeCmd()} ${JSON.stringify(SELF)} __hook --by claude --stop` : `${nodeCmd()} ${JSON.stringify(SELF)} __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;