fix(mobile): terminal portrait first-prompt visible via lazy-create + resize debounce

Frontend lazy-create (P1): the Terminal component mounts on a local
_pending entry, calls fit.fit() to measure the container, then invokes
pty.create with the exact cols/rows. The shell spawns at its final grid
size so no SIGWINCH is ever needed and mksh's sigwinch_redisplay() pad
never fires — which was overwriting the first prompt in portrait.

Backend resize debounce (P3): applyResize() centralizes the resize path
and (a) no-ops identical-to-spawn dims, (b) holds the first resize for
up to 800ms if no shell output has been seen yet, flushing on first
onData. Belt-and-suspenders against late viewport settling.

Schema: CreateInput accepts an optional client-provided id (pty_*), so
the frontend can keep the id stable across the mount → create → WS flow.
SDK v2 regenerated to surface id/cols/rows in PtyCreateData.body.

Diagnostic flags kept for this checkpoint — REVERT BEFORE SHIPPING:
- MainActivity: WebView.setWebContentsDebuggingEnabled(true)
- build.gradle.kts release: isDebuggable = true

Validated on Mi 10 Pro (b7163823) in portrait. Bugs #3 (virtual keyboard
single vs double tap) and anomalyco#5 (touch scroll) remain open.

Author: Rwanbt

packages/app/src/components/terminal.tsx

@@ -13,7 +13,7 @@ import { usePlatform } from "@/context/platform"
 import { useSDK } from "@/context/sdk"
 import { useServer } from "@/context/server"
 import { monoFontFamily, useSettings } from "@/context/settings"
-import type { LocalPTY } from "@/context/terminal"
+import { useTerminal, type LocalPTY } from "@/context/terminal"
 import { terminalAttr, terminalProbe } from "@/testing/terminal"
 import { disposeIfDisposable, getHoveredLinkText, setOptionIfSupported } from "@/utils/runtime-adapters"
 import { terminalWriter } from "@/utils/terminal-writer"
@@ -232,6 +232,7 @@ const persistTerminal = (input: {
 export const Terminal = (props: TerminalProps) => {
   const platform = usePlatform()
   const sdk = useSDK()
+  const terminalCtx = useTerminal()
   const settings = useSettings()
   const theme = useTheme()
   const language = useLanguage()
@@ -642,6 +643,30 @@ export const Terminal = (props: TerminalProps) => {
         startResize()
       } else {
         fit.fit()
+        if (local.pty._pending) {
+          // Lazy-create: backend has no session for this id yet. Call
+          // pty.create with the *exact* grid dims measured above. The shell
+          // spawns at final size so no SIGWINCH is ever emitted and mksh's
+          // readline pad-erase redisplay never fires — fixes the portrait
+          // first-prompt bug at its root.
+          try {
+            await client.pty.create({
+              id,
+              title: local.pty.title,
+              cols: t.cols,
+              rows: t.rows,
+            })
+            // Pre-seed lastSize so the immediate scheduleSize below (and the
+            // ones from WS open / ResizeObserver if dims are still identical)
+            // are no-ops and never trigger a PUT /pty/:id.
+            lastSize = { cols: t.cols, rows: t.rows }
+            terminalCtx.finalizePending(id)
+          } catch (err) {
+            addDebug(`pty.create failed: ${err instanceof Error ? err.message : String(err)}`)
+            terminalCtx.failPending(id)
+            throw err
+          }
+        }
         scheduleSize(t.cols, t.rows)
         if (restore) {
           await write(restore)

packages/app/src/context/terminal.tsx

@@ -17,6 +17,26 @@ export type LocalPTY = {
   buffer?: string
   scrollY?: number
   cursor?: number
+  // Lazy-create flag. True between the moment the user opens a terminal tab
+  // and the moment the Terminal component has mounted, measured its
+  // container, and called sdk.client.pty.create(). During this window no
+  // backend session exists yet — the shell is spawned at the exact final
+  // grid dimensions so no SIGWINCH/readline-pad is ever needed. The sweep
+  // and persist/migrate paths must skip pending entries.
+  _pending?: boolean
+}
+
+// Client-side PTY id generator. Must produce a string matching the server's
+// `pty_...` prefix validation (see Identifier.schema in opencode/src/id/id.ts).
+// Format mimics ascending ids (timestamp prefix + random suffix) so the
+// server's ordering assumptions still hold when the id reaches the backend.
+function generateClientPtyId(): string {
+  const ts = Date.now().toString(36)
+  const rand =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? (crypto as { randomUUID: () => string }).randomUUID().replace(/-/g, "")
+      : Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2)
+  return `pty_${ts}${rand}`.slice(0, 30)
 }
 
 const WORKSPACE_KEY = "__workspace__"
@@ -74,6 +94,10 @@ function pty(value: unknown): LocalPTY | undefined {
   const id = text(value.id)
   if (!id) return
 
+  // Drop entries that were still pending at persist time — they have no
+  // backend session to reconnect to, so keeping them only confuses sweep.
+  if (value._pending === true) return
+
   const title = text(value.title) ?? ""
   const number = num(value.titleNumber)
   const rows = num(value.rows)
@@ -232,6 +256,26 @@ function createWorkspaceTerminalSession(sdk: ReturnType<typeof useSDK>, dir: str
       setSweepDone(true)
       return
     }
+    // Drop any persisted pending entries — they had no backend session when
+    // persistence ran (the Terminal component never completed the lazy
+    // pty.create call), so nothing to reconnect to. Also saves us from
+    // querying the server with ids it has never seen.
+    const pendingIds = new Set(store.all.filter((pty) => pty._pending).map((pty) => pty.id))
+    if (pendingIds.size > 0) {
+      batch(() => {
+        setStore(
+          "all",
+          produce((draft) => {
+            for (let i = draft.length - 1; i >= 0; i--) {
+              if (pendingIds.has(draft[i].id)) draft.splice(i, 1)
+            }
+          }),
+        )
+        if (store.active && pendingIds.has(store.active)) {
+          setStore("active", store.all[0]?.id)
+        }
+      })
+    }
     const ids = store.all.map((pty) => pty.id)
     if (ids.length === 0) {
       setSweepDone(true)
@@ -346,29 +390,44 @@ function createWorkspaceTerminalSession(sdk: ReturnType<typeof useSDK>, dir: str
     },
     new() {
       const nextNumber = pickNextTerminalNumber()
-      const estimated = estimateTerminalSize()
-
-      sdk.client.pty
-        .create({ title: defaultTitle(nextNumber), cols: estimated.cols, rows: estimated.rows })
-        .then((pty: { data?: { id?: string; title?: string } }) => {
-          const id = pty.data?.id
-          if (!id) return
-          const newTerminal = {
-            id,
-            title: pty.data?.title ?? defaultTitle(nextNumber),
-            titleNumber: nextNumber,
-          }
-          setStore("all", store.all.length, newTerminal)
-          setStore("active", id)
-        })
-        .catch((error: unknown) => {
-          console.error("Failed to create terminal", error)
-          showToast({
-            variant: "error",
-            title: "Terminal",
-            description: error instanceof Error ? error.message : "Failed to create terminal session",
-          })
-        })
+      // Lazy-create: no backend call here. The Terminal component mounts on
+      // this _pending entry, measures its container with fit.fit(), and calls
+      // sdk.client.pty.create() with the *exact* grid dims. The shell spawns
+      // at its final size so no initial resize/SIGWINCH is needed.
+      const id = generateClientPtyId()
+      const pending: LocalPTY = {
+        id,
+        title: defaultTitle(nextNumber),
+        titleNumber: nextNumber,
+        _pending: true,
+      }
+      batch(() => {
+        setStore("all", store.all.length, pending)
+        setStore("active", id)
+      })
+    },
+    finalizePending(id: string) {
+      const index = store.all.findIndex((x) => x.id === id)
+      if (index === -1) return
+      if (!store.all[index]?._pending) return
+      setStore("all", index, (pty) => ({ ...pty, _pending: undefined }))
+    },
+    failPending(id: string) {
+      const index = store.all.findIndex((x) => x.id === id)
+      if (index === -1) return
+      if (!store.all[index]?._pending) return
+      batch(() => {
+        if (store.active === id) {
+          const fallback = index > 0 ? store.all[index - 1]?.id : store.all[1]?.id
+          setStore("active", fallback)
+        }
+        setStore(
+          "all",
+          produce((draft) => {
+            draft.splice(index, 1)
+          }),
+        )
+      })
     },
     update(pty: Partial<LocalPTY> & { id: string }) {
       update(sdk.client, pty)
@@ -524,6 +583,8 @@ export const { use: useTerminal, provider: TerminalProvider } = createSimpleCont
       all: () => workspace().all(),
       active: () => workspace().active(),
       new: () => workspace().new(),
+      finalizePending: (id: string) => workspace().finalizePending(id),
+      failPending: (id: string) => workspace().failPending(id),
       update: (pty: Partial<LocalPTY> & { id: string }) => workspace().update(pty),
       trim: (id: string) => workspace().trim(id),
       trimAll: () => workspace().trimAll(),

packages/mobile/src-tauri/assets/runtime/opencode-cli.js

@@ -53,7 +53,12 @@ android {
             }
         }
         getByName("release") {
-            isDebuggable = false
+            // Diagnostic-only: isDebuggable=true exposes the WebView to
+            // chrome://inspect (see MainActivity.setWebContentsDebuggingEnabled).
+            // Revert to false before shipping. Required to investigate the
+            // portrait first-prompt bug — the artefact reproduces only on
+            // release builds (minified/shrunk asset paths differ).
+            isDebuggable = true
             isJniDebuggable = false
             isMinifyEnabled = true
             isShrinkResources = true

packages/mobile/src-tauri/gen/android/app/build.gradle.kts

@@ -9,6 +9,7 @@ import android.os.Bundle
 import android.os.Environment
 import android.provider.Settings
 import android.view.WindowManager
+import android.webkit.WebView
 import androidx.activity.enableEdgeToEdge
 import androidx.core.app.ActivityCompat
 import androidx.core.content.ContextCompat
@@ -19,6 +20,13 @@ class MainActivity : TauriActivity() {
     enableEdgeToEdge()
     super.onCreate(savedInstanceState)
 
+    // Diagnostic-only: expose the WebView to `chrome://inspect` on the host
+    // PC so we can live-inspect DOM / console / WebSocket frames. Required to
+    // investigate the portrait first-prompt bug (see plan doc). Remove before
+    // shipping to end users — this is not a debug-only build guard because
+    // release builds are where the bug reproduces.
+    WebView.setWebContentsDebuggingEnabled(true)
+
     // Start LlamaService (Foreground Service) FIRST so it's alive before any
     // llama-server spawn. LlamaService keeps the whole process tree at adj=0
     // (foreground), exempt from Android PhantomProcessKiller and MIUI

packages/mobile/src-tauri/gen/android/app/src/main/assets/runtime/opencode-cli.js

@@ -33,8 +33,27 @@ export namespace Pty {
     bufferCursor: number
     cursor: number
     subscribers: Map<unknown, Socket>
+    // Mobile portrait first-prompt fix: track the dims the shell was spawned
+    // with so we can no-op identical resize requests (the frontend's initial
+    // fit.fit() produces the same numbers as estimateTerminalSize() on matching
+    // viewports), and we record the spawn timestamp so we can delay the first
+    // SIGWINCH until after mksh has emitted its PS1 and entered its readline
+    // loop. Sending SIGWINCH during that window triggers sigwinch_redisplay()
+    // which pads the line with spaces and overwrites the prompt.
+    spawnedAt: number
+    spawnCols: number
+    spawnRows: number
+    firstOutputAt: number | undefined
+    pendingResize: { cols: number; rows: number; timer: ReturnType<typeof setTimeout> } | undefined
   }
 
+  // Hold the first post-spawn resize for this long if it arrives before any
+  // shell output — gives mksh time to source rc files, emit PS1 and initialize
+  // readline. Measured locally: PS1 arrives within ~120ms on cold boot; 800ms
+  // covers worst-case .profile sourcing. If output is seen earlier, the queued
+  // resize is flushed immediately.
+  const SPAWN_SIGWINCH_HOLD_MS = 800
+
   type State = {
     dir: string
     sessions: Map<PtyID, Active>
@@ -85,6 +104,14 @@ export namespace Pty {
     cwd: z.string().optional(),
     title: z.string().optional(),
     env: z.record(z.string(), z.string()).optional(),
+    // Optional client-provided session id. Used by the mobile frontend's
+    // lazy-create flow: the Terminal component mounts first, measures its
+    // container, calls fit() to get the *exact* grid size, and only then
+    // calls pty.create with that id + the measured dims. The shell is then
+    // born at the final size so no SIGWINCH is ever needed and readline's
+    // pad-erase redisplay never fires — fixing the portrait first-prompt
+    // bug at its root. When omitted, the server generates one as before.
+    id: z.string().startsWith("pty_").optional(),
     // Initial PTY dimensions. When omitted the platform default (80x24) is
     // used, which on mobile webviews causes the first shell prompt to be
     // dropped: the shell writes its prompt at 80x24, the frontend fit()s
@@ -140,6 +167,10 @@ export namespace Pty {
       const bus = yield* Bus.Service
       const plugin = yield* Plugin.Service
       function teardown(session: Active) {
+        if (session.pendingResize) {
+          clearTimeout(session.pendingResize.timer)
+          session.pendingResize = undefined
+        }
         try {
           session.process.kill()
         } catch {}
@@ -193,7 +224,12 @@ export namespace Pty {
 
       const create = Effect.fn("Pty.create")(function* (input: CreateInput) {
         const s = yield* InstanceState.get(state)
-        const id = PtyID.ascending()
+        // Use the client-provided id if present (lazy-create flow), else mint
+        // a fresh ascending id. PtyID.ascending(given) validates the prefix.
+        if (input.id && s.sessions.has(input.id as PtyID)) {
+          return s.sessions.get(input.id as PtyID)!.info
+        }
+        const id = input.id ? PtyID.ascending(input.id) : PtyID.ascending()
         const command = input.command || Shell.preferred()
         const args = input.args || []
         if (Shell.login(command)) {
@@ -260,11 +296,35 @@ export namespace Pty {
           bufferCursor: 0,
           cursor: 0,
           subscribers: new Map(),
+          spawnedAt: Date.now(),
+          spawnCols: input.cols ?? 80,
+          spawnRows: input.rows ?? 24,
+          firstOutputAt: undefined,
+          pendingResize: undefined,
         }
         s.sessions.set(id, session)
         proc.onData(
           Instance.bind((chunk) => {
             session.cursor += chunk.length
+            if (session.firstOutputAt === undefined) {
+              session.firstOutputAt = Date.now()
+              // Flush any resize that was held while we waited for the shell
+              // to emit its prompt. Deferring until after output reaches
+              // readline means SIGWINCH lands in a state where mksh only
+              // updates its internal COLUMNS without repainting (no pad).
+              const pending = session.pendingResize
+              if (pending) {
+                clearTimeout(pending.timer)
+                session.pendingResize = undefined
+                try {
+                  session.process.resize(pending.cols, pending.rows)
+                  session.spawnCols = pending.cols
+                  session.spawnRows = pending.rows
+                } catch (err) {
+                  log.info("deferred resize failed", { id, err: String(err) })
+                }
+              }
+            }
 
             for (const [key, ws] of session.subscribers.entries()) {
               if (ws.readyState !== 1) {
@@ -310,17 +370,61 @@ export namespace Pty {
           session.info.title = input.title
         }
         if (input.size) {
-          session.process.resize(input.size.cols, input.size.rows)
+          applyResize(session, input.size.cols, input.size.rows)
         }
         yield* bus.publish(Event.Updated, { info: session.info })
         return session.info
       })
 
+      // Mobile portrait first-prompt guard. Three cases:
+      //  1. Identical to spawn dims — skip ioctl+SIGWINCH entirely. No kernel
+      //     state change needed, no signal to trigger readline pad.
+      //  2. Shell hasn't emitted output yet and we're inside the hold window —
+      //     queue the resize; it is flushed either by the first onData callback
+      //     (see create handler) or by a fallback timer at hold-deadline.
+      //  3. Anything else — resize immediately (genuine mid-session resize).
+      function applyResize(session: Active, cols: number, rows: number) {
+        if (cols === session.spawnCols && rows === session.spawnRows) {
+          if (session.pendingResize) {
+            clearTimeout(session.pendingResize.timer)
+            session.pendingResize = undefined
+          }
+          return
+        }
+        const sinceSpawn = Date.now() - session.spawnedAt
+        if (session.firstOutputAt === undefined && sinceSpawn < SPAWN_SIGWINCH_HOLD_MS) {
+          if (session.pendingResize) {
+            clearTimeout(session.pendingResize.timer)
+          }
+          const timer = setTimeout(() => {
+            const pending = session.pendingResize
+            if (!pending) return
+            session.pendingResize = undefined
+            try {
+              session.process.resize(pending.cols, pending.rows)
+              session.spawnCols = pending.cols
+              session.spawnRows = pending.rows
+            } catch (err) {
+              log.info("held resize fallback failed", { err: String(err) })
+            }
+          }, Math.max(0, SPAWN_SIGWINCH_HOLD_MS - sinceSpawn))
+          session.pendingResize = { cols, rows, timer }
+          return
+        }
+        try {
+          session.process.resize(cols, rows)
+          session.spawnCols = cols
+          session.spawnRows = rows
+        } catch (err) {
+          log.info("resize failed", { err: String(err) })
+        }
+      }
+
       const resize = Effect.fn("Pty.resize")(function* (id: PtyID, cols: number, rows: number) {
         const s = yield* InstanceState.get(state)
         const session = s.sessions.get(id)
         if (session && session.info.status === "running") {
-          session.process.resize(cols, rows)
+          applyResize(session, cols, rows)
         }
       })