Summary

Fixes #15177. After a SIGUSR1 in-process restart, the gateway can enter a zombie state where:

1. Heartbeat scheduler blocks permanently — the module-level running flag in heartbeat-wake.ts stays true when an in-flight heartbeat is interrupted, blocking all future schedule() attempts.
2. Message lanes block permanently — active counters in command-queue.ts stay elevated from interrupted tasks, blocking all message dequeuing.

Approach

Generation-based lane reset (addresses Greptile review)

Previous version used resetAllLanes() which zeroed counters and immediately called drainLane(). This violated concurrency invariants: if old tasks were still executing, new tasks could start alongside them, breaking main-lane serialization.

New approach: Each lane has a generation counter. When resetAllLanes() fires:

• Generation increments per lane
• Active counters reset to 0
• No immediate drain — new work resumes naturally on next enqueueCommandInLane()

When old tasks' finally blocks run, completeTask() checks generation — stale tasks are no-ops. This preserves concurrency invariants at all times.

Heartbeat wake handler improvements

• setHeartbeatWakeHandler() now returns a generation-scoped disposer — stale disposers from previous registrations can't clear a newer handler (fixes the ownership race)
• Clears stale timer metadata (retry cooldowns) when registering a new handler
• Resets running/scheduled flags on new registration
• Priority-based wake reason queueing (action > default > interval > retry)
• Timer preemption: sooner requests preempt later ones, but retry cooldowns are preserved

Orphan recovery script

scripts/recover-orphaned-processes.sh scans for coding agent processes (Claude Code, Codex) that outlived their session. Output: JSON object with orphaned array and ts timestamp.

Test plan

• 21 tests (10 command-queue, 11 heartbeat-wake), all passing
• Tests cover: generation mismatch, stale disposer no-op, timer preemption, retry cooldown preservation, active task counting, drain-after-reset flow

Files changed

• src/process/command-queue.ts — generation-based lane reset, completeTask(), resetAllLanes(), getActiveTaskCount(), waitForActiveTasks()
• src/infra/heartbeat-wake.ts — generation-scoped disposer, priority wake reasons, timer preemption
• src/process/command-queue.test.ts — 6 new tests
• src/infra/heartbeat-wake.test.ts — 11 new tests (new file)
• scripts/recover-orphaned-processes.sh — orphan scanner (new file)

Greptile Overview

Greptile Summary

This change hardens SIGUSR1 in-process restarts by resetting stale runtime state that can otherwise block progress after an interrupted lifecycle.

• src/process/command-queue.ts replaces the separate active counter with a generation + activeTaskIds.size model, and adds resetAllLanes() to bump generations, clear stale in-flight bookkeeping, and immediately drain preserved queued work.
• Restart coordinators (src/cli/gateway-cli/run-loop.ts, src/macos/gateway-daemon.ts) now call resetAllLanes() only on restart iterations (not initial boot).
• src/infra/heartbeat-wake.ts makes handler disposal generation-scoped, resets stale timer/execution flags when registering a new handler, and refines wake coalescing/priorities/timer preemption.
• Adds tests for the above behaviors and introduces scripts/recover-orphaned-processes.sh to report likely orphaned agent processes as JSON.

No new merge-blocking issues were found in the current diff based on the reviewed code paths.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk.
• Changes are narrowly scoped to restart recovery and wake scheduling, with state reset gated to restart iterations, generation-based stale-task handling in the command queue, and extensive new unit coverage for the new semantics.
• No files require special attention

_{Last reviewed commit: d62a97a}