| --- |
| title: Background completion backlogs |
| sidebar_label: Completion backlogs |
| --- |
| |
| # Background completion backlogs |
|
|
| Interactive surfaces coalesce consecutive background-process completions that are |
| already ready for one conversation into a single notification turn. This does not |
| add a delay or promise to combine jobs that finish at different times. Failures and |
| successful outputs remain in the batch; one completion keeps its original text. |
|
|
| Process identity remains available until dispatch. Explicit `process_manage` |
| wait/log/kill consumption can therefore suppress a CLI completion even after it |
| has left the process registry and entered the input queue. An entirely consumed |
| batch starts no turn. Watching output and async-delegation results remain separate |
| notifications, in their original order; they are not folded into completion batches. |
|
|
| ## Consumers and ownership |
|
|
| - **Classic CLI:** `hermes_cli/cli_process_notifications.py` owns the idle/post-turn |
| drain, compression-aware ownership and final input unwrapping. |
| - **TUI and Desktop:** `tui_gateway/session_notifications.py` groups the poller's |
| ready snapshot after checking ownership. Each process still emits its own UI |
| status. Busy sessions requeue structured events, not rendered batch strings. |
| - **Post-turn TUI safety net:** `tui_gateway/prompt_turn.py` uses the same routing |
| and rendering path. Desktop and dashboard chat clients share this backend. |
| - **Messaging gateway:** `gateway/run_notifications.py` already uses its own |
| route-keyed short-window batching. This interactive-backlog change does not |
| replace that mechanism or alter adapter sends. |
| - **Noninteractive/headless consumers:** this change does not create a new |
| autonomous notification loop for an API request, ACP client, or one-shot CLI. |
|
|
| The shared renderer is `tools/process_registry_notifications.py::ProcessNotificationBatch`. |
| Neither a batch nor its delivery status is persisted into the system prompt. |
| Addressed events still require a provable owner; another live session cannot adopt |
| them. Delegation delivery continues through its existing durable claim/complete |
| ledger, once per delegation rather than once per process batch. |
|
|
| ## Local validation and its limits |
|
|
| `evals/completion_backlog_probe.py REPO OUTPUT.json` starts real local shell children |
| in temporary directories, reads their real completion events, and drives the |
| production CLI, TUI poller and post-turn notification routes. A loopback HTTP turn |
| sink replaces `chat` / `_run_prompt_submit`; it records actual dispatches but does |
| **not** exercise model inference, native renderer interaction or a hosted platform. |
| Synthetic watch and delegation envelopes are labeled fixtures; delegation claims |
| use the real temporary SQLite ledger. The backlog case includes a nonzero exit. |
|
|
| The probe checks a ready backlog, a single exact payload, explicitly consumed |
| results, foreign ownership, and watches/delegations interleaved with completions. |
| It measures turn admission at the notification boundary, not model token savings. |
|
|
