@ngockhoale/ukit 3.4.21 → 3.4.22

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.22 - 2026-10-07
+
+**Windows: `.sh` hooks no longer deny every Edit/Write/Bash.**
+- `.sh` hooks are now launched through Git for Windows bash: `UKIT_BASH_BIN` → `CLAUDE_CODE_GIT_BASH_PATH` →
+  default Git install paths → absolute `PATH` entries. WSL's `bash.exe` and a cwd `bash.exe` are never used.
+- On Windows a `.sh` hook whose bash cannot be found or started is reported as `spawn-unavailable` and warned
+  instead of denying every Edit/Write/Bash. POSIX behaviour is unchanged; timeouts, real blocks, missing gate
+  files and `block-dangerous.sh` stay fail-closed.
+- `ukit doctor` flags Windows hook launch failures.
+- `*.sh` is pinned to LF (repo `.gitattributes` and a shipped `.claude/.gitattributes`) so a CRLF checkout cannot
+  break hook scripts. Troubleshooting added to `docs/INSTALL.md`.
+
 ## 3.4.21 - 2026-10-07
 
 **Hook runtime no longer burns CPU/disk on every tool call** (five measured bugs, C95).

package/manifests/documentation.yaml

@@ -707,6 +707,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
+  - id: tpl-claude-gitattributes
+    path: template_project/.claude/.gitattributes
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: template_project/.claude/.gitattributes
+    merge_strategy: skip
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: non-.md entry — keeps hook *.sh LF on Windows autocrlf checkouts; exists for FR-002 manifest consistency
 
   # ── repo mirrors (derived from template_project/) ───────────────────────────────
   - id: mirror-claude-dir

package/manifests/platform.full.yaml

@@ -1511,6 +1511,19 @@ items:
     packs:
       - core
 
+  # Ships `*.sh text eol=lf` inside .claude/ only (never the user's root .gitattributes) so
+  # a Windows autocrlf checkout cannot turn hook scripts into CRLF that bash rejects.
+  - id: claude-gitattributes
+    type: config
+    sourceTemplate: .claude/.gitattributes
+    targetPath: .claude/.gitattributes
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.21",
+  "version": "3.4.22",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/hookChainDoctor.js

@@ -24,12 +24,31 @@ const FAILURE_OUTCOMES = new Set([
   'output-overflow',
   'error',
   'signal',
+  'spawn-unavailable',
 ]);
 
 // The pre-O6 remedy, kept verbatim: a failure with no gate evidence must read
 // exactly as it did before escalation existed (SPEC §FR-012).
+// SPEC §FR-007: launch failures only arise on win32 (the runner emits
+// `spawn-unavailable` from its bash-launcher path), so there is one remedy.
+const LAUNCH_REMEDY = 'Windows cannot execute .sh hooks directly — install Git for Windows so C:\\Program Files\\Git\\bin\\bash.exe exists, or set UKIT_BASH_BIN to the full path of bash.exe, then restart the session.';
+
+// Legacy pre-fix win32 rows recorded a failed .sh launch as a plain `error`
+// that finished almost instantly.
+const LEGACY_LAUNCH_FAILURE_MAX_MS = 10;
+
 const BASE_REMEDY = 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.';
 
+function isLaunchFailure(entry, platform) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (typeof entry.scriptName !== 'string' || !entry.scriptName.toLowerCase().endsWith('.sh')) return false;
+  if (entry.failureKind === 'spawn-unavailable') return true;
+  return platform === 'win32'
+    && entry.failureKind === 'error'
+    && typeof entry.elapsedMs === 'number'
+    && entry.elapsedMs < LEGACY_LAUNCH_FAILURE_MAX_MS;
+}
+
 function telemetryDirFor(projectRoot) {
   return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
 }
@@ -78,7 +97,7 @@ async function tailLines(filePath, size) {
   }
 }
 
-export async function inspectHookChainHealth({ projectRoot, now = Date.now() } = {}) {
+export async function inspectHookChainHealth({ projectRoot, now = Date.now(), platform = process.platform } = {}) {
   const label = 'hook-chain health';
 
   // Never-fatal posture extends to malformed input: a missing projectRoot is
@@ -106,6 +125,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   // evidence shapes that prove it, collected in the same pass that counts
   // outcomes so no second read of the rows is needed.
   const gateFailures = new Set();
+  const launchFailures = new Set();
   let budgetExhaustedChains = 0;
 
   for (const file of files) {
@@ -130,6 +150,14 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       const outcome = typeof row.outcome === 'string' && row.outcome.length > 0 ? row.outcome : 'ok';
       counts[outcome] = (counts[outcome] ?? 0) + 1;
 
+      // .sh launch failures are collected from EVERY row (an exit-code row can
+      // still carry one); they are a different signal from a gate that ran and failed.
+      if (Array.isArray(row.scripts)) {
+        for (const entry of row.scripts) {
+          if (isLaunchFailure(entry, platform)) launchFailures.add(entry.scriptName);
+        }
+      }
+
       // Escalation evidence is only ever read off a FAILING row — a gate that
       // ran fine is not evidence of anything, and SPEC §FR-012 scopes the
       // budget signal to a non-ok row ("a non-ok row ... escalates only when
@@ -155,6 +183,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
         if (!entry || typeof entry !== 'object') continue;
         if (entry.failClosed !== true) continue;
         if (typeof entry.failureKind !== 'string' || entry.failureKind === 'ok') continue;
+        if (entry.failureKind === 'spawn-unavailable') continue; // reported as a launch failure
         gateFailures.add(typeof entry.scriptName === 'string' ? entry.scriptName : 'unknown');
       }
     }
@@ -177,7 +206,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
     .filter((key) => FAILURE_OUTCOMES.has(key) && counts[key] > 0)
     .sort();
 
-  if (failureKinds.length === 0) {
+  if (failureKinds.length === 0 && launchFailures.size === 0) {
     return {
       label,
       passed: true,
@@ -190,7 +219,9 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   }
 
   const breakdown = failureKinds.map((kind) => `${kind}=${counts[kind]}`).join(', ');
-  const baseDetail = `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`;
+  const baseDetail = failureKinds.length > 0
+    ? `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`
+    : `${counts.rowsScanned} chain row(s) scanned`;
 
   // O6 (SPEC §FR-012): escalate only when a failure actually landed ON a gate —
   // a gate that merely ran is not evidence. The escalation is purely additive:
@@ -207,6 +238,11 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       `A fail-closed gate actually failed (${gateList.join(', ')}) — that is a real budget or path problem, not a slow advisory hook; widen the failing gate's budget or fix that step.`,
     );
   }
+  const launchList = [...launchFailures].sort();
+  if (launchList.length > 0) {
+    escalations.push(`.sh hook(s) could not be launched: ${launchList.join(', ')}`);
+    advices.push(LAUNCH_REMEDY);
+  }
   if (budgetExhaustedChains > 0) {
     escalations.push(`${budgetExhaustedChains} chain row(s) exhausted the total budget`);
     advices.push(

package/template_project/.claude/.gitattributes

@@ -0,0 +1,2 @@
+# Hook scripts must stay LF: a CRLF checkout makes bash fail on "\r".
+*.sh text eol=lf

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -6,7 +6,7 @@ import { pathToFileURL } from 'node:url';
 // TASK-016: children run through the process-tree runner instead of bare
 // spawnSync — a timed-out child is TERM→KILLed as a whole POSIX process group,
 // so a bash wrapper can no longer orphan the Node grandchildren it spawned.
-import { runHookProcess } from './hook-process.mjs';
+import { runHookProcess, resolveHookCommand, SPAWN_UNAVAILABLE_CODES } from './hook-process.mjs';
 // Repeated identical blocks (a model respawning an agent into the same refusal) get a
 // "stop and report verbatim" directive appended. Advisory + fail-open; see block-breaker.mjs.
 // Loaded dynamically so a partially-updated runtime (module missing) degrades to "no advice"
@@ -88,6 +88,7 @@ async function readStdinBounded() {
 //   'signal'           — the child died from a signal this runner did not send
 //   'error'            — the child never spawned (ENOENT and friends)
 //   'budget-exhausted' — the script never ran: the chain total budget was spent
+//   'spawn-unavailable' — win32 bash launcher not found or could not start the .sh script (no process ran); warned, never blocks
 function chainFailureKind(processResult) {
   switch (processResult?.failureKind) {
     case 'overflow':
@@ -169,6 +170,18 @@ function parseScriptArg(arg) {
 // 'timeout'. The deadline is enforced by Promise.race + AbortSignal; the
 // rejection race keeps running in the background (in-proc code cannot be
 // SIGKILLed) but its late return value is discarded.
+// FR-004: warning for a step whose win32 bash launcher never started. Single
+// Windows fixText — this classification is unreachable off win32 (`viaBash`).
+const SPAWN_UNAVAILABLE_FIX =
+  'Fix: install Git for Windows (https://git-scm.com/download/win) or set UKIT_BASH_BIN to the full path of bash.exe.';
+
+function spawnUnavailableWarning(scriptName, cause) {
+  const gateText = FAIL_CLOSED_SCRIPTS.has(scriptName)
+    ? 'fail-closed gate NOT enforced'
+    : 'advisory hook skipped';
+  return `UKit WARNING: hook ${scriptName} could not be launched (${cause}) and was SKIPPED — ${gateText}. ${SPAWN_UNAVAILABLE_FIX}\n`;
+}
+
 async function runModuleStep({ scriptPath, payload, payloadText, projectRoot, env, deadlineMs }) {
   const controller = new AbortController();
   let timer;
@@ -308,6 +321,13 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
     // TASK-001: `.mjs` args run in-proc via runHook(ctx); `.sh` stays a child
     // process. Both paths share deadline/budget, results[] shape, and break
     // conditions.
+    // FR-003/FR-004: non-.mjs steps launch through the resolver (absolute Git
+    // Bash on win32 for `.sh`, the script itself everywhere else). `viaBash`
+    // is the ONLY thing that can turn a launch failure into spawn-unavailable.
+    const launch = scriptPath.endsWith('.mjs')
+      ? { command: scriptPath, args: [], viaBash: false }
+      : resolveHookCommand(scriptPath);
+    const { viaBash } = launch;
     const result = scriptPath.endsWith('.mjs')
       ? await runModuleStep({
           scriptPath,
@@ -317,10 +337,13 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
           env: stepEnv,
           deadlineMs: stepDeadlineMs,
         })
-      : await runHookProcess({
-          command: scriptPath,
+      : launch.command === null
+        // No bash found on win32: nothing is spawned (never a bare `bash`).
+        ? { code: 1, stdout: '', stderr: '', failureKind: 'error', spawnFailed: true, errorCode: null }
+        : await runHookProcess({
+          command: launch.command,
           deadlineMs: stepDeadlineMs,
-          args: [],
+          args: launch.args,
           input: payloadText,
           maxBuffer: MAX_BUFFER_BYTES,
           cwd: projectRoot,
@@ -331,6 +354,38 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
           // decision JSON.
           env: stepEnv,
         });
+    const launchFailed = viaBash && (
+      launch.command === null
+      || (result.spawnFailed === true && SPAWN_UNAVAILABLE_CODES.has(result.errorCode))
+    );
+    if (launchFailed && scriptName !== 'block-dangerous.sh' && fs.existsSync(scriptPath)) {
+      const stepElapsedMs = Date.now() - childStartedAt;
+      results.push({
+        scriptName,
+        code: 0,
+        stdout: '',
+        stderr: spawnUnavailableWarning(scriptName, launch.command === null ? 'bash.exe not found' : result.errorCode),
+        failureKind: 'spawn-unavailable',
+        killed: false,
+        elapsedMs: stepElapsedMs,
+      });
+      recordHookTiming({
+        projectRoot,
+        sessionId: payload?.session_id,
+        event: payload?.hook_event_name || null,
+        tool: payload?.tool_name || null,
+        toolUseId: payload?.tool_use_id || null,
+        hook: scriptName,
+        elapsedMs: stepElapsedMs,
+        outcome: 'spawn-unavailable',
+      });
+      continue;
+    }
+    if (launch.command === null) {
+      // Resolver found no bash but the step does not qualify for the degrade
+      // (script missing / block-dangerous.sh): fail closed exactly like a spawn error.
+      result.stderr = `UKit hook ${scriptName} could not be launched: bash.exe not found\n`;
+    }
     const failureKind = chainFailureKind(result);
     // FR-001: on infra failure (error/timeout — no module verdict) the result
     // code is 2 when the step is fail-closed, else 1.
@@ -609,18 +664,34 @@ try {
       .filter((r) => r !== decisionResult && r !== last && typeof r.stdout === 'string' && r.stdout.length > 0)
       .map((r) => r.stdout)
       .join('');
+    // FR-005: spawn-unavailable steps never block, but must stay visible. Their
+    // warnings go to stderr exactly ONCE (here) and, where stdout is a clean
+    // JSON document the runner owns, into `systemMessage`.
+    const warnings = chain.results
+      .filter((r) => r.failureKind === 'spawn-unavailable')
+      .map((r) => r.stderr)
+      .join('');
+    if (warnings) process.stderr.write(warnings);
     if (decisionOwnsVerdict) {
       let verdictOut = decisionResult.stdout;
       try {
         const doc = JSON.parse(verdictOut);
         const hso = doc?.hookSpecificOutput;
+        let changed = false;
         if (hso?.permissionDecision === 'deny') {
           const advice = breakerAdvice(hso.permissionDecisionReason);
           if (advice) {
             hso.permissionDecisionReason = `${hso.permissionDecisionReason}\n${advice}`;
-            verdictOut = JSON.stringify(doc);
+            changed = true;
           }
         }
+        if (warnings && doc && typeof doc === 'object' && !Array.isArray(doc)) {
+          doc.systemMessage = typeof doc.systemMessage === 'string' && doc.systemMessage
+            ? `${doc.systemMessage}\n${warnings.trimEnd()}`
+            : warnings.trimEnd();
+          changed = true;
+        }
+        if (changed) verdictOut = JSON.stringify(doc);
       } catch { /* unparseable verdict: replay it untouched */ }
       process.stdout.write(verdictOut);
       if (decisionResult.stderr) process.stderr.write(decisionResult.stderr);
@@ -669,8 +740,14 @@ try {
       } else {
         if (contextStdout) process.stdout.write(contextStdout);
         if (last.stdout) process.stdout.write(last.stdout);
-        if (last.stderr) process.stderr.write(last.stderr);
+        // A spawn-unavailable `last` carries only the warning already written above.
+        if (last.stderr && last.failureKind !== 'spawn-unavailable') process.stderr.write(last.stderr);
         process.exitCode = last.code === 0 ? 0 : (lastIsFailClosed ? 2 : 0);
+        // FR-005(c): exiting 0 with an otherwise empty stdout — surface the warning
+        // to the host as a systemMessage. Plain context stdout is left untouched.
+        if (warnings && process.exitCode === 0 && !contextStdout && !last.stdout) {
+          process.stdout.write(JSON.stringify({ systemMessage: warnings.trimEnd() }));
+        }
       }
     }
   }

package/template_project/.claude/ukit/runtime/hook-process.mjs

@@ -18,15 +18,29 @@
 //     assumes group semantics.
 //
 // Contract (TASK-016 Interfaces):
-//   runHookProcess({command, args, input, deadlineMs, maxBuffer, ...}) ->
-//     Promise<{code, signal, stdout, stderr, failureKind, elapsedMs}>
+//   runHookProcess({command, args, input, deadlineMs, maxBuffer, spawnImpl, ...}) ->
+//     Promise<{code, signal, stdout, stderr, failureKind, elapsedMs, spawnFailed, errorCode}>
 //   failureKind: 'none' | 'deadline' | 'signal' | 'overflow' | 'error'
 //     'deadline' — this runner killed the child because the deadline expired
 //     'signal'   — the child died from a signal this runner did not send
 //     'overflow' — captured output exceeded maxBuffer; the tree was culled
 //     'error'    — the child never spawned (ENOENT and friends)
+//   spawnFailed: true only when the process was NEVER started — derived from child
+//     event order (an 'error' with no preceding 'spawn' event, or spawn() throwing
+//     synchronously), never from timing. An 'error' after 'spawn' is not a spawn failure.
+//   errorCode: the error's `code` (ENOENT, EINVAL, EPIPE, ...) or null.
+//   spawnImpl: injectable spawn function (default child_process.spawn) for tests.
+//
+// Windows .sh launching (resolveHookCommand / resolveWindowsBash):
+//   Windows cannot exec a `.sh` file directly, so on win32 a `.sh` hook is launched
+//   through an ABSOLUTE Git Bash path (never a bare `bash`, which Windows would look up
+//   in the child cwd first). Script paths are passed with forward slashes. POSIX spawns
+//   the script directly, unchanged. UKIT_HOOK_SHELL_PLATFORM overrides the platform seen
+//   by resolveHookCommand only (tests/diagnostics); UKIT_BASH_BIN overrides the bash path.
 
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 // POSIX only. Windows kill() targets the direct child; process groups do not
 // exist there, so pretending otherwise would be a silent, wrong assumption.
@@ -41,6 +55,93 @@ export const KILL_GRACE_MS = 500;
 // runner past its own budget.
 const HARD_SETTLE_SLACK_MS = 2000;
 
+// Error codes meaning "the launcher itself could not be started".
+export const SPAWN_UNAVAILABLE_CODES = new Set([
+  'ENOENT',
+  'EINVAL',
+  'EACCES',
+  'EPERM',
+  'ENOEXEC',
+  'EFTYPE',
+]);
+
+/** Windows path -> forward slashes, so bash's dirname/$0 logic works. */
+export function toBashPath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+const win32 = path.win32;
+
+function safeExists(exists, candidate) {
+  try {
+    return Boolean(exists(candidate));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate Git Bash on Windows. Returns an absolute path or null — never a bare
+ * or relative name (Windows resolves bare names in the child cwd first, which
+ * would let a planted bash.exe in a cloned repo run).
+ */
+export function resolveWindowsBash({ env = process.env, exists = fs.existsSync } = {}) {
+  const override = env.UKIT_BASH_BIN;
+  if (typeof override === 'string' && override && win32.isAbsolute(override)) return override;
+
+  const probe = (candidate) =>
+    typeof candidate === 'string' &&
+    candidate !== '' &&
+    win32.isAbsolute(candidate) &&
+    safeExists(exists, candidate);
+
+  const claude = env.CLAUDE_CODE_GIT_BASH_PATH;
+  if (probe(claude)) return claude;
+
+  const defaults = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+  ];
+  if (typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA) {
+    defaults.push(win32.join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'));
+  }
+  for (const candidate of defaults) {
+    if (probe(candidate)) return candidate;
+  }
+
+  const trimSlash = (p) => p.replace(/\\+$/, '').toLowerCase();
+  const system32 = trimSlash(win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32'));
+  const rawPath = env.PATH ?? env.Path ?? '';
+  for (const rawEntry of String(rawPath).split(';')) {
+    const entry = rawEntry.trim().replace(/^"+|"+$/g, '').trim();
+    if (!entry || !win32.isAbsolute(entry)) continue;
+    const norm = trimSlash(win32.normalize(entry));
+    if (norm === system32 || norm.endsWith('\\microsoft\\windowsapps')) continue;
+    const candidate = win32.join(entry, 'bash.exe');
+    if (safeExists(exists, candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Decide how to launch a hook script. win32 + `.sh` -> Git Bash (command may be
+ * null when none was found); everything else spawns the script directly.
+ */
+export function resolveHookCommand(
+  scriptPath,
+  { env = process.env, platform = env.UKIT_HOOK_SHELL_PLATFORM || process.platform, exists = fs.existsSync } = {},
+) {
+  if (typeof scriptPath !== 'string') return { command: '', args: [], viaBash: false };
+  if (platform === 'win32' && /\.sh$/i.test(scriptPath)) {
+    return {
+      command: resolveWindowsBash({ env, exists }),
+      args: [toBashPath(scriptPath)],
+      viaBash: true,
+    };
+  }
+  return { command: scriptPath, args: [], viaBash: false };
+}
+
 /**
  * Signal a process GROUP by pid (negative-pid kill). Swallows ESRCH — the
  * child may have exited between arming the timer and this call, or the pid may
@@ -73,18 +174,20 @@ export function runHookProcess({
   cwd,
   env = process.env,
   graceMs = KILL_GRACE_MS,
+  spawnImpl = spawn,
 }) {
   return new Promise((resolve) => {
     const startedAt = Date.now();
     let child;
     try {
-      child = spawn(command, args, {
+      child = spawnImpl(command, args, {
         cwd,
         env,
         // Detached ONLY on POSIX: the child becomes a group leader so the whole
         // tree dies together. Windows never gets a group assumption.
         detached: GROUP_KILL_SUPPORTED,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
       });
     } catch (err) {
       resolve({
@@ -94,6 +197,8 @@ export function runHookProcess({
         stderr: String(err?.message || err),
         failureKind: 'error',
         elapsedMs: Date.now() - startedAt,
+        spawnFailed: true,
+        errorCode: err?.code ?? null,
       });
       return;
     }
@@ -104,6 +209,8 @@ export function runHookProcess({
     let hardSettled = false;
     let overflowed = false;
     let spawnError = null;
+    let spawned = false;
+    let spawnFailed = false;
     let stdoutBuf = Buffer.alloc(0);
     let stderrBuf = Buffer.alloc(0);
     const stdoutRef = { value: stdoutBuf };
@@ -146,6 +253,8 @@ export function runHookProcess({
         stderr: stderrRef.value.toString('utf8'),
         failureKind,
         elapsedMs: Date.now() - startedAt,
+        spawnFailed,
+        errorCode: spawnError?.code ?? null,
       });
     };
 
@@ -238,9 +347,16 @@ export function runHookProcess({
       }, deadlineMs + Math.max(0, graceMs) + HARD_SETTLE_SLACK_MS);
     }
 
+    // Event order, not timing, tells "never started" from "failed after start".
+    child.once('spawn', () => {
+      spawned = true;
+    });
     child.on('error', (err) => {
       // Spawn failures (ENOENT and friends) emit 'error' without 'close'.
-      if (!spawnError) spawnError = err;
+      if (!spawnError) {
+        spawnError = err;
+        spawnFailed = !spawned;
+      }
       finish();
     });
     child.on('close', () => {

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -273,6 +273,18 @@ function parseStructuredDecision(stdout) {
 
 function translateExecResult(scriptName, execResult) {
   const failureKind = typeof execResult?.failureKind === 'string' ? execResult.failureKind : null;
+  // The runner could not launch a .sh hook at all (win32 without bash): a loud warning,
+  // never a block, and no captured content travels with it.
+  if (failureKind === 'spawn-unavailable') {
+    const launchStderr = typeof execResult?.stderr === 'string' ? execResult.stderr : '';
+    return {
+      block: false,
+      warning: launchStderr.trim()
+        || `${scriptName} could not be launched and was skipped (spawn-unavailable) — install Git for Windows or set UKIT_BASH_BIN.`,
+      stdout: '',
+      stderr: launchStderr,
+    };
+  }
   // Infrastructure outcomes produce no verdict: no captured content travels with
   // them (overflowed stdout is truncated mid-stream and may embed secrets).
   const infrastructure = failureKind

package/template_project/docs/UKIT_INTERNALS.md

@@ -280,13 +280,25 @@ Internals: `src/core/permissionPolicy.js` compiles the semantic policy (preceden
   non-zero on its own), `output-overflow` (capture exceeded the 2 MiB maxBuffer and the
   tree was culled), `timeout` (the runner killed the child at its deadline), `signal`
   (the child died from a signal the runner did not send), `error` (the child never
-  spawned), `budget-exhausted` (the script never ran — the chain total budget was spent
-  first). The `--emit-verdict` contract maps them onto one exit code: `ok`/`exit-code 0`
+  spawned), `spawn-unavailable` (win32 only: no usable bash could be found or started for
+  a `.sh` script — see the launcher bullet below), `budget-exhausted` (the script never
+  ran — the chain total budget was spent first). The `--emit-verdict` contract maps them onto one exit code: `ok`/`exit-code 0`
   and any non-fail-closed failure → exit 0 (fail OPEN); a real `exit-code 2` block, or
   ANY failure on a fail-closed gate (`output-overflow`, `timeout`, `signal`, `error`,
   `budget-exhausted`) → exit 2 (fail CLOSED). An overflowed capture is dropped whole
   before it can be replayed, so a truncated stream can never masquerade as a verdict.
   `tests/hooks/hookChainFailureSurface.test.js` pins these surfaces.
+- **Windows bash launcher.** On win32 a `.sh` hook is not executed directly; the runner
+  launches it through Git Bash. The bash binary is the first hit of: an absolute
+  `UKIT_BASH_BIN` → `CLAUDE_CODE_GIT_BASH_PATH` → the Git for Windows default install
+  paths → absolute `PATH` entries (the System32 and WindowsApps `bash.exe`, i.e. WSL, are
+  skipped; a relative or cwd `bash.exe` is never used). The script path is passed with
+  forward slashes. When no candidate exists or the spawn fails, the entry is
+  `spawn-unavailable`: it warns instead of denying every Edit/Write/Bash. That kind is
+  win32-launcher-only — POSIX spawn errors stay `error` and fail closed, and timeouts,
+  real `exit-code 2` blocks, missing gate files and `block-dangerous.sh` stay fail closed
+  on every platform. `UKIT_HOOK_SHELL_PLATFORM` is a diagnostic override of the platform
+  the launcher assumes.
 - **stderr is a diagnostic channel, not verdict payload.** Under `--emit-verdict` the
   runner drops the stderr of every non-verdict script: stdout is the verdict and Claude
   Code parses it as ONE JSON document, so interleaving arbitrary hook diagnostics there