dsh-code 0.6.1 → 0.8.0

package/src/render/text.ts

@@ -3,8 +3,11 @@
  * tool payloads, skill descriptions). Control characters — including ANSI
  * CSI/OSC escape sequences — would otherwise pass through Ink into the
  * terminal, letting output rewrite the screen or inject prompts. Newlines
- * and tabs survive; everything else in C0/C1 plus DEL becomes a visible
- * `\xNN` escape.
+ * survive; everything else in C0/C1 plus DEL becomes a visible `\xNN`
+ * escape, and bidi overrides / invisible format controls / Unicode line and
+ * paragraph separators become a visible `\uXXXX` escape (terminal emulators
+ * that render bidirectional text would otherwise reorder the displayed
+ * glyphs and let a command read as something it is not).
  *
  * @module @deepseek-ai/dsh-code/render/text
  */
@@ -13,14 +16,27 @@
 const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu
 
 /**
- * Escape control characters so externally sourced text cannot drive the
- * terminal.
+ * Bidi overrides and isolates (U+202A-202E, U+2066-2069), the Arabic Letter
+ * Mark (U+061C), directional and zero-width format characters (U+200B,
+ * U+200E/200F, U+2060-2064, U+FEFF), and Unicode line/paragraph separators
+ * (U+2028/2029). Terminal emulators with bidi support (Windows Terminal,
+ * iTerm2, kitty, WezTerm) reorder or hide these, so they must never reach
+ * the terminal raw.
+ */
+const INVISIBLE_ESCAPE = /[\u061c\u200b\u200e\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u206f\ufeff]/gu
+
+/**
+ * Escape control and deceptive characters so externally sourced text cannot
+ * drive the terminal. C0/C1/DEL render as a literal `\xNN` escape; bidi,
+ * invisible-format, and separator controls render as a literal `\uXXXX`
+ * escape. Newlines and tabs survive (budgeted callers normalize tabs).
  * @param text - raw text from a session event, tool payload, or catalog.
- * @returns text with every control character (except `\n`, `\t`) rendered
- * as a literal `\xNN` escape.
+ * @returns display-safe text with every injectable character made visible.
  */
 export function displayText(text: string): string {
-  return text.replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
+  return text
+    .replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
+    .replace(INVISIBLE_ESCAPE, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)
 }
 
 /** Collapse external text to one terminal-safe logical row. */
@@ -84,7 +100,10 @@ function previousCharacter(text: string, end: number): { char: string; start: nu
  * Keep only the newest display-safe text that fits a terminal rectangle.
  * The scan walks backward and stops as soon as the suffix is full, so a long
  * reasoning stream does not rescan its entire accumulated prefix per chunk.
- * Explicit newlines and terminal wrapping both consume rows.
+ * Explicit newlines and terminal wrapping both consume rows; tabs expand to
+ * two spaces so terminal tab stops (which render at contextual column 8
+ * boundaries, not at the budgeted cell count) cannot inflate the physical
+ * row count of the live region.
  * @param text - raw externally sourced text.
  * @param columns - available terminal columns.
  * @param rows - available terminal rows.
@@ -109,7 +128,7 @@ export function displayTail(text: string, columns: number, rows: number): Displa
       continue
     }
 
-    const safe = displayText(previous.char)
+    const safe = previous.char === '\t' ? '  ' : displayText(previous.char)
     const width = cellWidth(safe)
     if (used > 0 && used + width > columnLimit) {
       if (row >= rowLimit) break

package/src/render/tool-detail.ts

@@ -17,6 +17,9 @@ const MAX_READ_LINES = 120
 const MAX_SOURCES = 10
 const MAX_RAW_CHARS = 6000
 const MAX_LINE_COLUMNS = 240
+/** Hard caps on adversarial `tool/result.meta` before any row is built. */
+const MAX_DIFFS = 8
+const MAX_DIFF_TEXT_CHARS = 24_000
 
 /** One rendered diff row: removed, added, or shared context. */
 export interface DiffLine {
@@ -77,15 +80,32 @@ function toLines(text: string): string[] {
  * Render one change as removed-then-added rows, hunked by common prefix and
  * suffix. A null before-image (file create) renders as pure additions. The
  * budget caps emitted rows and reports the cut, so a whole-file overwrite
- * never floods the transcript.
+ * never floods the transcript. Inputs are hard-capped before line splitting
+ * and the row list is built incrementally up to the budget — a crafted or
+ * replayed giant diff cannot force a full intermediate rows array.
  * @param oldText - prior content, or null for a create.
  * @param newText - content after the change.
  * @param budget - maximum rows to emit.
  * @returns the bounded rows and whether they were cut.
  */
 export function diffRows(oldText: string | null, newText: string, budget: number): { lines: readonly DiffLine[]; truncated: boolean } {
-  const oldLines = oldText === null ? [] : toLines(oldText)
-  const newLines = toLines(newText)
+  const oldRaw = oldText ?? ''
+  const newRaw = newText
+  let inputTruncated = false
+  let oldSource = oldRaw
+  let newSource = newRaw
+  // Bound the working arrays before `toLines` allocates them: keep a
+  // combined-characters share of each side proportional to its input size.
+  const combined = oldRaw.length + newRaw.length
+  if (combined > MAX_DIFF_TEXT_CHARS) {
+    inputTruncated = true
+    const oldShare = Math.min(oldRaw.length, Math.floor(MAX_DIFF_TEXT_CHARS * oldRaw.length / combined))
+    const newShare = Math.min(newRaw.length, MAX_DIFF_TEXT_CHARS - oldShare)
+    oldSource = oldRaw.slice(0, oldShare)
+    newSource = newRaw.slice(0, newShare)
+  }
+  const oldLines = oldText === null ? [] : toLines(oldSource)
+  const newLines = toLines(newSource)
   let prefix = 0
   while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix += 1
   let suffix = 0
@@ -93,14 +113,20 @@ export function diffRows(oldText: string | null, newText: string, budget: number
     suffix < oldLines.length - prefix && suffix < newLines.length - prefix
     && oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
   ) suffix += 1
-  const removed = oldLines.slice(prefix, oldLines.length - suffix)
-  const added = newLines.slice(prefix, newLines.length - suffix)
-  const rows: DiffLine[] = [
-    ...removed.map((text): DiffLine => ({ mark: '-', text: clipLine(text) })),
-    ...added.map((text): DiffLine => ({ mark: '+', text: clipLine(text) })),
-  ]
-  if (rows.length <= budget) return { lines: rows, truncated: false }
-  return { lines: rows.slice(0, budget), truncated: true }
+  const removedCount = oldLines.length - prefix - suffix
+  const addedCount = newLines.length - prefix - suffix
+  const truncated = inputTruncated || removedCount + addedCount > budget
+  // Build at most `budget` rows directly; never materialize the full hunk.
+  const rows: DiffLine[] = []
+  const removedLimit = Math.min(removedCount, Math.max(0, budget))
+  for (let index = 0; index < removedLimit; index += 1) {
+    rows.push({ mark: '-', text: clipLine(oldLines[prefix + index] ?? '') })
+  }
+  const addedLimit = Math.min(addedCount, Math.max(0, budget - removedLimit))
+  for (let index = 0; index < addedLimit; index += 1) {
+    rows.push({ mark: '+', text: clipLine(newLines[prefix + index] ?? '') })
+  }
+  return { lines: rows, truncated }
 }
 
 /** Whether `value` is a valid upstream FileDiff (defensive narrowing). */
@@ -140,45 +166,60 @@ export function toolResultDetail(meta: unknown, rawText: string): ToolDetail | u
     const record = meta as Record<string, unknown>
 
     const diffs = record['diffs']
-    if (Array.isArray(diffs) && diffs.length > 0 && diffs.every(isFileDiff)) {
-      const budget = Math.max(8, Math.floor(MAX_DIFF_LINES / diffs.length))
-      return {
-        kind: 'diff',
-        diffs: diffs.map(diff => ({
-          path: diff.path,
-          ...diffRows(diff.oldText, diff.newText, budget),
-        })),
+    // Validate and process only the capped prefix: an adversarial meta with
+    // thousands of diffs never runs `.every` over the full array.
+    if (Array.isArray(diffs) && diffs.length > 0) {
+      const capped = diffs.slice(0, MAX_DIFFS)
+      if (capped.every(isFileDiff)) {
+        const budget = Math.max(8, Math.floor(MAX_DIFF_LINES / capped.length))
+        // Diffs dropped beyond the cap must not vanish silently: the last
+        // kept diff reports the cut exactly like a hunk cut does.
+        const dropped = diffs.length > capped.length
+        const rendered = capped.map((diff, index) => {
+          const rows = diffRows(diff.oldText, diff.newText, budget)
+          return dropped && index === capped.length - 1
+            ? { path: diff.path, ...rows, truncated: true }
+            : { path: diff.path, ...rows }
+        })
+        return { kind: 'diff', diffs: rendered }
       }
     }
 
     const { path, offset, lines, totalLines } = record
     if (typeof path === 'string' && Number.isInteger(offset) && (offset as number) >= 1
       && Number.isInteger(totalLines) && (totalLines as number) >= 0
-      && Array.isArray(lines) && lines.every(isReadLine)) {
-      const window = lines as { number: number; text: string }[]
-      const truncated = window.length > MAX_READ_LINES
-      return {
-        kind: 'read',
-        path,
-        offset: offset as number,
-        lines: (truncated ? window.slice(0, MAX_READ_LINES) : window)
-          .map(line => ({ number: line.number, text: clipLine(line.text) })),
-        totalLines: totalLines as number,
-        truncated,
+      && Array.isArray(lines)) {
+      // Validate the bounded window only: lines beyond the display cap are
+      // dropped anyway, so a giant persisted window cannot force a full-array
+      // validation pass before the slice.
+      const window = lines.slice(0, MAX_READ_LINES)
+      if (window.every(isReadLine)) {
+        const truncated = lines.length > MAX_READ_LINES
+        return {
+          kind: 'read',
+          path,
+          offset: offset as number,
+          lines: window.map(line => ({ number: line.number, text: clipLine(line.text) })),
+          totalLines: totalLines as number,
+          truncated,
+        }
       }
     }
 
     const sources = record['sources']
-    if (Array.isArray(sources) && sources.every(isWebSource)) {
-      const truncated = sources.length > MAX_SOURCES
-      return {
-        kind: 'web-search',
-        sources: (truncated ? sources.slice(0, MAX_SOURCES) : sources).map(source => ({
-          url: source.url,
-          title: typeof source.title === 'string' ? source.title : undefined,
-          snippet: typeof source.snippet === 'string' ? clipLine(source.snippet) : '',
-        })),
-        truncated,
+    if (Array.isArray(sources)) {
+      const capped = sources.slice(0, MAX_SOURCES)
+      if (capped.every(isWebSource)) {
+        const truncated = sources.length > MAX_SOURCES
+        return {
+          kind: 'web-search',
+          sources: capped.map(source => ({
+            url: source.url,
+            title: typeof source.title === 'string' ? source.title : undefined,
+            snippet: typeof source.snippet === 'string' ? clipLine(source.snippet) : '',
+          })),
+          truncated,
+        }
       }
     }
 

package/src/render/tool-preview.ts

@@ -2,7 +2,10 @@
  * Bounded preview line for a tool invocation's raw JSON arguments: the first
  * human-meaningful string among the well-known keys (command, path, query, …)
  * with a fallback to the bounded raw JSON. Shared by the tool card in the
- * transcript and the approval bar's command preview.
+ * transcript and the approval bar's command preview. Arguments longer than
+ * {@link MAX_PARSE_CHARS} are never parsed: the preview is a display concern,
+ * and a synchronous `JSON.parse` plus string copies of an unbounded model
+ * payload must not run on the approval or projection paths.
  *
  * @module @deepseek-ai/dsh-code/render/tool-preview
  */
@@ -10,6 +13,18 @@
 /** Keys searched in declaration order when building a preview. */
 const PREVIEW_KEYS = ['command', 'cmd', 'description', 'path', 'pattern', 'query'] as const
 
+/**
+ * Raw arguments longer than this are skipped without parsing and fall back
+ * to the bounded raw preview. Well above any realistic command/path/query
+ * string while keeping the synchronous parse cost negligible.
+ */
+const MAX_PARSE_CHARS = 4096
+
+/** Bounded raw-arguments fallback shared by the skip-parse and parse-failure paths. */
+function boundedRawPreview(args: string): string {
+  return args.length > 80 ? `${args.slice(0, 77)}...` : args
+}
+
 /**
  * Resolve one bounded preview for raw tool arguments.
  * @param args - raw JSON arguments string as the model produced it.
@@ -18,6 +33,7 @@ const PREVIEW_KEYS = ['command', 'cmd', 'description', 'path', 'pattern', 'query
  */
 export function toolArgumentsPreview(args: string, toolName: string): string {
   if (args === '') return toolName
+  if (args.length > MAX_PARSE_CHARS) return boundedRawPreview(args)
   try {
     const parsed: unknown = JSON.parse(args)
     if (parsed !== null && typeof parsed === 'object') {
@@ -30,5 +46,5 @@ export function toolArgumentsPreview(args: string, toolName: string): string {
   } catch {
     // Raw JSON parse failed: fall through to the bounded raw arguments.
   }
-  return args.length > 80 ? `${args.slice(0, 77)}...` : args
+  return boundedRawPreview(args)
 }

package/src/session-directory.ts

@@ -53,21 +53,60 @@ export interface SessionRow {
   readonly title?: string
 }
 
-function samePath(left: string | undefined, right: string): boolean {
+/** Case-insensitive filesystems (Windows, macOS) compare paths by lowercased form. */
+const CASE_INSENSITIVE_FS = process.platform === 'win32' || process.platform === 'darwin'
+
+/** True when the header describes a subagent conversation (durable lineage). */
+export function isSubagentSession(header: SessionHeader): boolean {
+  return header.origin === 'subagent' || header.parentSession !== undefined
+}
+
+function comparablePath(value: string): string {
+  const resolved = resolve(value)
+  return CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved
+}
+
+/** Platform-consistent path equality for session cwd comparisons. */
+export function samePath(left: string | undefined, right: string): boolean {
   if (left === undefined) return false
-  return resolve(left).toLowerCase() === resolve(right).toLowerCase()
+  return comparablePath(left) === comparablePath(right)
+}
+
+/**
+ * Unique header match by exact id or unique id prefix (root and subagent
+ * headers alike); the caller applies any lineage gate.
+ * @param headers - the persisted headers.
+ * @param wanted - the id or id prefix.
+ * @returns the uniquely matched header.
+ * @throws when nothing matches or the prefix is ambiguous.
+ */
+export function matchSessionId(headers: readonly SessionHeader[], wanted: string): SessionHeader {
+  const exact = headers.filter(header => header.id === wanted)
+  const matches = exact.length > 0 ? exact : headers.filter(header => header.id.startsWith(wanted))
+  if (matches.length === 0) throw new Error(`no persisted session matches "${wanted}"`)
+  if (matches.length > 1) {
+    throw new Error(`session prefix "${wanted}" is ambiguous (${matches.length} matches): use more of the id`)
+  }
+  return matches[0]!
+}
+
+/** The newest persisted ROOT session pinned to this cwd, or undefined. */
+export function newestRootForCwd(headers: readonly SessionHeader[], cwd: string): SessionHeader | undefined {
+  const local = headers
+    .filter(header => !isSubagentSession(header) && samePath(header.cwd, cwd))
+    .sort((left, right) => right.createdAt - left.createdAt)
+  return local[0]
 }
 
 /** Filter/sort header-only records. No session log is loaded here. */
 export function projectSessionRows(records: readonly SessionRecord[], options: SessionDirectoryOptions): SessionRow[] {
   const needle = options.query.trim().toLowerCase()
   return records
-    .filter(record => options.sessions === 'all'
-      || (record.header.parentSession === undefined && record.header.origin !== 'subagent'))
+    .filter(record => options.sessions === 'all' || !isSubagentSession(record.header))
     .filter(record => options.cwd === 'all' || samePath(record.header.cwd, options.currentCwd))
     .map(record => {
       const cwd = record.header.cwd ?? ''
-      const subagent = record.header.origin === 'subagent' || record.header.parentSession !== undefined
+      const subagent = isSubagentSession(record.header)
       return {
         id: record.header.id,
         createdAt: record.header.createdAt,

package/src/skills.ts

@@ -69,12 +69,15 @@ export function watchSkills(ctx: Context): SkillsWatch {
   const listeners = new Set<() => void>()
 
   const reload = (): void => {
-    const currentAgent = agent
-    if (skills === undefined || currentAgent === undefined) return
+    const target = agent
+    if (skills === undefined || target === undefined) return
     Promise.resolve().then(() => skills.list({
-      cwd: currentAgent.session.header.cwd,
-      scope: currentAgent,
+      cwd: target.session.header.cwd,
+      scope: target,
     })).then((summaries: readonly SkillSummary[]) => {
+      // A retarget landed while this catalog was loading: the rows belong to
+      // another agent's workspace and must never overwrite the current view.
+      if (agent !== target) return
       const next = toRows(summaries)
       const unchanged = next.length === rows.length && next.every((row, index) => row.name === rows[index]?.name)
       rows = next
@@ -83,6 +86,7 @@ export function watchSkills(ctx: Context): SkillsWatch {
       if (unchanged && !recovered) return
       for (const listener of listeners) listener()
     }).catch((cause: unknown) => {
+      if (agent !== target) return
       // Discovery failure keeps the last good rows; the next skills/change
       // notification is the retry surface (mirrors the web directory).
       rows = [...rows]

package/src/startup.ts

@@ -1,109 +1,119 @@
-/**
- * The interactive terminal app's command-line provider: parses `--resume`,
- * `--continue`, `--session`, `--mode`, and `--help`, then publishes
- * {@link TUI_STARTUP_SERVICE} for the runner to consume lazily. Follows the
- * headless bundle's startup shape (a commander action publishing a service
- * through {@link parseCmdline}).
- *
- * Semantics:
- * - `--resume <id|prefix>` — continue the persisted session whose id or unique
- *   id-prefix matches; the TUI replays its transcript and appends to the same
- *   durable log.
- * - `--continue` / `-c` — resume the most recently modified persisted session
- *   whose project directory matches the current working directory.
- * - `--session <id>` — create a new session under an explicit identity (the
- *   id must not exist yet).
- * - no flags — a fresh session with a minted id.
- *
- * @module @deepseek-ai/dsh-tui/startup
- */
-
-import { Command } from 'commander'
-import type { Context } from '@deepseek-ai/cordis'
-import { parseCmdline } from '@deepseek-ai/dsh-cmdline'
-
-/** Stable Cordis plugin name. */
-export const name = 'tui-startup'
-
-/** Services required before the invocation can be resolved. */
-export const inject = ['cmdlineArgs']
-
-/** Service provided by this plugin and injected by the terminal runner. */
-export const TUI_STARTUP_SERVICE = 'tuiStartup'
-
-/** How the runner obtains its session identity. */
-export type TuiStartup =
-  | { readonly kind: 'fresh'; readonly mode?: string }
-  | { readonly kind: 'named'; readonly sessionId: string; readonly mode?: string }
-  | { readonly kind: 'resume'; readonly sessionId: string }
-  | { readonly kind: 'latest' }
-
-export interface TuiStartupOptions {
-  readonly resume?: string
-  readonly continue?: boolean
-  readonly session?: string
-  readonly mode?: string
-}
-
-/** Pure option policy shared by Commander and tests. */
-export function resolveTuiStartup(options: TuiStartupOptions): TuiStartup {
-  const selected = [options.resume !== undefined, options.continue === true, options.session !== undefined]
-  if (selected.filter(Boolean).length > 1) throw new Error('--resume, --continue, and --session are mutually exclusive')
-  if (options.session === '') throw new Error('--session needs an id')
-  if (options.resume === '') throw new Error('--resume needs a session id or id prefix')
-  if (options.mode === '') throw new Error('--mode needs a preset id')
-  if (options.mode !== undefined && (options.resume !== undefined || options.continue === true)) {
-    throw new Error('--mode applies only to a new session; it cannot be combined with --resume or --continue')
-  }
-  return options.resume !== undefined
-    ? { kind: 'resume', sessionId: options.resume }
-    : options.continue === true
-      ? { kind: 'latest' }
-      : options.session !== undefined
-        ? { kind: 'named', sessionId: options.session, ...options.mode === undefined ? {} : { mode: options.mode } }
-        : { kind: 'fresh', ...options.mode === undefined ? {} : { mode: options.mode } }
-}
-
-/**
- * This app's command: the launcher's flags this app owns, its description,
- * and its help text.
- * @returns a fresh program, so one process can parse more than once (tests).
- */
-function tuiCommand(): Command {
-  return new Command()
-    .name('dsh --profile cli')
-    .description('Claude-Code-style interactive terminal for DeepSeek Harness.')
-    .helpOption('-h, --help', 'show this help')
-    .option('-r, --resume <session>', 'resume the persisted session with this id (or unique id prefix)')
-    .option('-c, --continue', 'resume the most recent persisted session for this working directory')
-    .option('--session <id>', 'create a new session under this explicit id')
-    .option('--mode <preset>', 'agent preset for a newly created session')
-    .addHelpText('after', `
-Examples:
-  dsh --profile cli                       fresh session, minted id
-  dsh --profile cli --resume abc123       resume session by id prefix
-  dsh --profile cli --continue            resume the latest local session
-  dsh --profile cli --mode minimal        fresh session using the minimal preset
-`)
-}
-
-/**
- * Parse the invocation and publish the startup service. Mutual exclusions are
- * usage errors rejected from the action before anything is provided.
- * @param ctx - plugin context carrying the command line and exit request.
- */
-export function apply(ctx: Context): void {
-  const program = tuiCommand()
-  program.action(() => {
-    const options = program.opts<TuiStartupOptions>()
-    let startup: TuiStartup | undefined
-    try {
-      startup = resolveTuiStartup(options)
-    } catch (error: unknown) {
-      program.error(`error: ${error instanceof Error ? error.message : String(error)}`)
-    }
-    if (startup === undefined) return
-    ctx.provide(TUI_STARTUP_SERVICE, { startup } satisfies { startup: TuiStartup })
-  })
-  parseCmdline(ctx, program)
-}
+/**
+ * The interactive terminal app's command-line provider: parses `--resume`,
+ * `--continue`, `--session`, `--mode`, `--theme`, and `--help`, then
+ * publishes {@link TUI_STARTUP_SERVICE} for the runner to consume lazily.
+ * Follows the headless bundle's startup shape (a commander action publishing
+ * a service through {@link parseCmdline}).
+ *
+ * Semantics:
+ * - `--resume <id|prefix>` — continue the persisted session whose id or unique
+ *   id-prefix matches; the TUI replays its transcript and appends to the same
+ *   durable log.
+ * - `--continue` / `-c` — resume the most recently modified persisted session
+ *   whose project directory matches the current working directory.
+ * - `--session <id>` — create a new session under an explicit identity (the
+ *   id must not exist yet).
+ * - `--theme <dark|light|auto>` — the color palette; auto follows the
+ *   terminal (dark fallback until OSC-11 detection lands).
+ * - no flags — a fresh session with a minted id.
+ *
+ * @module @deepseek-ai/dsh-tui/startup
+ */
+
+import { Command } from 'commander'
+import type { Context } from '@deepseek-ai/cordis'
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline'
+import { THEME_NAMES, type ThemeName } from './theme.ts'
+
+/** Stable Cordis plugin name. */
+export const name = 'tui-startup'
+
+/** Services required before the invocation can be resolved. */
+export const inject = ['cmdlineArgs']
+
+/** Service provided by this plugin and injected by the terminal runner. */
+export const TUI_STARTUP_SERVICE = 'tuiStartup'
+
+/** How the runner obtains its session identity. */
+export type TuiStartup =
+  | { readonly kind: 'fresh'; readonly mode?: string; readonly theme?: ThemeName }
+  | { readonly kind: 'named'; readonly sessionId: string; readonly mode?: string; readonly theme?: ThemeName }
+  | { readonly kind: 'resume'; readonly sessionId: string; readonly theme?: ThemeName }
+  | { readonly kind: 'latest'; readonly theme?: ThemeName }
+
+export interface TuiStartupOptions {
+  readonly resume?: string
+  readonly continue?: boolean
+  readonly session?: string
+  readonly mode?: string
+  readonly theme?: ThemeName
+}
+
+/** Pure option policy shared by Commander and tests. */
+export function resolveTuiStartup(options: TuiStartupOptions): TuiStartup {
+  const selected = [options.resume !== undefined, options.continue === true, options.session !== undefined]
+  if (selected.filter(Boolean).length > 1) throw new Error('--resume, --continue, and --session are mutually exclusive')
+  if (options.session === '') throw new Error('--session needs an id')
+  if (options.resume === '') throw new Error('--resume needs a session id or id prefix')
+  if (options.mode === '') throw new Error('--mode needs a preset id')
+  if (options.mode !== undefined && (options.resume !== undefined || options.continue === true)) {
+    throw new Error('--mode applies only to a new session; it cannot be combined with --resume or --continue')
+  }
+  if (options.theme !== undefined && !THEME_NAMES.includes(options.theme)) {
+    throw new Error('--theme must be dark, light, or auto')
+  }
+  const theme = options.theme === undefined ? {} : { theme: options.theme }
+  return options.resume !== undefined
+    ? { kind: 'resume', sessionId: options.resume, ...theme }
+    : options.continue === true
+      ? { kind: 'latest', ...theme }
+      : options.session !== undefined
+        ? { kind: 'named', sessionId: options.session, ...options.mode === undefined ? {} : { mode: options.mode }, ...theme }
+        : { kind: 'fresh', ...options.mode === undefined ? {} : { mode: options.mode }, ...theme }
+}
+
+/**
+ * This app's command: the launcher's flags this app owns, its description,
+ * and its help text.
+ * @returns a fresh program, so one process can parse more than once (tests).
+ */
+function tuiCommand(): Command {
+  return new Command()
+    .name('dsh --profile cli')
+    .description('Claude-Code-style interactive terminal for DeepSeek Harness.')
+    .helpOption('-h, --help', 'show this help')
+    .option('-r, --resume <session>', 'resume the persisted session with this id (or unique id prefix)')
+    .option('-c, --continue', 'resume the most recent persisted session for this working directory')
+    .option('--session <id>', 'create a new session under this explicit id')
+    .option('--mode <preset>', 'agent preset for a newly created session')
+    .option('--theme <name>', 'color theme: dark (default), light, or auto')
+    .addHelpText('after', `
+Examples:
+  dsh --profile cli                       fresh session, minted id
+  dsh --profile cli --resume abc123       resume session by id prefix
+  dsh --profile cli --continue            resume the latest local session
+  dsh --profile cli --mode minimal        fresh session using the minimal preset
+  dsh --profile cli --theme light         light palette for bright terminals
+`)
+}
+
+/**
+ * Parse the invocation and publish the startup service. Mutual exclusions are
+ * usage errors rejected from the action before anything is provided.
+ * @param ctx - plugin context carrying the command line and exit request.
+ */
+export function apply(ctx: Context): void {
+  const program = tuiCommand()
+  program.action(() => {
+    const options = program.opts<TuiStartupOptions>()
+    let startup: TuiStartup | undefined
+    try {
+      startup = resolveTuiStartup(options)
+    } catch (error: unknown) {
+      program.error(`error: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (startup === undefined) return
+    ctx.provide(TUI_STARTUP_SERVICE, { startup } satisfies { startup: TuiStartup })
+  })
+  parseCmdline(ctx, program)
+}