agentxchain 2.87.0 → 2.89.0

package/dashboard/app.js

@@ -12,6 +12,7 @@ import { render as renderBlocked } from './components/blocked.js';
 import { render as renderGate } from './components/gate.js';
 import { render as renderInitiative } from './components/initiative.js';
 import { render as renderCrossRepo } from './components/cross-repo.js';
+import { render as renderDelegations } from './components/delegations.js';
 import { render as renderBlockers } from './components/blockers.js';
 import { render as renderArtifacts } from './components/artifacts.js';
 import { render as renderRunHistory } from './components/run-history.js';
@@ -20,6 +21,7 @@ import { render as renderCoordinatorTimeouts } from './components/coordinator-ti
 
 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 },
   hooks: { fetch: ['audit', 'annotations', 'coordinatorAudit', 'coordinatorAnnotations'], render: renderHooks },
   blocked: { fetch: ['state', 'audit', 'coordinatorState', 'coordinatorAudit'], render: renderBlocked },

package/dashboard/components/delegations.js

@@ -0,0 +1,237 @@
+function esc(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function statusColor(status) {
+  const colors = {
+    pending: 'var(--text-dim)',
+    active: 'var(--yellow)',
+    completed: 'var(--green)',
+    failed: 'var(--red)',
+    review_pending: 'var(--yellow)',
+    reviewed: 'var(--accent)',
+    unknown: 'var(--text-dim)',
+  };
+  return colors[status] || 'var(--text-dim)';
+}
+
+function summarizeReview(results) {
+  const counts = { completed: 0, failed: 0, other: 0 };
+  for (const result of results || []) {
+    if (result?.status === 'completed') counts.completed += 1;
+    else if (result?.status === 'failed') counts.failed += 1;
+    else counts.other += 1;
+  }
+  return counts;
+}
+
+function normalizeDelegationChain(parentEntry, state, history) {
+  const issued = Array.isArray(parentEntry?.delegations_issued) ? parentEntry.delegations_issued : [];
+  const pendingQueue = Array.isArray(state?.delegation_queue)
+    ? state.delegation_queue.filter((entry) => entry.parent_turn_id === parentEntry.turn_id)
+    : [];
+  const pendingReview = state?.pending_delegation_review?.parent_turn_id === parentEntry.turn_id
+    ? state.pending_delegation_review
+    : null;
+  const reviewEntry = Array.isArray(history)
+    ? history.find((entry) => entry?.delegation_review?.parent_turn_id === parentEntry.turn_id)
+    : null;
+
+  const delegations = issued.map((item) => {
+    const queueEntry = pendingQueue.find((entry) => entry.delegation_id === item.id) || null;
+    const reviewResult = Array.isArray(pendingReview?.delegation_results)
+      ? pendingReview.delegation_results.find((entry) => entry.delegation_id === item.id)
+      : null;
+    const reviewHistoryResult = Array.isArray(reviewEntry?.delegation_review?.results)
+      ? reviewEntry.delegation_review.results.find((entry) => entry.delegation_id === item.id)
+      : null;
+    const childTurn = Array.isArray(history)
+      ? history.find((entry) => entry?.delegation_context?.delegation_id === item.id)
+      : null;
+
+    return {
+      delegation_id: item.id,
+      to_role: item.to_role,
+      charter: item.charter,
+      acceptance_contract: Array.isArray(item.acceptance_contract) ? item.acceptance_contract : [],
+      status: queueEntry?.status
+        || reviewResult?.status
+        || reviewHistoryResult?.status
+        || childTurn?.status
+        || 'unknown',
+      child_turn_id: queueEntry?.child_turn_id
+        || reviewResult?.child_turn_id
+        || reviewHistoryResult?.child_turn_id
+        || childTurn?.turn_id
+        || null,
+      summary: reviewResult?.summary
+        || reviewHistoryResult?.summary
+        || childTurn?.summary
+        || null,
+      files_changed: reviewResult?.files_changed
+        || reviewHistoryResult?.files_changed
+        || childTurn?.files_changed
+        || [],
+    };
+  });
+
+  let chainStatus = 'unknown';
+  if (pendingReview) chainStatus = 'review_pending';
+  else if (pendingQueue.length > 0) chainStatus = delegations.some((entry) => entry.status === 'active') ? 'active' : 'pending';
+  else if (reviewEntry) chainStatus = 'reviewed';
+  else if (delegations.length > 0) chainStatus = delegations.every((entry) => entry.status === 'completed' || entry.status === 'failed') ? 'reviewed' : 'unknown';
+
+  return {
+    parent_turn_id: parentEntry.turn_id,
+    parent_role: parentEntry.role,
+    parent_summary: parentEntry.summary || '(no summary)',
+    accepted_at: parentEntry.accepted_at || null,
+    status: chainStatus,
+    delegations,
+    pending_review: pendingReview,
+    review_entry: reviewEntry,
+  };
+}
+
+function renderAcceptanceContract(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return '<span class="turn-detail">No acceptance contract recorded.</span>';
+  }
+  return `<ul>${items.map((item) => `<li>${esc(item)}</li>`).join('')}</ul>`;
+}
+
+function renderChainCard(chain) {
+  const reviewResults = chain.pending_review?.delegation_results
+    || chain.review_entry?.delegation_review?.results
+    || [];
+  const reviewCounts = summarizeReview(reviewResults);
+
+  let html = `<div class="turn-card">
+    <div class="turn-header">
+      ${badge(chain.parent_role || 'unknown', '#fb923c')}
+      <span class="mono">${esc(chain.parent_turn_id)}</span>
+      ${badge(chain.status.replace(/_/g, ' '), statusColor(chain.status))}
+    </div>
+    <div class="turn-summary">${esc(chain.parent_summary)}</div>`;
+
+  if (chain.accepted_at) {
+    html += `<div class="turn-detail"><span class="detail-label">Accepted:</span> ${esc(chain.accepted_at)}</div>`;
+  }
+
+  html += `<div class="turn-detail"><span class="detail-label">Delegations:</span> ${esc(chain.delegations.length)}</div>`;
+
+  if (chain.delegations.length > 0) {
+    html += `<div class="turn-list">`;
+    for (const delegation of chain.delegations) {
+      html += `<div class="turn-card">
+        <div class="turn-header">
+          <span class="mono">${esc(delegation.delegation_id)}</span>
+          ${badge(delegation.to_role || 'unknown', '#38bdf8')}
+          ${badge(delegation.status, statusColor(delegation.status))}
+        </div>
+        <div class="turn-detail"><span class="detail-label">Charter:</span> ${esc(delegation.charter || '(none)')}</div>
+        <div class="turn-detail"><span class="detail-label">Acceptance Contract:</span>${renderAcceptanceContract(delegation.acceptance_contract)}</div>`;
+      if (delegation.child_turn_id) {
+        html += `<div class="turn-detail"><span class="detail-label">Child Turn:</span> <span class="mono">${esc(delegation.child_turn_id)}</span></div>`;
+      }
+      if (delegation.summary) {
+        html += `<div class="turn-detail"><span class="detail-label">Outcome:</span> ${esc(delegation.summary)}</div>`;
+      }
+      if (Array.isArray(delegation.files_changed) && delegation.files_changed.length > 0) {
+        html += `<div class="turn-detail"><span class="detail-label">Files:</span> <span class="mono">${delegation.files_changed.map((item) => esc(item)).join(', ')}</span></div>`;
+      }
+      html += `</div>`;
+    }
+    html += `</div>`;
+  }
+
+  if (chain.pending_review) {
+    html += `<div class="turn-detail"><span class="detail-label">Review Pending:</span> ${esc(chain.pending_review.parent_role)} is reviewing ${reviewResults.length} delegated result${reviewResults.length === 1 ? '' : 's'}.</div>`;
+  } else if (chain.review_entry) {
+    html += `<div class="turn-detail"><span class="detail-label">Review Turn:</span> <span class="mono">${esc(chain.review_entry.turn_id)}</span></div>`;
+  }
+
+  if (reviewResults.length > 0) {
+    html += `<div class="turn-detail"><span class="detail-label">Review Summary:</span> ${reviewCounts.completed} completed, ${reviewCounts.failed} failed</div>`;
+  }
+
+  html += `</div>`;
+  return html;
+}
+
+export function render({ state, history }) {
+  if (!state) {
+    return `<div class="placeholder"><h2>No Run</h2><p>No governed run found. Start one with <code class="mono">agentxchain init --governed</code></p></div>`;
+  }
+
+  const historyEntries = Array.isArray(history) ? history : [];
+  const parentTurns = historyEntries
+    .filter((entry) => Array.isArray(entry?.delegations_issued) && entry.delegations_issued.length > 0)
+    .reverse();
+  const chains = parentTurns.map((entry) => normalizeDelegationChain(entry, state, historyEntries));
+  const queue = Array.isArray(state.delegation_queue) ? state.delegation_queue : [];
+  const pendingReview = state.pending_delegation_review || null;
+
+  if (chains.length === 0 && queue.length === 0 && !pendingReview) {
+    return `<div class="placeholder"><h2>No Delegations</h2><p>This run has no delegation chains yet. Delegation state will appear here once a turn emits a <code class="mono">delegations</code> array.</p></div>`;
+  }
+
+  let html = `<div class="delegations-view">`;
+
+  html += `<div class="run-header">
+    <div class="run-meta">
+      <span class="mono run-id">${esc(state.run_id || 'unknown')}</span>
+      ${badge(state.status || 'unknown', statusColor(state.status || 'unknown'))}
+      <span class="phase-label">Phase: <strong>${esc(state.phase || 'unknown')}</strong></span>
+      <span class="turn-count">${chains.length} chain${chains.length === 1 ? '' : 's'} recorded</span>
+    </div>
+  </div>`;
+
+  if (queue.length > 0 || pendingReview) {
+    html += `<div class="section"><h3>Live Delegation State</h3><div class="turn-list">`;
+    if (queue.length > 0) {
+      html += `<div class="turn-card">
+        <div class="turn-header">
+          <span class="mono">delegation_queue</span>
+          ${badge(`${queue.length} item${queue.length === 1 ? '' : 's'}`, statusColor('pending'))}
+        </div>`;
+      for (const entry of queue) {
+        html += `<div class="turn-detail"><span class="detail-label">${esc(entry.delegation_id)}:</span> ${esc(entry.parent_role || 'unknown')} → ${esc(entry.to_role || 'unknown')} (${esc(entry.status || 'unknown')})</div>`;
+      }
+      html += `</div>`;
+    }
+    if (pendingReview) {
+      const counts = summarizeReview(pendingReview.delegation_results);
+      html += `<div class="turn-card">
+        <div class="turn-header">
+          <span class="mono">${esc(pendingReview.parent_turn_id)}</span>
+          ${badge('review pending', statusColor('review_pending'))}
+        </div>
+        <div class="turn-detail"><span class="detail-label">Parent Role:</span> ${esc(pendingReview.parent_role || 'unknown')}</div>
+        <div class="turn-detail"><span class="detail-label">Results:</span> ${counts.completed} completed, ${counts.failed} failed</div>
+      </div>`;
+    }
+    html += `</div></div>`;
+  }
+
+  html += `<div class="section"><h3>Delegation Chains</h3>`;
+  if (chains.length === 0) {
+    html += `<div class="placeholder compact"><p>No completed delegation chains recorded yet.</p></div>`;
+  } else {
+    html += `<div class="turn-list">${chains.map((chain) => renderChainCard(chain)).join('')}</div>`;
+  }
+  html += `</div>`;
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/components/timeline.js

@@ -187,6 +187,23 @@ function renderTurnDetailPanel(turnId, annotations, audit, coordinatorAnnotation
   return html;
 }
 
+function renderDelegationIssued(entry) {
+  const issued = Array.isArray(entry?.delegations_issued) ? entry.delegations_issued : [];
+  if (issued.length === 0) return '';
+  return `<div class="turn-detail"><span class="detail-label">Delegated:</span> ${issued.map((item) => `${esc(item.id)} → ${esc(item.to_role)}`).join(', ')}</div>`;
+}
+
+function renderDelegationContext(context) {
+  if (!context) return '';
+  return `<div class="turn-detail"><span class="detail-label">Delegation:</span> <span class="mono">${esc(context.delegation_id)}</span> from ${esc(context.parent_role || 'unknown')} — ${esc(context.charter || '(no charter)')}</div>`;
+}
+
+function renderDelegationReview(review) {
+  if (!review) return '';
+  const resultCount = Array.isArray(review.results) ? review.results.length : 0;
+  return `<div class="turn-detail"><span class="detail-label">Delegation Review:</span> <span class="mono">${esc(review.parent_turn_id || 'unknown')}</span> with ${esc(resultCount)} result${resultCount === 1 ? '' : 's'}</div>`;
+}
+
 function renderContinuityPanel(continuity) {
   if (!continuity) return '';
 
@@ -323,6 +340,8 @@ export function render({ state, continuity, history, annotations, audit, connect
           <span class="turn-status">${esc(turn.status || 'assigned')}</span>
           ${elapsedStr ? `<span class="turn-timing">Elapsed: ${esc(elapsedStr)}</span>` : ''}
         </div>
+        ${renderDelegationContext(turn.delegation_context)}
+        ${renderDelegationReview(turn.delegation_review)}
       </div>`;
     }
     html += `</div></div>`;
@@ -355,6 +374,10 @@ export function render({ state, continuity, history, annotations, audit, connect
         html += `<div class="turn-summary">${esc(entry.summary)}</div>`;
       }
 
+      html += renderDelegationIssued(entry);
+      html += renderDelegationContext(entry.delegation_context);
+      html += renderDelegationReview(entry.delegation_review);
+
       if (files.length > 0) {
         html += `<div class="turn-detail"><span class="detail-label">Files:</span> <span class="mono">${files.map(f => esc(f)).join(', ')}</span></div>`;
       }

package/dashboard/index.html

@@ -377,6 +377,7 @@
     <a href="#initiative">Initiative</a>
     <a href="#cross-repo">Cross-Repo</a>
     <a href="#timeline" class="active">Timeline</a>
+    <a href="#delegations">Delegations</a>
     <a href="#ledger">Decisions</a>
     <a href="#hooks">Hooks</a>
     <a href="#blocked">Blocked</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.87.0",
+  "version": "2.89.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/lib/dispatch-bundle.js

@@ -124,6 +124,12 @@ export function writeDispatchBundle(root, state, config, opts = {}) {
   if (turn.conflict_context) {
     assignment.conflict_context = turn.conflict_context;
   }
+  if (turn.delegation_context) {
+    assignment.delegation_context = turn.delegation_context;
+  }
+  if (turn.delegation_review) {
+    assignment.delegation_review = turn.delegation_review;
+  }
   if (warnings.length > 0) {
     assignment.advisory_warnings = warnings.map((message) => ({ code: 'advisory_scope_overlap', message }));
   }
@@ -238,6 +244,8 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('- Your artifact type should be `patch`.');
     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('- For non-completion turns, set `artifact.type` to `patch`. Do NOT use `workspace` or `commit`.');
+      lines.push('- Use `artifact.type: "review"` only for completion-only final-phase turns that propose no file changes.');
       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');
       lines.push('  "proposed_changes": [');
@@ -390,6 +398,10 @@ function renderPrompt(role, roleId, turn, state, config, root) {
   if (role.write_authority === 'review_only') {
     lines.push('- `objections`: **must be non-empty** (challenge requirement for review_only roles)');
   }
+  if (role.write_authority === 'proposed' && (runtimeType === 'api_proxy' || runtimeType === 'remote_agent')) {
+    lines.push('- For `proposed` `api_proxy`/`remote_agent` turns with file changes, `artifact.type` must be `patch` and `proposed_changes` must be non-empty.');
+    lines.push('- Do NOT use `artifact.type: "workspace"` or `artifact.type: "commit"` on a `proposed` `api_proxy`/`remote_agent` turn.');
+  }
   // List valid phase names explicitly to prevent gate-name confusion
   const phaseNames = config.routing ? Object.keys(config.routing) : [];
   if (phaseNames.length > 0) {
@@ -547,6 +559,52 @@ function renderContext(state, config, root, turn, role) {
     lines.push('');
   }
 
+  // Delegation context (when this turn is a delegated sub-task)
+  if (turn.delegation_context) {
+    const dc = turn.delegation_context;
+    lines.push('## Delegation Context');
+    lines.push('');
+    lines.push('You are executing a delegated sub-task.');
+    lines.push('');
+    lines.push(`- **Delegated by:** ${dc.parent_role} (turn ${dc.parent_turn_id})`);
+    lines.push(`- **Charter:** ${dc.charter}`);
+    if (Array.isArray(dc.acceptance_contract) && dc.acceptance_contract.length > 0) {
+      lines.push('- **Acceptance contract:**');
+      for (const req of dc.acceptance_contract) {
+        lines.push(`  - ${req}`);
+      }
+    }
+    lines.push('');
+    lines.push('Focus exclusively on the charter above. Do not expand scope beyond the delegation.');
+    lines.push('');
+  }
+
+  // Delegation review context (when this turn reviews completed delegations)
+  if (turn.delegation_review) {
+    const dr = turn.delegation_review;
+    lines.push('## Delegation Review');
+    lines.push('');
+    lines.push('Your delegated sub-tasks have been completed. Review the results below.');
+    lines.push('');
+    for (const result of dr.results || []) {
+      lines.push(`### ${result.delegation_id} → ${result.to_role}`);
+      lines.push('');
+      lines.push(`- **Charter:** ${result.charter}`);
+      lines.push(`- **Status:** ${result.status}`);
+      lines.push(`- **Summary:** ${result.summary}`);
+      if (result.files_changed?.length > 0) {
+        lines.push(`- **Files changed:** ${result.files_changed.join(', ')}`);
+      }
+      if (result.verification?.status) {
+        lines.push(`- **Verification:** ${result.verification.status}`);
+      }
+      lines.push('');
+    }
+    lines.push('Evaluate whether each delegation met its acceptance contract.');
+    lines.push('Your turn result should assess the delegation outcomes and decide next steps.');
+    lines.push('');
+  }
+
   // Inherited context from parent run (when --inherit-context was used)
   if (state.inherited_context) {
     // First turn gets the full rendering; subsequent turns get compact
@@ -1214,6 +1272,7 @@ function readLastHistoryEntry(root, warnings = []) {
 
 function buildTurnResultTemplate(state, turn, roleId, role) {
   const isReviewOnly = role.write_authority === 'review_only';
+  const isProposed = role.write_authority === 'proposed';
   return {
     schema_version: '1.0',
     run_id: state.run_id,
@@ -1254,13 +1313,24 @@ function buildTurnResultTemplate(state, turn, roleId, role) {
         : [{ command: '<exact command that was run>', exit_code: 0 }],
     },
     artifact: {
-      type: isReviewOnly ? 'review' : 'workspace',
-      ref: isReviewOnly ? null : 'git:dirty',
+      type: isReviewOnly ? 'review' : (isProposed ? 'patch' : 'workspace'),
+      ref: isReviewOnly ? null : (isProposed ? null : 'git:dirty'),
     },
     proposed_next_role: '<role_id that should act next>',
     phase_transition_request: null,
     run_completion_request: null,
     needs_human_reason: null,
+    ...(isProposed
+      ? {
+          proposed_changes: [
+            {
+              path: '<path/to/modified/file>',
+              action: 'create',
+              content: '<full file content>',
+            },
+          ],
+        }
+      : {}),
     cost: {
       input_tokens: 0,
       output_tokens: 0,

package/src/lib/export.js

@@ -166,6 +166,93 @@ function countDirectoryFiles(files, prefix) {
   return Object.keys(files).filter((path) => path.startsWith(`${prefix}/`)).length;
 }
 
+export function buildDelegationSummary(files) {
+  const historyData = files['.agentxchain/history.jsonl']?.data;
+  if (!Array.isArray(historyData)) {
+    return null;
+  }
+
+  // Index history entries by delegation-related fields
+  const parentTurns = new Map(); // parent_turn_id -> { role, delegations_issued }
+  const childTurns = new Map();  // delegation_id -> { child entry }
+  const reviewTurns = new Map(); // parent_turn_id -> { review entry }
+
+  for (const entry of historyData) {
+    if (entry.delegations_issued && Array.isArray(entry.delegations_issued)) {
+      parentTurns.set(entry.turn_id, {
+        role: entry.role,
+        delegations_issued: entry.delegations_issued,
+      });
+    }
+    if (entry.delegation_context) {
+      childTurns.set(entry.delegation_context.delegation_id, {
+        turn_id: entry.turn_id,
+        status: entry.status || 'completed',
+      });
+    }
+    if (entry.delegation_review) {
+      reviewTurns.set(entry.delegation_review.parent_turn_id, {
+        turn_id: entry.turn_id,
+        results: entry.delegation_review.results || [],
+      });
+    }
+  }
+
+  let totalDelegationsIssued = 0;
+  const delegationChains = [];
+
+  for (const [parentTurnId, parent] of parentTurns) {
+    totalDelegationsIssued += parent.delegations_issued.length;
+
+    const review = reviewTurns.get(parentTurnId);
+    const reviewResultsByDelegation = new Map();
+    if (review) {
+      for (const r of review.results) {
+        if (r.delegation_id) {
+          reviewResultsByDelegation.set(r.delegation_id, r);
+        }
+      }
+    }
+
+    const delegations = parent.delegations_issued.map((del) => {
+      const child = childTurns.get(del.id);
+      const reviewResult = reviewResultsByDelegation.get(del.id);
+      return {
+        delegation_id: del.id,
+        to_role: del.to_role,
+        charter: del.charter,
+        status: reviewResult?.status || child?.status || 'pending',
+        child_turn_id: child?.turn_id || null,
+      };
+    });
+
+    let outcome;
+    if (!review) {
+      outcome = 'pending';
+    } else {
+      const statuses = delegations.map((d) => d.status);
+      const allCompleted = statuses.every((s) => s === 'completed');
+      const allFailed = statuses.every((s) => s === 'failed');
+      if (allCompleted) outcome = 'completed';
+      else if (allFailed) outcome = 'failed';
+      else outcome = 'mixed';
+    }
+
+    delegationChains.push({
+      parent_turn_id: parentTurnId,
+      parent_role: parent.role,
+      delegations,
+      review_turn_id: review?.turn_id || null,
+      outcome,
+    });
+  }
+
+  return {
+    total_delegations_issued: totalDelegationsIssued,
+    delegation_chains: delegationChains,
+  };
+}
+
 function isGitRepo(root) {
   try {
     execSync('git rev-parse --is-inside-work-tree', {
@@ -317,6 +404,7 @@ export function buildRunExport(startDir = process.cwd()) {
         staging_artifact_files: countDirectoryFiles(files, '.agentxchain/staging'),
         intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),
         coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
+        delegation_summary: buildDelegationSummary(files),
       },
       workspace: buildRunWorkspaceMetadata(root),
       files,

package/src/lib/governed-state.js

@@ -2065,24 +2065,53 @@ export function assignGovernedTurn(root, config, roleId) {
   // Record which turns are concurrent siblings (for conflict detection context)
   const concurrentWith = Object.keys(activeTurns);
 
+  // Build the new turn object
+  const newTurn = {
+    turn_id: turnId,
+    assigned_role: roleId,
+    status: 'running',
+    attempt: 1,
+    started_at: now,
+    deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
+    runtime_id: runtimeId,
+    baseline,
+    assigned_sequence: nextSequence,
+    concurrent_with: concurrentWith,
+  };
+
+  // Attach delegation context if this turn fulfills a pending delegation
+  const delegationQueue = state.delegation_queue || [];
+  const pendingDelegation = delegationQueue.find(d => d.status === 'pending' && d.to_role === roleId);
+  if (pendingDelegation) {
+    newTurn.delegation_context = {
+      delegation_id: pendingDelegation.delegation_id,
+      parent_turn_id: pendingDelegation.parent_turn_id,
+      parent_role: pendingDelegation.parent_role,
+      charter: pendingDelegation.charter,
+      acceptance_contract: pendingDelegation.acceptance_contract,
+    };
+    // Mark the delegation as active
+    pendingDelegation.status = 'active';
+    pendingDelegation.child_turn_id = turnId;
+  }
+
+  // Attach delegation review context if a review is pending for this role
+  const pendingReview = state.pending_delegation_review;
+  if (pendingReview && pendingReview.parent_role === roleId && !pendingDelegation) {
+    newTurn.delegation_review = {
+      parent_turn_id: pendingReview.parent_turn_id,
+      results: pendingReview.delegation_results,
+    };
+  }
+
   const updatedState = {
     ...state,
     turn_sequence: nextSequence,
     budget_reservations: reservations,
+    delegation_queue: delegationQueue,
     active_turns: {
       ...activeTurns,
-      [turnId]: {
-        turn_id: turnId,
-        assigned_role: roleId,
-        status: 'running',
-        attempt: 1,
-        started_at: now,
-        deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
-        runtime_id: runtimeId,
-        baseline,
-        assigned_sequence: nextSequence,
-        concurrent_with: concurrentWith,
-      },
+      [turnId]: newTurn,
     },
   };
 
@@ -2599,6 +2628,35 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     ...(currentTurn.started_at ? { started_at: currentTurn.started_at } : {}),
     accepted_at: now,
     ...(currentTurn.started_at ? { duration_ms: Math.max(0, new Date(now).getTime() - new Date(currentTurn.started_at).getTime()) } : {}),
+    ...(Array.isArray(turnResult.delegations) && turnResult.delegations.length > 0
+      ? {
+          delegations_issued: turnResult.delegations.map((delegation) => ({
+            id: delegation.id,
+            to_role: delegation.to_role,
+            charter: delegation.charter,
+            acceptance_contract: delegation.acceptance_contract,
+          })),
+        }
+      : {}),
+    ...(currentTurn.delegation_context
+      ? {
+          delegation_context: {
+            delegation_id: currentTurn.delegation_context.delegation_id,
+            parent_turn_id: currentTurn.delegation_context.parent_turn_id,
+            parent_role: currentTurn.delegation_context.parent_role,
+            charter: currentTurn.delegation_context.charter,
+            acceptance_contract: currentTurn.delegation_context.acceptance_contract,
+          },
+        }
+      : {}),
+    ...(currentTurn.delegation_review
+      ? {
+          delegation_review: {
+            parent_turn_id: currentTurn.delegation_review.parent_turn_id,
+            results: currentTurn.delegation_review.results,
+          },
+        }
+      : {}),
   };
   const nextHistoryEntries = [...historyEntries, historyEntry];
   // Build ledger entries for the journal
@@ -2649,6 +2707,97 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     },
   };
 
+  // ── Delegation queue management ──────────────────────────────────────────
+  // Initialize delegation queue if not present
+  if (!updatedState.delegation_queue) {
+    updatedState.delegation_queue = [];
+  }
+  if (!updatedState.pending_delegation_review) {
+    updatedState.pending_delegation_review = null;
+  }
+
+  // If this turn has delegations, enqueue them
+  if (Array.isArray(turnResult.delegations) && turnResult.delegations.length > 0) {
+    for (const del of turnResult.delegations) {
+      updatedState.delegation_queue.push({
+        delegation_id: del.id,
+        parent_turn_id: turnResult.turn_id,
+        parent_role: turnResult.role,
+        to_role: del.to_role,
+        charter: del.charter,
+        acceptance_contract: del.acceptance_contract,
+        status: 'pending',
+        child_turn_id: null,
+        created_at: now,
+      });
+    }
+    // Override next_recommended_role to first pending delegation
+    updatedState.next_recommended_role = turnResult.delegations[0].to_role;
+  }
+
+  // If this turn was a delegated sub-task, update the delegation queue entry
+  if (currentTurn.delegation_context) {
+    const delId = currentTurn.delegation_context.delegation_id;
+    const queueEntry = updatedState.delegation_queue.find(d => d.delegation_id === delId);
+    if (queueEntry) {
+      queueEntry.status = turnResult.status === 'completed' ? 'completed' : 'failed';
+      queueEntry.child_turn_id = currentTurn.turn_id;
+
+      // Check if all delegations from the same parent are now complete
+      const parentTurnId = queueEntry.parent_turn_id;
+      const parentDelegations = updatedState.delegation_queue.filter(d => d.parent_turn_id === parentTurnId);
+      const allDone = parentDelegations.every(d => d.status === 'completed' || d.status === 'failed');
+
+      if (allDone) {
+        // Build delegation review context
+        const delegationResults = parentDelegations.map(d => {
+          const childHistory = nextHistoryEntries.find(h => h.turn_id === d.child_turn_id);
+          return {
+            delegation_id: d.delegation_id,
+            child_turn_id: d.child_turn_id,
+            to_role: d.to_role,
+            charter: d.charter,
+            acceptance_contract: d.acceptance_contract,
+            summary: childHistory?.summary || '(no summary)',
+            status: d.status,
+            files_changed: childHistory?.files_changed || [],
+            verification: childHistory?.verification || { status: 'skipped' },
+          };
+        });
+
+        updatedState.pending_delegation_review = {
+          parent_turn_id: parentTurnId,
+          parent_role: queueEntry.parent_role,
+          delegation_results: delegationResults,
+        };
+
+        // Recommend the parent role for the review turn
+        updatedState.next_recommended_role = queueEntry.parent_role;
+
+        // Clear completed delegation queue entries for this parent
+        updatedState.delegation_queue = updatedState.delegation_queue.filter(
+          d => d.parent_turn_id !== parentTurnId
+        );
+      } else {
+        // More pending delegations — route to the next one
+        const nextPending = updatedState.delegation_queue.find(
+          d => d.parent_turn_id === parentTurnId && d.status === 'pending'
+        );
+        if (nextPending) {
+          updatedState.next_recommended_role = nextPending.to_role;
+        }
+      }
+    }
+  }
+
+  // If a delegation review was pending and this turn was the review, clear it
+  if (updatedState.pending_delegation_review &&
+      turnResult.role === updatedState.pending_delegation_review.parent_role &&
+      !currentTurn.delegation_context) {
+    // The parent role just completed their review turn
+    updatedState.pending_delegation_review = null;
+  }
+
   if (updatedState.status === 'blocked' && !hasBlockingActiveTurn(remainingTurns)) {
     updatedState.status = 'active';
     updatedState.blocked_on = null;

package/src/lib/report.js

@@ -1,8 +1,63 @@
 import { verifyExportArtifact } from './export-verifier.js';
+import { buildDelegationSummary } from './export.js';
 import { normalizeRunProvenance, summarizeRunProvenance } from './run-provenance.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
+const VALID_DELEGATION_OUTCOMES = new Set(['completed', 'failed', 'mixed', 'pending']);
+
+function normalizeDelegationSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) return null;
+  if (!Number.isInteger(summary.total_delegations_issued) || summary.total_delegations_issued < 0) return null;
+  if (!Array.isArray(summary.delegation_chains)) return null;
+
+  const chains = [];
+  for (const chain of summary.delegation_chains) {
+    if (!chain || typeof chain !== 'object' || Array.isArray(chain)) return null;
+    if (typeof chain.parent_turn_id !== 'string' || chain.parent_turn_id.length === 0) return null;
+    if (typeof chain.parent_role !== 'string' || chain.parent_role.length === 0) return null;
+    if (!Array.isArray(chain.delegations)) return null;
+    if (chain.review_turn_id !== null && (typeof chain.review_turn_id !== 'string' || chain.review_turn_id.length === 0)) return null;
+    if (!VALID_DELEGATION_OUTCOMES.has(chain.outcome)) return null;
+
+    const delegations = [];
+    for (const delegation of chain.delegations) {
+      if (!delegation || typeof delegation !== 'object' || Array.isArray(delegation)) return null;
+      if (typeof delegation.delegation_id !== 'string' || delegation.delegation_id.length === 0) return null;
+      if (typeof delegation.to_role !== 'string' || delegation.to_role.length === 0) return null;
+      if (typeof delegation.charter !== 'string') return null;
+      if (!['completed', 'failed', 'pending'].includes(delegation.status)) return null;
+      if (delegation.child_turn_id !== null && (typeof delegation.child_turn_id !== 'string' || delegation.child_turn_id.length === 0)) return null;
+      delegations.push({
+        delegation_id: delegation.delegation_id,
+        to_role: delegation.to_role,
+        charter: delegation.charter,
+        status: delegation.status,
+        child_turn_id: delegation.child_turn_id,
+      });
+    }
+
+    chains.push({
+      parent_turn_id: chain.parent_turn_id,
+      parent_role: chain.parent_role,
+      delegations,
+      review_turn_id: chain.review_turn_id,
+      outcome: chain.outcome,
+    });
+  }
+
+  return {
+    total_delegations_issued: summary.total_delegations_issued,
+    delegation_chains: chains,
+  };
+}
+
+function extractDelegationSummary(artifact) {
+  const fromSummary = normalizeDelegationSummary(artifact.summary?.delegation_summary);
+  if (fromSummary) return fromSummary;
+  return normalizeDelegationSummary(buildDelegationSummary(artifact.files || {}));
+}
+
 function yesNo(value) {
   return value ? 'yes' : 'no';
 }
@@ -846,6 +901,7 @@ function buildRunSubject(artifact) {
   const recoverySummary = extractRecoverySummary(artifact);
   const continuity = extractContinuityMetadata(artifact);
   const governanceEvents = extractGovernanceEventDigest(artifact);
+  const delegationSummary = extractDelegationSummary(artifact);
 
   return {
     kind: 'governed_run',
@@ -881,6 +937,7 @@ function buildRunSubject(artifact) {
       governance_events: governanceEvents,
       gate_failures: gateFailures,
       timeout_events: timeoutEvents,
+      delegation_summary: delegationSummary,
       hook_summary: hookSummary,
       gate_summary: gateSummary,
       intake_links: intakeLinks,
@@ -1174,6 +1231,17 @@ export function formatGovernanceReportText(report) {
       }
     }
 
+    if (run.delegation_summary?.delegation_chains?.length > 0) {
+      lines.push('', 'Delegation Summary:');
+      lines.push(`  Total delegations issued: ${run.delegation_summary.total_delegations_issued}`);
+      for (const chain of run.delegation_summary.delegation_chains) {
+        lines.push(`  - ${chain.parent_role} (${chain.parent_turn_id}) | outcome: ${chain.outcome} | review: ${chain.review_turn_id || 'pending'}`);
+        for (const delegation of chain.delegations) {
+          lines.push(`      ${delegation.delegation_id} -> ${delegation.to_role} | ${delegation.status} | child: ${delegation.child_turn_id || 'pending'} | ${delegation.charter}`);
+        }
+      }
+    }
+
     if (run.turns && run.turns.length > 0) {
       lines.push('', 'Turn Timeline:');
       for (let i = 0; i < run.turns.length; i++) {
@@ -1628,6 +1696,23 @@ export function formatGovernanceReportMarkdown(report) {
       }
     }
 
+    if (run.delegation_summary?.delegation_chains?.length > 0) {
+      lines.push('', '## Delegation Summary', '');
+      lines.push(`- Total delegations issued: ${run.delegation_summary.total_delegations_issued}`, '');
+      lines.push('| Parent Role | Parent Turn | Outcome | Review Turn | Delegation | Child Turn | Status | Charter |', '|-------------|-------------|---------|-------------|------------|------------|--------|---------|');
+      for (const chain of run.delegation_summary.delegation_chains) {
+        for (let i = 0; i < chain.delegations.length; i++) {
+          const delegation = chain.delegations[i];
+          const parentRole = i === 0 ? chain.parent_role : '';
+          const parentTurn = i === 0 ? `\`${chain.parent_turn_id}\`` : '';
+          const outcome = i === 0 ? `\`${chain.outcome}\`` : '';
+          const reviewTurn = i === 0 ? `\`${chain.review_turn_id || 'pending'}\`` : '';
+          const charter = delegation.charter.replace(/\|/g, '\\|');
+          lines.push(`| ${parentRole} | ${parentTurn} | ${outcome} | ${reviewTurn} | \`${delegation.delegation_id}\` → \`${delegation.to_role}\` | \`${delegation.child_turn_id || 'pending'}\` | \`${delegation.status}\` | ${charter} |`);
+        }
+      }
+    }
+
     if (run.turns && run.turns.length > 0) {
       lines.push('', '## Turn Timeline', '', '| # | Role | Phase | Summary | Files | Cost | Time |', '|---|------|-------|---------|-------|------|------|');
       for (let i = 0; i < run.turns.length; i++) {

package/src/lib/role-resolution.js

@@ -30,6 +30,15 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
   const routing = phase ? config?.routing?.[phase] : null;
   const warnings = [];
 
+  // ── Delegation queue priority ───────────────────────────────────────────
+  // If there are pending delegations, the next role is the delegation target
+  const pendingDelegation = Array.isArray(state?.delegation_queue)
+    ? state.delegation_queue.find(d => d.status === 'pending')
+    : null;
+
+  // If a delegation review is pending, the parent role takes priority
+  const pendingReview = state?.pending_delegation_review || null;
+
   if (override) {
     if (!config?.roles?.[override]) {
       return {
@@ -45,6 +54,14 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
       warnings.push(`role "${override}" is not in allowed_next_roles for phase "${phase}"`);
     }
 
+    // Warn if override skips a pending delegation
+    if (pendingDelegation && override !== pendingDelegation.to_role) {
+      warnings.push(`Override skips pending delegation ${pendingDelegation.delegation_id} to role "${pendingDelegation.to_role}"`);
+    }
+    if (pendingReview && override !== pendingReview.parent_role) {
+      warnings.push(`Override skips pending delegation review for role "${pendingReview.parent_role}"`);
+    }
+
     return {
       roleId: override,
       warnings,
@@ -54,6 +71,30 @@ export function resolveGovernedRole({ override = null, state = null, config }) {
     };
   }
 
+  // Delegation review takes priority over pending delegations
+  if (pendingReview && config?.roles?.[pendingReview.parent_role]) {
+    return {
+      roleId: pendingReview.parent_role,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+      delegation_review: true,
+    };
+  }
+
+  // Pending delegation takes priority over normal resolution
+  if (pendingDelegation && config?.roles?.[pendingDelegation.to_role]) {
+    return {
+      roleId: pendingDelegation.to_role,
+      warnings,
+      error: null,
+      availableRoles: roles,
+      phase,
+      delegation: pendingDelegation,
+    };
+  }
+
   if (state?.next_recommended_role && config?.roles?.[state.next_recommended_role]) {
     const recommended = state.next_recommended_role;
     const isLegal = !routing?.allowed_next_roles || routing.allowed_next_roles.includes(recommended);

package/src/lib/schemas/turn-result.schema.json

@@ -228,6 +228,39 @@
         "output_tokens": { "type": "integer", "minimum": 0 },
         "usd": { "type": "number", "minimum": 0 }
       }
+    },
+    "delegations": {
+      "type": "array",
+      "description": "Sub-tasks delegated to other roles. The delegating role defines the charter; delegates execute it; the delegating role reviews results.",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "required": ["id", "to_role", "charter", "acceptance_contract"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^del-\\d{3}$",
+            "description": "Delegation ID, e.g. del-001"
+          },
+          "to_role": {
+            "type": "string",
+            "pattern": "^[a-z0-9_-]+$",
+            "description": "Role that should execute this sub-task. Must be a defined role and routing-legal."
+          },
+          "charter": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Scope of the delegated work."
+          },
+          "acceptance_contract": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "description": "What the delegate must achieve for this delegation to be considered complete."
+          }
+        }
+      }
     }
   }
 }

package/src/lib/token-budget.js

@@ -18,6 +18,7 @@ const SEPARATOR = '\n\n---\n\n';
 const SYSTEM_PROMPT = [
   'You are acting as a governed agent in an AgentXchain protocol run.',
   'Your task and rules are described in the user message.',
+  'You MUST obey the write-authority-specific rules in the prompt exactly.',
   'You MUST respond with a valid JSON object matching the turn result schema provided in the prompt.',
   'Do NOT wrap the JSON in markdown code fences. Respond with raw JSON only.',
 ].join('\n');

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

@@ -602,6 +602,54 @@ function validateProtocol(tr, state, config) {
     warnings.push('status is "needs_human" but needs_human_reason is empty.');
   }
 
+  // ── Delegation validation ───────────────────────────────────────────────
+  if (Array.isArray(tr.delegations) && tr.delegations.length > 0) {
+    // Maximum 5 delegations per turn
+    if (tr.delegations.length > 5) {
+      errors.push(`Maximum 5 delegations per turn (got ${tr.delegations.length}).`);
+    }
+
+    // Delegations are mutually exclusive with run_completion_request
+    if (tr.run_completion_request) {
+      errors.push('delegations are mutually exclusive with run_completion_request — a turn cannot delegate and complete the run.');
+    }
+
+    // No recursive delegation: if this turn is a delegation review, it cannot delegate further
+    const activeTurn = state?.active_turns ? Object.values(state.active_turns)[0] : null;
+    if (activeTurn?.delegation_context) {
+      errors.push('Delegation review turns cannot contain further delegations.');
+    }
+
+    const seenIds = new Set();
+    for (const del of tr.delegations) {
+      // Duplicate IDs
+      if (seenIds.has(del.id)) {
+        errors.push(`Duplicate delegation id "${del.id}".`);
+      }
+      seenIds.add(del.id);
+
+      // Self-delegation
+      if (del.to_role === tr.role) {
+        errors.push(`Role "${tr.role}" cannot delegate to itself (delegation ${del.id}).`);
+      }
+
+      // to_role must be a defined role
+      if (!config.roles?.[del.to_role]) {
+        errors.push(`Delegation to_role "${del.to_role}" is not a defined role (delegation ${del.id}).`);
+      }
+
+      // to_role must be routing-legal for current phase
+      if (routing && del.to_role) {
+        const allowed = routing.allowed_next_roles || [];
+        if (allowed.length > 0 && !allowed.includes(del.to_role)) {
+          errors.push(
+            `Delegation to_role "${del.to_role}" is not in allowed_next_roles for phase "${phase}": [${allowed.join(', ')}] (delegation ${del.id}).`
+          );
+        }
+      }
+    }
+  }
+
   return { errors, warnings };
 }