What Problem This Solves

Fixes #90766.

After long gateway downtime, restart-aborted subagent runs with abortedLastRun: true were exempt from the stale-unended pruning that every other stale run goes through. As a result, very old aborted child sessions (hours past the 2h stale window) were resurrected by orphan recovery and sent a synthetic resume message — producing late, meaningless recovery output for work that was abandoned long ago.

Two gaps in current main:

1. resolveSubagentRunOrphanReason skips stale-unended-run classification when abortedLastRun === true (src/agents/subagent-registry-helpers.ts:192).
2. recoverOrphanedSubagentSessions checks abortedLastRun then goes straight to evaluateSubagentRecoveryGate without applying isStaleUnendedSubagentRun, and fire-and-forget finalization can leave stale runs unended with no scheduler retry (src/agents/subagent-orphan-recovery.ts:251).

Why This Change Was Made

The stale-run liveness policy (isStaleUnendedSubagentRun) already encodes the cutoff beyond which an unended run is not worth recovering. The abortedLastRun exemption was a special case that bypassed this policy at two boundaries (registry restore and orphan recovery), creating a path where stale aborted runs could be resurrected indefinitely across restarts.

This PR removes the exemption and reuses the existing liveness helper at both boundaries:

• subagent-registry-helpers.ts: Drop the abortedLastRun !== true condition from resolveSubagentRunOrphanReason so stale aborted runs are classified as stale-unended-run like any other stale run.
• subagent-orphan-recovery.ts: Evaluate a frozen stale-first scan snapshot before recovery. Stale aborted runs are finalized via the exact run ID, and failed terminal transitions remain generation-scoped across bounded scheduler retries. Fresh aborted successors still pass through normal recovery.
• Registry lifecycle: Persist an explicit interrupted-recovery terminal owner before task projection, arbitrate late provider/kill/yield callbacks through the existing completion lock, and preserve partial or conflicting terminal evidence. If restart admission is already draining, defer and replay only the matching exact terminal transition after admission reopens.
• Persistence restore: Preserve valid interrupted-recovery ownership and normalize matching flat/nested terminal evidence so cleanup and delivery can resume after process loss.
• docs/tools/subagents.md: Update the restart-recovery contract so docs match the runtime.
• Tests: Cover stale/fresh same-session generations, persistence rollback and replay, restart-drain deferral, partial/conflicting terminal winners, bounded retry, and a faithful restart-path integration test driving the real registry + real session store + real liveness policy.

User Impact

• Stale aborted subagent runs older than the 2h stale window are finalized (terminal error outcome) instead of being resumed after gateway restart. Parents no longer see late, meaningless recovery output for abandoned child work.
• Fresh aborted runs (within the stale window) are unchanged — they still resume through orphan recovery as today.
• Persisted restart-aborted rows older than the stale window will be pruned/finalized on the first restart after upgrade. This is a one-time transition in recovery semantics for old state; no config or migration is required.

Evidence

Maintainer proof targets public head 3e199d7d3909033a9aa2afc58c22ed9111ab8112.

Blacksmith Testbox focused run:

pnpm test \
  src/agents/subagent-delivery-state.test.ts \
  src/agents/subagent-orphan-recovery.test.ts \
  src/agents/subagent-orphan-recovery.restart-integration.test.ts \
  src/agents/subagent-registry-lifecycle.test.ts \
  src/agents/subagent-registry.persistence.test.ts \
  src/agents/subagent-registry.store.sqlite.test.ts \
  src/agents/subagent-registry.test.ts

Result: 7 files / 261 tests pass. Exact-head targeted Oxlint also passes with 0 warnings and 0 errors under all 242 rules. A near-final check:changed run passed dependency guards, core and core-test typechecks, and all core lint shards after its sole sort() finding was changed to toSorted() and re-proved at the final head.

Blacksmith lease evidence: https://github.com/openclaw/openclaw/actions/runs/29120499066

The restart-path integration test (subagent-orphan-recovery.restart-integration.test.ts) drives the real recoverOrphanedSubagentSessions against the real subagent registry, real isStaleUnendedSubagentRun policy, and a real on-disk session store. Only the outbound gateway WebSocket (callGateway) and transcript reader (readSessionMessagesAsync) are mocked — the genuine process boundaries a single-process test cannot stand up.

Captured logs:

[proof] before recovery: stale run endedAt=undefined outcome=undefined
[proof] after recovery: result={"recovered":0,"failed":0,"skipped":1,"failedRuns":[]} endedAt=<timestamp> outcome=error
[subagent-interrupted-resume] found orphaned subagent session: agent:main:subagent:fresh-aborted (run=run-fresh-aborted)
[subagent-interrupted-resume] resumed orphaned session: agent:main:subagent:fresh-aborted
[subagent-interrupted-resume] orphan recovery complete: recovered=1 failed=0 skipped=0
[proof] fresh recovery: result={"recovered":1,"failed":0,"skipped":0,"failedRuns":[]} gatewayCalls=2

The stale aborted run (startedAt 3h ago) is finalized in the real registry — endedAt goes from undefined to a real timestamp, outcome=error — and is never resumed (no gateway agent call). The fresh aborted run (55s old) passes the stale gate and resumes normally (recovered=1).

Disclosed seams: outbound gateway WebSocket and transcript reader are mocked; the clock is seeded via run timestamps. A literal multi-hour live-gateway downtime is not exercised (the stale window is 2h), but every decision boundary — restore pruning, stale finalization, and fresh resume — runs through production code.

Source-blind validation did not substitute a weaker scenario: supported public surfaces cannot seed stale and fresh registered generations on one exact child session while controlling predecessor age and restart-aborted state. The faithful integration test is therefore the executable proof for that topology.

Fixes: #90766