@ngockhoale/ukit 3.4.21 → 3.4.23

package/template_project/.claude/ukit/index/stale-spec-check.mjs

@@ -99,7 +99,54 @@ export async function checkStaleSpec({ projectRoot = process.cwd(), payload = {}
   const toolName = getToolName(payload);
   const filePath = getFilePath(payload);
   if (!filePath) return { status: 'skipped', reason: 'no-file' };
-  const resolved = resolveProjectFile(projectRoot, filePath);
+  // C97 (FR-001): classify target containment at the checker boundary. The
+  // shared resolver THROWS "Path escapes project root" on containment misses
+  // and its contract must not change, so classify lexically here — before any
+  // fs probe of the target. An absolute path strictly outside the project is
+  // out of scope for this project-only check: scoped skip, NOT permission to
+  // write (other gates keep ownership, and the target is never read). Relative
+  // escapes and root-as-file get a structured block instead of an unhandled
+  // crash that killed the whole fail-closed chain. Lexical only — symlink
+  // expansion must never widen authority.
+  // Fix1 (review round 1): containment is SEGMENT-aware. String prefix
+  // matching (`startsWith('..')`) also caught internal dot-prefixed names
+  // whose first path segment starts with `..` (e.g. a project-root-level
+  // `..internal.mjs`), scoping real in-project files out of the check. An
+  // escape is a `..` PATH SEGMENT — the whole relative path or its first
+  // segment — never a leading-dot filename.
+  const root = path.resolve(projectRoot || process.cwd());
+  const rawPath = String(filePath).trim();
+  const candidate = path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(root, rawPath);
+  const candidateRelative = path.relative(root, candidate);
+  const escapesRoot = candidateRelative === '..'
+    || candidateRelative.startsWith(`..${path.sep}`)
+    || path.isAbsolute(candidateRelative);
+  if (!candidateRelative || escapesRoot) {
+    if (!path.isAbsolute(rawPath) || !candidateRelative) {
+      return {
+        status: 'blocked',
+        code: 'invalid-project-target',
+        message: `BLOCKED: target path '${filePath}' resolves outside the project root (invalid-project-target) — relative traversal and the project root itself are refused. Choose a path inside the project.`,
+        file: rawPath,
+      };
+    }
+    return { status: 'skipped', reason: 'outside-project', file: rawPath };
+  }
+  // The unchanged strict resolver still refuses first-segment dot-names
+  // (its own `startsWith('..')` contract). Keep that refusal — it is the
+  // resolver's safety contract — but surface it as the structured block
+  // instead of the unhandled-crash class this checker used to die from.
+  let resolved;
+  try {
+    resolved = resolveProjectFile(projectRoot, filePath);
+  } catch (error) {
+    return {
+      status: 'blocked',
+      code: 'invalid-project-target',
+      message: `BLOCKED: project resolver refused target '${filePath}' (invalid-project-target): ${error?.message || error}. Use a normal in-project path whose segments do not start with '..'.`,
+      file: rawPath,
+    };
+  }
   const exists = await withTransientFsRetry(
     () => probeExists(resolved.absolute),
     { deadlineMs: TRANSIENT_READ_DEADLINE_MS },

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -27,21 +27,35 @@
 //        `intent` is the MOST RECENT qualifying intent, `known=false` when the scan
 //        could not complete (missing/unreadable path, budget overrun) — callers keep
 //        their fail-closed posture on `known=false`.
+//
+// Intent values stay the historical pair 'create' | 'fullstack': an exact
+// `handoff-implement` invocation CLAIMS the run (the fullstack command says so
+// itself), so it maps onto the existing 'fullstack' intent instead of adding a
+// new enum every consumer would have to learn (TASK-C97-004).
 
 import fs from 'node:fs/promises';
 
-export const HANDOFF_FULLSTACK_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack\b/;
-export const HANDOFF_CREATE_TAG = /<command-name>\/?(?:ukit:)?handoff-create\b/;
+// The `(?![\w-])` closer is the exact token boundary: a command name followed by
+// MORE name characters or a hyphen (`handoff-fullstack-custom`) is a different,
+// unsupported command — `\b` would still match there and let the suffix spoof
+// the intent.
+export const HANDOFF_FULLSTACK_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack(?![\w-])/;
+export const HANDOFF_CREATE_TAG = /<command-name>\/?(?:ukit:)?handoff-create(?![\w-])/;
 export const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run';
 
+// Sweeper for "which command tag came LAST in this entry": finds every exact
+// command-name tag occurrence with its position so the newest one wins.
+const COMMAND_TAG_SWEEP = /<command-name>\/?(?:ukit:)?handoff-(create|fullstack|implement)(?![\w-])/g;
+
 // omp and Codex do NOT wrap a slash command in `<command-name>` tags the way
 // Claude Code's user turn does. Their native evidence is the command *expansion*:
 // omp replaces `/ukit:handoff-fullstack` with the command body, whose FIRST
 // non-empty line is the H1 `# /ukit:handoff-fullstack — …`; Codex records the same
 // expanded body as a `response_item`/`message` with `input_text` blocks. Matching
 // the FIRST line only (not any heading in the body) keeps prose references to the
-// command inside the document from being mistaken for an invocation.
-const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack)\b/;
+// command inside the document from being mistaken for an invocation. The same
+// exact token boundary applies: `-custom` suffixed headings are not commands.
+const NATIVE_COMMAND_HEADING = /^\s{0,3}#{1,3}\s+\/?(?:ukit:)?(handoff-create|handoff-fullstack|handoff-implement)(?![\w-])/;
 
 // The unique customType the omp bridge stamps on host-injected UKit hook context
 // (`sendContext` → `hookContextMessage`). A resume banner only counts as intent
@@ -62,6 +76,19 @@ function firstNonEmptyLine(text) {
   return '';
 }
 
+/**
+ * Map an exact command token (full `handoff-implement` or the captured suffix
+ * `implement`) onto the two intent values. `handoff-implement` CLAIMS the run,
+ * so it maps onto the existing 'fullstack' intent.
+ * @returns {'create' | 'fullstack' | null}
+ */
+function commandTokenIntent(token) {
+  const t = String(token).toLowerCase().replace(/^handoff-/, '');
+  if (t === 'create') return 'create';
+  if (t === 'fullstack' || t === 'implement') return 'fullstack';
+  return null;
+}
+
 /**
  * Does this text open with a native (omp/Codex) command-expansion heading?
  * Only the FIRST non-empty line is inspected, so an H1 that appears later in the
@@ -72,7 +99,7 @@ function firstNonEmptyLine(text) {
 function nativeCommandIntent(text) {
   const m = firstNonEmptyLine(text).match(NATIVE_COMMAND_HEADING);
   if (!m) return null;
-  return m[1] === 'handoff-create' ? 'create' : 'fullstack';
+  return commandTokenIntent(m[1]);
 }
 
 // Bounds for the tail scan. Recency is what matters, so the reader walks the
@@ -109,51 +136,61 @@ function splitUserContent(content) {
   return { text, blocks, hasToolOutput };
 }
 
+/**
+ * Classify one user text block. Structured evidence only: exact Claude Code
+ * `<command-name>` tags (the LAST one in the block wins) or a native
+ * command-expansion heading on the block's first line.
+ * @returns {'fullstack' | 'create' | null}
+ */
+function classifyUserText(text) {
+  const tags = [...String(text ?? '').matchAll(COMMAND_TAG_SWEEP)];
+  if (tags.length > 0) return commandTokenIntent(tags[tags.length - 1][1]);
+  return nativeCommandIntent(text);
+}
+
 /**
  * Classify a user turn (Claude Code `type:'user'`, omp `type:'message'` role user,
- * Codex `type:'response_item'` payload message role user). Structured evidence only:
- * a Claude Code `<command-name>` tag, or a native command-expansion heading on the
- * first line of a user text block.
+ * Codex `type:'response_item'` payload message role user). The LATEST qualifying
+ * evidence inside the entry wins — a later tag/block supersedes an earlier one,
+ * while trailing non-qualifying content never erases it. Tool-output blocks
+ * (`tool_result` round-trips) are not user words and never carry intent, so a
+ * turn that is purely tool output has no user text to match.
  * @returns {'fullstack' | 'create' | null}
  */
 function classifyUserTurn(content) {
-  const { text, blocks, hasToolOutput } = splitUserContent(content);
-  // Check the planning tag first: a single turn carrying both is a create turn.
-  if (HANDOFF_CREATE_TAG.test(text)) return 'create';
-  if (HANDOFF_FULLSTACK_TAG.test(text)) return 'fullstack';
-  // Native (omp / Codex) command expansion — the FIRST line of a user text block.
-  // A user turn that is purely tool output has no user text to match, so a
-  // `tool_result` carrying the marker string can never register as intent.
+  const { blocks } = splitUserContent(content);
+  let latest = null;
   for (const block of blocks) {
-    const intent = nativeCommandIntent(block);
-    if (intent) return intent;
+    const intent = classifyUserText(block);
+    if (intent) latest = intent;
   }
-  if (hasToolOutput) return null;
-  return null;
+  return latest;
 }
 
 /**
  * Classify assistant tool-call blocks. Handles both Claude Code (`tool_use`, name
- * `Skill`, input.skill) and omp (`toolCall`, name/arguments.skill).
+ * `Skill`, input.skill) and omp (`toolCall`, name/arguments.skill). The LAST
+ * qualifying block wins; unrelated tool blocks never erase it.
  */
 function classifyAssistantBlocks(blocks) {
   if (!Array.isArray(blocks)) return null;
+  let latest = null;
   for (const b of blocks) {
     if (!b || typeof b !== 'object') continue;
     if (b.type === 'tool_use' && b.name === 'Skill') {
       const skill = String(b.input?.skill ?? '');
-      if (/^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
-      if (/^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      if (m) latest = commandTokenIntent(m[1]);
       continue;
     }
     if (b.type === 'toolCall') {
       const name = String(b.name ?? '');
       const skill = String(b.arguments?.skill ?? '');
-      if (/^(?:ukit:)?handoff-create$/i.test(name) || /^(?:ukit:)?handoff-create$/.test(skill)) return 'create';
-      if (/^(?:ukit:)?handoff-fullstack$/i.test(name) || /^(?:ukit:)?handoff-fullstack$/.test(skill)) return 'fullstack';
+      const m = /^(?:ukit:)?handoff-(create|fullstack|implement)$/i.exec(name) || /^(?:ukit:)?handoff-(create|fullstack|implement)$/.exec(skill);
+      if (m) latest = commandTokenIntent(m[1]);
     }
   }
-  return null;
+  return latest;
 }
 
 /**
@@ -170,7 +207,9 @@ function classifyAssistantBlocks(blocks) {
  *   - Codex:        `{ type:'response_item', payload:{ type:'message', role:'user', content:[input_text…] } }`
  *
  * Anything else — including a format we do not recognise — returns null (never a
- * guessed intent), so the caller's fail-closed posture is preserved.
+ * guessed intent), so the caller's fail-closed posture is preserved. Within one
+ * entry the LATEST qualifying evidence wins; `-custom` suffixed command names and
+ * tool-result / unknown-namespace content are never intent.
  * @returns {'fullstack' | 'create' | null}
  */
 export function classifyHandoffEntry(entry) {
@@ -263,11 +302,30 @@ export async function transcriptHandoffIntent(transcriptPath, {
       const line = lines[i];
       if (!line) continue;
       // Cheap prefilter — skip JSON.parse for lines that cannot be evidence.
-      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('HANDOFF RESUME')) {
+      // `handoff-implement` is included: an implement invocation after a create
+      // must be seen as the NEWEST intent, not lost to the older create line.
+      if (!line.includes('handoff-create') && !line.includes('handoff-fullstack') && !line.includes('handoff-implement') && !line.includes('HANDOFF RESUME')) {
         continue;
       }
-      const intent = classifyHandoffLine(line);
+      // This is the NEWEST line carrying intent evidence. A host append can be
+      // cut mid-record (killed turn, torn write), leaving this line as unparseable
+      // JSON. Skipping it like any other non-qualifying line would fall through to
+      // an OLDER — possibly OPPOSITE — intent and misreport the session's current
+      // ownership (a torn `handoff-implement` after a create released a real
+      // fullstack run). An incomplete newest evidence-bearing record is therefore
+      // UNDETERMINED, not "no intent": return unknown so fail-closed callers keep
+      // their blocking/conservative posture (MODULE02-SPEC FR-M2-002).
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        return { intent: null, known: false };
+      }
+      const intent = classifyHandoffEntry(entry);
       if (intent) return { intent, known: true };
+      // Complete record that carries no recognised intent (tool output, a foreign
+      // envelope, a malformed-but-whole unrelated line): not evidence — keep
+      // walking older lines.
     }
     // Nothing found. Only a scan of the WHOLE transcript proves "no handoff
     // intent"; a tail window that missed it (the invoking turn usually appears

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"
@@ -43,6 +43,23 @@ const FAIL_CLOSED_SCRIPTS = new Set([
 
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
 
+// C97 (SPEC §FR-002): bound for replaying a triggering step's already-captured
+// stderr diagnostic in the skippedFailClosed verdict. Large enough for real
+// causes, small enough that a flooded capture cannot drown the skipped-gate
+// notice. The excerpt is cut at a UTF-8 code-point boundary so the emitted
+// diagnostic is always valid UTF-8.
+const CAUSE_EXCERPT_MAX_BYTES = 4096;
+
+function boundedUtf8Excerpt(text, maxBytes = CAUSE_EXCERPT_MAX_BYTES) {
+  const buf = Buffer.from(String(text ?? ''), 'utf8');
+  if (buf.length <= maxBytes) return { text: buf.toString('utf8'), truncated: false };
+  let end = maxBytes;
+  // Back off over UTF-8 continuation bytes (0b10xxxxxx) so the cut never
+  // splits a code point.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end--;
+  return { text: buf.subarray(0, end).toString('utf8'), truncated: true };
+}
+
 // TASK-234 review fix (critical): stdin staging must be bounded. The old
 // `fs.readFileSync(0)` blocked until the producer closed the pipe — a stalled
 // producer held the runner until the settings timeout SIGKILLed it, so every
@@ -88,6 +105,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 +187,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 +338,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 +354,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 +371,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 +681,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);
@@ -629,14 +717,57 @@ try {
       // TASK-234 review fix (critical): a mid-chain break that skipped a
       // fail-closed gate must fail CLOSED — the old per-script path ran every
       // hook independently, so a killed advisory never skipped a gate.
+      // C97 (SPEC §FR-002): the old emission named the unrun gates but dropped
+      // the triggering step's already-captured diagnostic entirely (the
+      // sibling fail-closed branch below DOES replay `last.stderr`), so an
+      // exit-1 gate's cause never reached the operator. Provenance now names
+      // the triggering result's step + failureKind — an actual child as the
+      // attempted step; the synthetic budget-exhausted result (elapsedMs 0,
+      // killed true: the script never launched) explicitly as unattempted —
+      // and replays the step's captured stderr ONCE, bounded. An
+      // output-overflow capture is truncated mid-stream and may embed anything
+      // (payloads, secrets), so it never leaves this process; the generic
+      // stdout message carries no raw stderr.
       if (contextStdout) process.stdout.write(contextStdout);
+      const broke = chain.results[chain.results.length - 1] ?? null;
       const skipped = scriptPaths
         .slice(chain.results.length)
         .map((p) => failClosedName(p))
         .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
         .join(', ');
+      const unattempted = broke?.failureKind === 'budget-exhausted';
+      const causeLabel = !broke
+        ? 'unknown step'
+        : unattempted
+          ? `${broke.scriptName} (${broke.failureKind}, unattempted — budget exhausted before launch)`
+          : `${broke.scriptName} (${broke.failureKind}, attempted step)`;
+      const provenanceMsg = `UKit hook chain broke at ${causeLabel}.\n`;
       const brokeMsg = `UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`;
+      process.stderr.write(provenanceMsg);
+      const causeText = broke
+        && broke.failureKind !== 'output-overflow'
+        && typeof broke.stderr === 'string'
+        ? broke.stderr
+        : '';
+      if (causeText.trim()) {
+        const excerpt = boundedUtf8Excerpt(causeText);
+        process.stderr.write(
+          excerpt.truncated
+            ? `${excerpt.text}\n[ukit] cause excerpt truncated at ${CAUSE_EXCERPT_MAX_BYTES} UTF-8 bytes\n`
+            : (excerpt.text.endsWith('\n') ? excerpt.text : `${excerpt.text}\n`),
+        );
+      }
       process.stderr.write(brokeMsg + breakerAdvice(brokeMsg));
+      if (!contextStdout) {
+        // Otherwise-empty stdout: emit exactly ONE parseable JSON document so
+        // the host still gets a single valid verdict — the generic failure
+        // (step/kind/skipped gates), never the raw cause. Appending it after
+        // prior stdout would create an invalid two-document stream, so prior
+        // stdout suppresses it entirely.
+        process.stdout.write(JSON.stringify({
+          systemMessage: `${provenanceMsg.trimEnd()} ${brokeMsg.trimEnd()}`,
+        }));
+      }
       process.exitCode = 2;
     } else if (!last) {
       // No script ran at all (empty chain or budget spent before the first
@@ -669,8 +800,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() }));
+        }
       }
     }
   }