agentxchain 2.148.0 → 2.149.1

package/src/lib/dispatch-streams.js

@@ -0,0 +1,21 @@
+const TURN_RUNNING_PROOF_STREAMS = new Set(['stdout', 'request', 'staged_result']);
+
+export function isKnownTurnRunningProofStream(stream) {
+  return typeof stream === 'string' && TURN_RUNNING_PROOF_STREAMS.has(stream);
+}
+
+export function isPersistedTurnStartupProofStream(stream) {
+  if (stream == null) {
+    // Legacy states may have first_output_at without a tagged stream.
+    return true;
+  }
+  return isKnownTurnRunningProofStream(stream);
+}
+
+export function isDispatchProgressProofOutputStream(stream) {
+  return stream === 'stdout';
+}
+
+export function isDispatchProgressDiagnosticStream(stream) {
+  return stream === 'stderr';
+}

package/src/lib/governed-state.js

@@ -77,6 +77,7 @@ import {
   derivePhaseScopeFromIntentMetadata,
   evaluateAcceptanceItemLifecycle,
 } from './intent-phase-scope.js';
+import { isKnownTurnRunningProofStream } from './dispatch-streams.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -995,8 +996,10 @@ export function transitionActiveTurnLifecycle(root, turnId, nextStatus, options
   } 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) {
+    if (options.stream == null) {
+      nextTurn.first_output_at = nextTurn.first_output_at || nowIso;
+    } else if (isKnownTurnRunningProofStream(options.stream)) {
+      nextTurn.first_output_at = nextTurn.first_output_at || nowIso;
       nextTurn.first_output_stream = nextTurn.first_output_stream || options.stream;
     }
   } else {
@@ -1531,6 +1534,68 @@ function findHistoryTurnRequest(historyEntries, turnId, kind) {
   return entry;
 }
 
+function findMatchingPhaseTransitionDeclarer(historyEntries, gateFailure) {
+  if (!Array.isArray(historyEntries) || historyEntries.length === 0) {
+    return null;
+  }
+
+  const targetPhase = typeof gateFailure?.to_phase === 'string' && gateFailure.to_phase.length > 0
+    ? gateFailure.to_phase
+    : null;
+  const sourcePhase = typeof gateFailure?.from_phase === 'string' && gateFailure.from_phase.length > 0
+    ? gateFailure.from_phase
+    : null;
+
+  return [...historyEntries].reverse().find((entry) => {
+    if (!entry?.phase_transition_request) {
+      return false;
+    }
+    if (targetPhase && entry.phase_transition_request !== targetPhase) {
+      return false;
+    }
+    if (sourcePhase && entry.phase && entry.phase !== sourcePhase) {
+      return false;
+    }
+    return true;
+  }) || null;
+}
+
+function resolvePhaseTransitionSource(historyEntries, gateFailure, fallbackTurnId, queuedPhaseTransition = null) {
+  const requestedTurnId = gateFailure?.requested_by_turn
+    || queuedPhaseTransition?.requested_by_turn
+    || fallbackTurnId
+    || null;
+  const requestedSource = findHistoryTurnRequest(historyEntries, requestedTurnId, 'phase_transition');
+  if (requestedSource?.phase_transition_request) {
+    return requestedSource;
+  }
+
+  // Turn 94: a bare null-failure path only gets the exact last_completed_turn
+  // lookup. Without a surviving gate_failure or queued_phase_transition
+  // descriptor, mining "the latest request anywhere in history" can replay an
+  // unrelated older phase request on resume.
+  if (!gateFailure && !queuedPhaseTransition) {
+    return requestedSource;
+  }
+
+  const fallbackSource = findMatchingPhaseTransitionDeclarer(
+    historyEntries,
+    gateFailure || (
+      queuedPhaseTransition
+        ? {
+            from_phase: queuedPhaseTransition.from || null,
+            to_phase: queuedPhaseTransition.to || null,
+          }
+        : null
+    ),
+  );
+  if (fallbackSource?.phase_transition_request) {
+    return { ...fallbackSource, phase_transition_request: fallbackSource.phase_transition_request };
+  }
+
+  return requestedSource;
+}
+
 function buildBlockedReason({ category, recovery, turnId, blockedAt = new Date().toISOString() }) {
   return {
     category,
@@ -2535,7 +2600,19 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null)
   }
 
   const gateFailure = currentState.last_gate_failure;
-  if (gateFailure?.gate_type !== 'phase_transition') {
+  // BUG-52 Turn 93 (DEC-BUG52-NEEDS-HUMAN-PHASE-ADVANCE-001): accept two entry
+  // shapes. (A) gate_failed left `last_gate_failure.gate_type === 'phase_transition'`
+  // (existing Turn 57-60 coverage). (B) The accepted turn emitted
+  // `status: 'needs_human'`, which short-circuits gate evaluation inside
+  // `applyAcceptedTurn` (see needs_human guard at line 4657) — so
+  // `last_gate_failure` stays null and `queued_phase_transition` stays null, but
+  // the turn's `phase_transition_request` is preserved in history. After unblock
+  // clears the human block, we must still attempt to advance using the
+  // history-declared request; otherwise the dispatcher re-dispatches the current
+  // phase's entry role and the tester reproduces the planning_signoff false-loop.
+  // A non-`phase_transition` gate failure (e.g. run_completion) is still a hard
+  // skip — this expansion only opens the null-failure path.
+  if (gateFailure && gateFailure.gate_type !== 'phase_transition') {
     return {
       ok: true,
       state: attachLegacyCurrentTurnAlias(currentState),
@@ -2544,10 +2621,11 @@ export function reconcilePhaseAdvanceBeforeDispatch(root, config, state = null)
   }
 
   const historyEntries = readJsonlEntries(root, HISTORY_PATH);
-  const phaseSource = findHistoryTurnRequest(
+  const phaseSource = resolvePhaseTransitionSource(
     historyEntries,
-    gateFailure.requested_by_turn || currentState.last_completed_turn_id || null,
-    'phase_transition',
+    gateFailure,
+    currentState.last_completed_turn_id || null,
+    currentState.queued_phase_transition || null,
   );
   if (!phaseSource?.phase_transition_request) {
     return {

package/src/lib/normalized-config.js

@@ -442,6 +442,9 @@ export function validateV4Config(data, projectRoot) {
       if (!VALID_RUNTIME_TYPES.includes(rt.type)) {
         errors.push(`Runtime "${id}": type must be one of: ${VALID_RUNTIME_TYPES.join(', ')}`);
       }
+      if (rt.type === 'local_cli') {
+        validateRuntimePositiveInteger(`Runtime "${id}": startup_watchdog_ms`, rt.startup_watchdog_ms, errors);
+      }
       // Validate prompt_transport for local_cli runtimes
       if (rt.type === 'local_cli' && rt.prompt_transport) {
         if (!VALID_PROMPT_TRANSPORTS.includes(rt.prompt_transport)) {
@@ -652,6 +655,15 @@ function validateRunLoopPositiveInteger(path, value, errors) {
   }
 }
 
+function validateRuntimePositiveInteger(path, value, errors) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+    errors.push(`${path} must be a positive integer (milliseconds)`);
+  }
+}
+
 export function validateBudgetConfig(budget) {
   const errors = [];
 

package/src/lib/schemas/agentxchain-config.schema.json

@@ -253,6 +253,11 @@
         "cwd": {
           "$ref": "#/$defs/non_empty_string"
         },
+        "startup_watchdog_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional local_cli-specific override for the startup watchdog. When set, this runtime uses the declared threshold before falling back to run_loop.startup_watchdog_ms."
+        },
         "prompt_transport": {
           "enum": ["argv", "stdin", "dispatch_bundle_only"]
         },

package/src/lib/stale-turn-watchdog.js

@@ -24,7 +24,8 @@
  * requiring a background daemon.
  *
  * Default thresholds:
- *   - Startup watchdog: 30 seconds (configurable via run_loop.startup_watchdog_ms)
+ *   - Startup watchdog: 30 seconds (configurable via run_loop.startup_watchdog_ms
+ *     or runtimes.<id>.startup_watchdog_ms for local_cli runtimes)
  *   - local_cli stale turns: 10 minutes
  *   - api_proxy stale turns: 5 minutes
  *   - Configurable via run_loop.stale_turn_threshold_ms in agentxchain.json
@@ -36,6 +37,7 @@ import { safeWriteJson } from './safe-write.js';
 import { emitRunEvent, readRunEvents } from './run-events.js';
 import { getTurnStagingResultPath } from './turn-paths.js';
 import { getDispatchProgressRelativePath } from './dispatch-progress.js';
+import { isPersistedTurnStartupProofStream } from './dispatch-streams.js';
 import { hasMeaningfulStagedResult } from './staged-result-proof.js';
 
 const DEFAULT_LOCAL_CLI_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
@@ -122,7 +124,6 @@ export function detectGhostTurns(root, state, config) {
   const activeTurns = state?.active_turns || {};
   const ghosts = [];
   const now = Date.now();
-  const startupThreshold = resolveStartupThreshold(config);
 
   for (const [turnId, turn] of Object.entries(activeTurns)) {
     if (!['dispatched', 'starting', 'running', 'retrying'].includes(turn.status)) continue;
@@ -130,6 +131,13 @@ export function detectGhostTurns(root, state, config) {
     const lifecycleStart = parseGhostLifecycleStart(turn);
     if (!Number.isFinite(lifecycleStart)) continue;
 
+    // BUG-54 follow-up: per-turn threshold honors per-runtime startup override.
+    // Without this, an operator who sets `runtimes.<id>.startup_watchdog_ms`
+    // higher than the global to accommodate a slow QA/Claude runtime would still
+    // have ghost detection fire at the global threshold, defeating the override.
+    const runtime = config?.runtimes?.[turn.runtime_id];
+    const startupThreshold = resolveStartupThreshold(config, runtime);
+
     const runningMs = now - lifecycleStart;
     if (runningMs < startupThreshold) continue;
 
@@ -274,7 +282,16 @@ function resolveThreshold(turn, config) {
   return DEFAULT_LOCAL_CLI_THRESHOLD_MS;
 }
 
-function resolveStartupThreshold(config) {
+function resolveStartupThreshold(config, runtime) {
+  // BUG-54 follow-up: per-runtime override beats the global.
+  // Mirrors `resolveStartupWatchdogMs()` in local-cli-adapter.js so the
+  // ghost-detection scanner uses the same threshold the in-flight adapter
+  // watchdog uses; otherwise the scanner pre-empts the override.
+  if (runtime && runtime.type === 'local_cli'
+      && Number.isInteger(runtime.startup_watchdog_ms)
+      && runtime.startup_watchdog_ms > 0) {
+    return runtime.startup_watchdog_ms;
+  }
   const configThreshold = config?.run_loop?.startup_watchdog_ms;
   if (typeof configThreshold === 'number' && configThreshold > 0) {
     return configThreshold;
@@ -291,6 +308,7 @@ export function failTurnStartup(root, state, config, turnId, details = {}) {
   if (!turn) {
     return { ok: false, error: `Turn ${turnId} not found in active turns` };
   }
+  const runtime = config?.runtimes?.[turn.runtime_id];
 
   const nowIso = new Date().toISOString();
   const activeTurns = { ...(state.active_turns || {}) };
@@ -300,7 +318,7 @@ export function failTurnStartup(root, state, config, turnId, details = {}) {
     role: turn.assigned_role || 'unknown',
     runtime_id: turn.runtime_id || 'unknown',
     running_ms: details.running_ms ?? computeLifecycleAgeMs(turn),
-    threshold_ms: details.threshold_ms ?? resolveStartupThreshold(config),
+    threshold_ms: details.threshold_ms ?? resolveStartupThreshold(config, runtime),
     failure_type: classifyStartupFailureType(turn, null, details.failure_type || 'no_subprocess_output'),
     recommendation: details.recommendation
       || `Turn ${turnId} failed to start cleanly. Run \`agentxchain reissue-turn --turn ${turnId} --reason ghost\` to recover.`,
@@ -476,7 +494,14 @@ function mapStartupFailureEventType(failureType) {
 }
 
 function hasStartupProof(turn, progress) {
-  if (turn.first_output_at) {
+  // DEC-BUG54-STDERR-IS-NOT-STARTUP-PROOF-002 (Turn 88) extended to the
+  // fast-startup watchdog in Turn 89: stderr activity is not startup proof.
+  // A subprocess that spawns and emits stderr-only text must still be caught
+  // by the fast watchdog as stdout_attach_failed. Only stdout-derived signals
+  // (stream-tagged `turn.first_output_at`, `progress.first_output_at`, or
+  // `progress.output_lines`) satisfy startup proof. `progress.stderr_lines`
+  // deliberately does NOT.
+  if (turn.first_output_at && isPersistedTurnStartupProofStream(turn.first_output_stream)) {
     return true;
   }
   if (!progress || typeof progress !== 'object') {
@@ -485,7 +510,7 @@ function hasStartupProof(turn, progress) {
   if (progress.first_output_at) {
     return true;
   }
-  return Number(progress.output_lines || 0) > 0 || Number(progress.stderr_lines || 0) > 0;
+  return Number(progress.output_lines || 0) > 0;
 }
 
 function hasTurnScopedStagedResult(root, turnId) {

package/src/lib/turn-checkpoint.js

@@ -57,6 +57,14 @@ function normalizeFilesChanged(filesChanged) {
   return normalizeCheckpointableFiles(filesChanged);
 }
 
+function normalizeGitBaselineRef(ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('git:')) {
+    return null;
+  }
+  const gitRef = ref.slice(4).trim();
+  return gitRef || null;
+}
+
 function supportsLegacyFilesChangedRecovery(entry) {
   const artifactType = entry?.artifact?.type;
   return artifactType === 'workspace' || artifactType === 'patch';
@@ -148,14 +156,21 @@ function diffMissingDeclaredPaths(declaredFiles, stagedFiles) {
  * Partition paths that were missing from the staged-diff into
  * (a) paths genuinely absent from git (untracked or dirty without staging)
  * (b) paths already committed upstream (tracked in HEAD, no pending diff)
+ * (c) paths tracked and clean at HEAD but unchanged since the accepted
+ *     baseline — the BUG-55A wrong-lineage case (actor committed the file
+ *     off the accepted lineage, e.g. on a throwaway side-branch or the
+ *     lineage was reset to baseline).
  *
- * BUG-55A completeness must only fail on (a). An actor that committed a
- * declared file before `checkpoint-turn` ran (see BUG-23 scenario) is
- * already-checkpointed-upstream; treating that as "missing from checkpoint"
- * is a false positive from the completeness gate.
+ * BUG-55A completeness must fail on (a) and (c). (c) has a different
+ * operator-visible recovery path than (a): the file DID exist in some
+ * commit but is not reachable from the accepted baseline + HEAD comparison
+ * the governed run relies on. Surface it separately so the CLI can tell
+ * the operator which failure they hit.
  */
-function partitionDeclaredPathsByUpstreamPresence(root, missingPaths) {
+function partitionDeclaredPathsByUpstreamPresence(root, missingPaths, options = {}) {
+  const baselineRef = normalizeGitBaselineRef(options.baselineRef);
   const genuinelyMissing = [];
+  const divergentFromAcceptedLineage = [];
   const alreadyCommittedUpstream = [];
   for (const filePath of missingPaths) {
     let tracked = false;
@@ -179,11 +194,36 @@ function partitionDeclaredPathsByUpstreamPresence(root, missingPaths) {
     }
     if (hasDivergence) {
       genuinelyMissing.push(filePath);
-    } else {
-      alreadyCommittedUpstream.push(filePath);
+      continue;
     }
+
+    // BUG-55A wrong-branch guard: a path only counts as already checkpointed
+    // if the current branch differs from the accepted baseline on that path.
+    if (baselineRef) {
+      let changedSinceAcceptedBaseline = false;
+      try {
+        const baselineDiff = git(root, ['diff', baselineRef, 'HEAD', '--', filePath]);
+        changedSinceAcceptedBaseline = Boolean(baselineDiff);
+      } catch {
+        changedSinceAcceptedBaseline = true;
+      }
+      if (!changedSinceAcceptedBaseline) {
+        divergentFromAcceptedLineage.push(filePath);
+        continue;
+      }
+    }
+
+    alreadyCommittedUpstream.push(filePath);
   }
-  return { genuinelyMissing, alreadyCommittedUpstream };
+  // Preserve the pre-existing return shape: `genuinelyMissing` is the union
+  // that the completeness gate must fail on. `divergent_from_accepted_lineage`
+  // is an additional, operator-facing subcategory that callers can surface
+  // without changing the pass/fail contract.
+  return {
+    genuinelyMissing: [...genuinelyMissing, ...divergentFromAcceptedLineage],
+    divergentFromAcceptedLineage,
+    alreadyCommittedUpstream,
+  };
 }
 
 export function detectPendingCheckpoint(root, dirtyFiles = []) {
@@ -281,14 +321,21 @@ export function checkpointAcceptedTurn(root, opts = {}) {
   }
 
   const rawMissingFromStage = diffMissingDeclaredPaths(filesChanged, staged);
-  const { genuinelyMissing, alreadyCommittedUpstream } =
-    partitionDeclaredPathsByUpstreamPresence(root, rawMissingFromStage);
+  const { genuinelyMissing, divergentFromAcceptedLineage, alreadyCommittedUpstream } =
+    partitionDeclaredPathsByUpstreamPresence(root, rawMissingFromStage, {
+      baselineRef: entry?.observed_artifact?.baseline_ref ?? null,
+    });
   if (genuinelyMissing.length > 0) {
+    const baseMessage = `Checkpoint completeness failure: accepted turn ${entry.turn_id} declared ${filesChanged.length} checkpointable file(s), but Git staged only ${staged.length} and ${genuinelyMissing.length} declared path(s) are absent from git. Missing from checkpoint: ${genuinelyMissing.join(', ')}.`;
+    const lineageHint = divergentFromAcceptedLineage.length > 0
+      ? ` Wrong-lineage paths (tracked at HEAD but unchanged since accepted baseline — actor likely committed off the accepted lineage): ${divergentFromAcceptedLineage.join(', ')}.`
+      : '';
     return {
       ok: false,
       turn: entry,
-      error: `Checkpoint completeness failure: accepted turn ${entry.turn_id} declared ${filesChanged.length} checkpointable file(s), but Git staged only ${staged.length} and ${genuinelyMissing.length} declared path(s) are absent from git. Missing from checkpoint: ${genuinelyMissing.join(', ')}.`,
+      error: `${baseMessage}${lineageHint}`,
       missing_declared_paths: genuinelyMissing,
+      divergent_from_accepted_lineage: divergentFromAcceptedLineage,
       already_committed_upstream: alreadyCommittedUpstream,
       staged_paths: staged,
     };