agentxchain 2.155.73 → 2.157.0

package/src/lib/claude-local-auth.js

@@ -17,6 +17,18 @@ const CLAUDE_NODE_INCOMPATIBILITY_RE =
   /TypeError:\s*Object not disposable|TypeError\(["']Object not disposable["']\)|Object not disposable[\s\S]{0,2000}Node\.js v(?:1[0-9]|20\.[0-4]\.)/i;
 const CLAUDE_COMPATIBLE_NODE_MIN = { major: 20, minor: 5, patch: 0 };
 
+// Rate-limit detection — provider-agnostic patterns for subprocess output.
+// Matches Claude/Anthropic, OpenAI/Codex, and generic rate-limit signatures.
+const RATE_LIMIT_RE = /rate_limit_error|"error"\s*:\s*"rate_limit"|rate[_\s-]?limited|hit[_\s-]your[_\s-]limit|usage\s+limit|rate\s+limit\s+reached|429\s*too\s*many\s*requests|too\s+many\s+requests/i;
+
+// Reset time extraction — best-effort parsing of provider-reported reset delay.
+const RESET_PATTERNS = [
+  /resets?\s+in\s+(\d+)\s*s/i,                   // "Resets in 42s"
+  /retry[_\s-]?after\s*[:=]\s*(\d+)/i,           // "Retry-After: 30"
+  /wait\s+(\d+)\s*s(?:econds?)?/i,               // "Please wait 60 seconds"
+  /(?:rate[_\s-]?limit|too\s+many)[\s\S]{0,80}?(\d+)\s*seconds?/i,  // "Rate limited. Try again in 120 seconds."
+];
+
 function normalizeCommandTokens(runtime) {
   if (Array.isArray(runtime?.command)) {
     return runtime.command.flatMap((element) =>
@@ -47,6 +59,33 @@ export function isCodexLocalCliRuntime(runtime) {
   return head === 'codex' || head.endsWith('/codex');
 }
 
+export function isCursorLocalCliRuntime(runtime) {
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return false;
+  }
+  const head = tokens[0].toLowerCase();
+  return head === 'cursor' || head.endsWith('/cursor');
+}
+
+export function isWindsurfLocalCliRuntime(runtime) {
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return false;
+  }
+  const head = tokens[0].toLowerCase();
+  return head === 'windsurf' || head.endsWith('/windsurf');
+}
+
+export function isOpenCodeLocalCliRuntime(runtime) {
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return false;
+  }
+  const head = tokens[0].toLowerCase();
+  return head === 'opencode' || head.endsWith('/opencode');
+}
+
 export function hasClaudeAuthenticationFailureText(text) {
   return typeof text === 'string' && CLAUDE_AUTH_FAILURE_RE.test(text);
 }
@@ -63,6 +102,41 @@ export function hasClaudeBareFlag(runtime) {
   return normalizeCommandTokens(runtime).includes('--bare');
 }
 
+/**
+ * Returns true if the text contains any provider rate-limit signature.
+ * Provider-agnostic — works for Claude, OpenAI/Codex, Cursor, Windsurf, OpenCode, and generic 429 patterns.
+ */
+export function hasProviderRateLimitText(text) {
+  return typeof text === 'string' && RATE_LIMIT_RE.test(text);
+}
+
+/**
+ * Returns true if any log line contains a rate-limit signature.
+ * Mirrors hasClaudeAuthFailureOutput / hasCodexAuthFailureOutput pattern.
+ */
+export function hasRateLimitOutput(logs) {
+  if (!Array.isArray(logs)) return false;
+  return logs.some((line) => hasProviderRateLimitText(line));
+}
+
+/**
+ * Best-effort extraction of reset delay from subprocess output text.
+ * Returns milliseconds or null if no reset time is found.
+ */
+export function parseRateLimitResetMs(text) {
+  if (typeof text !== 'string') return null;
+  for (const pattern of RESET_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      const seconds = Number.parseInt(match[1], 10);
+      if (seconds > 0 && seconds <= 3600) {
+        return seconds * 1000;
+      }
+    }
+  }
+  return null;
+}
+
 function parseNodeVersion(raw) {
   const match = String(raw || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
   if (!match) return null;
@@ -324,4 +398,4 @@ export async function runClaudeSmokeProbe(opts) {
   });
 }
 
-export { CLAUDE_ENV_AUTH_KEYS, normalizeCommandTokens };
+export { CLAUDE_ENV_AUTH_KEYS, normalizeCommandTokens, RESET_PATTERNS };

package/src/lib/connector-probe.js

@@ -28,6 +28,24 @@ const KNOWN_CLI_AUTHORITY_FLAGS = [
     weak_flags: ['--full-auto'],
     label: 'OpenAI Codex CLI',
   },
+  {
+    binary: 'cursor',
+    authoritative_flag: '--background-agent',
+    weak_flags: [],
+    label: 'Cursor IDE',
+  },
+  {
+    binary: 'windsurf',
+    authoritative_flag: '--agent',
+    weak_flags: [],
+    label: 'Windsurf IDE',
+  },
+  {
+    binary: 'opencode',
+    authoritative_flag: '--non-interactive',
+    weak_flags: [],
+    label: 'OpenCode CLI',
+  },
 ];
 
 /**
@@ -37,6 +55,9 @@ const KNOWN_CLI_AUTHORITY_FLAGS = [
 const KNOWN_CLI_TRANSPORTS = {
   claude: ['stdin'],
   codex: ['argv', 'stdin'],
+  cursor: ['dispatch_bundle_only'],
+  windsurf: ['dispatch_bundle_only'],
+  opencode: ['stdin'],
 };
 
 function formatCommand(command, args = []) {

package/src/lib/continuous-run.js

@@ -1141,10 +1141,27 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
   }
 
   const errorClass = result.error_class || 'reconcile_refused';
+  // RB-14: `reconcile-state --accept-operator-head` runs the SAME safety check, so it
+  // cannot clear an unsafe-edit refusal — recommending it for governance_state_modified
+  // or critical_artifact_deleted is a dead end. Give the recovery that actually applies.
+  const offendingCommit = result.offending_commit || result.commit || null;
+  const offendingPath = result.offending_path || result.path || null;
+  let recoveryAction;
+  let recoveryDetailTail;
+  if (errorClass === 'governance_state_modified') {
+    recoveryAction = offendingCommit ? `git revert ${offendingCommit.slice(0, 12)}` : 'git revert <offending-commit>';
+    recoveryDetailTail = `${offendingPath || 'A commit'} edits governed state under .agentxchain/ directly, which the anti-tamper guard never auto-accepts (reconcile-state --accept-operator-head enforces the same check). Revert it (${recoveryAction}) to restore the governed lineage, or restart from an explicit prior checkpoint.`;
+  } else if (errorClass === 'critical_artifact_deleted') {
+    recoveryAction = (offendingCommit && offendingPath) ? `git checkout ${offendingCommit.slice(0, 12)}^ -- ${offendingPath}` : 'git checkout <commit>^ -- <deleted-path>';
+    recoveryDetailTail = `Critical governed evidence ${offendingPath || ''} was deleted; restore it (${recoveryAction}), then resume.`;
+  } else {
+    recoveryAction = 'agentxchain reconcile-state --accept-operator-head';
+    recoveryDetailTail = `Run: ${recoveryAction} once the unsafe changes are resolved, or revert them.`;
+  }
   const detailLines = [
     `Operator-commit auto-reconcile refused (${errorClass}).`,
     result.error || 'Unsafe operator commits detected; manual recovery required.',
-    'Run: agentxchain reconcile-state --accept-operator-head once the unsafe changes are resolved, or revert them.',
+    recoveryDetailTail,
   ];
   const detail = detailLines.join(' ');
 
@@ -1164,7 +1181,7 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
           ...((state.blocked_reason || {}).recovery || {}),
           typed_reason: 'operator_commit_reconcile_refused',
           owner: 'human',
-          recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+          recovery_action: recoveryAction,
           turn_retained: false,
           detail,
         },
@@ -1196,7 +1213,7 @@ export function maybeAutoReconcileOperatorCommits(context, session, contOpts, lo
     status: 'blocked',
     action: 'operator_commit_reconcile_refused',
     run_id: session.current_run_id,
-    recovery_action: 'agentxchain reconcile-state --accept-operator-head',
+    recovery_action: recoveryAction,
     blocked_category: 'operator_commit_reconcile_refused',
     error_class: errorClass,
   };
@@ -1326,6 +1343,9 @@ export function seedFromVision(root, visionPath, options = {}) {
         reason: 'roadmap-open-work auto-approval',
       });
       if (!approveResult.ok) {
+        if (approveResult.error === 'scope_overlap_detected') {
+          return { ok: true, idle: true, deferred_reason: 'scope_overlap', overlap: approveResult.overlap };
+        }
         return { ok: false, error: `approve failed: ${approveResult.error}` };
       }
     }
@@ -1401,6 +1421,9 @@ export function seedFromVision(root, visionPath, options = {}) {
         reason: 'roadmap-replenishment auto-approval (BUG-77)',
       });
       if (!approveResult.ok) {
+        if (approveResult.error === 'scope_overlap_detected') {
+          return { ok: true, idle: true, deferred_reason: 'scope_overlap', overlap: approveResult.overlap };
+        }
         return { ok: false, error: `approve failed: ${approveResult.error}` };
       }
     }
@@ -1484,6 +1507,9 @@ export function seedFromVision(root, visionPath, options = {}) {
       reason: 'vision-derived auto-approval',
     });
     if (!approveResult.ok) {
+      if (approveResult.error === 'scope_overlap_detected') {
+        return { ok: true, idle: true, deferred_reason: 'scope_overlap', overlap: approveResult.overlap };
+      }
       return { ok: false, error: `approve failed: ${approveResult.error}` };
     }
   }
@@ -2570,10 +2596,47 @@ export async function executeContinuousRun(context, contOpts, executeGovernedRun
   process.on('SIGINT', sigHandler);
 
   try {
+    // RB-13: circuit-breaker for the recover-and-continue path. A deterministic,
+    // recurring failure (e.g. an unclean baseline) must escalate, not busy-loop
+    // forever — without this, the same start error spun 582 times in seconds.
+    // Track consecutive identical recoveries; halt and escalate after a cap, and
+    // back off between attempts so even allowed retries can't tight-loop.
+    let consecutiveRecoveries = 0;
+    let lastRecoveryReason = null;
+    const maxConsecutiveRecoveries = Math.max(1, contOpts.maxConsecutiveRecoveries ?? 3);
+
     while (!stopping) {
       const step = await advanceContinuousRunOnce(context, session, contOpts, executeGovernedRun, log);
 
       if (step.status === 'failed' && isGovernedRunStillActiveForSession(root, context.config, session)) {
+        const recoveryReason = step.stop_reason || step.action || 'unknown';
+        if (recoveryReason === lastRecoveryReason) {
+          consecutiveRecoveries += 1;
+        } else {
+          consecutiveRecoveries = 1;
+          lastRecoveryReason = recoveryReason;
+        }
+
+        if (consecutiveRecoveries >= maxConsecutiveRecoveries) {
+          // Circuit open: the same recoverable failure keeps recurring without
+          // progress. Escalate to a human instead of spinning the loop.
+          session.status = 'blocked';
+          writeContinuousSession(root, session);
+          emitRunEvent(root, 'continuous_recovery_circuit_open', {
+            run_id: session.current_run_id || null,
+            phase: null,
+            status: 'blocked',
+            payload: {
+              session_id: session.session_id,
+              failed_action: step.action || null,
+              failed_reason: recoveryReason,
+              consecutive_recoveries: consecutiveRecoveries,
+            },
+          });
+          log(`Continuous loop halted (circuit-breaker): the same recoverable failure recurred ${consecutiveRecoveries} times with no progress — escalating to a human instead of spinning. Reason: ${recoveryReason}`);
+          return { exitCode: 1, session };
+        }
+
         session.status = 'running';
         writeContinuousSession(root, session);
         emitRunEvent(root, 'session_failed_recovered_active_run', {
@@ -2584,12 +2647,20 @@ export async function executeContinuousRun(context, contOpts, executeGovernedRun
             session_id: session.session_id,
             failed_action: step.action || null,
             failed_reason: step.stop_reason || null,
+            consecutive_recoveries: consecutiveRecoveries,
           },
         });
-        log('Session failure recovered - governed run still active, continuing.');
+        log(`Session failure recovered - governed run still active, continuing (recovery ${consecutiveRecoveries}/${maxConsecutiveRecoveries}).`);
+        // Backoff before retrying so a recurring failure cannot busy-loop.
+        const recoveryBackoffMs = Math.max(1000, (contOpts.cooldownSeconds ?? 5) * 1000);
+        await new Promise((resolve) => setTimeout(resolve, recoveryBackoffMs));
         continue;
       }
 
+      // A non-recovery step means the loop made forward progress — reset the breaker.
+      consecutiveRecoveries = 0;
+      lastRecoveryReason = null;
+
       // Terminal states
       if (step.status === 'completed' || step.status === 'idle_exit' || step.status === 'failed' || step.status === 'blocked' || step.status === 'stopped' || step.status === 'vision_exhausted' || step.status === 'vision_expansion_exhausted' || step.status === 'session_budget') {
         const terminalMessage = describeContinuousTerminalStep(step, contOpts);

package/src/lib/dashboard/bridge-server.js

@@ -287,14 +287,19 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       try {
         const eventsPath = join(agentxchainDir, 'events.jsonl');
         if (!existsSync(eventsPath)) return;
-        const content = readFileSync(eventsPath, 'utf8');
-        if (content.length <= lastEventsFileSize) {
+        // Read as Buffer so .length is byte count, consistent with the
+        // byte-based lastEventsFileSize initialized at startup.  The old
+        // code read as 'utf8' (string), whose .length is *character* count
+        // — a mismatch that caused a full-replay on the first invalidation
+        // when events contained multi-byte UTF-8 content.
+        const contentBuf = readFileSync(eventsPath);
+        if (contentBuf.length <= lastEventsFileSize) {
           // File was truncated — reset and push all
-          if (content.length < lastEventsFileSize) lastEventsFileSize = 0;
+          if (contentBuf.length < lastEventsFileSize) lastEventsFileSize = 0;
           else return;
         }
-        const newContent = content.slice(lastEventsFileSize);
-        lastEventsFileSize = content.length;
+        const newContent = contentBuf.slice(lastEventsFileSize).toString('utf8');
+        lastEventsFileSize = contentBuf.length;
         const lines = newContent.split('\n').filter(Boolean);
         for (const line of lines) {
           try {

package/src/lib/governed-state.js

@@ -4868,7 +4868,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
 
   const derivedRef = deriveAcceptedRef(observation, artifactType, state.accepted_integration_ref);
   const verificationReplay = (config.policies || []).some((policy) => policy?.rule === 'require_reproducible_verification')
-    ? replayVerificationMachineEvidence({ root, verification: turnResult.verification })
+    ? replayVerificationMachineEvidence({ root, verification: turnResult.verification, allowCommandExecution: true })
     : null;
 
   if (verificationReplay?.workspace_guard?.ok === false) {

package/src/lib/intake.js

@@ -28,6 +28,7 @@ import {
   derivePhaseScopeFromIntentMetadata,
   getPhaseOrder,
 } from './intent-phase-scope.js';
+import { checkIntentScopeOverlap } from './scope-overlap.js';
 
 const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan', 'vision_idle_expansion'];
 const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
@@ -886,6 +887,25 @@ export function approveIntent(root, intentId, options = {}) {
     return { ok: false, error: `cannot approve from status "${intent.status}" (must be triaged or blocked)`, exitCode: 1 };
   }
 
+  // --- Scope overlap guard (M10) ---
+  if (!options.forceScope) {
+    const charterText = intent.charter || '';
+    const acceptanceItems = Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract : [];
+    if (charterText) {
+      const overlapCheck = checkIntentScopeOverlap(root, charterText, acceptanceItems, {
+        threshold: options.scopeOverlapThreshold ?? 0.4,
+      });
+      if (overlapCheck.overlapping) {
+        return {
+          ok: false,
+          error: 'scope_overlap_detected',
+          overlap: overlapCheck,
+          exitCode: 3,
+        };
+      }
+    }
+  }
+
   const approver = options.approver || 'operator';
   const previousStatus = intent.status;
   const reason = options.reason || (previousStatus === 'blocked' ? 're-approved after block resolution' : 'approved for planning');
@@ -1077,13 +1097,19 @@ export function startIntent(root, intentId, options = {}) {
 
   // Load governed state
   const statePath = join(root, STATE_PATH);
+  let state;
   if (!existsSync(statePath)) {
-    return { ok: false, error: 'No governed state.json found', exitCode: 2 };
-  }
-
-  let state = loadProjectState(root, config);
-  if (!state) {
-    return { ok: false, error: 'Failed to parse governed state.json', exitCode: 2 };
+    // RB-11: cold-start. No state.json yet — synthesize an idle state so the
+    // bootstrap below initializes a fresh governed run, matching the `run`
+    // command. Without this, `intake start` (and continuous mode, which starts
+    // its first derived intent via this path) cannot start lights-out from a
+    // clean initialized project.
+    state = { status: 'idle', run_id: null };
+  } else {
+    state = loadProjectState(root, config);
+    if (!state) {
+      return { ok: false, error: 'Failed to parse governed state.json', exitCode: 2 };
+    }
   }
 
   const allowCompletedRestart = options.allowTerminalRestart === true

package/src/lib/normalized-config.js

@@ -445,6 +445,7 @@ export function validateV4Config(data, projectRoot) {
       if (rt.type === 'local_cli') {
         validateRuntimePositiveInteger(`Runtime "${id}": startup_watchdog_ms`, rt.startup_watchdog_ms, errors);
         validateRuntimePositiveInteger(`Runtime "${id}": startup_heartbeat_ms`, rt.startup_heartbeat_ms, errors);
+        validateRuntimePositiveInteger(`Runtime "${id}": liveness_heartbeat_ms`, rt.liveness_heartbeat_ms, errors);
       }
       // Validate prompt_transport for local_cli runtimes
       if (rt.type === 'local_cli' && rt.prompt_transport) {
@@ -641,6 +642,7 @@ export function validateRunLoopConfig(runLoop) {
   }
   validateRunLoopPositiveInteger('run_loop.startup_watchdog_ms', runLoop.startup_watchdog_ms, errors);
   validateRunLoopPositiveInteger('run_loop.startup_heartbeat_ms', runLoop.startup_heartbeat_ms, errors);
+  validateRunLoopPositiveInteger('run_loop.liveness_heartbeat_ms', runLoop.liveness_heartbeat_ms, errors);
   validateRunLoopPositiveInteger('run_loop.stale_turn_threshold_ms', runLoop.stale_turn_threshold_ms, errors);
   if (runLoop.continuous !== undefined && runLoop.continuous !== null) {
     validateRunLoopContinuousConfig('run_loop.continuous', runLoop.continuous, errors);

package/src/lib/scope-overlap.js

@@ -0,0 +1,214 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Stop words aligned with vision-reader.js:155
+const STOP_WORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+  'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
+  'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
+  'could', 'should', 'may', 'might', 'must', 'shall', 'can', 'that',
+  'this', 'these', 'those', 'it', 'its', 'they', 'them', 'their',
+  'not', 'no', 'nor', 'only', 'also', 'just', 'than', 'then',
+  'each', 'every', 'all', 'any', 'both', 'such', 'as', 'more',
+]);
+
+// Structural boilerplate introduced by seedFromVision charter/acceptance templates.
+// These tokens appear in every vision-derived intent and create false overlap.
+const TEMPLATE_NOISE = new Set([
+  'vision', 'goal', 'addressed', 'section',
+]);
+
+/**
+ * Extract a scope fingerprint from charter/acceptance text.
+ *
+ * Extracts normalized significant tokens:
+ * - Milestone references: M1, M2, ..., M10 (case-insensitive)
+ * - Bug references: BUG-54, BUG-78, etc.
+ * - MW reference (workflow kit milestone)
+ * - File paths: patterns matching cli/src/..., cli/test/..., .planning/...
+ * - Module keywords: significant words (>3 chars) after stop-word removal
+ *
+ * @param {string} text - Charter and/or acceptance contract text (concatenated)
+ * @returns {Set<string>} - Set of normalized lowercase tokens
+ */
+export function extractScopeFingerprint(text) {
+  if (!text || typeof text !== 'string') return new Set();
+
+  const tokens = new Set();
+
+  // 1. Milestone refs: M1, M2, ..., M10 etc.
+  const milestoneRefs = text.match(/\bM\d+\b/gi);
+  if (milestoneRefs) {
+    for (const ref of milestoneRefs) tokens.add(ref.toLowerCase());
+  }
+
+  // 2. Bug refs: BUG-54, BUG-78, etc.
+  const bugRefs = text.match(/\bBUG-\d+\b/gi);
+  if (bugRefs) {
+    for (const ref of bugRefs) tokens.add(ref.toLowerCase());
+  }
+
+  // 3. MW ref
+  const mwRefs = text.match(/\bMW\b/gi);
+  if (mwRefs) tokens.add('mw');
+
+  // 4. File paths: cli/src/..., cli/test/..., cli/bin/..., .planning/...
+  const filePaths = text.match(/(?:cli\/(?:src|test|bin)\/\S+|\.planning\/\S+)/g);
+  if (filePaths) {
+    for (const fp of filePaths) tokens.add(fp.toLowerCase());
+  }
+
+  // 5. Module keywords: significant words (>3 chars) after stop-word removal
+  const cleaned = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 3 && !STOP_WORDS.has(w) && !TEMPLATE_NOISE.has(w) && !/^\d+$/.test(w));
+  for (const word of cleaned) tokens.add(word);
+
+  return tokens;
+}
+
+/**
+ * Compute Jaccard similarity between two scope fingerprints.
+ *
+ * Jaccard = |A ∩ B| / |A ∪ B|
+ * Returns 0 when both sets are empty (no overlap by definition).
+ *
+ * @param {Set<string>} a - First fingerprint
+ * @param {Set<string>} b - Second fingerprint
+ * @returns {number} - Similarity score between 0.0 and 1.0
+ */
+export function computeScopeOverlap(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+
+  let intersection = 0;
+  for (const token of a) {
+    if (b.has(token)) intersection++;
+  }
+
+  const union = a.size + b.size - intersection;
+  if (union === 0) return 0;
+
+  return intersection / union;
+}
+
+/**
+ * Extract charter text from state.json active run.
+ * Checks: 1) first active turn's intake_context.charter, 2) provenance.trigger_reason
+ */
+function extractActiveRunCharter(state) {
+  // Check active turns for intake_context.charter
+  if (state.active_turns && Array.isArray(state.active_turns)) {
+    for (const turn of state.active_turns) {
+      if (turn.intake_context && turn.intake_context.charter) {
+        return turn.intake_context.charter;
+      }
+    }
+  }
+
+  // Fall back to provenance.trigger_reason
+  if (state.provenance && state.provenance.trigger_reason) {
+    return state.provenance.trigger_reason;
+  }
+
+  return null;
+}
+
+/**
+ * Load recent completed intents from .agentxchain/intake/intents/*.json
+ */
+function loadRecentCompletedIntents(root, limit) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  if (!existsSync(intentsDir)) return [];
+
+  let files;
+  try {
+    files = readdirSync(intentsDir).filter(f => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+
+  const intents = [];
+  for (const file of files) {
+    try {
+      const intent = JSON.parse(readFileSync(join(intentsDir, file), 'utf8'));
+      if (intent.status === 'completed' || intent.status === 'satisfied') {
+        intents.push(intent);
+      }
+    } catch {
+      // Skip malformed intent files
+    }
+  }
+
+  // Sort by updated_at descending, take first `limit`
+  intents.sort((a, b) => {
+    const dateA = a.updated_at || a.created_at || '';
+    const dateB = b.updated_at || b.created_at || '';
+    return dateB.localeCompare(dateA);
+  });
+
+  return intents.slice(0, limit);
+}
+
+/**
+ * Check if an intent's charter overlaps with active or recent work.
+ *
+ * @param {string} root - Project root
+ * @param {string} charter - The candidate intent's charter text
+ * @param {string[]} acceptanceContract - The candidate intent's acceptance items
+ * @param {object} [options]
+ * @param {number} [options.threshold=0.4] - Jaccard score above which overlap is reported
+ * @param {number} [options.lookbackIntents=10] - Max recent completed intents to check
+ * @returns {{ overlapping: boolean, matches: Array<{ source: string, charter: string, score: number }>, max_score: number }}
+ */
+export function checkIntentScopeOverlap(root, charter, acceptanceContract, options = {}) {
+  const threshold = options.threshold ?? 0.4;
+  const lookbackIntents = options.lookbackIntents ?? 10;
+
+  const candidateText = charter + ' ' + (Array.isArray(acceptanceContract) ? acceptanceContract.join(' ') : '');
+  const candidateFP = extractScopeFingerprint(candidateText);
+
+  // Too few tokens means there isn't enough semantic signal for meaningful
+  // comparison — skip overlap check to avoid false positives from
+  // section names or template scaffolding alone.
+  if (candidateFP.size < 3) {
+    return { overlapping: false, matches: [], max_score: 0 };
+  }
+
+  const matches = [];
+
+  // 1. Check active run
+  const statePath = join(root, '.agentxchain', 'state.json');
+  if (existsSync(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync(statePath, 'utf8'));
+      if (state && state.status === 'active') {
+        const activeCharter = extractActiveRunCharter(state);
+        if (activeCharter) {
+          const activeFP = extractScopeFingerprint(activeCharter);
+          const score = computeScopeOverlap(candidateFP, activeFP);
+          if (score > 0) {
+            matches.push({ source: 'active_run', charter: activeCharter, score });
+          }
+        }
+      }
+    } catch {
+      // Non-fatal — state read failure doesn't block approval
+    }
+  }
+
+  // 2. Check recent completed intents
+  const recentIntents = loadRecentCompletedIntents(root, lookbackIntents);
+  for (const intent of recentIntents) {
+    const intentText = (intent.charter || '') + ' ' + (Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract.join(' ') : '');
+    const intentFP = extractScopeFingerprint(intentText);
+    const score = computeScopeOverlap(candidateFP, intentFP);
+    if (score > 0) {
+      matches.push({ source: `intent:${intent.intent_id}`, charter: intent.charter || '', score });
+    }
+  }
+
+  const max_score = Math.max(0, ...matches.map(m => m.score));
+  return { overlapping: max_score >= threshold, matches, max_score };
+}