fix(codex): deterministic attention bell — thread-scoped, status-guarded turn completion

crates/freshell-activity/src/idle.rs

@@ -3,7 +3,10 @@
 //! Pinned wire contract: `{ terminalId, at (server epoch ms), reason:
 //! 'grace' | 'queue-empty' }`, emitted ONCE per busy→truly-idle transition.
 //!
-//! Semantics:
+//! Semantics (terminal.idle is never emitted after a HUMAN-REQUESTED stop;
+//! it IS emitted for failed turns, non-human abort reasons (forward-compatible
+//! — none emitted at codex <= 0.147), spontaneous death while engaged, and
+//! approval pauses; see shared/ws-protocol.ts terminal.idle doc):
 //! * a turn boundary (the provider's positive turn end) ARMS a grace window
 //!   (default [`IDLE_GRACE_MS`] = 2000ms);
 //! * new activity within the window EXTENDS it (amplifier: any events.jsonl
@@ -18,10 +21,37 @@
 //! * a turn boundary while the tracker still reports busy/pending is a
 //!   QUEUED turn: it records queue evidence and never arms mid-turn;
 //! * subagent/tool completions inside a running turn never reach this gate
-//!   (the trackers only report REAL turn boundaries).
+//!   (the trackers only report REAL turn boundaries);
+//! * spontaneous death (exit removal while `is_engaged`): the gate itself
+//!   never emits for a removed terminal. The hub reads `is_engaged` BEFORE
+//!   removal and emits the exit-death bell directly. `is_engaged` deliberately
+//!   excludes the input-only Pending state because a human `/quit`/`/exit`
+//!   Enter from an idle pane is indistinguishable from a prompt submit
+//!   (ringing there would bell the canonical human quit).
 //!
 //! Zero-polling: pure deadlines + `next_deadline()`; the hub arms a single
 //! one-shot timer. No pending windows ⇒ no timers.
+//!
+//! # Accepted Residuals
+//!
+//! The following edge cases are accepted design trade-offs (not deferrals):
+//! 1. Mid-turn `/quit`/Ctrl+D: codex sends NO `Op::Interrupt` on Ctrl+D, and
+//!    the TUI's ~2s shutdown budget can exit before the abort evidence lands
+//!    — may ring on a human force-quit of a visibly-working pane. No in-band
+//!    discriminator exists; accepted.
+//! 2. Out-of-band `kill -9`/SIGTERM of the CLI by the user: observationally
+//!    identical to a crash — rings; accepted.
+//! 3. Claude/amplifier Enter-executed quits (`/exit`): input-driven Busy is
+//!    those trackers' ONLY turn evidence, so it stays death-bell engagement;
+//!    same residual family as (1); accepted.
+//! 4. Node 120s busy-deadman swallow (audit A17): a recovery window longer
+//!    than `BUSY_DEADMAN_MS` demotes busy→unknown and `unknown` never arms the
+//!    death bell — a MISSED bell (never a false ring); accepted.
+//! 5. A SENT approval request auto-resolved server-side slower than ~2s rings
+//!    once (decision 5); accepted.
+//! 6. Node opencode death bells: deliberately excluded (noisy busy proxy) —
+//!    follow-up. Rust opencode: no hub tracker exists — N/A.
+//! 7. Unmanaged/PTY-only codex has no approval signal — documented limitation.
 
 use std::collections::HashMap;
 
@@ -143,6 +173,20 @@ impl IdleGate {
         self.states.remove(terminal_id);
     }
 
+    /// Engagement for the DEATH BELL (decision 3): true only for a CONFIRMED
+    /// busy phase or an armed grace window. The codex input-only Pending
+    /// submit gate is excluded — the Enter that executes a human /quit//exit
+    /// is indistinguishable from a prompt submit in the input lane
+    /// (signal.rs:36-38), so ringing on pending would bell the canonical
+    /// human quit. Read by the hub's exit arm BEFORE `note_exit` drops the
+    /// state: a spontaneous process death while engaged rings the bell.
+    pub fn is_engaged(&self, terminal_id: &str) -> bool {
+        self.states
+            .get(terminal_id)
+            .map(|s| (s.busy && !s.pending) || s.deadline.is_some())
+            .unwrap_or(false)
+    }
+
     /// Emit every window whose deadline has lapsed (once each). A terminal
     /// that re-entered busy never emits (defensive second gate).
     pub fn expire(&mut self, at: i64) -> Vec<IdleEmission> {
@@ -400,6 +444,33 @@ mod tests {
         );
     }
 
+    #[test]
+    fn is_engaged_reflects_confirmed_busy_and_armed_deadlines_but_never_input_pending() {
+        let mut gate = IdleGate::with_grace_ms(2_000);
+        assert!(!gate.is_engaged("t1"), "unknown terminal is not engaged");
+        gate.note_phase("t1", IdleGatePhase::Pending);
+        assert!(
+            !gate.is_engaged("t1"),
+            "input-only pending is NOT death-bell engagement: the Enter that \
+             executes /quit looks like a prompt submit (signal.rs:36-38) and \
+             must not ring when the pty then exits (decision 3, audit A6)"
+        );
+        gate.note_phase("t1", IdleGatePhase::Busy);
+        assert!(gate.is_engaged("t1"), "confirmed busy is engaged");
+        gate.note_phase("t1", IdleGatePhase::Idle);
+        assert!(
+            !gate.is_engaged("t1"),
+            "idle with no pending window is not engaged"
+        );
+        gate.note_turn_boundary("t1", 10_000); // arms deadline
+        assert!(
+            gate.is_engaged("t1"),
+            "an armed grace window is engaged (a pending bell must survive death)"
+        );
+        gate.expire(20_000);
+        assert!(!gate.is_engaged("t1"), "after emission nothing is engaged");
+    }
+
     #[test]
     fn default_gate_uses_the_production_grace_window() {
         // HubInner is #[derive(Default)] (freshell-ws activity.rs), so

crates/freshell-activity/src/lib.rs

@@ -49,4 +49,8 @@ pub enum TrackerEffect<R> {
     },
     /// Amplifier only: force-read the events tail (missed-signal failsafe).
     ForceRead { terminal_id: String, at: i64 },
+    /// Arms the truly-idle gate WITHOUT minting a turn completion or a
+    /// terminal.turn.complete frame. Used for attention causes that are not
+    /// turn ends (approval-request pauses).
+    AttentionBoundary { terminal_id: String, at: i64 },
 }