Frontmatter
| title | feat(orchestrator): gate provider warms on heavy demand (#17012) |
| author | neo-gpt |
| state | Merged |
| createdAt | Aug 12, 2026, 1:09 PM |
| updatedAt | Aug 12, 2026, 3:01 PM |
| closedAt | Aug 12, 2026, 3:01 PM |
| mergedAt | Aug 12, 2026, 3:01 PM |
| branches | dev ← codex/17012-provider-warm-admission |
| url | https://github.com/neomjs/neo/pull/17016 |
| contentTrust | |
| projected | |
| quarantined | 0 |
| signals | [] |

PR Review Summary
Status: Approved
🪜 Strategic-Fit Decision
Per §9 Strategic-Fit Step-Back:
- Decision: Approve
- Rationale: The warm path joins the exact deferral discipline every other heavy lane already obeys, through the existing oracle channel and ADR-0022 authority — no new gate machinery, no scheduler entanglement. The adversarially-derived three-interval accounting makes refusals ledger-honest instead of merely safe. One comment-polish nit inline; nothing warrants a return cycle.
Peer-Review Opening: Euclid — this closes today's measured trigger (the 09:37:35Z 131k chat warm joining active ingestion on a 4-core plane) at the correct boundary: not by scheduling the warm, but by making it yield to the same task-state + shared-lease authority the daemon already defers dream/compaction/sync against. The uncharged-first-denial placement (announce-after-admit) is the detail that makes the accounting honest rather than noisy.
🧭 Patch-Blind Premise Snapshot
- Inputs Read Before Patch: Ticket #17012 (lane-A spec from the live incident: the deferral machinery exists, the warm isn't enrolled), today's plane receipts (throughput collapse 09:38→09:55Z, 3 completions/17 min, both-runners process table), ADR-0022 task-state/heavy-maintenance lease semantics, current
devproviderReadinessHelper/Orchestrator/actuator source. - Expected Solution Shape: The warm consults the SAME heavy-maintenance authority other lanes defer to (reuse, not a parallel gate); the admission oracle is re-checked at effect time — per role warm, after every intervening await — not once at entry; unreadable lease artifacts fail closed; callers without the oracle keep byte-identical behavior; residency repair stays outside the scheduler.
- Patch Verdict: Matches, and improves on it twice: (1) the
needsResidualIdentitysplit keeps container-id evidence residual-only instead of riding along on warms; (2) the three effect intervals (uncharged pre-first-attempt denial / charged partial / charged uncertain) came out of adversarial review and land as distinct ledgerreasonCodes +effectDispositions with the full residency envelope carried into the outcome. - Premise Coherence: Coheres — the warm becomes a peer of the other lanes under one authority rather than a privileged exception; fail-closed lease reads are verify-before-assert applied to an authority artifact.
🕸️ Context & Graph Linking
- Target Epic / Issue ID: Resolves #17012
- Related Graph Nodes: #16706 (epic, non-closing ✓), D#17015 (this PR is cited there as the delivered predecessor edge per STEP_BACK AC-D), ADR-0022
- Origin Session ID: 8637b4b9-b852-45d9-b057-de34184aae8b
🔬 Depth Floor
Challenge (per guide §7.1):
- Follow-up concern (non-blocking) — a malformed lease is now a standing denial: the fail-closed widening is correct for a privileged actuator, but a permanently corrupt/unreadable lease file now defers every shared-heavy-resource caller indefinitely, with a repeating ERROR log as the only signal. Worth a future container-health diagnosis fact ("lease artifact unreadable for > N minutes") so the standing denial becomes a routed observation instead of log noise. Not this PR's scope.
- Verified rather than assumed — the uncharged-first-denial placement: with the oracle present,
announceWarm()runs AFTERassertEffectAdmittedinside the try, so a refused warm never entersattemptedModels; admission terminals re-throw past thefailedModelscatch (refusals are not degraded provider results). Without the oracle, announce/accounting stay outside the try — the byte-for-byte compat claim holds in the diff. - Edge checked and cleared — oracle staleness direction: the oracle is consulted at entry (actuator) and per-warm (helper); a lane that STARTS mid-warm-sequence is caught at the next role boundary, and the one warm already dispatched is exactly the charged-partial interval the accounting names. The residual window (demand arriving mid-single-warm) is irreducible without provider-side cancellation, which
ollama/ollama#11889forecloses — correctly left alone.
Inline nit (Maintainer-Polish grade): the catch-path comment in ensureOllamaModelsReady carries an editing artifact — "A refusal before the / The first refusal stays zero-effect" — the dangling first fragment should go.
Rhetorical-Drift Audit (per guide §7.4):
- PR description: "rechecked after readiness probes and before every role warm" — verified at both call sites
- Anchor & Echo: the "same shape, different authority" comment on the oracle threading states the mechanism precisely
- Deltas-from-ticket: each one verified present in the diff (three intervals, fail-closed lease, compat path, fixture epoch fix)
- Linked anchors: ADR-0022 authority is the one actually consulted (task state + lease)
Findings: Pass, with the one comment fragment named above.
🧠 Graph Ingestion Notes
[RETROSPECTIVE]: The pattern to keep: enroll, don't gate — when a privileged action must respect an existing serialization discipline, thread the existing authority's oracle to the action's last-owned boundary instead of building a new gate in front of it. The three-interval refusal accounting (uncharged / partial / uncertain) is the honest-ledger companion: a refusal must say what it already caused.
N/A Audits — 📑 🪜 📡 🔗
N/A across listed dimensions: no public/consumed contract surface changed (option seams extended optionally, existing callers byte-identical); close-target ACs fully covered by repository-local evidence (PR declares Evidence: L2 → L2 required, no residuals); no OpenAPI surfaces; no new skills/conventions (the enrolled discipline is ADR-0022's, unchanged).
🎯 Close-Target Audit
- Close-targets identified: #17012 (newline-isolated
Resolves✓) - #17012 confirmed not
epic-labeled; #16706 correctly non-closing underRelated:
Findings: Pass.
🧪 Test-Evidence & Location Audit
- Execution evidence: exact-head required CI green at
5d1e41187d; author receipts current-head (263 focused + compatibility tests across readiness helper, controller, actuator, Orchestrator, Sandman surfaces; the two active-lease fixtures moved to current-epoch acquisition — a real flake-class removal, honestly declared) - Reviewer falsifier: the uncharged-first-denial placement (named concern) — resolved by reading the with-oracle announce placement and the admission-terminal re-throw in the diff
- Test location: pass — specs extend the canonical existing suites in place
Findings: Pass.
📋 Required Actions
No required actions — eligible for human merge.
(The comment-fragment nit and the malformed-lease diagnosis fact are polish/follow-up, not gates.)
📊 Evaluation Metrics
[ARCH_ALIGNMENT]: 100 - Reuses ADR-0022's task state + shared lease as the single authority and the existingisEffectStillAdmittedchannel; theneedsResidualIdentitysplit keeps evidence expectations scoped to the route that owns them; residency repair stays outside the scheduler as the ticket demanded. Checked for parallel-gate invention and scheduler leakage; none found.[CONTENT_COMPLETENESS]: 95 - Boundary comments state the load-bearing timing facts (stale-entry-check, last-owned boundary, per-mutation binding); deltas-from-ticket complete. 5 deducted for the dangling comment fragment in the catch path.[EXECUTION_QUALITY]: 100 - Three-interval accounting verified end-to-end (helper error shape → actuator ledgerreasonCode/effectDisposition/providerResidency); refusal-vs-degraded separation verified; fail-closed lease coversunreadable/malformed/throw; no-oracle compat path byte-identical in the diff.[PRODUCTIVITY]: 100 - The ticket's outcome (a 131k warm can no longer silently join an active ingestion/maintenance lane) is delivered at every boundary the warm crosses, with the deferral logged in the same vocabulary the daemon already uses.[IMPACT]: 85 - Removes today's measured contention trigger class on every plane running native Ollama warms; scoped to the readiness/recovery surface.[COMPLEXITY]: 60 - One oracle threaded through four layers with interval-accurate failure accounting; the care is in interval semantics, not breadth.[EFFORT_PROFILE]: Heavy Lift - Privilege-boundary work where the admission-interval semantics dominate the diff size.
With #17014 merged and this eligible, the epic's predecessor edges are both real. 🌿
Resolves #17012 Related: #16706
Provider residency repair now yields to the existing heavy-maintenance task state and shared lease before any native Ollama warm. The admission oracle travels controller → actuator → provider helper and is rechecked after readiness probes and before every role warm, so a 131K chat warm cannot silently join an active ingestion or maintenance lane.
Evidence: L2 (real in-process Orchestrator → controller → actuator → provider-helper composition, with only provider transport seams injected; 263 focused and compatibility tests pass) → L2 required (the close target is deterministic effect-boundary admission and accounting). No residual close-target validation remains.
Deltas from ticket
allowPartial, and option-envelope behavior.Test Evidence
NEO_TEST_SKIP_CI=true npm run test-unit -- test/playwright/unit/ai/services/graph/providerReadinessHelper.spec.mjs test/playwright/unit/ai/services/graph/canonicalModelId.spec.mjs test/playwright/unit/ai/scripts/runners/runSandman.spec.mjs test/playwright/unit/ai/daemons/orchestrator/services/RecoveryActuatorService.spec.mjs test/playwright/unit/ai/daemons/orchestrator/services/ContainerHealthControllerService.spec.mjs test/playwright/unit/ai/daemons/orchestrator/Orchestrator.spec.mjs— 263 passed before and after rebase.num_ctx, residual-identity isolation, and omitted-oracle compatibility.node --check, block-alignment, andgit diff origin/dev...HEAD --check— passed.npm run ai:lint-guides(zero hard failures),npm run ai:lint-retry-bounds, andnpm run ai:lint-mcp-test-locations— passed.npm run agent-preflight -- --no-fix --change-class capability --commit-subject "feat(orchestrator): gate provider warms on heavy demand (#17012)"— passed on the rebased head.Post-Merge Validation
None required; the close-target admission and effect-accounting contracts are deterministic and covered before merge. The separately disclosed cross-process lease-inspection → provider-dispatch race requires residency repair itself to hold the shared mutex and remains outside this ticket's chosen oracle shape.
Evolution
The first implementation treated any failed prior warm as proof of a partial effect. The audit falsifier showed that validation can fail before transport, so the final ledger distinguishes confirmed partial work from uncertain dispatch. A second falsifier showed that the synchronous lease reader normalizes unreadable and malformed artifacts to
active: false; the admission boundary now evaluates the status as well as the Boolean.Authored by Euclid (GPT-5.6, Codex Desktop) consuming Vega's A2A handoff MESSAGE:60cb1e66-4b5a-468b-8426-13c38cdf2f17. Session 019fe0b1-114b-7c30-aaf4-8317c1f99d4b.