dsh-code 1.2.0 → 1.4.0

package/src/index.ts

@@ -10,29 +10,49 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { appendFile as appendFileAsync, mkdir, readdir, rm, stat, writeFile as writeFileAsync } from 'node:fs/promises'
-import { basename, dirname, join } from 'node:path'
+import { writeFile as writeFileAsync } from 'node:fs/promises'
+import { basename, join } from 'node:path'
 import { createElement } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { installModelSelection } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentHandle, AgentStatus, Inbox, ModelSelection, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, ModelSelection, ModelSelectionRef } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-agent-default-model'
 import type {} from '@deepseek-ai/dsh-attachment'
-import { createUserMessage, MessageId, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import { createUserMessage, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { JobSnapshot } from '@deepseek-ai/dsh-jobs'
-import { SessionId, SessionLogOffset, type Session, type SessionEvent, type SessionHeader, type UserMessage } from '@deepseek-ai/dsh-session'
+import { SessionId, SessionLogOffset, type Session, type SessionEvent, type UserMessage } from '@deepseek-ai/dsh-session'
 import { deriveTurnTokenUsage } from '@deepseek-ai/dsh-token-meter/client'
-import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 // Type-only: carries the ctx.sessionTitle service merge for /title.
 import type {} from '@deepseek-ai/dsh-session-title'
 // Empty type imports carry the loader Context merge for the settlement await
 // and the cmdline Context merge for the appExit host value.
 import type {} from '@deepseek-ai/cordis-plugin-loader'
 import type {} from '@deepseek-ai/dsh-cmdline'
-import { App, type NoticeTone, type QueueMutation } from './app.ts'
+import { App } from './app.ts'
+import type { NoticeTone, QueueMutation } from './ui/ui-contract.ts'
+import { planCycleDecision } from './runner/mode-cycle.ts'
+export { planCycleDecision, type ModeCycleDecision } from './runner/mode-cycle.ts'
+import { runQuitSequence, type QuitCleanupStep } from './runner/quit.ts'
+export { runQuitSequence, type QuitCleanupStep } from './runner/quit.ts'
+import { exportSessionIdSuffix, resolveTarget, type Target } from './runner/session-target.ts'
+export { exportSessionIdSuffix, resolveTarget } from './runner/session-target.ts'
+import {
+  applyQueueMutation,
+  cancelPreservingQueue,
+  StartupInputGate,
+  submissionBelongsToSession,
+} from './runner/submissions.ts'
+export {
+  applyQueueMutation,
+  cancelPreservingQueue,
+  queueEditContent,
+  StartupInputGate,
+  submissionBelongsToSession,
+  type QueuedSubmission,
+  type QueueMutationOutcome,
+} from './runner/submissions.ts'
 import { mountApprovalAnswerer, type ApprovalStore } from './approval.ts'
 import { isSlashLine, submissionPayload, watchCommands, type CommandsView } from './commands.ts'
 import { internals, type TuiMount } from './internals.ts'
@@ -44,6 +64,7 @@ import {
   removeProviderSettings,
   saveProviderCredential,
   saveProviderConfiguration,
+  enableProviderSubscription,
   subscribeProviderSettings,
   unsetProviderCredential,
 } from './provider-settings.ts'
@@ -52,10 +73,10 @@ 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 { createTranscriptStore, type TranscriptStore } from './session/store.ts'
+import { createSubagentFeed, subagentCatalogSeed, type SubagentFeedView } from './session/subagents.ts'
+export { subagentCatalogSeed } from './session/subagents.ts'
 import { parseStatuslineItems } from './render/status.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'
@@ -70,7 +91,8 @@ import {
   openAuthorizationUrl,
   subscribeProviderAuthorizations,
 } from './authorization.ts'
-import { selectForkSeed } from './fork.ts'
+import { selectForkSeed } from './session/fork.ts'
+import { gitBranch } from './git-workflow.ts'
 import {
   buildReviewPrompt,
   listReviewBranches,
@@ -81,7 +103,7 @@ import {
   type ReviewSelection,
 } from './git-workflow.ts'
 import type { TuiStartup } from './startup.ts'
-import { SessionSwitchQueue } from './session-switch.ts'
+import { SessionSwitchQueue } from './session/session-switch.ts'
 import { agentPresetsFrom, normalizePresetId, resolvePreset, selectPreset } from './presets.ts'
 import {
   applyPendingPermission,
@@ -97,21 +119,18 @@ import { parseThemeName, setTheme, type ThemeName } from './theme.ts'
 import { parseLanguageName, setLanguage, t, type LanguageName } from './i18n.ts'
 import {
   isSubagentSession,
-  matchSessionId,
-  mergeSessionTitles,
-  newestRootForCwd,
-  isSessionArtifactName,
-  jsonlSessionRoot,
-  planSessionDeletion,
-  projectSessionRows,
-  sessionArtifactDirectory,
-  sessionDirectoryFor,
-  type SessionDirectoryOptions,
   type SessionQueryService,
   type SessionRow,
-} from './session-directory.ts'
-import type { JobRow, SearchRow } from './kernel-panels.ts'
-import { createUserSettingsPersistence, writeFileAtomically } from './settings-file.ts'
+} from './session/session-directory.ts'
+import type { JobRow } from './panels/kernel-panels.ts'
+import { searchHitToRow, type SearchRow } from './runner/search-rows.ts'
+export { searchHitToRow } from './runner/search-rows.ts'
+import { createUserSettingsPersistence } from './settings-file.ts'
+import { preferencePath, readPreference, savePreference } from './runner/preferences.ts'
+import { createInputHistory } from './runner/input-history.ts'
+import { createSessionIo } from './runner/session-io.ts'
+import { EXPECTED_HARNESS_VERSION, probeRunningHarness, requireHarnessVersion } from './runner/harness-gate.ts'
+import { resolveStartupConfig } from './runner/startup-config.ts'
 import { turnUsages, type UsageView } from './render/usage.ts'
 // Type-only import: merges the projection registry into the Context type so
 // `ctx.get('sessionProjections')` is typed (the service itself is mounted by
@@ -181,373 +200,16 @@ function listJobs(ctx: Context, caller: Agent | undefined): readonly JobRow[] {
   }
 }
 
-/**
- * Read one user-level settings file as a plain object. The callers all treat a
- * missing file as "unset" and a corrupt one as "warn and fall back", so this
- * helper owns the one distinction they share: readable JSON that is not an
- * object is corruption, not an absent preference, and must not surface as a
- * cryptic property access on `null`.
- * @param path - absolute path of the settings file.
- * @returns the parsed object; the caller narrows each field itself.
- */
-function readSettingsObject(path: string): Record<string, unknown> {
-  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`${basename(path)} must contain a JSON object`)
-  }
-  return parsed as Record<string, unknown>
-}
-
-/**
- * Resolve the working directory's git branch for the status line.
- * @param cwd - the session's working directory.
- * @returns the branch name, or '' outside a repository or on a detached HEAD.
- */
-function gitBranch(cwd: string): string {
-  try {
-    const ref = readFileSync(join(cwd, '.git', 'HEAD'), 'utf8').trim().match(/^ref: refs\/heads\/(.+)$/)
-    return ref?.[1] ?? ''
-  } catch {
-    // Only the single HEAD read is attempted, so the sole reachable failure is
-    // a missing repository (or unreadable HEAD file): the branch group drops out.
-    return ''
-  }
-}
-
-/** The session identity this invocation will run, plus whether it is resumed. */
-interface Target {
-  sessionId: string
-  resume: boolean
-  mode?: string
-  cwd?: string
-  seed?: readonly SessionEvent[]
-  parentSession?: SessionId
-  /** Marks the session as a subagent conversation in the durable header. */
-  origin?: 'subagent'
-  seedLength?: number
-}
-
-/**
- * Reduce a session id to a filename-safe /export default-name suffix. Session
- * ids are normally minted `session-<uuid>`, but `--session` accepts arbitrary
- * user text: path separators must never leak into the default export filename
- * (which would escape the session cwd).
- * @param id - the session id.
- * @returns at most the last 8 filename-safe characters.
- */
-export function exportSessionIdSuffix(id: string): string {
-  return id.replace(/[^a-zA-Z0-9._-]/gu, '_').slice(-8)
-}
-
-/** One ordered step of the terminal quit cleanup. */
-export interface QuitCleanupStep {
-  /** Step label used in diagnostics and tests. */
-  readonly name: string
-  /** The step's async work; a rejection is contained by the sequence. */
-  readonly run: () => Promise<void>
-}
-
-/**
- * Run the ordered quit cleanup, then request exit. Every step rejection is
- * contained (reported through `onError`) so a failed flush or dispose never
- * skips the remaining cleanup; the exit request is always reached exactly
- * once.
- * @param steps - the cleanup steps in dependency order (settle the visible
- * session, await the final in-flight composition, await durable recall).
- * @param exit - the terminal exit request (code 0).
- * @param onError - optional failure sink; called once per failing step and
- * itself contained, so a throwing sink cannot abort the sequence.
- * @returns the names of the steps that started, in order (for tests).
- */
-export async function runQuitSequence(
-  steps: readonly QuitCleanupStep[],
-  exit: (code: number) => void,
-  onError?: (name: string, error: unknown) => void,
-): Promise<readonly string[]> {
-  const started: string[] = []
-  for (const step of steps) {
-    started.push(step.name)
-    try {
-      await step.run()
-    } catch (error) {
-      try {
-        onError?.(step.name, error)
-      } catch {
-        // The failure sink must never abort the cleanup sequence.
-      }
-    }
-  }
-  try {
-    exit(0)
-  } catch {
-    // The exit request itself must not become an unhandled rejection.
-  }
-  return started
-}
 
-/** One composer submission waiting behind the startup delivery. */
-export interface QueuedSubmission {
-  readonly text: string
-  /** `steer` inserts into the running turn; `followup` waits for the next one. */
-  readonly mode: 'followup' | 'steer'
-  readonly images: readonly ContentBlock[]
-}
 
-/** What one requested queue mutation did; the runner maps it to one notice. */
-export type QueueMutationOutcome =
-  | 'removed'
-  | 'edited'
-  | 'steered'
-  | 'unavailable'
-  | 'empty'
-  | 'steerUnavailable'
 
-/**
- * Replace one queued message's text while keeping its attachments. A queue
- * edit rewrites what the user typed, not what they attached: image and file
- * blocks ride through in delivery order (text first, then attachments, the
- * shape {@link deliverLine} submits). Dropping them here would silently strip
- * an attachment the user already confirmed, so this is the edit's single
- * definition and the panel's read-only marker only mirrors it.
- */
-export function queueEditContent(content: readonly ContentBlock[], text: string): ContentBlock[] {
-  const attachments = content.filter(block => block.type !== 'text')
-  return [{ type: 'text', text }, ...attachments]
-}
 
-/**
- * Apply one terminal queue mutation to the live inbox. The decision and the
- * inbox change are pure over the supplied handles so every branch is testable
- * without an agent; steering itself is injected because it wakes the driver
- * rather than mutating the inbox. The durable inbox splices remain the UI's
- * single source of truth — this helper never reports a state the inbox did not
- * actually reach.
- * @param inbox - the live agent inbox (pending lists plus its mutators).
- * @param status - the agent's lifecycle status; steering needs `running`.
- * @param messageId - identity of the queued message to mutate.
- * @param action - the requested mutation.
- * @param steer - submits the removed message as next-step steering.
- * @returns the outcome the caller reports.
- */
-export function applyQueueMutation(
-  inbox: Pick<Inbox, 'nextTurn' | 'append' | 'remove' | 'replace'>,
-  status: AgentStatus,
-  messageId: string,
-  action: QueueMutation,
-  steer: (message: UserMessage) => void,
-): QueueMutationOutcome {
-  const id = MessageId(messageId)
-  const message = inbox.nextTurn.find(candidate => candidate.id === id)
-  if (message === undefined) return 'unavailable'
-  switch (action.kind) {
-    case 'remove':
-      return inbox.remove(id) ? 'removed' : 'unavailable'
-    case 'edit':
-      if (action.text.trim() === '') return 'empty'
-      inbox.replace(id, createUserMessage({
-        content: queueEditContent(message.content, action.text),
-        source: message.source,
-      }))
-      return 'edited'
-    case 'steer':
-      if (status !== 'running') return 'steerUnavailable'
-      // Steer promotes the message out of next-turn, so a failing submit must
-      // put it back: the row the user was looking at never just disappears.
-      if (!inbox.remove(id)) return 'unavailable'
-      try {
-        steer(message)
-      } catch (error: unknown) {
-        inbox.append('next-turn', message)
-        throw error
-      }
-      return 'steered'
-  }
-}
 
-/**
- * Cancel the active turn while keeping the next-turn queue, then wake the
- * driver again so the preserved messages actually run. `cancel` clears
- * pending work by default and never wakes the driver on its own, so the queue
- * is captured first and re-submitted afterwards: a waking submission latches
- * the wake while the aborted activity converges to idle, which is what turns
- * "preserved" into "sent next" instead of "parked forever". Next-step
- * steering is deliberately dropped — it belonged to the cancelled turn.
- * @param agent - the live agent handle.
- * @returns how many queued messages were preserved across the abort.
- */
-export function cancelPreservingQueue(agent: Pick<Agent, 'inbox' | 'cancel' | 'followup'>): number {
-  const queued = [...agent.inbox.nextTurn]
-  agent.cancel({ kind: 'user' })
-  for (const message of queued) agent.followup(message)
-  return queued.length
-}
 
-/**
- * Whether a tagged submission still belongs to the active session. Attachment
- * prepares resolve on the microtask timeline, while a queued session switch
- * remounts the app asynchronously — the composing instance's unmount cleanup
- * runs too late to abort, so the delivery itself carries the composing
- * session's full id and the runner drops it here when the world moved on.
- * An untagged (synchronous) or pending-session ('') submission always passes.
- */
-export function submissionBelongsToSession(origin: string | undefined, activeSessionId: string | undefined): boolean {
-  return origin === undefined || origin === '' || origin === activeSessionId
-}
 
-/**
- * Root-log catalog facts a resumed session must replay into the subagent
- * feed: constructor seeds never fire on the live bus, so without this the
- * children of a resumed session vanish behind a restart. The empty-child
- * placeholder row (childId '') is a placeholder, not a child, and stays out.
- */
-export function subagentCatalogSeed(events: readonly SessionEvent[]): readonly SessionEvent<'subagent/catalog'>[] {
-  return events.filter((event): event is SessionEvent<'subagent/catalog'> =>
-    event.type === 'subagent/catalog' && event.data.childId !== '')
-}
 
-/**
- * Map one cross-session full-text hit onto the /search panel's row (pure).
- * Labels fall back to the short id form — the engine's hit carries the
- * strongest matching event, not the title observation.
- */
-export function searchHitToRow(hit: {
-  header: SessionHeader
-  bestMatch: { snippet: string; time: number }
-}): SearchRow {
-  const subagent = hit.header.origin === 'subagent'
-  const cwd = hit.header.cwd ?? ''
-  // Session cwds may arrive in either separator style regardless of the
-  // observing host (a workspace synced from Windows), so split on both.
-  const workspace = cwd.split(/[\\/]/u).filter(part => part !== '').at(-1) ?? ''
-  const preset = hit.header.agentPreset ?? ''
-  const flat = hit.bestMatch.snippet.replace(/\s+/gu, ' ').trim()
-  return {
-    id: hit.header.id,
-    label: hit.header.id.slice(-12),
-    detail: [workspace, preset].filter(part => part !== '').join(' · '),
-    snippet: flat.length > 158 ? `${flat.slice(0, 157)}…` : flat,
-    updatedAt: hit.bestMatch.time,
-    subagent,
-    resumable: !subagent,
-  }
-}
 
-/** One Shift+Tab station decision for the mode cycle. */
-export type ModeCycleDecision =
-  | { readonly kind: 'permission'; readonly preset: string }
-  | { readonly kind: 'plan-on' }
-  | { readonly kind: 'plan-off'; readonly preset: string }
 
-/**
- * Decide the next Shift+Tab station. The cycle keeps the preset table's
- * own order (most restrictive first) and inserts ONE plan station between
- * the most restrictive preset and the wrap target: with the shipped three
- * presets the user sees workspace-write → danger-full-access → read-only
- * → plan → workspace-write. Plan IS the most restrictive preset plus the
- * plan prompt layer — entering it switches nothing (the cycle is already
- * parked on read-only), and leaving it lands on the next preset after the
- * most restrictive one. Without the /plan command the cycle is exactly the
- * preset table.
- *
- * `planIntent` covers the committed fold's commit lag: upstream queues a
- * plan switch during an open turn (and the command pipeline is async even
- * idle), so the durable plan/mode event lands AFTER the press that chose
- * it. While an intent from an earlier press is in flight it — not the
- * stale committed fold — decides the station, so repeated presses advance
- * the cycle instead of re-issuing the same plan transition (the stuck
- * plan-on/plan-off toggle). Undefined falls back to the committed fold.
- */
-export function planCycleDecision(input: {
-  readonly names: readonly string[]
-  readonly current: string
-  readonly inPlan: boolean
-  readonly planAvailable: boolean
-  readonly planIntent?: boolean
-}): ModeCycleDecision | undefined {
-  const names = input.names
-  if (names.length === 0) return undefined
-  const first = names[0]
-  if ((input.planIntent ?? input.inPlan) === true) return { kind: 'plan-off', preset: names[1] ?? first }
-  const at = names.indexOf(input.current)
-  if (at === 0 && input.planAvailable) return { kind: 'plan-on' }
-  return { kind: 'permission', preset: names[(at + 1) % names.length] ?? first }
-}
-
-/**
- * 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.
- * @param persistence - the persistence service; required for resume/latest.
- * @param cwd - the working directory `--continue` filters by.
- * @returns the target identity.
- * @throws with a user-facing message when the flags name nothing resolvable.
- */
-export async function resolveTarget(startup: TuiStartup, persistence: SessionPersistence | undefined, cwd: string): Promise<Target> {
-  if (startup.kind === 'fresh') return { sessionId: `session-${randomUUID()}`, resume: false, mode: startup.mode }
-  if (startup.kind === 'named') {
-    // The id must not exist yet: reject before any Agent composition when the
-    // backend can tell us (a live collision is still caught by the session
-    // store at create time).
-    if (persistence !== undefined) {
-      const headers: readonly SessionHeader[] = (await persistence.list()).map(snapshot => snapshot.header)
-      if (headers.some(header => header.id === startup.sessionId)) {
-        throw new Error(`session "${startup.sessionId}" already exists; use --resume to continue it`)
-      }
-    }
-    return { sessionId: startup.sessionId, resume: false, mode: startup.mode }
-  }
-  if (persistence === undefined) {
-    throw new Error('cannot resolve the requested session: session persistence is not configured')
-  }
-  const headers: readonly SessionHeader[] = (await persistence.list()).map(snapshot => snapshot.header)
-  if (startup.kind === 'resume') {
-    const matched = matchSessionId(headers, startup.sessionId)
-    // Subagent conversations are read-only everywhere else; the CLI must not
-    // be a back door into appending root turns to a child's durable log.
-    if (isSubagentSession(matched)) {
-      throw new Error('subagent conversations are read-only; resume a root session')
-    }
-    return { sessionId: matched.id, resume: true }
-  }
-  // --continue: the newest persisted ROOT session whose header pins this cwd.
-  const newest = newestRootForCwd(headers, cwd)
-  if (newest === undefined) throw new Error(`no persisted session for this directory (${cwd}); start one without --continue`)
-  return { sessionId: newest.id, resume: true }
-}
 
 /**
  * Resolve a bounded command preview for one pending approval: the request
@@ -941,17 +603,10 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   // /statusline persistence: one user-level JSON file under the DSH home.
   // Missing file means defaults; a corrupt file degrades to defaults with a
   // surfaced warning (the customization is user-authored, never silent).
-  const statuslinePath = join(homedir(), '.dsh', 'dsh-code', 'statusline.json')
-  let statuslineWarning: string | undefined
-  let statuslineItems: readonly string[] = []
-  try {
-    statuslineItems = parseStatuslineItems(readSettingsObject(statuslinePath).items)
-  } catch (error) {
-    statuslineItems = parseStatuslineItems(undefined)
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      statuslineWarning = error instanceof Error ? error.message : String(error)
-    }
-  }
+  const statuslinePath = preferencePath('statusline.json')
+  const statuslineRead = readPreference(statuslinePath, 'items', parseStatuslineItems)
+  const statuslineWarning: string | undefined = statuslineRead.warning
+  let statuslineItems: readonly string[] = statuslineRead.value ?? parseStatuslineItems(undefined)
   // Serialized, crash-atomic writes for the user-level JSON files: the chain
   // orders rapid consecutive saves (the LAST snapshot wins on disk), each
   // write goes through a sibling temp file + rename, and quit waits for the
@@ -959,10 +614,9 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   const settingsPersistence = createUserSettingsPersistence()
   const saveStatusline = (items: readonly string[]): void => {
     statuslineItems = [...items]
-    void settingsPersistence.save(statuslinePath, JSON.stringify({ items }, null, 2) + '\n')
-      .catch((writeError: unknown) => {
-        bridge.notify(t('notice.statuslineSaveFailed', { message: writeError instanceof Error ? writeError.message : String(writeError) }), 'error')
-      })
+    savePreference(settingsPersistence, statuslinePath, 'items', items, message => {
+      bridge.notify(t('notice.statuslineSaveFailed', { message }), 'error')
+    })
   }
 
   // /vscode-keys: detect the hosting editor's user keybindings.json and pass
@@ -971,7 +625,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   const editorKeysEnv: EditorKeysEnv = {
     env: process.env,
     paths: { homedir: homedir(), appdata: process.env.APPDATA, platform: process.platform },
-    flagPath: join(homedir(), '.dsh', 'dsh-code', 'editor-keys.json'),
+    flagPath: preferencePath('editor-keys.json'),
   }
   const applyEditorKeys = (): Promise<string> => applyCtrlRPassthrough(editorKeysEnv)
 
@@ -980,45 +634,36 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   // degrades to dark with a surfaced warning. Precedence: CLI --theme > file >
   // auto detection > dark (auto detection itself is a later enhancement and
   // currently falls back to dark inside theme.ts).
-  const themePath = join(homedir(), '.dsh', 'dsh-code', 'theme.json')
+  const themePath = preferencePath('theme.json')
   let themeWarning: string | undefined
   if (startup.theme === undefined) {
-    try {
-      setTheme(parseThemeName(readSettingsObject(themePath).theme))
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-        themeWarning = error instanceof Error ? error.message : String(error)
-      }
-    }
+    const read = readPreference(themePath, 'theme', parseThemeName)
+    themeWarning = read.warning
+    // A missing or corrupt file leaves theme.ts on its own dark default.
+    if (read.value !== undefined) setTheme(read.value)
   } else {
     setTheme(startup.theme)
   }
   const saveTheme = (name: ThemeName): void => {
     setTheme(name)
-    void settingsPersistence.save(themePath, JSON.stringify({ theme: name }, null, 2) + '\n')
-      .catch((writeError: unknown) => {
-        bridge.notify(t('notice.themeSaveFailed', { message: writeError instanceof Error ? writeError.message : String(writeError) }), 'error')
-      })
+    savePreference(settingsPersistence, themePath, 'theme', name, message => {
+      bridge.notify(t('notice.themeSaveFailed', { message }), 'error')
+    })
   }
 
   // /language persistence: one user-level JSON file beside theme.json. A
   // missing file means English; a corrupt file degrades to English with a
   // surfaced warning.
-  const languagePath = join(homedir(), '.dsh', 'dsh-code', 'language.json')
-  let languageWarning: string | undefined
-  try {
-    setLanguage(parseLanguageName(readSettingsObject(languagePath).language))
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      languageWarning = error instanceof Error ? error.message : String(error)
-    }
-  }
+  const languagePath = preferencePath('language.json')
+  const languageRead = readPreference(languagePath, 'language', parseLanguageName)
+  const languageWarning: string | undefined = languageRead.warning
+  // A missing or corrupt file leaves i18n on its own English default.
+  if (languageRead.value !== undefined) setLanguage(languageRead.value)
   const saveLanguage = (name: LanguageName): void => {
     setLanguage(name)
-    void settingsPersistence.save(languagePath, JSON.stringify({ language: name }, null, 2) + '\n')
-      .catch((writeError: unknown) => {
-        bridge.notify(t('notice.languageSaveFailed', { message: writeError instanceof Error ? writeError.message : String(writeError) }), 'error')
-      })
+    savePreference(settingsPersistence, languagePath, 'language', name, message => {
+      bridge.notify(t('notice.languageSaveFailed', { message }), 'error')
+    })
   }
 
   // /animation persistence: one user-level JSON file under the DSH home,
@@ -1026,68 +671,25 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   // corrupt file degrades to on with a surfaced warning. Only an explicit
   // `false` disables (parseAnimationsPref), so hand-edited or partial files
   // never silently freeze the UI.
-  const animationsPath = join(homedir(), '.dsh', 'dsh-code', 'animations.json')
-  let animationsEnabled = true
-  let animationsWarning: string | undefined
-  try {
-    // A literal `null` file reads as corruption and surfaces the warning the
-    // block above promises, instead of a property access on `null`.
-    animationsEnabled = parseAnimationsPref(readSettingsObject(animationsPath).animations)
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-      animationsWarning = error instanceof Error ? error.message : String(error)
-    }
-  }
+  const animationsPath = preferencePath('animations.json')
+  // A literal `null` file reads as corruption and surfaces a warning, instead
+  // of a property access on `null`.
+  const animationsRead = readPreference(animationsPath, 'animations', parseAnimationsPref)
+  const animationsWarning: string | undefined = animationsRead.warning
+  const animationsEnabled = animationsRead.value ?? true
   const saveAnimations = (enabled: boolean): void => {
-    void settingsPersistence.save(animationsPath, JSON.stringify({ animations: enabled }, null, 2) + '\n')
-      .catch((writeError: unknown) => {
-        bridge.notify(t('notice.animationsSaveFailed', { message: writeError instanceof Error ? writeError.message : String(writeError) }), 'error')
-      })
+    savePreference(settingsPersistence, animationsPath, 'animations', enabled, message => {
+      bridge.notify(t('notice.animationsSaveFailed', { message }), 'error')
+    })
   }
 
   // Global input recall (Codex composer-history contract): one JSONL file
   // under the DSH home. A missing file means an empty history; unreadable or
   // corrupt content degrades to the valid lines it could parse, silently —
   // 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 {
-    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 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)
-    historyWriteChain = historyWriteChain
-      .then(() => mkdir(dirname(historyPath), { recursive: true }))
-      .then(() => appendFileAsync(historyPath, historyLine(text), 'utf8'))
-      .catch((writeError: unknown) => {
-        bridge.notify(t('notice.historySaveFailed', { message: writeError instanceof Error ? writeError.message : String(writeError) }), 'error')
-      })
-  }
+  const inputHistory = createInputHistory(preferencePath('history.jsonl'), message => {
+    bridge.notify(t('notice.historySaveFailed', { message }), 'error')
+  })
 
   /** Mutate one next-turn inbox item; durable inbox splices remain the UI truth. */
   const updateQueued = (messageId: string, action: QueueMutation): void => {
@@ -1159,7 +761,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
           { name: 'dispose', run: () => currentActive.handle.dispose() },
         ]),
       { name: 'composing', run: () => composing ?? Promise.resolve() },
-      { name: 'history', run: () => historyWriteChain },
+      { name: 'history', run: () => inputHistory.flush() },
       { name: 'settings', run: () => settingsPersistence.flush() },
     ]
     void runQuitSequence(steps, io.exit, report)
@@ -1234,7 +836,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     try {
       parsed = currentMentions.parse(line)
     } catch (error: unknown) {
-      bridge.notify(`invalid session reference: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.invalidReference', { message: error instanceof Error ? error.message : String(error) }), 'error')
       return
     }
     // Ordered delivery: the inbox order IS the user's message order. A line
@@ -1269,7 +871,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
         if (mode === 'steer') currentAgent.steer(message)
         else currentAgent.followup(message)
       } catch (error: unknown) {
-        bridge.notify(`${mode === 'steer' ? 'steering' : 'message'} failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+        bridge.notify(t('notice.messageFailed', { kind: mode === 'steer' ? 'steering' : 'message', message: error instanceof Error ? error.message : String(error) }), 'error')
       }
     }
     if (parsed.references.length === 0) {
@@ -1287,7 +889,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       }, (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')
+        bridge.notify(t('notice.referenceFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
       })
     })
   }
@@ -1364,7 +966,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
           }
           await next.handle.dispose().catch(() => {})
           if (!quitting) renderCurrent()
-          bridge.notify(`session activation failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+          bridge.notify(t('notice.activationFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
           return
         }
         abortPendingControllers()
@@ -1383,7 +985,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       }
     }).catch((error: unknown) => {
       pendingInputs.length = 0
-      bridge.notify(`session creation failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.creationFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
     })
   }
 
@@ -1393,19 +995,27 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     // exact whitespace unless the line is a syntactic slash command.
     const line = submissionPayload(text)
     if (line.trim() === '' && images.length === 0) return
+    // A switch between the idle wait and the handoff keeps the OLD session
+    // installed: a line delivered now would start a turn the handoff discards.
+    // Refusing loudly beats losing it silently — the caller can retry after the
+    // switch, and `switchQueue.cancel()` is the way out.
+    if (switchQueue.activating) {
+      bridge.notify(t('notice.switchInProgress'), 'warning')
+      return
+    }
     if (images.length === 0 && line.startsWith('/mode ')) {
       void switchModeAction(line.slice(6).trim()).then(
-        selected => bridge.notify(`mode → ${selected}`),
-        error => bridge.notify(`mode switch failed: ${error instanceof Error ? error.message : String(error)}`, 'error'),
+        selected => bridge.notify(t('notice.modeChanged', { value: selected })),
+        error => bridge.notify(t('notice.modeChangeFailed', { message: error instanceof Error ? error.message : String(error) }), 'error'),
       )
       return
     }
     if (images.length === 0 && line.startsWith('/permission ')) {
       try {
         const selected = setPermissionAction(line.slice(12).trim())
-        bridge.notify(`permission → ${selected}`)
+        bridge.notify(t('notice.permissionChanged', { value: selected }))
       } catch (error: unknown) {
-        bridge.notify(`permission change failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+        bridge.notify(t('notice.permissionChangeFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
       }
       return
     }
@@ -1458,7 +1068,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       bridge.notify(t(preserved > 0 ? 'notice.turnCancelledKeepQueue' : 'notice.turnCancelled'))
       return true
     } catch (error: unknown) {
-      bridge.notify(`cancel failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.cancelFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
       return false
     }
   }
@@ -1491,7 +1101,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
    */
   const cycleMode = (): string => {
     if (permissionPresets === undefined || permissionPresets.names.length === 0) {
-      bridge.notify('permission presets are not mounted in this composition', 'warning')
+      bridge.notify(t('notice.permissionPresetsUnmounted'), 'warning')
       return ''
     }
     try {
@@ -1542,7 +1152,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       selectPermission(permissionPresets, session, decision.preset)
       return `plan → off · permission → ${decision.preset}`
     } catch (error: unknown) {
-      bridge.notify(`mode change failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.modeChangeFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
       return ''
     }
   }
@@ -1568,7 +1178,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     // it. Save failures degrade to a notice — the in-session switch already
     // took effect and must not roll back (the web contract).
     void defaultModel.saveSelection(selection).catch((error: unknown) => {
-      bridge.notify(`model switch applies to this session but was not saved as the default: ${error instanceof Error ? error.message : String(error)}`, 'warning')
+      bridge.notify(t('notice.modelNotDefault', { message: error instanceof Error ? error.message : String(error) }), 'warning')
     })
     // Advisory immediate validation (web selectModel parity): run the same
     // local resolveCallConfig check the request pipeline would, so a stale
@@ -1587,7 +1197,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
         model: selection.model,
         ...selection.reasoningEffort === undefined ? {} : { reasoningEffort: selection.reasoningEffort },
       })).catch((error: unknown) => {
-        bridge.notify(`model selection rejected: ${error instanceof Error ? error.message : String(error)} — reopen /model to pick again`, 'error')
+        bridge.notify(t('notice.modelSelectionRejected', { message: error instanceof Error ? error.message : String(error) }), 'error')
       })
     }
     return `${row.provider}/${row.model}`
@@ -1616,7 +1226,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
    */
   const exportTranscript = async (argument: string): Promise<void> => {
     if (session === undefined) {
-      bridge.notify('no session yet — submit a message to start', 'warning')
+      bridge.notify(t('notice.noSessionYet'), 'warning')
       return
     }
     const wanted = argument.trim()
@@ -1633,9 +1243,9 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     const markdown = buildExportMarkdown(store.getView(), session.id)
     try {
       await writeFileAsync(target, `${markdown}\n`, 'utf8')
-      bridge.notify(`exported to ${target}`)
+      bridge.notify(t('notice.exported', { path: target }))
     } catch (error: unknown) {
-      bridge.notify(`export failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.exportFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
     }
   }
 
@@ -1658,115 +1268,12 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
     }
   }
 
-  const loadSessions = async (options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]> => {
-    if (sessionQuery === undefined) throw new Error('session query is unavailable in this profile')
-    const records = await sessionQuery.listSessions(signal)
-    // Last-activity timestamps for sorting (codex UpdatedAt default): the
-    // newest generation artifact's mtime under the JSONL layout. 0.1.5 dropped
-    // the persistence `locate()` query, so paths are derived from the
-    // backend's public config root. Backends without a JSONL config (or
-    // vanished directories) fall back to createdAt inside the projection.
-    const root = jsonlSessionRoot(persistence)
-    const updated = new Map<string, number>()
-    if (root !== undefined) {
-      await Promise.all(records.map(async record => {
-        try {
-          const dir = sessionDirectoryFor(root, record.header.cwd, record.header.id)
-          const entries = await readdir(dir, { withFileTypes: true })
-          const stats = await Promise.all(
-            entries.filter(entry => entry.isFile() && isSessionArtifactName(entry.name))
-              .map(entry => stat(join(dir, entry.name))),
-          )
-          const newest = Math.max(...stats.map(info => info.mtimeMs))
-          if (Number.isFinite(newest)) updated.set(record.header.id, newest)
-        } catch {
-          // Artifact gone or unreadable: the projection falls back to createdAt.
-        }
-      }))
-    }
-    const projected = projectSessionRows(records, options, updated)
-    // Titles are the expensive fold. Fetch only the first bounded picker page;
-    // navigation/filter changes trigger a fresh, cancellable observation.
-    const page = projected.slice(0, 32)
-    if (page.length === 0) return projected
-    const observations = await sessionQuery.readTitleSnapshots(page.map(row => row.id), signal)
-    return mergeSessionTitles(projected, observations)
-  }
 
-  /**
-   * Delete one session subtree (/delete, codex semantics: subagent threads go
-   * with their root). The kernel persistence seam has NO deletion API by
-   * design — logs accumulate "until removed externally" — so this is the
-   * controlled external removal, in three phases with a hard boundary
-   * between planning and touching the filesystem:
-   *
-   * 1. `planSessionDeletion` collects the subtree and refuses when the root
-   *    or ANY member is live (a live child would outlive its deleted
-   *    parent), ordering the plan children-first.
-   * 2. Every plan node must derive to a guarded artifact directory
-   *    (`encodeSegment(id)` layout beneath the backend's config root).
-   *    Backends without a derivable artifact (non-JSONL) refuse the WHOLE
-   *    deletion here — no file has been touched yet, so a backend or layout
-   *    surprise can never strand a half-deleted subtree.
-   * 3. Artifacts are removed children-first: only an I/O error mid-delete
-   *    can stop it short (reported with removed/total counts), leaving the
-   *    shallowest lineage intact.
-   *
-   * @param id - the root session id to delete.
-   * @returns the outcome line for the panel/notice.
-   */
-  const deleteSession = async (id: string): Promise<string> => {
-    if (sessionQuery === undefined) return 'session query is unavailable in this profile'
-    if (session !== undefined && session.id === id) return 'cannot delete the session you are using — switch or /new first'
-    const records = await sessionQuery.listSessions()
-    const plan = planSessionDeletion(records, id)
-    if (!plan.ok) return plan.reason
-    // Phase 2 completes the plan before the first rm: derive and
-    // layout-check every node up front, so a refusal never leaves a
-    // partially removed subtree behind.
-    const root = jsonlSessionRoot(persistence)
-    if (root === undefined) {
-      return 'session backend exposes no deletable artifact (deletion is unsupported on this backend)'
-    }
-    const byId = new Map<string, (typeof records)[number]>(records.map(record => [record.header.id, record]))
-    const dirs = new Map<string, string>()
-    for (const node of plan.nodes) {
-      const record = byId.get(node.id)
-      if (record === undefined) return `no persisted session matches "${node.id}"`
-      const dir = sessionArtifactDirectory(sessionDirectoryFor(root, record.header.cwd, node.id), node.id)
-      if (dir === undefined) {
-        return `refusing to delete: unexpected artifact layout for ${node.id.slice(-12)}`
-      }
-      dirs.set(node.id, dir)
-    }
-    let removed = 0
-    for (const node of plan.nodes) {
-      const dir = dirs.get(node.id)!
-      try {
-        // Remove every canonical generation artifact this build knows; other
-        // sibling files are never ours to delete, and the directory itself is
-        // only removed once empty. An unreadable directory counts as a
-        // failure (not a silent success) so the outcome line stays honest.
-        const entries = await readdir(dir, { withFileTypes: true })
-        for (const entry of entries) {
-          if (entry.isFile() && isSessionArtifactName(entry.name)) {
-            await rm(join(dir, entry.name), { force: true })
-          }
-        }
-        await rm(dir, { force: true, recursive: false }).catch(() => {})
-        removed += 1
-      } catch (error: unknown) {
-        return `delete failed for ${node.id.slice(-12)} after ${removed} of ${plan.nodes.length}: ${error instanceof Error ? error.message : String(error)}`
-      }
-    }
-    return `deleted ${removed} session${removed === 1 ? '' : 's'}`
-  }
-
-  const loadSessionTranscript = async (id: string, signal?: AbortSignal): Promise<string> => {
-    if (sessionQuery === undefined) throw new Error('session query is unavailable in this profile')
-    const snapshot = await sessionQuery.readSession(id, signal)
-    return buildExportMarkdown(createTranscriptStore(snapshot.events).getView(), snapshot.session.id)
-  }
+  const { loadSessions, deleteSession, loadSessionTranscript } = createSessionIo({
+    sessionQuery,
+    persistence,
+    activeSessionId: () => session?.id,
+  })
 
   /**
    * Read one session's usage blocks for the /usage panel: the mounted
@@ -1787,7 +1294,6 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       turns: turnUsages(current.snapshotEvents(), deriveTurnTokenUsage),
     })
   }
-
   const switchModeAction = async (id: string): Promise<string> => {
     if (id === '') throw new Error('usage: /mode <preset>')
     const currentAgent = agent
@@ -1906,7 +1412,10 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
         // 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}`)
+          bridge.notify(t(next.resumed ? 'notice.sessionResumed' : 'notice.sessionCreated', {
+            id: next.session.id.slice(-12),
+            mode: next.mode,
+          }))
         }, 0)
         return
       }
@@ -1914,23 +1423,25 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       try {
         await sessions.flush(previous.session)
       } catch (error: unknown) {
-        cleanupWarning = `previous session flush failed: ${error instanceof Error ? error.message : String(error)}`
+        cleanupWarning = t('notice.flushFailed', { message: error instanceof Error ? error.message : String(error) })
       }
       try {
         await previous.handle.dispose()
       } catch (error: unknown) {
-        cleanupWarning = `${cleanupWarning === undefined ? '' : `${cleanupWarning}; `}previous agent release failed: ${error instanceof Error ? error.message : String(error)}`
+        const release = t('notice.agentReleaseFailed', { message: error instanceof Error ? error.message : String(error) })
+        cleanupWarning = cleanupWarning === undefined ? release : `${cleanupWarning}; ${release}`
       }
+      const shortId = next.session.id.slice(-12)
       bridge.notify(cleanupWarning === undefined
-        ? `${next.resumed ? 'resumed' : 'created'} ${next.session.id.slice(-12)} · mode ${next.mode}`
-        : `switched to ${next.session.id.slice(-12)}, but ${cleanupWarning}`,
+        ? t(next.resumed ? 'notice.sessionResumed' : 'notice.sessionCreated', { id: shortId, mode: next.mode })
+        : t('notice.sessionSwitchedDirty', { id: shortId, detail: cleanupWarning }),
       cleanupWarning === undefined ? 'info' : 'warning')
     })
   }
 
   const switchQueue = new SessionSwitchQueue<PendingSwitch>(
     async request => { if (!quitting) await activate(request.target) },
-    error => bridge.notify(`session switch failed: ${error instanceof Error ? error.message : String(error)}`, 'error'),
+    error => bridge.notify(t('notice.sessionSwitchFailed', { message: error instanceof Error ? error.message : String(error) }), 'error'),
   )
 
   const requestSwitch = (request: PendingSwitch): void => {
@@ -1939,17 +1450,17 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       // the target directly — there is no running turn to wait on and nothing
       // to flush.
       void activate(request.target).catch((error: unknown) => {
-        bridge.notify(`session switch failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+        bridge.notify(t('notice.sessionSwitchFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
       })
       return
     }
     if (request.target.sessionId === session.id) {
-      bridge.notify('that session is already active', 'warning')
+      bridge.notify(t('notice.alreadyActive'), 'warning')
       return
     }
     const outcome = switchQueue.request(agent!, request)
     if (outcome === 'queued') {
-      bridge.notify(`will switch to ${request.label} when the current turn finishes · /resume cancel to abort`)
+      bridge.notify(t('notice.switchQueued', { label: request.label }))
     }
   }
 
@@ -1975,7 +1486,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   const requestResume = (wanted: string): void => {
     void resolveResumeId(wanted).then(id => {
       requestSwitch({ target: { sessionId: id, resume: true }, label: id.slice(-12) })
-    }, (error: unknown) => bridge.notify(`resume failed: ${error instanceof Error ? error.message : String(error)}`, 'error'))
+    }, (error: unknown) => bridge.notify(t('notice.resumeFailed', { message: error instanceof Error ? error.message : String(error) }), 'error'))
   }
 
   const createSession = (mode?: string): void => {
@@ -2039,7 +1550,7 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
 
   const forkSession = (argument: string): void => {
     if (session === undefined || active === undefined) {
-      bridge.notify('no session yet - submit a message to start', 'warning')
+      bridge.notify(t('notice.noSessionYet'), 'warning')
       return
     }
     try {
@@ -2063,13 +1574,13 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
         label: id.slice(-12),
       })
     } catch (error: unknown) {
-      bridge.notify(`fork failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.forkFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
     }
   }
 
   const switchSession = (row: SessionRow): void => {
     if (!row.resumable) {
-      bridge.notify('subagent conversations are read-only', 'warning')
+      bridge.notify(t('notice.subagentsReadOnly'), 'warning')
       return
     }
     requestSwitch({ target: { sessionId: row.id, resume: true }, label: row.title ?? row.id.slice(-12) })
@@ -2151,6 +1662,25 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       loadModelProviders: () => loadProviderSettings(ctx),
       subscribeModelProviders: listener => subscribeProviderSettings(ctx, listener),
       saveModelProviderCredential: (target, key) => saveProviderCredential(ctx, target, key),
+      enableModelProviderSubscription: target => enableProviderSubscription(ctx, target),
+      attachSubagent: sessionQuery === undefined ? undefined : {
+        // The seed is the child's durable log; the two buses are the same
+        // process-local channels the root uses, filtered by the child's id
+        // (an Agent's id IS its SessionId).
+        load: (id, signal) => sessionQuery.readSession(id, signal).then(snapshot => snapshot.events),
+        subscribeEvents: (id, onEvent) => {
+          const off = ctx.on('session/event', (subject: Session, event: SessionEvent) => {
+            if (subject.id === id) onEvent(event)
+          })
+          return off
+        },
+        subscribeStream: (id, onFrame) => {
+          const off = ctx.on('agent/assistant-stream', ({ agent: source, frame }) => {
+            if (source.id === id) onFrame(frame)
+          })
+          return off
+        },
+      },
       saveModelProviderConfiguration: (target, configuration) => saveProviderConfiguration(ctx, target, configuration),
       discoverModelProvider: (target, request, signal) => discoverProviderModels(ctx, target, request, signal),
       unsetModelProviderCredential: target => unsetProviderCredential(ctx, target),
@@ -2215,8 +1745,8 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
       saveLanguage,
       animations: animationsEnabled,
       saveAnimations,
-      history: inputHistory,
-      recordHistory,
+      history: inputHistory.entries(),
+      recordHistory: inputHistory.record,
       updateQueued,
       onBridgeReady: (instance: AppBridge) => { bridge.notify = instance.notify },
     })
@@ -2234,29 +1764,29 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   // 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'}…`)
+      bridge.notify(t('notice.startupImages', { count: startup.images!.length, plural: startup.images!.length === 1 ? '' : 's' }))
     }
     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`)
+      if (images.length > 0) bridge.notify(t('notice.startupImagesAttached', { count: images.length, plural: images.length === 1 ? '' : 's' }))
       deliver({ text: startup.prompt ?? '', mode: 'followup', images })
     }).catch((error: unknown) => {
-      bridge.notify(`initial prompt failed: ${error instanceof Error ? error.message : String(error)}`, 'error')
+      bridge.notify(t('notice.initialPromptFailed', { message: error instanceof Error ? error.message : String(error) }), 'error')
     })
   }
 
   async function copyLastResponse(): Promise<string> {
     const text = latestAssistantText(store.getView())
-    if (text === undefined) return 'nothing to copy yet'
+    if (text === undefined) return t('notice.copyEmpty')
     await copyText(text)
-    return 'copied latest response'
+    return t('notice.copied')
   }
 
   // A corrupt statusline config must not vanish silently: surface it once
   // the notice channel is live, after the first frame settles.
   if (statuslineWarning !== undefined) {
     setTimeout(() => {
-      bridge.notify('statusline config unreadable, using defaults: ' + statuslineWarning, 'warning')
+      bridge.notify(t('notice.statuslineConfigUnreadable', { message: statuslineWarning }), 'warning')
     }, 50)
   }
   // Same one-shot surface for a corrupt theme file (dark fallback stays live).
@@ -2267,13 +1797,13 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
   }
   if (themeWarning !== undefined) {
     setTimeout(() => {
-      bridge.notify('theme config unreadable, using dark: ' + themeWarning, 'warning')
+      bridge.notify(t('notice.themeConfigUnreadable', { message: themeWarning }), 'warning')
     }, 50)
   }
   // And for a corrupt animations file (on-by-default fallback stays live).
   if (animationsWarning !== undefined) {
     setTimeout(() => {
-      bridge.notify('animations config unreadable, animations stay on: ' + animationsWarning, 'warning')
+      bridge.notify(t('notice.animationsConfigUnreadable', { message: animationsWarning }), 'warning')
     }, 50)
   }
 
@@ -2295,22 +1825,11 @@ async function run(ctx: Context, startup: TuiStartup, io: TuiIo): Promise<void>
  * @param config - validated startup config resolved from the tuiStartup provider.
  */
 export function apply(ctx: Context, config: Config): void {
-  // The CLI validated --theme at parse time; the loose config schema falls
-  // back to dark for anything unexpected.
-  const theme = config.startup.theme === undefined ? undefined : parseThemeName(config.startup.theme)
-  const input = {
-    ...(theme === undefined ? {} : { theme }),
-    ...(config.startup.prompt === undefined ? {} : { prompt: config.startup.prompt }),
-    ...(config.startup.images === undefined ? {} : { images: config.startup.images }),
-  }
-  const startup: TuiStartup =
-    config.startup.kind === 'resume' && config.startup.sessionId !== undefined
-      ? { kind: 'resume', sessionId: config.startup.sessionId, ...input }
-      : config.startup.kind === 'latest'
-        ? { kind: 'latest', ...input }
-        : config.startup.kind === 'named' && config.startup.sessionId !== undefined
-          ? { kind: 'named', sessionId: config.startup.sessionId, ...config.startup.mode === undefined ? {} : { mode: config.startup.mode }, ...input }
-          : { kind: 'fresh', ...config.startup.mode === undefined ? {} : { mode: config.startup.mode }, ...input }
+  // The host resolves every bare @deepseek-ai/* import against its own
+  // installed copies with no version check anywhere on that path, so refuse
+  // to run against an identified-but-different Harness before anything loads.
+  requireHarnessVersion(EXPECTED_HARNESS_VERSION, probeRunningHarness(process.argv[1]))
+  const startup = resolveStartupConfig(config)
   // Read through the global service store, not the property proxy: appExit is
   // an optional host value, never an injected dependency.
   const exit = ctx.get('appExit')