agentxchain 2.135.1 → 2.136.0

package/src/lib/intake.js

@@ -17,6 +17,11 @@ import { getDispatchTurnDir } from './turn-paths.js';
 import { loadCoordinatorConfig } from './coordinator-config.js';
 import { loadCoordinatorState, readBarriers } from './coordinator-state.js';
 import { writeCoordinatorHandoff } from './intake-handoff.js';
+import {
+  archiveStaleIntentsForRun,
+  migratePreBug34Intents,
+  formatLegacyIntentMigrationNotice,
+} from './intent-startup-migration.js';
 
 const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan'];
 const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
@@ -516,16 +521,14 @@ export function findNextDispatchableIntent(root, options = {}) {
     .filter((intent) => intent && DISPATCHABLE_STATUSES.has(intent.status));
 
   // BUG-34: when run_id scoping is active, filter out intents that belong to
-  // a different run. An intent belongs to the current run if:
-  //   (a) it has approved_run_id matching the current run, OR
-  //   (b) it has no approved_run_id AND is marked cross_run_durable, OR
-  //   (c) it was injected in the current run (approved_run_id matches)
-  // Legacy intents (no approved_run_id, no cross_run_durable) are excluded
-  // because they are stale leftovers from prior runs.
+  // a different run. `cross_run_durable` is only a pre-run holding state for
+  // freshly approved idle intents. Once a run starts, those intents must be
+  // rebound onto that run and the flag cleared; it must never override an
+  // existing run binding.
   if (scopeRunId) {
     intents = intents.filter((intent) => {
       if (intent.approved_run_id === scopeRunId) return true;
-      if (intent.cross_run_durable === true) return true;
+      if (!intent.approved_run_id && intent.cross_run_durable === true) return true;
       // Legacy intent with no run binding — stale, skip it
       if (!intent.approved_run_id) return false;
       // Intent bound to a different run — stale, skip it
@@ -579,10 +582,11 @@ export function findPendingApprovedIntents(root, options = {}) {
   return readJsonDir(dirs.intents)
     .filter((intent) => {
       if (!intent || intent.status !== 'approved') return false;
-      // BUG-34: run_id scoping — same logic as findNextDispatchableIntent
+      // BUG-34: run_id scoping — same logic as findNextDispatchableIntent.
+      // `cross_run_durable` only applies before the first run binding exists.
       if (scopeRunId) {
         if (intent.approved_run_id === scopeRunId) return true;
-        if (intent.cross_run_durable === true) return true;
+        if (!intent.approved_run_id && intent.cross_run_durable === true) return true;
         return false;
       }
       return true;
@@ -616,51 +620,7 @@ export function findPendingApprovedIntents(root, options = {}) {
  * @returns {{ archived: number }}
  */
 export function archiveStaleIntents(root, newRunId) {
-  const dirs = intakeDirs(root);
-  if (!existsSync(dirs.intents)) return { archived: 0, adopted: 0 };
-
-  const now = nowISO();
-  let archived = 0;
-  let adopted = 0;
-
-  const files = readdirSync(dirs.intents).filter(f => f.endsWith('.json') && !f.startsWith('.tmp-'));
-  for (const file of files) {
-    const intentPath = join(dirs.intents, file);
-    let intent;
-    try {
-      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
-    } catch {
-      continue;
-    }
-
-    if (!intent || !DISPATCHABLE_STATUSES.has(intent.status)) continue;
-    if (intent.cross_run_durable === true) continue;
-    if (intent.approved_run_id === newRunId) continue;
-
-    if (intent.approved_run_id && intent.approved_run_id !== newRunId) {
-      // Intent from a different run — archive it
-      intent.status = 'suppressed';
-      intent.updated_at = now;
-      intent.archived_reason = `stale: approved under run ${intent.approved_run_id}, archived on run ${newRunId} initialization`;
-      if (!intent.history) intent.history = [];
-      intent.history.push({ from: 'approved', to: 'suppressed', at: now, reason: intent.archived_reason });
-      safeWriteJson(intentPath, intent);
-      archived++;
-    } else if (!intent.approved_run_id) {
-      // BUG-39: pre-BUG-34 legacy intent with no run binding — archive it
-      // with explicit migration reason. Do NOT adopt into current run.
-      const prevStatus = intent.status;
-      intent.status = 'archived_migration';
-      intent.updated_at = now;
-      intent.archived_reason = `pre-BUG-34 intent with no run scope; archived during migration on run ${newRunId}`;
-      if (!intent.history) intent.history = [];
-      intent.history.push({ from: prevStatus, to: 'archived_migration', at: now, reason: intent.archived_reason });
-      safeWriteJson(intentPath, intent);
-      archived++;
-    }
-  }
-
-  return { archived, adopted };
+  return archiveStaleIntentsForRun(root, newRunId);
 }
 
 /**
@@ -823,9 +783,9 @@ export function approveIntent(root, intentId, options = {}) {
 
   // BUG-34/39: stamp the current run_id on approval so the intent is scoped
   // to the run that approved it. When approval happens before any governed
-  // run exists, mark the intent as cross_run_durable so the next run init
-  // preserves this freshly approved work instead of archiving it as legacy
-  // migration debt.
+  // run exists, hold the intent in a pre-run durable state so the *next* run
+  // initialization can bind it to that run. The flag is not an evergreen
+  // cross-run bypass; it exists only until first run binding happens.
   if (!intent.approved_run_id) {
     const statePath = join(root, '.agentxchain', 'state.json');
     if (existsSync(statePath)) {

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

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { safeWriteJson } from './safe-write.js';
+
+const DISPATCHABLE_STATUSES = new Set(['planned', 'approved']);
+
+function nowISO() {
+  return new Date().toISOString();
+}
+
+function getIntentsDir(root) {
+  return join(root, '.agentxchain', 'intake', 'intents');
+}
+
+function listIntentFiles(intentsDir) {
+  if (!existsSync(intentsDir)) return [];
+  return readdirSync(intentsDir).filter((file) => file.endsWith('.json') && !file.startsWith('.tmp-'));
+}
+
+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 migratePreBug34Intents(root, runId, options = {}) {
+  const intentsDir = getIntentsDir(root);
+  if (!existsSync(intentsDir)) {
+    return {
+      archived_migration_count: 0,
+      archived_migration_intent_ids: [],
+      migration_notice: null,
+    };
+  }
+
+  const now = nowISO();
+  const archivedMigrationIntentIds = [];
+  const protocolVersion = options.protocolVersion || '2.x';
+
+  for (const file of listIntentFiles(intentsDir)) {
+    const intentPath = join(intentsDir, file);
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!intent || !DISPATCHABLE_STATUSES.has(intent.status)) continue;
+    if (intent.cross_run_durable === true) continue;
+    if (intent.approved_run_id) continue;
+
+    const prevStatus = intent.status;
+    intent.status = 'archived_migration';
+    intent.updated_at = now;
+    intent.archived_reason = `pre-BUG-34 intent with no run scope; archived during v${protocolVersion} migration on run ${runId}`;
+    if (!intent.history) intent.history = [];
+    intent.history.push({
+      from: prevStatus,
+      to: 'archived_migration',
+      at: now,
+      reason: intent.archived_reason,
+    });
+    safeWriteJson(intentPath, intent);
+    if (intent.intent_id) archivedMigrationIntentIds.push(intent.intent_id);
+  }
+
+  return {
+    archived_migration_count: archivedMigrationIntentIds.length,
+    archived_migration_intent_ids: archivedMigrationIntentIds,
+    migration_notice: formatLegacyIntentMigrationNotice(archivedMigrationIntentIds),
+  };
+}
+
+export function archiveStaleIntentsForRun(root, runId, options = {}) {
+  const intentsDir = getIntentsDir(root);
+  if (!existsSync(intentsDir)) {
+    return {
+      archived: 0,
+      adopted: 0,
+      archived_migration_count: 0,
+      archived_migration_intent_ids: [],
+      migration_notice: null,
+    };
+  }
+
+  const now = nowISO();
+  let archived = 0;
+  let adopted = 0;
+
+  for (const file of listIntentFiles(intentsDir)) {
+    const intentPath = join(intentsDir, file);
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!intent || !DISPATCHABLE_STATUSES.has(intent.status)) continue;
+
+    if (intent.cross_run_durable === true && !intent.approved_run_id) {
+      intent.approved_run_id = runId;
+      delete intent.cross_run_durable;
+      intent.updated_at = now;
+      if (!intent.history) intent.history = [];
+      intent.history.push({
+        from: intent.status,
+        to: intent.status,
+        at: now,
+        reason: `pre-run durable approval bound to run ${runId}`,
+      });
+      safeWriteJson(intentPath, intent);
+      adopted += 1;
+      continue;
+    }
+
+    if (intent.cross_run_durable === true && intent.approved_run_id === runId) {
+      delete intent.cross_run_durable;
+      intent.updated_at = now;
+      safeWriteJson(intentPath, intent);
+      continue;
+    }
+
+    if (intent.approved_run_id && intent.approved_run_id !== runId) {
+      const prevStatus = intent.status;
+      intent.status = 'suppressed';
+      intent.updated_at = now;
+      intent.archived_reason = `stale: approved under run ${intent.approved_run_id}, archived on run ${runId} initialization`;
+      if (!intent.history) intent.history = [];
+      intent.history.push({
+        from: prevStatus,
+        to: 'suppressed',
+        at: now,
+        reason: intent.archived_reason,
+      });
+      safeWriteJson(intentPath, intent);
+      archived += 1;
+    }
+  }
+
+  const migration = migratePreBug34Intents(root, runId, options);
+
+  return {
+    archived,
+    adopted,
+    archived_migration_count: migration.archived_migration_count,
+    archived_migration_intent_ids: migration.archived_migration_intent_ids,
+    migration_notice: migration.migration_notice,
+  };
+}

package/src/lib/runtime-capabilities.js

@@ -4,10 +4,28 @@ function normalizeMcpTransport(runtime) {
     : 'stdio';
 }
 
+const DECLARABLE_CAPABILITY_FIELDS = new Set([
+  'can_write_files',
+  'proposal_support',
+  'workflow_artifact_ownership',
+]);
+
+function mergeExplicitCapabilities(base, runtime) {
+  const declared = runtime?.capabilities;
+  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return base;
+  const merged = { ...base };
+  for (const field of DECLARABLE_CAPABILITY_FIELDS) {
+    if (typeof declared[field] === 'string' && declared[field].length > 0) {
+      merged[field] = declared[field];
+    }
+  }
+  return merged;
+}
+
 export function getRuntimeCapabilityContract(runtime = {}) {
   switch (runtime?.type) {
     case 'manual':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'manual',
         transport: 'manual',
         can_write_files: 'direct',
@@ -15,10 +33,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'none',
         requires_local_binary: false,
         workflow_artifact_ownership: 'yes',
-      };
+      }, runtime);
 
     case 'local_cli':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'local_cli',
         transport: 'local_cli',
         can_write_files: 'direct',
@@ -26,10 +44,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'optional',
         requires_local_binary: true,
         workflow_artifact_ownership: 'yes',
-      };
+      }, runtime);
 
     case 'api_proxy':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'api_proxy',
         transport: 'provider_api',
         can_write_files: 'proposal_only',
@@ -37,10 +55,10 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'native',
         requires_local_binary: false,
         workflow_artifact_ownership: 'proposal_apply_required',
-      };
+      }, runtime);
 
     case 'remote_agent':
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'remote_agent',
         transport: 'remote_http',
         can_write_files: 'proposal_only',
@@ -48,13 +66,13 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'native',
         requires_local_binary: false,
         workflow_artifact_ownership: 'proposal_apply_required',
-      };
+      }, runtime);
 
     case 'mcp': {
       const transport = normalizeMcpTransport(runtime) === 'streamable_http'
         ? 'mcp_streamable_http'
         : 'mcp_stdio';
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: 'mcp',
         transport,
         can_write_files: 'tool_defined',
@@ -62,11 +80,11 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'tool_defined',
         requires_local_binary: transport === 'mcp_stdio',
         workflow_artifact_ownership: 'tool_defined',
-      };
+      }, runtime);
     }
 
     default:
-      return {
+      return mergeExplicitCapabilities({
         runtime_type: runtime?.type || 'unknown',
         transport: 'unknown',
         can_write_files: 'unknown',
@@ -74,7 +92,7 @@ export function getRuntimeCapabilityContract(runtime = {}) {
         proposal_support: 'unknown',
         requires_local_binary: false,
         workflow_artifact_ownership: 'unknown',
-      };
+      }, runtime);
   }
 }
 
@@ -91,79 +109,69 @@ export function getRoleRuntimeCapabilityContract(roleId, role = {}, runtime = {}
   let workflowArtifactOwnership = 'unknown';
 
   if (authority === 'review_only') {
-    switch (runtime?.type) {
-      case 'manual':
-        effectiveWritePath = 'planning_only';
-        workflowArtifactOwnership = 'yes';
-        appendNote(notes, 'Manual review roles can satisfy workflow-kit ownership for planning artifacts.');
-        break;
-      case 'local_cli':
-        effectiveWritePath = 'invalid_review_only_binding';
-        workflowArtifactOwnership = 'invalid';
-        appendNote(notes, 'review_only + local_cli is invalid because local_cli exposes direct repo writes.');
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'review_artifact_only';
-        workflowArtifactOwnership = 'no';
-        appendNote(notes, 'Review-only remote turns can attest and produce review artifacts, not workflow-kit files.');
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP review-only file production depends on the configured tool, not runtime type alone.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (runtime?.type === 'manual') {
+      effectiveWritePath = 'planning_only';
+      workflowArtifactOwnership = 'yes';
+      appendNote(notes, 'Manual review roles can satisfy workflow-kit ownership for planning artifacts.');
+    } else if (base.can_write_files === 'direct' && runtime?.type === 'local_cli') {
+      effectiveWritePath = 'invalid_review_only_binding';
+      workflowArtifactOwnership = 'invalid';
+      appendNote(notes, 'review_only + local_cli is invalid because local_cli exposes direct repo writes.');
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Review-only file production depends on the configured tool contract, not runtime type alone.');
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'review_artifact_only';
+      workflowArtifactOwnership = 'no';
+      appendNote(notes, 'Review-only remote turns can attest and produce review artifacts, not workflow-kit files.');
+    } else if (base.can_write_files === 'direct') {
+      effectiveWritePath = base.workflow_artifact_ownership === 'yes' ? 'planning_only' : 'review_artifact_only';
+      workflowArtifactOwnership = base.workflow_artifact_ownership === 'yes' ? 'yes' : 'no';
+      appendNote(notes, 'Review-only roles constrain direct-write runtimes to planning or review artifact production only.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   } else if (authority === 'proposed') {
-    switch (runtime?.type) {
-      case 'manual':
-      case 'local_cli':
-        effectiveWritePath = 'patch_authoring';
-        workflowArtifactOwnership = 'yes';
-        appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'proposal_apply_required';
-        workflowArtifactOwnership = 'proposal_apply_required';
-        appendNote(notes, 'Accepted proposals are staged under .agentxchain/proposed and require proposal apply before gate files exist in the repo.');
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP proposed-authoring behavior depends on the governed tool implementation.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (runtime?.type === 'manual') {
+      effectiveWritePath = 'patch_authoring';
+      workflowArtifactOwnership = 'yes';
+      appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
+    } else if (base.can_write_files === 'direct') {
+      effectiveWritePath = 'patch_authoring';
+      workflowArtifactOwnership = base.workflow_artifact_ownership;
+      appendNote(notes, 'This role can prepare patch-shaped work while still satisfying workflow-kit artifact ownership.');
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'proposal_apply_required';
+      workflowArtifactOwnership = 'proposal_apply_required';
+      appendNote(notes, 'Accepted proposals are staged under .agentxchain/proposed and require proposal apply before gate files exist in the repo.');
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Proposed-authoring behavior depends on the governed tool implementation.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   } else if (authority === 'authoritative') {
-    switch (runtime?.type) {
-      case 'manual':
-      case 'local_cli':
-        effectiveWritePath = 'direct';
-        workflowArtifactOwnership = 'yes';
-        break;
-      case 'api_proxy':
-      case 'remote_agent':
-        effectiveWritePath = 'invalid_authoritative_binding';
-        workflowArtifactOwnership = 'invalid';
-        appendNote(notes, `${runtime.type} does not support authoritative roles in v1.`);
-        break;
-      case 'mcp':
-        effectiveWritePath = 'tool_defined';
-        workflowArtifactOwnership = 'tool_defined';
-        appendNote(notes, 'MCP authoritative repo writes are tool-defined, not guaranteed by runtime type.');
-        break;
-      default:
-        effectiveWritePath = 'unknown';
-        workflowArtifactOwnership = 'unknown';
-        break;
+    if (base.can_write_files === 'direct') {
+      effectiveWritePath = 'direct';
+      workflowArtifactOwnership = base.workflow_artifact_ownership;
+      if (runtime?.type === 'mcp') {
+        appendNote(notes, 'Authoritative MCP repo writes are accepted because the connector declared a direct write path.');
+      }
+    } else if (base.can_write_files === 'proposal_only') {
+      effectiveWritePath = 'invalid_authoritative_binding';
+      workflowArtifactOwnership = 'invalid';
+      appendNote(notes, `${runtime.type} does not support authoritative roles in v1.`);
+    } else if (base.can_write_files === 'tool_defined' || base.workflow_artifact_ownership === 'tool_defined') {
+      effectiveWritePath = 'tool_defined';
+      workflowArtifactOwnership = 'tool_defined';
+      appendNote(notes, 'Authoritative repo writes are tool-defined, not guaranteed by runtime type alone.');
+    } else {
+      effectiveWritePath = 'unknown';
+      workflowArtifactOwnership = 'unknown';
     }
   }
 
@@ -213,6 +221,18 @@ export function summarizeRuntimeCapabilityContract(contract) {
   ].join('; ');
 }
 
+export { DECLARABLE_CAPABILITY_FIELDS };
+
+export function getCapabilityDeclarationWarnings(runtime = {}) {
+  const warnings = [];
+  const declared = runtime?.capabilities;
+  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) return warnings;
+  if (declared.can_write_files === 'direct' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent')) {
+    warnings.push(`Runtime type "${runtime.type}" declares can_write_files=direct, which the reference runner does not support in v1. A third-party runner may.`);
+  }
+  return warnings;
+}
+
 export function summarizeRoleRuntimeCapability(contract) {
   return [
     `${contract.role_id}(${contract.role_write_authority})`,