fix(runner): queue work when already running instead of discarding

[dreampuf]

Issue for this PR

Closes #35066

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

When a background subagent completes and calls ops.prompt() to notify the parent session, the parent's Runner is often still Running (processing the previous turn). The old ensureRunning discarded the new work item and just awaited the current run's completion — so the notification was lost and the parent session would hang until the user typed "continue".

Root cause: Runner.ensureRunning in packages/opencode/src/effect/runner.ts had this behavior when state was Running:

case "Running":
case "ShellThenRun":
  return [awaitDone(st.run.done), st] as const

It returned the existing run's deferred and threw away the new work argument. So if the parent was busy when the subagent finished, the ops.prompt() call that should have queued a new turn was silently dropped.

Commit dabf2dc ("remove the need for polling from experimental background agents" #29179) removed the old polling-based idle check (resumeWhenIdle), replacing it with a direct ops.prompt() call that races with ensureRunning — which is exactly where the race lives.

Fix: Add a RunningThenRun state to the Runner state machine (mirroring the existing ShellThenRun pattern):

1. ensureRunning when Running: store the new work as pending, transition to RunningThenRun, return a deferred that resolves when the pending work completes.
2. finishRun when RunningThenRun: when the current run finishes, start the pending work and transition back to Running.
3. cancel when RunningThenRun: interrupt both the current run's fiber and fail both deferreds (current + pending), then go idle.

Why this approach over PR #35041: PR #35041 (draft) moves the notification to the session completion path, but still has the same ensureRunning race — it doesn't fix the root cause. If the parent is busy when the notification fires, ensureRunning still discards the work. This PR fixes the root cause in the Runner itself, so all callers of ensureRunning (not just the subagent notification path) benefit.

How did you verify your code works?

• Updated "concurrent callers share the same run" — now expects calls=2 because the queued run also increments.
• Renamed "second ensureRunning ignores new work" → "second ensureRunning queues behind running and executes after" — now asserts the second work actually runs and returns its own result.
• Added 3 new tests:
  • ensureRunning queues behind running and transitions through RunningThenRun
  • third ensureRunning shares pending in RunningThenRun
  • cancel in RunningThenRun cancels both current and pending

runner.test.ts: 29 pass, 0 fail
prompt.test.ts + task.test.ts: 74 pass, 0 fail, 1 skip
typecheck (all 30 packages): pass

Screenshots / recordings

N/A — no UI changes.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential related PR found:

• fix(session): notify parent when subagents finish #35041 - fix(session): notify parent when subagents finish
  • This PR is explicitly mentioned in the description as an alternative approach to fixing the same underlying issue (fix(session): notify parent when subagent sessions finish #35066)
  • PR fix(runner): queue work when already running instead of discarding #36375 argues that fix(session): notify parent when subagents finish #35041 addresses the symptom but doesn't fix the root cause in Runner.ensureRunning, whereas this PR fixes it at the source so all callers benefit

This is related but takes a different approach. PR #36375 is the more comprehensive fix.

No other duplicate PRs found.

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍