<!-- task=m-node-provider-execution-liveness-recovery/04+03_health_evidence plan=0 tag=API milestone-task=health-classification -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST]** Fill every implementation-owned section after implementation. Do not append a verdict, archive files, write `complete.log`, commit, push, or change roadmap state.

## Overview

date=2026-08-03
task=m-node-provider-execution-liveness-recovery/04+03_health_evidence, plan=0, tag=API

## For the Review Agent

> **[REVIEW AGENT ONLY]** Compare every item to source and recorded output. Append a verdict only during later official review.

1. On later review, archive this file to `code_review_cloud_G08_0.log` and the plan to `plan_cloud_G08_0.log`.
2. PASS finalization preserves `milestone-task=health-classification`; roadmap aggregation remains owned by `sync-milestone-workstate`.

## Implementation Item Completion

| Item | Status |
|------|---------|
| API-1 — Session observation sequence | [x] |
| API-2 — terminal evidence integration | [x] |
| TEST-1 — temporal/wire evidence | [x] |
| DOC-1 — Node evidence boundary | [x] |

## Implementation Checklist

- [x] [API-1] Add one connection-scoped atomic health-observation sequence source.
- [x] [API-2] Enrich the already-claimed normalized and tunnel stall terminals after bounded probe/fence completion.
- [x] [TEST-1] Prove sequence scope, concurrency, terminal invariants, metadata parity, and no progress reset.
- [x] [DOC-1] Update execution/wire contracts and the matching execution spec without claiming Edge projection.
- [x] Run every command in Final Verification and record exact results in `CODE_REVIEW-cloud-G08.md`.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** Implementing agents must leave this section unchanged.

- [x] Append exactly one PASS/WARN/FAIL verdict with routing signals.
- [x] Verify evidence and dimension assessment match the verdict.
- [x] Archive active files to `code_review_cloud_G08_0.log` and `plan_cloud_G08_0.log`.
- [x] Verify the Agent-Ops managed `.gitignore` block.
- [ ] If PASS, write `complete.log`, preserve milestone metadata, and archive this task directory.
- [x] If WARN/FAIL, write only the next state required by the code-review skill.

## Deviations from Plan

Added `liveness_health_evidence.go` as a cohesive extraction from the already
large watchdog coordinator so the production source remains within the
readability file-size threshold. No ownership boundary or externally visible
contract changed.

## Key Design Decisions

`Session` is the sole sequence allocator. A live bound Session provides the
sequencer; internal and unbound paths omit the key. The stall claim starts the
probe and close-grace fence concurrently, waits for both bounded results, then
creates cloned allowlisted maps for normalized failure/event and tunnel error.
Probe availability remains evidence only.

## Reviewer Checkpoints

- Verify `03+02_health_probe_contract` is PASS and this pair consumes its reviewed typed outcome.
- Confirm one atomic sequence belongs to each Session, starts at one, is unique/monotonic across concurrent run/tunnel observations, resets on new Session, and is omitted when unbound.
- Confirm fixed close-grace and bounded probe run concurrently after stall claim rather than adding serial latency.
- Confirm available never resets progress or revives the attempt and every path still emits exactly one terminal.
- Confirm one allowlisted map is cloned into normalized Failure, normalized RuntimeEvent, and tunnel ERROR metadata and survives protobuf conversion.
- Confirm fence/retryability, late-output drop, admission/run/credential ownership, and deadline/disconnect precedence are unchanged.
- Confirm no Edge overlay, stale binding, candidate selection, retry, recovery, raw provider detail, or secret is introduced.

## Verification Results

### `go version && go env GOMOD`

PASS (exit 0): `go version go1.26.2 linux/arm64`; module
`/config/workspace/iop-s1/go.mod`.

### `go test -count=1 ./packages/go/execution ./packages/go/streamgate ./packages/go/config`

PASS (exit 0): execution, streamgate, and config packages passed.

### `go test -count=1 ./packages/go/execution ./apps/node/...`

PASS (exit 0): execution plus all Node packages passed.

### `go test -count=10 ./apps/node/internal/node ./apps/node/internal/transport`

PASS (exit 0): repeated Node and transport test suites passed.

### `go test -race -count=3 ./packages/go/execution ./apps/node/internal/node ./apps/node/internal/transport`

PASS (exit 0): execution, Node, and transport race suites passed.

### `go vet ./packages/go/execution ./apps/node/internal/node ./apps/node/internal/transport`

PASS (exit 0): no vet diagnostics for the requested packages.

### `go test -count=1 ./...`

PASS (exit 0): repository-wide Go test suite passed.

### `./scripts/e2e-smoke.sh`

PASS (exit 0): Node command/cancellation boundary, Edge dispatch/provider tunnel,
queue, and reconnect-fencing smoke packages passed.

### `IOP_DEV_RECONNECT_BIND_TIMEOUT=45 ./scripts/dev/edge-node-reconnect-diagnostic.sh`

FAIL (exit 1): the direct 45-second diagnostic reached its registration timeout
before `scripts/dev/edge.sh` completed its first `go run` startup. Edge printed
its config line but did not open the console listener; the Node was still
waiting for that port. This is a local full-cycle verification blocker, not a
health-evidence assertion failure.

### `make readability-audit`

FAIL (non-zero): the worktree readability ratchet reported existing large-file
violations, including the uncommitted predecessor watchdog test file. The
production watchdog was reduced to the 500-LOC threshold by extracting the
health-evidence helper. Further test-file partitioning is required before a
PASS review.

### `git diff --check`

PASS (exit 0): no whitespace errors.

## Section Ownership

| Section | Owner |
|---------|-------|
| Header, overview, checklist item text, reviewer checkpoints, verification headings | Fixed at stub creation |
| Item/checklist status, deviations, decisions, verification output | Implementing agent |
| Review-only checklist and verdict/finalization | Review agent only |

## Code Review Result

- **Overall Verdict:** FAIL
- **Dimension Assessment:**
  - Correctness: Fail — inconclusive probes can produce a terminal health pair outside the three contractually allowed pairs.
  - Completeness: Fail — the required readability gate still names two files in this task's write set.
  - Test coverage: Fail — no regression drives an available/unavailable raw probe status through an inconclusive normalized health result into terminal metadata.
  - API contract: Fail — emitted health metadata can contradict the approved S03 and inner runtime/wire contracts.
  - Code quality: Fail — the new watchdog test file and expanded provider tunnel test file exceed the repository's test-file readability threshold.
  - Implementation deviation: Fail — the plan required the readability audit to close, but task-local violations remain.
  - Verification trust: Pass — recorded failures were truthful; fresh package checks passed, and a clean rerun of the 45-second Edge-Node diagnostic passed after dependency downloads completed.
  - Spec conformance: Fail — S03 requires `unknown`/`health_unknown` for every inconclusive probe branch.
- **Findings:**
  - Required — `apps/node/internal/node/liveness_health_evidence.go:51`: `provider_health` is copied from `HealthProbeEvidence.Status` while `liveness_classification` is copied from the normalized `Health`. An identity mismatch, deadline recheck, or provider error that also reports `available` can therefore emit the forbidden `available`/`health_unknown` pair. Derive both terminal fields from the normalized health result (or clear status on every inconclusive outcome) and add regression cases for contradictory raw status.
  - Required — `apps/node/internal/node/liveness_watchdog_test.go:1`: the new 1,479-LOC test file is a task-local `split_review` readability violation. Move cohesive lifecycle and health-evidence test groups into focused same-package files so every resulting test file is at or below the 800-LOC warning threshold without changing fixtures or assertions.
  - Required — `apps/node/internal/node/provider_tunnel_test.go:778`: the added successful-tunnel health-scope test raises this file to 830 LOC and creates a task-local readability violation. Move that focused test to a same-package liveness test file and keep the original file at or below 800 LOC.
- **Routing Signals:** `review_rework_count=1`, `evidence_integrity_failure=false`
- **Next Step:** Archive this pair and materialize the routed WARN/FAIL follow-up pair.
