7.0 KiB
status, created, updated, owner
| status | created | updated | owner |
|---|---|---|---|
| shipped | 2026-07-21 | 2026-07-24 | kandev |
Background Work Liveness
Why
Operators need to know whether an agent is actively generating, is available for another prompt while recognized work continues, or has finished. Collapsing those conditions into a coarse running state both hides active background work and incorrectly prevents prompt delivery.
What
- A session distinguishes foreground generation from recognized background work. Foreground activity takes precedence over background work; neither condition may appear as done.
- A foreground-idle session with recognized background work accepts a new prompt. A session with foreground activity continues to reject it.
- Task and session status surfaces distinguish generating, background-running, and done without relying on color alone. A pending permission request takes precedence over a pending clarification request, which in turn takes precedence over the work-state indicator for a current, input-capable session only; stale pending flags on starting or terminal sessions do not override the work-state indicator.
- A task aggregates its sessions with most-active-wins: generating outranks background-running, which outranks existing settled-state rendering.
- A terminal asynchronous launch result closes its tool card but does not end the launched workload. Work remains live until accountable completion or execution teardown.
- The delete confirmation warns when a task has foreground or recognized background work. Archive uses the same warning only when archive confirmation is enabled.
API surface
- Session records and boot payloads expose
foreground_activityasgenerating,background, or absent when no fine-grained activity is known.backgroundcan be present after the coarse session state settles. session.activity_changedpublishes a changed fine-grained session value;session.state_changedcarries it with coarse state changes.- Task records and
task.updatedcarry the most-active-winsforeground_activityaggregate. A task update is emitted when that aggregate changes, including a generating-to-background transition with no coarse state change.
State machine
| State | Entry | Exit |
|---|---|---|
| generating | A prompt is claimed or dispatched, or known top-level foreground work emits output. | The current prompt yields or completes, unless more foreground activity arrives. |
| background-running | The foreground is idle and one or more recognized workloads remain registered. | A foreground prompt/output takes precedence, or the final workload completes or is torn down. |
| idle/done | Neither foreground ownership nor recognized background work remains. | A foreground prompt/output or recognized workload begins. |
Prompt admission is atomic: only one prompt can claim foreground ownership for a session. Delayed release or completion from an earlier prompt cycle cannot mutate a later accepted claim. Prompt delivery is serialized per agent execution so each prompt owns its completion wait and response buffers.
Failure modes
- An unknown activity value for an in-flight
RUNNINGsession is rendered as generating, not done. - Tool-call ownership is established by the initial call and retained across incremental updates. An update with unknown ownership preserves the current activity; missing parent metadata is not evidence that background-child work became foreground work.
- A task aggregate that cannot be recomputed preserves its last-known value rather than publishing a spurious done reading.
- When provider completion identifies a workload, only that registration is retired; duplicate completion is harmless. An uncorrelated completion retires only one outstanding registration and leaves an ambiguous remainder live.
- Execution stop, failure, cancellation, session removal, and teardown retire all registrations owned by that execution. Per-task publication is FIFO: a newly computed activity value must not be published ahead of an earlier value for the same task, and stale publication work must not overwrite a newer aggregate.
Persistence guarantees
Fine-grained activity is in memory and is authoritative only while the owning agent execution remains connected. A backend or agent-execution restart does not reconstruct detached work; it must not preserve a stale live reading. Durable coarse state continues to survive as before.
Scenarios
- GIVEN a foreground-idle session with a recognized background workload, WHEN the operator sends a prompt, THEN the prompt is accepted while the status remains background-running until foreground activity begins.
- GIVEN a task with one generating session and one background-running session, WHEN its aggregate is rendered, THEN it shows generating.
- GIVEN a task with no generating session and one background-running session, WHEN its aggregate is rendered on a board, list, graph, header, or sidebar, THEN it does not show done.
- GIVEN a detached workload launch completes, WHEN no workload terminal signal has arrived, THEN the session stays background-running.
- GIVEN a child tool call was attributed to recognized background work, WHEN an incremental update temporarily omits its parent metadata, THEN the session remains background-running.
- GIVEN a freshly loaded page or a second browser tab, WHEN a connected session has current background activity, THEN its task and session surfaces show background-running without waiting for a transition.
- GIVEN an activity transition for a task, WHEN a later transition is computed before earlier publication completes, THEN observers never see the later value followed by the stale earlier value.
- GIVEN a task with active foreground or recognized background work, WHEN the operator deletes it, THEN the confirmation warns that work is still in progress.
- GIVEN a task with active foreground or recognized background work, WHEN the operator archives it with archive confirmation enabled, THEN the archive confirmation carries the same warning.
- GIVEN archive confirmation is disabled, WHEN the operator archives a task with active foreground or recognized background work, THEN no archive dialog is shown.
Out of scope
- Mid-turn steering for agents without concurrent-prompt capability.
- Reconstructing detached-work liveness after backend or agent-execution restart.
- Changing Office autonomous-agent status vocabulary.
- Changing archive behavior when the operator has disabled archive confirmation.
Decision record
ADR 0049 — Fine-grained foreground-idle busy signal owns the architectural reasoning: ownership and admission rules, provider attestation, and the per-task publication-order invariant.