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.
This commit is contained in:
2026-10-18 11:17:01 +01:00
parent b93eee234c
commit 31d8f4a6d5
8 changed files with 363 additions and 8 deletions
+42
View File
@@ -0,0 +1,42 @@
# 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.