Summary

• Problem: overflow recovery had edge paths that could finalize with no renderable payload (undefined/empty outcome) when meta.error was context_overflow.
• Why it matters: this creates silent/non-actionable behavior in a high-friction reliability path.
• What changed:
  • Added deterministic overflow fallback when embedded overflow meta-error returns zero payloads.
  • Added deterministic overflow fallback when payloads normalize/filter to empty in runReplyAgent.
  • Added two regressions covering both paths.
• What did NOT change (scope boundary): no config/schema changes, no provider selection logic changes, no broad compaction refactor.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 [Bug]: Context-overflow recovery can finalize empty instead of deterministic fallback #19550
• Related fix: return user-facing error when session reset after compaction failure #1187
• Related Context overflow after failed compaction should trigger fallback failover #18095
• Related fix: improve context overflow error messages and docs #18997
• Related fix: improve context overflow error with diagnostic details #15749
• Related feat: progressive compaction escalation and mechanical flush fallback #18663
• Related [Bug] Telegram receives 'Context overflow' errors while dashboard shows correct responses #18719

User-visible / Behavior Changes

• Overflow edge paths now return a deterministic fallback response instead of potentially finalizing with an empty/undefined payload.

Security Impact (required)

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

Repro + Verification

Environment

• OS: Ubuntu 25.10
• Runtime/container: local source checkout
• Model/provider: N/A (runner behavior)
• Integration/channel (if any): reply-agent execution path
• Relevant config (redacted): defaults

Steps

1. Return meta.error.kind = context_overflow with payloads: [] and unavailable session reset context.
2. Return overflow error payload that normalizes/filters to empty.
3. Observe finalization behavior.

Expected

• Deterministic fallback payload is returned in both edge paths.

Actual

• Before fix: empty/undefined-style finalization possible.
• After fix: explicit overflow fallback response returned.

Evidence

Attach at least one:

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

Regression tests added:

• returns a deterministic overflow fallback when error meta has no payloads
• returns a deterministic overflow fallback when error payload normalizes to empty

Human Verification (required)

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

• Verified scenarios:
  • pnpm vitest run src/auto-reply/reply/agent-runner.runreplyagent.test.ts passed (25 tests).
  • pnpm test passed.
  • pnpm build passed.
• Edge cases checked:
  • existing compaction-reset and role-ordering tests still pass.
• What you did not verify:
  • exhaustive channel-by-channel delivery matrix.

Note: pnpm check reports pre-existing repository-wide formatting issues (Format issues found in above 1121 files) unrelated to this PR's touched files.

Compatibility / Migration

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

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Revert this PR commit.
• Files/config to restore:
  • src/auto-reply/reply/agent-runner-execution.ts
  • src/auto-reply/reply/agent-runner.ts
  • src/auto-reply/reply/agent-runner.runreplyagent.test.ts
• Known bad symptoms reviewers should watch for:
  • reappearance of empty/undefined finalization behavior on overflow edge paths.

Risks and Mitigations

• Risk: fallback could trigger in cases where empty payload was intentional.
  • Mitigation: fallback is restricted to explicit overflow/compaction error kinds.
• Risk: overlap with adjacent overflow/compaction work.
  • Mitigation: keep patch narrowly scoped and link related issues/PRs.

AI assistance

• AI-assisted: Yes (author verified code paths, tests, and scope).