Summary

• Problem: Telegram isolated ingress could keep a fresh-looking .json.processing claim from a previous gateway identity when the PID was reused after recreate, blocking later same-lane updates.
• Solution: Treat claims whose stored processPid equals the current process but whose unique processId differs as recoverable stale claims, not another live owner.
• What changed: Updated Telegram spool ownership detection and regression tests for startup/drain recovery of restart-stale claims.
• What did NOT change (scope boundary): No changes to Telegram delivery, handler timeout tombstoning, or cross-process live-claim protection for different live PIDs.

Motivation

• Fixes a released Docker failure mode where a stale Telegram .processing file can survive gateway recreate and block later updates until manually moved aside.

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 Telegram isolated ingress spool can remain blocked by stale .processing claim after gateway recreate #84674
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: stale Telegram isolated-ingress .json.processing claim from an older gateway identity with the current PID no longer blocks later queued updates.
• Real environment tested: local Linux checkout, Node v22.19.0, Telegram plugin spool/session tests.
• Exact steps or command run after this patch: node scripts/run-vitest.mjs extensions/telegram/src/telegram-ingress-spool.test.ts extensions/telegram/src/polling-session.test.ts
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

  ✓  extension-telegram  ../../extensions/telegram/src/polling-session.test.ts (42 tests) 9850ms
  ✓  extension-telegram  ../../extensions/telegram/src/telegram-ingress-spool.test.ts (7 tests) 14ms
  
  Test Files  2 passed (2)
       Tests  49 passed (49)
  

• Observed result after fix: restart-stale current-PID/different-process-id claims are recovered back to pending updates, and focused Telegram spool/session tests pass.
• What was not tested: live Docker/Telegram replay against a real bot.
• Before evidence (optional but encouraged): existing regression test preserved the .processing file and left only the later update pending.

Root Cause (if applicable)

• Root cause: live-claim detection considered any fresh claim with an existing PID to be owned by another live process, even when that PID was the current gateway process and the unique process id differed from the current gateway identity.
• Missing detection / guardrail: no regression test covered gateway recreate / PID reuse where processPid === process.pid but processId belongs to an older gateway instance.
• Contributing context (if known): isolated ingress drain uses this live-owner predicate before deciding whether to recover stale claims.

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: extensions/telegram/src/telegram-ingress-spool.test.ts, extensions/telegram/src/polling-session.test.ts
• Scenario the test should lock in: a .json.processing claim with the current PID but an older/different process identity is recoverable and returns the blocked update to the pending spool.
• Why this is the smallest reliable guardrail: it exercises the exact plugin-local ownership predicate and drain recovery gate without needing live Telegram.
• Existing test that already covers this (if any): N/A; existing coverage asserted the old blocking behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Telegram isolated polling ingress can recover stale .processing claims left behind by a recreated gateway when the PID is reused, preventing later updates from staying blocked indefinitely.

Diagram (if applicable)

Before:
old gateway claim (.processing, pid=current, processId=old) -> treated live-owned -> later .json updates stay blocked

After:
old gateway claim (.processing, pid=current, processId=old) -> recovered to .json -> drain can process queued updates

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: Linux kvm16007 6.1.0-44-amd64 x86_64
• Runtime/container: local source checkout, Node v22.19.0
• Model/provider: N/A
• Integration/channel (if any): Telegram isolated ingress spool
• Relevant config (redacted): N/A

Steps

1. Create a Telegram spool with update 42 claimed as .json.processing using processPid: process.pid and a different processId.
2. Queue update 43 on the same lane.
3. Run stale-claim recovery with the same live-owner gate used by isolated ingress drain.

Expected

• Update 42 is recovered back to .json; updates 42 and 43 are pending in order.

Actual

• After this patch, the focused regression test observes updates 42 and 43 pending and no lingering .json.processing file.

Evidence

Attach at least one:

• 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: focused Telegram spool/session regression tests pass; git diff --check passes.
• Edge cases checked: existing stale-timeout recovery and handler/session tests still pass in the same focused run.
• What you did not verify: live Docker/Telegram bot replay.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: accidentally replaying work still owned by a live second gateway.
  • Mitigation: the predicate only treats the current PID plus different process identity as restart-stale; different fresh live PIDs are still protected by the existing process-existence check.