@mobius-os/mobius 0.2.2

package/README.md

@@ -0,0 +1,174 @@
+# Mobius
+
+A terminal client for [Mobius](../..), written in Node + TypeScript +
+[Ink](https://github.com/vadimdemes/ink) (React for CLIs). It reuses the web
+frontend's TypeScript domain types and jsonl entry shapes verbatim, and drives
+the same backend HTTP + SSE API the web UI uses.
+
+```
+mobius/tui/
+  src/
+    main.tsx              entry — Ink render, exitOnCtrlC disabled
+    App.tsx               route machine: login → prep → chat (+ resume)
+    config.ts             ~/.mobius/{login,projects,dir2project,dir2project_preference}.json
+    api.ts                MobiusClient — all HTTP endpoints (bearer auth)
+    sse.ts                SseConnection — streaming fetch SSE frame parser
+    markdown.ts           terminal markdown (marked lexer + cli-highlight + chalk)
+    types.ts              domain + jsonl entry types (copied from frontend)
+    lib/entry-view.ts     jsonl entry → renderable view (copied classify fns)
+    hooks/useChat.ts      one session: lazy create + SSE + send
+    components/
+      primitives.tsx      TextInput / Select (single+multi) / Spinner
+      Login.tsx           server + username + optional password
+      PrepScreen.tsx      project picker + preference wizard (issue→model→language→skill→memory)
+      Chat.tsx            viewport-aware transcript + welcome card + composer/status
+      ResumePicker.tsx    /resume — 32 most-recent project sessions
+  tests/
+    integration.test.ts   real backend end-to-end (your server)
+    ui.test.tsx           ink-testing-library + mocked fetch/SSE
+  bin/mobius-tui.js       launcher
+```
+
+## Run
+
+```bash
+cd mobius/tui
+npm install --include=dev      # NODE_ENV=production prunes devDeps → must pass --include=dev
+npm start --silent             # suppress npm's script banner
+# or (cleanest): ./bin/mobius-tui.js
+```
+
+On first launch there is no `~/.mobius/login.json`, so the login screen appears.
+Enter your Mobius server URL and username (most servers are passwordless).
+On success the token is saved and the next launch auto-logs in
+(validated via `/api/auth/me`; re-login on expiry).
+
+After a successful login the TUI also starts its local AIMUX reverse connection
+in the background. The first run creates `~/.mobius/aimux-venv` and installs
+the `aimux` Python package, then runs:
+
+```text
+aimux reverse connect <server>/aimux_bridge --identifier tui-<hostname> --token <jwt> --replace
+```
+
+Python 3.10+ is discovered from `MOBIUS_TUI_PYTHON`, `python3`/`python` (or
+Windows `py`). If none is available and `uv` is installed, the TUI runs
+`uv python install 3.11` for a user-local interpreter. Set
+`MOBIUS_TUI_DISABLE_AIMUX=1` to opt out, for example on a machine that should
+only use the web API. A failed child is retried automatically with exponential
+backoff; AIMUX installation or connection failures do not prevent the chat
+client from opening. Python discovery, virtual-environment creation, pip
+download progress, bridge heartbeat state, and reconnect attempts remain
+visible in the TUI status area while the rest of the client stays usable.
+
+Once started, a background heartbeat checks
+`/aimux_bridge/api/remotes/<identifier>/connection` every five seconds with the
+current Mobius JWT. Three consecutive failed checks terminate the stale AIMUX
+child and reconnect with 1/2/4/8/15-second capped exponential backoff. A
+successful bridge heartbeat resets the backoff and changes the status indicator
+to green.
+
+## Flow
+
+1. **Login** — server / username / password → `POST /api/auth/login` → save
+   `~/.mobius/login.json`.
+2. **Prep**
+   - read `cwd`; look up `dir2project.json[cwd]`.
+   - if unbound → pick an existing project or create one (bound to `cwd`).
+   - preference wizard, stepped only through what's missing:
+     **Issue (task)** → **model** → **language** → **skills** → **memories**.
+     Preferences are stored *inside* the selected issue, so switching issues
+     restores that issue's choices.
+3. **Chat**: startup identity/context card, viewport-aware
+   transcript, composer, and persistent model/project/task status at the bottom.
+   The final line always shows the current web issue/session URL as an OSC 8
+   hyperlink, so supported terminals can open the matching Mobius page directly
+   (the URL remains visible and copyable everywhere).
+   - The first submitted message lazily creates a session
+     (`POST /api/issues/:iid/sessions`) with the saved preferences, opens the
+     SSE stream (`GET /api/sessions/:id/events?token=`), and posts the message.
+     The session carries `pc_client_metadata` with `is_tui: true`, the local
+     AIMUX identifier and current directory; TUI sessions always default to PC mode
+     and always include the `mobius-aimux` Skill.
+   - `jsonl_entry` events append to the transcript as they arrive; the view keeps
+     recent output inside the current terminal height instead of mixing permanent
+     `<Static>` rows with dynamic UI.
+   - The `typing` event drives the working indicator. Press Esc (or Ctrl+C) to
+     interrupt a running turn.
+   - Slash commands: `/clear` (new session), `/resume` (history), `/help`,
+     `/quit`. Ctrl+C stops a running turn, or quits when idle.
+
+## Reusing the web frontend
+
+The domain interfaces (`User`, `Project`, `Issue`, `Session`, `Message`,
+`SessionModelOption`) are copied from `frontend/src/store.ts`; the jsonl
+entry / render-block types from `frontend/src/components/viewer/types.ts`; and
+the pure helpers `assistantResponseText`, `assistantEntryText`, `entryUserText`
+and the noise predicates from `frontend/src/components/viewer/entry-classify.ts`.
+`api.ts` mirrors the frontend's `api()` helper (`Authorization: Bearer`, JSON).
+
+## Backend contract notes (gotchas)
+
+- Sessions are created under **issues**, not projects:
+  `POST /api/issues/:issueId/sessions`.
+- Issue title field is **`title`**; session name field is **`name`**.
+- Worktree flag is **`use_worktree`** (issues) / **`defaultUseWorktree`** (projects).
+- Skill/Memory preferences are **exclusion lists** (`excluded_skill_ids` /
+  `excluded_memory_ids`); omitting = everything enabled.
+- Model field is a short **`key`** from `GET /api/sessions/model-options`.
+- No SSE `done`/`tool_call` events — everything is a `jsonl_entry` carrying a raw
+  Claude/Codex SDK entry; turn-end = `typing active:false`.
+
+## Test
+
+```bash
+npm run typecheck
+npm run test:ui            # mocked fetch + fake SSE, no network
+MOBIUS_TUI_WAIT_MS=90000 npm run test:integration   # real backend (your server)
+npm test                   # all three
+```
+
+## Build an installable package
+
+From the repository root:
+
+```bash
+python3 build.py --build-tui
+```
+
+To build and immediately install the global command into the current user's
+`~/.local` prefix:
+
+```bash
+python3 build.py --build-tui-and-install
+```
+
+For CI or a custom location:
+
+```bash
+python3 build.py --build-tui-and-install --tui-install-prefix /custom/writable/prefix
+```
+
+The command runs the TUI typecheck and AIMUX regression tests, then writes an
+installable npm package plus checksum metadata to `mobius/tui-builds/`:
+
+```text
+mobius-tui-<version>.tgz
+mobius-tui-<version>.tgz.sha256
+manifest.json
+```
+
+Install it without `sudo` and without writing to `/usr/local`:
+
+```bash
+npm install --global --prefix "$HOME/.local" \
+  /path/to/mobius/tui-builds/mobius-tui-<version>.tgz
+export PATH="$HOME/.local/bin:$PATH"
+mobius
+```
+
+If the PATH export is not already in the shell profile, add it to `~/.bashrc`
+once. Using the explicit user prefix avoids the `EACCES ... /usr/local/lib/node_modules/mobius`
+error produced by a root-owned npm global prefix. The built package promotes
+`tsx` to a runtime dependency, so a production/global install can execute the
+TypeScript entry point without retaining the source checkout's devDependencies.

package/bin/mobius-tui.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// bin/mobius-tui.js — launch the Mobius TUI via tsx (no build step required).
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const tsx = join(here, '..', 'node_modules', '.bin', 'tsx')
+const entry = join(here, '..', 'src', 'main.tsx')
+
+const result = spawnSync(tsx, [entry], { stdio: 'inherit' })
+process.exit(result.status ?? 0)

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mobius-os/mobius",
+  "version": "0.2.2",
+  "type": "module",
+  "description": "Mobius terminal client. Reuses Mobius frontend TypeScript types and jsonl entry shapes.",
+  "bin": {
+    "mobius": "bin/mobius-tui.js",
+    "mobius-tui": "bin/mobius-tui.js"
+  },
+  "scripts": {
+    "start": "tsx src/main.tsx"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-highlight": "2.1.11",
+    "ink": "5.2.0",
+    "marked": "12.0.2",
+    "react": "18.3.1",
+    "tsx": "4.19.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,145 @@
+/**
+ * App — top-level route machine.
+ *
+ *   login ──(success / auto-login)──▶ prep ──(preferences ready)──▶ chat
+ *                                              chat ──/resume──▶ resume ──pick──▶ chat(resume)
+ *                                              chat ──/clear───▶ chat (fresh, remounted)
+ *
+ * Auto-login: on startup, read ~/.mobius/login.json and validate the token via
+ * GET /api/auth/me; on a stale token, re-login with the stored username/password
+ * (matching the desktop electron flow). Otherwise show the login form.
+ */
+import React, { useEffect, useState } from 'react'
+import { Box, Text } from 'ink'
+import { MobiusClient, getMe, login, ApiError } from './api.js'
+import { loadLogin, saveLogin, type LoginRecord } from './config.js'
+import { LoginScreen } from './components/Login.js'
+import { PrepScreen, type ReadyState } from './components/PrepScreen.js'
+import { ChatScreen } from './components/Chat.js'
+import { ResumePicker } from './components/ResumePicker.js'
+import { startAimuxConnection, stopAimuxConnection, type AimuxStatus } from './aimux.js'
+import { AimuxStatusLine } from './components/AimuxStatus.js'
+
+type Route = 'boot' | 'login' | 'prep' | 'chat' | 'resume'
+
+export function App() {
+  const [route, setRoute] = useState<Route>('boot')
+  const [bootMsg, setBootMsg] = useState('初始化…')
+  const [client, setClient] = useState<MobiusClient | null>(null)
+  const [userId, setUserId] = useState<string | null>(null)
+  const [prefill, setPrefill] = useState<{ server?: string; username?: string }>({})
+  const [ready, setReady] = useState<ReadyState | null>(null)
+  const [chatKey, setChatKey] = useState(0)
+  const [resumeSessionId, setResumeSessionId] = useState<string | null>(null)
+  const [aimuxStatus, setAimuxStatus] = useState<AimuxStatus>({
+    state: process.env.MOBIUS_TUI_DISABLE_AIMUX === '1' ? 'disabled' : 'stopped',
+    phase: 'idle',
+    detail: process.env.MOBIUS_TUI_DISABLE_AIMUX === '1' ? 'AIMUX 自动连接已关闭' : '登录后自动连接',
+  })
+
+  function bootAimux(rec: LoginRecord): void {
+    // AIMUX installation/connection is deliberately backgrounded: the TUI can
+    // continue into project preparation while a first-time pip install runs.
+    void startAimuxConnection({
+      server: rec.server,
+      token: rec.token,
+      onStatus: (status: AimuxStatus) => {
+        setAimuxStatus(status)
+        if (status.detail) setBootMsg(status.detail)
+      },
+    }).catch((e: any) => setBootMsg(`AIMUX 启动失败: ${e?.message ?? String(e)}`))
+  }
+
+  useEffect(() => () => { void stopAimuxConnection() }, [])
+
+  // ── bootstrap ──────────────────────────────────────────────────────────────
+  useEffect(() => { (async () => {
+    const rec = await loadLogin()
+    if (!rec) { setRoute('login'); return }
+    setPrefill({ server: rec.server, username: rec.username })
+    const c = new MobiusClient(rec.server, rec.token)
+    try {
+      setBootMsg('校验登录态…')
+      const me = await getMe(rec.server, rec.token)
+      setUserId(me.id)
+      setClient(c); setRoute('prep')
+      bootAimux(rec)
+    } catch {
+      // token expired — try to re-login with stored creds
+      if (rec.password) {
+        try {
+          setBootMsg('登录态已过期，重新登录…')
+          const r = await login(rec.server, rec.username, rec.password)
+          const updated: LoginRecord = { ...rec, token: r.token, user: r.user }
+          await saveLogin(updated)
+          setUserId(r.user.id)
+          setClient(new MobiusClient(rec.server, r.token))
+          setRoute('prep')
+          bootAimux(updated)
+          return
+        } catch { /* fall through to login */ }
+      }
+      setRoute('login')
+    }
+  })() }, [])
+
+  // ── handlers ───────────────────────────────────────────────────────────────
+  function onLoginSuccess(rec: LoginRecord) {
+    setUserId(rec.user.id)
+    setClient(new MobiusClient(rec.server, rec.token))
+    setRoute('prep')
+    bootAimux(rec)
+  }
+
+  function onPrepReady(st: ReadyState) {
+    setReady(st)
+    setResumeSessionId(null)
+    setChatKey(k => k + 1)
+    setRoute('chat')
+  }
+
+  function onClear() {
+    if (process.env.MOBIUS_TUI_DEBUG) console.error('[route] clear')
+    setResumeSessionId(null)
+    setChatKey(k => k + 1) // remount Chat → fresh session on next send
+  }
+
+  function onResume() { if (process.env.MOBIUS_TUI_DEBUG) console.error('[route] resume'); setRoute('resume') }
+
+  function onResumed(sid: string) {
+    setResumeSessionId(sid)
+    setChatKey(k => k + 1)
+    setRoute('chat')
+  }
+
+  function onQuit() {
+    void stopAimuxConnection().finally(() => process.exit(0))
+  }
+
+  // ── render ─────────────────────────────────────────────────────────────────
+  if (route === 'boot') {
+    return <Box paddingX={2} paddingY={1}><Text color="cyan">{bootMsg}</Text></Box>
+  }
+  if (route === 'login' || !client) {
+    return <LoginScreen onSuccess={onLoginSuccess} />
+  }
+  if (route === 'prep' || !ready) {
+    return <Box flexDirection="column"><AimuxStatusLine status={aimuxStatus} /><PrepScreen client={client} onReady={onPrepReady} onQuit={onQuit} /></Box>
+  }
+  if (route === 'resume') {
+    return <Box flexDirection="column"><AimuxStatusLine status={aimuxStatus} /><ResumePicker client={client} project={ready.project} onPick={onResumed} onBack={() => setRoute('chat')} /></Box>
+  }
+  return (
+    <ChatScreen
+      key={chatKey}
+      client={client}
+      ready={ready}
+      webUserId={ready.project.created_by || userId || ready.issue.created_by || ''}
+      resumeSessionId={resumeSessionId}
+      onClear={onClear}
+      onResume={onResume}
+      onQuit={onQuit}
+      aimuxStatus={aimuxStatus}
+    />
+  )
+}

package/src/aimux.ts

@@ -0,0 +1,294 @@
+/**
+ * AIMUX bootstrap for the terminal client.
+ *
+ * This mirrors the Electron shell: create a user-owned Python venv, install
+ * aimux on first use, then keep `aimux reverse connect` attached to the
+ * currently authenticated Mobius server.  Nothing is started before login.
+ */
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process'
+import { promises as fs, existsSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { mobiusHome } from './config.js'
+
+export type AimuxState = 'starting' | 'connected' | 'failed' | 'stopped' | 'disabled'
+export type AimuxPhase = 'idle' | 'python' | 'venv' | 'install' | 'connecting' | 'heartbeat' | 'retrying' | 'connected'
+export interface AimuxStatus {
+  state: AimuxState
+  phase?: AimuxPhase
+  detail?: string
+  identifier?: string
+  attempt?: number
+}
+export interface InstallProgress { phase: 'python' | 'venv' | 'install' | 'ready'; detail?: string }
+
+const AIMUX_PACKAGE = 'aimux'
+const WIN = process.platform === 'win32'
+const venvDir = () => path.join(mobiusHome(), 'aimux-venv')
+const venvPython = () => WIN ? path.join(venvDir(), 'Scripts', 'python.exe') : path.join(venvDir(), 'bin', 'python')
+const aimuxExe = () => WIN ? path.join(venvDir(), 'Scripts', 'aimux.exe') : path.join(venvDir(), 'bin', 'aimux')
+
+interface RunResult { code: number; stdout: string; stderr: string }
+
+function run(cmd: string, args: string[], onLine?: (line: string) => void): Promise<RunResult> {
+  return new Promise(resolve => {
+    let stdout = '', stderr = ''
+    let child: ChildProcess
+    try { child = spawn(cmd, args, { windowsHide: true }) } catch (e: any) {
+      resolve({ code: 1, stdout, stderr: e?.message ?? String(e) }); return
+    }
+    const feed = (buf: Buffer, sink: (s: string) => void) => {
+      const text = buf.toString('utf8'); sink(text)
+      for (const line of text.split(/[\r\n]+/).map(s => s.trim()).filter(Boolean)) onLine?.(line)
+    }
+    child.stdout?.on('data', b => feed(b, s => { stdout += s }))
+    child.stderr?.on('data', b => feed(b, s => { stderr += s }))
+    child.on('error', e => resolve({ code: 1, stdout, stderr: e.message }))
+    child.on('close', code => resolve({ code: code ?? 0, stdout, stderr }))
+  })
+}
+
+function executable(cmd: string, args: string[] = ['--version']): boolean {
+  try { return spawnSync(cmd, args, { stdio: 'ignore', windowsHide: true }).status === 0 } catch { return false }
+}
+
+/** Find Python without assuming a package-manager-specific installation. */
+function findPython(): string | null {
+  const configured = process.env.MOBIUS_TUI_PYTHON
+  if (configured && executable(configured, ['--version'])) return configured
+  const candidates = WIN ? ['python.exe', 'python', 'py'] : ['python3', 'python']
+  for (const candidate of candidates) if (executable(candidate, candidate === 'py' ? ['-3', '--version'] : ['--version'])) return candidate
+  return null
+}
+
+/** Install a user-local Python when no interpreter is present (requires uv). */
+async function installPython(onProgress?: (p: InstallProgress) => void): Promise<string | null> {
+  if (!executable('uv', ['--version'])) return null
+  onProgress?.({ phase: 'python', detail: '未找到 Python，使用 uv 安装 Python 3.11…' })
+  const r = await run('uv', ['python', 'install', '3.11'], line => onProgress?.({ phase: 'python', detail: line.slice(0, 120) }))
+  if (r.code !== 0) return null
+  const found = await run('uv', ['python', 'find', '3.11'])
+  const candidate = found.stdout.trim().split(/\r?\n/).pop()?.trim()
+  return candidate && executable(candidate, ['--version']) ? candidate : findPython()
+}
+
+async function pythonForAimux(onProgress?: (p: InstallProgress) => void): Promise<string | null> {
+  return findPython() ?? installPython(onProgress)
+}
+
+export async function ensureAimux(onProgress?: (p: InstallProgress) => void): Promise<{ ok: boolean; error?: string }> {
+  if (existsSync(aimuxExe()) && existsSync(venvPython())) { onProgress?.({ phase: 'ready' }); return { ok: true } }
+  const py = await pythonForAimux(onProgress)
+  if (!py) return { ok: false, error: '未找到 Python。请先安装 Python 3.10+（或安装 uv 后重试）。' }
+  onProgress?.({ phase: 'venv', detail: `创建 Python 虚拟环境（${py}）…` })
+  let r = await run(py, ['-m', 'venv', venvDir()])
+  if (r.code !== 0 && py === 'py') r = await run(py, ['-3', '-m', 'venv', venvDir()])
+  if (r.code !== 0) return { ok: false, error: `venv 创建失败: ${r.stderr || r.stdout}` }
+  onProgress?.({ phase: 'install', detail: `下载并安装 ${AIMUX_PACKAGE}…` })
+  r = await run(venvPython(), ['-m', 'pip', 'install', '--no-input', '--disable-pip-version-check', AIMUX_PACKAGE], line => {
+    if (/downloading|collecting|installing|using cached|%\s*\d|━|─/i.test(line)) onProgress?.({ phase: 'install', detail: line.slice(0, 120) })
+  })
+  if (r.code !== 0) return { ok: false, error: `pip install 失败: ${r.stderr || r.stdout}` }
+  if (!existsSync(aimuxExe())) return { ok: false, error: `aimux 可执行未生成: ${aimuxExe()}` }
+  onProgress?.({ phase: 'ready' }); return { ok: true }
+}
+
+export function tuiAimuxIdentifier(): string {
+  const host = os.hostname().toLowerCase().replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32)
+  return `tui-${host || 'pc'}`
+}
+
+export async function probeAimuxBridgeConnection(
+  server: string,
+  token: string,
+  identifier: string,
+  timeoutMs = 4_000,
+): Promise<boolean> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(
+      `${server.replace(/\/$/, '')}/aimux_bridge/api/remotes/${encodeURIComponent(identifier)}/connection`,
+      { headers: { Authorization: `Bearer ${token}` }, signal: controller.signal },
+    )
+    if (!response.ok) return false
+    const data: any = await response.json().catch(() => ({}))
+    return data?.identifier === identifier && data?.event_stream_connected === true
+  } catch {
+    return false
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
+interface SupervisorOptions {
+  server: string
+  token: string
+  identifier: string
+  onStatus: (s: AimuxStatus) => void
+  heartbeatIntervalMs?: number
+  heartbeatFailureThreshold?: number
+  retryBaseMs?: number
+  probeConnection?: () => Promise<boolean>
+  spawnProcess?: () => ChildProcess
+}
+
+export class AimuxSupervisor {
+  private child: ChildProcess | null = null
+  private stopping = false
+  private retry: ReturnType<typeof setTimeout> | null = null
+  private heartbeatTimer: ReturnType<typeof setTimeout> | null = null
+  private heartbeatEpoch = 0
+  private heartbeatFailures = 0
+  private reconnectAttempt = 0
+  private bridgeConnected = false
+  private opts: SupervisorOptions
+  constructor(opts: SupervisorOptions) { this.opts = opts }
+  start() { this.stopping = false; this.spawnChild() }
+  private spawnChild() {
+    const { server, token, identifier, onStatus } = this.opts
+    onStatus({ state: 'starting', phase: 'connecting', detail: '正在连接 Mobius AIMUX bridge…', identifier, attempt: this.reconnectAttempt })
+    const child = this.opts.spawnProcess?.() ?? spawn(
+      aimuxExe(),
+      ['reverse', 'connect', `${server.replace(/\/$/, '')}/aimux_bridge`, '--identifier', identifier, '--token', token, '--replace'],
+      { windowsHide: true },
+    )
+    this.child = child
+    this.startHeartbeat()
+    const classify = (buf: Buffer) => {
+      const text = buf.toString('utf8')
+      if (!this.bridgeConnected && /connected|registered|event stream|heartbeat|sse/i.test(text)) {
+        onStatus({ state: 'starting', phase: 'heartbeat', detail: 'AIMUX 已启动，等待 bridge 心跳确认…', identifier })
+      } else if (/connection (refused|reset|closed|error)|failed to connect|unauthorized|forbidden|token.*invalid/i.test(text)) {
+        onStatus({ state: 'failed', phase: 'heartbeat', detail: text.trim().slice(-200), identifier })
+      }
+    }
+    child.stdout?.on('data', classify); child.stderr?.on('data', classify)
+    child.on('error', e => onStatus({ state: 'failed', phase: 'retrying', detail: `AIMUX 启动失败: ${e.message}`, identifier }))
+    child.on('exit', code => {
+      if (this.child !== child) return
+      this.child = null
+      this.stopHeartbeat()
+      if (this.stopping) { onStatus({ state: 'stopped', phase: 'idle', detail: 'AIMUX 已停止', identifier }); return }
+      this.scheduleReconnect(`AIMUX 进程退出（code=${code}）`)
+    })
+  }
+
+  private startHeartbeat() {
+    this.stopHeartbeat()
+    this.heartbeatFailures = 0
+    this.bridgeConnected = false
+    const epoch = ++this.heartbeatEpoch
+    void this.checkHeartbeat(epoch)
+  }
+
+  private stopHeartbeat() {
+    this.heartbeatEpoch += 1
+    if (this.heartbeatTimer) clearTimeout(this.heartbeatTimer)
+    this.heartbeatTimer = null
+  }
+
+  private async checkHeartbeat(epoch: number): Promise<void> {
+    const connected = await (this.opts.probeConnection?.() ?? probeAimuxBridgeConnection(this.opts.server, this.opts.token, this.opts.identifier))
+    if (this.stopping || epoch !== this.heartbeatEpoch || !this.child) return
+
+    const threshold = this.opts.heartbeatFailureThreshold ?? 3
+    if (connected) {
+      this.heartbeatFailures = 0
+      this.reconnectAttempt = 0
+      this.bridgeConnected = true
+      this.opts.onStatus({
+        state: 'connected', phase: 'connected',
+        detail: `心跳正常 · ${this.opts.identifier}`,
+        identifier: this.opts.identifier,
+      })
+    } else {
+      this.heartbeatFailures += 1
+      if (this.heartbeatFailures >= threshold) {
+        this.bridgeConnected = false
+        await this.restartAfterDisconnect(`bridge 心跳连续 ${this.heartbeatFailures} 次未响应`)
+        return
+      }
+      this.opts.onStatus({
+        state: 'starting', phase: 'heartbeat',
+        detail: `等待 bridge 心跳确认（${this.heartbeatFailures}/${threshold}）…`,
+        identifier: this.opts.identifier,
+      })
+    }
+    const interval = this.opts.heartbeatIntervalMs ?? 5_000
+    this.heartbeatTimer = setTimeout(() => void this.checkHeartbeat(epoch), interval)
+  }
+
+  private async restartAfterDisconnect(reason: string) {
+    this.stopHeartbeat()
+    await this.killChild()
+    if (!this.stopping) this.scheduleReconnect(reason)
+  }
+
+  private scheduleReconnect(reason: string) {
+    if (this.stopping || this.retry) return
+    this.reconnectAttempt += 1
+    const base = this.opts.retryBaseMs ?? 1_000
+    const delay = Math.min(15_000, base * (2 ** Math.min(this.reconnectAttempt - 1, 4)))
+    const seconds = Math.max(1, Math.ceil(delay / 1_000))
+    this.opts.onStatus({
+      state: 'failed', phase: 'retrying',
+      detail: `${reason}，${seconds} 秒后进行第 ${this.reconnectAttempt} 次重连…`,
+      identifier: this.opts.identifier,
+      attempt: this.reconnectAttempt,
+    })
+    this.retry = setTimeout(() => {
+      this.retry = null
+      if (!this.stopping) this.spawnChild()
+    }, delay)
+  }
+
+  private async killChild() {
+    const child = this.child
+    this.child = null
+    if (!child?.pid) return
+    if (WIN) await run('taskkill', ['/PID', String(child.pid), '/T', '/F'])
+    else try { child.kill('SIGTERM') } catch { /* ignore */ }
+  }
+
+  async stop() {
+    this.stopping = true
+    if (this.retry) clearTimeout(this.retry)
+    this.retry = null
+    this.stopHeartbeat()
+    await this.killChild()
+    this.opts.onStatus({ state: 'stopped', phase: 'idle', detail: 'AIMUX 已停止', identifier: this.opts.identifier })
+  }
+}
+
+let supervisor: AimuxSupervisor | null = null
+let installing: Promise<void> | null = null
+
+export async function startAimuxConnection(opts: { server: string; token: string; onStatus?: (s: AimuxStatus) => void }): Promise<void> {
+  const onStatus = opts.onStatus ?? (() => {})
+  // Tests and explicitly opted-out users should not spawn a network worker.
+  if (process.env.MOBIUS_TUI_DISABLE_AIMUX === '1') {
+    onStatus({ state: 'disabled', phase: 'idle', detail: 'AIMUX 自动连接已关闭' }); return
+  }
+  if (process.env.NODE_ENV === 'test' || /^https?:\/\/mock(?:\.local)?(?::\d+)?$/i.test(opts.server)) {
+    onStatus({ state: 'disabled', phase: 'idle', detail: 'AIMUX 测试连接已跳过' }); return
+  }
+  if (supervisor || installing) return
+  installing = (async () => {
+    onStatus({ state: 'starting', phase: 'python', detail: '检查 Python 与 AIMUX 运行环境…' })
+    const ready = await ensureAimux(p => onStatus({
+      state: 'starting',
+      phase: p.phase === 'ready' ? 'connecting' : p.phase,
+      detail: p.detail || (p.phase === 'ready' ? 'AIMUX 已就绪，准备连接…' : p.phase),
+    }))
+    if (!ready.ok) { onStatus({ state: 'failed', phase: 'idle', detail: ready.error }); return }
+    supervisor = new AimuxSupervisor({ server: opts.server, token: opts.token, identifier: tuiAimuxIdentifier(), onStatus })
+    supervisor.start()
+  })().finally(() => { installing = null })
+  await installing
+}
+
+export async function stopAimuxConnection(): Promise<void> {
+  const current = supervisor; supervisor = null
+  await current?.stop()
+}