@opengsd/gsd-core 1.18.0 → 1.20.0

package/gsd-core/bin/lib/runtime-hooks-surface.cjs

@@ -1264,10 +1264,10 @@ function configuredEntrypointsForHook(configDir, hookName, opts) {
     const bash = resolveBashExecutable(opts);
     if (isShellHook) {
         // An unresolved bash must still surface as an interpreterCandidates entry
-        // (the literal token, same as the portableHooks runner below) so
+        // (the sentinel token, same as the portableHooks runner below) so
         // validateConfiguredEntrypoints reports 'unresolved-interpreter' instead
         // of silently skipping the check because the field is absent.
-        return [{ ...target, interpreterCandidates: [bash === null ? 'bash' : bash] }];
+        return [{ ...target, interpreterCandidates: [bash === null ? UNRESOLVED_BASH_SENTINEL : bash] }];
     }
     // #4249: check the SAME stable alias buildNodeRunnerChainToken bakes as its
     // first candidate (normalizeNodePath rewrites a version-manager shim like
@@ -1287,7 +1287,7 @@ function configuredEntrypointsForHook(configDir, hookName, opts) {
         runtime,
         configPath,
         scriptPath: node_path_1.default.join(configDir, 'hooks', NODE_RUNNER_RESOLVER_HOOK),
-        interpreterCandidates: bash === null ? ['bash'] : [bash],
+        interpreterCandidates: bash === null ? [UNRESOLVED_BASH_SENTINEL] : [bash],
         platform,
     };
     return [runner, { ...target, interpreterCandidates: nodeCandidates }];
@@ -1298,6 +1298,15 @@ function recordConfiguredHookCommand(command, configDir, hookName, opts) {
     }
     return command;
 }
+// #5100: the two null-runner branches of buildHookCommand share this. No
+// command was ever built, so track() (which needs one) cannot record the
+// hook — push the entry directly instead, so the gate sees it rather than
+// the hook going silently unregistered.
+function recordUnresolvedBashEntrypoint(configDir, hookName, opts) {
+    if (opts.configuredEntrypoints) {
+        opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
+    }
+}
 function buildHookCommand(configDir, hookName, opts) {
     if (!opts)
         opts = {};
@@ -1323,15 +1332,9 @@ function buildHookCommand(configDir, hookName, opts) {
         const runner = resolveBashRunner(opts);
         if (runner === null) {
             // #4249 (antigravity review): this early return skips `track()` below,
-            // so an unresolved bash on win32 (no Git Bash found) previously left
-            // this hook silently unregistered with nothing for
-            // validateConfiguredEntrypoints to reject — configuredEntrypointsForHook's
-            // own 'unresolved bash must still surface' comment describes intent this
-            // return never reached. Push the entry directly (no `command`, since
-            // none was ever built) so the gate actually sees it.
-            if (opts.configuredEntrypoints) {
-                opts.configuredEntrypoints.push(...configuredEntrypointsForHook(configDir, hookName, opts));
-            }
+            // which needs a command that was never built — record the entry
+            // directly so the gate can reject it.
+            recordUnresolvedBashEntrypoint(configDir, hookName, opts);
             return null;
         }
         if (opts.portableHooks) {
@@ -1374,9 +1377,13 @@ function buildHookCommand(configDir, hookName, opts) {
             configDir,
             homeDir: node_os_1.default.homedir(),
         });
-        // Absolute Git-Bash discovery on win32 when available (#580); `bash` on
-        // PATH otherwise — the same assumption .sh hooks already make.
-        const resolverRunner = resolveBashRunner(opts) || 'bash';
+        // #5100: same contract as the .sh early return. A bare `bash` is how
+        // win32 reaches WSL's System32 launcher, and the gate used to accept it.
+        const resolverRunner = resolveBashRunner(opts);
+        if (resolverRunner === null) {
+            recordUnresolvedBashEntrypoint(configDir, hookName, opts);
+            return null;
+        }
         return track(shellCmdProjection.projectShellCommandText({
             runnerToken: resolverRunner,
             argTokens: [
@@ -2158,6 +2165,9 @@ const SETTINGS_JSON_HOOK_ROWS = deepFreeze([
     // Guard: only register if the hook file was actually installed (#1754, #1817).
     { file: 'gsd-check-update.js', event: 'SessionStart', command: { opts: 'updateCheckCommand' },
         configuredMessage: 'Configured update check hook', skipLabel: 'update check hook' },
+    // #5465: persists the gsd-core bin directory on PATH through $CLAUDE_ENV_FILE (SessionStart-only).
+    { file: 'gsd-path-export.js', event: 'SessionStart', timeout: 5, command: { build: 'js' },
+        configuredMessage: 'Configured PATH persistence hook', skipLabel: 'PATH persistence hook' },
     { file: 'gsd-context-monitor.js', event: 'post', matcher: 'Bash|Edit|Write|MultiEdit|Agent|Task', timeout: 10,
         command: { opts: 'contextMonitorCommand' },
         configuredMessage: 'Configured context window monitor hook', skipLabel: 'context monitor hook',
@@ -2710,6 +2720,30 @@ function referencesHook(h, hookName) {
         (Array.isArray(args) && args.some(a => typeof a === 'string' && a.includes(hookName))) ||
         (typeof url === 'string' && url.includes(hookName));
 }
+// #5100: the writer emits the bare `bash` token when the Git Bash policy
+// finds nothing, and the gate resolves that token through the same policy —
+// never a PATH scan. One shared definition so the two sides cannot drift.
+const UNRESOLVED_BASH_SENTINEL = 'bash';
+const WIN32_BARE_BASH_TOKENS = [UNRESOLVED_BASH_SENTINEL, 'bash.exe'];
+function isWin32BareBashToken(candidate, platform) {
+    if ((platform || process.platform) !== 'win32')
+        return false;
+    // Equality already rejects any path: a string holding a separator can never
+    // equal a bare token, so no explicit separator guard is needed here.
+    return WIN32_BARE_BASH_TOKENS.includes(candidate.trim().toLowerCase());
+}
+// #5100: the literal `bash` sentinel means "Git Bash policy found nothing"
+// (#4249). Resolve that token through resolveBashExecutable, never a PATH
+// scan — WSL's System32\bash.exe is on PATH and cannot see Windows paths.
+function win32BareBashResolves(candidate, platform, deps) {
+    if (!isWin32BareBashToken(candidate, platform))
+        return null;
+    return resolveBashExecutable({
+        platform: 'win32',
+        env: deps.env,
+        existsSync: deps.existsSync,
+    }) !== null;
+}
 function validateConfiguredEntrypoints(entries, deps = {}) {
     const statSync = deps.statSync ?? node_fs_1.default.statSync;
     const accessSync = deps.accessSync ?? node_fs_1.default.accessSync;
@@ -2766,7 +2800,12 @@ function validateConfiguredEntrypoints(entries, deps = {}) {
                 invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'script', path: entry.scriptPath, reason: 'not-executable' });
             }
         }
-        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null)) {
+        if (entry.interpreterCandidates && !entry.interpreterCandidates.some(candidate => {
+            const bareBash = win32BareBashResolves(candidate, entry.platform, deps);
+            if (bareBash !== null)
+                return bareBash;
+            return resolve(candidate, { platform: entry.platform, requireExecutable: true }) !== null;
+        })) {
             invalid.push({ runtime: entry.runtime, configPath: entry.configPath, role: 'interpreter', path: entry.interpreterCandidates.join(' | '), reason: 'unresolved-interpreter' });
         }
     }
@@ -2856,6 +2895,11 @@ module.exports = {
     resolveBashExecutable,
     resolveBashRunner,
     NODE_RUNNER_RESOLVER_HOOK,
+    // #5100: the literal the writer records for an unresolved Git Bash and the
+    // gate resolves through the Git Bash policy. Exported so a consumer that
+    // needs to recognise that entry imports it rather than respelling it;
+    // bin/install.js keys on the entry having no command instead.
+    UNRESOLVED_BASH_SENTINEL,
     // Atomic write seam (shared with bin/install.js so all writes participate
     // in install.js's _cleanTmpFiles() scoped temp-cleanup).
     atomicWriteFileSync,

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -15,7 +15,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PATH_ACTION_REASON = void 0;
+exports.scrubGitLocationEnv = exports.GIT_LOCATION_ENV_VARS = exports.PATH_ACTION_REASON = void 0;
 exports.toPosixPath = toPosixPath;
 exports.toNativePath = toNativePath;
 exports.posixNormalize = posixNormalize;
@@ -37,6 +37,7 @@ exports.projectCodexHookTomlCommand = projectCodexHookTomlCommand;
 exports.escapePowerShellSingleQuoted = escapePowerShellSingleQuoted;
 exports.escapePosixDoubleQuoted = escapePosixDoubleQuoted;
 exports.escapeSingleQuotedShellLiteral = escapeSingleQuotedShellLiteral;
+exports.shellSingleQuote = shellSingleQuote;
 exports.projectPathExportLine = projectPathExportLine;
 exports.renderShellActionLines = renderShellActionLines;
 exports.projectPathActionProjection = projectPathActionProjection;
@@ -64,8 +65,11 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
 const pattern_cjs_1 = require("./pattern.cjs");
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const markdown_line_diff_cjs_1 = require("./markdown-line-diff.cjs");
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -249,6 +253,8 @@ const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
         'gsd-worktree-path-guard.js',
         // #4221: secret-file read guard (Read|Grep|Bash).
         'gsd-secret-read-guard.js',
+        // #5465: SessionStart PATH persistence through $CLAUDE_ENV_FILE.
+        'gsd-path-export.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -279,6 +285,8 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-worktree-path-guard.js',
         // #4221: secret-file read guard (Read|Grep|Bash).
         'gsd-secret-read-guard.js',
+        // #5465: SessionStart PATH persistence through $CLAUDE_ENV_FILE.
+        'gsd-path-export.js',
     ]),
     'codex-toml': new Set([
         'gsd-check-update.js',
@@ -452,6 +460,18 @@ function escapePosixDoubleQuoted(value) {
 function escapeSingleQuotedShellLiteral(value) {
     return String(value).replace(/'/g, "'\\''");
 }
+/**
+ * #1460 / #4039: POSIX single-quote an arbitrary string as ONE shell token. A path such as a
+ * hook script's absolute install location commonly sits under a home directory containing
+ * spaces or other metacharacters (e.g. "/Users/Bob Smith/.claude/..."); written unquoted it
+ * would word-split and, with a hostile prefix, could inject. Wrapping in single quotes — with
+ * each embedded `'` escaped as `'\''` by escapeSingleQuotedShellLiteral — makes the whole value a
+ * single token no metacharacter inside it can break. This is the one implementation of that rule;
+ * do not re-implement it in a caller.
+ */
+function shellSingleQuote(value) {
+    return "'" + escapeSingleQuotedShellLiteral(value) + "'";
+}
 /**
  * The `export PATH="<dir>:$PATH"` line every persistence lane appends, plus the escaped directory
  * token it embeds. One builder because three lanes emit this line: a lane that re-escapes it
@@ -609,12 +629,28 @@ function _spawnResult(result, program) {
         timedOut: isSpawnTimeout({ error }),
     };
 }
+// #5548: owned by read-only-git-env.cts (its default base is scrubbed); re-exported for callers.
+var read_only_git_env_cjs_2 = require("./read-only-git-env.cjs");
+Object.defineProperty(exports, "GIT_LOCATION_ENV_VARS", { enumerable: true, get: function () { return read_only_git_env_cjs_2.GIT_LOCATION_ENV_VARS; } });
+Object.defineProperty(exports, "scrubGitLocationEnv", { enumerable: true, get: function () { return read_only_git_env_cjs_2.scrubGitLocationEnv; } });
 function execGit(args, opts = {}) {
     // Non-interactive defaults: a hung credential prompt or terminal-input
     // probe must surface as a timeout, not block the tool forever. Callers
     // can override via opts.env.
+    //
+    // #5048: readOnlyGitEnv() as well. execGit is the shared seam behind every
+    // git call the tool makes, including the read-only ones (`status`,
+    // `diff --cached`, `rev-parse`, `log`, …). By default git refreshes the index
+    // and takes an *optional* `.git/index.lock` to write the refreshed copy back,
+    // so a read can lose a race against a real `git add` / `git commit` and fail
+    // it with `Unable to create '.git/index.lock': File exists`. The owner is
+    // src/read-only-git-env.cts, shared with every other read-only seam, so this
+    // call site cannot drift from them. The variable disables only those optional
+    // index operations; a caller that genuinely needs one (a writing command, or a
+    // status whose freshness it wants persisted) can still set it back through
+    // opts.env, which is spread last on purpose.
     const env = {
-        ...process.env,
+        ...(0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
         GIT_TERMINAL_PROMPT: '0',
         GCM_INTERACTIVE: 'never',
         ...(opts.env || {}),
@@ -1037,7 +1073,6 @@ function probeTty(opts = {}) {
         return null;
     }
 }
-// ─── Platform file I/O ────────────────────────────────────────────────────────
 /**
  * How many leading lines of LF-only `text` are its closed YAML frontmatter block (opening
  * fence through closing fence), or 0 when there is none (an unterminated block is not
@@ -1053,18 +1088,43 @@ function leadingFrontmatterLineCount(text) {
     // The lines before the closing fence, plus the closing fence line itself.
     return text.slice(0, fence.closingStart).split('\n').length;
 }
-function _normalizeMd(content) {
+/** A leading BOM is not part of the first line's content when aligning two documents. */
+function withoutBom(line) {
+    return line !== undefined && line.charCodeAt(0) === 0xFEFF ? line.slice(1) : (line ?? '');
+}
+function _normalizeMd(content, prior, preserveFencedStructure = false) {
     if (!content || typeof content !== 'string')
         return content;
     let text = content.replace(/\r\n/g, '\n');
     const lines = text.split('\n');
+    // #5165: when the document being replaced is known, only the junctions the
+    // write touched are normalized; every other region stays byte-identical.
+    let scope = null;
+    let priorLines = [];
+    if (typeof prior === 'string' && prior !== '') {
+        priorLines = prior.replace(/\r\n/g, '\n').split('\n');
+        // A BOM on either first line must not make an unchanged line look rewritten.
+        const alignPrior = [withoutBom(priorLines[0]), ...priorLines.slice(1)];
+        const alignNext = [withoutBom(lines[0]), ...lines.slice(1)];
+        const match = (0, markdown_line_diff_cjs_1.matchLines)(alignPrior, alignNext);
+        if (match)
+            scope = (0, markdown_line_diff_cjs_1.writeScope)(match, priorLines.length);
+    }
     // The frontmatter block is YAML, not markdown: its lines are published exactly as written.
     // A `# comment` is not a heading, and a blank line inserted into a multi-line quoted scalar
     // or removed from a block scalar changes the value (found while implementing #5105).
     const frontmatterLines = leadingFrontmatterLineCount(text);
     const result = [];
+    // A separating blank the rules add. In scoped mode (#5165) two rules that fire on
+    // the same junction add ONE blank: the whole-document pass collapses them in its
+    // final blank-run regex, which scoped mode must not apply to runs the write kept.
+    const blank = () => {
+        if (scope === null || result[result.length - 1] !== '')
+            result.push('');
+    };
     const fenceRegex = /^```/;
     const insideFence = new Array(lines.length);
+    const insideSharedFence = new Array(lines.length).fill(false);
     let fenceOpen = false;
     for (let i = 0; i < lines.length; i++) {
         if (i < frontmatterLines) {
@@ -1085,6 +1145,13 @@ function _normalizeMd(content) {
             insideFence[i] = fenceOpen;
         }
     }
+    if (preserveFencedStructure) {
+        for (const block of (0, markdown_sectionizer_cjs_1.scanFencedBlocks)(lines)) {
+            const end = block.closeLineIdx === -1 ? lines.length : block.closeLineIdx;
+            for (let i = block.openLineIdx + 1; i < end; i++)
+                insideSharedFence[i] = true;
+        }
+    }
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (i < frontmatterLines) {
@@ -1095,11 +1162,25 @@ function _normalizeMd(content) {
         const prevTrimmed = prev.trimEnd();
         const trimmed = line.trimEnd();
         const isFenceLine = fenceRegex.test(trimmed);
-        if (/^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---')
-            result.push('');
-        if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine)) {
+        // Bracket writers preserve literal headings and lists inside fenced examples.
+        const normalizeStructuralLine = !preserveFencedStructure || !insideSharedFence[i];
+        // A heading or fence line the write authored brings its own separation, even
+        // where it replaced a prose line in place (#5165). One that replaced a heading
+        // or fence (a rename, a renumber) inherits the spacing around it instead.
+        const isStructural = (text) => /^#{1,6}\s/.test(text.trimEnd()) || fenceRegex.test(text.trimEnd());
+        const replacedPrior = scope !== null ? scope.replacedPriorIndex(i) : -1;
+        const authoredStructure = scope !== null && scope.lineWritten(i) && isStructural(line)
+            && !(replacedPrior >= 0 && isStructural(priorLines[replacedPrior] ?? ''));
+        const keptBefore = scope !== null && !authoredStructure && i > 0 && scope.junctionKept(i - 1);
+        const keptAfter = scope !== null && !authoredStructure && i < lines.length - 1 && scope.junctionKept(i);
+        // A blank-line run is collapsed only where the write made it (#5165).
+        if (scope !== null && line === '' && result.length > 0 && result[result.length - 1] === '' && !keptBefore)
+            continue;
+        if (normalizeStructuralLine && /^#{1,6}\s/.test(trimmed) && i > 0 && prevTrimmed !== '' && prevTrimmed !== '---' && !keptBefore)
+            blank();
+        if (isFenceLine && i > 0 && prevTrimmed !== '' && !insideFence[i] && (i === 0 || !insideFence[i - 1] || isFenceLine) && !keptBefore) {
             if (i === 0 || !insideFence[i - 1])
-                result.push('');
+                blank();
         }
         // No "separate a list from a preceding paragraph" rule (#3854, #4725).
         // This pass re-normalizes the ENTIRE document on every .md write, so an
@@ -1111,21 +1192,21 @@ function _normalizeMd(content) {
         // from the after-heading rule below. The after-a-bullet rule at the end
         // of this loop is a different transition (list→prose) and is unaffected.
         result.push(line);
-        if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
-            result.push('');
-        if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
-            result.push('');
-        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1) {
+        if (normalizeStructuralLine && /^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '' && !keptAfter)
+            blank();
+        if (/^```\s*$/.test(trimmed) && i > 0 && insideFence[i - 1] && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '' && !keptAfter)
+            blank();
+        if (normalizeStructuralLine && /^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i < lines.length - 1 && !keptAfter) {
             const next = lines[i + 1];
             if (next !== undefined && next.trimEnd() !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(next) && !/^\s/.test(next))
-                result.push('');
+                blank();
         }
     }
     // The frontmatter lines are `result`'s first entries, unchanged; the blank-run collapse
     // applies from the line ending that closes the block onward.
     const head = result.slice(0, frontmatterLines).join('\n');
     text = result.join('\n');
-    text = head + text.slice(head.length).replace(/\n{3,}/g, '\n\n');
+    text = scope === null ? head + text.slice(head.length).replace(/\n{3,}/g, '\n\n') : text;
     text = text.replace(/\n*$/, '\n');
     return text;
 }
@@ -1136,7 +1217,7 @@ function normalizeContent(filePath, content, opts = {}) {
     const isMd = node_path_1.default.extname(filePath).toLowerCase() === '.md';
     let normalized;
     if (isMd) {
-        normalized = _normalizeMd(content);
+        normalized = _normalizeMd(content, opts.prior, opts.preserveFencedMarkdownStructure === true);
     }
     else {
         normalized = (content ?? '').replace(/\r\n/g, '\n').replace(/\n*$/, '\n');
@@ -1157,8 +1238,8 @@ function normalizeContent(filePath, content, opts = {}) {
  * post-write re-read of the actual on-disk bytes) instead of a raw `!==` —
  * do not simplify this back to a direct string comparison.
  */
-function contentChangedAfterNormalize(filePath, before, after) {
-    return normalizeContent(filePath, after).content !== normalizeContent(filePath, before).content;
+function contentChangedAfterNormalize(filePath, before, after, opts = {}) {
+    return normalizeContent(filePath, after, { ...opts, prior: before }).content !== normalizeContent(filePath, before, { ...opts, prior: before }).content;
 }
 // Rename errnos that are transient on Windows: a concurrent reader (or an AV
 // scanner / indexer) holding the target open makes renameSync fail briefly.
@@ -1210,8 +1291,59 @@ function retryRenameSync(fromPath, toPath) {
     if (err !== null)
         throw err;
 }
+/**
+ * Largest on-disk Markdown document read back as the `prior` of a scoped write.
+ * A larger file is normalized whole (the pre-#5165 behavior) rather than read and
+ * diffed on every write.
+ */
+const MAX_PRIOR_BYTES = 2 * 1024 * 1024;
+/**
+ * The Markdown document a write replaces, or undefined when there is none worth
+ * diffing against: no file, not a regular file (a FIFO or device reports size 0
+ * and would block or never end), unreadable, or larger than MAX_PRIOR_BYTES. The
+ * bound is enforced on the bytes actually read from one open descriptor, so a
+ * file that grows after the check cannot exceed it.
+ */
+function readPriorMarkdown(filePath, encoding) {
+    let fd;
+    try {
+        // O_NONBLOCK keeps opening a FIFO from waiting for a writer; it is absent on Windows.
+        fd = node_fs_1.default.openSync(filePath, node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NONBLOCK ?? 0));
+        const stat = node_fs_1.default.fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_PRIOR_BYTES)
+            return undefined;
+        // One byte of headroom: reading it means the file grew past what was measured.
+        const buffer = Buffer.alloc(stat.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = node_fs_1.default.readSync(fd, buffer, length, buffer.length - length, null);
+            if (read === 0)
+                break;
+            length += read;
+        }
+        if (length > stat.size)
+            return undefined;
+        return buffer.toString(encoding, 0, length);
+    }
+    catch {
+        return undefined; // no prior document (new file or unreadable): normalize it whole
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                node_fs_1.default.closeSync(fd);
+            }
+            catch { /* already closed */ }
+        }
+    }
+}
 function platformWriteSync(filePath, content, opts = {}) {
-    const { content: normalized, encoding } = normalizeContent(filePath, content, opts);
+    // #5165: a Markdown write is scoped to what it changed relative to the file it replaces.
+    let prior = opts.prior;
+    if (prior === undefined && opts.verbatim !== true && node_path_1.default.extname(filePath).toLowerCase() === '.md') {
+        prior = readPriorMarkdown(filePath, opts.encoding ?? 'utf-8');
+    }
+    const { content: normalized, encoding } = normalizeContent(filePath, content, { ...opts, prior });
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
     const tmpPath = filePath + '.tmp.' + process.pid;
     // Step 1: write the sibling tmp file. If THIS fails, nothing was published, so a

package/gsd-core/bin/lib/smart-entry.cjs

@@ -43,6 +43,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const read_only_git_env_cjs_1 = require("./read-only-git-env.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // #3696: the calendar-validity predicate moved to the STATE.md document module
 // so `state validate` can assert the same `last_activity` invariant this reader
@@ -68,11 +69,14 @@ const stateDocument = require("./state-document.cjs");
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseId = require("./phase-id.cjs");
-const { comparePhaseNum, extractPhaseToken, matchPhaseDirs, normalizePhaseName, parsePhaseFromProse, stripProjectCodePrefix } = phaseId;
+const { comparePhaseNum, extractPhaseToken, customPhaseQuery, customDirectoryOwner, parsePhaseFromProse, stripProjectCodePrefix } = phaseId;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateMod = require("./state.cjs");
 const { readStateHeadFreshness } = stateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { phaseDirectoryOptions, resolvePhaseDirectoryLookup, matchPhaseDirsForLookup } = phaseLocatorMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const unusableInput = require("./unusable-input.cjs");
 const { warnUnusableInput, UNUSABLE_REASON } = unusableInput;
 // #5118: the verification-status owner's frontmatter-only report check.
@@ -119,8 +123,8 @@ function parseIntOrNull(s) {
     const n = Number.parseInt(cleaned, 10);
     return Number.isFinite(n) ? n : null;
 }
-function phaseTokenFromDirName(name) {
-    const token = extractPhaseToken(name);
+function phaseTokenFromDirName(name, convention) {
+    const token = extractPhaseToken(name, convention);
     // #2528: the shape probe runs on the PROJECT-CODE-STRIPPED token. A prefixed
     // directory tokenizes to `MEM-05-80-20`, which does not start with a digit,
     // so the unstripped probe rejected it and the entry was dropped before any
@@ -222,6 +226,18 @@ function readGitSignals(cwd) {
                 windowsHide: true,
                 stdio: ['pipe', 'pipe', 'pipe'],
                 timeout: 10_000,
+                // #5048: readGitSignals runs `git status`, which by default refreshes
+                // the index and takes an *optional* `.git/index.lock` to write the
+                // refreshed copy back. That lock is the one a real `git add` / `git
+                // commit` needs, so a routine "which phase am I in" probe can fail
+                // someone else's commit with `Unable to create '.git/index.lock': File
+                // exists`. GIT_OPTIONAL_LOCKS=0 turns off exactly that optional write.
+                // The `rev-parse` / `log` calls sharing this helper never open the
+                // index, so the variable is inert for them. The block itself is owned by
+                // src/read-only-git-env.cts and shared with every other read-only seam;
+                // parity across every read-only surface is asserted in
+                // tests/git-optional-locks-parity.test.cjs.
+                env: (0, read_only_git_env_cjs_1.readOnlyGitEnv)(),
             });
         }
         catch {
@@ -239,9 +255,9 @@ function readGitSignals(cwd) {
     const unpushed = run(['log', '@{u}..HEAD', '--oneline']).trim().length > 0;
     return { has_git: true, dirty, unpushed };
 }
-/** Leading numeric phase token from a STATE.md scalar or body `Phase:` value. */
-function phaseTokenFromState(raw) {
-    return parsePhaseFromProse(raw).phase;
+/** Phase identity from a STATE.md scalar or body `Phase:` value, honoring custom naming when a context is supplied. */
+function phaseTokenFromState(raw, context) {
+    return parsePhaseFromProse(raw, undefined, context).phase;
 }
 /**
  * Detect whether the current phase's verify report indicates failure. The
@@ -251,12 +267,20 @@ function phaseTokenFromState(raw) {
  */
 function detectVerifyFailed(cwd, currentPhaseRaw) {
     const phasesDir = node_path_1.default.join(planningPaths(cwd).phases);
+    // #4304: both the directory admission scan and the later selector must read
+    // the same current-checkout grammar. Bracket is the only opt-in widening.
+    const convention = resolvePhaseIdConvention(cwd) === 'bracket' ? 'bracket' : undefined;
+    const directoryContext = phaseDirectoryOptions(cwd);
     let entries = [];
     try {
         entries = node_fs_1.default.readdirSync(phasesDir)
-            .map((name) => ({ name, phaseToken: phaseTokenFromDirName(name) }))
+            .map((name) => {
+            const custom = customPhaseQuery(name, directoryContext);
+            const parts = custom && customDirectoryOwner(name, custom);
+            return { name, phaseToken: parts ? parts.id : phaseTokenFromDirName(name, convention) };
+        })
             .filter((entry) => entry.phaseToken !== null)
-            .sort((a, b) => comparePhaseNum(a.phaseToken, b.phaseToken) || a.name.localeCompare(b.name))
+            .sort((a, b) => comparePhaseNum(a.phaseToken, b.phaseToken, directoryContext) || a.name.localeCompare(b.name))
             .map((entry) => entry.name);
     }
     catch {
@@ -264,10 +288,10 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
     }
     if (entries.length === 0)
         return false;
-    const phaseToken = phaseTokenFromState(currentPhaseRaw);
+    const phaseToken = phaseTokenFromState(currentPhaseRaw, directoryContext);
     let targetDir;
     if (phaseToken) {
-        const normalized = normalizePhaseName(phaseToken);
+        const lookup = resolvePhaseDirectoryLookup(cwd, phaseToken, undefined, directoryContext);
         // #2528: the fourth directory-resolution site, and the one where a miss is
         // silent — a phase whose directory cannot be found reports "not failed",
         // which reads identically to a healthy phase. It must therefore apply the
@@ -276,7 +300,7 @@ function detectVerifyFailed(cwd, currentPhaseRaw) {
         // surfaces its own failed verification. `entries` is already sorted, and
         // `matchPhaseDirs` filters without reordering, so taking the first match
         // preserves the previous `.find()` selection exactly.
-        const { matches } = matchPhaseDirs(entries, normalized);
+        const { matches } = matchPhaseDirsForLookup(entries, lookup, undefined, directoryContext);
         targetDir = matches[0];
         if (!targetDir)
             return false;