dsh-code 1.0.3 → 1.0.5

package/src/index.ts

@@ -12,7 +12,7 @@
 import { randomUUID } from 'node:crypto'
 import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { mkdir, rm, stat, writeFile as writeFileAsync } from 'node:fs/promises'
+import { appendFile as appendFileAsync, mkdir, rm, stat, writeFile as writeFileAsync } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 import { createElement } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
@@ -33,11 +33,12 @@ import type {} from '@deepseek-ai/cordis-plugin-loader'
 import type {} from '@deepseek-ai/dsh-cmdline'
 import { App, type NoticeTone } from './app.ts'
 import { mountApprovalAnswerer, type ApprovalStore } from './approval.ts'
-import { isSlashLine, watchCommands, type CommandsView } from './commands.ts'
+import { isSlashLine, submissionPayload, watchCommands, type CommandsView } from './commands.ts'
 import { internals, type TuiMount } from './internals.ts'
 import { syncModelCapabilities } from './model-capabilities.ts'
 import { buildModelSelection, applyModelSelectionToConfig, loadModelDirectory, modelSelectionLabel, resolveEffectiveSelection, type ModelRow } from './models.ts'
 import {
+  discoverProviderModels,
   loadProviderSettings,
   removeProviderSettings,
   saveProviderCredential,
@@ -47,10 +48,13 @@ import {
 } from './provider-settings.ts'
 import { createMentions, type MentionsApi } from './mentions.ts'
 import { mountQuestionProvider, type QuestionStore } from './questions.ts'
+// Type-only import merges the settings Events declarations ('settings/updated',
+// 'settings/document-updated') into this program's Cordis bus typing.
+import type {} from '@deepseek-ai/dsh-settings'
 import { createTranscriptStore, type TranscriptStore } from './store.ts'
 import { createSubagentFeed, type SubagentFeedView } from './subagents.ts'
 import { parseStatuslineItems } from './render/status.ts'
-import { HISTORY_MAX_ENTRIES, parseHistoryFile, serializeHistoryList } from './history.ts'
+import { historyLine, HISTORY_MAX_ENTRIES, needsCompaction, parseHistoryFile, serializeHistoryList } from './history.ts'
 import { watchSkills, type SkillsView } from './skills.ts'
 import { toolArgumentsPreview } from './render/tool-preview.ts'
 import { buildExportMarkdown } from './render/export.ts'
@@ -69,7 +73,7 @@ import { selectForkSeed } from './fork.ts'
 import { buildReviewPrompt, loadGitDiff } from './git-workflow.ts'
 import type { TuiStartup } from './startup.ts'
 import { SessionSwitchQueue } from './session-switch.ts'
-import { agentPresetsFrom, resolvePreset, selectPreset } from './presets.ts'
+import { agentPresetsFrom, normalizePresetId, resolvePreset, selectPreset } from './presets.ts'
 import {
   applyPendingPermission,
   cyclePermission as cyclePermissionPreset,
@@ -93,7 +97,7 @@ import {
   type SessionQueryService,
   type SessionRow,
 } from './session-directory.ts'
-import { createUserSettingsPersistence } from './settings-file.ts'
+import { createUserSettingsPersistence, writeFileAtomically } from './settings-file.ts'
 
 /** Stable Cordis plugin name. */
 export const name = 'tui-runner'
@@ -243,6 +247,48 @@ export async function runQuitSequence(
   return started
 }
 
+/** One composer submission waiting behind the startup delivery. */
+export interface QueuedSubmission {
+  readonly text: string
+  readonly mode: 'followup' | 'steer'
+  readonly images: readonly ImageBlock[]
+}
+
+/**
+ * Order-preserving gate for composer input while the startup prompt/images
+ * are still preparing. Anything submitted before the startup delivery settles
+ * queues and flushes afterwards in submit order, so the initial request can
+ * never be overtaken by typing that raced a slow image preparation. The flush
+ * also runs when the startup delivery fails: user input is never stranded.
+ */
+export class StartupInputGate {
+  private readonly queued: QueuedSubmission[] = []
+  private pending = false
+  constructor(private readonly deliver: (submission: QueuedSubmission) => void) {}
+
+  /** Submit one line: delivered now while idle, queued behind the startup delivery otherwise. */
+  submit(submission: QueuedSubmission): void {
+    if (this.pending) this.queued.push(submission)
+    else this.deliver(submission)
+  }
+
+  /**
+   * Run the startup delivery — the callback receives the direct-delivery sink
+   * for the startup prompt itself — then flush everything that queued behind
+   * it, in order, even when the callback rejects.
+   */
+  async run(startup: (deliver: (submission: QueuedSubmission) => void) => Promise<void>): Promise<void> {
+    this.pending = true
+    try {
+      await startup(submission => this.deliver(submission))
+    } finally {
+      this.pending = false
+      const queued = this.queued.splice(0)
+      for (const submission of queued) this.deliver(submission)
+    }
+  }
+}
+
 /**
  * Resolve the invocation's target session against the persisted headers.
  * @param startup - the parsed startup flags.
@@ -363,7 +409,9 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       ? {}
       : { picked: pendingSelection }
     let mode = next.resume ? next.mode : next.mode ?? pendingMode
-    if (!next.resume) mode = (await presets.resolve(mode)).id
+    // An explicit `--mode` or the settings-layer service default may still name
+    // an id an upstream rename retired (code → ptc); normalize both.
+    if (!next.resume) mode = (await presets.resolve(normalizePresetId(mode ?? presets.defaultId))).id
     const setup = async (agentCtx: Context): Promise<void> => {
       const sessionPreset = next.resume
         ? resolvePreset(agentCtx.agent!.session)
@@ -414,7 +462,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       handle,
       agent: handle.agent,
       session,
-      store: createTranscriptStore(session.events),
+      store: createTranscriptStore(session.snapshotEvents()),
       mentions: createMentions(ctx, handle.agent, session.header.cwd ?? nextCwd),
       mode: mode ?? 'standard',
       selection: selectionState,
@@ -505,7 +553,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   const commands: CommandsView = watchCommands(ctx)
   if (agent !== undefined) commands.setAgent(agent)
 
-  const skills: SkillsView = watchSkills(ctx)
+  const skills: SkillsView = watchSkills(ctx, cwd)
   if (agent !== undefined) skills.setAgent(agent)
 
   // Approval answerer: renders the ask as a y/n bar; only this TUI's agent is
@@ -530,19 +578,30 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     const subject = payload.agent
     const header = subject.session.header
     if (header.parentSession === undefined && header.origin !== 'subagent') return next()
+    // Only the ACTIVE session's explicit pick may steer a subagent request.
+    // During a switch window the old agent can still be mid-flight; routing
+    // it by the NEW session's pick sent one of its requests to the wrong
+    // model. A subject outside the active tree falls back to its own request
+    // header (plus any explicit /subagent override, which is user intent).
+    const activeAgent = active
+    const belongsToActive = activeAgent !== undefined
+      && (header.parentSession ?? subject.session.id) === activeAgent.session.id
     const picked = subagentOverride
       ?? resolveEffectiveSelection(
-        active?.selection.picked ?? pendingSelection,
+        belongsToActive && activeAgent !== undefined ? (activeAgent.selection.picked ?? pendingSelection) : undefined,
         subject.session.requestHeader()?.config,
         currentDefaults(),
       )
     return next().then(resolved => applyModelSelectionToConfig(resolved, picked))
   })
 
-  // ask_user_question provider: the single UI provider on the shared service,
-  // one request on screen at a time. Plan reviews (exit_plan_mode) arrive
-  // through this same pipe.
-  const questions: QuestionStore = mountQuestionProvider(ctx)
+  // ask_user_question answerer: one waterfall listener, one request on
+  // screen at a time. Plan reviews (exit_plan_mode) arrive through this same
+  // pipe; sibling answerers stay usable through the claim/defer split.
+  const questions: QuestionStore = mountQuestionProvider(
+    ctx,
+    candidate => agent !== undefined && candidate.id === agent.id,
+  )
 
   // The bridge the React app registers on mount: local notices from the
   // process side (unknown commands, switch confirmations, cancels).
@@ -645,22 +704,39 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   // recall is a convenience surface, never a gate.
   const historyPath = join(homedir(), '.dsh', 'dsh-code', 'history.jsonl')
   let inputHistory: readonly string[] = []
+  let historyWriteChain: Promise<void> = Promise.resolve()
   try {
-    inputHistory = parseHistoryFile(readFileSync(historyPath, 'utf8'))
+    const rawHistory = readFileSync(historyPath, 'utf8')
+    inputHistory = parseHistoryFile(rawHistory)
+    // Stale lines (adjacent duplicates, dropped garbage, an over-cap tail)
+    // accumulate in an append-only file; rewrite the canonical form once
+    // per boot. The rewrite rides the same chain, so it lands before any
+    // submission the user types next. An entry another terminal appends
+    // inside the read-to-rename window is dropped — a millisecond-scale
+    // gap at boot that recall tolerates by design.
+    if (needsCompaction(rawHistory)) {
+      historyWriteChain = historyWriteChain
+        .then(() => writeFileAtomically(historyPath, serializeHistoryList(inputHistory)))
+        .catch(() => {})
+    }
   } catch {
     inputHistory = []
   }
-  /** Serialized history writes: each submission rewrites the latest in-memory snapshot. */
-  let historyWriteChain: Promise<void> = Promise.resolve()
+  /**
+   * Serialized history writes: each submission appends one JSON line at the
+   * end of the file, so concurrent terminals add entries after each other
+   * instead of overwriting snapshots they read at their own boot. A
+   * multi-line draft still occupies one physical line (JSON escapes the
+   * newline), and a regular-length line reaches the disk as one positioned
+   * write; an oversized paste may interleave mid-line, which the next
+   * parse simply drops.
+   */
   const recordHistory = (text: string): void => {
     if (text === '') return
     inputHistory = [...inputHistory, text].slice(-HISTORY_MAX_ENTRIES)
-    // Write the whole current list, serialized per submission: the file is
-    // never read back on the submit path, so rapid same-process submissions
-    // cannot lose entries to a read-modify-write race.
     historyWriteChain = historyWriteChain
       .then(() => mkdir(dirname(historyPath), { recursive: true }))
-      .then(() => writeFileAsync(historyPath, serializeHistoryList(inputHistory), 'utf8'))
+      .then(() => appendFileAsync(historyPath, historyLine(text), 'utf8'))
       .catch((writeError: unknown) => {
         bridge.notify('history save failed: ' + (writeError instanceof Error ? writeError.message : String(writeError)), 'error')
       })
@@ -695,12 +771,18 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     off()
     for (const dispose of offCapabilitySync) dispose()
     if (capabilitySyncTimer !== undefined) clearTimeout(capabilitySyncTimer)
-    mountRef.current?.unmount()
     const currentSession = session
     const currentActive = active
     const report = (name: string, error: unknown): void => {
       internals.stderr.write(`dsh: quit ${name} failed: ${error instanceof Error ? error.message : String(error)}\n`)
     }
+    // A throwing unmount must not strand the terminal (stdin tap alive,
+    // keyboard protocol stacks unpopped) or skip the exit sequence below.
+    try {
+      mountRef.current?.unmount()
+    } catch (error: unknown) {
+      report('unmount', error)
+    }
     // One ordered cleanup: settle the visible session (if any — a bare launch
     // that never composed one resolves immediately), then wait for the final
     // in-flight composition (its work swallows errors and the quitting guard
@@ -770,6 +852,9 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     })
   }
 
+  /** Delivery serialization state: the chain's epoch pins it to one session. */
+  let deliveryChain: { epoch: number; tail: Promise<void> } = { epoch: 0, tail: Promise.resolve() }
+
   /** Deliver one trimmed line to the live session, expanding mentions first. */
   const deliverLine = (line: string, mode: 'followup' | 'steer', images: readonly ImageBlock[] = []): void => {
     const currentAgent = agent!
@@ -788,6 +873,15 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       bridge.notify(`invalid session reference: ${error instanceof Error ? error.message : String(error)}`, 'error')
       return
     }
+    // Ordered delivery: the inbox order IS the user's message order. A line
+    // with session mentions prepares asynchronously, and a later plain line
+    // used to deliver synchronously past it. Every line now waits for the
+    // previous line of the same session; an epoch change (switch/quit)
+    // abandons the chain instead of gating the next session on the old one.
+    if (deliveryChain.epoch !== epoch) deliveryChain = { epoch, tail: Promise.resolve() }
+    const enqueueDelivery = (run: () => void): void => {
+      deliveryChain.tail = deliveryChain.tail.then(run)
+    }
     const atEpoch = epoch
     const deliver = (readable: string, context?: UserMessage): void => {
       // A switch/quit landed while the snapshot was being prepared: never
@@ -818,19 +912,19 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       }
     }
     if (parsed.references.length === 0) {
-      deliver(parsed.text)
+      enqueueDelivery(() => deliver(parsed.text))
       return
     }
     const controller = new AbortController()
     pendingControllers.add(controller)
-    void currentMentions.prepare(parsed, controller.signal).then((prepared) => {
+    enqueueDelivery(() => currentMentions.prepare(parsed, controller.signal).then((prepared) => {
       pendingControllers.delete(controller)
       deliver(prepared.text, prepared.additionalContext)
     }, (error: unknown) => {
       pendingControllers.delete(controller)
       if (controller.signal.aborted || epoch !== atEpoch) return
       bridge.notify(`session reference failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
-    })
+    }))
   }
 
   // Deferred first-session creation for a bare launch: the session is composed
@@ -868,22 +962,45 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
           void next.handle.dispose().catch(() => {})
           return
         }
-        active = next
-        agent = next.agent
-        session = next.session
-        store = next.store
-        mentions = next.mentions
-        subagents.reset()
-        pendingMode = undefined
-        pendingPermission = undefined
-        commands.setAgent(agent)
-        skills.setAgent(agent)
-        // The App mounts with a placeholder key until the first input; the
-        // key-change remount below must start from a clean screen or the ghost
-        // static header stays visible above the new one (same source-backed
-        // clear the session-switch path performs).
-        process.stdout.write('\x1b[r\x1b[0m\x1b[H\x1b[2J\x1b[3J\x1b[H')
-        renderCurrent()
+        const previous = { active, agent, session, store, mentions }
+        try {
+          active = next
+          agent = next.agent
+          session = next.session
+          store = next.store
+          mentions = next.mentions
+          subagents.reset()
+          pendingMode = undefined
+          pendingPermission = undefined
+          commands.setAgent(agent)
+          skills.setAgent(agent)
+          // The App mounts with a placeholder key until the first input; the
+          // key-change remount below must start from a clean screen or the ghost
+          // static header stays visible above the new one (same source-backed
+          // clear the session-switch path performs).
+          process.stdout.write('\x1b[r\x1b[0m\x1b[H\x1b[2J\x1b[3J\x1b[H')
+          renderCurrent()
+        } catch (error: unknown) {
+          // The session composed but the screen handoff threw (stdout EPIPE,
+          // a render-time failure). Roll the published state back exactly
+          // like the switch path does — otherwise the runner reports "session
+          // creation failed" while the new session is actually live, clears
+          // the queued inputs, and every later line lands in the ghost. The
+          // queued inputs are KEPT for the next attempt.
+          active = previous.active
+          agent = previous.agent
+          session = previous.session
+          store = previous.store === undefined ? createTranscriptStore() : previous.store
+          mentions = previous.mentions === undefined ? createMentions(ctx, undefined, cwd) : previous.mentions
+          if (agent !== undefined) {
+            commands.setAgent(agent)
+            skills.setAgent(agent)
+          }
+          await next.handle.dispose().catch(() => {})
+          if (!quitting) renderCurrent()
+          bridge.notify(`session activation failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+          return
+        }
         abortPendingControllers()
         epoch += 1
         const queued = pendingInputs.splice(0)
@@ -898,9 +1015,11 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   }
 
   /** Deliver one readable line to the agent, expanding session mentions first. */
-  const send = (text: string, mode: 'followup' | 'steer', images: readonly ImageBlock[] = []): void => {
-    const line = text.trim()
-    if (line === '' && images.length === 0) return
+  const sendNow = (text: string, mode: 'followup' | 'steer', images: readonly ImageBlock[] = []): void => {
+    // Blank check on the trimmed form; the payload itself keeps the draft's
+    // exact whitespace unless the line is a syntactic slash command.
+    const line = submissionPayload(text)
+    if (line.trim() === '' && images.length === 0) return
     if (images.length === 0 && line.startsWith('/mode ')) {
       void switchModeAction(line.slice(6).trim()).then(
         selected => bridge.notify(`mode → ${selected}`),
@@ -925,6 +1044,13 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     deliverLine(line, mode, images)
   }
 
+  // Startup serialization: input submitted while the startup prompt/images
+  // are still preparing queues behind the initial request.
+  const inputGate = new StartupInputGate(({ text, mode, images }) => sendNow(text, mode, images))
+  const send = (text: string, mode: 'followup' | 'steer', images: readonly ImageBlock[] = []): void => {
+    inputGate.submit({ text, mode, images })
+  }
+
   /** Dispatch one submitted line: slash commands to the registry, other text to the agent. */
   const dispatch = (text: string, images: readonly ImageBlock[] = []): void => {
     send(text, 'followup', images)
@@ -1261,14 +1387,19 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       session = next.session
       store = next.store
       mentions = next.mentions
-      subagents.reset()
-      pendingMode = undefined
-      pendingPermission = undefined
       commands.setAgent(agent)
       skills.setAgent(agent)
       try {
         process.stdout.write('\x1b[r\x1b[0m\x1b[H\x1b[2J\x1b[3J\x1b[H')
         renderCurrent()
+        // Only a successful handoff may clear the transient per-session
+        // surfaces: a rolled-back switch keeps the previous session's
+        // subagent feed plus the user's pre-session /mode and permission
+        // picks (the bare-launch promise: explicit choices survive until
+        // composition takes them).
+        subagents.reset()
+        pendingMode = undefined
+        pendingPermission = undefined
       } catch (error: unknown) {
         active = previous
         agent = previous?.agent
@@ -1288,7 +1419,13 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       // No previous session (a bare launch switched straight into a resume):
       // nothing to flush or dispose, so just confirm the activation.
       if (previous === undefined) {
-        bridge.notify(`${next.resumed ? 'resumed' : 'created'} ${next.session.id.slice(-12)} · mode ${next.mode}`)
+        // The key-change remount above swaps the App in this same synchronous
+        // continuation; the new App registers its bridge.notify in a passive
+        // effect AFTER it, so an immediate notice reaches the UNMOUNTED
+        // instance and React drops it silently. Defer past the commit.
+        setTimeout(() => {
+          bridge.notify(`${next.resumed ? 'resumed' : 'created'} ${next.session.id.slice(-12)} · mode ${next.mode}`)
+        }, 0)
         return
       }
       let cleanupWarning: string | undefined
@@ -1371,11 +1508,13 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   }
 
   const reviewChanges = (argument: string): void => {
+    // Works from a bare launch too: with no session yet the read-only
+    // choice goes to pendingPermission (materialized when the first
+    // session composes) and the review prompt queues behind that
+    // creation exactly like a typed first submission. The identity guard
+    // below still aborts a load that outlives a mid-flight switch —
+    // including one landing on an undefined agent.
     const currentAgent = agent
-    if (currentAgent === undefined) {
-      bridge.notify('no session yet - submit a message to start', 'warning')
-      return
-    }
     // The diff loads from the CALLING session's cwd; capture that
     // workspace and this turn's identity so a switch mid-load can neither
     // flip the new session read-only nor send the old workspace's review
@@ -1417,7 +1556,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       if (text !== '' && (!Number.isSafeInteger(atSeq) || (atSeq ?? -1) < 0)) {
         throw new Error('usage: /fork [event-seq]')
       }
-      const seed = selectForkSeed(session.events, atSeq)
+      const seed = selectForkSeed(session.snapshotEvents(), atSeq)
       const id = `session-${randomUUID()}`
       requestSwitch({
         target: {
@@ -1483,7 +1622,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       branch: gitBranch(sessionCwd),
       sessionId: session === undefined ? '' : session.id.slice(-8),
       resumed: active?.resumed ?? false,
-      mode: active?.mode ?? pendingMode ?? presets.defaultId,
+      mode: active?.mode ?? pendingMode ?? normalizePresetId(presets.defaultId),
       permission,
       dispatch,
       steer,
@@ -1494,6 +1633,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       subscribeModelProviders: listener => subscribeProviderSettings(ctx, listener),
       saveModelProviderCredential: (target, key) => saveProviderCredential(ctx, target, key),
       saveModelProviderConfiguration: (target, configuration) => saveProviderConfiguration(ctx, target, configuration),
+      discoverModelProvider: (target, request, signal) => discoverProviderModels(ctx, target, request, signal),
       unsetModelProviderCredential: target => unsetProviderCredential(ctx, target),
       removeModelProvider: target => removeProviderSettings(ctx, target),
       loadProviderAuthorizations: () => loadProviderAuthorizations(ctx),
@@ -1557,18 +1697,20 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   mountRef.current = io.mount(appElement())
 
   // Startup prompt/images use the same durable delivery path as composer
-  // submissions. Image bytes are committed before the user/message event.
+  // submissions. Image bytes are committed before the user/message event, and
+  // input typed during that preparation queues behind the initial request so
+  // the agent always receives the startup prompt first.
   if (startup.prompt !== undefined || (startup.images?.length ?? 0) > 0) {
     if ((startup.images?.length ?? 0) > 0) {
       bridge.notify(`processing ${startup.images!.length} startup image${startup.images!.length === 1 ? '' : 's'}…`)
     }
-    void saveImagePaths(startup.images ?? [], ctx.get('attachments')).then(
-      images => {
-        if (images.length > 0) bridge.notify(`${images.length} startup image${images.length === 1 ? '' : 's'} attached`)
-        send(startup.prompt ?? '', 'followup', images)
-      },
-      (error: unknown) => bridge.notify(`initial prompt failed: ${error instanceof Error ? error.message : String(error)}`, 'error'),
-    )
+    void inputGate.run(async deliver => {
+      const images = await saveImagePaths(startup.images ?? [], ctx.get('attachments'))
+      if (images.length > 0) bridge.notify(`${images.length} startup image${images.length === 1 ? '' : 's'} attached`)
+      deliver({ text: startup.prompt ?? '', mode: 'followup', images })
+    }).catch((error: unknown) => {
+      bridge.notify(`initial prompt failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+    })
   }
 
   async function copyLastResponse(): Promise<string> {

package/src/input-split.ts

@@ -0,0 +1,191 @@
+/**
+ * Terminal input arrives as byte chunks, and one chunk can carry several
+ * keypresses: a fast space-then-enter, a bridged stdin that batches reads, a
+ * middle-click paste. Ink parses each chunk as exactly one keypress —
+ * `parseKeypress(' \r')` matches neither member, so both keys silently
+ * vanish (a multi-select question answered with an empty set). The splitter
+ * below cuts every chunk into the individual keypress units Ink's parser
+ * expects, keeping escape sequences and bracketed-paste blocks intact, and
+ * the stdin proxy feeds the split stream to the Ink mount.
+ *
+ * @module @deepseek-ai/dsh-tui/input-split
+ */
+
+import { PassThrough } from 'node:stream'
+import { PASTE_BRACKET_TIMEOUT_MS } from './keyboard.ts'
+
+/** Bracketed-paste wrapper bytes; the whole block travels as one unit. */
+const PASTE_START = '\x1b[200~'
+const PASTE_END = '\x1b[201~'
+
+/** One keypress cut from the input stream. */
+export interface KeypressSplitter {
+  /** Feed one chunk; returns every keypress unit this chunk completed. */
+  push(chunk: string): string[]
+  /** Whether an unterminated bracketed-paste block is currently held. */
+  openPaste(): boolean
+  /**
+   * Last-resort escape hatch for a paste whose end marker never arrived:
+   * drop the start marker and emit the held bytes as plain keypress units so
+   * nothing (Esc and Ctrl+C included) stays hostage. Inert when no paste is
+   * open.
+   */
+  releaseStalePaste(): string[]
+}
+
+/** Final byte of a CSI sequence (\x40-\x7e per ECMA-48). */
+const isCsiFinal = (char: string): boolean => char >= '@' && char <= '~'
+
+/**
+ * Build a stateful chunk splitter. A partial unit at the end of one chunk
+ * (a cut CSI sequence, an open paste block) waits in the buffer for the
+ * rest. A chunk-trailing lone ESC emits as the Escape key right away:
+ * terminals send Escape as its own chunk, and holding it hostage for a
+ * sequence that may never continue would break every Esc cancel.
+ */
+export function createKeypressSplitter(): KeypressSplitter {
+  let buffer = ''
+  const push = (chunk: string): string[] => {
+      buffer += chunk
+      const units: string[] = []
+      while (buffer !== '') {
+        // A bracketed paste block is display text, not keypresses: keep the
+        // whole wrapper plus its payload as the single unit the composer
+        // expects, even when the payload contains ESC-looking bytes.
+        if (buffer.startsWith(PASTE_START)) {
+          const end = buffer.indexOf(PASTE_END, PASTE_START.length)
+          if (end < 0) break
+          const stop = end + PASTE_END.length
+          units.push(buffer.slice(0, stop))
+          buffer = buffer.slice(stop)
+          continue
+        }
+        const head = buffer[0]!
+        if (head !== '\x1b') {
+          // Plain bytes key one at a time; a surrogate pair is one grapheme
+          // and must not split into two lone surrogates.
+          const pair = head >= '\uD800' && head <= '\uDBFF' && buffer[1] !== undefined
+          const take = pair ? 2 : 1
+          units.push(buffer.slice(0, take))
+          buffer = buffer.slice(take)
+          continue
+        }
+        // CSI (\x1b[…final) and SS3 (\x1bO<char): hold until complete.
+        if (buffer[1] === '[') {
+          let end = -1
+          for (let at = 2; at < buffer.length; at += 1) {
+            if (isCsiFinal(buffer[at]!)) {
+              end = at
+              break
+            }
+          }
+          if (end < 0) break
+          units.push(buffer.slice(0, end + 1))
+          buffer = buffer.slice(end + 1)
+          continue
+        }
+        if (buffer[1] === 'O') {
+          if (buffer[2] === undefined) break
+          units.push(buffer.slice(0, 3))
+          buffer = buffer.slice(3)
+          continue
+        }
+        if (buffer[1] === undefined) {
+          // Lone ESC: Escape key (see the tradeoff above).
+          units.push(buffer)
+          buffer = ''
+          continue
+        }
+        // Alt+key: ESC glued to one more byte travels as one unit.
+        units.push(buffer.slice(0, 2))
+        buffer = buffer.slice(2)
+      }
+      return units
+    }
+  return {
+    push,
+    openPaste(): boolean {
+      return buffer.startsWith(PASTE_START)
+    },
+    releaseStalePaste(): string[] {
+      if (!buffer.startsWith(PASTE_START)) return []
+      // Strip the unterminated start marker, then re-run the unit loop: the
+      // held bytes flow as ordinary keypresses under all the normal rules.
+      buffer = buffer.slice(PASTE_START.length)
+      return push('')
+    },
+  }
+}
+
+
+/** The stdin-shaped stream the Ink mount renders through. */
+export interface TuiStdin extends PassThrough {
+  /** Mirrors the real stdin so Ink's raw-mode gate passes. */
+  isTTY: boolean
+  /** Forwarded to the real stdin; Ink toggles it around focus. */
+  setRawMode(value: boolean): unknown
+  ref(): void
+  unref(): void
+}
+
+/**
+ * Wrap one real stdin in the splitting proxy: keypress units flow into a
+ * PassThrough Ink reads, while raw-mode/ref calls forward to the source.
+ * @param source - the process (or harness) input stream in raw mode.
+ * @returns the proxy stream plus a dispose that detaches the tap.
+ */
+export function createSplitStdin(source: NodeJS.ReadStream): { stdin: TuiStdin; dispose(): void } {
+  // Object mode matters: a plain stream's read() without a size drains the
+  // whole buffer as one chunk, which would re-coalesce the units this module
+  // exists to separate. In object mode every pushed unit reads back alone.
+  const stream = new PassThrough({ objectMode: true }) as TuiStdin
+  const splitter = createKeypressSplitter()
+  let stalePasteTimer: ReturnType<typeof setTimeout> | undefined
+  const disarmStalePasteTimer = (): void => {
+    if (stalePasteTimer === undefined) return
+    clearTimeout(stalePasteTimer)
+    stalePasteTimer = undefined
+  }
+  // A terminal that drops the end marker must not swallow every following
+  // keypress forever: past the shared paste window the held block is released
+  // as plain text, keeping Esc/Ctrl+C reachable. The App-level paste flag has
+  // its own reset net with the same window, but it can only see markers that
+  // reach Ink — this one guards the bytes that never do.
+  const armStalePasteTimer = (): void => {
+    if (stalePasteTimer !== undefined || !splitter.openPaste()) return
+    stalePasteTimer = setTimeout(() => {
+      stalePasteTimer = undefined
+      for (const unit of splitter.releaseStalePaste()) stream.write(unit)
+      armStalePasteTimer()
+    }, PASTE_BRACKET_TIMEOUT_MS)
+    stalePasteTimer.unref?.()
+  }
+  const onChunk = (chunk: string): void => {
+    for (const unit of splitter.push(String(chunk))) stream.write(unit)
+    if (splitter.openPaste()) armStalePasteTimer()
+    else disarmStalePasteTimer()
+  }
+  const proxy = Object.assign(stream, {
+    isTTY: source.isTTY === true,
+    setRawMode(value: boolean): TuiStdin {
+      source.setRawMode?.(value)
+      return stream
+    },
+    ref(): void {
+      source.ref?.()
+    },
+    unref(): void {
+      source.unref?.()
+    },
+  })
+  source.setEncoding('utf8')
+  source.on('data', onChunk)
+  return {
+    stdin: proxy,
+    dispose(): void {
+      disarmStalePasteTimer()
+      source.removeListener('data', onChunk)
+      source.pause()
+    },
+  }
+}