@opengsd/gsd-core 1.17.0 → 1.19.0

package/hooks/dist/gsd-statusline.js

@@ -889,8 +889,40 @@ function compactModelName(name) {
 // are a fixed array, and the workspace dir is passed via -C. Fails silently
 // (segment absent) outside a repo, without git, or on timeout.
 
+// #5048: bound for the `git status` spawn below. With GIT_OPTIONAL_LOCKS=0 the
+// spawn no longer writes the refreshed index back, so what is left is reading
+// the index and stat-ing the tracked paths. The bound keeps a hung network
+// filesystem from stalling a render for long while leaving room for a cold stat
+// cache on a large repo. The figure was chosen, not measured: time
+// `git status --porcelain=v2 --branch` on a large tree with a cold cache before
+// changing it. Exported so the test can pin the bound instead of restating the
+// literal (which is how the constant and its assertion drifted before).
 const GIT_STATUS_TIMEOUT_MS = 1500;
 
+/**
+ * #5048: env for the read-only git spawn in this file.
+ *
+ * By default `git status` refreshes the index and takes an *optional*
+ * `.git/index.lock` to write the refreshed copy back. That is a write the
+ * caller never asked for, and it turns a pure read into a contender for the
+ * lock a real `git add` / `git commit` needs — a read-only statusline render
+ * can then make a concurrent commit fail with
+ * `Unable to create '.git/index.lock': File exists`. The statusline spawns
+ * git on every render, so the lock is re-created continuously.
+ *
+ * The env block itself is owned by src/read-only-git-env.cts and shared with
+ * every other read-only seam (`execGit` in src/shell-command-projection.cts,
+ * `readGitSignals` in src/smart-entry.cts, `gitExec` in
+ * src/pristine-baseline.cts, the two blocking guards). This hook reads it per
+ * call rather than snapshotting at load, so a later `process.env` mutation is
+ * visible and the seams behave identically.
+ *
+ * Deliberately NOT applied to the `git rev-list` spawn in
+ * readStateHeadCommits(): that walks the commit graph and never opens the
+ * index, so the variable would be a no-op there.
+ */
+const { readOnlyGitEnv } = require('../gsd-core/bin/lib/read-only-git-env.cjs');
+
 /**
  * Run `git status --porcelain=v2 --branch` in dir.
  * Returns raw stdout, or null when git is missing, dir isn't a repo, or the
@@ -902,7 +934,7 @@ function readGitStatus(dir) {
     // or untracked files; overflow still degrades safely to segment-absent via
     // the catch below.
     return childProcess.execFileSync('git', ['-C', dir, 'status', '--porcelain=v2', '--branch'],
-      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+      { encoding: 'utf8', timeout: GIT_STATUS_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, env: readOnlyGitEnv() });
   } catch (e) {
     return null;
   }
@@ -995,7 +1027,7 @@ function isValidStateHeadStamp(raw) {
  */
 function readStateHeadCommits(root, stamp) {
   try {
-    return childProcess.execFileSync('git',
+    return childProcess.execFileSync('git', // allow-index-refresh: rev-list walks the commit graph and never opens the index
       ['-C', root, 'rev-list', '--left-right', '--count', `${stamp}...HEAD`],
       { encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
@@ -1396,6 +1428,7 @@ module.exports = {
   isAutoCompactDisabled, AUTO_COMPACT_DISABLE_ENV_KEYS, AUTO_COMPACT_ENV_TRUTHY,
   resolveAutoCompactThreshold, contextMeter, SETTINGS_FILE_MAX_BYTES,
   parseAutoCompactWindowEnv, canonicalModelKey, isAutoCompactWindowValue,
+  GIT_STATUS_TIMEOUT_MS,
 };
 
 /**

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

@@ -39,6 +39,27 @@ cleanup_temp_files() {
 }
 trap cleanup_temp_files EXIT
 
+# The first line of $1 (everything before the first newline), matched BYTE-wise.
+#
+# `${1%%$'\n'*}` is a longest-suffix glob match, and on bash 3.2 (macOS's
+# /bin/bash) in a multibyte locale such as en_US.UTF-8 it costs ~3.5 s on a
+# 112KB value (#5473, measured inside the macOS conformance job: the same hook
+# on the same 114750-byte command took ~5.6 s under LC_ALL=en_US.UTF-8 and
+# ~0.55 s under LC_ALL=C, and a trace put 3.5 s of it on this expansion). A
+# newline is the same single byte in every locale, so matching it byte-wise
+# changes no result.
+#
+# ONLY call this inside a command substitution, `SUBJECT=$(gsd_first_line "$MSG")`:
+# the substitution's subshell is what keeps LC_ALL=C from leaking into the rest
+# of the hook, whose regexes and length arithmetic keep the caller's locale. A
+# substitution is a fork with no pipe between two processes, so it keeps the
+# property the pure-expansion form was chosen for (no `head -1` SIGPIPE race
+# under `set -euo pipefail`, #4429); printf is a builtin, so no exec either.
+gsd_first_line() {
+  LC_ALL=C
+  printf '%s' "${1%%$'\n'*}"
+}
+
 # The 10 built-in Conventional Commits types — the SINGLE declaration (#3811
 # review finding: this was previously hand-typed a second time inside the
 # node -e script below, a generative-fix-divergence risk per CLAUDE.md's
@@ -575,18 +596,19 @@ if [ "$CLASSIFY_STATUS" = "0" ]; then
       SUBJECT=$(GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" MSG="$MSG" node -e "
         const {resolveCommitSubject}=require(process.env.GIT_CMD_LIB);
         process.stdout.write(resolveCommitSubject(process.env.MSG));
-      " 2>/dev/null) || SUBJECT="${MSG%%$'\n'*}"
+      " 2>/dev/null) || SUBJECT=$(gsd_first_line "$MSG")
     else
-      # Pure parameter expansion, not `echo "$MSG" | head -1`: that pipeline
+      # Pure parameter expansion (in gsd_first_line), not
+      # `echo "$MSG" | head -1`: that pipeline
       # raced a SIGPIPE under `set -euo pipefail` whenever $MSG had a body
       # (the common case) — `head -1` can close its read end as soon as it
       # has the first line, and if `echo`'s write lands after that close,
       # `echo` dies with signal 13 (exit 141), which is NOT suppressed by
       # `set -e` and aborted the whole hook intermittently (observed in
-      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). Zero
-      # subprocesses here means zero pipe/race surface. Equivalent to
+      # tests/hooks-opt-in.test.cjs's --fixup=HEAD "round 7" case). No pipe
+      # means no race surface. Equivalent to
       # `head -1` for single-line, multi-line, and trailing-newline input.
-      SUBJECT="${MSG%%$'\n'*}"
+      SUBJECT=$(gsd_first_line "$MSG")
     fi
     # Single source of truth for the accepted commit-type list (#3811): the
     # 10 built-ins plus whatever passed the safe-token filter above. Both the

package/hooks/dist/gsd-windsurf-pre-write.js

@@ -49,8 +49,35 @@ const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib
 // timeout does. The guard keeps its fail-open posture either way.
 const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: BLOCKING_GUARD_PROBE_TIMEOUT_MS, windowsHide: true };
 
+// #5048: GIT_OPTIONAL_LOCKS=0 on every git call from this hook. `git rev-parse`
+// never opens the index, so this is inert for today's callers; it is set anyway
+// so the read-only invariant has no holes if a `status` / `diff` caller is ever
+// added here. git refreshes the index and takes an *optional*
+// `.git/index.lock` on some reads, and this hook runs on every tool call, so a
+// read here can otherwise fail a concurrent `git add` / `git commit` with
+// `Unable to create '.git/index.lock': File exists`.
+//
+// The env block is owned by src/read-only-git-env.cts and shared with every
+// other read-only seam (built artifact, not a sibling hooks/-tree file — same
+// rule hooks/lib/git-cmd.js follows for token-scanner). It is read per spawn,
+// not snapshotted at load, so the two guards behave identically.
+// Parity: tests/git-optional-locks-parity.test.cjs.
+// A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
+// (#3582), so the compiled owner can be absent. This guard only runs
+// `git rev-parse`, which never opens the index, so the unmodified environment
+// loses nothing; requiring the artifact unguarded would throw at load and the
+// containment guard would silently stop running.
+let readOnlyGitEnv = () => process.env;
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ readOnlyGitEnv } = require('../gsd-core/bin/lib/read-only-git-env.cjs'));
+} catch {
+  // artifact absent and not buildable: keep the inert fallback above
+}
+
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
 }
 
 // Walk up from `start` to find the nearest existing DIRECTORY (not merely an

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

@@ -81,7 +81,7 @@ function forceGitAddCwds(command, defaultCwd) {
 }
 
 function currentBranch(cwd) {
-  const result = spawnSync('git', ['branch', '--show-current'], {
+  const result = spawnSync('git', ['branch', '--show-current'], { // allow-index-refresh: reads HEAD only, never opens the index
     cwd,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],

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

@@ -34,8 +34,35 @@ const ON_CRASH = HOOK_ON_CRASH.ALLOW;
 // hooks/lib/git-probe.js, #5180). This guard runs at most 3 sequential probes.
 const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: BLOCKING_GUARD_PROBE_TIMEOUT_MS, windowsHide: true };
 
+// #5048: GIT_OPTIONAL_LOCKS=0 on every git call from this hook. `git rev-parse`
+// never opens the index, so this is inert for today's callers; it is set anyway
+// so the read-only invariant has no holes if a `status` / `diff` caller is ever
+// added here. git refreshes the index and takes an *optional*
+// `.git/index.lock` on some reads, and this hook runs on every tool call, so a
+// read here can otherwise fail a concurrent `git add` / `git commit` with
+// `Unable to create '.git/index.lock': File exists`.
+//
+// The env block is owned by src/read-only-git-env.cts and shared with every
+// other read-only seam (built artifact, not a sibling hooks/-tree file — same
+// rule hooks/lib/git-cmd.js follows for token-scanner). It is read per spawn,
+// not snapshotted at load, so the two guards behave identically.
+// Parity: tests/git-optional-locks-parity.test.cjs.
+// A raw plugin-marketplace or git-clone install never ran `npm run build:lib`
+// (#3582), so the compiled owner can be absent. This guard only runs
+// `git rev-parse`, which never opens the index, so the unmodified environment
+// loses nothing; requiring the artifact unguarded would throw at load and the
+// containment guard would silently stop running.
+let readOnlyGitEnv = () => process.env;
+try {
+  const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');
+  ensureRuntimeBuild();
+  ({ readOnlyGitEnv } = require('../gsd-core/bin/lib/read-only-git-env.cjs'));
+} catch {
+  // artifact absent and not buildable: keep the inert fallback above
+}
+
 function git(args, cwd) {
-  return spawnSync('git', args, { ...SPAWNOPT, cwd });
+  return spawnSync('git', args, { ...SPAWNOPT, cwd, env: readOnlyGitEnv() });
 }
 
 // Walk up from `start` to find the nearest existing directory.

package/hooks/dist/lib/isolation-sentinel.js

@@ -91,6 +91,11 @@ const SENTINEL_RELATIVE_PATH = path.join('.gsd', 'dispatch-isolation-sentinel.js
 // later, unrelated phase.
 const SENTINEL_STALE_MS = 10 * 60 * 1000; // 10 minutes
 
+// #5479: the longest a recorded sequential degrade keeps governing its own phase after the trust
+// window (see agedNoneGovernsDispatch). A single executor run is minutes to a couple of hours; a
+// day is a generous bound that still ends a stale or forged record's authority.
+const AGED_NONE_MAX_MS = 24 * 60 * 60 * 1000;
+
 function sentinelPath(cwd) {
   return path.join(cwd, SENTINEL_RELATIVE_PATH);
 }
@@ -280,6 +285,43 @@ function sentinelAppliesToDispatch(sentinel, dispatchIds) {
   return true;
 }
 
+/**
+ * #5479: does an AGED recorded sequential degrade still govern THIS dispatch?
+ *
+ * The trust window (`SENTINEL_STALE_MS`) exists so a leftover sentinel cannot authorize an unisolated
+ * executor for a LATER, unrelated phase (#3045 F2). It also made the guard forget a legitimate
+ * degrade (the #683/#3060 base-check, the project opt-out) the moment the previous executor ran
+ * longer than the window: the next flag-less dispatch of the SAME phase was denied because the
+ * registry fallback answers "this host CAN isolate" and cannot see the shell-side degrade.
+ *
+ * True only when ALL of these hold, so the aged path can only ever loosen toward `none` for the exact
+ * phase the dispatch itself names:
+ *   - the sentinel is present, well-formed, and records `isolation: 'none'` (an aged
+ *     `harness-worktree`/`orchestrator-worktree` record authorizes nothing);
+ *   - its `written_at` is not in the future (a forged or clock-skewed record is never trusted);
+ *   - it carries a phase, the dispatch names a phase, and they are equal (a dispatch whose phase
+ *     cannot be established is "cannot compare", which keeps today's fallback, never an allow).
+ * A plan-scoped record speaks only for its own plan (or a plan-less dispatch): a `none` recorded for
+ * a submodule-degraded plan A must not authorize a genuinely isolated plan B of the same phase. The
+ * phase-level degrade (the base-check, the project opt-out) is the record with no plan.
+ *   - it is at most `AGED_NONE_MAX_MS` old: a static record, forged or left by a long-finished run,
+ *     does not govern indefinitely. The normal flow re-records at every phase start and plan gate,
+ *     so a live phase is always far younger.
+ * A fresh sentinel is handled by the existing path and never reaches here.
+ *
+ * `clock` is the injectable `{ now(): number }` seam `readSentinel` uses.
+ */
+function agedNoneGovernsDispatch(sentinel, dispatchIds, { clock = Date } = {}) {
+  if (!sentinel || sentinel.present !== true || sentinel.malformed) return false;
+  if (sentinel.isolation !== 'none') return false;
+  if (typeof sentinel.writtenAt !== 'number') return false;
+  const age = clock.now() - sentinel.writtenAt;
+  if (age < -5000 || age > AGED_NONE_MAX_MS) return false;
+  if (!sentinel.phase || !dispatchIds || !dispatchIds.phase) return false;
+  if (sentinel.plan && dispatchIds.plan && sentinel.plan !== dispatchIds.plan) return false;
+  return sentinel.phase === dispatchIds.phase;
+}
+
 /**
  * #4594 F3: build the structured "a fresh sentinel was present but did not
  * apply to this dispatch" descriptor, mirroring the exact comparison
@@ -307,10 +349,12 @@ module.exports = {
   VALID_ISOLATION,
   SENTINEL_RELATIVE_PATH,
   SENTINEL_STALE_MS,
+  AGED_NONE_MAX_MS,
   sentinelPath,
   resolveSentinelRoot,
   readSentinel,
   extractDispatchIdentifiers,
   sentinelAppliesToDispatch,
+  agedNoneGovernsDispatch,
   buildSentinelDiscard,
 };

package/hooks/dist/managed-hooks-registry.cjs

@@ -29,6 +29,7 @@ const MANAGED_HOOKS = [
   'gsd-cursor-subagent-stop.js',
   'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
+  'gsd-path-export.js',
   // #3662: portable node resolver (helper staged in hooks/; managed JS hook
   // commands route through it under --portable-hooks).
   'gsd-node-runner.sh',

package/hooks/gsd-agent-isolation-guard.js

@@ -71,7 +71,7 @@ if (require.main === module && !process.env.NODE_V8_COVERAGE) {
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, agedNoneGovernsDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
 
@@ -227,7 +227,9 @@ function resolveRuntimeIdentity(cwd, configPath, resolveRuntimeNameFromCandidate
   // never a resolution failure (this function only ever throws for the
   // config.json read above, which the caller's catch already handles).
   try {
-    const defaultsPath = path.join(os.homedir(), '.gsd', 'defaults.json');
+    // #5017: the store root is GSD_HOME when set and non-blank, else the home
+    // directory — the config loader's rule (src/runtime-homes.cts resolveGsdHome).
+    const defaultsPath = path.join(process.env.GSD_HOME || os.homedir(), '.gsd', 'defaults.json');
     const defaultsRaw = fs.readFileSync(defaultsPath, 'utf-8');
     const defaultsParsed = JSON.parse(defaultsRaw);
     if (defaultsParsed && typeof defaultsParsed === 'object' && 'runtime' in defaultsParsed) {
@@ -463,6 +465,16 @@ function resolveIsolationState(cwd, { clock = Date, dispatchIds = null } = {}) {
     };
   }
 
+  // #5479: a recorded sequential degrade (`none`) for THIS dispatch's phase keeps governing it after the
+  // trust window. Without this, an executor that ran longer than SENTINEL_STALE_MS made the next
+  // flag-less dispatch of the same phase fall back to the registry capability ("this host CAN
+  // isolate") and be denied for a degrade the workflow legitimately recorded. The predicate only
+  // loosens toward `none`, only for the phase the dispatch itself names, never for a future-dated
+  // record (see agedNoneGovernsDispatch).
+  if (sentinel.present && sentinel.stale && agedNoneGovernsDispatch(sentinel, dispatchIds, { clock })) {
+    return { gsdProject: true, isolation: 'none', harnessFlag: null, error: null, sentinelDiscarded: null };
+  }
+
   // Sentinel absent, stale, or does not apply to this dispatch (F2 mismatch):
   // conservative fallback (#3045 finding — must still cover fail-closed case
   // (a): a project that opted out of worktrees entirely via

package/hooks/gsd-cursor-subagent-start.js

@@ -70,7 +70,7 @@ const { allow } = require('./lib/hook-exit.js');
 // hooks/lib/cursor-workspace.js. Staged next to these scripts by
 // writeCursorHooksJson so the require always resolves post-install.
 const { resolveStatePath } = require('./lib/cursor-workspace.js');
-const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
+const { readSentinel, VALID_ISOLATION, extractDispatchIdentifiers, sentinelAppliesToDispatch, agedNoneGovernsDispatch, buildSentinelDiscard } = require('./lib/isolation-sentinel.js');
 const { REASON_CODE, describeSentinelDiscard } = require('./lib/isolation-deny-reason.js');
 // #3582: gsd-core/bin/lib/*.cjs (runtime-homes.cjs, worktree-safety.cjs,
 // runtime-name-policy.cjs, capability-registry.cjs — required below, inside
@@ -435,7 +435,8 @@ function resolveFallbackIsolation(root, configPath) {
   }
   if (!runtimeId) {
     try {
-      const defaultsPath = path.join(os.homedir(), '.gsd', 'defaults.json');
+      // #5017: GSD_HOME when set and non-blank, else the home directory — the loader's rule.
+      const defaultsPath = path.join(process.env.GSD_HOME || os.homedir(), '.gsd', 'defaults.json');
       const defaultsParsed = JSON.parse(fs.readFileSync(defaultsPath, 'utf-8'));
       if (defaultsParsed && typeof defaultsParsed === 'object' && 'runtime' in defaultsParsed) {
         runtimeId = resolveRuntimeNameFromCandidates(defaultsParsed.runtime) || null;
@@ -517,9 +518,13 @@ function evaluateRootIsolation(root, subagentType, { clock = Date, dispatchIds =
 
   let declaredIsolation;
   try {
+    // #5479: an aged recorded `none` for this dispatch's phase keeps governing it — the same predicate,
+    // and so the same verdicts, as the Claude guard (hooks/gsd-agent-isolation-guard.js).
     declaredIsolation = (sentinel.present && !sentinel.stale && applies)
       ? sentinel.isolation
-      : resolveFallbackIsolation(root, configPath);
+      : (sentinel.present && sentinel.stale && agedNoneGovernsDispatch(sentinel, dispatchIds, { clock }))
+        ? 'none'
+        : resolveFallbackIsolation(root, configPath);
   } catch {
     return {
       action: 'deny',

package/hooks/gsd-path-export.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+// SessionStart hook: put the installed gsd-core `bin/` directory (which holds `gsd_run`) on the
+// PATH of every later Bash tool call in this Claude Code session (#5465).
+//
+// Why a hook: the resolver snippet (gsd-core/workflows/_runtime-launcher.snippet.sh) persists its
+// PATH export through $CLAUDE_ENV_FILE, but Claude Code provides that variable only to SessionStart,
+// Setup, CwdChanged and FileChanged hooks, never to a workflow Bash block. So the write never fired
+// and a later block that called `gsd_run` without re-including the resolver got "command not found"
+// (hidden by `2>/dev/null || echo <fallback>`). This hook writes the same line from the one place
+// the variable exists. The snippet's in-block write stays for users who export the variable
+// themselves.
+//
+// Fail-open and side-effect-minimal by design: it only ever appends one line to the file Claude Code
+// hands to SessionStart hooks, only for a directory that contains an installed `gsd_run`, and any
+// problem (no variable, no gsd_run, unwritable file) exits 0 without output.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { allow } = require('./lib/hook-exit.js');
+
+/**
+ * The `bin/` directory next to this hook's install root: hooks live in `<root>/hooks/` and the
+ * runtime in `<root>/gsd-core/` for global, project-local and plugin layouts alike. Returns the
+ * real path, or null when `gsd_run` is not there.
+ */
+function resolveBinDir(hookDir) {
+  try {
+    const bin = fs.realpathSync(path.join(hookDir, '..', 'gsd-core', 'bin'));
+    return fs.statSync(path.join(bin, 'gsd_run')).isFile() ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The directory as the bash that sources $CLAUDE_ENV_FILE spells it. On Windows the env file is
+ * sourced by Git Bash, where `:` separates PATH entries and a drive letter is `/c/...`, which is
+ * also what the resolver snippet writes (it derives the directory from bash's `$GSD_TOOLS`). A
+ * native `C:\Users\x\...` would split at the colon and never resolve.
+ */
+function shellPath(dir, platform = process.platform) {
+  if (platform !== 'win32') return dir;
+  const m = /^([A-Za-z]):[\\/](.*)$/.exec(dir);
+  const rest = (m ? m[2] : dir.replace(/^[\\/]+/, '')).replace(/\\/g, '/');
+  return m ? `/${m[1].toLowerCase()}/${rest}` : dir.replace(/\\/g, '/');
+}
+
+/** The exact line the resolver snippet writes: `export PATH='<dir>':"$PATH"` with `'` escaped. */
+function exportLine(binDir, platform = process.platform) {
+  return `export PATH='${shellPath(binDir, platform).replace(/'/g, "'\\''")}':"$PATH"`;
+}
+
+/**
+ * Append the export to `envFile` unless it is already there. Returns true when it wrote.
+ * Never throws.
+ */
+function persistPath(envFile, binDir) {
+  try {
+    const line = exportLine(binDir);
+    let existing = '';
+    try {
+      existing = fs.readFileSync(envFile, 'utf8');
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') return false;
+    }
+    if (existing.split(/\r?\n/).includes(line)) return false;
+    const prefix = existing === '' || existing.endsWith('\n') ? '' : '\n';
+    fs.appendFileSync(envFile, `${prefix}${line}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main() {
+  const envFile = process.env.CLAUDE_ENV_FILE;
+  if (typeof envFile !== 'string' || envFile.trim() === '') return;
+  const binDir = resolveBinDir(__dirname);
+  if (binDir === null) return;
+  persistPath(envFile, binDir);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch {
+    // A PATH convenience must never fail session start.
+  }
+  allow();
+}
+
+module.exports = { resolveBinDir, shellPath, exportLine, persistPath };