@opengsd/gsd-core 1.15.0 → 1.16.0

package/scripts/lint-test-file-count.cjs

@@ -141,6 +141,38 @@ function buildTestMap(prodPrefixes, allTestFiles) {
   return map;
 }
 
+// #5074: a `<stem>.platform.test.cjs` alongside `<stem>.test.cjs` (or
+// `.test.ts`) in the SAME directory is the other half of that primary file —
+// the platform-sensitive slice extracted so the Windows CI selector runs
+// only the small sibling — not an additional test file. Exclude it from the
+// per-module count and from the allowlist identity comparison. A
+// `.platform.test.cjs` with no base file in the same directory counts
+// normally, so the rule cannot be used to smuggle in new standalone files.
+// An empty stem (bare `platform.test.cjs`) is never treated as a sibling.
+const PLATFORM_SIBLING_RE = /^(.+)\.platform\.test\.(cjs|ts)$/;
+
+function isSplitSibling(fileBasename, siblingBasenamesInDir) {
+  const m = fileBasename.match(PLATFORM_SIBLING_RE);
+  if (!m) return false;
+  const stem = m[1];
+  if (!stem) return false;
+  return siblingBasenamesInDir.includes(`${stem}.test.cjs`) ||
+         siblingBasenamesInDir.includes(`${stem}.test.ts`);
+}
+
+function excludeSplitSiblings(testFiles) {
+  const basenamesByDir = new Map();
+  for (const f of testFiles) {
+    const dir = path.dirname(f);
+    if (!basenamesByDir.has(dir)) basenamesByDir.set(dir, []);
+    basenamesByDir.get(dir).push(path.basename(f));
+  }
+  return testFiles.filter(f => {
+    const dir = path.dirname(f);
+    return !isSplitSibling(path.basename(f), basenamesByDir.get(dir));
+  });
+}
+
 function loadAllowlist() {
   try { return JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf-8')).modules || {}; }
   catch (_) { return {}; }
@@ -160,6 +192,7 @@ function loadAllowlist() {
  * Returns { verdict, prefix, count, knownFiles, novel, stale, files }
  */
 function evaluateLint({ prefix, testFiles, allowlist }) {
+  testFiles = excludeSplitSiblings(testFiles);
   const count = testFiles.length;
   const entry = allowlist[prefix];
   const currentNames = testFiles.map(f => path.basename(f));
@@ -258,7 +291,7 @@ function run() {
 }
 
 module.exports = {
-  Verdict, evaluateLint, testEffectivePrefix, prodPrefix,
+  Verdict, evaluateLint, testEffectivePrefix, prodPrefix, isSplitSibling,
   _collectProdPrefixes: collectProdPrefixes,
   _collectAllTestFiles: collectAllTestFiles,
   _buildTestMap: buildTestMap,

package/scripts/lint-vendored-deps.cjs

@@ -57,6 +57,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { buildVendorBundle } = require('./lib/vendor-bundle.cjs');
 
 const ROOT = path.join(__dirname, '..');
 
@@ -89,16 +90,29 @@ function resolvePath(p) {
  *                                       or null when there is no bin-side type twin
  * @property {string|null} srcTwin      path under src/vendor/ to the source-side type twin tsc
  *                                       resolves for a relative import from src/**, or null
- * @property {'upstream-verbatim'|'hand-authored'} twinKind
+ * @property {boolean} [bundle]        Reproducibly bundle upstream and its locked dependencies.
+ * @property {'upstream-verbatim'|'upstream-reference'|'hand-authored'} twinKind
  *                                       'upstream-verbatim': srcTwin/vendoredDts are byte-compared
  *                                       against upstream and each other.
  *                                       'hand-authored': no upstream counterpart exists, so the
  *                                       twin is excluded from the byte-compare (checks 2 and 3
  *                                       above are skipped for this row).
+ *                                       'upstream-reference': srcTwin must be exactly
+ *                                       `export * from '<name>';` (bundled rows).
  */
 
 /** @type {VendoredPackage[]} */
 const VENDORED = [
+  ...['tap-parser', 'saxes'].map((name) => ({
+    name,
+    upstreamCjs: name === 'tap-parser' ? 'node_modules/tap-parser/dist/commonjs/index.js' : 'node_modules/saxes/saxes.js',
+    vendoredCjs: `gsd-core/bin/lib/vendor/${name}.cjs`,
+    upstreamDts: null,
+    vendoredDts: null,
+    srcTwin: `src/vendor/${name}.d.cts`,
+    twinKind: 'upstream-reference',
+    bundle: true,
+  })),
   {
     name: 're2js',
     upstreamCjs: 'node_modules/re2js/build/index.cjs',
@@ -127,6 +141,7 @@ const VENDORED = [
  * @returns {string}
  */
 function buildRefreshCommand(row) {
+  if (row.bundle) return 'npm run lint:vendored-deps -- --fix';
   const parts = [`cp ${row.upstreamCjs} ${row.vendoredCjs}`];
   if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
     if (row.vendoredDts) parts.push(`cp ${row.upstreamDts} ${row.vendoredDts}`);
@@ -135,7 +150,8 @@ function buildRefreshCommand(row) {
   return parts.join(' && ');
 }
 
-const REFRESH_COMMAND = VENDORED.map(buildRefreshCommand).join(' && ');
+// Bundled rows share one refresh command; list it once.
+const REFRESH_COMMAND = [...new Set(VENDORED.map(buildRefreshCommand))].join(' && ');
 
 /**
  * Compare two files byte-for-byte. Returns null when equal, or a short
@@ -263,8 +279,17 @@ function readPinState(row, pkgRoot = ROOT) {
 function checkRow(row, pkgRoot = ROOT) {
   const findings = [];
 
-  const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
-  if (cjsDrift) findings.push(cjsDrift);
+  if (row.bundle) {
+    const built = buildVendorBundle(pkgRoot, row.upstreamCjs);
+    for (const [file, expected] of [[row.vendoredCjs, built.code], [`${row.vendoredCjs}.LICENSE.txt`, built.notices]]) {
+      if (!fs.existsSync(resolvePath(file)) || !fs.readFileSync(resolvePath(file)).equals(expected)) {
+        findings.push(`${file} != reproducible upstream bundle (including license notices)`);
+      }
+    }
+  } else {
+    const cjsDrift = compareFiles(row.vendoredCjs, row.upstreamCjs);
+    if (cjsDrift) findings.push(cjsDrift);
+  }
 
   if (row.twinKind === 'upstream-verbatim') {
     if (row.upstreamDts && row.vendoredDts) {
@@ -277,6 +302,11 @@ function checkRow(row, pkgRoot = ROOT) {
     }
   } else if (row.twinKind === 'hand-authored') {
     findings.push(...checkHandAuthoredTwin(row));
+  } else if (row.twinKind === 'upstream-reference') {
+    const expected = `export * from '${row.name}';\n`;
+    if (!row.srcTwin || !fs.existsSync(resolvePath(row.srcTwin)) || fs.readFileSync(resolvePath(row.srcTwin), 'utf8') !== expected) {
+      findings.push(`${row.name}: type twin must forward the upstream declarations verbatim`);
+    }
   }
 
   const { pinnedSpec, installedVersion } = readPinState(row, pkgRoot);
@@ -318,7 +348,13 @@ function checkRow(row, pkgRoot = ROOT) {
  * @returns {string[]} findings remaining after the fix (empty when fully resolved)
  */
 function fixRow(row, pkgRoot = ROOT) {
-  fs.copyFileSync(resolvePath(row.upstreamCjs), resolvePath(row.vendoredCjs));
+  if (row.bundle) {
+    const built = buildVendorBundle(pkgRoot, row.upstreamCjs);
+    fs.writeFileSync(resolvePath(row.vendoredCjs), built.code);
+    fs.writeFileSync(resolvePath(`${row.vendoredCjs}.LICENSE.txt`), built.notices);
+  } else {
+    fs.copyFileSync(resolvePath(row.upstreamCjs), resolvePath(row.vendoredCjs));
+  }
 
   if (row.twinKind === 'upstream-verbatim' && row.upstreamDts) {
     if (row.vendoredDts) fs.copyFileSync(resolvePath(row.upstreamDts), resolvePath(row.vendoredDts));

package/scripts/lint-workflow-shellcheck-baseline.json

@@ -354,11 +354,6 @@
     "code": "2012",
     "message": "Use find instead of ls to better handle non-alphanumeric filenames."
   },
-  {
-    "file": "gsd-core/workflows/execute-phase.md",
-    "code": "2012",
-    "message": "Use find instead of ls to better handle non-alphanumeric filenames."
-  },
   {
     "file": "gsd-core/workflows/execute-phase.md",
     "code": "2016",
@@ -384,11 +379,6 @@
     "code": "2086",
     "message": "Double quote to prevent globbing and word splitting."
   },
-  {
-    "file": "gsd-core/workflows/execute-phase.md",
-    "code": "2086",
-    "message": "Double quote to prevent globbing and word splitting."
-  },
   {
     "file": "gsd-core/workflows/execute-phase/detail/elaboration.md",
     "code": "2086",
@@ -414,6 +404,16 @@
     "code": "2086",
     "message": "Double quote to prevent globbing and word splitting."
   },
+  {
+    "file": "gsd-core/workflows/execute-phase/steps/verify-phase-goal.md",
+    "code": "2012",
+    "message": "Use find instead of ls to better handle non-alphanumeric filenames."
+  },
+  {
+    "file": "gsd-core/workflows/execute-phase/steps/verify-phase-goal.md",
+    "code": "2086",
+    "message": "Double quote to prevent globbing and word splitting."
+  },
   {
     "file": "gsd-core/workflows/execute-phase/steps/wave-post-gate-hooks.md",
     "code": "2086",

package/scripts/mutation-matrix.cjs

@@ -402,11 +402,22 @@ const COVERED = {
     //     extraTests above) rather than deleted, so the mutants they kill stay killed.
     //     frontmatter.test.cjs itself is UNCHANGED and keeps running in the normal
     //     (non-mutation) suite — only the mutation shard drops it.
+    //   - frontmatter-splice.property.test.cjs (#5105): the writer's own property suite,
+    //     moved out of frontmatter.property.test.cjs when spliceFrontmatter moved to
+    //     frontmatter-splice.cts. It requires frontmatter.cjs only as the read-back oracle and
+    //     matches this module's "frontmatter-" prefix, so the derivation would pull it in here;
+    //     it runs in the frontmatter-splice shard instead. Keeping it out of this shard is the
+    //     point of the split: the frontmatter shard was cancelled at its 20-minute cap on PR
+    //     #5114 (1149/1749 mutants tested) with these splice-heavy properties re-run for every
+    //     parser mutant they happened to cover.
     excludeTests: [
       'frontmatter-cli.test.cjs',
+      'frontmatter-splice.property.test.cjs',
       'frontmatter.test.cjs',
     ],
-    minScore: 65,
+    // 87.72% in CI run 36590493522 on PR #5114 (#5105 added in-process command tests).
+    // Floor = floor(87.72) - 1 = 86.
+    minScore: 86,
     // MEASUREMENT, not a projection. Under the tap runner with coverageAnalysis: 'perTest'
     // (#3915), Stryker now re-runs only the test files that cover each mutated line instead
     // of all six files for every one of ~1900 mutants. Measured result: the frontmatter shard
@@ -428,6 +439,37 @@ const COVERED = {
     // The prior audit's 'none' vs 'process' comparison (recorded here before this change)
     // is moot: there is nothing left to opt in or out of.
   },
+  // frontmatter-splice: net-new module from #5105 — the frontmatter WRITER (spliceFrontmatter
+  // and its layout slicing, comment classification, parse budget, key quoting and read-back
+  // check), split out of frontmatter.cts by module ownership. Before the split the writer grew
+  // frontmatter.cjs from 1249 to 1749 mutants and the frontmatter shard was cancelled at its
+  // 20-minute cap (PR #5114, run 36577087588, job 109435636296: 1149/1749 tested at ~1.34
+  // s/covered mutant). Stryker's instrumenter counts 1267 mutants in frontmatter.cjs and 498 in
+  // frontmatter-splice.cjs after the split. Registered here so the writer is scored at all —
+  // mutation coverage does not migrate with relocated code (the context-composer precedent).
+  //
+  // Tests: frontmatter-splice.property.test.cjs is auto-derived (requires this module, matches
+  // the naming rule). extraTests are the other files that drive spliceFrontmatter directly —
+  // they are named after frontmatter, so the derivation cannot find them for this module:
+  //   - frontmatter.unit.test.cjs: the #1572/#1660/#3257/#3742/#4802 splice cases.
+  //   - frontmatter.property.test.cjs: the #644 prohibitions parse -> splice -> re-parse
+  //     bijection.
+  //   - frontmatter-fence.test.cjs: the writer's BOM / CRLF / empty-block fence cases.
+  //
+  // minScore 62: the module was first registered with a provisional floor of 50 (the minimum
+  // the ratchet test permits, tests/mutation-matrix-ratchet.test.cjs:107-116) because the shard
+  // cannot run locally (see HOW TO UPDATE above). The first CI measurement was 63.82% (CI run
+  // 36586350120, PR #5114), so the floor is set to floor(63.82) - 1 = 62, following this file's
+  // convention, together with its RATCHET_BASELINE entry.
+  'frontmatter-splice': {
+    cjs: 'gsd-core/bin/lib/frontmatter-splice.cjs',
+    extraTests: [
+      'frontmatter-fence.test.cjs',
+      'frontmatter.property.test.cjs',
+      'frontmatter.unit.test.cjs',
+    ],
+    minScore: 62,
+  },
   // adr-parser / config-schema / active-workstream-store / core-utils: derivation reproduces
   // their prior hand lists exactly (every constraining file's own name already matched the
   // "<module>*" rule) — no extraTests/excludeTests needed. Note config-schema in particular:
@@ -456,7 +498,10 @@ const COVERED = {
   },
   'core-utils': {
     cjs: 'gsd-core/bin/lib/core-utils.cjs',
-    minScore: 75,  // measured 77.52% (2026-06-14, issue #1187); floor = 77 - 2
+    // measured 77.52% (2026-06-14, issue #1187); floor = 77 - 2.
+    // CI job 109435636183 (PR #5114, #5105): measured 81.13%. Floor =
+    // floor(81.13) - 1 = 80.
+    minScore: 80,
   },
   // planning-inspect / plan-document / planning-command-router: net-new modules
   // added by #2790. Registered here so the Stryker gate stops SKIPPING them
@@ -484,7 +529,7 @@ const COVERED = {
   // PASSED — not a local run; mutation shards run `node --test`, hard-blocked
   // in this repo's local environment):
   //   planning-command-router 95.65% → floor 94  (already exceeds TARGET_MUTATION_SCORE (80))
-  //   plan-document            76.58% → floor 75
+  //   plan-document            76.58% → floor 75; then 81.16% → floor 80 (#5026 parity tests)
   //   planning-inspect         57.03% → floor 56  (well below TARGET (80) — ratchet
   //     candidate; comfortably clears its own floor but has real room to grow.
   //     Raise as its tests improve, never lower it.)
@@ -507,7 +552,7 @@ const COVERED = {
   'planning-inspect': {
     cjs: 'gsd-core/bin/lib/planning-inspect.cjs',
     excludeTests: ['planning-inspect.test.cjs'],
-    minScore: 56,
+    minScore: 72, // #5118: 73.70% in CI run 36676296090; floor(73.70) - 1
   },
   // plan-document / planning-command-router: their own names never appear in any test
   // filename (the shared dedicated unit file is named after planning-inspect, the module
@@ -516,7 +561,7 @@ const COVERED = {
   'plan-document': {
     cjs: 'gsd-core/bin/lib/plan-document.cjs',
     extraTests: ['planning-inspect.unit.test.cjs'],
-    minScore: 75,
+    minScore: 80,
   },
   'planning-command-router': {
     cjs: 'gsd-core/bin/lib/planning-command-router.cjs',

package/scripts/require-issue-link-policy.cjs

@@ -53,7 +53,10 @@ const DEPENDABOT_LOGIN = 'dependabot[bot]';
 // A follow-up-only PR (references an issue without closing it) is only
 // allowed to skip the closing keyword when every changed file is a test or
 // doc file — i.e. it cannot be the PR that actually implements the fix.
-const EXEMPT_PATH_PREFIXES = ['tests/', 'docs/'];
+// #5061: .out-of-scope/ knowledge-base entries are informational documents,
+// already doc-only in pre-pr-gate.sh's DOC_ONLY_RE. Only `*.md` entries
+// qualify there (see allPathsAreTestsOrDocs): the KB holds nothing else.
+const EXEMPT_PATH_PREFIXES = ['tests/', 'docs/', '.out-of-scope/'];
 
 // Root-level markdown is documentation — this mirrors the repo's own doc-only
 // classifier (.claude/hooks/pre-pr-gate.sh:111), whose `[^/]+\.md` anchor is
@@ -115,7 +118,7 @@ function normalizePath(p) {
 /**
  * Returns true iff every changed file qualifies as a test/doc file, i.e. each
  * one is one of:
- *   1. under one of EXEMPT_PATH_PREFIXES (`tests/`, `docs/`) — the trailing
+ *   1. under one of EXEMPT_PATH_PREFIXES (`tests/`, `docs/`, `.out-of-scope/`) — the trailing
  *      slash on each prefix makes this directory-boundary aware, so
  *      lookalikes like `tests-e2e/`, `testsuite/`, or `docsite/` are
  *      correctly rejected (they are not `tests/` or `docs/`); or
@@ -126,6 +129,7 @@ function allPathsAreTestsOrDocs(changedFiles) {
   if (!Array.isArray(changedFiles) || changedFiles.length === 0) return false;
   return changedFiles.every((file) => {
     const normalized = normalizePath(file);
+    if (normalized.startsWith('.out-of-scope/')) return /\.md$/i.test(normalized);
     if (EXEMPT_PATH_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true;
     return isRootLevelDoc(normalized);
   });

package/scripts/sync-runtime-launcher.cjs

@@ -272,6 +272,49 @@ function insertPreamble(lines, preamble) {
   return [...before, ...preamble, ...after];
 }
 
+/**
+ * The first two statements EVERY version of the launcher preamble opens with
+ * (`_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT=`). Matching the pair, not
+ * the bare `_GSD_SHIM_NAME=` prefix, means a prose sample or an intentionally
+ * different resolver that happens to start a line with the variable name is never
+ * mistaken for the preamble and never rewritten (#5169 review).
+ */
+const PREAMBLE_LINE_RE = /^_GSD_SHIM_NAME="gsd-tools\.cjs"; _GSD_RUNTIME_ROOT=/;
+
+/**
+ * Index of the line that starts a launcher preamble inside `lines`, or -1.
+ *
+ * Matched by the marker every version of the preamble opens with
+ * (`_GSD_SHIM_NAME=`), NOT by equality with the CURRENT text: the sync runs
+ * precisely when the snippet changed, so the copy in the file is by definition an
+ * older version, and an exact match never found it — which hoisted a guard-fronted
+ * preamble to the top of its block on every snippet change (#5169; caught by the
+ * #3861 guard-only extraction in tests/code-review-pipeline-regression.test.cjs).
+ */
+function findPreambleStart(lines) {
+  return lines.findIndex((l) => PREAMBLE_LINE_RE.test(l));
+}
+
+/**
+ * Place the preamble in a block that ALREADY carried it. A block that opens
+ * with a guard (a status check that must run before any launcher resolution,
+ * e.g. execute-phase/steps/code-review-disposition.md, #3861) keeps the preamble
+ * BEHIND that guard: hoisting it to the top would put the resolver ahead of the
+ * guard and change what the guard-only extraction in the tests runs. A block
+ * whose preamble already sits at the top (after blank lines), or that had none,
+ * takes the ordinary top insertion.
+ *
+ * The position is kept in STRIPPED coordinates: the lines before the preamble
+ * are stripped on their own and their length is the insertion point.
+ */
+function insertPreambleKeepingGuard(original, stripped, preamble) {
+  const k = findPreambleStart(original);
+  const firstContent = original.findIndex((l) => l.trim() !== '');
+  if (k <= firstContent) return insertPreamble(stripped, preamble);
+  const at = stripAndReplace(original.slice(0, k), preamble).length;
+  return [...stripped.slice(0, at), ...preamble, ...stripped.slice(at)];
+}
+
 /**
  * Transform a single markdown file's content.
  * Returns new content string, or null if no changes needed.
@@ -366,7 +409,9 @@ function transformFile(content, preamble) {
   const delegates = delegatesToResolverReference(content);
   const finalBlocks = strippedBlocks.map((stripped, bi) => {
     if (!delegates && bi === preambleTargetIdx) {
-      return insertPreamble(stripped, preamble);
+      const range = shellBlockRanges[bi];
+      const original = allLines.slice(range.contentStart, range.contentEnd);
+      return insertPreambleKeepingGuard(original, stripped, preamble);
     }
     return stripped;
   });
@@ -405,9 +450,137 @@ function delegatesToResolverReference(content) {
   return content.includes('references/gsd-run-resolver.md');
 }
 
+// ---------------------------------------------------------------------------
+// `_gsd_homes` — the launcher's runtime-home candidate list, DERIVED from the
+// runtime descriptors (#5169, ADR-5057 §5 "one resolver", #4347).
+//
+// The JS resolver (src/runtime-homes.cts) resolves a runtime's home from its
+// `configHome` descriptor. The shell launcher used to carry a hand-written copy
+// of that list and drifted (it still probed GEMINI_CONFIG_DIR after the runtime
+// was retired, and omitted zcode/pi/kimi). Both now read the same registry:
+// this renderer is the only producer of the `_gsd_homes` text in the snippet,
+// and tests/runtime-launcher-parity.test.cjs fails when the snippet differs
+// from it.
+// ---------------------------------------------------------------------------
+
+const HOMES_START = '_gsd_homes() { ';
+const HOMES_END = '; }; if _gsd_at';
+
+function shellHomeExpr(configHome) {
+  const dotHome = (rel) => `$HOME/${rel}`;
+  const withEnvs = (envs, fallback) => envs.reduceRight((acc, name) => `\${${name}:-${acc}}`, fallback);
+  switch (configHome.kind) {
+    case 'dot-home':
+      return [withEnvs(configHome.env, dotHome(configHome.name))];
+    case 'dot-home-nested': {
+      const probes = configHome.probe && configHome.probe.length > 0 ? configHome.probe : [configHome.name];
+      const first = withEnvs(configHome.env.slice(0, 1), dotHome(`${configHome.parent}/${probes[0]}`));
+      return [first, ...probes.slice(1).map((p) => dotHome(`${configHome.parent}/${p}`))];
+    }
+    case 'xdg': {
+      const xdgVar = configHome.env[2];
+      const base = xdgVar ? `\${${xdgVar}:-$HOME/.config}` : '$HOME/.config';
+      return [withEnvs(configHome.env.slice(0, 1), `${base}/${configHome.name}`)];
+    }
+    case 'generic-agents-root': {
+      const probes = configHome.probe.map((p) => p.replace(/^~/, '$HOME'));
+      return [withEnvs(configHome.env.slice(0, 1), probes[0]), ...probes.slice(1)];
+    }
+    default:
+      return []; // kind "none": no file-projected home, nothing to probe
+  }
+}
+
+/** The `_gsd_homes() { _gsd_at ...; }` text for a registry + legacy-home table. */
+function renderHomesFunction(registry, legacyHomes) {
+  const ids = Object.keys(registry.runtimes).sort((a, b) =>
+    a === 'claude' ? -1 : b === 'claude' ? 1 : a < b ? -1 : a > b ? 1 : 0);
+  const exprs = [];
+  for (const id of ids) {
+    const configHome = registry.runtimes[id].runtime && registry.runtimes[id].runtime.configHome;
+    if (configHome) exprs.push(...shellHomeExpr(configHome));
+  }
+  for (const id of Object.keys(legacyHomes).sort()) {
+    const legacy = legacyHomes[id];
+    exprs.push(`\${${legacy.env}:-$HOME/${legacy.dir.join('/')}}`);
+  }
+  // One loop over the homes, the `/gsd-core/bin/<shim>` suffix written once: the
+  // preamble is inlined into ~240 prompt files, several of which sit at a size cap.
+  // The homes are loaded into the FUNCTION's own positional parameters (`set --`
+  // is scoped to the function) and walked with `for _h; do`, not `for _h in <list>`:
+  // lint-workflow-shellcheck's #4109 structural check flags any `for x in` list that
+  // contains a `$`, without parsing the quoting around it.
+  const homes = [...new Set(exprs)].map((e) => `"${e}"`).join(' ');
+  return `${HOMES_START}set -- ${homes}; for _h; do _gsd_at "$_h/gsd-core/bin/\${_GSD_SHIM_NAME}" && return 0; done; return 1; }`;
+}
+
+/** Locate the `_gsd_homes` function text inside the snippet's single line. */
+function extractHomesFunction(snippetText) {
+  const start = snippetText.indexOf(HOMES_START);
+  const end = snippetText.indexOf(HOMES_END, start);
+  if (start === -1 || end === -1) return null;
+  return { start, end: end + '; }'.length, text: snippetText.slice(start, end + '; }'.length) };
+}
+
+function loadDerivedHomes() {
+  const registry = require('../gsd-core/bin/lib/capability-registry.cjs');
+  const { LEGACY_NON_REGISTRY_RUNTIME_HOMES } = require('../gsd-core/bin/lib/runtime-name-policy.cjs');
+  return renderHomesFunction(registry, LEGACY_NON_REGISTRY_RUNTIME_HOMES);
+}
+
+/** Rewrite the snippet's `_gsd_homes` from the descriptors. Returns true when it changed. */
+function refreshSnippetHomes() {
+  const raw = fs.readFileSync(SNIPPET_FILE, 'utf8');
+  const found = extractHomesFunction(raw);
+  if (!found) throw new Error('_runtime-launcher.snippet.sh has no _gsd_homes function to refresh');
+  const derived = loadDerivedHomes();
+  if (found.text === derived) return false;
+  fs.writeFileSync(SNIPPET_FILE, raw.slice(0, found.start) + derived + raw.slice(found.end), 'utf8');
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Files that carry the preamble as ONE line but are not transformed by
+// `transformFile` (it would move a per-block definition into the first block):
+//   - gsd-core/references/gsd-run-resolver.md — the @-included canonical copy,
+//     asserted byte-equal to the snippet;
+//   - commands/**/*.md — slash-command templates whose every bash block carries
+//     its own definition (each block is a separate shell), originally copied from
+//     an older fixed-list resolver that still probed the retired gemini home.
+// Every line that starts a resolver (PREAMBLE_LINE_RE) is replaced by the
+// canonical preamble line, so these copies are generated, not hand-kept (#5169).
+// ---------------------------------------------------------------------------
+const RESOLVER_REFERENCE = path.join(__dirname, '..', 'gsd-core', 'references', 'gsd-run-resolver.md');
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands');
+
+function replaceResolverLines(content, preambleLine) {
+  return content
+    .split('\n')
+    .map((line) => (PREAMBLE_LINE_RE.test(line) && line !== preambleLine ? preambleLine : line))
+    .join('\n');
+}
+
+function syncSingleLinePreambleFiles(preamble) {
+  if (preamble.length !== 1) throw new Error('the launcher preamble must be a single line to be inlined per block');
+  const files = [RESOLVER_REFERENCE, ...collectFiles(COMMANDS_DIR)];
+  let changed = 0;
+  for (const f of files) {
+    const content = fs.readFileSync(f, 'utf8');
+    const next = replaceResolverLines(content, preamble[0]);
+    if (next !== content) {
+      fs.writeFileSync(f, next, 'utf8');
+      changed++;
+      console.log(`transformed (preamble line): ${path.relative(path.join(__dirname, '..'), f)}`);
+    }
+  }
+  return changed;
+}
+
 // Main
 function main() {
+  if (refreshSnippetHomes()) console.log('refreshed _gsd_homes in _runtime-launcher.snippet.sh from the runtime descriptors');
   const preamble = loadPreamble();
+  syncSingleLinePreambleFiles(preamble);
 
   let transformedCount = 0;
   let unchangedCount = 0;
@@ -447,4 +620,13 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { transformFile };
+module.exports = {
+  transformFile,
+  loadPreamble,
+  renderHomesFunction,
+  extractHomesFunction,
+  loadDerivedHomes,
+  refreshSnippetHomes,
+  replaceResolverLines,
+  PREAMBLE_LINE_RE,
+};