@ngockhoale/ukit 3.4.23 → 3.4.25

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

@@ -956,7 +956,7 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
  *
  * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
  */
-export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null } = {}) {
+export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false } = {}) {
   const gate = await loadHandoffGateConfig(projectRoot);
   if (!gate.enabled) return { kind: 'none' };
 
@@ -1024,6 +1024,20 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
 
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
+  // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
+  // inside the continuation turn WE forced. The same cursor signature seen again
+  // (streak > 1) means that continuation made no cursor progress — blocking again
+  // is a no-progress loop, so release once instead of waiting for the stalled cap.
+  // A moved cursor resets the streak to 1 and keeps blocking (real progress).
+  if (stopHookActive === true && streak !== null && streak > 1) {
+    return {
+      kind: 'advisory',
+      systemMessage:
+        `[ukit-stop-coordinator] handoff-cursor released this reentrant stop (stop_hook_active): ` +
+        `the run cursor ("${signature}") did not advance during the forced continuation. ` +
+        `RUN.md is untouched; resume with /ukit:handoff-fullstack or clear with /ukit:handoff-clear.`,
+    };
+  }
   if (streak !== null && streak > gate.maxStalledBlocks) {
     let predicateState = 'no ExitPredicate recorded';
     if (exitPredicate) {
@@ -1064,6 +1078,101 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   return { kind: 'block', reason: lines.join('\n') };
 }
 
+// ─── Explicit user interruption (pause / cancel) ──────────────────────────
+// A Stop must never be forced while the USER has paused or cancelled the run:
+// every lane (completion, watchdog, handoff-cursor) would otherwise bounce the
+// agent's "PAUSED" reply back as "CONTINUE IMMEDIATELY". The signal is read ONLY
+// from genuine user turns in the host-authored transcript — never from the agent's
+// own words, tool output, sub-agent reports or hook feedback (all skipped). The
+// latest pause/cancel-vs-resume turn wins; neutral turns (questions, health
+// checks) keep the earlier state; an unreadable/over-budget scan is "no
+// interruption" so enforcement is never relaxed by a lost read.
+export const INTERRUPT_SCAN_BUDGET_MS = 800;
+export const INTERRUPT_SCAN_MAX_BYTES = 8 * 1024 * 1024;
+const INTERRUPT_MAX_TEXT = 240;
+const WORD_END = '(?![\\p{L}\\p{N}])';
+const CANCEL_RE = new RegExp(`^(?:please\\s+)?(?:cancel|abort)${WORD_END}|^(?:hủy|huỷ|huy)${WORD_END}`, 'iu');
+const PAUSE_RE = new RegExp(
+  `^(?:please\\s+)?(?:pause|halt|stop|hold\\s+(?:on|off))${WORD_END}`
+  + `|^(?:tạm\\s+dừng|tạm\\s+ngưng|tạm\\s+ngừng|tam\\s+dung|dừng(?:\\s+lại)?|dung\\s+lai|ngừng)${WORD_END}`,
+  'iu',
+);
+const RESUME_RE = new RegExp(
+  `^(?:please\\s+)?(?:continue|resume|proceed|unpause|go\\s+on|carry\\s+on)${WORD_END}`
+  + `|^(?:tiếp\\s+tục|tiep\\s+tuc)${WORD_END}`,
+  'iu',
+);
+const SYNTHETIC_USER_PREFIX = /^(?:<system-reminder|<task-notification|<local-command|<user-prompt-submit-hook|Stop hook feedback|\[ukit|Caveat:|\[Request interrupted)/i;
+const RESUME_COMMAND_TAG = /^<command-name>\/?(?:ukit:)?handoff-(?:fullstack|implement)(?![\w-])/;
+
+function genuineUserText(entry) {
+  if (!entry || entry.type !== 'user' || entry.isSidechain === true || entry.isMeta === true) return null;
+  const msg = entry.message;
+  if (!msg || msg.role !== 'user') return null;
+  let text = '';
+  if (typeof msg.content === 'string') {
+    text = msg.content;
+  } else if (Array.isArray(msg.content)) {
+    for (const b of msg.content) {
+      if (!b || typeof b !== 'object') continue;
+      if (b.type === 'tool_result') return null;
+      if (b.type === 'text' && typeof b.text === 'string') text += (text ? '\n' : '') + b.text;
+    }
+  } else {
+    return null;
+  }
+  text = text.trim();
+  if (!text || SYNTHETIC_USER_PREFIX.test(text)) return null;
+  return text;
+}
+
+/**
+ * @returns {Promise<{ kind: 'pause'|'cancel'|null }>} Newest decisive genuine user
+ * turn: pause/cancel → interrupted; resume → not interrupted; none → not interrupted.
+ */
+export async function detectUserInterruption(transcriptPath, {
+  budgetMs = INTERRUPT_SCAN_BUDGET_MS,
+  maxBytes = INTERRUPT_SCAN_MAX_BYTES,
+} = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return { kind: null };
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const size = Number((await handle.stat()).size) || 0;
+    const start = Math.max(0, size - maxBytes);
+    const deadline = Date.now() + budgetMs;
+    const buf = Buffer.allocUnsafe(size - start);
+    let got = 0;
+    while (got < buf.length) {
+      if (Date.now() > deadline) return { kind: null };
+      const { bytesRead } = await handle.read(buf, got, buf.length - got, start + got);
+      if (!bytesRead) break;
+      got += bytesRead;
+    }
+    let lines = buf.toString('utf8', 0, got).split('\n');
+    if (start > 0) lines = lines.slice(1);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      if (Date.now() > deadline) return { kind: null };
+      const line = lines[i];
+      if (!line || !line.includes('"user"') || line.includes('"tool_result"')) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      const text = genuineUserText(entry);
+      if (text === null) continue;
+      if (RESUME_COMMAND_TAG.test(text)) return { kind: null };
+      if (text.length > INTERRUPT_MAX_TEXT) continue;
+      if (CANCEL_RE.test(text)) return { kind: 'cancel' };
+      if (PAUSE_RE.test(text)) return { kind: 'pause' };
+      if (RESUME_RE.test(text)) return { kind: null };
+    }
+    return { kind: null };
+  } catch {
+    return { kind: null };
+  } finally {
+    try { await handle?.close(); } catch {}
+  }
+}
+
 // ─── Once-per-stop guard ──────────────────────────────────────────────────
 /**
  * Lock-scoped dedupe: persist `{ lastStop: { key, ts } }` and report whether this
@@ -1124,6 +1233,27 @@ export async function runStopCoordinator({
     return { skip: 'duplicate Stop invocation for this session inside the dedupe window', merged: null };
   }
 
+  // User pause/cancel outranks every lane: release, change nothing (RUN.md, tasks,
+  // branches, worktrees stay as they are so the run can be resumed).
+  const interruption = await detectUserInterruption(
+    typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+  );
+  if (interruption.kind) {
+    return {
+      skip: null,
+      merged: {
+        decision: null,
+        reason: undefined,
+        systemMessage:
+          `[ukit-stop-coordinator] stop allowed: the user requested ${interruption.kind}. ` +
+          `No verification or continuation is forced; run state is preserved. ` +
+          `Resume by asking to continue (or /ukit:handoff-fullstack).`,
+        policyOwner: 'user-interruption',
+        policies: ['user-interruption'],
+      },
+    };
+  }
+
   let completion = null;
   const failures = {};
   try {
@@ -1149,6 +1279,7 @@ export async function runStopCoordinator({
       now,
       lockBudgetMs,
       transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+      stopHookActive: payload?.stop_hook_active === true,
     });
   } catch (error) {
     failures.handoff = error?.message || String(error);