agentxchain 2.103.0 → 2.105.0

package/README.md

@@ -17,7 +17,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 - [Templates](https://agentxchain.dev/docs/templates/)
 - [Export schema reference](https://agentxchain.dev/docs/export-schema/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
-- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
+- [Protocol v7](https://agentxchain.dev/docs/protocol/)
 - [Protocol reference](https://agentxchain.dev/docs/protocol-reference/)
 - [Build your own runner](https://agentxchain.dev/docs/build-your-own-runner/)
 - [Why governed multi-agent delivery matters](https://agentxchain.dev/why/)
@@ -173,16 +173,17 @@ agentxchain step
 | `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
 | `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
 | `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 |
+| `dashboard` | Open the live local governance dashboard in your browser for the current repo/workspace or multi-repo coordinator initiative, including pending gate approvals |
 | `run [--auto-approve] [--max-turns N] [--dry-run]` | Drive a governed run from start to completion — dispatches turns, handles gates, manages rejection/retry |
 
 ### Governed proof and inspection
 
 | Command | What it does |
 |---|---|
-| `audit [--format json]` | Live governance audit report with cost summary, decision history, and artifact inventory |
+| `audit [--format json]` | Live governance audit report for the current repo/workspace with cost summary, decision history, and artifact inventory |
 | `diff <left> <right>` | Compare two governed runs side by side (phase, decisions, artifacts, timing) |
-| `report` | Generate a governance report for the current run |
+| `report` | Generate a governance report from a verified export artifact (`--input <path>` or stdin) |
+| `replay export <export-file>` | Open an existing verified export artifact in the read-only dashboard for offline post-mortem inspection |
 | `events [--type <type>] [--limit N]` | Inspect the lifecycle event stream (turns, phases, gates, governance events) |
 | `history [--limit N] [--role <role>]` | Query accepted-turn history from append-only JSONL |
 | `role list\|show` | List all configured roles or inspect a single role's charter, runtime, and phase assignment |
@@ -192,6 +193,8 @@ agentxchain step
 | `doctor [--json]` | Governed project health check: config, roles, runtimes, state, schedules, plugins, workflow-kit, connector handoff |
 | `connector check [--json]` | Live health probes for all configured connectors (api_proxy, remote_agent, MCP stdio/streamable_http) |
 
+Partial coordinator artifacts are first-class here too: `audit` and `report` keep repo rows plus `repo_ok_count` / `repo_error_count` export-health totals when a child export fails, and they do not fabricate child drill-down for the failed repo.
+
 ### Governed automation, plugins, and continuity
 
 | Command | What it does |
@@ -202,10 +205,12 @@ agentxchain step
 | `schedule list\|run-due\|daemon\|status` | Run repo-local lights-out scheduling: inspect schedules, execute due runs, poll in a local daemon loop, or check daemon heartbeat |
 | `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins under `.agentxchain/plugins/` |
 | `plugin list-available` | List bundled built-in plugins installable by short name |
-| `export [--output <path>]` | Export run state for cross-machine continuity |
+| `export [--output <path>]` | Export the portable raw governed/coordinator artifact for continuity or offline review |
 | `restore --input <path>` | Restore run state from a prior export on a same-repo, same-commit checkout |
 | `restart` | Rebuild lost session context from `.agentxchain/session.json` |
 
+`dashboard` and `audit` read the live current repo/workspace. `report --input` and `replay export` read an existing verified export artifact instead: `report` renders a derived summary, while `replay export` opens the read-only dashboard. Partial coordinator artifacts remain first-class here too: `report` and `replay export` keep repo rows plus `repo_ok_count` / `repo_error_count` export-health totals when a child export fails, and they do not fabricate child drill-down for the failed repo.
+
 ### Shared utilities
 
 | Command | What it does |
@@ -224,7 +229,7 @@ agentxchain step
 | `supervise` | Run `watch` plus optional macOS auto-nudge |
 | `claim` / `release` | Human override of legacy lock ownership |
 | `rebind` | Rebuild Cursor bindings |
-| `generate` | Regenerate VS Code agent files |
+| `generate` | Regenerate VS Code agent files; use `generate planning` to restore scaffold-owned governed planning docs |
 | `branch` | Manage Cursor branch override for launches |
 | `doctor` | Check local environment and setup |
 | `stop` | Stop watch daemon and local sessions |
@@ -273,6 +278,7 @@ The first-party governed workflow kit includes `.planning/SYSTEM_SPEC.md` alongs
 - `local_cli`: implemented
 - `mcp`: implemented for stdio and streamable HTTP tool-contract dispatch
 - `api_proxy`: implemented for synchronous `review_only` and `proposed` write-authority turns; stages a provider-backed result during `step`
+- `remote_agent`: implemented for governed HTTP request/response dispatch against long-running remote agents
 
 ## Legacy IDE Mode
 
@@ -309,7 +315,7 @@ Requires:
 - [Quickstart](https://agentxchain.dev/docs/quickstart/)
 - [CLI reference](https://agentxchain.dev/docs/cli/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
-- [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
+- [Protocol v7](https://agentxchain.dev/docs/protocol/)
 - [GitHub](https://github.com/shivamtiwari93/agentXchain.dev)
 - [Legacy Protocol v3 spec](https://github.com/shivamtiwari93/agentXchain.dev/blob/main/PROTOCOL-v3.md)
 

package/bin/agentxchain.js

@@ -55,7 +55,7 @@ import { configCommand } from '../src/commands/config.js';
 import { updateCommand } from '../src/commands/update.js';
 import { watchCommand } from '../src/commands/watch.js';
 import { claimCommand, releaseCommand } from '../src/commands/claim.js';
-import { generateCommand } from '../src/commands/generate.js';
+import { generateCommand, generatePlanningCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
@@ -153,14 +153,14 @@ program
 
 program
   .command('export')
-  .description('Export the governed run audit surface as a single artifact')
+  .description('Write a portable governed/coordinator export artifact from the current repo/workspace')
   .option('--format <format>', 'Export format (json)', 'json')
   .option('--output <path>', 'Write the export artifact to a file instead of stdout')
   .action(exportCommand);
 
 program
   .command('audit')
-  .description('Render a governance audit directly from the current governed project or coordinator workspace')
+  .description('Render a governance audit from the live current repo/workspace')
   .option('--format <format>', 'Output format: text, json, markdown, or html', 'text')
   .action(auditCommand);
 
@@ -178,7 +178,7 @@ program
 
 program
   .command('report')
-  .description('Render a human-readable governance summary from an export artifact')
+  .description('Render a governance summary from an existing verified export artifact')
   .option('--input <path>', 'Export artifact path, or "-" for stdin', '-')
   .option('--format <format>', 'Output format: text, json, markdown, or html', 'text')
   .action(reportCommand);
@@ -223,11 +223,19 @@ program
   .option('--unset', 'Remove override and follow the active git branch automatically')
   .action(branchCommand);
 
-program
+const generateCmd = program
   .command('generate')
-  .description('Regenerate VS Code agent files (.agent.md, hooks) from agentxchain.json')
+  .description('Regenerate VS Code agent files, or governed planning artifacts via subcommands')
   .action(generateCommand);
 
+generateCmd
+  .command('planning')
+  .description('Generate or restore scaffold-owned governed planning artifacts')
+  .option('--dry-run', 'Show which planning artifacts would be written without changing files')
+  .option('--force', 'Overwrite existing scaffold-owned planning artifacts')
+  .option('-j, --json', 'Output as JSON')
+  .action(generatePlanningCommand);
+
 program
   .command('watch')
   .description('Watch lock.json and coordinate agent turns (the referee)')
@@ -441,7 +449,7 @@ replayCmd
 
 replayCmd
   .command('export <export-file>')
-  .description('Browse a completed export in the dashboard for offline post-mortem analysis')
+  .description('Open an existing export artifact in the read-only dashboard')
   .option('-j, --json', 'Output session info as JSON')
   .option('--port <port>', 'Dashboard port', '3847')
   .option('--no-open', 'Do not auto-open browser')
@@ -522,7 +530,7 @@ program
 
 program
   .command('dashboard')
-  .description('Open the read-only governance dashboard in your browser')
+  .description('Open the live governance dashboard for the current repo/workspace')
   .option('--port <port>', 'Server port', '3847')
   .option('--daemon', 'Run the dashboard in background mode')
   .option('--no-open', 'Do not auto-open the browser')

package/dashboard/app.js

@@ -18,15 +18,20 @@ import { render as renderArtifacts } from './components/artifacts.js';
 import { render as renderRunHistory } from './components/run-history.js';
 import { render as renderTimeouts } from './components/timeouts.js';
 import { render as renderCoordinatorTimeouts } from './components/coordinator-timeouts.js';
+import {
+  buildLiveMeta,
+  createLiveEventFromMessage,
+  shouldRefreshViewForLiveMessage,
+} from './live-observer.js';
 
 const VIEWS = {
   timeline: { fetch: ['state', 'continuity', 'history', 'audit', 'annotations', 'connectors', 'coordinatorAudit', 'coordinatorAnnotations'], render: renderTimeline },
   delegations: { fetch: ['state', 'history'], render: renderDelegations },
-  ledger: { fetch: ['state', 'ledger', 'coordinatorState', 'coordinatorLedger'], render: renderLedger },
+  ledger: { fetch: ['state', 'ledger', 'coordinatorState', 'coordinatorLedger', 'repoDecisionsSummary'], render: renderLedger },
   hooks: { fetch: ['audit', 'annotations', 'coordinatorAudit', 'coordinatorAnnotations'], render: renderHooks },
-  blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit'], render: renderBlocked },
+  blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit', 'coordinatorBlockers', 'coordinatorRepoStatusRows'], render: renderBlocked },
   gate: { fetch: ['state', 'history', 'coordinatorState', 'coordinatorHistory', 'coordinatorBarriers'], render: renderGate },
-  initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger', 'coordinatorBlockers'], render: renderInitiative },
+  initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger', 'coordinatorBlockers', 'coordinatorRepoStatusRows'], render: renderInitiative },
   'cross-repo': { fetch: ['coordinatorState', 'coordinatorHistory'], render: renderCrossRepo },
   blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
   artifacts: { fetch: ['workflowKitArtifacts'], render: renderArtifacts },
@@ -40,6 +45,7 @@ const API_MAP = {
   continuity: '/api/continuity',
   history: '/api/history',
   ledger: '/api/ledger',
+  repoDecisionsSummary: '/api/repo-decisions-summary',
   coordinatorLedger: '/api/coordinator/ledger',
   audit: '/api/hooks/audit',
   annotations: '/api/hooks/annotations',
@@ -50,6 +56,7 @@ const API_MAP = {
   coordinatorAudit: '/api/coordinator/hooks/audit',
   coordinatorAnnotations: '/api/coordinator/hooks/annotations',
   coordinatorBlockers: '/api/coordinator/blockers',
+  coordinatorRepoStatusRows: '/api/coordinator/repo-status',
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
   connectors: '/api/connectors',
   runHistory: '/api/run-history',
@@ -76,6 +83,12 @@ let activeViewName = null;
 let activeViewData = null;
 let dashboardSession = null;
 let actionInFlight = false;
+const liveObserverState = {
+  connected: false,
+  lastRefreshAt: null,
+  lastRunEvent: null,
+  lastCoordinatorEvent: null,
+};
 
 function escapeHtml(str) {
   if (str == null) return '';
@@ -132,19 +145,40 @@ async function pickInitialView() {
 }
 
 function buildRenderData(viewName, data) {
+  const liveMeta = viewName === 'timeline'
+    ? buildLiveMeta({
+      connected: liveObserverState.connected,
+      lastRefreshAt: liveObserverState.lastRefreshAt,
+      lastEvent: liveObserverState.lastRunEvent,
+      scope: 'run',
+    })
+    : viewName === 'cross-repo'
+      ? buildLiveMeta({
+        connected: liveObserverState.connected,
+        lastRefreshAt: liveObserverState.lastRefreshAt,
+        lastEvent: liveObserverState.lastCoordinatorEvent,
+        scope: 'coordinator',
+      })
+      : null;
+
   if (viewName === 'ledger') {
     return {
       ...data,
       filter: viewState.ledger,
+      liveMeta,
     };
   }
   if (viewName === 'hooks') {
     return {
       ...data,
       filter: viewState.hooks,
+      liveMeta,
     };
   }
-  return data;
+  return {
+    ...data,
+    liveMeta,
+  };
 }
 
 function renderView(viewName, data) {
@@ -172,6 +206,51 @@ function setActionBanner(message, tone = 'info') {
   banner.className = `action-banner visible ${tone === 'error' ? 'error' : tone === 'success' ? 'success' : ''}`.trim();
 }
 
+function formatActionErrorMessage(payload, status) {
+  if (!payload || typeof payload !== 'object') {
+    return `Dashboard action failed with HTTP ${status}.`;
+  }
+
+  const parts = [];
+  if (typeof payload.error === 'string' && payload.error.trim()) {
+    parts.push(payload.error.trim());
+  } else {
+    parts.push(`Dashboard action failed with HTTP ${status}.`);
+  }
+
+  const detail = payload.recovery_summary?.detail;
+  if (typeof detail === 'string' && detail.trim()) {
+    parts.push(detail.trim());
+  }
+
+  const nextAction = payload.next_actions?.[0]?.command || payload.next_action || null;
+  if (typeof nextAction === 'string' && nextAction.trim()) {
+    parts.push(`Next: ${nextAction.trim()}`);
+  }
+
+  return parts.join(' ');
+}
+
+function formatActionSuccessMessage(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return 'Gate approved.';
+  }
+
+  const parts = [];
+  if (typeof payload.message === 'string' && payload.message.trim()) {
+    parts.push(payload.message.trim());
+  } else {
+    parts.push('Gate approved.');
+  }
+
+  const nextAction = payload.next_actions?.[0]?.command || payload.next_action || null;
+  if (typeof nextAction === 'string' && nextAction.trim()) {
+    parts.push(`Next: ${nextAction.trim()}`);
+  }
+
+  return parts.join(' ');
+}
+
 async function loadView(viewName, { refresh = true } = {}) {
   const view = VIEWS[viewName];
   if (!view) {
@@ -183,11 +262,17 @@ async function loadView(viewName, { refresh = true } = {}) {
   activeViewName = viewName;
   if (shouldRefetch) {
     activeViewData = await fetchData(view.fetch);
+    liveObserverState.lastRefreshAt = new Date().toISOString();
   }
 
   renderView(viewName, activeViewData);
 }
 
+function rerenderActiveView() {
+  if (!activeViewName) return;
+  renderView(activeViewName, activeViewData);
+}
+
 // ── WebSocket connection ──────────────────────────────────────────────────
 
 let ws = null;
@@ -204,13 +289,30 @@ function connect() {
     statusDot.classList.remove('disconnected');
     statusLabel.textContent = 'Connected';
     reconnectDelay = 1000;
+    liveObserverState.connected = true;
     loadView(currentView());
   };
 
   ws.onmessage = (event) => {
     try {
       const msg = JSON.parse(event.data);
-      if (msg.type === 'invalidate') {
+      if (msg.type === 'event') {
+        liveObserverState.lastRunEvent = createLiveEventFromMessage(msg);
+        rerenderActiveView();
+        return;
+      }
+
+      if (msg.type === 'coordinator_event') {
+        liveObserverState.lastCoordinatorEvent = createLiveEventFromMessage(msg);
+        if (shouldRefreshViewForLiveMessage(currentView(), msg.type)) {
+          loadView(currentView());
+        } else {
+          rerenderActiveView();
+        }
+        return;
+      }
+
+      if (shouldRefreshViewForLiveMessage(currentView(), msg.type)) {
         loadView(currentView());
       }
     } catch {}
@@ -219,6 +321,8 @@ function connect() {
   ws.onclose = () => {
     statusDot.classList.add('disconnected');
     statusLabel.textContent = 'Disconnected';
+    liveObserverState.connected = false;
+    rerenderActiveView();
     setTimeout(() => {
       reconnectDelay = Math.min(reconnectDelay * 2, 30000);
       connect();
@@ -344,11 +448,11 @@ document.addEventListener('click', async (event) => {
     }));
 
     if (!res.ok || payload.ok === false) {
-      setActionBanner(payload.error || `Dashboard action failed with HTTP ${res.status}.`, 'error');
+      setActionBanner(formatActionErrorMessage(payload, res.status), 'error');
       return;
     }
 
-    setActionBanner(payload.message || 'Gate approved.', 'success');
+    setActionBanner(formatActionSuccessMessage(payload), 'success');
     await loadView(currentView());
   } catch (error) {
     setActionBanner(error?.message || 'Dashboard action failed.', 'error');

package/dashboard/components/blocked.js

@@ -1,3 +1,6 @@
+import { getCoordinatorPendingGateDetails } from '../../src/lib/coordinator-pending-gate-presentation.js';
+import { buildCoordinatorRepoStatusRows } from '../../src/lib/coordinator-repo-status-presentation.js';
+
 /**
  * Blocked State view — renders current blocked state with recovery info.
  *
@@ -23,6 +26,18 @@ function getHookName(entry) {
   return entry?.hook_name || entry?.hook || entry?.name || '';
 }
 
+function renderDetailRows(details) {
+  if (!Array.isArray(details) || details.length === 0) {
+    return '';
+  }
+
+  let html = '';
+  for (const detail of details) {
+    html += `<dt>${esc(detail.label)}</dt><dd${detail.mono ? ' class="mono"' : ''}>${esc(detail.value)}</dd>`;
+  }
+  return html;
+}
+
 function selectRelevantAuditEntries(state, audit) {
   if (!Array.isArray(audit) || audit.length === 0) {
     return [];
@@ -55,7 +70,36 @@ function selectRelevantAuditEntries(state, audit) {
   return audit.slice(-3);
 }
 
-export function render({ state, audit = [], coordinatorState = null, coordinatorAudit = [] }) {
+function getCoordinatorRepoRows(coordinatorState, coordinatorRepoStatusRows) {
+  if (Array.isArray(coordinatorRepoStatusRows) && coordinatorRepoStatusRows.length > 0) {
+    return coordinatorRepoStatusRows;
+  }
+
+  return buildCoordinatorRepoStatusRows({
+    config: null,
+    coordinatorRepoRuns: coordinatorState?.repo_runs || {},
+  });
+}
+
+function formatCoordinatorRepoCardMeta(row) {
+  const parts = [];
+  if (row?.run_id) {
+    parts.push(`run ${row.run_id}`);
+  }
+  for (const detail of Array.isArray(row?.details) ? row.details : []) {
+    parts.push(`${detail.label}: ${detail.value}`);
+  }
+  return parts.join(' | ') || '-';
+}
+
+export function render({
+  state,
+  audit = [],
+  coordinatorState = null,
+  coordinatorAudit = [],
+  coordinatorBlockers = null,
+  coordinatorRepoStatusRows = null,
+}) {
   const activeState = state?.status === 'blocked' ? state : coordinatorState;
   const activeAudit = activeState === state ? audit : coordinatorAudit;
   const isCoordinator = activeState === coordinatorState;
@@ -75,6 +119,26 @@ export function render({ state, audit = [], coordinatorState = null, coordinator
   const typedReason = recovery.typed_reason || null;
   const turnRetained = typeof recovery.turn_retained === 'boolean' ? recovery.turn_retained : null;
   const blockedAt = blocked.blocked_at || null;
+  const runtimeGuidance = Array.isArray(activeState.runtime_guidance) ? activeState.runtime_guidance : [];
+  const coordinatorNextActions = coordinatorBlockers?.ok === false
+    ? []
+    : Array.isArray(coordinatorBlockers?.next_actions)
+      ? coordinatorBlockers.next_actions
+      : [];
+  const nextActions = isCoordinator
+    ? coordinatorNextActions
+    : Array.isArray(activeState.next_actions)
+      ? activeState.next_actions
+      : [];
+  const coordinatorPendingGateDetails = isCoordinator
+    ? getCoordinatorPendingGateDetails({
+      pendingGate: activeState.pending_gate,
+      active: coordinatorBlockers?.active,
+    })
+    : [];
+  const coordinatorRepoRows = isCoordinator
+    ? getCoordinatorRepoRows(coordinatorState, coordinatorRepoStatusRows)
+    : [];
   const relevantAudit = selectRelevantAuditEntries(activeState, activeAudit);
 
   let html = `<div class="blocked-view">
@@ -104,22 +168,42 @@ export function render({ state, audit = [], coordinatorState = null, coordinator
     </div>`;
   }
 
-  if (isCoordinator && activeState.pending_gate) {
+  if (runtimeGuidance.length > 0) {
+    html += `<div class="section"><h3>Runtime Guidance</h3><div class="annotation-list">`;
+    for (const entry of runtimeGuidance) {
+      html += `<div class="annotation-card">
+        <span class="mono">${esc(entry.code || '-')}</span>
+        <span class="mono">${esc(entry.command || '-')}</span>
+        <span>${esc(entry.reason || '-')}</span>
+      </div>`;
+    }
+    html += `</div></div>`;
+  }
+
+  if (nextActions.length > 0) {
+    html += `<div class="section"><h3>Next Actions</h3><div class="annotation-list">`;
+    for (const action of nextActions) {
+      html += `<div class="annotation-card">
+        <span class="mono">${esc(action.command || '-')}</span>
+        <span>${esc(action.reason || '-')}</span>
+      </div>`;
+    }
+    html += `</div></div>`;
+  }
+
+  if (isCoordinator && coordinatorPendingGateDetails.length > 0) {
     html += `<div class="section"><h3>Pending Gate</h3>
-      <dl class="detail-list">
-        <dt>Gate</dt><dd class="mono">${esc(activeState.pending_gate.gate || '-')}</dd>
-        <dt>Type</dt><dd>${esc(activeState.pending_gate.gate_type || '-')}</dd>
-      </dl>
-      <pre class="recovery-command mono" data-copy="agentxchain multi approve-gate">agentxchain multi approve-gate</pre>
+      <dl class="detail-list">${renderDetailRows(coordinatorPendingGateDetails)}</dl>
     </div>`;
   }
 
-  if (isCoordinator && activeState.repo_runs && Object.keys(activeState.repo_runs).length > 0) {
+  if (isCoordinator && coordinatorRepoRows.length > 0) {
     html += `<div class="section"><h3>Repo Status</h3><div class="annotation-list">`;
-    for (const [repoId, repoRun] of Object.entries(activeState.repo_runs)) {
+    for (const row of coordinatorRepoRows) {
       html += `<div class="annotation-card">
-        <span class="mono">${esc(repoId)}</span>
-        <span>${esc(`${repoRun.status || 'unknown'}${repoRun.phase ? ` [${repoRun.phase}]` : ''}`)}</span>
+        <span class="mono">${esc(row.repo_id || '-')}</span>
+        <span>${esc(`${row.status || 'unknown'}${row.phase ? ` [${row.phase}]` : ''}`)}</span>
+        <span>${esc(formatCoordinatorRepoCardMeta(row))}</span>
       </div>`;
     }
     html += `</div></div>`;