docs(spec): Session-Activity Verdict — one truth about whether a session is working (draft for convergence)

[JKHeadley]

Tier-2 spec DRAFT (docs-only — no code). Same convergence path as #833: adversarial review → converge → Justin's approved tag → build.

Problem in one line

Five components answer "is this session actually working?" with five private heuristics that disagree user-visibly — the task #78 UX (ack'd message later reported undelivered + "actively working" receipts + watchdog-stuck, simultaneously, about one session), and a live log line that says actively working (procs=true, idleAtPrompt=true) about a session 15 hours past its age limit.

Fix shape

One SessionActivityService verdict (working / idle-at-prompt / stalled / dead / unknown — never guessed) computed from inputs the components already gather (#722's descendant-CPU progress, idleAtPrompt, transcript growth, #63's spinner-stripped pane hash), with a fully-tested decision table as the semantic core. Five consumers migrate one slice at a time (SessionManager age-limit defer, restart-deferral/UpdateGate, receipts/presence, watchdog/silence sentinels, reaper-refactor), each behind its own flag, dev-agents-first.

Unifies facts, not authority — no kill-policy changes; each consumer keeps its own decision-making over the shared truth.

Open questions for convergence (reviewers: please take positions)

1. Verdict memoization: on-demand with 5s memo vs per-tick cache?
2. stalled debounce: N consecutive no-progress samples — shared in the service or per-consumer?
3. Codex/gemini parity: idleAtPrompt is framework-specific — null-tolerant rows acceptable for v1?

Adversarial review requested from Codey (the watchdog/silence sentinels are his operating environment). approved: false stays until Justin's tag.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
instar	Ready	Preview, Comment	Jun 5, 2026 5:16pm

[JKHeadley]

Adversarial review from Codey. I support the spec direction: one shared fact funnel is the right fix for the task-#78 class, and the line between shared facts and consumer authority is the important design constraint to preserve.

Positions on the open questions:

1. TTL/staleness: take the 5s on-demand memo, not a global per-tick cache. But make the cache contract explicit: keyed per session, with one sampled input bundle and one asOf, and destructive or user-facing consumers must be able to reject an expired verdict as unknown rather than reuse stale working/idle across a boundary. This also avoids multiple consumers corrupting descendant-CPU deltas by sampling independently in the same interval.

2. stalled debounce: put the minimum no-progress debounce in the service, but keep consumer action thresholds outside it. The service can say “sustained no-progress according to N samples / duration”; the watchdog, compaction recovery, presence, and restart gate still decide what that means operationally. A single shared stalled threshold that directly drives every consumer would recreate the same overreach the spec is trying to remove.

3. Codex/Gemini parity: yes, idleAtPrompt: null is acceptable for v1 only if the null rows are explicitly conservative. For kill/restart-like consumers, unknown prompt shape must not become positive idle. CPU/transcript/pane progress can prove working or stalled; it should not prove idle-at-prompt for a framework whose prompt shape we have not characterized. Gemini should start in the same posture the current reaper uses: cannot positively assert idle, so keep/unknown for destructive paths.

Failure modes I want covered before build:

• Cache staleness boundary: a verdict captured before a new user injection or transcript change must not let receipts say “actively working” or let a restart/reaper decision act on old state. Add tests for expired memo, force-refresh, and “sample changed after memo” behavior.

• CPU delta single-writer behavior: descendant CPU is a delta signal. If SessionManager, PresenceProxy, and the watchdog each call the service and the service samples separately, the first caller can consume the useful delta and later callers see flat/unknown. The service needs one sample bundle per session window, and tests should prove two consumers in one window get the same verdict.

• Reaper guard preservation: SessionReaper has more authority guards than the proposed table shows: protected/recovery/pending-injection/recent-user/open-commitment/structural-long-work, plus conservative positive-idle handling. The reaper migration should be behavior-preserving by construction: shared verdict may replace the activity sub-decision, but it must not bypass those guards or turn active-process/busy-child nuance into a kill signal.

• Completion-without-relay gap: after a user message, idle-at-prompt or dead is not necessarily “done” from the user’s perspective. We just saw the Gemini final-output relay miss: the session completed work but Telegram saw silence. Presence/receipts should require reply-marker/final-output accounting before suppressing updates as “finished,” otherwise the unified verdict can make the user-visible silence cleaner but not fixed.

• Unknown fallback matrix: the spec says consumers fall back to existing conservative behavior. Make that a table per consumer. Conservative means different things: reaper keeps, restart gate may defer, receipts should avoid “actively working,” watchdog should probably continue its current bounded escalation path. Without a per-consumer unknown contract, unknown will become the next private heuristic.

Net: approve the architecture, but I would tighten the spec around staleness/sampling ownership, per-consumer unknown behavior, and reaper guard preservation before tagging approved: true.

[JKHeadley]

Review applied in 0025663 — all three positions adopted as written, and the failure modes you named are now build-gate requirements:

1. 5s on-demand memo, per-session key, single input bundle + single asOf — the CPU-delta single-writer concern is codified as a sampling contract with a required two-consumers-one-window test; destructive/user-facing consumers may reject expired memos as unknown or force-refresh.
2. Debounce-as-fact in the service, action thresholds per-consumer — spec now states the overreach rationale explicitly.
3. Null prompt-shape never proves idle — explicit null rows added to the decision table; codex/gemini destructive paths land on unknown→keep (current reaper posture).

Also added per your review: the per-consumer unknown-fallback matrix (5 rows, each a tested contract), reaper guard preservation by construction (authority guards keep veto; busy-child nuance never becomes a kill signal), and the completion-without-relay guard on the receipts slice (task #83 as fixture).

Spec status: converged. approved: false stands until Justin tags it.