<!-- task=m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual plan=3 tag=REVIEW_REVIEW_TEST milestone-task=hot-smoke -->

# Plan - Production-Truthful Hot Path Agent Smoke Evidence

## For the Implementing Agent

Filling the implementation-owned sections of `CODE_REVIEW-cloud-G09.md` is mandatory. Run every verification command, paste actual output or an exact saved-output path, keep both active files in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields; 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

The current harness passes its fake self-test but does not consume the production Edge observation lifecycle or the installed Pi JSON event stream. It can reject a real successful light trace, accept a direct trace without a terminal record, and report an empty reserved job directory as clean. These repository-fixable evidence defects must be closed before the missing SDD S16 actual Claude/Pi matrix can be trusted.

## Archive Evidence Snapshot

- `code_review_cloud_G07_2.log` records the current `FAIL`: Required R2 is the production observation reducer mismatch, R4 is the unsupported Pi 0.81.1 `AgentSessionEvent` contract, R5 is empty reserved-directory leakage, and R3 is the still-missing actual 10-case matrix. It records fresh local syntax, self-test, race, exit-fidelity, and diff checks plus all 17 external input names as unset.
- `plan_cloud_G07_2.log` is the superseded implementation packet. Its identity binding and fresh byte-range design remain useful, but its fake observation/Pi fixtures are not production-truthful.
- `agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/20+17,19_smoke_harness/complete.log` proves only the earlier fake-agent harness baseline; it is not actual S16 evidence.
- Roadmap scope remains `milestone-task=hot-smoke`. No Milestone completion is claimed.

## Finding Resolution Map

| Finding | Mode | Exact fix/evidence | Changed or satisfied precondition |
|---|---|---|---|
| Required R2 | direct-fix | `scripts/e2e-hot-path-agents.sh`: consume only exact production observation messages, close the lifecycle within a bound, reduce retry attempts by disposition, and add production-trace/missing-terminal/foreign-message controls. | Replaces a one-record-per-stage fake oracle with the production Edge lifecycle contract, so external observation evidence becomes admissible. |
| Required R4 | direct-fix | `scripts/e2e-hot-path-agents.sh`: parse Pi `AgentSessionEvent` JSON and signal-exit cancellation, make fake Pi output native, and assert scenario-relevant stage/tool visibility. | Replaces an OpenAI `choices` parser that returns no Pi events with the installed Pi JSON contract, so the five Pi cases can reach terminal validation. |
| Required R5 | direct-fix | `scripts/e2e-hot-path-agents.sh`: classify any reserved request path as artifact presence and add an empty-directory survivor negative control. | Prevents cleanup success from accepting leaked request state while retaining timeout-orphan evidence. |
| Required R3 | direct-fix | `scripts/e2e-hot-path-agents.sh` plus `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/CODE_REVIEW-cloud-G09.md`: after R2/R4/R5, run the exact external preflight/matrix and record the actual manifest evidence or the exact remaining blocker without an S16 completion claim. | The unchanged-precondition loop is removed first; the external run then exercises a production-compatible harness instead of repeating the rejected implementation. |

## Analysis

### Files Read

- `Makefile`
- `scripts/e2e-hot-path-agents.sh`
- `scripts/fixtures/hot-path-agent-smoke-manifest.schema.json`
- `apps/edge/internal/openai/hot_path_observation.go`
- `apps/edge/internal/openai/hot_path_observation_test.go`
- `agent-roadmap/phase/knowledge-tool-optimization-extension/milestones/iop-hot-path-one-shot-execution.md`
- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`
- `agent-spec/runtime/stream-evidence-gate.md`
- `agent-spec/input/openai-compatible-surface.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/outer/anthropic-compatible-api.md`
- `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/plan_cloud_G07_2.log`
- `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/code_review_cloud_G07_2.log`
- `agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/20+17,19_smoke_harness/complete.log`
- `/config/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/dist/modes/print-mode.js`
- `/config/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core/dist/types.d.ts`

### SDD Criteria

- SDD: `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`, status approved, lock released.
- Milestone task: `hot-smoke`.
- Target scenario: S16, actual Claude/Pi direct, light pass, repair, write-unavailable, and timeout/cancel smoke with visible protocol/stage output, artifact lifecycle, and standard terminal behavior.
- Evidence Map driver: actual Claude/Pi streaming logs plus matching runtime/source identity and workspace before/after evidence. This requires the implementation checklist to validate the production observation and Pi protocols, workspace cleanup/orphan state, and the exact 2x5 manifest before any PASS claim.

### Verification Context

No neutral `verification_context` handoff was supplied. Repository-native evidence came from the source, schema, production observation tests, prior same-task review, installed Pi 0.81.1 print-mode source/types, and fresh read-only probes.

- Fresh reviewer checks: `bash -n scripts/e2e-hot-path-agents.sh`, `TMPDIR=/config/workspace/iop-s0 make test-hot-path-agent-smoke-self-test`, the exact four-package `go test -race -count=1` command, and `git diff --check` all passed.
- Production observation probe: the `hotPathPassTrace` lifecycle was rejected (`production_pass_trace_rc=1`), while a dispatch-only direct trace without a terminal was accepted (`missing_terminal_direct_rc=0`).
- Pi probe: a native `AgentSessionEvent` JSON stream produced `pi_visible_event_count=0` under the current parser. Installed Pi is 0.81.1 and its print mode serializes `session.subscribe(event)` directly; SIGTERM exits 143 after disposal rather than emitting an OpenAI `finish_reason` object.
- Current checkout: `/config/workspace/iop-s0`, branch `feature/iop-hot-path-one-shot-execution`, HEAD `703f3b72`, Linux/arm64, Go 1.26.2. The worktree is shared and dirty; preserve unrelated changes. Source synchronization to an external runner is not established.

#### External Verification Preflight

- Runner/workdir: current host at `/config/workspace/iop-s0`; no authorized matching isolated Edge runner was selected.
- Binaries: installed Claude 2.1.221 and Pi 0.81.1 exist, but the required caller-selected CLI and Edge binary paths/digests are unset.
- Config/runtime: Edge config, Pi config directory/provider, four preset aliases, base URL, runtime evidence file, live observation file, workspace parent, output path, and both secret-env names are unset.
- Runtime identity/ports/hosts: no matching runtime identity, listener, external host, or port was supplied; do not infer one from CLI installation.
- OS/architecture: current host is Linux/arm64. External host assumptions remain unknown until the caller supplies the exact runtime evidence.
- Setup/resume: after repository fixes, select/start the matching isolated Edge runtime, export all 17 declared inputs without printing their values, regenerate runtime evidence for the current worktree and exact binaries/config/profile, then run `make test-hot-path-agent-smoke-preflight` followed by `make test-hot-path-agent-smoke`.
- Gap/confidence: actual external execution is unavailable now, but repository root causes and deterministic local regression oracles are high confidence. If inputs remain unavailable after the fixes, record the exact preflight blocker; do not claim S16 complete.

### Test Coverage Gaps

- Observation lifecycle: current self-test covers stale/rotation/mixed/wrong-stage byte ranges but not the production repeated-attempt trace, exact message name, terminal closure, disposition, or orphan contradiction.
- Pi protocol: current fake Pi emits OpenAI `choices` objects, so it does not cover installed Pi `AgentSessionEvent` start/message/tool/end/error behavior or signal exit 143.
- Workspace lifecycle: content-changing and file-present cases are covered, but an empty surviving `.iop/job/<request-id>` directory is not.
- Actual S16: no local test substitutes for the matching credentialed 10-case matrix; it remains final external evidence.

### Symbol References

No public symbol is renamed or removed. Internal shell functions `capture_appended_observation`, `workspace_snapshot`, `parse_visible_events`, `derive_case_result`, `run_case`, `write_fake_binary`, and their self-test call sites remain in one script and must be updated together.

### Split Judgment

Keep one plan. Production observation closure, native Pi terminals, child-only cancellation, workspace artifact state, and manifest derivation are one evidence-integrity invariant: no child can independently PASS S16 while another still permits fabricated or rejected case evidence. The boundary is explicit and locally testable, so `large_indivisible_context=false` even though the final matrix is external.

### Scope Rationale

Modify only `scripts/e2e-hot-path-agents.sh` and the active review evidence file. Keep `Makefile`, the manifest schema, Edge production code/tests, OpenAI/Anthropic contracts, roadmap, SDD, agent-spec, and installed Pi package read-only: their current contracts are the source of truth and the generic manifest vocabulary can represent the corrected projections. Do not change provider behavior, deployment, shared runtime state, secret values, or tracked external smoke output.

### Final Routing

- `status=routed`, `evaluation_mode=isolated-reassessment`, `finalizer=finalize-task-policy.sh`, mode `pair`.
- Build closures: scope/context/verification/evidence/ownership/decision all `true`; basis is the complete follow-up packet and exact local/external verification contract. Scores: scope 2, state 2, blast 1, evidence 2, verification 2 = G09. Base/final route basis `grade-boundary`; cloud, `PLAN-cloud-G09.md`.
- Review closures: scope/context/verification/evidence/ownership/decision all `true`. Scores: scope 2, state 2, blast 1, evidence 2, verification 2 = G09. Route basis `official-review`; cloud, Codex `gpt-5.6-sol` xhigh, `CODE_REVIEW-cloud-G09.md`.
- `large_indivisible_context=false`; positive loop-risk signatures: `temporal_state`, `concurrent_consistency`, `boundary_contract`, `structured_interpretation`, `variant_product` (count 5).
- Recovery signals: `review_rework_count=2`, `evidence_integrity_failure=true`; risk and recovery boundaries match but do not replace the G09 `grade-boundary` basis. No capability gap is claimed.

## Implementation Checklist

- [ ] [REVIEW_REVIEW_TEST-1] Make per-case observation capture parse exact production messages, wait boundedly for a closed lifecycle, reduce attempts into schema stages, and reject missing/foreign/contradictory terminal, cleanup, or orphan records with production-trace controls.
- [ ] [REVIEW_REVIEW_TEST-2] Parse installed Pi `AgentSessionEvent` JSON and process-exit cancellation, require scenario-relevant visible stage/tool output, and replace fake Pi OpenAI-choice fixtures with native positive, error, and cancel controls.
- [ ] [REVIEW_REVIEW_TEST-3] Treat any reserved request path as artifact presence, add empty-directory survivor coverage, rerun local regression, then execute the matching external preflight/matrix and record the actual manifest or exact blocker without an S16 completion claim.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [REVIEW_REVIEW_TEST-1] Close the Production Observation Lifecycle

**Problem:** `scripts/e2e-hot-path-agents.sh:438-477` accepts records by field presence, discards terminal/light/orphan data, and compares raw projected stages to a one-record-per-stage fixture. Production emits repeated stage attempts and an explicit terminal; the current reducer rejects the success trace and accepts a missing-terminal direct trace.

**Solution:** Parse only `msg == "hot_path_observation"`, retain the closed event class, stage, attempt, disposition, reason, cleanup, and orphan fields, and acquire appended records until a bounded scenario-specific closure predicate is met. Validate exactly one request lifecycle; reject unknown/foreign/late/mixed/contradictory records. Collapse successful stage attempts to one manifest stage only after their order and terminal disposition are proven.

Before (`scripts/e2e-hot-path-agents.sh:438`):

```bash
projected=$(jq -c -s '
    [ .[]
      | select(type == "object")
      | select(((.hot_path_event_class // "") | type == "string") and ((.hot_path_event_class // "") != ""))
```

After:

```bash
projected=$(jq -c -s '
    [ .[]
      | select(type == "object" and .msg == "hot_path_observation")
      | {raw_rid:.hot_path_request_id, ec:.hot_path_event_class,
         sk:(.hot_path_stage_kind // ""), attempt:(.hot_path_attempt_bucket // ""),
         disposition:(.hot_path_disposition // ""), reason:(.hot_path_reason // ""),
         cleanup:(.hot_path_cleanup_outcome // ""), orphan:(.hot_path_orphan_outcome // "")} ]')
# Validate the full closed lifecycle, then project one ordered row per manifest stage.
```

**Modified Files and Checklist:**

- [ ] `scripts/e2e-hot-path-agents.sh`: implement bounded lifecycle acquisition, validation, and retry-aware projection.
- [ ] `scripts/e2e-hot-path-agents.sh`: make fake observation fixtures emit production pass/repair/failure/cancel shapes and add exact negative controls.
- [ ] `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/CODE_REVIEW-cloud-G09.md`: record actual commands and results.

**Test Strategy:** Add regression assertions inside the existing self-test. Accept the full `hotPathPassTrace` stage attempts; reject foreign-message field lookalikes, direct without terminal, duplicate/conflicting terminals, cleanup without success, unexpected orphan, and post-bound lifecycle timeout. No separate test file is needed because the production and fake entry paths are intentionally exercised through the same shell functions.

**Verification:** `bash -n scripts/e2e-hot-path-agents.sh && TMPDIR=/config/workspace/iop-s0 make test-hot-path-agent-smoke-self-test` must exit 0 and print the new production-trace and lifecycle-negative assertion labels.

### [REVIEW_REVIEW_TEST-2] Consume Native Pi JSON Events

**Problem:** `scripts/e2e-hot-path-agents.sh:539-548` parses OpenAI response chunks. Pi 0.81.1 JSON mode serializes `AgentSessionEvent`, whose terminal evidence is carried by assistant messages/`agent_end` and whose tools use `tool_execution_*`; SIGTERM exits 143 without an OpenAI cancellation object.

**Solution:** Map native Pi `agent_start`, assistant `message_update`/`message_end`, `tool_execution_start`/`tool_execution_end`, and `agent_end` into the closed visible-event vocabulary. Derive success/error from the final assistant `stopReason`, and synthesize cancellation only from the harness-owned triggered child-only signal plus exit 143 and absence of a contradictory successful/error terminal. Require stage/tool evidence appropriate to light-pass, repair, and cleanup scenarios instead of accepting a terminal-only fake stream.

Before (`scripts/e2e-hot-path-agents.sh:539`):

```jq
if ((.choices[0].finish_reason) // null) != null then
    if .choices[0].finish_reason == "stop" then {kind:"terminal_success", detail:"success"}
```

After:

```jq
if .type == "agent_start" then {kind:"system_init", detail:"init"}
elif .type == "tool_execution_start" then {kind:"tool_use", detail:tool_detail(.toolName)}
elif .type == "tool_execution_end" then {kind:"tool_result", detail:(if .isError then "error" else "ok" end)}
elif .type == "message_end" and .message.role == "assistant" then
    # Retain the final closed stopReason for terminal derivation.
elif .type == "agent_end" then
    # Emit exactly one success/error terminal from the final assistant message.
```

**Modified Files and Checklist:**

- [ ] `scripts/e2e-hot-path-agents.sh`: implement native Pi parsing and process/cancellation reconciliation.
- [ ] `scripts/e2e-hot-path-agents.sh`: replace all fake Pi `choices` JSON with actual `AgentSessionEvent` fixtures and assert required tool/stage visibility.
- [ ] `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/CODE_REVIEW-cloud-G09.md`: record Pi version/contract and verification output without raw content.

**Test Strategy:** Add native Pi direct success, tool pass, repair, tool error, assistant error, and SIGTERM/exit-143 cases to the self-test. Assert one terminal, correct tool labels, correct order, and rejection of OpenAI `choices` lookalikes or an `agent_end` without a terminal-capable assistant message.

**Verification:** The syntax/self-test command must pass. The external matrix must later produce five Pi cases with non-empty ordered visible events, scenario-relevant tool/stage evidence, and terminals consistent with process exit/cancellation.

### [REVIEW_REVIEW_TEST-3] Enforce Workspace Cleanup and Produce Actual Evidence

**Problem:** `scripts/e2e-hot-path-agents.sh:493-503` considers artifacts present only when a file exists under `.iop/job`; an empty request directory can survive a successful cleanup unnoticed. Separately, `code_review_cloud_G07_2.log` records no actual S16 matrix because all external inputs were absent.

**Solution:** Mark artifacts present when any reserved job/request path exists, not only a regular file. Add an empty-directory survivor control and keep timeout orphan classification based on a surviving reservation. After all local corrections pass, run the exact matching-runtime preflight and 2x5 matrix; record raw-safe command output and manifest assertions in the active review, or record the first exact blocker and resume condition without a completion claim.

Before (`scripts/e2e-hot-path-agents.sh:496`):

```bash
if [ -d "$ws/.iop/job" ] && [ -n "$(find "$ws/.iop/job" -type f -print -quit 2>/dev/null)" ]; then
    artifacts=true
fi
```

After:

```bash
if [ -e "$ws/.iop/job" ] && [ -n "$(find "$ws/.iop/job" -mindepth 1 -print -quit 2>/dev/null)" ]; then
    artifacts=true
fi
```

**Modified Files and Checklist:**

- [ ] `scripts/e2e-hot-path-agents.sh`: detect surviving reserved paths and preserve cleanup/orphan derivation.
- [ ] `scripts/e2e-hot-path-agents.sh`: add empty-request-directory success rejection and timeout-orphan acceptance controls.
- [ ] `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/CODE_REVIEW-cloud-G09.md`: record fresh local and external evidence or the exact external blocker.

**Test Strategy:** Add an empty `.iop/job/<request-id>` survivor to the fake success path and require exit 69/no manifest; retain a timeout case whose reserved path is classified as an orphan. Then run the actual matrix because fake tests cannot satisfy S16.

**Verification:** Run the full final verification below. The actual manifest must contain the fixed ten ids/outcomes, trusted visible/observation/workspace evidence, and `.redaction.matches == 0`; otherwise the review remains non-PASS.

## Modified Files Summary

| File | Items |
|---|---|
| `scripts/e2e-hot-path-agents.sh` | REVIEW_REVIEW_TEST-1, REVIEW_REVIEW_TEST-2, REVIEW_REVIEW_TEST-3 |
| `agent-task/m-iop-hot-path-one-shot-execution/21+20_hot_smoke_actual/CODE_REVIEW-cloud-G09.md` | REVIEW_REVIEW_TEST-1, REVIEW_REVIEW_TEST-2, REVIEW_REVIEW_TEST-3 evidence |

## Final Verification

Run from `/config/workspace/iop-s0` and record actual stdout/stderr. Fresh execution is required; Go test cache is not acceptable.

```bash
bash -n scripts/e2e-hot-path-agents.sh
TMPDIR=/config/workspace/iop-s0 make test-hot-path-agent-smoke-self-test
go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service
git diff --check
```

Expected: all commands exit 0. The self-test explicitly reports production retry-trace acceptance, missing/foreign/contradictory lifecycle rejection, native Pi success/error/cancel parsing, scenario-relevant tool visibility, empty reserved-directory rejection, timeout orphan acceptance, and all retained identity/redaction/schema/exit controls.

External presence-only preflight; never print values:

```bash
test -n "${IOP_HOT_SMOKE_BASE_URL:-}"
test -n "${IOP_HOT_SMOKE_DIRECT_MODEL:-}" && test -n "${IOP_HOT_SMOKE_PASS_MODEL:-}"
test -n "${IOP_HOT_SMOKE_REPAIR_MODEL:-}" && test -n "${IOP_HOT_SMOKE_SLOW_MODEL:-}"
test -n "${IOP_HOT_SMOKE_CLAUDE_BIN:-}" && test -x "$IOP_HOT_SMOKE_CLAUDE_BIN"
test -n "${IOP_HOT_SMOKE_PI_BIN:-}" && test -x "$IOP_HOT_SMOKE_PI_BIN"
test -n "${PI_CODING_AGENT_DIR:-}" && test -d "$PI_CODING_AGENT_DIR"
test -n "${IOP_HOT_SMOKE_PI_PROVIDER:-}"
test -n "${IOP_HOT_SMOKE_EDGE_BIN:-}" && test -x "$IOP_HOT_SMOKE_EDGE_BIN"
test -n "${IOP_HOT_SMOKE_EDGE_CONFIG:-}" && test -f "$IOP_HOT_SMOKE_EDGE_CONFIG"
test -n "${IOP_HOT_SMOKE_RUNTIME_EVIDENCE:-}" && test -f "$IOP_HOT_SMOKE_RUNTIME_EVIDENCE"
test -n "${IOP_HOT_SMOKE_OBSERVATION_FILE:-}" && test -f "$IOP_HOT_SMOKE_OBSERVATION_FILE"
test -n "${IOP_HOT_SMOKE_WORKSPACE_PARENT:-}" && test -d "$IOP_HOT_SMOKE_WORKSPACE_PARENT"
test -n "${IOP_HOT_SMOKE_OUTPUT:-}"
test -n "${IOP_HOT_SMOKE_CLAUDE_SECRET_ENV:-}" && test -n "${!IOP_HOT_SMOKE_CLAUDE_SECRET_ENV:-}"
test -n "${IOP_HOT_SMOKE_PI_SECRET_ENV:-}" && test -n "${!IOP_HOT_SMOKE_PI_SECRET_ENV:-}"
make test-hot-path-agent-smoke-preflight
make test-hot-path-agent-smoke
jq -e '
  .schema_version == "1"
  and ([.cases[].id] == ["claude:direct","claude:light-pass","claude:repair","claude:write-unavailable","claude:timeout-cancel","pi:direct","pi:light-pass","pi:repair","pi:write-unavailable","pi:timeout-cancel"])
  and ([.cases[].outcome] == ["completed","completed","completed","error","cancelled","completed","completed","completed","error","cancelled"])
  and all(.cases[]; (.visible_events | length) > 0 and (.observation | length) > 0)
  and all(.cases[] | select(.scenario == "light-pass" or .scenario == "repair"); any(.visible_events[]; .kind == "tool_use"))
  and (.redaction.matches == 0)
' "$IOP_HOT_SMOKE_OUTPUT"
```

Expected: presence checks, preflight, matrix, and `jq` all exit 0 against the matching isolated runtime. If any external input or authorization remains unavailable, stop after the first exact failed command and record its output, runner identity, missing input name, and resume condition in `CODE_REVIEW-cloud-G09.md`; do not claim S16 completion.

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