agentxchain 2.36.0 → 2.38.0

package/dashboard/components/timeline.js

@@ -154,8 +154,19 @@ function renderContinuityPanel(continuity) {
     html += `<div class="turn-detail"><span class="detail-label">Checkpoint:</span> No session checkpoint recorded</div>`;
   }
 
-  if (continuity.restart_recommended) {
-    html += `<div class="turn-detail"><span class="detail-label">Restart:</span> <span class="mono">agentxchain restart</span></div>`;
+  if (continuity.drift_detected === true && Array.isArray(continuity.drift_warnings) && continuity.drift_warnings.length > 0) {
+    html += `<div class="turn-detail risks"><span class="detail-label">Drift:</span><ul>`;
+    for (const warning of continuity.drift_warnings) {
+      html += `<li>${esc(warning)}</li>`;
+    }
+    html += `</ul></div>`;
+  } else if (continuity.drift_detected === false) {
+    html += `<div class="turn-detail"><span class="detail-label">Drift:</span> none detected since checkpoint</div>`;
+  }
+
+  if (continuity.recommended_command) {
+    const detail = continuity.recommended_detail ? ` (${continuity.recommended_detail})` : '';
+    html += `<div class="turn-detail"><span class="detail-label">Action:</span> <span class="mono">${esc(continuity.recommended_command)}</span>${esc(detail)}</div>`;
   }
 
   if (continuity.recovery_report_path) {

package/package.json

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

package/scripts/release-bump.sh

@@ -121,7 +121,11 @@ echo "  OK: tag v${TARGET_VERSION} does not exist"
 # Ensures all governed version surfaces already reference the target version
 # BEFORE the bump commit is created. This catches stale drift that would
 # otherwise only be discovered after minting local release identities.
-echo "[4/8] Verifying version-surface alignment for ${TARGET_VERSION}..."
+#
+# NOTE: Homebrew mirror formula and README are NOT checked here. They are
+# auto-aligned in step 5 because the registry SHA256 is inherently a
+# post-publish artifact. See DEC-HOMEBREW-SHA-SPLIT-001.
+echo "[4/9] Verifying version-surface alignment for ${TARGET_VERSION}..."
 SURFACE_ERRORS=()
 
 # 4a. CHANGELOG top heading
@@ -164,25 +168,6 @@ if ! grep -qE "^# Launch Evidence Report — AgentXchain v${ESCAPED_VERSION}" "$
   SURFACE_ERRORS+=("LAUNCH_EVIDENCE_REPORT.md title does not carry v${TARGET_VERSION}")
 fi
 
-# 4h. Homebrew mirror formula version
-HOMEBREW_MIRROR="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
-if [[ -f "$HOMEBREW_MIRROR" ]]; then
-  if ! grep -q "agentxchain-${TARGET_VERSION}\.tgz" "$HOMEBREW_MIRROR" 2>/dev/null; then
-    SURFACE_ERRORS+=("homebrew mirror formula does not reference agentxchain-${TARGET_VERSION}.tgz")
-  fi
-fi
-
-# 4i. Homebrew mirror maintainer README version
-HOMEBREW_MIRROR_README="${REPO_ROOT}/cli/homebrew/README.md"
-if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
-  if ! grep -q -- "- version: \`${TARGET_VERSION}\`" "$HOMEBREW_MIRROR_README" 2>/dev/null; then
-    SURFACE_ERRORS+=("homebrew mirror README does not declare version ${TARGET_VERSION}")
-  fi
-  if ! grep -q "agentxchain-${TARGET_VERSION}\.tgz" "$HOMEBREW_MIRROR_README" 2>/dev/null; then
-    SURFACE_ERRORS+=("homebrew mirror README does not reference agentxchain-${TARGET_VERSION}.tgz")
-  fi
-fi
-
 if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
   printf '  - %s\n' "${SURFACE_ERRORS[@]}" >&2
@@ -191,15 +176,47 @@ if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "create release identity when governed surfaces are stale." >&2
   exit 1
 fi
-echo "  OK: all 10 governed version surfaces reference ${TARGET_VERSION}"
+echo "  OK: all 7 governed version surfaces reference ${TARGET_VERSION}"
+
+# 5. Auto-align Homebrew mirror to target version
+# The formula URL and README version/tarball are updated automatically.
+# The SHA256 is carried from the previous version — it is inherently a
+# post-publish artifact (npm registry tarballs are not byte-identical to
+# local npm-pack output). sync-homebrew.sh corrects the SHA after publish.
+echo "[5/9] Auto-aligning Homebrew mirror to ${TARGET_VERSION}..."
+HOMEBREW_MIRROR="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
+HOMEBREW_MIRROR_README="${REPO_ROOT}/cli/homebrew/README.md"
+TARBALL_URL="https://registry.npmjs.org/agentxchain/-/agentxchain-${TARGET_VERSION}.tgz"
+HOMEBREW_ALIGNED=false
+
+if [[ -f "$HOMEBREW_MIRROR" ]]; then
+  ESCAPED_URL="$(printf '%s' "$TARBALL_URL" | sed 's/[&/\]/\\&/g')"
+  sed -i.bak -E "s|^([[:space:]]*url \").*(\")|\1${ESCAPED_URL}\2|" "$HOMEBREW_MIRROR"
+  rm -f "${HOMEBREW_MIRROR}.bak"
+  HOMEBREW_ALIGNED=true
+  echo "  OK: formula URL -> ${TARBALL_URL}"
+fi
+
+if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
+  sed -i.bak -E "s|^(- version: \`).*(\`)|\1${TARGET_VERSION}\2|" "$HOMEBREW_MIRROR_README"
+  sed -i.bak -E "s|^(- source tarball: \`).*(\`)|\1${TARBALL_URL}\2|" "$HOMEBREW_MIRROR_README"
+  rm -f "${HOMEBREW_MIRROR_README}.bak"
+  echo "  OK: README version and tarball -> ${TARGET_VERSION}"
+fi
+
+if $HOMEBREW_ALIGNED; then
+  echo "  Note: SHA carried from previous version; sync-homebrew.sh will set the real registry SHA post-publish"
+else
+  echo "  Skipped: no Homebrew mirror files found"
+fi
 
-# 5. Update version files (no git operations)
-echo "[5/8] Updating version files..."
+# 6. Update version files (no git operations)
+echo "[6/9] Updating version files..."
 npm version "$TARGET_VERSION" --no-git-tag-version
 echo "  OK: package.json updated to ${TARGET_VERSION}"
 
-# 6. Stage version files
-echo "[6/8] Staging version files..."
+# 7. Stage version files
+echo "[7/9] Staging version files..."
 git add -- package.json
 if [[ -f package-lock.json ]]; then
   git add -- package-lock.json
@@ -209,8 +226,8 @@ for rel_path in "${ALLOWED_RELEASE_PATHS[@]}"; do
 done
 echo "  OK: version files and allowed release surfaces staged"
 
-# 7. Create release commit
-echo "[7/8] Creating release commit..."
+# 8. Create release commit
+echo "[8/9] Creating release commit..."
 git commit -m "${TARGET_VERSION}"
 RELEASE_SHA=$(git rev-parse HEAD)
 COMMIT_MSG=$(git log -1 --format=%s)
@@ -220,8 +237,8 @@ if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
 fi
 echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
-# 8. Create annotated tag
-echo "[8/8] Creating annotated tag..."
+# 9. Create annotated tag
+echo "[9/9] Creating annotated tag..."
 git tag -a "v${TARGET_VERSION}" -m "v${TARGET_VERSION}"
 TAG_SHA=$(git rev-parse "v${TARGET_VERSION}")
 if [[ -z "$TAG_SHA" ]]; then

package/src/commands/restart.js

@@ -23,13 +23,13 @@ import {
   HISTORY_PATH,
   LEDGER_PATH,
 } from '../lib/governed-state.js';
-import { readSessionCheckpoint, SESSION_PATH } from '../lib/session-checkpoint.js';
+import { readSessionCheckpoint, writeSessionCheckpoint, captureBaselineRef, SESSION_PATH } from '../lib/session-checkpoint.js';
 
 /**
  * Generate a session recovery report summarizing the run state
  * so a new agent session can orient quickly.
  */
-function generateRecoveryReport(root, state, checkpoint) {
+function generateRecoveryReport(root, state, checkpoint, driftWarnings = []) {
   const lines = [
     '# Session Recovery Report',
     '',
@@ -102,7 +102,50 @@ function generateRecoveryReport(root, state, checkpoint) {
     }
   }
 
-  lines.push('## Next Steps', '', 'The next turn has been assigned. Check the dispatch bundle for context.', '');
+  // Pending gate / run completion surfacing
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    lines.push(
+      '## Pending Phase Transition',
+      '',
+      `- **From**: ${pt.from}`,
+      `- **To**: ${pt.to}`,
+      `- **Gate**: ${pt.gate}`,
+      `- **Requested by**: ${pt.requested_by_turn || 'unknown'}`,
+      `- **Action**: Run \`agentxchain approve-transition\` to approve`,
+      '',
+    );
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    lines.push(
+      '## Pending Run Completion',
+      '',
+      `- **Gate**: ${pc.gate}`,
+      `- **Requested by**: ${pc.requested_by_turn || 'unknown'}`,
+      `- **Action**: Run \`agentxchain approve-completion\` to approve`,
+      '',
+    );
+  }
+
+  // Repo-drift warnings
+  if (checkpoint?.baseline_ref && driftWarnings?.length > 0) {
+    lines.push('## Continuity Warnings', '');
+    for (const warning of driftWarnings) {
+      lines.push(`- ⚠ ${warning}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Next Steps', '');
+  if (state.pending_phase_transition) {
+    lines.push('A phase transition is pending approval. Run `agentxchain approve-transition` before assigning new turns.', '');
+  } else if (state.pending_run_completion) {
+    lines.push('A run completion is pending approval. Run `agentxchain approve-completion` to finalize.', '');
+  } else {
+    lines.push('The next turn has been assigned. Check the dispatch bundle for context.', '');
+  }
 
   return lines.join('\n');
 }
@@ -160,6 +203,42 @@ export async function restartCommand(opts) {
     process.exit(1);
   }
 
+  // ── Repo-drift detection ────────────────────────────────────────────────
+  const driftWarnings = [];
+  if (checkpoint?.baseline_ref) {
+    const currentBaseline = captureBaselineRef(root);
+    const prev = checkpoint.baseline_ref;
+
+    if (prev.git_head && currentBaseline.git_head && prev.git_head !== currentBaseline.git_head) {
+      driftWarnings.push(`Git HEAD has moved since checkpoint: ${prev.git_head.slice(0, 8)} → ${currentBaseline.git_head.slice(0, 8)}`);
+    }
+    if (prev.git_branch && currentBaseline.git_branch && prev.git_branch !== currentBaseline.git_branch) {
+      driftWarnings.push(`Branch changed since checkpoint: ${prev.git_branch} → ${currentBaseline.git_branch}`);
+    }
+    if (prev.workspace_dirty === false && currentBaseline.workspace_dirty === true) {
+      driftWarnings.push('Workspace was clean at checkpoint but is now dirty');
+    }
+  }
+
+  if (driftWarnings.length > 0) {
+    for (const warning of driftWarnings) {
+      console.log(chalk.yellow(`⚠ ${warning}`));
+    }
+  }
+
+  // ── Pending gate / completion check ────────────────────────────────────
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    console.log(chalk.yellow(`Pending phase transition: ${pt.from} → ${pt.to} (gate: ${pt.gate})`));
+    console.log(chalk.dim('Run `agentxchain approve-transition` to approve before assigning new turns.'));
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    console.log(chalk.yellow(`Pending run completion (gate: ${pc.gate})`));
+    console.log(chalk.dim('Run `agentxchain approve-completion` to finalize.'));
+  }
+
   // Handle abandoned active turns (assigned but never completed)
   const activeTurns = getActiveTurns(state);
   const activeTurnCount = getActiveTurnCount(state);
@@ -167,9 +246,29 @@ export async function restartCommand(opts) {
     const turnIds = Object.keys(activeTurns);
     console.log(chalk.yellow(`Warning: ${activeTurnCount} turn(s) were assigned but never completed: ${turnIds.join(', ')}`));
     console.log(chalk.dim('These turns will be available for the next agent to complete.'));
+
+    // Fail closed if retained turn + irreconcilable drift
+    if (driftWarnings.length > 0) {
+      console.log(chalk.yellow('Active turns exist with repo drift since checkpoint. Reconnecting with warnings.'));
+      console.log(chalk.dim('Inspect the drift before continuing work on the retained turns.'));
+    }
   }
 
-  // If paused, reactivate
+  // If pending gate/completion, do not bypass — surface and exit with recovery
+  if (state.pending_phase_transition || state.pending_run_completion) {
+    // Write checkpoint for the reconnect
+    writeSessionCheckpoint(root, state, 'restart_reconnect');
+
+    const recoveryReport = generateRecoveryReport(root, state, checkpoint, driftWarnings);
+    const recoveryPath = join(root, '.agentxchain/SESSION_RECOVERY.md');
+    const recoveryDir = dirname(recoveryPath);
+    if (!existsSync(recoveryDir)) mkdirSync(recoveryDir, { recursive: true });
+    writeFileSync(recoveryPath, recoveryReport);
+    console.log(chalk.dim(`  Recovery report: .agentxchain/SESSION_RECOVERY.md`));
+    return;
+  }
+
+  // If paused or idle without a pending approval gate, reactivate.
   if (state.status === 'paused' || state.status === 'idle') {
     const reactivated = reactivateGovernedRun(root, state, {
       reason: 'session_restart',
@@ -198,6 +297,8 @@ export async function restartCommand(opts) {
       process.exit(1);
     }
 
+    // assignGovernedTurn already writes a checkpoint at turn_assigned
+
     console.log(chalk.green(`✓ Restarted run ${state.run_id}`));
     console.log(chalk.dim(`  Phase: ${phase}`));
     console.log(chalk.dim(`  Turn: ${assignment.turn?.id || 'assigned'}`));
@@ -206,6 +307,9 @@ export async function restartCommand(opts) {
       console.log(chalk.dim(`  Last checkpoint: ${checkpoint.checkpoint_reason} at ${checkpoint.last_checkpoint_at}`));
     }
   } else {
+    // Reconnect to existing active turns — write checkpoint
+    writeSessionCheckpoint(root, state, 'restart_reconnect');
+
     console.log(chalk.green(`✓ Reconnected to run ${state.run_id}`));
     console.log(chalk.dim(`  Phase: ${phase}`));
     console.log(chalk.dim(`  Active turns: ${Object.keys(activeTurns).join(', ')}`));
@@ -213,7 +317,7 @@ export async function restartCommand(opts) {
   }
 
   // Write session recovery report
-  const recoveryReport = generateRecoveryReport(root, state, checkpoint);
+  const recoveryReport = generateRecoveryReport(root, state, checkpoint, driftWarnings);
   const recoveryPath = join(root, '.agentxchain/SESSION_RECOVERY.md');
   const recoveryDir = dirname(recoveryPath);
   if (!existsSync(recoveryDir)) mkdirSync(recoveryDir, { recursive: true });

package/src/commands/status.js

@@ -268,8 +268,21 @@ function renderContinuityStatus(continuity, state) {
     console.log(`  ${chalk.dim('Checkpoint:')} ${chalk.yellow('No session checkpoint recorded')}`);
   }
 
-  if (continuity.restart_recommended) {
-    console.log(`  ${chalk.dim('Restart:')} ${chalk.cyan('agentxchain restart')} (rebuild session context from disk)`);
+  if (continuity.drift_detected === true) {
+    const [firstWarning, ...remainingWarnings] = continuity.drift_warnings || [];
+    if (firstWarning) {
+      console.log(`  ${chalk.dim('Drift:')}    ${chalk.yellow(firstWarning)}`);
+    }
+    for (const warning of remainingWarnings) {
+      console.log(`  ${chalk.dim('         ')} ${chalk.yellow(warning)}`);
+    }
+  } else if (continuity.drift_detected === false) {
+    console.log(`  ${chalk.dim('Drift:')}    ${chalk.green('none detected since checkpoint')}`);
+  }
+
+  if (continuity.recommended_command) {
+    const detail = continuity.recommended_detail ? ` (${continuity.recommended_detail})` : '';
+    console.log(`  ${chalk.dim('Action:')}   ${chalk.cyan(continuity.recommended_command)}${chalk.dim(detail)}`);
   }
 
   if (continuity.recovery_report_path) {

package/src/lib/adapters/api-proxy-adapter.js

@@ -23,7 +23,7 @@
  *   All error returns include a `classified` ApiProxyError object with
  *   error_class, recovery instructions, and retryable flag.
  *
- * Supported providers: "anthropic", "openai"
+ * Supported providers: "anthropic", "openai", "google"
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
@@ -45,9 +45,12 @@ import {
 import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
 
 // Provider endpoint registry
+// Google Gemini endpoint requires the model name interpolated at call time;
+// the registry stores a template with {model} as a placeholder.
 const PROVIDER_ENDPOINTS = {
   anthropic: 'https://api.anthropic.com/v1/messages',
   openai: 'https://api.openai.com/v1/chat/completions',
+  google: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
 };
 
 // Bundled cost rates per million tokens (USD).
@@ -67,6 +70,10 @@ const BUNDLED_COST_RATES = {
   'o3': { input_per_1m: 2.00, output_per_1m: 8.00 },
   'o3-mini': { input_per_1m: 1.10, output_per_1m: 4.40 },
   'o4-mini': { input_per_1m: 1.10, output_per_1m: 4.40 },
+  // Google Gemini — verified 2026-04-09 (training knowledge)
+  'gemini-2.5-pro': { input_per_1m: 1.25, output_per_1m: 10.00 },
+  'gemini-2.5-flash': { input_per_1m: 0.15, output_per_1m: 0.60 },
+  'gemini-2.0-flash': { input_per_1m: 0.10, output_per_1m: 0.40 },
 };
 
 // Resolve cost rates: operator-supplied cost_rates override bundled defaults
@@ -135,6 +142,25 @@ const PROVIDER_ERROR_MAPS = {
       { provider_error_type: 'rate_limit_error', http_status: 429, error_class: 'rate_limited', retryable: true },
     ],
   },
+  google: {
+    extractErrorType(body) {
+      // Google errors use { error: { status: "INVALID_ARGUMENT", ... } }
+      return typeof body?.error?.status === 'string' ? body.error.status : null;
+    },
+    extractErrorCode(body) {
+      return typeof body?.error?.code === 'number' ? String(body.error.code) : null;
+    },
+    mappings: [
+      { provider_error_type: 'UNAUTHENTICATED', http_status: 401, error_class: 'auth_failure', retryable: false },
+      { provider_error_type: 'PERMISSION_DENIED', http_status: 403, error_class: 'auth_failure', retryable: false },
+      { provider_error_type: 'NOT_FOUND', http_status: 404, error_class: 'model_not_found', retryable: false },
+      { provider_error_type: 'RESOURCE_EXHAUSTED', http_status: 429, error_class: 'rate_limited', retryable: true },
+      { provider_error_type: 'INVALID_ARGUMENT', http_status: 400, body_pattern: /token.*limit|context|too.long/i, error_class: 'context_overflow', retryable: false },
+      { provider_error_type: 'INVALID_ARGUMENT', http_status: 400, error_class: 'invalid_request', retryable: false },
+      { provider_error_type: 'UNAVAILABLE', http_status: 503, error_class: 'provider_overloaded', retryable: true },
+      { provider_error_type: 'INTERNAL', http_status: 500, error_class: 'unknown_api_error', retryable: true },
+    ],
+  },
 };
 
 // ── Error classification ──────────────────────────────────────────────────────
@@ -442,6 +468,10 @@ function usageFromTelemetry(provider, model, usage, config) {
   if (provider === 'openai') {
     inputTokens = Number.isFinite(usage.prompt_tokens) ? usage.prompt_tokens : 0;
     outputTokens = Number.isFinite(usage.completion_tokens) ? usage.completion_tokens : 0;
+  } else if (provider === 'google') {
+    // Google Gemini returns usageMetadata at root level with promptTokenCount / candidatesTokenCount
+    inputTokens = Number.isFinite(usage.promptTokenCount) ? usage.promptTokenCount : 0;
+    outputTokens = Number.isFinite(usage.candidatesTokenCount) ? usage.candidatesTokenCount : 0;
   } else {
     inputTokens = Number.isFinite(usage.input_tokens) ? usage.input_tokens : 0;
     outputTokens = Number.isFinite(usage.output_tokens) ? usage.output_tokens : 0;
@@ -691,7 +721,9 @@ async function executeApiCall({
     };
   }
 
-  const usage = usageFromTelemetry(provider, model, responseData.usage, config);
+  // Google Gemini returns usage at responseData.usageMetadata; others at responseData.usage
+  const usageSource = provider === 'google' ? responseData.usageMetadata : responseData.usage;
+  const usage = usageFromTelemetry(provider, model, usageSource, config);
   const extraction = extractTurnResult(responseData, provider);
 
   if (!extraction.ok) {
@@ -791,7 +823,7 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
     return errorReturn(root, turn.turn_id, classified);
   }
 
-  const endpoint = runtime.base_url || PROVIDER_ENDPOINTS[provider];
+  let endpoint = runtime.base_url || PROVIDER_ENDPOINTS[provider];
   if (!endpoint) {
     const classified = classifyError(
       'unsupported_provider',
@@ -802,6 +834,12 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
     return errorReturn(root, turn.turn_id, classified);
   }
 
+  // Google Gemini: interpolate model into endpoint URL and append API key as query param
+  if (provider === 'google') {
+    endpoint = endpoint.replace('{model}', encodeURIComponent(model));
+    endpoint += (endpoint.includes('?') ? '&' : '?') + `key=${encodeURIComponent(apiKey)}`;
+  }
+
   // Build request
   const maxOutputTokens = runtime.max_output_tokens || 4096;
   const timeoutSeconds = runtime.timeout_seconds || 120;
@@ -1086,10 +1124,92 @@ function buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens) {
   };
 }
 
+function buildGoogleHeaders(_apiKey) {
+  // Google Gemini uses API key as a query parameter, not a header
+  return {
+    'Content-Type': 'application/json',
+  };
+}
+
+function buildGoogleRequest(promptMd, contextMd, model, maxOutputTokens) {
+  const userContent = contextMd
+    ? `${promptMd}${SEPARATOR}${contextMd}`
+    : promptMd;
+
+  return {
+    systemInstruction: {
+      parts: [{ text: SYSTEM_PROMPT }],
+    },
+    contents: [
+      {
+        role: 'user',
+        parts: [{ text: userContent }],
+      },
+    ],
+    generationConfig: {
+      maxOutputTokens,
+      responseMimeType: 'application/json',
+    },
+  };
+}
+
+function extractGoogleTurnResult(responseData) {
+  const promptBlockReason = responseData?.promptFeedback?.blockReason;
+  if (typeof promptBlockReason === 'string' && promptBlockReason.trim()) {
+    return {
+      ok: false,
+      error: `Google Gemini blocked the prompt before generation (blockReason: ${promptBlockReason})`,
+    };
+  }
+
+  if (!Array.isArray(responseData?.candidates) || responseData.candidates.length === 0) {
+    return { ok: false, error: 'API response has no candidates' };
+  }
+
+  const candidate = responseData.candidates[0];
+  const finishReason = typeof candidate?.finishReason === 'string'
+    ? candidate.finishReason
+    : null;
+  const parts = candidate?.content?.parts;
+  if (!Array.isArray(parts) || parts.length === 0) {
+    if (finishReason && finishReason !== 'STOP') {
+      return {
+        ok: false,
+        error: `Google Gemini candidate has no content parts (finishReason: ${finishReason})`,
+      };
+    }
+    return { ok: false, error: 'API response candidate has no content parts' };
+  }
+
+  const textPart = parts.find(p => typeof p.text === 'string');
+  if (!textPart?.text?.trim()) {
+    if (finishReason && finishReason !== 'STOP') {
+      return {
+        ok: false,
+        error: `Google Gemini returned no extractable text (finishReason: ${finishReason})`,
+      };
+    }
+    return { ok: false, error: 'API response has no text content part' };
+  }
+
+  const extraction = extractTurnResultFromText(textPart.text);
+  if (!extraction.ok && finishReason && finishReason !== 'STOP') {
+    return {
+      ok: false,
+      error: `Google Gemini returned non-extractable turn JSON (finishReason: ${finishReason})`,
+    };
+  }
+
+  return extraction;
+}
+
 function buildProviderHeaders(provider, apiKey) {
   if (provider === 'openai') {
     return buildOpenAiHeaders(apiKey);
   }
+  if (provider === 'google') {
+    return buildGoogleHeaders(apiKey);
+  }
   return buildAnthropicHeaders(apiKey);
 }
 
@@ -1097,6 +1217,9 @@ function buildProviderRequest(provider, promptMd, contextMd, model, maxOutputTok
   if (provider === 'openai') {
     return buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
   }
+  if (provider === 'google') {
+    return buildGoogleRequest(promptMd, contextMd, model, maxOutputTokens);
+  }
   return buildAnthropicRequest(promptMd, contextMd, model, maxOutputTokens);
 }
 
@@ -1184,6 +1307,9 @@ function extractTurnResult(responseData, provider = 'anthropic') {
   if (provider === 'openai') {
     return extractOpenAiTurnResult(responseData);
   }
+  if (provider === 'google') {
+    return extractGoogleTurnResult(responseData);
+  }
   return extractAnthropicTurnResult(responseData);
 }
 
@@ -1198,6 +1324,7 @@ export {
   extractTurnResult,
   buildAnthropicRequest,
   buildOpenAiRequest,
+  buildGoogleRequest,
   classifyError,
   classifyHttpError,
   BUNDLED_COST_RATES,

package/src/lib/continuity-status.js

@@ -1,9 +1,111 @@
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { readSessionCheckpoint } from './session-checkpoint.js';
+import { captureBaselineRef, readSessionCheckpoint } from './session-checkpoint.js';
 
 export const SESSION_RECOVERY_PATH = '.agentxchain/SESSION_RECOVERY.md';
 
+function deriveRecommendedContinuityAction(state) {
+  if (!state) {
+    return {
+      recommended_command: null,
+      recommended_reason: 'no_state',
+      recommended_detail: null,
+      restart_recommended: false,
+    };
+  }
+
+  if (state.pending_phase_transition) {
+    const pt = state.pending_phase_transition;
+    return {
+      recommended_command: 'agentxchain approve-transition',
+      recommended_reason: 'pending_phase_transition',
+      recommended_detail: `${pt.from || 'unknown'} -> ${pt.to || 'unknown'} (gate: ${pt.gate || 'unknown'})`,
+      restart_recommended: false,
+    };
+  }
+
+  if (state.pending_run_completion) {
+    const pc = state.pending_run_completion;
+    return {
+      recommended_command: 'agentxchain approve-completion',
+      recommended_reason: 'pending_run_completion',
+      recommended_detail: pc.gate ? `gate: ${pc.gate}` : null,
+      restart_recommended: false,
+    };
+  }
+
+  if (!['blocked', 'completed', 'failed'].includes(state.status)) {
+    return {
+      recommended_command: 'agentxchain restart',
+      recommended_reason: 'restart_available',
+      recommended_detail: 'rebuild session context from disk',
+      restart_recommended: true,
+    };
+  }
+
+  return {
+    recommended_command: null,
+    recommended_reason: state.status === 'blocked' ? 'blocked' : 'terminal_state',
+    recommended_detail: null,
+    restart_recommended: false,
+  };
+}
+
+function deriveCheckpointDrift(root, checkpoint, staleCheckpoint) {
+  if (!checkpoint?.baseline_ref || staleCheckpoint) {
+    return {
+      drift_detected: null,
+      drift_warnings: [],
+    };
+  }
+
+  const currentBaseline = captureBaselineRef(root);
+  const previousBaseline = checkpoint.baseline_ref;
+
+  if (
+    currentBaseline.git_head == null
+    && currentBaseline.git_branch == null
+    && currentBaseline.workspace_dirty == null
+  ) {
+    return {
+      drift_detected: null,
+      drift_warnings: [],
+    };
+  }
+
+  const driftWarnings = [];
+
+  if (
+    previousBaseline.git_head
+    && currentBaseline.git_head
+    && previousBaseline.git_head !== currentBaseline.git_head
+  ) {
+    driftWarnings.push(
+      `Git HEAD has moved since checkpoint: ${previousBaseline.git_head.slice(0, 8)} -> ${currentBaseline.git_head.slice(0, 8)}`
+    );
+  }
+
+  if (
+    previousBaseline.git_branch
+    && currentBaseline.git_branch
+    && previousBaseline.git_branch !== currentBaseline.git_branch
+  ) {
+    driftWarnings.push(`Branch changed since checkpoint: ${previousBaseline.git_branch} -> ${currentBaseline.git_branch}`);
+  }
+
+  if (
+    previousBaseline.workspace_dirty === false
+    && currentBaseline.workspace_dirty === true
+  ) {
+    driftWarnings.push('Workspace was clean at checkpoint but is now dirty');
+  }
+
+  return {
+    drift_detected: driftWarnings.length > 0,
+    drift_warnings: driftWarnings,
+  };
+}
+
 export function getContinuityStatus(root, state) {
   const checkpoint = readSessionCheckpoint(root);
   const recoveryReportPath = existsSync(join(root, SESSION_RECOVERY_PATH))
@@ -18,10 +120,18 @@ export function getContinuityStatus(root, state) {
     && checkpoint.run_id !== state.run_id
   );
 
+  const action = deriveRecommendedContinuityAction(state);
+  const drift = deriveCheckpointDrift(root, checkpoint, staleCheckpoint);
+
   return {
     checkpoint,
     stale_checkpoint: staleCheckpoint,
     recovery_report_path: recoveryReportPath,
-    restart_recommended: !!state && !['blocked', 'completed', 'failed'].includes(state.status),
+    restart_recommended: action.restart_recommended,
+    recommended_command: action.recommended_command,
+    recommended_reason: action.recommended_reason,
+    recommended_detail: action.recommended_detail,
+    drift_detected: drift.drift_detected,
+    drift_warnings: drift.drift_warnings,
   };
 }

package/src/lib/governed-state.js

@@ -1352,6 +1352,11 @@ export function markRunBlocked(root, details) {
 
   writeState(root, updatedState);
 
+  // Session checkpoint — non-fatal, written after blocked state is persisted
+  writeSessionCheckpoint(root, updatedState, 'blocked', {
+    role: turnId ? (getActiveTurns(updatedState)[turnId]?.assigned_role || null) : null,
+  });
+
   emitBlockedNotification(root, details.notificationConfig, updatedState, {
     category: details.category,
     blockedOn: details.blockedOn,
@@ -1753,6 +1758,13 @@ export function assignGovernedTurn(root, config, roleId) {
   };
 
   writeState(root, updatedState);
+
+  // Session checkpoint — non-fatal, written after every successful turn assignment
+  writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
+    role: roleId,
+    dispatch_dir: `.agentxchain/dispatch/turns/${turnId}`,
+  });
+
   const assignedTurn = updatedState.active_turns[turnId];
   const result = { ok: true, state: attachLegacyCurrentTurnAlias(updatedState), turn: assignedTurn };
   if (warnings.length > 0) {

package/src/lib/normalized-config.js

@@ -18,7 +18,7 @@ import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
-const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
+const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];

package/src/lib/session-checkpoint.js

@@ -2,9 +2,10 @@
  * Session checkpoint — automatic state markers for cross-session restart.
  *
  * Writes .agentxchain/session.json at every governance boundary
- * (turn acceptance, phase transition, gate approval, run completion)
- * so that `agentxchain restart` can reconstruct dispatch context
- * without any in-memory session state.
+ * (turn assignment, acceptance, phase transition, blocked state,
+ * gate approval, run completion, restart/reconnect) so that
+ * `agentxchain restart` can reconstruct dispatch context without
+ * any in-memory session state.
  *
  * Design rules:
  *   - Checkpoint writes are non-fatal: failures log a warning and do not
@@ -12,11 +13,13 @@
  *   - The file is always overwritten, not appended.
  *   - run_id in session.json must agree with state.json; mismatch is a
  *     corruption signal.
+ *   - state.json is always authoritative; session.json is recovery metadata.
  */
 
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { randomBytes } from 'crypto';
+import { execSync as shellExec } from 'child_process';
 
 const SESSION_PATH = '.agentxchain/session.json';
 
@@ -27,6 +30,25 @@ function generateSessionId() {
   return `session_${randomBytes(8).toString('hex')}`;
 }
 
+/**
+ * Capture git baseline ref for repo-drift detection.
+ * Non-fatal: returns partial/null fields on failure.
+ */
+export function captureBaselineRef(root) {
+  try {
+    const gitHead = shellExec('git rev-parse HEAD', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const gitBranch = shellExec('git rev-parse --abbrev-ref HEAD', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    const statusOutput = shellExec('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    return {
+      git_head: gitHead,
+      git_branch: gitBranch,
+      workspace_dirty: statusOutput.length > 0,
+    };
+  } catch {
+    return { git_head: null, git_branch: null, workspace_dirty: null };
+  }
+}
+
 /**
  * Read the current session checkpoint, or null if none exists.
  */
@@ -40,12 +62,21 @@ export function readSessionCheckpoint(root) {
   }
 }
 
+/**
+ * Extract active turn IDs from governed state.
+ */
+function getActiveTurnIds(state) {
+  const turns = state.active_turns || {};
+  return Object.keys(turns);
+}
+
 /**
  * Write or update the session checkpoint.
  *
  * @param {string} root - project root
  * @param {object} state - current governed state (from state.json)
- * @param {string} reason - checkpoint reason (e.g. 'turn_accepted', 'phase_approved', 'run_completed')
+ * @param {string} reason - checkpoint reason (e.g. 'turn_assigned', 'turn_accepted',
+ *                          'phase_approved', 'run_completed', 'blocked', 'restart_reconnect')
  * @param {object} [extra] - optional extra context fields
  */
 export function writeSessionCheckpoint(root, state, reason, extra = {}) {
@@ -58,20 +89,40 @@ export function writeSessionCheckpoint(root, state, reason, extra = {}) {
       : generateSessionId();
 
     const currentTurn = state.current_turn || null;
-    const lastTurnId = currentTurn?.id || currentTurn?.turn_id || state.last_completed_turn_id || null;
+    const activeTurnIds = getActiveTurnIds(state);
+    const lastTurnId = currentTurn?.id || currentTurn?.turn_id
+      || (activeTurnIds.length > 0 ? activeTurnIds[activeTurnIds.length - 1] : null)
+      || state.last_completed_turn_id || null;
     const lastRole = currentTurn?.role || currentTurn?.assigned_role || extra.role || null;
     const lastPhase = state.current_phase || state.phase || null;
 
+    // Derive last_completed_turn_id from history or state
+    const lastCompletedTurnId = state.last_completed_turn_id || existing?.last_completed_turn_id || null;
+
+    // Derive pending gates
+    const pendingGate = state.pending_phase_transition?.gate || state.pending_transition?.gate || null;
+    const pendingRunCompletion = state.pending_run_completion?.gate || null;
+
+    // Capture git baseline for repo-drift detection
+    const baselineRef = extra.baseline_ref || captureBaselineRef(root);
+
     const checkpoint = {
       session_id: sessionId,
       run_id: state.run_id,
       started_at: existing?.started_at || new Date().toISOString(),
       last_checkpoint_at: new Date().toISOString(),
+      checkpoint_reason: reason,
+      run_status: state.status || null,
+      phase: lastPhase,
+      last_phase: lastPhase, // backward compat alias for report.js consumers
       last_turn_id: lastTurnId,
-      last_phase: lastPhase,
+      last_completed_turn_id: lastCompletedTurnId,
+      active_turn_ids: activeTurnIds,
       last_role: lastRole,
-      run_status: state.status || null,
-      checkpoint_reason: reason,
+      pending_gate: pendingGate,
+      pending_run_completion: pendingRunCompletion ? true : null,
+      blocked: state.status === 'blocked',
+      baseline_ref: baselineRef,
       agent_context: {
         adapter: extra.adapter || null,
         dispatch_dir: extra.dispatch_dir || null,