@opengsd/gsd-core 1.13.0 → 1.14.0

package/hooks/dist/gsd-secret-read-guard.js

@@ -26,12 +26,24 @@
 //   .env, .secrets, and .env.<suffix> — EXCEPT .env.example / .env.sample /
 //   .env.template / .env.dist, which are the non-secret templates GSD's own
 //   phase prompt tells executors to read.
-//   Stated cost: this is narrower than the retired `Read(.env.*)` rule — a
-//   real secret stored in `.env.example` is not protected.
+//   Stated cost (#4580): the exemption matches the token's FINAL EXTENSION,
+//   not the whole name, so the trusted set is `.env.<anything>.example` /
+//   `.sample` / `.template` / `.dist` — an unbounded family, not four fixed
+//   names. A real secret named `.env.prod-real-secrets.example` is NOT
+//   protected, and renaming any secret to end in one of those four
+//   extensions bypasses the guard across Read, Grep and Bash alike. This is
+//   the deliberate cost of #4580, which fixed the prior whole-name
+//   comparison wrongly refusing committed, secret-free templates like
+//   `.env.local.example`.
 //   A token containing `:` is also tested on the part after its LAST `:`,
 //   so `git show HEAD:.env`, `origin/main:config/.env` and `C:\proj\.env`
-//   are caught without git-specific parsing. No whitespace trimming: the
-//   commit message `fix: .env parsing` yields ` .env parsing`, not a name.
+//   are caught without git-specific parsing. Leading/interior whitespace is
+//   still NOT trimmed: the commit message `fix: .env parsing` yields
+//   ` .env parsing`, which is prose, not a name. TRAILING dots and spaces ARE
+//   stripped from the basename before classification (`.env.`, `.env..`,
+//   `.env `, `.env. ` all normalize to `.env`), because Win32 strips trailing
+//   dots and spaces from each path component, so these are aliases for the
+//   same on-disk file, not distinct names.
 //
 // Bash analysis is a two-pass token scan, not a shell:
 //   pass 1 tokenizes with quote state, comments, redirect operators (with fd
@@ -86,6 +98,7 @@
 'use strict';
 
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
+const { finalExtension, normalizeWindowsBasename, lastSegment } = require('./lib/filename-classification.js');
 
 // Fail open on a hook-internal error (see header). Declared ONCE so the
 // outer catch states its policy explicitly (#3911).
@@ -148,21 +161,18 @@ const GLOB_PROBES = [
 // ---------------------------------------------------------------------------
 
 function isSecretBasename(name) {
-  if (name === '.env' || name === '.secrets') return true;
-  if (name.startsWith('.env.')) {
-    const suffix = name.slice('.env.'.length);
-    return suffix !== '' && !NON_SECRET_ENV_SUFFIXES.has(suffix.toLowerCase());
+  // Win32 strips trailing dots/spaces per path component, so `.env.`,
+  // `.env ` etc. resolve to the real `.env` on Windows — normalize FIRST so
+  // those aliases can't bypass classification.
+  const n = normalizeWindowsBasename(name);
+  if (n === '.env' || n === '.secrets') return true;
+  if (n.startsWith('.env.')) {
+    const suffix = n.slice('.env.'.length);
+    return suffix !== '' && !NON_SECRET_ENV_SUFFIXES.has(finalExtension(suffix).toLowerCase());
   }
   return false;
 }
 
-// Last `/`- or `\`-separated segment, ignoring trailing separators.
-function lastSegment(tok) {
-  const s = tok.replace(/[\\/]+$/, '');
-  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
-  return i === -1 ? s : s.slice(i + 1);
-}
-
 // True when the token's basename — or the basename of the part after its
 // last `:` (git `<ref>:<path>`, Windows drive) — is a secret name. Folded to
 // lower case once at the top so `.ENV` / `.Secrets` match on the
@@ -247,7 +257,19 @@ function globAltSelectsSecret(alt) {
   if (/^[*?]+$/.test(alt)) return false; // pure wildcard: equivalent to no glob
   const wild = alt.search(/[*?[]/);
   const lit = wild === -1 ? alt : alt.slice(0, wild);
-  if (lit.startsWith('.env.')) return true;
+  // #4580: when there is no wildcard, `alt` (== `lit`) is a WHOLE literal
+  // filename, so classify it exactly the same way Read/Bash do (by its
+  // FINAL extension, via isSecretBasename) rather than by a `.env.`-prefix
+  // heuristic — that heuristic mis-blocked multi-dot templates like
+  // `.env.local.example`. When a wildcard IS present, `lit` is only a
+  // PARTIAL literal prefix (`.env.local.exam*` can still select
+  // `.env.local`), which cannot be classified exactly, so the original
+  // conservative prefix rule stays.
+  if (wild === -1) {
+    if (isSecretBasename(lit)) return true;
+  } else if (lit.startsWith('.env.')) {
+    return true;
+  }
   if (lit !== '' && ('.env.'.startsWith(lit) || '.secrets'.startsWith(lit))) return true;
   let re;
   try {
@@ -260,10 +282,14 @@ function globAltSelectsSecret(alt) {
 
 // Returns null (allowed), 'secret-read', or 'glob-too-complex'.
 function classifyGrepGlob(glob) {
-  const segIdx = glob.replace(/\/+$/, '').lastIndexOf('/');
+  // Segment via the SAME `lastSegment` helper Read/Bash use (namesSecret),
+  // rather than a hand-rolled forward-slash-only split — the two used to
+  // diverge on a backslash-bearing glob (`config\.env`), which `lastSegment`
+  // reduces to `.env` but a `/`-only split left untouched, letting it escape
+  // this arm's predicate while Read/Bash still blocked it.
   // Case-fold the last segment (GLOB_PROBES are lower case) so `.ENV*` and
   // `*.ENV` select the secret namespace on case-insensitive filesystems.
-  const segment = (segIdx === -1 ? glob : glob.slice(segIdx + 1)).toLowerCase();
+  const segment = lastSegment(glob).toLowerCase();
   const alts = expandBraces(segment);
   if (alts === null) return 'glob-too-complex';
   return alts.some(globAltSelectsSecret) ? 'secret-read' : null;

package/hooks/dist/gsd-statusline.js

@@ -449,13 +449,17 @@ function contextTokenSuffix(currentUsage) {
 // --- Compact state format (opt-in) ---------------------------------------------
 
 /**
- * Collapse GSD's free-text status (often a multi-sentence narrative) to a
- * single keyword, built on the canonical normalizer (#2162 approval
- * condition): normalizeStateStatus() in state-document.cjs owns the status
- * vocabulary (discussing / planning / executing / verifying / completed /
- * paused) so the two can't drift. "paused" — the canonical stuck state — is
- * uppercased to PAUSED, the one state worth shouting about. Statuses the
- * normalizer passes through unrecognized fall back to their first word,
+ * Collapse GSD's status value to a single keyword, built on the canonical
+ * normalizer (#2162 approval condition): normalizeStateStatus() in
+ * state-document.cjs owns the status vocabulary (discussing / planning /
+ * executing / verifying / completed / paused) so the two can't drift.
+ * #4186: the normalizer recognizes the DECLARED vocabulary by anchored
+ * whole-field match — vocabulary values (the state writer persists tokens)
+ * collapse to their keyword; free-text narratives are no longer
+ * keyword-guessed from substrings (a `.planning/` mention in non-English
+ * prose used to render `planning`), and pass through unrecognized to the
+ * first-word fallback below. "paused" — the canonical stuck state — is
+ * uppercased to PAUSED, the one state worth shouting about. The fallback is
  * capped at 16 chars so a rogue STATE.md can't blow up the line.
  * Returns null for empty input.
  */

package/hooks/dist/gsd-validate-commit.sh

@@ -69,7 +69,11 @@ if [ -f .planning/config.json ]; then
     echo "gsd-validate-commit.sh: could not read .planning/config.json (opt-in check) — validator disabled for this call. $(cat "$ENABLED_ERR")" >&2
     exit 0
   fi
-  ENABLED=$(printf '%s\n' "$CONFIG_OUT" | head -1)
+  # Pure parameter expansion, not `printf ... | head -1`: same SIGPIPE race
+  # class as the SUBJECT extraction below (`echo "$MSG" | head -1`) — CONFIG_OUT
+  # is multi-line whenever extra commit types are configured, and `head -1`
+  # closing early can SIGPIPE `printf` under `set -euo pipefail`.
+  ENABLED="${CONFIG_OUT%%$'\n'*}"
   if [ "$ENABLED" != "1" ]; then exit 0; fi
   # Remaining lines (if any) are the sanitized, deduped configured commit
   # types beyond the 10 built-ins (#3811). Read into a bash-3.2-safe array —
@@ -214,7 +218,24 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       # the message — the window a guard must use when the token it scans for
       # is also legal English inside a commit message, but may legally appear
       # on EITHER side of the message on the command line.
-      MSG_SUFFIX="${CMD#*"$MSG_MATCH"}"
+      # Indexed, not searched (#4492). `${CMD#*"$MSG_MATCH"}` is quadratic in
+      # the message: bash walks every prefix length and compares the whole
+      # matched literal at each one, and MSG_MATCH is BASH_REMATCH[0] — the
+      # entire `-m "..."` — so the cost grows with the thing being scanned.
+      # Measured on the path EVERY commit takes (conforming and non-conforming
+      # cost the same): 10.0 s at a 64 KB message, 22.0 s at 96 KB, 30.2 s at
+      # 112 KB. Sizes stop there deliberately — a single argument above Linux's
+      # MAX_ARG_STRLEN (131072 on a 4 KB-page kernel) never reaches this code
+      # at all, because execve fails and the hook fails open, so a larger
+      # "measurement" would be timing the wrong thing.
+      #
+      # MSG_PREFIX above has already located the match, so the suffix is
+      # arithmetic rather than a search: skip the prefix and the match. This
+      # removes the quadratic SEARCH; the expansion still counts characters and
+      # materialises a substring, so it is linear in the command, not O(1).
+      # Same first-occurrence assumption both expansions here always made —
+      # MSG_MATCH is a literal substring of CMD by construction.
+      MSG_SUFFIX="${CMD:$(( ${#MSG_PREFIX} + ${#MSG_MATCH} ))}"
       # LINE CONTINUATIONS ARE NOT SEPARATORS (review of #3816, rounds 8 and 9).
       # `git commit \` newline `  -m "$(cat <<'EOF' …` is an ordinary way to
       # spread an invocation over lines, and every guard below reads a newline in
@@ -521,9 +542,18 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       SUBJECT=$(GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" MSG="$MSG" node -e "
         const {resolveCommitSubject}=require(process.env.GIT_CMD_LIB);
         process.stdout.write(resolveCommitSubject(process.env.MSG));
-      " 2>/dev/null) || SUBJECT=$(echo "$MSG" | head -1)
+      " 2>/dev/null) || SUBJECT="${MSG%%$'\n'*}"
     else
-      SUBJECT=$(echo "$MSG" | head -1)
+      # Pure parameter expansion, not `echo "$MSG" | head -1`: that pipeline
+      # raced a SIGPIPE under `set -euo pipefail` whenever $MSG had a body
+      # (the common case) — `head -1` can close its read end as soon as it
+      # has the first line, and if `echo`'s write lands after that close,
+      # `echo` dies with signal 13 (exit 141), which is NOT suppressed by
+      # `set -e` and aborted the whole hook intermittently (observed in
+      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). Zero
+      # subprocesses here means zero pipe/race surface. Equivalent to
+      # `head -1` for single-line, multi-line, and trailing-newline input.
+      SUBJECT="${MSG%%$'\n'*}"
     fi
     # Single source of truth for the accepted commit-type list (#3811): the
     # 10 built-ins plus whatever passed the safe-token filter above. Both the

package/hooks/dist/gsd-worktree-path-guard.js

@@ -163,17 +163,37 @@ process.stdin.on('end', () => {
     // returns a path containing .git/worktrees/ as a component.
     // In the main repo or a submodule it returns .git (or a path without /worktrees/).
     // This approach works even when cwd is a subdirectory of the worktree.
-    const gitDirResult = git(['rev-parse', '--git-dir'], cwd);
+    // Combined into one spawn — git rev-parse accepts multiple query flags in
+    // one invocation and prints one line of output per flag, in the exact
+    // order given, reducing this guard's worst-case subprocess count under
+    // CI/load contention (three spawns collapse into one). `--abbrev-ref HEAD`
+    // is used instead of `symbolic-ref --short HEAD` because it is combinable
+    // (a single `rev-parse` call) and behaviorally equivalent for this guard's
+    // branch-acceptance check, including on detached HEAD: `--abbrev-ref`
+    // returns the literal string `HEAD` there (exit 0), which the acceptance
+    // regex below also rejects — the same guard outcome as symbolic-ref's
+    // exit-128/empty-stdout failure. Do not change any timeout value as part
+    // of this change, only the spawn count.
+    const combinedResult = git(['rev-parse', '--git-dir', '--abbrev-ref', 'HEAD', '--show-toplevel'], cwd);
     // #3911: a timeout/spawn-failure result is indistinguishable from a clean
     // "not a git repo" answer by status/stdout alone — reportIfUndetermined
     // is a no-op on a genuine negative and only fires the diagnostic when the
     // probe itself could not run. The allow() below is UNCHANGED either way.
-    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --git-dir', gitDirResult);
-    if (gitDirResult.status !== 0 || !gitDirResult.stdout) {
+    reportIfUndetermined(
+      'gsd-worktree-path-guard',
+      'git rev-parse --git-dir --abbrev-ref HEAD --show-toplevel',
+      combinedResult
+    );
+    if (combinedResult.status !== 0 || !combinedResult.stdout) {
       allow(undefined); // not a git repo — pass through
     }
 
-    const gitDir = gitDirResult.stdout.trim();
+    const combinedLines = combinedResult.stdout.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
+    if (combinedLines.length < 3) {
+      allow(undefined); // malformed/short output — can't determine root, fail open
+    }
+    const [gitDir, branch, wtTopRaw] = combinedLines;
+
     // A linked worktree's --git-dir contains .git/worktrees/ as a path component
     const isLinkedWorktree = /[/\\]\.git[/\\]worktrees[/\\]/.test(gitDir);
     if (!isLinkedWorktree) {
@@ -186,23 +206,14 @@ process.stdin.on('end', () => {
     // created linked worktree (plain non-GSD work, e.g. Claude Code plan-mode) is
     // on the user's own branch, so the guard must be a no-op there. Detached HEAD
     // / error → not GSD-managed → no-op.
-    const branchResult = git(['symbolic-ref', '--short', 'HEAD'], cwd);
-    reportIfUndetermined('gsd-worktree-path-guard', 'git symbolic-ref --short HEAD', branchResult);
-    const branch = branchResult.status === 0 && branchResult.stdout ? branchResult.stdout.trim() : '';
     // #3021: accept worktree-wf_<runid>-<n> branches (Workflow backend's naming).
     if (!/^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/.test(branch)) {
       allow(undefined); // not a GSD-managed executor worktree — no-op
     }
 
-    // Get the raw --show-toplevel output for the worktree (cwd).
+    // wtTopRaw: the raw --show-toplevel output for the worktree (cwd).
     // We keep it raw (not path.resolve'd) to compare directly with the
     // file's toplevel — same git binary, same format, no normalization needed.
-    const wtTopResult = git(['rev-parse', '--show-toplevel'], cwd);
-    reportIfUndetermined('gsd-worktree-path-guard', 'git rev-parse --show-toplevel (worktree cwd)', wtTopResult);
-    if (wtTopResult.status !== 0 || !wtTopResult.stdout) {
-      allow(undefined); // can't determine root — fail open
-    }
-    const wtTopRaw = wtTopResult.stdout.trim();
 
     // #2595 (review Major 3): read the field TYPED. `?.file_path || ''` let a
     // non-string through — `[]` and `{}` are truthy, so they survived the

package/hooks/dist/gsd-write-guard.js

@@ -105,10 +105,37 @@ const FLOOR_LINES = 40;
 // default to, a differently-cased path is the SAME real file — a Write to
 // '.planning/roadmap.md' clobbers ROADMAP.md while a case-sensitive match
 // waves it through.
+// #4455: workstream-scoped (and optionally project-scoped) variants —
+// planningDir(cwd) (src/planning-workspace.cts) resolves to
+// `.planning/[<project>/]workstreams/<ws>/...` whenever GSD_WORKSTREAM is
+// set. Before this, none of these three root-only patterns matched a
+// workstream-scoped target at all, so the ENTIRE guard (not just the
+// sentinel step — the shrink-ratio check too) silently never engaged for a
+// workstream-scoped ROADMAP.md/STATE.md/milestone-archive Write: exactly
+// the catastrophic-shrink scenario this file exists to stop, unguarded
+// under an active workstream. consumeSentinelFor's own `.planning`
+// derivation below is unaffected by this addition — it locates the single
+// outer `.planning` segment regardless of what's nested inside it, which is
+// also where the workflow's sentinel `printf` already writes, so no change
+// was needed there.
+//
+// Same gap exists one level up: planningDir(cwd) ALSO resolves to
+// `.planning/<project>/...` when GSD_PROJECT is set with NO GSD_WORKSTREAM
+// (project-only mode — the two env vars are independent; see planningDir's
+// own body). None of the patterns above cover that shape either. Found
+// during #4455's own review pass (same root cause, one more path variant)
+// — fixed in the same change rather than deferred, since it is the
+// identical defect class this PR already exists to close.
 const CURATED_PATTERNS = [
   /(?:^|\/)\.planning\/ROADMAP\.md$/i,
   /(?:^|\/)\.planning\/STATE\.md$/i,
   /(?:^|\/)\.planning\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/(?:[^/]+\/)?workstreams\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/ROADMAP\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/STATE\.md$/i,
+  /(?:^|\/)\.planning\/[^/]+\/milestones\/[^/]+-ROADMAP\.md$/i,
 ];
 
 // Count logical lines, ignoring a single trailing newline so that
@@ -156,7 +183,25 @@ function consumeSentinelFor(filePath, normalized) {
     // Path-bound: the token names exactly one file, resolved against the
     // .planning/ dir's parent (repo root) — same case-insensitive stance as
     // the curated match itself.
-    const namedNorm = path.resolve(path.join(planningDir, '..'), token).replace(/\\/g, '/').toLowerCase();
+    let namedPath = path.resolve(path.join(planningDir, '..'), token);
+    // Symmetry with the caller's own resolution (#4455 CI finding, macOS
+    // full-test shard): `filePath`/`normalized` were already realpath-resolved
+    // before this function was called (round 9 Minor 1's symlink-before-match
+    // fix), but `token` — typically an already-absolute path composed by the
+    // workflow's own init.* fields — was compared WITHOUT that same
+    // resolution. Wherever cwd sits under a symlink (macOS's /var ->
+    // /private/var is the common case, since that's exactly what os.tmpdir()
+    // resolves through, but any symlinked project/worktree checkout hits the
+    // same asymmetry), the token names the lexical path while `normalized`
+    // names the realpath — a validly-armed sentinel then never matches, and a
+    // legitimate milestone-reset Write stays incorrectly blocked. The named
+    // file is already known to exist (the caller only reaches this function
+    // after successfully reading it), so realpath is expected to succeed;
+    // keep the lexical path on failure, matching the caller's own fallback.
+    try {
+      namedPath = fs.realpathSync(namedPath);
+    } catch { /* keep the lexical path */ }
+    const namedNorm = namedPath.replace(/\\/g, '/').toLowerCase();
     if (namedNorm !== normalized.toLowerCase()) {
       return false; // armed for a different file — leave it for that write
     }

package/hooks/dist/lib/dispatch-identity.js

@@ -0,0 +1,187 @@
+'use strict';
+// hooks/lib/dispatch-identity.js — the ONE canonical owner of the
+// `[gsd:dispatch phase="…" plan="…"]` marker format and its prose fallback
+// (#4594, epic #4630 Phase 1). See
+// `.gsd/phase/fix-4594-dispatch-identity-seam/40-design.md` for the full
+// rationale (behavior table, negative space, rejected alternatives).
+//
+// COLD-LOAD CONSTRAINT (load-bearing, not a style choice): this module MUST
+// require NOTHING — no `fs`, no `path`, and above all nothing under
+// `gsd-core/bin/lib/` or `ensure-runtime-build`. The guard hooks that consume
+// this module must load on a raw plugin-marketplace install where the
+// compiled lib is absent and the self-healing build seam has not run — a
+// hook that dies at module load is worse than one carrying a mirror. See
+// `tests/dispatch-identity.test.cjs`'s "cold tree load" test, which asserts
+// this by monkeypatching `Module._load` to throw on exactly those paths.
+
+// DISPATCH_PHASE_TOKEN_SOURCE is a DELIBERATE MIRROR of
+// `CASE_FLEXIBLE_PHASE_NUMBER_TOKEN_SOURCE` in `src/phase-id.cts`
+// (ADR-2121 owns the phase-token grammar; `gsd-core/bin/lib/phase-id.cjs` is
+// its compiled form). It cannot be an `require()`-based import: importing the
+// compiled lib here would violate the cold-load constraint above (either a
+// direct dependency on `gsd-core/bin/lib/` or a forced self-heal via
+// `ensure-runtime-build`), which is exactly the failure mode this module
+// exists to avoid for the guard hooks that consume it.
+//
+// Because this is a hand-copied mirror and not a shared reference, a
+// hand-edited grammar change on one side that is not mirrored on the other
+// does NOT fail loudly — both sides remain independently valid regex
+// sources, so the failure mode is a silent, invisible non-match (a dispatch
+// whose phase token the two owners now parse differently), never a thrown
+// error. `tests/dispatch-identity.test.cjs`'s "templates: prose token source
+// matches the case-flexible phase-id grammar" test pins this string equal to
+// the compiled source at test time specifically to turn that silent drift
+// into a loud, in-CI failure.
+const DISPATCH_PHASE_TOKEN_SOURCE = '\\d+[A-Za-z]?(?:\\.\\d+)*';
+
+// Bounded marker grammar: `[gsd:dispatch key="value" key2="value2"]`.
+// - Key names bounded to {1,31} — no key we emit or expect is anywhere near
+//   that long; this is purely a backstop against pathological input.
+// - Values bounded to {0,200} and forbidden from containing `"`, `]`, or any
+//   control character that could either close the marker early or forge a
+//   sibling key — enforced structurally by the negated character class, not
+//   by a separate validation pass.
+// Global flag so `findMarker` can scan forward through a large prompt.
+const MARKER_RE = /\[gsd:dispatch((?:\s+[A-Za-z][A-Za-z0-9_-]{0,31}="[^"\]\r\n]{0,200}")*)\s*\]/g;
+const MARKER_KV_RE = /([A-Za-z][A-Za-z0-9_-]{0,31})="([^"\]\r\n]{0,200})"/g;
+
+// Prose fallback frame: `execute plan <token> of phase <PHASE TOKEN>`.
+// - Case-insensitive, `\s+` throughout so CRLF (and any run of whitespace)
+//   parses identically to LF.
+// - The plan token is bounded (`\S{1,80}`) but its VALUE is deliberately
+//   discarded by the caller (see `parseDispatchIdentity` below) — captured
+//   only so the phase token can be anchored correctly after it.
+// - The phase token is bounded by `DISPATCH_PHASE_TOKEN_SOURCE`, replacing
+//   the old greedy `(\S+)`, so a directory-name suffix (`-auth`) or a
+//   sentence-terminating period is never swept into the token.
+const PROSE_RE = new RegExp(
+  `execute\\s+plan\\s+(\\S{1,80})\\s+of\\s+phase\\s+(${DISPATCH_PHASE_TOKEN_SOURCE})`,
+  'i',
+);
+
+/**
+ * Render the `[gsd:dispatch phase="…" plan="…"]` marker for a producer to
+ * embed verbatim in a dispatch description/prompt. Never throws.
+ *
+ * Emits only keys whose value is a non-empty string not containing `"`, `]`,
+ * `\r`, or `\n` — such a value is UNUSABLE and that key is omitted entirely,
+ * because embedding it could close the marker early and forge a second,
+ * attacker-controlled field. Key order is always `phase` then `plan`.
+ * Returns `''` when neither key is usable (nothing worth emitting).
+ */
+function renderDispatchIdentityMarker(input) {
+  const value = input && typeof input === 'object' ? input : {};
+  const parts = [];
+  for (const key of ['phase', 'plan']) {
+    const v = value[key];
+    if (typeof v === 'string' && v.length > 0 && !/["\]\r\n]/.test(v)) {
+      parts.push(`${key}="${v}"`);
+    }
+  }
+  if (parts.length === 0) return '';
+  return `[gsd:dispatch ${parts.join(' ')}]`;
+}
+
+function emptyResult() {
+  return { phase: null, plan: null, source: null };
+}
+
+/**
+ * Scan `texts` in order for the first well-formed marker that yields at
+ * least one recognized key (`phase` and/or `plan`). Returns `{ phase, plan }`
+ * (one of the two possibly null, never both) or `null` if no QUALIFYING
+ * marker was found in any text. Unrecognized keys inside a marker are
+ * ignored (forward compatibility — a later `run=`/`wave=` key must not break
+ * a deployed parser).
+ *
+ * #4594 F1 fix: a marker that matches `MARKER_RE` but carries neither
+ * `phase=` nor `plan=` (e.g. only unrecognized keys, or an empty kv block)
+ * is NOT treated as "found" — it is skipped and scanning continues (later
+ * markers in the same text, then subsequent texts), falling through to the
+ * prose fallback if nothing qualifying turns up. Without this, prompt text
+ * that merely CONTAINS the literal marker syntax with no usable identifiers
+ * silently suppressed the prose fallback entirely, since the old
+ * implementation returned on the first syntactic match regardless of
+ * content.
+ */
+function findMarker(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    MARKER_RE.lastIndex = 0;
+    let match;
+    while ((match = MARKER_RE.exec(text)) !== null) {
+      const kvBlock = match[1] || '';
+      let phase = null;
+      let plan = null;
+      MARKER_KV_RE.lastIndex = 0;
+      let kv;
+      while ((kv = MARKER_KV_RE.exec(kvBlock)) !== null) {
+        const [, key, val] = kv;
+        if (key === 'phase' && phase === null) phase = val;
+        else if (key === 'plan' && plan === null) plan = val;
+      }
+      if (phase === null && plan === null) continue;
+      return { phase, plan };
+    }
+  }
+  return null;
+}
+
+/**
+ * Scan `texts` in order for the first `execute plan <token> of phase
+ * <PHASE TOKEN>` frame. Returns `{ phase }` or `null`.
+ *
+ * The prose fallback returns `plan: null` DELIBERATELY (enforced by the
+ * caller, not here): the prose plan token (e.g. `02`) is a bare in-phase
+ * plan number, a different namespace from the sentinel's `plan_id` (e.g.
+ * `03-02-hardening`, which is phase-prefixed AND slugged). Reporting the
+ * prose plan token as the parsed `plan` is exactly the false-mismatch bug
+ * this module exists to fix — an absent value is honestly "cannot compare",
+ * while a wrong value silently forges a mismatch on every dispatch. Do not
+ * "fix" this by threading the plan token through — that was the bug.
+ */
+function findProse(texts) {
+  for (const text of texts) {
+    if (typeof text !== 'string' || text.length === 0) continue;
+    const match = PROSE_RE.exec(text);
+    if (match) {
+      return { phase: match[2] };
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse dispatch identity out of one or more texts (a short description, a
+ * full prompt body, etc). Never throws for any input type; non-string
+ * entries are skipped.
+ *
+ * Pass 1: scan all texts in order for a well-formed marker; the first one
+ * wins outright (marker beats prose even if prose appears earlier in the
+ * same text — see the design doc's row 8).
+ * Pass 2 (only if no marker was found anywhere): scan all texts in order for
+ * the prose frame; the first match wins. `plan` is always `null` from this
+ * path (see `findProse`'s doc comment).
+ *
+ * Returns `{ phase, plan, source }` where `source` is `'marker' | 'prose' |
+ * null`.
+ */
+function parseDispatchIdentity(...texts) {
+  const marker = findMarker(texts);
+  if (marker) {
+    return { phase: marker.phase, plan: marker.plan, source: 'marker' };
+  }
+
+  const prose = findProse(texts);
+  if (prose) {
+    return { phase: prose.phase, plan: null, source: 'prose' };
+  }
+
+  return emptyResult();
+}
+
+module.exports = {
+  DISPATCH_PHASE_TOKEN_SOURCE,
+  renderDispatchIdentityMarker,
+  parseDispatchIdentity,
+};

package/hooks/dist/lib/filename-classification.js

@@ -0,0 +1,64 @@
+'use strict';
+// hooks/lib/filename-classification.js — hand-written, NOT generated. One
+// tiny, deliberately-named filename slicer.
+//
+// WHY this exists: issue #4580 was caused by comparing "everything after the
+// `.env.` prefix" — a multi-segment token like `local.example` — against a
+// set whose members are FINAL EXTENSIONS (`example`). `.env.local.example`
+// was classified by its full `local.example` tail, which is not in a set
+// built from bare extensions, so the comparison silently failed. This module
+// deliberately exposes ONLY the final-extension answer so the wrong token
+// can't be picked by accident at a call site. The "everything after the
+// first dot" form is intentionally NOT exported: no caller needs it, and an
+// unused export is dead code.
+
+/**
+ * The segment after the LAST dot in `name`. A string with no dot IS its own
+ * final extension. Inert on non-strings/empty input: never throws, returns
+ * ''.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function finalExtension(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  const i = name.lastIndexOf('.');
+  return i === -1 ? name : name.slice(i + 1);
+}
+
+/**
+ * Strips ALL trailing dots and spaces from `name`, repeatedly, from the end
+ * of the basename.
+ *
+ * WHY: Win32 strips trailing dots and trailing spaces from each path
+ * component when resolving a filesystem path — `.env.`, `.env..`, `.env `,
+ * and `.env. ` all resolve to the same on-disk file as `.env` on Windows.
+ * These are therefore ALIASES for the protected name, not distinct names,
+ * and a guard that classifies the literal string without normalizing first
+ * can be bypassed by any of them. This is not cosmetic tidying — it closes
+ * that Windows path-alias bypass.
+ *
+ * This runs UNCONDITIONALLY on every host platform (macOS, Linux, Windows),
+ * not only when actually running on Windows: the guard must behave
+ * identically everywhere, and a name is judged by what Win32 would resolve
+ * it to, regardless of what OS the hook happens to run on.
+ *
+ * @param {*} name
+ * @returns {string}
+ */
+function normalizeWindowsBasename(name) {
+  if (typeof name !== 'string' || name === '') return '';
+  let end = name.length;
+  while (end > 0 && (name[end - 1] === '.' || name[end - 1] === ' ')) end--;
+  return name.slice(0, end);
+}
+
+// Last `/`- or `\`-separated segment, ignoring trailing separators. A string
+// with no separator IS its own last segment.
+function lastSegment(tok) {
+  const s = tok.replace(/[\\/]+$/, '');
+  const i = Math.max(s.lastIndexOf('/'), s.lastIndexOf('\\'));
+  return i === -1 ? s : s.slice(i + 1);
+}
+
+module.exports = { finalExtension, normalizeWindowsBasename, lastSegment };

package/hooks/dist/lib/isolation-deny-reason.js

@@ -36,4 +36,56 @@ const REASON_CODE = Object.freeze({
   NOT_ISOLATED_WORKTREE: 'not_isolated_worktree',
 });
 
-module.exports = { REASON_CODE };
+// #4594 row 15 / F2: values interpolated into a deny reason (sentinel/dispatch
+// phase and plan) come from a sentinel file on disk and, transitively, from
+// model-authored prompt text, neither of which is trusted — bound length and
+// strip control characters/newlines so a crafted value cannot forge extra
+// lines or otherwise inject content into the guard's stdout/stderr message
+// (same discipline as escaping an untrusted token before embedding it in a
+// message, e.g. phase-plan-index's `depends_on` warning).
+//
+// Originally duplicated byte-for-byte in hooks/gsd-agent-isolation-guard.js
+// and hooks/gsd-cursor-subagent-start.js (#4594 F2 review finding) — both
+// hooks already require this dependency-free module, so there is no
+// cold-load justification for the duplication the way there is for
+// hooks/lib/dispatch-identity.js's grammar mirror. Moved here as the single
+// owner; both hooks now import it.
+const REASON_INTERPOLATION_MAX_LEN = 64;
+
+// F6: also strip Unicode line/paragraph separators (U+2028/U+2029) and the
+// bidi-override/isolate control characters (U+202A-U+202E, U+2066-U+2069) —
+// none of these are in `[\x00-\x1f\x7f]`, so a crafted sentinel or dispatch
+// value carrying them could still visually reflow the deny message onto a
+// new line or reverse/hide part of it despite the ASCII control-char strip.
+const REASON_UNSAFE_CHARS_RE = new RegExp(
+  // eslint-disable-next-line no-control-regex -- deliberately stripping control chars/newlines
+  '[\\x00-\\x1f\\x7f\\u2028\\u2029\\u202a-\\u202e\\u2066-\\u2069]',
+  'g',
+);
+
+function sanitizeForReason(value) {
+  if (typeof value !== 'string' || value.length === 0) return '(none)';
+  const stripped = value.replace(REASON_UNSAFE_CHARS_RE, '');
+  return stripped.length > REASON_INTERPOLATION_MAX_LEN
+    ? `${stripped.slice(0, REASON_INTERPOLATION_MAX_LEN)}…`
+    : stripped;
+}
+
+function describeSentinelDiscard(sentinelDiscarded) {
+  const sentinelPhase = sanitizeForReason(sentinelDiscarded.sentinel.phase);
+  const sentinelPlan = sanitizeForReason(sentinelDiscarded.sentinel.plan);
+  const dispatchPhase = sanitizeForReason(sentinelDiscarded.dispatch.phase);
+  const dispatchPlan = sanitizeForReason(sentinelDiscarded.dispatch.plan);
+  return (
+    ` A fresh dispatch-isolation sentinel was present but did not apply to this dispatch ` +
+    `(sentinel phase="${sentinelPhase}" plan="${sentinelPlan}"; dispatch phase="${dispatchPhase}" ` +
+    `plan="${dispatchPlan}"), so it was not consulted.`
+  );
+}
+
+module.exports = {
+  REASON_CODE,
+  REASON_INTERPOLATION_MAX_LEN,
+  sanitizeForReason,
+  describeSentinelDiscard,
+};