Files

Behruz Nassre Esfahani 5d804dd287 fix(#3709 ): clear the context-monitor warn sentinel on PreCompact (#3808 )

* fix(#3709): clear the context-monitor warn sentinel on PreCompact

The monitor's per-session warn sentinel survived a compaction, so once the
first CRITICAL of a session had fired, `lastLevel` stayed pinned at 'critical'
for the rest of the run. The hook was already wired to PreCompact (#772), but
read the event only at the very END, and solely to pick an output envelope.

Two documented behaviours died as a result:

- "First warning always fires immediately" — the first warning of the
post-compaction cycle was debounced instead.
- "Severity escalation (WARNING -> CRITICAL) bypasses debounce" — computed as
`lastLevel === 'warning'`, which can never be true again, so every later
CRITICAL waited out the full five-tool-use debounce, exactly when an
immediate warning matters most.

`criticalRecorded` was equally sticky: a session that compacted and later truly
ran out kept a /gsd:resume-work breadcrumb (#1974) describing the earlier
near-miss rather than the exhaustion that ended the run.

Reproduced first, with the issue's own literal repro, including the detail that
the compaction consumed a debounce slot (callsSinceWarn 0 -> 1).

The reset runs BEFORE the metrics read, deliberately: a post-compaction reading
is healthy again, so the ENOENT / stale / above-threshold branches would all
exit first and never reach it. Returning early also stops the compaction from
eating a slot of the cycle it was meant to restart. The event name is now read
once through a shared `readEventName()` helper, so this reset and the #2289
output allowlist cannot drift on what counts as "no event name".

Seven rows against a real sequence (the defect is state carried ACROSS calls, so
they need their own driver — the existing helpers delete the sentinel after each
invocation). Reverting the reset turns SIX of them red; the seventh is the
non-vacuity row asserting a NON-compaction event must not clear the sentinel,
which correctly passes either way.

AC4 initially passed with and without the fix — asserting `criticalRecorded ===
true` is vacuous when the seeded stale sentinel already carries it. It now seeds
a `staleProbe` marker that can only survive if the sentinel survives, so its
absence is what proves the state was rebuilt.

hooks/dist/ is gitignored and regenerated by build:hooks, so no committed dist
copy needs syncing.

Verified: `npm run lint:ci` exit 0; acceptance criteria 1-6 driven end-to-end
against the real hook.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(#3709): reset ahead of the config gate, and pin the placement itself

Codex review of the #3709 fix, before opening the PR. Three findings, all in
this change's own new code.

1. `context_warnings: false` prevented the reset. The config early-exit sits
ABOVE where the reset was placed, so a session that disabled warnings,
compacted, then re-enabled them mid-session resurrected the stale sentinel
and the original bug with it. Config is re-read per invocation, so that
sequence is supported rather than hypothetical. The reset now runs ahead of
the config gate: clearing the sentinel is CLEANUP, not a warning — state that
must not outlive a compaction should not outlive it merely because warnings
are switched off right now. It cannot emit anything from there, so the
disabled contract is untouched.

2. Nothing pinned the "before the metrics read" placement. Every row wrote a
fresh metrics file, so the reset could have been moved below the metrics
read, the stale check, or the healthy-threshold exit with all seven rows
still green — while a REAL PreCompact, which carries no fresh metrics and
follows a recovery to healthy usage, silently kept its sentinel. Three rows
now pin it: no metrics file at all, usage recovered to healthy, and warnings
disabled. Each catches a distinct wrong placement — moving the reset below
the config check reds the third; below the metrics read reds all three.

3. The absent-sentinel row proved nothing. `assert.doesNotThrow` was vacuous
because the driver caught every child exit, so a hook that exited 1 on the
ENOENT unlink would still have passed. The driver now returns the exit code
and the row asserts it is 0.

Also corrected the `readEventName` comment: it said the event is "read once",
which is not literally true — there are two call sites. The point is one
DEFINITION of what counts as an event name, so the reset and the #2289
allowlist cannot drift; the comment now says that.

Verified: 60 rows in tests/perf-317-context-monitor-fs.test.cjs, 0 fail, with
both placement mutations driven to red and reverted.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore(#3709): backfill changeset pr number

The fragment shipped with the documented `pr: 0` placeholder, which the
changeset lint treats as always-silent, because the PR number does not exist
until the PR is opened. Backfilled to 3808 now that it does.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(#3709): a compaction clears the stale reading too, not just the state

Review round 1. Major 1 was right and it mattered: clearing only the sentinel
traded a warning that never fires for one that fires when it must not.

The statusline bridge still holds the PRE-compaction reading, and STALE_SECONDS
is 60, so for up to a minute it still reads fresh and still says the context is
exhausted. With the sentinel gone, firstWarn is true, so the next PostToolUse
emitted a spurious CONTEXT CRITICAL immediately after the compaction that FREED
the context — and flipped criticalRecorded, spawning a false context-exhaustion
breadcrumb. That is the same breadcrumb inaccuracy #3709 exists to fix, re-entered
from the other side. Reproduced before fixing, exactly as the review described.

A compaction now invalidates the warning state AND the reading that produced it.
Removing the bridge loses nothing: the statusline owns that file and rewrites it
on every render, and its absence is already the "no reading yet" state a fresh
session starts in, which exits silently.

Two things my own verification caught while fixing it:

- The first attempt did NOTHING. metricsPath was declared below the PreCompact
block, so referencing it hit the temporal dead zone, threw, and the outer
catch swallowed it into a silent exit 0. The probe still printed "silent",
which looked like success but was the old debounce. metricsPath is now
hoisted beside warnPath.

- The new Major 1 row was VACUOUS. The driver's `metrics: false` DELETES the
bridge, but the defect is a bridge that is still there and still reads fresh,
so the row passed on the ENOENT early-exit rather than on the fix. Only the
sentinel-only mutation exposed it. The driver grew a `metrics: 'keep'` mode
that leaves the stale file in place; both Major 1 rows now red under that
mutation.

Also from the review:
- Minor 1 — the compaction-abort path is now stated in the source rather than
left silent, including why a conditional reset (SessionStart source "compact")
is out of scope for this fix.
- Minor 2 — docs/context-monitor.md completed: PreCompact wiring and the early
return under How It Works, a table of all three things the reset clears, the
breadcrumb guard, the warnings-disabled interaction, and the never-block
property under Safety.
- Minor 3 — changeset trimmed from ~1,400 chars of implementation narration to
the user-visible change.
- Nit 1 — a failed unlink (Windows EPERM/EBUSY) no longer leaves the bug
silently intact: the file is neutralised in place instead, with a shape safe
for each (an empty sentinel, a timestamp-0 bridge).
- Nit 2 — reviewer-process narration removed from shipped test source. The
remaining "Codex" mentions are pre-existing and name the RUNTIME.
- Nit 3 — the debounce-slot row now asserts the observable consequence (the
first post-compaction warning fires) rather than repeating AC1's assertion.
- Nit 4 — the file docblock now lists the folded-in blocks and asks the next
contributor to extend it.

Verified: `npm run lint:ci` exit 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(#3709): the unlink-failure fallback truncates to empty, matching deletion

The fallback wrote well-formed neutral values, and neither was equivalent
to the deletion it stood in for: '{}' parses, so firstWarn was false and
the first post-compaction warning was debounced — AC2 undone on exactly
the path the fallback exists for — and '{"timestamp":0}' was never stale
(the guard is `metrics.timestamp && ...`), so the flow reached emit with
remaining === undefined and injected a literal 'Usage at undefined%'.
Truncating to '' makes JSON.parse throw on both reads: the sentinel read
keeps firstWarn true, the bridge read falls to the outer catch and exits
0 silently (review of #3808, Blocker 1).

The branch is now executed for real: an EPERM is injected into the
child's fs.unlinkSync via --require preload — method monkeypatching,
never chmod 0o000, which root bypasses under Docker/CI (Blocker 2). Both
rows proved failing-first against the neutral-value fallback. The
boundary trios at WARNING=35 / CRITICAL=25 are completed on the emit
path with 34, 26, and 24 (Major 3); 36/35/25 were already pinned.