fix(cap): move the enforcement boundary to a denial tombstone, not the turn count

allowTurn() appends BEFORE the turn runs, so during granted turn N the
ledger holds N records. The hook denied at `used >= budget`, which blocked
every tool call of the FINAL granted turn: the primitive granted B turns
and the harness permitted B-1. Worse, an exhausted run therefore always
terminated through an exit-2 tool denial instead of the graceful "cap
exhausted" exit at commands/trekresearch.md - and the prose says in as
many words that exit 2 is not exit 1, so the model was pushed out through
the one exit it is told NOT to treat as a cap.

The review recommended denying at `used > budget`. Taken alone that fixes
the count and breaks the hook: once the O_EXCL claim (previous commit)
makes a breached ledger impossible, `granted > budget` can no longer fire,
and the case this hook exists for - the loop consults the gate, is denied,
and issues the tool call anyway - would be allowed. A deny branch that
cannot be reached is a dead security claim, which is the same thing S82
removed two of rather than leave standing.

So the denial itself became a record. allowTurn() appends a tombstone
{runId, exhausted: true} when it denies for budget, and the hook denies on
the tombstone. Both properties now hold at once:

  granted == budget, no tombstone  -> turn B is in flight   -> ALLOW
  tombstone present                -> the gate already said no -> DENY
  granted  >  budget               -> breached, any cause   -> DENY

A tombstone is not a turn: readLedger reports {granted, exhausted}
separately so it can never consume budget. allowTurn short-circuits on an
existing tombstone, so a hammered gate neither re-walks every slot nor
grows the ledger. The tombstone write is best effort on purpose - the
denial is already the correct answer, so a ledger that cannot take the
record must not turn a denial into a grant.

The parallel-boundary test now asserts GRANTED turns rather than raw
ledger lines, because the denied callers legitimately add tombstones.

Review finding 8eb53458ac3efec778094f9f03b09e1cc1077a09 (MINOR).
Operator decision: tombstone over the literal recommended_action.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuGhWAbWyRFBFeemfhxoVv

tests/lib/research-loop-cap.test.mjs

@@ -415,17 +415,77 @@ test('allowTurn — parallel processes at the boundary cannot exceed the budget'
         runShimAsync(['--run-id', 'r-par', '--dimension', `p${i}`, '--effort', 'high'], env),
       ),
     );
-    const granted = results.filter((r) => r.code === 0).length;
-    assert.equal(granted, 1, `exactly one of six concurrent callers may take the last slot, got ${granted}`);
+    const winners = results.filter((r) => r.code === 0).length;
+    assert.equal(winners, 1, `exactly one of six concurrent callers may take the last slot, got ${winners}`);
 
-    const lines = readFileSync(join(dir, 'trekresearch-loop-ledger.jsonl'), 'utf-8')
-      .split('\n').filter(Boolean);
-    assert.equal(lines.length, 8, `the ledger must never exceed the budget, got ${lines.length}`);
+    // Granted turns, not raw lines: the five denied callers also record
+    // exhaustion tombstones, and a tombstone is not a turn.
+    const { granted } = readLedger(join(dir, 'trekresearch-loop-ledger.jsonl'), 'r-par');
+    assert.equal(granted, 8, `granted turns must never exceed the budget, got ${granted}`);
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
+// ---- the exhaustion tombstone -----------------------------------------------
+//
+// allowTurn appends BEFORE the turn runs, so during granted turn N the ledger
+// holds N records. The hook denied at `used >= budget`, which blocked every
+// tool call of the FINAL granted turn: the primitive granted B turns and the
+// harness permitted B-1. Worse, an exhausted run then always terminated through
+// an exit-2 tool denial instead of the graceful "cap exhausted" exit at
+// commands/trekresearch.md, which is the only exit the prose teaches.
+//
+// Letting the hook allow at `used == budget` fixes the count but would leave it
+// unable to catch the one case it exists for — the loop consults the gate, is
+// denied, and issues the tool call anyway. So the denial itself becomes a
+// record: a tombstone the hook can see.
+
+test('allowTurn — denying for budget writes an exhaustion tombstone', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1', TREKRESEARCH_MAX_CONV_TURNS: '1' };
+    for (let i = 0; i < 8; i++) {
+      assert.equal(allowTurn({ runId: 'r-tomb', dimension: `d${i}`, effort: 'high' }, { env }).ok, true);
+    }
+    const ledgerPath = join(dir, 'trekresearch-loop-ledger.jsonl');
+    assert.equal(readLedger(ledgerPath, 'r-tomb').exhausted, 0, 'no tombstone before the gate has denied anything');
+
+    const denied = allowTurn({ runId: 'r-tomb', dimension: 'd0', effort: 'high' }, { env });
+    assert.equal(denied.ok, false);
+    assert.equal(denied.reason, 'budget_exhausted');
+
+    const after = readLedger(ledgerPath, 'r-tomb');
+    assert.equal(after.exhausted, 1, 'the denial must leave a record the harness gate can read');
+    assert.equal(after.granted, 8, 'a tombstone is not a granted turn and must not count as one');
+  });
+});
+
+test('allowTurn — the tombstone is written once, not once per repeated denial', () => {
+  withTmpDataDir((dir) => {
+    const env = { CLAUDE_PLUGIN_DATA: dir, VOYAGE_STORM_ENABLED: '1', TREKRESEARCH_MAX_CONV_TURNS: '1' };
+    for (let i = 0; i < 8; i++) allowTurn({ runId: 'r-once', dimension: `d${i}`, effort: 'high' }, { env });
+    for (let i = 0; i < 5; i++) allowTurn({ runId: 'r-once', dimension: 'd0', effort: 'high' }, { env });
+    const after = readLedger(join(dir, 'trekresearch-loop-ledger.jsonl'), 'r-once');
+    assert.equal(after.exhausted, 1, 'a hammered gate must not grow the ledger without bound');
+    assert.equal(after.granted, 8);
+  });
+});
+
+test('readLedger — a tombstone is reported separately and never as a granted turn', () => {
+  withTmpDataDir((dir) => {
+    const p = join(dir, 'trekresearch-loop-ledger.jsonl');
+    writeFileSync(p, [
+      JSON.stringify({ runId: 'r1', dimension: 'd1', slot: 1 }),
+      JSON.stringify({ runId: 'r1', exhausted: true }),
+      JSON.stringify({ runId: 'other', exhausted: true }),
+    ].join('\n') + '\n');
+    const l = readLedger(p, 'r1');
+    assert.equal(l.granted, 1);
+    assert.equal(l.exhausted, 1);
+    assert.equal(readLedger(p, 'other').granted, 0, 'another run’s tombstone is not a granted turn either');
+  });
+});
+
 // ---- (g) shim contract --------------------------------------------------------
 
 test('CLI shim — grants and exits 0 when enabled + high effort + budget available', () => {