impl-supervisor-controller-composition

Metadata

Status	abandoned ‖ paused
Created	2026-07-25T20:57:17.564619574+00:00
Tags	`integration`, `smoke`, `controller`, `supervisor`
Failure reason	Superseded by the operator-published post-lifecycle synthesis: deterministic convergence is service-owned; no supervisor persona, adaptive outage controller, or composition authority remains.

Description

Objective

The integrator at the join point (AGENTS guide: always include an integrator at join points). Wire + smoke-test the one-way composition contract between the supervisor (T3) and the adaptive-parallelism controller (T4) so the two daemon peers compose without fighting, and prove a real rate-limit burst makes the controller shed and recover WITHOUT tripping the global-outage breaker while the supervisor does not starve the floor.

Context: docs/studies/adaptive-parallelism-budget-design.md §9 (the boundary + shared-state contract). docs/studies/supervisor-hard-agent-design.md §7 (the health snapshot the controller reads). docs/studies/roadmap-rate-limit-and-distribution.md §2.3/§4(T5).

The contract to wire (one-way, never a hard dependency)

The supervisor READS dir/service/budget_state.json's effective_max_agents only to decide whether a reset burst would be immediately rate-limited — it MAY delay a reset if the controller is at floor AND 429s are high (a polite backoff). The supervisor NEVER forces anything on the controller.
The controller READS the supervisor reset log (.wg/supervisor/journal.jsonl / state.json) only to discount "dumb-failure" resets from its throughput denominator — a task the supervisor reset for a non-quality reason should NOT count against the provider apparent success rate. The controller NEVER resets tasks.
The single rule that prevents them fighting (study §9): the controller never resets tasks; the supervisor never touches max_agents. When the supervisor requeues a batch, the controller sees the resulting busy-fraction/429 signal on its OWN cadence and adjusts downward if needed. When the controller cuts max_agents, newly-idle slots just mean the supervisor requeued tasks wait longer — they are not reset again.

What to build

Read-contract methods on both peers (small, non-mutating):
- Supervisor side (src/supervisor/mod.rs or memory.rs): should_delay_reset(controller_state) -> Option<DelayReason> that returns Some when effective_max_agents == floor AND recent 429 rate is high. The supervisor pass consults it before a reset burst and logs the polite delay.
- Controller side (src/budget/mod.rs): discounted_success_rate(supervisor_reset_log) that excludes tasks the supervisor reset for dumb reasons from the throughput denominator.
A smoke scenario tests/smoke/scenarios/controller_supervisor_rate_burst.sh that:
- Seeds a rate-limit burst (several tasks failing with the T2 RateLimit signal).
- Asserts the controller sheds effective_max_agents (subtractive-down) and then RECOVERS (additive-up) once the burst clears, WITHOUT tripping the global-outage breaker (src/commands/service/zero_output.rs) into a full pause.
- Seeds a supervisor reset burst (a batch of stuck tasks the supervisor requeues) and asserts the controller sees the resulting busy-fraction signal on its own cadence and adjusts (does not need a heads-up); asserts the supervisor, when the controller is at floor + high 429s, POLITELY DELAYS rather than re-flooding.
- Asserts the controller discounts the supervisor dumb-failure resets from its success-rate denominator (no mis-attribution of a local reset to the provider).
List the scenario in owners of tests/smoke/manifest.toml (grow-only) so the smoke gate catches future regressions.

File scope

src/supervisor/mod.rs (read-contract method; consult in the pass)
src/budget/mod.rs (read-contract method; consult in eval)
new tests/smoke/scenarios/controller_supervisor_rate_burst.sh
tests/smoke/manifest.toml (add to owners — grow-only)

Implement directly. This is a focused integration + smoke task, not a decomposition candidate.

Validation

Unit test: should_delay_reset returns Some(DelayReason) iff effective_max_agents == floor AND recent 429 rate is high; None otherwise.
Unit test: discounted_success_rate excludes supervisor-reset tasks from the denominator.
Smoke scenario controller_supervisor_rate_burst.sh passes: controller sheds + recovers on a rate burst without tripping the global breaker; supervisor politely delays a reset burst when the controller is at floor + high 429s; controller does not mis-attribute a local reset to the provider.
Scenario added to tests/smoke/manifest.toml owners (grow-only manifest — never remove an existing owner).
cargo build + cargo test pass; cargo fmt --check + cargo clippy clean.
No model pin; routes through the active zai profile.

## Objective
The integrator at the join point (AGENTS guide: always include an integrator at join points). Wire + smoke-test the one-way composition contract between the supervisor (T3) and the adaptive-parallelism controller (T4) so the two daemon peers compose without fighting, and prove a real rate-limit burst makes the controller shed and recover WITHOUT tripping the global-outage breaker while the supervisor does not starve the floor.

Context: `docs/studies/adaptive-parallelism-budget-design.md` §9 (the boundary + shared-state contract). `docs/studies/supervisor-hard-agent-design.md` §7 (the health snapshot the controller reads). `docs/studies/roadmap-rate-limit-and-distribution.md` §2.3/§4(T5).

## The contract to wire (one-way, never a hard dependency)
- The supervisor READS `dir/service/budget_state.json`'s `effective_max_agents` only to decide whether a reset burst would be immediately rate-limited — it MAY delay a reset if the controller is at floor AND 429s are high (a polite backoff). The supervisor NEVER forces anything on the controller.
- The controller READS the supervisor reset log (`.wg/supervisor/journal.jsonl` / `state.json`) only to discount "dumb-failure" resets from its throughput denominator — a task the supervisor reset for a non-quality reason should NOT count against the provider apparent success rate. The controller NEVER resets tasks.
- The single rule that prevents them fighting (study §9): the controller never resets tasks; the supervisor never touches `max_agents`. When the supervisor requeues a batch, the controller sees the resulting busy-fraction/429 signal on its OWN cadence and adjusts downward if needed. When the controller cuts `max_agents`, newly-idle slots just mean the supervisor requeued tasks wait longer — they are not reset again.

## What to build
1. Read-contract methods on both peers (small, non-mutating):
   - Supervisor side (`src/supervisor/mod.rs` or `memory.rs`): `should_delay_reset(controller_state) -> Option<DelayReason>` that returns Some when `effective_max_agents == floor` AND recent 429 rate is high. The supervisor pass consults it before a reset burst and logs the polite delay.
   - Controller side (`src/budget/mod.rs`): `discounted_success_rate(supervisor_reset_log)` that excludes tasks the supervisor reset for dumb reasons from the throughput denominator.
2. A smoke scenario `tests/smoke/scenarios/controller_supervisor_rate_burst.sh` that:
   - Seeds a rate-limit burst (several tasks failing with the T2 `RateLimit` signal).
   - Asserts the controller sheds `effective_max_agents` (subtractive-down) and then RECOVERS (additive-up) once the burst clears, WITHOUT tripping the global-outage breaker (`src/commands/service/zero_output.rs`) into a full pause.
   - Seeds a supervisor reset burst (a batch of stuck tasks the supervisor requeues) and asserts the controller sees the resulting busy-fraction signal on its own cadence and adjusts (does not need a heads-up); asserts the supervisor, when the controller is at floor + high 429s, POLITELY DELAYS rather than re-flooding.
   - Asserts the controller discounts the supervisor dumb-failure resets from its success-rate denominator (no mis-attribution of a local reset to the provider).
3. List the scenario in `owners` of `tests/smoke/manifest.toml` (grow-only) so the smoke gate catches future regressions.

## File scope
- `src/supervisor/mod.rs` (read-contract method; consult in the pass)
- `src/budget/mod.rs` (read-contract method; consult in eval)
- new `tests/smoke/scenarios/controller_supervisor_rate_burst.sh`
- `tests/smoke/manifest.toml` (add to owners — grow-only)

Implement directly. This is a focused integration + smoke task, not a decomposition candidate.

## Validation
- [ ] Unit test: `should_delay_reset` returns Some(DelayReason) iff `effective_max_agents == floor` AND recent 429 rate is high; None otherwise.
- [ ] Unit test: `discounted_success_rate` excludes supervisor-reset tasks from the denominator.
- [ ] Smoke scenario `controller_supervisor_rate_burst.sh` passes: controller sheds + recovers on a rate burst without tripping the global breaker; supervisor politely delays a reset burst when the controller is at floor + high 429s; controller does not mis-attribute a local reset to the provider.
- [ ] Scenario added to `tests/smoke/manifest.toml` `owners` (grow-only manifest — never remove an existing owner).
- [ ] `cargo build` + `cargo test` pass; `cargo fmt --check` + `cargo clippy` clean.
- [ ] No model pin; routes through the active zai profile.

Depends on

Required by

abandoned .flip-impl-supervisor-controller-composition

Log

2026-07-25T20:57:17.554093474+00:00 Task paused
2026-07-25T20:57:30.632010241+00:00 Task published
2026-07-31T11:40:21.162958071+00:00 Task paused
2026-07-31T11:40:21.330746520+00:00 Paused as a reversible safety interlock by reframe-supervisor-as-convergence-reconciler. The deterministic daemon reconciler decision draft explicitly requires an operator to choose clean supersession, budget-only narrowing, or in-place rewrite before any controller implementation proceeds. No supersession/edit has been applied yet.
2026-07-31T12:40:35.848685544+00:00 Task abandoned: Superseded by the operator-published post-lifecycle synthesis: deterministic convergence is service-owned; no supervisor persona, adaptive outage controller, or composition authority remains.