Mobile sessions and terminal interaction
The mobile session view gives a phone or tablet one focused view of a host worktree. It joins worktree activity, session tabs, agent history, agent chat, terminal streams, browser views, file review, and local state that can survive a reconnect. The same session model supports the native app and the mobile web surface. This page extends Mobile client and complements Mobile web delivery.
Session model
Host and worktree context
The mobile client opens a session for one host and one worktree. A worktree is the host-side coding area that scopes tabs, terminals, agent activity, files, and review actions. Host-qualified identity keeps equal local IDs on different execution hosts separate.
The worktree catalog combines the desktop catalog with reachable server data. It can show a first page of useful rows before the full catalog arrives. Search, visibility filters, pinning, repository grouping, and lineage help the user move from a large host catalog to the worktree that needs attention.
Each server keeps its own catalog snapshot for each active client. A slow or failed server does not make healthy data from the desktop or another server look empty. A failed host read keeps the last confirmed rows for that server until the desktop removes the server. Valid unchanged or delta snapshots avoid rebuilding all rows.
References: mobile/…/server-workspaces.ts• L18-20 mobile/…/server-workspaces.ts• L99-145 mobile/…/server-workspaces.ts• L162-193 mobile/…/use-workspace-sections.ts• L22-120
Session tabs
Session tabs are the host-published list of open surfaces in a worktree. One tab strip moves between terminals, Markdown, files and diffs, browser pages, terminal-backed agent chat, and structured agent sessions.
The tab list is the source of surface identity and order. A terminal may be visible while its host handle is still being created or restored. A closed session can remain empty until the user creates a new tab. Long press exposes actions for a chat tab, such as continuing in a CLI, changing worker auto-close behavior, or closing the tab.
The strip shows agent state when the host has confirmed it. A status restored across a host restart is not shown as live until new host data confirms it. On narrow screens the strip scrolls horizontally and gives an edge hint when hidden tabs contain active agent work.
The session can also show two terminal tabs at once. The active pane owns input. The second pane stays mounted when it is hidden so its scrollback survives a layout change.
This diagram shows how a worktree becomes mobile surfaces and, when selected, terminal panes.
flowchart LR
Host[Host worktree] --> Snapshot[Published tab snapshot]
Snapshot --> Strip[Mobile tab strip]
Strip --> Terminal[Terminal surface]
Strip --> Agent[Agent chat]
Strip --> File[File or diff]
Strip --> Browser[Browser page]
Strip --> Markdown[Markdown note]
Terminal --> Layout[One or two panes]
References: mobile/…/mobile-session-tabs.ts• L14-106 mobile/…/active-session-tab.ts• L19-72 mobile/…/MobileSessionActiveContent.tsx• L155-390 mobile/…/MobileSessionHeader.tsx• L60-171
Session startup and creation
Session startup resets state for the selected host and worktree before it hydrates tabs and terminal inventory. It keeps route state, terminal drafts, pending selections, pane state, and document caches from one worktree from leaking into the next.
The client restores the published session view, obtains terminal records, and subscribes to the selected terminal after its surface is ready. Creation and activation use caller-scoped navigation, so opening a session does not unexpectedly navigate other paired clients. New tabs keep a stable operation identity while the result is pending. If a reply is lost, the client checks the published tab before it starts a duplicate.
The session can create a terminal, quick command, Markdown note, browser page, terminal-backed agent, or structured agent session. The host advertises which paths it supports. Folder and floating workspaces hide actions that need repository or host-browser context.
Structured chat creation first checks host support. A successful creation publishes a new session tab. An uncertain result stays uncertain because the host may already own the new chat.
References: mobile/…/use-mobile-session-foundation.ts• L21-67 mobile/…/use-mobile-session-startup.ts• L50-204 mobile/…/use-mobile-session-terminal-create-actions.ts• L60-171 mobile/…/mobile-structured-agent-session-launch.ts• L34-191 mobile/…/mobile-session-tab-write-operations.ts• L9-37
Worktree presentation
Worktree actions
The session header keeps the active worktree as the scope for file browsing, source control, pull request context, and review actions. Wide layouts can place these views beside the session. Narrow layouts use their own route while preserving the same worktree identity.
The mobile view follows shared host and workspace view choices when those choices are available. It hides actions that need repository data when the current workspace cannot provide that data. Pull request details and checks can fail independently, so a check read failure does not remove the usable review controls. A stale linked review is cleared only when the branch and current revision prove that it no longer applies.
References: mobile/…/MobileSessionHeader.tsx• L94-177 mobile/…/MobileSourceControlButton.tsx• L1-80 mobile/…/MobileSessionSurface.tsx• L19-79 mobile/…/mobile-pr-sidebar-state.ts• L24-221
Worktree list organization
The worktree list turns host catalog data into navigable sections. It applies search and visibility rules before sorting, pinning, grouping, and lineage display. Pinned parents can keep their child worktrees visible, which preserves the relationship between related work.
Activity uses host sidebar state when available. Older hosts use weaker signals such as unread state, workspace status, and live terminal count. Rows include host and workspace-instance identity, so worktrees with equal local IDs do not merge across servers or lineage branches. Cross-server parent links are used only when instance identity proves that the relationship is current.
References: mobile/…/use-workspace-sections.ts• L22-120 mobile/…/workspace-list-sections.ts• L104-317 mobile/…/mobile-workspace-lineage.ts• L41-151 mobile/…/home-worktree-info.ts• L33-87
Agent history and chat
Agent history
Agent Session History gives the user a searchable view of past agent sessions known to a host. It supports Workspace, Project, and All scopes. Workspace means the active worktree. Project includes sibling worktrees from the same repository. All keeps the host-wide result set.
The list groups sessions by folder and shows the agent, title, latest message, message count, age, and current-worktree context. It can expand a row for a short conversation preview. A transcript scan issue appears as a count while usable sessions remain available. The screen checks host support before it offers history and keeps a ready list during a short reconnect.
References: mobile/…/MobileAgentSessionHistoryPanel.tsx• L45-84 mobile/…/MobileAgentSessionHistoryPanel.tsx• L318-409 mobile/…/MobileAgentSessionHistoryList.tsx• L14-196 mobile/…/use-mobile-agent-history-state.ts• L41-218
History resume
A history row can resume an agent session in a worktree that can run it safely. Resume resolves the session's owning worktree and host, checks that the target is local or SSH-backed, prepares the saved session, and queues it in a terminal. Runtime-hosted workspaces and mismatched hosts are blocked with a clear message.
The resume action owns one operation at a time. It uses a stable mutation identity while the result is uncertain, then returns to the existing session route when the target is the current worktree. A later deliberate resume receives a new identity.
References: mobile/…/MobileAgentSessionHistoryPanel.tsx• L45-84 mobile/…/MobileAgentSessionHistoryList.tsx• L14-196 mobile/…/use-mobile-agent-history-state.ts• L41-218 mobile/…/agent-history-resume-target.ts• L24-139
Chat lanes
The chat surface presents two host session types through one mobile view. A terminal-backed lane reads agent output from a terminal transcript. A structured lane reads a host journal with turn status, prompts, queued messages, options, and background work. The lane resolver keeps the two sources separate while the view gives them a common set of message and input controls.
The structured lane is the richer session model. It can expose model and permission choices, context use, a thread goal, usage-limit state, background tasks, child work, rewind, and an interrupted-turn Continue action. Each control is offered only when the current host and route can carry it.
Both lanes retain a device copy of settled transcript state. That copy restores the reading view quickly, but it does not prove that a prompt or turn is still live. A fresh host read must confirm live state before the client enables actions.
This diagram shows the shared chat surface without hiding the difference between its two source lanes.
flowchart LR
Tab[Active agent tab] --> Resolve[Resolve session lane]
Resolve --> Legacy[Terminal-backed transcript]
Resolve --> Structured[Journal-backed session]
Legacy --> Chat[Mobile chat view]
Structured --> Chat
Chat --> Transcript[Messages and tool activity]
Chat --> Prompts[Questions and approvals]
Chat --> Queue[Queued messages]
Chat --> Composer[Composer and session options]
References: mobile/…/use-mobile-native-chat-session-lane.ts• L12-95 mobile/…/use-mobile-native-chat-session.ts• L77-256 mobile/…/use-mobile-structured-agent-session.ts• L56-82 mobile/…/use-mobile-structured-agent-session.ts• L258-309 mobile/…/MobileNativeChatOverlay.tsx• L96-128
Chat transcript
The transcript turns host messages and live turn state into readable mobile rows. It separates agent prose, reasoning, tool activity, notices, plans, questions, permissions, images, diffs, and background-task runs. Older pages load on demand, and the view follows the latest turn until the user reads elsewhere.
Rows can open referenced files, follow Markdown links, show visual output, copy message text, and offer response actions. The row projection folds related tool and image records into stable mobile rows. Unchanged history keeps its reading position and disclosure state during live updates.
Some structured responses can offer a fork. Forking creates a new chat from the selected response and places it after the source tab when the host supports that placement. The source chat stays unchanged, and the new chat keeps a link back to its source.
References: mobile/…/MobileNativeChatView.tsx• L223-431 mobile/…/mobile-native-chat-projection.ts• L37-103 mobile/…/mobile-native-chat-transcript-store.ts• L19-79 mobile/…/MobileNativeChatForkProvider.tsx• L13-61 mobile/…/mobile-structured-chat-fork.ts• L32-101
Chat input and prompts
The composer sends text to the active host session and can hold file references, images, skills, provider options, model choices, and dictation. Its draft is scoped to the host, worktree, and tab. Text drafts persist per open tab and restore after a page or app restart. Launch prefill is treated as context rather than user text, so clearing it does not make it return.
A send clears the matching draft before the host acknowledges it. Accepted messages can remain as local pending rows until the transcript proves that they landed. A refusal restores the draft. An unknown result does not resend automatically because the host may have accepted it. Offline sends can wait in a local queue when the active lane cannot accept them yet.
Prompt cards represent approvals, questions, permissions, and other input that the host currently needs. Responses include the prompt identity and revision that the user saw. This prevents a late tap from answering a newer prompt. Prompts from stopped work remain readable but are no longer actionable.
References: mobile/…/MobileNativeChatView.tsx• L230-385 mobile/…/MobileNativeChatComposer.tsx• L1-80 mobile/…/use-mobile-native-chat-drafts.ts• L48-244 mobile/…/mobile-native-chat-draft-persistence.ts• L107-229 mobile/…/MobileNativeChatOfflineQueue.tsx• L1-120
Queued messages
Structured agent sessions can hold messages while the current turn runs. The mobile client shows host-owned cards between the transcript and composer. A user can send, steer, delete, edit, reorder, or copy a message into the composer. Cards distinguish waiting, paused, returned, failed, and attention-needed states.
Editing keeps the message visible until the host accepts its delete or edit path. The editor can retain supported images, files, and skills. If an edit cannot complete, its text remains in the composer and the original card stays visible. Queue pause and Resume act on the host queue rather than on a local copy.
The host queue remains the source of truth across devices. If a hand-off races with delivery, the card reports that the message was already sent rather than creating a second message. Returned and failed cards stay visible so the user can understand and retry the action.
References: mobile/…/use-mobile-structured-agent-session.ts• L229-247 mobile/…/MobileNativeChatQueuedMessages.tsx• L1-120 mobile/…/MobileQueuedMessageCardRow.tsx• L60-207 mobile/…/MobileQueuedMessageComposer.tsx• L20-140 mobile/…/mobile-queued-message-edit-lease.ts• L1-120
Structured session controls
Structured sessions expose host-supported controls for model choice, effort, permission mode, prompt cancellation, queued commands, Stop, background tasks, context usage, thread goals, usage limits, and rewind. The mobile client reads capability facts before it enables a control. Older hosts receive a safe fallback or a clear unavailable state instead of an unsupported request.
Stop requests name the running turn or the prompt revision that the user saw. On older hosts the client joins repeated Stop requests while the first one is in flight. Queue cards remain after Stop, and a later Resume is the action that continues the held queue.
An interrupted structured turn can expose Continue when the host and route support it. A usage-limit row can show host auto-continue state, offer account switching, let the user cancel a scheduled continuation, or send the standard Continue message. A thread goal uses host time for its running duration, so phone clock differences do not change the displayed goal age.
Rewind asks for confirmation, blocks while work or queued actions make the target unsafe, and returns the selected message to the composer. File changes on disk are kept. Background tasks remain visible as agents, shells, monitors, workflows, and tasks, with status marked unavailable when the live roster cannot be verified.
References: mobile/…/mobile-structured-agent-session-host-support.ts• L41-137 mobile/…/use-mobile-structured-agent-session.ts• L84-256 mobile/…/use-mobile-structured-agent-session.ts• L258-309 mobile/…/use-mobile-structured-agent-options.ts• L1-160 mobile/…/use-mobile-structured-agent-rewind.ts• L29-135
Terminal interaction
Terminal surface
The terminal surface is a live host terminal shown in a native WebView or in the mobile web page. Both hosts use the same contract for readiness, output, input, selection, resizing, and errors. The web surface mounts the same terminal document model and can replace a failed document without rebuilding the whole session route.
Each mounted terminal pane has its own connection, viewport, renderer, and cleanup boundary. A session may show one terminal or a split pair. The active pane receives input, while hidden panes stay mounted so changing the pair does not lose scrollback. In a split view, interaction is enabled only when the pane is visible, its route is focused, and the app is in the foreground.
References: mobile/…/MobileSessionActiveContent.tsx• L273-390 mobile/…/TerminalPaneView.tsx• L85-199 mobile/…/TerminalWebView.web.tsx• L26-145 mobile/…/TerminalWebView.tsx• L15-99
Terminal layouts
Terminal layout controls choose one terminal or two visible panes. Split mode can fit the available space, force two columns, or force two rows. The choice is local to the device and remains available across later session views.
The layout adapts to orientation and frame size. Keyboard lift reduces the visible pane area, and each pane keeps its own measured geometry. Split panes show a small focus heading so the user can identify and select the input pane. If a split pair loses one terminal, the remaining active terminal stays visible instead of leaving an empty pane.
References: mobile/…/terminal-stream-layout.ts• L4-47 mobile/…/TerminalPaneView.tsx• L110-169 mobile/…/MobileSessionActiveContent.tsx• L45-47 mobile/…/MobileSessionActiveContent.tsx• L275-309
Terminal output
When a terminal subscription starts, the host sends a scrollback snapshot before live output. The mobile client restores that snapshot into the terminal and then applies new data. This lets a reopened tab show the current prompt and recent work instead of only output produced after the phone arrived.
The terminal preserves the user's position in normal scrollback and keeps alternate-screen programs tied to the live cursor and repaint state. Query replies stay apart from replayed output, so restoring a snapshot does not send parser-generated responses back to the host program. A covered terminal can keep input ownership while its visible WebView is replaced by the chat surface.
Layout sequence values are separate from output sequence values. This lets a valid resize arrive after a larger scrollback sequence without being treated as stale terminal output.
References: mobile/…/use-mobile-session-terminal-subscription.ts• L115-228 mobile/…/use-mobile-session-terminal-subscription.ts• L248-299 mobile/…/terminal-stream-layout.ts• L4-32 mobile/…/mobile-terminal-query-reply.ts• L21-69
Terminal input
The mobile client supports buffered commands and live input. Buffered input lets the user compose a command and send it as one action. Live input sends the visible field directly to the active terminal for interactive programs. An accessory area adds terminal keys, arrows, paste, attachments, dictation, shortcuts, and repeatable keys.
Input is scoped to the active terminal and current connection. Unfinished platform text composition stays out of the PTY until it commits. Bytes that become uncertain during a connection or terminal change are dropped instead of replayed into a different shell. Ordered input is used when the route and host advertise it; otherwise the client uses the compatible input path.
The command dock keeps the live-input field and accessory controls aligned with the active surface. Its field disables sending when the current session cannot accept input. Dictation and image or file attachment actions remain tied to the current command or agent destination rather than an older route.
Quick commands provide reusable terminal or agent prompts when the host supports them. Malformed host command data does not erase a known command list.
References: mobile/…/MobileSessionCommandDock.tsx• L20-150 mobile/…/MobileTerminalInputActions.tsx• L1-160 mobile/…/mobile-session-terminal-operations.ts• L1-120 mobile/…/mobile-quick-command-operations.ts• L6-30 mobile/…/mobile-native-chat-send.ts• L117-165
Terminal gestures
Touch and mouse-aware programs use different input paths. Normal-buffer gestures select or scroll local terminal content. Alternate-screen or mouse-aware programs receive mouse reports only after the client has proved that their encoding is safe.
Taps resolve links and worktree file paths before they reach the terminal program. A file path opens a file surface. A link opens a choice of the host browser, the phone's system browser, or the clipboard. The host-browser option is absent when the worktree or host cannot stream it. Other taps fall back to terminal input and keyboard focus. A cancelled drag still sends a release when its press reached the program.
Pinch changes the local text scale and commits to a supported size when the gesture ends. Vertical movement scrolls terminal output. Horizontal movement pans only when the scaled terminal is wider than the visible frame. Selection mode stops normal touch scrolling until the selection ends.
References: mobile/…/surface-touch-gestures.ts• L72-305 mobile/…/selection-mode.ts• L10-36 mobile/…/mouse-input-encoding.ts• L58-186 mobile/…/MobileLinkActionSheet.tsx• L9-65 mobile/…/use-mobile-file-tap-handlers.ts• L26-184
Terminal display modes
Terminal display mode controls whether the host follows the phone's measured cell grid or keeps a desktop-oriented width. Phone mode measures the visible terminal frame and asks the host to fit its PTY to that grid. The client re-measures after layout, rotation, keyboard, tab changes, text-size changes, foreground return, and reconnect.
The client prefers an in-place resize and can start a fresh subscription when the host cannot update the current view. Missing dimensions hold the stream. Repeated mismatches stop after a bounded recovery budget and show a degraded state instead of retrying forever.
Terminal settings provide a local text scale and a host-specific period after which phone fitting can restore to desktop width. The default keeps the host at the phone's size, which avoids reflow in interactive CLI programs while the app is away. The setting is saved per host and can be restored manually from the desktop.
References: mobile/…/use-mobile-session-terminal-subscription.ts• L89-103 mobile/…/use-mobile-session-terminal-subscription.ts• L218-299 mobile/…/terminal-stream-layout.ts• L35-47 mobile/…/terminal-settings.tsx• L36-130 mobile/…/terminal-settings.tsx• L274-318
File and browser surfaces
File and Markdown surfaces
The session can open worktree files, Markdown, HTML, images, media, and diffs without leaving the selected worktree. Text surfaces support selection and syntax color. HTML and SVG have rendered and source views. Large or unknown content remains clearly bounded or readable as plain text when the host can provide it.
Markdown edits stay local until Save. Refresh and leaving a dirty draft require a discard choice. If the host renderer is unavailable, the phone can show disk content as a read-only fallback and marks stale desktop content so it is not mistaken for the saved document. File and diff views can keep durable review notes while the file surface changes.
References: mobile/…/MobileSessionFileReader.tsx• L40-187 mobile/…/MobileSessionFileReader.tsx• L189-335 mobile/…/MobileSessionActiveContent.tsx• L171-226 mobile/…/MobileSessionMarkdownReader.tsx• L42-164
Diff review
Diff views let the user inspect changed files, add line notes, mark review state, and send notes to an existing terminal or a new agent. The review queue can cover worktree, branch, and commit changes. Unchanged context folds to keep the mobile view readable, while opened, annotated, and threaded lines remain visible.
Notes belong to the worktree and retain the diff identity that produced them. GitHub threads appear on local lines only when the local branch matches the pull request head. Otherwise the phone reports that the threads are waiting for a matching revision instead of placing them on possibly wrong lines.
Review content remains useful during a short connection loss and reloads after the shell reconnects. Notes become sent only after the host accepts delivery. A late load cannot reopen a dismissed sheet or replace a newer review request.
References: mobile/…/MobileDiffReviewRouteScreen.tsx• L13-66 mobile/…/use-mobile-diff-review-controller.ts• L91-153 mobile/…/mobile-diff-review-loaders.ts• L106-243 mobile/…/mobile-diff-review-github.ts• L10-57
Browser tabs
Browser tabs show a host browser page as an interactive image stream inside the worktree session. The user can navigate, go back or forward, reload, click, scroll, use a secondary click, and enter a URL. Page identity and navigation state remain part of the host session tab.
The stream adapts to the mobile pane. Web mode keeps the host browser viewport. Mobile mode asks the host browser to use the measured phone area. The client decodes frames off screen and displays only the newest usable frame. A command with unknown delivery is not replayed.
Links in chat and terminal output can open a host browser tab only when the current worktree has a connected host and browser streaming capability. Otherwise the phone offers its system browser or copy action. Browser tab creation uses the same deferred outcome rules as other session-tab creation.
References: mobile/…/MobileBrowserPane.tsx• L65-218 mobile/…/MobileBrowserPaneView.tsx• L161-257 mobile/…/mobile-session-browser-operations.ts• L8-15 mobile/…/browser-frame-pacer.ts• L33-211 mobile/…/MobileLinkActionSheet.tsx• L9-65
Capability gates
The mobile client checks host capabilities before it offers browser streaming, agent history, quick commands, ordered terminal input, or structured session controls. If the host is too old, the session explains that an update is needed instead of opening a surface that cannot work.
On the web page, access to binary browser frames also depends on a grant for the current shell route. Native transport receives frames directly. A capability or route change clears old capability state so a previous host or path cannot authorize a new one. Structured controls use the same rule for queue edits, attachments, Continue, goals, rewind, usage-limit actions, and fork support.
References: mobile/…/use-mobile-session-tab-reconciliation.ts• L172-211 mobile/…/mobile-structured-agent-session-host-support.ts• L90-137 mobile/…/use-mobile-browser-stream.ts• L146-182 mobile/…/runtime-capability-probe.ts• L12-67 mobile/…/use-browser-binary-screencast-grant.web.test.tsx• L62-88
Mobile web shell
The mobile web shell provides the browser-hosted session page when the native app is not the active surface. It checks the host and route, opens a cached or downloaded page generation, and keeps a running page stable while an update downloads in the background.
The shell fences effects and page reports by host, route, flow, and document session. A failed renderer can remount within a bounded budget. A stale download, old page event, or retired document cannot replace the current session. Route grants and host status are judged against the document that is actually shown.
References: mobile/…/use-mobile-web-shell-session.ts• L39-64 mobile/…/use-mobile-web-shell-session.ts• L66-203 mobile/…/use-mobile-web-shell-session.ts• L234-319 mobile/…/mobile-web-shell-session-contract.ts• L58-207
Reconnect-aware state
Session snapshot reconciliation
Session tabs arrive through both a stream and list reads. The mobile client merges those sources into one view and accepts only current snapshots. Connection generations, stream barriers, and snapshot revisions prevent an old connection or delayed list response from replacing newer tab state.
Local selections, closes, dirty Markdown drafts, and active terminal surfaces remain pending until host data confirms them. Short-lived close markers stop a stale snapshot from flashing a closed tab back into view. A host-directed navigation intent is applied once and is kept separate from a local tab choice.
Chat draft ownership follows the same rule. The client retains drafts for live, selected, or phone-owned tabs and prunes them only after a trustworthy tab publication confirms the current set. A route change cannot make a draft from another host or worktree appear in the new session.
References: mobile/…/mobile-session-tab-read-operations.ts• L6-14 mobile/…/mobile-session-tab-write-operations.ts• L9-37 mobile/…/use-mobile-session-tab-reconciliation.ts• L60-170 mobile/…/active-session-tab.ts• L24-72 mobile/…/mobile-native-chat-draft-store.ts• L154-223
Stream health
The session tracks whether its tab stream is probing, live, or degraded. Missing terminals, stream errors, browser focus waits, and reminted chat handles can start bounded reconciliation. A slower terminal inventory read confirms absence before it removes a terminal that may only be missing from a partial response.
The native app owns a retry action when it owns reconnect. The mobile web shell owns its connection and therefore shows the condition without duplicating the retry control. Recovery pauses when the app is backgrounded, the route loses focus, or the connection is unavailable. A changed active tab cancels recovery for the old surface.
Structured chat drops its connection-scoped host hold when transport is lost, but keeps the cached transcript. After reconnect it reacquires the hold and reads current journal state. Child work and status are marked unverified when the live feed cannot confirm them.
References: mobile/…/use-mobile-session-presentation.ts• L52-102 mobile/…/MobileSessionHeader.tsx• L30-108 mobile/…/use-mobile-session-tab-reconciliation.ts• L91-228 mobile/…/use-mobile-terminal-inventory-recovery.ts• L123-229 mobile/…/use-mobile-native-chat-session-lane.ts• L63-89
Transcript recovery
Legacy transcripts use a recent window for fast display and load older history on demand. Reconnect replay merges with retained history when its range is contiguous. A replacement window is accepted only when its session identity and authority make it safe. The reader keeps its visible row anchored when older content is inserted above it.
Structured sessions use journal pages, a bounded cache, and a connection-scoped hold. A reconnect reacquires the hold before it follows the stream. Drafts, optimistic messages, prompt responses, queued cards, option state, background-task rows, and structured controls use the same host, worktree, tab, and agent-session scope.
The chat keeps a pending local echo until authoritative history proves that the message landed. Image previews can outlive the optimistic row and are then attached to the matching authoritative message. A response that is still unknown stays visible as an unconfirmed outcome rather than being sent again automatically. Stored transcript rows restore the reading view, but live journal state still decides whether an action is safe.
References: mobile/…/use-mobile-native-chat-session.ts• L121-256 mobile/…/use-mobile-native-chat-session.ts• L258-345 mobile/…/mobile-native-chat-transcript-store.ts• L114-176 mobile/…/use-mobile-native-chat-drafts.ts• L223-289 mobile/…/use-mobile-structured-agent-session.ts• L81-145
Dictation state
Dictation belongs to one host, worktree, active tab, and input destination. The session keeps recording through a reconnect and returns the words to the terminal or chat surface where recording began. A destination that is no longer valid does not silently place speech in a newly selected terminal.
The same state supports tap-to-toggle and press-and-hold input. If delivery fails, the client reports the failure and copies the text so the user can recover it. Navigation can bring the owning session and pane back to the front without changing another session's route.
References: mobile/…/use-mobile-session-dictation.ts• L36-143 mobile/…/use-mobile-session-dictation.ts• L204-254 mobile/…/use-mobile-session-native-chat-dictation.ts• L12-104 mobile/…/mobile-dictation-session-state.ts• L1-160
Delivery outcomes
Host actions distinguish accepted, rejected, queued, and unknown outcomes. A lost acknowledgement does not prove that an action failed or succeeded. The mobile client waits for transcript, tab, journal, or queue evidence before it reports delivery.
Operation identities, runtime fences, prompt revisions, session keys, and input-surface identity fence late replies. A later deliberate send receives a new identity rather than replaying an earlier unknown action. This keeps recovery safe without hiding a message that the host may already have accepted.
This diagram shows the high-level return from a transport cut or app-state change.
flowchart TD
Live[Live session] --> Cut[Transport cut or app background]
Cut --> Reconnect[Reconnect or path change]
Reconnect --> Reconcile[Reconcile tabs, terminals, chat, and web page]
Reconcile --> Restore[Restore snapshots, drafts, queues, transcript windows, and grants]
Restore --> Live
Reconnect --> Degraded[Keep local state and show degraded or retry state]
References: mobile/…/mobile-native-chat-send.ts• L40-79 mobile/…/mobile-native-chat-send.ts• L117-159 mobile/…/use-mobile-session-tab-reconciliation.ts• L148-211 mobile/…/use-mobile-session-terminal-subscription.ts• L120-177 mobile/…/use-mobile-web-shell-session.ts• L118-203
Change checklist
When these files or sections are changed, remember to consider these:
- Keep host, execution-host, worktree, tab, pane, and agent-session identity aligned across routes, catalog rows, snapshots, terminal state, chat drafts, stored transcripts, and review notes.
- Keep session tab types aligned with surface rendering, split-pane selection, terminal records, pending selection, launch matching, close behavior, and host tab publication.
- Keep capability checks aligned with the controls they enable, especially browser frames, history, quick commands, ordered terminal input, queue edits, attachments, Continue, goals, rewind, usage-limit actions, and forks.
- Keep accepted, rejected, queued, and unknown outcomes aligned with operation identity, runtime fences, transcript evidence, tab evidence, and queue evidence.
- Keep the terminal-backed transcript lane and structured journal lane aligned with their shared chat view, stored transcript shape, prompt state, queue state, draft state, fork links, and reconnect rules.
- Keep terminal readiness, scrollback order, viewport dimensions, display mode, pane layout, input scope, query replies, focus gating, and cleanup aligned between native and web hosts.
- Keep display layout sequence checks separate from output sequence checks when terminal stream ordering changes.
- Keep mouse-mode proof aligned with touch selection, alternate-screen input, gesture rate limits, safe fallback behavior, and pointer release.
- Keep dictation destination identity aligned with chat drafts, terminal command drafts, live input, previews, reconnect, and route changes.
- Keep file and Markdown state aligned with dirty drafts, disk fallback, truncation, read-only reasons, save actions, syntax views, and stale desktop content.
- Keep diff identity aligned with review notes, changed-since-review state, GitHub thread placement, note delivery, agent launch, and late sheet loads.
- Keep browser page identity aligned with route grants, frame generation, viewport mode, link actions, and delivery-unknown commands.
- Keep snapshot generations and reconciliation barriers aligned across stream reads, list reads, inventory recovery, reconnect, draft pruning, stored transcript reads, and host-directed navigation.
- Keep mobile web shell epochs, cached generations, document session IDs, route grants, and renderer remount budgets aligned so an old page cannot take ownership of a new session.
- Keep per-server catalog snapshots aligned with server removal, failed reads, delta reads, lineage resolution, and worktree row identity.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A delayed session snapshot follows a newer close or tab selection | An old tab can reappear or take focus | Snapshot markers, barriers, revisions, and close markers reject stale state |
| A host or server catalog read fails | Healthy worktrees can look empty | Per-host results retain their error state and server snapshots keep the last confirmed rows |
| A terminal split pair loses one handle | The layout can show an empty or wrong pane | Pane resolution keeps the active handle and only renders a second pane when it survives |
| An agent launch, history resume, browser-tab create, or structured-chat create reply is lost | A second action can create duplicate work | Stable operation identity and published-tab or journal evidence resolve the unknown result |
| A structured fork is requested from an unsupported or still-running response | The source chat can be changed or a sibling chat can be opened in the wrong place | Fork offers are derived from host capability, turn state, and the selected response; creation uses the source session and stable launch identity |
| A history session targets another host or runtime-owned workspace | Resume can start in the wrong execution environment | Resume target resolution requires a compatible local or SSH worktree |
| A prompt changes before its response arrives | A late answer can affect a newer prompt | Responses carry the prompt item and expected revision |
| A queued message races with host delivery or edit deletion | The user can send a message twice or lose edited text | Host queue state, edit leases, pending cards, and copy-before-delete behavior distinguish each outcome |
| A queue edit includes a command or an unsupported attachment | The host can reject the edit or save content with the wrong meaning | The editor checks command rules and host capability before it serializes text, files, images, or skills |
| A Stop request names an old turn or an unknown operation | Current work can continue while the phone reports a misleading result | Runtime fences, turn identity, prompt revision, and legacy Stop joining fence the request |
| A usage-limit or interrupted-turn action lands after the chat advances | Continue or cancel can affect a later turn | The action names the cut's turn item and the host rechecks current state |
| A terminal stream uses output sequence as its layout sequence | A valid resize can be dropped as stale | Layout sequence marks apply only to layout events, not scrollback byte sequence |
| Terminal output arrives before its surface is ready | Scrollback can be lost or written to the wrong terminal | Terminal readiness and per-handle subscription generations gate replay |
| A hidden or background terminal keeps receiving interaction | Input can go to a pane the user cannot see | Visibility, route focus, and app foreground state gate terminal interaction |
| Input survives a connection, pane, or terminal change | Old bytes can run in a different shell | Current connection, handle, active surface, and input-scope checks drop uncertain input |
| Mouse tracking exists without a proven encoding | Touch bytes can become literal program input | The client uses local selection or safe fallback input until encoding is known |
| Viewport dimensions never become usable | The PTY can keep the wrong grid or retry forever | Missing dimensions hold the stream and bounded fitting ends in a visible degraded state |
| Markdown refresh or leaving occurs with a dirty draft | Local edits can be lost or confused with disk content | Save, discard, and read-only fallback states remain explicit |
| A browser frame, link action, or command has unknown delivery | The page can show stale content or repeat a click | Frame generations fence stale frames and unknown commands are not replayed; link actions offer safe alternatives |
| Local diff lines do not match the GitHub pull request head | Review threads can appear on the wrong lines | Thread placement waits for a matching head and reports hidden threads until then |
| A saved chat transcript is treated as live journal state | The phone can offer a prompt or action that no longer exists | Stored rows are shown for continuity, while a fresh host read confirms actionability |
| A saved chat draft is loaded after its tab was closed or replaced | Text from an old tab can appear in a new session | Workspace-scoped persistence tracks retained and closed tabs before restoring drafts |
| A stale mobile web shell effect reports ready after a route or host change | An old page generation can replace the current session | Host, route, epoch, flow, and document-session fences reject retired effects and reports |
Key files
| File | Why to read it |
|---|---|
| mobile/…/MobileSessionActiveContent.tsx | Shows how the active tab becomes a terminal, split terminal panes, chat, browser, file, or Markdown surface. |
| mobile/…/use-mobile-session-controller.ts | Shows how startup, tab state, terminal runtime, chat, documents, review, dictation, and presentation form one session controller. |
| mobile/…/mobile-session-tabs.ts | Defines the host-published tab types and the phone-only identity fields. |
| mobile/…/active-session-tab.ts | Explains how host snapshots, local selection, pending tabs, and navigation intent choose the active surface. |
| mobile/…/use-mobile-session-tab-reconciliation.ts | Explains snapshot recovery, capability probes, terminal inventory recovery, and connection loss handling. |
| mobile/…/MobileSessionHeader.tsx | Shows responsive header actions, source control access, connection retry, and tab placement. |
| mobile/…/use-mobile-native-chat-session-lane.ts | Shows the shared boundary between terminal-backed and structured chats. |
| mobile/…/MobileNativeChatView.tsx | Shows transcript rendering, paging, tail following, prompts, offline sends, composer input, and Stop state. |
| mobile/…/use-mobile-native-chat-session.ts | Shows transcript identity, snapshot merging, retained history, stored rows, and older-page loading. |
| mobile/…/mobile-native-chat-transcript-store.ts | Shows the device copy of terminal and structured transcript state and its scope. |
| mobile/…/mobile-native-chat-projection.ts | Shows how message history becomes stable mobile rows and folded tool or image units. |
| mobile/…/use-mobile-native-chat-drafts.ts | Shows draft scope, optimistic sends, pending echoes, image previews, and unknown delivery. |
| mobile/…/use-mobile-structured-agent-session.ts | Shows journal projection, prompts, queue controls, options, Stop, background tasks, Continue, goals, usage limits, and rewind. |
| mobile/…/mobile-structured-agent-session-host-support.ts | Shows the host capability boundary for structured chat features. |
| mobile/…/TerminalPaneView.tsx | Shows split-pane focus, hidden-pane preservation, and app or route interaction gating. |
| mobile/…/use-mobile-session-terminal-subscription.ts | Shows terminal snapshot restoration, live output, viewport fitting, layout ordering, resize, and recovery boundaries. |
| mobile/…/terminal-stream-layout.ts | Shows the distinction between layout sequence and terminal output sequence. |
| mobile/…/MobileSessionCommandDock.tsx | Shows the live terminal input field, accessory key controls, attachments, and dictation. |
| mobile/…/surface-touch-gestures.ts | Shows terminal scrolling, panning, pinch scaling, momentum, and mouse-aware touch routing. |
| mobile/…/TerminalWebView.web.tsx | Shows how the web terminal mounts, reloads, and reports document errors. |
| mobile/…/terminal-settings.tsx | Shows device text size and per-host phone-fit restore settings. |
| mobile/…/MobileSessionFileReader.tsx | Shows worktree file, media, HTML, SVG, source, and diff presentation. |
| mobile/…/MobileSessionMarkdownReader.tsx | Shows Markdown read, edit, save, discard, and fallback behavior. |
| mobile/…/MobileBrowserPane.tsx | Shows the browser tab stream and host page controls. |
| mobile/…/mobile-session-browser-operations.ts | Shows the browser-tab creation contract and delivery boundary. |
| mobile/…/use-mobile-web-shell-session.ts | Shows cached web-page generations, update flow, reconnect state, and stale-effect fencing. |
| mobile/…/mobile-web-shell-session-contract.ts | Defines web-shell states, route grants, page identity, retry budgets, and flow events. |
| mobile/…/MobileDiffReviewRouteScreen.tsx | Shows diff route scope, reconnect handling, and hand-off back to the session. |
| mobile/…/mobile-pr-sidebar-state.ts | Shows pull request identity, check isolation, stale-link handling, and partial review failures. |
| mobile/…/server-workspaces.ts | Shows per-server catalog reads, snapshot scope, and preservation of healthy rows during a failed read. |
| mobile/…/workspace-list-sections.ts | Shows filtering, sorting, pinning, grouping, project sections, and worktree activity. |
| mobile/…/mobile-workspace-lineage.ts | Shows same-host and cross-server worktree lineage and instance guards. |