@opengsd/gsd-core 1.17.0 → 1.19.0

package/commands/gsd/code-review.md

@@ -48,6 +48,14 @@ Optional flags parsed from the `<arguments>` block:
 - `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
 
 Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<required_reading>` blocks.
+
+## Outside a phase
+
+Reviewer lanes run without a phase (`gsd_run` is defined by the runtime-launcher preamble inside workflow fences; in a plain shell call `node <install>/gsd-core/bin/gsd-tools.cjs` instead): pipe canonical repo-relative file paths (one per line) to stdin of
+`gsd_run review-lane dispatch-step --repo-root <root> --depth <quick|standard|deep> --base-sha <sha> --run-dir "$(mktemp -d)" --cap-id code-review --point execute:post --explicit <slugs> --raw`.
+`review-lane` flags are space-separated (`--depth quick`), never `--flag=value`. `--explicit` (omitted, nothing dispatches yet the call exits ok), `--depth`, `--base-sha` (lane reviews changes relative to it; commit them first) and stdin paths are required; `--run-dir` should be a fresh temp dir (default `.` writes the prompt file into the current directory); read each lane's output path (`results[].reviewPath`) from the JSON before removing it. `--cap-id`/`--point` select the `code-review` capability, which must be enabled (`workflow.code_review`) and active at `--point` — `execute:post`, or `execute:wave:post` when `workflow.code_review_point` selects it; otherwise nothing dispatches.
+`--explicit` takes comma-separated canonical slugs, no spaces (`codex,antigravity`), not flag aliases (`antigravity`, not `agy`); slugs: first column of `gsd_run review-lane sections` (`review-lane flags` lists flags/aliases).
+Each lane declares its own model key, which is not always its slug (antigravity's is `review.models.agy`); see the `review.models.*` table in `docs/CONFIGURATION.md`. Unset = lane default model.
 </context>
 
 <process>

package/commands/gsd/pause-work.md

@@ -21,7 +21,7 @@ Routes to the pause-work workflow which handles:
 - Current phase detection from recent files
 - Complete state gathering (position, completed work, remaining work, decisions, blockers)
 - Handoff file creation with all context sections
-- Git commit as WIP
+- Git commit handoff
 - Resume instructions
 </objective>
 

package/gsd-core/bin/gsd-tools.cjs

@@ -85,6 +85,14 @@
  *     [--no-archive-phases]          Skip moving phase dirs to milestones/vX.Y-phases/ (archived by default)
  *     [--archive-quick]              Move .planning/quick/* dirs to milestones/vX.Y-quick/ + reset the
  *                                    Quick Tasks Completed table (#2142; opt-in, default OFF)
+ *     [--release-map <file>]         Archive a per-repository release map (JSON array of
+ *                                    {repo, release, reference, environment, status, tag}) as
+ *                                    milestones/vX.Y-RELEASE-MAP.json and record it in MILESTONES.md
+ *                                    (#5706; validated before any write, absent = unchanged)
+ *
+ *   milestone release-tags --map <file.json> [--dry-run]
+ *                                      Preflight, then create annotated tags per sub-repo from a JSON array of
+ *                                      {repo, tag, ref?, message?, skip?}; never pushes, never overwrites (#5705)
  *
  *   milestone archive-quick <version>  Move .planning/quick/* dirs to milestones/vX.Y-quick/ + reset the
  *                                      Quick Tasks Completed table, WITHOUT the milestone complete close-out
@@ -312,6 +320,7 @@ try {
 } catch { /* advisory — never block */ }
 
 const { resolveActiveWorkstream, applyResolvedWorkstreamEnv, peekActiveWorkstream } = require('./lib/active-workstream-store.cjs');
+const { planningDir, planningRoot } = require('./lib/planning-workspace.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -325,6 +334,7 @@ const config = require('./lib/config.cjs');
 const estimateCli = require('./lib/estimate-cli.cjs');
 const template = require('./lib/template.cjs');
 const milestone = require('./lib/milestone.cjs');
+const milestoneReleaseTags = require('./lib/milestone-release-tags.cjs');
 const commands = require('./lib/commands.cjs');
 const runtimeIdentity = require('./lib/runtime-identity.cjs');
 const init = require('./lib/init.cjs');
@@ -847,7 +857,31 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       error,
       output: output,
     });
-    if (!handled) config.cmdConfigNewProject(cwd, args[1], raw);
+    if (handled) return;
+    // #5268: this verb's flag surface is closed, as `todo complete`'s is
+    // (#4096). `--dry-run` is parsed and plumbed, and any OTHER flag fails loudly
+    // instead of being silently ignored: an accepted-but-ignored `--dry-run`
+    // wrote the config it was meant to preview. (`--raw` is spliced by the
+    // dispatcher before routing; it stays in the set as a guard against that
+    // splice ever moving.) The choices JSON is the one positional argument,
+    // wherever the flag sits, and a second one is refused for the same reason.
+    // A flag is a dash followed by a letter: `-1` is a (negative-number) JSON
+    // argument, refused below as choices that are not an object, not a flag.
+    const CONFIG_NEW_PROJECT_KNOWN_FLAGS = new Set(['--dry-run', '--raw']);
+    const positionals = [];
+    for (const a of args.slice(1)) {
+      if (typeof a === 'string' && /^--?[A-Za-z]/.test(a)) {
+        if (!CONFIG_NEW_PROJECT_KNOWN_FLAGS.has(a)) {
+          error(`Unknown flag for config-new-project: ${a}`, ERROR_REASON.USAGE);
+        }
+        continue;
+      }
+      positionals.push(a);
+    }
+    if (positionals.length > 1) {
+      error(`Unexpected argument for config-new-project: ${positionals[1]}. Usage: config-new-project [choices-json] [--dry-run]`, ERROR_REASON.USAGE);
+    }
+    config.cmdConfigNewProject(cwd, positionals[0], raw, { dryRun: args.includes('--dry-run') });
   }
 
   function routeConfigPath({ cwd, raw, workstreamContext }) {
@@ -1445,8 +1479,12 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // Silent no-op when the section is absent or the table is already canonical
     // — the quick/fast workflows call this before their first append, so the
     // migration runs exactly once, on the first quick run, unprompted otherwise.
-    const statePath = path.join(cwd, '.planning', 'STATE.md');
+    const planningPath = planningDir(cwd);
+    const statePath = path.join(planningPath, 'STATE.md');
     if (!fs.existsSync(statePath)) {
+      if (planningPath !== planningRoot(cwd)) {
+        throw new ExitError(1, `quick-tasks-migrate: STATE.md not found at ${statePath}`);
+      }
       output({ ok: true, migrated: false, reason: `STATE.md not found at ${statePath}` }, raw);
       return;
     }
@@ -1519,7 +1557,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             || (qtaQuickId && qtaSlug ? `[${qtaQuickId}-${qtaSlug}](./quick/${qtaQuickId}-${qtaSlug}/)` : undefined);
           const qtaStatus = qtaParsed['status'] || undefined;
 
-          const statePath = path.join(cwd, '.planning', 'STATE.md');
+          const statePath = path.join(planningDir(cwd), 'STATE.md');
           if (!fs.existsSync(statePath)) {
             error(`quick-tasks-append: STATE.md not found at ${statePath}`, ERROR_REASON.USAGE);
           }
@@ -1593,7 +1631,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     const fsx = require('node:fs');
     const os = require('node:os');
     const { REVIEWER_LANES, mergeReviewerLanes } = require('./lib/review-lane-descriptor.cjs');
-    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneBudget } = require('./lib/review-lane-invocation.cjs');
+    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneBudget, applyPromptOverride } = require('./lib/review-lane-invocation.cjs');
     // OpenCode 2.x argv differs from 1.x (no --variant; effort rides on the model as `#variant`;
     // ADR-5331 D5/D8). The generation is probed lazily, only when the opencode lane is resolved.
     const resolveLanePlan = (laneInput) => {
@@ -1627,8 +1665,9 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // `plan`/`invoke` are the only subs that need the expensive plan-building path
     // below; `sections`/`flags` return earlier still. Anything else errors here, before
     // any of that work starts.
-    if (!['plan', 'invoke', 'sections', 'flags', 'dispatch-step', 'explicit-from-argv'].includes(sub)) {
-      error("Usage: review-lane <plan|invoke|sections|flags|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]");
+    const REVIEW_LANE_USAGE = 'Usage: review-lane <plan|invoke|sections|flags|availability|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]';
+    if (!['plan', 'invoke', 'sections', 'flags', 'availability', 'dispatch-step', 'explicit-from-argv'].includes(sub)) {
+      error(REVIEW_LANE_USAGE);
       return;
     }
     const runDir = flag('--run-dir') || '.';
@@ -1704,8 +1743,34 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             method: opts.method,
             headers: opts.body ? { 'Content-Type': 'application/json' } : undefined,
             body: opts.body,
+            // Never follow a redirect: the egress check compares the CONFIGURED host, so a
+            // followed redirect would send the review prompt to a host the user never named (#5433).
+            redirect: 'manual',
             signal: AbortSignal.timeout(opts.timeoutMs),
           });
+          // probe:true marks a reachability probe (returns status only, body ''): the status line is the answer, so do not
+          // let a stalled body turn a replying server into `missing`.
+          if (opts.probe) {
+            res.body?.cancel().catch(() => {});
+            return { ok: res.ok, status: res.status, body: '' };
+          }
+          if (res.status >= 300 && res.status < 400) {
+            res.body?.cancel().catch(() => {});
+            const location = res.headers.get('location');
+            let target = 'without a Location header';
+            if (location) {
+              target = 'to an unparseable Location';
+              try { target = `to ${new URL(location, url).host}`; } catch { /* keep the unparseable wording */ }
+            }
+            // Host and path only: a configured URL may carry credentials that must not reach a review file.
+            const asked = (() => { try { const u = new URL(url); return `${u.host}${u.pathname}`; } catch { return 'the configured URL'; } })();
+            return {
+              ok: false,
+              status: res.status,
+              body: '',
+              error: `${asked} answered HTTP ${res.status}, redirecting ${target}. The lane does not follow redirects; configure the final URL as the lane's host.`,
+            };
+          }
           return { ok: res.ok, status: res.status, body: await res.text() };
         } catch (e) {
           return { ok: false, status: 0, body: '', error: e && e.message ? e.message : String(e) };
@@ -1732,6 +1797,23 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
 
     const selected = (flag('--selected') || '')
       .split(',').map((s) => s.trim()).filter(Boolean);
+    // #5266: `<slug>:available|missing` per openai-http lane. Host + default come from the lane
+    // descriptor (resolveLanePlan), probing is runner.probeLane — review.md keeps no host table.
+    // Prerequisite binaries (jq) are reported separately by the workflow, not folded in here.
+    // First-party lanes only: ADR-2782 D5 requires egress/consent before a third-party lane's host is
+    // contacted; detection has no such check, so installed third-party lanes are never probed here.
+    if (sub === 'availability') {
+      const { rows, warnings } = await runner.probeHttpLanes(
+        REVIEWER_LANES,
+        selected,
+        (lane) => resolveLanePlan({ lane, configGet, runDir, repoRoot }),
+        buildLaneRunnerDeps(),
+      );
+      for (const w of warnings) process.stderr.write(`review-lane availability: ${w}\n`);
+      process.stdout.write(rows.join('\n') + (rows.length ? '\n' : ''));
+      return;
+    }
+
     // ADR-2782 D8 (#2927): the lane map is first-party ∪ INSTALLED overlay
     // `reviewer` bodies, first-party winning on slug collision. Before this merge
     // the map was built from the frozen REVIEWER_LANES array alone, so an installed,
@@ -1945,7 +2027,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       const dispatchResult = await dispatchReviewerLanes(
         {
           trait,
-          selection: { explicitFlags, detected: rosterSlugs },
+          selection: { explicitFlags, detected: rosterSlugs, lanes: mergedLanes },
           repoRoot,
           paths,
           depth,
@@ -1996,7 +2078,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     }
 
     if (sub !== 'invoke') {
-      error("Usage: review-lane <plan|invoke|sections|flags|dispatch-step|explicit-from-argv> [--selected a,b] [--run-dir D] [--repo-root R]");
+      error(REVIEW_LANE_USAGE);
       return;
     }
 
@@ -2097,14 +2179,11 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     }
 
     // `--prompt-file` lets the caller substitute a budget-trimmed prompt. Applied to whichever
-    // channel this lane actually reads from, so one flag serves both transports.
+    // channel this lane actually reads from (stdin, argv, an argv-embedded file reference, or the
+    // http promptPath), so one flag serves every lane (#5049).
     const promptOverride = flag('--prompt-file');
     if (promptOverride) {
-      if (entry.plan.transport === 'spawn') {
-        if (entry.plan.stdin) entry.plan.stdin = promptOverride;
-      } else {
-        entry.plan.promptPath = promptOverride;
-      }
+      entry.plan = applyPromptOverride(entry.plan, promptOverride, repoRoot);
     }
 
     // ADR-2782 D5 rule 4: re-resolve the consented destination at INVOCATION. `undefined` (no
@@ -2139,6 +2218,13 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           testCommandNormalizer.cmdNormalizeTestCommand(cwd, args[1]);
   }
 
+  function routeResolvePackageManager({ args, cwd }) {
+    // #5346: the gates' no-configured-command fallback asks here for the
+    // project's package manager (packageManager field, then lockfile, else npm).
+    // args[1] is the script name; --cwd (already parsed into `cwd`) locates package.json.
+    require('./lib/normalize-test-command.cjs').cmdResolvePackageManager(cwd, args[1]);
+  }
+
   function routeDispatchShouldFlatten({ args, cwd, raw, error }) {
     // #1708 / #853: typed query replacing the `RUNTIME === 'codex'` prose rule.
           //
@@ -3022,7 +3108,12 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           const jsonIdx = args.indexOf('--json');
           const agentSkillsJsonMode = jsonIdx !== -1;
           if (agentSkillsJsonMode) args.splice(jsonIdx, 1);
-          init.cmdAgentSkills(cwd, args[1], raw, agentSkillsJsonMode);
+          // #5122: the agent's own self-load asks for configured skills only,
+          // never the persona fallback served to orchestrator-side injection.
+          const skillsOnlyIdx = args.indexOf('--skills-only');
+          const agentSkillsOnly = skillsOnlyIdx !== -1;
+          if (agentSkillsOnly) args.splice(skillsOnlyIdx, 1);
+          init.cmdAgentSkills(cwd, args[1], raw, agentSkillsJsonMode, agentSkillsOnly);
   }
 
   function routeSkillManifest({ args, cwd, raw, error }) {
@@ -3135,7 +3226,18 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             // --dry-run) the command refuses before touching anything. Distinct
             // from --force, which bypasses the narrow scope guards only.
             const confirm = args.includes('--confirm');
-            milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force, dryRun, archiveQuick, confirm }, raw);
+            // #5706 (epic #3628): optional caller-supplied release map file.
+            // A flag with no usable value fails loud rather than being dropped.
+            let releaseMap = null;
+            const releaseMapIdx = args.indexOf('--release-map');
+            if (releaseMapIdx !== -1) {
+              const releaseMapValue = args[releaseMapIdx + 1];
+              if (typeof releaseMapValue !== 'string' || releaseMapValue.startsWith('--') || releaseMapValue.trim() === '') {
+                error('--release-map requires a file path (a JSON array of release-map entries)');
+              }
+              releaseMap = releaseMapValue;
+            }
+            milestone.cmdMilestoneComplete(cwd, args[2], { name: milestoneName, archivePhases, force, dryRun, archiveQuick, confirm, releaseMap }, raw);
           } else if (subcommand === 'archive-quick') {
             // #2142 escalation: narrow archival-only entry point (does NOT
             // touch ROADMAP/REQUIREMENTS/MILESTONES.md, runs no completion
@@ -3143,8 +3245,11 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             // unlike `milestone complete --archive-quick`.
             const dryRun = args.includes('--dry-run');
             milestone.cmdQuickArchive(cwd, args[2], { dryRun }, raw);
+          } else if (subcommand === 'release-tags') {
+            // #5705 (epic #3628 Phase 1): repository-scoped annotated release tags.
+            milestoneReleaseTags.cmdMilestoneReleaseTags(cwd, args, raw);
           } else {
-            error('Unknown milestone subcommand. Available: complete, archive-quick', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+            error('Unknown milestone subcommand. Available: complete, archive-quick, release-tags', ERROR_REASON.SDK_UNKNOWN_COMMAND);
           }
   }
 
@@ -4802,6 +4907,7 @@ const HOST_COMMAND_ROUTERS = {
     // #3676 (Phase 4, epic #3344): quick-batch coordination verbs.
     'quick-batch': routeQuickBatchCommand,
     'normalize-test-command': routeNormalizeTestCommand,
+    'resolve-package-manager': routeResolvePackageManager,
     'dispatch-should-flatten': routeDispatchShouldFlatten,
     'dispatch-isolation': routeDispatchIsolation,
     'dispatch-capacity': routeDispatchCapacity,
@@ -5107,7 +5213,7 @@ function runWithTimeout(argv) {
 // drifting apart when a query command was added to only one or two.
 const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--project-dir <path>] [--ws <name>] [--json-errors] [--exit-contract=<v>]\n' +
   'Commands: agent, agent-skills, assumption-delta, audit-open, audit-uat, check, check-commit, commit, commit-docs-guard, commit-to-subrepo, pr-subrepo, ' +
-  'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, ' +
+  'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, normalize-test-command, resolve-package-manager, ' +
   'context-predicates, current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
   'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
   'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +

package/gsd-core/bin/lib/agent-install-check.cjs

@@ -328,8 +328,33 @@ function checkCodexModelPosture(runtime, projectRoot) {
 // derives its sandbox_mode from actually lives, in every install shape
 // (repo-dev tree or npm-global package, where the package still ships its
 // own agents/ alongside bin/ and gsd-core/).
-function _canonicalAgentSourceDir() {
-    return node_path_1.default.join(__dirname, '..', '..', '..', 'agents');
+//
+// #5496: "install-relative" has three shapes. This module compiles to
+// `<root>/gsd-core/bin/lib/`, so `<root>` is three parents up. In the repository
+// and the npm package the canonical sources are `<root>/agents`. In an INSTALLED
+// config dir `<root>/agents` holds the CONVERTED runtime copies (no `tools:`
+// declaration — every role then derived `read-only`, 26 false violations on a
+// clean Codex install) and the canonical sources are `<root>/gsd-core/agents`.
+// Prefer the nested directory when it actually holds agent sources; fall back to
+// `<root>/agents`. `root` is a parameter so each layout is testable.
+//
+// #5636: "holds agent sources" is a recognized agent file, `gsd-<name>.md` (every file in the shipped
+// roster) that is not a `.compact.md` variant. Any markdown would let a stray README in the nested
+// directory hide the real sources, so the posture check found no role's canonical file and skipped all.
+const CANONICAL_AGENT_SOURCE_FILE = /^gsd-.+\.md$/;
+function isCanonicalAgentSourceFile(entry) {
+    return CANONICAL_AGENT_SOURCE_FILE.test(entry) && !entry.endsWith('.compact.md');
+}
+function canonicalAgentSourceDir(root = node_path_1.default.join(__dirname, '..', '..', '..')) {
+    const nested = node_path_1.default.join(root, 'gsd-core', 'agents');
+    try {
+        if (node_fs_1.default.readdirSync(nested).some(isCanonicalAgentSourceFile))
+            return nested;
+    }
+    catch {
+        // Absent or unreadable: not this layout.
+    }
+    return node_path_1.default.join(root, 'agents');
 }
 /**
  * Validate installed Codex `.toml` agents' `sandbox_mode` against what each
@@ -384,7 +409,7 @@ function checkCodexSandboxPosture(runtime, projectRoot) {
             reason: POSTURE_REASON.AGENTS_DIR_MISSING,
         };
     }
-    const canonicalAgentsDir = _canonicalAgentSourceDir();
+    const canonicalAgentsDir = canonicalAgentSourceDir();
     // Same symlink guard as checkCodexModelPosture, same reason (never follow
     // an agents-dir symlink into an arbitrary file's content).
     const tomlFiles = node_fs_1.default
@@ -533,6 +558,7 @@ module.exports = {
     checkAgentsInstalled,
     checkCodexModelPosture,
     checkCodexSandboxPosture,
+    canonicalAgentSourceDir,
     POSTURE_REASON,
     resolveAgentHint,
 };

package/gsd-core/bin/lib/args-terminator.cjs

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Per-install terminators for the typed-text capture heredocs (#5637).
+ *
+ * Every workflow that reads the typed text opens with
+ *
+ *   IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+ *   $ARGUMENTS
+ *   GSD_ARGS_END
+ *
+ * and `/gsd-quick-batch` feeds `parse-args` through the same shape with `GSD_QUICK_BATCH_ARGS_END`.
+ * The harness replaces `$ARGUMENTS` with the typed text before the shell parses the fence, so typed
+ * text with a terminator line of its own closes the heredoc early and the lines after it run as
+ * shell. A literal in a shipped file cannot be made unforgeable, so each install replaces it with
+ * `<TERMINATOR>_<nonce>`, a nonce the typed text has no way to know. The shipped source keeps the
+ * canonical tokens; only the files an install writes carry the nonce.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARGS_NONCE_RE = exports.ARGS_TERMINATOR = exports.ARGS_TERMINATORS = void 0;
+exports.generateArgsNonce = generateArgsNonce;
+exports.stampArgsTerminator = stampArgsTerminator;
+exports.readInstalledNonce = readInstalledNonce;
+exports.armArgsNonce = armArgsNonce;
+exports.disarmArgsNonce = disarmArgsNonce;
+exports.stampInstalledContent = stampInstalledContent;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The canonical terminators the shipped workflows and commands carry. */
+exports.ARGS_TERMINATORS = Object.freeze(['GSD_ARGS_END', 'GSD_QUICK_BATCH_ARGS_END']);
+/** The terminator every workflow carries. */
+exports.ARGS_TERMINATOR = 'GSD_ARGS_END';
+/** A nonce is 128 random bits as 32 lowercase hex characters. */
+exports.ARGS_NONCE_RE = /^[0-9a-f]{32}$/;
+const OPENER_RE = new RegExp(`<<'(${exports.ARGS_TERMINATORS.join('|')})'`, 'g');
+const CLOSER_RE = new RegExp(`^(${exports.ARGS_TERMINATORS.join('|')})(?=\\r?$)`, 'gm');
+/** A fresh nonce. `randomBytes` is a seam for tests. */
+function generateArgsNonce(randomBytes = node_crypto_1.randomBytes) {
+    return randomBytes(16).toString('hex');
+}
+/**
+ * `content` with each canonical terminator replaced by the stamped one: the heredoc opener tag and
+ * the closing line. A terminator that is already stamped does not match and is left alone, and so
+ * is prose that names a token inside a line.
+ *
+ * @throws {TypeError} when `nonce` is not 32 lowercase hex characters
+ */
+function stampArgsTerminator(content, nonce) {
+    if (typeof nonce !== 'string' || !exports.ARGS_NONCE_RE.test(nonce)) {
+        throw new TypeError('stampArgsTerminator: nonce must be 32 lowercase hex characters');
+    }
+    return content
+        .replace(OPENER_RE, (_m, token) => `<<'${token}_${nonce}'`)
+        .replace(CLOSER_RE, (_m, token) => `${token}_${nonce}`);
+}
+let armedNonce = null;
+const INSTALLED_NONCE_RE = /^GSD_ARGS_END_([0-9a-f]{32})\r?$/m;
+/** A workflow is tens of KiB; anything near this is not one, and is not read. */
+const MAX_WORKFLOW_BYTES = 2 * 1024 * 1024;
+/**
+ * The nonce a previous install left in `configDir`, read from the first installed workflow that
+ * carries one; null when there is none. Entries that are not regular files (a directory, a FIFO,
+ * a symlink) and files over MAX_WORKFLOW_BYTES are skipped, and one unreadable entry does not end
+ * the scan.
+ */
+function readInstalledNonce(configDir) {
+    let dir;
+    let names;
+    try {
+        dir = (0, node_path_1.join)(configDir, 'gsd-core', 'workflows');
+        names = (0, node_fs_1.readdirSync)(dir).sort();
+    }
+    catch {
+        return null;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.md'))
+            continue;
+        try {
+            const full = (0, node_path_1.join)(dir, name);
+            const stat = (0, node_fs_1.lstatSync)(full);
+            if (!stat.isFile() || stat.size > MAX_WORKFLOW_BYTES)
+                continue;
+            const match = INSTALLED_NONCE_RE.exec((0, node_fs_1.readFileSync)(full, 'utf8'));
+            if (match)
+                return match[1];
+        }
+        catch {
+            // This entry is unreadable; the next one may still carry the nonce.
+        }
+    }
+    return null;
+}
+/**
+ * Arm stamping for the install into `configDir`, before it writes anything. When `reuse` is true
+ * the directory's installed nonce is kept, so a reinstall changes nothing; otherwise, or when
+ * there is none, a fresh one is minted. Only a global install (a directory under the user's home,
+ * which a cloned repository cannot seed) may reuse: a project-local directory is often committed,
+ * and a nonce planted there would be adopted. Generators never arm it, so the committed generated
+ * skills stay canonical and deterministic.
+ */
+function armArgsNonce(configDir, reuse = false) {
+    const prior = reuse && configDir !== undefined ? readInstalledNonce(configDir) : null;
+    armedNonce = prior ?? generateArgsNonce();
+    return armedNonce;
+}
+/** Stop stamping: the process is no longer writing for an install that has a nonce. */
+function disarmArgsNonce() {
+    armedNonce = null;
+}
+/** `content` stamped with the armed nonce, or untouched when this process is not an installer. */
+function stampInstalledContent(content) {
+    return armedNonce === null ? content : stampArgsTerminator(content, armedNonce);
+}

package/gsd-core/bin/lib/broken-windows.cjs

@@ -504,6 +504,63 @@ function validateEntryShape(e, i) {
         ...('milestone' in o ? { milestone: typeof o.milestone === 'string' ? o.milestone : null } : {}),
     };
 }
+/**
+ * #5418: when the frontmatter counts disagree with the parsed entries, the usual
+ * cause is a hand-edited table: a row added to the rendered table (and the counts
+ * bumped to match) while the fenced JSON block, the sole source of entries, was left
+ * behind. Names the row ids the table and the JSON block disagree about so the
+ * counts message does not point at the (correct) frontmatter. Returns '' when there
+ * is nothing to add. Best-effort by design: it runs while a WindowsError is already
+ * on its way out, so it must never throw and replace that error.
+ */
+/** Row ids spelled out in the divergence note; the rest are counted. */
+const ROW_ID_LIST_LIMIT = 20;
+function describeTableJsonDivergence(raw, entries) {
+    try {
+        // The hint is the PARSED entry count, not frontmatter total_count: the latter
+        // is the number that is wrong here.
+        const table = extractTableRegion(raw, entries.length);
+        if (table === null)
+            return '';
+        const rowId = (line) => (line.split('|')[1] ?? '').trim();
+        // Ids are positive integers (the JSON side enforces it), so a first cell that is
+        // not one — the `_(none)_` empty-ledger placeholder, a continuation line of a
+        // multi-line description, control characters — is not a row id and is never
+        // echoed into the message.
+        const tableIds = new Set();
+        const tableLines = table.split('\n');
+        for (let i = 2; i < tableLines.length; i++) {
+            if (!tableLines[i].startsWith('|'))
+                continue;
+            const id = rowId(tableLines[i]);
+            if (/^\d{1,15}$/.test(id))
+                tableIds.add(id);
+        }
+        const jsonIds = new Set(entries.map((e) => String(e.id)));
+        const byNumber = (a, b) => Number(a) - Number(b);
+        const list = (ids) => {
+            const shown = ids.slice(0, ROW_ID_LIST_LIMIT).join(', ');
+            return ids.length > ROW_ID_LIST_LIMIT ? `${shown} and ${ids.length - ROW_ID_LIST_LIMIT} more` : shown;
+        };
+        const tableOnly = [...tableIds].filter((id) => !jsonIds.has(id)).sort(byNumber);
+        const jsonOnly = [...jsonIds].filter((id) => !tableIds.has(id)).sort(byNumber);
+        const parts = [];
+        if (tableOnly.length > 0) {
+            parts.push(`row id(s) in the table but not in the fenced JSON block: ${list(tableOnly)}`);
+        }
+        if (jsonOnly.length > 0) {
+            parts.push(`row id(s) in the fenced JSON block but not in the table: ${list(jsonOnly)}`);
+        }
+        if (parts.length === 0)
+            return '';
+        return ` The table and the fenced JSON block disagree (${parts.join('; ')}). The JSON block is the ` +
+            'authoritative entries source: add the missing entries there (or remove the stray table rows) ' +
+            'and keep the frontmatter counts in step with it.';
+    }
+    catch {
+        return '';
+    }
+}
 function parseLedger(raw) {
     const fm = parseFrontmatterStrict(raw);
     if (fm.schema_version !== exports.SCHEMA_VERSION) {
@@ -537,7 +594,8 @@ function parseLedger(raw) {
         recomputed.total_count !== ledger.total_count) {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger counts disagree with entries: frontmatter open/waived/fixed/total=` +
             `${ledger.open_count}/${ledger.waived_count}/${ledger.fixed_count}/${ledger.total_count}` +
-            ` but entries yield ${recomputed.open_count}/${recomputed.waived_count}/${recomputed.fixed_count}/${recomputed.total_count}.`);
+            ` but entries yield ${recomputed.open_count}/${recomputed.waived_count}/${recomputed.fixed_count}/${recomputed.total_count}.` +
+            describeTableJsonDivergence(raw, entries));
     }
     return ledger;
 }

package/gsd-core/bin/lib/capability-ledger.cjs

@@ -807,6 +807,28 @@ function reconcile(runtimeDir) {
     }
     return result;
 }
+/**
+ * #5121: the one bounded read for a SKILL.md found by walking a skill root. A skill file is untrusted
+ * repository (or installed-runtime) content: a symlink to /dev/zero exhausts memory and a FIFO blocks
+ * the process, because a bare readFileSync does neither a type nor a size check. Reuses the fd protocol
+ * of readSmallRegularFile and maps its fail-closed "unreadable" conditions (not a regular file after
+ * following symlinks, over the cap) to null, so a caller treats the file as it treats a missing one.
+ * Any other IO error still throws, as the unbounded read did.
+ *
+ * 256 KiB: the largest shipped SKILL.md is ~21 KB, so the cap is >10x headroom while still bounding the
+ * allocation a hostile repository can force.
+ */
+const SKILL_FILE_MAX_BYTES = 256 * 1024;
+function readSkillFile(filePath) {
+    try {
+        return readSmallRegularFile(filePath, SKILL_FILE_MAX_BYTES);
+    }
+    catch (err) {
+        if (err instanceof LedgerIOError && (err.code === 'ENXIO' || err.code === 'EISDIR' || err.code === 'EFBIG'))
+            return null;
+        throw err;
+    }
+}
 module.exports = {
     readLedger,
     readLedgerStrict,
@@ -822,6 +844,9 @@ module.exports = {
     // #1459 finding 1 (HIGH): the RAW-BYTES variant — the SOLE correct reader for the byte-exact,
     // injective consent content-hash binding (a utf8 decode is lossy and could collide binary artifacts).
     readSmallRegularFileBuffer,
+    // #5121: bounded SKILL.md read shared by skill discovery, the installed-runtime manifest and capability skills.
+    readSkillFile,
+    SKILL_FILE_MAX_BYTES,
     // Exported for testing / introspection
     LEDGER_FILE_NAME,
     CorruptLedgerError,