Summary

• Problem: when openclaw agent hit the gateway final-response timeout, embedded fallback reused the same session/run id while the gateway could still hold the session lock.
• Why it matters: the fallback could immediately fail with session file locked, then cascade through model fallbacks.
• What changed: gateway timeout fallbacks now run the embedded agent under a fresh fallback session/run id while preserving normal embedded fallback behavior for non-timeout gateway failures.
• What did NOT change (scope boundary): no gateway protocol, session-store format, or non-timeout fallback behavior changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes session file locked when gateway times out and falls back to embedded runner #62981
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: agentCliCommand() reused the original local options after a gateway timeout, so embedded fallback inherited the same session id/run id as the still-running gateway agent path.
• Missing detection / guardrail: there was no regression test distinguishing gateway timeout fallback from other gateway connection failures.
• Contributing context (if known): the gateway agent RPC can acknowledge a run and continue working after the CLI-side final response timeout expires.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/commands/agent-via-gateway.test.ts
• Scenario the test should lock in: gateway timeout fallback invokes embedded agent with a fresh gateway-fallback-* session/run id instead of the locked original values.
• Why this is the smallest reliable guardrail: the bug is in CLI fallback option construction after callGateway() rejects.
• Existing test that already covers this (if any): existing fallback tests covered generic gateway failures, not timeout lock isolation.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Gateway timeout fallback still attempts embedded execution, but the embedded run uses a fresh fallback session/run id to avoid racing the gateway-held session lock.

Diagram (if applicable)

Before:
[gateway timeout] -> [embedded fallback with same session id] -> [session lock failure]

After:
[gateway timeout] -> [embedded fallback with fresh session id] -> [fallback can acquire its own transcript]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Windows local checkout
• Runtime/container: Node 22 via repo scripts
• Model/provider: mocked tests
• Integration/channel (if any): Gateway CLI fallback path
• Relevant config (redacted): default test config

Steps

1. Mock callGateway() to reject with a typed gateway timeout.
2. Run agentCliCommand() with an existing sessionId and runId.
3. Assert embedded fallback receives a fresh gateway-fallback-* session/run id.

Expected

• Embedded fallback does not reuse the gateway-locked session/run id.

Actual

• Fixed by this PR.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test src/commands/agent-via-gateway.test.ts -t "uses a fresh embedded session when gateway agent times out" -- --reporter=verbose
  • pnpm test src/commands/agent-via-gateway.test.ts -- --reporter=verbose
  • pnpm test src/commands/agent-via-gateway.test.ts src/gateway/call.test.ts src/agents/run-wait.test.ts -- --reporter=verbose
  • pnpm check:changed
  • pnpm test:changed
• Edge cases checked: generic gateway failure fallback still uses the existing path; timeout fallback overrides both sessionId and runId.
• What you did not verify: live gateway/model timeout against a real provider.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: timeout fallback starts a new transcript instead of continuing the original session context.
  • Mitigation: this only applies after gateway timeout, where the original session may still be locked by the gateway run; non-timeout fallback behavior is unchanged.