fix(cua-driver): let start_session revive an idle-reaped session (recover from "session ended")

[LaZzyMan]

Problem

A caller-declared session reclaimed by the idle-TTL sweep is permanently dead, and start_session cannot bring it back — so a run that goes quiet for >5 min (the agent reasoning / writing code without calling an MCP tool) loses the driver entirely.

Seen in agent trajectories: a run does start_session{session:"X"}, works fine for ~80 tool calls (all carrying session:"X"), then idles past the TTL. After that every MCP tool — including start_session{session:"X"} itself — returns session ended; tool call ignored, with no way to recover.

Root cause

Three things compound (cua-driver-core/src/session.rs, cua-driver/src/serve.rs):

1. evict_idle marks an idle session ended by inserting it into ENDED_SESSIONS, which is never cleared.
2. touch_session no-ops on an ended id, so it can't re-arm one.
3. The daemon's resurrection guard (serve.rs "call" arm) rejects any call whose session is_session_ended — including start_session, which is itself a normal tool call routed through that same arm. So the one tool meant to (re)start a session is blocked before its invoke ever runs.

Net: once X is reaped, is_session_ended("X") is true forever and nothing flips it back.

Fix

• session::revive_session — clears the ended tombstone + re-arms the idle-TTL clock. A superset of touch_session: equivalent for a live/new id; resumes an ended one.
• start_session tool — calls revive_session instead of touch_session, so it can resume a reaped run.
• serve.rs — exempts start_session from the resurrection guard in both dispatch arms so it actually runs (it is the recovery path); every other tool stays guarded so a stale in-flight call can't rebuild reaped state.
• The guard message now tells the agent how to recover.

revive semantics: a later end_session re-fires the cleanup hooks (they key on ENDED_SESSIONS), which is correct — a fresh lifecycle for the id.

This is the core correctness fix and is independent of the TTL value: a short TTL just triggers reaping more often — with revival that's recoverable instead of fatal. Whether to also raise the 300 s default (CUA_DRIVER_RS_SESSION_IDLE_TTL_SECS) is a separate tuning call, intentionally left out.

Tests

New revive_resumes_an_ended_session proves an ended id is usable again after revive; the sweep-using session tests are serialized so a cross-test zero-TTL reap can't flake them.

Verification status

• ✅ cargo test -p cua-driver-core green (101 passed, incl. the new revive test).
• ✅ cargo check -p cua-driver green.
• ⚠️ No end-to-end daemon test: the cua-driver binary doesn't link on my machine (unrelated platform-macos Swift/Metal interop vs the local SDK), and I can't re-run the eval that surfaced this. The core logic is unit-tested and the serve.rs guard exemption is a one-line condition. A daemon-level smoke (reap a session → start_session → confirm subsequent calls work) would be a good addition on infra that can build the binary.

Summary by CodeRabbit

• New Features

  • You can now resume a previously ended or idle-reclaimed session by calling start_session again with the same session ID.
  • Session recovery now works even after a session has been marked ended, instead of being permanently unavailable.

• Bug Fixes

  • Improved handling of ended sessions so non-resume tool calls return clearer guidance on how to continue.
  • Fixed session lifecycle behavior so revived sessions can be used normally again and ended afterward.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[vercel]

@LaZzyMan is attempting to deploy a commit to the Cua Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds revive_session, updates start_session to call it, and changes daemon call dispatch so ended sessions can resume via start_session on Unix and Windows. Session tests now serialize TTL sweeps and cover revive/end lifecycle behavior.

Changes

Session revival flow

Layer / File(s)	Summary
Session revival state libs/cua-driver/rust/crates/cua-driver-core/src/session.rs	Adds revive_session, serializes TTL-sweep tests, and extends session lifecycle coverage for ending, reviving, sweeping, and ending again.
start_session revival libs/cua-driver/rust/crates/cua-driver-core/src/session_tools.rs	Updates the start_session description and switches invocation from touch_session to revive_session.
Ended-session dispatch libs/cua-driver/rust/crates/cua-driver/src/serve.rs	Allows start_session through the ended-session guard on Unix and Windows and changes the blocked-call response text for other tools.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant call_dispatch as "serve.rs call dispatch"
  participant start_tool as "StartSessionTool::invoke"
  participant revive_session as "session::revive_session"
  participant ENDED_SESSIONS
  participant SESSION_ACTIVITY

  Client->>call_dispatch: call(tool_name, effective_session=session_id)
  alt tool_name == "start_session"
    call_dispatch->>start_tool: invoke(session_id)
    start_tool->>revive_session: revive_session(session_id)
    revive_session->>ENDED_SESSIONS: remove tombstone
    revive_session->>SESSION_ACTIVITY: store fresh timestamp
    start_tool-->>call_dispatch: session resumes
    call_dispatch-->>Client: ok
  else tool_name != "start_session" and session ended
    call_dispatch-->>Client: ok + call start_session with same session
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nibbled the tombstone, hop and cheer,
revived the session, crystal clear.
The idle clock gave one more beat,
and start_session hopped to its seat.
With a tiny thump, the run’s alive!
✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: allowing start_session to revive an idle-reaped session.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@libs/cua-driver/rust/crates/cua-driver-core/src/session.rs`:
- Around line 138-152: revive_session currently clears the session-layer
tombstone but leaves the overlay-layer tombstone in place, so revived sessions
still get blocked by the cursor renderer. Update revive_session in session.rs to
also clear the overlay state for the same session_id, ideally by introducing or
invoking a dedicated revive hook that removes the key from RenderState::ended in
platform-macos/src/overlay.rs. Make sure the fix aligns with the existing
end-session cleanup path so revived sessions can start rendering cursors again
without changing the trackable-session guard behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a03f76d9-2fd4-452c-a837-f2286fe6501b

📥 Commits

Reviewing files that changed from the base of the PR and between e08574c and ad8cbb4.

📒 Files selected for processing (3)

• libs/cua-driver/rust/crates/cua-driver-core/src/session.rs
• libs/cua-driver/rust/crates/cua-driver-core/src/session_tools.rs
• libs/cua-driver/rust/crates/cua-driver/src/serve.rs

[coderabbitai]

🩺 Stability & Availability | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# 1. Find revive_session and any hooks it fires.
rg -nP -C3 '\bfn revive_session\b' libs/cua-driver/rust/crates

# 2. Show how the overlay `ended` tombstone is mutated — is it ever removed from?
fd -t f overlay.rs libs/cua-driver/rust/crates/platform-macos \
  --exec rg -nP -C3 '\bended\b'

# 3. Look for any revive/resume hook registration that could clear overlay state.
rg -nP -C2 'revive|resume_session|register_session_(begin|revive)_hook' \
  libs/cua-driver/rust/crates

Repository: trycua/cua

Length of output: 10236

---

revive_session clears the session tombstone but not the overlay-layer cursor tombstone — revived sessions will fail to render cursors.

The cursor overlay (platform-macos/src/overlay.rs) maintains a separate ended: HashSet<CursorKey> that permanently blocks command processing for tombstoned keys. As seen in lines 143–145 and 255–257 of overlay.rs, any Cmd or seed_start for a key in this set is silently dropped to prevent "ghost-cursor resurrection."

revive_session in session.rs (lines 138–152) correctly clears the session-layer tombstone (ended_sessions) but fails to clear the overlay-layer tombstone. Consequently:

1. The daemon accepts tool calls for the revived session.
2. The overlay guard continues to drop all cursor commands for that session_id.
3. The cursor never reappears, violating the "RESUMES the session" contract in session_tools.rs (line 79).

Add a call to clear the overlay tombstone (e.g., via a fire_session_revive hook that removes the session_id from RenderState::ended) to ensure the render layer respects the session lifecycle reset.

Relevant code sections

session.rs:

pub fn revive_session(session_id: &str) {
    if !is_trackable(session_id) {
        return;
    }
    // ...
    ended_sessions().lock().unwrap().remove(session_id); // Clears session tombstone
    // MISSING: Clear overlay tombstone here
    activity()
        .lock()
        .unwrap()
        .insert(session_id.to_owned(), Instant::now());
}

overlay.rs (guard logic):

// Line 143-145
if map.ended.contains(&key) {
    return None; // Drops command silently
}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@libs/cua-driver/rust/crates/cua-driver-core/src/session.rs` around lines 138
- 152, revive_session currently clears the session-layer tombstone but leaves
the overlay-layer tombstone in place, so revived sessions still get blocked by
the cursor renderer. Update revive_session in session.rs to also clear the
overlay state for the same session_id, ideally by introducing or invoking a
dedicated revive hook that removes the key from RenderState::ended in
platform-macos/src/overlay.rs. Make sure the fix aligns with the existing
end-session cleanup path so revived sessions can start rendering cursors again
without changing the trackable-session guard behavior.