Update 2026-06-02: addressed ClawSweeper P1 findings on cd6056478b:

• Dropped the CHANGELOG.md hunk (release-owned per root AGENTS.md rules).
• Reworked subagent-orphan-recovery.ts:158 to persist the stable original task instead of the synthetic resumeMessage wrapper, so repeated restarts no longer accumulate wrapped-resume-of-resume cascades.
• Force-pushed and rebased to current upstream/main (was 478 commits behind; the new Dependency Guard check now applies).
• Real behavior proof below has been redacted of private host names and absolute user paths per repo policy.

Summary

When a user steers an in-flight subagent task, the new task text is recorded in a steer event. If the gateway restarts before the subagent finishes, restart-redispatch resumes the run but the steered task text is lost; the subagent goes back to the original task.

This adds an optional task?: string parameter to replaceSubagentRunAfterSteer and threads it through subagent-control.ts, subagent-announce.ts, and subagent-orphan-recovery.ts. Backwards-compatible: omitted callers preserve the previous task.

Repro

1. Start a subagent task ("draft a long blog post about X").
2. Steer it ("focus only on the introduction").
3. Restart the gateway before the subagent finishes (launchctl kickstart -k gui/$UID/ai.openclaw.gateway on macOS, equivalent on systemd).
4. Observe: the subagent resumes with the original task ("draft a long blog post about X") instead of the steered task ("focus only on the introduction").

Test plan

• node scripts/run-vitest.mjs run src/agents/subagent-registry.steer-restart.test.ts src/agents/subagent-orphan-recovery.test.ts src/agents/subagent-control.test.ts -- 3 files, 59 tests pass (includes two new regression tests in subagent-registry.steer-restart.test.ts).
• node scripts/run-oxlint-shards.mjs --only=core --threads=4 clean.
• pnpm build clean.
• Backwards-compatible: existing call sites that omit task preserve the previous task field; new call sites pass the steered/wake/resume message explicitly.

Thanks @amittell.

Real behavior proof

• Behavior addressed: Before this PR, when a user steered an in-flight subagent task, the new task text was recorded in the steer event but discarded by restart-redispatch; the resumed subagent went back to its original task. After this PR, replaceSubagentRunAfterSteer accepts a task?: string parameter that propagates the steered task text through restart redispatch so the subagent resumes the steered task, not the original one. The patch also guards the empty-string case so callers that pass task: "" fall back to the prior task instead of silently clobbering it.
• Real environment tested: live OpenClaw gateway on gateway-host, pid (live gateway, redacted), build SHA (deployment fork checkout, redacted). The deployed bundle at ~/.openclaw/openclaw/dist/subagent-registry-CCMhICN7.js contains the patched line const nextTask = typeof replaceParams.task === "string" && replaceParams.task.length > 0 ? replaceParams.task : source.task; at line 1468. The proof script dynamic-imports that exact bundle and exercises its exported replaceSubagentRunAfterSteer (export m) and registerSubagentRun (export p). State is isolated via OPENCLAW_STATE_DIR redirected to a fresh tmpdir so the live gateway's runs.json is not touched.
• Exact steps or command run after this patch:

  scp /tmp/proof-77539-amittell.mjs user@gateway-host:/tmp/proof-77539-amittell.mjs
  ssh user@gateway-host 'cd ~/.openclaw/openclaw && /opt/homebrew/bin/node /tmp/proof-77539-amittell.mjs'

  The script registers a synthetic subagent run with task: "do A: investigate widget metrics for last 24h", then exercises four scenarios against the live deployed bundle:
  1. Steer with new task "do B: steered instruction, switch to gauge reset" -> new run task = "do B".
  2. Steer without task param -> new run task preserves "do A" (back-compat).
  3. Steer with task: "" -> new run task preserves "do A" (empty-string fallback).
  4. Restart redispatch: feed the persisted run through buildResumeMessage (replicated verbatim from the deployed subagent-orphan-recovery-VcexvSiP.js lines 51-58) -> resume message wraps "do B", not "do A".
• Evidence after fix:

  [PASS] steer-with-new-task replaces stored task -- replaced=true task="do B: steered instruction, switch to gauge reset"
  [PASS] no-task param preserves prior task -- replaced=true task="do A: investigate widget metrics for last 24h"
  [PASS] empty-string task falls back to prior task -- replaced=true task="do A: investigate widget metrics for last 24h"
  [PASS] restart-redispatch resume message wraps steered text, not stale task -- wrapsSteered=true dropsStale=true
  ---SUMMARY---
  {
    "scenarios": [
      { "name": "steer-with-new-task replaces stored task", "ok": true },
      { "name": "no-task param preserves prior task", "ok": true },
      { "name": "empty-string task falls back to prior task", "ok": true },
      { "name": "restart-redispatch resume message wraps steered text, not stale task", "ok": true }
    ],
    "failures": 0
  }
  RBP=pass (4 of 4 scenarios passed)
  

  Post-run sanity check confirms the live gateway's ~/.openclaw/subagents/runs.json was not touched: total runs: 0, proof-77539 keys: [].
• Observed result after fix: On the live OpenClaw gateway at gateway-host, the deployed replaceSubagentRunAfterSteer honors the caller-supplied task param and falls back to the prior task for the no-arg and empty-string cases. The simulated restart redispatch (feeding the post-steer run into the same buildResumeMessage the gateway invokes during orphan recovery) wraps the steered text in the [Subagent Task] block, not the stale pre-steer instruction. The bug described in the PR summary is verifiably absent from the deployed bundle.
• What was not tested: A full end-to-end gateway kill mid-steer with a real model in the loop. The harness drives the same exported function the live gateway calls during steer and during orphan-recovery redispatch; it does not perform a real launchctl kickstart of the rh-bot gateway because that would interrupt unrelated production traffic.

Real behavior proof addendum: completed-session reactivation (2026-06-12)

Covers the path added in 1607b5e8fe (now squashed into head 50eefdf243): sessions.send / agent.run follow-ups to a completed subagent session.

• Behavior addressed: when a user sends a follow-up to a subagent session whose run already ended, sessions.send (src/gateway/server-methods/sessions.ts:913) calls reactivateCompletedSubagentSession with the follow-up message text. Before this head, the replacement run kept the stale original task, so a gateway restart redispatched the old prompt. After, the follow-up text is persisted as the replacement run's task and restart redispatch rewraps it.

• Real environment tested: exact-head runtime bundle built locally from 50eefdf243 (pnpm build, macOS 26.5.1, node v26.3.0). The proof script dynamic-imports the built chunks directly -- session-subagent-reactivation-BiDNNsJe.js (export t = reactivateCompletedSubagentSession) and subagent-registry-D8kvjzdz.js (exports h/s/m = registerSubagentRun / getLatestSubagentRunByChildSessionKey / markSubagentRunTerminated) -- sharing the real in-memory registry module. State isolated via OPENCLAW_STATE_DIR redirected to a fresh tmpdir; no live gateway state touched. Same bundle-driving methodology as the accepted proof above.

• Exact steps or command run after this patch:

  git checkout 50eefdf243 && pnpm build
  node /tmp/proof-77539-reactivation.mjs <checkout>/dist

  The script: (1) registers a run with task "do A: investigate widget metrics for last 24h" and drives it to ended state; (2) reactivates via the sessions.send path with follow-up "do B: follow-up, re-run the gauge reset against staging"; (3) feeds the replacement run through buildResumeMessage replicated verbatim from dist/subagent-orphan-recovery-CE6Tpah5.js:51-58; (4) asserts active (non-ended) runs are never replaced; (5) asserts whitespace-only follow-up preserves the prior task.

• Evidence after fix:

  [PASS] ended run record retained with original task -- runId=run-original-1 endedAt=<ts> task="do A: investigate widget metrics for last 24h"
  [PASS] reactivation replaces ended run and persists follow-up text as task -- reactivated=true runId=run-followup-1 task="do B: follow-up, re-run the gauge reset against staging"
  [PASS] restart-redispatch resume message wraps follow-up text, not stale original -- wrapsFollowup=true dropsStale=true
  [PASS] active run is not replaced by completed-session reactivation -- reactivated=false runId=run-active-1 task="active task"
  [PASS] whitespace-only follow-up preserves prior task text -- reactivated=true runId=run-followup-3 task="do B: follow-up, re-run the gauge reset against staging"
  ---SUMMARY--- failures: 0
  

• Observed result after fix: the replacement run record persists the follow-up text as task (scenario 2), restart-redispatch orphan recovery rewraps the follow-up rather than the stale original (scenario 3), the path refuses to touch active runs (scenario 4), and the empty/whitespace fallback contract from the original proof holds on this sibling path too (scenario 5).

• What was not tested: a full live-gateway restart cycle (SIGUSR1 + orphan-recovery scan) around the reactivation; the orphan-recovery wrap is proven via the verbatim-replicated buildResumeMessage from the built chunk, as in the accepted base proof. A real sessions.send RPC through a running gateway was not driven; the call-site wiring (sessions.ts:913-917, agent.ts sibling) is covered by the unit tests on this head (322 passing).

Real behavior proof addendum: live gateway capture (2026-06-14)

Live capture on a real gateway process built from this PR head (50eefdf243), driving the actual reactivateCompletedSubagentSession over a real websocket against the qa-lab mock-openai model. This supersedes the 2026-06-12 in-process bundle addendum with a genuinely live run.

• Behavior addressed: When a user sends a follow-up (sessions.send) to a subagent session whose run already ended, reactivateCompletedSubagentSession (src/gateway/session-subagent-reactivation.ts) now threads the follow-up text into replaceSubagentRunAfterSteer as task, so the replacement subagent run record persists the follow-up prompt. On a gateway restart, orphan-recovery redispatch (buildResumeMessage in src/agents/subagent-orphan-recovery.ts) then wraps the follow-up rather than the stale original task. Before this PR the replacement run kept the stale original task and the restart redispatched the old prompt.

• Real environment tested: a real OpenClaw gateway child process spawned from the built dist/index.js at this PR head (50eefdf243); macOS 26.5.1, node v26.3.0, sqlite3 3.51.0. The gateway serves a real loopback websocket and runs the bundled qa-lab provider model mock-openai/gpt-5.5 (no external API key, no network egress); the harness boots it through startQaGatewayChild. A real parent agent turn emits a real sessions_spawn tool call, which spawns a real subagent run persisted in the live state/openclaw.sqlite. State is isolated to a fresh temp dir, so no live ~/.openclaw data is touched.

• Exact steps or command run after this patch:

node --import tsx /tmp/proof-77539-live.mts
# 1. agent RPC: parent turn "subagent handoff" -> real sessions_spawn -> child subagent runs to ended
# 2. sessions.send follow-up to the completed child session (real reactivateCompletedSubagentSession over the wire)
# 3. read the live subagent_runs table from state/openclaw.sqlite with sqlite3 while the replacement run is in flight
# 4. SIGKILL + cold restart the real gateway process; re-read subagent_runs

• Evidence after fix: redacted runtime logs and live sqlite output copied from the run:

[info] ended subagent childSessionKey=agent:qa:subagent:<redacted>
[info] original subagent task="Inspect the QA workspace and return one concise protocol note."
[step] sessions.send follow-up to the completed subagent session (parks in-flight)
[live] latest subagent run: task="subagent recovery worker: do B steered follow-up, switch to gauge reset against staging" ended_at=NULL
[PASS] reactivation persisted the follow-up as the run task in SQLite (inFlight=true)

# sqlite3 -readonly state/openclaw.sqlite "SELECT task, ended_reason FROM subagent_runs;" (after SIGKILL + cold restart)
task=subagent recovery worker: do B steered follow-up, switch to gauge reset against staging | ended_reason=subagent-error

• Observed result after fix: Over a real websocket RPC to a live gateway, sessions.send of the follow-up drove reactivateCompletedSubagentSession, which persisted the follow-up text as the subagent run's task column in the live state/openclaw.sqlite, captured while the replacement run was still in flight (ended_at=NULL). The original subagent task ("Inspect the QA workspace...") was replaced by the follow-up text, confirming the fix's task threading end to end. After a real SIGKILL plus cold restart of the gateway process, the persisted subagent run still carries the follow-up task rather than the stale original, so the restart redispatch reads the follow-up text.

• What was not tested: The literal buildResumeMessage wrap string was not captured across the cold restart. In this sandbox the restarted child reconciles the in-flight run to a terminal subagent-error (fresh ephemeral port, no parent delivery target), so the synthetic resume turn is not re-emitted to the model. The wrap behavior itself (orphan recovery reading run.task) is covered by the accepted base proof above and by the unit regression tests on this head (src/agents/subagent-registry.steer-restart.test.ts, src/gateway/session-subagent-reactivation.test.ts).