agentxchain 2.155.72 → 2.156.0

package/src/lib/recovery-classification.js

@@ -0,0 +1,158 @@
+const DOMAINS = ['ghost', 'budget', 'credential', 'crash'];
+const OUTCOMES = ['recovered', 'exhausted', 'manual', 'pending'];
+
+const EVENT_CLASSIFICATIONS = {
+  auto_retried_ghost: {
+    domain: 'ghost',
+    severity: 'medium',
+    outcome: 'recovered',
+    mechanism: 'auto_retry',
+    summary: 'Ghost turn reissued automatically',
+  },
+  ghost_retry_exhausted: {
+    domain: 'ghost',
+    severity: 'high',
+    outcome: 'exhausted',
+    mechanism: 'auto_retry',
+    summary: 'Ghost retry budget exhausted',
+  },
+  auto_retried_productive_timeout: {
+    domain: 'ghost',
+    severity: 'medium',
+    outcome: 'recovered',
+    mechanism: 'auto_retry',
+    summary: 'Productive timeout reissued automatically',
+  },
+  productive_timeout_retry_exhausted: {
+    domain: 'ghost',
+    severity: 'high',
+    outcome: 'exhausted',
+    mechanism: 'auto_retry',
+    summary: 'Productive timeout retry budget exhausted',
+  },
+  budget_exceeded_warn: {
+    domain: 'budget',
+    severity: 'medium',
+    outcome: 'pending',
+    mechanism: 'config_change',
+    summary: 'Budget warning threshold exceeded',
+  },
+  retained_claude_auth_escalation_reclassified: {
+    domain: 'credential',
+    severity: 'medium',
+    outcome: 'pending',
+    mechanism: 'env_refresh',
+    summary: 'Claude credential escalation reclassified',
+  },
+  continuous_paused_active_run_recovered: {
+    domain: 'crash',
+    severity: 'medium',
+    outcome: 'recovered',
+    mechanism: 'loop_guard',
+    summary: 'Paused continuous session recovered active run',
+  },
+  session_failed_recovered_active_run: {
+    domain: 'crash',
+    severity: 'medium',
+    outcome: 'recovered',
+    mechanism: 'loop_guard',
+    summary: 'Failed continuous step recovered active run',
+  },
+};
+
+function getEventPayload(event) {
+  return event && typeof event.payload === 'object' && !Array.isArray(event.payload)
+    ? event.payload
+    : {};
+}
+
+function escalateSeverity(eventType, payload, severity) {
+  if (eventType === 'ghost_retry_exhausted' && payload.exhaustion_reason === 'same_signature_repeat') {
+    return 'critical';
+  }
+  if (eventType === 'budget_exceeded_warn' && typeof payload.remaining_usd === 'number' && payload.remaining_usd <= 0) {
+    return 'high';
+  }
+  return severity;
+}
+
+function emptyOutcomeCounts() {
+  return Object.fromEntries(OUTCOMES.map((outcome) => [outcome, 0]));
+}
+
+function emptyDomainCounts() {
+  return Object.fromEntries(DOMAINS.map((domain) => [domain, { total: 0, ...emptyOutcomeCounts() }]));
+}
+
+function formatSummary(eventType, payload, fallback) {
+  if (payload.recovery_class && typeof payload.recovery_class === 'string') return payload.recovery_class;
+  if (payload.warning && typeof payload.warning === 'string') return payload.warning;
+  if (payload.recovery_action && typeof payload.recovery_action === 'string') return payload.recovery_action;
+  return fallback || eventType;
+}
+
+export function classifyRecoveryEvent(event) {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) return null;
+  const eventType = event.event_type || event.type;
+  const base = EVENT_CLASSIFICATIONS[eventType];
+  if (!base) return null;
+
+  const payload = getEventPayload(event);
+  return {
+    domain: base.domain,
+    severity: escalateSeverity(eventType, payload, base.severity),
+    outcome: base.outcome,
+    mechanism: base.mechanism,
+  };
+}
+
+export function buildRecoveryClassificationReport(events) {
+  const byDomain = emptyDomainCounts();
+  const byOutcome = emptyOutcomeCounts();
+  const timeline = [];
+
+  for (const event of Array.isArray(events) ? events : []) {
+    const classification = classifyRecoveryEvent(event);
+    if (!classification) continue;
+
+    byDomain[classification.domain].total += 1;
+    byDomain[classification.domain][classification.outcome] += 1;
+    byOutcome[classification.outcome] += 1;
+
+    const eventType = event.event_type || event.type;
+    const payload = getEventPayload(event);
+    timeline.push({
+      event_id: event.event_id || null,
+      timestamp: event.timestamp || null,
+      event_type: eventType,
+      domain: classification.domain,
+      severity: classification.severity,
+      outcome: classification.outcome,
+      mechanism: classification.mechanism,
+      summary: formatSummary(eventType, payload, EVENT_CLASSIFICATIONS[eventType]?.summary),
+    });
+  }
+
+  timeline.sort((left, right) => {
+    const leftTime = Date.parse(left.timestamp || '');
+    const rightTime = Date.parse(right.timestamp || '');
+    const normalizedLeft = Number.isNaN(leftTime) ? Number.POSITIVE_INFINITY : leftTime;
+    const normalizedRight = Number.isNaN(rightTime) ? Number.POSITIVE_INFINITY : rightTime;
+    if (normalizedLeft !== normalizedRight) return normalizedLeft - normalizedRight;
+    return String(left.event_id || '').localeCompare(String(right.event_id || ''), 'en');
+  });
+
+  const totalRecoveryEvents = timeline.length;
+  const hasCritical = timeline.some((entry) => entry.severity === 'critical');
+  const healthScore = hasCritical || byOutcome.exhausted > byOutcome.recovered
+    ? 'critical'
+    : (byOutcome.exhausted > 0 || byOutcome.manual > 0 ? 'degraded' : 'healthy');
+
+  return {
+    total_recovery_events: totalRecoveryEvents,
+    by_domain: byDomain,
+    by_outcome: byOutcome,
+    timeline,
+    health_score: healthScore,
+  };
+}

package/src/lib/report.js

@@ -12,6 +12,7 @@ import {
 import { buildCoordinatorRepoStatusEntries } from './coordinator-repo-status-presentation.js';
 import { summarizeCoordinatorEvent } from './coordinator-event-narrative.js';
 import { extractGateActionDigest } from './gate-actions.js';
+import { buildRecoveryClassificationReport } from './recovery-classification.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
@@ -703,6 +704,19 @@ function extractRecoverySummary(artifact) {
   };
 }
 
+function extractRecoveryClassification(artifact) {
+  const report = buildRecoveryClassificationReport(extractRunEventTimeline(artifact));
+  return report.total_recovery_events > 0 ? report : null;
+}
+
+function formatRecoveryOutcomeCounts(counts) {
+  return `${counts.recovered} recovered, ${counts.exhausted} exhausted, ${counts.manual} manual, ${counts.pending} pending`;
+}
+
+function formatRecoveryDomainLabel(domain) {
+  return domain.charAt(0).toUpperCase() + domain.slice(1);
+}
+
 function extractCoordinatorTimeline(artifact) {
   const data = extractFileData(artifact, '.agentxchain/multirepo/history.jsonl');
   if (!Array.isArray(data) || data.length === 0) return [];
@@ -1008,6 +1022,7 @@ function buildRunSubject(artifact) {
   const gateSummary = extractGateSummary(artifact);
   const intakeLinks = extractIntakeLinks(artifact);
   const recoverySummary = extractRecoverySummary(artifact);
+  const recoveryClassification = extractRecoveryClassification(artifact);
   const nextActions = deriveGovernedRunNextActions(artifact.state, artifact.config);
   const continuity = extractContinuityMetadata(artifact);
   const governanceEvents = extractGovernanceEventDigest(artifact);
@@ -1057,6 +1072,7 @@ function buildRunSubject(artifact) {
       gate_summary: gateSummary,
       intake_links: intakeLinks,
       recovery_summary: recoverySummary,
+      recovery_classification: recoveryClassification,
       next_actions: nextActions,
       continuity,
       workflow_kit_artifacts: extractWorkflowKitArtifacts(artifact),
@@ -1539,6 +1555,26 @@ export function formatGovernanceReportText(report) {
       }
     }
 
+    if (run.recovery_classification) {
+      const rc = run.recovery_classification;
+      lines.push('', 'Recovery Classification:');
+      lines.push(`  Health: ${rc.health_score}`);
+      lines.push(`  Events: ${rc.total_recovery_events} total (${formatRecoveryOutcomeCounts(rc.by_outcome)})`);
+      lines.push('  By Domain:');
+      for (const [domain, counts] of Object.entries(rc.by_domain)) {
+        lines.push(`    ${formatRecoveryDomainLabel(domain)}: ${counts.total} (${formatRecoveryOutcomeCounts(counts)})`);
+      }
+      if (rc.timeline.length > 0) {
+        const { items: boundedRecoveryEvents, omitted: recoveryEventsOmitted } = boundedSlice(rc.timeline);
+        lines.push('  Timeline:');
+        for (let i = 0; i < boundedRecoveryEvents.length; i++) {
+          const evt = boundedRecoveryEvents[i];
+          lines.push(`    ${i + 1}. ${evt.timestamp || 'n/a'} | ${evt.domain} | ${evt.severity} | ${evt.outcome} | ${evt.mechanism} | ${evt.summary}`);
+        }
+        if (recoveryEventsOmitted > 0) lines.push(`    (${recoveryEventsOmitted} more recovery events omitted)`);
+      }
+    }
+
     if (run.next_actions && run.next_actions.length > 0) {
       lines.push('', 'Next Actions:');
       for (let i = 0; i < run.next_actions.length; i++) {
@@ -2137,6 +2173,27 @@ export function formatGovernanceReportMarkdown(report) {
       }
     }
 
+    if (run.recovery_classification) {
+      const rc = run.recovery_classification;
+      lines.push('', '## Recovery Classification', '');
+      lines.push(`- Health: \`${rc.health_score}\``);
+      lines.push(`- Events: ${rc.total_recovery_events} total (${formatRecoveryOutcomeCounts(rc.by_outcome)})`);
+      lines.push('', '| Domain | Total | Recovered | Exhausted | Manual | Pending |', '|--------|-------|-----------|-----------|--------|---------|');
+      for (const [domain, counts] of Object.entries(rc.by_domain)) {
+        lines.push(`| ${formatRecoveryDomainLabel(domain)} | ${counts.total} | ${counts.recovered} | ${counts.exhausted} | ${counts.manual} | ${counts.pending} |`);
+      }
+      if (rc.timeline.length > 0) {
+        const { items: boundedRecoveryEvents, omitted: recoveryEventsOmitted } = boundedSlice(rc.timeline);
+        lines.push('', '| # | Time | Domain | Severity | Outcome | Mechanism | Summary |', '|---|------|--------|----------|---------|-----------|---------|');
+        for (let i = 0; i < boundedRecoveryEvents.length; i++) {
+          const evt = boundedRecoveryEvents[i];
+          const summary = (evt.summary || '').replace(/\|/g, '\\|');
+          lines.push(`| ${i + 1} | \`${evt.timestamp || 'n/a'}\` | \`${evt.domain}\` | \`${evt.severity}\` | \`${evt.outcome}\` | \`${evt.mechanism}\` | ${summary} |`);
+        }
+        if (recoveryEventsOmitted > 0) lines.push('', `*(${recoveryEventsOmitted} more recovery events omitted)*`);
+      }
+    }
+
     if (run.next_actions && run.next_actions.length > 0) {
       lines.push('', '## Next Actions', '');
       for (let i = 0; i < run.next_actions.length; i++) {
@@ -2877,6 +2934,40 @@ function renderRunHtml(report) {
     sections.push(`<div class="section">${htmlSection('Recovery', recoveryHtml)}</div>`);
   }
 
+  if (run.recovery_classification) {
+    const rc = run.recovery_classification;
+    const domainRows = Object.entries(rc.by_domain).map(([domain, counts]) => [
+      esc(formatRecoveryDomainLabel(domain)),
+      String(counts.total),
+      String(counts.recovered),
+      String(counts.exhausted),
+      String(counts.manual),
+      String(counts.pending),
+    ]);
+    const { items: boundedRecoveryEvents, omitted: recoveryEventsOmitted } = boundedSlice(rc.timeline);
+    const timelineRows = boundedRecoveryEvents.map((evt, index) => [
+      String(index + 1),
+      `<code>${esc(evt.timestamp || 'n/a')}</code>`,
+      `<code>${esc(evt.domain)}</code>`,
+      `<code>${esc(evt.severity)}</code>`,
+      `<code>${esc(evt.outcome)}</code>`,
+      `<code>${esc(evt.mechanism)}</code>`,
+      esc(evt.summary || ''),
+    ]);
+    let classificationHtml = htmlDl([
+      ['Health', `<code>${esc(rc.health_score)}</code>`],
+      ['Events', `${rc.total_recovery_events} total (${esc(formatRecoveryOutcomeCounts(rc.by_outcome))})`],
+    ]);
+    classificationHtml += htmlSection('By Domain', htmlTable(['Domain', 'Total', 'Recovered', 'Exhausted', 'Manual', 'Pending'], domainRows), 3);
+    if (timelineRows.length > 0) {
+      classificationHtml += htmlSection('Timeline', htmlTable(['#', 'Time', 'Domain', 'Severity', 'Outcome', 'Mechanism', 'Summary'], timelineRows), 3);
+    }
+    if (recoveryEventsOmitted > 0) {
+      classificationHtml += `<p><em>(${recoveryEventsOmitted} more recovery events omitted)</em></p>`;
+    }
+    sections.push(`<div class="section">${htmlSection('Recovery Classification', classificationHtml)}</div>`);
+  }
+
   if (run.next_actions?.length > 0) {
     const nextHtml = '<ol>' + run.next_actions.map((action) =>
       `<li><code>${esc(action.command)}</code>: ${esc(action.reason)}</li>`

package/src/lib/run-events.js

@@ -8,6 +8,7 @@
 import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
+import { classifyRecoveryEvent } from './recovery-classification.js';
 
 export const RUN_EVENTS_PATH = '.agentxchain/events.jsonl';
 
@@ -72,6 +73,11 @@ export const VALID_RUN_EVENTS = [
  */
 export function emitRunEvent(root, eventType, details = {}) {
   const event_id = `evt_${randomBytes(8).toString('hex')}`;
+  const payload = details.payload || {};
+  const recoveryClassification = classifyRecoveryEvent({ event_type: eventType, payload });
+  const classifiedPayload = recoveryClassification && !payload.recovery_classification
+    ? { ...payload, recovery_classification: recoveryClassification }
+    : payload;
   const entry = {
     event_id,
     event_type: eventType,
@@ -81,7 +87,7 @@ export function emitRunEvent(root, eventType, details = {}) {
     status: details.status || null,
     turn: details.turn || null,
     intent_id: details.intent_id || null,
-    payload: details.payload || {},
+    payload: classifiedPayload,
   };
 
   try {

package/src/lib/schemas/agentxchain-config.schema.json

@@ -100,6 +100,11 @@
           "minimum": 1,
           "description": "Milliseconds to wait after dispatch for worker attach/first-output proof before retaining the turn as failed_start. Default 180000."
         },
+        "startup_heartbeat_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds between local_cli adapter startup keepalive diagnostics while a spawned subprocess is silent before first-output proof. Default 30000."
+        },
         "stale_turn_threshold_ms": {
           "type": "integer",
           "minimum": 1,
@@ -409,6 +414,11 @@
           "minimum": 1,
           "description": "Optional local_cli-specific override for the startup watchdog. When set, this runtime uses the declared threshold before falling back to run_loop.startup_watchdog_ms."
         },
+        "startup_heartbeat_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional local_cli-specific startup keepalive diagnostic interval. When set, this runtime uses the declared interval before falling back to run_loop.startup_heartbeat_ms."
+        },
         "prompt_transport": {
           "enum": ["argv", "stdin", "dispatch_bundle_only"]
         },

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 };
+}

package/src/lib/turn-checkpoint.js

@@ -201,14 +201,21 @@ function extractGitError(err) {
   return stderr || stdout || err?.message || 'git command failed';
 }
 
+function normalizeRuntimeId(entry) {
+  return typeof entry?.runtime_id === 'string' && entry.runtime_id.trim()
+    ? entry.runtime_id.trim()
+    : null;
+}
+
 function buildCheckpointCommit(entry) {
-  const subject = `checkpoint: ${entry.turn_id} (role=${entry.role}, phase=${entry.phase})`;
+  const runtimeId = normalizeRuntimeId(entry) || '(unknown)';
+  const subject = `checkpoint: ${entry.turn_id} (role=${entry.role}, phase=${entry.phase}, runtime=${runtimeId})`;
   const bodyLines = [
     `Summary: ${entry.summary || '(none)'}`,
     `Turn-ID: ${entry.turn_id}`,
     `Role: ${entry.role || '(unknown)'}`,
     `Phase: ${entry.phase || '(unknown)'}`,
-    `Runtime: ${entry.runtime_id || '(unknown)'}`,
+    `Runtime: ${runtimeId}`,
   ];
   if (entry.intent_id) bodyLines.push(`Intent-ID: ${entry.intent_id}`);
   if (entry.accepted_at) bodyLines.push(`Accepted-At: ${entry.accepted_at}`);
@@ -345,6 +352,27 @@ export function checkpointAcceptedTurn(root, opts = {}) {
   }
 
   const entry = resolved.entry;
+
+  // Proposed turns materialize their files under .agentxchain/proposed/<turn_id>/, never
+  // the workspace — there is nothing to `git add` until `proposal apply` promotes them.
+  // Attempting to stage the declared workspace paths fails with "pathspec did not match",
+  // so checkpoint cleanly skips proposed/patch turns.
+  if (
+    entry?.artifact
+    && typeof entry.artifact === 'object'
+    && !Array.isArray(entry.artifact)
+    && entry.artifact.type === 'patch'
+    && typeof entry.artifact.ref === 'string'
+    && entry.artifact.ref.startsWith('.agentxchain/proposed/')
+  ) {
+    return {
+      ok: true,
+      skipped: true,
+      turn: entry,
+      reason: 'Proposed turn materialized under .agentxchain/proposed/; no workspace checkpoint needed until proposal apply.',
+    };
+  }
+
   const supplementalFilesChanged = entry.checkpoint_sha
     ? recoverSupplementalCheckpointFiles(root, entry)
     : [];
@@ -450,6 +478,7 @@ export function checkpointAcceptedTurn(root, opts = {}) {
 
   const checkpointSha = git(root, ['rev-parse', 'HEAD']);
   const checkpointedAt = new Date().toISOString();
+  const runtimeId = normalizeRuntimeId(entry);
 
   const historyEntries = readHistoryEntries(root).map((historyEntry) => (
     historyEntry.turn_id === entry.turn_id
@@ -470,6 +499,7 @@ export function checkpointAcceptedTurn(root, opts = {}) {
         turn_id: entry.turn_id,
         role: entry.role || null,
         phase: entry.phase || null,
+        runtime_id: runtimeId,
         checkpoint_sha: checkpointSha,
         checkpointed_at: checkpointedAt,
         intent_id: entry.intent_id || null,
@@ -480,7 +510,7 @@ export function checkpointAcceptedTurn(root, opts = {}) {
       run_id: state.run_id || null,
       phase: state.phase || null,
       status: state.status || null,
-      turn: { turn_id: entry.turn_id, role_id: entry.role || null },
+      turn: { turn_id: entry.turn_id, role_id: entry.role || null, runtime_id: runtimeId },
       intent_id: entry.intent_id || null,
       payload: { checkpoint_sha: checkpointSha, checkpointed_at: checkpointedAt },
     });