@opengsd/gsd-core 1.17.0 → 1.18.0

package/agents/gsd-roadmapper.compact.md

@@ -23,7 +23,7 @@ Job: transform requirements into a phase structure that delivers the project. Ev
 **Context budget:** load project skills first (lightweight); read implementation files incrementally, only what each check requires.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/`:
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-roadmapper`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` per skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` as needed

package/agents/gsd-roadmapper.md

@@ -27,7 +27,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-roadmapper`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-security-auditor.compact.md

@@ -44,7 +44,7 @@ Read ALL `<required_reading>` files. Extract:
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Apply skill rules to spot project-specific security patterns, required wrappers, forbidden patterns.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-security-auditor`) — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Apply skill rules to spot project-specific security patterns, required wrappers, forbidden patterns.
 </step>
 
 <step name="analyze_threats">

package/agents/gsd-security-auditor.md

@@ -50,7 +50,7 @@ Read ALL files from `<required_reading>`. Extract:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-security-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-ui-auditor.compact.md

@@ -48,7 +48,7 @@ Before auditing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if present; follow all project-specific guidelines.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/`.
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-auditor`)
 1. List available skills 2. Read `SKILL.md` for each 3. Do NOT load full `AGENTS.md` (100KB+ context cost)
 </project_context>
 

package/agents/gsd-ui-auditor.md

@@ -50,7 +50,7 @@ Before auditing, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill
 3. Do NOT load full `AGENTS.md` files (100KB+ context cost)

package/agents/gsd-ui-checker.compact.md

@@ -63,7 +63,7 @@ Before verifying: read `./CLAUDE.md` if present, follow project-specific guideli
 
 Check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-checker`) — list
 skills, read each `SKILL.md` (~130 lines), load `rules/*.md` as needed during verification. Do
 NOT load full `AGENTS.md` (100KB+ cost). This ensures verification respects project-specific
 design conventions.

package/agents/gsd-ui-checker.md

@@ -62,7 +62,7 @@ Before verifying, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-checker`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification

package/agents/gsd-ui-researcher.compact.md

@@ -29,7 +29,7 @@ GSD UI researcher, spawned by `/gsd:ui-phase`. Answer "What visual and interacti
 <project_context>
 Before researching: read `./CLAUDE.md` if it exists (follow project guidelines/security/conventions). Check `.claude/skills/` or `.agents/skills/`:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirectories; read each `SKILL.md` (~130 lines); load `rules/*.md` as needed; do NOT load full `AGENTS.md` (100KB+ cost); account for project skill patterns in the design contract.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-researcher`) — list skill subdirectories; read each `SKILL.md` (~130 lines); load `rules/*.md` as needed; do NOT load full `AGENTS.md` (100KB+ cost); account for project skill patterns in the design contract.
 </project_context>
 
 <upstream_input>
@@ -99,6 +99,18 @@ node -p "require('<pkg>/package.json').version"                            # RES
 ```
 A first-party CLI with a JSON mode, or an MCP tool the design system ships, beats all three. What matters: the command is **recorded and re-runnable**. Take the version from the installed package, not the range in your dependent's `package.json` (a caret range hides staleness).
 
+**Cross-check the first answer — always.** A tool's count is a claim: `npx shadcn info` reports "No components installed" on projects with hand-authored or pre-CLI primitives. After the first command answers, count component files on disk as a second source (shadcn: the `aliases.ui` dir in `components.json`, else `components/ui` / `src/components/ui`):
+```bash
+ls <ui-dir>/*.tsx 2>/dev/null | wc -l                                      # filesystem count
+```
+If they disagree (including a tool reporting none while files exist), do not pick silently: record the larger filesystem-backed count with the command that produced it, and add directly under the provenance line `Mismatch: <tool> reported <A>, filesystem has <B>.`
+
+**A failed lookup is a failure, never a pass-through.** `2>/dev/null` hides why `node -p` died: treat empty output, a non-zero exit, or the literal `undefined` as that step failing. With `node_modules` absent the `require()` version lookup fails; resolve from the lockfile instead (still not the caret range):
+```bash
+node -p "(require('./package-lock.json').packages['node_modules/<pkg>']||{}).version"
+```
+For `pnpm-lock.yaml` / `yarn.lock`, read `<pkg>`'s resolved version from that file. If the lockfile cannot answer, write `<version unresolved: <reason>>` in the version slot instead of leaving it empty or guessing.
+
 Record it as the first line of the section, verbatim:
 ```
 Enumerated by `<command>` — <N> components — <package>@<version> — <YYYY-MM-DD>.

package/agents/gsd-ui-researcher.md

@@ -41,7 +41,7 @@ Before researching, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-researcher`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
@@ -166,6 +166,33 @@ A first-party CLI with a JSON mode, or an MCP tool the design system ships, beat
 matters is that the command is **recorded and re-runnable**. Take the version from the installed
 package, not the range in your dependent's `package.json` — a caret range hides staleness.
 
+**Cross-check the first answer — always.** A tool's count is a claim, not a fact: `npx shadcn info`
+reports "No components installed" on a project whose primitives were hand-authored or predate the
+CLI's tracking. After the first command answers, count the component files on disk as an independent
+second source (for shadcn, the `aliases.ui` directory in `components.json`, else `components/ui` or
+`src/components/ui`):
+
+```bash
+ls <ui-dir>/*.tsx 2>/dev/null | wc -l                                      # filesystem count
+```
+
+If the two disagree — including a tool that reports none while files exist — do not pick one
+silently. Record the larger, filesystem-backed count with the command that produced it, and add a
+line directly under the provenance line: `Mismatch: <tool> reported <A>, filesystem has <B>.`
+
+**A failed lookup is a failure, never a pass-through.** `2>/dev/null` hides why a `node -p` call died,
+so treat empty output, a non-zero exit, or the literal `undefined` as that step failing. When
+`node_modules` is absent the `require()` version lookup fails; resolve the version from the lockfile
+instead — still not the caret range:
+
+```bash
+node -p "(require('./package-lock.json').packages['node_modules/<pkg>']||{}).version"
+```
+
+For `pnpm-lock.yaml` or `yarn.lock`, read the resolved version for `<pkg>` from that file. If the
+lockfile cannot answer either, say `<version unresolved: <reason>>` in the version slot rather than
+leaving it empty or guessing.
+
 Record it as the first line of the section, verbatim:
 
 ```

package/agents/gsd-verifier.md

@@ -55,7 +55,7 @@ Before verifying, discover project context:
 - Load `rules/*.md` as needed during **verification**.
 - Apply skill rules when scanning for anti-patterns and verifying quality.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-verifier`)
 </project_context>
 
 <core_principle>

package/bin/install.js

@@ -35,6 +35,7 @@ const {
   getGlobalSkillsBase,
   resolveKimiHooksTomlDir,
   isRegisteredRuntimeId,
+  resolveGsdHome,
 } = require('../gsd-core/bin/lib/runtime-homes.cjs');
 // #2870: the Install Scope Module — turns a bare 'global' | 'local' scope id
 // plus a runtime into one resolved value (configHome, settingsFile,
@@ -7033,7 +7034,7 @@ function recordDefaultsProvenance(gsdDir, runtime, defaults, setNow) {
 /** @returns {boolean} true when it removed or reverted something */
 function revertNonClaudeDefaults(runtime) {
   if (hostBehaviorsFor(runtime).nativeModelAliases || process.env.GSD_TEST_MODE) return false;
-  const gsdDir = path.join(os.homedir(), '.gsd');
+  const gsdDir = path.join(resolveGsdHome(), '.gsd'); // #5017: GSD_HOME-aware, like the loader
   const provPath = path.join(gsdDir, DEFAULTS_PROVENANCE_NAME);
   if (!fs.existsSync(provPath)) return false;
   let releaseLock = null;
@@ -7086,7 +7087,7 @@ function revertNonClaudeDefaults(runtime) {
  */
 function writeNonClaudeDefaults(runtime) {
   if (hostBehaviorsFor(runtime).nativeModelAliases || process.env.GSD_TEST_MODE) return;
-  const gsdDir = path.join(os.homedir(), '.gsd');
+  const gsdDir = path.join(resolveGsdHome(), '.gsd'); // #5017: GSD_HOME-aware, like the loader
   const defaultsPath = path.join(gsdDir, 'defaults.json');
   let releaseLock = null;
   try {
@@ -12565,6 +12566,41 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           }
         }
       }
+      // #5123: the Copilot and Antigravity converters write their DEFAULT home
+      // into `@` includes and Kimi's prompt converter leaves a prose "GSD core/"
+      // path, none of which exist when the payload lives somewhere else. Point
+      // them at the real install root (the same `$HOME/…` / absolute prefix the
+      // other runtimes use). Global installs only: a local install resolves
+      // against its project, which the converters already handle.
+      const includeRetarget = hostBehaviorsFor(runtime);
+      if (isGlobal && (includeRetarget.defaultHomeIncludeRoot || includeRetarget.retargetsGsdCoreProsePath === true)) {
+        const includePrefix = runtimeArtifactConversion._computePathPrefix({
+          isGlobal: true,
+          isOpencode: false,
+          resolvedTarget: targetDir,
+          homeDir: os.homedir(),
+        });
+        for (const relPath of manifestFiles) {
+          const fileName = path.basename(relPath);
+          if (!(fileName.endsWith('.md') || fileName.endsWith('.toml'))) continue;
+          if (fileName === 'CHANGELOG.md') continue;
+          const retargetPath = path.join(targetDir, relPath);
+          let retargetContent;
+          try {
+            retargetContent = fs.readFileSync(retargetPath, 'utf8');
+          } catch (_retargetReadErr) {
+            continue; // inaccessible or missing — never fail the install over this pass
+          }
+          const retargeted = runtimeArtifactConversion.retargetInstalledIncludes(retargetContent, includeRetarget, includePrefix);
+          if (retargeted !== retargetContent) {
+            try {
+              fs.writeFileSync(retargetPath, retargeted);
+            } catch (_retargetWriteErr) {
+              continue;
+            }
+          }
+        }
+      }
       for (const relPath of manifestFiles) {
         const fileName = path.basename(relPath);
         if (!(fileName.endsWith('.md') || fileName.endsWith('.toml'))) continue;

package/commands/gsd/code-review.md

@@ -48,6 +48,14 @@ Optional flags parsed from the `<arguments>` block:
 - `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
 
 Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<required_reading>` blocks.
+
+## Outside a phase
+
+Reviewer lanes run without a phase (`gsd_run` is defined by the runtime-launcher preamble inside workflow fences; in a plain shell call `node <install>/gsd-core/bin/gsd-tools.cjs` instead): pipe canonical repo-relative file paths (one per line) to stdin of
+`gsd_run review-lane dispatch-step --repo-root <root> --depth <quick|standard|deep> --base-sha <sha> --run-dir "$(mktemp -d)" --cap-id code-review --point execute:post --explicit <slugs> --raw`.
+`review-lane` flags are space-separated (`--depth quick`), never `--flag=value`. `--explicit` (omitted, nothing dispatches yet the call exits ok), `--depth`, `--base-sha` (lane reviews changes relative to it; commit them first) and stdin paths are required; `--run-dir` should be a fresh temp dir (default `.` writes the prompt file into the current directory); read each lane's output path (`results[].reviewPath`) from the JSON before removing it. `--cap-id`/`--point` select the `code-review` capability, which must be enabled (`workflow.code_review`) and active at `--point` — `execute:post`, or `execute:wave:post` when `workflow.code_review_point` selects it; otherwise nothing dispatches.
+`--explicit` takes comma-separated canonical slugs, no spaces (`codex,antigravity`), not flag aliases (`antigravity`, not `agy`); slugs: first column of `gsd_run review-lane sections` (`review-lane flags` lists flags/aliases).
+Each lane declares its own model key, which is not always its slug (antigravity's is `review.models.agy`); see the `review.models.*` table in `docs/CONFIGURATION.md`. Unset = lane default model.
 </context>
 
 <process>

package/commands/gsd/pause-work.md

@@ -21,7 +21,7 @@ Routes to the pause-work workflow which handles:
 - Current phase detection from recent files
 - Complete state gathering (position, completed work, remaining work, decisions, blockers)
 - Handoff file creation with all context sections
-- Git commit as WIP
+- Git commit handoff
 - Resume instructions
 </objective>
 

package/gsd-core/bin/gsd-tools.cjs

@@ -312,6 +312,7 @@ try {
 } catch { /* advisory — never block */ }
 
 const { resolveActiveWorkstream, applyResolvedWorkstreamEnv, peekActiveWorkstream } = require('./lib/active-workstream-store.cjs');
+const { planningDir, planningRoot } = require('./lib/planning-workspace.cjs');
 const state = require('./lib/state.cjs');
 const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
@@ -1445,8 +1446,12 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     // Silent no-op when the section is absent or the table is already canonical
     // — the quick/fast workflows call this before their first append, so the
     // migration runs exactly once, on the first quick run, unprompted otherwise.
-    const statePath = path.join(cwd, '.planning', 'STATE.md');
+    const planningPath = planningDir(cwd);
+    const statePath = path.join(planningPath, 'STATE.md');
     if (!fs.existsSync(statePath)) {
+      if (planningPath !== planningRoot(cwd)) {
+        throw new ExitError(1, `quick-tasks-migrate: STATE.md not found at ${statePath}`);
+      }
       output({ ok: true, migrated: false, reason: `STATE.md not found at ${statePath}` }, raw);
       return;
     }
@@ -1519,7 +1524,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
             || (qtaQuickId && qtaSlug ? `[${qtaQuickId}-${qtaSlug}](./quick/${qtaQuickId}-${qtaSlug}/)` : undefined);
           const qtaStatus = qtaParsed['status'] || undefined;
 
-          const statePath = path.join(cwd, '.planning', 'STATE.md');
+          const statePath = path.join(planningDir(cwd), 'STATE.md');
           if (!fs.existsSync(statePath)) {
             error(`quick-tasks-append: STATE.md not found at ${statePath}`, ERROR_REASON.USAGE);
           }
@@ -1593,7 +1598,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     const fsx = require('node:fs');
     const os = require('node:os');
     const { REVIEWER_LANES, mergeReviewerLanes } = require('./lib/review-lane-descriptor.cjs');
-    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneBudget } = require('./lib/review-lane-invocation.cjs');
+    const { resolveLanePlan: resolveLanePlanBase, resolveLaneEffort, resolveLaneBudget, applyPromptOverride } = require('./lib/review-lane-invocation.cjs');
     // OpenCode 2.x argv differs from 1.x (no --variant; effort rides on the model as `#variant`;
     // ADR-5331 D5/D8). The generation is probed lazily, only when the opencode lane is resolved.
     const resolveLanePlan = (laneInput) => {
@@ -1945,7 +1950,7 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
       const dispatchResult = await dispatchReviewerLanes(
         {
           trait,
-          selection: { explicitFlags, detected: rosterSlugs },
+          selection: { explicitFlags, detected: rosterSlugs, lanes: mergedLanes },
           repoRoot,
           paths,
           depth,
@@ -2097,14 +2102,11 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
     }
 
     // `--prompt-file` lets the caller substitute a budget-trimmed prompt. Applied to whichever
-    // channel this lane actually reads from, so one flag serves both transports.
+    // channel this lane actually reads from (stdin, argv, an argv-embedded file reference, or the
+    // http promptPath), so one flag serves every lane (#5049).
     const promptOverride = flag('--prompt-file');
     if (promptOverride) {
-      if (entry.plan.transport === 'spawn') {
-        if (entry.plan.stdin) entry.plan.stdin = promptOverride;
-      } else {
-        entry.plan.promptPath = promptOverride;
-      }
+      entry.plan = applyPromptOverride(entry.plan, promptOverride, repoRoot);
     }
 
     // ADR-2782 D5 rule 4: re-resolve the consented destination at INVOCATION. `undefined` (no
@@ -3022,7 +3024,12 @@ function dispatchOverlayCapabilityCommand({ command, args, cwd, raw, error, load
           const jsonIdx = args.indexOf('--json');
           const agentSkillsJsonMode = jsonIdx !== -1;
           if (agentSkillsJsonMode) args.splice(jsonIdx, 1);
-          init.cmdAgentSkills(cwd, args[1], raw, agentSkillsJsonMode);
+          // #5122: the agent's own self-load asks for configured skills only,
+          // never the persona fallback served to orchestrator-side injection.
+          const skillsOnlyIdx = args.indexOf('--skills-only');
+          const agentSkillsOnly = skillsOnlyIdx !== -1;
+          if (agentSkillsOnly) args.splice(skillsOnlyIdx, 1);
+          init.cmdAgentSkills(cwd, args[1], raw, agentSkillsJsonMode, agentSkillsOnly);
   }
 
   function routeSkillManifest({ args, cwd, raw, error }) {

package/gsd-core/bin/lib/capability-ledger.cjs

@@ -807,6 +807,28 @@ function reconcile(runtimeDir) {
     }
     return result;
 }
+/**
+ * #5121: the one bounded read for a SKILL.md found by walking a skill root. A skill file is untrusted
+ * repository (or installed-runtime) content: a symlink to /dev/zero exhausts memory and a FIFO blocks
+ * the process, because a bare readFileSync does neither a type nor a size check. Reuses the fd protocol
+ * of readSmallRegularFile and maps its fail-closed "unreadable" conditions (not a regular file after
+ * following symlinks, over the cap) to null, so a caller treats the file as it treats a missing one.
+ * Any other IO error still throws, as the unbounded read did.
+ *
+ * 256 KiB: the largest shipped SKILL.md is ~21 KB, so the cap is >10x headroom while still bounding the
+ * allocation a hostile repository can force.
+ */
+const SKILL_FILE_MAX_BYTES = 256 * 1024;
+function readSkillFile(filePath) {
+    try {
+        return readSmallRegularFile(filePath, SKILL_FILE_MAX_BYTES);
+    }
+    catch (err) {
+        if (err instanceof LedgerIOError && (err.code === 'ENXIO' || err.code === 'EISDIR' || err.code === 'EFBIG'))
+            return null;
+        throw err;
+    }
+}
 module.exports = {
     readLedger,
     readLedgerStrict,
@@ -822,6 +844,9 @@ module.exports = {
     // #1459 finding 1 (HIGH): the RAW-BYTES variant — the SOLE correct reader for the byte-exact,
     // injective consent content-hash binding (a utf8 decode is lossy and could collide binary artifacts).
     readSmallRegularFileBuffer,
+    // #5121: bounded SKILL.md read shared by skill discovery, the installed-runtime manifest and capability skills.
+    readSkillFile,
+    SKILL_FILE_MAX_BYTES,
     // Exported for testing / introspection
     LEDGER_FILE_NAME,
     CorruptLedgerError,

package/gsd-core/bin/lib/capability-lock.cjs

@@ -176,7 +176,8 @@ function isSameHost(parsed) {
  * equality comparison (never parsed as a date). The pair (pid, startTime) uniquely identifies a
  * process instance: even if a crashed holder's pid is REUSED, the new process's start-time differs.
  * Returns null on ANY error / unobtainable value (liveness cannot be VERIFIED → steal-eligible past
- * the deadman). The shell-outs only run on the rare STEAL-decision path, never the happy path.
+ * the deadman). Probing ANOTHER pid only happens on the rare STEAL-decision path; this process's own
+ * start-time is probed on its first lock acquire (see selfStartTime) — never at module load (#5327).
  */
 function getProcessStartTime(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -208,11 +209,29 @@ function getProcessStartTime(pid) {
         return null;
     }
 }
-/** THIS process's start-time, captured ONCE at module load so we never re-shell on every lock write. */
-const _selfStartTime = getProcessStartTime(process.pid);
-/** Serialize the lockfile body: JSON carrying the owner token, pid, hostname, cached start-time, ts. */
-function lockFileBody(token) {
-    return JSON.stringify({ token, pid: process.pid, hostname: node_os_1.default.hostname(), startTime: _selfStartTime, ts: Date.now() });
+/**
+ * THIS process's start-time, probed on the first lock acquire and cached so later acquires never re-shell.
+ * Not probed at module load: every config read loads this module, and most never take a lock (#5327).
+ * Only a successful probe is cached. A failed one (a PowerShell launch past its 5 s timeout on a loaded
+ * Windows host) is retried on the next acquire, up to SELF_PROBE_ATTEMPTS probes in all, so a host whose
+ * probe never succeeds pays a bounded cost instead of one launch per acquire.
+ * Probed per acquire ATTEMPT, before the O_EXCL create, so a process whose first acquire meets a live
+ * holder still pays it: probing after a successful create instead would widen the empty-body window
+ * that the steal path's `LOCK_STALE_MS` floor relies on.
+ */
+const SELF_PROBE_ATTEMPTS = 2;
+let _selfStartTime = null;
+let _selfProbeAttempts = 0;
+function selfStartTime() {
+    if (_selfStartTime === null && _selfProbeAttempts < SELF_PROBE_ATTEMPTS) {
+        _selfProbeAttempts++;
+        _selfStartTime = getProcessStartTime(process.pid);
+    }
+    return _selfStartTime;
+}
+/** Serialize the lockfile body: JSON carrying the owner token, pid, hostname, start-time, ts. */
+function lockFileBody(token, startTime) {
+    return JSON.stringify({ token, pid: process.pid, hostname: node_os_1.default.hostname(), startTime, ts: Date.now() });
 }
 // ---------------------------------------------------------------------------
 // Liveness probes (test seam)
@@ -364,6 +383,9 @@ function acquireLock(lockPath, opts) {
         ? opts.maxAttempts
         : LOCK_MAX_ATTEMPTS;
     const waitForFresh = !!(opts && opts.waitForFresh);
+    // Probe BEFORE the O_EXCL create: the first probe can be a PowerShell launch, and between the create
+    // and the body write a racing acquirer sees an empty lockfile. That window must stay sub-ms (#5327).
+    const startTime = selfStartTime();
     // A held lock that is NOT steal-eligible: fail-fast (return null) by default, or BACK OFF + RETRY
     // (continue) when waitForFresh and a retry budget remains — so a contended consent writer serializes.
     const blocked = (attempt) => {
@@ -382,7 +404,7 @@ function acquireLock(lockPath, opts) {
             // write/close error, best-effort unlink the file we just created and bail. fs.writeFileSync(fd, …)
             // flushes the WHOLE buffer (no short-write) unlike a bare fs.writeSync.
             try {
-                node_fs_1.default.writeFileSync(fd, lockFileBody(token));
+                node_fs_1.default.writeFileSync(fd, lockFileBody(token, startTime));
             }
             catch (writeErr) {
                 try {