agentxchain 2.154.8 → 2.154.10

package/package.json

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

package/src/commands/resume.js

@@ -27,6 +27,7 @@ import {
   getActiveTurnCount,
   reactivateGovernedRun,
   reconcilePhaseAdvanceBeforeDispatch,
+  reconcileRunCompletionBeforeDispatch,
   transitionActiveTurnLifecycle,
   STATE_PATH,
 } from '../lib/governed-state.js';
@@ -59,42 +60,77 @@ function getStandingPendingExitGate(state, config) {
   return config?.gates?.[gateId] || null;
 }
 
+function isFinalPhase(state, config) {
+  const phase = state?.phase;
+  if (!phase) return false;
+  const phases = Object.keys(config?.routing || {});
+  return phases.length > 0 && phases[phases.length - 1] === phase;
+}
+
 function entrySatisfiesSyntheticGateVerification(gate, entry) {
   if (!gate?.requires_verification_pass) return true;
   const verificationStatus = entry?.verification?.status;
   return verificationStatus === 'pass' || verificationStatus === 'attested_pass';
 }
 
-function turnContributedToHumanApprovalGateArtifacts(root, state, config, entry) {
-  // Returns true only when the accepted turn itself produced at least one of
-  // the phase exit gate's required_files AND all required_files are present
-  // on disk. This distinguishes a PM turn that finished phase work and
-  // escalated for final sign-off (BUG-52 third variant) from a generic
-  // escalation where the agent blocked BEFORE writing gate artifacts
-  // (schedule-daemon `needs_decision` fixture).
+function evaluateHumanApprovalGateArtifacts(root, state, config, entry) {
+  // Returns the artifact readiness shape for a human-required phase exit gate.
+  // A turn can be a valid standing-gate source either by producing one of the
+  // required files, or by re-verifying already-complete gate artifacts as the
+  // phase entry role before escalating to the human reviewer.
   const phase = state?.phase;
   const gateId = phase ? config?.routing?.[phase]?.exit_gate : null;
-  if (!gateId) return false;
+  if (!gateId) return { ready: false, contributed: false, entryRole: false };
   const gate = config?.gates?.[gateId];
   if (!gate || !Array.isArray(gate.requires_files) || gate.requires_files.length === 0) {
-    return false;
+    return { ready: false, contributed: false, entryRole: false };
   }
-  if (!gate.requires_human_approval) return false;
+  if (!gate.requires_human_approval) return { ready: false, contributed: false, entryRole: false };
   const filesChanged = Array.isArray(entry?.files_changed) ? entry.files_changed : [];
   const required = gate.requires_files.filter((p) => typeof p === 'string' && p.trim());
-  if (required.length === 0) return false;
+  if (required.length === 0) return { ready: false, contributed: false, entryRole: false };
   const changedSet = new Set(filesChanged.filter((p) => typeof p === 'string'));
   const contributed = required.some((relPath) => changedSet.has(relPath));
-  if (!contributed) return false;
-  for (const relPath of required) {
-    if (!existsSync(join(root, relPath))) return false;
-  }
-  return true;
+  const ready = required.every((relPath) => existsSync(join(root, relPath)));
+  const entryRole = Boolean(config?.routing?.[phase]?.entry_role)
+    && (entry?.role === config.routing[phase].entry_role || entry?.assigned_role === config.routing[phase].entry_role);
+  return { ready, contributed, entryRole };
+}
+
+function turnCanApproveHumanGateFromEscalation(root, state, config, entry, proposed) {
+  const artifacts = evaluateHumanApprovalGateArtifacts(root, state, config, entry);
+  if (!artifacts.ready) return false;
+  if (artifacts.contributed) return true;
+  const phase = state?.phase;
+  const gateId = phase ? config?.routing?.[phase]?.exit_gate : null;
+  const gateApprovalText = [
+    entry?.summary,
+    entry?.needs_human_reason,
+    entry?.verification?.evidence_summary,
+    state?.blocked_on,
+    state?.blocked_reason?.recovery?.detail,
+    ...(Array.isArray(entry?.decisions)
+      ? entry.decisions.flatMap((decision) => [decision?.statement, decision?.rationale])
+      : []),
+  ]
+    .filter((value) => typeof value === 'string' && value.trim())
+    .join('\n')
+    .toLowerCase();
+  const referencesHumanGateApproval = Boolean(gateId)
+    && (
+      gateApprovalText.includes(gateId.toLowerCase())
+      || (gateApprovalText.includes('gate') && gateApprovalText.includes('human approval'))
+      || (gateApprovalText.includes('gate') && gateApprovalText.includes('human-required'))
+    );
+  // tusq.dev BUG-52 real shape: PM re-verified already-complete planning
+  // artifacts, changed no files by design, and escalated to human because the
+  // gate requires human approval. The human unblock is the gate approval.
+  return proposed === 'human' && artifacts.entryRole && referencesHumanGateApproval;
 }
 
 function latestCompletedTurnWantsPhaseContinuation(root, state, config, opts = {}) {
   const turnId = opts?.turnId || state?.last_completed_turn_id || state?.blocked_reason?.turn_id || null;
-  if (!turnId) return false;
+  if (!turnId || isFinalPhase(state, config)) return false;
   const historyPath = join(root, config?.files?.history || '.agentxchain/history.jsonl');
   if (!existsSync(historyPath)) return false;
   const lines = readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
@@ -130,7 +166,36 @@ function latestCompletedTurnWantsPhaseContinuation(root, state, config, opts = {
     if (
       entry.status === 'needs_human'
       && entrySatisfiesSyntheticGateVerification(standingGate, entry)
-      && turnContributedToHumanApprovalGateArtifacts(root, state, config, entry)
+      && turnCanApproveHumanGateFromEscalation(root, state, config, entry, proposed)
+    ) {
+      return true;
+    }
+    return false;
+  }
+  return false;
+}
+
+function latestCompletedTurnWantsRunCompletion(root, state, config, opts = {}) {
+  const turnId = opts?.turnId || state?.last_completed_turn_id || state?.blocked_reason?.turn_id || null;
+  if (!turnId || !isFinalPhase(state, config)) return false;
+  const historyPath = join(root, config?.files?.history || '.agentxchain/history.jsonl');
+  if (!existsSync(historyPath)) return false;
+  const lines = readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    let entry = null;
+    try {
+      entry = JSON.parse(lines[index]);
+    } catch {
+      continue;
+    }
+    if (entry?.turn_id !== turnId) continue;
+    if (entry.run_completion_request === true) return true;
+    const standingGate = getStandingPendingExitGate(state, config);
+    const proposed = typeof entry.proposed_next_role === 'string' ? entry.proposed_next_role.trim() : '';
+    if (
+      entry.status === 'needs_human'
+      && entrySatisfiesSyntheticGateVerification(standingGate, entry)
+      && turnCanApproveHumanGateFromEscalation(root, state, config, entry, proposed)
     ) {
       return true;
     }
@@ -301,6 +366,57 @@ export async function resumeCommand(opts) {
     }
   }
 
+  if (
+    state.status === 'blocked'
+    && resumeVia === 'operator_unblock'
+    && hasStandingPendingExitGate(state, config)
+    && latestCompletedTurnWantsRunCompletion(root, state, config, { turnId: opts.turn || null })
+  ) {
+    const reactivated = reactivateGovernedRun(root, state, { via: resumeVia, 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}`));
+    if (reactivated.migration_notice) {
+      console.log(chalk.yellow(reactivated.migration_notice));
+    }
+    if (reactivated.phantom_notice) {
+      console.log(chalk.yellow(reactivated.phantom_notice));
+    }
+
+    const completionReconciliation = reconcileRunCompletionBeforeDispatch(root, config, state, {
+      allow_active_turn_cleanup: true,
+      allow_standing_gate: true,
+      standing_gate_turn_id: opts.turn || null,
+    });
+    if (!completionReconciliation.ok && !completionReconciliation.state) {
+      console.log(chalk.red(`Failed to reconcile run completion before dispatch: ${completionReconciliation.error}`));
+      process.exit(1);
+    }
+    state = completionReconciliation.state || state;
+    if (completionReconciliation.completed) {
+      console.log(chalk.green(`Completed run before dispatch: ${state.run_id}`));
+      return;
+    }
+    markRunBlocked(root, {
+      category: 'needs_human',
+      blockedOn: state.blocked_on || 'human:unblock_completion_reconcile_failed',
+      recovery: {
+        typed_reason: 'needs_human',
+        owner: 'human',
+        recovery_action: 'agentxchain approve-completion',
+        turn_retained: true,
+        detail: 'Operator unblock resolved the escalation, but no run completion could be materialized from the current gate state.',
+      },
+      turnId: opts.turn || null,
+      notificationConfig: config,
+    });
+    console.log(chalk.red('Unblock did not materialize run completion; leaving the run blocked for manual recovery.'));
+    process.exit(1);
+  }
+
   if (state.status === 'blocked' && activeCount > 0 && !skipRetainedRedispatch) {
     let retainedTurn = null;
     if (opts.turn) {

package/src/lib/continuous-run.js

@@ -790,11 +790,15 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   const activeGovernedState = loadProjectState(root, context.config);
+  const queuedIntent = session.current_run_id
+    ? findNextDispatchableIntent(root, { run_id: session.current_run_id })
+    : { ok: false };
   if (
     session.current_run_id
     && activeGovernedState?.status === 'active'
     && activeGovernedState.run_id === session.current_run_id
-    && Object.keys(activeGovernedState.active_turns || {}).length > 0
+    && !contOpts.continueFrom
+    && !queuedIntent.ok
   ) {
     log('Continuing active governed run.');
     let execution;
@@ -855,7 +859,9 @@ export async function advanceContinuousRunOnce(context, session, contOpts, execu
   }
 
   // Step 1: Check intake queue for pending work (BUG-34: scope to current run)
-  const queued = findNextDispatchableIntent(root, { run_id: session.current_run_id });
+  const queued = queuedIntent.ok
+    ? queuedIntent
+    : findNextDispatchableIntent(root, { run_id: session.current_run_id });
   let targetIntentId = null;
   let visionObjective = null;
 

package/src/lib/governed-state.js

@@ -1629,6 +1629,30 @@ function buildStandingPhaseTransitionSource(state, config, opts = {}) {
   };
 }
 
+function buildStandingRunCompletionSource(state, config, opts = {}) {
+  const phase = state?.phase;
+  const routing = phase ? config?.routing?.[phase] : null;
+  const gateId = routing?.exit_gate || null;
+  const nextPhase = getNextPhase(phase, config?.routing || {});
+  if (!phase || !gateId || nextPhase) {
+    return null;
+  }
+  if ((state?.phase_gate_status || {})[gateId] !== 'pending') {
+    return null;
+  }
+  return {
+    turn_id: opts?.turn_id || state?.last_completed_turn_id || state?.blocked_reason?.turn_id || null,
+    run_id: state?.run_id || null,
+    role: null,
+    assigned_role: null,
+    phase,
+    status: 'completed',
+    run_completion_request: true,
+    summary: `Synthetic ${gateId} completion source for operator-unblocked standing gate.`,
+    verification: { status: 'pass' },
+  };
+}
+
 function getPhaseRoles(config, phase) {
   const routing = config?.routing?.[phase] || {};
   const roles = new Set();
@@ -2974,6 +2998,204 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null,
   };
 }
 
+export function reconcileRunCompletionBeforeDispatch(root, config, state = null, opts = {}) {
+  const currentState = state && typeof state === 'object' ? state : readState(root);
+  if (!currentState) {
+    return { ok: false, error: 'No governed state.json found' };
+  }
+
+  const activeTurnCount = getActiveTurnCount(currentState);
+  const allowActiveTurnCleanup = opts?.allow_active_turn_cleanup === true;
+  if (currentState.status !== 'active' || (activeTurnCount > 0 && !allowActiveTurnCleanup)) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      completed: false,
+    };
+  }
+
+  const gateFailure = currentState.last_gate_failure;
+  if (gateFailure && gateFailure.gate_type !== 'run_completion') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      completed: false,
+    };
+  }
+
+  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+  const requestedTurnId = gateFailure?.requested_by_turn
+    || currentState.queued_run_completion?.requested_by_turn
+    || currentState.last_completed_turn_id
+    || null;
+  let completionSource = findHistoryTurnRequest(historyEntries, requestedTurnId, 'run_completion');
+  if (!completionSource?.run_completion_request && opts?.allow_standing_gate === true) {
+    completionSource = buildStandingRunCompletionSource(currentState, config, {
+      turn_id: opts?.standing_gate_turn_id || null,
+    });
+  }
+  if (!completionSource?.run_completion_request) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      completed: false,
+    };
+  }
+
+  const completionResult = evaluateRunCompletion({
+    state: { ...currentState, history: historyEntries },
+    config,
+    acceptedTurn: completionSource,
+    root,
+  });
+
+  if (completionResult.action === 'awaiting_human_approval') {
+    const approvalResult = evaluateApprovalPolicy({
+      gateResult: completionResult,
+      gateType: 'run_completion',
+      state: { ...currentState, history: historyEntries },
+      config,
+    });
+
+    if (approvalResult.action === 'auto_approve') {
+      const now = new Date().toISOString();
+      const updatedState = {
+        ...currentState,
+        status: 'completed',
+        completed_at: now,
+        blocked_on: null,
+        blocked_reason: null,
+        last_gate_failure: null,
+        pending_run_completion: null,
+        queued_run_completion: null,
+        queued_phase_transition: null,
+        phase_gate_status: {
+          ...(currentState.phase_gate_status || {}),
+          [completionResult.gate_id || 'no_gate']: 'passed',
+        },
+      };
+      writeState(root, updatedState);
+      clearSlaReminders(root, 'pending_run_completion');
+      appendJsonl(root, LEDGER_PATH, {
+        type: 'approval_policy',
+        gate_type: 'run_completion',
+        action: 'auto_approve',
+        matched_rule: approvalResult.matched_rule,
+        reason: approvalResult.reason,
+        gate_id: completionResult.gate_id || null,
+        timestamp: now,
+      });
+      emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+        completed_at: updatedState.completed_at,
+        completed_via: 'approval_policy_reconciled_before_dispatch',
+        gate: completionResult.gate_id || null,
+        requested_by_turn: completionSource.turn_id || null,
+      }, null);
+      emitRunEvent(root, 'gate_approved', {
+        run_id: updatedState.run_id,
+        phase: updatedState.phase,
+        status: 'completed',
+        turn: completionSource.turn_id ? { turn_id: completionSource.turn_id, role_id: completionSource.role || completionSource.assigned_role || null } : undefined,
+        payload: {
+          gate_type: 'run_completion',
+          gate_id: completionResult.gate_id || null,
+          requested_by_turn: completionSource.turn_id || null,
+          trigger: 'auto_approved',
+        },
+      });
+      emitRunEvent(root, 'run_completed', {
+        run_id: updatedState.run_id,
+        phase: updatedState.phase,
+        status: 'completed',
+        payload: { completed_at: updatedState.completed_at },
+      });
+      writeSessionCheckpoint(root, updatedState, 'run_completed');
+      recordRunHistory(root, updatedState, config, 'completed');
+      return {
+        ok: true,
+        state: attachLegacyCurrentTurnAlias(updatedState),
+        completed: true,
+        gate_id: completionResult.gate_id || null,
+        completionResult,
+        approval_policy: approvalResult,
+      };
+    }
+
+    const pausedState = {
+      ...currentState,
+      status: 'paused',
+      blocked_on: `human_approval:${completionResult.gate_id}`,
+      blocked_reason: null,
+      pending_run_completion: {
+        gate: completionResult.gate_id,
+        requested_by_turn: completionSource.turn_id,
+        requested_at: new Date().toISOString(),
+      },
+      queued_run_completion: null,
+      queued_phase_transition: null,
+    };
+    writeState(root, pausedState);
+    const approved = approveRunCompletion(root, config);
+    return {
+      ok: approved.ok,
+      error: approved.error,
+      state: approved.state || attachLegacyCurrentTurnAlias(readState(root)),
+      completed: approved.ok,
+      gate_id: completionResult.gate_id || null,
+      completionResult,
+      approval_policy: approvalResult,
+    };
+  }
+
+  if (completionResult.action !== 'complete') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      completed: false,
+      completionResult,
+    };
+  }
+
+  const now = new Date().toISOString();
+  const updatedState = {
+    ...currentState,
+    status: 'completed',
+    completed_at: now,
+    blocked_on: null,
+    blocked_reason: null,
+    last_gate_failure: null,
+    pending_run_completion: null,
+    queued_run_completion: null,
+    queued_phase_transition: null,
+    phase_gate_status: {
+      ...(currentState.phase_gate_status || {}),
+      [completionResult.gate_id || 'no_gate']: 'passed',
+    },
+  };
+  writeState(root, updatedState);
+  emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
+    completed_at: updatedState.completed_at,
+    completed_via: 'reconciled_before_dispatch',
+    gate: completionResult.gate_id || null,
+    requested_by_turn: completionSource.turn_id || null,
+  }, null);
+  emitRunEvent(root, 'run_completed', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'completed',
+    payload: { completed_at: updatedState.completed_at },
+  });
+  writeSessionCheckpoint(root, updatedState, 'run_completed');
+  recordRunHistory(root, updatedState, config, 'completed');
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(updatedState),
+    completed: true,
+    gate_id: completionResult.gate_id || null,
+    completionResult,
+  };
+}
+
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**