dsh-code 1.3.0 → 1.4.0

package/src/{theme-panel.ts → panels/theme-panel.ts}

@@ -9,11 +9,11 @@
 
 import { createElement, useState, type ReactElement } from 'react'
 import { Box, Text, useInput, useStdout } from 'ink'
-import { clampScroll, panelViewport } from './render/inspector.ts'
-import { truncateColumns } from './render/text.ts'
-import { panelAccent } from './panel-accent.ts'
-import { getPalette, inkColor, THEMES, type ThemeName } from './theme.ts'
-import { t } from './i18n.ts'
+import { clampScroll, panelViewport } from '../render/inspector.ts'
+import { truncateColumns } from '../render/text.ts'
+import { panelAccent } from '../ui/panel-accent.ts'
+import { getPalette, inkColor, THEMES, type ThemeName } from '../theme.ts'
+import { t } from '../i18n.ts'
 
 /**
  * The /theme list: one row per theme, the current one marked with ●, the

package/src/{update-panel.ts → panels/update-panel.ts}

@@ -11,12 +11,12 @@
 
 import { createElement, useEffect, useState, type ReactElement } from 'react'
 import { Box, Text, useInput, useStdout } from 'ink'
-import type { LauncherUpdatePlan, LauncherUpdateStatus } from './update.ts'
-import { clampScroll, panelViewport } from './render/inspector.ts'
-import { singleLineText, truncateColumns } from './render/text.ts'
-import { panelAccent } from './panel-accent.ts'
-import { getPalette, inkColor } from './theme.ts'
-import { t } from './i18n.ts'
+import type { LauncherUpdatePlan, LauncherUpdateStatus } from '../update.ts'
+import { clampScroll, panelViewport } from '../render/inspector.ts'
+import { singleLineText, truncateColumns } from '../render/text.ts'
+import { panelAccent } from '../ui/panel-accent.ts'
+import { getPalette, inkColor } from '../theme.ts'
+import { t } from '../i18n.ts'
 
 /** Retained apply-progress lines (ring tail; npm output is ephemeral). */
 export const UPDATE_OUTPUT_CAP = 800

package/src/provider-settings.ts

@@ -666,6 +666,44 @@ export async function saveProviderConfiguration(
   }
 }
 
+/**
+ * Switch one provider route to its subscription (plan sign-in) channel: the
+ * profile keeps neither a key reference nor an explicit model list, so the
+ * official catalog endpoint serves requests and the stored OAuth record — not
+ * a settings-named key override — authenticates them. Enabling a route that
+ * has no profile yet creates the empty profile that registers it.
+ * @param ctx - context carrying the `settings` service.
+ * @param target - provider row whose settings namespace owns the profile.
+ * @throws when the route is unmanaged or settings are read-only.
+ */
+export async function enableProviderSubscription(ctx: Context, target: ProviderTargetView): Promise<void> {
+  if (target.settingsNs.length === 0) {
+    throw new ProviderSettingsError(`provider "${target.provider}" has no managed settings namespace; configure it in settings.yaml`)
+  }
+  const settings = ctx.get('settings') as SettingsFace | undefined
+  if (settings === undefined || settings.writable !== true) {
+    throw new ProviderSettingsError('settings are read-only; provider configuration cannot be changed here')
+  }
+  const root = target.settingsPath
+  const ops: SettingsPathOpFace[] = target.configured
+    ? [
+      // The key reference would resolve as a request-level override BEFORE
+      // the stored sign-in record, so the subscription channel must drop it;
+      // the endpoint and the explicit model list belong to the key channel.
+      { op: 'unset', path: [...root, 'apiKeyEnv'] },
+      { op: 'unset', path: [...root, 'baseURL'] },
+      { op: 'unset', path: [...root, 'models'] },
+    ]
+    // A route with no profile stays dormant: an empty profile registers it
+    // with the catalog endpoint and every catalog model.
+    : [{ op: 'set', path: [...root], value: {} }]
+  try {
+    await settings.mutate(target.settingsNs, ops, target.settingsRevision)
+  } catch (error) {
+    throw new ProviderSettingsError(singleLine(messageOf(error)))
+  }
+}
+
 /**
  * Interrogate a provider endpoint for the models it really serves, through
  * the model-discovery capability the provider's settings namespace

package/src/render/inspector.ts

@@ -99,6 +99,29 @@ export function panelViewport(columns: number, rows: number): InspectorViewport
   }
 }
 
+/**
+ * Viewport for an expanded (near-fullscreen) document overlay: the document
+ * replaces the transcript area entirely, so the half-screen overlay cap and
+ * the inter-section gaps drop away while the bottom live region (composer,
+ * status) and the Static-rewrite margin stay reserved. The result stays
+ * below terminal height, which is what keeps Ink off its full-rewrite path.
+ */
+export function expandedDocumentViewport(columns: number, rows: number): InspectorViewport {
+  const safeColumns = Math.max(1, Math.floor(columns))
+  const safeRows = Math.max(1, Math.floor(rows))
+  const maxHeight = Math.max(0, safeRows - 2 - INSPECTOR_CHROME_ROWS - layoutGutterRows(safeRows))
+  const compact = maxHeight < 5 || safeColumns < 8
+  const outerColumns = compact ? safeColumns : Math.max(1, safeColumns - 1)
+  return {
+    maxHeight,
+    bodyRows: compact ? 0 : maxHeight - 4,
+    gapRows: 0,
+    contentColumns: compact ? Math.max(1, safeColumns - 1) : Math.max(1, outerColumns - 4),
+    outerColumns,
+    compact,
+  }
+}
+
 /** Backward-compatible name for the Ctrl+O-specific caller and tests. */
 export function inspectorViewport(columns: number, rows: number): InspectorViewport {
   return panelViewport(columns, rows)

package/src/render/text.ts

@@ -14,6 +14,8 @@
 
 import { graphemeWidth, splitGraphemes, stringWidth } from './width.ts'
 
+export { stringWidth }
+
 /**
  * Compact token count: exact below 1K, then one-decimal-ish K/M.
  * @param n - token count.
@@ -84,6 +86,12 @@ export function truncateColumns(text: string, columns: number): string {
   return `${result}…`
 }
 
+/** Sanitize, clip, and right-pad one cell to an exact terminal-column width. */
+export function padColumns(text: string, columns: number): string {
+  const clipped = truncateColumns(singleLineText(text), columns)
+  return clipped + ' '.repeat(Math.max(0, columns - stringWidth(clipped)))
+}
+
 /** A display-safe suffix bounded by terminal rows and columns. */
 export interface DisplayTail {
   /** Sanitized suffix suitable for direct terminal rendering. */

package/src/runner/harness-gate.ts

@@ -0,0 +1,168 @@
+/**
+ * Load-time DeepSeek Harness version gate.
+ *
+ * The terminal driver is validated against exactly one Harness snapshot, and
+ * the host resolves every bare `@deepseek-ai/*` import the plugin makes
+ * against ITS OWN installed copies (the profile's `HostResolvedRootInclude`
+ * redirects bare names to the installed-host base). No install-time or
+ * load-time check exists anywhere on that path, so a user who updates `dsh`
+ * would otherwise run this build against unvetted upstream code silently.
+ *
+ * This gate mirrors how the host itself reads its identity: the running CLI
+ * entry (`process.argv[1]`) sits inside the `@deepseek-ai/dsh` package, whose
+ * manifest version is released in lockstep with the Harness packages bundled
+ * beside it. When the probe can identify the host it compares the running
+ * versions against the one this build declares and fails fast with an
+ * actionable message; when it cannot identify the host it stays silent rather
+ * than brick a supported embedding on a false positive.
+ *
+ * @module @deepseek-ai/dsh-code/runner/harness-gate
+ */
+
+import { realpathSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The one Harness release this build was validated against. */
+export const EXPECTED_HARNESS_VERSION = '0.1.5-rc.2'
+
+/** Host packages whose bundled copy the plugin binds to at runtime. */
+export const HARNESS_GATE_PACKAGES = [
+  '@deepseek-ai/dsh-agent',
+  '@deepseek-ai/dsh-session',
+] as const
+
+/** The installed-host CLI package that carries the Harness runtime. */
+const HOST_PACKAGE_NAME = '@deepseek-ai/dsh'
+
+/** Filesystem slice the probe needs; injectable so tests stay pure. */
+export interface HarnessFs {
+  /** Resolve a symlinked entry to its real path. */
+  realpathSync(path: string): string
+  /** Read and parse one package.json; undefined when absent or unreadable. */
+  readManifest(path: string): { name?: unknown; version?: unknown } | undefined
+}
+
+const defaultHarnessFs: HarnessFs = {
+  realpathSync: path => realpathSync(path),
+  readManifest: path => {
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as { name?: unknown; version?: unknown }
+    } catch {
+      return undefined
+    }
+  },
+}
+
+/** What the probe learned about the running host. */
+export interface HarnessProbe {
+  /** Installed-host package root, when identified. */
+  readonly hostRoot?: string
+  /** Installed-host CLI version (`@deepseek-ai/dsh`). */
+  readonly hostVersion?: string
+  /** Version of each gate package bundled beside the host, when present. */
+  readonly packages: Readonly<Record<string, string | undefined>>
+}
+
+const UNKNOWN_PROBE: HarnessProbe = { packages: {} }
+
+/**
+ * Walk up from one directory to the nearest `@deepseek-ai/dsh` package root.
+ * @param start - directory of the running CLI entry (already realpath'd).
+ * @param fs - filesystem slice to walk with.
+ * @returns the host package root, or undefined when no ancestor matches.
+ */
+function findHostRoot(start: string, fs: HarnessFs): string | undefined {
+  let directory = start
+  for (;;) {
+    const manifest = fs.readManifest(join(directory, 'package.json'))
+    if (manifest !== undefined && manifest.name === HOST_PACKAGE_NAME) return directory
+    const parent = dirname(directory)
+    if (parent === directory) return undefined
+    directory = parent
+  }
+}
+
+/**
+ * Identify the running host and the Harness versions it provides.
+ * @param argv1 - `process.argv[1]`, the running CLI entry path.
+ * @param fs - filesystem slice; defaults to the real one.
+ * @returns the probe result; `packages` is empty when the host is unknown.
+ */
+export function probeRunningHarness(argv1: string | undefined, fs: HarnessFs = defaultHarnessFs): HarnessProbe {
+  if (argv1 === undefined || argv1 === '') return UNKNOWN_PROBE
+  let entry: string
+  try {
+    entry = fs.realpathSync(argv1)
+  } catch {
+    return UNKNOWN_PROBE
+  }
+  const hostRoot = findHostRoot(dirname(entry), fs)
+  if (hostRoot === undefined) return UNKNOWN_PROBE
+  const hostManifest = fs.readManifest(join(hostRoot, 'package.json'))
+  const hostVersion = typeof hostManifest?.version === 'string' ? hostManifest.version : undefined
+  const packages: Record<string, string | undefined> = {}
+  for (const name of HARNESS_GATE_PACKAGES) {
+    const manifest = fs.readManifest(join(hostRoot, 'node_modules', name, 'package.json'))
+    if (typeof manifest?.version === 'string') packages[name] = manifest.version
+  }
+  return { hostRoot, hostVersion, packages }
+}
+
+/** One host fact that disagrees with the version this build declares. */
+export interface HarnessMismatch {
+  /** What was compared: the host CLI or one bundled package. */
+  readonly source: string
+  /** The version this build was validated against. */
+  readonly expected: string
+  /** The version the running host actually provides. */
+  readonly provided: string
+}
+
+/**
+ * Compare one probe against the expected snapshot. Unknown facts never
+ * mismatch: the gate must stay silent when it cannot judge, not brick a
+ * supported embedding on missing evidence.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @returns every concrete disagreement, empty when compatible or unknown.
+ */
+export function harnessVersionMismatches(expected: string, probe: HarnessProbe): readonly HarnessMismatch[] {
+  const mismatches: HarnessMismatch[] = []
+  if (probe.hostVersion !== undefined && probe.hostVersion !== expected) {
+    mismatches.push({ source: `${HOST_PACKAGE_NAME} host`, expected, provided: probe.hostVersion })
+  }
+  for (const name of HARNESS_GATE_PACKAGES) {
+    const provided = probe.packages[name]
+    if (provided !== undefined && provided !== expected) {
+      mismatches.push({ source: name, expected, provided })
+    }
+  }
+  return mismatches
+}
+
+/**
+ * Render the gate failure the user sees on stderr.
+ * @param expected - the Harness version this build declares.
+ * @param mismatches - the disagreements to report.
+ * @param hostRoot - installed-host root, when identified, for the fix hint.
+ * @returns the multi-line diagnostic.
+ */
+export function harnessGateMessage(expected: string, mismatches: readonly HarnessMismatch[], hostRoot?: string): string {
+  const lines = [`dsh: this dsh-code build requires DeepSeek Harness ${expected}, but this dsh provides:`]
+  for (const mismatch of mismatches) lines.push(`dsh:   ${mismatch.source} ${mismatch.provided}`)
+  lines.push('dsh: update dsh-code to a release built for this dsh, or use a dsh matching ' + expected + '.')
+  if (hostRoot !== undefined) lines.push(`dsh: running host: ${hostRoot}`)
+  return lines.join('\n')
+}
+
+/**
+ * Refuse to run against an identified-but-incompatible host.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @throws an Error carrying the gate diagnostic when a version disagrees.
+ */
+export function requireHarnessVersion(expected: string, probe: HarnessProbe): void {
+  const mismatches = harnessVersionMismatches(expected, probe)
+  if (mismatches.length === 0) return
+  throw new Error(harnessGateMessage(expected, mismatches, probe.hostRoot))
+}

package/src/runner/input-history.ts

@@ -0,0 +1,77 @@
+/** Global input recall: the appended prompts and their durable JSONL file.
+ *
+ * One JSONL file under the DSH home. A missing file means an empty history and
+ * unreadable or corrupt content degrades to the valid lines it could parse,
+ * silently — recall is a convenience surface, never a gate.
+ *
+ * @module @deepseek-ai/dsh-code/input-history
+ */
+
+import { readFileSync } from 'node:fs'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import {
+  historyLine,
+  HISTORY_MAX_ENTRIES,
+  needsCompaction,
+  parseHistoryFile,
+  serializeHistoryList,
+} from '../session/history.ts'
+import { writeFileAtomically } from '../settings-file.ts'
+
+/** Live recall state plus its serialized durable writes. */
+export interface InputHistoryStore {
+  /** The recall list, newest last; read live by the composer. */
+  readonly entries: () => readonly string[]
+  /** Append one submitted line and persist it; '' is ignored. */
+  readonly record: (text: string) => void
+  /** Await the pending writes (the quit flush). */
+  readonly flush: () => Promise<void>
+}
+
+/**
+ * Load the recall history and return its live store.
+ *
+ * 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.
+ *
+ * @param path - absolute path of the JSONL recall file.
+ * @param onFailure - receives the write failure message for a bounded notice.
+ */
+export function createInputHistory(path: string, onFailure: (message: string) => void): InputHistoryStore {
+  let entries: readonly string[] = []
+  let chain: Promise<void> = Promise.resolve()
+  try {
+    const raw = readFileSync(path, 'utf8')
+    entries = parseHistoryFile(raw)
+    // 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(raw)) {
+      chain = chain.then(() => writeFileAtomically(path, serializeHistoryList(entries))).catch(() => {})
+    }
+  } catch {
+    entries = []
+  }
+  return {
+    entries: () => entries,
+    record: (text: string): void => {
+      if (text === '') return
+      entries = [...entries, text].slice(-HISTORY_MAX_ENTRIES)
+      chain = chain
+        .then(() => mkdir(dirname(path), { recursive: true }))
+        .then(() => appendFile(path, historyLine(text), 'utf8'))
+        .catch((error: unknown) => {
+          onFailure(error instanceof Error ? error.message : String(error))
+        })
+    },
+    flush: () => chain,
+  }
+}

package/src/runner/mode-cycle.ts

@@ -0,0 +1,49 @@
+/** Shift+Tab mode-cycle stations for the terminal runner.
+ *
+ * Pure decision over the preset table and the committed plan fold: the runner
+ * applies the returned station, so the whole cycle is testable without a
+ * session.
+ *
+ * @module @deepseek-ai/dsh-code/mode-cycle
+ */
+
+/** 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 }
+}

package/src/runner/preferences.ts

@@ -0,0 +1,67 @@
+/** User-level preference files under the DSH home.
+ *
+ * The statusline, theme, language, and animations customizations each live in
+ * one small JSON file. They share exactly two policies: a missing file is the
+ * default and stays silent while a corrupt one degrades to the default with a
+ * surfaced warning (a user-authored customization must never fail silently),
+ * and every save goes through the serialized crash-atomic writer.
+ *
+ * @module @deepseek-ai/dsh-code/preferences
+ */
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { readSettingsObject, type UserSettingsPersistence } from '../settings-file.ts'
+
+/** Absolute path of one preference file under the DSH home. */
+export function preferencePath(fileName: string): string {
+  return join(homedir(), '.dsh', 'dsh-code', fileName)
+}
+
+/** Outcome of reading one preference file. */
+export interface PreferenceRead<T> {
+  /** Parsed value; undefined when the file is missing or corrupt (keep the default). */
+  readonly value?: T
+  /** Corruption message to surface; undefined for a missing or clean file. */
+  readonly warning?: string
+}
+
+/**
+ * Read one field of a preference file. A missing file is silence — the default
+ * stands and nothing is reported — while unreadable JSON or a non-object
+ * document both warn and keep the default.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param parse - narrows the raw field to the usable value.
+ * @returns the parsed value and/or the warning to surface.
+ */
+export function readPreference<T>(path: string, field: string, parse: (raw: unknown) => T): PreferenceRead<T> {
+  try {
+    return { value: parse(readSettingsObject(path)[field]) }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}
+    return { warning: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * Persist one preference field through the serialized crash-atomic writer.
+ * A failed write is reported through `onFailure` instead of rejecting.
+ * @param persistence - the shared user-settings writer.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param value - the value to store under `field`.
+ * @param onFailure - receives the failure message for a bounded notice.
+ */
+export function savePreference(
+  persistence: UserSettingsPersistence,
+  path: string,
+  field: string,
+  value: unknown,
+  onFailure: (message: string) => void,
+): void {
+  void persistence.save(path, JSON.stringify({ [field]: value }, null, 2) + '\n')
+    .catch((error: unknown) => {
+      onFailure(error instanceof Error ? error.message : String(error))
+    })
+}

package/src/runner/quit.ts

@@ -0,0 +1,53 @@
+/** Ordered terminal quit cleanup.
+ *
+ * Pure sequencing: every step rejection is contained and the exit request is
+ * always reached exactly once, so a failing flush never strands the process.
+ *
+ * @module @deepseek-ai/dsh-code/quit
+ */
+
+/** 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
+}

package/src/runner/search-rows.ts

@@ -0,0 +1,55 @@
+/** Cross-session search rows for the /search panel.
+ *
+ * Owns the panel row shape and the pure mapping from a session-query hit, so
+ * the row contract does not live inside the panel component that renders it
+ * and the runner can build rows without importing the panel module.
+ *
+ * @module @deepseek-ai/dsh-code/search-rows
+ */
+
+import type { SessionHeader } from '@deepseek-ai/dsh-session'
+
+/** One cross-session full-text search hit mapped from the session-query engine. */
+export interface SearchRow {
+  /** Session id (Enter resumes it through the switch machinery). */
+  readonly id: string
+  /** Display label: session title or the short id form. */
+  readonly label: string
+  /** Secondary facts line (workspace · preset markers). */
+  readonly detail: string
+  /** Bounded plain-text excerpt around the strongest match. */
+  readonly snippet: string
+  /** Match timestamp (relative labels derive from it). */
+  readonly updatedAt: number
+  /** Whether the hit is a delegated subagent conversation (not resumable). */
+  readonly subagent: boolean
+  /** Whether Enter may switch into it. */
+  readonly resumable: boolean
+}
+
+/**
+ * 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,
+  }
+}