dsh-code 1.0.6 → 1.2.0

package/src/subagents.ts

@@ -1,229 +1,229 @@
-/**
- * Live subagent activity feed: a bounded, display-only projection of CHILD
- * session events. The transcript store folds only the root session (the
- * durable truth this TUI renders); subagent conversations are their own
- * sessions, and before this module their events were dropped entirely —
- * a running subagent was invisible until its parent tool call settled.
- *
- * This is NOT a second transcript: each child folds to ONE row (label,
- * running state, bounded last-activity text), capped at
- * {@link MAX_SUBAGENT_ROWS}. The cap is a display budget, not a fan-out
- * limit: a new running child evicts the OLDEST settled row when one
- * exists, and while every row is busy the newcomer waits off-screen — but
- * the observed-session total (getTotalSeen) keeps counting, so status
- * totals never under-report the fan-out. Rows are advisory display
- * state, rebuilt from live events; nothing here persists or replays.
- * Notification is coalesced
- * by the same ~16ms frame throttle as the transcript store (per-burst
- * microtask notify chained SyncLane rerenders past React's nested update
- * limit; a bare macrotask merge repaints a whole turn's bursts at once).
- *
- * @module @deepseek-ai/dsh-code/subagents
- */
-
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-// Type-only import merges the subagent package's SessionEventMap variant
-// ('subagent/catalog') into the union this fold switches on.
-import type {} from '@deepseek-ai/dsh-subagent'
-
-/** Hard row cap: overflow evicts the oldest settled row; a fully busy feed waits. */
-export const MAX_SUBAGENT_ROWS = 8
-
-/** Render frame budget: the notification cadence's upper bound. */
-const NOTIFY_FRAME_MS = 16
-
-/** Bounded last-activity text (plain characters, display-sliced later). */
-const MAX_ACTIVITY_CHARS = 80
-
-/** One live subagent row in the feed. */
-export interface SubagentRow {
-  /** Child session id. */
-  readonly id: string
-  /** Display label (session title when observed, else a short id form). */
-  readonly label: string
-  /** Coarse lifecycle state folded from the child's events. */
-  readonly state: 'running' | 'idle' | 'done'
-  /** Bounded last-activity text for the status line. */
-  readonly activity: string
-  /** Last fold time (ms, event clock) — newest-first ordering key. */
-  readonly updatedAt: number
-}
-
-/** The read-only snapshot surface the renderer subscribes to. */
-export interface SubagentFeedView {
-  /** Subscribe to feed changes; returns the unsubscribe function. */
-  subscribe(listener: () => void): () => void
-  /** Read the current rows (identity-stable between changes). */
-  getSnapshot(): readonly SubagentRow[]
-  /**
-   * Distinct child sessions observed since the last reset. The row cap is
-   * a display budget, not a count of the fan-out; totals surface this.
-   */
-  getTotalSeen(): number
-}
-
-/** Single-line bounded preview of an assembled message's text content. */
-function messagePreview(content: unknown): string {
-  if (!Array.isArray(content)) return 'replied'
-  const texts: string[] = []
-  for (const block of content) {
-    if (texts.join(' ').length >= MAX_ACTIVITY_CHARS) break
-    if (typeof block === 'object' && block !== null) {
-      const { type, text } = block as Record<string, unknown>
-      if (type === 'text' && typeof text === 'string' && text !== '') texts.push(text)
-    }
-  }
-  const joined = texts.join(' ').replace(/\s+/gu, ' ').trim()
-  return joined === '' ? 'replied' : bound(joined)
-}
-
-/** Bound one activity string to the display budget. */
-function bound(text: string): string {
-  const flat = text.replace(/\s+/gu, ' ').trim()
-  return flat.length > MAX_ACTIVITY_CHARS ? `${flat.slice(0, MAX_ACTIVITY_CHARS - 1)}…` : flat
-}
-
-/**
- * Fold one child-session event into its feed row (pure).
- * Unknown event kinds leave the row untouched.
- * @param previous - the row's current state, when any.
- * @param sessionId - the child session id.
- * @param event - the child session event.
- * @returns the next row state.
- */
-export function foldSubagentRow(previous: SubagentRow | undefined, sessionId: string, event: SessionEvent): SubagentRow {
-  const base: SubagentRow = previous ?? {
-    id: sessionId,
-    label: `agent ${sessionId.slice(-6)}`,
-    state: 'running',
-    activity: 'starting…',
-    updatedAt: event.time,
-  }
-  const data = event.data as Record<string, unknown>
-  switch (event.type) {
-    case 'session/title': {
-      const title = data['title']
-      const text = typeof title === 'string' && title.trim() !== '' ? title : undefined
-      return text === undefined || text === base.label ? base : { ...base, label: bound(text), updatedAt: event.time }
-    }
-    case 'request/header':
-      return { ...base, state: 'running', activity: 'working…', updatedAt: event.time }
-    case 'user/message':
-      return { ...base, state: 'running', activity: 'prompted', updatedAt: event.time }
-    case 'assistant/attempt':
-      // Durable logs are settlement-only since session-log v2; an attempt
-      // landing without a surface message means the model is retrying or
-      // recovered from a stream error, so the child stays running.
-      return { ...base, state: 'running', activity: 'thinking…', updatedAt: event.time }
-    case 'subagent/catalog': {
-      // Parent-owned durable discovery fact (0.1.5): the catalog names the
-      // child's mode (one-shot vs continuable) and its authored label — the
-      // most semantic label the row can carry. It is a discovery fact, not a
-      // lifecycle signal: a fresh row starts idle, but a late delivery never
-      // regresses a row that already ran or finished. An unchanged fact keeps
-      // the row's identity (the no-op discipline of the default branch), so
-      // repeated deliveries never churn the snapshot array.
-      const mode = event.data.mode === 'continuable' ? 'continuable' : 'one-shot'
-      const label = event.data.label !== undefined && event.data.label.trim() !== '' ? bound(event.data.label) : undefined
-      const nextLabel = label === undefined ? base.label : label
-      const activity = label === undefined ? `catalog · ${mode}` : `catalog · ${mode} · ${label}`
-      const state = previous === undefined ? 'idle' : base.state
-      if (nextLabel === base.label && state === base.state && activity === base.activity) return base
-      return { ...base, state, label: nextLabel, activity, updatedAt: event.time }
-    }
-    case 'assistant/message':
-      return { ...base, state: 'idle', activity: messagePreview(data['message'] === undefined ? undefined : (data['message'] as { content?: unknown }).content), updatedAt: event.time }
-    case 'tool/call': {
-      const name = typeof data['name'] === 'string' ? data['name'] : 'tool'
-      return { ...base, state: 'running', activity: `tool ${name}`, updatedAt: event.time }
-    }
-    case 'tool/result':
-      return { ...base, state: 'running', activity: 'tool done', updatedAt: event.time }
-    case 'turn/start':
-      return { ...base, state: 'running', activity: base.activity === 'starting…' ? 'working…' : base.activity, updatedAt: event.time }
-    case 'turn/end':
-      return { ...base, state: 'done', activity: 'finished', updatedAt: event.time }
-    default:
-      // Unknown kinds leave the row untouched (identity-stable: a no-op
-      // fold must not churn the snapshot array).
-      return base
-  }
-}
-
-/**
- * Create one subagent feed. `apply` folds a child event (the caller gates
- * which sessions are children); `reset` clears on a session switch. Row
- * order is first-seen; the snapshot array is frozen and only replaced when
- * a row actually changed.
- * @returns the mutable feed handle plus its `SubagentFeedView`.
- */
-export function createSubagentFeed(): SubagentFeedView & {
-  apply(sessionId: string, event: SessionEvent): void
-  reset(): void
-} {
-  let rows: readonly SubagentRow[] = Object.freeze([])
-  const seen = new Set<string>()
-  const listeners = new Set<() => void>()
-  let scheduled = false
-  let lastNotifyAt = 0
-  const notify = (): void => {
-    if (scheduled) return
-    scheduled = true
-    const wait = NOTIFY_FRAME_MS - (Date.now() - lastNotifyAt)
-    const dispatch = (): void => {
-      scheduled = false
-      lastNotifyAt = Date.now()
-      for (const listener of listeners) listener()
-    }
-    if (wait <= 0) setImmediate(dispatch)
-    else setTimeout(dispatch, wait)
-  }
-  return {
-    apply(sessionId: string, event: SessionEvent): void {
-      const index = rows.findIndex(row => row.id === sessionId)
-      const previous = index === -1 ? undefined : rows[index]
-      const next = foldSubagentRow(previous, sessionId, event)
-      if (index !== -1) {
-        if (next === previous) return
-        rows = Object.freeze(rows.map((row, at) => at === index ? next : row))
-        notify()
-        return
-      }
-      // A child this feed has not shown yet: the honest total grows even
-      // when every row is busy; admission then prefers evicting the OLDEST
-      // settled row (idle or done — both are non-running) so a new running
-      // agent never waits on one that already settled.
-      const counted = !seen.has(sessionId)
-      if (counted) seen.add(sessionId)
-      if (rows.length >= MAX_SUBAGENT_ROWS) {
-        const evict = rows.findIndex(row => row.state !== 'running')
-        if (evict === -1) {
-          if (counted) notify()
-          return
-        }
-        rows = Object.freeze([...rows.slice(0, evict), next, ...rows.slice(evict + 1)])
-      } else {
-        rows = Object.freeze([...rows, next])
-      }
-      notify()
-    },
-    reset(): void {
-      seen.clear()
-      if (rows.length === 0) return
-      rows = Object.freeze([])
-      notify()
-    },
-    subscribe(listener: () => void): () => void {
-      listeners.add(listener)
-      return () => {
-        listeners.delete(listener)
-      }
-    },
-    getSnapshot(): readonly SubagentRow[] {
-      return rows
-    },
-    getTotalSeen(): number {
-      return seen.size
-    },
-  }
-}
+/**
+ * Live subagent activity feed: a bounded, display-only projection of CHILD
+ * session events. The transcript store folds only the root session (the
+ * durable truth this TUI renders); subagent conversations are their own
+ * sessions, and before this module their events were dropped entirely —
+ * a running subagent was invisible until its parent tool call settled.
+ *
+ * This is NOT a second transcript: each child folds to ONE row (label,
+ * running state, bounded last-activity text), capped at
+ * {@link MAX_SUBAGENT_ROWS}. The cap is a display budget, not a fan-out
+ * limit: a new running child evicts the OLDEST settled row when one
+ * exists, and while every row is busy the newcomer waits off-screen — but
+ * the observed-session total (getTotalSeen) keeps counting, so status
+ * totals never under-report the fan-out. Rows are advisory display
+ * state, rebuilt from live events; nothing here persists or replays.
+ * Notification is coalesced
+ * by the same ~16ms frame throttle as the transcript store (per-burst
+ * microtask notify chained SyncLane rerenders past React's nested update
+ * limit; a bare macrotask merge repaints a whole turn's bursts at once).
+ *
+ * @module @deepseek-ai/dsh-code/subagents
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+// Type-only import merges the subagent package's SessionEventMap variant
+// ('subagent/catalog') into the union this fold switches on.
+import type {} from '@deepseek-ai/dsh-subagent'
+
+/** Hard row cap: overflow evicts the oldest settled row; a fully busy feed waits. */
+export const MAX_SUBAGENT_ROWS = 8
+
+/** Render frame budget: the notification cadence's upper bound. */
+const NOTIFY_FRAME_MS = 16
+
+/** Bounded last-activity text (plain characters, display-sliced later). */
+const MAX_ACTIVITY_CHARS = 80
+
+/** One live subagent row in the feed. */
+export interface SubagentRow {
+  /** Child session id. */
+  readonly id: string
+  /** Display label (session title when observed, else a short id form). */
+  readonly label: string
+  /** Coarse lifecycle state folded from the child's events. */
+  readonly state: 'running' | 'idle' | 'done'
+  /** Bounded last-activity text for the status line. */
+  readonly activity: string
+  /** Last fold time (ms, event clock) — newest-first ordering key. */
+  readonly updatedAt: number
+}
+
+/** The read-only snapshot surface the renderer subscribes to. */
+export interface SubagentFeedView {
+  /** Subscribe to feed changes; returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+  /** Read the current rows (identity-stable between changes). */
+  getSnapshot(): readonly SubagentRow[]
+  /**
+   * Distinct child sessions observed since the last reset. The row cap is
+   * a display budget, not a count of the fan-out; totals surface this.
+   */
+  getTotalSeen(): number
+}
+
+/** Single-line bounded preview of an assembled message's text content. */
+function messagePreview(content: unknown): string {
+  if (!Array.isArray(content)) return 'replied'
+  const texts: string[] = []
+  for (const block of content) {
+    if (texts.join(' ').length >= MAX_ACTIVITY_CHARS) break
+    if (typeof block === 'object' && block !== null) {
+      const { type, text } = block as Record<string, unknown>
+      if (type === 'text' && typeof text === 'string' && text !== '') texts.push(text)
+    }
+  }
+  const joined = texts.join(' ').replace(/\s+/gu, ' ').trim()
+  return joined === '' ? 'replied' : bound(joined)
+}
+
+/** Bound one activity string to the display budget. */
+function bound(text: string): string {
+  const flat = text.replace(/\s+/gu, ' ').trim()
+  return flat.length > MAX_ACTIVITY_CHARS ? `${flat.slice(0, MAX_ACTIVITY_CHARS - 1)}…` : flat
+}
+
+/**
+ * Fold one child-session event into its feed row (pure).
+ * Unknown event kinds leave the row untouched.
+ * @param previous - the row's current state, when any.
+ * @param sessionId - the child session id.
+ * @param event - the child session event.
+ * @returns the next row state.
+ */
+export function foldSubagentRow(previous: SubagentRow | undefined, sessionId: string, event: SessionEvent): SubagentRow {
+  const base: SubagentRow = previous ?? {
+    id: sessionId,
+    label: `agent ${sessionId.slice(-6)}`,
+    state: 'running',
+    activity: 'starting…',
+    updatedAt: event.time,
+  }
+  const data = event.data as Record<string, unknown>
+  switch (event.type) {
+    case 'session/title': {
+      const title = data['title']
+      const text = typeof title === 'string' && title.trim() !== '' ? title : undefined
+      return text === undefined || text === base.label ? base : { ...base, label: bound(text), updatedAt: event.time }
+    }
+    case 'request/header':
+      return { ...base, state: 'running', activity: 'working…', updatedAt: event.time }
+    case 'user/message':
+      return { ...base, state: 'running', activity: 'prompted', updatedAt: event.time }
+    case 'assistant/attempt':
+      // Durable logs are settlement-only since session-log v2; an attempt
+      // landing without a surface message means the model is retrying or
+      // recovered from a stream error, so the child stays running.
+      return { ...base, state: 'running', activity: 'thinking…', updatedAt: event.time }
+    case 'subagent/catalog': {
+      // Parent-owned durable discovery fact (0.1.5): the catalog names the
+      // child's mode (one-shot vs continuable) and its authored label — the
+      // most semantic label the row can carry. It is a discovery fact, not a
+      // lifecycle signal: a fresh row starts idle, but a late delivery never
+      // regresses a row that already ran or finished. An unchanged fact keeps
+      // the row's identity (the no-op discipline of the default branch), so
+      // repeated deliveries never churn the snapshot array.
+      const mode = event.data.mode === 'continuable' ? 'continuable' : 'one-shot'
+      const label = event.data.label !== undefined && event.data.label.trim() !== '' ? bound(event.data.label) : undefined
+      const nextLabel = label === undefined ? base.label : label
+      const activity = label === undefined ? `catalog · ${mode}` : `catalog · ${mode} · ${label}`
+      const state = previous === undefined ? 'idle' : base.state
+      if (nextLabel === base.label && state === base.state && activity === base.activity) return base
+      return { ...base, state, label: nextLabel, activity, updatedAt: event.time }
+    }
+    case 'assistant/message':
+      return { ...base, state: 'idle', activity: messagePreview(data['message'] === undefined ? undefined : (data['message'] as { content?: unknown }).content), updatedAt: event.time }
+    case 'tool/call': {
+      const name = typeof data['name'] === 'string' ? data['name'] : 'tool'
+      return { ...base, state: 'running', activity: `tool ${name}`, updatedAt: event.time }
+    }
+    case 'tool/result':
+      return { ...base, state: 'running', activity: 'tool done', updatedAt: event.time }
+    case 'turn/start':
+      return { ...base, state: 'running', activity: base.activity === 'starting…' ? 'working…' : base.activity, updatedAt: event.time }
+    case 'turn/end':
+      return { ...base, state: 'done', activity: 'finished', updatedAt: event.time }
+    default:
+      // Unknown kinds leave the row untouched (identity-stable: a no-op
+      // fold must not churn the snapshot array).
+      return base
+  }
+}
+
+/**
+ * Create one subagent feed. `apply` folds a child event (the caller gates
+ * which sessions are children); `reset` clears on a session switch. Row
+ * order is first-seen; the snapshot array is frozen and only replaced when
+ * a row actually changed.
+ * @returns the mutable feed handle plus its `SubagentFeedView`.
+ */
+export function createSubagentFeed(): SubagentFeedView & {
+  apply(sessionId: string, event: SessionEvent): void
+  reset(): void
+} {
+  let rows: readonly SubagentRow[] = Object.freeze([])
+  const seen = new Set<string>()
+  const listeners = new Set<() => void>()
+  let scheduled = false
+  let lastNotifyAt = 0
+  const notify = (): void => {
+    if (scheduled) return
+    scheduled = true
+    const wait = NOTIFY_FRAME_MS - (Date.now() - lastNotifyAt)
+    const dispatch = (): void => {
+      scheduled = false
+      lastNotifyAt = Date.now()
+      for (const listener of listeners) listener()
+    }
+    if (wait <= 0) setImmediate(dispatch)
+    else setTimeout(dispatch, wait)
+  }
+  return {
+    apply(sessionId: string, event: SessionEvent): void {
+      const index = rows.findIndex(row => row.id === sessionId)
+      const previous = index === -1 ? undefined : rows[index]
+      const next = foldSubagentRow(previous, sessionId, event)
+      if (index !== -1) {
+        if (next === previous) return
+        rows = Object.freeze(rows.map((row, at) => at === index ? next : row))
+        notify()
+        return
+      }
+      // A child this feed has not shown yet: the honest total grows even
+      // when every row is busy; admission then prefers evicting the OLDEST
+      // settled row (idle or done — both are non-running) so a new running
+      // agent never waits on one that already settled.
+      const counted = !seen.has(sessionId)
+      if (counted) seen.add(sessionId)
+      if (rows.length >= MAX_SUBAGENT_ROWS) {
+        const evict = rows.findIndex(row => row.state !== 'running')
+        if (evict === -1) {
+          if (counted) notify()
+          return
+        }
+        rows = Object.freeze([...rows.slice(0, evict), next, ...rows.slice(evict + 1)])
+      } else {
+        rows = Object.freeze([...rows, next])
+      }
+      notify()
+    },
+    reset(): void {
+      seen.clear()
+      if (rows.length === 0) return
+      rows = Object.freeze([])
+      notify()
+    },
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    getSnapshot(): readonly SubagentRow[] {
+      return rows
+    },
+    getTotalSeen(): number {
+      return seen.size
+    },
+  }
+}

package/src/terminal-title.ts

@@ -0,0 +1,190 @@
+/**
+ * Terminal tab/window title management for the TUI.
+ *
+ * Terminals label their tab from the window title, which an application sets
+ * with an OSC 0 sequence; without one the tab shows the process name ("node").
+ * The title text is untrusted display content (session names arrive through
+ * events and user input), so it is sanitized before emission: control
+ * characters and bidi/invisible formatting codepoints are stripped, whitespace
+ * runs collapse to single spaces, and the result is bounded. Clearing writes
+ * an empty OSC payload and the terminal falls back to its own default; the
+ * previously set title is not portable to read back and is never restored.
+ *
+ * @module @deepseek-ai/dsh-code/terminal-title
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { useLayoutEffect, useRef } from 'react'
+import { useStdout } from 'ink'
+
+/** The host process title at module load, restored on unmount. On Windows
+ * this reaches the tab through SetConsoleTitleW (ConPTY reflects it to VS
+ * Code and friends without any user setting); on POSIX it becomes the ps
+ * name. Node replaces the argv memory, so the original must be saved before
+ * the first assignment. */
+const initialProcessTitle = process.title
+
+/** Tab label before a session carries a name. */
+export const DEFAULT_TERMINAL_TITLE = 'deepseek'
+
+/** Practical upper bound on title length, in visible characters: long enough
+ * for session names, short enough for tab bars and window managers. */
+export const MAX_TERMINAL_TITLE_CHARS = 240
+
+/** Control characters, DEL/C1 range, and bidi or invisible formatting
+ * codepoints that could terminate the OSC sequence or visually reorder the
+ * title relative to its underlying text. */
+const DISALLOWED_TITLE_CHARS = /[\u0000-\u001F\u007F-\u009F\u00AD\u034F\u061C\u180E\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/
+
+/** Normalize untrusted title text into one bounded display line: disallowed
+ * codepoints dropped, whitespace runs collapsed to single spaces, leading and
+ * trailing whitespace removed, length bounded. */
+export function sanitizeTerminalTitle(text: string): string {
+  const chars: string[] = []
+  let pendingSpace = false
+  for (const ch of text) {
+    if (DISALLOWED_TITLE_CHARS.test(ch)) continue
+    if (ch.trim() === '') {
+      if (chars.length > 0) pendingSpace = true
+      continue
+    }
+    if (pendingSpace) {
+      if (chars.length + 1 >= MAX_TERMINAL_TITLE_CHARS) break
+      chars.push(' ')
+      pendingSpace = false
+    }
+    if (chars.length >= MAX_TERMINAL_TITLE_CHARS) break
+    chars.push(ch)
+  }
+  return chars.join('')
+}
+
+/** Build one OSC 0 title sequence. An empty sanitized title yields an empty
+ * string: emitting nothing is distinct from clearing, which is a separate
+ * policy decision made by the caller. */
+export function terminalTitleSequence(text: string): string {
+  const title = sanitizeTerminalTitle(text)
+  return title === '' ? '' : `\x1b]0;${title}\x07`
+}
+
+/** Clear the managed title with an empty OSC payload; the terminal falls back
+ * to its own default label. */
+export function clearTerminalTitleSequence(): string {
+  return '\x1b]0;\x07'
+}
+
+/**
+ * Resolve the VS Code stable user-settings file for one platform and
+ * environment: `%APPDATA%` on Windows, the bundle data folder on macOS (NOT
+ * XDG `~/.config` — VS Code never reads that path there, so writing it
+ * silently no-ops and the tab kept showing the process name "node"), and
+ * XDG config on Linux.
+ */
+export function vscodeSettingsPath(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): string | undefined {
+  const windows = platform === 'win32'
+  const darwin = platform === 'darwin'
+  const base = windows ? env['APPDATA'] : env['HOME']
+  if (base === undefined || base === '') return undefined
+  return windows
+    ? join(base, 'Code', 'User', 'settings.json')
+    : darwin
+      ? join(base, 'Library', 'Application Support', 'Code', 'User', 'settings.json')
+      : join(base, '.config', 'Code', 'User', 'settings.json')
+}
+
+/** Outcome of the VS Code settings alignment. */
+export interface VsCodeTitleSettingResult {
+  wrote: boolean
+  reason?: 'not-vscode' | 'unparseable' | 'key-present' | 'error'
+}
+
+/** VS Code renders an application-set tab title only when
+ * "terminal.integrated.tabs.title" maps to the sequence variable; the editor
+ * default shows the process name instead ("node" for a Node CLI). Inside a VS
+ * Code integrated terminal, align the user settings once: if the key is
+ * absent, insert it and keep a one-shot backup of the original file. A value
+ * the user already set is never overwritten, an unparseable file is never
+ * touched, and every failure degrades to a no-op - the OSC and process-title
+ * channels keep working everywhere else. */
+export function ensureVsCodeTabTitleSetting(options: {
+  env?: NodeJS.ProcessEnv
+  settingsFile?: string
+  isTTY?: boolean
+} = {}): VsCodeTitleSettingResult {
+  const env = options.env ?? process.env
+  if (env['TERM_PROGRAM'] !== 'vscode') return { wrote: false, reason: 'not-vscode' }
+  if ((options.isTTY ?? process.stdout.isTTY) !== true) return { wrote: false, reason: 'not-vscode' }
+  let file = options.settingsFile
+  if (file === undefined) {
+    const resolved = vscodeSettingsPath(process.platform, env)
+    if (resolved === undefined) return { wrote: false, reason: 'error' }
+    file = resolved
+  }
+  try {
+    if (!existsSync(file)) {
+      mkdirSync(dirname(file), { recursive: true })
+      writeFileSync(file, '{\n  "terminal.integrated.tabs.title": "${sequence}"\n}\n', 'utf8')
+      return { wrote: true }
+    }
+    const text = readFileSync(file, 'utf8')
+    if (text.includes('"terminal.integrated.tabs.title"')) return { wrote: false, reason: 'key-present' }
+    try {
+      JSON.parse(text)
+    } catch {
+      return { wrote: false, reason: 'unparseable' }
+    }
+    const close = text.lastIndexOf('}')
+    if (close < 0) return { wrote: false, reason: 'unparseable' }
+    const before = text.slice(0, close)
+    const trimmedBefore = before.replace(/[ \t\r\n]+$/, '')
+    const tail = before.slice(trimmedBefore.length)
+    const needsComma = trimmedBefore.trim() !== '' && !trimmedBefore.trimEnd().endsWith('{')
+    const inserted = (needsComma ? ',' : '') + '\n    "terminal.integrated.tabs.title": "${sequence}"\n'
+    writeFileSync(file + '.dsh-backup', text, 'utf8')
+    writeFileSync(file, trimmedBefore + inserted + tail + text.slice(close), 'utf8')
+    return { wrote: true }
+  } catch {
+    return { wrote: false, reason: 'error' }
+  }
+}
+
+/**
+ * Keep the terminal tab label on `title` (sanitized; empty titles leave the
+ * current label alone). Two delivery channels run in parallel: the OSC 0
+ * sequence to stdout, and the host process title. Writes are deduplicated by
+ * title, and on unmount the managed title is cleared and the process title
+ * restored so the host shell regains its default label.
+ */
+export function useTerminalTitle(title: string, options: { clearOnUnmount?: boolean } = {}): void {
+  const { clearOnUnmount = true } = options
+  const { stdout } = useStdout()
+  const writtenRef = useRef<string | undefined>(undefined)
+  const processTitleRef = useRef(false)
+  // Layout effects: the clear must run synchronously at unmount (passive
+  // cleanups are not flushed synchronously when Ink tears the tree down).
+  useLayoutEffect(() => {
+    if (stdout === undefined) return undefined
+    return () => {
+      if (processTitleRef.current) {
+        processTitleRef.current = false
+        process.title = initialProcessTitle
+      }
+      if (clearOnUnmount && writtenRef.current !== undefined) stdout.write(clearTerminalTitleSequence())
+    }
+  }, [stdout, clearOnUnmount])
+  useLayoutEffect(() => {
+    if (stdout === undefined) return
+    if (title === writtenRef.current) return
+    const sequence = terminalTitleSequence(title)
+    if (sequence === '') return
+    stdout.write(sequence)
+    // The process title is the second delivery channel: on Windows it drives
+    // the console title that ConPTY reflects onto the tab without any user
+    // setting, where the OSC channel alone only shows once the host maps
+    // "terminal.integrated.tabs.title" to the sequence variable.
+    process.title = sanitizeTerminalTitle(title)
+    processTitleRef.current = true
+    writtenRef.current = title
+  }, [stdout, title])
+}