@opengsd/gsd-core 1.12.0 → 1.14.0

package/hooks/gsd-context-monitor.js

@@ -14,6 +14,9 @@
 // Thresholds:
 //   WARNING  (remaining <= 35%): Agent should wrap up current task
 //   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+// Both fire-points are overridable per project via .planning/config.json
+// (hooks.context_warning_threshold / hooks.context_critical_threshold, #4285);
+// the values above are the defaults used when the keys are absent or unusable.
 //
 // Debounce: 5 tool uses between warnings to avoid spam
 // Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
@@ -30,20 +33,180 @@ const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
 // context warning is far cheaper than stalling the agent's work (#3911).
 const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 
-const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
-const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35% (default, see resolveThresholds)
+const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25% (default, see resolveThresholds)
 const STALE_SECONDS = 60;      // ignore metrics older than 60s
 const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+// How long after a PreCompact readings stay suspect. The watermark records the
+// compaction's START; the compaction keeps running after it, and a statusline
+// render during it stamps the PRE-compaction reading with a CURRENT timestamp
+// (Codex review of #3808, round 3) — so "newer than the watermark" alone still
+// admits it. Everything inside this window is dropped instead. The cost is
+// bounded: a healthy reading dropped here behaves identically to an accepted
+// one (it would exit above-threshold anyway). A genuine exhaustion reading
+// inside the window is SKIPPED, not queued — its warning and its #1974
+// breadcrumb both fire on the next reading after the window, so they are
+// delayed by at most this window plus the accepted skew below when a later
+// reading comes, and lost when
+// none does, i.e. when the session ends inside the window (review of #3808,
+// round 9). That loss is accepted over the alternative, which is trusting a
+// reading that may be the pre-compaction value under a fresh timestamp.
+const COMPACT_GRACE_SECONDS = 60;
+// How far AHEAD of this process's clock a watermark may be and still be
+// honored. PreCompact stamps it from the same clock as the reader, so the
+// legitimate skew is 0; this tolerance only absorbs a clock step. It is a
+// THRESHOLD, so it is named rather than inlined and carries its own boundary
+// trio (Codex review of #3808, round 4). Note it also extends the mute: a
+// watermark this far ahead pushes first recovery from +61 to +66 (measured).
+const WATERMARK_SKEW_SECONDS = 5;
+
+// Resolve the two fire-points from the project's `.planning/config.json`
+// (#4285). The constants above are the DEFAULTS; a project overrides either one
+// through `hooks.context_warning_threshold` / `hooks.context_critical_threshold`,
+// which is what keeps a tuned fire-point alive across updates — this file is in
+// the MANAGED registry, so an edit to the constants is re-staged away by the
+// next install.
+//
+// TOTAL and never-throwing: this hook must not block the tool call it rides in
+// on, so every unusable input degrades to the default instead of raising.
+// Unusable is decided by Number.isFinite, which is type-strict (the string
+// "30" and true are both rejected, unlike the global isFinite), plus the 0-100
+// domain of the remaining_percentage these are compared against.
+//
+// The PAIR is validated too, and falls back TOGETHER. `critical >= warning` has
+// no coherent reading — critical fires deeper into the window than warning —
+// and honouring one side of an inconsistent pair silently picks which of the
+// operator's two numbers to discard. This also rejects a single override that
+// contradicts the OTHER key's default (warning 20 with critical absent, i.e.
+// 25); the resulting pair is the same nonsense either way. Set-time validation
+// cannot stand in for this check: `config-set` writes one key per call, so
+// tuning both (warning first, then critical) is transiently inconsistent on
+// disk, and refusing it there would block a legitimate configuration.
+function resolveThresholds(hooks) {
+  const defaults = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
+  if (!hooks || typeof hooks !== 'object') return defaults;
+
+  const usable = (value, fallback) =>
+    (Number.isFinite(value) && value >= 0 && value <= 100) ? value : fallback;
+
+  const warning = usable(hooks.context_warning_threshold, WARNING_THRESHOLD);
+  const critical = usable(hooks.context_critical_threshold, CRITICAL_THRESHOLD);
+
+  return critical < warning ? { warning, critical } : defaults;
+}
+
+// One DEFINITION of what counts as a lifecycle event name, shared by the #3709
+// PreCompact reset and the #2289 output-envelope allowlist. Two call sites, one
+// rule — so the two cannot drift into disagreeing about what "no event name" is.
+// TOTAL, and STRICT about type: only an actual string is an event name. The old
+// inline expression threw on a truthy non-string, and hoisting it ahead of the
+// pipeline would have moved that throw ahead of the side effects #2289
+// documents as always running; a String() coercion is no better — it renders
+// ['PreCompact'] as 'PreCompact' and would run the reset off a malformed
+// payload, and a hostile toString still throws (Codex review of #3808,
+// round 3). typeof does neither: any non-string reads as "no event" — silent,
+// side effects intact — on both call sites.
+function readEventName(data) {
+  const name = data && data.hook_event_name;
+  if (typeof name === 'string') return name.trim();
+  // ABSENT vs MALFORMED are not the same event (Codex review of #3808, round 7,
+  // measured base-vs-head). A MISSING name is the documented pre-#2289 Gemini
+  // fallback: under GEMINI_API_KEY it means AfterTool and still emits. A name
+  // that is PRESENT but not a string is a malformed payload and must not
+  // inherit that fallback — at the merge-base it threw on `.trim()` after the
+  // side effects, so no envelope was ever produced, and collapsing both onto ''
+  // silently turned `42`, `{}` and `['PreCompact']` into emitting AfterTool
+  // events. Measured: base silent, head emitted, for both `42` and
+  // `['PreCompact']`. null keeps them distinguishable while staying unequal to
+  // every event name, so the PreCompact reset and the allowlist below are
+  // byte-for-byte unchanged for every well-formed payload.
+  return (name === undefined || name === null) ? '' : null;
+}
+
+// SENTINEL WRITE HARDENING (review of #3808, round 7). `warnPath` lives in
+// os.tmpdir(), which may resolve to a shared sticky directory — not guaranteed
+// per-user, and the file persists across invocations — so an object already
+// sitting there may be a planted symlink. The three routine debounce-accounting writes were bare
+// writeFileSync, which follows one and writes through to its target, while the
+// PreCompact clear and the compaction watermark in this same file already
+// refuse to. Unlink-then-O_EXCL is the watermark's own shape (the watermark
+// write itself now calls this helper — review round 10): the unlink
+// removes any existing object (regular file or link) and O_EXCL then refuses
+// to create through one, so the write can only ever land on a fresh regular
+// file this process made. Best effort by design — a lost sentinel write costs
+// only debounce accounting, which is never worth breaking the hook over, so
+// every failure is swallowed exactly as the watermark write's is.
+// NOT an atomic read-modify-write, and not claimed to be (Codex review of
+// #3808, round 7): two concurrent invocations can read the same state and race
+// through unlink/create, so one invocation's accounting can be lost — the same
+// lost-update race the bare writeFileSync already had, not a class this change
+// introduces. What a lost write leaves behind is whatever the competing writer
+// wrote, which may be a perfectly valid sentinel; it does not reliably mean
+// "defaults on the next call". Advisory debounce bookkeeping is the right place
+// to accept that.
+// The read-side twin of writeSentinel (review of #3808, round 9). Both
+// sentinel files this hook reads — the compaction watermark and the warn
+// state — must be read the same way: lstat first so a planted link, FIFO or
+// directory is refused before any open; O_NOFOLLOW so a link raced in between
+// is refused by the kernel too (0 on Windows, where lstat already carries the
+// check); a 4096-byte bound so a planted large file cannot stall a
+// synchronous read. Rounds 4 and 7 each wrote that sequence inline at their
+// own call site, which left two copies to keep in step by hand. One place
+// now. Refusal THROWS; every caller already wraps the read in a try/catch and
+// degrades to "no file", which is the same behaviour the inline copies had.
+function readSentinel(target) {
+  const st = fs.lstatSync(target);
+  if (!st.isFile() || st.size > 4096) throw new Error('not a plain sentinel');
+  const fd = fs.openSync(target, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const buf = Buffer.alloc(st.size);
+    // The RETURN VALUE, not just the call (review of #3808, round 11). A file that shrinks
+    // between the lstat above and this read — a concurrent legitimate writer truncating
+    // mid-write, not the planted-object case the rest of this function guards — leaves the tail
+    // of `buf` zero-filled, and those NULs reach JSON.parse as garbage. Every caller already
+    // treats a throw here as "no file", so refusing a short read is both safer and the same
+    // outcome the caller would reach one line later, stated on purpose rather than by accident.
+    const bytesRead = fs.readSync(fd, buf, 0, st.size, 0);
+    if (bytesRead !== st.size) throw new Error('sentinel shrank under the read');
+    return buf.toString('utf8');
+  } finally { fs.closeSync(fd); }
+}
+
+function writeSentinel(target, payload) {
+  try {
+    try {
+      fs.unlinkSync(target);
+    } catch (e) {
+      if (!e || e.code !== 'ENOENT') throw e;
+    }
+    const fd = fs.openSync(
+      target,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL
+    );
+    try {
+      // LOOP, and check progress (Codex review of round 11). A single `fs.writeSync` is
+      // permitted to write fewer bytes than it was given, and the return value was discarded —
+      // a short write left a truncated sentinel that JSON.parse rejects, silently defeating the
+      // debounce accounting or the compaction watermark this write exists to record. Node's own
+      // `writeFileSync` loops for exactly this reason; the explicit no-progress guard keeps a
+      // pathological fd from spinning. Symmetric with the bytesRead check in readSentinel.
+      const buf = Buffer.from(payload, 'utf8');
+      let written = 0;
+      while (written < buf.length) {
+        const n = fs.writeSync(fd, buf, written, buf.length - written);
+        if (!(n > 0)) throw new Error('sentinel write made no progress');
+        written += n;
+      }
+    } finally { fs.closeSync(fd); }
+  } catch (e) { /* best effort — see above */ }
+}
 
 let input = '';
-// Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
-// Windows/Git Bash, or slow Claude Code piping during large outputs),
-// exit silently instead of hanging until Claude Code kills the process
-// and reports "hook error". See #775, #1162.
-const stdinTimeout = setTimeout(() => allow(undefined), 10000);
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => input += chunk);
-process.stdin.on('end', () => {
+// Assigned by main(); the handler below clears it. Declared out here rather
+// than inside main() because the handler closes over it.
+let stdinTimeout = null;
+
+const handleStdinEnd = () => {
   clearTimeout(stdinTimeout);
   try {
     const data = JSON.parse(input);
@@ -60,29 +223,122 @@ process.stdin.on('end', () => {
       allow(undefined);
     }
 
-    // Check if context warnings are disabled via config.
+    const tmpDir = os.tmpdir();
+    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+    const watermarkPath = path.join(tmpDir, `claude-ctx-${sessionId}-compacted.json`);
+
+    // #3709: a compaction RESTARTS the context lifecycle, so neither the warn
+    // sentinel nor the pre-compaction statusline reading may survive it. Full
+    // rationale — what dies when the sentinel outlives a compaction, why the
+    // reset sits ahead of the config gate and the metrics read, and why an
+    // aborted compaction deliberately stays cleared — lives in ONE place:
+    // docs/context-monitor.md, "PreCompact reset". Constraints the code itself
+    // must keep are stated at their lines below.
+    if (readEventName(data) === 'PreCompact') {
+      // ORDERING ASSUMPTION, stated rather than enforced (review of #3808,
+      // round 9): this reset and the debounce writeSentinel(warnPath) further
+      // down are two writers to the same file, and nothing here serialises
+      // them. A debounce invocation that read the pre-compaction state and
+      // lands its write AFTER this unlink would resurrect exactly the stale
+      // sentinel this block removes. The hook relies on the host dispatching a
+      // session's hooks one at a time, which Claude Code does; the other
+      // runtimes this hook is installed for are assumed to, and that is not
+      // tested. A lock file would close it at the cost of a second file to
+      // harden on every platform; not taken here.
+      // BOTH files: with the sentinel gone but the bridge still holding the
+      // pre-compaction reading (fresh for STALE_SECONDS), the next PostToolUse
+      // would fire a spurious CRITICAL off a context the compaction just freed
+      // (review of #3709).
+      for (const stale of [warnPath, metricsPath]) {
+        try {
+          fs.unlinkSync(stale);
+        } catch (e) {
+          if (e && e.code === 'ENOENT') continue;   // already absent — that IS the reset
+          // Best-effort fallback for a held handle (Windows EPERM/EBUSY):
+          // truncate to EMPTY — the one state both readers treat exactly like
+          // deletion, because JSON.parse('') throws. A well-formed "neutral"
+          // value is NOT equivalent: '{}' debounces the first post-compaction
+          // warning, '{"timestamp":0}' is never stale (falsy guard) and emits
+          // "undefined%" (review of #3808). Never through a LINK: lstat
+          // rejects non-regular files on every platform (Windows has no
+          // effective O_NOFOLLOW — libuv defines it as 0 — and TEMP/TMP means
+          // its tmpdir is not guaranteed per-user); O_NOFOLLOW additionally
+          // closes the lstat→open substitution race where honored. Every
+          // refusal lands in this give-up arm — including a Windows runner
+          // refusing the write-open of a freshly written file outright —
+          // which is why the fallback is best-effort, never asserted-on.
+          try {
+            if (fs.lstatSync(stale).isFile()) {
+              fs.closeSync(fs.openSync(
+                stale,
+                fs.constants.O_WRONLY | fs.constants.O_TRUNC | (fs.constants.O_NOFOLLOW || 0)
+              ));
+            }
+          } catch (e2) { /* give up, never throw */ }
+        }
+      }
+
+      // COMPACTION WATERMARK (review of #3808, round 3). Deleting the bridge
+      // only NARROWS the stale-reading window: the statusline is an
+      // uncoordinated process that re-writes the bridge on every render, so a
+      // render landing between this clear and the compaction's completion
+      // re-creates the PRE-compaction reading with a CURRENT timestamp — and
+      // it would sail past STALE_SECONDS as freshly valid. The watermark makes
+      // the pre-compaction reading identifiable rather than merely absent: the
+      // metrics read drops any reading not strictly newer than it. Written
+      // through writeSentinel (review of #3808, round 10 — this block was the
+      // shape writeSentinel was lifted from in round 7 and kept its own copy):
+      // unlink-then-O_EXCL so an existing file — or a planted symlink — is
+      // never followed or overwritten in place; failure to write degrades to
+      // the old narrowing, never throws.
+      writeSentinel(watermarkPath, JSON.stringify({ at: Math.floor(Date.now() / 1000) }));
+      // allow(), not raw process.exit: #3911/ADR-3889 moved this hook onto the
+      // declared-policy exit vocabulary while this PR was in review, and the
+      // PreCompact branch is new here, so it needs the same conversion.
+      // A compaction is never blocked by this hook — ALLOW is the policy the
+      // rest of the file already declares.
+      allow(undefined);
+    }
+
+    // Check if context warnings are disabled via config, and resolve the two
+    // fire-points from the same read (#4285 — one config read, not two).
     // Collapsed existsSync+readFileSync into a single read guarded by try/catch
     // (ENOENT or parse error → use defaults, same as old "planningDir absent" branch).
     const cwd = data.cwd || process.cwd();
+    let thresholds = { warning: WARNING_THRESHOLD, critical: CRITICAL_THRESHOLD };
     try {
       const configPath = path.join(cwd, '.planning', 'config.json');
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       if (config.hooks?.context_warnings === false) {
         allow(undefined);
       }
+      // After the disable check, not before: a disabled monitor exits above and
+      // never reaches a threshold, so resolving first would only add work to the
+      // path that does nothing. allow() exits the process (it does not throw),
+      // so this line is unreachable when warnings are off.
+      thresholds = resolveThresholds(config.hooks);
     } catch (e) {
-      // Missing or unparseable config → proceed with defaults (context warnings enabled)
+      // Missing or unparseable config → proceed with defaults (context warnings
+      // enabled, thresholds at the constants above, which `thresholds` already holds)
     }
 
-    const tmpDir = os.tmpdir();
-    const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
-
     // If no metrics file, this is a subagent or fresh session -- exit silently.
     // Collapsed existsSync+readFileSync: ENOENT → exit 0 (identical to old !existsSync branch),
     // other errors rethrow to the outer catch (swallowed → exit 0, as before).
+    //
+    // Through readSentinel, like the other two (review of #3808, round 11). This read was the
+    // asymmetry left in this file: `metricsPath` is built one line away from `warnPath` and
+    // `watermarkPath` (same tmpdir, same predictable `claude-ctx-{sessionId}` shape), it is the
+    // only one of the three read on EVERY invocation, and it was the only one still reached by a
+    // bare readFileSync — so the symlink-to-FIFO stall the other two are hardened against was
+    // still reachable here, on the highest-traffic path in the file. The 4096-byte bound is
+    // ample: the statusline writes four fixed fields (`gsd-statusline.js`, ~140 bytes with a
+    // UUID session id), so no legitimate bridge approaches it. A refusal throws and lands in the
+    // rethrow below exactly as an unreadable or malformed bridge already did.
     let metricsRaw;
     try {
-      metricsRaw = fs.readFileSync(metricsPath, 'utf8');
+      metricsRaw = readSentinel(metricsPath);
     } catch (e) {
       if (e && e.code === 'ENOENT') allow(undefined);
       throw e;
@@ -90,6 +346,46 @@ process.stdin.on('end', () => {
     const metrics = JSON.parse(metricsRaw);
     const now = Math.floor(Date.now() / 1000);
 
+    // #3709 (round 3): a reading not clearly PAST the compaction is suspect,
+    // whatever its timestamp says — the statusline re-writes the bridge on
+    // every render, and a render during the compaction stamps the OLD
+    // remaining_percentage with a current time. The watermark records the
+    // compaction's START, so "newer than the watermark" alone still admits a
+    // mid-compaction render (Codex review of #3808, round 3): the grace
+    // window covers the compaction's own duration. `!(>)` rather than `<=` so
+    // a missing/zero/garbage timestamp is also dropped once a compaction has
+    // happened — an unstamped reading cannot prove it is post-compaction.
+    //
+    // The watermark itself must be SANE to count: one stamped in the future
+    // (a clock step backwards, a stray file) would otherwise drop every
+    // reading indefinitely and silently self-disable monitoring — so it is
+    // honored only when its own timestamp is not ahead of this process's
+    // clock (small skew allowed). No watermark, an unreadable one, or an
+    // insane one all degrade to the plain STALE_SECONDS behaviour below.
+    //
+    // READ HARDENING (Codex review of #3808, round 4). The WRITE side already
+    // refuses to follow or overwrite a planted object (unlink-then-O_EXCL
+    // above), but this read was a bare readFileSync — so on any write-side
+    // give-up the planted object survived and every later invocation followed
+    // it. In a shared sticky os.tmpdir() that is a mute primitive (a planted
+    // recent watermark suppresses monitoring) and a stall primitive (a symlink
+    // to a FIFO blocks this synchronous read indefinitely; measured: such a
+    // read is still running after 300ms). The same lstat + O_NOFOLLOW pair the
+    // sentinel path uses, plus a size bound, applied to the file this PR adds.
+    // Every refusal degrades to "no watermark", never throws.
+    try {
+      const watermark = JSON.parse(readSentinel(watermarkPath));
+      if (
+        watermark && typeof watermark.at === 'number'
+        && watermark.at <= now + WATERMARK_SKEW_SECONDS
+        && !(metrics.timestamp > watermark.at + COMPACT_GRACE_SECONDS)
+      ) {
+        // Same #3911/ADR-3889 conversion as the PreCompact branch above: this
+        // gate is new in this PR, so it did not exist to be migrated.
+        allow(undefined);
+      }
+    } catch (e) { /* no watermark — nothing to compare against */ }
+
     // Ignore stale metrics
     if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) {
       allow(undefined);
@@ -99,19 +395,36 @@ process.stdin.on('end', () => {
     const usedPct = metrics.used_pct;
 
     // No warning needed
-    if (remaining > WARNING_THRESHOLD) {
+    if (remaining > thresholds.warning) {
       allow(undefined);
     }
 
-    // Debounce: check if we warned recently
-    const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+    // Debounce: check if we warned recently. `warnPath` is resolved above, next to
+    // metricsPath, because the PreCompact reset needs it before this point.
     let warnData = { callsSinceWarn: 0, lastLevel: null };
     let firstWarn = true;
 
     // Collapsed existsSync+readFileSync: ENOENT or parse error → keep default warnData
     // (same as old "file absent" branch). firstWarn tracks whether we read a valid sentinel.
+    //
+    // READ HARDENING (self-found while addressing round 7; same class, same
+    // file). Hardening the writes above leaves this read as a bare
+    // readFileSync on warnPath, which is the exact asymmetry round 7 asks be
+    // removed from the write side — and the watermark's read was hardened in
+    // round 4 for this same reason, so leaving this one recreates it. It was
+    // not the LAST bare read in the file: the statusline bridge kept its own
+    // until round 11 found it. All three go through readSentinel now. The
+    // exposure is real but bounded: the writes now unlink any planted object,
+    // so only a read reaching this line BEFORE the first write of an
+    // invocation can follow one, and re-planting reopens it every invocation.
+    // Following it is a mute primitive — attacker-chosen callsSinceWarn keeps
+    // the debounce arm below taken so no warning is ever emitted — and a
+    // symlink to a FIFO stalls this synchronous read, the same two primitives
+    // measured on the watermark. Same lstat + O_NOFOLLOW + size bound; every
+    // refusal degrades to the default warnData this catch already produces,
+    // so a normal regular file behaves exactly as before.
     try {
-      warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+      warnData = JSON.parse(readSentinel(warnPath));
       firstWarn = false;
     } catch (e) {
       // Missing or corrupted sentinel → firstWarn stays true, warnData stays at defaults
@@ -119,7 +432,7 @@ process.stdin.on('end', () => {
 
     warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
 
-    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const isCritical = remaining <= thresholds.critical;
     const currentLevel = isCritical ? 'critical' : 'warning';
 
     // Emit immediately on first warning, then debounce subsequent ones
@@ -127,14 +440,14 @@ process.stdin.on('end', () => {
     const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
     if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
       // Update counter and exit without warning
-      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      writeSentinel(warnPath, JSON.stringify(warnData));
       allow(undefined);
     }
 
     // Reset debounce counter
     warnData.callsSinceWarn = 0;
     warnData.lastLevel = currentLevel;
-    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+    writeSentinel(warnPath, JSON.stringify(warnData));
 
     // Detect if GSD is active (has .planning/STATE.md in working directory)
     const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
@@ -161,7 +474,7 @@ process.stdin.on('end', () => {
         ).unref();
         warnData.criticalRecorded = true;
         // Persist the sentinel so subsequent debounce cycles don't re-fire
-        fs.writeFileSync(warnPath, JSON.stringify(warnData));
+        writeSentinel(warnPath, JSON.stringify(warnData));
       } catch { /* non-critical — don't let state recording break the hook */ }
     }
 
@@ -198,7 +511,7 @@ process.stdin.on('end', () => {
     // not enough — a missing name would still fall through to the injection path.
     // All side effects above (debounce counter, one-time critical-session
     // recording) have already run regardless of whether output is emitted.
-    const eventName = (data.hook_event_name && data.hook_event_name.trim()) || "";
+    const eventName = readEventName(data);
     // Preserve the pre-#2289 Gemini fallback: a missing event name under a
     // Gemini-dialect runtime (GEMINI_API_KEY set) still means AfterTool, so its
     // advisory output is unchanged. A missing name on any other host is silent.
@@ -209,7 +522,8 @@ process.stdin.on('end', () => {
       const output = {
         hookSpecificOutput: {
           hookEventName: eventName || "AfterTool",
-          additionalContext: message
+          additionalContext: message,
+          severity: currentLevel
         }
       };
       process.stdout.write(JSON.stringify(output));
@@ -220,4 +534,34 @@ process.stdin.on('end', () => {
     // exit(0) fail-open behavior exactly (#3911).
     crash(ON_CRASH, undefined);
   }
-});
+};
+
+// The stdin adapter is the only side-effecting statement in this file, so it is
+// the only thing that must not run on `require()`. Gating it lets a test import
+// `resolveThresholds` and drive it directly — the repo's own conclusion for a
+// seam like this (CONTEXT-INDEX, on the ROADMAP Requirements parser: a closure
+// reachable only by spawning the CLI is one "no fast-check property can do").
+// A spawn-per-case property test is not the same test: it would exercise the
+// resolver at whatever pairs survive to an observable severity, not over its
+// whole numeric domain.
+/* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
+function main() {
+  // Timeout guard: if stdin doesn't close within 10s (e.g. pipe issues on
+  // Windows/Git Bash, or slow Claude Code piping during large outputs),
+  // exit silently instead of hanging until Claude Code kills the process
+  // and reports "hook error". See #775, #1162.
+  stdinTimeout = setTimeout(() => allow(undefined), 10000);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => input += chunk);
+  process.stdin.on('end', handleStdinEnd);
+}
+
+if (require.main === module) {
+  main();
+}
+
+// Exported for the #4285 property test only. The two constants ride along so a
+// test asserts the fallback pair against the SOURCE of truth rather than
+// re-hardcoding 35/25 — a test carrying its own copy of the defaults would stay
+// green if the constants were edited.
+module.exports = { resolveThresholds, WARNING_THRESHOLD, CRITICAL_THRESHOLD };

package/hooks/gsd-cursor-subagent-start.js

@@ -62,8 +62,8 @@ const { allow } = require('./lib/hook-exit.js');
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
 // writeCursorHooksJson so the require always resolves post-install.
 const { resolveStatePath } = require('./lib/cursor-workspace.js');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch } = require('./lib/isolation-sentinel.js');
-const { REASON_CODE } = require('./lib/isolation-deny-reason.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 // #3582: gsd-core/bin/lib/*.cjs (runtime-homes.cjs, worktree-safety.cjs,
 // runtime-name-policy.cjs, capability-registry.cjs — required below, inside
 // resolveIsolationEvidence and resolveFallbackIsolation) are tsc build
@@ -491,18 +491,25 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `Refusing to allow this subagent to spawn until the runtime library is built — a guard ` +
         `that cannot verify must not answer "safe" (#3050).`,
       reasonCode: REASON_CODE.RUNTIME_BUILD_FAILED,
+      sentinelDiscarded: null,
     };
   }
 
+  // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS dispatch's
+  // actual resolved isolation — see the doc comment above.
+  // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT plan/phase
+  // than this dispatch is not applicable to it — fall through to the
+  // conservative fallback exactly as a stale sentinel would.
+  // Hoisted (readSentinel never throws) so the "present, fresh, but did not
+  // apply" case (#4594 row 15) can be reported on every deny path below
+  // instead of silently discarded.
+  const sentinel = readSentinel(root, { clock });
+  const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
+  const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
+
   let declaredIsolation;
   try {
-    // #3045 BLOCKER fix: a fresh sentinel is authoritative for THIS
-    // dispatch's actual resolved isolation — see the doc comment above.
-    // #3045 SECURITY F2: a fresh sentinel that names a DIFFERENT
-    // plan/phase than this dispatch is not applicable to it — fall through
-    // to the conservative fallback exactly as a stale sentinel would.
-    const sentinel = readSentinel(root, { clock });
-    declaredIsolation = (sentinel.present && !sentinel.stale && sentinelAppliesToDispatch(sentinel, dispatchIds))
+    declaredIsolation = (sentinel.present && !sentinel.stale && applies)
       ? sentinel.isolation
       : resolveFallbackIsolation(root, configPath);
   } catch {
@@ -513,8 +520,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `dispatch-isolation configuration ('.planning/config.json' exists under "${root}"). ` +
         `Refusing to allow this subagent to spawn without being able to verify whether ` +
         `isolation is required — a guard that cannot verify must not answer "safe" (#3050). ` +
-        `Retry once the project configuration is readable.`,
+        `Retry once the project configuration is readable.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CONFIG_UNREADABLE,
+      sentinelDiscarded,
     };
   }
 
@@ -530,8 +539,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `GSD subagent isolation guard: this project's dispatch isolation resolves to ` +
         `"harness-worktree", but the subagentStart payload for this dispatch carries no usable ` +
         `subagent_type. Refusing to allow it to spawn without being able to confirm whether it ` +
-        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).`,
+        `is a GSD executor — a guard that cannot verify must not answer "safe" (#3050).` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.NO_SUBAGENT_TYPE,
+      sentinelDiscarded,
     };
   }
 
@@ -547,8 +558,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
         `"harness-worktree", but whether "${root}" is running in an isolated Cursor worktree ` +
         `could not be determined (git did not respond). Refusing to allow subagent_type=` +
         `"${subagentType}" to spawn without being able to verify isolation — a guard that ` +
-        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.`,
+        `cannot verify must not answer "safe" (#3050). Retry once git is responsive.` +
+        (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
       reasonCode: REASON_CODE.CANNOT_DETERMINE_ISOLATION,
+      sentinelDiscarded,
     };
   }
 
@@ -560,8 +573,10 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
       `which is not an isolated Cursor worktree — it would edit the user's primary checkout ` +
       `directly, with no consent and no warning. Start an isolated session first (the ` +
       `"--worktree" CLI flag or the "/worktree" chat command; Cursor manages these worktrees ` +
-      `under "~/.cursor/worktrees/") and retry.`,
+      `under "~/.cursor/worktrees/") and retry.` +
+      (sentinelDiscarded ? describeSentinelDiscard(sentinelDiscarded) : ''),
     reasonCode: REASON_CODE.NOT_ISOLATED_WORKTREE,
+    sentinelDiscarded,
   };
 }
 
@@ -611,7 +626,12 @@ function main() {
         decision = { action: 'allow' };
       }
       if (decision.action === 'deny') {
-        const out = { permission: 'deny', user_message: decision.reason, reason_code: decision.reasonCode };
+        const out = {
+          permission: 'deny',
+          user_message: decision.reason,
+          reason_code: decision.reasonCode,
+          sentinel_discarded: decision.sentinelDiscarded ?? null,
+        };
         if (additionalContext !== null) out.additional_context = additionalContext;
         process.stdout.write(JSON.stringify(out));
         return;

package/hooks/gsd-node-runner.sh

@@ -1,4 +1,5 @@
 #!/bin/sh
+# gsd-hook-version: {{GSD_VERSION}}
 # gsd-node-runner.sh — GSD portable node resolver (#3662).
 #
 # Managed JS hook commands under --portable-hooks route through this script: