@opengsd/gsd-core 1.12.0 → 1.14.0

package/hooks/dist/lib/isolation-sentinel.js

@@ -56,6 +56,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { parseDispatchIdentity } = require('./dispatch-identity.js');
 
 // Isolation modes ADR-1239 declares (mirrors gsd-tools.cjs
 // routeDispatchIsolation / routeRecordDispatchIsolation).
@@ -223,26 +224,40 @@ function readSentinel(cwd, { clock = Date } = {}) {
 }
 
 /**
- * #3045 SECURITY F2: extract the `{plan, phase}` a specific Agent()/Task()
- * dispatch is FOR, from the one place that data is reliably embedded today —
- * the dispatch prompt/description text (`execute-phase.md`'s Agent() block
- * uses the literal shape `description="Execute plan {plan_number} of phase
- * {phase_number}"`, and the prompt body's `<objective>` repeats "Execute plan
- * {plan_number} of phase {phase_number}-{phase_name}." verbatim — the SAME
- * text the orchestrator-worktree EXECUTOR_PROMPT template and Cursor's `task`
- * field carry, since Cursor dispatches the same prompt content). There is no
- * structured per-dispatch kwarg carrying plan/phase identifiers today (#3045
- * would need a larger dispatch-protocol change to add one) — this is
- * therefore a best-effort, NOT a guaranteed, extraction: a dispatch whose
- * text doesn't match the expected shape returns `{ plan: null, phase: null }`
- * and the caller must NOT treat that as a mismatch (see
- * `sentinelAppliesToDispatch`).
+ * #3045 SECURITY F2 / #4594: extract the `{plan, phase}` a specific
+ * Agent()/Task() dispatch is FOR. Variadic — accepts any number of text
+ * sources (short description, full prompt body, etc) and delegates to
+ * `hooks/lib/dispatch-identity.js::parseDispatchIdentity`, the one canonical
+ * owner of both the `[gsd:dispatch phase="…" plan="…"]` marker format and its
+ * prose fallback (see `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md`).
+ *
+ * MARKER-FIRST CONTRACT: producers embed a structured marker carrying the
+ * exact shell values the sentinel itself records (`$PHASE_NUMBER`,
+ * `$plan_id`), so producer and consumer agree by construction, independent
+ * of how the prose reads or whether a model paraphrases the dispatch
+ * sentence. Only when no marker is found anywhere in the supplied texts does
+ * this fall back to scanning for the prose frame "execute plan <token> of
+ * phase <PHASE TOKEN>".
+ *
+ * The prose fallback is now CORRECT-OR-ABSENT rather than possibly-wrong:
+ * the phase token is bounded by the same grammar `src/phase-id.cts` owns
+ * (ADR-2121), so a directory-name slug or trailing punctuation can no longer
+ * leak into the phase value, and the prose plan token is never reported at
+ * all (it lives in a different namespace than the sentinel's phase-prefixed,
+ * slugged `plan_id` — reporting it was the #4594 false-mismatch bug).
+ *
+ * This is still a best-effort, NOT a guaranteed, extraction: a dispatch that
+ * carries neither a marker nor a matching prose frame in ANY supplied text
+ * returns `{ plan: null, phase: null }`, and the caller MUST NEVER treat
+ * that as a mismatch — see `sentinelAppliesToDispatch`, whose whole
+ * contract depends on "missing" and "wrong" being distinguishable.
+ *
+ * Returns only the two-field `{ plan, phase }` shape existing callers
+ * depend on — `parseDispatchIdentity`'s `source` field is discarded here.
  */
-function extractDispatchIdentifiers(text) {
-  if (typeof text !== 'string' || text.length === 0) return { plan: null, phase: null };
-  const m = /execute\s+plan\s+(\S+)\s+of\s+phase\s+(\S+)/i.exec(text);
-  if (!m) return { plan: null, phase: null };
-  return { plan: m[1], phase: m[2] };
+function extractDispatchIdentifiers(...texts) {
+  const { phase, plan } = parseDispatchIdentity(...texts);
+  return { plan, phase };
 }
 
 /**
@@ -265,6 +280,29 @@ function sentinelAppliesToDispatch(sentinel, dispatchIds) {
   return true;
 }
 
+/**
+ * #4594 F3: build the structured "a fresh sentinel was present but did not
+ * apply to this dispatch" descriptor, mirroring the exact comparison
+ * `sentinelAppliesToDispatch` performs. Returns `null` when the sentinel is
+ * absent, stale, malformed, or DOES apply — i.e. exactly when there is
+ * nothing to report as discarded. Otherwise returns the nested
+ * `{ sentinel: {phase, plan}, dispatch: {phase, plan} }` shape, reusing the
+ * `{phase, plan}` pair already flowing through this module end to end rather
+ * than renaming its fields into an ad hoc `sentinelPhase`/`dispatchPlan` bag
+ * (previously rebuilt identically at two call sites in the guard hooks).
+ */
+function buildSentinelDiscard(sentinel, dispatchIds) {
+  if (!sentinel || !sentinel.present || sentinel.stale) return null;
+  if (sentinelAppliesToDispatch(sentinel, dispatchIds)) return null;
+  return {
+    sentinel: { phase: sentinel.phase ?? null, plan: sentinel.plan ?? null },
+    dispatch: {
+      phase: dispatchIds ? (dispatchIds.phase ?? null) : null,
+      plan: dispatchIds ? (dispatchIds.plan ?? null) : null,
+    },
+  };
+}
+
 module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
@@ -274,4 +312,5 @@ module.exports = {
   readSentinel,
   extractDispatchIdentifiers,
   sentinelAppliesToDispatch,
+  buildSentinelDiscard,
 };

package/hooks/dist/managed-hooks-registry.cjs

@@ -36,6 +36,7 @@ const MANAGED_HOOKS = [
   'gsd-prompt-guard.js',
   'gsd-read-guard.js',
   'gsd-read-injection-scanner.js',
+  'gsd-secret-read-guard.js',
   'gsd-session-state.sh',
   'gsd-statusline.js',
   'gsd-update-banner.js',

package/hooks/gsd-agent-isolation-guard.js

@@ -63,8 +63,8 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-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');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
 
 // Required at module top, alongside the other ./lib requires — NOT behind
@@ -385,16 +385,20 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
     projectExists = false;
   }
   if (!projectExists) {
-    return { gsdProject: false, isolation: null, harnessFlag: null, error: null };
+    return { gsdProject: false, isolation: null, harnessFlag: null, error: null, sentinelDiscarded: null };
   }
 
   const sentinel = readSentinel(cwd, { clock });
-  if (sentinel.present && !sentinel.stale && sentinelAppliesToDispatch(sentinel, dispatchIds)) {
+  // Hoisted so the "sentinel was present/fresh but did not apply" case below
+  // (#4594 row 15 — Postel's-Law finding) can distinguish itself from
+  // "absent"/"stale" without re-deriving applicability.
+  const applies = sentinelAppliesToDispatch(sentinel, dispatchIds);
+  if (sentinel.present && !sentinel.stale && applies) {
     if (sentinel.isolation !== 'harness-worktree') {
-      return { gsdProject: true, isolation: sentinel.isolation, harnessFlag: null, error: null };
+      return { gsdProject: true, isolation: sentinel.isolation, harnessFlag: null, error: null, sentinelDiscarded: null };
     }
     if (sentinel.harnessFlag) {
-      return { gsdProject: true, isolation: 'harness-worktree', harnessFlag: sentinel.harnessFlag, error: null };
+      return { gsdProject: true, isolation: 'harness-worktree', harnessFlag: sentinel.harnessFlag, error: null, sentinelDiscarded: null };
     }
     // #3045 BLOCKER 2 fix: the sentinel already PROVED this dispatch requires
     // isolation (it resolved harness-worktree) but carries no usable flag —
@@ -423,6 +427,7 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
         'dispatch-isolation sentinel resolved "harness-worktree" but recorded no harness_flag — ' +
         'cannot verify what parameter the dispatch must carry.'
       ),
+      sentinelDiscarded: null,
     };
   }
 
@@ -430,11 +435,19 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
   // conservative fallback (#3045 finding — must still cover fail-closed case
   // (a): a project that opted out of worktrees entirely via
   // workflow.use_worktrees).
+  //
+  // #4594 row 15: a PRESENT, FRESH sentinel that simply does not apply to
+  // THIS dispatch (identifiers disagree) is a distinct case from "absent" or
+  // "stale" — record what was discarded so evaluateDispatch can name it in a
+  // block reason instead of silently falling through to a registry-resolution
+  // message that never mentions the sentinel existed.
+  const sentinelDiscarded = buildSentinelDiscard(sentinel, dispatchIds);
+
   try {
     const { isolation, harnessFlag } = resolveRegistryIsolation(cwd, configPath);
-    return { gsdProject: true, isolation, harnessFlag, error: null };
+    return { gsdProject: true, isolation, harnessFlag, error: null, sentinelDiscarded };
   } catch (err) {
-    return { gsdProject: true, isolation: null, harnessFlag: null, error: err };
+    return { gsdProject: true, isolation: null, harnessFlag: null, error: err, sentinelDiscarded };
   }
 }
 
@@ -464,10 +477,16 @@ function evaluateDispatch(data, { clock = Date } = {}) {
   }
 
   const cwd = data.cwd || process.cwd();
-  // #3045 SECURITY F2: best-effort plan/phase extraction from this
-  // dispatch's own description text, so a fresh sentinel that disagrees
-  // with THIS dispatch is treated as inapplicable rather than trusted.
-  const dispatchIds = extractDispatchIdentifiers(toolInput.description);
+  // #3045 SECURITY F2 / #4594: best-effort plan/phase extraction from this
+  // dispatch's own text, so a fresh sentinel that disagrees with THIS
+  // dispatch is treated as inapplicable rather than trusted. PROMPT FIRST:
+  // `description` is short, model-authored free text that only carries usable
+  // identity when the model happens to reproduce the dispatch template
+  // verbatim, while the canonical `[gsd:dispatch phase="…" plan="…"]` marker
+  // (or, failing that, the prose fallback) lives in the prompt body itself —
+  // `description` is kept only as a fallback for a marker/prose match that
+  // exists solely in it.
+  const dispatchIds = extractDispatchIdentifiers(toolInput.prompt, toolInput.description);
   const state = resolveIsolationState(cwd, { clock, dispatchIds });
 
   if (!state.gsdProject) return { action: 'allow' };
@@ -493,7 +512,8 @@ function evaluateDispatch(data, { clock = Date } = {}) {
         `required — a guard that cannot verify must not answer "safe" (#3050). Retry once the ` +
         `project configuration is readable.`;
     const reasonCode = isBuildFailure ? REASON_CODE.RUNTIME_BUILD_FAILED : REASON_CODE.CONFIG_UNREADABLE;
-    return { action: 'block', reason, reasonCode };
+    const fullReason = state.sentinelDiscarded ? reason + describeSentinelDiscard(state.sentinelDiscarded) : reason;
+    return { action: 'block', reason: fullReason, reasonCode, sentinelDiscarded: state.sentinelDiscarded };
   }
 
   if (state.isolation !== 'harness-worktree') return { action: 'allow' };
@@ -503,13 +523,14 @@ function evaluateDispatch(data, { clock = Date } = {}) {
 
   if (toolInput[parsed.param] === parsed.value) return { action: 'allow' };
 
-  const reason =
+  let reason =
     `Agent isolation guard: this project's dispatch isolation resolves to "harness-worktree", ` +
     `but the Agent() dispatch for subagent_type="${subagentType}" is missing ` +
     `${parsed.param}="${parsed.value}". Add ${parsed.param}="${parsed.value}" to the Agent() ` +
     `call so the executor runs in an isolated worktree instead of the primary checkout ` +
     `(gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md).`;
-  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING };
+  if (state.sentinelDiscarded) reason += describeSentinelDiscard(state.sentinelDiscarded);
+  return { action: 'block', reason, reasonCode: REASON_CODE.HARNESS_FLAG_MISSING, sentinelDiscarded: state.sentinelDiscarded };
 }
 
 /* istanbul ignore next -- stdin adapter, exercised via spawnSync in tests */
@@ -524,7 +545,12 @@ function main() {
       const data = JSON.parse(input);
       const decision = evaluateDispatch(data);
       if (decision.action === 'block') {
-        const out = { decision: 'block', reason: decision.reason, reason_code: decision.reasonCode };
+        const out = {
+          decision: 'block',
+          reason: decision.reason,
+          reason_code: decision.reasonCode,
+          sentinel_discarded: decision.sentinelDiscarded ?? null,
+        };
         // Kimi feeds stderr (not stdout) back to the model on exit 2.
         deny(out, decision.reason);
       }

package/hooks/gsd-check-update-worker.js

@@ -156,5 +156,22 @@ const result = {
 };
 
 if (cacheFile) {
-  try { fs.writeFileSync(cacheFile, JSON.stringify(result)); } catch (e) {}
-}
+  // #4091: the cache file is shared per-PACKAGE across every runtime's worker
+  // (#607/#1421), so concurrent statusline/banner readers parse it while this
+  // worker writes it. A direct writeFileSync truncates before writing — a
+  // reader landing mid-write sees a torn/empty record (its JSON.parse catch
+  // swallows it, so the symptom is an intermittently blank update segment).
+  // Publish atomically instead: stage under a unique same-directory temp
+  // (same filesystem, so rename(2) is atomic — readers see the old or the new
+  // record, never a partial one), then renameSync into place. Failure policy
+  // is unchanged (#3582 degrade): any error is swallowed and the temp, if
+  // left behind, is best-effort removed.
+  const tmp = cacheFile + '.tmp-' + process.pid;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(result));
+    fs.renameSync(tmp, cacheFile);
+  } catch (e) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch (e2) {}
+  }}