@tulex-cli/tulex-code 0.1.1

package/dist/src/ui/hooks/useBranchCommand.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type Config } from '@tulex-cli/tulex-cli-core';
+import type { UseHistoryManagerReturn } from './useHistoryManager.js';
+export interface UseBranchCommandOptions {
+    config: Config | null;
+    historyManager: Pick<UseHistoryManagerReturn, 'clearItems' | 'loadHistory' | 'addItem'>;
+    startNewSession: (sessionId: string) => void;
+    setSessionName?: (name: string | null) => void;
+    remount?: () => void;
+}
+export interface UseBranchCommandResult {
+    handleBranch: (name?: string) => Promise<void>;
+}
+/**
+ * Orchestrates `/branch`:
+ *   1. Capture the current (soon-to-be-parent) sessionId for the resume hint.
+ *   2. Finalize the outgoing ChatRecordingService so the last metadata is on disk.
+ *   3. Call `SessionService.forkSession` to write a new JSONL under a new id.
+ *   4. Load the fork back via `loadSession` and switch the UI + core config.
+ *   5. Compute the customTitle — user-provided name OR `deriveFirstPrompt` —
+ *      always suffixed with ` (Branch)` (bumping to `(Branch N)` on collision).
+ *   6. Fire the SessionStart hook.
+ *   7. Announce the fork with Claude-style two-line info item:
+ *        `Branched conversation "foo". You are now in the branch.`
+ *        `To resume the original: /resume <oldSessionId>`
+ *
+ * Mirrors claude-code/src/commands/branch/branch.ts.
+ */
+export declare function useBranchCommand(options: UseBranchCommandOptions): UseBranchCommandResult;

package/dist/src/ui/hooks/useBranchCommand.js

@@ -0,0 +1,230 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { useCallback } from 'react';
+import { randomUUID } from 'node:crypto';
+import { SessionStartSource, } from '@tulex-cli/tulex-cli-core';
+import { buildResumedHistoryItems } from '../utils/resumeHistoryUtils.js';
+import { restoreGoalFromHistory } from '../utils/restoreGoal.js';
+import { t } from '../../i18n/index.js';
+/**
+ * Cap for the `(Branch N)` collision suffix. We scan all matching titles
+ * once via `findSessionTitlesByPrefix` and then pick the first free slot
+ * in memory; 99 is generous for realistic use and bounds the timestamp-
+ * fallback path on pathologically dense title spaces.
+ */
+const MAX_BRANCH_COLLISION_SCAN = 99;
+/**
+ * Derives a short one-line title from the first *real* user message in the
+ * transcript. Mirrors Claude Code's `deriveFirstPrompt` (see
+ * claude-code/src/commands/branch/branch.ts): collapse whitespace, truncate
+ * to 100 chars, fall back to "Branched conversation" when the transcript
+ * has no user text.
+ *
+ * Reads ChatRecord[] — the JSONL-level transcript — NOT the Gemini API
+ * `Content[]` history. The latter is prepended with environment / CLAUDE.md /
+ * context injections by the runtime; its first role=user entry is a
+ * synthetic bootstrap message, not anything the user typed.
+ *
+ * Records with a `subtype` are skipped — those are cron-fired prompts,
+ * notifications, slash-command echoes, etc., not genuine user input.
+ */
+function deriveFirstPrompt(messages) {
+    for (const record of messages) {
+        if (record.type !== 'user')
+            continue;
+        if (record.subtype)
+            continue;
+        const parts = record.message?.parts;
+        if (!parts)
+            continue;
+        for (const part of parts) {
+            if ('text' in part && typeof part.text === 'string' && part.text) {
+                const collapsed = part.text.replace(/\s+/g, ' ').trim().slice(0, 100);
+                if (collapsed)
+                    return collapsed;
+            }
+        }
+    }
+    return 'Branched conversation';
+}
+/**
+ * Appends ` (Branch)` to `baseName`, bumping to ` (Branch 2)`, ` (Branch 3)`,
+ * ... when the exact name is already taken by another session's customTitle
+ * in the current project. Mirrors Claude's `getUniqueForkName`.
+ *
+ * Does ONE prefix scan instead of probing each candidate via
+ * `findSessionsByTitle`: in dense title spaces the per-probe scanner could
+ * walk the project's chat directory up to {@link MAX_BRANCH_COLLISION_SCAN}
+ * times, and `/branch` would visibly stall. We collect every existing
+ * `${trimmed} (Branch...` title once, then pick the first free slot in memory.
+ */
+async function computeUniqueBranchTitle(baseName, sessionService) {
+    const trimmed = baseName.trim();
+    const taken = new Set((await sessionService.findSessionTitlesByPrefix(`${trimmed} (Branch`)).map((t) => t.toLowerCase().trim()));
+    const first = `${trimmed} (Branch)`;
+    if (!taken.has(first.toLowerCase()))
+        return first;
+    for (let n = 2; n <= MAX_BRANCH_COLLISION_SCAN; n++) {
+        const candidate = `${trimmed} (Branch ${n})`;
+        if (!taken.has(candidate.toLowerCase()))
+            return candidate;
+    }
+    // Pathological density — timestamp fallback keeps the fork unique.
+    return `${trimmed} (Branch ${Date.now()})`;
+}
+/**
+ * Orchestrates `/branch`:
+ *   1. Capture the current (soon-to-be-parent) sessionId for the resume hint.
+ *   2. Finalize the outgoing ChatRecordingService so the last metadata is on disk.
+ *   3. Call `SessionService.forkSession` to write a new JSONL under a new id.
+ *   4. Load the fork back via `loadSession` and switch the UI + core config.
+ *   5. Compute the customTitle — user-provided name OR `deriveFirstPrompt` —
+ *      always suffixed with ` (Branch)` (bumping to `(Branch N)` on collision).
+ *   6. Fire the SessionStart hook.
+ *   7. Announce the fork with Claude-style two-line info item:
+ *        `Branched conversation "foo". You are now in the branch.`
+ *        `To resume the original: /resume <oldSessionId>`
+ *
+ * Mirrors claude-code/src/commands/branch/branch.ts.
+ */
+export function useBranchCommand(options) {
+    const { config, historyManager, startNewSession, setSessionName, remount } = options;
+    const handleBranch = useCallback(async (name) => {
+        if (!config)
+            return;
+        const oldSessionId = config.getSessionId();
+        const newSessionId = randomUUID();
+        const sessionService = config.getSessionService();
+        let coreSwapped = false;
+        let uiSwapped = false;
+        let prevSessionData;
+        try {
+            // 1. Flush outgoing recorder. Must happen BEFORE the parent snapshot
+            //    so the snapshot captures `finalize()`'s trailing custom_title
+            //    record — without that, a rollback restores the recorder with
+            //    a stale `lastCompletedUuid` and the next user message attaches
+            //    its parentUuid to a record that's no longer the JSONL tail.
+            try {
+                config.getChatRecordingService()?.finalize();
+            }
+            catch {
+                // best-effort
+            }
+            // 2. Snapshot the parent JSONL state for rollback. `/branch` is
+            //    guarded on `isIdleRef`, so the file isn't being mutated
+            //    concurrently between this load and the swap below.
+            try {
+                prevSessionData = await sessionService.loadSession(oldSessionId);
+            }
+            catch {
+                // Best-effort snapshot. Falling back to undefined still rolls
+                // back sessionId + recorder, which is the load-bearing invariant;
+                // we just lose the parentUuid chain on the restored recorder.
+            }
+            // 3. Fork the JSONL on disk.
+            await sessionService.forkSession(oldSessionId, newSessionId);
+            // 4. Load the new file.
+            const resumed = await sessionService.loadSession(newSessionId);
+            if (!resumed) {
+                throw new Error('Failed to load newly forked session');
+            }
+            // 5. Swap core first. Anything that can still fail (startNewSession,
+            //    client init) runs while the UI is still showing the parent
+            //    session, so a throw leaves the user safely on the parent
+            //    instead of stranded with a cleared history and a half-live
+            //    client. `coreSwapped` gates the rollback path in the catch
+            //    block below — without it, a failure between swap and UI
+            //    update would leave core on the fork while UI still shows
+            //    the parent, silently recording user input into an orphan.
+            config.startNewSession(newSessionId, resumed);
+            coreSwapped = true;
+            await config.getGeminiClient()?.initialize?.(SessionStartSource.Branch);
+            // 6. Swap UI. Once this commits, rolling core back is unsafe —
+            //    it would leave UI on the branch but recorder writing into
+            //    the parent JSONL (the inverse split-brain). `uiSwapped` is
+            //    set immediately after the UI commits so any subsequent
+            //    failure (title, hook, remount, announce) skips the catch
+            //    block's core rollback.
+            const uiHistoryItems = buildResumedHistoryItems(resumed, config);
+            startNewSession(newSessionId);
+            historyManager.clearItems();
+            historyManager.loadHistory(uiHistoryItems);
+            uiSwapped = true;
+            // Re-arm /goal under the fork's new sessionId. The branched JSONL
+            // is a verbatim copy of the parent's, so an active goal sentinel
+            // carries over — but `config.startNewSession` rebuilt the hook
+            // system under `newSessionId`, leaving the parent's `activeGoal`
+            // store entry stale and the Stop hook unregistered. Same rationale
+            // as the /resume path; see [[useResumeCommand]] for details.
+            try {
+                restoreGoalFromHistory(uiHistoryItems, config, historyManager.addItem);
+            }
+            catch {
+                // Best-effort — branch must not fail on goal restoration.
+            }
+            // 7. Compute and apply the branch customTitle.
+            //    The forked transcript is identical to the parent's, so reading
+            //    the first real user message from `resumed.conversation.messages`
+            //    mirrors Claude's "use the first parent message" behavior.
+            const baseName = name ?? deriveFirstPrompt(resumed.conversation.messages);
+            const effectiveTitle = await computeUniqueBranchTitle(baseName, sessionService);
+            config.getChatRecordingService()?.recordCustomTitle(effectiveTitle);
+            setSessionName?.(effectiveTitle);
+            // 8. Refresh terminal UI.
+            remount?.();
+            // 10. Announce. Two history items mirror Claude's success message
+            //    (branched line + resume hint). The quoted name is the raw
+            //    user-provided `name`; no `(Branch)` suffix — that decoration
+            //    belongs in the picker/prompt bar, not in the user-facing
+            //    announcement.
+            const titleInfo = name ? ` "${name}"` : '';
+            historyManager.addItem({
+                type: 'info',
+                text: t('Branched conversation{{titleInfo}}. You are now in the branch.', { titleInfo }),
+            }, Date.now());
+            historyManager.addItem({
+                type: 'info',
+                text: t('To resume the original: /resume {{sessionId}}', {
+                    sessionId: oldSessionId,
+                }),
+            }, Date.now());
+        }
+        catch (err) {
+            if (coreSwapped && !uiSwapped) {
+                // Core switched to the fork but UI hasn't swapped yet — put core
+                // back on the parent, otherwise the recorder would keep writing
+                // new user messages into the orphan fork JSONL while UI still
+                // shows the parent.
+                //
+                // Skipped once `uiSwapped` is true: at that point UI is already
+                // on the branch, so reverting core would create the inverse
+                // split-brain (UI on branch, recorder on parent). Post-UI-swap
+                // failures (title, hook, remount, announce) are non-fatal and
+                // surfaced as an error item without unwinding the swap.
+                try {
+                    config.startNewSession(oldSessionId, prevSessionData);
+                    // Re-hydrate chat history against the restored session. Best-
+                    // effort: if this throws too, sessionId + recorder are still
+                    // back on the parent, which is the load-bearing invariant.
+                    await config.getGeminiClient()?.initialize?.();
+                }
+                catch (rollbackErr) {
+                    config
+                        .getDebugLogger()
+                        .warn(`Rollback after failed /branch init failed: ${rollbackErr}`);
+                }
+            }
+            historyManager.addItem({
+                type: 'error',
+                text: t('Failed to branch conversation: {{message}}', {
+                    message: err instanceof Error ? err.message : String(err),
+                }),
+            }, Date.now());
+        }
+    }, [config, historyManager, startNewSession, setSessionName, remount]);
+    return { handleBranch };
+}
+//# sourceMappingURL=useBranchCommand.js.map

package/dist/src/ui/hooks/useBranchCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBranchCommand.js","sourceRoot":"","sources":["../../../../src/ui/hooks/useBranchCommand.ts"],"names":[],"mappings":"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"}

package/dist/src/ui/hooks/useBranchCommand.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/ui/hooks/useBranchCommand.test.js

@@ -0,0 +1,386 @@
+/**
+ * @license
+ * Copyright 2025 Qwen Code
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useBranchCommand } from './useBranchCommand.js';
+import { restoreGoalFromHistory } from '../utils/restoreGoal.js';
+vi.mock('../utils/restoreGoal.js', () => ({
+    restoreGoalFromHistory: vi.fn(() => ({ restored: false })),
+}));
+describe('useBranchCommand', () => {
+    let forkSession;
+    let loadSession;
+    let finalize;
+    let startNewSessionConfig;
+    let startNewSessionUI;
+    let recordCustomTitle;
+    let findSessionTitlesByPrefix;
+    let clearItems;
+    let loadHistory;
+    let setSessionName;
+    let remount;
+    let addItem;
+    // Mock Config shape covers only what useBranchCommand touches.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let config;
+    const makeOptions = () => ({
+        config,
+        historyManager: { clearItems, loadHistory, addItem },
+        startNewSession: startNewSessionUI,
+        setSessionName,
+        remount,
+    });
+    // Helper to build a ChatRecord-shaped user message for loadSession mocks.
+    // Keeps intent explicit at each call site (genuine user msg vs. synthetic
+    // subtype vs. non-text) without pulling in the full ChatRecord type here.
+    const userRecord = (text, subtype) => ({
+        uuid: 'u' + text.slice(0, 3),
+        parentUuid: null,
+        sessionId: 'sid',
+        type: 'user',
+        ...(subtype ? { subtype } : {}),
+        timestamp: 't',
+        cwd: '/',
+        version: 'v',
+        message: { role: 'user', parts: [{ text }] },
+    });
+    beforeEach(() => {
+        vi.mocked(restoreGoalFromHistory).mockClear();
+        forkSession = vi
+            .fn()
+            .mockResolvedValue({ filePath: '/tmp/new.jsonl', copiedCount: 2 });
+        loadSession = vi.fn().mockResolvedValue({
+            conversation: {
+                messages: [userRecord('help me fix the login bug')],
+            },
+            filePath: '/tmp/new.jsonl',
+            lastCompletedUuid: 'u2',
+        });
+        finalize = vi.fn();
+        recordCustomTitle = vi.fn().mockReturnValue(true);
+        findSessionTitlesByPrefix = vi.fn().mockResolvedValue([]);
+        startNewSessionConfig = vi.fn();
+        startNewSessionUI = vi.fn();
+        clearItems = vi.fn();
+        loadHistory = vi.fn();
+        setSessionName = vi.fn();
+        remount = vi.fn();
+        addItem = vi.fn();
+        config = {
+            getSessionId: () => '12345678-aaaa-bbbb-cccc-dddddddddddd',
+            getSessionService: () => ({
+                forkSession,
+                loadSession,
+                findSessionTitlesByPrefix,
+            }),
+            getChatRecordingService: () => ({ finalize, recordCustomTitle }),
+            getGeminiClient: () => ({ initialize: vi.fn() }),
+            startNewSession: startNewSessionConfig,
+            getDebugLogger: () => ({ warn: vi.fn() }),
+        };
+    });
+    it('runs finalize → snapshot → forkSession → loadSession → config.startNewSession in order', async () => {
+        // The parent snapshot must come AFTER finalize(): finalize() appends a
+        // trailing custom_title record to the parent JSONL, advancing the
+        // recorder's lastCompletedUuid. A snapshot taken before that captures
+        // a stale tail; on rollback the restored recorder would chain its next
+        // record's parentUuid to a record that's no longer the JSONL tail,
+        // orphaning the custom_title record from the parent chain.
+        const order = [];
+        finalize.mockImplementation(() => order.push('finalize'));
+        forkSession.mockImplementation(async () => {
+            order.push('fork');
+            return { filePath: '/tmp/new.jsonl', copiedCount: 2 };
+        });
+        loadSession.mockImplementation(async () => {
+            order.push('load');
+            return {
+                conversation: { messages: [] },
+                filePath: '/tmp/new.jsonl',
+                lastCompletedUuid: 'u',
+            };
+        });
+        startNewSessionConfig.mockImplementation(() => order.push('config.start'));
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(order).toEqual([
+            'finalize',
+            'load', // parent snapshot for rollback (after finalize so it captures the custom_title append)
+            'fork',
+            'load', // forked session
+            'config.start',
+        ]);
+    });
+    it('re-arms /goal against the forked sessionId after the UI swap', async () => {
+        // The branched JSONL is a verbatim copy of the parent's, so an active
+        // goal sentinel rides along. Without this restore call the forked
+        // session inherits the goal in transcript only — store stays empty,
+        // footer pill shows nothing, and the Stop hook never fires under the
+        // new sessionId. Same root cause as the /resume gap; pin it here.
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(restoreGoalFromHistory).toHaveBeenCalledWith(expect.any(Array), config, addItem);
+    });
+    it('records the user-provided name with a (Branch) suffix', async () => {
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(recordCustomTitle).toHaveBeenCalledWith('my-branch (Branch)');
+        expect(setSessionName).toHaveBeenCalledWith('my-branch (Branch)');
+    });
+    it('bumps to (Branch N) when the default suffix is already taken', async () => {
+        // `findSessionTitlesByPrefix` returns every existing title under the
+        // `${name} (Branch` prefix in one shot, so the bump logic picks the
+        // first free slot in memory — no per-candidate disk probe.
+        findSessionTitlesByPrefix.mockResolvedValue(['my-branch (Branch)']);
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(recordCustomTitle).toHaveBeenCalledWith('my-branch (Branch 2)');
+        expect(setSessionName).toHaveBeenCalledWith('my-branch (Branch 2)');
+    });
+    it('does ONE prefix scan even when many (Branch N) slots are taken', async () => {
+        // Pin the perf invariant: regardless of collision density, the
+        // collision lookup must be a single project-wide scan, not N probes.
+        // Reviewer's concern was that 99 sequential probes can stall /branch
+        // on dense title spaces.
+        findSessionTitlesByPrefix.mockResolvedValue([
+            'my-branch (Branch)',
+            'my-branch (Branch 2)',
+            'my-branch (Branch 3)',
+            'my-branch (Branch 4)',
+        ]);
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(findSessionTitlesByPrefix).toHaveBeenCalledTimes(1);
+        expect(findSessionTitlesByPrefix).toHaveBeenCalledWith('my-branch (Branch');
+        expect(recordCustomTitle).toHaveBeenCalledWith('my-branch (Branch 5)');
+    });
+    it('derives the base title from the first user ChatRecord when no name is given', async () => {
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch();
+        });
+        // deriveFirstPrompt collapses whitespace and truncates to 100 chars;
+        // "help me fix the login bug" fits, then + " (Branch)"
+        expect(recordCustomTitle).toHaveBeenCalledWith('help me fix the login bug (Branch)');
+    });
+    it('falls back to "Branched conversation (Branch)" when the transcript has no user records', async () => {
+        loadSession.mockResolvedValue({
+            conversation: { messages: [] },
+            filePath: '/tmp/new.jsonl',
+            lastCompletedUuid: null,
+        });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch();
+        });
+        expect(recordCustomTitle).toHaveBeenCalledWith('Branched conversation (Branch)');
+    });
+    it('skips synthetic user-role records (cron, notification, etc.) and picks the first real prompt', async () => {
+        loadSession.mockResolvedValue({
+            conversation: {
+                messages: [
+                    userRecord('scheduled task ran', 'cron'),
+                    userRecord('agent finished X', 'notification'),
+                    userRecord('what does this codebase do'),
+                ],
+            },
+            filePath: '/tmp/new.jsonl',
+            lastCompletedUuid: null,
+        });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch();
+        });
+        expect(recordCustomTitle).toHaveBeenCalledWith('what does this codebase do (Branch)');
+    });
+    it('emits the Claude-style success pair naming the branch and the resume hint with the old sessionId', async () => {
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'info',
+            text: 'Branched conversation "my-branch". You are now in the branch.',
+        }), expect.any(Number));
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'info',
+            text: 'To resume the original: /resume 12345678-aaaa-bbbb-cccc-dddddddddddd',
+        }), expect.any(Number));
+    });
+    it('initializes GeminiClient with SessionStartSource.Branch', async () => {
+        const initialize = vi.fn().mockResolvedValue(undefined);
+        config.getGeminiClient = () => ({ initialize });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('my-branch');
+        });
+        expect(initialize).toHaveBeenCalledTimes(1);
+        expect(initialize).toHaveBeenCalledWith('branch');
+    });
+    it('omits the quoted-title fragment when no name is provided', async () => {
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch();
+        });
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'info',
+            text: 'Branched conversation. You are now in the branch.',
+        }), expect.any(Number));
+    });
+    it('surfaces an error item and does not switch sessions when forkSession throws', async () => {
+        forkSession.mockRejectedValue(new Error('disk full'));
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('x');
+        });
+        expect(startNewSessionConfig).not.toHaveBeenCalled();
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'error',
+            text: expect.stringMatching(/Failed to branch conversation.*disk full/),
+        }), expect.any(Number));
+    });
+    it('rolls core back to the parent session when getGeminiClient().initialize() rejects after swap', async () => {
+        // The reviewer's scenario: config.startNewSession succeeds (core is now
+        // on the fork), but then getGeminiClient().initialize() rejects. Without
+        // rollback, core stays on the fork while UI is still on the parent, so
+        // the recorder silently writes subsequent user input into an orphan
+        // JSONL. This test pins the rollback invariant — after the failure core
+        // must be back on the parent sessionId with the parent's ResumedSessionData.
+        const oldSessionId = '12345678-aaaa-bbbb-cccc-dddddddddddd';
+        const parentResumed = {
+            conversation: { messages: [userRecord('parent msg')] },
+            filePath: `/tmp/${oldSessionId}.jsonl`,
+            lastCompletedUuid: 'uparent',
+        };
+        const forkResumed = {
+            conversation: { messages: [userRecord('parent msg')] },
+            filePath: '/tmp/new.jsonl',
+            lastCompletedUuid: 'uparent',
+        };
+        // Called twice: once up front to snapshot the parent for rollback,
+        // once after forkSession to load the fork.
+        loadSession.mockImplementation(async (sid) => sid === oldSessionId ? parentResumed : forkResumed);
+        const initialize = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('init boom')) // fork init fails
+            .mockResolvedValueOnce(undefined); // rollback re-init succeeds
+        config.getGeminiClient = () => ({ initialize });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('x');
+        });
+        // Core was swapped to the fork, then rolled back to the parent.
+        expect(startNewSessionConfig).toHaveBeenNthCalledWith(1, expect.not.stringMatching(oldSessionId), forkResumed);
+        expect(startNewSessionConfig).toHaveBeenNthCalledWith(2, oldSessionId, parentResumed);
+        // Client was re-initialized after rollback so chat history re-hydrates
+        // against the parent session.
+        expect(initialize).toHaveBeenCalledTimes(2);
+        // UI never switched — no cleared history, no UI sessionId swap.
+        expect(clearItems).not.toHaveBeenCalled();
+        expect(loadHistory).not.toHaveBeenCalled();
+        expect(startNewSessionUI).not.toHaveBeenCalled();
+        expect(setSessionName).not.toHaveBeenCalled();
+        // User sees the failure.
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'error',
+            text: expect.stringMatching(/Failed to branch conversation.*init boom/),
+        }), expect.any(Number));
+    });
+    it('still surfaces the error and leaves core on the parent when rollback re-init also throws', async () => {
+        // If the rollback initialize() itself rejects, the swap of sessionId +
+        // recorder has still happened — that is the load-bearing invariant —
+        // so we just log and surface the original failure without crashing.
+        const oldSessionId = '12345678-aaaa-bbbb-cccc-dddddddddddd';
+        loadSession.mockResolvedValue({
+            conversation: { messages: [userRecord('parent msg')] },
+            filePath: '/tmp/new.jsonl',
+            lastCompletedUuid: 'u2',
+        });
+        const debugWarn = vi.fn();
+        config.getDebugLogger = () => ({ warn: debugWarn });
+        const initialize = vi
+            .fn()
+            .mockRejectedValueOnce(new Error('init boom'))
+            .mockRejectedValueOnce(new Error('rollback boom'));
+        config.getGeminiClient = () => ({ initialize });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('x');
+        });
+        // Core was still rolled back to the parent sessionId.
+        expect(startNewSessionConfig).toHaveBeenNthCalledWith(2, oldSessionId, expect.any(Object));
+        expect(debugWarn).toHaveBeenCalledWith(expect.stringContaining('Rollback after failed /branch init failed'));
+        // Original failure is what the user sees, not the rollback failure.
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'error',
+            text: expect.stringMatching(/Failed to branch conversation.*init boom/),
+        }), expect.any(Number));
+    });
+    it('does not roll core back to parent when a post-UI-swap step throws', async () => {
+        // The reviewer's reverse split-brain: once the UI commits to the branch,
+        // any subsequent failure (recordCustomTitle, hook fire, remount,
+        // announcement render) must NOT trigger the catch block's core rollback.
+        // If it did, the user would see the branch UI but every new prompt
+        // would be recorded into the parent's JSONL.
+        //
+        // Pin the invariant by making remount() — which runs after the UI swap —
+        // throw, then assert: only ONE config.startNewSession call (to the
+        // branch), no second call resetting it back to the parent.
+        const oldSessionId = '12345678-aaaa-bbbb-cccc-dddddddddddd';
+        remount.mockImplementation(() => {
+            throw new Error('remount boom');
+        });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('x');
+        });
+        // UI did swap.
+        expect(startNewSessionUI).toHaveBeenCalledTimes(1);
+        expect(clearItems).toHaveBeenCalled();
+        expect(loadHistory).toHaveBeenCalled();
+        // Core did NOT roll back to the parent — only the initial swap to
+        // the branch. A second call with `oldSessionId` would mean the catch
+        // block reverted core while UI stayed on the branch.
+        expect(startNewSessionConfig).toHaveBeenCalledTimes(1);
+        expect(startNewSessionConfig).not.toHaveBeenCalledWith(oldSessionId, expect.anything());
+        // The user still sees the failure surfaced as an error item.
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'error',
+            text: expect.stringMatching(/Failed to branch conversation.*remount boom/),
+        }), expect.any(Number));
+    });
+    it('does not clear or swap the UI when core startNewSession throws post-fork', async () => {
+        // Guards the "swap core first" invariant: if core swap fails after the
+        // disk fork succeeds, the UI must stay on the parent — no cleared
+        // history, no new UI sessionId — so the user is not stranded.
+        startNewSessionConfig.mockImplementation(() => {
+            throw new Error('core boom');
+        });
+        const { result } = renderHook(() => useBranchCommand(makeOptions()));
+        await act(async () => {
+            await result.current.handleBranch('x');
+        });
+        expect(forkSession).toHaveBeenCalledTimes(1);
+        expect(clearItems).not.toHaveBeenCalled();
+        expect(loadHistory).not.toHaveBeenCalled();
+        expect(startNewSessionUI).not.toHaveBeenCalled();
+        expect(addItem).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'error',
+            text: expect.stringMatching(/Failed to branch conversation.*core boom/),
+        }), expect.any(Number));
+    });
+});
+//# sourceMappingURL=useBranchCommand.test.js.map