herm-tui 1.0.0-dev.1

package/src/dialogs/rollback.tsx

@@ -0,0 +1,190 @@
+// Checkpoint rollback browser — list git-style checkpoints the gateway
+// has captured, preview a unified diff, and restore on confirm.
+//
+// State lives entirely inside <RollbackDialog>; the global dialog
+// provider closes on Esc, so when we want Esc to mean "back to list"
+// from the diff view we immediately re-replace() ourselves with the
+// already-loaded data (our key handler registers after the provider's,
+// so our replace wins the batched setState race).
+
+import { useEffect, useState } from "react"
+import { useKeyboard } from "@opentui/react"
+import { useKeys, handleListKey } from "../keys"
+import { useTheme } from "../theme"
+import type { DialogContext } from "../ui/dialog"
+import type { useToast } from "../ui/toast"
+import type { Gateway } from "../app/gateway"
+import { DiffBlock } from "../components/chat/DiffBlock"
+import { ago, trunc } from "../ui/fmt"
+
+type Toast = ReturnType<typeof useToast>
+
+type Checkpoint = { hash: string; timestamp: number; message: string }
+type ListRes = { enabled: boolean; checkpoints: Checkpoint[] }
+type DiffRes = { stat: string; diff: string; rendered?: string }
+type RestoreRes = { success: boolean; history_removed?: number }
+
+type Props = {
+  gw: Gateway
+  toast: Toast
+  dialog: DialogContext
+  /** Pre-loaded list (used when Esc re-opens at list view). */
+  initial?: ListRes
+  sel?: number
+}
+
+const RollbackDialog = (props: Props) => {
+  const theme = useTheme().theme
+  const [data, setData] = useState<ListRes | null>(props.initial ?? null)
+  const [sel, setSel] = useState(props.sel ?? 0)
+  const [diff, setDiff] = useState<DiffRes | null>(null)
+  const [confirm, setConfirm] = useState(false)
+
+  useEffect(() => {
+    if (props.initial) return
+    props.gw.request<ListRes>("rollback.list")
+      .then(setData)
+      .catch((e: Error) => setData({ enabled: false, checkpoints: [], ...{ err: e.message } } as ListRes))
+  }, [props.gw, props.initial])
+
+  const points = data?.checkpoints ?? []
+  const cur = points[sel]
+
+  const open = (cp: Checkpoint) => {
+    props.gw.request<DiffRes>("rollback.diff", { hash: cp.hash })
+      .then(setDiff)
+      .catch((e: Error) => props.toast.error(e))
+  }
+
+  const back = () => {
+    setDiff(null)
+    setConfirm(false)
+    // Provider already dispatched clear() on this Esc — replace() wins
+    // the batch. React reconciles same-type at same slot and keeps our
+    // state, so the setDiff(null) above is what actually flips the view.
+    props.dialog.replace(
+      <RollbackDialog gw={props.gw} toast={props.toast} dialog={props.dialog}
+        initial={data ?? undefined} sel={sel} />,
+    )
+  }
+
+  const restore = (cp: Checkpoint) => {
+    props.gw.request<RestoreRes>("rollback.restore", { hash: cp.hash })
+      .then(r => {
+        if (!r.success) throw new Error("restore rejected")
+        const n = r.history_removed
+        props.toast.show({ variant: "success",
+          message: `Restored ${cp.hash.slice(0, 7)}${n ? ` · ${n} turns removed` : ""}` })
+        props.dialog.clear()
+      })
+      .catch((e: Error) => {
+        props.toast.show({ variant: "error", message: `Restore failed: ${e.message}` })
+        props.dialog.clear()
+      })
+  }
+
+  const keys = useKeys()
+  useKeyboard((key) => {
+    if (diff) {
+      if (confirm) {
+        if (keys.match("dialog.confirm", key)) return restore(cur)
+        if (keys.match("dialog.deny", key) || keys.match("dialog.cancel", key)) {
+          setConfirm(false); return back()
+        }
+        return
+      }
+      if (keys.match("dialog.cancel", key)) return back()
+      if (key.name === "r") return setConfirm(true)
+      return
+    }
+    if (!data?.enabled) return
+    handleListKey(keys, key, {
+      count: points.length, setSel,
+      onActivate: () => { if (cur) open(cur) },
+    })
+  })
+
+  // ── Render ────────────────────────────────────────────────────────
+
+  if (!data) return (
+    <box width={60} height={3}>
+      <text fg={theme.textMuted}>Loading checkpoints…</text>
+    </box>
+  )
+
+  if (!data.enabled) return (
+    <box flexDirection="column" width={60} height={5}>
+      <box height={1}><text fg={theme.warning}><strong>Checkpoints disabled</strong></text></box>
+      <box height={1} />
+      <box height={1}><text fg={theme.textMuted}>Enable checkpoints in config to use /rollback.</text></box>
+      <box height={1} />
+      <box height={1}><text fg={theme.textMuted}>Esc to close</text></box>
+    </box>
+  )
+
+  if (diff) {
+    const body = diff.rendered || diff.diff || diff.stat || "(empty diff)"
+    return (
+      <box flexDirection="column" width={110} height={30}>
+        <box height={1}><text>
+          <span fg={theme.primary}><strong>Rollback · </strong></span>
+          <span fg={theme.accent}>{cur.hash.slice(0, 7)}</span>
+          <span fg={theme.textMuted}>{`  ${trunc(cur.message, 70)}`}</span>
+        </text></box>
+        <box height={1}><text fg={theme.textMuted}>{diff.stat || " "}</text></box>
+        <box height={1} />
+        <scrollbox scrollY flexGrow={1}>
+          <box flexDirection="column" width="100%">
+            <DiffBlock text={body} />
+          </box>
+        </scrollbox>
+        <box height={1} />
+        {confirm ? (
+          <box height={1}><text>
+            <span fg={theme.warning}><strong>Restore this checkpoint?  </strong></span>
+            <span fg={theme.textMuted}>[y] restore  [n] cancel</span>
+          </text></box>
+        ) : (
+          <box height={1}><text fg={theme.textMuted}>[r] restore  ·  Esc back</text></box>
+        )}
+      </box>
+    )
+  }
+
+  return (
+    <box flexDirection="column" width={90} height={Math.min(28, Math.max(8, points.length + 6))}>
+      <box height={1}><text fg={theme.primary}><strong>Rollback</strong></text></box>
+      <box height={1}><text fg={theme.textMuted}>
+        {`${points.length} checkpoints  ·  ↑↓ navigate  Enter diff  Esc close`}
+      </text></box>
+      <box height={1} />
+      {points.length === 0 ? (
+        <box height={1}><text fg={theme.textMuted}>No checkpoints yet.</text></box>
+      ) : (
+        <scrollbox scrollY flexGrow={1}>
+          <box flexDirection="column" width="100%">
+            {points.map((cp, i) => {
+              const on = i === sel
+              return (
+                <box key={cp.hash} height={1}
+                     backgroundColor={on ? theme.backgroundElement : undefined}
+                     onMouseDown={() => { setSel(i); open(cp) }}
+                     onMouseOver={() => setSel(i)}>
+                  <text>
+                    <span fg={on ? theme.primary : theme.textMuted}>{on ? "▸ " : "  "}</span>
+                    <span fg={theme.accent}>{cp.hash.slice(0, 7).padEnd(9)}</span>
+                    <span fg={theme.textMuted}>{ago(cp.timestamp).padEnd(12)}</span>
+                    <span fg={on ? theme.text : theme.textMuted}>{trunc(cp.message, 56)}</span>
+                  </text>
+                </box>
+              )
+            })}
+          </box>
+        </scrollbox>
+      )}
+    </box>
+  )
+}
+
+export const openRollback = (dialog: DialogContext, gw: Gateway, toast: Toast) =>
+  dialog.replace(<RollbackDialog gw={gw} toast={toast} dialog={dialog} />)

package/src/dialogs/spawn-history.tsx

@@ -0,0 +1,80 @@
+import type { Gateway } from "../app/gateway"
+import type { DialogContext } from "../ui/dialog"
+import { DialogSelect } from "../ui/dialog-select"
+import type { SpawnTreeEntry, SpawnTreeSnapshot, SpawnSubagent } from "../utils/gateway-types"
+import { useTheme } from "../theme"
+import { dur, when, fmt, trunc } from "../ui/fmt"
+
+// Browse persisted spawn trees (spawn_tree.list) and inspect one
+// (spawn_tree.load). Read-only — the live tree lives in the Agents tab.
+
+const Status = ({ s }: { s: SpawnSubagent["status"] }) => {
+  const theme = useTheme().theme
+  const fg = s === "completed" ? theme.success
+    : s === "failed" ? theme.error
+    : s === "interrupted" ? theme.warning
+    : theme.textMuted
+  return <span fg={fg}>{s}</span>
+}
+
+const SnapshotView = (props: { entry: SpawnTreeEntry; snap: SpawnTreeSnapshot }) => {
+  const theme = useTheme().theme
+  const subs = props.snap.subagents ?? []
+  const tok = subs.reduce((n, s) => n + (s.input_tokens ?? 0) + (s.output_tokens ?? 0), 0)
+  const span = props.snap.started_at && props.snap.finished_at
+    ? dur(props.snap.finished_at - props.snap.started_at) : "—"
+  return (
+    <box flexDirection="column" width={80}>
+      <text fg={theme.text}><strong>{props.entry.label || `${subs.length} subagents`}</strong></text>
+      <text fg={theme.textMuted}>{when(props.entry.finished_at)} · {span} · {subs.length} agents · {fmt(tok)} tok</text>
+      <box height={1} />
+      <scrollbox scrollY maxHeight={20} contentOptions={{ flexDirection: "column" }}>
+        {subs.map(s => (
+          <box key={s.subagent_id} flexDirection="column" marginBottom={1}>
+            <box height={1}>
+              <text>
+                <span fg={theme.textMuted}>{"┃ " + "· ".repeat(s.depth)}</span>
+                <span fg={theme.text}>{trunc(s.goal.replace(/\s+/g, " "), 60)}</span>
+              </text>
+            </box>
+            <box height={1}>
+              <text fg={theme.textMuted}>
+                {"┃ " + " ".repeat(2 * s.depth + 2)}
+                <Status s={s.status} />
+                {` · ${s.tool_count}t`}
+                {s.finished_at ? ` · ${dur(s.finished_at - s.started_at)}` : ""}
+                {s.model ? ` · ${s.model}` : ""}
+              </text>
+            </box>
+          </box>
+        ))}
+      </scrollbox>
+    </box>
+  )
+}
+
+export function openSpawnHistory(dialog: DialogContext, gw: Gateway, sessionId: string): void {
+  gw.request<{ entries: SpawnTreeEntry[] }>("spawn_tree.list", { session_id: sessionId, limit: 50 })
+    .then(r => {
+      const entries = r.entries ?? []
+      dialog.replace(
+        <DialogSelect
+          title="Spawn history"
+          placeholder={entries.length ? "filter…" : "no saved spawn trees"}
+          options={entries.map(e => ({
+            value: e.path,
+            title: `${e.count.toString().padStart(2)}× ${trunc(e.label || "(unlabeled)", 40)}`,
+            description: when(e.finished_at),
+            category: e.session_id === sessionId ? "This session" : e.session_id,
+          }))}
+          onSelect={opt => {
+            const entry = entries.find(e => e.path === opt.value)!
+            gw.request<SpawnTreeSnapshot>("spawn_tree.load", { path: entry.path })
+              .then(snap => dialog.replace(<SnapshotView entry={entry} snap={snap} />))
+              .catch(() => dialog.clear())
+          }}
+        />,
+      )
+    })
+    .catch(() => dialog.clear())
+}

package/src/dialogs/text-prompt.tsx

@@ -0,0 +1,68 @@
+// Single-line text prompt dialog. Enter submits, Esc cancels.
+
+import { useState } from "react"
+import { useKeyboard } from "@opentui/react"
+import { useTheme } from "../theme"
+import type { DialogContext } from "../ui/dialog"
+
+type Props = {
+  title: string
+  label?: string
+  initial?: string
+  onSubmit: (value: string) => void
+  onCancel: () => void
+}
+
+const TextPrompt = (props: Props) => {
+  const theme = useTheme().theme
+  const [value, setValue] = useState(props.initial ?? "")
+
+  useKeyboard((key) => {
+    if (key.name === "escape") return props.onCancel()
+    if (key.name === "return") {
+      const v = value.trim()
+      if (v) props.onSubmit(v)
+      return
+    }
+    if (key.name === "backspace") return setValue(v => v.slice(0, -1))
+    if (key.ctrl && key.name === "u") return setValue("")
+    if (!key.ctrl && !key.meta && key.raw && key.raw.length === 1 && key.raw >= " ")
+      return setValue(v => v + key.raw)
+  })
+
+  return (
+    <box flexDirection="column" width={60}>
+      <box height={1}><text fg={theme.primary}><strong>{props.title}</strong></text></box>
+      <box height={1} />
+      {props.label ? <box height={1}><text fg={theme.textMuted}>{props.label}</text></box> : null}
+      <box height={1} flexDirection="row" overflow="hidden">
+        <box flexShrink={0}><text fg={theme.accent}>{"┃ "}</text></box>
+        <box flexGrow={1} minWidth={0} height={1} overflow="hidden">
+          <text>
+            <span fg={theme.text}>{value}</span>
+            <span fg={theme.accent}>█</span>
+          </text>
+        </box>
+      </box>
+      <box height={1} />
+      <box height={1}><text fg={theme.textMuted}>
+        {value.trim() ? "Enter confirm  ·  Esc cancel  ·  Ctrl+U clear" : "Esc cancel"}
+      </text></box>
+    </box>
+  )
+}
+
+export function openTextPrompt(
+  dialog: DialogContext,
+  opts: { title: string; label?: string; initial?: string },
+): Promise<string | null> {
+  return new Promise((resolve) => {
+    dialog.replace(
+      <TextPrompt
+        title={opts.title} label={opts.label} initial={opts.initial}
+        onSubmit={(v) => { dialog.clear(); resolve(v) }}
+        onCancel={() => { dialog.clear(); resolve(null) }}
+      />,
+    )
+  })
+}

package/src/dialogs/theme-picker.tsx

@@ -0,0 +1,50 @@
+/**
+ * Theme picker dialog — live preview with DialogSelect.
+ */
+
+import { useCallback } from "react"
+import { useTheme } from "../theme"
+import { useDialog } from "../ui/dialog"
+import { DialogSelect } from "../ui/dialog-select"
+import type { SelectOption } from "../ui/dialog-select"
+
+const ThemePickerDialog = ({ onConfirm }: { onConfirm: () => void }) => {
+  const ctx = useTheme()
+  const dialog = useDialog()
+
+  const options: SelectOption[] = ctx.names.map(n => ({
+    title: n,
+    value: n,
+  }))
+
+  const onMove = useCallback((opt: SelectOption) => {
+    ctx.set(opt.value)
+  }, [ctx])
+
+  const onSelect = useCallback((opt: SelectOption) => {
+    ctx.set(opt.value)
+    onConfirm()
+    dialog.clear()
+  }, [ctx, dialog, onConfirm])
+
+  return (
+    <DialogSelect
+      title="Switch Theme"
+      options={options}
+      current={ctx.name}
+      onSelect={onSelect}
+      onMove={onMove}
+      placeholder="Search themes..."
+    />
+  )
+}
+
+/** Open the theme picker, reverting on close without selection */
+export const openThemePicker = (dialog: ReturnType<typeof useDialog>, ctx: ReturnType<typeof useTheme>) => {
+  const saved = ctx.name
+  let confirmed = false
+  dialog.replace(
+    <ThemePickerDialog onConfirm={() => { confirmed = true }} />,
+    () => { if (!confirmed) ctx.set(saved) }
+  )
+}

package/src/home/index.ts

@@ -0,0 +1,23 @@
+import { useEffect, useSyncExternalStore } from "react"
+import { home, type HomeState, type SliceKey } from "./store"
+
+export { home } from "./store"
+export type { HomeState, SliceKey } from "./store"
+
+/**
+ * Subscribe to a single slice of ~/.hermes/ state.
+ *
+ * Returns `undefined` until the first read resolves, then the current value.
+ * Rerenders on fs.watch-driven invalidation or explicit `home.invalidate(k)`,
+ * and only for the requested key.
+ */
+export function useHome<K extends SliceKey>(k: K): HomeState[K] | undefined {
+  const v = useSyncExternalStore(
+    (cb) => home.subscribe(k, cb),
+    () => home.get(k),
+  )
+  useEffect(() => {
+    void home.ensure(k)
+  }, [k])
+  return v
+}

package/src/home/store.ts

@@ -0,0 +1,267 @@
+/**
+ * Reactive data layer for ~/.hermes/.
+ *
+ * A slice is a typed reader with optional dependency keys and optional
+ * fs.watch paths. `ensure(k)` lazily resolves deps, reads, and starts a
+ * watcher on first pull. `invalidate(k)` drops the value, re-reads if there
+ * are subscribers, and cascades to dependents.
+ *
+ * Slices registered below; remaining readers migrate in from
+ * utils/hermes-home.ts as they're converted to collectors.
+ */
+
+import { watch, existsSync, statSync, type FSWatcher } from "node:fs"
+import { dirname, basename } from "node:path"
+import {
+  hermesPath,
+  readConfig,
+  readMemoryFile,
+  readMemoryProviders,
+  readEnvFile,
+  readSoul,
+  readLiveSessions,
+  readSystemPromptInfo,
+  readToolsFromLatestSession,
+  queryRecentSessions,
+  readSkillUsage,
+  readCuratorState,
+  type HermesConfig,
+  type MemoryFileInfo,
+  type MemoryProviderInfo,
+  type SoulInfo,
+  type LiveSession,
+  type SystemPromptInfo,
+  type ToolsInfo,
+  type SessionRow,
+  type SkillUsage,
+  type CuratorState,
+} from "../utils/hermes-home"
+import { readMemoryActivity, type MemoryActivity } from "../utils/memory-activity"
+
+// ─── State shape ──────────────────────────────────────────────────────
+
+export interface HomeState {
+  config: HermesConfig | null
+  memory: MemoryFileInfo | null
+  userProfile: MemoryFileInfo | null
+  memoryProviders: MemoryProviderInfo[]
+  memoryActivity: MemoryActivity[]
+  env: Record<string, string>
+  soul: SoulInfo | null
+  liveSessions: Record<string, LiveSession>
+  recentSessions: SessionRow[]
+  systemPrompt: SystemPromptInfo | null
+  toolsInfo: ToolsInfo | null
+  skillUsage: Record<string, SkillUsage>
+  curatorState: CuratorState | null
+}
+
+export type SliceKey = keyof HomeState
+
+export interface Slice<K extends SliceKey> {
+  /** Produce the value. Receives already-resolved dependency values. */
+  read: (deps: Partial<HomeState>) => Promise<HomeState[K]>
+  /** Slice keys this reader needs resolved first. Invalidation cascades along these edges. */
+  deps?: readonly SliceKey[]
+  /** Absolute paths to fs.watch. Change → invalidate(k). */
+  watch?: readonly string[]
+}
+
+type Slices = { [K in SliceKey]: Slice<K> }
+
+const SLICES: Slices = {
+  config: {
+    read: () => readConfig(),
+    watch: [hermesPath("config.yaml")],
+  },
+  memory: {
+    read: (d) => readMemoryFile("MEMORY.md", d.config?.memory?.memory_char_limit ?? 2200),
+    deps: ["config"],
+    watch: [hermesPath("memories/MEMORY.md")],
+  },
+  userProfile: {
+    read: (d) => readMemoryFile("USER.md", d.config?.memory?.user_char_limit ?? 1375),
+    deps: ["config"],
+    watch: [hermesPath("memories/USER.md")],
+  },
+  memoryProviders: {
+    read: (d) => readMemoryProviders(d.config?.memory?.provider ?? ""),
+    deps: ["config"],
+  },
+  memoryActivity: {
+    read: async () => readMemoryActivity(),
+  },
+  env: {
+    read: () => readEnvFile(),
+    watch: [hermesPath(".env")],
+  },
+  soul: {
+    read: () => readSoul(),
+    watch: [hermesPath("SOUL.md")],
+  },
+  liveSessions: {
+    read: () => readLiveSessions(),
+    watch: [hermesPath("sessions/sessions.json")],
+  },
+  // DB-backed slices are pull-only: WAL mode means writes land in
+  // state.db-wal, so watching state.db misses them until checkpoint;
+  // and the query is heavy enough that firing on every checkpoint from
+  // an always-mounted Sidebar is wasteful. Consumers invalidate on
+  // demand (section-open, `r`, post-mutation).
+  recentSessions: {
+    read: async () => queryRecentSessions(),
+  },
+  systemPrompt: {
+    read: async () => readSystemPromptInfo(),
+  },
+  toolsInfo: {
+    // Scans sessions/ for newest session_*.json — watching the dir picks
+    // up new files without tracking a specific one.
+    read: () => readToolsFromLatestSession(),
+    watch: [hermesPath("sessions")],
+  },
+  skillUsage: {
+    read: () => readSkillUsage(),
+    watch: [hermesPath("skills/.usage.json")],
+  },
+  curatorState: {
+    read: () => readCuratorState(),
+    watch: [hermesPath("skills/.curator_state")],
+  },
+}
+
+/** Reverse dep edges: key → slices that listed it in `deps`. */
+const DEPENDENTS: ReadonlyMap<SliceKey, readonly SliceKey[]> = (() => {
+  const m = new Map<SliceKey, SliceKey[]>()
+  for (const [k, s] of Object.entries(SLICES) as [SliceKey, Slice<SliceKey>][]) {
+    for (const d of s.deps ?? []) {
+      const arr = m.get(d) ?? []
+      arr.push(k)
+      m.set(d, arr)
+    }
+  }
+  return m
+})()
+
+// ─── Store ────────────────────────────────────────────────────────────
+
+const DEBOUNCE_MS = 50
+
+export class HomeStore {
+  private data: Partial<HomeState> = {}
+  private subs = new Map<SliceKey, Set<() => void>>()
+  private inflight = new Map<SliceKey, Promise<unknown>>()
+  private watchers = new Map<SliceKey, FSWatcher[]>()
+  private debounce = new Map<SliceKey, ReturnType<typeof setTimeout>>()
+
+  /** Current value, or undefined if not yet loaded. Stable ref until changed. */
+  get<K extends SliceKey>(k: K): HomeState[K] | undefined {
+    return this.data[k] as HomeState[K] | undefined
+  }
+
+  /** Register a change listener. Returns unsubscribe. */
+  subscribe<K extends SliceKey>(k: K, cb: () => void): () => void {
+    let set = this.subs.get(k)
+    if (!set) this.subs.set(k, (set = new Set()))
+    set.add(cb)
+    return () => set.delete(cb)
+  }
+
+  /**
+   * Resolve deps, read, store, start watching (first call only), notify.
+   * Concurrent calls for the same key share one inflight promise.
+   */
+  ensure<K extends SliceKey>(k: K): Promise<HomeState[K]> {
+    if (k in this.data) return Promise.resolve(this.data[k] as HomeState[K])
+    const hit = this.inflight.get(k)
+    if (hit) return hit as Promise<HomeState[K]>
+
+    const slice = SLICES[k]
+    const p = (async () => {
+      const deps: Partial<HomeState> = {}
+      for (const d of slice.deps ?? []) {
+        (deps as Record<SliceKey, unknown>)[d] = await this.ensure(d)
+      }
+      const v = await slice.read(deps)
+      this.data[k] = v
+      this.startWatch(k, slice.watch)
+      this.notify(k)
+      return v
+    })().finally(() => this.inflight.delete(k))
+
+    this.inflight.set(k, p)
+    return p
+  }
+
+  /**
+   * Drop the cached value; re-read if there are subscribers. Cascades to
+   * dependents. Call after TUI-driven writes so the UI reflects the change
+   * without waiting on a watch event.
+   */
+  invalidate(k: SliceKey): void {
+    if (!(k in this.data) && !this.inflight.has(k)) return
+    delete this.data[k]
+    if (this.subs.get(k)?.size) void this.ensure(k)
+    for (const dep of DEPENDENTS.get(k) ?? []) this.invalidate(dep)
+  }
+
+  /** Dispose all watchers and timers. Tests must call this. */
+  close(): void {
+    for (const ws of this.watchers.values()) for (const w of ws) w.close()
+    for (const t of this.debounce.values()) clearTimeout(t)
+    this.watchers.clear()
+    this.debounce.clear()
+    this.subs.clear()
+    this.inflight.clear()
+    this.data = {}
+  }
+
+  private notify(k: SliceKey): void {
+    const set = this.subs.get(k)
+    if (set) for (const cb of set) cb()
+  }
+
+  private startWatch(k: SliceKey, paths: readonly string[] | undefined): void {
+    if (!paths || this.watchers.has(k)) return
+    const ws: FSWatcher[] = []
+    const fire = () => {
+      const prev = this.debounce.get(k)
+      if (prev) clearTimeout(prev)
+      this.debounce.set(k, setTimeout(() => this.invalidate(k), DEBOUNCE_MS))
+    }
+    for (const p of paths) {
+      // Watching a file by path is unreliable across rewrites on Linux
+      // (inotify binds to the inode). Watch the parent dir and filter on
+      // basename so rename-into-place editors still fire. Only watch the
+      // path itself when it's an existing directory.
+      //
+      // Known runtime gap: Bun's fs.watch(dir) never emits for entries
+      // created after the watcher was armed (Node does). A target that
+      // didn't exist at first ensure stays non-reactive for the process
+      // lifetime. In practice only an optional file absent at launch is
+      // affected; in-TUI writes call invalidate() which re-reads directly,
+      // and `r` forces a manual refresh for the rare external-edit case.
+      let dir = dirname(p)
+      let name: string | null = basename(p)
+      try {
+        if (existsSync(p) && statSync(p).isDirectory()) {
+          dir = p
+          name = null
+        }
+      } catch {
+        continue
+      }
+      if (!existsSync(dir)) continue
+      try {
+        ws.push(watch(dir, { persistent: false }, (_ev, f) => {
+          if (name === null || f === name) fire()
+        }))
+      } catch {
+        // Unwatchable (permissions, exotic fs). Slice still works; just not reactive.
+      }
+    }
+    this.watchers.set(k, ws)
+  }
+}
+
+export const home = new HomeStore()