dsh-code 0.3.0 → 0.5.0

package/src/render/status.ts

@@ -36,6 +36,18 @@ export function formatDuration(ms: number): string {
   return `${Math.floor(whole / 60)}m${whole % 60}s`
 }
 
+/**
+ * Compact decode rate: one decimal under a hundred, whole below a thousand,
+ * then thousands (15.3 / 124 / 1.2K).
+ * @param n - tokens per second.
+ * @returns display string.
+ */
+export function formatRate(n: number): string {
+  if (n < 100) return String(Math.round(n * 10) / 10)
+  if (n < 1_000) return String(Math.round(n))
+  return `${Math.round(n / 100) / 10}K`
+}
+
 /**
  * Cache-hit share of billed prompt-side input.
  * @param usage - cumulative token totals.
@@ -51,12 +63,20 @@ export function cacheHitPercent(usage: TranscriptStats['usage']): number | null
 export interface StatusFacts {
   /** `provider/model` selection serving this session. */
   model: string
+  /** Agent preset composing this session. */
+  mode?: string
   /** Working-directory basename the session serves. */
   cwd: string
   /** Git branch name, empty outside a repository or on a detached HEAD file. */
   branch: string
   /** Short session identifier (last dash-separated segment or tail). */
   sessionId: string
+  /** Latest session title (folded from `session/title`); shown in place of the id. */
+  title: string
+  /** Sandbox-mode override (folded from `sandbox/mode`), empty when never switched. */
+  sandbox: string
+  /** Live goal summary (folded from `goal/change`), undefined when none. */
+  goal: { phase: string; rounds: number; max: number } | undefined
   /** Whether plan mode is active (folded from `plan/mode`). */
   plan: boolean
   /** Active permission preset (folded from `permission/preset`), empty when unknown. */
@@ -78,22 +98,52 @@ export function buildStatusGroups(facts: StatusFacts, stats: TranscriptStats): s
     facts.plan ? '⧉ plan' : undefined,
   ].filter(part => part !== undefined && part !== '')
   if (identity.length > 0) groups.push(identity.join(' · '))
+  if (facts.mode !== undefined && facts.mode !== '') groups.push(`mode ${facts.mode}`)
   if (stats.turns > 0 || stats.steps > 0) {
     groups.push(`T${stats.turns} · S${stats.steps}`)
     const durations: string[] = []
     if (stats.llmMs > 0) durations.push(`llm ${formatDuration(stats.llmMs)}`)
+    // Decode latency figures (the web StatsLine's TTFT and throughput):
+    // average first-token wait and tokens per second over timed steps.
+    if (stats.ttftSteps > 0) durations.push(`ttft ${formatDuration(stats.ttftMs / stats.ttftSteps)}`)
+    if (stats.decodeMs > 0 && stats.decodeTokens > 0) {
+      durations.push(`${formatRate(stats.decodeTokens / (stats.decodeMs / 1_000))} tok/s`)
+    }
     if (stats.toolMs > 0) durations.push(`tool ${formatDuration(stats.toolMs)}`)
     if (durations.length > 0) groups.push(durations.join(' · '))
   }
   const cacheHit = cacheHitPercent(stats.usage)
   if (stats.usage.inputTokens > 0 || stats.usage.outputTokens > 0) {
     if (cacheHit !== null) groups.push(`cache ${cacheHit}%`)
+    // Context occupancy (the web StatsLine's meter): the most recent
+    // reported prompt size against the advertised route capacity.
+    if (stats.contextWindow > 0 && stats.lastPromptTokens > 0) {
+      groups.push(`ctx ${Math.min(999, Math.round(stats.lastPromptTokens / stats.contextWindow * 100))}%`)
+    }
     groups.push(`↑${formatTokens(stats.usage.inputTokens)} ↓${formatTokens(stats.usage.outputTokens)}`)
   }
-  if (facts.sessionId !== '') groups.push(facts.sessionId)
+  // The session title replaces the bare short id whenever one has landed
+  // (user rename or provider generation), bounded so a long title cannot
+  // crowd out the rest of the line.
+  const label = facts.title !== undefined && facts.title !== ''
+    ? (facts.title.length > 48 ? `${facts.title.slice(0, 47)}…` : facts.title)
+    : facts.sessionId
+  if (label !== '') groups.push(label)
   // The permission preset trails the line: switching it changes only the
   // tail, so the left-aligned bar never shifts its other groups. Plain text,
   // the Claude-Code permission-mode display (no glyphs).
   if (facts.permission !== undefined && facts.permission !== '') groups.push(facts.permission)
+  // The sandbox override stays implicit when it merely echoes the preset —
+  // the badge exists to surface a divergence, not to duplicate the label.
+  const sandbox = facts.sandbox ?? ''
+  if (sandbox !== '' && sandbox.toLowerCase() !== facts.permission.toLowerCase()) {
+    groups.push(`sandbox ${sandbox}`)
+  }
+  // Goal badge: round progress while active, the phase otherwise.
+  if (facts.goal !== undefined) {
+    groups.push(facts.goal.phase === 'active'
+      ? `◎ r${facts.goal.rounds}/${facts.goal.max}`
+      : `◎ ${facts.goal.phase}`)
+  }
   return groups
 }

package/src/render/text.ts

@@ -22,3 +22,110 @@ const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu
 export function displayText(text: string): string {
   return text.replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
+
+/** Collapse external text to one terminal-safe logical row. */
+export function singleLineText(text: string): string {
+  return displayText(text).replace(/\r?\n/gu, ' ↵ ').replace(/\t/gu, '  ')
+}
+
+/** Terminal-cell width matching the TUI's existing CJK-aware wrapping rule. */
+function cellWidth(text: string): number {
+  let columns = 0
+  for (const char of text) {
+    columns += (char.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1
+  }
+  return columns
+}
+
+/**
+ * Truncate one display-safe row without ever exceeding its physical-column
+ * budget. The ellipsis is included inside the budget, matching Codex's popup
+ * truncation contract; the previous app-local helper appended it after the
+ * row was already full and could force an extra terminal wrap.
+ */
+export function truncateColumns(text: string, columns: number): string {
+  const limit = Math.max(0, Math.floor(columns))
+  if (limit === 0) return ''
+  if (cellWidth(text) <= limit) return text
+
+  const contentLimit = limit - 1
+  let used = 0
+  let result = ''
+  for (const char of text) {
+    const width = cellWidth(char)
+    if (used + width > contentLimit) break
+    result += char
+    used += width
+  }
+  return `${result}…`
+}
+
+/** A display-safe suffix bounded by terminal rows and columns. */
+export interface DisplayTail {
+  /** Sanitized suffix suitable for direct terminal rendering. */
+  text: string
+  /** Whether content before the returned suffix was omitted. */
+  truncated: boolean
+}
+
+/** Read one Unicode character immediately before `end`. */
+function previousCharacter(text: string, end: number): { char: string; start: number } {
+  const last = text.charCodeAt(end - 1)
+  if (last >= 0xdc00 && last <= 0xdfff && end >= 2) {
+    const first = text.charCodeAt(end - 2)
+    if (first >= 0xd800 && first <= 0xdbff) {
+      return { char: text.slice(end - 2, end), start: end - 2 }
+    }
+  }
+  return { char: text.slice(end - 1, end), start: end - 1 }
+}
+
+/**
+ * Keep only the newest display-safe text that fits a terminal rectangle.
+ * The scan walks backward and stops as soon as the suffix is full, so a long
+ * reasoning stream does not rescan its entire accumulated prefix per chunk.
+ * Explicit newlines and terminal wrapping both consume rows.
+ * @param text - raw externally sourced text.
+ * @param columns - available terminal columns.
+ * @param rows - available terminal rows.
+ * @returns a sanitized bounded suffix and whether an earlier prefix was cut.
+ */
+export function displayTail(text: string, columns: number, rows: number): DisplayTail {
+  const columnLimit = Math.max(1, Math.floor(columns))
+  const rowLimit = Math.max(1, Math.floor(rows))
+  const reversed: string[] = []
+  let row = 1
+  let used = 0
+  let end = text.length
+
+  while (end > 0) {
+    const previous = previousCharacter(text, end)
+    if (previous.char === '\n') {
+      if (row >= rowLimit) break
+      reversed.push('\n')
+      row += 1
+      used = 0
+      end = previous.start
+      continue
+    }
+
+    const safe = displayText(previous.char)
+    const width = cellWidth(safe)
+    if (used > 0 && used + width > columnLimit) {
+      if (row >= rowLimit) break
+      // Materialize the soft wrap. Ink otherwise reflows at word boundaries
+      // and can turn a cell-counted two-row suffix into three rendered rows.
+      reversed.push('\n')
+      row += 1
+      used = 0
+    }
+    const extraRows = Math.floor(Math.max(0, width - 1) / columnLimit)
+    if (row + extraRows > rowLimit) break
+    row += extraRows
+    reversed.push(safe)
+    used = extraRows === 0 ? used + width : width - extraRows * columnLimit
+    end = previous.start
+  }
+
+  return { text: reversed.reverse().join(''), truncated: end > 0 }
+}

package/src/render/tool-detail.ts

@@ -0,0 +1,197 @@
+/**
+ * Expansion payloads for tool cards (the Ctrl+O verbose transcript): the
+ * TUI-side consumption of the harness presentation contract. Mutation and
+ * read tools persist a structured `tool/result.meta` (`diffs`, read
+ * windows, web sources) exactly so a capable UI can replay richer cards than
+ * the model-facing text; this module narrows that opaque JSON defensively —
+ * mirroring the upstream validators — and pre-formats bounded, render-ready
+ * rows. Malformed or absent metadata always degrades to the bounded raw
+ * result text, never throws during replay.
+ *
+ * @module @deepseek-ai/dsh-code/render/tool-detail
+ */
+
+/** Budgets keeping one expanded card bounded on a terminal. */
+const MAX_DIFF_LINES = 200
+const MAX_READ_LINES = 120
+const MAX_SOURCES = 10
+const MAX_RAW_CHARS = 6000
+const MAX_LINE_COLUMNS = 240
+
+/** One rendered diff row: removed, added, or shared context. */
+export interface DiffLine {
+  /** '-' removed, '+' added, ' ' context. */
+  mark: '-' | '+' | ' '
+  /** The line text, truncated to the column budget. */
+  text: string
+}
+
+/** One file's bounded inline diff. */
+export interface ToolDiff {
+  /** File path the change belongs to. */
+  path: string
+  /** Rendered rows in order; '-' block before the '+' block. */
+  lines: readonly DiffLine[]
+  /** True when the line budget cut the hunk. */
+  truncated: boolean
+}
+
+/** One numbered line of a read window. */
+export interface ToolReadLine {
+  /** 1-based file line number. */
+  number: number
+  /** The line text, truncated to the column budget. */
+  text: string
+}
+
+/** One web-search source row. */
+export interface ToolWebSource {
+  /** Source URL. */
+  url: string
+  /** Source title, when the provider returned one. */
+  title: string | undefined
+  /** Short excerpt, truncated to the column budget. */
+  snippet: string
+}
+
+/** The expansion payload a verbose tool card renders; a discriminated union. */
+export type ToolDetail =
+  | { kind: 'diff'; diffs: readonly ToolDiff[] }
+  | { kind: 'read'; path: string; offset: number; lines: readonly ToolReadLine[]; totalLines: number; truncated: boolean }
+  | { kind: 'web-search'; sources: readonly ToolWebSource[]; truncated: boolean }
+  | { kind: 'web-fetch'; url: string; statusCode: number }
+  | { kind: 'raw'; text: string; truncated: boolean }
+
+/** Truncate one line to the visible-column budget with an ellipsis marker. */
+function clipLine(text: string): string {
+  return text.length > MAX_LINE_COLUMNS ? `${text.slice(0, MAX_LINE_COLUMNS - 1)}…` : text
+}
+
+/** Split text into lines, dropping the trailing empty element of a final newline. */
+function toLines(text: string): string[] {
+  const split = text.split('\n')
+  return split.length > 0 && split[split.length - 1] === '' ? split.slice(0, -1) : split
+}
+
+/**
+ * Render one change as removed-then-added rows, hunked by common prefix and
+ * suffix. A null before-image (file create) renders as pure additions. The
+ * budget caps emitted rows and reports the cut, so a whole-file overwrite
+ * never floods the transcript.
+ * @param oldText - prior content, or null for a create.
+ * @param newText - content after the change.
+ * @param budget - maximum rows to emit.
+ * @returns the bounded rows and whether they were cut.
+ */
+export function diffRows(oldText: string | null, newText: string, budget: number): { lines: readonly DiffLine[]; truncated: boolean } {
+  const oldLines = oldText === null ? [] : toLines(oldText)
+  const newLines = toLines(newText)
+  let prefix = 0
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) prefix += 1
+  let suffix = 0
+  while (
+    suffix < oldLines.length - prefix && suffix < newLines.length - prefix
+    && oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) suffix += 1
+  const removed = oldLines.slice(prefix, oldLines.length - suffix)
+  const added = newLines.slice(prefix, newLines.length - suffix)
+  const rows: DiffLine[] = [
+    ...removed.map((text): DiffLine => ({ mark: '-', text: clipLine(text) })),
+    ...added.map((text): DiffLine => ({ mark: '+', text: clipLine(text) })),
+  ]
+  if (rows.length <= budget) return { lines: rows, truncated: false }
+  return { lines: rows.slice(0, budget), truncated: true }
+}
+
+/** Whether `value` is a valid upstream FileDiff (defensive narrowing). */
+function isFileDiff(value: unknown): value is { path: string; oldText: string | null; newText: string } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const { path, oldText, newText } = value as Record<string, unknown>
+  return typeof path === 'string' && (oldText === null || typeof oldText === 'string') && typeof newText === 'string'
+}
+
+/** Whether `value` is a valid read-window line (defensive narrowing). */
+function isReadLine(value: unknown): value is { number: number; text: string } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const { number, text } = value as Record<string, unknown>
+  return typeof number === 'number' && Number.isInteger(number) && number >= 1 && typeof text === 'string'
+}
+
+/** Whether `value` is a valid web source (defensive narrowing). */
+function isWebSource(value: unknown): value is { url: string; title?: unknown; snippet?: unknown } {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const { url, title, snippet } = value as Record<string, unknown>
+  return typeof url === 'string'
+    && (title === undefined || typeof title === 'string')
+    && (snippet === undefined || typeof snippet === 'string')
+}
+
+/**
+ * Narrow the opaque `tool/result.meta` into one bounded expansion payload,
+ * mirroring the upstream presenters' degradation ladder: diffs (write/edit),
+ * read windows (read), sources (web_search), fetch summaries (web_fetch), and
+ * the bounded raw result text as the universal fallback.
+ * @param meta - the persisted presentation metadata, when the tool attached one.
+ * @param rawText - the joined text blocks of the result message.
+ * @returns the expansion payload, or undefined when nothing renderable exists.
+ */
+export function toolResultDetail(meta: unknown, rawText: string): ToolDetail | undefined {
+  if (typeof meta === 'object' && meta !== null && !Array.isArray(meta)) {
+    const record = meta as Record<string, unknown>
+
+    const diffs = record['diffs']
+    if (Array.isArray(diffs) && diffs.length > 0 && diffs.every(isFileDiff)) {
+      const budget = Math.max(8, Math.floor(MAX_DIFF_LINES / diffs.length))
+      return {
+        kind: 'diff',
+        diffs: diffs.map(diff => ({
+          path: diff.path,
+          ...diffRows(diff.oldText, diff.newText, budget),
+        })),
+      }
+    }
+
+    const { path, offset, lines, totalLines } = record
+    if (typeof path === 'string' && Number.isInteger(offset) && (offset as number) >= 1
+      && Number.isInteger(totalLines) && (totalLines as number) >= 0
+      && Array.isArray(lines) && lines.every(isReadLine)) {
+      const window = lines as { number: number; text: string }[]
+      const truncated = window.length > MAX_READ_LINES
+      return {
+        kind: 'read',
+        path,
+        offset: offset as number,
+        lines: (truncated ? window.slice(0, MAX_READ_LINES) : window)
+          .map(line => ({ number: line.number, text: clipLine(line.text) })),
+        totalLines: totalLines as number,
+        truncated,
+      }
+    }
+
+    const sources = record['sources']
+    if (Array.isArray(sources) && sources.every(isWebSource)) {
+      const truncated = sources.length > MAX_SOURCES
+      return {
+        kind: 'web-search',
+        sources: (truncated ? sources.slice(0, MAX_SOURCES) : sources).map(source => ({
+          url: source.url,
+          title: typeof source.title === 'string' ? source.title : undefined,
+          snippet: typeof source.snippet === 'string' ? clipLine(source.snippet) : '',
+        })),
+        truncated,
+      }
+    }
+
+    const { url, statusCode } = record
+    if (typeof url === 'string' && typeof statusCode === 'number') {
+      return { kind: 'web-fetch', url, statusCode: Math.trunc(statusCode) }
+    }
+  }
+  if (rawText === '') return undefined
+  const truncated = rawText.length > MAX_RAW_CHARS
+  return {
+    kind: 'raw',
+    text: truncated ? rawText.slice(0, MAX_RAW_CHARS) : rawText,
+    truncated,
+  }
+}

package/src/session-directory.ts

@@ -0,0 +1,102 @@
+/** Lightweight session-directory projection for the /resume picker. */
+
+import { basename, resolve } from 'node:path'
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
+
+export interface SessionRecord {
+  readonly header: SessionHeader
+  readonly live: boolean
+  readonly persisted: boolean
+}
+
+export interface TitleObservationResult {
+  readonly sessionId: string
+  readonly status: 'fulfilled' | 'rejected'
+  readonly value?: { readonly title?: { readonly title?: string; readonly text?: string } }
+}
+
+export interface SessionLogSnapshot {
+  readonly session: SessionHeader
+  readonly events: SessionEvent[]
+}
+
+/** Structural upstream SessionQuery surface used by the TUI. */
+export interface SessionQueryService {
+  listSessions(signal?: AbortSignal): Promise<SessionRecord[]>
+  readTitleSnapshots(ids: readonly string[], signal?: AbortSignal): Promise<TitleObservationResult[]>
+  readSession(id: string, signal?: AbortSignal): Promise<SessionLogSnapshot>
+}
+
+export type SessionScope = 'roots' | 'all'
+export type CwdScope = 'all' | 'current'
+export type SessionSort = 'newest' | 'oldest'
+
+export interface SessionDirectoryOptions {
+  readonly sessions: SessionScope
+  readonly cwd: CwdScope
+  readonly sort: SessionSort
+  readonly currentCwd: string
+  readonly query: string
+}
+
+export interface SessionRow {
+  readonly id: string
+  readonly createdAt: number
+  readonly cwd: string
+  readonly workspace: string
+  readonly parent?: string
+  readonly subagent: boolean
+  readonly resumable: boolean
+  readonly live: boolean
+  readonly persisted: boolean
+  readonly preset: string
+  readonly title?: string
+}
+
+function samePath(left: string | undefined, right: string): boolean {
+  if (left === undefined) return false
+  return resolve(left).toLowerCase() === resolve(right).toLowerCase()
+}
+
+/** Filter/sort header-only records. No session log is loaded here. */
+export function projectSessionRows(records: readonly SessionRecord[], options: SessionDirectoryOptions): SessionRow[] {
+  const needle = options.query.trim().toLowerCase()
+  return records
+    .filter(record => options.sessions === 'all'
+      || (record.header.parentSession === undefined && record.header.origin !== 'subagent'))
+    .filter(record => options.cwd === 'all' || samePath(record.header.cwd, options.currentCwd))
+    .map(record => {
+      const cwd = record.header.cwd ?? ''
+      const subagent = record.header.origin === 'subagent' || record.header.parentSession !== undefined
+      return {
+        id: record.header.id,
+        createdAt: record.header.createdAt,
+        cwd,
+        workspace: cwd === '' ? '(no workspace)' : basename(cwd),
+        parent: record.header.parentSession,
+        subagent,
+        resumable: !subagent,
+        live: record.live,
+        persisted: record.persisted,
+        preset: record.header.agentPreset ?? 'standard',
+      }
+    })
+    .filter(row => needle === '' || `${row.id} ${row.cwd} ${row.workspace} ${row.preset}`.toLowerCase().includes(needle))
+    .sort((left, right) => options.sort === 'newest'
+      ? right.createdAt - left.createdAt
+      : left.createdAt - right.createdAt)
+}
+
+/** Merge page-local title observations without disturbing directory order. */
+export function mergeSessionTitles(
+  rows: readonly SessionRow[],
+  observations: readonly TitleObservationResult[],
+): SessionRow[] {
+  const titles = new Map<string, string>()
+  for (const observation of observations) {
+    if (observation.status !== 'fulfilled') continue
+    const title = observation.value?.title?.title ?? observation.value?.title?.text
+    if (title !== undefined && title.trim() !== '') titles.set(observation.sessionId, title)
+  }
+  return rows.map(row => titles.has(row.id) ? { ...row, title: titles.get(row.id) } : row)
+}

package/src/session-switch.ts

@@ -0,0 +1,58 @@
+/** Latest-wins, idle-bound queue for safe Agent session changes. */
+
+export interface IdleActivity {
+  readonly status: 'idle' | 'running'
+  whenIdle(): Promise<void>
+}
+
+interface Request<T> {
+  readonly activity: IdleActivity
+  readonly value: T
+}
+
+export class SessionSwitchQueue<T> {
+  private pending: Request<T> | undefined
+  private pumping = false
+
+  constructor(
+    private readonly execute: (value: T) => Promise<void>,
+    private readonly failed: (error: unknown) => void,
+  ) {}
+
+  /** Queue a request; a later request replaces any request still waiting. */
+  request(activity: IdleActivity, value: T): 'queued' | 'started' {
+    this.pending = { activity, value }
+    const outcome = activity.status === 'running' || this.pumping ? 'queued' : 'started'
+    if (!this.pumping) void this.pump()
+    return outcome
+  }
+
+  /** Cancel only work that has not begun activation. */
+  cancel(): boolean {
+    if (this.pending === undefined) return false
+    this.pending = undefined
+    return true
+  }
+
+  private async pump(): Promise<void> {
+    this.pumping = true
+    try {
+      while (this.pending !== undefined) {
+        const observed = this.pending
+        await observed.activity.whenIdle()
+        // Another request replaced this one while the turn was converging.
+        if (this.pending !== observed) continue
+        this.pending = undefined
+        try {
+          await this.execute(observed.value)
+        } catch (error: unknown) {
+          this.failed(error)
+        }
+      }
+    } finally {
+      this.pumping = false
+      // A request may land between the loop condition and finally.
+      if (this.pending !== undefined) void this.pump()
+    }
+  }
+}

package/src/skills.ts

@@ -28,6 +28,8 @@ export interface SkillRow {
 export interface SkillsView {
   /** Name-sorted user-invocable rows; empty until the first load lands. */
   readonly rows: readonly SkillRow[]
+  /** Latest catalog-read failure; the help panel exposes it in place. */
+  readonly error?: string
   /** Subscribe to catalog changes; returns the unsubscribe function. */
   subscribe(listener: () => void): () => void
   /** Retarget the agent whose workspace the catalog is read for. */
@@ -63,21 +65,29 @@ export function watchSkills(ctx: Context): SkillsWatch {
   const skills = ctx.get('skills')
   let agent: Agent | undefined
   let rows: readonly SkillRow[] = []
+  let error: string | undefined
   const listeners = new Set<() => void>()
 
   const reload = (): void => {
-    if (skills === undefined || agent === undefined) return
-    skills.list({
-      cwd: agent.session.header.cwd,
-      scope: agent,
-    }).then((summaries: readonly SkillSummary[]) => {
+    const currentAgent = agent
+    if (skills === undefined || currentAgent === undefined) return
+    Promise.resolve().then(() => skills.list({
+      cwd: currentAgent.session.header.cwd,
+      scope: currentAgent,
+    })).then((summaries: readonly SkillSummary[]) => {
       const next = toRows(summaries)
-      if (next.length === rows.length && next.every((row, index) => row.name === rows[index]?.name)) return
+      const unchanged = next.length === rows.length && next.every((row, index) => row.name === rows[index]?.name)
       rows = next
+      const recovered = error !== undefined
+      error = undefined
+      if (unchanged && !recovered) return
       for (const listener of listeners) listener()
-    }, () => {
+    }).catch((cause: unknown) => {
       // Discovery failure keeps the last good rows; the next skills/change
       // notification is the retry surface (mirrors the web directory).
+      rows = [...rows]
+      error = cause instanceof Error ? cause.message : String(cause)
+      for (const listener of listeners) listener()
     })
   }
 
@@ -89,6 +99,9 @@ export function watchSkills(ctx: Context): SkillsWatch {
     get rows(): readonly SkillRow[] {
       return rows
     },
+    get error(): string | undefined {
+      return error
+    },
     subscribe(listener: () => void): () => void {
       listeners.add(listener)
       return () => {