agentxchain 2.9.0 → 2.11.0

package/README.md

@@ -109,6 +109,7 @@ agentxchain step
 | `approve-transition` | Approve a pending human-gated phase transition |
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
+| `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
 | `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |

package/bin/agentxchain.js

@@ -69,6 +69,7 @@ import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
 import { stepCommand } from '../src/commands/step.js';
+import { runCommand } from '../src/commands/run.js';
 import { approveTransitionCommand } from '../src/commands/approve-transition.js';
 import { approveCompletionCommand } from '../src/commands/approve-completion.js';
 import { dashboardCommand } from '../src/commands/dashboard.js';
@@ -245,6 +246,9 @@ verifyCmd
   .option('--tier <tier>', 'Conformance tier to verify (1, 2, or 3)', '1')
   .option('--surface <surface>', 'Restrict verification to a single surface')
   .option('--target <path>', 'Target root containing .agentxchain-conformance/capabilities.json', '.')
+  .option('--remote <url>', 'Remote HTTP conformance endpoint base URL')
+  .option('--token <token>', 'Bearer token for remote HTTP conformance endpoint')
+  .option('--timeout <ms>', 'Per-fixture remote HTTP timeout in milliseconds', '30000')
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyProtocolCommand);
 
@@ -304,6 +308,16 @@ program
   .option('--auto-reject', 'Auto-reject and retry on validation failure')
   .action(stepCommand);
 
+program
+  .command('run')
+  .description('Drive a governed run to completion: multi-turn execution with gate prompting')
+  .option('--role <role>', 'Override the initial role (default: config-driven selection)')
+  .option('--max-turns <n>', 'Maximum turns before stopping (default: 50)', parseInt)
+  .option('--auto-approve', 'Auto-approve all gates (non-interactive mode)')
+  .option('--verbose', 'Stream adapter subprocess output')
+  .option('--dry-run', 'Print what would be dispatched without executing')
+  .action(runCommand);
+
 program
   .command('approve-transition')
   .description('Approve a pending phase transition that requires human sign-off')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "test:node": "node --test test/*.test.js",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
+    "postflight:release": "bash scripts/release-postflight.sh",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/src/commands/run.js

@@ -0,0 +1,365 @@
+/**
+ * agentxchain run — drive a governed run to completion.
+ *
+ * Thin CLI surface over the runLoop library. Wires runLoop callbacks to:
+ *   - Existing adapter system (api_proxy, local_cli, mcp)
+ *   - Interactive gate prompting (stdin) or auto-approve mode
+ *   - Terminal output via chalk
+ *
+ * Does NOT support manual adapter — use `agentxchain step` for that.
+ * Does NOT call assignTurn/acceptTurn/rejectTurn directly — runLoop owns the state machine.
+ *
+ * See .planning/AGENTXCHAIN_RUN_SPEC.md for the full specification.
+ */
+
+import chalk from 'chalk';
+import { createInterface } from 'readline';
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { runLoop } from '../lib/run-loop.js';
+import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
+import {
+  dispatchLocalCli,
+  saveDispatchLogs,
+  resolvePromptTransport,
+} from '../lib/adapters/local-cli-adapter.js';
+import { dispatchMcp, resolveMcpTransport, describeMcpRuntimeTarget } from '../lib/adapters/mcp-adapter.js';
+import { runHooks } from '../lib/hook-runner.js';
+import { finalizeDispatchManifest } from '../lib/dispatch-manifest.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { resolveGovernedRole } from '../lib/role-resolution.js';
+import {
+  getDispatchAssignmentPath,
+  getDispatchContextPath,
+  getDispatchEffectiveContextPath,
+  getDispatchPromptPath,
+  getDispatchTurnDir,
+  getTurnStagingResultPath,
+} from '../lib/turn-paths.js';
+
+export async function runCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The run command is only available for governed projects.'));
+    console.log(chalk.dim('Legacy projects use: agentxchain start'));
+    process.exit(1);
+  }
+
+  const maxTurns = opts.maxTurns || 50;
+  const autoApprove = !!opts.autoApprove;
+  const verbose = !!opts.verbose;
+  const overrideResolution = opts.role
+    ? resolveGovernedRole({ override: opts.role, state: null, config })
+    : null;
+
+  if (overrideResolution?.error) {
+    console.log(chalk.red(overrideResolution.error));
+    if (overrideResolution.availableRoles.length) {
+      console.log(chalk.dim(`Available roles: ${overrideResolution.availableRoles.join(', ')}`));
+    }
+    process.exit(1);
+  }
+
+  // ── Dry run ───────────────────────────────────────────────────────────────
+  if (opts.dryRun) {
+    const dryRunState = loadProjectState(root, config);
+    const roleId = overrideResolution?.roleId || resolveRole(null, dryRunState, config);
+    console.log(chalk.cyan('Dry run — no execution'));
+    console.log(`  First role:   ${roleId || chalk.dim('(unresolved)')}`);
+    console.log(`  Max turns:    ${maxTurns}`);
+    console.log(`  Gate mode:    ${autoApprove ? 'auto-approve' : 'interactive'}`);
+    const roleIds = Object.keys(config.roles || {});
+    for (const rid of roleIds) {
+      const role = config.roles[rid];
+      const rtId = role.runtime;
+      const rt = config.runtimes?.[rtId];
+      const rtType = rt?.type || role.runtime_class || 'manual';
+      const supported = rtType !== 'manual';
+      console.log(`  ${supported ? chalk.green('✓') : chalk.red('✗')} ${rid} → ${rtType}${supported ? '' : ' (not supported in run mode)'}`);
+    }
+    process.exit(0);
+  }
+
+  // ── SIGINT handling ─────────────────────────────────────────────────────
+  let aborted = false;
+  let sigintCount = 0;
+  const controller = new AbortController();
+
+  process.on('SIGINT', () => {
+    sigintCount++;
+    if (sigintCount >= 2) {
+      process.exit(130);
+    }
+    aborted = true;
+    controller.abort();
+    console.log(chalk.yellow('\nSIGINT received — finishing current turn, then stopping.'));
+  });
+
+  // ── Run header ──────────────────────────────────────────────────────────
+  console.log(chalk.cyan.bold('agentxchain run'));
+  console.log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
+  console.log('');
+
+  // ── Track first-call for --role override ────────────────────────────────
+  let firstSelectRole = true;
+
+  // ── Callbacks ───────────────────────────────────────────────────────────
+  const callbacks = {
+    selectRole(state, cfg) {
+      if (aborted) return null;
+
+      if (firstSelectRole && opts.role) {
+        firstSelectRole = false;
+        return overrideResolution.roleId;
+      }
+      firstSelectRole = false;
+      return resolveRole(null, state, cfg);
+    },
+
+    async dispatch(ctx) {
+      const { turn, state, config: cfg, root: projectRoot } = ctx;
+      const roleId = turn.assigned_role;
+      const role = cfg.roles?.[roleId];
+      const runtimeId = turn.runtime_id;
+      const runtime = cfg.runtimes?.[runtimeId];
+      const runtimeType = runtime?.type || role?.runtime_class || 'manual';
+      const hooksConfig = cfg.hooks || {};
+
+      // Manual adapter is not supported in run mode
+      if (runtimeType === 'manual') {
+        console.log(chalk.yellow(`Skipping manual role "${roleId}" — use agentxchain step for manual dispatch.`));
+        return { accept: false, reason: 'manual adapter is not supported in run mode — use agentxchain step' };
+      }
+
+      // ── after_dispatch hooks ──────────────────────────────────────────
+      if (hooksConfig.after_dispatch?.length > 0) {
+        const hookResult = runHooks(projectRoot, hooksConfig, 'after_dispatch', {
+          turn_id: turn.turn_id,
+          role_id: roleId,
+          bundle_path: getDispatchTurnDir(turn.turn_id),
+          bundle_files: ['ASSIGNMENT.json', 'PROMPT.md', 'CONTEXT.md'],
+        }, {
+          run_id: state.run_id,
+          turn_id: turn.turn_id,
+          protectedPaths: [
+            getDispatchAssignmentPath(turn.turn_id),
+            getDispatchPromptPath(turn.turn_id),
+            getDispatchContextPath(turn.turn_id),
+            getDispatchEffectiveContextPath(turn.turn_id),
+          ],
+        });
+
+        if (!hookResult.ok) {
+          return { accept: false, reason: `after_dispatch hook blocked: ${hookResult.error || 'hook failure'}` };
+        }
+      }
+
+      // ── Finalize dispatch manifest ────────────────────────────────────
+      const manifestResult = finalizeDispatchManifest(projectRoot, turn.turn_id, {
+        run_id: state.run_id,
+        role: roleId,
+      });
+      if (!manifestResult.ok) {
+        return { accept: false, reason: `dispatch manifest failed: ${manifestResult.error}` };
+      }
+
+      // ── Route to adapter ──────────────────────────────────────────────
+      const adapterOpts = {
+        signal: controller.signal,
+        onStatus: (msg) => console.log(chalk.dim(`  ${msg}`)),
+        verifyManifest: true,
+      };
+
+      if (verbose) {
+        adapterOpts.onStdout = (text) => process.stdout.write(chalk.dim(text));
+        adapterOpts.onStderr = (text) => process.stderr.write(chalk.yellow(text));
+      }
+
+      let adapterResult;
+
+      if (runtimeType === 'api_proxy') {
+        console.log(chalk.dim(`  Dispatching to API proxy: ${runtime?.provider || '?'} / ${runtime?.model || '?'}`));
+        adapterResult = await dispatchApiProxy(projectRoot, state, cfg, adapterOpts);
+      } else if (runtimeType === 'mcp') {
+        const transport = resolveMcpTransport(runtime);
+        console.log(chalk.dim(`  Dispatching to MCP ${transport}: ${describeMcpRuntimeTarget(runtime)}`));
+        adapterResult = await dispatchMcp(projectRoot, state, cfg, adapterOpts);
+      } else if (runtimeType === 'local_cli') {
+        const transport = runtime ? resolvePromptTransport(runtime) : 'dispatch_bundle_only';
+        console.log(chalk.dim(`  Dispatching to local CLI: ${runtime?.command || '(default)'}  transport: ${transport}`));
+        adapterResult = await dispatchLocalCli(projectRoot, state, cfg, adapterOpts);
+      } else {
+        return { accept: false, reason: `unknown runtime type "${runtimeType}"` };
+      }
+
+      // Save adapter logs
+      if (adapterResult.logs?.length) {
+        saveDispatchLogs(projectRoot, turn.turn_id, adapterResult.logs);
+      }
+
+      // Aborted
+      if (adapterResult.aborted) {
+        return { accept: false, reason: 'dispatch aborted by operator' };
+      }
+
+      // Timed out
+      if (adapterResult.timedOut) {
+        return { accept: false, reason: 'dispatch timed out' };
+      }
+
+      // Adapter failure
+      if (!adapterResult.ok) {
+        const errorDetail = adapterResult.classified
+          ? `${adapterResult.classified.error_class}: ${adapterResult.classified.recovery}`
+          : adapterResult.error;
+        return { accept: false, reason: errorDetail || 'adapter dispatch failed' };
+      }
+
+      // ── Read staged result ────────────────────────────────────────────
+      const stagingFile = join(projectRoot, getTurnStagingResultPath(turn.turn_id));
+      if (!existsSync(stagingFile)) {
+        return { accept: false, reason: 'adapter completed but no staged result found' };
+      }
+
+      let turnResult;
+      try {
+        turnResult = JSON.parse(readFileSync(stagingFile, 'utf8'));
+      } catch (err) {
+        return { accept: false, reason: `failed to parse staged result: ${err.message}` };
+      }
+
+      return { accept: true, turnResult };
+    },
+
+    async approveGate(gateType, state) {
+      if (autoApprove) {
+        console.log(chalk.yellow(`  Auto-approved ${gateType} gate`));
+        return true;
+      }
+
+      // Non-TTY → fail-closed
+      if (!process.stdin.isTTY) {
+        console.log(chalk.yellow(`  Gate pause: ${gateType} — stdin is not a TTY, failing closed.`));
+        console.log(chalk.dim('  Use --auto-approve for non-interactive mode.'));
+        return false;
+      }
+
+      const target = gateType === 'phase_transition'
+        ? state.pending_phase_transition?.target || '(next phase)'
+        : 'run completion';
+
+      console.log('');
+      console.log(chalk.yellow.bold(`Gate pause: ${gateType}`));
+      console.log(chalk.dim(`  Phase: ${state.phase} → ${target}`));
+
+      const answer = await promptUser(`  Approve? [y/N] `);
+      const approved = /^y(es)?$/i.test(answer.trim());
+      return approved;
+    },
+
+    onEvent(event) {
+      switch (event.type) {
+        case 'turn_assigned':
+          console.log(chalk.cyan(`Turn assigned: ${event.turn?.turn_id} → ${event.role}`));
+          break;
+        case 'turn_accepted':
+          console.log(chalk.green(`Turn accepted: ${event.turn?.turn_id}`));
+          break;
+        case 'turn_rejected':
+          console.log(chalk.yellow(`Turn rejected: ${event.turn?.turn_id} — ${event.reason || 'no reason'}`));
+          break;
+        case 'gate_paused':
+          console.log(chalk.yellow(`Gate paused: ${event.gateType}`));
+          break;
+        case 'gate_approved':
+          console.log(chalk.green(`Gate approved: ${event.gateType}`));
+          break;
+        case 'gate_held':
+          console.log(chalk.yellow(`Gate held: ${event.gateType} — run paused`));
+          break;
+        case 'blocked':
+          console.log(chalk.red(`Run blocked`));
+          break;
+        case 'completed':
+          console.log(chalk.green.bold('Run completed'));
+          break;
+        case 'caller_stopped':
+          console.log(chalk.yellow('Run stopped by caller'));
+          break;
+      }
+    },
+  };
+
+  // ── Execute ─────────────────────────────────────────────────────────────
+  const result = await runLoop(root, config, callbacks, { maxTurns });
+
+  // ── Summary ─────────────────────────────────────────────────────────────
+  console.log('');
+  console.log(chalk.dim('─── Run Summary ───'));
+  console.log(`  Status:  ${result.ok ? chalk.green('completed') : chalk.yellow(result.stop_reason)}`);
+  console.log(`  Turns:   ${result.turns_executed}`);
+  console.log(`  Gates:   ${result.gates_approved} approved`);
+  console.log(`  Errors:  ${result.errors.length ? chalk.red(result.errors.length) : 'none'}`);
+
+  if (result.errors.length) {
+    for (const err of result.errors) {
+      console.log(chalk.red(`    ${err}`));
+    }
+  }
+
+  // Recovery guidance for blocked/rejected states
+  if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
+    const recovery = deriveRecoveryDescriptor(result.state);
+    if (recovery) {
+      console.log('');
+      console.log(chalk.yellow(`  Recovery: ${recovery.typed_reason}`));
+      console.log(chalk.dim(`  Action:   ${recovery.recovery_action}`));
+      if (recovery.detail) {
+        console.log(chalk.dim(`  Detail:   ${recovery.detail}`));
+      }
+    }
+  }
+
+  // ── Exit code ───────────────────────────────────────────────────────────
+  const successReasons = new Set(['completed', 'gate_held', 'caller_stopped', 'max_turns_reached']);
+  if (result.ok || successReasons.has(result.stop_reason)) {
+    process.exit(0);
+  }
+  process.exit(1);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the target role for the next turn.
+ * Same routing contract as step.js resolveTargetRole, minus interactive logging.
+ */
+function resolveRole(override, state, config) {
+  const resolved = resolveGovernedRole({ override, state, config });
+  return resolved.error ? null : resolved.roleId;
+}
+
+/**
+ * Prompt the user via stdin readline.
+ */
+function promptUser(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+    rl.on('close', () => resolve(''));
+  });
+}

package/src/commands/step.js

@@ -61,6 +61,7 @@ import { safeWriteJson } from '../lib/safe-write.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest, verifyDispatchManifest } from '../lib/dispatch-manifest.js';
+import { resolveGovernedRole } from '../lib/role-resolution.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -836,45 +837,24 @@ function printLifecycleHookFailure(title, result, { turnId, roleId, action }) {
 }
 
 function resolveTargetRole(opts, state, config) {
-  const phase = state.phase;
-  const routing = config.routing?.[phase];
-
-  if (opts.role) {
-    if (!config.roles?.[opts.role]) {
-      console.log(chalk.red(`Unknown role: "${opts.role}"`));
-      console.log(chalk.dim(`Available roles: ${Object.keys(config.roles || {}).join(', ')}`));
-      return null;
-    }
-    if (routing?.allowed_next_roles && !routing.allowed_next_roles.includes(opts.role) && opts.role !== 'human') {
-      console.log(chalk.yellow(`Warning: role "${opts.role}" is not in allowed_next_roles for phase "${phase}".`));
-    }
-    return opts.role;
-  }
-
-  // Use stored next_recommended_role if routing-legal
-  if (state.next_recommended_role) {
-    const recommended = state.next_recommended_role;
-    if (config.roles?.[recommended]) {
-      const isLegal = !routing?.allowed_next_roles || routing.allowed_next_roles.includes(recommended);
-      if (isLegal) {
-        console.log(chalk.dim(`Using recommended role: ${recommended} (from previous turn)`));
-        return recommended;
-      }
+  const resolved = resolveGovernedRole({ override: opts.role || null, state, config });
+  if (resolved.error) {
+    console.log(chalk.red(resolved.error));
+    if (resolved.availableRoles.length) {
+      console.log(chalk.dim(`Available roles: ${resolved.availableRoles.join(', ')}`));
     }
+    return null;
   }
 
-  if (routing?.entry_role) {
-    return routing.entry_role;
+  if (!opts.role && state.next_recommended_role && resolved.roleId === state.next_recommended_role) {
+    console.log(chalk.dim(`Using recommended role: ${resolved.roleId} (from previous turn)`));
   }
 
-  const roles = Object.keys(config.roles || {});
-  if (roles.length > 0) {
-    console.log(chalk.yellow(`No entry_role for phase "${phase}". Defaulting to "${roles[0]}".`));
-    return roles[0];
+  for (const warning of resolved.warnings) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
   }
 
-  console.log(chalk.red('No roles defined in config.'));
-  return null;
+  return resolved.roleId;
 }
 
 function printRecoverySummary(state, heading) {

package/src/commands/template-validate.js

@@ -7,7 +7,9 @@ import {
   validateGovernedTemplateRegistry,
   validateProjectPlanningArtifacts,
   validateAcceptanceHintCompletion,
+  validateGovernedWorkflowKit,
 } from '../lib/governed-templates.js';
+import { loadNormalizedConfig } from '../lib/normalized-config.js';
 
 function loadProjectTemplateValidation() {
   const root = findProjectRoot();
@@ -17,6 +19,7 @@ function loadProjectTemplateValidation() {
       root: null,
       template: null,
       source: null,
+      normalized_config: null,
       ok: true,
       errors: [],
       warnings: [],
@@ -33,16 +36,24 @@ function loadProjectTemplateValidation() {
       root,
       template: null,
       source: 'agentxchain.json',
+      normalized_config: null,
       ok: false,
       errors: [`Failed to parse ${CONFIG_FILE}: ${err.message}`],
       warnings: [],
     };
   }
 
+  let normalizedConfig = null;
+  const normalized = loadNormalizedConfig(parsed, root);
+  if (normalized.ok) {
+    normalizedConfig = normalized.normalized;
+  }
+
   const projectValidation = validateGovernedProjectTemplate(parsed.template);
   return {
     present: true,
     root,
+    normalized_config: normalizedConfig,
     ...projectValidation,
   };
 }
@@ -63,16 +74,36 @@ export function templateValidateCommand(opts = {}) {
     acceptanceHints = validateAcceptanceHintCompletion(project.root, project.template);
   }
 
+  let workflowKit = null;
+  if (project.present && project.ok && project.root) {
+    if (project.normalized_config?.protocol_mode === 'governed') {
+      workflowKit = validateGovernedWorkflowKit(project.root, project.normalized_config);
+    } else if (!project.normalized_config) {
+      workflowKit = {
+        ok: true,
+        required_files: [],
+        gate_required_files: [],
+        present: [],
+        missing: [],
+        structural_checks: [],
+        errors: [],
+        warnings: ['Workflow kit validation skipped because project config could not be normalized.'],
+      };
+    }
+  }
+
   const errors = [
     ...registry.errors,
     ...project.errors,
     ...(planningArtifacts?.errors || []),
+    ...(workflowKit?.errors || []),
   ];
   const warnings = [
     ...registry.warnings,
     ...project.warnings,
     ...(planningArtifacts?.warnings || []),
     ...(acceptanceHints?.warnings || []),
+    ...(workflowKit?.warnings || []),
   ];
   const ok = errors.length === 0;
 
@@ -82,6 +113,7 @@ export function templateValidateCommand(opts = {}) {
     project,
     planning_artifacts: planningArtifacts,
     acceptance_hints: acceptanceHints,
+    workflow_kit: workflowKit,
     errors,
     warnings,
   };
@@ -125,6 +157,16 @@ export function templateValidateCommand(opts = {}) {
         console.log(`  ${chalk.dim('Planning:')}   ${chalk.red('FAIL')} (${planningArtifacts.missing.length}/${total} missing: ${planningArtifacts.missing.join(', ')})`);
       }
     }
+    if (workflowKit) {
+      const fileCount = workflowKit.required_files.length;
+      const checkCount = workflowKit.structural_checks.length;
+      const passedChecks = workflowKit.structural_checks.filter((check) => check.ok).length;
+      if (workflowKit.ok) {
+        console.log(`  ${chalk.dim('Workflow:')}   ${chalk.green('OK')} (${workflowKit.present.length}/${fileCount} files, ${passedChecks}/${checkCount} checks)`);
+      } else {
+        console.log(`  ${chalk.dim('Workflow:')}   ${chalk.red('FAIL')} (${workflowKit.missing.length}/${fileCount} missing, ${checkCount - passedChecks}/${checkCount} checks failed)`);
+      }
+    }
     if (acceptanceHints) {
       if (acceptanceHints.total === 0) {
         console.log(`  ${chalk.dim('Acceptance:')} ${chalk.green('OK')} (no template hints defined)`);

package/src/commands/verify.js

@@ -3,27 +3,42 @@ import { resolve } from 'node:path';
 import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
 import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
 
-export async function verifyProtocolCommand(opts) {
-  const target = opts.target ? resolve(opts.target) : process.cwd();
+export async function verifyProtocolCommand(opts, command) {
   const requestedTier = Number.parseInt(String(opts.tier || '1'), 10);
+  const timeout = Number.parseInt(String(opts.timeout || '30000'), 10);
   const format = opts.format || 'text';
+  const targetSource = command?.getOptionValueSource?.('target');
+  const timeoutSource = command?.getOptionValueSource?.('timeout');
+  const hasExplicitTarget = targetSource && targetSource !== 'default';
+  const remote = opts.remote || null;
+
+  if (remote && hasExplicitTarget) {
+    emitProtocolVerifyError(format, 'Cannot specify both --target and --remote');
+    process.exit(2);
+  }
+
+  if (!remote && opts.token) {
+    emitProtocolVerifyError(format, 'Cannot specify --token without --remote');
+    process.exit(2);
+  }
+
+  if (!remote && timeoutSource && timeoutSource !== 'default') {
+    emitProtocolVerifyError(format, 'Cannot specify --timeout without --remote');
+    process.exit(2);
+  }
 
   let result;
   try {
-    result = verifyProtocolConformance({
-      targetRoot: target,
+    result = await verifyProtocolConformance({
+      targetRoot: remote ? null : resolve(opts.target || process.cwd()),
+      remote,
+      token: opts.token || null,
+      timeout,
       requestedTier,
       surface: opts.surface || null,
     });
   } catch (error) {
-    if (format === 'json') {
-      console.log(JSON.stringify({
-        overall: 'error',
-        message: error.message,
-      }, null, 2));
-    } else {
-      console.log(chalk.red(`Protocol verification failed: ${error.message}`));
-    }
+    emitProtocolVerifyError(format, error.message);
     process.exit(2);
   }
 
@@ -36,6 +51,18 @@ export async function verifyProtocolCommand(opts) {
   process.exit(result.exitCode);
 }
 
+function emitProtocolVerifyError(format, message) {
+  if (format === 'json') {
+    console.log(JSON.stringify({
+      overall: 'error',
+      message,
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.red(`Protocol verification failed: ${message}`));
+}
+
 export async function verifyExportCommand(opts) {
   const format = opts.format || 'text';
   const loaded = loadExportArtifact(opts.input || '-', process.cwd());
@@ -72,7 +99,8 @@ function printProtocolReport(report) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Protocol Conformance'));
   console.log(chalk.dim('  ' + '─'.repeat(44)));
-  console.log(chalk.dim(`  Target: ${report.target_root}`));
+  const targetLabel = report.remote || report.target_root;
+  console.log(chalk.dim(`  Target: ${targetLabel}`));
   console.log(chalk.dim(`  Implementation: ${report.implementation}`));
   console.log(chalk.dim(`  Tier requested: ${report.tier_requested}`));
   console.log('');