@opengsd/gsd-core 1.18.0 → 1.20.0

package/hooks/dist/gsd-statusline.js

@@ -18,6 +18,7 @@ const os = require('os');
 // monkeypatching childProcess.execFileSync.
 const childProcess = require('child_process');
 const { HOOK_ON_CRASH, allow, crash } = require('./lib/hook-exit.js');
+const { gitEnv } = require('./lib/git-probe.js');
 
 // This hook's build-seam outer catch (require.main guard just below) has
 // always exited 0 (fail open — the statusline renders on EVERY prompt, so a
@@ -889,8 +890,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 +935,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(gitEnv()) });
   } catch (e) {
     return null;
   }
@@ -995,9 +1028,9 @@ 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,
+      { env: gitEnv(), encoding: 'utf8', timeout: STATE_FRESHNESS_GIT_TIMEOUT_MS,
         stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
   } catch (e) {
     return null;
@@ -1396,6 +1429,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-windsurf-pre-write.js

@@ -31,7 +31,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { allow, deny } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // #3911 (ADR-3889 Phase 7): the exit(2) call site (block(), below) is
 // migrated to hook-exit.js's deny(undefined, reason) — see
@@ -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 scrubbed gitEnv() base
+// loses nothing; requiring the artifact unguarded would throw at load and the
+// containment guard would silently stop running.
+let readOnlyGitEnv = (base = process.env) => base;
+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(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing DIRECTORY (not merely an

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

@@ -22,7 +22,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const { tokenize, skipToSubcommand } = require('./lib/git-cmd.js');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard is almost entirely advisory (fail open — a broken advisory must
 // never wedge every tool call), with ONE hard block (#3504 force-add-on-
@@ -81,8 +81,9 @@ 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,
+    env: gitEnv(),
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'ignore'],
     windowsHide: true,

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

@@ -18,7 +18,7 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
-const { reportIfUndetermined, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
+const { reportIfUndetermined, gitEnv, BLOCKING_GUARD_PROBE_TIMEOUT_MS } = require('./lib/git-probe.js');
 
 // This guard's outer catch has always exited 0 (fail open): a path guard that
 // cannot resolve the worktree must not block the user's edit — its whole job
@@ -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 scrubbed gitEnv() base
+// loses nothing; requiring the artifact unguarded would throw at load and the
+// containment guard would silently stop running.
+let readOnlyGitEnv = (base = process.env) => base;
+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(gitEnv()) });
 }
 
 // Walk up from `start` to find the nearest existing directory.

package/hooks/dist/lib/git-probe.js

@@ -92,7 +92,23 @@ function reportIfUndetermined(hookName, probeLabel, result) {
 const BLOCKING_GUARD_PROBE_TIMEOUT_MS = 5000;
 const BLOCKING_GUARD_MAX_SEQUENTIAL_PROBES = 3;
 
+// #5548: repo-location vars git sets in hooks; inherited, they override the
+// probe's cwd/-C. Parity-tested copy of GIT_LOCATION_ENV_VARS in
+// src/shell-command-projection.cts (hooks ship standalone and cannot import it).
+const GIT_LOCATION_ENV_VARS = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE', 'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE', 'GIT_PREFIX', 'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR',
+];
+
+/** `env` (default process.env) minus the repo-location vars (case-insensitive, for Windows). */
+function gitEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => !GIT_LOCATION_ENV_VARS.includes(k.toUpperCase())));
+}
+
 module.exports = {
+  GIT_LOCATION_ENV_VARS,
+  gitEnv,
   classifyGitProbe,
   reportIfUndetermined,
   BLOCKING_GUARD_PROBE_TIMEOUT_MS,

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');
 
@@ -465,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
@@ -518,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-graphify-update.sh

@@ -81,6 +81,12 @@ case "$COMMAND" in
   *) exit 0 ;;
 esac
 
+# #5548: inherited repo-location vars (GIT_DIR, GIT_INDEX_FILE, ...) would override
+# cwd for every git call below. Drop git's own list minus the config-injection vars.
+for v in $(git rev-parse --local-env-vars 2>/dev/null); do
+  case "$v" in GIT_CONFIG|GIT_CONFIG_PARAMETERS|GIT_CONFIG_COUNT) ;; *) unset "$v" ;; esac
+done
+
 # Gate 3 — inside git repo
 git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 

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 };