fix(compaction): review round 8 — seam obligations become primitives

Eight rounds of findings against the defer-and-drain seam shared one
generator: N sites each hand-copying M obligations (spawn discipline,
the order-barrier pair, backpressure, best-effort emission, the client
settle matrix), with every review finding an empty (site x obligation)
cell. This round makes each obligation a single primitive:

- The order barrier is Workstream.send_barrier_active() — one
  definition of the two-term pair (pending entries OR drain alive),
  consulted by the /send route, the coordinator adapter, and the
  queued-nudge wake gate, which previously carried only the list term
  and let a synthetic wake jump an acknowledged send during the
  claimed-entry window. _PendingSend moved to workstream.py beside the
  invariant that justifies the drain-alive term; the pending fields got
  precise types and worker_kind became a Literal, so a typo'd
  "command" comparison is now a type error instead of a silently
  never-firing defer guard.
- _defer_send probes the barrier before constructing anything, bounds
  acceptance at 10 pending (the interjection queue's own backpressure
  contract — unbounded acceptance pinned message + attachment bytes
  per entry for a whole command window and then ran one unattended
  turn each), and spawns the drain with rollback: a Thread.start
  failure pops the just-accepted entry and answers the retryable
  queue_full instead of 500ing after registration (a phantom the
  client could neither see nor retract, dispatched later as duplicate
  turns). start() deliberately stays inside the lock, unlike
  session_worker's outside-lock discipline: this slot is
  is_alive()-gated, false for a constructed-but-unstarted thread, so
  an outside-lock start would open a double-drain window.
- A /command whose worker never spawned answers 503
  {"status": "error"} (spec + docs + a pane error arm) instead of the
  generic 200 ok that told SDK callers their /clear ran.
- The compaction lifecycle emitter is raise-proof at its single
  dispatch tail: a raising duck-typed hook degrades to a lost render,
  never a lost end event — previously a raising on_error or a raising
  failed-end emit left every pane a frozen progress bar, and a raising
  SUCCESS end after the committed swap fabricated a failed end.
- The client settle matrix lives once: composer_queue's
  settleSendResponse owns every /send response arm for both panes
  (the near-verbatim twins were already drifting), parsePriority is
  shared, and the busy stamp is centralized in setBusy(b, source) with
  "server" as the fail-safe default. Deferred sends release the
  composer (no worker exists for them; retracting the chip no longer
  strands the pane in Stop mode), queue_full on an idle-looking pane
  removes the optimistic bubble and restores busy (the refusal can now
  fire with no worker and no drain to ever emit a state event), and
  the pre-bind settle buffer is TTL-based — a burst of deferred
  dispatches parked this tab's own raced settle first, where the old
  size cap evicted exactly it.
- The command backstop / console proxy timeout inequality is enforced
  by a test importing both named constants (both proxy_client
  constructions, startup and the mTLS re-create); the compaction card
  wears blue (magenta is reserved for the MCP surface); the redundant
  TerminalUI.on_compaction override is gone (the inherited protocol
  default is the policy site).
This commit is contained in:
Patrick Buckley
2026-07-17 02:22:37 -07:00
parent 5511ab9a35
commit 1224b02d03
24 changed files with 1000 additions and 381 deletions
+12 -7
View File
@@ -807,8 +807,12 @@ Sends a user message to a workstream. Spawns a daemon worker thread that calls
list (a command window holds the slot, or earlier deferred sends are
pending) and dispatched as its own full-fidelity send afterwards; see the
defer contract under `POST /v1/api/command`.
- `{"status": "queue_full", ...}` — the live worker's queue is at capacity;
retry shortly.
- `{"status": "queue_full", ...}` — the send was refused with retry-shortly
semantics: the live worker's interjection queue is at capacity, the
deferred-send list hit its saturation bound (10 pending — the same
backpressure contract), or the deferred-send drain could not be started
under resource exhaustion (the message was **not** accepted; nothing is
parked).
- `{"status": "attachments_busy", ...}` — attachments can't ride a queued
turn; the staged uploads survive for a retry once the worker idles.
@@ -940,11 +944,12 @@ or `{"status": "running"}` as above.
**Error responses:**
| Status | Body | Condition |
|--------|------------------------------------|----------------------------------|
| 400 | `{"error": "Empty command"}` | Command is empty |
| 404 | `{"error": "Unknown workstream"}` | `ws_id` not found |
| 409 | `{"status": "busy", "error": ...}` | A turn/command holds the worker |
| Status | Body | Condition |
|--------|-------------------------------------|--------------------------------------------------|
| 400 | `{"error": "Empty command"}` | Command is empty |
| 404 | `{"error": "Unknown workstream"}` | `ws_id` not found |
| 409 | `{"status": "busy", "error": ...}` | A turn/command holds the worker |
| 503 | `{"status": "error", "error": ...}` | The command worker could not be started (resource exhaustion) — the command did **not** run; retry shortly |
---