Summary

• Problem: After a gateway restart with long downtime, stale subagent runs with abortedLastRun: true are treated as resumable by orphan recovery even when they are hours past the staleness window. This can resurrect contextless child work long after the original run should have been retired.
• Root Cause: Two gaps — (1) recoverOrphanedSubagentSessions checks abortedLastRun and the recovery gate (re-wedge window) but never checks run age; (2) resolveSubagentRunOrphanReason used in restore reconciliation exempts abortedLastRun: true entries from the stale-unended pruning branch (sessionEntry.abortedLastRun !== true guard on line 193), so stale aborted runs survive registry init and proceed to orphan recovery.
• Fix:
  • Add isStaleUnendedSubagentRun check in recoverOrphanedSubagentSessions after the abortedLastRun gate, before evaluateSubagentRecoveryGate — stale runs are skipped and reported as stale-unended-run.
  • Remove the abortedLastRun !== true exemption from resolveSubagentRunOrphanReason so restore reconciliation prunes stale runs regardless of abortedLastRun. Fresh aborted runs (under the 2-hour staleness window) are NOT stale and still proceed to orphan recovery as before.
• What changed:
  • src/agents/subagent-orphan-recovery.ts — import isStaleUnendedSubagentRun, add age-out guard before recovery gate
  • src/agents/subagent-registry-helpers.ts — remove abortedLastRun exemption from stale-unended restore pruning
  • src/agents/subagent-registry.persistence.test.ts — replaces the "keeps stale aborted runs for restart recovery" test with a "retires stale aborted runs past the staleness window" test
• What did NOT change (scope boundary):
  • evaluateSubagentRecoveryGate / subagent-recovery-state.ts — recovery gate unchanged; it handles re-wedge bounding, not staleness
  • Doc files (docs/tools/subagents.md) — out of scope; docs describe behavior at a higher level
  • Fresh restart recovery — runs under the 2-hour STALE_UNENDED_SUBAGENT_RUN_MS cutoff still proceed to orphan recovery unchanged

Reproduction

1. Start a subagent run that writes normal recovery metadata
2. Leave it unresolved across downtime longer than the staleness window (default 2 hours)
3. Restart the gateway
4. Before this PR: The stale aborted run is classified as recoverable and agent.wait is called to resume it
5. After this PR: The stale aborted run is skipped during orphan recovery and pruned from the registry as stale-unended-run

Real behavior proof

Behavior or issue addressed (90766): Orphan recovery and restore reconciliation now age out stale aborted subagent runs past the STALE_UNENDED_SUBAGENT_RUN_MS (2-hour) staleness window, instead of resurrecting them as restart-recoverable.

Real environment tested: Linux, Node 22 — test runner against subagent orphan recovery, registry persistence, and registry queries

Exact steps or command run after this patch: node scripts/run-vitest.mjs src/agents/subagent-orphan-recovery.test.ts src/agents/subagent-registry.persistence.test.ts src/agents/subagent-registry-queries.test.ts

Evidence after fix:

[test] starting test/vitest/vitest.unit-fast.config.ts
 RUN  v4.1.7 /home/0668001395/openclawProject1
 Test Files  1 passed (1)
      Tests  16 passed (16)

[test] starting test/vitest/vitest.agents.config.ts
 RUN  v4.1.7 /home/0668001395/openclawProject1
 Test Files  2 passed (2)
      Tests  37 passed (37)

[test] passed 2 Vitest shards

Observed result after fix: The orphan recovery suite (16 tests including stale-skip coverage) and the persistence/queries suites (37 tests including the new "retires stale aborted restored runs past the staleness window" regression) all complete successfully. The before test on origin/main passes the old "keeps stale aborted runs for restart recovery" behavior (3-hour-old abortedLastRun run stays recoverable), confirming the gap existed; the after test confirms those stale aborted runs are now retired and pruned.

What was not tested: Live gateway restart with a real subagent run that spans multi-hour downtime and gate-level run-age cutoff. Systemd service stop/start cycle with a stale orphan.

Repro confirmation: The existing test on origin/main (subagent-registry.persistence.test.ts line ~727, "keeps stale unended restored runs with abortedLastRun for restart recovery") seeds a 3-hour-old restored run with abortedLastRun: true and expects callGateway to run agent.wait — confirming main treats the stale run as recoverable. After the patch, the replacement test seeds a 3-hour-old abortedLastRun run and confirms it is pruned from the registry (no callGateway call, no announce). All other tests unchanged.

Risk / Mitigation

• Risk: A careless age guard could break legitimate fresh restart recovery for recent abortedLastRun runs.
  Mitigation: isStaleUnendedSubagentRun uses the existing STALE_UNENDED_SUBAGENT_RUN_MS (2-hour) cutoff with resolveStaleCutoffMs respecting explicit runTimeoutSeconds. Freshly restarted runs under the cutoff are NOT stale and proceed to orphan recovery unchanged.
• Risk: Removing the abortedLastRun exemption from restore reconciliation could prematurely prune runs that should stay visible.
  Mitigation: The isStaleUnendedSubagentRun guard is unchanged — it only fires when the run is past the staleness window. Runs under the window are not stale and stay in the registry regardless of abortedLastRun.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• agents
• subagent-registry
• orphan-recovery

Regression Test Plan

• node scripts/run-vitest.mjs src/agents/subagent-orphan-recovery.test.ts
• node scripts/run-vitest.mjs src/agents/subagent-registry.persistence.test.ts
• node scripts/run-vitest.mjs src/agents/subagent-registry-queries.test.ts

Review Findings Addressed

N/A (initial submission)

Linked Issue/PR

Fixes #90766