agentxchain 2.146.0 → 2.148.0

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

@@ -55,6 +55,8 @@ 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}]` : ''}`;
@@ -77,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',
 ];
 
 /**

package/src/lib/run-loop.js

@@ -31,6 +31,7 @@ import {
   getActiveTurnCount,
   getActiveTurns,
   getMaxConcurrentTurns,
+  transitionActiveTurnLifecycle,
   RUNNER_INTERFACE_VERSION,
 } from './runner-interface.js';
 
@@ -40,6 +41,18 @@ import { join, dirname } from 'path';
 import { evaluateApprovalSlaReminders } from './notification-runner.js';
 import { validatePreemptionMarker } from './intake.js';
 import { buildTimeoutBlockedReason, evaluateTimeouts } from './timeout-evaluator.js';
+import { hasMinimumTurnResultShape } from './turn-result-shape.js';
+
+// Per DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001 (Turn 33): runLoop is the SDK boundary
+// any third-party runner can wire (see website-v2/docs/build-your-own-runner.mdx).
+// In-repo adapters (api_proxy, mcp, local_cli, remote_agent) already validate
+// staged-result shape before write per DEC-MINIMUM-TURN-RESULT-SHAPE-001, and
+// run.js's dispatch callback re-validates before returning per
+// DEC-RUN-STAGED-READ-SHAPE-GUARD-001. Third-party callbacks have no such
+// obligation. runLoop must therefore validate dispatchResult.turnResult shape
+// before persisting it as a governed staged-result artifact.
+const MIN_SHAPE_REJECTION_REASON =
+  'staged result missing minimum governed envelope (schema_version + identity + lifecycle fields)';
 
 const DEFAULT_MAX_TURNS = 50;
 
@@ -182,7 +195,7 @@ async function executeSequentialTurn(root, config, state, callbacks, emit, error
   let assignState;
   const activeTurn = getActiveTurn(state);
 
-  if (activeTurn && (activeTurn.status === 'running' || activeTurn.status === 'retrying')) {
+  if (activeTurn && isDispatchableActiveTurn(activeTurn)) {
     turn = activeTurn;
     assignState = state;
   } else {
@@ -224,7 +237,7 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
   const activeTurns = getActiveTurns(state);
   const turnsToDispatch = [];
   for (const turn of Object.values(activeTurns)) {
-    if (turn.status === 'running' || turn.status === 'retrying') {
+    if (isDispatchableActiveTurn(turn)) {
       turnsToDispatch.push({ turn, state });
     }
   }
@@ -317,6 +330,7 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       errors.push(`writeDispatchBundle(${turn.assigned_role}): ${bundleResult.error}`);
       continue;
     }
+    transitionActiveTurnLifecycle(root, turn.turn_id, 'dispatched');
     const stagingPath = getTurnStagingResultPath(turn.turn_id);
     contexts.push({
       turn,
@@ -362,6 +376,23 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       continue;
     }
 
+    if (dispatchResult.accept && !hasMinimumTurnResultShape(dispatchResult.turnResult)) {
+      // DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001: third-party dispatch callback claimed
+      // accept=true but returned a payload missing the minimum envelope. Refuse to
+      // stage; convert to standard rejection so the run state advances cleanly.
+      const validationResult = { stage: 'dispatch', errors: [MIN_SHAPE_REJECTION_REASON] };
+      rejectTurn(root, config, validationResult, MIN_SHAPE_REJECTION_REASON, { turnId: turn.turn_id });
+      history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+      emit({ type: 'turn_rejected', turn, role: roleId, reason: MIN_SHAPE_REJECTION_REASON });
+      const postRejectState = loadState(root, config);
+      if (postRejectState?.status === 'blocked') {
+        errors.push(`Turn rejected for ${roleId}, retries exhausted`);
+        emit({ type: 'blocked', state: postRejectState });
+        return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history, acceptedCount };
+      }
+      continue;
+    }
+
     if (dispatchResult.accept) {
       const absStaging = join(root, ctx.stagingPath);
       mkdirSync(dirname(absStaging), { recursive: true });
@@ -409,6 +440,12 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
       }
       emit({ type: 'turn_accepted', turn, role: roleId, state: acceptResult.state });
     } else {
+      if (dispatchResult?.blocked === true) {
+        history.push({ role: roleId, turn_id: turn.turn_id, accepted: false, blocked: true });
+        const blockedState = loadState(root, config);
+        emit({ type: 'blocked', state: blockedState });
+        return { terminal: true, ok: false, stop_reason: 'blocked', history, acceptedCount };
+      }
       const validationResult = {
         stage: 'dispatch',
         errors: [dispatchResult.reason || 'Dispatch callback rejected the turn'],
@@ -449,6 +486,10 @@ async function executeParallelTurns(root, config, state, maxConcurrent, callback
   return { terminal: false, history, acceptedCount };
 }
 
+function isDispatchableActiveTurn(turn) {
+  return ['assigned', 'dispatched', 'starting', 'running', 'retrying'].includes(turn?.status);
+}
+
 /**
  * Dispatch a single turn and process its result.
  */
@@ -463,6 +504,7 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     errors.push(`writeDispatchBundle(${roleId}): ${bundleResult.error}`);
     return { terminal: true, ok: false, stop_reason: 'blocked', history };
   }
+  transitionActiveTurnLifecycle(root, turn.turn_id, 'dispatched');
 
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
   const context = {
@@ -488,6 +530,22 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     return { terminal: true, ok: false, stop_reason: 'blocked', history };
   }
 
+  if (dispatchResult.accept && !hasMinimumTurnResultShape(dispatchResult.turnResult)) {
+    // DEC-RUN-LOOP-MIN-SHAPE-SYMMETRY-001: same boundary as parallel branch.
+    // Refuse to stage; convert to a standard rejection.
+    const validationResult = { stage: 'dispatch', errors: [MIN_SHAPE_REJECTION_REASON] };
+    rejectTurn(root, config, validationResult, MIN_SHAPE_REJECTION_REASON);
+    history.push({ role: roleId, turn_id: turn.turn_id, accepted: false });
+    emit({ type: 'turn_rejected', turn, role: roleId, reason: MIN_SHAPE_REJECTION_REASON });
+    const postRejectState = loadState(root, config);
+    if (postRejectState?.status === 'blocked') {
+      errors.push(`Turn rejected for ${roleId}, retries exhausted`);
+      emit({ type: 'blocked', state: postRejectState });
+      return { terminal: true, ok: false, stop_reason: 'reject_exhausted', history };
+    }
+    return { terminal: false, accepted: false, history };
+  }
+
   if (dispatchResult.accept) {
     const absStaging = join(root, stagingPath);
     mkdirSync(dirname(absStaging), { recursive: true });
@@ -537,6 +595,13 @@ async function dispatchAndProcess(root, config, turn, assignState, callbacks, em
     return { terminal: false, accepted: true, history };
   }
 
+  if (dispatchResult?.blocked === true) {
+    history.push({ role: roleId, turn_id: turn.turn_id, accepted: false, blocked: true });
+    const blockedState = loadState(root, config);
+    emit({ type: 'blocked', state: blockedState });
+    return { terminal: true, ok: false, stop_reason: 'blocked', history };
+  }
+
   // Rejection
   const validationResult = {
     stage: 'dispatch',

package/src/lib/runner-interface.js

@@ -41,6 +41,7 @@ export {
   releaseAcceptanceLock as releaseLock,
   refreshTurnBaselineSnapshot,
   reissueTurn,
+  transitionActiveTurnLifecycle,
 } from './governed-state.js';
 
 // ── Dispatch ────────────────────────────────────────────────────────────────

package/src/lib/schema.js

@@ -35,6 +35,13 @@ export function validateGovernedStateSchema(data) {
   // but validators and read-only surfaces still tolerate reserved/manual states.
   const VALID_RUN_STATUSES = ['idle', 'active', 'paused', 'blocked', 'completed', 'failed'];
   const isV1_1 = data?.schema_version === '1.1';
+  // NOTE: `current_turn` is the persisted v1.0 schema field. Under v1.1 it is
+  // not a persisted field at all — `loadProjectState()` re-attaches it as a
+  // non-enumerable getter alias over `active_turns` after normalization
+  // (DEC-CURRENT-TURN-COMPAT-ALIAS-001). This validator runs against the
+  // persisted shape, so an `own` property named `current_turn` on a v1.1 doc
+  // means "stray persisted-shape leak from a legacy write" and is rejected
+  // below — it does NOT mean the runtime alias is going away.
   const hasLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(data || {}, 'current_turn');
 
   function validateTurn(turn, label) {

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

@@ -85,7 +85,21 @@
       "type": "object"
     },
     "run_loop": {
-      "type": "object"
+      "type": "object",
+      "description": "Runner control knobs for execution watchdogs and automation behavior.",
+      "properties": {
+        "startup_watchdog_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds to wait after dispatch for worker attach/first-output proof before retaining the turn as failed_start. Default 30000."
+        },
+        "stale_turn_threshold_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Milliseconds to wait before a started turn that previously produced output is treated as stale. Default 600000 for local_cli turns and 300000 for api_proxy turns."
+        }
+      },
+      "additionalProperties": true
     },
     "mission_planner": {
       "type": "object"

package/src/lib/schemas/turn-result.schema.json

@@ -148,7 +148,10 @@
         },
         "commands": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string",
+            "pattern": "\\S"
+          },
           "description": "Verification commands that were run."
         },
         "evidence_summary": {
@@ -161,7 +164,10 @@
             "type": "object",
             "required": ["command", "exit_code"],
             "properties": {
-              "command": { "type": "string" },
+              "command": {
+                "type": "string",
+                "pattern": "\\S"
+              },
               "exit_code": { "type": "integer" }
             }
           }

package/src/lib/staged-result-proof.js

@@ -0,0 +1,43 @@
+/**
+ * Staged turn-result proof helpers.
+ *
+ * Per DEC-BUG51-STAGING-PLACEHOLDER-NOT-PROOF-001: a turn-scoped staged-result
+ * file is proof of execution only when it contains meaningful result content.
+ * Adapter-authored placeholders (`{}`, blank, whitespace-only) are cleanup
+ * artifacts — watchdog, adapter, and recovery code must treat them as absent.
+ *
+ * This module centralizes that check so every surface (local-cli adapter,
+ * manual adapter, stale-turn watchdog) uses the same rule.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * Returns true when the staged-result file at `filePath` exists AND contains
+ * content that is not a placeholder (empty, whitespace-only, or `{}`).
+ *
+ * Trim-aware: `{}\n`, `  {}\n`, and `{}` are all rejected. Legitimate turn
+ * results carry the full governed schema and are far larger than the
+ * placeholder shapes this function filters.
+ *
+ * @param {string} filePath - absolute path to the staged-result file
+ * @returns {boolean}
+ */
+export function hasMeaningfulStagedResult(filePath) {
+  if (!existsSync(filePath)) {
+    return false;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return false;
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === '{}') {
+    return false;
+  }
+  return true;
+}