agentxchain 2.137.0 → 2.138.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.137.0",
+  "version": "2.138.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
     "./runner-interface": "./src/lib/runner-interface.js",
     "./run-loop": "./src/lib/run-loop.js",
     "./schemas/agentxchain-config": "./src/lib/schemas/agentxchain-config.schema.json",
-    "./schemas/connector-capabilities-output": "./src/lib/schemas/connector-capabilities-output.schema.json"
+    "./schemas/connector-capabilities-output": "./src/lib/schemas/connector-capabilities-output.schema.json",
+    "./schemas/workflow-kit-output": "./src/lib/schemas/workflow-kit-output.schema.json"
   },
   "files": [
     "bin/",

package/src/commands/migrate-intents.js

@@ -1,9 +1,11 @@
 /**
- * One-shot repair command for legacy intents stuck with approved_run_id: null.
+ * One-shot repair command for legacy and phantom intents.
  *
- * Belt-and-suspenders insurance for BUG-41: the automatic startup migration
- * is now idempotent, but operators who already have stuck repos need a direct
- * lever that works without starting a governed run.
+ * Handles two classes of stuck intents:
+ * 1. Legacy (null-scoped): approved_run_id is null — pre-BUG-34 intents
+ * 2. Phantom: approved_run_id matches current run but planning artifacts
+ *    already exist on disk — would fail with "existing planning artifacts
+ *    would be overwritten" if dispatched (BUG-42)
  */
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
@@ -11,7 +13,10 @@ import { join } from 'node:path';
 import chalk from 'chalk';
 
 import { findProjectRoot } from '../lib/config.js';
-import { migratePreBug34Intents } from '../lib/intent-startup-migration.js';
+import { isPhantomIntent, migratePreBug34Intents } from '../lib/intent-startup-migration.js';
+import { safeWriteJson } from '../lib/safe-write.js';
+
+const MIGRATE_INTENTS_SCOPE = 'legacy_and_phantom';
 
 function loadRunId(root) {
   const statePath = join(root, '.agentxchain', 'state.json');
@@ -48,6 +53,112 @@ function listLegacyIntents(root) {
   return results;
 }
 
+function listRunScopedIntents(root) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  if (!existsSync(intentsDir)) return [];
+
+  const DISPATCHABLE = new Set(['planned', 'approved']);
+  const results = [];
+
+  for (const file of readdirSync(intentsDir)) {
+    if (!file.endsWith('.json') || file.startsWith('.tmp-')) continue;
+    const intentPath = join(intentsDir, file);
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!intent || !DISPATCHABLE.has(intent.status)) continue;
+    if (intent.cross_run_durable === true) continue;
+    if (!intent.approved_run_id) continue;
+    results.push({
+      file,
+      intent_id: intent.intent_id || file.replace('.json', ''),
+      status: intent.status,
+      approved_run_id: intent.approved_run_id,
+    });
+  }
+  return results;
+}
+
+function listPhantomIntents(root, runId) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  if (!existsSync(intentsDir)) return [];
+
+  const DISPATCHABLE = new Set(['planned', 'approved']);
+  const results = [];
+
+  for (const file of readdirSync(intentsDir)) {
+    if (!file.endsWith('.json') || file.startsWith('.tmp-')) continue;
+    const intentPath = join(intentsDir, file);
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!intent || !DISPATCHABLE.has(intent.status)) continue;
+    if (!intent.approved_run_id) continue;
+    // Only check intents bound to the current run — intents from other runs
+    // are a different reconciliation concern (stale cross-run archival).
+    if (runId && intent.approved_run_id !== runId) continue;
+    if (isPhantomIntent(root, intent)) {
+      results.push({
+        file,
+        intent_id: intent.intent_id || file.replace('.json', ''),
+        status: intent.status,
+        approved_run_id: intent.approved_run_id,
+      });
+    }
+  }
+  return results;
+}
+
+function supersedePhantomIntents(root, phantomIntents) {
+  const intentsDir = join(root, '.agentxchain', 'intake', 'intents');
+  const now = new Date().toISOString();
+  const supersededIds = [];
+
+  for (const phantom of phantomIntents) {
+    const intentPath = join(intentsDir, phantom.file);
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    const prevStatus = intent.status;
+    intent.status = 'superseded';
+    intent.updated_at = now;
+    intent.archived_reason = 'planning artifacts for this intent already exist on disk; intent superseded';
+    if (!intent.history) intent.history = [];
+    intent.history.push({
+      from: prevStatus,
+      to: 'superseded',
+      at: now,
+      reason: intent.archived_reason,
+    });
+    safeWriteJson(intentPath, intent);
+    supersededIds.push(phantom.intent_id);
+  }
+
+  return supersededIds;
+}
+
+function buildJsonResult({ archivedCount, archivedIntentIds, phantomCount, phantomIntentIds, dryRun, message }) {
+  return {
+    archived_count: archivedCount,
+    archived_intent_ids: archivedIntentIds,
+    phantom_superseded_count: phantomCount,
+    phantom_superseded_intent_ids: phantomIntentIds,
+    scope: MIGRATE_INTENTS_SCOPE,
+    dry_run: dryRun,
+    message,
+  };
+}
+
 export function migrateIntentsCommand(opts) {
   const root = findProjectRoot();
   if (!root) {
@@ -59,63 +170,105 @@ export function migrateIntentsCommand(opts) {
     process.exit(1);
   }
 
+  const runId = loadRunId(root);
   const legacyIntents = listLegacyIntents(root);
+  const phantomIntents = listPhantomIntents(root, runId);
+  const totalIssues = legacyIntents.length + phantomIntents.length;
 
   if (opts.dryRun) {
+    const msg = [];
+    if (legacyIntents.length > 0) msg.push(`Would archive ${legacyIntents.length} legacy intent(s)`);
+    if (phantomIntents.length > 0) msg.push(`Would supersede ${phantomIntents.length} phantom intent(s)`);
+    const message = msg.length > 0 ? msg.join('; ') : 'No legacy or phantom intents found';
+
     if (opts.json) {
-      console.log(JSON.stringify({
-        archived_count: legacyIntents.length,
-        archived_intent_ids: legacyIntents.map(i => i.intent_id),
-        dry_run: true,
-        message: legacyIntents.length > 0
-          ? `Would archive ${legacyIntents.length} pre-BUG-34 intent(s)`
-          : 'No legacy intents found',
-      }, null, 2));
+      console.log(JSON.stringify(buildJsonResult({
+        archivedCount: legacyIntents.length,
+        archivedIntentIds: legacyIntents.map((i) => i.intent_id),
+        phantomCount: phantomIntents.length,
+        phantomIntentIds: phantomIntents.map((i) => i.intent_id),
+        dryRun: true,
+        message,
+      }), null, 2));
     } else {
-      if (legacyIntents.length === 0) {
-        console.log(chalk.green('  No legacy intents found. Nothing to migrate.'));
+      if (totalIssues === 0) {
+        console.log(chalk.green('  No legacy or phantom intents found. Nothing to migrate.'));
       } else {
-        console.log(chalk.yellow(`  Would archive ${legacyIntents.length} legacy intent(s):`));
-        for (const item of legacyIntents) {
-          console.log(`    ${chalk.dim('•')} ${item.intent_id} (${item.status})`);
+        if (legacyIntents.length > 0) {
+          console.log(chalk.yellow(`  Would archive ${legacyIntents.length} legacy intent(s):`));
+          for (const item of legacyIntents) {
+            console.log(`    ${chalk.dim('•')} ${item.intent_id} (${item.status})`);
+          }
+        }
+        if (phantomIntents.length > 0) {
+          console.log(chalk.yellow(`  Would supersede ${phantomIntents.length} phantom intent(s) (planning artifacts already exist):`));
+          for (const item of phantomIntents) {
+            console.log(`    ${chalk.dim('•')} ${item.intent_id} (${item.status}, run=${item.approved_run_id})`);
+          }
         }
       }
     }
     return;
   }
 
-  if (legacyIntents.length === 0) {
+  if (totalIssues === 0) {
     if (opts.json) {
-      console.log(JSON.stringify({
-        archived_count: 0,
-        archived_intent_ids: [],
-        dry_run: false,
-        message: 'No legacy intents found',
-      }, null, 2));
+      console.log(JSON.stringify(buildJsonResult({
+        archivedCount: 0,
+        archivedIntentIds: [],
+        phantomCount: 0,
+        phantomIntentIds: [],
+        dryRun: false,
+        message: 'No legacy or phantom intents found',
+      }), null, 2));
     } else {
-      console.log(chalk.green('  No legacy intents found. Nothing to migrate.'));
+      console.log(chalk.green('  No legacy or phantom intents found. Nothing to migrate.'));
     }
     return;
   }
 
-  const runId = loadRunId(root);
-  const result = migratePreBug34Intents(root, runId);
+  // Archive legacy intents
+  const legacyResult = legacyIntents.length > 0
+    ? migratePreBug34Intents(root, runId)
+    : { archived_migration_count: 0, archived_migration_intent_ids: [], migration_notice: null };
+
+  // Supersede phantom intents
+  const phantomSupersededIds = phantomIntents.length > 0
+    ? supersedePhantomIntents(root, phantomIntents)
+    : [];
+
+  const messages = [];
+  if (legacyResult.archived_migration_count > 0) {
+    messages.push(legacyResult.migration_notice || `Archived ${legacyResult.archived_migration_count} legacy intent(s)`);
+  }
+  if (phantomSupersededIds.length > 0) {
+    messages.push(`Superseded ${phantomSupersededIds.length} phantom intent(s)`);
+  }
 
   if (opts.json) {
-    console.log(JSON.stringify({
-      archived_count: result.archived_migration_count,
-      archived_intent_ids: result.archived_migration_intent_ids,
-      dry_run: false,
-      message: result.migration_notice || `Archived ${result.archived_migration_count} pre-BUG-34 intent(s)`,
-    }, null, 2));
+    console.log(JSON.stringify(buildJsonResult({
+      archivedCount: legacyResult.archived_migration_count,
+      archivedIntentIds: legacyResult.archived_migration_intent_ids,
+      phantomCount: phantomSupersededIds.length,
+      phantomIntentIds: phantomSupersededIds,
+      dryRun: false,
+      message: messages.join('; ') || 'No legacy or phantom intents found',
+    }), null, 2));
   } else {
-    if (result.archived_migration_count === 0) {
-      console.log(chalk.green('  No legacy intents found. Nothing to migrate.'));
-    } else {
-      console.log(chalk.green(`  ✓ ${result.migration_notice}`));
-      for (const id of result.archived_migration_intent_ids) {
+    if (legacyResult.archived_migration_count > 0) {
+      console.log(chalk.green(`  ✓ ${legacyResult.migration_notice}`));
+      for (const id of legacyResult.archived_migration_intent_ids) {
         console.log(`    ${chalk.dim('•')} ${id}`);
       }
     }
+    if (phantomSupersededIds.length > 0) {
+      console.log(chalk.green(`  ✓ Superseded ${phantomSupersededIds.length} phantom intent(s)`));
+      for (const id of phantomSupersededIds) {
+        console.log(`    ${chalk.dim('•')} ${id}`);
+      }
+    }
+    if (legacyResult.archived_migration_count === 0 && phantomSupersededIds.length === 0) {
+      console.log(chalk.green('  No legacy or phantom intents found. Nothing to migrate.'));
+    }
   }
 }

package/src/commands/restart.js

@@ -329,6 +329,9 @@ export async function restartCommand(opts) {
     if (reactivated.migration_notice) {
       console.log(chalk.yellow(reactivated.migration_notice));
     }
+    if (reactivated.phantom_notice) {
+      console.log(chalk.yellow(reactivated.phantom_notice));
+    }
   }
 
   // Determine role from option or routing

package/src/commands/resume.js

@@ -147,6 +147,9 @@ export async function resumeCommand(opts) {
       if (reactivated.migration_notice) {
         console.log(chalk.yellow(reactivated.migration_notice));
       }
+      if (reactivated.phantom_notice) {
+        console.log(chalk.yellow(reactivated.phantom_notice));
+      }
 
       // Write dispatch bundle for the existing turn
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -210,6 +213,9 @@ export async function resumeCommand(opts) {
     if (reactivated.migration_notice) {
       console.log(chalk.yellow(reactivated.migration_notice));
     }
+    if (reactivated.phantom_notice) {
+      console.log(chalk.yellow(reactivated.phantom_notice));
+    }
 
     const bundleResult = writeDispatchBundle(root, state, config, { turnId: retainedTurn.turn_id });
     if (!bundleResult.ok) {
@@ -242,6 +248,9 @@ export async function resumeCommand(opts) {
     if (initResult.migration_notice) {
       console.log(chalk.yellow(initResult.migration_notice));
     }
+    if (initResult.phantom_notice) {
+      console.log(chalk.yellow(initResult.phantom_notice));
+    }
   }
 
   // §47: paused + run_id exists → resume same run
@@ -256,6 +265,9 @@ export async function resumeCommand(opts) {
     if (reactivated.migration_notice) {
       console.log(chalk.yellow(reactivated.migration_notice));
     }
+    if (reactivated.phantom_notice) {
+      console.log(chalk.yellow(reactivated.phantom_notice));
+    }
   }
 
   // §47: paused + run_id exists → resume same run
@@ -270,6 +282,9 @@ export async function resumeCommand(opts) {
     if (reactivated.migration_notice) {
       console.log(chalk.yellow(reactivated.migration_notice));
     }
+    if (reactivated.phantom_notice) {
+      console.log(chalk.yellow(reactivated.phantom_notice));
+    }
   }
 
   // Print run-context header before dispatch

package/src/commands/step.js

@@ -263,6 +263,9 @@ export async function stepCommand(opts) {
         if (reactivated.migration_notice) {
           console.log(chalk.yellow(reactivated.migration_notice));
         }
+        if (reactivated.phantom_notice) {
+          console.log(chalk.yellow(reactivated.phantom_notice));
+        }
         skipAssignment = true;
 
         // BUG-1 fix: refresh baseline snapshot to capture files dirtied between assignment and dispatch
@@ -291,6 +294,9 @@ export async function stepCommand(opts) {
       if (initResult.migration_notice) {
         console.log(chalk.yellow(initResult.migration_notice));
       }
+      if (initResult.phantom_notice) {
+        console.log(chalk.yellow(initResult.phantom_notice));
+      }
     }
 
     // paused → resume
@@ -305,6 +311,9 @@ export async function stepCommand(opts) {
       if (reactivated.migration_notice) {
         console.log(chalk.yellow(reactivated.migration_notice));
       }
+      if (reactivated.phantom_notice) {
+        console.log(chalk.yellow(reactivated.phantom_notice));
+      }
     }
 
     if (!skipAssignment && state.status === 'paused' && state.run_id) {
@@ -318,6 +327,9 @@ export async function stepCommand(opts) {
       if (reactivated.migration_notice) {
         console.log(chalk.yellow(reactivated.migration_notice));
       }
+      if (reactivated.phantom_notice) {
+        console.log(chalk.yellow(reactivated.phantom_notice));
+      }
     }
 
     // Assign the turn

package/src/lib/continuous-run.js

@@ -28,6 +28,7 @@ import { emitRunEvent } from './run-events.js';
 import {
   archiveStaleIntentsForRun,
   formatLegacyIntentMigrationNotice,
+  formatPhantomIntentSupersessionNotice,
 } from './intent-startup-migration.js';
 
 const CONTINUOUS_SESSION_PATH = '.agentxchain/continuous-session.json';
@@ -172,6 +173,20 @@ function reconcileContinuousStartupState(context, session, contOpts, log) {
       const migrationNotice = formatLegacyIntentMigrationNotice(startupIntents.archived_migration_intent_ids);
       if (migrationNotice) log(migrationNotice);
     }
+    if (startupIntents.phantom_superseded_intent_ids?.length > 0) {
+      emitRunEvent(root, 'intents_superseded', {
+        run_id: scopedRunId,
+        phase: governedState?.phase || null,
+        status: governedState?.status || 'active',
+        payload: {
+          superseded_count: startupIntents.phantom_superseded_intent_ids.length,
+          superseded_intent_ids: startupIntents.phantom_superseded_intent_ids,
+          reason: 'approved intents already satisfied by on-disk planning artifacts superseded during continuous startup',
+        },
+      });
+      const phantomNotice = formatPhantomIntentSupersessionNotice(startupIntents.phantom_superseded_intent_ids);
+      if (phantomNotice) log(phantomNotice);
+    }
     if (session.startup_reconciled_run_id !== scopedRunId) {
       session.startup_reconciled_run_id = scopedRunId;
       sessionChanged = true;

package/src/lib/governed-state.js

@@ -49,6 +49,7 @@ import { buildDefaultRunProvenance } from './run-provenance.js';
 import {
   archiveStaleIntentsForRun,
   formatLegacyIntentMigrationNotice,
+  formatPhantomIntentSupersessionNotice,
 } from './intent-startup-migration.js';
 import {
   ensureHumanEscalation,
@@ -2098,6 +2099,18 @@ export function reactivateGovernedRun(root, state, details = {}) {
       },
     });
   }
+  if (startupIntents.phantom_superseded_intent_ids?.length > 0) {
+    emitRunEvent(root, 'intents_superseded', {
+      run_id: nextState.run_id,
+      phase: nextState.phase,
+      status: nextState.status,
+      payload: {
+        superseded_count: startupIntents.phantom_superseded_intent_ids.length,
+        superseded_intent_ids: startupIntents.phantom_superseded_intent_ids,
+        reason: 'approved intents already satisfied by on-disk planning artifacts superseded during run reactivation',
+      },
+    });
+  }
 
   if (humanEscalation) {
     resolveHumanEscalation(root, humanEscalation.escalation_id, {
@@ -2144,6 +2157,7 @@ export function reactivateGovernedRun(root, state, details = {}) {
     ok: true,
     state: attachLegacyCurrentTurnAlias(nextState),
     migration_notice: formatLegacyIntentMigrationNotice(startupIntents.archived_migration_intent_ids),
+    phantom_notice: formatPhantomIntentSupersessionNotice(startupIntents.phantom_superseded_intent_ids),
   };
 }
 
@@ -2216,6 +2230,18 @@ export function initializeGovernedRun(root, config, options = {}) {
       },
     });
   }
+  if (startupIntents.phantom_superseded_intent_ids?.length > 0) {
+    emitRunEvent(root, 'intents_superseded', {
+      run_id: runId,
+      phase: updatedState.phase,
+      status: 'active',
+      payload: {
+        superseded_count: startupIntents.phantom_superseded_intent_ids.length,
+        superseded_intent_ids: startupIntents.phantom_superseded_intent_ids,
+        reason: 'approved intents already satisfied by on-disk planning artifacts superseded during run initialization',
+      },
+    });
+  }
 
   emitRunEvent(root, 'run_started', {
     run_id: runId,
@@ -2225,8 +2251,14 @@ export function initializeGovernedRun(root, config, options = {}) {
   });
   // BUG-39: return migration notice so callers can display it
   const migrationNotice = startupIntents.migration_notice;
+  const phantomNotice = formatPhantomIntentSupersessionNotice(startupIntents.phantom_superseded_intent_ids);
 
-  return { ok: true, state: attachLegacyCurrentTurnAlias(updatedState), migration_notice: migrationNotice };
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(updatedState),
+    migration_notice: migrationNotice,
+    phantom_notice: phantomNotice,
+  };
 }
 
 /**

package/src/lib/intent-startup-migration.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { safeWriteJson } from './safe-write.js';
+import { VALID_GOVERNED_TEMPLATE_IDS, loadGovernedTemplate } from './governed-templates.js';
 
 const DISPATCHABLE_STATUSES = new Set(['planned', 'approved']);
 
@@ -18,11 +19,60 @@ function listIntentFiles(intentsDir) {
   return readdirSync(intentsDir).filter((file) => file.endsWith('.json') && !file.startsWith('.tmp-'));
 }
 
+function normalizeArtifactPaths(paths) {
+  return [...new Set(
+    (Array.isArray(paths) ? paths : [])
+      .filter((value) => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter(Boolean),
+  )];
+}
+
+function readPlanningGateFiles(root) {
+  const configPath = join(root, 'agentxchain.json');
+  if (!existsSync(configPath)) return [];
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return [];
+  }
+
+  // Only use planning gate requires_files for phantom detection when:
+  // 1. The planning gate has NOT been passed yet (once passed, these files
+  //    are expected to exist from normal planning work), AND
+  // 2. At least one turn has been completed (turn_sequence > 0). If no turns
+  //    have been completed, the files are scaffolding templates, not evidence
+  //    of completed planning work. Without this check, ANY approved intent
+  //    in a freshly scaffolded project would be falsely detected as phantom.
+  const statePath = join(root, '.agentxchain', 'state.json');
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    const gateStatus = state.phase_gate_status || {};
+    const exitGateId = config?.routing?.planning?.exit_gate;
+    if (exitGateId && gateStatus[exitGateId] === 'passed') return [];
+    const turnSequence = state.turn_sequence || 0;
+    if (turnSequence === 0) return [];
+  } catch {
+    // If state is unreadable, fall through to check gate files
+  }
+
+  const exitGateId = config?.routing?.planning?.exit_gate;
+  const requiresFiles = exitGateId ? config?.gates?.[exitGateId]?.requires_files : null;
+  return normalizeArtifactPaths(requiresFiles);
+}
+
 export function formatLegacyIntentMigrationNotice(intentIds) {
   if (!Array.isArray(intentIds) || intentIds.length === 0) return null;
   return `Archived ${intentIds.length} pre-BUG-34 intent(s): ${intentIds.join(', ')}`;
 }
 
+export function formatPhantomIntentSupersessionNotice(intentIds) {
+  if (!Array.isArray(intentIds) || intentIds.length === 0) return null;
+  return `Superseded ${intentIds.length} phantom intent(s): ${intentIds.join(', ')}`;
+}
+
 export function migratePreBug34Intents(root, runId, options = {}) {
   const intentsDir = getIntentsDir(root);
   if (!existsSync(intentsDir)) {
@@ -30,6 +80,7 @@ export function migratePreBug34Intents(root, runId, options = {}) {
       archived_migration_count: 0,
       archived_migration_intent_ids: [],
       migration_notice: null,
+      phantom_supersession_notice: null,
     };
   }
 
@@ -72,12 +123,50 @@ export function migratePreBug34Intents(root, runId, options = {}) {
   };
 }
 
+/**
+ * BUG-42: Detect phantom intents — approved intents bound to the current run
+ * whose planning artifacts already exist on disk. These intents would fail with
+ * "existing planning artifacts would be overwritten" if dispatched.
+ */
+export function listExpectedPlanningArtifacts(root, intent) {
+  const recordedArtifacts = normalizeArtifactPaths(intent?.planning_artifacts);
+  let templateArtifacts = [];
+
+  if (intent?.template) {
+    try {
+      const manifest = loadGovernedTemplate(intent.template);
+      templateArtifacts = normalizeArtifactPaths(
+        (manifest.planning_artifacts || []).map((artifact) => `.planning/${artifact.filename}`),
+      );
+    } catch {
+      // Best-effort: unknown/broken template should not crash startup reconciliation.
+    }
+  }
+
+  return normalizeArtifactPaths([
+    ...recordedArtifacts,
+    ...templateArtifacts,
+    ...readPlanningGateFiles(root),
+  ]);
+}
+
+export function isPhantomIntent(root, intent) {
+  if (intent.status !== 'approved') return false;
+  const artifacts = listExpectedPlanningArtifacts(root, intent);
+  if (artifacts.length === 0) return false;
+
+  return artifacts.some((artifact) => existsSync(join(root, artifact)));
+}
+
 export function archiveStaleIntentsForRun(root, runId, options = {}) {
   const intentsDir = getIntentsDir(root);
   if (!existsSync(intentsDir)) {
     return {
       archived: 0,
       adopted: 0,
+      phantom_superseded: 0,
+      phantom_superseded_intent_ids: [],
+      phantom_supersession_notice: null,
       archived_migration_count: 0,
       archived_migration_intent_ids: [],
       migration_notice: null,
@@ -87,6 +176,8 @@ export function archiveStaleIntentsForRun(root, runId, options = {}) {
   const now = nowISO();
   let archived = 0;
   let adopted = 0;
+  let phantomSuperseded = 0;
+  const phantomSupersededIntentIds = [];
 
   for (const file of listIntentFiles(intentsDir)) {
     const intentPath = join(intentsDir, file);
@@ -136,6 +227,28 @@ export function archiveStaleIntentsForRun(root, runId, options = {}) {
       });
       safeWriteJson(intentPath, intent);
       archived += 1;
+      continue;
+    }
+
+    // BUG-42: Detect phantom intents — approved intents bound to the current
+    // run whose planning artifacts already exist on disk. These would fail with
+    // "existing planning artifacts would be overwritten" if dispatched.
+    if (intent.approved_run_id === runId && isPhantomIntent(root, intent)) {
+      const prevStatus = intent.status;
+      intent.status = 'superseded';
+      intent.updated_at = now;
+      intent.archived_reason = 'planning artifacts for this intent already exist on disk; intent superseded';
+      if (!intent.history) intent.history = [];
+      intent.history.push({
+        from: prevStatus,
+        to: 'superseded',
+        at: now,
+        reason: intent.archived_reason,
+      });
+      safeWriteJson(intentPath, intent);
+      phantomSuperseded += 1;
+      if (intent.intent_id) phantomSupersededIntentIds.push(intent.intent_id);
+      continue;
     }
   }
 
@@ -144,6 +257,9 @@ export function archiveStaleIntentsForRun(root, runId, options = {}) {
   return {
     archived,
     adopted,
+    phantom_superseded: phantomSuperseded,
+    phantom_superseded_intent_ids: phantomSupersededIntentIds,
+    phantom_supersession_notice: formatPhantomIntentSupersessionNotice(phantomSupersededIntentIds),
     archived_migration_count: migration.archived_migration_count,
     archived_migration_intent_ids: migration.archived_migration_intent_ids,
     migration_notice: migration.migration_notice,

package/src/lib/recent-event-summary.js

@@ -56,6 +56,13 @@ function describeEvent(eventType, entry) {
       return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
     case 'dispatch_progress':
       return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'intents_migrated':
+    case 'intents_superseded': {
+      const count = Number.isFinite(entry.payload?.archived_count)
+        ? entry.payload.archived_count
+        : (Number.isFinite(entry.payload?.superseded_count) ? entry.payload.superseded_count : null);
+      return `${prefix}${eventType}${count !== null ? ` (${count})` : ''}`;
+    }
     case 'run_blocked':
     case 'run_completed':
     case 'run_started':

package/src/lib/run-events.js

@@ -14,6 +14,8 @@ export const RUN_EVENTS_PATH = '.agentxchain/events.jsonl';
 export const VALID_RUN_EVENTS = [
   'run_started',
   'phase_entered',
+  'intents_migrated',
+  'intents_superseded',
   'turn_dispatched',
   'turn_accepted',
   'turn_rejected',

package/src/lib/schemas/workflow-kit-output.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentxchain.dev/schemas/workflow-kit-output.schema.json",
+  "title": "AgentXchain Workflow Kit Output",
+  "description": "Output schema for `workflow-kit describe --json`. Describes the workflow kit contract including phase templates, artifacts, semantic validators, and gate artifact coverage.",
+  "type": "object",
+  "required": [
+    "workflow_kit_version",
+    "source",
+    "phase_templates",
+    "phases",
+    "semantic_validators",
+    "gate_artifact_coverage"
+  ],
+  "properties": {
+    "workflow_kit_version": {
+      "type": "string",
+      "description": "Workflow kit contract version."
+    },
+    "source": {
+      "$ref": "#/$defs/kit_source",
+      "description": "How the workflow kit was derived: default (inferred from phase names), explicit (user-defined), or mixed."
+    },
+    "phase_templates": {
+      "$ref": "#/$defs/phase_templates",
+      "description": "Available and in-use phase templates."
+    },
+    "phases": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/phase_contract"
+      },
+      "description": "Per-phase workflow kit contract keyed by phase ID."
+    },
+    "semantic_validators": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of semantic validator IDs available in this workflow kit."
+    },
+    "gate_artifact_coverage": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/gate_coverage"
+      },
+      "description": "Per-gate artifact coverage mapping keyed by gate ID."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "kit_source": {
+      "enum": ["default", "explicit", "mixed"]
+    },
+    "phase_source": {
+      "enum": ["default", "explicit", "not_declared"]
+    },
+    "phase_templates": {
+      "type": "object",
+      "required": ["available", "in_use"],
+      "properties": {
+        "available": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "All valid workflow-kit phase template IDs."
+        },
+        "in_use": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Template IDs currently applied to phases."
+        }
+      },
+      "additionalProperties": false
+    },
+    "artifact": {
+      "type": "object",
+      "required": ["path", "required", "semantics", "exists"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Relative path to the workflow artifact."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether the artifact is required for phase completion."
+        },
+        "semantics": {
+          "type": ["string", "null"],
+          "description": "Semantic validator ID, or null if no validator applies."
+        },
+        "exists": {
+          "type": "boolean",
+          "description": "Whether the artifact exists on disk at introspection time."
+        }
+      },
+      "additionalProperties": false
+    },
+    "phase_contract": {
+      "type": "object",
+      "required": ["template", "source", "artifacts"],
+      "properties": {
+        "template": {
+          "type": ["string", "null"],
+          "description": "Phase template ID, or null if no template applies."
+        },
+        "source": {
+          "$ref": "#/$defs/phase_source",
+          "description": "How this phase was configured."
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/artifact" },
+          "description": "Workflow artifacts for this phase."
+        }
+      },
+      "additionalProperties": false
+    },
+    "gate_coverage": {
+      "type": "object",
+      "required": ["linked_phases", "predicates_referencing_artifacts", "artifacts_covered"],
+      "properties": {
+        "linked_phases": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Phase IDs linked to this gate via routing or explicit annotation."
+        },
+        "predicates_referencing_artifacts": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of artifact predicates this gate evaluates."
+        },
+        "artifacts_covered": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Artifact paths this gate references."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/lib/turn-checkpoint.js

@@ -52,12 +52,24 @@ function isGitRepo(root) {
   }
 }
 
+// BUG-43: Staging and dispatch dirs are ephemeral — cleaned up after acceptance.
+// They must never appear in checkpoint git-add paths.
+const EPHEMERAL_PATH_PREFIXES = [
+  '.agentxchain/staging/',
+  '.agentxchain/dispatch/',
+];
+
+function isEphemeralPath(filePath) {
+  return EPHEMERAL_PATH_PREFIXES.some((prefix) => filePath.startsWith(prefix));
+}
+
 function normalizeFilesChanged(filesChanged) {
   return [...new Set(
     (Array.isArray(filesChanged) ? filesChanged : [])
       .filter((value) => typeof value === 'string')
       .map((value) => value.trim())
-      .filter(Boolean),
+      .filter(Boolean)
+      .filter((value) => !isEphemeralPath(value)),
   )];
 }