agentxchain 2.154.7 → 2.154.9

package/package.json

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

package/scripts/reproduce-bug-54.mjs

@@ -68,18 +68,12 @@ import {
   resolvePromptTransport,
   resolveStartupWatchdogMs,
 } from '../src/lib/adapters/local-cli-adapter.js';
+import { CLAUDE_ENV_AUTH_KEYS } from '../src/lib/claude-local-auth.js';
 
 const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
 const REPO_ROOT_GUESS = resolve(SCRIPT_DIR, '..', '..');
 
 const DIAGNOSTIC_ENV_KEYS = ['PATH', 'HOME', 'PWD', 'SHELL', 'TMPDIR'];
-const AUTH_ENV_KEYS_TO_PROBE = [
-  'ANTHROPIC_API_KEY',
-  'CLAUDE_API_KEY',
-  'CLAUDE_CODE_OAUTH_TOKEN',
-  'CLAUDE_CODE_USE_VERTEX',
-  'CLAUDE_CODE_USE_BEDROCK',
-];
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Argv parsing — kept simple/explicit so tester can read what their flags do.
@@ -227,7 +221,7 @@ function snapshotEnv(env) {
     if (typeof env[k] === 'string' && env[k].length > 0) visible[k] = env[k];
   }
   const authProbe = {};
-  for (const k of AUTH_ENV_KEYS_TO_PROBE) {
+  for (const k of CLAUDE_ENV_AUTH_KEYS) {
     authProbe[k] = typeof env[k] === 'string' && env[k].length > 0;
   }
   return { visible, auth_env_present: authProbe };

package/src/commands/approve-transition.js

@@ -1,10 +1,25 @@
 import chalk from 'chalk';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { approvePhaseTransition } from '../lib/governed-state.js';
+import { getNextPhase } from '../lib/gate-evaluator.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { checkCleanBaseline } from '../lib/repo-observer.js';
 
+function getStandingPendingHumanExitGate(state, config) {
+  const phase = state?.phase || null;
+  const gateId = phase ? config?.routing?.[phase]?.exit_gate || null : null;
+  if (!phase || !gateId) return null;
+  const gate = config?.gates?.[gateId] || null;
+  if (!gate?.requires_human_approval) return null;
+  if ((state?.phase_gate_status || {})[gateId] !== 'pending') return null;
+  return {
+    gateId,
+    from: phase,
+    to: getNextPhase(phase, config?.routing || {}) || null,
+  };
+}
+
 export async function approveTransitionCommand(opts) {
   const context = loadProjectContext();
   if (!context) {
@@ -25,6 +40,16 @@ export async function approveTransitionCommand(opts) {
     if (state?.phase) {
       console.log(chalk.dim(`  Current phase: ${state.phase}`));
     }
+    const standingGate = getStandingPendingHumanExitGate(state, config);
+    if (standingGate) {
+      console.log('');
+      console.log(chalk.yellow(`  Gate "${standingGate.gateId}" is pending human approval, but no phase transition object is prepared.`));
+      if (standingGate.to) {
+        console.log(chalk.dim(`  Expected transition: ${standingGate.from} → ${standingGate.to}`));
+      }
+      console.log(chalk.dim('  If this gate has an open human escalation, run: agentxchain unblock <hesc_id>'));
+      console.log(chalk.dim(`  To inspect gate evidence, run: agentxchain gate show ${standingGate.gateId} --evaluate`));
+    }
     process.exit(1);
   }
 

package/src/commands/gate.js

@@ -312,4 +312,23 @@ function showGate(requestedGateId, { root, config, state, gateIds, opts }) {
     }
     console.log('');
   }
+
+  const standingHint = getStandingRecoveryHint(gate, state);
+  if (standingHint) {
+    console.log(chalk.dim('  Recovery:'));
+    console.log(chalk.dim(`    No phase transition is prepared for "${standingHint.gateId}".`));
+    console.log(chalk.dim('    If a human escalation is open, resolve with: agentxchain unblock <hesc_id>'));
+    console.log(chalk.dim('    After resolution, run: agentxchain approve-transition'));
+    console.log('');
+  }
+}
+
+function getStandingRecoveryHint(gate, state) {
+  if (!gate) return null;
+  if (!gate.requires_human_approval) return null;
+  if (gate.status !== 'pending') return null;
+  const currentPhase = state?.phase || null;
+  if (!currentPhase || gate.linked_phase !== currentPhase) return null;
+  if (state?.pending_phase_transition) return null;
+  return { gateId: gate.id };
 }

package/src/commands/resume.js

@@ -65,35 +65,63 @@ function entrySatisfiesSyntheticGateVerification(gate, entry) {
   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) {
-  const turnId = state?.last_completed_turn_id || state?.blocked_reason?.turn_id || null;
+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;
   const historyPath = join(root, config?.files?.history || '.agentxchain/history.jsonl');
   if (!existsSync(historyPath)) return false;
@@ -130,7 +158,7 @@ function latestCompletedTurnWantsPhaseContinuation(root, state, config) {
     if (
       entry.status === 'needs_human'
       && entrySatisfiesSyntheticGateVerification(standingGate, entry)
-      && turnContributedToHumanApprovalGateArtifacts(root, state, config, entry)
+      && turnCanApproveHumanGateFromEscalation(root, state, config, entry, proposed)
     ) {
       return true;
     }
@@ -253,7 +281,7 @@ export async function resumeCommand(opts) {
     state.status === 'blocked'
     && resumeVia === 'operator_unblock'
     && hasStandingPendingExitGate(state, config)
-    && latestCompletedTurnWantsPhaseContinuation(root, state, config)
+    && latestCompletedTurnWantsPhaseContinuation(root, state, config, { turnId: opts.turn || null })
   ) {
     const reactivated = reactivateGovernedRun(root, state, { via: resumeVia, notificationConfig: config });
     if (!reactivated.ok) {
@@ -272,6 +300,7 @@ export async function resumeCommand(opts) {
     const phaseReconciliation = reconcilePhaseAdvanceBeforeDispatch(root, config, state, {
       allow_active_turn_cleanup: true,
       allow_standing_gate: true,
+      standing_gate_turn_id: opts.turn || null,
     });
     if (!phaseReconciliation.ok && !phaseReconciliation.state) {
       console.log(chalk.red(`Failed to reconcile phase gate before dispatch: ${phaseReconciliation.error}`));

package/src/lib/adapters/local-cli-adapter.js

@@ -42,6 +42,7 @@ const DIAGNOSTIC_ENV_KEYS = [
 ];
 const DIAGNOSTIC_STDERR_EXCERPT_LIMIT = 800;
 const DEFAULT_STARTUP_WATCHDOG_MS = 180_000;
+const DEFAULT_STARTUP_WATCHDOG_SIGKILL_GRACE_MS = 10_000;
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -89,6 +90,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     return { ok: false, error: `Runtime "${runtimeId}" not found in config` };
   }
   const startupWatchdogMs = startupWatchdogOverrideMs ?? resolveStartupWatchdogMs(config, runtime);
+  const startupWatchdogKillGraceMs = resolveStartupWatchdogKillGraceMs(options.startupWatchdogKillGraceMs);
 
   // Read the dispatch bundle prompt
   const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
@@ -188,6 +190,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     let spawnConfirmedAtMs = null;
     let firstOutputLatencyMs = null;
     let startupWatchdog = null;
+    let startupSigkillHandle = null;
     let startupTimedOut = false;
     let startupFailureType = null;
     let stdoutBytes = 0;
@@ -205,6 +208,10 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         clearTimeout(startupWatchdog);
         startupWatchdog = null;
       }
+      if (startupSigkillHandle) {
+        clearTimeout(startupSigkillHandle);
+        startupSigkillHandle = null;
+      }
     };
 
     const armStartupWatchdog = () => {
@@ -218,15 +225,31 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         startupTimedOut = true;
         startupFailureType = 'no_subprocess_output';
         logs.push(`[adapter] Startup watchdog fired after ${Math.round(startupWatchdogMs / 1000)}s with no output.`);
-      appendDiagnostic(logs, 'startup_watchdog_fired', {
-        startup_watchdog_ms: startupWatchdogMs,
-        pid: child.pid ?? null,
-        spawn_confirmed_at: spawnConfirmedAt,
-        elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
-      });
-      try {
-        child.kill('SIGTERM');
+        appendDiagnostic(logs, 'startup_watchdog_fired', {
+          startup_watchdog_ms: startupWatchdogMs,
+          startup_watchdog_sigkill_grace_ms: startupWatchdogKillGraceMs,
+          pid: child.pid ?? null,
+          spawn_confirmed_at: spawnConfirmedAt,
+          elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+        });
+        try {
+          child.kill('SIGTERM');
         } catch {}
+        if (startupWatchdogKillGraceMs > 0) {
+          startupSigkillHandle = setTimeout(() => {
+            logs.push('[adapter] Startup watchdog grace period expired. Sending SIGKILL.');
+            appendDiagnostic(logs, 'startup_watchdog_sigkill', {
+              startup_watchdog_ms: startupWatchdogMs,
+              startup_watchdog_sigkill_grace_ms: startupWatchdogKillGraceMs,
+              pid: child.pid ?? null,
+              spawn_confirmed_at: spawnConfirmedAt,
+              elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+            });
+            try {
+              child.kill('SIGKILL');
+            } catch {}
+          }, startupWatchdogKillGraceMs);
+        }
       }, startupWatchdogMs);
     };
 
@@ -313,6 +336,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     // Timeout handling per §20.4
     let timeoutHandle;
     let sigkillHandle;
+    let abortSigkillHandle;
 
     if (timeoutMs > 0 && timeoutMs < Infinity) {
       timeoutHandle = setTimeout(() => {
@@ -337,11 +361,13 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
+      clearTimeout(abortSigkillHandle);
       try {
         child.kill('SIGTERM');
       } catch {}
       // Give it 5 seconds to exit gracefully
-      setTimeout(() => {
+      abortSigkillHandle = setTimeout(() => {
+        abortSigkillHandle = null;
         try { child.kill('SIGKILL'); } catch {}
       }, 5000);
     };
@@ -355,6 +381,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
+      clearTimeout(abortSigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
 
       if (signal?.aborted) {
@@ -457,6 +484,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       clearStartupWatchdog();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
+      clearTimeout(abortSigkillHandle);
       if (signal) signal.removeEventListener('abort', onAbort);
       // BUG-54 hypothesis #1 fix: explicitly release stdio streams on the
       // error path so Node reclaims pipe handles immediately instead of
@@ -583,6 +611,13 @@ function resolveStartupWatchdogMs(config, runtime) {
   return DEFAULT_STARTUP_WATCHDOG_MS;
 }
 
+function resolveStartupWatchdogKillGraceMs(value) {
+  if (Number.isInteger(value) && value >= 0) {
+    return value;
+  }
+  return DEFAULT_STARTUP_WATCHDOG_SIGKILL_GRACE_MS;
+}
+
 /**
  * Check if the staged result file exists and has meaningful content.
  * Delegates to the shared `hasMeaningfulStagedResult` helper so watchdog,

package/src/lib/governed-state.js

@@ -1605,7 +1605,7 @@ function resolvePhaseTransitionSource(historyEntries, gateFailure, fallbackTurnI
   return requestedSource;
 }
 
-function buildStandingPhaseTransitionSource(state, config) {
+function buildStandingPhaseTransitionSource(state, config, opts = {}) {
   const phase = state?.phase;
   const routing = phase ? config?.routing?.[phase] : null;
   const gateId = routing?.exit_gate || null;
@@ -1617,7 +1617,7 @@ function buildStandingPhaseTransitionSource(state, config) {
     return null;
   }
   return {
-    turn_id: state?.last_completed_turn_id || state?.blocked_reason?.turn_id || null,
+    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,
@@ -2746,7 +2746,9 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null,
     currentState.queued_phase_transition || null,
   );
   if (!phaseSource?.phase_transition_request && opts?.allow_standing_gate === true) {
-    phaseSource = buildStandingPhaseTransitionSource(currentState, config);
+    phaseSource = buildStandingPhaseTransitionSource(currentState, config, {
+      turn_id: opts?.standing_gate_turn_id || null,
+    });
   }
   if (!phaseSource?.phase_transition_request) {
     return {
@@ -2801,6 +2803,7 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null,
       const cleanup = cleanupPhaseAdvanceArtifacts(root, nextState, config, prevPhase);
       nextState = cleanup.state;
       writeState(root, nextState);
+      writeSessionCheckpoint(root, nextState, 'phase_reconciled');
       appendJsonl(root, LEDGER_PATH, {
         type: 'approval_policy',
         gate_type: 'phase_transition',
@@ -2919,6 +2922,7 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null,
   nextState = cleanup.state;
 
   writeState(root, nextState);
+  writeSessionCheckpoint(root, nextState, 'phase_reconciled');
   const retiredIntentIds = retireApprovedPhaseScopedIntents(root, nextState, config, prevPhase, now);
   if (retiredIntentIds.length > 0) {
     emitRunEvent(root, 'intent_retired_by_phase_advance', {
@@ -6152,17 +6156,26 @@ export function approvePhaseTransition(root, config, opts = {}) {
     run_id: updatedState.run_id,
     phase: updatedState.phase,
     status: 'active',
-    payload: { gate_type: 'phase_transition', from: transition.from, to: transition.to },
+    turn: transition.requested_by_turn ? { turn_id: transition.requested_by_turn, role_id: null } : undefined,
+    payload: {
+      gate_id: transition.gate || null,
+      gate_type: 'phase_transition',
+      from: transition.from,
+      to: transition.to,
+      requested_by_turn: transition.requested_by_turn || null,
+    },
   });
   emitRunEvent(root, 'phase_entered', {
     run_id: updatedState.run_id,
     phase: updatedState.phase,
     status: 'active',
+    turn: transition.requested_by_turn ? { turn_id: transition.requested_by_turn, role_id: null } : undefined,
     payload: {
       from: transition.from,
       to: transition.to,
       gate_id: transition.gate || 'no_gate',
       trigger: 'human_approved',
+      requested_by_turn: transition.requested_by_turn || null,
     },
   });
   emitRunEvent(root, 'phase_cleanup', {