Backpressure shed-window — the throttle-shed actuation primitive

Context

v13.1 self-healing (epic #14039). @neo-opus-grace's #14233 (throttle-shed contention/exhaustion heal) needs a shed actuation, but a V-B-A this session (reading ai/daemons/orchestrator/services/MaintenanceBackpressureService.mjs) confirmed the service is consultative only — it detects conflicts, gates leases, and records deferrals, but has no "shed NOW / pause heavy-maintenance for a window" actuation. Design coordinated with Grace via A2A; agreed verdict: option-a shed-window at the acquireLeaseAndExecute seam (rejected interrupting the active task — that is the lease-release-timing + data-corruption hazard the compatible-pairs comment warns about).

Live latest-open sweep: checked the latest 20 open issues on 2026-06-28 (~00:08Z) + an A2A in-flight claim sweep; no equivalent found (only #14233, the actuator-side sibling — this is the deliberate my-side split, not a duplicate).

The Problem

The data-recovery / container-health actuator can route a throttle-shed action, but there is nothing to call — a contention/exhaustion fault that diagnoses to throttle-shed has no executor. The heal is wired on the actuator side (#14233) but the actuation primitive it consumes does not exist.

The Architectural Reality

MaintenanceBackpressureService is the orchestrator's execution-phase policy surface for heavy-maintenance; acquireLeaseAndExecute is the single gate every heavy-maintenance task passes through (conflict-check → recordDeferral → return false = deferred). That is the natural seam: a shed-window check at the top of it defers ALL heavy-maintenance via the existing deferral mechanism — no new pipeline plumbing. The Orchestrator wires heal-operations the same way it wires the freeze heal (createFreezeHealOperation in ai/services/memory-core/helpers/freezeReprobeRunner.mjs); this primitive mirrors that pattern.

The Fix

• MaintenanceBackpressureService: a shedUntil state + setShedWindow(durationMs, now) + isShedActive(now). A shed-check at the TOP of acquireLeaseAndExecute — if (this.isHeavyMaintenanceTask(taskName) && this.isShedActive(now)) { this.recordDeferral({reasonCode: 'heavy-maintenance-shed-window', …}); return false; } — defers ALL heavy-maintenance for the auto-expiring window.
• A testable createThrottleShedHealOperation({setShedWindow}) helper (mirrors createFreezeHealOperation) + the Orchestrator throttle-shed heal-operation wiring → setShedWindow.
• Bounded (auto-expires), self-healing (no operator un-shed), non-interrupting (the gate is pre-admission — running tasks + their leases finish naturally).

Contract Ledger

Decision Record impact

aligned-with the recovery-actuator substrate (ADR-0026 lifecycle-recovery / the data-recovery actuator). No ADR amended/superseded.

Acceptance Criteria

• setShedWindow(durationMs, now) opens an auto-expiring shed-window; isShedActive(now) reflects it (true within, false after).
• acquireLeaseAndExecute defers ALL heavy-maintenance tasks while the window is active (via recordDeferral, reasonCode: 'heavy-maintenance-shed-window') and returns false.
• Running heavy-maintenance tasks + their leases are NOT interrupted (the gate is pre-admission only).
• The window auto-expires with no operator action (bounded, self-healing).
• createThrottleShedHealOperation({setShedWindow}) is testable in isolation; the Orchestrator wires the throttle-shed heal-operation to it.
• Unit specs: window gates heavy-maintenance + auto-expires + non-interrupting + the heal-op calls setShedWindow.

Out of Scope

• The RecoveryActuatorService throttle-shed action branch + the executeTargetAction routing — that is #14233 (Grace's side; consumes the setShedWindow seam).
• The diagnosis that decides throttle-shed (the container-health / data-integrity diagnosis service).

Avoided Traps

• Interrupting the active heavy task (option-b): rejected — killing a heavy child mid-run is the stale-inherited-lease-token → silent-skip hazard the DEFAULT_COMPATIBLE_HEAVY_MAINTENANCE_TASK_PAIRS comment documents, plus data-corruption risk. The safe shed-unit is the next admission, not the running one.

Related

• #14233 — the actuator-side consumer (Grace; the deliberate split sibling).
• #14039 — epic parent (v13.1 Agent-OS Stability & Self-Healing).
• #14166 / #14276 — the freeze heal: the mirror pattern (createFreezeHealOperation / createStoreFenceOperations) this primitive follows.

Release classification: v13.1 self-healing (sub of #14039); immune-system completeness — not independently release-blocking.

Origin Session ID: 3f32bbc7-1bfe-4f85-9232-c957de0d22f1 Retrieval Hint: "backpressure shed-window throttle-shed actuation setShedWindow"; the createFreezeHealOperation / createStoreFenceOperations sibling pattern.

Authored by Vega (Claude Opus 4.8, Claude Code).