@ngockhoale/ukit 3.4.21 → 3.4.23

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/.claude/ukit/runtime/output-compression.mjs

@@ -1204,6 +1204,18 @@ function extractExitCode(payload) {
   return null;
 }
 
+// FR-M5-004 (TASK-C97-014): child identity is a top-level, nonempty, trimmed string
+// `agent_id` OR `agent_type` — the same documented subagent marker skill-router.sh
+// reads for its sidechain guard. Nested output text that merely contains marker
+// words is never authority, and missing/blank/nonstring markers fall through to the
+// existing main-session accounting unchanged.
+function isChildToolPayload(payload) {
+  if (!payload || typeof payload !== 'object') return false;
+  return [payload.agent_id, payload.agent_type].some(
+    (marker) => typeof marker === 'string' && marker.trim() !== '',
+  );
+}
+
 function extractText(payload, preferredKeys = []) {
   const queue = [payload];
   const seen = new Set();
@@ -1376,6 +1388,10 @@ async function main() {
 
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // FR-M5-004 (TASK-C97-014): resolved once from the parsed payload and applied at
+  // BOTH raw-output pressure updates below. Deliberately NOT an early exit — the
+  // compression, cache, history, tee and hard-cap paths all keep running for a child.
+  const isChildOutput = isChildToolPayload(payload);
   // Session-scoped pressure bookkeeping: output tokens must land in the calling
   // session's record, never a sibling session's.
   const sessionConfig = {
@@ -1448,16 +1464,21 @@ async function main() {
         recoveryReason: cached.metadata?.recoveryReason ?? null,
         truncated: Boolean(cached.metadata?.truncated),
       });
-      await updateCompactPressureFromOutput(projectRoot, {
-        timestamp: Date.now(),
-        command: cachedCommand,
-        profile: cachedProfile,
-        summary: String(cached.content),
-        tokensBefore: cached.tokensBefore ?? 0,
-        tokensAfter: cached.tokensAfter ?? 0,
-        savedTokens: cached.savedTokens ?? 0,
-        exitCode,
-      }, sessionConfig);
+      // FR-M5-004: a subagent's raw output must not be charged to its parent's
+      // compact pressure. Suppress ONLY this pressure write — cache/history/tee
+      // writes above, the summary on stdout below, and every safety gate are untouched.
+      if (!isChildOutput) {
+        await updateCompactPressureFromOutput(projectRoot, {
+          timestamp: Date.now(),
+          command: cachedCommand,
+          profile: cachedProfile,
+          summary: String(cached.content),
+          tokensBefore: cached.tokensBefore ?? 0,
+          tokensAfter: cached.tokensAfter ?? 0,
+          savedTokens: cached.savedTokens ?? 0,
+          exitCode,
+        }, sessionConfig);
+      }
       process.stdout.write(String(cached.content));
       return;
     }
@@ -1548,16 +1569,21 @@ async function main() {
     savedTokens: result.savedTokens,
     metadata: { command: result.command, exitCode },
   });
-  await updateCompactPressureFromOutput(projectRoot, {
-    timestamp: Date.now(),
-    command: result.command,
-    profile: result.profile,
-    summary: result.summary,
-    tokensBefore: result.tokensBefore,
-    tokensAfter: result.tokensAfter,
-    savedTokens: result.savedTokens,
-    exitCode,
-  }, sessionConfig);
+  // FR-M5-004: same suppression on the fresh path — a child's raw output never
+  // charges the parent's compact estimate; compression, history, tee, the recovery
+  // anchor and every downstream gate keep their existing behavior.
+  if (!isChildOutput) {
+    await updateCompactPressureFromOutput(projectRoot, {
+      timestamp: Date.now(),
+      command: result.command,
+      profile: result.profile,
+      summary: result.summary,
+      tokensBefore: result.tokensBefore,
+      tokensAfter: result.tokensAfter,
+      savedTokens: result.savedTokens,
+      exitCode,
+    }, sessionConfig);
+  }
 
   if (config?.tokenPipeline?.promptCache) {
     await writePromptCacheEntry(projectRoot, {

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -966,7 +966,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   } catch {
     return { kind: 'none' };
   }
-  const { goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
+  const { command, goal, phase, cursor, next, exitPredicate } = parseRunCursor(text);
   // Shared terminal predicate — tests/handoff/cycle21 greps this exact shape across
   // all four RUN.md consumers; keep `^(done|blocked)` as one expression.
   const terminal = String(phase).match(/^(done|blocked)\b/i)?.[1]?.toLowerCase() || '';
@@ -980,7 +980,8 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   // must not be bounced into a stale run. Only a positive "scanned the whole
   // transcript, latest intent is not fullstack" releases; unknown (null) keeps
   // the block, so a real run is never released by a lost read.
-  if (gate.scope === 'session' && await transcriptShowsHandoffRun(transcriptPath) === false) {
+  const transcriptOwner = gate.scope === 'session' ? await transcriptShowsHandoffRun(transcriptPath) : true;
+  if (gate.scope === 'session' && transcriptOwner === false) {
     return { kind: 'none' };
   }
 
@@ -1008,6 +1009,19 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
     return { kind: 'block', reason: lines.join('\n') };
   }
 
+  // Nonterminal planning cursor (TASK-C97-006, FR-M2-003): a RUN.md whose Command
+  // is EXACTLY `handoff-create` is the planner's own cursor — it does not demand
+  // fullstack implementation even when the session's intent is unknown (no
+  // transcript path, unreadable, known-null). Stop releases UNLESS the latest
+  // structured intent positively reacquired the run (`fullstack`: an explicit
+  // handoff-implement or handoff-fullstack turn). This is the ONLY command
+  // exception: actual handoff-fullstack/implement/review and a missing/unknown
+  // Command keep the legacy posture, including the unknown fail-closed block. The
+  // terminal `done` branch above is untouched.
+  if (String(command).trim().toLowerCase() === 'handoff-create' && transcriptOwner !== true) {
+    return { kind: 'none' };
+  }
+
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
   if (streak !== null && streak > gate.maxStalledBlocks) {

package/template_project/.omp/agents/feature-implementer.md

@@ -138,9 +138,16 @@ mode only; daily flow does not get a Progress section.
   reports `undeclared-drift`.
 - **Milestone commit.** The commit lives on your worktree branch only (e.g.
   `handoff/task-xxx`). Use a `-m "milestone: <name>"` message. Never commit outside your
-  worktree, never push. The orchestrator's copy-back step (`git diff --name-only` against
-  base) diffs the working tree, so intermediate commits on the worktree branch are free —
-  **copy-back is unaffected** by milestone commits.
+  worktree, never push. The orchestrator's copy-back step lands the branch's final
+  base-relative snapshot (`land-worktree.mjs` diffs the working tree against the immutable
+  base), so intermediate commits on the worktree branch are free — **copy-back is
+  unaffected** by milestone commits.
+- **Final clean milestone commit (required before PASS).** End your run with one final
+  milestone commit so the worktree's snapshot equals its committed tree — nothing staged,
+  nothing unstaged, no nonignored untracked file left behind. A Git-clean snapshot is what
+  lets a later receipt-gated cleanup remove the worktree without `--force`; a tree dirty
+  against the snapshot is retained with a named reason, never forced. Do not report PASS on
+  a dirty worktree.
 - **Resume.** When a previous run aborted, you will be respawned. Read `## Progress`,
   jump straight to the last entry whose `last-green:` is not `none`, and continue from
   there. Do NOT re-plan, do NOT restart from RED, do NOT re-write tests that already

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