Files
kandev/docs/specs/platform/background-work-liveness.md
T
2026-07-26 19:41:26 +01:00

237 lines
14 KiB
Markdown

---
status: shipped
created: 2026-07-21
updated: 2026-07-26
owner: 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.
- When a provider-attested, generation-bearing foreground-idle boundary also
guarantees prompt handoff, the next human prompt reaches the provider
immediately even if the prior prompt RPC remains open for detached work.
Synthetic wakeups remain serialized behind the owning RPC. Providers that do
not attest handoff keep the follow-up queued until they release ownership.
- Only adapter-attested workloads relax prompt admission. An adapter opts in a
workload only when Kandev has fixture-tested both its launch and accountable
terminal lifecycle. Claude subagents, background shells, and Monitor watches
are initially supported. Codex and other ACP agents remain conservatively
foreground-busy until their providers reliably emit the terminal lifecycle
Kandev needs.
- The runtime retains one registration per live subagent and derives an active
subagent count from those registrations. Background shells and Monitor
watches contribute to background liveness but not to the subagent count.
- Task and session status surfaces distinguish generating,
background-running, and done with text or accessible labels in addition to
color. The compact sidebar uses the same dashed spinner for both running
states: yellow for foreground generation and violet for background work, with
a distinct background-work tooltip and accessible label. 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.
- Terminal execution teardown retires every tool-ownership and background-work
entry owned by that execution. It releases the whole session activity record
when no successor execution or in-flight prompt/dispatch token still owns it.
- 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_activity` as
`generating`, `background`, or absent when no fine-grained activity is known.
`background` can be present after the coarse session state settles.
- Session records, boot payloads, activity/state notifications, task records,
and `task.updated` always expose `active_subagent_count` as an integer. It is
zero when no adapter-attested subagent is live and may be positive while
`foreground_activity` is either `generating` or `background`.
- `session.activity_changed` publishes the changed fine-grained session value
and active subagent count; a count-only transition is publishable even when
the activity tier does not change. `session.state_changed` carries both with
coarse state changes.
- Task records and `task.updated` carry the most-active-wins
`foreground_activity` aggregate and the sum of active subagents across its
sessions. A task update is emitted when either aggregate changes, including a
generating-to-background or count-only 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 except for one generation-matched human ownership transfer at an
adapter-attested provider handoff. The transfer finalizes the earlier lifecycle
buffer/completion owner before the successor starts; synthetic wakeups cannot
consume it, and a delayed response from the earlier RPC cannot finalize the
successor. Prompt-end cleanup for that successor excludes predecessor background
work and its nested tool/Monitor lineage, while explicit cancellation and session
replacement still clear all ownership.
## Failure modes
- An unknown activity value for an in-flight `RUNNING` session is rendered as
generating, not done.
- A foreground-idle signal without a nonzero matching prompt generation and
adapter-attested handoff capability does not relax transport serialization.
The session remains visibly foreground-owned and the follow-up remains
queued rather than being reported as delivered.
- A normalized tool-card shape cannot attest to background capability. An
unsupported adapter that emits a subagent-looking card remains foreground-busy
until its launch, yield, and terminal lifecycle are explicitly supported.
- The development/E2E mock provider may replay captured Claude lifecycle
metadata through the same attested path. This is a deterministic test seam,
not an additional production-agent capability.
- Codex child thread/session identity may correlate launch and activity cards
for presentation, but Codex subagents do not attest background liveness.
Observed Codex ACP streams can omit accountable terminal child activity, so a
started card must not create a live registration or nonzero subagent count.
- Tool-call ownership is established by the initial call and retained across
incremental updates from the same execution. Ownership includes the execution
identity because provider-local tool-call IDs may be reused after rotation.
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 completion, stop, failure, cancellation, crash cleanup, forced
cleanup, and session removal retire all activity owned by that execution.
Cleanup is idempotent and must preserve activity already claimed by a
successor on the same session. Session removal quiesces any still-live
lifecycle execution and rejects deletion if that stop fails, except when the
runtime reports that the exact execution is already absent. Per-session
activity validation and delivery remain ordered across record replacement;
each publication snapshots its activity value and active-subagent count
together. Per-task publication is FIFO: a newly computed activity value must
not be published ahead of an earlier value for the same task, and a detached
predecessor record or stale publication must not overwrite a newer session or
task 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 or active subagent counts; it must not preserve a
stale live reading. Counts are derived from the live registration map rather
than persisted or incremented independently. Execution teardown releases the
record when it has no successor owner; completed session history does not retain
an empty activity record. 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** an attested provider keeps a prompt RPC open for a detached child
after emitting foreground-idle for the matching generation, **WHEN** the
operator sends a follow-up, **THEN** that human prompt reaches the provider
immediately and the detached child may continue streaming.
- **GIVEN** a synthetic wakeup is waiting when an attested human handoff occurs,
**WHEN** a human follow-up is submitted, **THEN** the human prompt inherits
ownership and the wakeup remains serialized until the human turn completes.
- **GIVEN** predecessor background tools or Monitors are still live after the
follow-up completes, **WHEN** the successor runs prompt-end cleanup, **THEN**
those predecessor-owned streams remain tracked until their authoritative
terminal event, explicit cancellation, or session replacement.
- **GIVEN** the provider has not authoritatively released the foreground,
**WHEN** the operator submits a follow-up, **THEN** Kandev reports it as
queued and does not send it concurrently.
- **GIVEN** two adapter-attested subagents and one background shell are live,
**WHEN** the session is serialized or publishes an activity update, **THEN**
`active_subagent_count` is two while all three workloads still contribute to
background liveness.
- **GIVEN** one generating session with one live subagent and another session
with two live subagents, **WHEN** the task is serialized, **THEN** its
`foreground_activity` is generating and its `active_subagent_count` is three.
- **GIVEN** a Codex subagent launch card without an accountable terminal
lifecycle, **WHEN** its prompt remains in flight or later settles, **THEN**
Kandev may render the card but reports no recognized background work and the
active subagent count remains zero.
- **GIVEN** an unsupported ACP adapter emits a normalized subagent-shaped tool
card, **WHEN** its prompt remains in flight, **THEN** Kandev reports the
foreground as generating and the active subagent count remains zero.
- **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** an execution terminates with orphaned tool ownership and background
work and no successor exists, **WHEN** teardown runs, **THEN** all owned state
and the session activity record are released.
- **GIVEN** execution B has claimed the same session before delayed teardown for
execution A, **WHEN** A is retired, **THEN** B's prompt claim, prompt
generation, foreground state, tools, and background work remain unchanged.
- **GIVEN** execution B reuses a tool-call ID left nonterminal by execution A,
**WHEN** B emits an ownership-incomplete update, **THEN** A's classification
is not observable as ownership evidence for B.
- **GIVEN** execution A's cleanup publication is delayed until after execution B
claims the session, **WHEN** the delayed publication resumes, **THEN** it
cannot recreate A's record or overwrite B's activity.
- **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.
- Rendering the active subagent count or individual subagent details in the UI.
- 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](../../decisions/0049-fine-grained-foreground-idle-busy-signal.md) owns the architectural reasoning: ownership and admission rules, provider attestation, and the per-task publication-order invariant.
## Implementation plan
[Background work liveness implementation plan](../../plans/background-work-liveness/plan.md)