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.
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.