dsh-code 1.2.0 → 1.4.0

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,
+  }
+}

package/src/runner/session-io.ts

@@ -0,0 +1,206 @@
+/** Session directory IO exposed to the picker, /delete, and /export.
+ *
+ * The kernel persistence seam has NO deletion API by design — logs accumulate
+ * "until removed externally" — so removal is planned, layout-checked, and
+ * lease-guarded here before any file is touched. Every read goes through the
+ * in-process session-query engine, so this module stays free of `app.ts` and
+ * of the Ink tree.
+ *
+ * @module @deepseek-ai/dsh-code/runner/session-io
+ */
+
+import { readdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { SessionAlreadyOwnedError } from '@deepseek-ai/dsh-session-persistence'
+import { buildExportMarkdown } from '../render/export.ts'
+import {
+  acquireSessionDeletionLeases,
+  isSessionArtifactName,
+  jsonlSessionRoot,
+  mergeSessionTitles,
+  planSessionDeletion,
+  projectSessionRows,
+  releaseSessionDeletionLeases,
+  sessionArtifactDirectory,
+  sessionDirectoryFor,
+  sessionRowMatchesQuery,
+  type SessionDeletionPersistence,
+  type SessionDirectoryOptions,
+  type SessionQueryService,
+  type SessionRow,
+} from '../session/session-directory.ts'
+import { createTranscriptStore } from '../session/store.ts'
+
+/**
+ * The persistence surface this module needs: the JSONL backend's public
+ * session root plus its per-session write handles. Typing the narrow shape
+ * instead of the upstream service keeps the IO injectable from a test double.
+ */
+export interface SessionIoPersistence extends SessionDeletionPersistence {
+  /** JSONL backend plugin config carrying the session root, when exposed. */
+  readonly config?: { readonly root?: unknown }
+}
+
+/** Services the session IO closes over. */
+export interface SessionIoServices {
+  /** In-process session-query engine; absent in profiles without one. */
+  readonly sessionQuery?: SessionQueryService
+  /** The durable persistence service; absent in profiles without one. */
+  readonly persistence?: SessionIoPersistence
+  /** The session currently visible in the UI (self-deletion guard). */
+  readonly activeSessionId: () => string | undefined
+}
+
+/** Session directory reads and the guarded /delete operation. */
+export interface SessionIo {
+  /** Project the session directory for the picker (query-filtered). */
+  readonly loadSessions: (options: SessionDirectoryOptions, signal?: AbortSignal) => Promise<readonly SessionRow[]>
+  /** Delete one session subtree, returning the outcome line. */
+  readonly deleteSession: (id: string) => Promise<string>
+  /** Render one session's whole transcript as export Markdown. */
+  readonly loadSessionTranscript: (id: string, signal?: AbortSignal) => Promise<string>
+}
+
+/**
+ * Bind the session IO to one runner's services.
+ * @param services - the query engine, persistence, and the live-session probe.
+ * @returns the picker/delete/export reads used by the app bridge.
+ */
+export function createSessionIo(services: SessionIoServices): SessionIo {
+  const { sessionQuery, persistence } = services
+
+  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, query: '' }, updated)
+    // Titles are the expensive fold. Fetch the first picker page when idle;
+    // a non-empty query loads more so the displayed title can match.
+    const titleBudget = options.query.trim() === '' ? 32 : Math.min(projected.length, 128)
+    const page = projected.slice(0, titleBudget)
+    if (page.length === 0) return projected
+    const observations = await sessionQuery.readTitleSnapshots(page.map(row => row.id), signal)
+    const titled = mergeSessionTitles(projected, observations)
+    return titled.filter(row => sessionRowMatchesQuery(row, options.query))
+  }
+
+  /**
+   * 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. Acquire every node's public persistence write handle before touching
+   *    files. The JSONL backend holds its cross-process kernel lease for each
+   *    handle, so another terminal's live session refuses the whole deletion.
+   * 4. Artifacts are removed children-first while every lease remains held:
+   *    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'
+    const activeId = services.activeSessionId()
+    if (activeId !== undefined && activeId === 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 || persistence === 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 leases
+    try {
+      leases = await acquireSessionDeletionLeases(persistence, plan.nodes.map(node => node.id))
+    } catch (error: unknown) {
+      if (error instanceof SessionAlreadyOwnedError) {
+        return `cannot delete ${error.sessionId.slice(-12)} — it is open in this or another process`
+      }
+      return `cannot safely lock sessions for deletion: ${error instanceof Error ? error.message : String(error)}`
+    }
+
+    let removed = 0
+    let outcome: string | undefined
+    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. The POSIX session.lock file
+        // deliberately remains because unlinking a held flock inode would
+        // forfeit the backend's exclusion guarantee.
+        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) {
+        outcome = `delete failed for ${node.id.slice(-12)} after ${removed} of ${plan.nodes.length}: ${error instanceof Error ? error.message : String(error)}`
+        break
+      }
+    }
+    outcome ??= `deleted ${removed} session${removed === 1 ? '' : 's'}`
+    try {
+      await releaseSessionDeletionLeases(leases)
+    } catch (error: unknown) {
+      return `${outcome}; failed to release deletion locks: ${error instanceof Error ? error.message : String(error)}`
+    }
+    return outcome
+  }
+
+  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)
+  }
+  return { loadSessions, deleteSession, loadSessionTranscript }
+}