Skip to content

fix(harnesswire): prepare Connect before journaling - #282

Merged
Anish Ramasekar (aramase) merged 5 commits into
agent-primitives:mainfrom
Tatsinnit:fix/276-connect-preflight
Nov 17, 2026
Merged

Anish Ramasekar (aramase) merged 5 commits into
agent-primitives:mainfrom
Tatsinnit:fix/276-connect-preflight

Conversation

@Tatsinnit

Copy link
Copy Markdown
Contributor

Summary

  • open the actual Harness.Connect stream before recording a new execution, without sending Start
  • leave no execution records when Connect setup fails, so the same session can retry its first turn
  • preserve fail-closed behavior once Send(Start) is attempted: send/receive failures remain durable and visible in later history
  • make terminal wire handling strict: clean EOF before EVENT_END, unsupported events, and frames after END fail the execution

Problem

controller.Exec records EXECUTION_START and every INPUT before calling Harness.Run. For harnesswire.ClientHarness, Run previously opened Harness.Connect only after those records committed.

If the first Connect failed, no Start reached the harness, but the next Exec still received the failed execution in Start.History. Claude Code conservatively treats any prior EXECUTION_START or INPUT as evidence that it may already have run, so a transient first-turn Connect failure permanently wedged the session with errStateLost.

Design

This PR adds an optional Go SPI extension:

  • api.HarnessRunPreparer prepares one Run without invoking the harness or sending Start.
  • api.PreparedHarnessRun is one-shot. It is either run once or closed; concurrent Close prevents or cancels Run.
  • harnesswire.ClientHarness implements the extension by opening the actual Connect stream and retaining that exact stream for Run.

controller.Exec invokes 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_START and all inputs still commit before Start is sent.

Resume and reconstruction Replay are unchanged. They operate on already-durable executions and continue through ordinary Harness.Run.

Delivery boundary

Failure point Journal result Interpretation
Connect preparation fails No new execution records Positive non-delivery; retry the same cursor/session
Start or input append fails No Start send Existing CAS/incomplete-invocation behavior
Send(Start) fails Attempted execution remains durable Delivery uncertain; fail closed
Recv fails after Start Attempted execution remains durable Delivery uncertain; fail closed
EOF before EVENT_END or unsupported frame Durable failed execution Protocol failure, never implicit success

Error and privacy behavior

A live-caller Connect outage maps to UNAVAILABLE with host-owned reason HARNESS_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

  • The placement connection is registered before preparation, so a stateful Fork can mark it superseded, cancel the idle Connect stream, and wait for fence settlement before snapshotting.
  • A prepared stream is closed on append refusal, partial input persistence, cancellation, checkpoint supersession, or normal Run completion.
  • Custom placement.Dialer closers are now documented to interrupt blocked PrepareRun/Run calls and return promptly.
  • Approval park keeps its separate correlated EVENT_PARKED + EOF path.
  • Host-side sink failures retain their bounded drain so harness spans flush before the turn returns.

Additional protocol hardening

While validating the certainty boundary, the existing client was found to accept clean EOF without EVENT_END as success and ignore unsupported event kinds. That contradicted WIRE-12 and 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 ./session
  • go test -race ./internal/harnessnode ./harnesswire ./conformance
  • go test ./... -skip '^TestDocumentedPythonExecutorLogsStorageFailureWithoutPayload$'
  • go test ./... in integrations/claudecode
  • go test ./... in integrations/substrate
  • go vet ./...
  • go build ./...
  • go run ./hack/doccheck
  • go test ./hack/changelog
  • go run ./hack/changelog check -base upstream-agentsession/main -head HEAD -skip=false
  • clean-checkout python3 hack/check-doc-links.py: 660 links across 76 Markdown files
  • npm run build && node hack/check-links.mjs in site: 19 pages and 18 routes
  • git diff --check
  • gofmt -l on all changed Go files

The excluded root test is an existing macOS Python 3.9.6 portability failure: sqlite3.OperationalError reports sqlite_errorname as unknown where the test requires SQLITE_ERROR. It reproduces on the unmodified base and is unrelated to these changes.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread harnesswire/harnesswire.go Resolved

@aramase Anish Ramasekar (aramase) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread harnesswire/harnesswire.go Resolved
Comment thread harnesswire/harnesswire.go Resolved
Copilot AI balanced review requested due to automatic review settings November 17, 2026 05:59

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the Connect stream preparation and retry-handling changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 17, 2026 06:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the harness connection preparation and retry-boundary changes.

No open issues 🎉

Review effort: Balanced

@aramase Anish Ramasekar (aramase) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread spec.md Resolved
Comment thread spec.md Resolved
Copilot AI balanced review requested due to automatic review settings November 17, 2026 07:34

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the harness preparation and terminal-handling changes.

No open issues 🎉

Review effort: Balanced

@aramase Anish Ramasekar (aramase) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@aramase Anish Ramasekar (aramase) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread harnesswire/harnesswire.go Resolved
Comment thread controller/prepare_run_test.go Resolved
Copilot AI balanced review requested due to automatic review settings November 17, 2026 18:17

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the harness connection preparation and terminal-stream handling changes.

No open issues 🎉

Review effort: Balanced

@aramase
Anish Ramasekar (aramase) merged commit e14b902 into agent-primitives:main Nov 17, 2026
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

claudecode: first-turn harnesswire Connect failure wedges the session with errStateLost

3 participants