@lazyingart/agintiflow 0.20.250 → 0.20.252

package/docs/model-selection.md

@@ -26,6 +26,8 @@ The local tier policy uses the workstation's installed aliases without treating
 
 Installed aliases are not loaded during routing. A genuine coding/implementation request starts on Deep, checks the authenticated model inventory, and selects the exact `AGINTI_LOCALLLM_CODE_MODEL` value only when present. Missing or unverified capability stays on Deep; the decision and effective model are recorded so fallback sessions can re-evaluate and selected sessions resume on the same model. Explanation-only code questions and non-code writing/research/documentation/design keep their existing route. Automatic Max is off by default; set `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true` to opt in. An opted-in high-complexity non-code run starts on Deep, confirms the Max alias through authenticated `/v1/models`, and only then samples current resources. Unknown or pressured resource state stays on Deep. Explicit Max also cannot bypass the live gate: immediately before client creation, each new or resumed run rechecks at least 24 GiB available RAM, swap use at or below 75%, and 40 GiB aggregate free NVIDIA memory. A blocked explicit gate creates no model client and performs no inference.
 
+Smart hosted routes fail over only toward the local trust boundary. If a hosted provider returns an authentication, quota, rate-limit, model-availability, capacity, or network failure, AgInTiFlow records `provider.handoff_requested`, patches the same durable session to `localllm-deep`, verifies LocalLLM readiness, records `provider.handoff_activated`, and continues without replaying the user request or prior side effects. Manual routing remains exact and never changes provider automatically. Retained integration profiles also keep their pinned provider identity. Set `AGINTI_PROVIDER_HANDOFF=false` to disable the smart hosted-to-local handoff or `AGINTI_PROVIDER_HANDOFF_MODEL` to select another verified local fallback model.
+
 Long writing tasks use an additional tool boundary: `writing_specialist`. The main model still plans the run, manages files, formats Markdown/LaTeX/Final Draft output, compiles/checks artifacts, and finishes. The specialist gets only the writing brief, canon, style guide, prior draft, target, audience, constraints, and format intent, then returns prose plus a formatter handoff. It follows the active LocalLLM provider by default even when hosted keys exist. Cross-provider writing requires both an explicit target (`AGINTI_WRITING_PROVIDER` or a per-run provider override) and `AGINTI_ALLOW_HOSTED_WRITING_SPECIALIST=true` (or the equivalent per-run permission flag); language detection and ambient credentials never grant that permission.
 
 ## CLI Commands

package/docs/supervision-campaign-ledger.md

@@ -379,3 +379,32 @@ local report paths and existing-document revision language now count as local
 workspace intent, so surrounding research policy does not force a new deep
 research route. The phrase `page-safe` no longer creates a browser-evidence
 requirement. Focused routing/evidence smokes and the full npm suite pass.
+
+### Fresh current-turn command evidence on retained sessions
+
+`security-labshare-035` exercised a long-lived LocalLLM security-repair
+session after the target repository was already fixed, committed, and clean.
+The follow-up prompt deliberately asked the agent not to edit or recommit. It
+required only the exact hidden verifier and `git status --short`, while allowing
+all other passing implementation and unit-test evidence to remain reusable.
+
+Installed AgInTiFlow `0.20.250` incorrectly finished after `inspect_project`.
+It reused the old verifier/status evidence and never executed either command in
+the current turn. The defect was not model quality: the runtime had failed to
+turn explicit commands in a concrete same-task interruption into a fresh,
+revision-bound evidence obligation.
+
+The runtime now records explicit current-turn commands in the active execution
+contract and creates a fresh command batch for only that subset. Unrelated
+passing evidence from the unchanged mutation revision remains valid, while old
+runs of the newly requested commands cannot pre-complete the batch. Inline
+command extraction also recognizes natural `verify`, `validate`, `check`,
+`confirm`, and rerun wording in English and Chinese.
+
+The same real session was replayed against the patched source at goal revision
+`34`. Its event ledger records both commands under
+`required-command-batch-3`: the exact external security contract returned
+`security_labshare_contract: PASS`, and `git status --short` returned empty.
+The target stayed at commit `2b35928` with no mutation. Focused planning,
+truthful-completion, and dynamic-budget regressions pass, as does the complete
+AgInTiFlow npm suite. The fix is released in AgInTiFlow `0.20.251`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.250",
+  "version": "0.20.252",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -174,6 +174,7 @@
     "smoke:localllm-code-routing": "node scripts/smoke-localllm-code-routing.js",
     "smoke:local-failure-recovery": "node scripts/smoke-local-failure-recovery.js",
     "smoke:planning-timeout-recovery": "node scripts/smoke-planning-timeout-recovery.js",
+    "smoke:provider-handoff": "node scripts/smoke-provider-handoff.js",
     "smoke:local-resource-policy": "node scripts/smoke-local-resource-policy.js",
     "smoke:context-budget-recovery": "node scripts/smoke-context-budget-recovery.js",
     "smoke:localllm-model-tiers": "node scripts/smoke-localllm-model-tiers.js",
@@ -228,7 +229,7 @@
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
     "pretest": "npm run smoke:planning-timeout-recovery",
-    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:integration-production-runtime-bundle && npm run smoke:integration-retained-idempotency-store && npm run smoke:integration-storage-authority && npm run smoke:integration-retained-durable-common && npm run smoke:integration-retained-file-lock && npm run smoke:integration-retained-event-ledger && npm run smoke:integration-retained-event-ledger-bundle && npm run smoke:integration-retained-repository-kernel && npm run smoke:integration-retained-session-state-store && npm run smoke:integration-retained-native-session-repository-state && npm run smoke:integration-retained-native-execution-evidence && npm run smoke:integration-retained-runtime-repository-surface && npm run smoke:integration-retained-runtime-repository-phase-b && npm run smoke:integration-runtime-repository-contract && npm run smoke:integration-runtime-authority && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:local-failure-recovery && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:document-artifact-quality && npm run smoke:writing-specialist-routing && npm run smoke:workspace-secret-false-positive && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:supervision-ledger && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:integration-production-runtime-bundle && npm run smoke:integration-retained-idempotency-store && npm run smoke:integration-storage-authority && npm run smoke:integration-retained-durable-common && npm run smoke:integration-retained-file-lock && npm run smoke:integration-retained-event-ledger && npm run smoke:integration-retained-event-ledger-bundle && npm run smoke:integration-retained-repository-kernel && npm run smoke:integration-retained-session-state-store && npm run smoke:integration-retained-native-session-repository-state && npm run smoke:integration-retained-native-execution-evidence && npm run smoke:integration-retained-runtime-repository-surface && npm run smoke:integration-retained-runtime-repository-phase-b && npm run smoke:integration-runtime-repository-contract && npm run smoke:integration-runtime-authority && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:local-failure-recovery && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:document-artifact-quality && npm run smoke:writing-specialist-routing && npm run smoke:workspace-secret-false-positive && npm run smoke:provider-handoff && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:supervision-ledger && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-dynamic-step-budget.js

@@ -2885,6 +2885,152 @@ try {
     "the goal contract did not separate durable task lineage from the active interruption"
   );
 
+  const exactVerifier = "python3 /tmp/security_labshare_contract.py";
+  const exactStatus = "git status --short";
+  const retainedUnitTest = "python3 -m unittest discover -s tests -v";
+  const freshCommandState = {
+    goal: "Repair and verify the current security task.",
+    plan: "The prior implementation and validation are complete.",
+    messages: [
+      toolMessage({
+        ok: true,
+        toolName: "run_command",
+        args: { command: retainedUnitTest },
+        exitCode: 0,
+        stdout: "OK",
+        projectMutationRevision: 7,
+        goalRevision: 5,
+      }),
+      toolMessage({
+        ok: true,
+        toolName: "run_command",
+        args: { command: exactVerifier },
+        exitCode: 0,
+        stdout: "security_labshare_contract: PASS",
+        projectMutationRevision: 7,
+        requiredCommandBatchId: "required-command-batch-2",
+        requiredProjectCommand: exactVerifier,
+        goalRevision: 5,
+      }),
+      toolMessage({
+        ok: true,
+        toolName: "run_command",
+        args: { command: exactStatus },
+        exitCode: 0,
+        stdout: "",
+        projectMutationRevision: 7,
+        requiredCommandBatchId: "required-command-batch-2",
+        requiredProjectCommand: exactStatus,
+        goalRevision: 5,
+      }),
+    ],
+    meta: {
+      taskProfile: "security",
+      goalContract: {
+        version: 3,
+        revision: 5,
+        status: "completed",
+        taskGoal: "Repair and verify the current security task.",
+        activeGoal: "Repair and verify the current security task.",
+        currentRequest: "Repair and verify the current security task.",
+        history: [{ revision: 5, taskHash: "same-security-task" }],
+      },
+      projectVerification: {
+        mutationRevision: 7,
+        requiredCommands: [retainedUnitTest],
+        contractRequiredCommands: [exactVerifier, exactStatus],
+        requiredCommandBatchSequence: 2,
+        requiredCommandBatch: {
+          id: "required-command-batch-2",
+          key: JSON.stringify([exactVerifier, exactStatus]),
+          requiredCommands: [exactVerifier, exactStatus],
+          goalRevision: 5,
+          completedCommands: [exactVerifier, exactStatus],
+          completedRuns: [
+            { command: exactVerifier, mutationRevision: 7 },
+            { command: exactStatus, mutationRevision: 7 },
+          ],
+          startedMutationRevision: 7,
+          lastMutationRevision: 7,
+          complete: true,
+        },
+        commandRuns: [{
+          command: retainedUnitTest,
+          mutationRevision: 7,
+          ok: true,
+        }],
+        testRuns: [],
+      },
+    },
+  };
+  const freshCommandRequest =
+    "Continue the same corrective task. Run `python3 /tmp/security_labshare_contract.py`, verify `git status --short`, and finish without editing or recommitting files.";
+  const freshCommandUpdate = applyContinuationContractTransition(
+    freshCommandState,
+    freshCommandRequest,
+    { at: "2026-08-26T04:00:00.000Z" }
+  );
+  assert(
+    freshCommandUpdate?.preserveTaskBoundary && freshCommandUpdate?.refreshExecutionContract,
+    "an explicit same-task command rerun did not refresh the execution contract"
+  );
+  assert(
+    JSON.stringify(freshCommandState.meta.activeExecutionContract.requiredProjectCommands) ===
+      JSON.stringify([exactVerifier, exactStatus]),
+    "the current turn lost an explicitly verified inline command"
+  );
+  assert(
+    freshCommandState.meta.projectVerification.requiredCommandBatch.goalRevision === 6,
+    "the fresh command batch was not bound to the current goal revision"
+  );
+  assert(
+    freshCommandState.meta.projectVerification.requiredCommandBatch.completedCommands.length === 0,
+    "retained command evidence pre-completed a current-turn rerun obligation"
+  );
+  const freshCommandConfig = {
+    taskProfile: "security",
+    commandCwd: workspace,
+  };
+  let freshCommandRuntime = nextStepRuntimeConfig(freshCommandConfig, freshCommandState);
+  assert(
+    freshCommandRuntime.requiredProjectCommandPending === true,
+    "the current-turn verifier was not marked pending"
+  );
+  assert(
+    freshCommandRuntime.requiredProjectCommand === exactVerifier,
+    "the first explicitly repeated command was not pending"
+  );
+  const verifierResult = {
+    ok: true,
+    toolName: "run_command",
+    args: { command: exactVerifier },
+    exitCode: 0,
+    stdout: "security_labshare_contract: PASS",
+    stderr: "",
+  };
+  recordProjectVerificationOutcome(freshCommandState, verifierResult, freshCommandConfig);
+  freshCommandState.messages.push(toolMessage(verifierResult));
+  freshCommandRuntime = nextStepRuntimeConfig(freshCommandConfig, freshCommandState);
+  assert(
+    freshCommandRuntime.requiredProjectCommand === exactStatus,
+    "the second current-turn command was not retained after the verifier passed"
+  );
+  const statusResult = {
+    ok: true,
+    toolName: "run_command",
+    args: { command: exactStatus },
+    exitCode: 0,
+    stdout: "",
+    stderr: "",
+  };
+  recordProjectVerificationOutcome(freshCommandState, statusResult, freshCommandConfig);
+  freshCommandState.messages.push(toolMessage(statusResult));
+  freshCommandRuntime = nextStepRuntimeConfig(freshCommandConfig, freshCommandState);
+  assert(
+    freshCommandRuntime.requiredProjectCommandPending !== true,
+    "the fresh command batch stayed pending after both exact commands passed"
+  );
+
   const bareContinuationState = {
     goal: concreteContinuation,
     plan: "Update both retained outputs, validate, and commit.",

package/src/agent-runner.js

@@ -93,6 +93,7 @@ import { longJobStatus, startLongJob } from "./long-job-tools.js";
 import { executeAgentLinkTool, isAgentLinkTool } from "./agentlink.js";
 import { classifyGoalIntent, isDirectAnswerIntent } from "./goal-intent.js";
 import { normalizeProviderBaseURL, normalizeProviderId, providerRequiresApiKey } from "./provider-contract.js";
+import { resolveProviderHandoff } from "./provider-handoff.js";
 import { ProviderReadinessError, probeProviderRuntime } from "./provider-runtime.js";
 import { probeLocalMaxResources } from "./local-resource-policy.js";
 import {
@@ -3066,10 +3067,25 @@ export function resetSameTaskExecutionContract(state = {}, revision = 0) {
     removed.push(key);
   }
   state.plan = "";
+  const activeRevision = Math.max(0, Number(revision || state.meta?.goalContract?.revision || 0));
+  const currentRequest = String(state.meta?.goalContract?.currentRequest || state.goal || "").trim();
+  const currentTurnCommands = normalizedRequiredProjectCommands(
+    deriveScsTaskContract({
+      goal: currentRequest,
+      taskProfile: state.meta?.taskProfile || "auto",
+    }).requiredProjectCommands
+  );
   state.meta.activeExecutionContract = {
-    revision: Math.max(0, Number(revision || state.meta?.goalContract?.revision || 0)),
+    revision: activeRevision,
     refreshedAt: new Date().toISOString(),
+    requiredProjectCommands: currentTurnCommands,
   };
+  const verification = state.meta.projectVerification;
+  if (verification && typeof verification === "object" && currentTurnCommands.length) {
+    startRequiredCommandBatch(verification, currentTurnCommands, {
+      goalRevision: activeRevision,
+    });
+  }
   return removed;
 }
 
@@ -4289,10 +4305,27 @@ function effectiveRequiredProjectCommands(state = {}, verification = {}, config
 
 function currentRequiredCommandBatch(verification = {}, requiredCommands = []) {
   const batch = verification.requiredCommandBatch;
-  const key = requiredCommandBatchKey(requiredCommands);
-  if (!batch || typeof batch !== "object" || !key || batch.key !== key || !batch.id) return null;
+  const effectiveCommands = normalizedRequiredProjectCommands(requiredCommands);
+  const batchCommands = normalizedRequiredProjectCommands(
+    Array.isArray(batch?.requiredCommands)
+      ? batch.requiredCommands
+      : batch?.key === requiredCommandBatchKey(effectiveCommands)
+        ? effectiveCommands
+        : []
+  );
+  if (
+    !batch ||
+    typeof batch !== "object" ||
+    !batch.id ||
+    !batchCommands.length ||
+    batch.key !== requiredCommandBatchKey(batchCommands) ||
+    batchCommands.some((command) => !effectiveCommands.includes(command))
+  ) {
+    return null;
+  }
   return {
     ...batch,
+    requiredCommands: batchCommands,
     completedCommands: Array.isArray(batch.completedCommands)
       ? batch.completedCommands.map(normalizeProjectCommand).filter(Boolean)
       : [],
@@ -4307,13 +4340,20 @@ function currentRequiredCommandBatch(verification = {}, requiredCommands = []) {
   };
 }
 
-function startRequiredCommandBatch(verification = {}, requiredCommands = []) {
+function startRequiredCommandBatch(
+  verification = {},
+  requiredCommands = [],
+  { goalRevision = 0 } = {}
+) {
+  const normalizedCommands = normalizedRequiredProjectCommands(requiredCommands);
   const sequence = Math.max(0, Number(verification.requiredCommandBatchSequence || 0)) + 1;
   verification.requiredCommandBatchSequence = sequence;
   const revision = Math.max(0, Number(verification.mutationRevision || 0));
   const batch = {
     id: `required-command-batch-${sequence}`,
-    key: requiredCommandBatchKey(requiredCommands),
+    key: requiredCommandBatchKey(normalizedCommands),
+    requiredCommands: normalizedCommands,
+    goalRevision: Math.max(0, Number(goalRevision || 0)),
     completedCommands: [],
     completedRuns: [],
     startedMutationRevision: revision + 1,
@@ -4474,7 +4514,7 @@ function requiredCommandRunIsCurrent(
   if (!required || !commandMatches) return false;
   const requiredCommands = verificationRequiredProjectCommands(verification);
   const batch = currentRequiredCommandBatch(verification, requiredCommands);
-  if (batch?.id) {
+  if (batch?.id && batch.requiredCommands.includes(required)) {
     const accepted = batch.completedRuns.find((item) => item.command === required);
     return Boolean(
       accepted &&
@@ -4597,21 +4637,45 @@ export function recordProjectVerificationOutcome(state = {}, toolResult = {}, co
         commandCanMutateProjectContent(mutationCommand, commandPolicy)
     );
     let requiredBatch = currentRequiredCommandBatch(verification, requiredCommands);
+    const activeExecutionContract = state.meta?.activeExecutionContract;
+    const activeTurnCommands =
+      Number(activeExecutionContract?.revision || 0) ===
+      Number(state.meta?.goalContract?.revision || 0)
+        ? normalizedRequiredProjectCommands(activeExecutionContract?.requiredProjectCommands)
+        : [];
+    if (
+      !requiredBatch &&
+      requiredCommand &&
+      activeTurnCommands.includes(requiredCommand)
+    ) {
+      requiredBatch = startRequiredCommandBatch(verification, activeTurnCommands, {
+        goalRevision: state.meta?.goalContract?.revision || 0,
+      });
+    }
+    let batchRequiredCommands = requiredBatch?.requiredCommands || requiredCommands;
     if (projectContentMutation) {
       delete state.meta.verifiedCompletionCandidate;
       if (
         requiredCommand &&
+        batchRequiredCommands.includes(requiredCommand) &&
         (!requiredBatch ||
           requiredBatch.complete ||
           requiredBatch.completedCommands.includes(requiredCommand))
       ) {
-        requiredBatch = startRequiredCommandBatch(verification, requiredCommands);
+        requiredBatch = startRequiredCommandBatch(verification, batchRequiredCommands, {
+          goalRevision: state.meta?.goalContract?.revision || 0,
+        });
+        batchRequiredCommands = requiredBatch.requiredCommands;
       }
       verification.mutationRevision += 1;
-      if (requiredCommand && requiredBatch) {
+      if (
+        requiredCommand &&
+        requiredBatch &&
+        requiredBatch.requiredCommands.includes(requiredCommand)
+      ) {
         invalidateRequiredBatchValidations(
           requiredBatch,
-          requiredCommands,
+          requiredBatch.requiredCommands,
           config,
           requiredCommand
         );
@@ -4640,17 +4704,19 @@ export function recordProjectVerificationOutcome(state = {}, toolResult = {}, co
     };
     if (requiredCommand && commandSucceeded) {
       if (!requiredBatch && requiredMutatingCommands.length === 0) {
-        requiredBatch = startRequiredCommandBatch(verification, requiredCommands);
+        requiredBatch = startRequiredCommandBatch(verification, requiredCommands, {
+          goalRevision: state.meta?.goalContract?.revision || 0,
+        });
         requiredBatch.startedMutationRevision = verification.mutationRevision;
         requiredBatch.lastMutationRevision = verification.mutationRevision;
       }
-      if (requiredBatch) {
+      if (requiredBatch?.requiredCommands.includes(requiredCommand)) {
         recordRequiredBatchRun(
           requiredBatch,
           requiredCommand,
           verification.mutationRevision
         );
-        requiredBatch.complete = requiredCommands.every((candidate) =>
+        requiredBatch.complete = requiredBatch.requiredCommands.every((candidate) =>
           requiredBatch.completedCommands.includes(candidate)
         );
         verification.requiredCommandBatch = requiredBatch;
@@ -10993,7 +11059,78 @@ async function recordPreInferenceFailure({ error, config, state, store, observer
   emitConsole(config, result, { kind: "error", error: true });
 }
 
-export async function runAgent(config) {
+class ProviderHandoffSignal extends Error {
+  constructor({ sessionId, expectedRuntimeRevision, decision }) {
+    super(`Provider handoff requested for ${decision.sourceProvider} -> ${decision.targetProvider}.`);
+    this.name = "ProviderHandoffSignal";
+    this.sessionId = sessionId;
+    this.expectedRuntimeRevision = expectedRuntimeRevision;
+    this.decision = decision;
+  }
+}
+
+async function prepareProviderHandoff({ error, config, state, store, observers, sessionId, stage = "runtime" }) {
+  const decision = resolveProviderHandoff(error, config, { stage });
+  if (!decision) return null;
+
+  state.meta = state.meta || {};
+  const priorAttempts = Number(state.meta.providerHandoff?.attempts || 0);
+  if (priorAttempts >= 1) return null;
+
+  const at = new Date().toISOString();
+  const detail = {
+    version: 1,
+    attempts: priorAttempts + 1,
+    status: "pending",
+    sourceProvider: decision.sourceProvider,
+    sourceModel: decision.sourceModel,
+    targetProvider: decision.targetProvider,
+    targetModel: decision.targetModel,
+    failureCode: decision.failureCode,
+    httpStatus: decision.status || 0,
+    requestedAt: at,
+  };
+  state.meta.providerHandoff = detail;
+  state.updatedAt = at;
+  updateGoalStatus(state, "active", "provider_handoff", at);
+  await store.saveState(state);
+  await store.appendEvent("provider.handoff_requested", detail);
+  observers.event("provider.handoff_requested", { ...detail, sessionId });
+  emitConsole(
+    config,
+    `${decision.sourceProvider}/${decision.sourceModel} is unavailable (${decision.failureCode}); continuing the same session with ${decision.targetProvider}/${decision.targetModel}.`,
+    { kind: "meta" }
+  );
+  return new ProviderHandoffSignal({
+    sessionId,
+    expectedRuntimeRevision: Number(state.meta.runtimeConfig?.revision || 1),
+    decision,
+  });
+}
+
+async function activatePendingProviderHandoff({ config, state, store, observers, sessionId }) {
+  const handoff = state.meta?.providerHandoff;
+  if (
+    !handoff ||
+    handoff.status !== "pending" ||
+    normalizeProviderId(handoff.targetProvider, "") !== normalizeProviderId(config.provider, "") ||
+    String(handoff.targetModel || "") !== String(config.model || "")
+  ) {
+    return;
+  }
+  const detail = {
+    ...handoff,
+    status: "active",
+    activatedAt: new Date().toISOString(),
+  };
+  state.meta.providerHandoff = detail;
+  state.updatedAt = detail.activatedAt;
+  await store.saveState(state);
+  await store.appendEvent("provider.handoff_activated", detail);
+  observers.event("provider.handoff_activated", { ...detail, sessionId });
+}
+
+async function runAgentOnce(config) {
   assertIntegrationRunAgentInvocation(config);
   const incomingConfig = config;
   const sessionId = config.resume || config.sessionId || `web-agent-${crypto.randomUUID()}`;
@@ -11022,6 +11159,11 @@ export async function runAgent(config) {
     state.meta = state.meta || {};
     state.meta.runtimeConfig = runtime.snapshot;
     config = rebuildResumedRuntimeConfig(incomingConfig, runtime.runtimeOverrides, sessionId);
+    // Keep compatibility fields aligned with the authoritative runtime
+    // snapshot. Provider/model patches otherwise leave stale top-level values
+    // that can mislead later diagnostics and legacy session readers.
+    state.provider = config.provider;
+    state.model = config.model;
     const patchedRuntimeFields = runtime.patched
       ? Object.keys(incomingConfig.runtimePatch || {}).filter((field) => isSessionRuntimeField(field))
       : [];
@@ -11196,10 +11338,22 @@ export async function runAgent(config) {
     }
     client = config.clientFactory ? await config.clientFactory(config) : createClient(config);
   } catch (error) {
+    const handoff = await prepareProviderHandoff({
+      error,
+      config,
+      state,
+      store,
+      observers,
+      sessionId,
+      stage: "preflight",
+    });
+    if (handoff) throw handoff;
     await recordPreInferenceFailure({ error, config, state, store, observers, sessionId });
     throw error;
   }
 
+  await activatePendingProviderHandoff({ config, state, store, observers, sessionId });
+
   ensureChatState(state);
 
   const initialRepair = repairModelMessageHistory(state, config);
@@ -12872,6 +13026,9 @@ export async function runAgent(config) {
       ...goalRunMetadata(state),
     };
   } catch (error) {
+    if (error instanceof ProviderHandoffSignal) throw error;
+    const handoff = await prepareProviderHandoff({ error, config, state, store, observers, sessionId });
+    if (handoff) throw handoff;
     if (isModelTimeoutError(error)) {
       const detail = {
         reason: "model_timeout",
@@ -12935,3 +13092,20 @@ export async function runAgent(config) {
     await flushHousekeeping();
   }
 }
+
+export async function runAgent(config) {
+  try {
+    return await runAgentOnce(config);
+  } catch (error) {
+    if (!(error instanceof ProviderHandoffSignal)) throw error;
+    const decision = error.decision;
+    return runAgentOnce({
+      ...config,
+      goal: "",
+      resume: error.sessionId,
+      sessionId: error.sessionId,
+      runtimePatch: decision.runtimePatch,
+      expectedRuntimeRevision: error.expectedRuntimeRevision,
+    });
+  }
+}

package/src/model-client.js

@@ -148,6 +148,22 @@ function shouldRetryWithoutReasoningEffort(error, payload = {}) {
   return /reasoning[_\s.-]?effort|unsupported parameter|unknown parameter|unrecognized request argument/i.test(message);
 }
 
+function annotateProviderRequestError(error, config = {}, label = "model request") {
+  if (!error || (typeof error !== "object" && typeof error !== "function")) return error;
+  try {
+    Object.defineProperties(error, {
+      agintiProviderRequest: { value: true, configurable: true },
+      agintiProvider: { value: String(config.provider || ""), configurable: true },
+      agintiProviderModel: { value: String(config.model || ""), configurable: true },
+      agintiProviderRequestLabel: { value: String(label || "model request"), configurable: true },
+    });
+  } catch {
+    // Some SDK errors can be non-extensible. Classification still has the
+    // explicit preflight path, while an unmarked runtime error fails normally.
+  }
+  return error;
+}
+
 export async function createChatCompletion(client, payload, config, label = "model request") {
   const preparedPayload = withChatReasoningEffort(payload, config);
   const timeout = resolveModelTimeoutMs(config);
@@ -157,9 +173,13 @@ export async function createChatCompletion(client, payload, config, label = "mod
     } catch (error) {
       if (shouldRetryWithoutReasoningEffort(error, preparedPayload)) {
         const { reasoning_effort: _reasoningEffort, ...retryPayload } = preparedPayload;
-        return client.chat.completions.create(retryPayload, requestOptions(config));
+        try {
+          return await client.chat.completions.create(retryPayload, requestOptions(config));
+        } catch (retryError) {
+          throw annotateProviderRequestError(retryError, config, label);
+        }
       }
-      throw error;
+      throw annotateProviderRequestError(error, config, label);
     }
   }
 
@@ -196,18 +216,22 @@ export async function createChatCompletion(client, payload, config, label = "mod
   } catch (error) {
     if (shouldRetryWithoutReasoningEffort(error, preparedPayload)) {
       const { reasoning_effort: _reasoningEffort, ...retryPayload } = preparedPayload;
-      return await client.chat.completions.create(retryPayload, {
-        ...requestOptions(config),
-        signal: controller.signal,
-      });
+      try {
+        return await client.chat.completions.create(retryPayload, {
+          ...requestOptions(config),
+          signal: controller.signal,
+        });
+      } catch (retryError) {
+        throw annotateProviderRequestError(retryError, config, label);
+      }
     }
     if (timedOut && error?.name !== "ModelTimeoutError") {
       const timeoutError = new Error(`${label} timed out after ${timeout}ms`);
       timeoutError.name = "ModelTimeoutError";
       timeoutError.cause = error;
-      throw timeoutError;
+      throw annotateProviderRequestError(timeoutError, config, label);
     }
-    throw error;
+    throw annotateProviderRequestError(error, config, label);
   } finally {
     if (timer) clearTimeout(timer);
     if (config.abortSignal) {

package/src/provider-handoff.js

@@ -0,0 +1,126 @@
+import { LOCALLLM_MODEL_TIERS } from "./model-routing.js";
+import { normalizeProviderId } from "./provider-contract.js";
+
+const NETWORK_ERROR_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+]);
+
+function enabled(value, fallback = true) {
+  if (value === undefined || value === null || String(value).trim() === "") return fallback;
+  return !/^(?:0|false|off|no)$/i.test(String(value).trim());
+}
+
+function providerErrorText(error) {
+  return [
+    error?.code,
+    error?.type,
+    error?.message,
+    error?.error?.code,
+    error?.error?.type,
+    error?.error?.message,
+    error?.response?.data?.error?.code,
+    error?.response?.data?.error?.type,
+    error?.response?.data?.error?.message,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+export function classifyProviderHandoffError(error) {
+  const status = Number(error?.status || error?.response?.status || 0);
+  const code = String(error?.code || "").trim().toUpperCase();
+  const text = providerErrorText(error);
+
+  if (
+    status === 402 ||
+    /insufficient[_ -]?(?:quota|balance)|quota exceeded|billing|account balance|credits? exhausted/.test(text)
+  ) {
+    return { eligible: true, code: "provider_quota", status };
+  }
+  if (
+    code === "API_KEY_REQUIRED" ||
+    status === 401 ||
+    status === 403 ||
+    /authentication|unauthorized|invalid[_ -]?api[_ -]?key|permission denied/.test(text)
+  ) {
+    return { eligible: true, code: "provider_auth", status };
+  }
+  if (status === 429 || /rate[_ -]?limit|too many requests/.test(text)) {
+    return { eligible: true, code: "provider_rate_limited", status };
+  }
+  if (
+    status === 404 &&
+    /model|deployment|endpoint|not found|does not exist|unavailable/.test(text)
+  ) {
+    return { eligible: true, code: "provider_model_unavailable", status };
+  }
+  if (
+    status === 408 ||
+    status === 503 ||
+    status === 529 ||
+    status >= 500 ||
+    NETWORK_ERROR_CODES.has(code) ||
+    /overload|overloaded|capacity|temporarily unavailable|connection refused|network unreachable/.test(text)
+  ) {
+    return { eligible: true, code: "provider_unavailable", status };
+  }
+  return { eligible: false, code: "provider_request_failed", status };
+}
+
+export function resolveProviderHandoff(error, config = {}, { stage = "runtime" } = {}) {
+  const sourceProvider = normalizeProviderId(config.provider, "");
+  const targetProvider = normalizeProviderId(
+    config.providerHandoffProvider || process.env.AGINTI_PROVIDER_HANDOFF_PROVIDER || "localllm",
+    ""
+  );
+  if (!enabled(config.allowProviderHandoff ?? process.env.AGINTI_PROVIDER_HANDOFF, true)) return null;
+  if (!sourceProvider || sourceProvider === "mock" || sourceProvider === "localllm") return null;
+  if (!targetProvider || targetProvider !== "localllm" || targetProvider === sourceProvider) return null;
+  if (String(config.routingMode || "smart").trim().toLowerCase() === "manual") return null;
+  if (String(config.integrationSessionProfile || "").trim()) return null;
+  if (stage !== "preflight" && error?.agintiProviderRequest !== true) return null;
+
+  const failure = classifyProviderHandoffError(error);
+  if (!failure.eligible) return null;
+
+  const routeModel =
+    String(config.providerHandoffRouteModel || process.env.AGINTI_LOCALLLM_ROUTE_MODEL || "").trim() ||
+    LOCALLLM_MODEL_TIERS.fast.model;
+  const mainModel =
+    String(
+      config.providerHandoffModel ||
+        process.env.AGINTI_PROVIDER_HANDOFF_MODEL ||
+        process.env.AGINTI_LOCALLLM_MAIN_MODEL ||
+        ""
+    ).trim() || LOCALLLM_MODEL_TIERS.deep.model;
+
+  return {
+    version: 1,
+    sourceProvider,
+    sourceModel: String(config.model || ""),
+    targetProvider,
+    targetModel: mainModel,
+    routeModel,
+    mainModel,
+    spareModel: mainModel,
+    failureCode: failure.code,
+    status: failure.status,
+    runtimePatch: {
+      provider: targetProvider,
+      model: mainModel,
+      routingMode: "manual",
+      routeProvider: targetProvider,
+      routeModel,
+      mainProvider: targetProvider,
+      mainModel,
+      spareProvider: targetProvider,
+      spareModel: mainModel,
+    },
+  };
+}

package/src/scs-evidence.js

@@ -980,9 +980,9 @@ function prefixRequestsInlineCommandExecution(prefix = "") {
   while (preamble.test(clause)) clause = clause.replace(preamble, "").trim();
   clause = clause.replace(/(?:[:：]|--?)\s*$/, "").trim();
   return (
-    /^(?:run|execute|invoke|launch)(?:\s+(?:(?:the|this|that)\s+)?(?:following\s+)?command(?:\s+named)?)?\s*$/i.test(
+    /^(?:run|rerun|re-run|execute|invoke|launch|verify|validate|check|confirm)(?:\s+(?:(?:the|this|that)\s+)?(?:following\s+)?command(?:\s+named)?)?\s*$/i.test(
       clause
-    ) || /^(?:运行|運行|执行|執行|调用|調用)\s*$/.test(clause)
+    ) || /^(?:运行|運行|执行|執行|调用|調用|验证|驗證|检查|檢查|确认|確認)\s*$/.test(clause)
   );
 }
 
@@ -1239,9 +1239,19 @@ export function augmentScsTaskContractWithProjectVerification(contract = {}, sta
     ...verificationRequiredProjectCommands,
   ].map(normalizeProjectCommand).filter(Boolean)).slice(0, 24);
   const requiredCommandBatch = verification.requiredCommandBatch;
+  const batchRequiredCommands = unique(
+    (Array.isArray(requiredCommandBatch?.requiredCommands)
+      ? requiredCommandBatch.requiredCommands
+      : requiredCommandBatch?.key === JSON.stringify(requiredProjectCommands)
+        ? requiredProjectCommands
+        : [])
+      .map(normalizeProjectCommand)
+      .filter((command) => command && requiredProjectCommands.includes(command))
+  );
   const requiredProjectCommandBatchId =
     requiredCommandBatch &&
-    requiredCommandBatch.key === JSON.stringify(requiredProjectCommands) &&
+    batchRequiredCommands.length > 0 &&
+    requiredCommandBatch.key === JSON.stringify(batchRequiredCommands) &&
     requiredCommandBatch.id
       ? String(requiredCommandBatch.id)
       : "";
@@ -1286,7 +1296,7 @@ export function augmentScsTaskContractWithProjectVerification(contract = {}, sta
     requiredProjectCommands,
     requiredProjectCommandBatchId,
     requiredProjectCommandBatchCommands: requiredProjectCommandBatchId
-      ? requiredProjectCommands
+      ? batchRequiredCommands
       : [],
     requiredProjectCommandRuns,
     projectMutationRevision: mutationRevision,