agentxchain 2.6.0 → 2.7.0

package/bin/agentxchain.js

@@ -65,6 +65,7 @@ import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
 import { migrateCommand } from '../src/commands/migrate.js';
 import { resumeCommand } from '../src/commands/resume.js';
+import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
 import { stepCommand } from '../src/commands/step.js';
@@ -260,6 +261,15 @@ program
   .option('--turn <id>', 'Target a specific retained turn when multiple exist')
   .action(resumeCommand);
 
+program
+  .command('escalate')
+  .description('Raise an operator escalation and block the governed run intentionally')
+  .requiredOption('--reason <reason>', 'Operator escalation summary')
+  .option('--detail <detail>', 'Longer escalation detail for status and ledger surfaces')
+  .option('--action <action>', 'Override the default recovery action string')
+  .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
+  .action(escalateCommand);
+
 program
   .command('accept-turn')
   .description('Accept the currently staged governed turn result')

package/package.json

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

package/src/commands/escalate.js

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { raiseOperatorEscalation } from '../lib/governed-state.js';
+
+export async function escalateCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The escalate command is only available for governed projects.'));
+    console.log(chalk.dim('Legacy projects use: agentxchain claim / release'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+  if (!state) {
+    console.log(chalk.red('No governed state.json found. Run `agentxchain init --governed` first.'));
+    process.exit(1);
+  }
+
+  const result = raiseOperatorEscalation(root, config, {
+    reason: opts.reason,
+    detail: opts.detail,
+    action: opts.action,
+    turnId: opts.turn,
+  });
+  if (!result.ok) {
+    console.log(chalk.red(result.error));
+    process.exit(1);
+  }
+
+  const recovery = deriveRecoveryDescriptor(result.state);
+
+  console.log('');
+  console.log(chalk.yellow('  Run Escalated'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log('');
+  console.log(`  ${chalk.dim('Reason:')}   ${result.escalation.reason}`);
+  if (result.escalation.detail && result.escalation.detail !== result.escalation.reason) {
+    console.log(`  ${chalk.dim('Detail:')}   ${result.escalation.detail}`);
+  }
+  console.log(`  ${chalk.dim('Blocked:')}  ${result.state.blocked_on}`);
+  console.log(`  ${chalk.dim('Source:')}   operator`);
+  console.log(`  ${chalk.dim('Turn:')}     ${result.escalation.from_turn_id || 'none retained'}`);
+  if (result.escalation.from_role) {
+    console.log(`  ${chalk.dim('Role:')}     ${result.escalation.from_role}`);
+  }
+  console.log('');
+
+  if (recovery) {
+    console.log(`  ${chalk.dim('Typed:')}    ${recovery.typed_reason}`);
+    console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+    console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+    console.log(`  ${chalk.dim('Retained:')} ${recovery.turn_retained ? 'yes' : 'no'}`);
+  }
+  console.log('');
+}

package/src/commands/resume.js

@@ -24,6 +24,7 @@ import {
   markRunBlocked,
   getActiveTurns,
   getActiveTurnCount,
+  reactivateGovernedRun,
   STATE_PATH,
 } from '../lib/governed-state.js';
 import { writeDispatchBundle, getDispatchTurnDir, getTurnStagingResultPath } from '../lib/dispatch-bundle.js';
@@ -154,6 +155,62 @@ export async function resumeCommand(opts) {
     }
   }
 
+  if (state.status === 'blocked' && activeCount > 0) {
+    let retainedTurn = null;
+    if (opts.turn) {
+      retainedTurn = activeTurns[opts.turn];
+      if (!retainedTurn) {
+        console.log(chalk.red(`No active turn found for --turn ${opts.turn}`));
+        process.exit(1);
+      }
+    } else if (activeCount > 1) {
+      console.log(chalk.red('Multiple retained turns exist. Use --turn <id> to specify which to re-dispatch.'));
+      for (const turn of Object.values(activeTurns)) {
+        console.log(`  ${chalk.yellow('●')} ${turn.turn_id} — ${chalk.bold(turn.assigned_role)} (${turn.status})`);
+      }
+      console.log('');
+      console.log(chalk.dim('Example: agentxchain resume --turn <turn_id>'));
+      process.exit(1);
+    } else {
+      retainedTurn = Object.values(activeTurns)[0];
+    }
+
+    if (retainedTurn.status === 'conflicted') {
+      console.log(chalk.red(`Turn ${retainedTurn.turn_id} is conflicted. Resolve the conflict before resuming.`));
+      process.exit(1);
+    }
+
+    console.log(chalk.yellow(`Re-dispatching blocked turn: ${retainedTurn.turn_id}`));
+    console.log(`  Role:    ${retainedTurn.assigned_role}`);
+    console.log(`  Attempt: ${retainedTurn.attempt}`);
+    console.log('');
+
+    const reactivated = reactivateGovernedRun(root, state, { via: 'resume --turn', notificationConfig: config });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+      process.exit(1);
+    }
+    state = reactivated.state;
+
+    const bundleResult = writeDispatchBundle(root, state, config, { turnId: retainedTurn.turn_id });
+    if (!bundleResult.ok) {
+      console.log(chalk.red(`Failed to write dispatch bundle: ${bundleResult.error}`));
+      process.exit(1);
+    }
+    printDispatchBundleWarnings(bundleResult);
+
+    const hooksConfig = config.hooks || {};
+    if (hooksConfig.after_dispatch?.length > 0) {
+      const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, retainedTurn, config);
+      if (!afterDispatchResult.ok) {
+        process.exit(1);
+      }
+    }
+
+    printDispatchSummary(state, config, retainedTurn);
+    return;
+  }
+
   // §47: idle + no run_id → initialize new run
   if (state.status === 'idle' && !state.run_id) {
     const initResult = initializeGovernedRun(root, config);
@@ -165,10 +222,22 @@ export async function resumeCommand(opts) {
     console.log(chalk.green(`Initialized governed run: ${state.run_id}`));
   }
 
+  // §47: paused + run_id exists → resume same run
+  if (state.status === 'blocked' && state.run_id) {
+    const reactivated = reactivateGovernedRun(root, state, { via: 'resume', notificationConfig: config });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+      process.exit(1);
+    }
+    state = reactivated.state;
+    console.log(chalk.green(`Resumed blocked run: ${state.run_id}`));
+  }
+
   // §47: paused + run_id exists → resume same run
   if (state.status === 'paused' && state.run_id) {
     state.status = 'active';
     state.blocked_on = null;
+    state.blocked_reason = null;
     state.escalation = null;
     safeWriteJson(statePath, state);
     console.log(chalk.green(`Resumed governed run: ${state.run_id}`));
@@ -203,7 +272,7 @@ export async function resumeCommand(opts) {
   const hooksConfig = config.hooks || {};
   const turn = state.current_turn;
   if (hooksConfig.after_dispatch?.length > 0) {
-    const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, turn);
+    const afterDispatchResult = runAfterDispatchHooks(root, hooksConfig, state, turn, config);
     if (!afterDispatchResult.ok) {
       process.exit(1);
     }
@@ -259,7 +328,7 @@ function resolveTargetRole(opts, state, config) {
   return null;
 }
 
-function runAfterDispatchHooks(root, hooksConfig, state, turn) {
+function runAfterDispatchHooks(root, hooksConfig, state, turn, config) {
   const turnId = turn.turn_id;
   const roleId = turn.assigned_role;
 
@@ -300,6 +369,7 @@ function runAfterDispatchHooks(root, hooksConfig, state, turn) {
         detail,
       },
       turnId,
+      notificationConfig: config,
     });
 
     printDispatchHookFailure({

package/src/commands/step.js

@@ -32,6 +32,7 @@ import {
   markRunBlocked,
   getActiveTurnCount,
   getActiveTurns,
+  reactivateGovernedRun,
   STATE_PATH,
 } from '../lib/governed-state.js';
 import { getMaxConcurrentTurns } from '../lib/normalized-config.js';
@@ -203,8 +204,12 @@ export async function stepCommand(opts) {
       }
 
       console.log(chalk.yellow(`Re-dispatching blocked turn: ${targetTurn.turn_id}`));
-      state = clearBlockedState(state);
-      safeWriteJson(join(root, STATE_PATH), state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'step --resume', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
       skipAssignment = true;
 
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -251,8 +256,12 @@ export async function stepCommand(opts) {
 
     // paused → resume
     if (!skipAssignment && state.status === 'blocked' && state.run_id) {
-      state = clearBlockedState(state);
-      safeWriteJson(join(root, STATE_PATH), state);
+      const reactivated = reactivateGovernedRun(root, state, { via: 'step', notificationConfig: config });
+      if (!reactivated.ok) {
+        console.log(chalk.red(`Failed to reactivate blocked run: ${reactivated.error}`));
+        process.exit(1);
+      }
+      state = reactivated.state;
       console.log(chalk.green(`Resumed blocked run: ${state.run_id}`));
     }
 
@@ -332,6 +341,7 @@ export async function stepCommand(opts) {
         hookResults: afterDispatchHooks,
         phase: 'after_dispatch',
         defaultDetail: `after_dispatch hook blocked dispatch for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Dispatch Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -382,6 +392,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -462,6 +473,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -530,6 +542,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -556,6 +569,7 @@ export async function stepCommand(opts) {
         },
         turnId: turn.turn_id,
         hooksConfig,
+        notificationConfig: config,
       });
       if (blocked.ok) {
         state = blocked.state;
@@ -643,6 +657,7 @@ export async function stepCommand(opts) {
         hookResults: beforeValidationHooks,
         phase: 'before_validation',
         defaultDetail: `before_validation hook blocked validation for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Validation Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -674,6 +689,7 @@ export async function stepCommand(opts) {
         hookResults: afterValidationHooks,
         phase: 'after_validation',
         defaultDetail: `after_validation hook blocked acceptance for turn ${turn.turn_id}`,
+        config,
       });
       printLifecycleHookFailure('Validation Blocked By Hook', blocked.result, {
         turnId: turn.turn_id,
@@ -758,7 +774,7 @@ function loadHookStagedTurn(root, stagingRel) {
   }
 }
 
-function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail }) {
+function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail, config }) {
   const hookName = hookResults.blocker?.hook_name
     || hookResults.results?.find((entry) => entry.hook_name)?.hook_name
     || 'unknown';
@@ -777,6 +793,7 @@ function blockStepForHookIssue(root, turn, { hookResults, phase, defaultDetail }
       detail,
     },
     turnId: turn.turn_id,
+    notificationConfig: config,
   });
 
   return {
@@ -860,16 +877,6 @@ function resolveTargetRole(opts, state, config) {
   return null;
 }
 
-function clearBlockedState(state) {
-  return {
-    ...state,
-    status: 'active',
-    blocked_on: null,
-    blocked_reason: null,
-    escalation: null,
-  };
-}
-
 function printRecoverySummary(state, heading) {
   const recovery = deriveRecoveryDescriptor(state);
   console.log(chalk.yellow(heading));

package/src/lib/blocked-state.js

@@ -65,12 +65,16 @@ export function deriveRecoveryDescriptor(state) {
   }
 
   if (state.blocked_on.startsWith('escalation:')) {
+    const isOperatorEscalation = state.blocked_on.startsWith('escalation:operator:') || state.escalation?.source === 'operator';
+    const recoveryAction = turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step';
     return {
-      typed_reason: 'retries_exhausted',
+      typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       owner: 'human',
-      recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+      recovery_action: recoveryAction,
       turn_retained: turnRetained,
-      detail: state.blocked_on,
+      detail: state.escalation?.detail || state.escalation?.reason || state.blocked_on,
     };
   }
 

package/src/lib/export-verifier.js

@@ -187,6 +187,7 @@ function verifyRunExport(artifact, errors) {
   const expectedHistoryEntries = countJsonl(artifact.files, '.agentxchain/history.jsonl');
   const expectedDecisionEntries = countJsonl(artifact.files, '.agentxchain/decision-ledger.jsonl');
   const expectedHookAuditEntries = countJsonl(artifact.files, '.agentxchain/hook-audit.jsonl');
+  const expectedNotificationAuditEntries = countJsonl(artifact.files, '.agentxchain/notification-audit.jsonl');
   const expectedDispatchFiles = countDirectoryFiles(artifact.files, '.agentxchain/dispatch');
   const expectedStagingFiles = countDirectoryFiles(artifact.files, '.agentxchain/staging');
   const expectedIntakePresent = Object.keys(artifact.files).some((path) => path.startsWith('.agentxchain/intake/'));
@@ -201,6 +202,9 @@ function verifyRunExport(artifact, errors) {
   if (artifact.summary.hook_audit_entries !== expectedHookAuditEntries) {
     addError(errors, 'summary.hook_audit_entries', 'must match .agentxchain/hook-audit.jsonl entry count');
   }
+  if (artifact.summary.notification_audit_entries !== expectedNotificationAuditEntries) {
+    addError(errors, 'summary.notification_audit_entries', 'must match .agentxchain/notification-audit.jsonl entry count');
+  }
   if (artifact.summary.dispatch_artifact_files !== expectedDispatchFiles) {
     addError(errors, 'summary.dispatch_artifact_files', 'must match .agentxchain/dispatch file count');
   }

package/src/lib/export.js

@@ -24,6 +24,7 @@ const INCLUDED_ROOTS = [
   '.agentxchain/decision-ledger.jsonl',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/notification-audit.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -172,6 +173,7 @@ export function buildRunExport(startDir = process.cwd()) {
         history_entries: countJsonl(files, '.agentxchain/history.jsonl'),
         decision_entries: countJsonl(files, '.agentxchain/decision-ledger.jsonl'),
         hook_audit_entries: countJsonl(files, '.agentxchain/hook-audit.jsonl'),
+        notification_audit_entries: countJsonl(files, '.agentxchain/notification-audit.jsonl'),
         dispatch_artifact_files: countDirectoryFiles(files, '.agentxchain/dispatch'),
         staging_artifact_files: countDirectoryFiles(files, '.agentxchain/staging'),
         intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),

package/src/lib/governed-state.js

@@ -34,6 +34,7 @@ import {
 import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
+import { emitNotifications } from './notification-runner.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -53,6 +54,29 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+function emitBlockedNotification(root, config, state, details = {}, turn = null) {
+  if (!config?.notifications?.webhooks?.length) {
+    return;
+  }
+
+  const recovery = state?.blocked_reason?.recovery || details.recovery || null;
+  emitNotifications(root, config, state, 'run_blocked', {
+    category: state?.blocked_reason?.category || details.category || 'unknown_block',
+    blocked_on: state?.blocked_on || details.blockedOn || null,
+    typed_reason: recovery?.typed_reason || null,
+    owner: recovery?.owner || null,
+    recovery_action: recovery?.recovery_action || null,
+    detail: recovery?.detail || null,
+  }, turn);
+}
+
+function emitPendingLifecycleNotification(root, config, state, eventType, payload, turn = null) {
+  if (!config?.notifications?.webhooks?.length) {
+    return;
+  }
+  emitNotifications(root, config, state, eventType, payload, turn);
+}
+
 function normalizeActiveTurns(activeTurns) {
   if (!activeTurns || typeof activeTurns !== 'object' || Array.isArray(activeTurns)) {
     return {};
@@ -555,6 +579,22 @@ function buildBlockedReason({ category, recovery, turnId, blockedAt = new Date()
   };
 }
 
+function slugifyEscalationReason(reason) {
+  if (typeof reason !== 'string') {
+    return 'operator';
+  }
+  const slug = reason
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'operator';
+}
+
+function isOperatorEscalationBlockedOn(blockedOn) {
+  return typeof blockedOn === 'string' && blockedOn.startsWith('escalation:operator:');
+}
+
 function canApprovePendingGate(state) {
   return state?.status === 'paused' || state?.status === 'blocked';
 }
@@ -599,7 +639,7 @@ function deriveHookRecovery(state, { phase, hookName, detail, errorCode, turnId,
   };
 }
 
-function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, errorCode, turnRetained }) {
+function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, errorCode, turnRetained, notificationConfig }) {
   const blockedAt = new Date().toISOString();
   const typedReason = errorCode?.includes('_tamper') ? 'hook_tamper' : 'hook_block';
   const recovery = deriveHookRecovery(state, {
@@ -622,6 +662,11 @@ function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, er
     }),
   };
   writeState(root, blockedState);
+  emitBlockedNotification(root, notificationConfig, blockedState, {
+    category: typedReason,
+    blockedOn: blockedState.blocked_on,
+    recovery,
+  }, turnId ? getActiveTurns(blockedState)[turnId] || null : null);
   return attachLegacyCurrentTurnAlias(blockedState);
 }
 
@@ -694,14 +739,18 @@ function inferBlockedReasonFromState(state) {
   }
 
   if (state.blocked_on.startsWith('escalation:')) {
+    const isOperatorEscalation = isOperatorEscalationBlockedOn(state.blocked_on) || state.escalation?.source === 'operator';
+    const recoveryAction = turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step';
     return buildBlockedReason({
-      category: 'retries_exhausted',
+      category: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
       recovery: {
-        typed_reason: 'retries_exhausted',
+        typed_reason: isOperatorEscalation ? 'operator_escalation' : 'retries_exhausted',
         owner: 'human',
-        recovery_action: 'Resolve the escalation, then run agentxchain step --resume',
+        recovery_action: recoveryAction,
         turn_retained: turnRetained,
-        detail: state.blocked_on,
+        detail: state.escalation?.detail || state.escalation?.reason || state.blocked_on,
       },
       turnId: activeTurn?.turn_id ?? null,
     });
@@ -819,6 +868,12 @@ export function markRunBlocked(root, details) {
 
   writeState(root, updatedState);
 
+  emitBlockedNotification(root, details.notificationConfig, updatedState, {
+    category: details.category,
+    blockedOn: details.blockedOn,
+    recovery: details.recovery,
+  }, turnId ? getActiveTurns(updatedState)[turnId] || null : null);
+
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   // Only fire for non-hook-caused blocks to prevent circular invocations.
   if (details.hooksConfig?.on_escalation?.length > 0) {
@@ -837,6 +892,141 @@ export function markRunBlocked(root, details) {
   return { ok: true, state: updatedState };
 }
 
+export function raiseOperatorEscalation(root, config, details) {
+  const state = readState(root);
+  if (!state) {
+    return { ok: false, error: 'No governed state.json found' };
+  }
+
+  const reason = typeof details.reason === 'string' ? details.reason.trim() : '';
+  if (!reason) {
+    return { ok: false, error: 'Escalation reason is required.' };
+  }
+
+  if (state.status !== 'active') {
+    return { ok: false, error: `Cannot escalate run: status is "${state.status}", expected "active"` };
+  }
+
+  const activeTurns = getActiveTurns(state);
+  let targetTurn = null;
+  if (details.turnId) {
+    targetTurn = activeTurns[details.turnId] || null;
+    if (!targetTurn) {
+      return { ok: false, error: `No active turn found for --turn ${details.turnId}` };
+    }
+  } else {
+    const turns = Object.values(activeTurns);
+    if (turns.length > 1) {
+      return { ok: false, error: 'Multiple active turns exist. Use --turn <id> to target the escalation.' };
+    }
+    targetTurn = turns[0] || null;
+  }
+
+  const turnRetained = Boolean(targetTurn);
+  const recoveryAction = details.action
+    || (turnRetained
+      ? 'Resolve the escalation, then run agentxchain step --resume'
+      : 'Resolve the escalation, then run agentxchain step');
+  const detail = typeof details.detail === 'string' && details.detail.trim()
+    ? details.detail.trim()
+    : reason;
+  const blockedOn = `escalation:operator:${slugifyEscalationReason(reason)}`;
+  const escalatedAt = new Date().toISOString();
+
+  const escalation = {
+    source: 'operator',
+    raised_by: 'human',
+    from_role: targetTurn?.assigned_role || null,
+    from_turn_id: targetTurn?.turn_id || null,
+    reason,
+    detail,
+    recovery_action: recoveryAction,
+    escalated_at: escalatedAt,
+  };
+
+  const blocked = markRunBlocked(root, {
+    blockedOn,
+    category: 'operator_escalation',
+    recovery: {
+      typed_reason: 'operator_escalation',
+      owner: 'human',
+      recovery_action: recoveryAction,
+      turn_retained: turnRetained,
+      detail,
+    },
+    turnId: targetTurn?.turn_id || null,
+    escalation,
+    hooksConfig: config?.hooks || {},
+    notificationConfig: config,
+  });
+  if (!blocked.ok) {
+    return blocked;
+  }
+
+  appendJsonl(root, LEDGER_PATH, {
+    timestamp: escalatedAt,
+    decision: 'operator_escalated',
+    run_id: blocked.state.run_id,
+    phase: blocked.state.phase,
+    blocked_on: blockedOn,
+    escalation,
+  });
+
+  emitPendingLifecycleNotification(root, config, blocked.state, 'operator_escalation_raised', {
+    source: 'operator',
+    blocked_on: blockedOn,
+    reason,
+    detail,
+    recovery_action: recoveryAction,
+  }, targetTurn);
+
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(blocked.state),
+    escalation,
+  };
+}
+
+export function reactivateGovernedRun(root, state, details = {}) {
+  if (!state || typeof state !== 'object') {
+    return { ok: false, error: 'State is required.' };
+  }
+
+  const now = new Date().toISOString();
+  const wasEscalation = state.status === 'blocked' && typeof state.blocked_on === 'string' && state.blocked_on.startsWith('escalation:');
+  const nextState = {
+    ...state,
+    status: 'active',
+    blocked_on: null,
+    blocked_reason: null,
+    escalation: null,
+  };
+
+  writeState(root, nextState);
+
+  if (wasEscalation) {
+    appendJsonl(root, LEDGER_PATH, {
+      timestamp: now,
+      decision: 'escalation_resolved',
+      run_id: state.run_id,
+      phase: state.phase,
+      resolved_via: details.via || 'unknown',
+      blocked_on: state.blocked_on,
+      escalation: state.escalation || null,
+      turn_id: state.escalation?.from_turn_id ?? getActiveTurn(state)?.turn_id ?? null,
+      role: state.escalation?.from_role ?? getActiveTurn(state)?.assigned_role ?? null,
+    });
+
+    emitPendingLifecycleNotification(details.root || root, details.notificationConfig, nextState, 'escalation_resolved', {
+      blocked_on: state.blocked_on,
+      resolved_via: details.via || 'unknown',
+      previous_escalation: state.escalation || null,
+    }, state.escalation?.from_turn_id ? getActiveTurns(state)[state.escalation.from_turn_id] || getActiveTurn(state) : getActiveTurn(state));
+  }
+
+  return { ok: true, state: attachLegacyCurrentTurnAlias(nextState) };
+}
+
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**
@@ -1014,6 +1204,7 @@ export function assignGovernedTurn(root, config, roleId) {
           detail,
           errorCode: beforeAssignmentHooks.tamper.error_code,
           turnRetained: activeCount > 0,
+          notificationConfig: config,
         });
         return {
           ok: false,
@@ -1240,6 +1431,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: beforeValidationHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1281,6 +1473,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: afterValidationHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1426,6 +1619,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: beforeAcceptanceHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: true,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1698,6 +1892,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         detail,
         errorCode: hookResults.tamper?.error_code || 'hook_post_commit_error',
         turnRetained: Object.keys(getActiveTurns(updatedState)).length > 0,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -1713,6 +1908,39 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  if (updatedState.status === 'blocked') {
+    emitBlockedNotification(root, config, updatedState, {
+      category: updatedState.blocked_reason?.category || 'needs_human',
+      blockedOn: updatedState.blocked_on,
+      recovery: updatedState.blocked_reason?.recovery || null,
+    }, currentTurn);
+  }
+
+  if (updatedState.pending_phase_transition) {
+    emitPendingLifecycleNotification(root, config, updatedState, 'phase_transition_pending', {
+      from: updatedState.pending_phase_transition.from,
+      to: updatedState.pending_phase_transition.to,
+      gate: updatedState.pending_phase_transition.gate,
+      requested_by_turn: updatedState.pending_phase_transition.requested_by_turn,
+    }, currentTurn);
+  }
+
+  if (updatedState.pending_run_completion) {
+    emitPendingLifecycleNotification(root, config, updatedState, 'run_completion_pending', {
+      gate: updatedState.pending_run_completion.gate,
+      requested_by_turn: updatedState.pending_run_completion.requested_by_turn,
+      requested_at: updatedState.pending_run_completion.requested_at,
+    }, currentTurn);
+  }
+
+  if (updatedState.status === 'completed') {
+    emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+      completed_at: updatedState.completed_at || now,
+      completed_via: completionResult?.action === 'complete' ? 'accept_turn' : 'accept_turn_direct',
+      requested_by_turn: completionResult?.requested_by_turn || turnResult.turn_id,
+    }, currentTurn);
+  }
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -1898,6 +2126,12 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
 
   writeState(root, updatedState);
 
+  emitBlockedNotification(root, config, updatedState, {
+    category: 'retries_exhausted',
+    blockedOn: updatedState.blocked_on,
+    recovery: updatedState.blocked_reason?.recovery || null,
+  }, updatedState.active_turns[currentTurn.turn_id]);
+
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   const hooksConfig = config?.hooks || {};
   if (hooksConfig.on_escalation?.length > 0) {
@@ -1977,6 +2211,7 @@ export function approvePhaseTransition(root, config) {
         detail,
         errorCode: gateHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: false,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -2067,6 +2302,7 @@ export function approveRunCompletion(root, config) {
         detail,
         errorCode: gateHooks.tamper?.error_code || 'hook_blocked',
         turnRetained: false,
+        notificationConfig: config,
       });
       return {
         ok: false,
@@ -2093,6 +2329,13 @@ export function approveRunCompletion(root, config) {
 
   writeState(root, updatedState);
 
+  emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+    completed_at: updatedState.completed_at,
+    completed_via: 'approve_run_completion',
+    gate: completion.gate,
+    requested_by_turn: completion.requested_by_turn || null,
+  }, completion.requested_by_turn ? getActiveTurns(state)[completion.requested_by_turn] || null : null);
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -2136,4 +2379,10 @@ function deriveNextRecommendedRole(turnResult, state, config) {
   return routing?.entry_role || null;
 }
 
-export { STATE_PATH, HISTORY_PATH, LEDGER_PATH, STAGING_PATH, TALK_PATH };
+export {
+  STATE_PATH,
+  HISTORY_PATH,
+  LEDGER_PATH,
+  STAGING_PATH,
+  TALK_PATH,
+};

package/src/lib/normalized-config.js

@@ -13,6 +13,7 @@
  */
 
 import { validateHooksConfig } from './hook-runner.js';
+import { validateNotificationsConfig } from './notification-runner.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
@@ -425,6 +426,12 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...hookValidation.errors);
   }
 
+  // Notifications (optional but validated if present)
+  if (data.notifications) {
+    const notificationValidation = validateNotificationsConfig(data.notifications);
+    errors.push(...notificationValidation.errors);
+  }
+
   return { ok: errors.length === 0, errors };
 }
 
@@ -467,6 +474,7 @@ export function normalizeV3(raw) {
     routing: buildLegacyRouting(Object.keys(agents)),
     gates: {},
     hooks: {},
+    notifications: {},
     budget: null,
     retention: {
       talk_strategy: 'append_only',
@@ -526,6 +534,7 @@ export function normalizeV4(raw) {
     routing: raw.routing || {},
     gates: raw.gates || {},
     hooks: raw.hooks || {},
+    notifications: raw.notifications || {},
     budget: raw.budget || null,
     retention: raw.retention || {
       talk_strategy: 'append_only',

package/src/lib/notification-runner.js

@@ -0,0 +1,330 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { interpolateHeaders } from './hook-runner.js';
+
+export const NOTIFICATION_AUDIT_PATH = '.agentxchain/notification-audit.jsonl';
+export const VALID_NOTIFICATION_EVENTS = [
+  'run_blocked',
+  'operator_escalation_raised',
+  'escalation_resolved',
+  'phase_transition_pending',
+  'run_completion_pending',
+  'run_completed',
+];
+
+const NOTIFICATION_NAME_RE = /^[a-z0-9_-]+$/;
+const MAX_NOTIFICATION_WEBHOOKS = 8;
+const HEADER_VAR_RE = /\$\{([^}]+)\}/g;
+const SIGKILL_GRACE_MS = 2000;
+const MAX_STDERR_CAPTURE = 4096;
+
+function collectMissingHeaderVars(headers, webhookEnv) {
+  if (!headers) return [];
+  const missing = [];
+  const mergedEnv = { ...process.env };
+
+  for (const [key, value] of Object.entries(webhookEnv || {})) {
+    if (typeof value === 'string') {
+      mergedEnv[key] = value;
+    }
+  }
+
+  for (const [headerName, value] of Object.entries(headers)) {
+    let match;
+    while ((match = HEADER_VAR_RE.exec(value)) !== null) {
+      if (mergedEnv[match[1]] === undefined) {
+        missing.push({ header: headerName, varName: match[1] });
+      }
+    }
+    HEADER_VAR_RE.lastIndex = 0;
+  }
+
+  return missing;
+}
+
+function appendAudit(root, entry) {
+  const filePath = join(root, NOTIFICATION_AUDIT_PATH);
+  if (!existsSync(dirname(filePath))) {
+    mkdirSync(dirname(filePath), { recursive: true });
+  }
+  appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+}
+
+function generateEventId() {
+  return `notif_${randomBytes(8).toString('hex')}`;
+}
+
+function executeWebhook(webhook, envelope) {
+  const startedAt = Date.now();
+  let headers;
+
+  try {
+    headers = interpolateHeaders(webhook.headers, webhook.env);
+  } catch (error) {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: Date.now() - startedAt,
+      message: String(error?.message || error),
+      stderr_excerpt: String(error?.message || error).slice(0, MAX_STDERR_CAPTURE),
+    };
+  }
+
+  headers['Content-Type'] = 'application/json';
+
+  const script = `
+const url = process.argv[1];
+const body = process.argv[2];
+const headers = JSON.parse(process.argv[3]);
+headers.Connection = 'close';
+(async () => {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(${webhook.timeout_ms}),
+    });
+    const text = await response.text();
+    process.stdout.write(JSON.stringify({ status: response.status, body: text }));
+    process.exit(0);
+  } catch (error) {
+    if (error?.name === 'TimeoutError' || error?.name === 'AbortError') {
+      process.stderr.write('timeout');
+      process.exit(2);
+    }
+    process.stderr.write(error?.message || String(error));
+    process.exit(1);
+  }
+})();
+`;
+
+  const result = spawnSync(process.execPath, ['-e', script, webhook.url, JSON.stringify(envelope), JSON.stringify(headers)], {
+    timeout: webhook.timeout_ms + SIGKILL_GRACE_MS,
+    maxBuffer: 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, ...(webhook.env || {}) },
+  });
+
+  const durationMs = Date.now() - startedAt;
+  const timedOut = result.error?.code === 'ETIMEDOUT' || durationMs > webhook.timeout_ms;
+  const stdout = result.stdout ? result.stdout.toString('utf8') : '';
+  const stderr = result.stderr ? result.stderr.toString('utf8').slice(0, MAX_STDERR_CAPTURE) : '';
+
+  if (timedOut) {
+    return {
+      delivered: false,
+      timed_out: true,
+      status_code: null,
+      duration_ms: durationMs,
+      message: `Timed out after ${webhook.timeout_ms}ms`,
+      stderr_excerpt: stderr,
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: durationMs,
+      message: stderr || `Webhook delivery failed with exit code ${result.status}`,
+      stderr_excerpt: stderr,
+    };
+  }
+
+  try {
+    const bridge = JSON.parse(stdout || '{}');
+    const statusCode = Number.isInteger(bridge.status) ? bridge.status : null;
+    const delivered = statusCode >= 200 && statusCode < 300;
+    return {
+      delivered,
+      timed_out: false,
+      status_code: statusCode,
+      duration_ms: durationMs,
+      message: delivered ? 'Delivered' : `Webhook returned HTTP ${statusCode}`,
+      stderr_excerpt: stderr,
+    };
+  } catch {
+    return {
+      delivered: false,
+      timed_out: false,
+      status_code: null,
+      duration_ms: durationMs,
+      message: 'Failed to parse webhook bridge response',
+      stderr_excerpt: stderr || stdout.slice(0, MAX_STDERR_CAPTURE),
+    };
+  }
+}
+
+export function validateNotificationsConfig(notifications) {
+  const errors = [];
+
+  if (!notifications || typeof notifications !== 'object' || Array.isArray(notifications)) {
+    errors.push('notifications must be an object');
+    return { ok: false, errors };
+  }
+
+  const allowedKeys = new Set(['webhooks']);
+  for (const key of Object.keys(notifications)) {
+    if (!allowedKeys.has(key)) {
+      errors.push(`notifications contains unknown field "${key}"`);
+    }
+  }
+
+  if (!('webhooks' in notifications)) {
+    return { ok: errors.length === 0, errors };
+  }
+
+  if (!Array.isArray(notifications.webhooks)) {
+    errors.push('notifications.webhooks must be an array');
+    return { ok: false, errors };
+  }
+
+  if (notifications.webhooks.length > MAX_NOTIFICATION_WEBHOOKS) {
+    errors.push(`notifications.webhooks: maximum ${MAX_NOTIFICATION_WEBHOOKS} webhooks`);
+  }
+
+  const names = new Set();
+  notifications.webhooks.forEach((webhook, index) => {
+    const label = `notifications.webhooks[${index}]`;
+
+    if (!webhook || typeof webhook !== 'object' || Array.isArray(webhook)) {
+      errors.push(`${label} must be an object`);
+      return;
+    }
+
+    if (typeof webhook.name !== 'string' || !webhook.name.trim()) {
+      errors.push(`${label}: name must be a non-empty string`);
+    } else if (!NOTIFICATION_NAME_RE.test(webhook.name)) {
+      errors.push(`${label}: name must match ^[a-z0-9_-]+$`);
+    } else if (names.has(webhook.name)) {
+      errors.push(`${label}: duplicate webhook name "${webhook.name}"`);
+    } else {
+      names.add(webhook.name);
+    }
+
+    if (typeof webhook.url !== 'string' || !webhook.url.trim()) {
+      errors.push(`${label}: url must be a non-empty string`);
+    } else if (!/^https?:\/\/.+/.test(webhook.url)) {
+      errors.push(`${label}: url must be a valid HTTP or HTTPS URL`);
+    }
+
+    if (!Array.isArray(webhook.events) || webhook.events.length === 0) {
+      errors.push(`${label}: events must be a non-empty array`);
+    } else {
+      for (const eventName of webhook.events) {
+        if (!VALID_NOTIFICATION_EVENTS.includes(eventName)) {
+          errors.push(
+            `${label}: events contains unknown event "${eventName}". Valid events: ${VALID_NOTIFICATION_EVENTS.join(', ')}`
+          );
+        }
+      }
+    }
+
+    if (!Number.isInteger(webhook.timeout_ms) || webhook.timeout_ms < 100 || webhook.timeout_ms > 30000) {
+      errors.push(`${label}: timeout_ms must be an integer between 100 and 30000`);
+    }
+
+    if ('headers' in webhook && webhook.headers !== undefined) {
+      if (!webhook.headers || typeof webhook.headers !== 'object' || Array.isArray(webhook.headers)) {
+        errors.push(`${label}: headers must be an object`);
+      } else {
+        for (const [key, value] of Object.entries(webhook.headers)) {
+          if (typeof value !== 'string') {
+            errors.push(`${label}: headers.${key} must be a string`);
+          }
+        }
+        const missingHeaderVars = collectMissingHeaderVars(webhook.headers, webhook.env);
+        if (missingHeaderVars.length > 0) {
+          errors.push(
+            `${label}: unresolved header env vars ${missingHeaderVars.map(({ header, varName }) => `${header}:${varName}`).join(', ')}`
+          );
+        }
+      }
+    }
+
+    if ('env' in webhook && webhook.env !== undefined) {
+      if (!webhook.env || typeof webhook.env !== 'object' || Array.isArray(webhook.env)) {
+        errors.push(`${label}: env must be an object`);
+      } else {
+        for (const [key, value] of Object.entries(webhook.env)) {
+          if (typeof value !== 'string') {
+            errors.push(`${label}: env.${key} must be a string`);
+          }
+        }
+      }
+    }
+  });
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function emitNotifications(root, config, state, eventType, payload = {}, turn = null) {
+  const webhooks = config?.notifications?.webhooks;
+  if (!Array.isArray(webhooks) || webhooks.length === 0) {
+    return { ok: true, results: [] };
+  }
+
+  if (!VALID_NOTIFICATION_EVENTS.includes(eventType)) {
+    return { ok: false, error: `Unknown notification event "${eventType}"`, results: [] };
+  }
+
+  const eventId = generateEventId();
+  const emittedAt = new Date().toISOString();
+  const envelope = {
+    schema_version: '0.1',
+    event_id: eventId,
+    event_type: eventType,
+    emitted_at: emittedAt,
+    project: {
+      id: config?.project?.id || 'unknown',
+      name: config?.project?.name || 'Unknown',
+      root,
+    },
+    run: {
+      run_id: state?.run_id || null,
+      status: state?.status || null,
+      phase: state?.phase || null,
+    },
+    turn: turn ? {
+      turn_id: turn.turn_id || null,
+      role_id: turn.assigned_role || turn.role_id || null,
+      attempt: Number.isInteger(turn.attempt) ? turn.attempt : null,
+      assigned_sequence: Number.isInteger(turn.assigned_sequence) ? turn.assigned_sequence : null,
+    } : null,
+    payload,
+  };
+
+  const results = [];
+  for (const webhook of webhooks) {
+    if (!webhook.events.includes(eventType)) {
+      continue;
+    }
+
+    const delivery = executeWebhook(webhook, envelope);
+    const auditEntry = {
+      event_id: eventId,
+      event_type: eventType,
+      notification_name: webhook.name,
+      transport: 'webhook',
+      delivered: delivery.delivered,
+      status_code: delivery.status_code,
+      timed_out: delivery.timed_out,
+      duration_ms: delivery.duration_ms,
+      message: delivery.message,
+      emitted_at: emittedAt,
+    };
+    if (delivery.stderr_excerpt) {
+      auditEntry.stderr_excerpt = delivery.stderr_excerpt;
+    }
+    appendAudit(root, auditEntry);
+    results.push(auditEntry);
+  }
+
+  return { ok: true, event_id: eventId, results };
+}