@opengsd/gsd-core 1.20.0 → 1.21.0

package/gsd-core/bin/lib/gate-phase-context.cjs

@@ -31,7 +31,7 @@ const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
 const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspaceMod = require("./planning-workspace.cjs");
-const { planningDir } = planningWorkspaceMod;
+const { planningDir, planningRoot } = planningWorkspaceMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { phaseDirectoryOptions, findPhaseInternal, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
@@ -40,12 +40,24 @@ const roadmapModule = require("./roadmap.cjs");
 const { getRoadmapPhaseWithFallback } = roadmapModule;
 /**
  * Resolve a caller-supplied path (absolute, or relative to `projectDir`) and require the result to
- * stay inside `projectDir` (realpath containment, ADR-4650). Returns the contained path the
- * predicate produced, or a `GateUsageFailure` (`usage`, `path escapes its allowed directory: <arg>`).
+ * stay inside `projectDir` or inside the realpath of the project's OWN `.planning` (#5474: it may be
+ * a symlink to an out-of-repo store, so its phases realpath outside `projectDir`; ADR-5057 "Two
+ * containment roots"). Both decisions go through `tryWithinRoot` (realpath containment, ADR-4650);
+ * a symlink inside the store that leaves it, `..` traversal and a name-prefix sibling of the store
+ * still fail both. Returns the contained path the predicate produced, or a `GateUsageFailure`
+ * (`usage`, `path escapes its allowed directory: <arg>`).
+ *
+ * Trust assumption: the `.planning` link is trusted like the rest of the project tree. Whatever it
+ * resolves to becomes a containment root, so a `.planning` linked to a broad directory (a home
+ * directory, `/etc`) makes every path under that directory contained. This is accepted by design
+ * (#5474 scope): the link is part of the checkout the user chose to run gates on, and the gates
+ * read paths, they do not grant access the user's own shell lacks. Only the project's own
+ * `.planning` is honoured; any other symlink target is still refused.
  */
 function resolveContainedPath(inputPath, projectDir) {
     const candidate = node_path_1.default.isAbsolute(inputPath) ? inputPath : node_path_1.default.join(projectDir, inputPath);
-    const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+    const contained = (0, security_cjs_1.tryWithinRoot)(candidate, projectDir, security_cjs_1.PathAcceptance.AbsoluteInsideRoot) ??
+        (0, security_cjs_1.tryWithinRoot)(candidate, planningRoot(projectDir), security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
     if (contained === null) {
         return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, `path escapes its allowed directory: ${inputPath}`);
     }

package/gsd-core/bin/lib/graphify.cjs

@@ -14,6 +14,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- config-file-read.cjs is an export= CommonJS module
+const configFileReadMod = require("./config-file-read.cjs");
+const { readConfigFileBounded } = configFileReadMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { isCapabilityActive } = capabilityStateMod;
@@ -175,6 +178,20 @@ function safeReadJson(filePath) {
         return null;
     }
 }
+/**
+ * Safely read and parse `<planningDir>/config.json` as a bounded regular file (#5759). Returns
+ * null on a missing, non-regular (FIFO/device), oversized, unreadable or malformed file — never
+ * blocks. Not `safeReadJson`: that reader is for graph artifacts and opens blocking.
+ */
+function safeReadConfigJson(planningDir) {
+    try {
+        const raw = readConfigFileBounded(node_path_1.default.join(planningDir, 'config.json'));
+        return raw === null ? null : JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build a bidirectional adjacency map from graph nodes and edges.
  * Each node ID maps to an array of { target, edge } entries.
@@ -390,7 +407,7 @@ const SNAPSHOT_FILENAME = '.last-build-snapshot.json';
  * default `<planningDir>/graphs/graph.json` when unset/blank/non-string.
  */
 function resolveGraphLocation(cwd, planningDir) {
-    const config = safeReadJson(node_path_1.default.join(planningDir, 'config.json'));
+    const config = safeReadConfigJson(planningDir);
     const graphify = (config && config['graphify']);
     const configuredValue = graphify && graphify['graph_path'];
     if (typeof configuredValue === 'string' && configuredValue.trim().length > 0) {
@@ -564,7 +581,7 @@ function graphifyBuild(cwd) {
     const graphsDir = node_path_1.default.join(planningDir, 'graphs');
     node_fs_1.default.mkdirSync(graphsDir, { recursive: true });
     // Read build timeout from config -- default 300s per D-02
-    const config = safeReadJson(node_path_1.default.join(planningDir, 'config.json')) || {};
+    const config = safeReadConfigJson(planningDir) || {};
     const graphifyConfig = config.graphify;
     const timeoutSec = (graphifyConfig && graphifyConfig.build_timeout) || 300;
     return {

package/gsd-core/bin/lib/gsd-tool-dir.cjs

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Tool-owned `.gsd/` directory owner (#5757).
+ *
+ * gsd-core keeps small tool state under `<project>/.gsd/` (the dispatch
+ * isolation sentinel, the harness fork-probe cache). A user project does not
+ * inherit gsd-core's own root `.gitignore`, and the project may contain a
+ * `.gsd` symlink, so every writer needs the same two guarantees before it
+ * writes anything there:
+ *
+ *   1. the directory is a real directory that resolves inside the project
+ *      (never write through a project-supplied symlink or ancestor redirect);
+ *   2. the directory is ignored by git (`.gsd/.gitignore`), without clobbering
+ *      rules a user already put there.
+ *
+ * This module is the single owner of both. Callers pass their own ignore-file
+ * `marker` comment and the `rules` they need; the owner appends only the rules
+ * that are missing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GSD_IGNORE_SYMLINK = exports.GSD_DIR_UNSAFE = void 0;
+exports.ignoreAdditions = ignoreAdditions;
+exports.ensureToolOwnedGsdDir = ensureToolOwnedGsdDir;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const SYMLINK_IGNORE_MESSAGE = '.gsd/.gitignore is a symlink';
+/** Stable `code` values on the refusal errors; callers translate by code, never by message. */
+exports.GSD_DIR_UNSAFE = 'GSD_DIR_UNSAFE';
+exports.GSD_IGNORE_SYMLINK = 'GSD_IGNORE_SYMLINK';
+function codedError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function hasLine(text, line) {
+    return text.split('\n').some((l) => l.replace(/\r$/, '') === line);
+}
+/**
+ * Pure merge: the text to append to an existing ignore file so that `marker`
+ * and every rule are present, or '' when nothing is missing. A file that
+ * already ignores everything (`*` line) needs nothing.
+ */
+function ignoreAdditions(current, { marker, rules }) {
+    if (hasLine(current, '*'))
+        return '';
+    const missing = rules.filter((rule) => !hasLine(current, rule));
+    if (missing.length === 0)
+        return '';
+    const lead = current === '' || current.endsWith('\n') ? '' : '\n';
+    const markerLine = current.includes(marker) ? '' : `${marker}\n`;
+    return `${lead}${markerLine}${missing.join('\n')}\n`;
+}
+function isLinkError(err) {
+    const e = err;
+    return !!e && (e.code === 'ELOOP' || e.message === SYMLINK_IGNORE_MESSAGE);
+}
+function mergeExistingIgnore(ignorePath, options) {
+    let fd;
+    let tmpPath = null;
+    try {
+        if (node_fs_1.default.lstatSync(ignorePath).isSymbolicLink())
+            throw new Error(SYMLINK_IGNORE_MESSAGE);
+        // Read through an fd opened without following links where supported
+        // (O_NOFOLLOW is absent on Windows, hence `|| 0`), then replace by rename
+        // rather than append through the path, so a link swapped in after the
+        // check cannot redirect a write elsewhere.
+        fd = node_fs_1.default.openSync(ignorePath, node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NOFOLLOW || 0));
+        if (!node_fs_1.default.fstatSync(fd).isFile())
+            throw new Error('.gsd/.gitignore is not a regular file');
+        const current = node_fs_1.default.readFileSync(fd, 'utf8');
+        node_fs_1.default.closeSync(fd);
+        fd = undefined;
+        const additions = ignoreAdditions(current, options);
+        if (additions === '')
+            return;
+        // `tmpPath` is assigned only once the exclusive create succeeded, so an
+        // EEXIST never unlinks an entry this process did not create.
+        const candidateTmp = `${ignorePath}.tmp-${process.pid}-${node_crypto_1.default.randomBytes(6).toString('hex')}`;
+        const tmpFd = node_fs_1.default.openSync(candidateTmp, 'wx');
+        tmpPath = candidateTmp;
+        try {
+            node_fs_1.default.writeFileSync(tmpFd, current + additions);
+        }
+        finally {
+            node_fs_1.default.closeSync(tmpFd);
+        }
+        if (node_fs_1.default.lstatSync(ignorePath).isSymbolicLink())
+            throw new Error(SYMLINK_IGNORE_MESSAGE);
+        (0, shell_command_projection_cjs_1.retryRenameSync)(tmpPath, ignorePath);
+        tmpPath = null;
+    }
+    catch (err) {
+        if (isLinkError(err))
+            throw codedError(SYMLINK_IGNORE_MESSAGE, exports.GSD_IGNORE_SYMLINK);
+        // Ignore seeding is best-effort; the caller's state is still useful if
+        // this path cannot be read or updated.
+    }
+    finally {
+        if (fd !== undefined)
+            node_fs_1.default.closeSync(fd);
+        if (tmpPath) {
+            try {
+                node_fs_1.default.unlinkSync(tmpPath);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}
+/**
+ * Ensure `<cwd>/.gsd` exists as a real, project-contained, git-ignored
+ * directory and return its path. Throws when `.gsd` is a symlink, resolves
+ * outside the project, or `.gsd/.gitignore` is a symlink.
+ */
+function ensureToolOwnedGsdDir(cwd, options) {
+    const dir = node_path_1.default.join(cwd, '.gsd');
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    if (node_fs_1.default.lstatSync(dir).isSymbolicLink() ||
+        node_path_1.default.relative(node_fs_1.default.realpathSync(cwd), node_fs_1.default.realpathSync(dir)) !== '.gsd') {
+        throw codedError('.gsd directory is a symlink or resolves outside the project', exports.GSD_DIR_UNSAFE);
+    }
+    const ignorePath = node_path_1.default.join(dir, '.gitignore');
+    try {
+        node_fs_1.default.writeFileSync(ignorePath, '*\n', { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            mergeExistingIgnore(ignorePath, options);
+        // Any other ignore-file IO failure must not prevent the caller's write.
+    }
+    return dir;
+}

package/gsd-core/bin/lib/health-diagnostic.cjs

@@ -324,7 +324,11 @@ function runRepairAction(cwd, action, paths, args = {}) {
         case REMEDY_ACTION.ADD_NYQUIST_KEY:
         case REMEDY_ACTION.ADD_AI_INTEGRATION_PHASE_KEY: {
             const key = action === REMEDY_ACTION.ADD_NYQUIST_KEY ? 'nyquist_validation' : 'ai_integration_phase';
-            const configRaw = node_fs_1.default.readFileSync(configPath, 'utf-8');
+            // Bounded read (#5759): a FIFO/device/oversized config throws (the repair fails, never blocks).
+            const configRaw = configLoaderMod.readConfigFileBounded(configPath);
+            if (configRaw === null) {
+                throw Object.assign(new Error(`ENOENT: no such file or directory, open '${configPath}'`), { code: 'ENOENT' });
+            }
             const configParsed = JSON.parse(configRaw);
             if (!configParsed['workflow'])
                 configParsed['workflow'] = {};

package/gsd-core/bin/lib/init.cjs

@@ -48,7 +48,7 @@ const secrets_cjs_1 = require("./secrets.cjs");
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-document.cjs is an export= CommonJS module
 const planDocument = require("./plan-document.cjs");
-const state_document_cjs_1 = require("./state-document.cjs");
+const state_transition_cjs_1 = require("./state-transition.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const host_runtime_detection_cjs_1 = require("./host-runtime-detection.cjs");
 const security_cjs_1 = require("./security.cjs");
@@ -99,7 +99,7 @@ const { resolveModelInternal, resolveGranularityInternal, assertValidGranularity
 const { phaseDirectoryOptions, findPhaseInternal, listMilestonePhaseDirs, listAllPhaseDirs, } = phaseLocator;
 const { getRoadmapPhaseInternal, getMilestoneInfo, stripShippedMilestones, extractCurrentMilestone, } = roadmapParser;
 const { pathExistsInternal, generateSlugInternal, toPosixPath } = coreUtils;
-const { comparePhaseNum, phaseDirectoryName, customPhaseQuery, customDirectoryOwner, phaseScanTokenSource, phaseKeyFromToken, phaseDirectoryContext, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, extractPhaseDependencyTokens, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, bracketQualifiedKey, phaseHeadingPrefixSrcFor, parsePhaseChecklistLine, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
+const { comparePhaseNum, phaseDirectoryName, customPhaseQuery, customDirectoryOwner, phaseScanTokenSource, phaseNumberTokenSource, phaseKeyFromToken, phaseDirectoryContext, normalizePhaseName, stripProjectCodePrefix, PHASE_NUMBER_TOKEN_SOURCE, PHASE_DEP_REF_SOURCE, extractPhaseDependencyTokens, isForeignPrefixedPhaseQuery, isSentinelPhaseId, extractPhaseToken, scopeToPhase, renderPhaseBranchName, parsePhaseId, renderPhaseId, bracketQualifiedKey, phaseHeadingPrefixSrcFor, parsePhaseChecklistLine, PHASE_HEADING_BASELINE, buildPhaseHeadingScanRegex, } = phaseId;
 const { phaseToken } = phaseIdDisplayMod;
 const { pruneOrphanedWorktrees } = worktreeSafety;
 const { planningPaths, planningDir, planningRoot, todosDir, listAvailableWorkstreams, peekActiveWorkstream, resolveEnvWorkstream, diagnoseUnresolvedActiveWorkstream, describeUnresolvedWorkstreamReason, findContextMdIn, findPhaseSpecIn, resolvePhaseIdConvention, worktreesOptedOut, } = planningWorkspace;
@@ -540,7 +540,10 @@ function detectHasPriorPhases(cwd, phaseInfo) {
  */
 function readConfigJsonBoolean(cwd, keyPath) {
     try {
-        const raw = node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'config.json'), 'utf8');
+        // Bounded read (#5759): a FIFO/device/oversized config throws and degrades to false below.
+        const raw = configLoader.readConfigFileBounded(node_path_1.default.join(planningDir(cwd), 'config.json'));
+        if (raw === null)
+            return false;
         let cursor = JSON.parse(raw);
         for (const segment of keyPath) {
             if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor))
@@ -576,7 +579,10 @@ function readNonEmptyFileOrNull(filePath) {
  */
 function readConfigJsonValue(cwd, keyPath) {
     try {
-        const raw = node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'config.json'), 'utf8');
+        // Bounded read (#5759): a FIFO/device/oversized config throws and degrades to undefined below.
+        const raw = configLoader.readConfigFileBounded(node_path_1.default.join(planningDir(cwd), 'config.json'));
+        if (raw === null)
+            return undefined;
         let cursor = JSON.parse(raw);
         for (const segment of keyPath) {
             if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor))
@@ -1058,8 +1064,7 @@ function cmdInitExecutePhase(cwd, phase, raw, options = {}) {
                 const stateWarnings = [];
                 if (phaseInfo?.['directory'] && node_fs_1.default.existsSync(node_path_1.default.join(cwd, phaseInfo['directory']))) {
                     const diskPlans = listPhasePlanFiles(node_path_1.default.join(cwd, phaseInfo['directory'])).length;
-                    const totalPlansRaw = (0, state_document_cjs_1.stateExtractField)(stateContent, 'Total Plans in Phase');
-                    const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+                    const totalPlansInPhase = (0, state_transition_cjs_1.readRecordedPlanTotal)(stateContent);
                     if (totalPlansInPhase !== null && diskPlans !== totalPlansInPhase) {
                         stateWarnings.push(`Plan count mismatch: STATE.md says ${totalPlansInPhase}, disk has ${diskPlans}`);
                     }
@@ -1286,8 +1291,7 @@ function cmdInitPlanPhase(cwd, phase, raw, options = {}) {
             if (stateContent !== null) {
                 const stateWarnings = [];
                 result['state_validation_ran'] = true;
-                const totalPlansRaw = (0, state_document_cjs_1.stateExtractField)(stateContent, 'Total Plans in Phase');
-                const totalPlansInPhase = totalPlansRaw ? parseInt(totalPlansRaw, 10) : null;
+                const totalPlansInPhase = (0, state_transition_cjs_1.readRecordedPlanTotal)(stateContent);
                 if (totalPlansInPhase !== null &&
                     phaseInfo &&
                     totalPlansInPhase !==
@@ -2626,7 +2630,7 @@ function cmdInitManager(cwd, raw) {
         }
     }
     // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${phaseScanTokenSource(directoryContext)})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
+    const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefix}(${phaseScanTokenSource(directoryContext, phaseIdConvention)})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:\\s*([^\\n]+)`, 'gi');
     const phases = [];
     const bracketIdsByPhaseNumber = new Map();
     let match;
@@ -2635,9 +2639,7 @@ function cmdInitManager(cwd, raw) {
         const phaseNum = capturesBracketId ? match[2] : match[1];
         if (bracketId)
             bracketIdsByPhaseNumber.set(phaseNum, bracketId);
-        const phaseName = (capturesBracketId ? match[3] : match[2])
-            .replace(/\(INSERTED\)/i, '')
-            .trim();
+        const phaseName = (0, phase_entry_grammar_cjs_1.stripInsertedMarker)(capturesBracketId ? match[3] : match[2]);
         let displayId;
         if (bracketId) {
             try {
@@ -2650,7 +2652,7 @@ function cmdInitManager(cwd, raw) {
         }
         const sectionStart = match.index;
         const restOfContent = content.slice(sectionStart);
-        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}${phaseScanTokenSource(directoryContext)}`, 'i'));
+        const nextHeader = restOfContent.match(new RegExp(`\\n#{2,4}\\s+${phaseHeadingPrefixNoCapture}${phaseScanTokenSource(directoryContext, phaseIdConvention)}`, 'i'));
         const sectionEnd = nextHeader
             ? sectionStart + nextHeader.index
             : content.length;
@@ -2849,7 +2851,7 @@ function cmdInitManager(cwd, raw) {
     }
     else {
         // Preserve the historical greedy non-bracket fallback byte-for-byte.
-        const _allCompletedPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`.*${phaseHeadingPrefixNoCapture}(${PHASE_NUMBER_TOKEN_SOURCE})[:\\s]`, 'gi');
+        const _allCompletedPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`.*${phaseHeadingPrefixNoCapture}(${phaseNumberTokenSource(phaseIdConvention)})[:\\s]`, 'gi');
         let _allMatch;
         while ((_allMatch = _allCompletedPattern.exec(rawContent)) !== null) {
             if (!(0, phase_entry_grammar_cjs_1.isPhaseEntryChecked)(_allMatch[0]))
@@ -3433,9 +3435,9 @@ function cmdInitProgress(cwd, raw, options = {}) {
     const roadmapPhaseNums = new Set();
     const roadmapPhaseNames = new Map();
     const roadmapCheckboxStates = new Map();
+    const progressConvention = resolvePhaseIdConvention(cwd);
     try {
         const roadmapContent = extractCurrentMilestone(node_fs_1.default.readFileSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'), 'utf-8'), cwd);
-        const progressConvention = resolvePhaseIdConvention(cwd);
         // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag, owned by
         // buildPhaseHeadingScanRegex (phase-id.cts) so this scan also recognizes
         // bracket-convention headings instead of hand-rolling a literal `Phase\s+`.
@@ -3443,7 +3445,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         let hm;
         while ((hm = headingPattern.exec(roadmapContent)) !== null) {
             roadmapPhaseNums.add(hm[hNumGroup]);
-            roadmapPhaseNames.set(hm[hNumGroup], hm[hNameGroup].replace(/\(INSERTED\)/i, '').trim());
+            roadmapPhaseNames.set(hm[hNumGroup], (0, phase_entry_grammar_cjs_1.stripInsertedMarker)(hm[hNameGroup]));
         }
         // #4906 Phase 5 (#4984): NOT migrated onto phaseHeadingPrefixSrcFor — same
         // out-of-scope reasoning as roadmapPhaseMatchesExactPrefix/detectPhaseMvpMode
@@ -3472,7 +3474,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // matched (by absorbing the bracket text). This does NOT migrate the site
         // onto phaseHeadingPrefixSrcFor / the bracket convention — that stays
         // out of scope per the comment above (#4984 revert, pinned census).
-        const cbPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${phaseScanTokenSource(directoryContext)})[:\\s]`, 'gim', { state: 'captured' });
+        const cbPattern = (0, phase_entry_grammar_cjs_1.phaseEntryRegExp)(`(?:\\[[^\\]\\n]{0,200}\\]\\s*)?Phase\\s+(${phaseScanTokenSource(directoryContext, progressConvention)})[:\\s]`, 'gim', { state: 'captured' });
         let cbm;
         while ((cbm = cbPattern.exec(roadmapContent)) !== null) {
             const cbKey = cbm[2];
@@ -3494,7 +3496,7 @@ function cmdInitProgress(cwd, raw, options = {}) {
         // behavior-preserving).
         const dirs = listMilestonePhaseDirs(phasesDir, { cwd }).value;
         for (const dir of dirs) {
-            const dirMatch = dir.match(new RegExp(`^(${phaseScanTokenSource(directoryContext)})-?(.*)`, 'i'));
+            const dirMatch = dir.match(new RegExp(`^(${phaseScanTokenSource(directoryContext, progressConvention)})-?(.*)`, 'i'));
             const query = customPhaseQuery(dir, directoryContext);
             const owner = query && customDirectoryOwner(dir, query);
             const phaseNumber = owner ? owner.id : dirMatch ? dirMatch[1] : dir;

package/gsd-core/bin/lib/install-effort-resolver.cjs

@@ -36,9 +36,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- config-file-read.cjs is an export= CommonJS module
+const configFileReadMod = require("./config-file-read.cjs");
+const { unboundedConfigFileReason, printablePath, readConfigFileBounded } = configFileReadMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- install-fs-adapter.cjs is an export= CommonJS module
 const installFsAdapter = require("./install-fs-adapter.cjs");
-const { installFs } = installFsAdapter;
+const { installFs, isRealInstallFs } = installFsAdapter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
 const modelResolver = require("./model-resolver.cjs");
 const { EFFORT_SET: GSD_EFFORT_SET } = modelResolver;
@@ -54,19 +57,36 @@ const { mergeEffortTierDefaults } = modelCatalog;
 function _readGsdConfigFile(absPath, label) {
     if (!installFs().existsSync(absPath))
         return null;
+    // #5759: refuse a FIFO/device/socket or an oversized file BEFORE the adapter's blocking read
+    // (shared guard; a path that is not on the real fs is left to the adapter).
     let raw;
     try {
-        raw = installFs().readFileSync(absPath, 'utf-8');
+        if (isRealInstallFs()) {
+            // The real fs: the descriptor-bound reader (non-blocking open, fstat, cap).
+            const text = readConfigFileBounded(absPath);
+            if (text === null)
+                return null;
+            raw = text;
+        }
+        else {
+            // An injected adapter cannot give a descriptor: stat the real path first (best effort).
+            const unbounded = unboundedConfigFileReason(absPath);
+            if (unbounded !== null) {
+                process.stderr.write(`gsd: warning — could not read ${label} (${printablePath(absPath)}): ${unbounded}\n`);
+                return null;
+            }
+            raw = installFs().readFileSync(absPath, 'utf-8');
+        }
     }
     catch (err) {
-        process.stderr.write(`gsd: warning — could not read ${label} (${absPath}): ${err.message}\n`);
+        process.stderr.write(`gsd: warning — could not read ${label} (${printablePath(absPath)}): ${printablePath(err.message)}\n`);
         return null;
     }
     try {
         return JSON.parse(raw);
     }
     catch (err) {
-        process.stderr.write(`gsd: warning — invalid JSON in ${label} (${absPath}): ${err.message}\n`);
+        process.stderr.write(`gsd: warning — invalid JSON in ${label} (${printablePath(absPath)}): ${printablePath(err.message)}\n`);
         return null;
     }
 }

package/gsd-core/bin/lib/install-engine.cjs

@@ -122,7 +122,7 @@ function pruneEmptyCorpusParents(start, stop) {
 }
 function syncRuntimeSurfaceCorpus(source, destination, configDir, manifestPrefix) {
     if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), destination, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-        throw new Error(`syncRuntimeSurfaceCorpus: destination "${destination}" contains a symlink the install root "${configDir}" does not trust — refusing to write.`);
+        throw new Error(runtimeArtifactInstallPlan.syncRuntimeSurfaceCorpusSymlinkRefusalMessage(destination, configDir));
     }
     assertCorpusTreeHasNoSymlinks(destination);
     // Remove only paths the previous manifest proves GSD owned and which the
@@ -160,15 +160,7 @@ function syncRuntimeSurfaceCorpus(source, destination, configDir, manifestPrefix
  * The compatibility marker does not replace that installed-corpus authority.
  */
 function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
-    const required = new Set();
-    if ((0, install_scope_cjs_1.isGlobalScope)(scope)) {
-        for (const kind of layout.kinds) {
-            if (kind.kind === 'commands' || kind.kind === 'skills')
-                required.add('commands');
-            if (kind.kind === 'agents' || kind.kind === 'kimi-agents')
-                required.add('agents');
-        }
-    }
+    const required = runtimeArtifactInstallPlan.requiredRuntimeSurfaceSources(layout, scope);
     if (required.size === 0)
         return;
     const corpusRoot = node_path_1.default.join(configDir, 'gsd-core');
@@ -229,11 +221,8 @@ const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
  * with the computed pathPrefix for the install.
  */
 function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
-    content = content.replace(/~\/\.claude\//g, pathPrefix);
-    content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
-    content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
-    content = content.replace(/~\/\.opencode\//g, pathPrefix);
-    content = content.replace(/~\/\.kilo\//g, pathPrefix);
+    // #5715: one pass with literal replacement (see rewriteOpencodeFamilyConfigDirForms).
+    content = runtimeArtifactConversion._rewriteOpencodeFamilyConfigDirForms(content, pathPrefix, getDirName(runtime));
     // #5637: the typed-text capture heredoc ends at a terminator the typed text cannot know.
     return (0, args_terminator_cjs_1.stampInstalledContent)(content);
 }
@@ -560,7 +549,7 @@ function _resolveDevPreferencesSkillTarget(targetDir, runtime, scope = 'global')
         // legacy dev-preferences migration lands in the SAME tree the installer
         // and surface-apply use. Runtimes with no `home` override are unaffected.
         hasHomeOverride = skillsKindEntry.home != null;
-        installRoot = skillsKindEntry.home ?? targetDir;
+        installRoot = runtimeArtifactInstallPlan.resolveRuntimeArtifactInstallRoot(targetDir, skillsKindEntry);
         skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, skillsKindEntry.destSubpath), stemName);
     }
     else {
@@ -669,7 +658,7 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
     // that case this defense-in-depth check must confine against the resolved
     // alternate root instead, matching the upstream gate's own root selection in
     // createRuntimeArtifactInstallPlan.
-    const installRoot = (kind && typeof kind.home === 'string' && kind.home !== '') ? kind.home : configDir;
+    const installRoot = runtimeArtifactInstallPlan.resolveRuntimeArtifactInstallRoot(configDir, kind);
     // Strict-subpath + NUL containment via the canonical gate (shared with the
     // layout-driven install plan); throws if destDir escapes the install root.
     // destDir here is an absolute path; path.resolve(installRoot, absoluteDest) returns it unchanged, so the gate's strict-subpath check still correctly confines it to installRoot.
@@ -1303,7 +1292,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // previously lived inline in bin/install.js.
         const behaviors = hostBehaviorsFor(runtime);
         const projectDir = scope === 'global' ? process.cwd() : configDir;
-        if (behaviors.combinedFamilyInstall) {
+        if (runtimeArtifactInstallPlan.shouldInstallCombinedFamily(behaviors)) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
             // _runLegacyInstallMigrations below entirely (early return), so their
             // legacy-directory cleanup needs its own pre-materialization hook here.
@@ -1381,12 +1370,12 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                 // A fake adapter can change what those probes observe for paths that
                 // were never real to begin with; it cannot make this `if` pass for a
                 // path the real filesystem would refuse.
-                const installRoot = (kind && typeof kind.home === 'string' && kind.home !== '') ? kind.home : configDir;
+                const installRoot = runtimeArtifactInstallPlan.resolveRuntimeArtifactInstallRoot(configDir, kind);
                 // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
                 // Threat model from #1704 / ADR-1239 Phase B preserved: path-traversal and
                 // resolved-target-equals-root still refuse regardless of opt-in.
                 if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), dest, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-                    throw new Error(`installRuntimeArtifacts: destDir "${dest}" contains a symlink the install root "${installRoot}" does not trust — refusing to create. If this is an intentional user-owned symlink layout (e.g. externalized skills/hooks dir, multi-account configHome, or a dotfiles-managed configHome), re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
+                    throw new Error(runtimeArtifactInstallPlan.installRuntimeArtifactsSymlinkRefusalMessage(dest, installRoot));
                 }
                 // #2875 defect fix (--minimal regression closed): a restricted profile
                 // (e.g. --minimal) can legitimately stage ZERO agents — no skill in
@@ -1580,6 +1569,7 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
     if (!skillsKindEntry)
         return 0;
+    const installRoot = runtimeArtifactInstallPlan.resolveRuntimeArtifactInstallRoot(targetDir, skillsKindEntry);
     // #3712: combined-family runtimes take installRuntimeArtifacts' early return
     // BEFORE its guard runs, and this writer honors `skillsKindEntry.home` below and
     // then prunes that destination. opencode/kilo declare no `home` today, so there
@@ -1606,13 +1596,12 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     // OpenCode/Kilo writer lands in the SAME tree the installer and surface-apply use.
     // Runtimes with no `home` override (opencode, kilo today) are unaffected. Must stay
     // in lockstep with the sibling writers — the destination-parity test enforces it.
-    const installRoot = skillsKindEntry.home ?? targetDir;
     const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, skillsKindEntry.destSubpath);
     // Symlink-escape guard: reject if any path component between installRoot and
     // dest is a symlink that would redirect writes outside the install root.
     // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
     if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), dest, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-        throw new Error(`installOpencodeFamilySkills: destDir "${dest}" contains a symlink the install root "${installRoot}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
+        throw new Error(runtimeArtifactInstallPlan.installOpencodeFamilySkillsSymlinkRefusalMessage(dest, installRoot));
     }
     installFs().mkdirSync(dest, { recursive: true });
     // Preserve user-owned GSD-prefixed skill dirs across the gsd-* prune.
@@ -1653,7 +1642,8 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
         let content = installFs().readFileSync(node_path_1.default.join(rawDir, entry.name), 'utf8');
         content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
         content = processAttribution(content, resolveAttribution(runtime));
-        content = converter(content, skillName);
+        // #5715: the converter runs after the prefix pass; shield the emitted prefix from it.
+        content = runtimeArtifactConversion._shieldEmittedPrefix(content, pathPrefix, (c) => converter(c, skillName));
         const skillDir = node_path_1.default.join(dest, skillName);
         installFs().mkdirSync(skillDir, { recursive: true });
         installFs().writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
@@ -1800,14 +1790,14 @@ function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile,
     const stagedAgentFiles = installFs().existsSync(stagedDir)
         ? installFs().readdirSync(stagedDir).filter((f) => f.endsWith('.md'))
         : [];
-    const installRoot = (typeof agentsKindEntry.home === 'string' && agentsKindEntry.home !== '') ? agentsKindEntry.home : targetDir;
+    const installRoot = runtimeArtifactInstallPlan.resolveRuntimeArtifactInstallRoot(targetDir, agentsKindEntry);
     const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, agentsKindEntry.destSubpath);
     // Symlink-escape guard — same gate _copyStaged/installOpencodeFamilySkills apply
     // to their own writes (#2393 GSD_ALLOW_SYMLINKED_DEST opt-in preserved). Runs
     // even when nothing will be written this call — the stale-agent prune below
     // (`_removeGsdEntries`) still touches `dest` whenever it already exists.
     if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), dest, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-        throw new Error(`installAgentsKindStandalone: destDir "${dest}" contains a symlink the install root "${installRoot}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
+        throw new Error(runtimeArtifactInstallPlan.installAgentsKindStandaloneSymlinkRefusalMessage(dest, installRoot));
     }
     // #2875 defect fix, corrected: the ORIGINAL fix returned `null` (no-op)
     // whenever a restricted profile (e.g. --minimal) staged ZERO agents,
@@ -1881,9 +1871,11 @@ function installOpencodeFamilyCommands(runtime, destDir, srcDir, pathPrefix, res
             // already satisfies the fold-to-descriptor requirement. Only the SKILLS
             // converter site above (installOpencodeFamilySkills) has a real
             // `converter` string to key on via SKILLS_CONVERTER_REGISTRY.
-            content = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
-                ? runtimeArtifactConversion.convertClaudeToKiloFrontmatter(content)
-                : runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(content);
+            // #5715: the converter runs after the prefix pass; shield the emitted prefix from it.
+            const frontmatterConverter = hostBehaviorsFor(runtime).frontmatterDialect === 'kilo'
+                ? (c) => runtimeArtifactConversion.convertClaudeToKiloFrontmatter(c)
+                : (c) => runtimeArtifactConversion.convertClaudeToOpencodeFrontmatter(c);
+            content = runtimeArtifactConversion._shieldEmittedPrefix(content, pathPrefix, frontmatterConverter);
             installFs().writeFileSync(node_path_1.default.join(destDir, destName), content);
         }
     }

package/gsd-core/bin/lib/install-fs-adapter.cjs

@@ -259,4 +259,8 @@ function mkInstallTempDir(prefix) {
     installFs().mkdirSync(dir, { recursive: true });
     return dir;
 }
-module.exports = { installFs, withInstallFs, mkInstallTempDir };
+/** True when no fake adapter is active, i.e. installFs() is the real `node:fs` (#5759). */
+function isRealInstallFs() {
+    return current === REAL_ADAPTER;
+}
+module.exports = { installFs, withInstallFs, mkInstallTempDir, isRealInstallFs };