From 29322f45257c1b8d6185de882b24bc90efb252ab Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sat, 29 Aug 2026 11:51:43 +0000
Subject: [PATCH 1/3] Add GUI and TUI session handoff via resume id

Co-authored-by: Gao Yu <gaoyu06@users.noreply.github.com>
---
 src-tauri/src/backend.rs      |  76 +++++++++++++++++---
 src/lib/ChatPane.svelte       |  11 +++
 src/lib/Composer.svelte       |  28 +++++++-
 src/lib/TuiPanel.svelte       |  57 +++++++++++++--
 src/lib/i18n/messages/chat.ts |   6 ++
 src/lib/i18n/messages/dock.ts |   8 ++-
 src/lib/session.svelte.ts     |  64 ++++++++++++++++-
 src/lib/session.test.ts       | 126 +++++++++++++++++++++++++++++++++-
 src/lib/tuiHandoff.test.ts    |  60 ++++++++++++++++
 src/lib/tuiHandoff.ts         |  35 ++++++++++
 src/lib/types.ts              |   5 ++
 src/routes/+page.svelte       |  32 ++++++---
 12 files changed, 478 insertions(+), 30 deletions(-)
 create mode 100644 src/lib/tuiHandoff.test.ts
 create mode 100644 src/lib/tuiHandoff.ts

diff --git a/src-tauri/src/backend.rs b/src-tauri/src/backend.rs
index 6b10fd3..8664859 100644
--- a/src-tauri/src/backend.rs
+++ b/src-tauri/src/backend.rs
@@ -384,23 +384,39 @@ pub fn tui_allowed_args(kind: BackendKind) -> &'static [&'static str] {
     }
 }
 
-/// Validates the extra argv for a TUI spawn against the backend's fixed
-/// token allowlist. Anything else — flags, values, whitespace tricks — is
+/// The one TUI token that may be followed by a session id (GUI → TUI session
+/// handoff resumes by id). jucode has no resume argv — its TUI resumes via
+/// the `/resume` slash command after spawn.
+fn tui_resume_flag(kind: BackendKind) -> Option<&'static str> {
+    match kind {
+        BackendKind::Claude => Some("--resume"),
+        BackendKind::Codex => Some("resume"),
+        BackendKind::Jucode | BackendKind::Acp => None,
+    }
+}
+
+/// Validates the extra argv for a TUI spawn. Accepted shapes only:
+/// nothing, exactly one allowlisted token, or the backend's resume flag
+/// followed by one id that passes `is_valid_session_id`. Anything else —
+/// free-form flags, `--resume=<id>`, flag-like "ids", extra tokens — is
 /// rejected outright. ACP backends are rejected entirely: their command
 /// comes from the registry, not a resolvable well-known binary.
 pub fn validate_tui_args(kind: BackendKind, args: &[String]) -> Result<(), String> {
     if kind == BackendKind::Acp {
         return Err("ACP agents cannot be opened as a TUI tab".to_string());
     }
-    for arg in args {
-        if !tui_allowed_args(kind).contains(&arg.as_str()) {
-            return Err(format!(
-                "argument not allowed for {} TUI: {arg}",
-                kind.bin_name()
-            ));
+    match args {
+        [] => Ok(()),
+        [tok] if tui_allowed_args(kind).contains(&tok.as_str()) => Ok(()),
+        [flag, id] if tui_resume_flag(kind) == Some(flag.as_str()) && is_valid_session_id(id) => {
+            Ok(())
         }
+        _ => Err(format!(
+            "arguments not allowed for {} TUI: {}",
+            kind.bin_name(),
+            args.join(" ")
+        )),
     }
-    Ok(())
 }
 
 /// Validates a settings-provided binary path for a TUI spawn (same rule as
@@ -985,6 +1001,48 @@ mod tests {
         assert!(validate_tui_args(BackendKind::Claude, &["resume".into()]).is_err());
     }
 
+    #[test]
+    fn tui_resume_accepts_a_validated_session_id() {
+        let sid = "0f3d7a1c-9e2b-4b7e-9d4d-2a1b3c4d5e6f";
+        assert!(validate_tui_args(BackendKind::Claude, &["--resume".into(), sid.into()]).is_ok());
+        assert!(validate_tui_args(BackendKind::Codex, &["resume".into(), sid.into()]).is_ok());
+        // The resume-with-id shape doesn't leak across backends, and jucode
+        // has no resume argv at all (it resumes via /resume after spawn).
+        assert!(validate_tui_args(BackendKind::Claude, &["resume".into(), sid.into()]).is_err());
+        assert!(validate_tui_args(BackendKind::Codex, &["--resume".into(), sid.into()]).is_err());
+        assert!(validate_tui_args(BackendKind::Jucode, &["resume".into(), sid.into()]).is_err());
+        assert!(validate_tui_args(BackendKind::Jucode, &["--resume".into(), sid.into()]).is_err());
+        // Only the resume flag takes a value.
+        assert!(validate_tui_args(BackendKind::Claude, &["--continue".into(), sid.into()]).is_err());
+    }
+
+    #[test]
+    fn tui_resume_rejects_invalid_ids_and_extra_tokens() {
+        let sid = "0f3d7a1c-9e2b-4b7e-9d4d-2a1b3c4d5e6f";
+        for bad_id in ["--help", "-x", "a b", "../etc/passwd", "", "a".repeat(65).as_str()] {
+            assert!(
+                validate_tui_args(BackendKind::Claude, &["--resume".into(), bad_id.into()])
+                    .is_err(),
+                "{bad_id:?} must be rejected as a resume id"
+            );
+            assert!(
+                validate_tui_args(BackendKind::Codex, &["resume".into(), bad_id.into()]).is_err(),
+                "{bad_id:?} must be rejected as a resume id"
+            );
+        }
+        // No third token, ever.
+        assert!(validate_tui_args(
+            BackendKind::Claude,
+            &["--resume".into(), sid.into(), "-x".into()]
+        )
+        .is_err());
+        assert!(validate_tui_args(
+            BackendKind::Claude,
+            &["--continue".into(), "--resume".into(), sid.into()]
+        )
+        .is_err());
+    }
+
     #[test]
     fn tui_rejects_arbitrary_and_dangerous_argv() {
         for bad in [
diff --git a/src/lib/ChatPane.svelte b/src/lib/ChatPane.svelte
index 3c9a003..60355db 100644
--- a/src/lib/ChatPane.svelte
+++ b/src/lib/ChatPane.svelte
@@ -38,6 +38,7 @@
 		type Op
 	} from '$lib/protocol';
 	import { buildModelRows } from '$lib/composer/modelRows';
+	import { canHandOffToTui, isValidResumeSessionId } from '$lib/tuiHandoff';
 	import { dispatch } from '$lib/backends/router';
 	import { browser } from '$lib/browser.svelte';
 	import { prefs } from '$lib/prefs.svelte';
@@ -176,6 +177,14 @@
 	// yet (an optimistic push counts) and not a resumed conversation.
 	const backendLocked = $derived(!!session.restored || chat.userTurns > 0);
 
+	// GUI → TUI handoff: offered for the native CLIs only (never ACP), enabled
+	// once the engine holds a resumable conversation under a valid session id
+	// (same gate as SessionStore.openInTui).
+	const tuiCapable = $derived(canHandOffToTui(session.backendId));
+	const tuiReady = $derived(
+		isValidResumeSessionId(chat.sessionId) && (chat.resumable || !!session.restored)
+	);
+
 	// Current git branch for the composer's footer strip. A detached HEAD reads
 	// "detached"; a failed probe (not a git repo) hides the chip.
 	let gitBranch = $state('');
@@ -776,6 +785,8 @@
 			modelSearch={showPickerSearch}
 			{backendLocked}
 			{gitBranch}
+			{tuiReady}
+			onOpenTui={tuiCapable ? () => store.openInTui(session.id) : undefined}
 			onBackend={(b, acpAgent) => store.switchBackend(session.id, b, acpAgent)}
 			bind:pickerQuery
 			bind:pickerSelIdx={selIdx}
diff --git a/src/lib/Composer.svelte b/src/lib/Composer.svelte
index cc3c339..6d87b49 100644
--- a/src/lib/Composer.svelte
+++ b/src/lib/Composer.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { Send, Square, Paperclip, FastForward, ShieldCheck, CircleStop, Mic, LoaderCircle, GitBranch } from 'lucide-svelte';
+	import { Send, Square, Paperclip, FastForward, ShieldCheck, CircleStop, Mic, LoaderCircle, GitBranch, SquareTerminal } from 'lucide-svelte';
 	import { message } from '@tauri-apps/plugin-dialog';
 	import IconButton from '$lib/ui/IconButton.svelte';
 	import BackendIcon from '$lib/BackendIcon.svelte';
@@ -32,6 +32,8 @@
 		modelSearch = false,
 		backendLocked = true,
 		gitBranch = '',
+		tuiReady = false,
+		onOpenTui,
 		onBackend,
 		onSubmit,
 		onStop,
@@ -59,6 +61,12 @@
 		backendLocked?: boolean;
 		/** Current git branch for the footer strip ('' hides the chip). */
 		gitBranch?: string;
+		/** The session holds a resumable engine conversation the native TUI
+		 *  can continue (gates the "continue in TUI" chip). */
+		tuiReady?: boolean;
+		/** Hand the conversation to the native TUI. Absent (e.g. ACP) hides
+		 *  the chip entirely. */
+		onOpenTui?: () => void;
 		onBackend?: (b: BackendId, acpAgent?: { id: string; name: string }) => void | Promise<void>;
 		onSubmit: () => void;
 		onStop: () => void;
@@ -588,6 +596,16 @@
 				{/if}
 			</div>
 		{/if}
+		{#if onOpenTui}
+			<button
+				class="foot-chip"
+				disabled={!tuiReady}
+				onclick={onOpenTui}
+				title={tuiReady ? t('chat.tuiContinueTitle') : t('chat.tuiNotReady')}
+			>
+				<SquareTerminal size={12} /><span>{t('chat.tuiContinue')}</span>
+			</button>
+		{/if}
 		<div class="fspace"></div>
 		{#if bcaps.contextUsage && ctxLimit > 0}
 			<div class="foot-ctx">
@@ -846,6 +864,14 @@
 		background: var(--surface2);
 		color: var(--text);
 	}
+	.foot-chip:disabled {
+		opacity: 0.45;
+		cursor: default;
+	}
+	.foot-chip:disabled:hover {
+		background: none;
+		color: var(--dim);
+	}
 	.foot-chip.auto {
 		color: var(--warn);
 		border-color: color-mix(in oklab, var(--warn) 35%, transparent);
diff --git a/src/lib/TuiPanel.svelte b/src/lib/TuiPanel.svelte
index 44f5e8c..0c2cffa 100644
--- a/src/lib/TuiPanel.svelte
+++ b/src/lib/TuiPanel.svelte
@@ -1,8 +1,11 @@
 <script lang="ts">
-	// A native TUI tab: the real interactive CLI (jucode / codex / claude)
-	// running in a pty, rendered by xterm. Independent of any GUI session —
-	// closing the tab kills the process. The backend name is the only thing
-	// sent to Rust; argv and binary resolution are validated there.
+	// A native TUI panel: the real interactive CLI (jucode / codex / claude)
+	// running in a pty, rendered by xterm. Two uses: a standalone `tui:*` tab
+	// (no args, independent of any GUI session) and a session handoff, where
+	// the chat tile hands its conversation over via resume argv / a `/resume`
+	// line (`onBackToGui` present). Closing the panel kills the process. Only
+	// the backend name + allowlisted args reach Rust; argv and binary
+	// resolution are validated there.
 	import { onMount, onDestroy } from 'svelte';
 	import { listen } from '@tauri-apps/api/event';
 	import { Terminal } from '@xterm/xterm';
@@ -17,10 +20,22 @@
 	let {
 		backend,
 		cwd = '',
+		args = [],
+		resumeCommand,
+		onBackToGui,
 		onOpenSettings
 	}: {
 		backend: BackendId;
 		cwd?: string;
+		/** Session-handoff resume argv (must match the Rust TUI allowlist,
+		 *  e.g. `['--resume', '<id>']`). Empty for standalone TUI tabs. */
+		args?: string[];
+		/** Line written into the pty once it is running — the jucode TUI has
+		 *  no resume argv and resumes via `/resume <id>\n` instead. */
+		resumeCommand?: string;
+		/** Present only for session handoffs: hand the conversation back to
+		 *  the GUI chat (shows the "back to GUI" bar). */
+		onBackToGui?: () => void;
 		onOpenSettings?: () => void;
 	} = $props();
 
@@ -52,9 +67,13 @@
 			fit?.fit();
 			await ptyOpen(id, term.cols, term.rows, cwd || undefined, {
 				command: backend,
+				args: args.length ? args : undefined,
 				binOverride: loadBackendSettings().paths[backend]
 			});
 			status = 'running';
+			// Session handoff into the jucode TUI: resume the conversation with
+			// its slash command (the pty buffers the line until the TUI reads).
+			if (resumeCommand) ptyWrite(id, resumeCommand).catch(() => {});
 		} catch (e) {
 			const msg = String(e);
 			status = msg.includes('binary-missing:') ? 'missing' : 'error';
@@ -129,6 +148,12 @@
 </script>
 
 <div class="tui-wrap">
+	{#if onBackToGui}
+		<div class="handoffbar">
+			<span class="hb-text">{t('dock.tui.handoff')}</span>
+			<button class="btn sm" onclick={onBackToGui}>{t('dock.tui.backToGui')}</button>
+		</div>
+	{/if}
 	<div class="term-host" bind:this={host}></div>
 	{#if status === 'missing' || status === 'error'}
 		<div class="notice">
@@ -151,6 +176,9 @@
 		<div class="exitbar">
 			<span>{t('dock.tui.exited')}</span>
 			<button class="btn sm" onclick={restart}>{t('dock.tui.restart')}</button>
+			{#if onBackToGui}
+				<button class="btn sm" onclick={onBackToGui}>{t('dock.tui.backToGui')}</button>
+			{/if}
 		</div>
 	{/if}
 </div>
@@ -158,11 +186,30 @@
 <style>
 	.tui-wrap {
 		position: relative;
+		display: flex;
+		flex-direction: column;
 		height: 100%;
 		width: 100%;
 	}
+	.handoffbar {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 10px;
+		padding: 4px 10px;
+		font-size: 12px;
+		color: var(--dim);
+		background: var(--surface);
+		border-bottom: 1px solid var(--hairline);
+	}
+	.hb-text {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
 	.term-host {
-		height: 100%;
+		flex: 1;
+		min-height: 0;
 		width: 100%;
 		padding: 8px 6px 6px 10px;
 		background: var(--panel);
diff --git a/src/lib/i18n/messages/chat.ts b/src/lib/i18n/messages/chat.ts
index 682e1b7..5b82e60 100644
--- a/src/lib/i18n/messages/chat.ts
+++ b/src/lib/i18n/messages/chat.ts
@@ -33,6 +33,9 @@ const chat = {
 		statusTitle: '状态',
 		approvalModeTitle: '工具审批模式',
 		gitBranch: '当前 git 分支',
+		tuiContinue: '在 TUI 中继续',
+		tuiContinueTitle: '关闭 GUI 引擎，在原生 TUI 中恢复此会话',
+		tuiNotReady: '还没有可恢复的会话 id（先发送一条消息）',
 		context: '上下文',
 		toCompaction: '{pct}% · 到压缩点',
 		contextUsed: '{pct}% · 上下文占用',
@@ -91,6 +94,9 @@ const chat = {
 		statusTitle: 'Status',
 		approvalModeTitle: 'Tool approval mode',
 		gitBranch: 'Current git branch',
+		tuiContinue: 'Continue in TUI',
+		tuiContinueTitle: 'Close the GUI engine and resume this session in the native TUI',
+		tuiNotReady: 'No resumable session id yet (send a message first)',
 		context: 'Context',
 		toCompaction: '{pct}% · to compaction',
 		contextUsed: '{pct}% · context used',
diff --git a/src/lib/i18n/messages/dock.ts b/src/lib/i18n/messages/dock.ts
index aa18fec..0fb38dc 100644
--- a/src/lib/i18n/messages/dock.ts
+++ b/src/lib/i18n/messages/dock.ts
@@ -32,7 +32,9 @@ const dock = {
 			retry: '重试',
 			failed: '启动失败',
 			exited: '进程已退出',
-			restart: '重新启动'
+			restart: '重新启动',
+			handoff: '会话已移交给原生 TUI',
+			backToGui: '回到 GUI'
 		},
 		turns: {
 			empty: '本会话还没有文件改动',
@@ -218,7 +220,9 @@ const dock = {
 			retry: 'Try again',
 			failed: 'Failed to start',
 			exited: 'Process exited',
-			restart: 'Restart'
+			restart: 'Restart',
+			handoff: 'Session handed to the native TUI',
+			backToGui: 'Back to GUI'
 		},
 		turns: {
 			empty: 'No file changes in this session yet',
diff --git a/src/lib/session.svelte.ts b/src/lib/session.svelte.ts
index 2e82a19..d5def10 100644
--- a/src/lib/session.svelte.ts
+++ b/src/lib/session.svelte.ts
@@ -1,5 +1,7 @@
+import { tick } from 'svelte';
 import { ChatState } from './chat.svelte';
 import { createSession, closeSession, projectRoot, writeConfig, git, claudeSessionTranscript } from './protocol';
+import { canHandOffToTui, isValidResumeSessionId } from './tuiHandoff';
 import { createAdapter, normalizeBackendId, type BackendId } from './backends';
 import { dispatch, ioFor, registerAdapter, unregisterAdapter } from './backends/router';
 import { buildBackendOpts, defaultBackendFor } from './backends/settings';
@@ -33,6 +35,9 @@ export interface SavedProject {
 		/** backend 为 'acp' 时：驱动该会话的 registry agent（重启动/恢复时必需）。 */
 		acpAgent?: { id: string; name: string };
 		archived?: boolean;
+		/** The conversation was handed to the native TUI (resume by `sid`).
+		 *  Omitted for the default GUI surface so old layouts stay clean. */
+		surface?: 'tui';
 	} & SavedTabChrome)[];
 	/** 并行任务 worktree 项目的元数据（isWorktree/mainRepoPath/branch/baseBranch/slug）。 */
 	worktree?: WorktreeMeta;
@@ -296,7 +301,8 @@ export class SessionStore {
 		archived = false,
 		chrome?: SavedTabChrome,
 		reuseId?: string,
-		acpAgent?: { id: string; name: string }
+		acpAgent?: { id: string; name: string },
+		surface?: 'tui'
 	) {
 		const s = this.#newSession(backend, backend === 'acp' ? acpAgent : undefined, reuseId);
 		if (title) s.chat.title = title;
@@ -309,6 +315,15 @@ export class SessionStore {
 		s.restored = true;
 		project.sessions.push(s);
 		if (backend === 'claude' || backend === 'codex') s.chat.sessionId = sid;
+		// The conversation was handed to the native TUI when it was persisted:
+		// render the TuiPanel (which resumes by id) and never spawn the GUI
+		// engine beside it — one process per conversation. `returnToGui`
+		// respawns the engine with resume later.
+		if (surface === 'tui' && canHandOffToTui(backend)) {
+			s.surface = 'tui';
+			s.chat.sessionId = sid;
+			return s.id;
+		}
 		const spawned =
 			backend === 'claude'
 				? this.#spawn(s, project.path, () => this.#replayClaudeTranscript(s, project.path, sid), {
@@ -389,7 +404,10 @@ export class SessionStore {
 		s.chat.restartWindowStart = now;
 		s.chat.restarts++;
 		const sid = s.chat.sessionId;
-		const canResume = s.chat.resumable;
+		// A restored session's conversation exists engine-side even while its
+		// replayed transcript is still empty (replay is async / best-effort) —
+		// the same rule serialize uses to decide a tab is resumable.
+		const canResume = s.chat.resumable || (!!sid && !!s.restored);
 		s.chat.engineState = 'connecting';
 		s.chat.messages.push({ kind: 'system', text: force ? t('shell.restarting') : t('shell.autoRestarting') });
 		// claude resumes via the --resume spawn option (no /resume command in
@@ -571,6 +589,43 @@ export class SessionStore {
 		dispatch(id, { op: 'command', input: '/resume' });
 	}
 
+	/** Hand a conversation to the native TUI (same chat tile, `surface` flips
+	 *  to 'tui'): the tile re-renders as a TuiPanel resuming the same engine
+	 *  session by id (claude `--resume <id>`, codex `resume <id>`, jucode
+	 *  `/resume <id>` written into the pty). The GUI engine is closed FIRST so
+	 *  two processes never hold the same conversation. Requires a usable
+	 *  engine session id — resume-by-id is the product, never a TUI picker —
+	 *  so a fresh empty chat and ACP sessions are a no-op. */
+	async openInTui(id: string) {
+		const s = this.allSessions.find((x) => x.id === id);
+		if (!s || s.surface === 'tui' || !canHandOffToTui(s.backendId)) return;
+		// Same rule serialize uses for `sid`: the engine persisted the
+		// conversation only once a user turn exists (or it was restored).
+		if (!isValidResumeSessionId(s.chat.sessionId) || !(s.chat.resumable || s.restored)) return;
+		// Intentional close — handleExit must not auto-restart the GUI engine
+		// underneath the TUI.
+		s.chat.switching = true;
+		try {
+			await closeSession(id);
+		} catch {
+			/* engine already gone */
+		}
+		s.surface = 'tui';
+	}
+
+	/** Bring a handed-off conversation back to the GUI: flip the surface first
+	 *  (unmounting the TuiPanel closes its pty in onDestroy), wait one tick
+	 *  for that unmount, then respawn the GUI engine resuming the same
+	 *  conversation (claude `--resume`, jucode `/resume`, codex thread ctx —
+	 *  all inside restartSession). */
+	async returnToGui(id: string) {
+		const s = this.allSessions.find((x) => x.id === id);
+		if (!s || s.surface !== 'tui') return;
+		s.surface = 'gui';
+		await tick(); // let the TuiPanel unmount issue its ptyClose first
+		this.restartSession(id, true);
+	}
+
 	/** Snapshot of the layout + open tabs for persistence. Every session is
 	 *  written (empty windows survive a workspace switch under their desktop
 	 *  id); `sid` only when the engine actually persisted the conversation —
@@ -595,6 +650,7 @@ export class SessionStore {
 					...(s.backendId !== 'jucode' ? { backend: s.backendId } : {}),
 					...(s.backendId === 'acp' && s.acpAgent ? { acpAgent: s.acpAgent } : {}),
 					...(s.archived ? { archived: true } : {}),
+					...(s.surface === 'tui' ? { surface: 'tui' as const } : {}),
 					...(s.color ? { color: s.color } : {}),
 					...(s.icon ? { icon: s.icon } : {}),
 					...(s.chat.titleLocked ? { titleLocked: true } : {})
@@ -656,8 +712,10 @@ export class SessionStore {
 					};
 					// With a conversation to resume, resume it; an empty window spawns
 					// fresh. Both keep the saved desktop id (pre-id files mint anew).
+					// A tab handed to the TUI restores as a TUI surface (no engine).
+					const surface = t.surface === 'tui' ? ('tui' as const) : undefined;
 					const id = t.sid
-						? this.restoreSession(proj, t.sid, t.title, backend, !!t.archived, chrome, t.id, acpAgent)
+						? this.restoreSession(proj, t.sid, t.title, backend, !!t.archived, chrome, t.id, acpAgent, surface)
 						: this.#spawnSaved(proj, t.id!, t.title, backend, !!t.archived, chrome, acpAgent);
 					if (!first && !t.archived) first = id;
 				}
diff --git a/src/lib/session.test.ts b/src/lib/session.test.ts
index ed615a4..befb6c8 100644
--- a/src/lib/session.test.ts
+++ b/src/lib/session.test.ts
@@ -12,7 +12,7 @@ vi.mock('./protocol', () => ({
 }));
 
 import { SessionStore } from './session.svelte';
-import { createSession, sendOp, git, writeConfig } from './protocol';
+import { createSession, closeSession, sendOp, git, writeConfig } from './protocol';
 import { setLocale } from './i18n';
 import type { Project, WorktreeMeta } from './types';
 
@@ -374,6 +374,130 @@ describe('SessionStore lifecycle', () => {
 	});
 });
 
+describe('SessionStore GUI ⇄ TUI handoff', () => {
+	const SID = '0f3d7a1c-9e2b-4b7e-9d4d-2a1b3c4d5e6f';
+
+	/** A session whose engine conversation is resumable (sid + one user turn). */
+	function readySession(store: SessionStore, p: Project, backend: 'jucode' | 'claude' | 'codex') {
+		const id = store.addSession(p, undefined, backend);
+		const s = p.sessions.find((x) => x.id === id)!;
+		s.chat.sessionId = SID;
+		s.chat.messages.push({ kind: 'user', text: 'hi' });
+		return s;
+	}
+
+	it('openInTui closes the GUI engine before flipping the surface', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		let surfaceAtClose: string | undefined = 'not-called';
+		vi.mocked(closeSession).mockImplementationOnce(async () => {
+			surfaceAtClose = s.surface;
+		});
+		await store.openInTui(s.id);
+		expect(closeSession).toHaveBeenCalledWith(s.id);
+		expect(surfaceAtClose).toBeUndefined(); // still on the GUI when the engine died
+		expect(s.surface).toBe('tui');
+		// The intentional close must not be treated as a crash to auto-restart.
+		expect(s.chat.switching).toBe(true);
+	});
+
+	it('openInTui refuses acp sessions', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const id = store.addSession(p, undefined, 'acp', { id: 'gemini', name: 'Gemini CLI' });
+		const s = p.sessions.find((x) => x.id === id)!;
+		s.chat.sessionId = SID;
+		s.chat.messages.push({ kind: 'user', text: 'hi' });
+		vi.clearAllMocks();
+		await store.openInTui(id);
+		expect(closeSession).not.toHaveBeenCalled();
+		expect(s.surface).toBeUndefined();
+	});
+
+	it('openInTui without a usable engine session id is a no-op', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		// jucode session with no engine session id at all.
+		const a = store.addSession(p, undefined, 'jucode');
+		// claude session with a pinned id but no user turn (never persisted).
+		const b = store.addSession(p, undefined, 'claude');
+		// resumable, but the id would fail the rust validator.
+		const c = store.addSession(p, undefined, 'jucode');
+		const sc = p.sessions.find((x) => x.id === c)!;
+		sc.chat.sessionId = 'a b';
+		sc.chat.messages.push({ kind: 'user', text: 'hi' });
+		vi.clearAllMocks();
+		for (const id of [a, b, c]) await store.openInTui(id);
+		expect(closeSession).not.toHaveBeenCalled();
+		for (const s of p.sessions) expect(s.surface).toBeUndefined();
+	});
+
+	it('returnToGui respawns the engine resuming the conversation', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		await store.openInTui(s.id);
+		vi.clearAllMocks();
+		await store.returnToGui(s.id);
+		expect(s.surface).toBe('gui');
+		const call = vi.mocked(createSession).mock.calls.at(-1)!;
+		expect(call[2]).toBe('claude');
+		expect((call[3] as { resume?: string }).resume).toBe(SID);
+	});
+
+	it('returnToGui resumes a jucode conversation via /resume', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'jucode');
+		await store.openInTui(s.id);
+		vi.clearAllMocks();
+		await store.returnToGui(s.id);
+		await Promise.resolve(); // let the spawn continuation run
+		expect(createSession).toHaveBeenCalled();
+		expect(sendOp).toHaveBeenCalledWith(s.id, { op: 'command', input: `/resume ${SID}` });
+	});
+
+	it('serialize writes surface only for tui tabs', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const tui = readySession(store, p, 'claude');
+		const gui = readySession(store, p, 'jucode');
+		await store.openInTui(tui.id);
+		const tabs = store.serialize()[0].tabs!;
+		expect(tabs.find((t) => t.id === tui.id)?.surface).toBe('tui');
+		expect('surface' in tabs.find((t) => t.id === gui.id)!).toBe(false);
+	});
+
+	it('a restored tui tab spawns no engine until returnToGui resumes it', async () => {
+		const store = new SessionStore();
+		await store.restore([
+			{
+				id: 'p1',
+				name: 'p1',
+				path: '/tmp/p1',
+				tabs: [{ id: 'live-a', sid: SID, title: 'A', backend: 'claude', surface: 'tui' }]
+			}
+		]);
+		const s = store.projects[0].sessions[0];
+		expect(s.surface).toBe('tui');
+		expect(s.chat.sessionId).toBe(SID);
+		// The TUI owns the conversation — no GUI engine beside it.
+		expect(createSession).not.toHaveBeenCalled();
+		await store.returnToGui('live-a');
+		expect(s.surface).toBe('gui');
+		const call = vi.mocked(createSession).mock.calls.at(-1)!;
+		expect(call[2]).toBe('claude');
+		expect((call[3] as { resume?: string }).resume).toBe(SID);
+	});
+});
+
 describe('SessionStore parallel-task worktrees', () => {
 	const meta: WorktreeMeta = {
 		isWorktree: true,
diff --git a/src/lib/tuiHandoff.test.ts b/src/lib/tuiHandoff.test.ts
new file mode 100644
index 0000000..9f0afcc
--- /dev/null
+++ b/src/lib/tuiHandoff.test.ts
@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import {
+	canHandOffToTui,
+	isValidResumeSessionId,
+	tuiResumeArgs,
+	tuiResumeCommand
+} from './tuiHandoff';
+
+const SID = '0f3d7a1c-9e2b-4b7e-9d4d-2a1b3c4d5e6f';
+
+describe('isValidResumeSessionId', () => {
+	it('accepts uuid-like ids (mirrors rust is_valid_session_id)', () => {
+		expect(isValidResumeSessionId(SID)).toBe(true);
+		expect(isValidResumeSessionId('abc123')).toBe(true);
+		expect(isValidResumeSessionId('a'.repeat(64))).toBe(true);
+	});
+
+	it('rejects flag-like, whitespace, unicode and oversized ids', () => {
+		for (const bad of [
+			'',
+			'-x',
+			'--resume',
+			'a b',
+			'../etc/passwd',
+			'a_b',
+			'ID;rm',
+			'会话id',
+			'a'.repeat(65)
+		]) {
+			expect(isValidResumeSessionId(bad), JSON.stringify(bad)).toBe(false);
+		}
+	});
+});
+
+describe('canHandOffToTui', () => {
+	it('allows the three native CLIs and never acp', () => {
+		expect(canHandOffToTui('jucode')).toBe(true);
+		expect(canHandOffToTui('claude')).toBe(true);
+		expect(canHandOffToTui('codex')).toBe(true);
+		expect(canHandOffToTui('acp')).toBe(false);
+	});
+});
+
+describe('tuiResumeArgs / tuiResumeCommand', () => {
+	it('builds the per-backend resume argv the rust allowlist accepts', () => {
+		expect(tuiResumeArgs('claude', SID)).toEqual(['--resume', SID]);
+		expect(tuiResumeArgs('codex', SID)).toEqual(['resume', SID]);
+		// jucode resumes via the slash command written into the pty, not argv.
+		expect(tuiResumeArgs('jucode', SID)).toEqual([]);
+		expect(tuiResumeCommand('jucode', SID)).toBe(`/resume ${SID}\n`);
+		expect(tuiResumeCommand('claude', SID)).toBeUndefined();
+		expect(tuiResumeCommand('codex', SID)).toBeUndefined();
+	});
+
+	it('emits nothing for an invalid id', () => {
+		expect(tuiResumeArgs('claude', '--help')).toEqual([]);
+		expect(tuiResumeArgs('codex', '')).toEqual([]);
+		expect(tuiResumeCommand('jucode', 'a b')).toBeUndefined();
+	});
+});
diff --git a/src/lib/tuiHandoff.ts b/src/lib/tuiHandoff.ts
new file mode 100644
index 0000000..5b6dcf6
--- /dev/null
+++ b/src/lib/tuiHandoff.ts
@@ -0,0 +1,35 @@
+// Pure helpers for the GUI ⇄ TUI session handoff: which backends can hand a
+// conversation to the native TUI, and the resume argv / slash command a
+// TuiPanel spawn uses to continue that conversation by session id. Mirrors
+// the Rust-side allowlist (`backend::validate_tui_args`) so the UI never
+// offers a spawn Rust would reject.
+
+import type { BackendId } from './backends/types';
+
+/** Mirrors Rust `is_valid_session_id`: nonempty, ≤64 chars, no leading dash,
+ *  ascii alphanumerics + dashes only. */
+export function isValidResumeSessionId(s: string): boolean {
+	return s.length > 0 && s.length <= 64 && !s.startsWith('-') && /^[a-zA-Z0-9-]+$/.test(s);
+}
+
+/** Backends whose session can move to the native TUI. ACP agents have no
+ *  fixed TUI binary and are never offered a handoff. */
+export function canHandOffToTui(backend: BackendId): boolean {
+	return backend === 'jucode' || backend === 'claude' || backend === 'codex';
+}
+
+/** Extra argv for the TUI spawn of a handed-off session (exactly the shapes
+ *  `validate_tui_args` accepts). jucode has no resume argv — see
+ *  `tuiResumeCommand`. */
+export function tuiResumeArgs(backend: BackendId, sid: string): string[] {
+	if (!isValidResumeSessionId(sid)) return [];
+	if (backend === 'claude') return ['--resume', sid];
+	if (backend === 'codex') return ['resume', sid];
+	return [];
+}
+
+/** The `/resume <id>` line written into a fresh jucode TUI pty (the jucode
+ *  TUI resumes via slash command, not argv). Undefined for other backends. */
+export function tuiResumeCommand(backend: BackendId, sid: string): string | undefined {
+	return backend === 'jucode' && isValidResumeSessionId(sid) ? `/resume ${sid}\n` : undefined;
+}
diff --git a/src/lib/types.ts b/src/lib/types.ts
index c91782c..cb25366 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -22,6 +22,11 @@ export interface Session {
 	/** Opened by resuming a persisted conversation — the engine already holds
 	 *  context, so the backend is locked even before any visible user turn. */
 	restored?: boolean;
+	/** Which surface currently owns the conversation: the GUI chat (default,
+	 *  undefined) or the native TUI resumed by session id. Exactly one process
+	 *  holds the conversation at a time — the store closes the GUI engine
+	 *  before flipping to 'tui' and the TUI pty before flipping back. */
+	surface?: 'gui' | 'tui';
 }
 
 /** 并行任务（git worktree）项目的元数据，随项目布局持久化。 */
diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte
index d45c982..7b8170e 100644
--- a/src/routes/+page.svelte
+++ b/src/routes/+page.svelte
@@ -48,6 +48,7 @@
 		reconcileLayout
 	} from '$lib/workbench/canvas';
 	import { tuiBackendOf, tuiTabTitle } from '$lib/workbench/tuiTab';
+	import { tuiResumeArgs, tuiResumeCommand } from '$lib/tuiHandoff';
 	import type { WorkspaceEntry } from '$lib/workbench/workspaces';
 	import type { TabIcon } from '$lib/workbench/tabChrome';
 	import Mosaic from '$lib/workbench/Mosaic.svelte';
@@ -900,15 +901,28 @@
 						{#if sid}
 							{@const sess = sessionMap.get(sid)}
 							{#if sess}
-								<ChatPane
-									session={sess}
-									{store}
-									{providers}
-									{providersList}
-									isActive={sid === activeId}
-									onRegister={registerPane}
-									onUnregister={unregisterPane}
-								/>
+								{#if sess.surface === 'tui'}
+									<!-- Session handoff: the same chat tile renders the native TUI
+									     resuming this conversation by id (never a standalone tui:* tab). -->
+									<TuiPanel
+										backend={sess.backendId}
+										cwd={store.projectPathOf(sid) ?? ''}
+										args={tuiResumeArgs(sess.backendId, sess.chat.sessionId)}
+										resumeCommand={tuiResumeCommand(sess.backendId, sess.chat.sessionId)}
+										onBackToGui={() => store.returnToGui(sid)}
+										onOpenSettings={() => { settingsInitial = 'behavior'; showSettings = true; }}
+									/>
+								{:else}
+									<ChatPane
+										session={sess}
+										{store}
+										{providers}
+										{providersList}
+										isActive={sid === activeId}
+										onRegister={registerPane}
+										onUnregister={unregisterPane}
+									/>
+								{/if}
 							{:else}
 								<div class="gone">{t('shell.chatGone')}</div>
 							{/if}

From 07d2ea01fec31354ca5e737b129d7f54a0788f4a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sat, 29 Aug 2026 11:57:33 +0000
Subject: [PATCH 2/3] Harden GUI/TUI resume handoff ownership

Co-authored-by: Gao Yu <gaoyu06@users.noreply.github.com>
---
 src/lib/Composer.svelte       | 13 +------
 src/lib/TuiPanel.svelte       | 58 +++++++++++++++++++++++++----
 src/lib/i18n/messages/chat.ts |  2 -
 src/lib/session.svelte.ts     | 54 ++++++++++++++++++++-------
 src/lib/session.test.ts       | 70 +++++++++++++++++++++++++++++++++++
 src/lib/types.ts              |  3 +-
 6 files changed, 164 insertions(+), 36 deletions(-)

diff --git a/src/lib/Composer.svelte b/src/lib/Composer.svelte
index 6d87b49..41c8d77 100644
--- a/src/lib/Composer.svelte
+++ b/src/lib/Composer.svelte
@@ -596,12 +596,11 @@
 				{/if}
 			</div>
 		{/if}
-		{#if onOpenTui}
+		{#if onOpenTui && tuiReady}
 			<button
 				class="foot-chip"
-				disabled={!tuiReady}
 				onclick={onOpenTui}
-				title={tuiReady ? t('chat.tuiContinueTitle') : t('chat.tuiNotReady')}
+				title={t('chat.tuiContinueTitle')}
 			>
 				<SquareTerminal size={12} /><span>{t('chat.tuiContinue')}</span>
 			</button>
@@ -864,14 +863,6 @@
 		background: var(--surface2);
 		color: var(--text);
 	}
-	.foot-chip:disabled {
-		opacity: 0.45;
-		cursor: default;
-	}
-	.foot-chip:disabled:hover {
-		background: none;
-		color: var(--dim);
-	}
 	.foot-chip.auto {
 		color: var(--warn);
 		border-color: color-mix(in oklab, var(--warn) 35%, transparent);
diff --git a/src/lib/TuiPanel.svelte b/src/lib/TuiPanel.svelte
index 0c2cffa..402ef94 100644
--- a/src/lib/TuiPanel.svelte
+++ b/src/lib/TuiPanel.svelte
@@ -35,7 +35,7 @@
 		resumeCommand?: string;
 		/** Present only for session handoffs: hand the conversation back to
 		 *  the GUI chat (shows the "back to GUI" bar). */
-		onBackToGui?: () => void;
+		onBackToGui?: () => void | Promise<void>;
 		onOpenSettings?: () => void;
 	} = $props();
 
@@ -48,6 +48,9 @@
 	// pty-output/pty-exit events from the old process can't leak in.
 	let id = newId();
 	let cleanups: Array<() => void> = [];
+	let disposed = false;
+	let closing = $state(false);
+	let launchTask: Promise<void> | undefined;
 
 	function newId() {
 		return `tui-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
@@ -61,20 +64,28 @@
 
 	async function launch() {
 		if (!term) return;
+		const launchId = id;
 		status = 'starting';
 		errMsg = '';
 		try {
 			fit?.fit();
-			await ptyOpen(id, term.cols, term.rows, cwd || undefined, {
+			await ptyOpen(launchId, term.cols, term.rows, cwd || undefined, {
 				command: backend,
 				args: args.length ? args : undefined,
 				binOverride: loadBackendSettings().paths[backend]
 			});
+			// An unmount/back-to-GUI request may race an in-flight ptyOpen. Close
+			// the child it just created before allowing any GUI owner to start.
+			if (disposed || closing || launchId !== id) {
+				await ptyClose(launchId);
+				return;
+			}
 			status = 'running';
 			// Session handoff into the jucode TUI: resume the conversation with
 			// its slash command (the pty buffers the line until the TUI reads).
-			if (resumeCommand) ptyWrite(id, resumeCommand).catch(() => {});
+			if (resumeCommand) ptyWrite(launchId, resumeCommand).catch(() => {});
 		} catch (e) {
+			if (disposed || closing || launchId !== id) return;
 			const msg = String(e);
 			status = msg.includes('binary-missing:') ? 'missing' : 'error';
 			errMsg = msg;
@@ -82,14 +93,37 @@
 	}
 
 	function restart() {
+		if (disposed || closing) return;
 		ptyClose(id).catch(() => {});
 		id = newId();
 		term?.reset();
-		launch();
+		launchTask = launch();
+	}
+
+	/** Establish exclusive ownership in the other direction too: the callback
+	 *  flips the session to GUI and respawns its engine, so it must not run
+	 *  until the current (or still-opening) pty has definitely been reaped. */
+	async function backToGui() {
+		if (!onBackToGui || closing) return;
+		closing = true;
+		const ptyId = id;
+		try {
+			await ptyClose(ptyId);
+			await launchTask;
+			// If ptyOpen was still crossing the IPC boundary, the first close
+			// may have found nothing. launch() also closes in that case; this is
+			// a final idempotent barrier before the GUI process can start.
+			await ptyClose(ptyId);
+			await onBackToGui();
+		} catch (e) {
+			if (disposed) return;
+			closing = false;
+			status = 'error';
+			errMsg = String(e);
+		}
 	}
 
 	onMount(() => {
-		let disposed = false;
 		(async () => {
 			term = new Terminal({
 				fontFamily:
@@ -116,7 +150,12 @@
 				ptyWrite(id, d).catch(() => {});
 			});
 
-			await launch();
+			if (disposed || closing) {
+				cleanups.forEach((f) => f());
+				return;
+			}
+			launchTask = launch();
+			await launchTask;
 
 			const ro = new ResizeObserver(() => {
 				try {
@@ -133,6 +172,7 @@
 		})();
 		return () => {
 			disposed = true;
+			closing = true;
 		};
 	});
 
@@ -141,6 +181,8 @@
 	});
 
 	onDestroy(() => {
+		disposed = true;
+		closing = true;
 		cleanups.forEach((f) => f());
 		ptyClose(id).catch(() => {});
 		term?.dispose();
@@ -151,7 +193,7 @@
 	{#if onBackToGui}
 		<div class="handoffbar">
 			<span class="hb-text">{t('dock.tui.handoff')}</span>
-			<button class="btn sm" onclick={onBackToGui}>{t('dock.tui.backToGui')}</button>
+			<button class="btn sm" disabled={closing} onclick={backToGui}>{t('dock.tui.backToGui')}</button>
 		</div>
 	{/if}
 	<div class="term-host" bind:this={host}></div>
@@ -177,7 +219,7 @@
 			<span>{t('dock.tui.exited')}</span>
 			<button class="btn sm" onclick={restart}>{t('dock.tui.restart')}</button>
 			{#if onBackToGui}
-				<button class="btn sm" onclick={onBackToGui}>{t('dock.tui.backToGui')}</button>
+				<button class="btn sm" disabled={closing} onclick={backToGui}>{t('dock.tui.backToGui')}</button>
 			{/if}
 		</div>
 	{/if}
diff --git a/src/lib/i18n/messages/chat.ts b/src/lib/i18n/messages/chat.ts
index 5b82e60..b13afe1 100644
--- a/src/lib/i18n/messages/chat.ts
+++ b/src/lib/i18n/messages/chat.ts
@@ -35,7 +35,6 @@ const chat = {
 		gitBranch: '当前 git 分支',
 		tuiContinue: '在 TUI 中继续',
 		tuiContinueTitle: '关闭 GUI 引擎，在原生 TUI 中恢复此会话',
-		tuiNotReady: '还没有可恢复的会话 id（先发送一条消息）',
 		context: '上下文',
 		toCompaction: '{pct}% · 到压缩点',
 		contextUsed: '{pct}% · 上下文占用',
@@ -96,7 +95,6 @@ const chat = {
 		gitBranch: 'Current git branch',
 		tuiContinue: 'Continue in TUI',
 		tuiContinueTitle: 'Close the GUI engine and resume this session in the native TUI',
-		tuiNotReady: 'No resumable session id yet (send a message first)',
 		context: 'Context',
 		toCompaction: '{pct}% · to compaction',
 		contextUsed: '{pct}% · context used',
diff --git a/src/lib/session.svelte.ts b/src/lib/session.svelte.ts
index d5def10..326556f 100644
--- a/src/lib/session.svelte.ts
+++ b/src/lib/session.svelte.ts
@@ -1,4 +1,3 @@
-import { tick } from 'svelte';
 import { ChatState } from './chat.svelte';
 import { createSession, closeSession, projectRoot, writeConfig, git, claudeSessionTranscript } from './protocol';
 import { canHandOffToTui, isValidResumeSessionId } from './tuiHandoff';
@@ -72,6 +71,7 @@ export class SessionStore {
 	loaded = $state(false);
 
 	#counter = 0;
+	#surfaceTransitions = new Set<string>();
 	uid() {
 		return `s${Date.now().toString(36)}-${(this.#counter++).toString(36)}`;
 	}
@@ -396,7 +396,9 @@ export class SessionStore {
 	 */
 	restartSession(id: string, force = false) {
 		const s = this.allSessions.find((x) => x.id === id);
-		if (!s) return;
+		// The native TUI owns handed-off conversations. No crash/manual path may
+		// bring up a GUI engine beside it; returnToGui flips ownership first.
+		if (!s || s.surface === 'tui') return;
 		const now = Date.now();
 		if (force) {
 			s.chat.restarts = 0;
@@ -447,6 +449,12 @@ export class SessionStore {
 	handleExit(id: string) {
 		const s = this.allSessions.find((x) => x.id === id);
 		if (!s) return;
+		// An intentional GUI close can be observed after openInTui has already
+		// flipped the surface. Never auto-restart underneath the native TUI.
+		if (s.surface === 'tui') {
+			s.chat.switching = false;
+			return;
+		}
 		// Intentional close for a provider switch — switchProvider re-creates the
 		// engine itself, so don't treat this exit as a crash.
 		if (s.chat.switching) {
@@ -598,31 +606,45 @@ export class SessionStore {
 	 *  so a fresh empty chat and ACP sessions are a no-op. */
 	async openInTui(id: string) {
 		const s = this.allSessions.find((x) => x.id === id);
-		if (!s || s.surface === 'tui' || !canHandOffToTui(s.backendId)) return;
+		if (
+			!s ||
+			s.surface === 'tui' ||
+			s.chat.switching ||
+			this.#surfaceTransitions.has(id) ||
+			!canHandOffToTui(s.backendId)
+		)
+			return;
 		// Same rule serialize uses for `sid`: the engine persisted the
 		// conversation only once a user turn exists (or it was restored).
 		if (!isValidResumeSessionId(s.chat.sessionId) || !(s.chat.resumable || s.restored)) return;
+		// Keep a second click from issuing another close that could resolve first
+		// and expose the TUI while the original GUI child is still shutting down.
+		this.#surfaceTransitions.add(id);
 		// Intentional close — handleExit must not auto-restart the GUI engine
 		// underneath the TUI.
 		s.chat.switching = true;
 		try {
 			await closeSession(id);
 		} catch {
-			/* engine already gone */
+			// A failed close cannot establish exclusive ownership. Leave the GUI
+			// surface in place rather than starting a second process.
+			s.chat.switching = false;
+			return;
+		} finally {
+			this.#surfaceTransitions.delete(id);
 		}
+		// The tab/project may have been removed while the close was in flight.
+		if (!this.allSessions.includes(s)) return;
 		s.surface = 'tui';
 	}
 
-	/** Bring a handed-off conversation back to the GUI: flip the surface first
-	 *  (unmounting the TuiPanel closes its pty in onDestroy), wait one tick
-	 *  for that unmount, then respawn the GUI engine resuming the same
-	 *  conversation (claude `--resume`, jucode `/resume`, codex thread ctx —
-	 *  all inside restartSession). */
+	/** Bring a handed-off conversation back to the GUI. TuiPanel invokes this
+	 *  only after `ptyClose` has completed, so flipping ownership and resuming
+	 *  the GUI engine cannot overlap the native TUI process. */
 	async returnToGui(id: string) {
 		const s = this.allSessions.find((x) => x.id === id);
 		if (!s || s.surface !== 'tui') return;
 		s.surface = 'gui';
-		await tick(); // let the TuiPanel unmount issue its ptyClose first
 		this.restartSession(id, true);
 	}
 
@@ -688,7 +710,11 @@ export class SessionStore {
 				this.projects.push(proj);
 				if (proj.stale) continue;
 				for (const t of p.tabs ?? []) {
-					if (!t.sid && !t.id) continue;
+					// Workspace data is user-editable. Invalid ids must never
+					// reach either a GUI resume or the TUI pty argv.
+					const sid =
+						typeof t.sid === 'string' && isValidResumeSessionId(t.sid) ? t.sid : undefined;
+					if (!sid && !t.id) continue;
 					// Tabs saved before multi-backend support carry no backend field →
 					// jucode (normalizeBackendId maps unknown/missing to the default).
 					// Chrome fields are re-validated here (the file is user-editable).
@@ -713,9 +739,9 @@ export class SessionStore {
 					// With a conversation to resume, resume it; an empty window spawns
 					// fresh. Both keep the saved desktop id (pre-id files mint anew).
 					// A tab handed to the TUI restores as a TUI surface (no engine).
-					const surface = t.surface === 'tui' ? ('tui' as const) : undefined;
-					const id = t.sid
-						? this.restoreSession(proj, t.sid, t.title, backend, !!t.archived, chrome, t.id, acpAgent, surface)
+					const surface = t.surface === 'tui' && sid ? ('tui' as const) : undefined;
+					const id = sid
+						? this.restoreSession(proj, sid, t.title, backend, !!t.archived, chrome, t.id, acpAgent, surface)
 						: this.#spawnSaved(proj, t.id!, t.title, backend, !!t.archived, chrome, acpAgent);
 					if (!first && !t.archived) first = id;
 				}
diff --git a/src/lib/session.test.ts b/src/lib/session.test.ts
index befb6c8..5c167b9 100644
--- a/src/lib/session.test.ts
+++ b/src/lib/session.test.ts
@@ -403,6 +403,56 @@ describe('SessionStore GUI ⇄ TUI handoff', () => {
 		expect(s.chat.switching).toBe(true);
 	});
 
+	it('openInTui serializes concurrent requests behind the GUI close', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		let releaseClose!: () => void;
+		vi.mocked(closeSession).mockImplementationOnce(
+			() =>
+				new Promise<void>((resolve) => {
+					releaseClose = resolve;
+				})
+		);
+
+		const first = store.openInTui(s.id);
+		const second = store.openInTui(s.id);
+		expect(closeSession).toHaveBeenCalledTimes(1);
+		expect(s.surface).toBeUndefined();
+
+		releaseClose();
+		await Promise.all([first, second]);
+		expect(s.surface).toBe('tui');
+	});
+
+	it('openInTui keeps GUI ownership when its engine cannot be closed', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		vi.mocked(closeSession).mockRejectedValueOnce(new Error('close failed'));
+
+		await store.openInTui(s.id);
+		expect(s.surface).toBeUndefined();
+		expect(s.chat.switching).toBe(false);
+	});
+
+	it('an intentional GUI exit cannot auto-restart underneath the TUI', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		await store.openInTui(s.id);
+		vi.clearAllMocks();
+
+		store.handleExit(s.id);
+		store.restartSession(s.id, true);
+		expect(createSession).not.toHaveBeenCalled();
+		expect(s.surface).toBe('tui');
+		expect(s.chat.switching).toBe(false);
+	});
+
 	it('openInTui refuses acp sessions', async () => {
 		const store = new SessionStore();
 		const p = proj();
@@ -496,6 +546,26 @@ describe('SessionStore GUI ⇄ TUI handoff', () => {
 		expect(call[2]).toBe('claude');
 		expect((call[3] as { resume?: string }).resume).toBe(SID);
 	});
+
+	it('an invalid persisted sid never restores a TUI owner', async () => {
+		const store = new SessionStore();
+		await store.restore([
+			{
+				id: 'p1',
+				name: 'p1',
+				path: '/tmp/p1',
+				tabs: [{ id: 'live-a', sid: 'a b', title: 'A', surface: 'tui' }]
+			}
+		]);
+		const s = store.projects[0].sessions[0];
+		expect(s.surface).toBeUndefined();
+		expect(s.restored).toBeUndefined();
+		expect(sendOp).not.toHaveBeenCalledWith('live-a', {
+			op: 'command',
+			input: '/resume a b'
+		});
+		expect(createSession).toHaveBeenCalledWith('live-a', '/tmp/p1');
+	});
 });
 
 describe('SessionStore parallel-task worktrees', () => {
diff --git a/src/lib/types.ts b/src/lib/types.ts
index cb25366..b05fee9 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -25,7 +25,8 @@ export interface Session {
 	/** Which surface currently owns the conversation: the GUI chat (default,
 	 *  undefined) or the native TUI resumed by session id. Exactly one process
 	 *  holds the conversation at a time — the store closes the GUI engine
-	 *  before flipping to 'tui' and the TUI pty before flipping back. */
+	 *  before flipping to 'tui', and TuiPanel closes its pty before asking the
+	 *  store to flip back. */
 	surface?: 'gui' | 'tui';
 }
 

From 91de9677cd17c148b7dda9cccbbb1bb74ab21d5d Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sat, 29 Aug 2026 12:38:19 +0000
Subject: [PATCH 3/3] Clear switching flag after TUI handoff

Co-authored-by: Gao Yu <gaoyu06@users.noreply.github.com>
---
 src/lib/session.svelte.ts |  8 ++++++++
 src/lib/session.test.ts   | 30 ++++++++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/lib/session.svelte.ts b/src/lib/session.svelte.ts
index 326556f..2d9da31 100644
--- a/src/lib/session.svelte.ts
+++ b/src/lib/session.svelte.ts
@@ -636,6 +636,11 @@ export class SessionStore {
 		// The tab/project may have been removed while the close was in flight.
 		if (!this.allSessions.includes(s)) return;
 		s.surface = 'tui';
+		// TUI ownership is established: a late exit event from the closed GUI
+		// child lands on handleExit's `surface === 'tui'` branch, and if the
+		// engine was already dead no exit event arrives at all — so the flag
+		// must be cleared here or it latches forever.
+		s.chat.switching = false;
 	}
 
 	/** Bring a handed-off conversation back to the GUI. TuiPanel invokes this
@@ -645,6 +650,9 @@ export class SessionStore {
 		const s = this.allSessions.find((x) => x.id === id);
 		if (!s || s.surface !== 'tui') return;
 		s.surface = 'gui';
+		// Never carry a latched handoff flag back to the GUI — it would block
+		// later openInTui calls and make handleExit swallow the next real crash.
+		s.chat.switching = false;
 		this.restartSession(id, true);
 	}
 
diff --git a/src/lib/session.test.ts b/src/lib/session.test.ts
index 5c167b9..7acaead 100644
--- a/src/lib/session.test.ts
+++ b/src/lib/session.test.ts
@@ -399,8 +399,9 @@ describe('SessionStore GUI ⇄ TUI handoff', () => {
 		expect(closeSession).toHaveBeenCalledWith(s.id);
 		expect(surfaceAtClose).toBeUndefined(); // still on the GUI when the engine died
 		expect(s.surface).toBe('tui');
-		// The intentional close must not be treated as a crash to auto-restart.
-		expect(s.chat.switching).toBe(true);
+		// Once the TUI owns the conversation the flag must not stay latched —
+		// handleExit's `surface === 'tui'` branch already suppresses auto-restart.
+		expect(s.chat.switching).toBe(false);
 	});
 
 	it('openInTui serializes concurrent requests behind the GUI close', async () => {
@@ -453,6 +454,31 @@ describe('SessionStore GUI ⇄ TUI handoff', () => {
 		expect(s.chat.switching).toBe(false);
 	});
 
+	it('openInTui on an already-exited engine does not latch switching', async () => {
+		const store = new SessionStore();
+		const p = proj();
+		store.projects.push(p);
+		const s = readySession(store, p, 'claude');
+		// The GUI engine already exited (e.g. crash budget exhausted): the close
+		// is a no-op and no exit event will ever arrive to clear `switching`.
+		s.chat.engineState = 'exited';
+
+		await store.openInTui(s.id);
+		expect(s.surface).toBe('tui');
+		expect(s.chat.switching).toBe(false);
+
+		await store.returnToGui(s.id);
+		expect(s.surface).toBe('gui');
+		expect(s.chat.switching).toBe(false);
+
+		// The switching guard must not reject a later handoff.
+		vi.clearAllMocks();
+		await store.openInTui(s.id);
+		expect(closeSession).toHaveBeenCalledWith(s.id);
+		expect(s.surface).toBe('tui');
+		expect(s.chat.switching).toBe(false);
+	});
+
 	it('openInTui refuses acp sessions', async () => {
 		const store = new SessionStore();
 		const p = proj();