Repository navigation
fix(harnesswire): prepare Connect before journaling - #282
Anish Ramasekar (aramase) merged 5 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
A critical cancellation gap lets sink calls using an independent Run context remain blocked after Close, violating the prepared-run cancellation contract and potentially leaving host-side work running after transport teardown.
1 open issue
What changed in this PR
This PR addresses #276 by preparing the harness Connect stream before journaling a new execution, allowing first-turn setup failures to be retried without leaving misleading history.
Changes:
- Add optional, one-shot harness run preparation and integrate it into
controller.Exec. - Classify preparation outages separately from uncertain delivery failures.
- Reject missing END and unsupported or surplus frames, with regression tests and contract documentation.
| File | Description |
|---|---|
spec.md |
Define preparation, retry, and terminal-event requirements. |
session/error_connect_test.go |
Test retry, public error privacy, and durable protocol failures. |
placement/transport_test.go |
Test checkpoint cancellation during preparation. |
placement/placement.go |
Classify preparation errors and document transport cleanup. |
placement/describe_boundary_test.go |
Test preparation error classification and cleanup. |
harnesswire/prepare_test.go |
Test prepared stream lifecycle and strict terminal handling. |
harnesswire/harnesswire.go |
Implement stream preparation and protocol validation. |
docs/harness-authoring.md |
Explain the optional preparation interface. |
controller/prepare_run_test.go |
Test journal ordering, cleanup, and durable run failures. |
controller/controller.go |
Prepare supported harnesses before execution records. |
changelog/unreleased/harness-run-preparer.md |
Announce the optional Go interfaces. |
changelog/unreleased/harness-connect-preparation.md |
Document retry and protocol-handling fixes. |
api/harness.go |
Define preparation and cancellation contracts. |
Review effort: Balanced
Anish Ramasekar (aramase)
left a comment
There was a problem hiding this comment.
Preparing Connect before the first append is the right shape for #276: no new journal record, and an empty journal is the proof of non-delivery. Two things before this goes in, both inline: one regression in the stricter END handling, and one question about whether a successful Connect proves what the fix needs it to.
Anish Ramasekar (aramase)
left a comment
There was a problem hiding this comment.
Thanks, 90ab5fa resolves both earlier points: END COMPLETED now survives a caller cancel during the flush, and the Connect boundary is documented honestly. One spec sentence still promises more than the code does (inline), plus two small doc fixes that can go in the same push.
Anish Ramasekar (aramase)
left a comment
There was a problem hiding this comment.
LGTM, thanks for working through all the rounds. EXE-43 and EXE-45 now match what the code does, and the post-END and Close cancellation fixes hold. Two optional changelog nits inline. Fine as a follow-up or not at all.
Anish Ramasekar (aramase)
left a comment
There was a problem hiding this comment.
CI is red on this head: golangci-lint in the ci job reports 2 staticcheck issues (https://github.com/agent-primitives/sessions/actions/runs/44039826500/job/134194698957). main is green with the same linter version, so both come from this PR. Details inline.
e14b902
into
agent-primitives:main

Summary
Harness.Connectstream before recording a new execution, without sendingStartSend(Start)is attempted: send/receive failures remain durable and visible in later historyEVENT_END, unsupported events, and frames after END fail the executionProblem
controller.ExecrecordsEXECUTION_STARTand everyINPUTbefore callingHarness.Run. Forharnesswire.ClientHarness,Runpreviously openedHarness.Connectonly after those records committed.If the first Connect failed, no
Startreached the harness, but the next Exec still received the failed execution inStart.History. Claude Code conservatively treats any priorEXECUTION_STARTorINPUTas evidence that it may already have run, so a transient first-turn Connect failure permanently wedged the session witherrStateLost.Design
This PR adds an optional Go SPI extension:
api.HarnessRunPreparerprepares one Run without invoking the harness or sendingStart.api.PreparedHarnessRunis one-shot. It is either run once or closed; concurrent Close prevents or cancels Run.harnesswire.ClientHarnessimplements the extension by opening the actual Connect stream and retaining that exact stream for Run.controller.Execinvokes preparation only after journal/descriptor/model-policy prechecks and before its first append. A preparation failure therefore proves non-delivery and appends nothing. After successful preparation,EXECUTION_STARTand all inputs still commit beforeStartis sent.Resume and reconstruction Replay are unchanged. They operate on already-durable executions and continue through ordinary
Harness.Run.Delivery boundary
Connectpreparation failsSend(Start)failsRecvfails after StartEVENT_ENDor unsupported frameError and privacy behavior
A live-caller Connect outage maps to
UNAVAILABLEwith host-owned reasonHARNESS_UNAVAILABLE. The public message is fixed (placement: harness unavailable); private endpoint or credential-provider text stays only in the Go cause chain. Caller cancellation/deadline retains its own code with no reason.Errors after Start sending are not classified as preparation outages, even if they carry the same gRPC code.
Concurrency and cleanup
placement.Dialerclosers are now documented to interrupt blocked PrepareRun/Run calls and return promptly.EVENT_PARKED+ EOF path.Additional protocol hardening
While validating the certainty boundary, the existing client was found to accept clean EOF without
EVENT_ENDas success and ignore unsupported event kinds. That contradictedWIRE-12and could journal a false successful END. The client now requires exactly one terminal END and rejects surplus frames after it.Closes #276.
Verification
go test -race -shuffle=on ./api ./controller ./harnesswire ./conformance ./placement ./sessiongo test -race ./internal/harnessnode ./harnesswire ./conformancego test ./... -skip '^TestDocumentedPythonExecutorLogsStorageFailureWithoutPayload$'go test ./...inintegrations/claudecodego test ./...inintegrations/substratego vet ./...go build ./...go run ./hack/doccheckgo test ./hack/changeloggo run ./hack/changelog check -base upstream-agentsession/main -head HEAD -skip=falsepython3 hack/check-doc-links.py: 660 links across 76 Markdown filesnpm run build && node hack/check-links.mjsinsite: 19 pages and 18 routesgit diff --checkgofmt -lon all changed Go filesThe excluded root test is an existing macOS Python 3.9.6 portability failure:
sqlite3.OperationalErrorreportssqlite_errornameasunknownwhere the test requiresSQLITE_ERROR. It reproduces on the unmodified base and is unrelated to these changes.