agentxchain 2.5.0 → 2.7.0

package/src/lib/export.js

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+import { loadProjectContext, loadProjectState } from './config.js';
+import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
+import { loadCoordinatorState } from './coordinator-state.js';
+
+const EXPORT_SCHEMA_VERSION = '0.2';
+
+const COORDINATOR_INCLUDED_ROOTS = [
+  'agentxchain-multi.json',
+  '.agentxchain/multirepo/state.json',
+  '.agentxchain/multirepo/history.jsonl',
+  '.agentxchain/multirepo/barriers.json',
+  '.agentxchain/multirepo/decision-ledger.jsonl',
+  '.agentxchain/multirepo/barrier-ledger.jsonl',
+];
+
+const INCLUDED_ROOTS = [
+  'agentxchain.json',
+  '.agentxchain/state.json',
+  '.agentxchain/history.jsonl',
+  '.agentxchain/decision-ledger.jsonl',
+  '.agentxchain/hook-audit.jsonl',
+  '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/dispatch',
+  '.agentxchain/staging',
+  '.agentxchain/transactions/accept',
+  '.agentxchain/intake',
+  '.agentxchain/multirepo',
+];
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function collectPaths(root, relPath) {
+  const absPath = join(root, relPath);
+  if (!existsSync(absPath)) {
+    return [];
+  }
+
+  const stats = statSync(absPath);
+  if (stats.isFile()) {
+    return [relPath];
+  }
+
+  if (!stats.isDirectory()) {
+    return [];
+  }
+
+  const entries = readdirSync(absPath, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name, 'en'));
+
+  const files = [];
+  for (const entry of entries) {
+    const childRelPath = `${relPath}/${entry.name}`;
+    if (entry.isDirectory()) {
+      files.push(...collectPaths(root, childRelPath));
+    } else if (entry.isFile()) {
+      files.push(childRelPath);
+    }
+  }
+  return files;
+}
+
+function parseJsonl(relPath, raw) {
+  if (!raw.trim()) {
+    return [];
+  }
+
+  return raw
+    .split('\n')
+    .filter((line) => line.trim())
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`${relPath}: invalid JSONL at line ${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+function parseFile(root, relPath) {
+  const absPath = join(root, relPath);
+  const buffer = readFileSync(absPath);
+  const raw = buffer.toString('utf8');
+
+  let format = 'text';
+  let data = raw;
+
+  if (relPath.endsWith('.json')) {
+    try {
+      data = JSON.parse(raw);
+      format = 'json';
+    } catch (error) {
+      throw new Error(`${relPath}: invalid JSON: ${error.message}`);
+    }
+  } else if (relPath.endsWith('.jsonl')) {
+    data = parseJsonl(relPath, raw);
+    format = 'jsonl';
+  }
+
+  return {
+    format,
+    bytes: buffer.byteLength,
+    sha256: sha256(buffer),
+    content_base64: buffer.toString('base64'),
+    data,
+  };
+}
+
+function countJsonl(files, relPath) {
+  return Array.isArray(files[relPath]?.data) ? files[relPath].data.length : 0;
+}
+
+function countDirectoryFiles(files, prefix) {
+  return Object.keys(files).filter((path) => path.startsWith(`${prefix}/`)).length;
+}
+
+export function buildRunExport(startDir = process.cwd()) {
+  const context = loadProjectContext(startDir);
+  if (!context) {
+    return {
+      ok: false,
+      error: 'No governed project found. Run this inside an AgentXchain governed project.',
+    };
+  }
+
+  if (context.config.protocol_mode !== 'governed') {
+    return {
+      ok: false,
+      error: 'Run export only supports governed projects in this slice.',
+    };
+  }
+
+  const { root, rawConfig, config, version } = context;
+  const state = loadProjectState(root, config);
+
+  const collectedPaths = [...new Set(INCLUDED_ROOTS.flatMap((relPath) => collectPaths(root, relPath)))]
+    .sort((a, b) => a.localeCompare(b, 'en'));
+
+  const files = {};
+  for (const relPath of collectedPaths) {
+    files[relPath] = parseFile(root, relPath);
+  }
+
+  const activeTurns = Object.keys(state?.active_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+  const retainedTurns = Object.keys(state?.retained_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
+
+  return {
+    ok: true,
+    export: {
+      schema_version: EXPORT_SCHEMA_VERSION,
+      export_kind: 'agentxchain_run_export',
+      exported_at: new Date().toISOString(),
+      project_root: relative(process.cwd(), root) || '.',
+      project: {
+        id: config.project.id,
+        name: config.project.name,
+        template: config.template || 'generic',
+        protocol_mode: config.protocol_mode,
+        schema_version: version,
+      },
+      summary: {
+        run_id: state?.run_id || null,
+        status: state?.status || null,
+        phase: state?.phase || null,
+        active_turn_ids: activeTurns,
+        retained_turn_ids: retainedTurns,
+        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/')),
+        coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
+      },
+      files,
+      config: rawConfig,
+      state,
+    },
+  };
+}
+
+export function buildCoordinatorExport(startDir = process.cwd()) {
+  const workspaceRoot = resolve(startDir);
+  const configPath = join(workspaceRoot, COORDINATOR_CONFIG_FILE);
+
+  if (!existsSync(configPath)) {
+    return {
+      ok: false,
+      error: `No ${COORDINATOR_CONFIG_FILE} found at ${workspaceRoot}.`,
+    };
+  }
+
+  let rawConfig;
+  try {
+    rawConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Invalid JSON in ${COORDINATOR_CONFIG_FILE}: ${err.message}`,
+    };
+  }
+
+  const configResult = loadCoordinatorConfig(workspaceRoot);
+  const normalizedConfig = configResult.ok ? configResult.config : null;
+
+  // Collect coordinator-level files
+  const collectedPaths = [...new Set(
+    COORDINATOR_INCLUDED_ROOTS.flatMap((relPath) => collectPaths(workspaceRoot, relPath)),
+  )].sort((a, b) => a.localeCompare(b, 'en'));
+
+  const files = {};
+  for (const relPath of collectedPaths) {
+    files[relPath] = parseFile(workspaceRoot, relPath);
+  }
+
+  // Load coordinator state for summary
+  const coordState = loadCoordinatorState(workspaceRoot);
+
+  // Build repo run statuses from coordinator state
+  const repoRunStatuses = {};
+  if (coordState?.repo_runs) {
+    for (const [repoId, repoRun] of Object.entries(coordState.repo_runs)) {
+      repoRunStatuses[repoId] = repoRun.status || 'unknown';
+    }
+  }
+
+  // Count barriers from barriers.json
+  let barrierCount = 0;
+  const barriersKey = '.agentxchain/multirepo/barriers.json';
+  if (files[barriersKey]?.format === 'json' && files[barriersKey]?.data) {
+    barrierCount = Object.keys(files[barriersKey].data).length;
+  }
+
+  // Determine repos from config
+  const repos = {};
+  const repoEntries = rawConfig.repos && typeof rawConfig.repos === 'object'
+    ? Object.entries(rawConfig.repos)
+    : [];
+
+  for (const [repoId, repoDef] of repoEntries) {
+    const repoPath = repoDef?.path || '';
+    const resolvedPath = resolve(workspaceRoot, repoPath);
+
+    try {
+      const childExport = buildRunExport(resolvedPath);
+      if (childExport.ok) {
+        repos[repoId] = {
+          ok: true,
+          path: repoPath,
+          export: childExport.export,
+        };
+      } else {
+        repos[repoId] = {
+          ok: false,
+          path: repoPath,
+          error: childExport.error,
+        };
+      }
+    } catch (err) {
+      repos[repoId] = {
+        ok: false,
+        path: repoPath,
+        error: err.message || String(err),
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    export: {
+      schema_version: EXPORT_SCHEMA_VERSION,
+      export_kind: 'agentxchain_coordinator_export',
+      exported_at: new Date().toISOString(),
+      workspace_root: relative(process.cwd(), workspaceRoot) || '.',
+      coordinator: {
+        project_id: rawConfig.project?.id || null,
+        project_name: rawConfig.project?.name || null,
+        schema_version: rawConfig.schema_version || null,
+        repo_count: repoEntries.length,
+        workstream_count: rawConfig.workstreams
+          ? Object.keys(rawConfig.workstreams).length
+          : 0,
+      },
+      summary: {
+        super_run_id: coordState?.super_run_id || null,
+        status: coordState?.status || null,
+        phase: coordState?.phase || null,
+        repo_run_statuses: repoRunStatuses,
+        barrier_count: barrierCount,
+        history_entries: countJsonl(files, '.agentxchain/multirepo/history.jsonl'),
+        decision_entries: countJsonl(files, '.agentxchain/multirepo/decision-ledger.jsonl'),
+      },
+      files,
+      config: rawConfig,
+      repos,
+    },
+  };
+}

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,
+};