fix: classify settled spawned TTL cleanup correctly - #469

Summary

Closes ENG-147.

This change makes spawned-session TTL cleanup state-aware. A child whose prompt has already settled is now reaped as a clean completed session, while a prompt that is still in flight at the stop transition remains a timeout failure.

The existing cleanup lifecycle remains intact: lease release, process teardown, spawn.ttl_expired, spawn.reaped, session stop hooks, durable stop origin, and creator wake delivery continue to use their existing paths and exact-once success semantics.

Root cause

The spawn reaper previously mapped every ttl_expired candidate to session.CauseTimeout. That cleanup reason was therefore indistinguishable from an active prompt timeout.

The session lifecycle then projected the stop as:

• StopTimeout
• a timeout failure payload
• a transcript.MarkerPromptTimeout
• a failed parent wake/badge

even when the child had already received a durable done or end_turn event and had no active prompt.

Design

• Added an internal CauseSpawnTTLExpired request and Manager.StopWithSpawnTTL operation.
• The concrete session manager resolves that request under the session lifecycle lock, at the same transition that changes the session to stopping.
  • Active prompt setup/turn state becomes CauseTimeout.
  • Settled prompt state becomes CauseCompleted.
  • A prompt admitted after the lifecycle lock is rejected by the stopping state instead of racing into a clean classification.
• The clean path preserves spawn_reaper:ttl_expired as the durable stop detail.
• Transport-only session adapters that do not expose the atomic operation conservatively retain the historical timeout classification; they cannot prove that a prompt stayed settled through the stop transition.
• Hook/payload helpers were split into spawn_reaper_hooks.go so production files remain below the repository's 500-line cap.

Changed surfaces

• Runtime daemon spawn reaper classification and atomic TTL stop dispatch.
• Session stop-cause resolution and clean stop-detail persistence.
• Lifecycle projections covering failure absence, timeout-marker absence, stopped notifier, and parent wake badge.
• Daemon reaper tests for settled, in-flight, atomic-adapter, and conservative-fallback paths.
• Session stop-reason and lifecycle contract tests.
• skills/compozy/references/runtime-operations.md now documents the settled-versus-in-flight TTL behavior.
• QA tracker:
  • added RT-spawn-ttl-cleanup
  • reset the affected RT-session-spawn-wake scenario
  • recorded focused evidence and explicit provider-backed blocked-verify instructions in docs/qa/reports/2026-08-24-eng-147-ttl-cleanup.md

Lifecycle and exactly-once behavior

The change does not reorder or duplicate the existing reaper sequence:

1. dispatch the reason hook;
2. release child run leases with spawn_reaper:ttl_expired;
3. stop the child through the session lifecycle;
4. dispatch spawn.reaped;
5. let the existing session finalization path emit one stopped notification and one creator wake.

The clean branch only changes the stop classification. It does not suppress process teardown, lease release, hooks, or creator wake. Existing failure-path ordering and error reporting are intentionally unchanged because durable retry/idempotency semantics would be a separate design.

Tests and focused verification

Passing focused checks:

• go test -race ./internal/daemon -run 'TestSpawnReaper' -count=1 — 9 tests passed.
• go test -race ./internal/session -run 'Test(ClassifyStopReason|SpawnTTLStopCauseUsesPromptStateAtLifecycleTransition|CompletedSpawnReapKeepsCleanTerminalProjection|PromptActivitySupervisorTimeoutCancelsThenStopsSession)$' -count=1 — 22 tests passed.
• go run github.com/golangci/golangci-lint/v2/cmd/[email protected] run --new-from-rev origin/main --timeout 10m --concurrency 8 ./internal/daemon/... ./internal/session/... — 0 new issues.
• git diff --check — passed.
• Compozy test-shape checks for internal/daemon/spawn_reaper_test.go and internal/session/stop_reason_test.go — passed.

make gate was attempted as the focused repository gate. It reached the scoped Go packages but is currently blocked by 56 pre-existing lint findings elsewhere in internal/daemon/... and internal/session/... (goconst/gocritic baseline findings); no new-code findings remain. Per the ENG-147 request, make gate-full, make verify, and other full-monorepo gates were not run.

A provider-backed CLI/HTTP/UDS QA walk is recorded as blocked-verify because this review environment has no isolated ACP provider. The automated lifecycle evidence is committed, with exact human walk instructions in the QA report.

Risks and trade-offs

• The clean TTL path is available only when the concrete session manager can make the atomic decision. Unknown prompt state in a transport-only adapter remains a timeout for safety.
• The stop-origin detail is now retained for clean completion, which improves public diagnosis without changing the stop reason enum.
• No schema, migration, config, provider, or native tool contract changes are required.

Compozy Impact Audit

• Native tools: no compozy__* tool IDs, toolsets, descriptors, schemas, digests, risk flags, capability gates, or CLI/API fallbacks changed; checked the session-spawn and session-status projection surfaces.
• Extensibility and hooks: no extension registry or config lifecycle changes; existing spawn.ttl_expired, spawn.reaped, session stop hooks, lease release, and creator wake hooks remain wired exactly once on the success path; the official runtime-operations skill reference was updated.
• Workspace data isolation: no new datum or scope was introduced; stop cause/detail remain session-scoped, and parent wake resolution continues through the existing child lineage/workspace path without cross-workspace reads.
• Official Compozy skill: updated skills/compozy/references/runtime-operations.md with the state-aware TTL cleanup rule.

Review resolution

The required GPT-5.6-Sol high-reasoning review identified a possible snapshot race and an unsafe adapter fallback. Both are addressed by the atomic StopWithSpawnTTL lifecycle operation and conservative timeout fallback. The review also examined lease/hook behavior on partial failures; that ordering is unchanged from the base branch and is intentionally outside this classification fix.

Summary by CodeRabbit

• Bug Fixes
  • Improved spawn session expiration handling by distinguishing completed sessions from sessions interrupted during an active prompt or turn.
  • Preserved clean completion details and terminal status for sessions that finish before expiration.
  • Added lifecycle notifications for session stops and reaping events.
  • Improved cleanup and lease release behavior after expired sessions.