agentxchain 2.145.0 → 2.147.0

package/src/lib/governed-state.js

@@ -955,6 +955,67 @@ function writeState(root, state) {
   safeWriteJson(join(root, STATE_PATH), stripLegacyCurrentTurn(state));
 }
 
+export function transitionActiveTurnLifecycle(root, turnId, nextStatus, options = {}) {
+  const state = readState(root);
+  if (!state) {
+    return { ok: false, error: 'No governed state found' };
+  }
+
+  const activeTurns = { ...(state.active_turns || {}) };
+  const turn = activeTurns[turnId];
+  if (!turn) {
+    return { ok: false, error: `Turn ${turnId} not found in active turns` };
+  }
+
+  const nowIso = options.at || new Date().toISOString();
+  const nextTurn = { ...turn };
+
+  if (nextStatus === 'dispatched') {
+    nextTurn.status = 'dispatched';
+    nextTurn.dispatched_at = nowIso;
+    delete nextTurn.started_at;
+    delete nextTurn.worker_attached_at;
+    delete nextTurn.worker_pid;
+    delete nextTurn.first_output_at;
+    delete nextTurn.first_output_stream;
+    emitRunEvent(root, 'turn_dispatched', {
+      run_id: state.run_id,
+      phase: state.phase,
+      status: state.status,
+      turn: { turn_id: turnId, role_id: turn.assigned_role },
+      intent_id: turn.intake_context?.intent_id || null,
+    });
+  } else if (nextStatus === 'starting') {
+    nextTurn.status = 'starting';
+    nextTurn.started_at = nowIso;
+    nextTurn.worker_attached_at = nowIso;
+    if (options.pid != null) {
+      nextTurn.worker_pid = options.pid;
+    }
+  } else if (nextStatus === 'running') {
+    nextTurn.status = 'running';
+    nextTurn.started_at = nextTurn.started_at || nowIso;
+    nextTurn.first_output_at = nextTurn.first_output_at || nowIso;
+    if (options.stream) {
+      nextTurn.first_output_stream = nextTurn.first_output_stream || options.stream;
+    }
+  } else {
+    return { ok: false, error: `Unsupported turn lifecycle status: ${nextStatus}` };
+  }
+
+  activeTurns[turnId] = nextTurn;
+  const nextState = {
+    ...state,
+    active_turns: activeTurns,
+  };
+  writeState(root, nextState);
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(nextState),
+    turn: attachLegacyCurrentTurnAlias(nextState).active_turns[turnId],
+  };
+}
+
 function appendJsonl(root, relPath, entry) {
   const filePath = join(root, relPath);
   mkdirSync(dirname(filePath), { recursive: true });
@@ -1894,6 +1955,137 @@ export function reconcileRecoveryActionsWithConfig(state, config) {
   return { state: nextState, changed };
 }
 
+function inferApprovalPauseFromState(state, config) {
+  if (!state || typeof state !== 'object' || !config) {
+    return null;
+  }
+
+  if (state.pending_run_completion?.gate) {
+    return {
+      gateType: 'run_completion',
+      gateId: state.pending_run_completion.gate,
+      pendingField: 'pending_run_completion',
+      pendingValue: state.pending_run_completion,
+      typedReason: 'pending_run_completion',
+      recoveryAction: 'agentxchain approve-completion',
+    };
+  }
+
+  if (state.pending_phase_transition?.gate) {
+    return {
+      gateType: 'phase_transition',
+      gateId: state.pending_phase_transition.gate,
+      pendingField: 'pending_phase_transition',
+      pendingValue: state.pending_phase_transition,
+      typedReason: 'pending_phase_transition',
+      recoveryAction: 'agentxchain approve-transition',
+    };
+  }
+
+  // Approval waits are post-turn pause states. If a turn is still retained,
+  // recover the turn first instead of synthesizing a gate wait from stale
+  // blocked_on metadata.
+  if (getActiveTurnCount(state) > 0) {
+    return null;
+  }
+
+  if (typeof state.blocked_on !== 'string' || !state.blocked_on.startsWith('human_approval:')) {
+    return null;
+  }
+
+  const gateId = state.blocked_on.slice('human_approval:'.length) || null;
+  const currentRouting = config.routing?.[state.phase];
+  if (!gateId || !currentRouting?.exit_gate || currentRouting.exit_gate !== gateId) {
+    return null;
+  }
+
+  const requestedByTurn = state.blocked_reason?.turn_id ?? state.last_completed_turn_id ?? null;
+  const nextPhase = getNextPhase(state.phase, config.routing || {});
+
+  if (nextPhase) {
+    return {
+      gateType: 'phase_transition',
+      gateId,
+      pendingField: 'pending_phase_transition',
+      pendingValue: {
+        from: state.phase,
+        to: nextPhase,
+        gate: gateId,
+        requested_by_turn: requestedByTurn,
+      },
+      typedReason: 'pending_phase_transition',
+      recoveryAction: 'agentxchain approve-transition',
+    };
+  }
+
+  return {
+    gateType: 'run_completion',
+    gateId,
+    pendingField: 'pending_run_completion',
+    pendingValue: {
+      gate: gateId,
+      requested_by_turn: requestedByTurn,
+    },
+    typedReason: 'pending_run_completion',
+    recoveryAction: 'agentxchain approve-completion',
+  };
+}
+
+export function reconcileApprovalPausesWithConfig(state, config) {
+  if (!state || typeof state !== 'object' || !config) {
+    return { state, changed: false };
+  }
+
+  const inferred = inferApprovalPauseFromState(state, config);
+  if (!inferred) {
+    return { state, changed: false };
+  }
+
+  let nextState = state;
+  let changed = false;
+
+  if (!state[inferred.pendingField]) {
+    nextState = {
+      ...nextState,
+      [inferred.pendingField]: inferred.pendingValue,
+    };
+    changed = true;
+  }
+
+  if (nextState.status === 'blocked' || nextState.blocked_reason != null) {
+    nextState = {
+      ...nextState,
+      status: 'paused',
+      blocked_reason: null,
+    };
+    changed = true;
+  }
+
+  const recovery = nextState.blocked_reason?.recovery;
+  if (recovery && (
+    recovery.typed_reason !== inferred.typedReason
+    || recovery.recovery_action !== inferred.recoveryAction
+    || recovery.detail !== inferred.gateId
+  )) {
+    nextState = {
+      ...nextState,
+      blocked_reason: {
+        ...nextState.blocked_reason,
+        recovery: {
+          ...recovery,
+          typed_reason: inferred.typedReason,
+          recovery_action: inferred.recoveryAction,
+          turn_retained: false,
+          detail: inferred.gateId,
+        },
+      },
+    };
+    changed = true;
+  }
+
+  return { state: nextState, changed };
+}
+
 function inferBlockedReasonFromState(state) {
   if (!state || typeof state !== 'object') {
     return null;
@@ -2328,6 +2520,144 @@ export function reactivateGovernedRun(root, state, details = {}) {
   };
 }
 
+export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null) {
+  const currentState = state && typeof state === 'object' ? state : readState(root);
+  if (!currentState) {
+    return { ok: false, error: 'No governed state.json found' };
+  }
+
+  if (currentState.status !== 'active' || getActiveTurnCount(currentState) > 0) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const gateFailure = currentState.last_gate_failure;
+  if (gateFailure?.gate_type !== 'phase_transition') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const historyEntries = readJsonlEntries(root, HISTORY_PATH);
+  const phaseSource = findHistoryTurnRequest(
+    historyEntries,
+    gateFailure.requested_by_turn || currentState.last_completed_turn_id || null,
+    'phase_transition',
+  );
+  if (!phaseSource?.phase_transition_request) {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+    };
+  }
+
+  const gateResult = evaluatePhaseExit({
+    state: { ...currentState, history: historyEntries },
+    config,
+    acceptedTurn: phaseSource,
+    root,
+  });
+
+  if (gateResult.action === 'awaiting_human_approval') {
+    const pausedState = {
+      ...currentState,
+      status: 'paused',
+      blocked_on: `human_approval:${gateResult.gate_id}`,
+      blocked_reason: null,
+      pending_phase_transition: {
+        from: currentState.phase,
+        to: gateResult.next_phase,
+        gate: gateResult.gate_id,
+        requested_by_turn: phaseSource.turn_id,
+        requested_at: new Date().toISOString(),
+      },
+    };
+    writeState(root, pausedState);
+    const approved = approvePhaseTransition(root, config);
+    return {
+      ok: approved.ok,
+      error: approved.error,
+      state: approved.state || attachLegacyCurrentTurnAlias(readState(root)),
+      advanced: approved.ok,
+      from_phase: currentState.phase,
+      to_phase: approved.state?.phase || gateResult.next_phase || null,
+      gate_id: gateResult.gate_id || null,
+      gateResult,
+    };
+  }
+
+  if (gateResult.action !== 'advance') {
+    return {
+      ok: true,
+      state: attachLegacyCurrentTurnAlias(currentState),
+      advanced: false,
+      gateResult,
+    };
+  }
+
+  const now = new Date().toISOString();
+  const prevPhase = currentState.phase;
+  const nextState = {
+    ...currentState,
+    phase: gateResult.next_phase,
+    phase_entered_at: now,
+    blocked_on: null,
+    blocked_reason: null,
+    last_gate_failure: null,
+    pending_phase_transition: null,
+    queued_phase_transition: null,
+    phase_gate_status: {
+      ...(currentState.phase_gate_status || {}),
+      [gateResult.gate_id || 'no_gate']: 'passed',
+    },
+  };
+
+  writeState(root, nextState);
+  const retiredIntentIds = retireApprovedPhaseScopedIntents(root, nextState, config, prevPhase, now);
+  if (retiredIntentIds.length > 0) {
+    emitRunEvent(root, 'intent_retired_by_phase_advance', {
+      run_id: nextState.run_id,
+      phase: nextState.phase,
+      status: nextState.status,
+      turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+      payload: {
+        exited_phase: prevPhase,
+        entered_phase: gateResult.next_phase,
+        retired_count: retiredIntentIds.length,
+        retired_intent_ids: retiredIntentIds,
+      },
+    });
+  }
+  emitRunEvent(root, 'phase_entered', {
+    run_id: nextState.run_id,
+    phase: nextState.phase,
+    status: nextState.status,
+    turn: phaseSource.turn_id ? { turn_id: phaseSource.turn_id, role_id: phaseSource.role || phaseSource.assigned_role || null } : undefined,
+    payload: {
+      from: prevPhase,
+      to: gateResult.next_phase,
+      gate_id: gateResult.gate_id || 'no_gate',
+      trigger: 'reconciled_before_dispatch',
+    },
+  });
+
+  return {
+    ok: true,
+    state: attachLegacyCurrentTurnAlias(nextState),
+    advanced: true,
+    from_phase: prevPhase,
+    to_phase: gateResult.next_phase,
+    gate_id: gateResult.gate_id || null,
+    gateResult,
+  };
+}
+
 // ── Core Operations ──────────────────────────────────────────────────────────
 
 /**
@@ -2629,9 +2959,9 @@ export function assignGovernedTurn(root, config, roleId, options = {}) {
   const newTurn = {
     turn_id: turnId,
     assigned_role: roleId,
-    status: 'running',
+    status: 'assigned',
     attempt: 1,
-    started_at: now,
+    assigned_at: now,
     deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
     runtime_id: runtimeId,
     baseline,
@@ -2681,14 +3011,6 @@ export function assignGovernedTurn(root, config, roleId, options = {}) {
 
   writeState(root, updatedState);
 
-  emitRunEvent(root, 'turn_dispatched', {
-    run_id: updatedState.run_id,
-    phase: updatedState.phase,
-    status: updatedState.status,
-    turn: { turn_id: turnId, role_id: roleId },
-    intent_id: options.intakeContext?.intent_id || null,
-  });
-
   // Session checkpoint — non-fatal, written after every successful turn assignment.
   // Pass the captured baseline so session.json agrees with state.json (BUG-2 fix).
   writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
@@ -2901,9 +3223,9 @@ export function reissueTurn(root, config, opts = {}) {
   const newTurn = {
     turn_id: newTurnId,
     assigned_role: roleId,
-    status: 'running',
+    status: 'assigned',
     attempt: (oldTurn.attempt || 1) + 1,
-    started_at: now,
+    assigned_at: now,
     deadline_at: new Date(Date.now() + timeoutMinutes * 60 * 1000).toISOString(),
     runtime_id: currentRuntimeId,
     baseline: newBaseline,
@@ -2922,10 +3244,30 @@ export function reissueTurn(root, config, opts = {}) {
   delete newActiveTurns[turnId];
   newActiveTurns[newTurnId] = newTurn;
 
+  // BUG-51 fix #6 (reissue path): release the old turn's reservation and create
+  // a fresh reservation for the new turn. Without this, an operator who runs
+  // `reissue-turn` before the watchdog fires (e.g., drift recovery, or
+  // operator-initiated reissue) leaves the old turn's reservation lingering in
+  // budget_reservations and the new turn carries no budget tracking at all.
+  // The watchdog paths (reconcileStaleTurns / failTurnStartup) already release
+  // on stalled/failed_start; this closes the same hole on the reissue surface.
+  const newReservations = { ...(state.budget_reservations || {}) };
+  delete newReservations[turnId];
+  const reissueEstimate = estimateTurnBudget(config, roleId);
+  if (reissueEstimate > 0) {
+    newReservations[newTurnId] = {
+      reserved_usd: reissueEstimate,
+      role_id: roleId,
+      created_at: now,
+      reissued_from: oldTurn.turn_id,
+    };
+  }
+
   const updatedState = {
     ...state,
     turn_sequence: nextSequence,
     active_turns: newActiveTurns,
+    budget_reservations: newReservations,
   };
 
   writeState(root, updatedState);
@@ -5044,7 +5386,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
  * Reject a governed turn.
  *
  * 1. Preserve the invalid staged artifact under .agentxchain/dispatch/rejected/
- * 2. Increment current_turn.attempt or escalate if retries exhausted
+ * 2. Increment the active turn's attempt counter or escalate if retries exhausted
  * 3. Clear staging file
  *
  * Does NOT append to history.jsonl or decision-ledger.jsonl.

package/src/lib/intake.js

@@ -8,6 +8,7 @@ import {
   assignGovernedTurn,
   getActiveTurns,
   getActiveTurnCount,
+  transitionActiveTurnLifecycle,
   STATE_PATH,
 } from './governed-state.js';
 import { loadProjectContext, loadProjectState } from './config.js';
@@ -1090,10 +1091,18 @@ export function startIntent(root, intentId, options = {}) {
       return { ok: false, error: `dispatch bundle failed: ${bundleResult.error}`, exitCode: 1 };
     }
 
-    finalizeDispatchManifest(root, assignedTurn.turn_id, {
+    const manifestResult = finalizeDispatchManifest(root, assignedTurn.turn_id, {
       run_id: state.run_id,
       role: assignedTurn.assigned_role,
     });
+    if (!manifestResult.ok) {
+      return { ok: false, error: `dispatch manifest failed: ${manifestResult.error}`, exitCode: 1 };
+    }
+    const dispatched = transitionActiveTurnLifecycle(root, assignedTurn.turn_id, 'dispatched');
+    if (!dispatched.ok) {
+      return { ok: false, error: `dispatch lifecycle transition failed: ${dispatched.error}`, exitCode: 1 };
+    }
+    state = dispatched.state;
   }
 
   // Update intent: planned → executing

package/src/lib/normalized-config.js

@@ -395,6 +395,11 @@ export function validateV4Config(data, projectRoot) {
   } else {
     if (typeof data.project.id !== 'string' || !data.project.id.trim()) errors.push('project.id must be a non-empty string');
     if (typeof data.project.name !== 'string' || !data.project.name.trim()) errors.push('project.name must be a non-empty string');
+    if ('default_branch' in data.project) {
+      if (typeof data.project.default_branch !== 'string' || !data.project.default_branch.trim()) {
+        errors.push('project.default_branch must be a non-empty string when provided');
+      }
+    }
     // Optional project.goal field
     if (data.project.goal !== undefined && data.project.goal !== null) {
       if (typeof data.project.goal !== 'string') {
@@ -480,6 +485,17 @@ export function validateV4Config(data, projectRoot) {
             }
           }
         }
+        // Schema publishes max_output_tokens as `integer, minimum: 1`. The
+        // api-proxy adapter silently falls back to 4096 on `0` / null /
+        // undefined and passes negative/non-integer values straight through
+        // to the provider, which is the same silent-fallback defect class
+        // the run_loop watchdog knobs had (DEC-SILENT-FALLBACK-DEFECT-CLASS-001).
+        // Reject at write time so the operator sees the bad value immediately.
+        if ('max_output_tokens' in rt) {
+          if (!Number.isInteger(rt.max_output_tokens) || rt.max_output_tokens < 1) {
+            errors.push(`Runtime "${id}": max_output_tokens must be a positive integer`);
+          }
+        }
         if ('retry_policy' in rt) {
           validateApiProxyRetryPolicy(id, rt.retry_policy, errors);
         }
@@ -597,6 +613,14 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...timeoutValidation.errors);
   }
 
+  // Run-loop watchdog knobs (BUG-47 / BUG-51). Schema publishes both as
+  // positive integers; runtime silently falls back to defaults on bad input,
+  // which misleads operators into thinking their config --set took effect.
+  // Reject at config-write / validate time so the operator sees the problem.
+  if (data.run_loop !== undefined) {
+    errors.push(...validateRunLoopConfig(data.run_loop));
+  }
+
   // Admission control (ADM-001..004) is handled by the validate, doctor, and
   // run-loop paths which call runAdmissionControl() directly. Config schema
   // validation here should not duplicate that surface.
@@ -604,6 +628,30 @@ export function validateV4Config(data, projectRoot) {
   return { ok: errors.length === 0, errors, warnings };
 }
 
+export function validateRunLoopConfig(runLoop) {
+  const errors = [];
+  if (runLoop === null || typeof runLoop !== 'object' || Array.isArray(runLoop)) {
+    errors.push('run_loop must be an object');
+    return errors;
+  }
+  validateRunLoopPositiveInteger('run_loop.startup_watchdog_ms', runLoop.startup_watchdog_ms, errors);
+  validateRunLoopPositiveInteger('run_loop.stale_turn_threshold_ms', runLoop.stale_turn_threshold_ms, errors);
+  return errors;
+}
+
+function validateRunLoopPositiveInteger(path, value, errors) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    errors.push(`${path} must be a positive integer (milliseconds)`);
+    return;
+  }
+  if (value < 1) {
+    errors.push(`${path} must be a positive integer (milliseconds)`);
+  }
+}
+
 export function validateBudgetConfig(budget) {
   const errors = [];
 
@@ -1145,7 +1193,9 @@ export function normalizeV4(raw) {
       id: raw.project?.id || 'unknown',
       name: raw.project?.name || 'Unknown',
       ...(typeof raw.project?.goal === 'string' && raw.project.goal.trim() ? { goal: raw.project.goal.trim() } : {}),
-      default_branch: raw.project?.default_branch || 'main',
+      default_branch: typeof raw.project?.default_branch === 'string' && raw.project.default_branch.trim()
+        ? raw.project.default_branch.trim()
+        : 'main',
     },
     roles,
     runtimes: raw.runtimes || {},

package/src/lib/recent-event-summary.js

@@ -54,6 +54,9 @@ function describeEvent(eventType, entry) {
     }
     case 'turn_checkpointed':
     case 'turn_stalled':
+    case 'turn_start_failed':
+    case 'runtime_spawn_failed':
+    case 'stdout_attach_failed':
       return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
     case 'dispatch_progress':
       return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
@@ -76,6 +79,15 @@ function describeEvent(eventType, entry) {
     case 'escalation_resolved':
     case 'budget_exceeded_warn':
       return `${prefix}${eventType}`;
+    case 'session_continuation': {
+      const prev = trimToNull(entry.payload?.previous_run_id);
+      const next = trimToNull(entry.payload?.next_run_id);
+      const objective = trimToNull(entry.payload?.next_objective);
+      if (prev && next) {
+        return `${prefix}${eventType} ${prev} -> ${next}${objective ? ` (${objective})` : ''}`;
+      }
+      return `${prefix}${eventType}`;
+    }
     default:
       if (trimToNull(entry.summary)) return entry.summary.trim();
       return `${prefix}${eventType || 'unknown_event'}`;

package/src/lib/run-events.js

@@ -25,6 +25,9 @@ export const VALID_RUN_EVENTS = [
   'acceptance_failed',
   'turn_reissued',
   'turn_stalled',
+  'turn_start_failed',
+  'runtime_spawn_failed',
+  'stdout_attach_failed',
   'turn_checkpointed',
   'coordinator_retry',
   'coordinator_retry_projection_warning',
@@ -39,6 +42,7 @@ export const VALID_RUN_EVENTS = [
   'human_escalation_raised',
   'human_escalation_resolved',
   'dispatch_progress',
+  'session_continuation',
 ];
 
 /**