rterm-cli 3.4.4 → 3.7.4

package/README.md

@@ -7,11 +7,13 @@ no dependencies.
 ## Install / run
 
 ```bash
-# from a checkout
+# run directly (nothing to install)
+npx rterm-cli ping
+
+# or from a checkout
 node apps/cli/rterm-cli.mjs ping
 
 # link it
-npm --workspace @rterm/cli run build 2>/dev/null || true
 ln -s "$(pwd)/apps/cli/rterm-cli.mjs" /usr/local/bin/rterm
 ```
 
@@ -28,11 +30,57 @@ rterm close <tabIdOrName>                  # close a terminal tab
 rterm run <tabIdOrName> <command>          # run a command in a tab (waits)
 rterm fleet <tab1,tab2,...> <command>      # run on many tabs at once
 rterm sessions                             # list chat sessions
+rterm chat                                 # INTERACTIVE persistent chat (see below)
 rterm chat <sessionId> <message>           # send a message to the agent (blocking)
 rterm dashboard                            # live dashboard state
 rterm metrics [--format prometheus]        # host metrics
 ```
 
+## Interactive chat — the desktop experience, in your terminal
+
+`rterm chat` (with no arguments) opens a persistent, streaming conversation with
+the RTerm agent — the same session, events, and history the desktop app uses:
+
+```text
+$ rterm chat
+Connected to ws://127.0.0.1:17888 — session 96c153ac…
+── resuming (4 messages) ──
+you> Reply with exactly one word: PONG
+· Reasoning... The user wants me to reply with exactly one word: PONG
+assistant> PONG
+you> /exit
+session 96c153ac… kept server-side — rerun "rterm chat" to resume.
+```
+
+What you get:
+
+- **Streaming replies** — text, reasoning, and tool output render live as the
+  agent works (`say` / `sub_tool_*` / `command_*` gateway events).
+- **Persistent sessions** — the conversation lives on the backend (SQLite), not
+  in the terminal. Exit, kill the process, reboot the machine — the next
+  `rterm chat` resumes where you left off (last session id saved in
+  `~/.rterm-cli/chat-state.json`; override with `--session <id>`).
+- **History replay** — resuming a session prints the past transcript first.
+- **Command approvals** — when the agent asks to run a command, the CLI pauses
+  and prompts `allow? [y/N]`, replying via the same approval RPC the desktop
+  uses. Any non-`y` answer denies.
+- **Slash commands**:
+
+| Command | Action |
+|---|---|
+| `/new` | Start a fresh session |
+| `/sessions` | List sessions; type a number to resume one |
+| `/rename <title>` | Rename the current session |
+| `/branch` | Branch a new session from the last assistant message |
+| `/export [--simple]` | Export this session as markdown |
+| `/search <query>` | Full-text search across ALL sessions (needs a history bridge) |
+| `/stop` | Stop the running agent task |
+| `/verbose` | Toggle raw gateway-event display |
+| `/exit` (or Ctrl-D) | Leave — the session stays on the server |
+
+Flags: `--session <id>` (resume a specific session), `--verbose` (start with
+raw events on).
+
 ## Configuration
 
 | Env | Default | Meaning |

package/package.json

@@ -1,37 +1,35 @@
 {
   "name": "rterm-cli",
-  "version": "3.4.4",
-  "description": "rterm \u2014 command CLI for the RTerm / neuralOS backend WebSocket gateway",
+  "version": "3.7.4",
+  "description": "rterm — command CLI for the RTerm / neuralOS backend WebSocket gateway",
+  "type": "module",
+  "bin": {
+    "rterm": "./rterm-cli.mjs",
+    "rterm-cli": "./rterm-cli.mjs"
+  },
+  "files": [
+    "rterm-cli.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "keywords": [
-    "forward-deployed-engineer",
-    "fde",
-    "ai-terminal",
-    "ai-agent",
-    "ssh",
-    "winrm",
-    "serial-console",
-    "cisco",
-    "network-automation",
-    "sre",
-    "observability",
-    "incident-response",
-    "change-management",
-    "infrastructure-automation",
-    "runbooks",
+    "rterm",
     "neuralos",
-    "aiops",
-    "ai-sre",
-    "agentic-ai",
+    "terminal",
+    "ssh",
+    "ai",
+    "agent",
+    "cli",
     "chatops",
-    "self-healing",
-    "runbook-automation",
-    "closed-loop-remediation",
-    "mcp"
+    "fde",
+    "agentic-ai"
   ],
-  "license": "Apache-2.0",
-  "bin": {
-    "rterm": "rterm-cli.mjs",
-    "rterm-cli": "rterm-cli.mjs"
-  },
-  "type": "module"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DrOlu/RTerm.git",
+    "directory": "apps/cli"
+  }
 }

package/rterm-cli.mjs

@@ -10,15 +10,21 @@
  *   rterm ping | version | methods | call | terminals | connections
  *   rterm open <name> | close <tab> | run <tab> <cmd> | fleet <tabs> <cmd>
  *   rterm sessions | chat <session> <msg> | dashboard | metrics
+ *   rterm chat                        Interactive persistent chat (REPL):
+ *                                     streaming replies, session resume,
+ *                                     command approvals, slash commands.
  */
 
-import { readFileSync, existsSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import readline from 'node:readline'
 
 const DEFAULT_HOST = process.env.RTERM_HOST || '127.0.0.1'
 const DEFAULT_PORT = Number(process.env.RTERM_PORT || 17888)
 const DEFAULT_URL = process.env.RTERM_URL || `ws://${DEFAULT_HOST}:${DEFAULT_PORT}`
+const STATE_DIR = join(homedir(), '.rterm-cli')
+const STATE_FILE = join(STATE_DIR, 'chat-state.json')
 
 // ── tiny arg parser ─────────────────────────────────────────────────────────
 
@@ -85,11 +91,31 @@ function loadToken() {
   return null
 }
 
+/**
+ * Append the token as an `access_token` query parameter. The gateway accepts
+ * the token from the Authorization header OR this query param; the query param
+ * works on every WebSocket client (native WS ignores constructor options on
+ * some runtimes, and browsers cannot send custom headers at all).
+ */
+function urlWithToken(url, token) {
+  if (!token) return url
+  try {
+    const u = new URL(url)
+    if (!u.searchParams.has('access_token')) u.searchParams.set('access_token', token)
+    return u.toString()
+  } catch {
+    return url
+  }
+}
+
 async function openSocket(url, token) {
   const headers = token ? { Authorization: `Bearer ${token}` } : undefined
   if (typeof globalThis.WebSocket === 'function') {
     return await new Promise((resolve, reject) => {
-      const ws = new globalThis.WebSocket(url)
+      // Pass the token BOTH ways: as a query param (always works) and try the
+      // options object (native WebSocket in Node >= 22 forwards extra options
+      // to undici and sends the header; browsers ignore it harmlessly).
+      const ws = new globalThis.WebSocket(urlWithToken(url, token), headers ? { headers } : undefined)
       ws.onopen = () => resolve(ws)
       ws.onerror = () => reject(new Error(`Cannot connect to ${url}. Is the backend running? (gybackend)`))
     })
@@ -99,7 +125,7 @@ async function openSocket(url, token) {
     const require = createRequire(import.meta.url)
     const WS = require('ws')
     return await new Promise((resolve, reject) => {
-      const ws = new WS(url, { headers })
+      const ws = new WS(urlWithToken(url, token), { headers })
       ws.on('open', () => resolve(ws))
       ws.on('error', () => reject(new Error(`Cannot connect to ${url}. Is the backend running? (gybackend)`)))
     })
@@ -157,6 +183,95 @@ function makeClient(url, token) {
   }
 }
 
+// ── persistent (multiplexed) client for interactive chat ────────────────────
+
+/**
+ * One long-lived WebSocket; JSON-RPC calls are multiplexed by id and every
+ * gateway event frame is fanned out to registered listeners. This is what
+ * makes the interactive chat possible: we LISTEN while we TALK.
+ */
+class PersistentClient {
+  constructor(url, token) {
+    this.url = url
+    this.token = token
+    this.ws = null
+    this.pending = new Map() // id -> { resolve, reject }
+    this.eventListeners = new Set() // (frame) => void
+  }
+
+  async connect() {
+    this.ws = await openSocket(this.url, this.token)
+    const wire = (raw) => {
+      let frame
+      try {
+        frame = JSON.parse(typeof raw === 'string' ? raw : raw.toString())
+      } catch { return }
+      if (frame.type === 'gateway:response' && frame.id !== undefined) {
+        const p = this.pending.get(String(frame.id))
+        if (p) {
+          this.pending.delete(String(frame.id))
+          if (frame.ok) p.resolve(frame.result)
+          else p.reject(frame.error || new Error('gateway error'))
+        }
+        return
+      }
+      if (frame.type === 'gateway:event' || frame.type === 'gateway:ui-update') {
+        for (const fn of this.eventListeners) {
+          try { fn(frame) } catch { /* listener errors never kill the socket */ }
+        }
+      }
+    }
+    if (typeof this.ws.addEventListener === 'function') {
+      this.ws.addEventListener('message', (e) => wire(e.data))
+      this.ws.addEventListener('close', () => this.onClosed())
+    } else if (typeof this.ws.on === 'function') {
+      this.ws.on('message', (d) => wire(d))
+      this.ws.on('close', () => this.onClosed())
+    } else {
+      this.ws.onmessage = (e) => wire(e.data)
+      this.ws.onclose = () => this.onClosed()
+    }
+  }
+
+  onClosed() {
+    // Reject everything in flight; the REPL surfaces a clear message.
+    for (const [, p] of this.pending) {
+      p.reject(new Error('Connection closed. Is the backend still running?'))
+    }
+    this.pending.clear()
+  }
+
+  get connected() {
+    return this.ws && this.ws.readyState === 1
+  }
+
+  async reconnect() {
+    try { this.ws?.close?.() } catch { /* ignore */ }
+    await this.connect()
+  }
+
+  onEvent(fn) {
+    this.eventListeners.add(fn)
+    return () => this.eventListeners.delete(fn)
+  }
+
+  call(method, params, timeoutMs = 60_000) {
+    if (!this.connected) throw new Error('Not connected.')
+    const id = String(nextId++)
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`Timeout calling ${method}`))
+      }, timeoutMs)
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timer); resolve(v) },
+        reject: (e) => { clearTimeout(timer); reject(e) },
+      })
+      this.ws.send(JSON.stringify({ id, method, ...(params !== undefined ? { params } : {}) }))
+    })
+  }
+}
+
 // ── output helpers ──────────────────────────────────────────────────────────
 
 function printJson(value) {
@@ -168,6 +283,18 @@ function fail(message) {
   process.exit(1)
 }
 
+const C = process.stdout.isTTY ? {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+} : {
+  dim: (s) => s, bold: (s) => s, cyan: (s) => s,
+  yellow: (s) => s, red: (s) => s, green: (s) => s,
+}
+
 const HELP = `rterm — command CLI for the RTerm / neuralOS backend gateway
 
 Usage:
@@ -182,10 +309,23 @@ Usage:
   rterm run <tabIdOrName> <command>         Run a command in a terminal tab (waits)
   rterm fleet <tab1,tab2,...> <command>     Run a command on many tabs at once
   rterm sessions                            List chat sessions
+  rterm chat                                Interactive persistent chat (REPL)
   rterm chat <sessionId> <message>          Send a message to the agent (blocking)
   rterm dashboard                           Print the live dashboard state
   rterm metrics [--format prometheus]       Host metrics
 
+Interactive chat slash commands:
+  /new                    Start a fresh session
+  /sessions               List sessions (pick one to resume)
+  /rename <title>         Rename the current session
+  /branch                 Branch from the last assistant message
+  /export [--simple]      Export this session as markdown
+  /search <query>         Full-text search across ALL sessions
+  /stop                   Stop the running agent task
+  /verbose                Toggle raw event display
+  /help                   This list
+  /exit                   Leave the chat (session is kept server-side)
+
 Options:
   --url ws://host:port    Gateway URL (default ${DEFAULT_URL}, env RTERM_URL)
   --token <token>         Access token (env RTERM_TOKEN; non-localhost requires one)
@@ -302,6 +442,486 @@ async function runInTab(client, tabIdOrName, commandText) {
   return stripAnsi(output).trimEnd()
 }
 
+// ── chat state (session resume) ─────────────────────────────────────────────
+
+function loadChatState() {
+  try {
+    if (existsSync(STATE_FILE)) {
+      const parsed = JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+      if (parsed && typeof parsed === 'object') return parsed
+    }
+  } catch { /* corrupted state → start fresh */ }
+  return {}
+}
+
+function saveChatState(patch) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true })
+    const next = { ...loadChatState(), ...patch }
+    writeFileSync(STATE_FILE, JSON.stringify(next, null, 2))
+  } catch { /* best-effort */ }
+}
+
+// ── interactive chat ────────────────────────────────────────────────────────
+
+/** Extract {sessionId, event} from a gateway:event frame (null otherwise). */
+function extractAgentEvent(frame) {
+  if (frame?.type !== 'gateway:event') return null
+  const p = frame.payload
+  if (p?.type !== 'agent:event') return null
+  if (!p.payload || typeof p.payload !== 'object') return null
+  return { sessionId: p.sessionId, event: p.payload }
+}
+
+function shortId(id) {
+  return typeof id === 'string' && id.length > 10 ? `${id.slice(0, 8)}…` : String(id)
+}
+
+class InteractiveChat {
+  constructor(client, flags) {
+    this.client = client
+    this.flags = flags || {}
+    this.sessionId = null
+    this.verbose = this.flags.verbose === true
+    this.turnActive = false
+    this.turnResolve = null
+    this.currentSayId = null
+    this.sayOpen = false
+    this.lastAssistantMessageId = null
+    this.unsubscribe = null
+    this.rl = null
+  }
+
+  async start() {
+    const state = loadChatState()
+    const requested = typeof this.flags.session === 'string' && this.flags.session
+      ? this.flags.session
+      : (state.lastSessionId || null)
+
+    if (requested) {
+      const ok = await this.tryResume(requested)
+      if (!ok) console.log(C.dim(`(saved session ${shortId(requested)} no longer exists — starting fresh)`))
+    }
+    if (!this.sessionId) {
+      await this.newSession()
+    }
+
+    this.unsubscribe = this.client.onEvent((frame) => this.handleFrame(frame))
+
+    console.log(C.dim(`Connected to ${this.client.url} — session ${shortId(this.sessionId)}`))
+    console.log(C.dim('Type a message, or /help for commands. /exit to leave.\n'))
+    await this.printHistory()
+    await this.repl()
+  }
+
+  async tryResume(sessionId) {
+    try {
+      const result = await this.client.call('session:get', { sessionId })
+      if (result?.session?.id || result?.session?.sessionId) {
+        this.sessionId = sessionId
+        return true
+      }
+      return false
+    } catch {
+      return false
+    }
+  }
+
+  async newSession() {
+    const result = await this.client.call('gateway:createSession')
+    this.sessionId = result?.sessionId
+    if (!this.sessionId) throw new Error('gateway:createSession returned no sessionId')
+    saveChatState({ lastSessionId: this.sessionId, lastUrl: this.client.url })
+  }
+
+  async switchSession(sessionId) {
+    this.sessionId = sessionId
+    saveChatState({ lastSessionId: sessionId, lastUrl: this.client.url })
+    console.log(C.dim(`\n── switched to session ${shortId(sessionId)} ──`))
+    await this.printHistory()
+  }
+
+  async printHistory() {
+    let messages = []
+    try {
+      messages = await this.client.call('agent:getUiMessages', { id: this.sessionId })
+      if (!Array.isArray(messages)) messages = []
+    } catch {
+      return // history bridge unavailable — fine on a fresh session
+    }
+    if (messages.length === 0) {
+      console.log(C.dim('(new session — no history yet)'))
+      return
+    }
+    console.log(C.dim(`── resuming (${messages.length} messages) ──`))
+    for (const m of messages) {
+      const role = m.role === 'user' ? 'you' : m.role === 'assistant' ? 'assistant' : m.role
+      const text = typeof m.content === 'string' ? m.content : ''
+      if (!text.trim()) continue
+      if (m.streaming) continue // never persisted as streaming in practice
+      console.log(`${C.bold(C.cyan(role))}> ${text.length > 2000 ? `${text.slice(0, 2000)}…` : text}`)
+    }
+    const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant' && m.id)
+    this.lastAssistantMessageId = lastAssistant?.id || null
+    console.log(C.dim('── end of history ──\n'))
+  }
+
+  handleFrame(frame) {
+    const extracted = extractAgentEvent(frame)
+    if (!extracted || extracted.sessionId !== this.sessionId) return
+    const ev = extracted.event
+    if (this.verbose) {
+      console.log(C.dim(`  [event] ${JSON.stringify(ev).slice(0, 300)}`))
+    }
+    switch (ev.type) {
+      case 'say': {
+        this.renderSay(ev)
+        break
+      }
+      case 'user_input':
+        break // we echo input locally
+      case 'command_started': {
+        this.closeSay()
+        console.log(C.dim(`⚙ ${ev.command || ev.toolName || 'running…'}`))
+        break
+      }
+      case 'command_finished': {
+        this.closeSay()
+        const ok = ev.exitCode === undefined || ev.exitCode === 0
+        console.log(C.dim(`⚙ done${ev.exitCode !== undefined ? ` (exit ${ev.exitCode})` : ''}${ok ? '' : ' ✗'}`))
+        break
+      }
+      case 'sub_tool_started': {
+        this.closeSay()
+        process.stdout.write(C.dim(`· ${ev.title || ev.toolName || 'thinking'} `))
+        break
+      }
+      case 'sub_tool_delta': {
+        if (typeof ev.outputDelta === 'string') process.stdout.write(C.dim(ev.outputDelta))
+        break
+      }
+      case 'sub_tool_finished': {
+        process.stdout.write('\n')
+        break
+      }
+      case 'alert': {
+        this.closeSay()
+        console.log(C.yellow(`⚠ ${ev.message || ''}`))
+        break
+      }
+      case 'error': {
+        this.closeSay()
+        console.log(C.red(`✗ ${ev.message || ev.error || 'agent error'}`))
+        break
+      }
+      case 'command_ask': {
+        this.closeSay()
+        void this.handleApproval(ev)
+        break
+      }
+      case 'done': {
+        this.closeSay()
+        this.lastAssistantMessageId = ev.messageId || this.lastAssistantMessageId
+        this.finishTurn()
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  renderSay(ev) {
+    const delta = typeof ev.content === 'string' ? ev.content : (typeof ev.outputDelta === 'string' ? ev.outputDelta : '')
+    if (!delta) return
+    const id = ev.messageId || null
+    if (id && id !== this.currentSayId) {
+      if (this.sayOpen) process.stdout.write('\n\n')
+      else if (this.currentSayId !== null) process.stdout.write('\n\n')
+      process.stdout.write(`${C.bold(C.cyan('assistant'))}> `)
+      this.currentSayId = id
+      this.sayOpen = true
+    }
+    process.stdout.write(delta)
+  }
+
+  closeSay() {
+    if (this.sayOpen) {
+      process.stdout.write('\n')
+      this.sayOpen = false
+    }
+  }
+
+  async handleApproval(ev) {
+    const command = ev.command || ''
+    const toolName = ev.toolName || 'Command'
+    this.closeSay()
+    console.log(C.yellow(`\n⏸  approval needed — ${toolName}:`))
+    console.log(C.yellow(`   ${command}`))
+    // The turn is active (readline paused for the streaming turn) — resume
+    // input so the user can actually answer; otherwise this deadlocks.
+    this.rl.resume()
+    process.stdout.write(C.bold('allow? [y/N] '))
+    this.pendingApproval = {
+      approvalId: ev.approvalId,
+      resolve: async (answer) => {
+        const trimmed = (answer || '').trim().toLowerCase()
+        const decision = trimmed === 'y' || trimmed === 'yes' ? 'allow' : 'deny'
+        try {
+          await this.client.call('agent:replyCommandApproval', { approvalId: ev.approvalId, decision })
+          console.log(C.dim(decision === 'allow' ? '(allowed)' : '(denied)'))
+        } catch (error) {
+          console.log(C.red(`approval reply failed: ${errorMessage(error)}`))
+        }
+        this.pendingApproval = null
+      },
+    }
+  }
+
+  finishTurn() {
+    if (this.turnResolve) {
+      const r = this.turnResolve
+      this.turnResolve = null
+      r()
+    }
+    // EOF arrived while the turn was streaming → shut down now that it's done.
+    if (this.stdinClosed && !this.quitting) this.shutdown()
+  }
+
+  async runTurn(userInput) {
+    this.turnActive = true
+    this.currentSayId = null
+    this.sayOpen = false
+    const turnPromise = new Promise((resolve) => { this.turnResolve = resolve })
+    try {
+      await this.client.call('agent:startTaskAsync', { sessionId: this.sessionId, userInput })
+    } catch (error) {
+      this.turnActive = false
+      throw error
+    }
+    await turnPromise
+    this.turnActive = false
+  }
+
+  async stopTask() {
+    try {
+      await this.client.call('agent:stopTask', { sessionId: this.sessionId })
+      console.log(C.dim('(stop requested)'))
+    } catch (error) {
+      console.log(C.red(`stop failed: ${errorMessage(error)}`))
+    }
+  }
+
+  async listSessionsPick() {
+    const result = await this.client.call('session:list')
+    const sessions = Array.isArray(result?.sessions) ? result.sessions : []
+    if (sessions.length === 0) {
+      console.log(C.dim('(no sessions)'))
+      return
+    }
+    sessions.forEach((s, i) => {
+      const title = s.title || s.name || '(untitled)'
+      const when = s.updatedAt || s.lastActivity || ''
+      console.log(`  ${String(i + 1).padStart(3)}. ${shortId(s.id)}  ${title}${when ? C.dim(`  ${when}`) : ''}`)
+    })
+    this.pendingPick = {
+      resolve: async (answer) => {
+        const idx = Number.parseInt((answer || '').trim(), 10)
+        if (Number.isInteger(idx) && idx >= 1 && idx <= sessions.length) {
+          await this.switchSession(sessions[idx - 1].id)
+        }
+        this.pendingPick = null
+      },
+    }
+  }
+
+  async branchFromLast() {
+    if (!this.lastAssistantMessageId) {
+      console.log(C.dim('(no assistant message to branch from yet)'))
+      return
+    }
+    try {
+      const result = await this.client.call('agent:branchFromMessage', {
+        sessionId: this.sessionId,
+        messageId: this.lastAssistantMessageId,
+      })
+      const newId = result?.sessionId || result?.id
+      if (newId) await this.switchSession(newId)
+      else console.log(C.dim('(branch created — see /sessions)'))
+    } catch (error) {
+      console.log(C.red(`branch failed: ${errorMessage(error)}`))
+    }
+  }
+
+  async exportSession(mode) {
+    try {
+      const result = await this.client.call('agent:exportHistory', { sessionId: this.sessionId, mode })
+      if (typeof result === 'string') console.log(result)
+      else if (typeof result?.content === 'string') console.log(result.content)
+      else if (typeof result?.markdown === 'string') console.log(result.markdown)
+      else printJson(result)
+    } catch (error) {
+      console.log(C.red(`export failed: ${errorMessage(error)}`))
+    }
+  }
+
+  async searchHistory(query) {
+    try {
+      const result = await this.client.call('history:search', { query })
+      printJson(result)
+    } catch (error) {
+      console.log(C.red(`search failed: ${errorMessage(error)}`))
+    }
+  }
+
+  async handleSlash(line) {
+    const [cmd, ...rest] = line.slice(1).split(/\s+/)
+    const arg = rest.join(' ')
+    switch ((cmd || '').toLowerCase()) {
+      case 'new': {
+        await this.newSession()
+        console.log(C.dim(`── new session ${shortId(this.sessionId)} ──`))
+        return true
+      }
+      case 'sessions':
+        await this.listSessionsPick()
+        return true
+      case 'rename': {
+        if (!arg) { console.log(C.dim('usage: /rename <title>')); return true }
+        try {
+          await this.client.call('agent:renameSession', { sessionId: this.sessionId, newTitle: arg })
+          console.log(C.dim(`renamed to "${arg}"`))
+        } catch (error) { console.log(C.red(errorMessage(error))) }
+        return true
+      }
+      case 'branch':
+        await this.branchFromLast()
+        return true
+      case 'export':
+        await this.exportSession(this.flags.simple || arg.includes('--simple') ? 'simple' : 'detailed')
+        return true
+      case 'search':
+        if (!arg) { console.log(C.dim('usage: /search <query>')); return true }
+        await this.searchHistory(arg)
+        return true
+      case 'stop':
+        await this.stopTask()
+        return true
+      case 'verbose':
+        this.verbose = !this.verbose
+        console.log(C.dim(`verbose ${this.verbose ? 'on' : 'off'}`))
+        return true
+      case 'help':
+        console.log(HELP.split('Interactive chat slash commands:')[1]?.split('Options:')[0]?.trim() || 'see /exit')
+        return true
+      case 'exit':
+      case 'quit':
+      case 'q':
+        return false
+      default:
+        console.log(C.dim(`unknown command "/${cmd}" — /help for the list`))
+        return true
+    }
+  }
+
+  async repl() {
+    // Event-driven readline (NOT readline/promises question()): one 'line'
+    // handler dispatches by input state (approval → pick → command/chat).
+    // This works identically for a TTY and piped stdin, and never deadlocks.
+    this.rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: `${C.bold(C.green('you'))}> ` })
+    this.pendingApproval = null
+    this.pendingPick = null
+    this.quitting = false
+
+    this.rl.on('line', (line) => {
+      void this.onLine(line)
+    })
+    this.rl.on('close', () => {
+      // stdin EOF (piped input exhausted, Ctrl-D, or Ctrl-C on some platforms).
+      // If a turn is streaming, let it finish first (finishTurn shuts down);
+      // otherwise drain gracefully — NEVER process.exit() here, it would race
+      // in-flight async line handlers and truncate pending stdout writes.
+      this.stdinClosed = true
+      if (!this.turnActive) this.shutdown()
+    })
+    this.rl.prompt()
+    // Resolve only when the REPL shuts down — keeps main() alive.
+    return new Promise((resolve) => { this.replDone = resolve })
+  }
+
+  shutdown() {
+    if (this.quitting) return
+    this.quitting = true
+    this.unsubscribe?.()
+    console.log(C.dim(`\nsession ${shortId(this.sessionId)} kept server-side — rerun "rterm chat" to resume.`))
+    try { this.rl?.close() } catch { /* ignore */ }
+    try { this.client.ws?.close?.() } catch { /* ignore */ }
+    this.replDone?.()
+  }
+
+  async onLine(line) {
+    if (this.quitting) return
+    const trimmed = line.trim()
+
+    // 1. Pending approval prompt captures the next line.
+    if (this.pendingApproval) {
+      const resolver = this.pendingApproval.resolve
+      await resolver(trimmed)
+      this.rl.prompt()
+      return
+    }
+    // 2. Pending session-pick prompt captures the next line.
+    if (this.pendingPick) {
+      const resolver = this.pendingPick.resolve
+      await resolver(trimmed)
+      this.rl.prompt()
+      return
+    }
+    // 3. Slash commands.
+    if (trimmed.startsWith('/')) {
+      const keepGoing = await this.handleSlash(trimmed)
+      if (!keepGoing) {
+        this.shutdown()
+        return
+      }
+      this.rl.prompt()
+      return
+    }
+    // 4. Empty line → just re-prompt.
+    if (!trimmed) {
+      this.rl.prompt()
+      return
+    }
+    // 5. A chat turn. The prompt is suppressed while the agent streams;
+    //    the 'done' event re-prompts via finishTurn().
+    if (this.turnActive) {
+      console.log(C.dim('(agent is still running — /stop to interrupt)'))
+      this.rl.prompt()
+      return
+    }
+    this.rl.pause()
+    try {
+      await this.runTurn(trimmed)
+    } catch (error) {
+      console.log(C.red(`Error: ${errorMessage(error)}`))
+      if (!this.client.connected) {
+        try {
+          await this.client.reconnect()
+          this.unsubscribe?.()
+          this.unsubscribe = this.client.onEvent((frame) => this.handleFrame(frame))
+          console.log(C.dim('reconnected.'))
+        } catch {
+          console.log(C.red('reconnect failed — exiting.'))
+          this.quitting = true
+          this.rl.close()
+          process.exit(1)
+        }
+      }
+    }
+    this.rl.resume()
+    this.rl.prompt()
+  }
+}
+
 // ── commands ────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -420,7 +1040,16 @@ async function main() {
       case 'chat': {
         const sessionId = positional[1]
         const message = positional.slice(2).join(' ')
-        if (!sessionId || !message) fail('chat needs: rterm chat <sessionId> <message>')
+        if (!sessionId) {
+          // Interactive persistent chat (the desktop-style experience).
+          // chat.start() resolves only when the REPL shuts down.
+          const pclient = new PersistentClient(url, token)
+          await pclient.connect()
+          const chat = new InteractiveChat(pclient, flags)
+          await chat.start()
+          process.exit(0)
+        }
+        if (!message) fail('chat needs: rterm chat <sessionId> <message>  (or "rterm chat" for interactive mode)')
         printJson(await client.call('agent:startTask', { sessionId, userInput: message }))
         break
       }