agentxchain 2.28.0 → 2.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -62,7 +62,6 @@
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
     "inquirer": "^12.0.0",
-    "ora": "^8.0.0",
     "zod": "^4.3.6"
   },
   "engines": {

package/src/commands/run.js

@@ -2,7 +2,7 @@
  * 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)
+ *   - Existing adapter system (api_proxy, local_cli, mcp, remote_agent)
  *   - Interactive gate prompting (stdin) or auto-approve mode
  *   - Terminal output via chalk
  *
@@ -27,6 +27,7 @@ import {
   resolvePromptTransport,
 } from '../lib/adapters/local-cli-adapter.js';
 import { dispatchMcp, resolveMcpTransport, describeMcpRuntimeTarget } from '../lib/adapters/mcp-adapter.js';
+import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/remote-agent-adapter.js';
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest } from '../lib/dispatch-manifest.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
@@ -200,6 +201,9 @@ export async function runCommand(opts) {
         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 if (runtimeType === 'remote_agent') {
+        console.log(chalk.dim(`  Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
+        adapterResult = await dispatchRemoteAgent(projectRoot, state, cfg, adapterOpts);
       } else {
         return { accept: false, reason: `unknown runtime type "${runtimeType}"` };
       }

package/src/commands/step.js

@@ -18,6 +18,7 @@
  *   - api_proxy: implemented for synchronous review-only turns and stages
  *     provider-backed JSON before validation/acceptance
  *   - mcp: implemented for synchronous MCP stdio or streamable_http tool dispatch
+ *   - remote_agent: implemented for synchronous HTTP dispatch to external agent services
  */
 
 import chalk from 'chalk';
@@ -49,6 +50,7 @@ import {
   resolvePromptTransport,
 } from '../lib/adapters/local-cli-adapter.js';
 import { describeMcpRuntimeTarget, dispatchMcp, resolveMcpTransport } from '../lib/adapters/mcp-adapter.js';
+import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/remote-agent-adapter.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -504,11 +506,63 @@ export async function stepCommand(opts) {
 
     console.log(chalk.green(`MCP tool completed${mcpResult.toolName ? ` (${mcpResult.toolName})` : ''}. Staged result detected.`));
     console.log('');
+  } else if (runtimeType === 'remote_agent') {
+    console.log(chalk.cyan(`Dispatching to remote agent: ${describeRemoteAgentTarget(runtime)}`));
+    console.log(chalk.dim(`Turn: ${turn.turn_id}  Role: ${roleId}  Phase: ${state.phase}`));
+
+    const remoteResult = await dispatchRemoteAgent(root, state, config, {
+      signal: controller.signal,
+      onStatus: (msg) => console.log(chalk.dim(`  ${msg}`)),
+      verifyManifest: true,
+    });
+
+    if (remoteResult.logs?.length) {
+      saveDispatchLogs(root, turn.turn_id, remoteResult.logs);
+    }
+
+    if (remoteResult.aborted) {
+      console.log('');
+      console.log(chalk.yellow('Aborted. Turn remains assigned.'));
+      console.log(chalk.dim('Resume later with: agentxchain step --resume'));
+      console.log(chalk.dim('Or accept/reject manually: agentxchain accept-turn / reject-turn'));
+      process.exit(0);
+    }
+
+    if (!remoteResult.ok) {
+      const blocked = markRunBlocked(root, {
+        blockedOn: `dispatch:remote_agent_failure`,
+        category: 'dispatch_error',
+        recovery: {
+          typed_reason: 'dispatch_error',
+          owner: 'human',
+          recovery_action: 'Resolve the remote agent dispatch issue, then run agentxchain step --resume',
+          turn_retained: true,
+          detail: remoteResult.error,
+        },
+        turnId: turn.turn_id,
+        hooksConfig,
+        notificationConfig: config,
+      });
+      if (blocked.ok) {
+        state = blocked.state;
+      }
+
+      console.log('');
+      console.log(chalk.red(`Remote agent dispatch failed: ${remoteResult.error}`));
+      console.log(chalk.dim('The turn remains assigned. You can:'));
+      console.log(chalk.dim('  - Fix the issue and retry: agentxchain step --resume'));
+      console.log(chalk.dim('  - Complete manually: edit .agentxchain/staging/turn-result.json'));
+      console.log(chalk.dim('  - Reject: agentxchain reject-turn --reason "remote agent failed"'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green('Remote agent completed. Staged result detected.'));
+    console.log('');
   }
 
   // ── Phase 3: Wait for turn completion ─────────────────────────────────────
 
-  if (runtimeType === 'api_proxy' || runtimeType === 'mcp') {
+  if (runtimeType === 'api_proxy' || runtimeType === 'mcp' || runtimeType === 'remote_agent') {
     // api_proxy and mcp are synchronous — result already staged in Phase 2
   } else if (runtimeType === 'local_cli') {
     // ── Local CLI adapter: spawn subprocess ──
@@ -762,6 +816,7 @@ export async function stepCommand(opts) {
       console.log(chalk.dim('  - Fix the staged result and run: agentxchain accept-turn'));
       console.log(chalk.dim('  - Reject and retry: agentxchain reject-turn'));
       console.log(chalk.dim('  - Auto-reject on failure: agentxchain step --auto-reject'));
+      process.exit(1);
     }
   }
 }

package/src/lib/adapter-interface.js

@@ -28,4 +28,10 @@ export {
   describeMcpRuntimeTarget,
 } from './adapters/mcp-adapter.js';
 
+export {
+  dispatchRemoteAgent,
+  describeRemoteAgentTarget,
+  DEFAULT_REMOTE_AGENT_TIMEOUT_MS,
+} from './adapters/remote-agent-adapter.js';
+
 export const ADAPTER_INTERFACE_VERSION = '0.1';

package/src/lib/adapters/remote-agent-adapter.js

@@ -0,0 +1,257 @@
+/**
+ * Remote Agent adapter — HTTP-based governed turn dispatch.
+ *
+ * Specification: .planning/REMOTE_AGENT_BRIDGE_CONNECTOR_SPEC.md
+ *
+ * This adapter proves connector replaceability (VISION.md Layer 3) by executing
+ * governed turns over HTTP against an external agent service. The protocol's
+ * staging, validation, and acceptance flow is preserved exactly — the remote
+ * service receives a turn envelope and must return a valid turn-result JSON.
+ *
+ * v1 scope: synchronous request/response only. No polling, no webhooks.
+ *
+ * Security: authorization headers are sent to the remote service but are
+ * never echoed into dispatch logs or governance artifacts.
+ */
+
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  getDispatchContextPath,
+  getDispatchPromptPath,
+  getDispatchTurnDir,
+  getTurnStagingDir,
+  getTurnStagingResultPath,
+} from '../turn-paths.js';
+import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+
+/** Default timeout for remote agent requests (ms). */
+export const DEFAULT_REMOTE_AGENT_TIMEOUT_MS = 120_000;
+
+/** Header keys that must never appear in logs or artifacts. */
+const REDACTED_HEADER_PATTERNS = [/^authorization$/i, /^x-api-key$/i, /^cookie$/i, /^proxy-authorization$/i];
+
+function isSecretHeader(key) {
+  return REDACTED_HEADER_PATTERNS.some(p => p.test(key));
+}
+
+/**
+ * Build a safe header summary for logs (redacts secret values).
+ */
+function safeHeaderSummary(headers) {
+  if (!headers || typeof headers !== 'object') return {};
+  const safe = {};
+  for (const [k, v] of Object.entries(headers)) {
+    safe[k] = isSecretHeader(k) ? '[REDACTED]' : v;
+  }
+  return safe;
+}
+
+/**
+ * Dispatch a governed turn to a remote agent service.
+ *
+ * @param {string} root - project root directory
+ * @param {object} state - current governed state
+ * @param {object} config - normalized config
+ * @param {object} [options]
+ * @param {AbortSignal} [options.signal] - abort signal
+ * @param {function} [options.onStatus] - status callback
+ * @param {boolean} [options.verifyManifest] - require dispatch manifest verification
+ * @param {boolean} [options.skipManifestVerification] - skip manifest check
+ * @param {string} [options.turnId] - override turn ID
+ * @returns {Promise<{ ok: boolean, error?: string, logs?: string[], aborted?: boolean, timedOut?: boolean }>}
+ */
+export async function dispatchRemoteAgent(root, state, config, options = {}) {
+  const { signal, onStatus, turnId } = options;
+  const logs = [];
+
+  const turn = resolveTargetTurn(state, turnId);
+  if (!turn) {
+    return { ok: false, error: 'No active turn in state', logs };
+  }
+
+  const manifestCheck = verifyDispatchManifestForAdapter(root, turn.turn_id, options);
+  if (!manifestCheck.ok) {
+    return { ok: false, error: `Dispatch manifest verification failed: ${manifestCheck.error}`, logs };
+  }
+
+  const runtimeId = turn.runtime_id;
+  const runtime = config.runtimes?.[runtimeId];
+  if (!runtime || runtime.type !== 'remote_agent') {
+    return { ok: false, error: `Runtime "${runtimeId}" is not a remote_agent runtime`, logs };
+  }
+
+  if (!runtime.url) {
+    return { ok: false, error: `Runtime "${runtimeId}" is missing required "url"`, logs };
+  }
+
+  const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
+  const contextPath = join(root, getDispatchContextPath(turn.turn_id));
+
+  if (!existsSync(promptPath)) {
+    return { ok: false, error: 'Dispatch bundle not found — PROMPT.md missing', logs };
+  }
+
+  const prompt = readFileSync(promptPath, 'utf8');
+  const context = existsSync(contextPath) ? readFileSync(contextPath, 'utf8') : '';
+
+  // Build request envelope — governed turn metadata + rendered content
+  const timeoutMs = runtime.timeout_ms || DEFAULT_REMOTE_AGENT_TIMEOUT_MS;
+  const requestBody = {
+    run_id: state.run_id,
+    turn_id: turn.turn_id,
+    role: turn.assigned_role,
+    phase: state.phase,
+    runtime_id: runtimeId,
+    dispatch_dir: join(root, getDispatchTurnDir(turn.turn_id)),
+    prompt,
+    context,
+  };
+
+  // Ensure staging directory exists
+  const stagingDir = join(root, getTurnStagingDir(turn.turn_id));
+  mkdirSync(stagingDir, { recursive: true });
+
+  // Log transport metadata (safe — no secrets)
+  logs.push(`[remote] POST ${runtime.url}`);
+  logs.push(`[remote] timeout_ms=${timeoutMs}`);
+  const safeHeaders = safeHeaderSummary(runtime.headers);
+  if (Object.keys(safeHeaders).length > 0) {
+    logs.push(`[remote] headers=${JSON.stringify(safeHeaders)}`);
+  }
+
+  onStatus?.(`Posting to remote agent: ${runtime.url}`);
+
+  try {
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+
+    const headers = {
+      'content-type': 'application/json',
+      ...(runtime.headers || {}),
+    };
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    // Chain external abort signal to our controller
+    if (signal) {
+      signal.addEventListener('abort', () => controller.abort(), { once: true });
+    }
+
+    let response;
+    try {
+      response = await fetch(runtime.url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      clearTimeout(timeout);
+      if (signal?.aborted) {
+        return { ok: false, aborted: true, logs };
+      }
+      if (err.name === 'AbortError' || err.code === 'ABORT_ERR') {
+        logs.push(`[remote] Request timed out after ${timeoutMs}ms`);
+        return { ok: false, timedOut: true, error: `Remote agent timed out after ${timeoutMs}ms`, logs };
+      }
+      logs.push(`[remote] Network error: ${err.message}`);
+      return { ok: false, error: `Remote agent network error: ${err.message}`, logs };
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+
+    logs.push(`[remote] HTTP ${response.status} ${response.statusText}`);
+
+    if (!response.ok) {
+      let body = '';
+      try { body = await response.text(); } catch { /* ignore */ }
+      if (body) logs.push(`[remote] Body: ${body.slice(0, 500)}`);
+      return {
+        ok: false,
+        error: `Remote agent returned HTTP ${response.status}`,
+        logs,
+      };
+    }
+
+    // Parse response JSON
+    let responseData;
+    try {
+      responseData = await response.json();
+    } catch (err) {
+      logs.push(`[remote] JSON parse error: ${err.message}`);
+      return {
+        ok: false,
+        error: 'Remote agent response is not valid JSON',
+        logs,
+      };
+    }
+
+    // Validate turn result structure (lightweight — full validation happens in the acceptance pipeline)
+    if (!looksLikeTurnResult(responseData)) {
+      logs.push('[remote] Response missing required turn-result fields (need at least run_id/turn_id + status/role)');
+      return {
+        ok: false,
+        error: 'Remote agent response does not contain a valid turn result',
+        logs,
+      };
+    }
+
+    // Stage the result
+    const stagingPath = join(root, getTurnStagingResultPath(turn.turn_id));
+    writeFileSync(stagingPath, JSON.stringify(responseData, null, 2));
+
+    logs.push(`[remote] Turn result staged at ${getTurnStagingResultPath(turn.turn_id)}`);
+    onStatus?.('Remote agent returned valid turn result');
+    return { ok: true, logs };
+  } catch (error) {
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+    logs.push(`[remote] Unexpected error: ${error.message}`);
+    return {
+      ok: false,
+      error: `Remote agent dispatch failed: ${error.message}`,
+      logs,
+    };
+  }
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Lightweight structural check: does this object look like a turn result?
+ * Full validation happens later via validateStagedTurnResult.
+ */
+function looksLikeTurnResult(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const hasIdentity = 'run_id' in value || 'turn_id' in value;
+  const hasLifecycle = 'status' in value || 'role' in value || 'runtime_id' in value;
+  return hasIdentity && hasLifecycle;
+}
+
+function resolveTargetTurn(state, turnId) {
+  if (turnId && state?.active_turns?.[turnId]) {
+    return state.active_turns[turnId];
+  }
+  return state?.current_turn || Object.values(state?.active_turns || {})[0];
+}
+
+/**
+ * Describe a remote_agent runtime target for display (safe — no secrets).
+ */
+export function describeRemoteAgentTarget(runtime) {
+  if (!runtime?.url) return '(unknown)';
+  try {
+    const u = new URL(runtime.url);
+    return `${u.protocol}//${u.host}${u.pathname}`;
+  } catch {
+    return runtime.url;
+  }
+}

package/src/lib/context-section-parser.js

@@ -10,6 +10,7 @@ const SECTION_DEFINITIONS = [
   { id: 'last_turn_verification', header: null, required: false },
   { id: 'blockers', header: 'Blockers', required: true },
   { id: 'escalation', header: 'Escalation', required: true },
+  { id: 'workflow_artifacts', header: 'Workflow Artifacts', required: false },
   { id: 'gate_required_files', header: 'Gate Required Files', required: false },
   { id: 'phase_gate_status', header: 'Phase Gate Status', required: false },
 ];
@@ -88,6 +89,7 @@ export function renderContextSections(sections) {
 
   appendTopLevelSection(lines, 'Blockers', [sectionMap.get('blockers')?.content]);
   appendTopLevelSection(lines, 'Escalation', [sectionMap.get('escalation')?.content]);
+  appendTopLevelSection(lines, 'Workflow Artifacts', [sectionMap.get('workflow_artifacts')?.content]);
   appendTopLevelSection(lines, 'Gate Required Files', [sectionMap.get('gate_required_files')?.content]);
   appendTopLevelSection(lines, 'Phase Gate Status', [sectionMap.get('phase_gate_status')?.content]);
 

package/src/lib/dispatch-bundle.js

@@ -210,7 +210,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('- You may create/modify files under `.planning/` and `.agentxchain/reviews/`.');
     lines.push('- Your artifact type must be `review`.');
     lines.push('- You MUST raise at least one objection (even if minor).');
-    if (runtimeType === 'api_proxy') {
+    if (runtimeType === 'api_proxy' || runtimeType === 'remote_agent') {
       const reviewArtifactPath = getReviewArtifactPath(turn.turn_id, roleId);
       lines.push('- **This runtime cannot write repo files directly.** Do NOT claim `.planning/*` or `.agentxchain/reviews/*` changes you did not actually make.');
       lines.push(`- The orchestrator will materialize your accepted review at \`${reviewArtifactPath}\`.`);
@@ -230,7 +230,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
     lines.push('- You may propose changes as patches but cannot directly commit.');
     lines.push('- Your artifact type should be `patch`.');
-    if (runtimeType === 'api_proxy') {
+    if (runtimeType === 'api_proxy' || runtimeType === 'remote_agent') {
       lines.push('- **This runtime cannot write repo files directly.** When doing work, you MUST return proposed changes as structured JSON.');
       lines.push('- Include a `proposed_changes` array in your turn result with each file change (omit or set to `[]` on completion-only turns):');
       lines.push('  ```json');
@@ -248,6 +248,31 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  const workflowResponsibilities = getWorkflowPromptResponsibilities(config, phase, roleId, root);
+  if (workflowResponsibilities.length > 0) {
+    const isReviewOnlyOwner = role.write_authority === 'review_only';
+    lines.push('## Workflow-Kit Responsibilities');
+    lines.push('');
+    if (isReviewOnlyOwner) {
+      lines.push(`You are accountable for reviewing and attesting to these workflow-kit artifacts in phase \`${phase}\`:`);
+    } else {
+      lines.push(`You are accountable for producing these workflow-kit artifacts in phase \`${phase}\`:`);
+    }
+    lines.push('');
+    for (const artifact of workflowResponsibilities) {
+      const requiredLabel = artifact.required ? 'required' : 'optional';
+      const semanticsLabel = artifact.semantics ? `\`${artifact.semantics}\`` : '—';
+      lines.push(`- \`${artifact.path}\` — ${requiredLabel}; semantics: ${semanticsLabel}; status: ${artifact.status}`);
+    }
+    lines.push('');
+    if (isReviewOnlyOwner) {
+      lines.push('You cannot write repo files directly. Your accountability means you must confirm these artifacts exist, meet quality standards, and satisfy their semantic requirements. If a required artifact you own is missing, escalate to the producing role — do not request phase transition.');
+    } else {
+      lines.push('Do not request phase transition or run completion while a required workflow-kit artifact you own is missing or incomplete.');
+    }
+    lines.push('');
+  }
+
   // Gate requirements
   if (gateConfig) {
     lines.push('## Phase Exit Gate');
@@ -393,7 +418,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
       lines.push(`- **You are in the \`${currentPhase}\` phase (not final phase).** When your work is complete${gateClause}, set \`phase_transition_request: "${nextPhase}"\`.`);
     } else if (phaseIdx >= 0 && phaseIdx === phaseNames.length - 1) {
       lines.push(`- **You are in the \`${currentPhase}\` phase (final phase).** When ready to ship, set \`run_completion_request: true\` and \`phase_transition_request: null\`.`);
-      if (runtimeType === 'api_proxy') {
+      if (runtimeType === 'api_proxy' || runtimeType === 'remote_agent') {
         lines.push('- **Completion turns must be no-op:** set `proposed_changes` to `[]` or omit it, set `files_changed` to `[]`, and set `artifact.type` to `"review"`. Do NOT propose file changes on a completion turn.');
       }
     }
@@ -408,7 +433,7 @@ function renderPrompt(role, roleId, turn, state, config, root) {
       lines.push('- **If you found genuine blocking issues that prevent shipping:** set `status: "needs_human"` and explain the blockers in `needs_human_reason`.');
       lines.push('- Do NOT use `status: "needs_human"` to mean "human should approve the release." That is what `run_completion_request: true` is for.');
       lines.push('- Do NOT set `phase_transition_request` to the exit gate name.');
-      if (runtimeType === 'api_proxy') {
+      if (runtimeType === 'api_proxy' || runtimeType === 'remote_agent') {
         lines.push('- `run_completion_request: true` does **not** mean this runtime wrote `.planning/acceptance-matrix.md`, `.planning/ship-verdict.md`, or `.planning/RELEASE_NOTES.md` for you.');
       }
     }
@@ -421,6 +446,47 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   };
 }
 
+function getWorkflowPromptResponsibilities(config, phase, roleId, root) {
+  const artifacts = config?.workflow_kit?.phases?.[phase]?.artifacts;
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    return [];
+  }
+
+  const entryRole = config?.routing?.[phase]?.entry_role || null;
+  const responsibilities = [];
+
+  for (const artifact of artifacts) {
+    if (!artifact?.path) {
+      continue;
+    }
+
+    const owner = typeof artifact.owned_by === 'string' && artifact.owned_by
+      ? artifact.owned_by
+      : null;
+    const responsibleRole = owner || entryRole;
+    if (responsibleRole !== roleId) {
+      continue;
+    }
+
+    const absPath = join(root, artifact.path);
+    let exists = false;
+    try {
+      exists = existsSync(absPath);
+    } catch {
+      exists = false;
+    }
+
+    responsibilities.push({
+      path: artifact.path,
+      required: artifact.required !== false,
+      semantics: artifact.semantics || null,
+      status: exists ? 'exists' : 'MISSING',
+    });
+  }
+
+  return responsibilities;
+}
+
 // ── Context Rendering ───────────────────────────────────────────────────────
 
 function renderContext(state, config, root, turn, role) {
@@ -621,8 +687,59 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
-  // Phase gate requirements
+  // Workflow-kit artifacts for the current phase
   const phase = state.phase;
+  const wkArtifacts = config?.workflow_kit?.phases?.[phase]?.artifacts;
+  if (Array.isArray(wkArtifacts) && wkArtifacts.length > 0) {
+    lines.push('## Workflow Artifacts');
+    lines.push('');
+    lines.push(`Current phase **${phase}** declares the following artifacts:`);
+    lines.push('');
+    lines.push('| Artifact | Required | Semantics | Owner | Status |');
+    lines.push('|----------|----------|-----------|-------|--------|');
+    const isReviewRole = role?.write_authority === 'review_only';
+    const reviewPreviews = [];
+    for (const art of wkArtifacts) {
+      if (!art?.path) continue;
+      const absPath = join(root, art.path);
+      let exists = false;
+      try { exists = existsSync(absPath); } catch { /* treat as missing */ }
+      const req = art.required !== false ? 'yes' : 'no';
+      const owner = art.owned_by || '—';
+      const status = exists ? 'exists' : 'MISSING';
+      const semCol = art.semantics ? `\`${art.semantics}\`` : '—';
+      lines.push(`| \`${art.path}\` | ${req} | ${semCol} | ${owner} | ${status} |`);
+      if (isReviewRole && exists) {
+        reviewPreviews.push(art);
+      }
+    }
+    lines.push('');
+    if (reviewPreviews.length > 0) {
+      for (const art of reviewPreviews) {
+        const absPath = join(root, art.path);
+        const preview = buildGateFilePreview(absPath);
+        if (preview) {
+          lines.push(`### \`${art.path}\``);
+          lines.push('');
+          const semantic = extractGateFileSemantic(art.path, preview.raw);
+          if (semantic) {
+            lines.push(`**Semantic: ${semantic}**`);
+            lines.push('');
+          }
+          lines.push('```');
+          lines.push(preview.content);
+          lines.push('```');
+          if (preview.truncated) {
+            lines.push('');
+            lines.push(`_Preview truncated after ${GATE_FILE_PREVIEW_MAX_LINES} lines._`);
+          }
+          lines.push('');
+        }
+      }
+    }
+  }
+
+  // Phase gate requirements
   const routing = config.routing?.[phase];
   const exitGate = routing?.exit_gate;
   const gateConfig = exitGate ? config.gates?.[exitGate] : null;

package/src/lib/governed-state.js

@@ -139,7 +139,10 @@ function renderDerivedReviewArtifact(turnResult, state) {
 }
 
 function materializeDerivedReviewArtifact(root, turnResult, state, runtimeType, baseline = null) {
-  if (turnResult?.artifact?.type !== 'review' || runtimeType !== 'api_proxy') {
+  if (
+    turnResult?.artifact?.type !== 'review'
+    || (runtimeType !== 'api_proxy' && runtimeType !== 'remote_agent')
+  ) {
     return null;
   }
 
@@ -156,7 +159,10 @@ function materializeDerivedReviewArtifact(root, turnResult, state, runtimeType,
 }
 
 function materializeDerivedProposalArtifact(root, turnResult, state, runtimeType) {
-  if (turnResult?.artifact?.type !== 'patch' || runtimeType !== 'api_proxy') {
+  if (
+    turnResult?.artifact?.type !== 'patch'
+    || (runtimeType !== 'api_proxy' && runtimeType !== 'remote_agent')
+  ) {
     return null;
   }
   if (!Array.isArray(turnResult.proposed_changes) || turnResult.proposed_changes.length === 0) {

package/src/lib/normalized-config.js

@@ -17,7 +17,7 @@ import { validateNotificationsConfig } from './notification-runner.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
-const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp'];
+const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
 const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
@@ -157,6 +157,42 @@ function validateMcpRuntime(runtimeId, runtime, errors) {
   }
 }
 
+function validateRemoteAgentRuntime(runtimeId, runtime, errors) {
+  // url: required, absolute http(s)
+  if (typeof runtime?.url !== 'string' || !runtime.url.trim()) {
+    errors.push(`Runtime "${runtimeId}": remote_agent requires "url"`);
+  } else {
+    try {
+      const parsed = new URL(runtime.url);
+      if (!['http:', 'https:'].includes(parsed.protocol)) {
+        errors.push(`Runtime "${runtimeId}": remote_agent url must use http or https`);
+      }
+    } catch {
+      errors.push(`Runtime "${runtimeId}": remote_agent url must be a valid absolute URL`);
+    }
+  }
+
+  // headers: optional object of string values
+  if ('headers' in runtime) {
+    if (!runtime.headers || typeof runtime.headers !== 'object' || Array.isArray(runtime.headers)) {
+      errors.push(`Runtime "${runtimeId}": remote_agent headers must be an object of string values`);
+    } else {
+      for (const [key, value] of Object.entries(runtime.headers)) {
+        if (typeof value !== 'string') {
+          errors.push(`Runtime "${runtimeId}": remote_agent headers["${key}"] must be a string`);
+        }
+      }
+    }
+  }
+
+  // timeout_ms: optional positive integer
+  if ('timeout_ms' in runtime) {
+    if (!Number.isInteger(runtime.timeout_ms) || runtime.timeout_ms <= 0) {
+      errors.push(`Runtime "${runtimeId}": remote_agent timeout_ms must be a positive integer`);
+    }
+  }
+}
+
 function validateApiProxyRetryPolicy(runtimeId, retryPolicy, errors) {
   if (!retryPolicy || typeof retryPolicy !== 'object' || Array.isArray(retryPolicy)) {
     errors.push(`Runtime "${runtimeId}": retry_policy must be an object`);
@@ -391,6 +427,9 @@ export function validateV4Config(data, projectRoot) {
       if (rt.type === 'mcp') {
         validateMcpRuntime(id, rt, errors);
       }
+      if (rt.type === 'remote_agent') {
+        validateRemoteAgentRuntime(id, rt, errors);
+      }
     }
   }
 
@@ -412,11 +451,18 @@ export function validateV4Config(data, projectRoot) {
           errors.push(`Role "${id}" is review_only but uses local_cli runtime "${role.runtime}" — review_only roles should not have authoritative write access`);
         }
       }
-      // api_proxy restriction: only review_only and proposed roles may bind to api_proxy runtimes
+      // api_proxy and remote_agent restriction: only review_only and proposed roles may bind.
+      // These adapters do not have a proven local workspace mutation path in v1.
       if (role.runtime && data.runtimes[role.runtime]) {
         const rt = data.runtimes[role.runtime];
-        if (rt.type === 'api_proxy' && role.write_authority !== 'review_only' && role.write_authority !== 'proposed') {
-          errors.push(`Role "${id}" has write_authority "${role.write_authority}" but uses api_proxy runtime "${role.runtime}" — api_proxy only supports review_only and proposed roles`);
+        if (
+          (rt.type === 'api_proxy' || rt.type === 'remote_agent')
+          && role.write_authority !== 'review_only'
+          && role.write_authority !== 'proposed'
+        ) {
+          errors.push(
+            `Role "${id}" has write_authority "${role.write_authority}" but uses ${rt.type} runtime "${role.runtime}" — ${rt.type} only supports review_only and proposed roles`
+          );
         }
       }
     }
@@ -582,6 +628,25 @@ export function validateWorkflowKitConfig(wk, routing, roles) {
             errors.push(`${prefix} owned_by "${artifact.owned_by}" is not a valid role ID (must be lowercase alphanumeric with hyphens/underscores)`);
           } else if (roles && typeof roles === 'object' && !roles[artifact.owned_by]) {
             errors.push(`${prefix} owned_by "${artifact.owned_by}" does not reference a defined role`);
+          } else if (
+            artifact.required !== false &&
+            roles && typeof roles === 'object' &&
+            roles[artifact.owned_by]?.write_authority === 'review_only'
+          ) {
+            // Check if any authoritative/proposed role exists in this phase's routing
+            const phaseRouting = routing?.[phase];
+            const phaseRoles = new Set([
+              ...(phaseRouting?.allowed_next_roles || []),
+              ...(phaseRouting?.entry_role ? [phaseRouting.entry_role] : []),
+            ]);
+            const hasWriter = [...phaseRoles].some(rid =>
+              roles[rid]?.write_authority === 'authoritative' || roles[rid]?.write_authority === 'proposed',
+            );
+            if (!hasWriter) {
+              warnings.push(
+                `${prefix} owned_by "${artifact.owned_by}" is a review_only role in phase "${phase}" with no authoritative or proposed role — nobody can write this required artifact`,
+              );
+            }
           }
         }
       }

package/src/lib/turn-result-validator.js

@@ -387,14 +387,14 @@ function validateArtifact(tr, config) {
     warnings.push('Authoritative role completed with no files_changed — is this intentional?');
   }
 
-  // Validate proposed_changes for proposed + api_proxy turns
+  // Validate proposed_changes for proposed runtimes that cannot write repo files directly.
   const runtimeType = config.runtimes?.[tr.runtime_id]?.type;
-  if (writeAuthority === 'proposed' && runtimeType === 'api_proxy') {
+  if (writeAuthority === 'proposed' && (runtimeType === 'api_proxy' || runtimeType === 'remote_agent')) {
     // Completion-request turns are explicitly allowed to have empty proposed_changes —
     // the turn is signaling run completion, not delivering work.
     const isCompletionRequest = tr.run_completion_request === true;
     if (tr.status === 'completed' && (!tr.proposed_changes || tr.proposed_changes.length === 0) && !isCompletionRequest) {
-      errors.push('Proposed api_proxy turn completed but proposed_changes is empty or missing.');
+      errors.push(`Proposed ${runtimeType} turn completed but proposed_changes is empty or missing.`);
     }
   }
   if (tr.proposed_changes && Array.isArray(tr.proposed_changes)) {