@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/config-loader.cjs

@@ -290,6 +290,56 @@ function _resetRuntimeWarningCacheForTests() {
     _warnedConfigKeys.clear();
     _warnedUnknownConfigKeys.clear();
     _warnedUnusableConfig.clear();
+    _warnedShadowedGlobalKeys.clear();
+}
+// ─── #3532 (10b): shadowed global-defaults diagnostic ────────────────────────
+// The keys Branch D's `_globalBaseCfg` demonstrably honors from
+// ~/.gsd/defaults.json when no project config exists. Under a project
+// .planning/config.json (Branch A — every real project) the global file is
+// never opened, so each of these set globally is silently inert for resolution.
+// `effort` is in Branch D's honored set but is EXCLUDED from the shadow warning:
+// the install-time effort sync (readGsdEffectiveEffortConfig) DOES merge the
+// global file, so warning on it would be false for the channel users actually
+// control via `effort sync`. Keep this list in lockstep with `_globalBaseCfg`
+// below — the per-key canary in tests/config-loader.test.cjs fails first on
+// drift in either direction.
+const GLOBAL_DEFAULTS_RESOLUTION_KEYS = [
+    'model_profile', 'commit_docs', 'research', 'plan_checker', 'verifier',
+    'nyquist_validation', 'post_planning_gaps', 'parallelization', 'text_mode',
+    'resolve_model_ids', 'context_window', 'subagent_timeout', 'model_overrides',
+    'models', 'granularity', 'granularities', 'planning', 'dynamic_routing',
+    'effort', 'fast_mode', 'agent_skills', 'response_language', 'runtime',
+    'model_profile_overrides', 'model_policy',
+];
+// Module-level dedup keyed on the SORTED shadowed-key set: a later call with
+// the same shadowed set stays quiet, while a config that grows a new shadowed
+// key re-arms the warning. Stronger than _warnedUnknownConfigKeys (which keys
+// on insertion order) — same discipline, order-independent key.
+const _warnedShadowedGlobalKeys = new Set();
+function _warnShadowedGlobalDefaults(globalDefaults, globalPath) {
+    const shadowed = GLOBAL_DEFAULTS_RESOLUTION_KEYS.filter(k => k !== 'effort' && Object.prototype.hasOwnProperty.call(globalDefaults, k));
+    // Branch D also honors the nested alias workflow.post_planning_gaps (the
+    // `?? globalDefaults['workflow']?.['post_planning_gaps']` fallback in
+    // _globalBaseCfg) — a global file using only the nested form is equally
+    // shadowed, so it reports under its dotted name.
+    if (!shadowed.includes('post_planning_gaps')) {
+        const wf = globalDefaults['workflow'];
+        if (wf && typeof wf === 'object' && !Array.isArray(wf) &&
+            Object.prototype.hasOwnProperty.call(wf, 'post_planning_gaps')) {
+            shadowed.push('workflow.post_planning_gaps');
+        }
+    }
+    if (shadowed.length === 0)
+        return;
+    const dedupKey = shadowed.slice().sort().join(',');
+    if (_warnedShadowedGlobalKeys.has(dedupKey))
+        return;
+    _warnedShadowedGlobalKeys.add(dedupKey);
+    try {
+        process.stderr.write(`gsd-tools: warning: ${globalPath} sets ${shadowed.join(', ')} but a project config ` +
+            `takes precedence here — those global keys are ignored for model resolution. (#3532)\n`);
+    }
+    catch { /* stderr might be closed in some test harnesses */ }
 }
 // ─── FIX 2: Federated overlay helpers ────────────────────────────────────────
 /**
@@ -751,6 +801,13 @@ function loadConfigResolved(cwd, options = {}) {
             fast_mode: (parsed['fast_mode']) || null,
             agent_skills: (parsed['agent_skills']) || {},
             agent_skills_security: (parsed['agent_skills_security']) || null,
+            // #3587: phase_commit_docs.<phase-id> — a dynamic-key family shaped like
+            // agent_skills above (`{ "<phase-id>": boolean }`). Must be threaded here
+            // explicitly: `_baseConfig` is a hand-maintained allowlist, so a key that
+            // is only in config-schema.manifest.json's dynamicKeyPatterns (and not
+            // projected here) is silently dropped on read — the exact `features`-key
+            // failure mode this module's own A3 test guards against.
+            phase_commit_docs: (parsed['phase_commit_docs']) || {},
             manager: (parsed['manager']) || {},
             response_language: get('response_language') || null,
             claude_md_path: get('claude_md_path') || null,
@@ -777,6 +834,22 @@ function loadConfigResolved(cwd, options = {}) {
         // A1 vs A2: disambiguate by whether a real workstream was requested.
         // Fix 4: empty-string ws ('') resolves the root path → source:'root'.
         const source = wsRequested ? 'workstream' : 'root';
+        // #3532 (10b): a parsed project config means Branch D never runs, so every
+        // key ~/.gsd/defaults.json sets that Branch D would honor is silently inert
+        // here. Observation only — one deduped stderr warning; precedence is
+        // untouched. Faults in the global file stay silent in this branch (the
+        // project config governs; the nearer file is the actionable one).
+        try {
+            const shadowHome = process.env['GSD_HOME'] || node_os_1.default.homedir();
+            const shadowPath = node_path_1.default.join(shadowHome, '.gsd', 'defaults.json');
+            const shadowRead = _readConfigFile(shadowPath);
+            if (shadowRead.kind === 'ok') {
+                _warnShadowedGlobalDefaults(shadowRead.data, shadowPath);
+            }
+        }
+        catch {
+            // Observation only — never let the diagnostic perturb resolution.
+        }
         // This config parsed — but a DIFFERENT file on the resolution path may not
         // have. A workstream config that loads cleanly while the root config it
         // inherits from is corrupt is still a degraded resolution: the root's
@@ -908,6 +981,8 @@ module.exports = {
     _getNestedConfigDefault,
     _deepMergeConfig,
     _warnedUnknownConfigKeys,
+    _warnedShadowedGlobalKeys,
+    GLOBAL_DEFAULTS_RESOLUTION_KEYS,
     _warnUnknownProfileOverrides,
     _resetRuntimeWarningCacheForTests,
     _warnedConfigKeys,

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

@@ -68,6 +68,9 @@ const SCHEMA_DEFAULTS = {
     'planner.stall_detect_interval_minutes': 5,
     'planner.stall_threshold_minutes': 10,
     'git.create_tag': true,
+    // #1689: per-plan agent_hint executor routing — default-on. A no-op for plans
+    // without an agent_hint field, so existing dispatch is byte-identical.
+    'workflow.agent_hint_routing': true,
     // Derived from the defaults manifest rather than restated, so the manifest
     // stays the single source of truth for the smart-zone budget (#2630).
     'workflow.smart_zone_tokens': CONFIG_DEFAULTS.smart_zone_tokens,
@@ -652,7 +655,7 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
     const val = value;
     validateKnownConfigKeyPath(kp);
     if (!isValidConfigKey(kp, cwd)) {
-        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>`, ERROR_REASON.CONFIG_INVALID_KEY);
+        error(`Unknown config key: "${kp}". Valid keys: ${[...VALID_CONFIG_KEYS].sort().join(', ')}, agent_skills.<agent-type>, features.<feature_name>, phase_commit_docs.<phase-id>`, ERROR_REASON.CONFIG_INVALID_KEY);
     }
     // Parse value (handle booleans, numbers, and JSON arrays/objects)
     let parsedValue = val;
@@ -736,6 +739,12 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
             error(`Invalid workflow.post_planning_gaps '${val}'. Must be a boolean (true or false).`);
         }
     }
+    // Per-plan executor routing via agent_hint frontmatter (#1689)
+    if (kp === 'workflow.agent_hint_routing') {
+        if (typeof parsedValue !== 'boolean') {
+            error(`Invalid workflow.agent_hint_routing '${val}'. Must be a boolean (true or false).`);
+        }
+    }
     // #3086 — git.create_tag: boolean only
     if (kp === 'git.create_tag') {
         if (typeof parsedValue !== 'boolean') {

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

@@ -23,7 +23,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
-const { comparePhaseNum } = phaseIdModule;
+const { comparePhaseNum, scopeToPhase } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { findContextMdIn } = planningWorkspace;
@@ -72,17 +72,30 @@ function extractOneLinerFromBody(content) {
     if (!content)
         return null;
     const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-    const body = normalized.replace(/^---\n[\s\S]*?\n---\n*/, '');
-    const match = body.match(/^#[^\n]*\n+\*\*([^*\n]+)\*\*([^\n]*)/m);
-    if (!match)
-        return null;
-    const boldInner = match[1].trim();
-    const afterBold = match[2];
-    if (/:\s*$/.test(boldInner)) {
-        const prose = afterBold.trim();
-        return prose.length > 0 ? prose : null;
+    const body = normalized.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n*/, '');
+    // #3170: anchor to a summary-shaped heading (Summary / Overview /
+    // Accomplishments) so an incidental first heading (a rule list, task
+    // breakdown, deviation note) does not contribute its first bold run as the
+    // deliverable one-liner. Iterate headings in document order and extract from
+    // the first summary-shaped one that has a bold run; fall back to null (not the
+    // wrong text) when no such heading exists.
+    const headingRe = /^#+\s*([^\n]*)\n+\*\*([^*\n]+)\*\*([^\n]*)/gm;
+    let match;
+    while ((match = headingRe.exec(body)) !== null) {
+        if (!/summary|overview|accomplish/i.test(match[1]))
+            continue;
+        const boldInner = match[2].trim();
+        const afterBold = match[3];
+        if (/:\s*$/.test(boldInner)) {
+            const prose = afterBold.trim();
+            if (prose.length > 0)
+                return prose;
+        }
+        else if (boldInner.length > 0) {
+            return boldInner;
+        }
     }
-    return boldInner.length > 0 ? boldInner : null;
+    return null;
 }
 // ─── Misc utilities ───────────────────────────────────────────────────────────
 function pathExistsInternal(cwd, targetPath) {
@@ -151,27 +164,66 @@ function transliterateForSlug(text) {
     }
     return out;
 }
-// ─── Phase file helpers ──────────────────────────────────────────────────────
-/** Filter a file list to just PLAN.md / *-PLAN.md entries. */
-function filterPlanFiles(files) {
-    return files.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
-}
-/** Filter a file list to just SUMMARY.md / *-SUMMARY.md entries. */
-function filterSummaryFiles(files) {
-    return files.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
-}
 /**
  * Read a phase directory and return counts/flags for common file types.
+ *
+ * #3183 (ADR-3180 Decision 2): `plans`/`summaries` are derived from the
+ * canonical `scanPhasePlans` rather than a local re-derivation, so this
+ * primitive can no longer diverge from the single owner of live-plan
+ * counting. `scanPhasePlans`
+ * lives in plan-scan.cjs, which itself imports `countMatchedSummaries` from
+ * THIS module — a top-level import here would be circular, so the require
+ * is deferred (lazy, inside the function body) to break the cycle at load
+ * time. This mirrors the lazy-require seam already used elsewhere in this
+ * repo (see src/audit-command-router.cts) for the same "module A needs
+ * module B which needs module A" shape.
+ *
+ * `hasResearch`/`hasContext`/`hasVerification`/`hasReviews` stay on the raw
+ * `readdirSync` listing — they are not plan-scan concerns.
+ *
+ * #3511 BLOCKER-2: the raw listing is scoped through `scopeToPhase` (keyed on
+ * `path.basename(phaseDir)`) before any of the four artifact predicates run,
+ * so a stray cross-phase file (e.g. `04-VERIFICATION.md` sitting inside phase
+ * 03's directory) cannot flip `hasResearch`/`hasContext`/`hasVerification`/
+ * `hasReviews` true for a phase it does not belong to — the same membership
+ * rule every other aggregate phase-directory scan (`uat.cts`, `audit.cts`,
+ * `phase.cts`, `state.cts`) already routes through. `hasContext` is scoped by
+ * passing the already-scoped array into `findContextMdIn` at this call site
+ * only — `findContextMdIn` itself is unchanged and its other 4 call sites
+ * (roadmap.cts, gap-checker.cts, init.cts) are unaffected.
+ *
+ * Degrades on an unreadable directory instead of throwing: empty arrays,
+ * every flag false, scope UNREADABLE (mirroring scanPhasePlans's own
+ * degrade path).
  */
 function getPhaseFileStats(phaseDir) {
-    const files = node_fs_1.default.readdirSync(phaseDir);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const scanPhasePlans = require('./plan-scan.cjs');
+    const scan = scanPhasePlans(phaseDir);
+    let files;
+    try {
+        files = node_fs_1.default.readdirSync(phaseDir);
+    }
+    catch {
+        return {
+            plans: scan.planFiles,
+            summaries: scan.summaryFiles,
+            hasResearch: false,
+            hasContext: false,
+            hasVerification: false,
+            hasReviews: false,
+            scope: scan.scope,
+        };
+    }
+    const scopedFiles = scopeToPhase(files, node_path_1.default.basename(phaseDir));
     return {
-        plans: filterPlanFiles(files),
-        summaries: filterSummaryFiles(files),
-        hasResearch: files.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
-        hasContext: findContextMdIn(files) !== null,
-        hasVerification: files.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
-        hasReviews: files.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
+        plans: scan.planFiles,
+        summaries: scan.summaryFiles,
+        hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
+        hasContext: findContextMdIn(scopedFiles) !== null,
+        hasVerification: scopedFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
+        hasReviews: scopedFiles.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
+        scope: scan.scope,
     };
 }
 /**
@@ -297,6 +349,35 @@ function summaryCandidates(plan) {
     const extended = base.match(/^(\d+)-PLAN-(\d+)/i);
     if (extended)
         candidates.push(dir + extended[1] + '-' + extended[2] + '-SUMMARY.md');
+    // #3183: canonical-id form. Restores the coverage of the pre-migration
+    // bespoke I001 rule (verify.cts, pre-#3183, via validate.cjs's now-unused
+    // `canonicalPlanStem` — behaviourally identical to `extractCanonicalPlanId`,
+    // confirmed empirically), which matched a plan carrying a descriptive slug
+    // after its <phase>-<plan> id — e.g. `68-01-scaffolding-PLAN.md` — against
+    // a summary named only by the bare id — `68-01-SUMMARY.md`. None of the
+    // three candidates above produce that filename.
+    //
+    // Narrowed to the case `extractCanonicalPlanId` actually extracted an
+    // <id>-<id> pair (its result differs from the plan's own PLAN-stripped
+    // base). When no pair is found it falls back to returning that same base
+    // unchanged, which would otherwise push a redundant candidate identical to
+    // the `<stem>-SUMMARY.md` form above (e.g. `setup-PLAN.md` -> canonical
+    // 'setup' -> 'setup-SUMMARY.md', already candidate #2) rather than the
+    // original rule's actual behavior of matching only real id pairs.
+    //
+    // Collision, matching the original rule byte-for-behaviour: two plans that
+    // share the same <phase>-<plan> id but differ only in their descriptive
+    // slug (`68-01-alpha-PLAN.md` + `68-01-beta-PLAN.md`) both generate the
+    // SAME candidate `68-01-SUMMARY.md` and therefore BOTH read as summarized
+    // off one shared summary file. This is not a new regression: the
+    // pre-migration bespoke rule collapsed the same way (it populated one
+    // `summaryBases` Set keyed by canonical stem, so any plan whose canonical
+    // stem hit the set counted as matched, with no cardinality check against
+    // how many plans shared that stem).
+    const planStem = base.replace(/-PLAN$/i, '');
+    const canonicalId = extractCanonicalPlanId(base + '.md');
+    if (canonicalId !== planStem)
+        candidates.push(dir + canonicalId + '-SUMMARY.md');
     return candidates;
 }
 /**
@@ -314,6 +395,24 @@ function findUnsummarizedPlans(planFiles, summaryFiles) {
     const summarySet = new Set(summaryFiles);
     return planFiles.filter((plan) => !summaryCandidates(plan).some((c) => summarySet.has(c)));
 }
+/**
+ * #3183: the mirror image of `findUnsummarizedPlans` — the summary files in
+ * `summaryFiles` that do NOT pair with ANY plan in `planFiles`, using the
+ * identical `summaryCandidates` matching rule as `countMatchedSummaries` /
+ * `findUnsummarizedPlans`. Callers that must name orphaned summaries (a
+ * stray non-plan summary, or a summary whose plan was renamed/removed) need
+ * this instead of a bespoke exact-suffix Set-diff, which cannot recognize
+ * the nested or extended naming forms `summaryCandidates` already handles —
+ * a divergence that produced false "orphan summary" warnings.
+ */
+function findOrphanSummaries(planFiles, summaryFiles) {
+    const claimed = new Set();
+    for (const plan of planFiles) {
+        for (const candidate of summaryCandidates(plan))
+            claimed.add(candidate);
+    }
+    return summaryFiles.filter((s) => !claimed.has(s));
+}
 module.exports = {
     toPosixPath,
     detectSubRepos,
@@ -321,12 +420,11 @@ module.exports = {
     pathExistsInternal,
     generateSlugInternal,
     transliterateForSlug,
-    filterPlanFiles,
-    filterSummaryFiles,
     getPhaseFileStats,
     readSubdirectories,
     timeAgo,
     extractCanonicalPlanId,
     countMatchedSummaries,
     findUnsummarizedPlans,
+    findOrphanSummaries,
 };

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

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractDecisions = extractDecisions;
 exports.parseDecisions = parseDecisions;
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const token_scanner_cjs_1 = require("./token-scanner.cjs");
 const DISCRETION_HEADINGS = new Set([
     "claude's discretion",
     'claudes discretion',
@@ -89,12 +90,14 @@ function parseDecisionLines(block) {
     let category = '';
     let inDiscretion = false;
     let current = null;
+    let openIndent = null;
     let parseMisses = 0;
     const flush = () => {
         if (current) {
             current.text = current.text.trim();
             out.push(current);
             current = null;
+            openIndent = null;
         }
     };
     for (const line of lines) {
@@ -115,6 +118,23 @@ function parseDecisionLines(block) {
             inDiscretion = DISCRETION_HEADINGS.has(normalized);
             continue;
         }
+        // Nested bullet under an open decision (#3212 Phase 3, #3169): a bullet
+        // indented deeper than the currently-open decision's own bullet is that
+        // decision's elaboration (e.g. a cross-reference to a sibling decision),
+        // not a fresh declaration attempt — fold it into current.text exactly
+        // like a continuation line, before it ever reaches the declaration/
+        // parse-miss regexes below. A bullet at the SAME or a SHALLOWER indent
+        // is unaffected — tested exactly as before this fix. See design doc
+        // .gsd/phase/chore-3414-tokenizer-first-seam/40-design.md §1.3 for why
+        // nesting depth, not bullet content, is the signal that distinguishes
+        // this from a genuinely malformed top-level declaration.
+        if (current &&
+            openIndent !== null &&
+            trimmed.startsWith('-') &&
+            (0, token_scanner_cjs_1.indentWidth)(line) > openIndent) {
+            current.text += ' ' + trimmed;
+            continue;
+        }
         // Colon form: `- **D-NN[ [tags]]:** text`
         const colonMatch = line.match(bulletColonRe);
         if (colonMatch) {
@@ -125,6 +145,7 @@ function parseDecisionLines(block) {
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
             current = { id, text: colonMatch[3], category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Em-dash form: `- **D-NN[ [tags]] — title** body`
@@ -140,6 +161,7 @@ function parseDecisionLines(block) {
             // title itself is embedded in the bold run but we report the body as text
             // (consistent with how the gate cares only about coverage, not title/body split).
             current = { id, text: emDashMatch[3] || '', category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Titled-colon form: `- **D-NN[ [tags]]: Title.** body` (#1639). Checked LAST — it is
@@ -155,6 +177,7 @@ function parseDecisionLines(block) {
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
             current = { id, text: titledColonMatch[3] || '', category, tags, trackable };
+            openIndent = (0, token_scanner_cjs_1.indentWidth)(line);
             continue;
         }
         // Parse-miss guard (FIX B + #1343): a line that looks like a `D-NN` decision

package/gsd-core/bin/lib/fallow-runner.cjs

@@ -8,6 +8,13 @@
  *
  * Parses the real fallow `audit --format json` schema (schema_version 3
  * envelope, nested dead_code/duplication sections). See fallow 2.70.0+.
+ *
+ * #3411 Phase 2 (#3618): binary resolution no longer lives here — it delegates
+ * to the platform seam's `resolveExecutableBinary` (shell-command-projection.cts).
+ * This file's prior private resolver deliberately included an extensionless
+ * `fallow` as a win32 candidate; the seam does not, and that is a fix, not a
+ * regression — an extensionless file sitting beside `fallow.cmd` is npm's POSIX
+ * `sh` shim, which `CreateProcess` cannot run (#3275).
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -19,51 +26,20 @@ exports.normalizeFallowReport = normalizeFallowReport;
 exports.normalizeFallowReportFile = normalizeFallowReportFile;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-function candidateNames() {
-    return process.platform === 'win32'
-        ? ['fallow.exe', 'fallow.cmd', 'fallow.bat', 'fallow']
-        : ['fallow'];
-}
-function isExecutableFile(filePath) {
-    try {
-        const stat = node_fs_1.default.statSync(filePath);
-        if (!stat.isFile())
-            return false;
-        if (process.platform === 'win32')
-            return true;
-        node_fs_1.default.accessSync(filePath, node_fs_1.default.constants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function findInPath(envPath) {
-    if (!envPath)
-        return null;
-    const names = candidateNames();
-    const segments = envPath.split(node_path_1.default.delimiter).filter(Boolean);
-    for (const segment of segments) {
-        for (const name of names) {
-            const candidate = node_path_1.default.join(segment, name);
-            if (isExecutableFile(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-function findInNodeModules(cwd) {
-    const names = candidateNames();
-    const binDir = node_path_1.default.join(cwd, 'node_modules', '.bin');
-    for (const name of names) {
-        const candidate = node_path_1.default.join(binDir, name);
-        if (isExecutableFile(candidate))
-            return candidate;
-    }
-    return null;
-}
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 function resolveFallowBinary({ cwd, envPath = process.env['PATH'] ?? '' }) {
-    return findInNodeModules(cwd) || findInPath(envPath) || null;
+    return (0, shell_command_projection_cjs_1.resolveExecutableBinary)('fallow', {
+        prependPaths: [node_path_1.default.join(cwd, 'node_modules', '.bin')],
+        // #3619 (epic #3411 Phase 3): pathOverride carries envPath as the search
+        // path while leaving `env` unset, so the seam falls back to its default
+        // `env` (process.env) for everything else — PATHEXT included. Ambient
+        // PATHEXT therefore still governs win32 resolution exactly as before, but
+        // this file never reads it itself: that's what keeps this module clean
+        // under local/no-private-binary-resolution, which forbids a PATHEXT read
+        // outside the seam.
+        pathOverride: envPath,
+        requireExecutable: true,
+    });
 }
 function requireFallowBinary({ cwd, envPath = process.env['PATH'] ?? '' }) {
     const binary = resolveFallowBinary({ cwd, envPath });