<!-- task=m-node-provider-execution-liveness-recovery/08+07_health_overlay plan=3 tag=REVIEW_REFACTOR milestone-task=failure-handoff -->

# Exact-Target Provider Recovery Fence

## For the Implementing Agent

Implement only the direct fix mapped below, run every verification command, and fill all implementation-owned sections of `CODE_REVIEW-cloud-G06.md` with actual notes and raw output. Keep the active files in place and report ready for review; finalization belongs to the code-review skill. If blocked, record the exact blocker, attempted commands/output, and resume condition only. Do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`.

## Background

Current-catalog uniqueness and available-observation high-water retention are fixed, but recovery is still keyed only by provider id after catalog resolution. On a multi-target provider, a newer available observation for target A can therefore clear an unavailable overlay lowered by target B, contrary to SDD S04 and the runtime contracts.

## Archive Evidence Snapshot

- The plan=2 pair is archived as `agent-task/m-node-provider-execution-liveness-recovery/08+07_health_overlay/plan_cloud_G07_2.log` and `agent-task/m-node-provider-execution-liveness-recovery/08+07_health_overlay/code_review_cloud_G08_2.log` with verdict `FAIL`, Required=1, Suggested=0, Nit=0.
- Required R2 affects `apps/edge/internal/service/model_queue_release.go` and `apps/edge/internal/service/provider_health_overlay_test.go`: probe recovery must retain the exact adapter/target binding that lowered the provider while advancing its per-provider observation high-water mark.
- Reviewer reproduction proved the failure: unavailable target B at sequence 1 was recovered by available target A at sequence 2 on the same multi-target provider.
- Fresh focused, package, race, vet, provider smoke, local-capacity smoke, and diff verification passed. The authorized live long-context provider and Edge status endpoints remain unreachable; do not repeat those unchanged external commands in this repository-fix packet.
- Roadmap carryover remains `milestone-task=failure-handoff`, SDD S04. Existing contracts/specs already require same-provider/adapter/target higher-sequence recovery and need no semantic rewrite for R2.

## Finding Resolution Map

| Finding | Mode | Exact Fix Evidence | Changed/Satisfied Precondition |
|---------|------|--------------------|--------------------------------|
| R2 | direct-fix | Preserve a lowered overlay's adapter/target on cross-target available evidence in `apps/edge/internal/service/model_queue_release.go`; advance its sequence without recovery; add exact cross-target and later matching-target assertions in `apps/edge/internal/service/provider_health_overlay_test.go`. | The multi-target recovery transition and its deterministic oracle change before verification, so this is not an unchanged-precondition rerun. |

## Analysis

### Files Read

- `apps/edge/internal/node/store.go`
- `apps/edge/internal/node/registry.go`
- `apps/edge/internal/service/model_queue_types.go`
- `apps/edge/internal/service/model_queue_admission.go`
- `apps/edge/internal/service/model_queue_release.go`
- `apps/edge/internal/service/model_queue_snapshot.go`
- `apps/edge/internal/service/provider_resolution.go`
- `apps/edge/internal/service/node_command.go`
- `apps/edge/internal/service/provider_health_overlay_test.go`
- `agent-contract/inner/execution-runtime.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `agent-contract/inner/edge-config-runtime-refresh.md`
- `agent-spec/runtime/edge-node-execution.md`
- `agent-spec/runtime/provider-pool-config-refresh.md`
- `agent-roadmap/sdd/operational-observability-provider-management/node-provider-execution-liveness-recovery/SDD.md`
- `agent-test/local/edge-smoke.md`
- `agent-test/local/node-smoke.md`
- `agent-test/local/platform-common-smoke.md`
- `agent-test/local/testing-smoke.md`

### SDD Criteria

- SDD: `agent-roadmap/sdd/operational-observability-provider-management/node-provider-execution-liveness-recovery/SDD.md`; status `approved`; `milestone-task=failure-handoff`.
- Target: Acceptance Scenario S04 and its Evidence Map row. Recovery must use current bound evidence for the same provider/adapter/target, and stale sequence is a projection no-op.
- These criteria require one multi-target ordering regression and the focused repeated/race verification below. Existing contract/spec text already encodes the invariant.

### Verification Context

- No separate `verification_context` handoff was supplied. The archived plan=2 review, reviewer reproduction, repository tests, contracts, SDD, and local profiles are the evidence sources.
- Preconditions: dependent sibling `07+06_reception_fence` is satisfied by `agent-task/archive/2026/08/m-node-provider-execution-liveness-recovery/07+06_reception_fence/complete.log`; current-catalog uniqueness and available high-water behavior already pass repeated tests.
- Reviewer setup: local checkout at `/config/workspace/iop-s1`; `go version go1.26.2 linux/arm64`; module `/config/workspace/iop-s1/go.mod`.
- Deterministic reproduction: one provider serves targets A and B; target B is lowered at sequence 1; target A available at sequence 2 incorrectly returns recovery. Confidence is high because the failure invokes the production transition directly.
- Constraints: keep config health, Node wire evidence, command parsing, admission/snapshot consumers, and ingress recovery ownership unchanged. Fresh Go output is required; cached results are not acceptable.
- External verification carryover: the prior authorized provider `/v1/models` and Edge status endpoints were unreachable. This compact repository fix neither changes that precondition nor weakens the S04 oracle, so unchanged external retries remain excluded.

### Test Coverage Gaps

- Existing tests cover catalog ambiguity and same-target available-before-terminal ordering.
- No test lowers one target of a multi-target provider and offers newer available evidence for another target. Add that regression and prove the sequence advances without recovery before a later exact-target observation recovers.

### Symbol References

None. No symbol is renamed or removed.

### Split Judgment

Keep one packet. The lowered binding, provider high-water mark, recovery transition, and regression share one queue-locked invariant. Dependency `07+06_reception_fence` is satisfied by the archived `complete.log` cited above.

### Scope Rationale

Exclude Node probe generation, wire schemas, command parsing, admission/snapshot implementations, config health, ingress retry policy, metrics, contracts, and specs. They already provide or describe the required invariant; R2 is confined to the Edge overlay transition and its deterministic regression.

### Final Routing

- `evaluation_mode=isolated-reassessment`; `status=routed`; finalizer=`finalize-task-policy.sh`; mode=`pair`.
- Build closures: `scope_closed=true`, `context_closed=true`, `verification_closed=true`, `evidence_trusted=true`, `ownership_closed=true`, `decision_closed=true`; capability gap: none.
- Build scores: `scope_coupling=1`, `state_concurrency=2`, `blast_irreversibility=1`, `evidence_diagnosis=1`, `verification_complexity=1`; base=`local-fit`, route=`recovery-boundary`, lane=`cloud`, grade=`G06`, filename=`PLAN-cloud-G06.md`.
- Review closures are all true; capability gap: none. Review scores: `scope_coupling=1`, `state_concurrency=2`, `blast_irreversibility=1`, `evidence_diagnosis=1`, `verification_complexity=1`; route=`official-review`, lane=`cloud`, grade=`G06`, filename=`CODE_REVIEW-cloud-G06.md`, adapter=`codex`, model=`gpt-5.6-sol`, reasoning=`xhigh`.
- `large_indivisible_context=false`; positive loop risks: `temporal_state`, `concurrent_consistency`, `boundary_contract`, `variant_product` (4); `risk_boundary_matched=true`; `review_rework_count=2`; `evidence_integrity_failure=false`; `recovery_boundary_matched=true`.

## Implementation Checklist

- [ ] REVIEW_REFACTOR-1 preserves the lowered adapter/target binding, advances a newer cross-target observation without recovery, and recovers only on a later exact-target available observation.
- [ ] Add a deterministic multi-target regression while retaining catalog-ambiguity and available-before-terminal coverage.
- [ ] Run focused, package, race, vet, provider smoke, local-capacity smoke, and diff verification with fresh output; do not retry the unchanged blocked live endpoints.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [REVIEW_REFACTOR-1] Preserve the lowered recovery binding

**Problem:** `apps/edge/internal/service/model_queue_release.go:249` derives `recovered` from `overlay.unavailable` alone, then overwrites `overlay.adapter` and `overlay.target`. A multi-target provider lowered for target B is therefore recovered by a newer available observation for target A.

**Before (`apps/edge/internal/service/model_queue_release.go:249`):**

```go
recovered := overlay.unavailable
overlay.adapter = adapter
overlay.target = target
overlay.observationSeq = sequence
overlay.unavailable = false
```

**Solution:** Keep the provider-global sequence high-water mark, but make recovery depend on the exact binding that lowered health. A newer cross-target available observation advances `observationSeq` while preserving the unavailable binding/state and returns false. A later available observation matching that binding clears the overlay and pumps once.

```go
recovered := overlay.unavailable && overlay.adapter == adapter && overlay.target == target
overlay.observationSeq = sequence
if overlay.unavailable && !recovered {
	return false
}
overlay.adapter = adapter
overlay.target = target
overlay.unavailable = false
```

**Modified Files and Checklist:**

- [ ] `apps/edge/internal/service/model_queue_release.go`: preserve exact lowered binding while advancing cross-target provider sequence.
- [ ] `apps/edge/internal/service/provider_health_overlay_test.go`: add multi-target cross-recovery rejection, high-water advancement, and later exact-target recovery coverage.

**Test Strategy:** Add `TestProviderHealthOverlayCapabilitiesRecoveryRequiresLoweredBinding`. Configure one provider with targets A and B, lower B at sequence 1, offer A available at sequence 2, and assert no recovery, unavailable remains true, sequence becomes 2, and the B binding remains. Then offer B available at sequence 3 and assert exact recovery.

**Verification:** Run the focused recovery suite 50 times; the new test and all existing catalog/high-water/rejection cases must execute and pass.

## Dependencies and Execution Order

1. Predecessor `07+06_reception_fence` is satisfied by `agent-task/archive/2026/08/m-node-provider-execution-liveness-recovery/07+06_reception_fence/complete.log`.
2. Complete REVIEW_REFACTOR-1 before rerunning the full verification suite.

## Modified Files Summary

| File | Item |
|------|------|
| `apps/edge/internal/service/model_queue_release.go` | REVIEW_REFACTOR-1 |
| `apps/edge/internal/service/provider_health_overlay_test.go` | REVIEW_REFACTOR-1 |
| `agent-task/m-node-provider-execution-liveness-recovery/08+07_health_overlay/CODE_REVIEW-cloud-G06.md` | REVIEW_REFACTOR-1 |

## Final Verification

Fresh Go output is required; cached output is not acceptable.

1. `go test -count=50 ./apps/edge/internal/service -run '^(TestProviderHealthOverlayCapabilitiesRecoveryRequiresLoweredBinding|TestProviderHealthOverlayCapabilitiesRecoveryRejectsCatalogAmbiguity|TestProviderHealthOverlayCapabilitiesRecoveryPreservesAvailableHighWater|TestProviderHealthOverlayCapabilitiesRecoveryRejectsInconclusiveEvidence|TestProviderHealthOverlayCapabilitiesRecovery)$'` — PASS and every named test executes.
2. `go test -count=20 ./apps/edge/internal/service -run '^(TestProviderHealthOverlay|TestReceived.*Failure|Test.*ReleaseOnce)' && go test -count=10 ./apps/node/internal/node ./apps/edge/internal/service -run '^(TestCapabilitiesHealthEvidence|TestProviderHealthOverlayCapabilitiesRecovery)'` — PASS.
3. `go test -count=1 ./packages/go/execution ./apps/node/... ./apps/edge/internal/node ./apps/edge/internal/transport ./apps/edge/internal/bootstrap ./packages/go/streamgate ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/edge/internal/controlplane` — PASS.
4. `go test -race -count=3 ./apps/node/internal/node ./apps/edge/internal/node ./apps/edge/internal/transport ./apps/edge/internal/service` — PASS with no timeout or race report.
5. `go vet ./packages/go/execution ./apps/node/... ./apps/edge/internal/node ./apps/edge/internal/transport ./apps/edge/internal/bootstrap ./packages/go/streamgate ./apps/edge/internal/openai ./apps/edge/internal/service ./apps/edge/internal/controlplane` — no diagnostics.
6. `./scripts/e2e-smoke.sh` — PASS.
7. `(cd scripts && sed -e 's|^SCRIPT_DIR=.*|SCRIPT_DIR="$(pwd)"|' -e 's|TMP_DIR="$(mktemp -d /tmp/iop-provider-capacity-smoke.XXXXXX)"|TMP_DIR="$(mktemp -d "$REPO_ROOT/.tmp/iop-provider-capacity-smoke.XXXXXX")"|' e2e-provider-capacity-smoke.sh | bash)` — PASS with final provider available and counters zero.
8. `git diff --check` — no whitespace errors.

Do not rerun the unchanged blocked long-context external endpoints in this packet. Preserve their archived evidence for official review.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
