@ngockhoale/ukit 3.4.20 → 3.4.22

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