, ctx: SessionFailur
});
}
-/** Apply an intra-RUNNING flip of the fine-grained busy substate: the
- * foreground turn moved between generating and idle-on-background-work without
- * any coarse state change (ADR-0038). Annotates the
+/** Apply a fine-grained busy-substate flip (ADR-0049). Annotates the
* existing session row so the composer gate and status indicator update; does
* nothing until the row exists (state_changed seeds it first). */
function applyForegroundActivity(
@@ -501,12 +500,10 @@ function applyForegroundActivity(
const sessionId = toSessionId(payload.session_id);
const existing = store.getState().taskSessions.items[sessionId];
if (!existing) return;
- // The substate is only meaningful while the session is RUNNING. Ignoring a
- // flip for any other coarse state prevents a delayed/out-of-order background
- // event from reopening the composer after the turn already ended (the coarse
- // state governs then). Also guard the task binding so a stale or malformed
- // payload cannot move the session onto another task's list.
- if (existing.state !== "RUNNING") return;
+ // Detached work can outlive the foreground turn, whose coarse state is then
+ // WAITING_FOR_INPUT. Terminal/parked sessions reject delayed activity frames;
+ // their execution teardown owns the final clear.
+ if (existing.state !== "RUNNING" && existing.state !== "WAITING_FOR_INPUT") return;
if (existing.task_id && existing.task_id !== taskId) return;
store.getState().upsertTaskSessionFromEvent(taskId, {
id: sessionId,
diff --git a/docs/decisions/0049-fine-grained-foreground-idle-busy-signal.md b/docs/decisions/0049-fine-grained-foreground-idle-busy-signal.md
index 4a6057bcd3..21eeae8ed9 100644
--- a/docs/decisions/0049-fine-grained-foreground-idle-busy-signal.md
+++ b/docs/decisions/0049-fine-grained-foreground-idle-busy-signal.md
@@ -1,15 +1,16 @@
# 0049: Fine-grained foreground-idle busy signal
-**Status:** accepted
+**Status:** accepted (amended 2026-07-21)
**Date:** 2026-07-11
**Area:** backend, frontend, protocol
## Context
-A session's durable state is a single scalar (`RUNNING`, `WAITING_FOR_INPUT`, …). While a turn is `RUNNING`, that scalar cannot distinguish two very different situations:
+A session's durable state is a single scalar (`RUNNING`, `WAITING_FOR_INPUT`, …). That scalar cannot distinguish three independent lifecycle facts:
-1. the foreground agent is actively generating output, versus
-2. the foreground turn is idle and only held open by spawned background work — a subagent `Task`, a `run_in_background` shell, or an active Claude `Monitor` watch.
+1. the foreground agent is actively generating output,
+2. the foreground is idle while spawned background work is still live, or
+3. the foreground turn has completed while detached background work continues.
Because both read as `RUNNING`, a session that kicked off a long background job rejected every new operator message as "agent is already running" for the entire duration of that job — locking the operator out of the conversation with no recovery but a restart.
@@ -19,7 +20,33 @@ Mid-turn steering — delivering a message *into* a turn while the model is acti
## Decision
-Track, per session and **in memory**, whether the open turn is foreground-driven or has yielded to outstanding background work, and narrow the prompt gate (`checkSessionPromptable`) to the foreground only:
+Track, per session and **in memory**, foreground ownership and background
+liveness independently, and narrow the prompt gate (`checkSessionPromptable`)
+to the foreground only:
+
+- Foreground activity has absolute display and admission precedence. While a
+ prompt is claimed, dispatched, or producing top-level output, the session is
+ generating regardless of background activity. When the foreground is idle,
+ outstanding recognized work produces the background-running state; only the
+ absence of both produces done/idle.
+- Foreground turn completion clears foreground ownership only. It does not
+ clear background registrations. Each background registration remains live
+ until a terminal signal for that workload arrives or the owning agent
+ execution is explicitly torn down.
+- A tool result that reports successful asynchronous launch is terminal for the
+ launch tool card but not for the launched workload. The orchestrator retains
+ the originating tool-call registration and clears workload liveness separately
+ when the provider reports a
+ task-notification result. Claude ACP currently exposes the notification's
+ origin but not its task ID; one notification therefore retires one session
+ background registration, while an ambiguous remainder stays background-live
+ rather than guessing done. Prompt completion and prompt-end tool sweeps do not
+ synthesize workload completion for detached shell work.
+- Claude ACP usage updates expose the origin of each model cycle. Completion of
+ the human-origin cycle is the explicit foreground-yield boundary even when
+ the ACP prompt RPC remains held open for spawned subagents; a later
+ task-notification-origin cycle may temporarily take foreground precedence
+ while it generates the completion summary.
- A `RUNNING` session accepts a new prompt when its foreground turn is idle and at least one recognized background task is outstanding; otherwise it keeps rejecting input exactly as before.
- Recognition keys off the **normalized shape** of the work (subagent task / `run_in_background` shell / active Monitor), not tool-name string matching. The ACP normalizer is corrected to recognize Claude's `run_in_background:true` shell shape (a normalizer bug fix in its own right).
@@ -34,17 +61,26 @@ The distinction is surfaced to the operator as a fine-grained substate (`foregro
- The composer gates on foreground-generating rather than coarse `RUNNING`.
- A tri-state status indicator distinguishes generating / working-in-background / done; the established "running" affordance is unchanged and a distinct indicator is *added* for the background-idle substate — it never reads as "done" while background work runs.
-- The substate is delivered live over a `session.activity_changed` WS event (and carried on `session.state_changed` to reset on every coarse transition), and is also read from the in-memory tracker into the boot payload and the session REST/WS DTOs (`RUNNING`-only) so a fresh page-load or a second tab is immediately correct rather than showing the coarse busy signal until the next flip.
+- The substate is delivered live over a `session.activity_changed` WS event and
+ carried on `session.state_changed`. It is also read from the in-memory tracker
+ into the boot payload and the session REST/WS DTOs. Generating is meaningful
+ for a `RUNNING` session; background may also be carried after the coarse state
+ settles when detached work remains live.
## Consequences
The operator is no longer falsely locked out while background work runs, and the UI truthfully shows "working in the background" as distinct from both "generating" and "done". Accepting input earlier does not make delivery earlier for a held-open subagent turn — that message still waits behind the open exchange, as the queue does today — but out-of-turn work (a Monitor burst, a backgrounded shell after the main turn yielded) is forwarded promptly with no false "already running" rejection.
-The signal is best-effort across a backend restart: a restart ends the turn, so the in-memory tracker resets to the safe "generating" default and no stale "you may type" is ever surfaced. Correctness is never traded — only the optimization. Recognition is deliberately Claude-shaped today (subagent task, `run_in_background` shell, active Monitor are Claude features); other agents keep today's behavior.
+The signal is best-effort across a backend or agent-execution restart. Connected
+executions retain background liveness across foreground turns, but detached
+work that survives a restart cannot be reconstructed without an agent-side
+liveness API. Recognition is deliberately Claude-shaped today (subagent task,
+`run_in_background` shell, active Monitor are Claude features); other agents
+keep today's behavior.
## Alternatives Considered
- **Rely on upstream synthetic idle-turn completion alone.** Rejected: it structurally cannot arm while the foreground prompt exchange is open, and its debounce re-extends under event bursts, so the held-open and chained-burst windows remain. A falsifiable acceptance test drives a chatty Monitor and confirms a prompt sent during a burst is accepted only with the fine-grained gate.
- **Drop the `RUNNING` gate / always accept input.** Rejected: it would let a new message race a genuinely-generating foreground turn, risking dropped or reordered messages and regressing non-steering agents.
-- **Persist the foreground/background distinction to the database (like the coarse states).** Rejected: it only matters for a live in-flight turn, so a persisted value becomes a second source of truth that can drift from the gate, survives a restart as a false "you may type" for a session whose turn is gone (needing extra reconciliation to stay safe), and adds write churn to the hot streaming path. In-memory tracking that resets to the safe default on every turn-close is sufficient and simpler; the same in-memory value is read at the serialization boundary to keep fresh page-loads correct without persistence.
+- **Persist the foreground/background distinction to the database (like the coarse states).** Rejected: persistence without an agent-side reconciliation API becomes a second source of truth and can survive restart as a false live value after the workload has died. Connected-execution tracking is kept in memory and read at serialization boundaries; turn close no longer destroys it, while execution teardown does.
- **Recognize background work by tool-name string matching.** Rejected as brittle across agents and updates; recognition keys on the normalized payload shape so producer and consumer share one contract.
diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md
index b3847c16bf..d29c0d0d46 100644
--- a/docs/decisions/INDEX.md
+++ b/docs/decisions/INDEX.md
@@ -56,7 +56,7 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 0046 | [Settings route save coordinator](0046-settings-route-save-coordinator.md) | accepted | frontend | 2026-07-14 |
| 0047 | [Plugins read conversation content via a capability-gated Host RPC](0047-plugin-host-conversation-reads.md) | accepted | backend, protocol | 2026-07-21 |
| 0048 | [Plugins invoke a settings-selectable utility agent](0048-plugin-host-utility-agent-invoke.md) | accepted | backend, frontend, protocol | 2026-07-21 |
-| 0049 | [Fine-grained foreground-idle busy signal](0049-fine-grained-foreground-idle-busy-signal.md) | accepted | backend, frontend, protocol | 2026-07-11 |
+| 0049 | [Fine-grained foreground-idle busy signal](0049-fine-grained-foreground-idle-busy-signal.md) | accepted (amended 2026-07-21) | backend, frontend, protocol | 2026-07-11 |
| 2026-07-23-opencode-review-evidence-trust | [Trusted OpenCode Review Evidence](2026-07-23-opencode-review-evidence-trust.md) | accepted | workflow, infra | 2026-07-23 |
| 2026-07-23-planner-direct-small-work | [Planner Direct Small Work](2026-07-23-planner-direct-small-work.md) | accepted | workflow | 2026-07-23 |
| 2026-07-23-post-commit-hook-aware-verification | [Post-Commit Hook-Aware Verification](2026-07-23-post-commit-hook-aware-verification.md) | accepted | workflow | 2026-07-23 |
diff --git a/docs/plans/background-work-liveness/plan.md b/docs/plans/background-work-liveness/plan.md
new file mode 100644
index 0000000000..1c04ca1fdb
--- /dev/null
+++ b/docs/plans/background-work-liveness/plan.md
@@ -0,0 +1,154 @@
+---
+spec: docs/specs/fine-grained-background-running-status-indicator/spec.md
+created: 2026-07-21
+status: completed
+---
+
+# Implementation Plan: Background work liveness
+
+## Overview
+
+Correct the busy signal by separating foreground ownership, launch-tool
+completion, and launched-workload completion. The adapter first exposes the
+detached workload lifecycle, the orchestrator then retains it across foreground
+turn completion, and the existing frontend indicators consume the corrected
+session/task aggregate. The final E2E scenario must end the foreground turn
+before the background workload ends; the current mock holds one turn open and
+therefore cannot catch the reported false-done regression.
+
+The ACP evidence for the design is reproducible with `acpdbg`: Claude ACP 0.60
+returns a terminal Bash tool update containing
+`_meta.claudeCode.toolResponse.backgroundTaskId` and an output-file path, while
+the provider explicitly promises a later task notification. Async subagents use
+the parallel `agentId` / `outputFile` launch metadata. The human-origin
+`usage_update` arrives after the foreground reply even when `session/prompt`
+remains held open for that subagent; the eventual autonomous completion cycle
+ends with `_meta._claude/origin.kind=task-notification`. A terminal launch-tool
+frame therefore cannot be treated as terminal evidence for either foreground
+idleness or detached-work completion.
+
+## Backend
+
+### ACP detached-work lifecycle
+
+- Extend `apps/backend/internal/agentctl/types/streams/agent.go` with
+ protocol-neutral foreground-yield and detached-background completion events.
+ Keep tool-card status unchanged:
+ a Bash or Task launch can be complete while its workload remains live.
+- In `apps/backend/internal/agentctl/server/adapter/transport/acp/`, recognize
+ Claude's human-origin and task-notification-origin usage boundaries. Retain
+ the originating top-level tool-call registration across prompt completion.
+- Convert human-origin usage completion into an explicit foreground-yield event
+ and task-notification-origin usage completion into one workload-completion
+ event. Claude ACP does not expose the completed task ID on the latter frame,
+ so the orchestrator retires one outstanding registration per notification;
+ an ambiguous remainder stays live rather than falsely showing done. Monitor
+ notification routing continues updating its own correlated tool card.
+- Prompt-end active-tool sweeps continue closing launch cards but do not invent
+ detached-work completion. Agent execution teardown drains any remaining
+ registrations and publishes terminal cleanup.
+
+### Session activity state machine
+
+- Refactor `apps/backend/internal/orchestrator/turn_activity.go` so foreground
+ ownership and background registrations are independent. The read order is:
+ prompt claim/top-level foreground activity → generating; otherwise any
+ background registration → background; otherwise idle/default.
+- Replace the turn-close reset in
+ `apps/backend/internal/orchestrator/service.go::completeTurnForSession` with a
+ foreground-idle transition. Reserve full activity deletion for execution
+ stop, cancellation/teardown, and session removal paths.
+- Handle detached-background lifecycle events separately from tool-card
+ terminal updates. A launch-tool completion must not remove its workload;
+ an ID-bearing workload completion removes its registration, while an
+ uncorrelated provider completion retires one session registration and fails
+ closed when ambiguity remains.
+- Preserve atomic prompt admission: a foreground claim always wins over
+ background liveness, concurrent claims admit exactly one prompt, and a failed
+ claim restores background-idle only when its generation/epoch is still
+ current.
+
+### DTO, aggregate, and live updates
+
+- Update session DTO enrichment so `foreground_activity=background` may be
+ emitted for a settled coarse session when detached work remains. Unknown
+ activity on a `RUNNING` session still defaults to generating.
+- Update task most-active-wins aggregation to rank generating `RUNNING`
+ sessions first, then every session with live background work, then existing
+ settled-state behavior.
+- Publish `session.activity_changed` and task refreshes for the foreground-turn
+ close → background and final background → idle transitions, including after
+ the coarse session has left `RUNNING`.
+
+## Frontend
+
+### Shared session flags and store transitions
+
+- In `apps/web/hooks/domains/session/use-session-state.ts`, derive background
+ work from `foreground_activity` independently of coarse `RUNNING` state.
+ `isAgentBusy` remains foreground-only; `isWorking` includes background work.
+- Audit `session.state_changed` and `session.activity_changed` reducers so a
+ coarse settled transition does not erase a concurrently supplied background
+ value, and final liveness completion clears the working affordance.
+- Keep the existing indicators and layout. This is shared state/data
+ normalization, so desktop and mobile use the same view model with no new
+ composition, touch, navigation, or responsive behavior.
+
+## Tests
+
+- **Foreground precedence:** background + foreground output/claim reads
+ generating and queues a second simultaneous prompt. File:
+ `apps/backend/internal/orchestrator/foreground_busy_signal_test.go`.
+- **Turn outlived:** turn completion with a registered detached workload reads
+ background and stays promptable; only workload completion reads idle. Files:
+ `foreground_busy_signal_test.go`,
+ `foreground_activity_signal_test.go`.
+- **Launch versus workload terminal:** terminal Bash/async-Task launch updates
+ preserve detached liveness; human-origin usage yields the foreground;
+ task-notification-origin usage retires one workload; unknown or duplicate
+ notifications are harmless. Files under
+ `apps/backend/internal/agentctl/server/adapter/transport/acp/` and
+ `foreground_busy_signal_test.go`.
+- **Task aggregate:** a non-`RUNNING` session with live background work outranks
+ done, while any generating session outranks background. Files:
+ `apps/backend/internal/task/service/task_activity_test.go` and DTO tests.
+- **Frontend flags/store:** settled+background is working but not busy;
+ `RUNNING`+generating is busy; foreground always wins; final completion is
+ idle. Files: `use-session-state.test.ts` and relevant session WS slice tests.
+
+## E2E Tests
+
+- Add a mock-agent command that launches background work, completes its
+ foreground turn immediately, emits a later terminal notification, and does
+ not hold the prompt RPC open.
+- Update `apps/web/e2e/tests/chat/busy-signal.spec.ts` to assert, after the
+ foreground turn settles, that the green background spinner remains, the
+ composer sends immediately rather than queues, a new foreground prompt shows
+ orange for its duration, and the indicator returns to background until the
+ detached workload ends.
+- Update `apps/web/e2e/tests/chat/mobile-busy-signal.spec.ts` with the same
+ foreground-ended/background-live outcome at Pixel 5 width. No mobile layout
+ contract changes; this covers the shared state normalization already rendered
+ by the existing mobile surface.
+
+## Implementation Waves
+
+Wave 1:
+
+- [x] [Task 01: ACP detached-work lifecycle](task-01-acp-detached-lifecycle.md)
+
+Wave 2:
+
+- [x] [Task 02: Session activity ownership](task-02-session-activity-ownership.md)
+
+Wave 3:
+
+- [x] [Task 03: Client state contract](task-03-client-state-contract.md)
+
+Wave 4:
+
+- [x] [Task 04: Realistic E2E coverage](task-04-realistic-e2e-coverage.md)
+
+Wave 5:
+
+- [x] [Task 05: Review and verification](task-05-review-and-verification.md)
diff --git a/docs/plans/background-work-liveness/task-01-acp-detached-lifecycle.md b/docs/plans/background-work-liveness/task-01-acp-detached-lifecycle.md
new file mode 100644
index 0000000000..52d850a434
--- /dev/null
+++ b/docs/plans/background-work-liveness/task-01-acp-detached-lifecycle.md
@@ -0,0 +1,38 @@
+---
+id: "01-acp-detached-lifecycle"
+title: "ACP detached-work lifecycle"
+status: done
+wave: 1
+depends_on: []
+plan: "plan.md"
+spec: "../../specs/fine-grained-background-running-status-indicator/spec.md"
+---
+
+# Task 01: ACP detached-work lifecycle
+
+- **Acceptance:** Bash `backgroundTaskId` and async-subagent `agentId` launches
+ produce protocol-neutral workload-start evidence without changing the launch
+ card's terminal status; human-origin usage produces foreground-yield;
+ task-notification-origin usage produces exactly one workload-complete event;
+ prompt completion does not prematurely complete detached shell work.
+- **Verification:** `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp/... ./internal/agentctl/types/streams/...`
+- **Files likely touched:**
+ `internal/agentctl/types/streams/agent.go`,
+ `internal/agentctl/server/adapter/transport/acp/adapter.go`,
+ `adapter_tools.go`, `adapter_updates.go`, `monitor.go`, and focused tests in
+ the same ACP package.
+- **Dependencies:** None.
+- **Inputs:** ADR-0049 detached-lifecycle amendment; captured Claude 0.60 Bash
+ and async-subagent frame ordering; existing subagent, usage, and Monitor tests.
+- **Output contract:** Report event shapes, correlations, files changed, tests
+ run, lifecycle cleanup behavior, residual provider-data limits, and mark this
+ task plus its plan checkbox done.
+
+## Result
+
+- Added provider-neutral `foreground_idle` and `background_complete` events
+ from Claude ACP usage-origin metadata while preserving the paired context
+ window update.
+- Launch tool cards remain terminal; detached shell/async-subagent liveness is
+ retained by the orchestrator until provider completion evidence.
+- Verified with the ACP adapter package and live Claude 0.60 frame probes.
diff --git a/docs/plans/background-work-liveness/task-02-session-activity-ownership.md b/docs/plans/background-work-liveness/task-02-session-activity-ownership.md
new file mode 100644
index 0000000000..89b701228a
--- /dev/null
+++ b/docs/plans/background-work-liveness/task-02-session-activity-ownership.md
@@ -0,0 +1,35 @@
+---
+id: "02-session-activity-ownership"
+title: "Session activity ownership"
+status: done
+wave: 2
+depends_on: ["01-acp-detached-lifecycle"]
+plan: "plan.md"
+spec: "../../specs/fine-grained-background-running-status-indicator/spec.md"
+---
+
+# Task 02: Session activity ownership
+
+- **Acceptance:** Foreground claims/output always rank generating; turn close
+ leaves detached registrations background-running and promptable; matching
+ workload completion clears them; execution teardown clears all activity; task
+ and session DTOs remain correct when coarse state is settled.
+- **Verification:** `cd apps/backend && go test ./internal/orchestrator/... ./internal/task/service/... ./internal/task/dto/...`
+- **Files likely touched:** `internal/orchestrator/turn_activity.go`,
+ `service.go`, stream handlers and their focused tests,
+ `internal/task/service/task_activity.go`, and session/task DTO enrichment.
+- **Dependencies:** Task 01 event contract.
+- **Inputs:** spec three-state precedence and live-propagation sections;
+ existing claim-generation and activity-signal tests.
+- **Output contract:** Report state transitions, teardown ownership, files
+ changed, tests run, blockers/risks, and mark this task plus its plan checkbox
+ done.
+
+## Result
+
+Foreground completion now yields to, rather than deletes, outstanding detached
+registrations. Async launch-card completion preserves workload liveness;
+provider completion retires one registration, and execution teardown remains
+the full cleanup boundary. Settled session/task DTOs surface background while
+stale settled generating values remain omitted. Focused orchestrator, task
+service, and DTO suites pass.
diff --git a/docs/plans/background-work-liveness/task-03-client-state-contract.md b/docs/plans/background-work-liveness/task-03-client-state-contract.md
new file mode 100644
index 0000000000..6275a576e0
--- /dev/null
+++ b/docs/plans/background-work-liveness/task-03-client-state-contract.md
@@ -0,0 +1,33 @@
+---
+id: "03-client-state-contract"
+title: "Client state contract"
+status: done
+wave: 3
+depends_on: ["02-session-activity-ownership"]
+plan: "plan.md"
+spec: "../../specs/fine-grained-background-running-status-indicator/spec.md"
+---
+
+# Task 03: Client state contract
+
+- **Acceptance:** `settled+background` remains working with instant-send;
+ foreground-generating always shows the existing orange state and queue mode;
+ final background completion becomes done/idle; state and activity WS updates
+ cannot erase one another out of order.
+- **Verification:** `cd apps && pnpm --filter @kandev/web test -- hooks/domains/session/use-session-state.test.ts` plus focused session-store tests; `cd apps/web && pnpm run typecheck`.
+- **Files likely touched:** `apps/web/hooks/domains/session/use-session-state.ts`
+ and test, `apps/web/lib/state/slices/session/` WS reducers and tests, and shared
+ backend/session types only if the event contract requires it.
+- **Dependencies:** Task 02 DTO and event behavior.
+- **Inputs:** existing desktop/mobile status components; no layout changes.
+- **Output contract:** Report derived-flag truth table, event-ordering tests,
+ files changed, commands run, and mark this task plus its plan checkbox done.
+
+## Result
+
+`RUNNING` without background remains busy/working; any background value remains
+working but not busy even after the session settles; settled generating is
+idle. State changes carry background into `WAITING_FOR_INPUT`, later activity
+completion is accepted there, and terminal states reject delayed frames. The
+chat status row now consumes the shared working signal. Ninety-five focused web
+tests and web typecheck pass.
diff --git a/docs/plans/background-work-liveness/task-04-realistic-e2e-coverage.md b/docs/plans/background-work-liveness/task-04-realistic-e2e-coverage.md
new file mode 100644
index 0000000000..0fae543a08
--- /dev/null
+++ b/docs/plans/background-work-liveness/task-04-realistic-e2e-coverage.md
@@ -0,0 +1,34 @@
+---
+id: "04-realistic-e2e-coverage"
+title: "Realistic E2E coverage"
+status: done
+wave: 4
+depends_on: ["03-client-state-contract"]
+plan: "plan.md"
+spec: "../../specs/fine-grained-background-running-status-indicator/spec.md"
+---
+
+# Task 04: Realistic E2E coverage
+
+- **Acceptance:** The mock background scenario closes its foreground turn before
+ its workload; desktop and mobile tests observe background-working plus
+ instant-send during that interval; a foreground reply temporarily takes
+ orange precedence; done appears only after workload completion.
+- **Verification:** `cd apps/web && pnpm e2e:run tests/chat/busy-signal.spec.ts tests/chat/mobile-busy-signal.spec.ts`.
+- **Files likely touched:** `apps/backend/cmd/mock-agent/handler.go` and tests,
+ `apps/web/e2e/tests/chat/busy-signal.spec.ts`, and
+ `mobile-busy-signal.spec.ts`.
+- **Dependencies:** Tasks 01–03.
+- **Inputs:** existing `/background` test path demonstrates the old blind spot
+ and should remain available for held-open-turn coverage.
+- **Output contract:** Report the RED failure, GREEN run, desktop/mobile
+ outcomes, artifacts/blockers, and mark this task plus its plan checkbox done.
+
+## Result
+
+The new `/detached-background` mock command returns the foreground response,
+leaves a Claude-shaped async workload alive, and emits a later
+task-notification lifecycle boundary. The first browser run caught the chat
+status row's coarse-state dependency; after fixing that consumer, all four
+desktop tests and both Pixel 5 tests pass, including foreground precedence and
+reload hydration.
diff --git a/docs/plans/background-work-liveness/task-05-review-and-verification.md b/docs/plans/background-work-liveness/task-05-review-and-verification.md
new file mode 100644
index 0000000000..2c4ae514eb
--- /dev/null
+++ b/docs/plans/background-work-liveness/task-05-review-and-verification.md
@@ -0,0 +1,22 @@
+---
+id: "05-review-and-verification"
+title: "Review and verification"
+status: completed
+wave: 5
+depends_on: ["01-acp-detached-lifecycle", "02-session-activity-ownership", "03-client-state-contract", "04-realistic-e2e-coverage"]
+plan: "plan.md"
+spec: "../../specs/fine-grained-background-running-status-indicator/spec.md"
+---
+
+# Task 05: Review and verification
+
+- **Acceptance:** Changed code is simplified and reviewed; formatting,
+ typecheck, unit tests, lint, targeted desktop/mobile E2E, and ACP regression
+ tests pass; any provider signal limitation is explicitly documented.
+- **Verification:** `make fmt`; `make typecheck test lint`; `cd apps/web && pnpm e2e:run tests/chat/busy-signal.spec.ts tests/chat/mobile-busy-signal.spec.ts`.
+- **Files likely touched:** only review-driven corrections and plan/task status
+ metadata.
+- **Dependencies:** Tasks 01–04.
+- **Inputs:** code-review, simplify, verify, QA, and docs-maintainer guidance.
+- **Output contract:** Report review findings/fixes, exact commands and results,
+ remaining risks, and mark all plan/task status fields done.
diff --git a/docs/specs/fine-grained-background-running-status-indicator/spec.md b/docs/specs/fine-grained-background-running-status-indicator/spec.md
index 3c4091b8c5..e02e28b731 100644
--- a/docs/specs/fine-grained-background-running-status-indicator/spec.md
+++ b/docs/specs/fine-grained-background-running-status-indicator/spec.md
@@ -4,7 +4,7 @@ The system already tracks, per session, a fine-grained substate that
distinguishes an actively-generating foreground turn from a foreground turn that
has gone idle and is only held open by spawned background work — a subagent, a
backgrounded shell, or an active monitor (the busy signal recorded in
-ADR-0047). This spec makes the operator-facing status indicators as
+ADR-0049). This spec makes the operator-facing status indicators as
fine-grained as that signal: everywhere a task or session status appears, the
"still working in the background" condition reads as its own state, distinct
from both "actively generating" and "done".
@@ -37,6 +37,14 @@ conditions for an in-flight unit of work:
work (subagent / backgrounded shell / active monitor) is still running.
- **done** — no work is in progress.
+The states have strict precedence. Foreground work always wins: while the
+foreground is generating or a newly accepted prompt is being dispatched, the
+surface shows **generating**, regardless of any background work. Only after the
+foreground becomes idle does outstanding background work select
+**background-running**. **Done** is possible only when neither foreground nor
+recognized background work is active. Ending the foreground turn does not, by
+itself, end or hide background work that outlives that turn.
+
The background-running affordance is visually separable from *both* the
generating affordance *and* the done affordance, and the separation does not
rely on hue alone: an operator distinguishes it by shape or motion, so it
@@ -60,7 +68,7 @@ recognize.
**Additive, not a re-signal.** The background-running affordance communicates
only "work is still in progress." It deliberately does not signal "you may now
-type" — composer input-gating is a separate concern (ADR-0047) and is not
+type" — composer input-gating is a separate concern (ADR-0049) and is not
represented by this indicator.
**Alternatives considered.**
@@ -222,9 +230,12 @@ in-scope surface — session-level and task-level — updates promptly without a
manual refresh. A freshly loaded page and a second tab show the correct state
immediately rather than a stale value that only corrects on the next transition.
When the fine-grained substate is unknown or unavailable, no surface falsely
-reads "done" while a turn is still open.
+reads "done" while recognized background work remains live, including after
+the foreground turn has closed and the coarse session state has settled.
-**Decision and the constraint that drove it.** Transitions are pushed live:
+**Decision and the constraint that drove it.** Foreground ownership and
+background liveness are independent signals with foreground-first precedence.
+Transitions are pushed live:
per-session substate flips propagate to session-level surfaces, and because the
task-level aggregate is carried on the task record, a session's activity flip
also refreshes the task-level surfaces subscribed to that task. The initial page
@@ -234,22 +245,30 @@ by the requirement that a stale "done" that clears only on refresh is itself a
defect: the indicator's whole value is being trusted at a glance, so it must be
correct at the moment of the glance, including immediately after load.
+A foreground turn completing clears only foreground ownership. Recognized
+background work remains attached to the session until its own terminal
+lifecycle signal arrives or the owning agent execution is torn down. A
+background-running value may therefore be carried for a session whose coarse
+state is no longer `RUNNING`. The composer gates only on foreground ownership;
+background liveness alone never puts the composer into queue mode.
+
**Safe fallback.** The fine-grained substate is in-memory and best-effort by
-design (ADR-0047); after a backend restart the in-memory tracker resets. The
-fallback is chosen so that an unknown substate never resolves to "done" while a
-turn is open: an in-flight session whose substate is unknown reads as working
-(generating), not done, and a task with such a session does not read done.
-Correctness of "not falsely done" is never traded for the optimization of the
-finer distinction.
+design (ADR-0049). While the agent execution remains connected, a background
+launch stays background-running until terminal evidence arrives; a foreground
+turn-complete event is not terminal evidence for detached work. After a backend
+or agent-execution restart, live detached work that cannot be reconstructed is
+outside this guarantee. For an in-flight `RUNNING` session whose substate is
+unknown, the fallback remains working (generating), not done.
**Alternatives considered.**
- *Persist the fine-grained substate so it survives restart.* Rejected
- (consistent with ADR-0047): a persisted copy becomes a second source of truth
+ (consistent with ADR-0049): a persisted copy becomes a second source of truth
that can drift, can survive a restart as a false reading for a session whose
turn is already gone, and adds write churn on the hot streaming path. The
- substate only matters for a live in-flight turn; resetting to the safe default
- on turn-close is sufficient and simpler.
+ longer than the connected agent lifecycle. Persistence without an agent-side
+ reconciliation API could preserve a false live value after restart, so this
+ change keeps connected-execution tracking in memory.
- *Refresh task-level surfaces only on coarse state changes, not on
activity flips.* Rejected: a generating→background flip does not change the
coarse state, so the scanning surfaces would keep showing the wrong one of the
From b5174b50713091a2db3ab238e0240741dc47aa5d Mon Sep 17 00:00:00 2001
From: point-source <47544779+point-source@users.noreply.github.com>
Date: Wed, 22 Jul 2026 02:41:58 +0000
Subject: [PATCH 62/80] fix: prioritize pending input over task activity
---
.../backend/internal/backendapp/boot_state.go | 42 ++++++--
.../internal/backendapp/boot_state_routes.go | 1 +
.../internal/backendapp/helpers_test.go | 45 +++++++++
apps/backend/internal/task/dto/dto.go | 1 +
.../task/handlers/task_http_handlers.go | 47 +++++++--
.../task/handlers/task_http_handlers_test.go | 17 ++++
apps/backend/internal/task/models/models.go | 4 +-
.../internal/task/service/service_events.go | 39 ++++++++
.../task/service/service_events_test.go | 65 +++++++++++++
apps/web/app/tasks/[id]/kanban-task-shell.tsx | 34 +++++--
apps/web/app/tasks/tasks-list-view.tsx | 2 +
apps/web/components/kanban-card-content.tsx | 2 +
apps/web/components/kanban-card.tsx | 1 +
.../components/kanban/graph2-step-node.tsx | 2 +
.../kanban/swimlane-graph-content.tsx | 4 +
apps/web/components/task/TaskHeader.test.tsx | 44 +++++++--
apps/web/components/task/TaskHeader.tsx | 16 ++-
.../mobile/mobile-sessions-section.test.tsx | 87 ++++++++++++++---
.../task/mobile/mobile-sessions-section.tsx | 12 +--
.../session-task-switcher-sheet-helpers.ts | 32 ++++++
.../session-task-switcher-sheet-hooks.test.ts | 55 +++++++++++
.../session-task-switcher-sheet-hooks.ts | 78 ++++++---------
.../task/session-reopen-menu.test.tsx | 5 +
.../components/task/session-reopen-menu.tsx | 21 ++--
.../components/task/sessions-dropdown.test.ts | 25 +++++
.../web/components/task/sessions-dropdown.tsx | 16 +--
apps/web/components/task/task-item.test.tsx | 46 +++++++--
apps/web/components/task/task-item.tsx | 34 ++++---
.../task-session-sidebar-aggregate.test.ts | 24 +++++
.../task/task-session-sidebar-aggregate.ts | 34 +++++++
.../components/task/task-session-sidebar.tsx | 41 ++++++--
.../web/hooks/use-task-pending-input.test.tsx | 83 +++++++++++++++-
apps/web/hooks/use-task-pending-input.ts | 97 +++++++++++++++----
apps/web/lib/kanban/map-task.test.ts | 14 +++
apps/web/lib/kanban/map-task.ts | 2 +
apps/web/lib/ssr/mapper.ts | 1 +
apps/web/lib/state/slices/kanban/types.ts | 1 +
apps/web/lib/types/backend.ts | 1 +
apps/web/lib/types/http.ts | 1 +
apps/web/lib/ui/state-icons.test.tsx | 48 ++++++---
apps/web/lib/ui/state-icons.tsx | 27 ++----
apps/web/lib/ws/handlers/kanban.ts | 5 +
.../ws/handlers/tasks-pending-action.test.ts | 70 +++++++++++++
apps/web/lib/ws/handlers/tasks.ts | 6 ++
.../spec.md | 8 ++
45 files changed, 1027 insertions(+), 213 deletions(-)
create mode 100644 apps/web/components/task/mobile/session-task-switcher-sheet-helpers.ts
create mode 100644 apps/web/components/task/sessions-dropdown.test.ts
create mode 100644 apps/web/lib/ws/handlers/tasks-pending-action.test.ts
diff --git a/apps/backend/internal/backendapp/boot_state.go b/apps/backend/internal/backendapp/boot_state.go
index b78a43ad15..5ef9337e6d 100644
--- a/apps/backend/internal/backendapp/boot_state.go
+++ b/apps/backend/internal/backendapp/boot_state.go
@@ -698,7 +698,7 @@ func (b bootStateBuilder) taskDTOsWithSessionInfo(ctx context.Context, tasks []*
b.logBootError("get task detail primary session info", err)
return taskDTOs(tasks)
}
- pendingActionsBySession, err := b.bootPendingActionsForWaitingPrimarySessions(ctx, primaryInfoByTask)
+ pendingActionsBySession, err := b.bootPendingActionsForInputCapableSessions(ctx, sessionsByTask)
if err != nil {
b.logBootError("get task detail pending actions", err)
pendingActionsBySession = map[string]taskmodels.TaskPendingAction{}
@@ -736,6 +736,7 @@ func (b bootStateBuilder) taskDTOsWithSessionInfo(ctx context.Context, tasks []*
info.sessionState,
bootPendingActionPtr(info.sessionID, pendingActionsBySession),
)
+ dto.TaskPendingAction = bootTaskPendingActionPtr(sessions, pendingActionsBySession)
// Stamp the task-level MOST-ACTIVE-WINS activity aggregate so the board
// card and task list show the background-running affordance on first paint
// / in a second tab, without holding the task's full session set client-side
@@ -808,14 +809,16 @@ func bootSessionInfo(session *taskmodels.TaskSession) bootSessionInfoFields {
return info
}
-func (b bootStateBuilder) bootPendingActionsForWaitingPrimarySessions(
+func (b bootStateBuilder) bootPendingActionsForInputCapableSessions(
ctx context.Context,
- primaryInfoByTask map[string]*taskmodels.TaskSession,
+ sessionsByTask map[string][]*taskmodels.TaskSession,
) (map[string]taskmodels.TaskPendingAction, error) {
- sessionIDs := make([]string, 0, len(primaryInfoByTask))
- for _, info := range primaryInfoByTask {
- if info != nil && info.State == taskmodels.TaskSessionStateWaitingForInput {
- sessionIDs = append(sessionIDs, info.ID)
+ sessionIDs := make([]string, 0)
+ for _, sessions := range sessionsByTask {
+ for _, session := range sessions {
+ if bootInputCapableSession(session) {
+ sessionIDs = append(sessionIDs, session.ID)
+ }
}
}
if len(sessionIDs) == 0 {
@@ -824,6 +827,31 @@ func (b bootStateBuilder) bootPendingActionsForWaitingPrimarySessions(
return b.p.taskSvc.GetPendingActionsForSessions(ctx, sessionIDs)
}
+func bootInputCapableSession(session *taskmodels.TaskSession) bool {
+ return session != nil && (session.State == taskmodels.TaskSessionStateRunning || session.State == taskmodels.TaskSessionStateWaitingForInput)
+}
+
+func bootTaskPendingActionPtr(sessions []*taskmodels.TaskSession, actions map[string]taskmodels.TaskPendingAction) *string {
+ var clarification bool
+ for _, session := range sessions {
+ if !bootInputCapableSession(session) {
+ continue
+ }
+ switch actions[session.ID] {
+ case taskmodels.TaskPendingActionPermission:
+ value := string(taskmodels.TaskPendingActionPermission)
+ return &value
+ case taskmodels.TaskPendingActionClarification:
+ clarification = true
+ }
+ }
+ if clarification {
+ value := string(taskmodels.TaskPendingActionClarification)
+ return &value
+ }
+ return nil
+}
+
func bootPendingActionPtr(
sessionID *string,
pendingActionsBySession map[string]taskmodels.TaskPendingAction,
diff --git a/apps/backend/internal/backendapp/boot_state_routes.go b/apps/backend/internal/backendapp/boot_state_routes.go
index 01b215ec49..391fe4f038 100644
--- a/apps/backend/internal/backendapp/boot_state_routes.go
+++ b/apps/backend/internal/backendapp/boot_state_routes.go
@@ -561,6 +561,7 @@ func mapKanbanTaskState(task taskdto.TaskDTO) map[string]any {
"primarySessionId": task.PrimarySessionID,
"primarySessionState": task.PrimarySessionState,
"primarySessionPendingAction": task.PrimarySessionPendingAction,
+ "taskPendingAction": task.TaskPendingAction,
"sessionCount": task.SessionCount,
"reviewStatus": nullString(string(task.ReviewStatus)),
"parentTaskId": nullString(task.ParentID),
diff --git a/apps/backend/internal/backendapp/helpers_test.go b/apps/backend/internal/backendapp/helpers_test.go
index 88913fe7f9..d324829be9 100644
--- a/apps/backend/internal/backendapp/helpers_test.go
+++ b/apps/backend/internal/backendapp/helpers_test.go
@@ -469,6 +469,26 @@ func TestBootInitialStateHomeIncludesKanbanFirstPaintState(t *testing.T) {
}); err != nil {
t.Fatalf("CreateMessage: %v", err)
}
+ if err := harness.taskRepo.CreateTaskSession(ctx, &models.TaskSession{
+ ID: "boot-session-secondary", TaskID: task.ID, State: models.TaskSessionStateWaitingForInput,
+ StartedAt: now, UpdatedAt: now,
+ }); err != nil {
+ t.Fatalf("CreateTaskSession secondary: %v", err)
+ }
+ if err := harness.taskRepo.CreateTurn(ctx, &models.Turn{
+ ID: "boot-turn-secondary", TaskID: task.ID, TaskSessionID: "boot-session-secondary",
+ StartedAt: now, CreatedAt: now, UpdatedAt: now,
+ }); err != nil {
+ t.Fatalf("CreateTurn secondary: %v", err)
+ }
+ if err := harness.taskRepo.CreateMessage(ctx, &models.Message{
+ ID: "boot-permission", TaskID: task.ID, TaskSessionID: "boot-session-secondary",
+ TurnID: "boot-turn-secondary", AuthorType: models.MessageAuthorAgent,
+ Type: models.MessageTypePermissionRequest, Content: "Allow?",
+ Metadata: map[string]interface{}{"status": "pending"}, CreatedAt: now, UpdatedAt: now,
+ }); err != nil {
+ t.Fatalf("CreateMessage secondary: %v", err)
+ }
state := bootInitialState(
ctx,
@@ -512,6 +532,7 @@ func TestBootInitialStateHomeIncludesKanbanFirstPaintState(t *testing.T) {
WorkflowStepID string `json:"workflowStepId"`
PrimarySessionState *string `json:"primarySessionState"`
PrimarySessionPendingAction *string `json:"primarySessionPendingAction"`
+ TaskPendingAction *string `json:"taskPendingAction"`
} `json:"tasks"`
} `json:"snapshots"`
IsLoading bool `json:"isLoading"`
@@ -527,6 +548,7 @@ func TestBootInitialStateHomeIncludesKanbanFirstPaintState(t *testing.T) {
WorkflowStepID string `json:"workflowStepId"`
PrimarySessionState *string `json:"primarySessionState"`
PrimarySessionPendingAction *string `json:"primarySessionPendingAction"`
+ TaskPendingAction *string `json:"taskPendingAction"`
} `json:"tasks"`
IsLoading bool `json:"isLoading"`
} `json:"kanban"`
@@ -554,6 +576,9 @@ func TestBootInitialStateHomeIncludesKanbanFirstPaintState(t *testing.T) {
snapshotTask.PrimarySessionPendingAction,
)
}
+ if snapshotTask.TaskPendingAction == nil || *snapshotTask.TaskPendingAction != "permission" {
+ t.Fatalf("snapshot taskPendingAction = %#v, want permission", snapshotTask.TaskPendingAction)
+ }
if decoded.Kanban.WorkflowID != workflows[0].ID {
t.Fatalf("active kanban workflow = %q, want %q", decoded.Kanban.WorkflowID, workflows[0].ID)
}
@@ -564,11 +589,31 @@ func TestBootInitialStateHomeIncludesKanbanFirstPaintState(t *testing.T) {
activeTask.PrimarySessionPendingAction,
)
}
+ if activeTask.TaskPendingAction == nil || *activeTask.TaskPendingAction != "permission" {
+ t.Fatalf("active taskPendingAction = %#v, want permission", activeTask.TaskPendingAction)
+ }
if decoded.KanbanMulti.IsLoading || decoded.Kanban.IsLoading {
t.Fatal("boot payload should mark kanban data loaded")
}
}
+func TestBootTaskPendingActionExcludesStartingAndTerminalSessions(t *testing.T) {
+ sessions := []*models.TaskSession{
+ {ID: "starting", State: models.TaskSessionStateStarting},
+ {ID: "completed", State: models.TaskSessionStateCompleted},
+ {ID: "failed", State: models.TaskSessionStateFailed},
+ }
+ actions := map[string]models.TaskPendingAction{
+ "starting": models.TaskPendingActionPermission,
+ "completed": models.TaskPendingActionPermission,
+ "failed": models.TaskPendingActionClarification,
+ }
+
+ if got := bootTaskPendingActionPtr(sessions, actions); got != nil {
+ t.Fatalf("bootTaskPendingActionPtr() = %q, want nil for stale sessions", *got)
+ }
+}
+
func TestBootInitialStateHomePreservesSavedAllWorkflowsFilter(t *testing.T) {
harness := newBootStateTestHarness(t)
ctx := context.Background()
diff --git a/apps/backend/internal/task/dto/dto.go b/apps/backend/internal/task/dto/dto.go
index 4ff5c27345..7f97214718 100644
--- a/apps/backend/internal/task/dto/dto.go
+++ b/apps/backend/internal/task/dto/dto.go
@@ -153,6 +153,7 @@ type TaskDTO struct {
PrimaryWorkingDirectory *string `json:"primary_working_directory,omitempty"`
PrimarySessionState *string `json:"primary_session_state,omitempty"`
PrimarySessionPendingAction *string `json:"primary_session_pending_action"`
+ TaskPendingAction *string `json:"task_pending_action"`
// ForegroundActivity is the task-level MOST-ACTIVE-WINS activity aggregate
// across the task's sessions (§spec:task-level-indicator): "generating" when
// any session is generating, "background" when none is generating but at
diff --git a/apps/backend/internal/task/handlers/task_http_handlers.go b/apps/backend/internal/task/handlers/task_http_handlers.go
index 9845c273cd..fd01534b58 100644
--- a/apps/backend/internal/task/handlers/task_http_handlers.go
+++ b/apps/backend/internal/task/handlers/task_http_handlers.go
@@ -113,7 +113,7 @@ func buildTaskDTOsWithSessionInfo(
if err != nil {
return nil, err
}
- pendingActionsBySession, err := pendingActionsForWaitingPrimarySessions(ctx, svc, primarySessionInfoMap)
+ pendingActionsBySession, err := pendingActionsForInputCapableSessions(ctx, svc, sessionsByTask)
if err != nil {
log.Warn("failed to load pending actions for task list, using empty map", zap.Error(err))
pendingActionsBySession = map[string]models.TaskPendingAction{}
@@ -134,7 +134,7 @@ func buildTaskDTOsWithSessionInfo(
sessionCount = &n
}
si := extractSessionInfo(primarySessionInfoMap[task.ID])
- result = append(result, dto.FromTaskWithSessionInfo(
+ taskDTO := dto.FromTaskWithSessionInfo(
task,
primarySessionID,
sessionCount,
@@ -146,7 +146,9 @@ func buildTaskDTOsWithSessionInfo(
si.workingDirectory,
si.sessionState,
pendingActionPtr(si.sessionID, pendingActionsBySession),
- ))
+ )
+ taskDTO.TaskPendingAction = taskPendingActionPtr(sessions, pendingActionsBySession)
+ result = append(result, taskDTO)
}
return result, nil
}
@@ -201,15 +203,17 @@ func extractSessionInfo(info *models.TaskSession) sessionInfoFields {
return si
}
-func pendingActionsForWaitingPrimarySessions(
+func pendingActionsForInputCapableSessions(
ctx context.Context,
svc *service.Service,
- primarySessionInfoMap map[string]*models.TaskSession,
+ sessionsByTask map[string][]*models.TaskSession,
) (map[string]models.TaskPendingAction, error) {
- sessionIDs := make([]string, 0, len(primarySessionInfoMap))
- for _, info := range primarySessionInfoMap {
- if info != nil && info.State == models.TaskSessionStateWaitingForInput {
- sessionIDs = append(sessionIDs, info.ID)
+ sessionIDs := make([]string, 0)
+ for _, sessions := range sessionsByTask {
+ for _, session := range sessions {
+ if isInputCapableSession(session) {
+ sessionIDs = append(sessionIDs, session.ID)
+ }
}
}
if len(sessionIDs) == 0 {
@@ -218,6 +222,31 @@ func pendingActionsForWaitingPrimarySessions(
return svc.GetPendingActionsForSessions(ctx, sessionIDs)
}
+func isInputCapableSession(session *models.TaskSession) bool {
+ return session != nil && (session.State == models.TaskSessionStateRunning || session.State == models.TaskSessionStateWaitingForInput)
+}
+
+func taskPendingActionPtr(sessions []*models.TaskSession, actions map[string]models.TaskPendingAction) *string {
+ var clarification bool
+ for _, session := range sessions {
+ if !isInputCapableSession(session) {
+ continue
+ }
+ switch actions[session.ID] {
+ case models.TaskPendingActionPermission:
+ value := string(models.TaskPendingActionPermission)
+ return &value
+ case models.TaskPendingActionClarification:
+ clarification = true
+ }
+ }
+ if clarification {
+ value := string(models.TaskPendingActionClarification)
+ return &value
+ }
+ return nil
+}
+
func pendingActionPtr(
sessionID *string,
pendingActionsBySession map[string]models.TaskPendingAction,
diff --git a/apps/backend/internal/task/handlers/task_http_handlers_test.go b/apps/backend/internal/task/handlers/task_http_handlers_test.go
index 821b4cc376..9c94dc89cc 100644
--- a/apps/backend/internal/task/handlers/task_http_handlers_test.go
+++ b/apps/backend/internal/task/handlers/task_http_handlers_test.go
@@ -76,6 +76,23 @@ func TestQuickChatRequestBuildRepositoriesAcceptsPluralInput(t *testing.T) {
assert.Equal(t, service.TaskRepositoryInput{RepositoryID: "repo-2", BaseBranch: "develop"}, repos[1])
}
+func TestTaskPendingActionPtrAggregatesInputCapableSessions(t *testing.T) {
+ sessions := []*models.TaskSession{
+ {ID: "running", State: models.TaskSessionStateRunning},
+ {ID: "waiting", State: models.TaskSessionStateWaitingForInput},
+ {ID: "starting", State: models.TaskSessionStateStarting},
+ }
+ actions := map[string]models.TaskPendingAction{
+ "running": models.TaskPendingActionClarification,
+ "waiting": models.TaskPendingActionPermission,
+ "starting": models.TaskPendingActionPermission,
+ }
+
+ got := taskPendingActionPtr(sessions, actions)
+ require.NotNil(t, got)
+ assert.Equal(t, "permission", *got)
+}
+
func TestQuickChatResolveParamsForcesWorktreeForRepositoryContext(t *testing.T) {
defaultExecutor := models.ExecutorIDLocal
body := httpStartQuickChatRequest{
diff --git a/apps/backend/internal/task/models/models.go b/apps/backend/internal/task/models/models.go
index e31f161057..df7f37b091 100644
--- a/apps/backend/internal/task/models/models.go
+++ b/apps/backend/internal/task/models/models.go
@@ -661,8 +661,8 @@ const (
PermissionStatusExpired PermissionStatus = "expired"
)
-// TaskPendingAction is the compact task-list projection for a primary session
-// blocked on user input.
+// TaskPendingAction is the compact task-list projection for a session blocked
+// on user input.
type TaskPendingAction string
const (
diff --git a/apps/backend/internal/task/service/service_events.go b/apps/backend/internal/task/service/service_events.go
index 037d880727..f1ef599a71 100644
--- a/apps/backend/internal/task/service/service_events.go
+++ b/apps/backend/internal/task/service/service_events.go
@@ -243,6 +243,7 @@ func (s *Service) addTaskSessionEventFields(ctx context.Context, taskID string,
data["session_count"] = count
}
}
+ s.addTaskPendingActionEventField(ctx, taskID, data)
primarySessionInfoMap, err := s.GetPrimarySessionInfoForTasks(ctx, []string{taskID})
if err != nil {
@@ -283,6 +284,44 @@ func (s *Service) addTaskSessionEventFields(ctx context.Context, taskID string,
}
}
+func (s *Service) addTaskPendingActionEventField(ctx context.Context, taskID string, data map[string]interface{}) {
+ sessions, err := s.sessions.ListActiveTaskSessionsByTaskID(ctx, taskID)
+ if err != nil {
+ s.logger.Warn("failed to list sessions for task pending action", zap.String("task_id", taskID), zap.Error(err))
+ return
+ }
+ sessionIDs := make([]string, 0, len(sessions))
+ for _, session := range sessions {
+ if session != nil && (session.State == models.TaskSessionStateRunning || session.State == models.TaskSessionStateWaitingForInput) {
+ sessionIDs = append(sessionIDs, session.ID)
+ }
+ }
+ if len(sessionIDs) == 0 {
+ data["task_pending_action"] = nil
+ return
+ }
+ actions, err := s.GetPendingActionsForSessions(ctx, sessionIDs)
+ if err != nil {
+ s.logger.Warn("failed to load task pending action", zap.String("task_id", taskID), zap.Error(err))
+ return
+ }
+ var clarification bool
+ for _, sessionID := range sessionIDs {
+ switch actions[sessionID] {
+ case models.TaskPendingActionPermission:
+ data["task_pending_action"] = string(models.TaskPendingActionPermission)
+ return
+ case models.TaskPendingActionClarification:
+ clarification = true
+ }
+ }
+ if clarification {
+ data["task_pending_action"] = string(models.TaskPendingActionClarification)
+ } else {
+ data["task_pending_action"] = nil
+ }
+}
+
func (s *Service) addPrimarySessionPendingActionEventField(ctx context.Context, taskID string, sessionInfo *models.TaskSession, data map[string]interface{}) {
if sessionInfo.State != models.TaskSessionStateWaitingForInput {
data["primary_session_pending_action"] = nil
diff --git a/apps/backend/internal/task/service/service_events_test.go b/apps/backend/internal/task/service/service_events_test.go
index e036d8fd2f..4affc2403d 100644
--- a/apps/backend/internal/task/service/service_events_test.go
+++ b/apps/backend/internal/task/service/service_events_test.go
@@ -47,6 +47,14 @@ func (r primarySessionInfoRepository) GetSessionCountsByTaskIDs(ctx context.Cont
return map[string]int{}, nil
}
+func (r primarySessionInfoRepository) ListActiveTaskSessionsByTaskID(_ context.Context, taskID string) ([]*models.TaskSession, error) {
+ info := r.info[taskID]
+ if info == nil {
+ return nil, nil
+ }
+ return []*models.TaskSession{info}, nil
+}
+
// TestPublishTaskUpdated_FallbackRepositoryID exercises the DB fallback in
// taskRepositoriesForEvent: orchestrator-originated events load the task via the
// raw repo.GetTask, which does not populate Repositories. The publisher must
@@ -211,6 +219,63 @@ func TestPublishTaskUpdated_EmitsPrimarySessionPendingAction(t *testing.T) {
}
}
+func TestPublishTaskUpdated_EmitsTaskPendingPermissionFromSecondarySession(t *testing.T) {
+ svc, eventBus, repo := createTestService(t)
+ ctx := context.Background()
+ now := time.Now().UTC()
+
+ requireTaskEventFixture(t, ctx, repo)
+ task := &models.Task{ID: "task-1", WorkspaceID: "ws-1", WorkflowID: "wf-1", WorkflowStepID: "step-1", Title: "T", Priority: "medium"}
+ for _, session := range []*models.TaskSession{
+ {ID: "primary", TaskID: task.ID, State: models.TaskSessionStateRunning, IsPrimary: true, StartedAt: now, UpdatedAt: now},
+ {ID: "secondary", TaskID: task.ID, State: models.TaskSessionStateWaitingForInput, StartedAt: now, UpdatedAt: now},
+ {ID: "stale-starting", TaskID: task.ID, State: models.TaskSessionStateStarting, StartedAt: now, UpdatedAt: now},
+ } {
+ if err := repo.CreateTaskSession(ctx, session); err != nil {
+ t.Fatalf("CreateTaskSession(%s): %v", session.ID, err)
+ }
+ }
+ for _, turn := range []*models.Turn{
+ {ID: "primary-turn", TaskSessionID: "primary", TaskID: task.ID},
+ {ID: "secondary-turn", TaskSessionID: "secondary", TaskID: task.ID},
+ {ID: "stale-turn", TaskSessionID: "stale-starting", TaskID: task.ID},
+ } {
+ if err := repo.CreateTurn(ctx, turn); err != nil {
+ t.Fatalf("CreateTurn(%s): %v", turn.ID, err)
+ }
+ }
+ for _, message := range []*models.Message{
+ {ID: "primary-clarification", TaskSessionID: "primary", TaskID: task.ID, TurnID: "primary-turn", AuthorType: models.MessageAuthorAgent, Type: models.MessageTypeClarificationRequest, Metadata: map[string]interface{}{"status": "pending"}, CreatedAt: now},
+ {ID: "secondary-permission", TaskSessionID: "secondary", TaskID: task.ID, TurnID: "secondary-turn", AuthorType: models.MessageAuthorAgent, Type: models.MessageTypePermissionRequest, Metadata: map[string]interface{}{"status": "pending"}, CreatedAt: now},
+ {ID: "stale-clarification", TaskSessionID: "stale-starting", TaskID: task.ID, TurnID: "stale-turn", AuthorType: models.MessageAuthorAgent, Type: models.MessageTypeClarificationRequest, Metadata: map[string]interface{}{"status": "pending"}, CreatedAt: now},
+ } {
+ if err := repo.CreateMessage(ctx, message); err != nil {
+ t.Fatalf("CreateMessage(%s): %v", message.ID, err)
+ }
+ }
+ eventBus.ClearEvents()
+
+ svc.PublishTaskUpdated(ctx, task)
+
+ data := singlePublishedEventData(t, eventBus)
+ if value := data["task_pending_action"]; value != "permission" {
+ t.Fatalf("task_pending_action = %#v, want permission", value)
+ }
+}
+
+func requireTaskEventFixture(t *testing.T, ctx context.Context, repo taskEventTestRepository) {
+ t.Helper()
+ if err := repo.CreateWorkspace(ctx, &models.Workspace{ID: "ws-1", Name: "Workspace"}); err != nil {
+ t.Fatalf("CreateWorkspace: %v", err)
+ }
+ if err := repo.CreateWorkflow(ctx, &models.Workflow{ID: "wf-1", WorkspaceID: "ws-1", Name: "WF"}); err != nil {
+ t.Fatalf("CreateWorkflow: %v", err)
+ }
+ if err := repo.CreateTask(ctx, &models.Task{ID: "task-1", WorkspaceID: "ws-1", WorkflowID: "wf-1", WorkflowStepID: "step-1", Title: "T", Priority: "medium"}); err != nil {
+ t.Fatalf("CreateTask: %v", err)
+ }
+}
+
func TestAddTaskSessionEventFields_EmitsNullPrimarySessionStateWhenEmpty(t *testing.T) {
svc, _, _ := createTestService(t)
svc.sessions = primarySessionInfoRepository{
diff --git a/apps/web/app/tasks/[id]/kanban-task-shell.tsx b/apps/web/app/tasks/[id]/kanban-task-shell.tsx
index 64821754be..c9c0f03f95 100644
--- a/apps/web/app/tasks/[id]/kanban-task-shell.tsx
+++ b/apps/web/app/tasks/[id]/kanban-task-shell.tsx
@@ -100,25 +100,39 @@ export function KanbanTaskShell({
// background-running task reads distinctly and never as done (§spec:task-level-indicator),
// and carry the sidebar's rich "needs me" reading — pending clarification /
// permission — so the header distinguishes waiting-for-input (§spec:waiting-for-input-parity).
+function simpleTaskHeaderData(task: Task | null) {
+ return {
+ primarySessionId: task?.primary_session_id,
+ pendingFallback: {
+ taskId: task?.id,
+ taskPendingAction: task?.task_pending_action,
+ primarySessionState: task?.primary_session_state,
+ primarySessionPendingAction: task?.primary_session_pending_action,
+ },
+ identifier: task?.id?.slice(0, 8),
+ title: task?.title ?? "Loading...",
+ state: task?.state ?? null,
+ foregroundActivity: task?.foreground_activity,
+ };
+}
+
function SimpleTaskHeaderRow({ task }: { task: Task | null }) {
- const pendingInput = useTaskPendingInput(task?.primary_session_id, {
- primarySessionState: task?.primary_session_state,
- primarySessionPendingAction: task?.primary_session_pending_action,
- });
+ const data = simpleTaskHeaderData(task);
+ const pendingInput = useTaskPendingInput(data.primarySessionId, data.pendingFallback);
return (
diff --git a/apps/web/app/tasks/tasks-list-view.tsx b/apps/web/app/tasks/tasks-list-view.tsx
index 09fe92d950..a49bd91847 100644
--- a/apps/web/app/tasks/tasks-list-view.tsx
+++ b/apps/web/app/tasks/tasks-list-view.tsx
@@ -384,6 +384,8 @@ function TaskListRow({
// boot-payload snapshot fallback) instead of collapsing to the coarse state
// (§spec:waiting-for-input-parity).
const pendingInput = useTaskPendingInput(task.primary_session_id, {
+ taskId: task.id,
+ taskPendingAction: task.task_pending_action,
primarySessionState: task.primary_session_state,
primarySessionPendingAction: task.primary_session_pending_action,
});
diff --git a/apps/web/components/kanban-card-content.tsx b/apps/web/components/kanban-card-content.tsx
index e85b2ecb68..841827f6d8 100644
--- a/apps/web/components/kanban-card-content.tsx
+++ b/apps/web/components/kanban-card-content.tsx
@@ -265,6 +265,8 @@ function KanbanCardActions({
const debugEnabled = isDebug();
const effectiveMenuOpen = menuOpen || Boolean(isDeleting) || Boolean(isArchiving);
const pendingInput = useTaskPendingInput(task.primarySessionId, {
+ taskId: task.id,
+ taskPendingAction: task.taskPendingAction,
primarySessionState: task.primarySessionState,
primarySessionPendingAction: task.primarySessionPendingAction,
});
diff --git a/apps/web/components/kanban-card.tsx b/apps/web/components/kanban-card.tsx
index 6166618da9..ae3a6d0730 100644
--- a/apps/web/components/kanban-card.tsx
+++ b/apps/web/components/kanban-card.tsx
@@ -54,6 +54,7 @@ export interface Task {
*/
primarySessionState?: string | null;
primarySessionPendingAction?: TaskPendingAction | null;
+ taskPendingAction?: TaskPendingAction | null;
/**
* Task-level MOST-ACTIVE-WINS activity aggregate (§spec:task-level-indicator);
* undefined/null when no session is running. Drives the background-running
diff --git a/apps/web/components/kanban/graph2-step-node.tsx b/apps/web/components/kanban/graph2-step-node.tsx
index 0f209e1140..16a0bd068f 100644
--- a/apps/web/components/kanban/graph2-step-node.tsx
+++ b/apps/web/components/kanban/graph2-step-node.tsx
@@ -102,6 +102,8 @@ export function Graph2StepNode({
const router = useRouter();
const [isHovered, setIsHovered] = useState(false);
const pendingInput = useTaskPendingInput(task.primarySessionId, {
+ taskId: task.id,
+ taskPendingAction: task.taskPendingAction,
primarySessionState: task.primarySessionState,
primarySessionPendingAction: task.primarySessionPendingAction,
});
diff --git a/apps/web/components/kanban/swimlane-graph-content.tsx b/apps/web/components/kanban/swimlane-graph-content.tsx
index 2d6db040ed..cf4ecf87c8 100644
--- a/apps/web/components/kanban/swimlane-graph-content.tsx
+++ b/apps/web/components/kanban/swimlane-graph-content.tsx
@@ -75,6 +75,8 @@ function DraggableTaskChip({
});
const isPreviewed = useAppStore((state) => state.kanbanPreviewedTaskId === task.id);
const pendingInput = useTaskPendingInput(task.primarySessionId, {
+ taskId: task.id,
+ taskPendingAction: task.taskPendingAction,
primarySessionState: task.primarySessionState,
primarySessionPendingAction: task.primarySessionPendingAction,
});
@@ -111,6 +113,8 @@ function DraggableTaskChip({
function TaskChipPreview({ task }: { task: Task }) {
const pendingInput = useTaskPendingInput(task.primarySessionId, {
+ taskId: task.id,
+ taskPendingAction: task.taskPendingAction,
primarySessionState: task.primarySessionState,
primarySessionPendingAction: task.primarySessionPendingAction,
});
diff --git a/apps/web/components/task/TaskHeader.test.tsx b/apps/web/components/task/TaskHeader.test.tsx
index d4df9c70af..c74dd8f3e4 100644
--- a/apps/web/components/task/TaskHeader.test.tsx
+++ b/apps/web/components/task/TaskHeader.test.tsx
@@ -6,6 +6,9 @@ import { describe, it, expect, afterEach } from "vitest";
import { render, screen, cleanup } from "@testing-library/react";
import { TaskHeader } from "./TaskHeader";
+const WAITING_FOR_INPUT = "WAITING_FOR_INPUT";
+const WAITING_FOR_INPUT_LABEL = "Waiting for input";
+
afterEach(cleanup);
describe("TaskHeader", () => {
@@ -53,21 +56,21 @@ describe("TaskHeader", () => {
// §spec:waiting-for-input-parity: the header badge carries the sidebar's rich
// "needs me" reading, distinct from done and from running.
it("reads a plain WAITING_FOR_INPUT state as 'Waiting for input'", () => {
- render();
- expect(screen.getByText("Waiting for input")).toBeTruthy();
- expect(screen.queryByText("WAITING_FOR_INPUT")).toBeNull();
+ render();
+ expect(screen.getByText(WAITING_FOR_INPUT_LABEL)).toBeTruthy();
+ expect(screen.queryByText(WAITING_FOR_INPUT)).toBeNull();
});
it("reads a pending clarification as 'Waiting for input' even over a non-waiting coarse state", () => {
render();
- expect(screen.getByText("Waiting for input")).toBeTruthy();
+ expect(screen.getByText(WAITING_FOR_INPUT_LABEL)).toBeTruthy();
});
it("reads a pending permission as 'Permission requested', taking precedence over clarification", () => {
render(
,
@@ -75,16 +78,41 @@ describe("TaskHeader", () => {
expect(screen.getByText("Permission requested")).toBeTruthy();
});
- it("keeps live activity ahead of a waiting flag in the badge", () => {
+ it("lets a pending permission take precedence over live activity in the badge", () => {
render(
,
);
+ expect(screen.getByText("Permission requested")).toBeTruthy();
+ expect(screen.queryByText("Background running")).toBeNull();
+ });
+
+ it("lets a pending clarification take precedence over generating in the badge", () => {
+ render(
+ ,
+ );
+ expect(screen.getByText(WAITING_FOR_INPUT_LABEL)).toBeTruthy();
+ expect(screen.queryByText("Generating")).toBeNull();
+ });
+
+ it("lets generating activity win over a coarse waiting state without pending input", () => {
+ render();
+ expect(screen.getByText("Generating")).toBeTruthy();
+ expect(screen.queryByText(WAITING_FOR_INPUT_LABEL)).toBeNull();
+ });
+
+ it("lets background activity win over a coarse waiting state without pending input", () => {
+ render();
expect(screen.getByText("Background running")).toBeTruthy();
- expect(screen.queryByText("Permission requested")).toBeNull();
+ expect(screen.queryByText(WAITING_FOR_INPUT_LABEL)).toBeNull();
});
});
diff --git a/apps/web/components/task/TaskHeader.tsx b/apps/web/components/task/TaskHeader.tsx
index cd32e7d355..616c538e28 100644
--- a/apps/web/components/task/TaskHeader.tsx
+++ b/apps/web/components/task/TaskHeader.tsx
@@ -42,22 +42,20 @@ export type TaskHeaderProps = {
hasPendingPermission?: boolean;
};
-// The badge reflects the task-level activity aggregate ABOVE the coarse workflow
-// state (§spec:task-level-indicator), mirroring getTaskStateIcon: background-running
-// and generating each read distinctly and never fall back to a done coarse state.
-// The waiting-for-input variants (§spec:waiting-for-input-parity) sit below live
-// activity but above the coarse state, with pending-permission taking precedence
-// over the generic waiting/clarification reading.
+// Pending input is the most actionable state and sits above live activity, with
+// pending permission taking precedence over clarification. Without pending input,
+// the task-level activity aggregate sits above the coarse workflow state.
function resolveBadgeLabel(
state: string | null | undefined,
foregroundActivity: ForegroundActivity | null | undefined,
hasPendingClarification: boolean,
hasPendingPermission: boolean,
): string | null {
- if (foregroundActivity === "background") return "Background running";
- if (foregroundActivity === "generating") return "Generating";
if (hasPendingPermission) return "Permission requested";
- if (hasPendingClarification || state === "WAITING_FOR_INPUT") return "Waiting for input";
+ if (hasPendingClarification) return "Waiting for input";
+ if (foregroundActivity === "generating") return "Generating";
+ if (foregroundActivity === "background") return "Background running";
+ if (state === "WAITING_FOR_INPUT") return "Waiting for input";
return state ?? null;
}
diff --git a/apps/web/components/task/mobile/mobile-sessions-section.test.tsx b/apps/web/components/task/mobile/mobile-sessions-section.test.tsx
index dfb5743764..50e27963e6 100644
--- a/apps/web/components/task/mobile/mobile-sessions-section.test.tsx
+++ b/apps/web/components/task/mobile/mobile-sessions-section.test.tsx
@@ -49,7 +49,9 @@ const PILL_TESTID = "mobile-sessions-pill";
const ICON_CIRCLE_CHECK = "tabler-icon-circle-check";
const SESSION_A = "session-a";
const SESSION_BG = "session-bg";
+const TASK_ID = "task-1";
const START_TIME = "2026-01-01T00:00:00Z";
+const SECOND_TIME = "2026-01-01T00:01:00Z";
function session(
id: string,
@@ -59,7 +61,7 @@ function session(
): TaskSession {
return {
id,
- task_id: "task-1",
+ task_id: TASK_ID,
agent_profile_id: profileId,
state: "WAITING_FOR_INPUT",
started_at: startedAt,
@@ -84,7 +86,7 @@ beforeEach(() => {
mocks.activeSessionId = SESSION_A;
mocks.sessions = [
session(SESSION_A, "profile-a", START_TIME),
- session("session-b", "profile-b", "2026-01-01T00:01:00Z"),
+ session("session-b", "profile-b", SECOND_TIME),
];
mocks.agentProfiles = [
profile("profile-a", "Alpha", "claude"),
@@ -92,9 +94,9 @@ beforeEach(() => {
];
});
-describe("MobileSessionsPicker", () => {
+describe("MobileSessionsPicker selection", () => {
it("uses the effective layout session instead of a stale store session", () => {
- render();
+ render();
expect(
screen.getByRole("button", { name: "Active session: Beta. Tap to switch." }),
@@ -111,13 +113,15 @@ describe("MobileSessionsPicker", () => {
it("shows the effective session agent icon beside its label", () => {
mocks.activeSessionId = "session-b";
- render();
+ render();
const pill = screen.getByTestId(PILL_TESTID);
expect(within(pill).getByTestId("mobile-session-agent-icon")).toBeTruthy();
expect(within(pill).getByTestId("agent-logo-codex")).toBeTruthy();
});
+});
+describe("MobileSessionsPicker activity precedence", () => {
it("renders background-running distinctly — matching desktop, not a done check", () => {
// §spec:session-level-truth / §spec:state-vocabulary: a session whose
// foreground turn is idle while spawned background work runs (RUNNING +
@@ -132,7 +136,7 @@ describe("MobileSessionsPicker", () => {
state: "WAITING_FOR_INPUT",
foreground_activity: "background",
}),
- session("session-gen", "profile-b", "2026-01-01T00:01:00Z", {
+ session("session-gen", "profile-b", SECOND_TIME, {
state: "RUNNING",
foreground_activity: "generating",
}),
@@ -140,7 +144,7 @@ describe("MobileSessionsPicker", () => {
state: "COMPLETED",
}),
];
- render();
+ render();
fireEvent.click(screen.getByTestId(PILL_TESTID));
const bg = screen.getByTestId("mobile-session-state-session-bg");
@@ -164,7 +168,7 @@ describe("MobileSessionsPicker", () => {
expect(svgClass(done)).toContain(ICON_CIRCLE_CHECK);
});
- it("keeps the background-running label while the foreground has a pending prompt", () => {
+ it("shows pending clarification instead of background-running", () => {
mocks.activeSessionId = SESSION_BG;
mocks.sessions = [
session(SESSION_BG, "profile-a", START_TIME, {
@@ -176,11 +180,68 @@ describe("MobileSessionsPicker", () => {
[SESSION_BG]: [{ type: "clarification_request", metadata: { status: "pending" } }],
};
- render();
+ render();
+ fireEvent.click(screen.getByTestId(PILL_TESTID));
+
+ const state = screen.getByTestId("mobile-session-state-session-bg");
+ expect(state.textContent).toMatch(/waiting for input/i);
+ expect(state.querySelector("svg")?.getAttribute("class")).toContain(
+ "tabler-icon-message-question",
+ );
+ mocks.messagesBySession = {};
+ });
+
+ it("shows pending permission ahead of clarification and generating", () => {
+ mocks.activeSessionId = SESSION_A;
+ mocks.sessions = [
+ session(SESSION_A, "profile-a", START_TIME, {
+ state: "RUNNING",
+ foreground_activity: "generating",
+ }),
+ ];
+ mocks.messagesBySession = {
+ [SESSION_A]: [
+ { type: "clarification_request", metadata: { status: "pending" } },
+ { type: "permission_request", metadata: { status: "pending" } },
+ ],
+ };
+
+ render();
+ fireEvent.click(screen.getByTestId(PILL_TESTID));
+
+ const state = screen.getByTestId("mobile-session-state-session-a");
+ expect(state.textContent).toMatch(/permission requested/i);
+ expect(state.querySelector("svg")?.getAttribute("class")).toContain(
+ "tabler-icon-shield-question",
+ );
+ mocks.messagesBySession = {};
+ });
+});
+
+describe("MobileSessionsPicker pending lifecycle", () => {
+ it("does not let stale pending input mask starting or terminal labels", () => {
+ mocks.activeSessionId = SESSION_A;
+ mocks.sessions = [
+ session(SESSION_A, "profile-a", START_TIME, {
+ state: "STARTING",
+ foreground_activity: "background",
+ }),
+ session("session-done", "profile-b", SECOND_TIME, {
+ state: "COMPLETED",
+ foreground_activity: "generating",
+ }),
+ ];
+ mocks.messagesBySession = {
+ [SESSION_A]: [{ type: "permission_request", metadata: { status: "pending" } }],
+ "session-done": [{ type: "clarification_request", metadata: { status: "pending" } }],
+ };
+
+ render();
fireEvent.click(screen.getByTestId(PILL_TESTID));
- expect(screen.getByTestId("mobile-session-state-session-bg").textContent).toMatch(
- /background/i,
+ expect(screen.getByTestId("mobile-session-state-session-a").textContent).toMatch(/starting/i);
+ expect(screen.getByTestId("mobile-session-state-session-done").textContent).toMatch(
+ /completed/i,
);
mocks.messagesBySession = {};
});
@@ -194,7 +255,7 @@ describe("MobileSessionsPicker", () => {
session("session-clar", "profile-a", START_TIME, {
state: "WAITING_FOR_INPUT",
}),
- session("session-perm", "profile-b", "2026-01-01T00:01:00Z", {
+ session("session-perm", "profile-b", SECOND_TIME, {
state: "WAITING_FOR_INPUT",
}),
];
@@ -202,7 +263,7 @@ describe("MobileSessionsPicker", () => {
"session-clar": [{ type: "clarification_request", metadata: { status: "pending" } }],
"session-perm": [{ type: "permission_request", metadata: { status: "pending" } }],
};
- render();
+ render();
fireEvent.click(screen.getByTestId(PILL_TESTID));
const clar = screen.getByTestId("mobile-session-state-session-clar");
diff --git a/apps/web/components/task/mobile/mobile-sessions-section.tsx b/apps/web/components/task/mobile/mobile-sessions-section.tsx
index a7bf3860b3..1891e4fb08 100644
--- a/apps/web/components/task/mobile/mobile-sessions-section.tsx
+++ b/apps/web/components/task/mobile/mobile-sessions-section.tsx
@@ -91,14 +91,12 @@ function sessionStateLabel(
foregroundActivity: ForegroundActivity | null,
pending: PendingInput,
): string {
- if (
- (state === "RUNNING" || state === "WAITING_FOR_INPUT") &&
- foregroundActivity === "background"
- ) {
- return BACKGROUND_RUNNING_LABEL;
+ const canRequestInput = state === "RUNNING" || state === "WAITING_FOR_INPUT";
+ if (canRequestInput && pending.permission) return "Permission requested";
+ if (canRequestInput && pending.clarification) {
+ return formatTaskSessionStateLabel("WAITING_FOR_INPUT");
}
- if (pending.permission) return "Permission requested";
- if (pending.clarification) return formatTaskSessionStateLabel("WAITING_FOR_INPUT");
+ if (canRequestInput && foregroundActivity === "background") return BACKGROUND_RUNNING_LABEL;
return formatTaskSessionStateLabel(state);
}
diff --git a/apps/web/components/task/mobile/session-task-switcher-sheet-helpers.ts b/apps/web/components/task/mobile/session-task-switcher-sheet-helpers.ts
new file mode 100644
index 0000000000..b016afebcb
--- /dev/null
+++ b/apps/web/components/task/mobile/session-task-switcher-sheet-helpers.ts
@@ -0,0 +1,32 @@
+import { toKanbanTask } from "@/lib/kanban/map-task";
+import type { WorkflowSnapshot } from "@/lib/types/http";
+
+// Map workflow snapshot to kanban state on workspace switch.
+export function mapSnapshotToKanban(snapshot: WorkflowSnapshot, newWorkflowId: string) {
+ return {
+ workflowId: newWorkflowId,
+ isLoading: false,
+ steps: snapshot.steps.map((step) => ({
+ id: step.id,
+ title: step.name,
+ color: step.color,
+ position: step.position,
+ events: step.events,
+ // Preserve optional step capabilities until the next full reload.
+ allow_manual_move: step.allow_manual_move,
+ prompt: step.prompt,
+ is_start_step: step.is_start_step,
+ show_in_command_panel: step.show_in_command_panel,
+ agent_profile_id: step.agent_profile_id,
+ })),
+ tasks: snapshot.tasks.map(toKanbanTask),
+ };
+}
+
+export function sortByUpdatedAtDesc(items: T[]): T[] {
+ return [...items].sort((a, b) => {
+ const aDate = a.updated_at ? new Date(a.updated_at).getTime() : 0;
+ const bDate = b.updated_at ? new Date(b.updated_at).getTime() : 0;
+ return bDate - aDate;
+ });
+}
diff --git a/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.test.ts b/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.test.ts
index 43cf9505bf..b65f7c9931 100644
--- a/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.test.ts
+++ b/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.test.ts
@@ -1,5 +1,11 @@
import { describe, expect, it } from "vitest";
import { toSheetItem } from "./session-task-switcher-sheet-hooks";
+import {
+ sessionId as toSessionId,
+ taskId as toTaskId,
+ type Message,
+ type TaskSession,
+} from "@/lib/types/http";
type SheetTask = Parameters[0];
type SheetCtx = Parameters[1];
@@ -30,6 +36,29 @@ function task(overrides: Partial = {}): SheetTask {
} as SheetTask;
}
+function session(id: string, state: TaskSession["state"]): TaskSession {
+ return {
+ id: toSessionId(id),
+ task_id: toTaskId("t1"),
+ state,
+ started_at: "2026-07-22T00:00:00Z",
+ updated_at: "2026-07-22T00:00:00Z",
+ };
+}
+
+function pendingPermission(id: string, sessionId: string): Message {
+ return {
+ id,
+ session_id: toSessionId(sessionId),
+ task_id: toTaskId("t1"),
+ author_type: "agent",
+ content: "Allow?",
+ type: "permission_request",
+ metadata: { status: "pending" },
+ created_at: "2026-07-22T00:00:00Z",
+ };
+}
+
describe("toSheetItem", () => {
// The mobile task-switcher row must read the same task-level most-active-wins
// aggregate the desktop sidebar and board card read, so a background-running
@@ -48,4 +77,30 @@ describe("toSheetItem", () => {
const item = toSheetItem(task(), emptyCtx());
expect(item.foregroundActivity).toBeUndefined();
});
+
+ it("finds pending permission in a secondary waiting session", () => {
+ const ctx = emptyCtx();
+ ctx.sessionsByTaskId.t1 = [
+ session("primary", "STARTING"),
+ session("secondary", "WAITING_FOR_INPUT"),
+ ];
+ ctx.messagesBySession.primary = [];
+ ctx.messagesBySession.secondary = [pendingPermission("permission", "secondary")];
+
+ const item = toSheetItem(task({ primarySessionId: "primary" }), ctx);
+
+ expect(item.hasPendingPermission).toBe(true);
+ expect(item.hasPendingClarification).toBe(false);
+ });
+
+ it("excludes stale pending permission from a starting session", () => {
+ const ctx = emptyCtx();
+ ctx.sessionsByTaskId.t1 = [session("starting", "STARTING")];
+ ctx.messagesBySession.starting = [pendingPermission("stale-permission", "starting")];
+
+ const item = toSheetItem(task({ primarySessionId: "starting" }), ctx);
+
+ expect(item.hasPendingPermission).toBe(false);
+ expect(item.hasPendingClarification).toBe(false);
+ });
});
diff --git a/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.ts b/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.ts
index 77253c64f6..aadd7f1d19 100644
--- a/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.ts
+++ b/apps/web/components/task/mobile/session-task-switcher-sheet-hooks.ts
@@ -15,7 +15,7 @@ import {
hasPendingClarification,
hasPendingPermissionRequest,
} from "@/lib/utils/pending-clarification";
-import { toKanbanTask, workspaceModeFromMetadata } from "@/lib/kanban/map-task";
+import { workspaceModeFromMetadata } from "@/lib/kanban/map-task";
import {
repositoryId as toRepositoryId,
type TaskState,
@@ -23,7 +23,6 @@ import {
type TaskSessionState,
type Repository,
type Task,
- type WorkflowSnapshot,
type Message,
} from "@/lib/types/http";
import type { KanbanState } from "@/lib/state/slices";
@@ -35,37 +34,7 @@ import {
agentErrorAcknowledgementSessionIds,
usePersistResolvedAgentErrorAcknowledgements,
} from "../use-agent-error-acknowledgements";
-
-// Map workflow snapshot to kanban state on workspace switch.
-function mapSnapshotToKanban(snapshot: WorkflowSnapshot, newWorkflowId: string) {
- return {
- workflowId: newWorkflowId,
- isLoading: false,
- steps: snapshot.steps.map((step) => ({
- id: step.id,
- title: step.name,
- color: step.color,
- position: step.position,
- events: step.events,
- // Carry optional step capabilities forward so downstream UI doesn't see
- // them as missing after a workspace switch (until a full reload).
- allow_manual_move: step.allow_manual_move,
- prompt: step.prompt,
- is_start_step: step.is_start_step,
- show_in_command_panel: step.show_in_command_panel,
- agent_profile_id: step.agent_profile_id,
- })),
- tasks: snapshot.tasks.map(toKanbanTask),
- };
-}
-
-function sortByUpdatedAtDesc(items: T[]): T[] {
- return [...items].sort((a, b) => {
- const aDate = a.updated_at ? new Date(a.updated_at).getTime() : 0;
- const bDate = b.updated_at ? new Date(b.updated_at).getTime() : 0;
- return bDate - aDate;
- });
-}
+import { mapSnapshotToKanban, sortByUpdatedAtDesc } from "./session-task-switcher-sheet-helpers";
type SheetItemCtx = {
repositoryPathsById: Map;
@@ -92,7 +61,11 @@ export function toSheetItem(
);
const resolvedSessionState =
sessionInfo.sessionState ?? (task.primarySessionState as TaskSessionState | undefined);
- const pending = pendingFlagsForTask(task, resolvedSessionState, ctx.messagesBySession);
+ const pending = pendingFlagsForTask(
+ task,
+ ctx.sessionsByTaskId[task.id] ?? [],
+ ctx.messagesBySession,
+ );
return {
id: task.id,
title: task.title,
@@ -128,24 +101,27 @@ export function toSheetItem(
}
function pendingFlagsForTask(
- task: Pick,
- primarySessionState: TaskSessionState | undefined,
+ task: Pick,
+ sessions: TaskSession[],
messagesBySession: Record,
): { clarification: boolean; permission: boolean } {
- if (!task.primarySessionId) return { clarification: false, permission: false };
- const messages = messagesBySession[task.primarySessionId];
- if (messages !== undefined) {
- return {
- clarification: hasPendingClarification(messages),
- permission: hasPendingPermissionRequest(messages),
- };
- }
- if (primarySessionState !== "WAITING_FOR_INPUT") {
- return { clarification: false, permission: false };
+ let clarification = false;
+ let permission = false;
+ let hasUnloadedMessages = false;
+ for (const session of sessions) {
+ if (session.state !== "RUNNING" && session.state !== "WAITING_FOR_INPUT") continue;
+ const messages = messagesBySession[session.id];
+ if (messages === undefined) {
+ hasUnloadedMessages = true;
+ continue;
+ }
+ clarification ||= hasPendingClarification(messages);
+ permission ||= hasPendingPermissionRequest(messages);
}
+ if (sessions.length > 0 && !hasUnloadedMessages) return { clarification, permission };
return {
- clarification: task.primarySessionPendingAction === "clarification",
- permission: task.primarySessionPendingAction === "permission",
+ clarification: clarification || task.taskPendingAction === "clarification",
+ permission: permission || task.taskPendingAction === "permission",
};
}
@@ -326,11 +302,17 @@ function mergeSessionFields(
primarySessionId: resolvePrimarySessionId(task, existing, taskSessionId),
primarySessionState: resolvePrimarySessionState(task, existing),
primarySessionPendingAction: resolvePrimarySessionPendingAction(task, existing),
+ taskPendingAction: resolveTaskPendingAction(task, existing),
sessionCount: resolveSessionCount(task, existing, taskSessionId),
reviewStatus: resolveReviewStatus(task, existing),
};
}
+function resolveTaskPendingAction(task: Task, existing: KanbanState["tasks"][number] | undefined) {
+ if ("task_pending_action" in task) return task.task_pending_action ?? undefined;
+ return existing?.taskPendingAction ?? undefined;
+}
+
function resolvePrimarySessionId(
task: Task,
existing: KanbanState["tasks"][number] | undefined,
diff --git a/apps/web/components/task/session-reopen-menu.test.tsx b/apps/web/components/task/session-reopen-menu.test.tsx
index 06136e7bfe..000d54b05b 100644
--- a/apps/web/components/task/session-reopen-menu.test.tsx
+++ b/apps/web/components/task/session-reopen-menu.test.tsx
@@ -24,6 +24,11 @@ describe("shouldShowReopenStateIcon", () => {
expect(shouldShowReopenStateIcon("STARTING", null)).toBe(false);
});
+ it("ignores stale pending input while a session is still STARTING", () => {
+ expect(shouldShowReopenStateIcon("STARTING", null, true, false)).toBe(false);
+ expect(shouldShowReopenStateIcon("STARTING", null, false, true)).toBe(false);
+ });
+
it("now surfaces the waiting-for-input affordance (§spec:waiting-for-input-parity)", () => {
// Previously WAITING_FOR_INPUT was silent; it now shows the "needs me" icon
// so the reopen menu distinguishes waiting from done and running.
diff --git a/apps/web/components/task/session-reopen-menu.tsx b/apps/web/components/task/session-reopen-menu.tsx
index d2d6b254dd..0b88dae5b8 100644
--- a/apps/web/components/task/session-reopen-menu.tsx
+++ b/apps/web/components/task/session-reopen-menu.tsx
@@ -23,14 +23,11 @@ type AgentInfo = { label: string; agentName: string };
/**
* Whether the reopen-menu row should render a state icon for `session`.
*
- * A pending "needs me" prompt (clarification / permission) always surfaces — it
- * is actionable even mid-turn. Background-running (`background` while RUNNING
- * or WAITING_FOR_INPUT) also
- * reads distinctly (the shared background spinner), never as done, and
- * waiting-for-input now shows its "needs me" affordance too
- * (§spec:waiting-for-input-parity). Only STARTING stays icon-less (still
- * launching); a generating RUNNING session with no pending prompt also stays
- * silent. Terminal states (COMPLETED / FAILED / CANCELLED) keep their icons.
+ * An actionable pending prompt surfaces for RUNNING and WAITING_FOR_INPUT
+ * sessions. Background-running also reads distinctly (the shared background
+ * spinner), never as done. STARTING stays icon-less, and stale pending data
+ * cannot override terminal lifecycle icons. A generating RUNNING session with
+ * no pending prompt also stays silent.
*/
export function shouldShowReopenStateIcon(
state: TaskSessionState,
@@ -38,10 +35,12 @@ export function shouldShowReopenStateIcon(
hasPendingClarification = false,
hasPendingPermission = false,
): boolean {
- if (hasPendingClarification || hasPendingPermission) return true;
- if (foregroundActivity === "background") return true;
+ if (state === "STARTING") return false;
+ const canRequestInput = state === "RUNNING" || state === "WAITING_FOR_INPUT";
+ if (canRequestInput && (hasPendingClarification || hasPendingPermission)) return true;
+ if (canRequestInput && foregroundActivity === "background") return true;
if (state === "RUNNING") return false;
- return state !== "STARTING";
+ return true;
}
function resolveAgentInfo(
diff --git a/apps/web/components/task/sessions-dropdown.test.ts b/apps/web/components/task/sessions-dropdown.test.ts
new file mode 100644
index 0000000000..b7338f13f2
--- /dev/null
+++ b/apps/web/components/task/sessions-dropdown.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { sessionStatusTooltip } from "./sessions-dropdown";
+
+describe("sessionStatusTooltip", () => {
+ it("prioritizes permission over clarification for input-capable sessions", () => {
+ expect(sessionStatusTooltip("RUNNING", { permission: true, clarification: true })).toBe(
+ "Permission requested",
+ );
+ });
+
+ it("surfaces clarification over activity for input-capable sessions", () => {
+ expect(
+ sessionStatusTooltip("WAITING_FOR_INPUT", { permission: false, clarification: true }),
+ ).toBe("Waiting for input");
+ });
+
+ it.each([
+ ["STARTING", "Running"],
+ ["COMPLETED", "Complete"],
+ ["FAILED", "Failed"],
+ ["CANCELLED", "Cancelled"],
+ ] as const)("ignores stale pending input for %s sessions", (state, expected) => {
+ expect(sessionStatusTooltip(state, { permission: true, clarification: true })).toBe(expected);
+ });
+});
diff --git a/apps/web/components/task/sessions-dropdown.tsx b/apps/web/components/task/sessions-dropdown.tsx
index 23fa9d2970..bcff353101 100644
--- a/apps/web/components/task/sessions-dropdown.tsx
+++ b/apps/web/components/task/sessions-dropdown.tsx
@@ -58,11 +58,13 @@ const STATUS_LABELS: Record = {
// The session-icon tooltip reflects the message-derived "needs me" reading
// (§spec:waiting-for-input-parity): a pending permission / clarification prompt
-// names itself even when the coarse status is still "running" mid-turn.
-function sessionStatusTooltip(status: SessionStatus, pending: PendingInput): string {
- if (pending.permission) return "Permission requested";
- if (pending.clarification) return "Waiting for input";
- return STATUS_LABELS[status];
+// names itself even when the coarse status is still "running" mid-turn. Stale
+// pending data cannot replace a starting or terminal lifecycle label.
+export function sessionStatusTooltip(state: TaskSessionState, pending: PendingInput): string {
+ const canRequestInput = state === "RUNNING" || state === "WAITING_FOR_INPUT";
+ if (canRequestInput && pending.permission) return "Permission requested";
+ if (canRequestInput && pending.clarification) return "Waiting for input";
+ return STATUS_LABELS[mapSessionStatus(state)];
}
function mapSessionStatus(state: TaskSessionState): SessionStatus {
@@ -453,7 +455,9 @@ function SessionRow({
)}
- {sessionStatusTooltip(status, pending)}
+
+ {sessionStatusTooltip(session.state, pending)}
+