@ngockhoale/ukit 2.4.2 → 2.4.3

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

@@ -0,0 +1,509 @@
+#!/usr/bin/env node
+/**
+ * stop-coordinator.mjs — the ONE Stop decision coordinator (TASK-025, PLAN §2 H17).
+ *
+ * H17: `.claude/settings.json` used to register BOTH `completion-gate.sh` and
+ * `task-watchdog.sh` on the Stop event. Each hook evaluated its own policy and each
+ * could emit `decision: block`, so a single Stop could produce two continuation
+ * decisions and two state mutations (completion gate continuation counter + watchdog
+ * hard-block counter). This module replaces that with one coordinator:
+ *
+ *   - it evaluates the completion policy by spawning execution-ledger.mjs
+ *     `--evaluate-stop` exactly once (the ledger owns its own counting semantics);
+ *   - it evaluates the watchdog policy in-process through task-watchdog.mjs's
+ *     exported `evaluateStopWatchdog` exactly once;
+ *   - it merges the two evaluator results with a deterministic owner order —
+ *     fail-closed completion failure > completion block > watchdog block > merged
+ *     advisory > silent release — and emits AT MOST ONE Stop JSON line;
+ *   - a lock-scoped once-per-stop guard makes a legacy double-registered Stop
+ *     (old settings.json still listing both hooks) inert: the second coordinator
+ *     invocation for the same session inside the dedupe window emits nothing and
+ *     mutates nothing, so counters still move at most once.
+ *
+ * Failure posture (security test row):
+ *   - The completion gate is the fail-closed blocker. If it fails to produce a
+ *     verdict (missing script, spawn error, non-zero exit, unparseable output,
+ *     budget overrun) the coordinator BLOCKS fail-closed with a fixed, redacted
+ *     infrastructure reason — raw failure detail goes to stderr only, never into
+ *     the parsed decision (mirrors execution-ledger's own crash counter posture).
+ *   - The watchdog is an advisory lane. Its failure never decides anything; the
+ *     other evaluator's decision stands and the failure is reported verbatim in
+ *     the emitted `systemMessage` (stderr carries it too).
+ *
+ * Exports (independently testable — tests import the module directly):
+ *   DEDUPE_WINDOW_MS            — same-session Stop invocations closer than this are
+ *                                 treated as one event (a recovery turn takes >>2s).
+ *   redactInfrastructureReason  — the fixed redacted block reason for a failed
+ *                                 fail-closed blocker; never repeats its input.
+ *   redactDeadlineReason        — the fixed redacted block reason for a deadline
+ *                                 overrun (budget, not crash — same redaction).
+ *   emitDeadlineBlock           — the deadline path's single fail-closed emission.
+ *   normalizeEvaluatorStdout    — ledger stdout → { kind, reason?, systemMessage? }.
+ *   coordinateStopDecisions     — the pure ordered merge; owns ordering + provenance
+ *                                 only (evaluators stay independently testable).
+ *   evaluateCompletionPolicy    — spawns the ledger once, returns the normalized
+ *                                 completion evaluator result (throws on failure).
+ *   runStopCoordinator          — event guard + dedupe + both evaluators + merge.
+ *
+ * Like every UKit hook runtime this fails loud and stays inside the hook deadline:
+ * a self-kill timer honours UKIT_HOOK_DEADLINE_MS (default 3000ms), the ledger child
+ * gets a bounded budget, and every path exits 0.
+ *
+ * Deadline posture (fix round 1 — reviewer critical): the deadline is the LAST line
+ * of defence for the fail-closed blocker, so it must not be a silent exit. The
+ * wrapper (`completion-gate.sh`) reads "exit 0 with empty stdout" as a clean release,
+ * which meant a coordinator that hit its own deadline while the completion evaluator
+ * hung RELEASED Stop instead of blocking it. The deadline now emits the same fixed
+ * redacted fail-closed block (synchronously, so process.exit cannot drop a buffered
+ * pipe write) and reaps any in-flight evaluator child before exiting.
+ */
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import { withAsyncLock } from './async-lock.mjs';
+
+// Orphan-leak guard (2.4.1 / TASK-025): completion-gate.sh spawns this as
+// `node "$SCRIPT"`, so a host that kills the bash wrapper would reparent a
+// wedged coordinator to launchd. The env-gated arm is hook-only — CLI/tests
+// never set UKIT_HOOK_DEADLINE_MS, so this stays inert there.
+//
+// A hung completion evaluator keeps the event loop alive, which is exactly when this
+// timer fires — and firing it without a decision used to hand the wrapper a silent
+// release. The canonical self-kill line below is kept verbatim (the shipped-hook
+// watchdog gate in tests/consistency/hookWatchdogCoverage.test.js enforces it), so the
+// fail-closed block is emitted from a synchronous `exit` handler registered alongside
+// it: `process.exit` discards any write that comes after it, but `exit` listeners run
+// before the process actually terminates.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
+
+// Set by a timer scheduled 1ms ahead of the canonical self-kill. The exit handler uses
+// it to tell a genuine deadline exit apart from a naturally-finished-but-slow run: only
+// the former is a budget overrun of the fail-closed blocker and must block. Without this
+// distinction a slow (but healthy) evaluation that happened to finish just past the
+// budget would be blocked instead of released.
+let deadlineReached = false;
+
+// Evaluator children still running. The deadline path SIGKILLs them before exiting: a
+// `process.exit(0)` that abandons a spawned ledger would reparent it to launchd, the
+// same orphan class the deadline exists to prevent.
+const liveEvaluatorChildren = new Set();
+
+// Set once a decision has left this process (deadline block or normal main() output).
+// Idempotence matters because the deadline may fire after a normal emission, and two
+// JSON lines on one Stop would be two decisions — the exact thing this module removes.
+let decisionEmitted = false;
+
+/**
+ * The ONLY reason text the deadline path may put on stdout. Fixed string: no
+ * interpolation, no error messages, no paths. Distinct from
+ * `redactInfrastructureReason()` only so telemetry can tell a budget overrun from an
+ * evaluator crash without weakening redaction.
+ */
+export function redactDeadlineReason() {
+  return 'UKit stop coordinator: this stop exceeded the hook deadline before the fail-closed completion evaluator could decide, so the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message.';
+}
+
+/**
+ * Emit exactly one JSON decision line, synchronously, at most once per process.
+ * `fs.writeSync` on fd 1 is required on BOTH paths: stdout is a pipe here, and a
+ * `process.exit()` — whether from the deadline timer or the natural end of main() —
+ * discards a buffered async write. An async write that the deadline won the race for
+ * would leave stdout empty, restoring the silent release this module exists to prevent.
+ */
+function writeDecisionLine(payload) {
+  if (decisionEmitted) return false;
+  decisionEmitted = true;
+  try {
+    fsSync.writeSync(1, `${JSON.stringify(payload)}\n`);
+  } catch {}
+  return true;
+}
+
+/**
+ * Emit the fixed fail-closed block for the deadline path, exactly once, synchronously.
+ * Exported so the deadline behaviour is directly testable.
+ */
+export function emitDeadlineBlock() {
+  return writeDecisionLine({
+    decision: 'block',
+    reason: redactDeadlineReason(),
+    policyOwner: 'fail-closed',
+  });
+}
+
+if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
+  process.on('exit', () => {
+    // A run that finished inside its budget already emitted its decision (or decided to
+    // release) — main() owns that path. Only a run the deadline actually cut short is a
+    // budget overrun of the fail-closed blocker, and only that run blocks.
+    if (!deadlineReached) return;
+    emitDeadlineBlock();
+    for (const child of liveEvaluatorChildren) {
+      try { child.kill('SIGKILL'); } catch {}
+    }
+  });
+  // Flipped strictly before the canonical self-kill below, so the exit handler sees it.
+  setTimeout(() => { deadlineReached = true; }, Math.max(0, HOOK_DEADLINE_MS - 1)).unref();
+  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+}
+
+// Two hook scripts registered on the same Stop fire within milliseconds of each
+// other; the shortest real recovery turn is many seconds. 2s only ever catches
+// same-event double registration, never legitimate consecutive Stops.
+export const DEDUPE_WINDOW_MS = 2000;
+
+// Fixed budget slices inside the default 3000ms hook deadline: the ledger child
+// gets the larger slice, each watchdog lock acquisition gets a short one.
+const LEDGER_BUDGET_MS = 1500;
+const LOCK_BUDGET_MS = 600;
+
+const WATCHDOG_PROVENANCE_PREFIX = '[ukit-stop-coordinator] task-watchdog also requested a block: ';
+const WATCHDOG_FAILURE_PREFIX = '[ukit-stop-coordinator] task-watchdog evaluator failed (advisory lane, reported verbatim): ';
+
+// ─── Redaction ────────────────────────────────────────────────────────────
+/**
+ * The ONLY reason text a failed fail-closed blocker may put on stdout. Fixed
+ * string: no interpolation, no error messages, no paths — raw detail stays on
+ * stderr where hook telemetry can see it but the parsed decision cannot leak it.
+ */
+export function redactInfrastructureReason() {
+  return 'UKit stop coordinator: the fail-closed completion evaluator failed while this stop was being evaluated, so the stop is blocked fail-closed (failure details withheld). Run: ukit install, then re-send the task in a new message.';
+}
+
+// ─── Normalization ────────────────────────────────────────────────────────
+/**
+ * Parse one evaluator's stdout into a normalized result.
+ *   { kind: 'block', reason } | { kind: 'advisory', systemMessage } | { kind: 'complete' }
+ * Empty stdout (exit 0) is the ledger's silent-success shape. Unparseable output
+ * from an exit-0 evaluator is an infrastructure failure: throw, caller decides.
+ */
+export function normalizeEvaluatorStdout(stdout) {
+  const line = String(stdout || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .find(Boolean);
+  if (!line) return { kind: 'complete' };
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    throw new Error(`completion evaluator emitted unparseable output: ${line.slice(0, 120)}`);
+  }
+  if (parsed && parsed.decision === 'block') {
+    return {
+      kind: 'block',
+      reason: typeof parsed.reason === 'string' && parsed.reason
+        ? parsed.reason
+        : 'UKit completion gate: blocked this stop without a reason.',
+    };
+  }
+  if (parsed && typeof parsed.systemMessage === 'string' && parsed.systemMessage) {
+    return { kind: 'advisory', systemMessage: parsed.systemMessage };
+  }
+  return { kind: 'complete' };
+}
+
+// ─── Ordered decision merge (pure) ────────────────────────────────────────
+/**
+ * Merge the two evaluator results into AT MOST ONE Stop decision.
+ *
+ * @param {object} [input]
+ * @param {{ kind: 'block'|'advisory'|'complete'|'none', reason?: string, systemMessage?: string } | null} [input.completion]
+ * @param {{ kind: 'block'|'advisory'|'none', reason?: string, systemMessage?: string } | null} [input.watchdog]
+ * @param {{ completion?: string, watchdog?: string }} [input.failures] verbatim failure messages
+ * @returns {{ decision: 'block'|null, reason?: string, systemMessage?: string,
+ *             policyOwner: 'fail-closed'|'completion-gate'|'task-watchdog'|'none',
+ *             policies: string[] }}
+ *   Deterministic owner order: fail-closed completion failure > completion block >
+ *   watchdog block > merged advisory > silent. Reasons keep policy provenance (the
+ *   losing block's reason travels inside the winning reason; losing advisories and
+ *   advisory-lane failures travel in the single systemMessage) — one decision, no
+ *   duplicate prompts.
+ */
+export function coordinateStopDecisions({ completion = null, watchdog = null, failures = {} } = {}) {
+  const completionFailed = typeof failures?.completion === 'string' && failures.completion.length > 0;
+  const watchdogFailed = typeof failures?.watchdog === 'string' && failures.watchdog.length > 0;
+  const watchdogFailureNote = watchdogFailed
+    ? `${WATCHDOG_FAILURE_PREFIX}${failures.watchdog}`
+    : null;
+  const watchdogAdvisory = watchdog?.kind === 'advisory' ? watchdog.systemMessage : null;
+  const policies = [];
+
+  // 1. The fail-closed blocker itself failed → block, redacted, detail on stderr only.
+  if (completionFailed) {
+    policies.push('completion-gate');
+    let reason = redactInfrastructureReason();
+    if (watchdog?.kind === 'block') {
+      policies.push('task-watchdog');
+      reason += `\n${WATCHDOG_PROVENANCE_PREFIX}${watchdog.reason}`;
+    }
+    const notes = [watchdogFailureNote, watchdogAdvisory].filter(Boolean);
+    return {
+      decision: 'block',
+      reason,
+      systemMessage: notes.length > 0 ? notes.join('\n') : undefined,
+      policyOwner: 'fail-closed',
+      policies,
+    };
+  }
+
+  // 2. Completion block → completion owns continuation semantics (evidence/caps).
+  if (completion?.kind === 'block') {
+    policies.push('completion-gate');
+    let reason = completion.reason;
+    if (watchdog?.kind === 'block') {
+      policies.push('task-watchdog');
+      reason += `\n${WATCHDOG_PROVENANCE_PREFIX}${watchdog.reason}`;
+    }
+    const notes = [watchdogFailureNote, watchdogAdvisory].filter(Boolean);
+    return {
+      decision: 'block',
+      reason,
+      systemMessage: notes.length > 0 ? notes.join('\n') : undefined,
+      policyOwner: 'completion-gate',
+      policies,
+    };
+  }
+
+  // 3. Watchdog block → watchdog owns this stop; completion advisory rides along.
+  if (watchdog?.kind === 'block') {
+    policies.push('task-watchdog');
+    if (completion?.kind === 'advisory') policies.push('completion-gate');
+    const notes = [completion?.systemMessage, watchdogFailureNote].filter(Boolean);
+    return {
+      decision: 'block',
+      reason: watchdog.reason,
+      systemMessage: notes.length > 0 ? notes.join('\n') : undefined,
+      policyOwner: 'task-watchdog',
+      policies,
+    };
+  }
+
+  // 4. No block → merge advisories + verbatim failures into ONE systemMessage, or stay silent.
+  if (completion?.kind === 'advisory') policies.push('completion-gate');
+  if (watchdog?.kind === 'advisory') policies.push('task-watchdog');
+  const notes = [completion?.systemMessage, watchdogAdvisory, watchdogFailureNote].filter(Boolean);
+  return {
+    decision: null,
+    reason: undefined,
+    systemMessage: notes.length > 0 ? notes.join('\n') : undefined,
+    policyOwner: 'none',
+    policies,
+  };
+}
+
+// ─── Completion evaluator (spawn once) ────────────────────────────────────
+function runEvaluatorChild(scriptPath, input, budgetMs) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [scriptPath, '--evaluate-stop'], {
+      // The child gets the same environment plus its own (smaller) self-kill budget.
+      env: { ...process.env, UKIT_HOOK_DEADLINE_MS: String(Math.max(250, budgetMs)) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // Tracked so the hook-deadline path can reap a still-running evaluator instead of
+    // orphaning it to launchd when it exits.
+    liveEvaluatorChildren.add(child);
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch {}
+    }, budgetMs);
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.stdin.on('error', () => {}); // a stub evaluator that never reads stdin must not crash us
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      liveEvaluatorChildren.delete(child);
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      liveEvaluatorChildren.delete(child);
+      clearTimeout(timer);
+      if (timedOut) {
+        reject(new Error(`completion evaluator exceeded its ${budgetMs}ms budget and was killed`));
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`completion evaluator exited with status ${code}: ${stderr.trim().slice(-400) || 'no stderr'}`));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+    child.stdin.end(input);
+  });
+}
+
+/**
+ * Run the completion policy exactly once by spawning execution-ledger.mjs
+ * `--evaluate-stop`. Throws on any infrastructure failure — the coordinator
+ * turns that into the fail-closed redacted block.
+ */
+export async function evaluateCompletionPolicy({ projectRoot, rawInput, budgetMs = LEDGER_BUDGET_MS }) {
+  const ledgerPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
+  try {
+    await fs.access(ledgerPath);
+  } catch {
+    throw new Error('completion evaluator unavailable: execution-ledger.mjs is missing (run: ukit install)');
+  }
+  const { stdout } = await runEvaluatorChild(ledgerPath, String(rawInput || ''), budgetMs);
+  return normalizeEvaluatorStdout(stdout);
+}
+
+// ─── Once-per-stop guard ──────────────────────────────────────────────────
+/**
+ * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
+ * invocation is a same-session duplicate inside the window. Fail-open — an
+ * unreadable/unlockable dedupe state must never disable the Stop coordinator.
+ */
+async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs }) {
+  const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
+  try {
+    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {
+      let current = { lastStop: null };
+      try {
+        current = JSON.parse(await fs.readFile(statePath, 'utf8')) || current;
+      } catch {}
+      const last = current.lastStop;
+      const lastTs = Number(last?.ts);
+      if (last && last.key === sessionKey && Number.isFinite(lastTs) && now - lastTs >= 0 && now - lastTs < dedupeWindowMs) {
+        return true;
+      }
+      await fs.mkdir(path.dirname(statePath), { recursive: true });
+      await fs.writeFile(statePath, `${JSON.stringify({ lastStop: { key: sessionKey, ts: now } }, null, 1)}\n`, 'utf8');
+      return false;
+    });
+    return outcome.ok ? outcome.value === true : false;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Orchestration ────────────────────────────────────────────────────────
+/**
+ * One coordinator invocation: event guard → once-per-stop dedupe → completion
+ * evaluator (once) → watchdog evaluator (once) → ordered merge. Returns
+ * `{ skip, merged }`; `skip` is a reason string when nothing may be emitted.
+ */
+export async function runStopCoordinator({
+  projectRoot,
+  payload = {},
+  rawInput = '',
+  now = Date.now(),
+  dedupeWindowMs = DEDUPE_WINDOW_MS,
+  lockBudgetMs = LOCK_BUDGET_MS,
+  ledgerBudgetMs = LEDGER_BUDGET_MS,
+} = {}) {
+  const event = payload?.hook_event_name;
+  if (typeof event === 'string' && event && event !== 'Stop') {
+    return { skip: `ignored event: ${event}`, merged: null };
+  }
+
+  const sessionKey = typeof payload?.session_id === 'string' && payload.session_id
+    ? payload.session_id
+    : (typeof payload?.transcript_path === 'string' && payload.transcript_path ? payload.transcript_path : 'no-session');
+  if (await alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs })) {
+    return { skip: 'duplicate Stop invocation for this session inside the dedupe window', merged: null };
+  }
+
+  let completion = null;
+  const failures = {};
+  try {
+    completion = await evaluateCompletionPolicy({ projectRoot, rawInput, budgetMs: ledgerBudgetMs });
+  } catch (error) {
+    failures.completion = error?.message || String(error);
+    // Raw detail is loud on stderr; the parsed decision stays redacted.
+    process.stderr.write(`[ukit-stop-coordinator] completion evaluator failed: ${failures.completion}\n`);
+  }
+
+  let watchdog = null;
+  try {
+    const watchdogRuntime = await import(new URL('./task-watchdog.mjs', import.meta.url).href);
+    watchdog = await watchdogRuntime.evaluateStopWatchdog({ projectRoot, now, lockBudgetMs });
+  } catch (error) {
+    failures.watchdog = error?.message || String(error);
+    process.stderr.write(`[ukit-stop-coordinator] task-watchdog evaluator failed: ${failures.watchdog}\n`);
+  }
+
+  return { skip: null, merged: coordinateStopDecisions({ completion, watchdog, failures }) };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(String(chunk));
+  return chunks.join('');
+}
+
+async function main() {
+  // The self-deadline is armed once at module load (env-gated). A bare CLI run
+  // leaves it off, matching execution-ledger.mjs's posture.
+  const rawInput = await readStdin();
+  let payload = {};
+  try {
+    payload = JSON.parse(rawInput || '{}') || {};
+  } catch {
+    payload = {}; // malformed payload: forward the raw text to the ledger, which owns crash counting
+  }
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
+  const { skip, merged } = await runStopCoordinator({ projectRoot, payload, rawInput, now: Date.now() });
+  if (skip || !merged) return;
+
+  // Synchronous writes through the shared emission gate: the deadline timer can fire
+  // between any two turns of the event loop, and an already-written decision must never
+  // be followed by a second (deadline) block on the same Stop.
+  if (merged.decision === 'block') {
+    // One JSON line: the single decision, its provenance, and — when an advisory
+    // lane failed or has news — the verbatim note. undefined fields are omitted.
+    writeDecisionLine({
+      decision: 'block',
+      reason: merged.reason,
+      systemMessage: merged.systemMessage,
+      policyOwner: merged.policyOwner,
+    });
+    return;
+  }
+  if (merged.systemMessage) {
+    writeDecisionLine({ systemMessage: merged.systemMessage, policyOwner: merged.policyOwner });
+  }
+  // Neither → silent release: both policies decided "complete".
+}
+
+// Compare real paths (same shape as execution-ledger.mjs): a project under a
+// symlinked root makes import.meta.url resolve to the real path while argv[1]
+// keeps the symlinked spelling. Importing this module must never run main().
+function isDirectRun() {
+  const argvPath = process.argv[1];
+  if (!argvPath) return false;
+  const selfPath = path.resolve(argvPath);
+  let selfUrlPath = null;
+  try {
+    selfUrlPath = new URL(import.meta.url).pathname;
+  } catch {
+    selfUrlPath = null;
+  }
+  if (selfUrlPath && selfUrlPath === selfPath) return true;
+  try {
+    return fsSync.realpathSync(selfUrlPath) === fsSync.realpathSync(selfPath);
+  } catch {
+    return selfUrlPath === selfPath;
+  }
+}
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    // Last-resort failure INSIDE the coordinator: still fail-closed, still redacted.
+    process.stderr.write(`[ukit-stop-coordinator] ${error?.message || error}\n`);
+    writeDecisionLine({ decision: 'block', reason: redactInfrastructureReason() });
+  });
+}