fix(pregate): a wtree failure is WTREE_UNAVAILABLE, not an unresolvable base (#3197)

The pregate consumers of the working-tree fingerprint (buildContext,
withFingerprint, verifyPregate) move to lib/script-invocation.ts's
{tree}|{error} form, and lib/regen.ts drops its string-returning wrapper.

- A fingerprint failure was reported as "policy source unavailable:
  origin/<base> is not a resolvable commit" with git fetch as the fix. It is
  now WTREE_UNAVAILABLE: a launch failure lists each Windows bash candidate
  with its rejection reason and names GSTACK_GIT_BASH; a gstack-wtree exit
  keeps the repair it printed (set TMPDIR to a writable directory).
- A fingerprint failing after a check is incomplete with that cause, not
  "working tree changed"; verify says the tree cannot be fingerprinted.
- #3190's gstack-config read (test_backend) goes through runScriptSync, so
  Windows reaches it through Git Bash. The tripwire learns the bin-constant
  shape that let it through.
- Under --json every context refusal is one envelope on stdout
  ({ok:false,status:'refused',code,detail,fix,docs}, exit 3); the run object
  carries ok and status too, and GSTACK_RESULT goes to stderr.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

bin/gstack-doctor-components.sh

@@ -213,6 +213,7 @@ gstack_result_anchor() {
     BASH_UNAVAILABLE) printf '%s' 'bash-unavailable' ;;
     IOS_LAUNCH_ENV_INVALID) printf '%s' 'ios-launch-env-invalid' ;;
     OUTSIDE_VOICE_UNAVAILABLE) printf '%s' 'outside-voice-unavailable' ;;
+    WTREE_UNAVAILABLE) printf '%s' 'wtree-unavailable' ;;
     *) return 1 ;;
   esac
 }

bin/gstack-pregate

@@ -28,12 +28,12 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { EXIT, exitTableHelp, formatResult, type PregateFile } from '../lib/headless-artifacts';
 import { PREGATE_CONFIG_PATH, exampleConfigJson, explainConfig, loadConfigFromHead } from '../lib/pregate/config';
-import { buildContext } from '../lib/pregate/context';
+import { buildContext, describeRefusal } from '../lib/pregate/context';
 import { CHECKS, CHECK_IDS, PREGATE_OUT_REL, PREGATE_TIER2, clearDecision, clearObligation, readPregateFile, renderTable, runPregate, verifyPregate, writePregateFile } from '../lib/pregate/index';
 import { describeLane, discoverLanes } from '../lib/pregate/workflows';
 import { REMOTE_GATE_LANE } from '../lib/pregate/checks/lanes';
 import { ensureTmpExcluded } from '../lib/restamp';
-import { RESULT_CODES, resultCodeSuffix, resultLine, type ResultCodeName } from '../lib/result-codes';
+import { RESULT_CODES, resultCodeSuffix, resultLine } from '../lib/result-codes';
 import { DEFAULT_STALL_TIMEOUT_S } from '../lib/pregate/context';
 import { cancelActive } from '../lib/pregate/supervise';
 import { defaultGh, evaluateRegate, renderRegate } from '../lib/pregate/regate';
@@ -75,14 +75,17 @@ const HELP = `gstack-pregate — cheap checks before anything paid or remote (do
   --spend-cap <usd>             the cap --remote passes to the gate (default \$GSTACK_SPEND_CAP_USD); spend is reported as
                                 spent, reserved and unknown
   --explain                     print each selected test's provenance and each uncertain mapping
-  --json                        JSON only on stdout
+  --json                        one JSON object on stdout; a refusal before any check runs (unavailable base, invalid pin
+                                file, WTREE_UNAVAILABLE) is {ok:false,status:'refused',code,detail,fix,docs} with exit 3,
+                                and a run carries ok and status (complete|incomplete); GSTACK_RESULT goes to stderr
 
 A failing check blocks (exit 1); incomplete never passes; requires-remote lanes are persisted
 obligations publication needs receipts for. Under 8 cores, a base-branch remote_gate or a remote
 test_backend (gstack-config) records the local test tier as a requires-remote obligation with the
 command to run instead of running it. Test progress goes to stderr live (PREGATE_TEST: per file
 for bun test, PREGATE_HEARTBEAT: after each 60 s without progress, then PREGATE: tests <verdict>);
---json keeps stdout to the JSON document. Ends with GSTACK_RESULT: skill=pregate status=… run=<pregate.json>.
+--json keeps stdout to the JSON document. Ends with GSTACK_RESULT: skill=pregate status=… run=<pregate.json>
+(on stderr under --json).
 ${exitTableHelp()}`;
 
 function flag(args: string[], name: string): string | undefined { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
@@ -144,9 +147,10 @@ async function cmdRun(root: string, rest: string[], json: boolean): Promise<numb
   const base = resolveBaseBranch(root, flag(rest, '--base'));
   const loaded = buildContext({ repoRoot: root, base, policyFrom, allowRepoCommands: allow, timeoutMs, stallTimeoutMs, remote, knownChecks: [...CHECK_IDS, ...PREGATE_TIER2] });
   if ('refused' in loaded) {
-    const { code, message } = loaded.refused;
-    process.stderr.write((code === 'POLICY_SOURCE_UNAVAILABLE' ? policyUnavailableLine('gstack-pregate', base, message).replace('.gstack/ship-policy.json', 'pin files') : resultLine('gstack-pregate', code as ResultCodeName, message)) + '\n');
-    process.stdout.write(formatResult('pregate', 'refused', `origin/${base}`) + '\n');
+    const refusal = describeRefusal(loaded.refused, base);
+    process.stderr.write(refusal.line + '\n');
+    if (json) process.stdout.write(JSON.stringify({ ok: false, status: 'refused', code: refusal.code, detail: refusal.detail, fix: refusal.fix, docs: refusal.docs }) + '\n');
+    (json ? process.stderr : process.stdout).write(formatResult('pregate', 'refused', `origin/${base}`) + '\n');
     return EXIT.refused;
   }
   const ctx = loaded.ctx;
@@ -165,7 +169,11 @@ async function cmdRun(root: string, rest: string[], json: boolean): Promise<numb
   catch (e: any) { process.stderr.write(resultLine('gstack-pregate', 'ARTIFACT_SCHEMA', e.message) + '\n'); return EXIT.fail; }
   const blocking = file.checks.some(c => c.status === 'fail' || c.status === 'incomplete' || c.status === 'not_installed');
   const status = file.checks.some(c => c.status === 'incomplete' || c.status === 'not_installed') && !file.checks.some(c => c.status === 'fail') ? 'incomplete' : 'complete';
-  if (json) { process.stdout.write(JSON.stringify({ ...file, out: written, explain: rest.includes('--explain') ? ctx.explain : undefined, ok: !blocking }) + '\n'); return blocking ? EXIT.fail : EXIT.ok; }
+  if (json) {
+    process.stdout.write(JSON.stringify({ ...file, out: written, explain: rest.includes('--explain') ? ctx.explain : undefined, ok: !blocking, status }) + '\n');
+    process.stderr.write(formatResult('pregate', status, written) + '\n');
+    return blocking ? EXIT.fail : EXIT.ok;
+  }
   process.stdout.write(`pregate: policy ${ctx.configLabel}; registry ${ctx.registryLabel}; base ${ctx.baseRef}@${ctx.baseSha.slice(0, 12)}; ${ctx.touched.length} touched file(s); platform ${ctx.platform}\n`);
   process.stdout.write(renderTable(file));
   if (rest.includes('--explain')) { process.stdout.write('--- explain ---\n'); for (const line of ctx.explain) process.stdout.write(`${line}\n`); }

docs/troubleshooting.md

@@ -3334,3 +3334,40 @@ unset, not in bare mode). Then re-run the review.
 
 **Expected result.** An `OUTSIDE VOICE (...)` report, or `CODEX SAYS (plan
 review — outside voice)` when the provider runs.
+
+<a id="wtree-unavailable"></a>
+### `gstack-pregate: cannot fingerprint the working tree: bin/gstack-wtree could not start (on Windows, no Git Bash was found) or it ran and failed (<detail>); fix: <fix> (WTREE_UNAVAILABLE)`
+
+**Meaning.** `gstack-pregate` fingerprints the working tree with
+`bin/gstack-wtree` before any check runs, and refuses (exit 3) when it cannot.
+There are two causes, and the line says which:
+
+- **It could not start.** On Windows no Git Bash was found to run the script.
+  The detail lists every candidate tried with the reason it was rejected
+  (`GSTACK_GIT_BASH (unset): not set; git --exec-path …; install path …;
+  PATH bash: …`), in the order [`BASH_UNAVAILABLE`](#bash-unavailable)
+  describes. On macOS or Linux it means `bin/gstack-wtree` is missing.
+- **It ran and failed.** The detail is the script's own message, and the fix
+  is the repair it printed, for example `set TMPDIR to a writable directory`.
+
+Before this, both cases were reported as `policy source unavailable:
+origin/<base> is not a resolvable commit` with `git fetch` as the fix, which
+changed nothing.
+
+**Fix.** Run the fix the line prints. For the Windows case, point gstack at
+Git Bash's `bash.exe`, then rerun `gstack-pregate`:
+
+- Git Bash (this shell only): `export GSTACK_GIT_BASH='C:/Program Files/Git/bin/bash.exe'`
+- Windows PowerShell 5.1 or PowerShell 7 (this shell only):
+  `$env:GSTACK_GIT_BASH = 'C:\Program Files\Git\bin\bash.exe'`
+
+To set it for good (Claude Code reads it on its next start), follow the
+recipes under [`BASH_UNAVAILABLE`](#bash-unavailable), or install Git for
+Windows (`winget install --id Git.Git -e` in PowerShell).
+
+**With `--json`.** Every refusal before a check runs (this one, an
+unavailable base, an invalid pin file) is one JSON object on stdout,
+`{"ok":false,"status":"refused","code":"WTREE_UNAVAILABLE","detail":"…","fix":"…","docs":"…#wtree-unavailable"}`,
+with exit 3. A run's object carries the same `ok` and `status`
+(`complete` or `incomplete`), so `status` tells a refusal from a run. The
+`GSTACK_RESULT:` line goes to stderr under `--json`.

lib/pregate/context.ts

@@ -11,7 +11,10 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { wtreeFingerprint, isRegistryUnavailable, loadRegistryFromBase, loadRegistryFromHead, type Registry } from '../regen';
+import { isRegistryUnavailable, loadRegistryFromBase, loadRegistryFromHead, type Registry } from '../regen';
+import { RESULT_CODES, TROUBLESHOOTING_DOC, resultLine } from '../result-codes';
+import { runScriptSync, wtreeFingerprint, type InvocationOptions, type WtreeResult } from '../script-invocation';
+import { policyUnavailableLine } from '../ship-policy';
 import { isConfigUnavailable, loadConfigFromBase, loadConfigFromHead, type ConfigError, type PregateConfig } from './config';
 import type { CheckResult, PregateContext, TouchedFile } from './types';
 import { discoverLanes } from './workflows';
@@ -22,17 +25,54 @@ export interface BuildContextOptions {
   timeoutMs?: number; env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform; knownChecks?: readonly string[];
   /** `--stall-timeout`; default the config's `stall_timeout_s`, else 300 s. */
   stallTimeoutMs?: number; progress?: (line: string) => void; cores?: number; testBackend?: string; remote?: { spendCapUsd: number } | null;
+  /** How gstack's own bash bins launch (gstack-wtree, gstack-config); tests inject a Windows probe. */
+  invocation?: InvocationOptions;
 }
 
 export const DEFAULT_STALL_TIMEOUT_S = 300;
 const GSTACK_CONFIG = path.resolve(import.meta.dir, '..', '..', 'bin', 'gstack-config');
 
 /** `gstack-config get test_backend` (local | ubicloud); `local` when unreadable. */
-export function readTestBackend(env: NodeJS.ProcessEnv): string {
-  const r = spawnSync(GSTACK_CONFIG, ['get', 'test_backend'], { encoding: 'utf8', timeout: 15_000, env, stdio: ['ignore', 'pipe', 'ignore'] });
+export function readTestBackend(env: NodeJS.ProcessEnv, invocation?: InvocationOptions): string {
+  const r = runScriptSync(GSTACK_CONFIG, ['get', 'test_backend'], { encoding: 'utf8', timeout: 15_000, env, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }, invocation);
   return (r.status === 0 && (r.stdout ?? '').trim()) || 'local';
 }
-export type ContextLoad = { ctx: PregateContext } | { refused: { code: 'POLICY_SOURCE_UNAVAILABLE' | 'PREGATE_CONFIG_INVALID' | 'REGEN_REGISTRY_INVALID'; message: string; errors?: Array<ConfigError | RegistryError> } };
+export interface ContextRefusal {
+  code: 'POLICY_SOURCE_UNAVAILABLE' | 'PREGATE_CONFIG_INVALID' | 'REGEN_REGISTRY_INVALID' | 'WTREE_UNAVAILABLE';
+  message: string;
+  /** A cause-specific fix that replaces the code's own (a gstack-wtree exit names its repair). */
+  fix?: string;
+  errors?: Array<ConfigError | RegistryError>;
+}
+export type ContextLoad = { ctx: PregateContext } | { refused: ContextRefusal };
+
+/**
+ * A failed fingerprint as a refusal. A launch failure lists each Windows bash
+ * candidate tried with its rejection reason and keeps WTREE_UNAVAILABLE's fix
+ * (GSTACK_GIT_BASH); a helper exit keeps the repair gstack-wtree printed after
+ * its last `; ` (for example `set TMPDIR to a writable directory`).
+ */
+export function wtreeRefusal(fp: Extract<WtreeResult, { error: string }>): ContextRefusal {
+  if (fp.kind === 'launch') {
+    const message = fp.tried?.length ? `gstack-wtree could not start: no Git Bash found; tried ${fp.tried.map(c => `${c.source} ${c.path}: ${c.rejected}`).join('; ')}` : fp.error;
+    return { code: 'WTREE_UNAVAILABLE', message, fix: RESULT_CODES.WTREE_UNAVAILABLE.fix };
+  }
+  const cut = fp.error.lastIndexOf('; ');
+  if (cut > 0) return { code: 'WTREE_UNAVAILABLE', message: fp.error.slice(0, cut), fix: fp.error.slice(cut + 2) };
+  return { code: 'WTREE_UNAVAILABLE', message: fp.error, fix: 'run bin/gstack-wtree in the repository to see why it fails (it exits 1 outside a git repository, in one with no commits, or when a write fails), repair that, then rerun gstack-pregate' };
+}
+
+export interface RefusalReport { code: ContextRefusal['code']; detail: string; fix: string; docs: string; line: string }
+
+/** One context refusal as its stderr line and as the fields of the `--json` envelope. */
+export function describeRefusal(refused: ContextRefusal, base: string, context = 'gstack-pregate'): RefusalReport {
+  const { code, message } = refused;
+  const row = RESULT_CODES[code];
+  const docs = `${TROUBLESHOOTING_DOC}#${row.anchor}`;
+  if (code === 'POLICY_SOURCE_UNAVAILABLE') return { code, detail: message, fix: row.fix.replace('<base>', base), docs, line: policyUnavailableLine(context, base, message).replace('.gstack/ship-policy.json', 'pin files') };
+  if (!refused.fix) return { code, detail: message, fix: row.fix, docs, line: resultLine(context, code, message) };
+  return { code, detail: message, fix: refused.fix, docs, line: `${context}: ${row.summary} (${message}); fix: ${refused.fix} (${code})` };
+}
 
 function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv): { ok: boolean; out: string; err: string } {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024, env });
@@ -76,10 +116,11 @@ export function buildContext(o: BuildContextOptions): ContextLoad {
   const registryLoad = o.policyFrom === 'head' ? loadRegistryFromHead(o.repoRoot) : loadRegistryFromBase(o.repoRoot, base);
   if (isRegistryUnavailable(registryLoad)) return { refused: { code: 'POLICY_SOURCE_UNAVAILABLE', message: registryLoad.detail } };
   if (registryLoad.errors.length) return { refused: { code: 'REGEN_REGISTRY_INVALID', message: `${registryLoad.source.label}: ${registryLoad.errors.map(e => `${e.message} at ${e.path}`).join('; ')}`, errors: registryLoad.errors } };
-  const wtree = wtreeFingerprint(o.repoRoot);
-  if (!wtree) return { refused: { code: 'POLICY_SOURCE_UNAVAILABLE', message: 'cannot fingerprint the working tree (gstack-wtree failed)' } };
-  const platform = o.platform ?? process.platform;
   const env = o.env ?? process.env;
+  const fp = wtreeFingerprint({ cwd: o.repoRoot, env, invocation: o.invocation });
+  if ('error' in fp) return { refused: wtreeRefusal(fp) };
+  const wtree = fp.tree;
+  const platform = o.platform ?? process.platform;
   const config = configLoad.config as PregateConfig;
   return {
     ctx: {
@@ -88,7 +129,7 @@ export function buildContext(o: BuildContextOptions): ContextLoad {
       lanes: discoverLanes(o.repoRoot, platform), platform, allowRepoCommands: o.allowRepoCommands, timeoutMs: o.timeoutMs ?? 600_000,
       stallTimeoutMs: o.stallTimeoutMs ?? (config.stall_timeout_s ?? DEFAULT_STALL_TIMEOUT_S) * 1000,
       progress: o.progress ?? (line => process.stderr.write(`${line}\n`)),
-      cores: o.cores ?? os.availableParallelism(), testBackend: o.testBackend ?? readTestBackend(env), policyFrom: o.policyFrom, remote: o.remote ?? null,
+      cores: o.cores ?? os.availableParallelism(), testBackend: o.testBackend ?? readTestBackend(env, o.invocation), policyFrom: o.policyFrom, remote: o.remote ?? null,
       env, explain: [],
     },
   };
@@ -114,9 +155,11 @@ export async function withFingerprint(ctx: PregateContext, id: string, stage: Ch
   catch (e: any) {
     result = { id, stage, status: 'incomplete', detail: `threw: ${e?.message ?? e}`, code: 'PREGATE_INCOMPLETE', fix: 'read the error and rerun the check', inputs: baseInputs(ctx) };
   }
-  const after = wtreeFingerprint(ctx.repoRoot);
-  if (after !== ctx.wtree) {
-    result = { ...result, status: 'incomplete', detail: `working tree changed during the check (${ctx.wtree.slice(0, 12)} → ${(after ?? 'unknown').slice(0, 12)}); result not certified`, code: 'PREGATE_INCOMPLETE', fix: 'keep the tree still during the run, then rerun gstack-pregate' };
+  const after = wtreeFingerprint({ cwd: ctx.repoRoot, env: ctx.env });
+  if ('error' in after) {
+    result = { ...result, status: 'incomplete', detail: `cannot fingerprint the working tree after the check (${after.error}); result not certified`, code: 'PREGATE_INCOMPLETE', fix: wtreeRefusal(after).fix! };
+  } else if (after.tree !== ctx.wtree) {
+    result = { ...result, status: 'incomplete', detail: `working tree changed during the check (${ctx.wtree.slice(0, 12)} → ${after.tree.slice(0, 12)}); result not certified`, code: 'PREGATE_INCOMPLETE', fix: 'keep the tree still during the run, then rerun gstack-pregate' };
   }
   return { ...result, ms: Date.now() - started };
 }

lib/pregate/index.ts

@@ -14,7 +14,7 @@ import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ARTIFACT_SCHEMAS, checkSchema, type PregateFile, type PregateRemote, type ValidationError } from '../headless-artifacts';
-import { wtreeFingerprint } from '../regen';
+import { wtreeFingerprint, type WtreeResult } from '../script-invocation';
 import { guardsCheck } from './checks/guards';
 import { clearHint, lanesCheck, parseRemoteReport, REMOTE_GATE_LANE, remoteReportProblem } from './checks/lanes';
 import { literalsCheck } from './checks/literals';
@@ -123,10 +123,10 @@ export interface Verification { ok: boolean; code?: 'PREGATE_STALE' | 'PREGATE_R
  * current after final generation and stamping), no check may be fail or
  * incomplete, and every requires-remote obligation needs its receipt.
  */
-export function verifyPregate(repoRoot: string, file: PregateFile, treeNow = wtreeFingerprint(repoRoot)): Verification {
+export function verifyPregate(repoRoot: string, file: PregateFile, treeNow: WtreeResult = wtreeFingerprint({ cwd: repoRoot })): Verification {
   const uncleared = (file.requires_remote ?? []).filter(r => !r.receipt);
-  const current = !!treeNow && treeNow === file.tree;
-  if (!current) return { ok: false, code: 'PREGATE_STALE', message: `pregate.json was recorded against tree ${file.tree.slice(0, 12)}; the tree is now ${(treeNow ?? 'unknown').slice(0, 12)}`, current, uncleared };
+  const current = 'tree' in treeNow && treeNow.tree === file.tree;
+  if (!current) return { ok: false, code: 'PREGATE_STALE', message: `pregate.json was recorded against tree ${file.tree.slice(0, 12)}; ${'tree' in treeNow ? `the tree is now ${treeNow.tree.slice(0, 12)}` : `the tree cannot be fingerprinted now (${treeNow.error})`}`, current, uncleared };
   const failed = file.checks.filter(c => c.status === 'fail');
   if (failed.length) return { ok: false, code: 'PREGATE_LANE_FAILED', message: `${failed.length} check(s) failed: ${failed.map(c => c.id).join(', ')}`, current, uncleared };
   const incomplete = file.checks.filter(c => c.status === 'incomplete' || c.status === 'not_installed');

lib/regen.ts

@@ -21,7 +21,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { type ResultCodeName } from './result-codes';
-import { runBashSync, wtreeFingerprint as fingerprintTree } from './script-invocation';
+import { runBashSync, wtreeFingerprint } from './script-invocation';
 import { containedRelative, globToRegExp, matchesAny } from './ship-policy';
 
 export const GENERATED_PATH = '.gstack/generated.json';
@@ -128,17 +128,6 @@ export function selectEntries(registry: Registry, touched?: readonly string[]):
   return registry.entries.filter(e => e.inputs.length === 0 || touched.some(t => matchesAny(e.inputs, t) || matchesAny(e.outputs, t)));
 }
 
-/**
- * Compatibility wrapper for the pregate consumers (lib/pregate/context.ts,
- * lib/pregate/index.ts), files #3190 changes: they move to
- * lib/script-invocation.ts's `{tree}|{error}` form in item 10b, which then
- * deletes this.
- */
-export function wtreeFingerprint(repoRoot: string): string | null {
-  const r = fingerprintTree({ cwd: repoRoot });
-  return 'tree' in r ? r.tree : null;
-}
-
 export interface Scratch { dir: string; wtree: string; remove: () => void }
 
 /**
@@ -148,7 +137,7 @@ export interface Scratch { dir: string; wtree: string; remove: () => void }
  * Error naming the step.
  */
 export function scratchWorktree(repoRoot: string, prefix = 'gstack-regen-'): Scratch {
-  const fp = fingerprintTree({ cwd: repoRoot });
+  const fp = wtreeFingerprint({ cwd: repoRoot });
   if ('error' in fp) throw new Error(`cannot fingerprint the working tree (${fp.error})`);
   const wtree = fp.tree;
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -248,7 +237,7 @@ export function runRegen(o: RunRegenOptions): { results: EntryResult[]; wtree: s
     }
   } finally { scratch?.remove(); }
   if (scratch) return { results, wtree: scratch.wtree };
-  const fp = fingerprintTree({ cwd: o.repoRoot });
+  const fp = wtreeFingerprint({ cwd: o.repoRoot });
   return { results, wtree: 'tree' in fp ? fp.tree : null };
 }
 

lib/result-codes.ts

@@ -656,6 +656,12 @@ export const RESULT_CODES = {
     summary: 'a plan review ran without its second opinion: the outside provider did not run or failed, and the bounded native Plan reviewer was not offered or did not finish within five minutes',
     fix: 'repair the provider the line names (install it, or log in with `codex login`); for the native fallback use Claude Code 2.1.277 or later with background tasks enabled (`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` unset), then re-run the review',
   },
+  // Fix wave 2026-10-15, PR 5 (item 10b, #3197).
+  WTREE_UNAVAILABLE: {
+    anchor: 'wtree-unavailable',
+    summary: 'cannot fingerprint the working tree: bin/gstack-wtree could not start (on Windows, no Git Bash was found) or it ran and failed',
+    fix: 'on Windows point GSTACK_GIT_BASH at Git Bash\'s bash.exe (Git Bash: export GSTACK_GIT_BASH=\'C:/Program Files/Git/bin/bash.exe\'; PowerShell: $env:GSTACK_GIT_BASH = \'C:\\Program Files\\Git\\bin\\bash.exe\'), or install Git for Windows (winget install --id Git.Git -e); elsewhere rerun ./setup so bin/gstack-wtree is present; then rerun gstack-pregate',
+  },
 } as const satisfies Record<string, ResultCode>;
 
 export type ResultCodeName = keyof typeof RESULT_CODES;

lib/script-invocation.ts

@@ -177,7 +177,7 @@ export interface InvocationOptions extends BashProbe {
   bunExe?: string;
 }
 
-export type Invocation = { ok: true; cmd: string; argv: string[] } | { ok: false; error: string };
+export type Invocation = { ok: true; cmd: string; argv: string[] } | { ok: false; error: string; tried?: BashCandidate[] };
 
 /** The running Bun, or the `bun` on PATH when this process is a compiled binary. */
 export function bunExecutable(): string {
@@ -197,10 +197,10 @@ function readShebang(script: string): string {
 }
 
 const warned = new Set<string>();
-function windowsBash(o: InvocationOptions): { ok: true; bash: string } | { ok: false; error: string } {
+function windowsBash(o: InvocationOptions): { ok: true; bash: string } | { ok: false; error: string; tried: BashCandidate[] } {
   const res = o.resolve ? o.resolve() : resolveWindowsBash(o);
   if (res.warning && !warned.has(res.warning)) { warned.add(res.warning); process.stderr.write(res.warning + '\n'); }
-  return res.ok ? { ok: true, bash: res.bash } : { ok: false, error: res.message };
+  return res.ok ? { ok: true, bash: res.bash } : { ok: false, error: res.message, tried: res.tried };
 }
 
 /** How to run a gstack shebang bin on this platform. */
@@ -219,32 +219,33 @@ export function bashCommandInvocation(command: string, o: InvocationOptions = {}
 }
 
 /** A spawnSync-shaped failure for an invocation that could not be built, so callers keep one error path. */
-function unlaunched(error: string, encoding: unknown): SpawnSyncReturns<string | Buffer> {
+function unlaunched(error: string, encoding: unknown, tried?: BashCandidate[]): SpawnSyncReturns<string | Buffer> {
   const empty = encoding && encoding !== 'buffer' ? '' : Buffer.alloc(0);
-  return { pid: 0, output: [null, empty, empty], stdout: empty, stderr: empty, status: null, signal: null, error: Object.assign(new Error(error), { code: 'BASH_UNAVAILABLE' }) };
+  return { pid: 0, output: [null, empty, empty], stdout: empty, stderr: empty, status: null, signal: null, error: Object.assign(new Error(error), { code: 'BASH_UNAVAILABLE', tried }) };
 }
 
 export function runScriptSync(script: string, args: readonly string[], opts: SpawnSyncOptionsWithStringEncoding, o?: InvocationOptions): SpawnSyncReturns<string>;
 export function runScriptSync(script: string, args: readonly string[], opts: SpawnSyncOptions, o?: InvocationOptions): SpawnSyncReturns<string | Buffer>;
 export function runScriptSync(script: string, args: readonly string[], opts: SpawnSyncOptions, o: InvocationOptions = {}): SpawnSyncReturns<string | Buffer> {
   const inv = scriptInvocation(script, args, o);
-  return inv.ok ? spawnSync(inv.cmd, inv.argv, opts) : unlaunched(inv.error, opts.encoding);
+  return inv.ok ? spawnSync(inv.cmd, inv.argv, opts) : unlaunched(inv.error, opts.encoding, inv.tried);
 }
 
 export function runBashSync(command: string, opts: SpawnSyncOptionsWithStringEncoding, o?: InvocationOptions): SpawnSyncReturns<string>;
 export function runBashSync(command: string, opts: SpawnSyncOptions, o?: InvocationOptions): SpawnSyncReturns<string | Buffer>;
 export function runBashSync(command: string, opts: SpawnSyncOptions, o: InvocationOptions = {}): SpawnSyncReturns<string | Buffer> {
   const inv = bashCommandInvocation(command, o);
-  return inv.ok ? spawnSync(inv.cmd, inv.argv, opts) : unlaunched(inv.error, opts.encoding);
+  return inv.ok ? spawnSync(inv.cmd, inv.argv, opts) : unlaunched(inv.error, opts.encoding, inv.tried);
 }
 
-export type WtreeResult = { tree: string } | { error: string; kind: 'launch' | 'exit' };
+export type WtreeResult = { tree: string } | { error: string; kind: 'launch' | 'exit'; tried?: BashCandidate[] };
 
 /**
  * The working-tree content fingerprint (bin/gstack-wtree): tracked and
  * untracked non-ignored files, as a 40- or 64-hex git tree id (SHA-1 or
  * SHA-256 repositories). `launch` means gstack-wtree never ran (no bash, a
- * spawn error); `exit` means it ran and failed (its stderr says why).
+ * spawn error; `tried` lists each Windows bash candidate when none was
+ * found); `exit` means it ran and failed (its stderr says why).
  */
 export function wtreeFingerprint(o: { cwd: string; timeoutMs?: number; env?: NodeJS.ProcessEnv; invocation?: InvocationOptions }): WtreeResult {
   const r = runScriptSync(path.join(BIN_DIR, 'gstack-wtree'), [], {
@@ -253,7 +254,7 @@ export function wtreeFingerprint(o: { cwd: string; timeoutMs?: number; env?: Nod
   }, o.invocation);
   const out = (r.stdout ?? '').trim();
   if (r.status === 0 && /^[0-9a-f]{40,64}$/.test(out)) return { tree: out };
-  if (r.error && r.status === null && r.signal === null) return { kind: 'launch', error: `gstack-wtree could not start: ${r.error.message}` };
+  if (r.error && r.status === null && r.signal === null) return { kind: 'launch', error: `gstack-wtree could not start: ${r.error.message}`, tried: (r.error as { tried?: BashCandidate[] }).tried };
   const why = (r.stderr ?? '').trim().split('\n').pop() || (r.signal ? `killed by ${r.signal}` : r.status === 0 ? `unexpected output ${JSON.stringify(out.slice(0, 80))}` : 'no stderr');
   return { kind: 'exit', error: `gstack-wtree exited ${r.status ?? r.signal}: ${why}` };
 }

test/pregate-wtree-refusal.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Fix wave PR 5, item 10b (#3197): the pregate consumers of the working-tree
+ * fingerprint use lib/script-invocation.ts's `{tree}|{error}` form. A
+ * fingerprint failure is WTREE_UNAVAILABLE, never "origin/<base> is not a
+ * resolvable commit": a launch failure lists each Windows bash candidate and
+ * names GSTACK_GIT_BASH, a gstack-wtree exit keeps the repair it printed.
+ * Under --json every context refusal is one envelope on stdout with exit 3,
+ * sharing `ok` and `status` with the run object; GSTACK_RESULT is on stderr.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { EXIT, type PregateFile } from '../lib/headless-artifacts';
+import { buildContext, describeRefusal, readTestBackend, withFingerprint, wtreeRefusal } from '../lib/pregate/context';
+import { verifyPregate } from '../lib/pregate/index';
+import type { BashProbe } from '../lib/script-invocation';
+import { cleanup, makeFixtureRepo, runBin, type FixtureRepo } from './helpers/pregate-fixture';
+
+const repos: FixtureRepo[] = [];
+const fixture = () => { const r = makeFixtureRepo(); repos.push(r); return r; };
+afterEach(() => { while (repos.length) cleanup(repos.pop()!); });
+
+const noBash: BashProbe = { platform: 'win32', env: {}, exists: () => false, gitExecPath: () => null, which: () => null };
+const badTmp = (repo: FixtureRepo) => ({ TMPDIR: path.join(repo.root, 'no-such-tmp') });
+const pregate = (repo: FixtureRepo, args: string[], env: Record<string, string> = {}) => runBin(repo, 'gstack-pregate', ['--base', 'main', ...args], env);
+const lastLine = (text: string) => text.trim().split('\n').pop() ?? '';
+
+describe('WTREE_UNAVAILABLE (lib/pregate/context.ts)', () => {
+  test('a launch failure (no Git Bash) refuses with each candidate and the GSTACK_GIT_BASH fix, not an unresolvable base', () => {
+    const repo = fixture();
+    const loaded = buildContext({ repoRoot: repo.work, base: 'main', policyFrom: 'base', allowRepoCommands: false, env: { ...process.env, ...repo.env }, testBackend: 'local', invocation: noBash });
+    expect('refused' in loaded).toBe(true);
+    if (!('refused' in loaded)) return;
+    expect(loaded.refused.code).toBe('WTREE_UNAVAILABLE');
+    expect(loaded.refused.message).toStartWith('gstack-wtree could not start: no Git Bash found; tried GSTACK_GIT_BASH (unset): not set; ');
+    expect(loaded.refused.message).toContain('install path C:/Program Files/Git/bin/bash.exe: not found');
+    expect(loaded.refused.message).toContain('PATH bash: not on PATH');
+    const r = describeRefusal(loaded.refused, 'main');
+    expect(r.line).not.toContain('is not a resolvable commit');
+    expect(r.line).toEndWith('(WTREE_UNAVAILABLE)');
+    expect(r.fix).toContain("export GSTACK_GIT_BASH='C:/Program Files/Git/bin/bash.exe'");
+    expect(r.docs).toEndWith('docs/troubleshooting.md#wtree-unavailable');
+  });
+
+  test('a gstack-wtree exit keeps its own repair; an exit without one names how to reproduce it', () => {
+    expect(wtreeRefusal({ kind: 'exit', error: 'gstack-wtree exited 1: gstack-wtree: cannot create a temp index under /x; set TMPDIR to a writable directory' }))
+      .toEqual({ code: 'WTREE_UNAVAILABLE', message: 'gstack-wtree exited 1: gstack-wtree: cannot create a temp index under /x', fix: 'set TMPDIR to a writable directory' });
+    expect(wtreeRefusal({ kind: 'exit', error: 'gstack-wtree exited 1: no stderr' }).fix).toStartWith('run bin/gstack-wtree in the repository');
+  });
+
+  test('the after-check fingerprint failing is incomplete with its cause, not "working tree changed"', async () => {
+    const repo = fixture();
+    const loaded = buildContext({ repoRoot: repo.work, base: 'main', policyFrom: 'base', allowRepoCommands: false, env: { ...process.env, ...repo.env }, testBackend: 'local' });
+    if (!('ctx' in loaded)) throw new Error(JSON.stringify(loaded.refused));
+    const ctx = { ...loaded.ctx, env: { ...loaded.ctx.env, ...badTmp(repo) } };
+    const r = await withFingerprint(ctx, 'strays', 'preflight', () => ({ id: 'strays', stage: 'preflight', status: 'pass', inputs: {} }));
+    expect(r.status).toBe('incomplete');
+    expect(r.detail).toStartWith('cannot fingerprint the working tree after the check (gstack-wtree exited 1:');
+    expect(r.fix).toBe('set TMPDIR to a writable directory');
+  });
+
+  test('verify says the tree cannot be fingerprinted instead of comparing against "unknown"', () => {
+    const file = { schema_version: 1, tree: 'a'.repeat(40), checks: [], requires_remote: [] } as unknown as PregateFile;
+    const v = verifyPregate('/nonexistent', file, { kind: 'launch', error: 'gstack-wtree could not start: no Git Bash found' });
+    expect(v).toMatchObject({ ok: false, code: 'PREGATE_STALE', current: false });
+    expect(v.message).toContain('the tree cannot be fingerprinted now (gstack-wtree could not start: no Git Bash found)');
+  });
+
+  test('gstack-config (test_backend) launches through the script invocation, so Windows reaches it through Git Bash', () => {
+    const repo = fixture();
+    const env = { ...process.env, ...repo.env };
+    expect(runBin(repo, 'gstack-config', ['set', 'test_backend', 'ubicloud']).status).toBe(0);
+    const bash = Bun.which('bash')!;
+    let resolved = 0;
+    const backend = readTestBackend(env, { platform: 'win32', resolve: () => { resolved += 1; return { ok: true, bash, source: 'test', tried: [] }; } });
+    expect(resolved).toBe(1);
+    expect(backend).toBe('ubicloud');
+  });
+});
+
+describe('gstack-pregate context refusals through the CLI', () => {
+  test('a gstack-wtree failure prints WTREE_UNAVAILABLE with its own fix, never "is not a resolvable commit"', () => {
+    const repo = fixture();
+    const r = pregate(repo, ['--stage', 'preflight'], badTmp(repo));
+    expect(r.status).toBe(EXIT.refused);
+    expect(r.err).not.toContain('is not a resolvable commit');
+    expect(lastLine(r.err)).toMatch(/^gstack-pregate: cannot fingerprint the working tree: .* \(gstack-wtree exited 1: gstack-wtree: cannot create a temp index under .*no-such-tmp\); fix: set TMPDIR to a writable directory \(WTREE_UNAVAILABLE\)$/);
+    expect(lastLine(r.out)).toMatch(/^GSTACK_RESULT: skill=pregate status=refused /);
+  });
+
+  test('--json: both refusals are one envelope on stdout (exit 3) sharing ok and status with the run object; GSTACK_RESULT goes to stderr', () => {
+    const repo = fixture();
+    const wtree = pregate(repo, ['--stage', 'preflight', '--json'], badTmp(repo));
+    const base = runBin(repo, 'gstack-pregate', ['--base', 'no-such-base', '--stage', 'preflight', '--json']);
+    const run = pregate(repo, ['--stage', 'preflight', '--only', 'strays', '--json']);
+    for (const r of [wtree, base]) {
+      expect(r.status).toBe(EXIT.refused);
+      expect(r.out.trim().split('\n')).toHaveLength(1);
+      expect(r.out).not.toContain('GSTACK_RESULT');
+      expect(r.err).toMatch(/^GSTACK_RESULT: skill=pregate status=refused /m);
+    }
+    const w = JSON.parse(wtree.out);
+    expect(Object.keys(w).sort()).toEqual(['code', 'detail', 'docs', 'fix', 'ok', 'status']);
+    expect(w).toMatchObject({ ok: false, status: 'refused', code: 'WTREE_UNAVAILABLE', fix: 'set TMPDIR to a writable directory' });
+    expect(w.detail).toMatch(/cannot create a temp index under .*no-such-tmp$/);
+    expect(w.docs).toEndWith('#wtree-unavailable');
+    const b = JSON.parse(base.out);
+    expect(b).toMatchObject({ ok: false, status: 'refused', code: 'POLICY_SOURCE_UNAVAILABLE', detail: 'origin/no-such-base is not a resolvable commit' });
+    expect(b.fix).toContain('git fetch origin no-such-base --depth=1');
+    expect(b.docs).toEndWith('#policy-source-unavailable');
+    expect(run.status).toBe(EXIT.ok);
+    const ok = JSON.parse(run.out);
+    expect(ok).toMatchObject({ ok: true, status: 'complete' });
+    expect(run.err).toMatch(/^GSTACK_RESULT: skill=pregate status=complete run=.*pregate\.json$/m);
+    expect(fs.existsSync(ok.out)).toBe(true);
+  });
+});

test/script-invocation-tripwire.test.ts

@@ -21,11 +21,20 @@ const ROOT = path.resolve(import.meta.dir, '..');
 const SPAWN_BIN_BY_PATH = /\b(?:spawn|spawnSync|execFile|execFileSync)\(\s*(?:path\.)?join\(\s*(?:BIN_DIR|binDir|BIN|bin|binRoot|BIN_ROOT)\b/;
 const SPAWN_BARE_BASH = /\b(?:spawn|spawnSync|execFile|execFileSync|execSync)\(\s*['"]bash['"]|Bun\.spawn(?:Sync)?\(\s*\[\s*['"]bash['"]|\[\s*['"]bash['"]\s*,\s*['"]-l?c['"]/;
 const COMMENT = /^\s*(?:\/\/|\*|\/\*)/;
+/** `const X = path.resolve(…, 'bin', 'gstack-…')`: a bin path held in a constant, then spawned by name (#3190's gstack-config). */
+const BIN_CONSTANT = /\bconst\s+([A-Za-z_]\w*)\s*=\s*(?:path\.)?(?:resolve|join)\([^;]*['"]bin['"]\s*,\s*['"][^'"]+['"]\s*\)/g;
+function spawnsBinConstant(source: string): RegExp | null {
+  const names = [...source.matchAll(BIN_CONSTANT)].map(m => m[1]!);
+  return names.length ? new RegExp(`\\b(?:spawn|spawnSync|execFile|execFileSync)\\(\\s*(?:${names.join('|')})\\b`) : null;
+}
 
 const KNOWN_SITES: Record<string, string> = {
   'lib/evidence-bundle.ts': 'outside this wave: bundle replay commands (bash -lc) move to runBashSync',
   'bin/gstack-brain-context-load.ts': 'outside this wave: the brain context loader moves to runBashSync',
   'bin/gstack-issue-links': 'outside this wave: the gstack-issue-guard spawn moves to runScriptSync',
+  // Found when the bin-constant rule was added (fix wave PR 5, item 10b).
+  'bin/gstack-brain-cache': 'outside this wave: the gstack-config salience read moves to runScriptSync',
+  'lib/autoplan-admission.ts': 'returns before the spawn on win32; the bin/gstack-lease touch moves to runScriptSync with that bin\'s owner',
 };
 
 function productionFiles(): string[] {
@@ -51,9 +60,11 @@ function offendingSites(): Record<string, string[]> {
   const hits: Record<string, string[]> = {};
   for (const rel of productionFiles()) {
     if (rel === 'lib/script-invocation.ts') continue;
-    fs.readFileSync(path.join(ROOT, rel), 'utf8').split('\n').forEach((line, i) => {
+    const source = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    const spawnsConstant = spawnsBinConstant(source);
+    source.split('\n').forEach((line, i) => {
       if (COMMENT.test(line)) return;
-      if (SPAWN_BIN_BY_PATH.test(line) || SPAWN_BARE_BASH.test(line)) (hits[rel] ??= []).push(`${rel}:${i + 1}: ${line.trim().slice(0, 120)}`);
+      if (SPAWN_BIN_BY_PATH.test(line) || SPAWN_BARE_BASH.test(line) || spawnsConstant?.test(line)) (hits[rel] ??= []).push(`${rel}:${i + 1}: ${line.trim().slice(0, 120)}`);
     });
   }
   return hits;
@@ -80,6 +91,9 @@ describe('#3197: shebang bins and bash go through lib/script-invocation.ts', ()
     expect(SPAWN_BARE_BASH.test("spawnSync('bash', ['-c', cmd], { timeout: 1 })")).toBe(true);
     expect(SPAWN_BARE_BASH.test('const argv = ["bash", "-c", command];')).toBe(true);
     expect(SPAWN_BARE_BASH.test("spawnSync(process.execPath, [script], { timeout: 1 })")).toBe(false);
+    const constant = spawnsBinConstant("const GSTACK_CONFIG = path.resolve(import.meta.dir, '..', '..', 'bin', 'gstack-config');");
+    expect(constant?.test("const r = spawnSync(GSTACK_CONFIG, ['get', 'test_backend'], { timeout: 1 });")).toBe(true);
+    expect(constant?.test("const r = runScriptSync(GSTACK_CONFIG, ['get', 'test_backend'], { timeout: 1 });")).toBe(false);
   });
 });
 

test/script-invocation.test.ts

@@ -13,7 +13,6 @@ import {
   bashCommandInvocation, resolveWindowsBash, resolveWindowsBashCached, runBashSync, runScriptSync, scriptInvocation, wtreeFingerprint,
   type BashProbe,
 } from '../lib/script-invocation';
-import { wtreeFingerprint as regenWtreeFingerprint } from '../lib/regen';
 
 const ROOT = path.resolve(import.meta.dir, '..');
 const BIN = path.join(ROOT, 'bin');
@@ -183,12 +182,11 @@ describe('wtreeFingerprint', () => {
     return dir;
   };
 
-  test('a SHA-1 repository yields a 40-hex tree, and the regen compatibility wrapper returns the same string', () => {
+  test('a SHA-1 repository yields a 40-hex tree', () => {
     const dir = repo();
     try {
       const r = wtreeFingerprint({ cwd: dir });
       expect('tree' in r && r.tree).toMatch(/^[0-9a-f]{40}$/);
-      expect(regenWtreeFingerprint(dir)).toBe('tree' in r ? r.tree : 'missing');
     } finally { fs.rmSync(dir, { recursive: true, force: true }); }
   });
 
@@ -209,7 +207,7 @@ describe('wtreeFingerprint', () => {
       const exit = wtreeFingerprint({ cwd: dir, env: { ...process.env, TMPDIR: path.join(dir, 'no-such-dir') } });
       expect(exit).toMatchObject({ kind: 'exit' });
       expect('error' in exit && exit.error).toMatch(/^gstack-wtree exited 1: .*set TMPDIR to a writable directory/);
-      expect(regenWtreeFingerprint(path.join(os.tmpdir()))).toBeNull();
+      expect(wtreeFingerprint({ cwd: os.tmpdir() })).toMatchObject({ kind: 'exit' });
     } finally { fs.rmSync(dir, { recursive: true, force: true }); }
   });