Files
pipelines/docs/notes/stage-timeout-diagnostics.md
alan 31d8f4a6d5 Distinguish active stage deadlines from harness transport failures
Identify configured attempt expiry during V2 active-session idle waits and retain bounded phase, timeout and session diagnostics without claiming a lost response. Preserve genuine operation failures, error identities, redaction, cleanup and admitted-work replay protections. Add stage regressions and scratch-server CLI/websocket retention coverage.

Checked packaged templates in examples and the pipeline template generator: none needs updating because timeout configuration and contracts are unchanged. Checked packaged authoring skill references: debugging.md needs a STAGE DEADLINE playbook and clarified transport guidance. Recorded that stale shared documentation in docs/notes/stage-timeout-diagnostics.md for docs-fold; shared documentation was deliberately not edited.

Verification: go build ./...; go vet ./...; go test ./...; go test -count=1 ./internal/server ./internal/stage ./internal/pipeline ./internal/protocol; go test -count=1 -run TestStageDeadlineDiagnosticThroughCLIAndWebsocket -v ./internal/server; gofmt -l .; git diff --check. All passed. Live-provider behavior not tested; no deploy or deployed-service restart.
2026-10-18 11:17:01 +01:00

2.3 KiB

Stage-timeout diagnostics

Source behavior

The V2 active-session wait now reports STAGE DEADLINE when the configured attempt timer expires between successful polls of a running admitted session. Its bounded diagnostic names the idle-wait phase, configured timeout, retained session, and that the stage had not finished (active at the last poll). It does not claim that a completed response was lost. Cancellation is no longer recorded as a stage deadline. A bare deadline alone is not HARNESS TRANSPORT.

Actual request/HTTP/operation failures keep HARNESS TRANSPORT, their sanitized operation/status evidence and underlying error identities, including when joined with a deadline. A parent deadline no longer discards an accompanying transport failure. Final-result validation, budget accounting, cleanup, interrupts, side effects and replay policy are unchanged. No timeout was increased.

Documentation to fold manually

internal/author/skill/references/debugging.md needs a separate stage-deadline playbook alongside its HARNESS TRANSPORT section: inspect the retained session, last activity, configured limits and unfinished final-result evidence before deciding what to do. Do not blindly retry an admitted mutating stage; edits/tool side effects remain. Explain the distinction between a configured idle-wait overrun, cancellation, an actual failed request with a deadline, budget failure, and final-result validation. Do not infer that all deadline errors are transport failures or that a successful last tool means the stage returned a result.

Evidence and deployment

2026-10-18: installed server build metadata (go version -m /Users/alan/.local/share/pipelines/bin/pipelines-server) identifies revision 0d1ddc73a444fa24110ba5223646856c8f053d29. Comparing that revision with this worktree's initial HEAD showed identical model-failure classification, model attempt timing, V2 polling and agent wait/cleanup paths. The runner difference was unrelated session-export HTML-only metadata.

Regression tests use isolated loopback servers and scratch SQLite databases, with a controlled V2 CLI fixture for the admitted-active-session deadline and real loopback HTTP/refused-connection checks for native transport evidence. This is not a live-provider timeout test. No deployment or deployed-service restart is part of this item; retained historical runs are not rewritten.