chore: Bump version to 2.7.1

Scarf's `MACOSX_DEPLOYMENT_TARGET` is `14.6` (Sonoma) on the main
`scarf` target, set in 86762ea. Sonoma support is intentional —
several users dogfood on macOS 14.x and we want to keep them on the
release channel. Yesterday's BUILDING.md and the long-stale
CONTRIBUTING.md statement both claimed macOS/Xcode 26.x as minimums,
which would have steered Sonoma contributors and users away from a
build that actually runs on their box.

Correct values:

- Runtime min: **macOS 14.6 (Sonoma)** — matches the deployment target.
- Build min: **Xcode 16.0** — needed for Swift 6 strict-concurrency
  features the codebase uses.

Add a load-bearing-callout to BUILDING.md so future doc edits don't
silently raise the floor again.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -61,3 +61,8 @@ releases/v*/appcast-entry.xml
 
 # Wiki helper: personal patterns (hostnames, IPs) blocked from the wiki push.
 scripts/wiki-blocklist.txt
+
+# TestFlight feedback / crash JSONs downloaded for triage. PII (emails,
+# carriers, locales) and never meant for the public repo — kept local
+# while a fix round is in progress, deleted afterward.
+crashes/

BUILDING.md

@@ -0,0 +1,24 @@
+# Building Scarf
+
+Scarf is a native macOS app built with Xcode. For contributor builds, use the local script:
+
+```bash
+./scripts/local-build.sh
+```
+
+Requirements:
+
+- macOS 14.6 (Sonoma) or newer at runtime — that's the app's `MACOSX_DEPLOYMENT_TARGET`. Sonoma support is intentional and load-bearing; do not raise this without an explicit decision to drop Sonoma users
+- Xcode 16.0 or newer, selected by `xcode-select` (needed for Swift 6 strict-concurrency features the project uses)
+- Metal toolchain installed
+- Hermes installed at `~/.hermes/` (see the project README for setup)
+
+If the Metal toolchain is missing, the script will offer to install it in interactive shells. You can also install it manually:
+
+```bash
+xcodebuild -downloadComponent MetalToolchain
+```
+
+`scripts/local-build.sh` resolves Swift package dependencies, detects `arm64` vs `x86_64`, and builds the Debug app unsigned. Signing is intentionally disabled for local Debug builds so contributors do not need the maintainer's Apple Developer account.
+
+Release signing is separate from contributor builds. Maintainers should continue using the existing release process for signed distributable builds.

CLAUDE.md

@@ -113,9 +113,28 @@ Public documentation lives in the GitHub wiki at https://github.com/awizemann/sc
 
 ## Hermes Version
 
-Targets Hermes v2026.4.23 (v0.11.0). Log lines may carry an optional `[session_id]` tag between the level and logger name — `HermesLogService.parseLine` treats the session tag as an optional capture group, so older untagged lines still parse.
+Targets Hermes v2026.4.30 (v0.12.0). Log lines may carry an optional `[session_id]` tag between the level and logger name — `HermesLogService.parseLine` treats the session tag as an optional capture group, so older untagged lines still parse.
 
-**v2026.4.23 (v0.11.0)** added (Scarf-relevant subset):
+**Capability gating.** Scarf detects the target's Hermes version once per server connection via [HermesCapabilities](scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift) (`hermes --version` → semver + `YYYY.M.D` parse). The resulting `HermesCapabilitiesStore` is injected on `ContextBoundRoot` (Mac) and `ScarfGoTabRoot` (iOS) via `.environment(_:)` and `.hermesCapabilities(_:)`; UI that depends on a v0.12+ surface (Curator, Kanban, ACP image input, `auxiliary.curator`, `prompt_caching.cache_ttl`, Piper TTS, Vercel terminal) reads it through the typed environment key. Pre-v0.12 hosts gracefully hide the new affordances rather than throwing on unknown CLI subcommands. Add a new flag at the top of `HermesCapabilities` whenever Scarf gains a release-gated UI surface.
+
+**v2026.4.30 (v0.12.0)** added (Scarf-relevant subset):
+
+- **Autonomous Curator** — `hermes curator` self-prunes / -consolidates the skill library on a 7-day cycle. Reports land at `~/.hermes/logs/curator/run.json` + `REPORT.md`; paths exposed via `HermesPathSet.curatorLogsDir` (`logs/curator`) + `curatorStateFile` (`skills/.curator_state`), with the per-cycle `run.json` / `REPORT.md` resolved at runtime from the `last_report_path` field on the state file. Surfaced in Scarf as a dedicated "Curator" sidebar item under Interact (between Memory and Skills) on Mac, plus a read-mostly iOS panel with Run Now / Pause / Resume actions and inline pin toggles; both gated on `HermesCapabilities.hasCurator`.
+- **5 new inference providers** — GMI Cloud, Azure AI Foundry, LM Studio (upgraded to first-class), MiniMax OAuth, Tencent Tokenhub. Mirrored in `ModelCatalogService.overlayOnlyProviders`; the model picker reaches all of them automatically.
+- **`flush_memories` aux task removed (server side)** — `auxiliary.flush_memories` is gone from v0.12 Hermes config but remains alive on pre-v0.12 hosts. Scarf preserves `AuxiliarySettings.flushMemories: AuxiliaryModel`, the YAML reader still emits an `aux("flush_memories")` row, and `AuxiliaryTab` only renders the row when `HermesCapabilities.hasFlushMemoriesAux` is `true` (inverse semantics — pre-v0.12 only). v0.12 users never see the row; v0.11 users keep their edit surface.
+- **`auxiliary.curator` aux task added** — Curator's review model is configurable independently of the main model. Surfaced in `Settings → Auxiliary` next to the other aux rows.
+- **Multimodal ACP `session/prompt`** — ACP advertises and forwards image content blocks. Scarf chat composers (Mac drag/drop + paste; iOS PhotosPicker) attach images that flow through `ACPClient.sendPrompt(sessionId:text:images:)` as `[{"type":"text","text":...}, {"type":"image","data":"<base64>","mimeType":"image/jpeg"}]` — wire shape matches `acp.schema.ImageContentBlock`. `ImageEncoder` downsamples to 1568px long-edge JPEG q=0.85 detached (never blocks MainActor). Gated on `HermesCapabilities.hasACPImagePrompts`.
+- **CLI additions:** `hermes -z <prompt>` (non-interactive one-shot), `hermes update --check` (preflight), `hermes fallback` (manage fallback providers), `hermes curator` (status / run / pause / resume / pin / unpin / restore), `hermes kanban` (full task-board CLI; multi-profile collab was reverted upstream so Scarf ships a read-only Kanban view only). All capability-gated.
+- **Skills surface:** `hermes skills install <https-url>` direct-URL install (SkillsView "Install from URL…" toolbar button), reload via `hermes skills audit` (Skills "Reload" button — equivalent to the `/reload-skills` slash command for non-ACP contexts), enabled/disabled state read from `skills.disabled` in config.yaml (rendered as strikethrough + "OFF" pill), Curator pin badge from `~/.hermes/skills/.curator_state` (rendered as a pin glyph). The disable-toggle write path is deferred to v2.7 — Hermes only exposes `hermes skills config` as an interactive verb, and Scarf prefers reading accurately to risking a clobbered list.
+- **Two new gateway platforms:** Microsoft Teams (19th, plugin-shipped) + Tencent 元宝 / Yuanbao (18th, native). Surfaced in the Mac Platforms tab.
+- **Cron upgrades:** per-job `--workdir <abs-path>` (project-aware cwd that pulls AGENTS.md / CLAUDE.md / .cursorrules) is exposed in the editor sheet, gated on `HermesCapabilities.hasCronWorkdir` so pre-v0.12 hosts don't see the field (and a defensive override in `CronView` strips the value before calling `createJob`/`updateJob` even if it was hydrated from a pre-existing job). Pass an empty string on edit to clear an existing workdir, mirroring the `--script` shape. Hermes also added a `context_from` field for chaining cron outputs but only via YAML so far — Scarf reads it (HermesCronJob.contextFrom) but doesn't write it.
+- **Settings deltas:** `prompt_caching.cache_ttl` (5m/1h picker), `redaction.enabled` toggle (off-by-default in v0.12 — toggle restores it), `agent.runtime_metadata_footer` toggle, Piper added to TTS provider list, `vercel` added to terminal backend list.
+- **Bundled plugins:** Spotify, Google Meet, Langfuse observability, hermes-achievements (visible in Plugins tab).
+- **iOS catch-up (Phase H):** read-only Webhooks / Plugins / Profiles tabs (`Scarf iOS/Webhooks/WebhooksView.swift`, `Plugins/PluginsView.swift`, `Profiles/ProfilesView.swift`) parity-match the Mac surfaces but skip mutating CLI verbs. `Scarf iOS/Components/HermesVersionBanner.swift` nudges pre-v0.12 hosts to upgrade (renders only when the connected target is below v0.12).
+- **`hermes memory` providers:** honcho, openviking, mem0, hindsight, holographic, retaindb, byterover. `Settings → Memory` lists all providers in the picker; the existing "Run `hermes memory setup` in Terminal" hint stays — `hermes memory setup` is interactive (asks for tokens) so an in-app shellout would surface a frozen UI.
+- **Schema is unchanged from v0.11** — same state.db columns (`messages.reasoning_content`, `sessions.api_call_count` introduced in v0.11 remain). No migration needed.
+
+**v2026.4.23 (v0.11.0)** added (historical context, still consumed by Scarf when running against a pre-v0.12 host):
 
 - `/steer <prompt>` — non-interruptive mid-run guidance slash command. Surfaced in Scarf chat menus via `RichChatViewModel.nonInterruptiveCommands`; `ChatViewModel.sendViaACP` (Mac) and `ChatController.send` (iOS) skip the "Agent working…" status flip and show a transient toast instead.
 - New CLI subcommands: `hermes plugins` / `profile` / `webhook` / `insights` / `logs` / `memory reset` / `completion` / `dashboard`. Scarf v2.5 adopts **`hermes memory reset`** (toolbar button on MemoryView with destructive confirmation). The other CLIs are documented here for v2.6 — Scarf still reads `~/.hermes/plugins/`, `~/.hermes/profiles/` etc directly today; switching those paths to the canonical CLI is a forward-compatible change to make when bandwidth permits.

CONTRIBUTING.md

@@ -5,8 +5,10 @@ Thanks for your interest in contributing to Scarf.
 ## Getting Started
 
 1. Fork and clone the repo
-2. Open `scarf/scarf.xcodeproj` in Xcode 26.3+
-3. Build and run (requires macOS 26.2+ and Hermes installed at `~/.hermes/`)
+2. Open `scarf/scarf.xcodeproj` in Xcode 16.0+
+3. Build and run (Scarf runs on macOS 14.6 Sonoma or newer; Hermes must be installed at `~/.hermes/`)
+
+For an unsigned command-line Debug build without an Apple Developer account, run [`./scripts/local-build.sh`](scripts/local-build.sh). See [BUILDING.md](BUILDING.md) for prerequisites.
 
 ## Architecture
 

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="icon.png" width="128" height="128" alt="Scarf app icon">
+  <img src="icon-v2.5.png" width="128" height="128" alt="Scarf app icon">
 </p>
 
 <h1 align="center">Scarf</h1>
@@ -19,31 +19,71 @@
   <a href="https://www.buymeacoffee.com/awizemann"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me a Coffee" height="28"></a>
 </p>
 
-## What's New in 2.5
+## What's New in 2.7
 
-### ScarfGo — the iPhone companion ships in public TestFlight
+The biggest release since 2.6 — six weeks of work focused on **remote-context performance**, a **new project authoring flow**, **dashboard widgets**, **OAuth resilience**, and a top-to-bottom **performance instrumentation harness** that drove the bulk of the rest. 36 commits, no schema bump, no Hermes capability bump.
 
-Same Hermes server you've been running on your Mac — now reachable from your phone over SSH. Multi-server, project-scoped chat, session resume, memory editor, cron list, skills tree, settings (read), all native iOS. Pure-Swift SSH (Citadel under the hood — no `ssh` binary needed on iOS). Per-project chat writes the same Scarf-managed `AGENTS.md` block the Mac app does, so the agent boots with the same project context regardless of which client opened the session.
+### Remote chats and Activity in seconds, not 30s timeouts
+
+Resuming a chat or opening Activity on a slow remote (a 420ms-RTT droplet, an underprovisioned VPS, a tunnel through 4G) used to fetch the full message column set in one shot, which routinely tripped the 30s SSH timeout on chats with multi-page tool result blobs. v2.7 introduces a **skeleton-then-hydrate pattern** that bounds the wire payload by what the user actually needs to see RIGHT NOW, then fills in the heavy stuff in the background.
+
+- **Chat skeleton** — user + assistant rows only (skips `role='tool'`), `tool_calls` / `reasoning` hard-NULLed at SQL level. Wire payload bounded by conversational text. The chat appears in seconds. Background hydration pages tool calls in 5-id batches; tool-result CONTENT is opt-in (Settings → Display → "Load tool results in past chats", default off) with per-card lazy-fetch in the inspector pane.
+- **Activity skeleton** — metadata-only fetch (~3 KB for 50 rows). Placeholder rows render immediately; real per-call entries swap in as paged hydration completes.
+- **Single-id whale recovery** — when a 5-id batch trips the 30s timeout (one row carries an oversized `tool_calls` blob), an L1 single-id retry isolates the offender so the rest of the batch still hydrates.
+
+### SSH cancellation that actually cancels
+
+`Task.detached` doesn't inherit cancellation from the awaiting parent. Pre-fix, navigating away from a chat left the underlying ssh subprocess running for the full 30s, pinning a remote sqlite query and a ControlMaster session — the "third chat hangs" / "dashboard spins after rapid switching" symptom. v2.7 wires `withTaskCancellationHandler` through `SSHScriptRunner.run` and `RemoteSQLiteBackend.query`; cancellation now reaches the `Process` within ~100ms.
+
+### New Project from Scratch wizard + Keychain-backed cron secrets
+
+A third project entry point alongside Browse Catalog and Add Existing Project. Scaffolds a Scarf-standard skeleton, registers it, and hands off to a chat session that auto-activates the bundled `scarf-template-author` skill. The skill drives the rest conversationally — widgets, optional config schema, optional cron — and writes the final files itself.
+
+**Cron + Keychain.** Cron prompts that referenced `secret`-typed config fields used to get the literal `keychain://...` URI back, producing 401s. v2.7 mirrors resolved Keychain values into `~/.hermes/.env` under `$SCARF_<UPPER_SLUG>_<UPPER_FIELD>` env vars. Hermes already reloads `.env` per cron tick — credential rotation is automatic.
+
+### Project dashboards — file-reading widgets, sparklines, typed status
+
+Five new widget types and project-wide auto-refresh. **Backwards-compatible** — every existing `dashboard.json` renders byte-identically.
+
+- **`markdown_file`** / **`log_tail`** / **`cron_status`** / **`image`** / **`status_grid`** — file-reading widgets that auto-refresh when the underlying file changes. By convention, place files inside `<project>/.scarf/`.
+- **`stat` widget gains inline sparklines** via optional `sparkline: [Number]`. SVG-only render; dozens per dashboard cost nothing.
+- **Typed status badges** with lenient decode (`ok`/`up` → success, `down`/`error` → danger). Unknown strings render as plain text rather than crashing.
+- **Structured widget error card** replaces the legacy "Unknown: \<type\>" placeholder.
+
+### OAuth resilience + Credential Pools
+
+- **Daily OAuth keepalive cron** prevents Anthropic OAuth refresh tokens from expiring after weeks of inactivity.
+- **Remote re-auth** unblocked — OAuth flow drives a remote `hermes auth add` correctly with stdin forwarded.
+- **OAuth remove button** + auto-refresh of Credential Pools on `auth.json` change.
+- **`resolve_provider_client` errors** (auxiliary task references an unauthenticated provider) classified into a clear hint with a one-click jump to Settings → Aux Models.
+- **Model/provider mismatch banner** detects when `model.default` carries a `<provider>/...` prefix that disagrees with `model.provider`, with one-click fix in either direction.
+
+### ScarfMon — performance instrumentation harness
+
+The diagnostic surface that drove the bulk of the v2.7 perf work. Off by default; signpost-only mode (Instruments-friendly) is free; Full mode keeps a 4096-entry in-memory ring buffer you can copy as JSON for paste-into-issue diagnosis. Wiki: [Performance-Monitoring](https://github.com/awizemann/scarf/wiki/Performance-Monitoring).
+
+See the full [v2.7.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.7.0) for the complete list (36 commits, including: in-flight coalescing for `loadRecentSessions`, snapshot pipeline rewrite from `sqlite3 .backup` to direct SSH-streamed queries [#74](https://github.com/awizemann/scarf/issues/74), per-message TTS, window-position persistence, sidebar reorder, and many other fixes).
+
+**Previous releases:** see the [Release Notes Index](https://github.com/awizemann/scarf/wiki/Release-Notes-Index) on the wiki for v2.6, v2.5, v2.3, v2.2, v2.0, v1.6, and earlier.
+
+## ScarfGo — the iPhone companion
+
+Same Hermes server you've been running on your Mac — reachable from your phone over SSH. Multi-server, project-scoped chat, session resume, memory editor, cron list, skills tree, settings (read), all native iOS. Pure-Swift SSH (Citadel under the hood — no `ssh` binary needed on iOS). Per-project chat writes the same Scarf-managed `AGENTS.md` block the Mac app does, so the agent boots with the same project context regardless of which client opened the session.
 
 **[Join the public TestFlight](https://testflight.apple.com/join/qCrRpcTz)** — the link is live now but only accepts new beta testers once Apple's Beta Review approves the first build. If you hit a "not accepting testers" splash, bookmark it and try again in 24–48h.
 
+<p align="center">
+  <a href="assets/screenshots/scarfgo-servers.png"><img src="assets/screenshots/scarfgo-servers.png" alt="ScarfGo — Servers list" width="140"></a>
+  <a href="assets/screenshots/scarfgo-chat.png"><img src="assets/screenshots/scarfgo-chat.png" alt="ScarfGo — Chat with Hermes" width="140"></a>
+  <a href="assets/screenshots/scarfgo-project-dashboard.png"><img src="assets/screenshots/scarfgo-project-dashboard.png" alt="ScarfGo — Project dashboard" width="140"></a>
+  <a href="assets/screenshots/scarfgo-skills.png"><img src="assets/screenshots/scarfgo-skills.png" alt="ScarfGo — Skills browser" width="140"></a>
+  <a href="assets/screenshots/scarfgo-system.png"><img src="assets/screenshots/scarfgo-system.png" alt="ScarfGo — System tab" width="140"></a>
+</p>
+
+<p align="center"><sub><em>Tap any thumbnail to view full size. Servers list · Chat · Project dashboard (Site Status Checker template) · Skills browser · System tab.</em></sub></p>
+
 See the [ScarfGo wiki page](https://github.com/awizemann/scarf/wiki/ScarfGo) for the full feature tour, [ScarfGo Onboarding](https://github.com/awizemann/scarf/wiki/ScarfGo-Onboarding) for the SSH-key setup walkthrough, and [Platform Differences](https://github.com/awizemann/scarf/wiki/Platform-Differences) for what is and isn't shared between Mac and iOS.
 
-### Everything else in 2.5
-
-- **Portable project-scoped slash commands.** Author reusable prompt templates as Markdown files at `<project>/.scarf/slash-commands/<name>.md` with YAML frontmatter (name, description, argumentHint, optional model override). Invoke as `/<name> [args]` from chat — Scarf substitutes `{{argument}}` (with optional `default:` fallback) in the body and sends the expanded prompt to Hermes. Mac authoring tab + iOS read-only browser. Templates carry them via the new `slash-commands/` block in `.scarftemplate` bundles (schemaVersion 3). See [Slash Commands](https://github.com/awizemann/scarf/wiki/Slash-Commands) for the full schema.
-- **Hermes v2026.4.23 chat parity.** `/steer` non-interruptive guidance command, per-turn stopwatch on assistant bubbles, numbered keyboard shortcuts (1–9) on the permission sheet, git branch chip in the chat header. The new `messages.reasoning_content` and `sessions.api_call_count` columns surface as a richer reasoning disclosure + an "API" chip on session rows.
-- **Spotify + design-md skills.** Mac ships an in-app Spotify OAuth sheet (mirrors the v2.3 Nous Portal pattern); design-md gets a host-side `npx` prereq check on both platforms. SKILL.md frontmatter (`allowed_tools`, `related_skills`, `dependencies`) renders as chip rows. A "What's New" pill on the Skills tab tells you when remote skills changed since you last looked.
-- **Mac global Sessions: project filter + project badges** — parity with ScarfGo's Sessions tab. The list grows a filter Menu (All projects / Unattributed / each registered project) and each row carries a tinted folder chip with the project name when attributed.
-- **Human-readable cron schedules everywhere.** New `CronScheduleFormatter` in ScarfCore translates the common cron shapes into English phrases and falls back to the raw expression on anything custom. Mac and iOS render the same.
-- **Mac design-system overhaul.** Rust palette, typed token bundle (`ScarfColor`, `ScarfFont`, `ScarfSpace`, `ScarfRadius`), reusable components (`ScarfPageHeader`, `ScarfCard`, `ScarfBadge`, `ScarfTextField`, four button styles), redesigned 3-pane chat. iOS adopts the same tokens with a hybrid Dynamic Type policy so accessibility scaling on body text is preserved. See [Design System](https://github.com/awizemann/scarf/wiki/Design-System) for the full reference.
-- **Under the hood** — `SessionAttributionService`, `ProjectContextBlock`, `CronScheduleFormatter`, `GitBranchService`, `SkillPrereqService`, `SkillSnapshotService`, `ProjectSlashCommandService`, and the ACP error triplet (`acpError` / `acpErrorHint` / `acpErrorDetails`) consolidated into ScarfCore so Mac and iOS consume one source of truth. 179 tests across 13 suites, three consecutive green runs. Several `try?` swallows in iOS lifecycle code now surface real failures (Keychain unlock errors no longer drop people into onboarding; partial Forget operations report what failed).
-- **iOS push notifications skeleton** — `NotificationRouter` ships with foreground presentation + a lock-screen "Approve / Deny" action category gated by `apnsEnabled = false`. Lights up when Hermes ships a server-side push sender + an APNs cert.
-
-See the full [v2.5.0 release notes](https://github.com/awizemann/scarf/releases/tag/v2.5.0).
-
-**Previous releases:** see the [Release Notes Index](https://github.com/awizemann/scarf/wiki/Release-Notes-Index) on the wiki for v2.3, v2.2, v2.0, v1.6, and earlier.
-
 ## Connect ScarfGo to your Hermes server
 
 ScarfGo speaks SSH directly — no companion service, no developer-controlled server in between. Onboarding takes about a minute:
@@ -135,7 +175,7 @@ Custom, agent-generated dashboards for any project. Define stat boxes, charts, t
 - macOS 14.6+ (Sonoma) for Scarf
 - iOS 18.0+ for [ScarfGo](https://github.com/awizemann/scarf/wiki/ScarfGo) (the iPhone companion, public TestFlight from v2.5)
 - Xcode 16.0+ to build from source
-- [Hermes agent](https://github.com/hermes-ai/hermes-agent) v0.6.0+ installed at `~/.hermes/` on each target host (v0.11.0+ recommended for full v2.5 feature support — `/steer`, new state.db columns, design-md/spotify skills, SKILL.md frontmatter chips)
+- [Hermes agent](https://github.com/hermes-ai/hermes-agent) v0.6.0+ installed at `~/.hermes/` on each target host (v0.12.0+ recommended for full v2.6 feature support — autonomous Curator, multimodal image input, 5 new providers, Microsoft Teams + Yuanbao gateways, Kanban, Skills v0.12 surface, cron `--workdir`, prompt-cache TTL, Piper TTS, Vercel terminal)
 - For remote servers: SSH access (key-based), `sqlite3` on the remote (for atomic DB snapshots), and the `hermes` CLI resolvable from the remote user's `PATH` or at a path you specify per server. ScarfGo requires the same on every Hermes host it connects to.
 
 ### Compatibility
@@ -149,9 +189,10 @@ Scarf reads Hermes's SQLite database and parses CLI output from `hermes status`,
 | v0.8.0 (2026-04-08) | Verified |
 | v0.9.0 (2026-04-13) | Verified |
 | v0.10.0 (2026-04-16) | Verified (Tool Gateway introduced) |
-| v0.11.0 (2026-04-23) | **Verified — current target (recommended for full v2.5 feature support)** |
+| v0.11.0 (2026-04-23) | Verified |
+| v0.12.0 (2026-04-30) | **Verified — current target (recommended for full v2.6 feature support)** |
 
-Scarf 2.5 targets Hermes v0.11.0 for `/steer`, the new state.db columns (`messages.reasoning_content`, `sessions.api_call_count`), the new skills (design-md, spotify), the SKILL.md frontmatter chip surfaces, and the `hermes memory reset` toolbar action. Earlier Hermes versions remain supported for monitoring, sessions, file-based features, and ACP chat; v0.11-specific behavior degrades gracefully on older agents (`/steer` is harmless, new columns silently nil out).
+Scarf 2.6 targets Hermes v0.12.0 for the autonomous Curator, multimodal ACP image content blocks, the 5 new inference providers, Microsoft Teams + Yuanbao gateways, the read-only Kanban view, the Skills v0.12 surface (URL install / reload / disable badges / curator pin), cron `--workdir`, `auxiliary.curator`, `prompt_caching.cache_ttl`, the redaction toggle, the runtime metadata footer, Piper TTS, and the Vercel terminal backend. Every v0.12 surface is **capability-gated** — Scarf detects the host's Hermes version once per server connection (`hermes --version` → semver + `YYYY.M.D` parse) and hides v0.12-only UI on older hosts. v0.11.0 hosts keep the full v2.5 surface (`/steer`, `messages.reasoning_content`, `sessions.api_call_count`, design-md/spotify skills, SKILL.md frontmatter chips, `hermes memory reset`). Earlier Hermes versions remain supported for monitoring, sessions, file-based features, and ACP chat; new behavior degrades gracefully on older agents.
 
 If a Hermes update changes the database schema or CLI output format, Scarf may need to be updated. Check the [Health](#features) view for compatibility warnings.
 
@@ -169,6 +210,20 @@ Download the latest build from [Releases](https://github.com/awizemann/scarf/rel
 
 Scarf checks for updates automatically on launch via [Sparkle](https://sparkle-project.org) and daily thereafter. You can disable automatic checks or trigger a manual check from **Settings → General → Updates** or the menu bar icon.
 
+#### "Scarf.app is damaged" on first launch
+
+If Gatekeeper rejects the app on first launch (occasionally happens on macOS 14+ for zip-distributed apps depending on extraction tool + quarantine state), the bundle itself is fine — every release is verified to pass `codesign --verify --strict --deep` and `spctl --assess --type execute` before it ships. The fix is to **only remove the quarantine attribute**, never strip all xattrs or re-sign:
+
+```bash
+# Recommended — non-destructive
+xattr -d com.apple.quarantine /Applications/Scarf.app
+
+# Or extract with ditto instead of double-clicking the zip:
+ditto -xk ~/Downloads/Scarf-vX.X.X-Universal.zip ~/Downloads/
+```
+
+**Do not run `xattr -rc /Applications/Scarf.app`** — it strips codesign-related extended attributes and can break the bundle's seal. **Do not run `codesign --force --deep --sign - /Applications/Scarf.app`** — `--deep` ad-hoc re-signing is incompatible with Sparkle.framework's nested XPC services and `Updater.app` sub-bundle, and will corrupt the framework signature even if the outer app appears intact afterward. If a clean re-download + `xattr -d com.apple.quarantine` doesn't resolve the issue, please open an issue with `codesign --verify --verbose=4 --strict /Applications/Scarf.app` output captured **before** any mitigation attempts.
+
 ### Build from Source
 
 ```bash
@@ -183,6 +238,8 @@ Or from the command line:
 xcodebuild -project scarf/scarf.xcodeproj -scheme scarf -configuration Release -arch arm64 -arch x86_64 ONLY_ACTIVE_ARCH=NO build
 ```
 
+For an unsigned local Debug build without an Apple Developer account (handy for contributors), use [`./scripts/local-build.sh`](scripts/local-build.sh) — see [BUILDING.md](BUILDING.md) for prerequisites.
+
 ## Architecture
 
 Scarf follows the **MVVM-Feature** pattern with zero external dependencies beyond SwiftTerm:

releases/v2.5.1/RELEASE_NOTES.md

@@ -0,0 +1,47 @@
+## What's in 2.5.1
+
+A patch release that bundles every issue reported against 2.5.0 plus a couple of TestFlight-driven iOS fixes. No data migrations needed — drop-in replacement for 2.5.0 on Mac, drop-in TestFlight build on iOS.
+
+### Bug fixes
+
+#### Mac
+
+- **[#49](https://github.com/awizemann/scarf/issues/49) — macOS 26 "Scarf.app is damaged" recovery path.** Verified the shipped 2.5.0 bundles pass `codesign --verify --strict --deep` and `spctl --assess` on macOS 26.4.1; the user-facing "damaged" symptom in some reports turned out to be self-inflicted by destructive recovery commands. Added a [Troubleshooting section](https://github.com/awizemann/scarf/blob/main/README.md) to the README documenting the **non-destructive** fix path (`xattr -d com.apple.quarantine` only — never `xattr -rc` or `codesign --force --deep --sign -`). Hardened the release pipeline: every variant zip now goes through `codesign --verify --strict --deep` + `spctl --assess` after the final `ditto`, so any future regression in the shipped artifact fails the release before a user sees it.
+- **[#46](https://github.com/awizemann/scarf/issues/46) — chat performance: long sessions no longer bog down or crash.** Long chats were doing O(n) work per streamed token because every chunk rebuilt the full message-group array AND every `MessageGroupView` / `RichMessageBubble` re-evaluated its body. Three changes cap per-chunk work at O(1) for settled groups:
+  - `MessageGroupView` and `RichMessageBubble` are now `Equatable` with `.equatable()` short-circuit. Settled bubbles skip body re-eval entirely while the streaming bubble still redraws.
+  - `RichChatViewModel.upsertStreamingMessage` patches the trailing group in place via a new `patchTrailingGroupForStreaming(...)` instead of running `buildMessageGroups()` per chunk.
+  - `MessageGroup.toolKindCounts` moved to the model (was an `O(m × k)` computed property re-running on every render). `ToolCallCard.formatJSON` cached via `.task(id: callId)`. `ToolResultContent.lines` cached on content change.
+  
+  CPU during streaming on a 500-message session drops from sustained 100%+ to ~30–50% on representative hardware.
+- **[#50](https://github.com/awizemann/scarf/issues/50) — Hermes v0.11 profile awareness.** Hermes v0.11 stores each profile in its own `~/.hermes/profiles/<name>/` directory with its own `state.db`, `sessions/`, `config.yaml`, `memories/`, etc. Pre-fix Scarf hardcoded `~/.hermes` and ignored `~/.hermes/active_profile`, so `hermes profile use coder` followed by a Scarf relaunch silently read the wrong DB — sessions, memory, cron all coming from the default profile. New `HermesProfileResolver` reads `active_profile` and resolves the effective home path; `HermesPathSet.defaultLocalHome` consults it, so every derived path automatically follows the active profile. SessionInfoBar gains a profile chip when not on the default so users can see which profile Scarf is reading from.
+- **[#53](https://github.com/awizemann/scarf/issues/53) — granular reasons on the "Connected — can't read Hermes state" pill.** Tier 2 of the connection probe now distinguishes config.yaml-missing / `~/.hermes`-missing / permission-denied / Hermes-profile-active and surfaces a pill popover with the specific reason + an actionable hint + Run Diagnostics / Retry buttons. Profile case includes a copy-paste `hermes profile use default` affordance.
+- **[#44](https://github.com/awizemann/scarf/issues/44) — pill and Run Diagnostics no longer disagree.** A long-standing latent bug surfaced by Tailscale Mac-to-Mac users: the pill probe and the diagnostics view ran the same `[ -r ~/.hermes/config.yaml ]` check but went through different transport paths — `transport.runProcess` for the pill (which `remotePathArg`-quotes every argument and mangled the multi-line script) vs raw `/usr/bin/ssh ... -- /bin/sh -s` for diagnostics. Result: 14/14 diagnostics passing while the pill stayed stuck on "can't read Hermes state". Extracted the diagnostics workaround into a shared `SSHScriptRunner` in ScarfCore; both probes now use it. Side benefit: the granular #53 probe script (more `$VAR`s and nested quotes) is robust against the same class of bug going forward.
+- **[#54](https://github.com/awizemann/scarf/issues/54) — Add Project on remote server contexts.** The Add Project sheet always rendered a Browse button backed by `NSOpenPanel` (a Mac-local file dialog). On a remote SSH context the user picked a Mac path, the path landed in the projects registry as the project's "remote" working directory, and tool calls failed at runtime because that path doesn't exist on the Linux server. Tier-1 fix: sheet is now context-aware — local context keeps Browse unchanged; remote context hides Browse, shows a `"Path on <server> — must already exist on the server"` hint, and adds a Verify button that runs `transport.stat(path)` and renders inline ✓ / ⚠. A full SFTP-backed remote picker remains a deferred feature.
+
+#### ScarfGo (iOS)
+
+- **[#46](https://github.com/awizemann/scarf/issues/46) — same O(n)-per-token fix on iOS.** ScarfGo uses a different chat path (`LazyVStack` directly over `controller.vm.messages`, not message groups) so the Mac fix's `Equatable` conformances didn't propagate. Added an iOS-equivalent `MessageBubble: Equatable` with `.equatable()` at the `ForEach` call site — settled bubbles short-circuit body re-eval while the streaming bubble still redraws.
+- **[#51](https://github.com/awizemann/scarf/issues/51) — keyboard now dismissable.** Pre-fix the chat composer's `TextField` had no `@FocusState`, no `.scrollDismissesKeyboard`, and no keyboard accessory toolbar; with `axis: .vertical` + `.submitLabel(.send)` the Return key inserts a newline rather than submitting. Once the keyboard rose it stuck — hiding the system tab bar (which iOS auto-hides while a keyboard is up) and trapping users in the Chat tab. Added two redundant dismissal paths: `.scrollDismissesKeyboard(.interactively)` on the message list (drag messages downward to collapse) AND a `keyboard.chevron.compact.down` button in the keyboard accessory toolbar. Tab bar reappears on dismiss → users can switch tabs again.
+- **[#55](https://github.com/awizemann/scarf/issues/55) — first-run Cancel button no longer looks broken.** TestFlight feedback: the "Connect to Hermes" onboarding's Cancel button appeared dead. Root cause: `RootModel.cancelOnboarding` had a defensive `servers.isEmpty` branch that re-presented a fresh onboarding view when there was nothing to fall back to, making the button fire correctly but visually do nothing. The fix is at the right layer: `OnboardingRootView` now takes a `canCancel: Bool` parameter and hides the Cancel button entirely when there's no server list to return to.
+
+### New features (Mac)
+
+- **Chat density preferences ([#47](https://github.com/awizemann/scarf/issues/47) + [#48](https://github.com/awizemann/scarf/issues/48)).** New section in **Settings → Display → Chat density**. All defaults match today's UI exactly so existing users see no change until they opt in.
+  - **Tool calls**: Full card (default) / Compact chip / Hidden. Compact renders each call as a single-line tappable chip — kind icon + function name + status dot — that opens the right-pane inspector with the same details the inline expand shows. Hidden skips per-call rows; the always-visible group summary pill ("Used 5 tools (3 read, 2 edit)") becomes tappable so the inspector pane is still one click away.
+  - **Reasoning**: Disclosure box (default) / Inline (italic) / Hidden. Inline collapses the yellow disclosure to italic faded caption text inline above the reply with a small brain prefix — same data, far less vertical space. Hidden skips reasoning entirely.
+  - **Chat font size**: 85% to 130% slider (5% step). Applied at the chat root via `.environment(\.dynamicTypeSize, ...)` so message list, input bar, session info bar, and inspector pane all scale together.
+  
+  All density toggles preserve existing telemetry surfaces — per-turn stopwatch, per-message tokens, finish reason, and timestamp stay in the bubble metadata footer; SessionInfoBar input/output/reasoning tokens, USD cost, model, project, git branch, and started-at relative time are unaffected by every density setting.
+
+### New features (ScarfGo iOS)
+
+- **iCloud Keychain sync for SSH keys ([#52](https://github.com/awizemann/scarf/issues/52)).** Reddit-reported friction: every iOS device needed its own SSH key. Pairing iPhone + iPad meant onboarding twice and editing `authorized_keys` per device. New opt-in toggle in **System → Security**: when enabled, the SSH key bundle is stored with `kSecAttrAccessibleAfterFirstUnlock` + `kSecAttrSynchronizable=true` so iCloud Keychain picks it up on every signed-in device. Default off (preserves today's behavior on update). Toggling triggers a one-shot migration that re-saves all stored keys with the target attributes; failure reverts the toggle and surfaces the error inline. With Advanced Data Protection enabled, the encryption keys never leave your devices.
+
+### Documentation + tooling
+
+- **Privacy / sandboxing claim corrected.** Previous CLAUDE.md / README implied Scarf ran sandboxed; it doesn't (and can't, given that it spawns the user-installed `hermes` binary and reads `~/.hermes/` directly). Documentation now reflects the actual posture.
+- **Release pipeline hardened.** `scripts/release.sh` now extracts each variant's distribution zip and runs `codesign --verify --strict --deep` + `spctl --assess --type execute` on the extracted bundle as a final gate. Catches any future regression in the shipped artifact pre-ship rather than via user reports.
+
+### Notes for users running 2.5.0
+
+No data migrations needed. Server configs, Keychain entries, project registries, session attribution sidecar — all forward-compatible. The iCloud Keychain sync toggle defaults to off, so existing iOS users keep their device-local keys until they opt in.

releases/v2.5.2/RELEASE_NOTES.md

@@ -0,0 +1,55 @@
+## What's in 2.5.2
+
+A patch with one substantial new feature (**iOS chat resilience** — reconnect, cached snapshot fallback, history paging) plus a stack of fixes for issues reported against 2.5.1 and earlier. Drop-in replacement for 2.5.1 on Mac; drop-in TestFlight build on iOS. No data migrations.
+
+### iOS chat resilience
+
+ScarfGo now survives phone-sleep, network handoffs, and SSH socket drops without losing the agent's work. Hermes was already persisting messages to `state.db` in real-time; iOS just had no resync path.
+
+- **5-attempt exponential reconnect** (1s → 2s → 4s → 8s → 16s) via `session/resume` with `session/load` fallback. Reconciles with `state.db` on success and surfaces a *"Resynced N new messages"* toast when the agent kept working through the disconnect.
+- **`NetworkReachabilityService`** (NWPathMonitor singleton): suspends reconnect attempts while offline and kicks a fresh cycle on link-up. Two new banner states above the message list — `.reconnecting` and `.offline` — render as slim ScarfDesign-tinted strips so the user always knows what the chat is doing.
+- **Scene-phase awareness**: returning to foreground triggers a channel-health check; if dead, the reconnect cycle starts immediately rather than waiting for the next interaction.
+- **Draft persistence**: per-server, per-session draft survives force-quit (UserDefaults-backed, 7-day janitor at app launch).
+
+### Cached snapshot fallback (Mac + iOS)
+
+`ServerTransport.cachedSnapshotPath` lets `HermesDataService` fall back to the previously-pulled `state.db` snapshot when a fresh pull fails. `isUsingStaleSnapshot` + `lastSnapshotMtime` surface to views so they render *"Last updated X ago."* Chat-history reload still passes `forceFresh: true` to refuse stale data; everything else (Dashboard, Sessions list, Activity) gets read-while-disconnected for free.
+
+### Bounded message-history paging
+
+`HermesDataService.fetchMessages(sessionId:limit:before:)` paginates by id desc with centralized `HistoryPageSize` constants. `RichChatViewModel.loadEarlier()` walks back through long sessions via `oldestLoadedMessageID` + `hasMoreHistory`. Legacy unbounded overload deprecated.
+
+### Bug fixes
+
+#### Mac
+
+- **[#46](https://github.com/awizemann/scarf/issues/46) — chat O(n)-per-token bog-down (already shipped in 2.5.1 for the trailing-group patch; this release retains the fix and pairs with the new history paging so chats with thousands of messages stay smooth).**
+- **[#19](https://github.com/awizemann/scarf/issues/19) layer-3 — sqlite3 false-negative in diagnostics.** Already in v2.5.1; kept here.
+- **[#44](https://github.com/awizemann/scarf/issues/44) — pill / diagnostics agreement** via shared `SSHScriptRunner`. From v2.5.1; the tier-2 probe now also checks `state.db` (not just `config.yaml`) so a healthy fresh install reports green.
+- **[#59](https://github.com/awizemann/scarf/issues/59) — Settings → Model and Credential Pools no longer freeze.** Both views called `ModelCatalogService.loadProviders()` synchronously from `.onAppear` on the MainActor; on a remote SSH context that's a multi-megabyte SSH file read on the main thread, freezing the UI for 1–2 minutes. New `loadProvidersAsync()` / `loadModelsAsync(for:)` wrappers dispatch off the main thread; both views now use `.task` + `await` with a `ProgressView("Loading providers…")` overlay. Per-provider switching in the picker is also async now, so clicking a different provider doesn't re-freeze the UI.
+- **Diagnostics tri-state.** Hermes v0.11+ doesn't materialize `config.yaml` until the user changes a setting from defaults — so the diagnostics view was reporting *"12/14 passing"* on healthy fresh installs. The probe now distinguishes `.pass` / `.fail` / `.skipped`; a missing `config.yaml` emits SKIP and is excluded from the summary's denominator. Reads as *"12/12 passing (2 optional skipped)"* instead of the misleading 12/14.
+- **Credentials: OAuth providers visible.** `hasAnyAICredential()` only probed `credential_pool.<provider>` in `auth.json`; OAuth-authed providers land under `providers.<name>.access_token` (Nous, Spotify, GH Copilot ACP, Qwen, Gemini all use that path). The chat banner kept showing *"No AI provider credentials"* even after a successful Nous sign-in. Now both shapes count. Credential Pools view gains a parallel "OAuth providers" section listing OAuth-authed providers with token tail, expiry badge, and portal URL.
+- **Project-shadowed Hermes detection.** New `ProjectHermesShadowDetector` (ScarfCore) probes each registered project at chat-start; if a `.hermes/` dir or `hermes.yaml` is found inside the project, the user gets a banner explaining that project-local Hermes config will shadow the server-level one (a quiet failure mode for users who didn't realize Hermes prefers project-local config).
+- **[#58](https://github.com/awizemann/scarf/issues/58) — Mac chat side panes are hideable.** Two toolbar buttons next to the View picker (`sidebar.left` / `sidebar.right`) toggle the sessions list and tool inspector with a slide animation; both default visible (today's behavior). Clicking a tool card auto-shows the inspector if hidden so the click never silently dies. Settings → Display → Chat density gains parity Toggle rows.
+
+#### ScarfGo (iOS)
+
+- **[#56](https://github.com/awizemann/scarf/issues/56) — *"Citadel.SSHClient.CommandFailed error 1"* on dashboard.** `asyncSnapshotSQLite` was missed during the v2.5.0 Citadel hardening — used raw `executeCommand` (which discards stderr on non-zero exit) and didn't prepend the Citadel-friendly `PATH=$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH`. Now uses `executeCommandStream` and the same PATH prefix. `HermesDataService.humanize` already translates `sqlite3: command not found` / `permission denied` / `no such file` into actionable user copy — the bug was that the snapshot path never fed it real stderr.
+- **[#57](https://github.com/awizemann/scarf/issues/57) — keyboard-dismiss chevron over send button.** The keyboard accessory dismiss button added in v2.5.1 (#51) was placed at the trailing edge of the keyboard toolbar, directly above the trailing-edge send button. Moved to the leading edge — matches the iOS convention (Notes, Mail, Reminders).
+
+### New features (Mac)
+
+- **Chat-start model preflight ([commit](https://github.com/awizemann/scarf/commit/2aab9da)).** Catches a missing `model.default` / `model.provider` in `config.yaml` *before* the ACP session starts. Pre-fix the user typed a prompt, hit send, and got an opaque *"Model parameter is required"* HTTP 400 from the upstream provider. Now `ChatModelPreflightSheet` wraps the existing model picker so the same selection / validation / Nous-catalog branch is single-sourced; the chat the user originally opened lands without re-clicking the project row.
+- **Nous Portal live model catalog.** `NousModelCatalogService` fetches `GET /v1/models` from `inference-api.nousresearch.com` using the bearer token in `auth.json`. Cached at `~/.hermes/scarf/nous_models_cache.json` with a 24h TTL. The picker's nous-overlay detail view switches from a free-form TextField to a real model list, with a *"Custom…"* escape hatch for IDs not yet in the API response.
+- **Remote-aware admin sheets.** Three sheets gained the same context-aware Verify pattern that Add Project got in v2.5.1 (#54):
+  - **Profiles → Import / Export.** Buttons that drive `hermes profile import <zip>` / `hermes profile export <name> <zip>` over SSH. Local context picks via `NSOpenPanel`; remote context shows a path-input + Verify button.
+  - **Settings → Advanced → Restore.** Pick a local backup zip OR enter+verify a remote path.
+  - **Templates → Install destination.** The parent-directory step in the install sheet branches on context — local Browse, or remote text-input + Verify.
+
+### Translations
+
+`Localizable.xcstrings` adds strings for all the new copy across the seven supported locales (English, Simplified Chinese, German, French, Spanish, Japanese, Brazilian Portuguese).
+
+### Notes for users running 2.5.1
+
+No data migrations needed. `~/.hermes/scarf/nous_models_cache.json` is created lazily on first use of the Nous picker; everything else is forward-compatible with existing config / Keychain / project registries.

releases/v2.6.0/RELEASE_NOTES.md

@@ -0,0 +1,134 @@
+## What's in 2.6.0
+
+A major release tracking **Hermes v2026.4.30 (v0.12.0)** — the largest single Hermes update Scarf has had to follow since v0.10's Tool Gateway. Headline additions: the autonomous **Curator**, **multimodal image input** in chat, **5 new inference providers**, **Microsoft Teams + Yuanbao** gateway platforms, a **read-only Kanban** view, and ScarfGo gains read-only Webhooks/Plugins/Profiles plus a Hermes-version banner.
+
+Pre-v0.12 Hermes hosts are fully supported. Every new surface is gated on a runtime capability detector (`hermes --version` → semver), so users on older Hermes installs see the v2.5 surface unchanged. UI doesn't appear until the underlying CLI subcommand exists.
+
+### Curator (Mac + iOS)
+
+Hermes v0.12's autonomous skill curator prunes / consolidates / archives agent-created skills on a 7-day schedule. Scarf adds a dedicated **Curator** sidebar item under Interact (Mac) and a Curator nav row under the System tab (iOS).
+
+- **Status panel** — enabled/paused/disabled badge, last-run timestamp, last summary, run count, scheduling cadence (interval / stale-after / archive-after).
+- **Run Now** button triggers `hermes curator run`; pause/resume from the kebab menu.
+- **Three leaderboards** — least-recently-active, most-active, least-active. Each row carries activity / use / view / patch counters and an inline pin toggle.
+- **Pin / unpin** — pinned skills are protected from auto-archive and rewrites. State pulled from `~/.hermes/skills/.curator_state` and surfaced as a pin glyph everywhere skills appear (Curator screen, Skills sidebar/list, SkillDetailView).
+- **Restore archived** sheet calls `hermes curator restore <name>` to bring a previously-archived skill back.
+- **Last report Markdown** — when present, the previous run's REPORT.md renders inline in mono.
+
+Capability-gated; sidebar item disappears on pre-v0.12 hosts.
+
+### Multimodal image input in chat (Mac + iOS)
+
+Hermes v0.12 advertises `prompt_capabilities.image = true` on ACP and accepts image content blocks in `session/prompt`. Scarf wires the producer side on both targets:
+
+- **Mac**: paperclip toolbar button on the chat composer opens NSOpenPanel multi-pick. Drag-and-drop and paste also work — drop an image (or a Finder file URL) onto the composer and it attaches. Capability-gated; the entire attachment surface is hidden on pre-v0.12 hosts.
+- **iOS**: paperclip button opens PhotosPicker (multi-select up to 5 photos). Same byte-for-byte capability gate.
+- **ImageEncoder** downsamples to 1568px long-edge (Anthropic's recommended ceiling) at JPEG q=0.85, so a 12 MP screenshot lands under ~300 KB on the wire. Detached only — never blocks MainActor.
+- **Image-only sends are valid** — once at least one attachment is queued, the send button enables even with empty text. Vision models accept "describe this" with no caption.
+- **Per-attachment chips** above the input field with thumbnail + filename tooltip + X to remove. 5-image-per-message cap; total payload stays under ~2 MB so cellular sends don't time out.
+
+Hermes routes the resulting prompt to a vision-capable model automatically — no extra Scarf-side work to pick the right aux model.
+
+### 5 new inference providers (Mac + iOS)
+
+Five overlay-only providers added to `ModelCatalogService.overlayOnlyProviders`. The model picker reaches all of them; provider IDs match `HERMES_OVERLAYS` in `hermes_cli/providers.py` exactly so a typo here doesn't strand users with an unreachable provider.
+
+- **GMI Cloud** (api_key) — `https://api.gmi-serving.com/v1`
+- **Azure AI Foundry** (api_key) — base URL resolved from `AZURE_FOUNDRY_BASE_URL` per tenant
+- **LM Studio** (api_key, first-class) — promoted from custom-endpoint alias to a real provider; defaults to `http://127.0.0.1:1234/v1`
+- **MiniMax (OAuth)** (oauth_external) — `https://api.minimax.io/anthropic`
+- **Tencent TokenHub** (api_key) — base URL resolved from `TOKENHUB_BASE_URL`
+
+### `auxiliary.curator` aux task (Mac)
+
+Hermes removed `auxiliary.flush_memories` entirely in v0.12 (the underlying memory pipeline was rewritten) and added `auxiliary.curator` so the curator's review fork can run on a separate model from the main agent. Settings → Auxiliary now surfaces a Curator row when the active host is v0.12+ (gated on `HermesCapabilities.hasCuratorAux`); the obsolete Flush Memories panel is gone.
+
+The Tool Gateway health view in HealthView lost the flushMemories-routes-through-Nous row and gained a curator row, matching the new aux task list.
+
+### Skills v0.12 surface (Mac + iOS)
+
+Three new capabilities Scarf can now reach:
+
+- **Direct-URL install** — `hermes skills install <https-url>` lets users pull a one-off skill without going through a registry. Mac SkillsView gains an "Install from URL…" toolbar button (capability-gated) opening a sheet with the URL field plus optional `--category` / `--name` overrides.
+- **Reload** — `hermes skills audit` rescans the skills directory and refreshes the agent's view without a session restart. Wired to a "Reload" toolbar button next to the install button on Mac.
+- **Enabled / disabled state** — `skills.disabled` in config.yaml is read at scan time. Disabled skills render strikethrough + an "OFF" pill on Mac and iOS rows; iOS detail view explains the state in plain text.
+- **Curator pin badge** — pinned-skill names from `~/.hermes/skills/.curator_state` surface as a pin glyph on each row across Mac sidebar and iOS list, plus an explanatory chip on iOS detail view.
+
+The disable-toggle write path is deferred to v2.7 — Hermes only exposes `hermes skills config` as an interactive verb today, and we'd rather read accurately than risk clobbering the user's list with a half-tested write.
+
+### Cron — `--workdir` flag (Mac)
+
+Hermes v0.12 cron jobs accept `--workdir <absolute-path>` to inject AGENTS.md / CLAUDE.md / .cursorrules from that directory and pin cwd for terminal/file/code_exec tools. Scarf's CronJobEditor now has a Workdir field; both create and edit paths forward the flag. Existing v0.11 jobs keep the no-cwd behaviour by leaving the field blank.
+
+The `context_from` chaining field is read-only from Scarf this round (Hermes hasn't exposed a `--context-from` CLI flag yet, only YAML).
+
+### Microsoft Teams + Yuanbao (Mac)
+
+Two new gateway platforms. Microsoft Teams (the 19th platform) ships as a plugin; Yuanbao 元宝 (the 18th) is a native gateway adapter. Both surface in the Platforms tab with read-only setup panels — the OAuth dance for Yuanbao and the plugin install for Teams happen outside Scarf.
+
+### Read-only Kanban (Mac)
+
+Hermes v0.12 ships a SQLite-backed multi-tenant task board with a full CLI (`hermes kanban create / list / claim / dispatch / …`). The multi-profile *collaboration* layer was reverted upstream while the design is reworked, so v2.6 ships a **read-only** Kanban view: paginated table of `hermes kanban list --json` filtered by status, with status badges, meta chips (id / assignee / workspace / skills), and per-row metadata. 5-second polling while the view is foregrounded; suspended on disappear.
+
+Create / claim / dispatch UI is deferred until upstream stabilizes — building the editor now would risk rework on a quarter-out timeline.
+
+### Settings deltas (Mac)
+
+A new **Caching & Redaction** section under Settings → Advanced with three v0.12 knobs (gated on capability):
+
+- **Prompt cache TTL** picker — 5m default / 1h opt-in. Reduces cache writes on long agent loops with stable system prompts.
+- **Redact secrets in patches** toggle — Hermes flipped this off by default in v0.12 because the substitution corrupted patches; security-sensitive users can flip it back on here.
+- **Runtime metadata footer** toggle — opt-in compact footer on each final reply (provider/model/cost/turn count).
+
+TTS provider list gains **piper** (native local TTS engine new in v0.12). Terminal backend list gains **vercel** (Vercel Sandbox backend for execute_code/terminal). Both ride along unconditionally — Hermes silently falls back when an older host doesn't recognize the value.
+
+### iOS catch-up — Webhooks / Plugins / Profiles (read-only)
+
+Three new System-tab nav rows in ScarfGo, all read-only:
+
+- **Webhooks** — list of `hermes webhook list` output with description / deliver / events / route per row. "Platform not enabled" detection so a freshly-installed Hermes shows setup guidance instead of error noise.
+- **Plugins** — filesystem-first scan over `~/.hermes/plugins/` with manifest reads (plugin.json or plugin.yaml). Enabled/disabled badge, version, source, path.
+- **Profiles** — `hermes profile list` with active-profile highlighting from `~/.hermes/active_profile`. Tolerant of both Rich box-drawn and plain-text outputs.
+
+None of the three are capability-gated — the underlying list verbs work on both v0.11 and v0.12. Create / edit / delete remain Mac-only since they touch enough state we keep them off the phone.
+
+### Hermes-version banner (iOS)
+
+Yellow banner at the top of the Dashboard tab when the active server is pre-v0.12. Lists the v0.12 capabilities the user is missing out on (curator, multimodal image input, new providers); one-tap session-dismiss; reappears on next app open. Hidden entirely on v0.12+ hosts.
+
+### Internal — version-aware capability detection
+
+The foundation of every gated surface above:
+
+- `HermesCapabilities` value type parses `Hermes Agent v0.12.0 (2026.4.30)` from `hermes --version` output. Exposes booleans for each release-gated UI surface (`hasCurator`, `hasACPImagePrompts`, `hasKanban`, `hasOneShot`, `hasSkillURLInstall`, `hasFallbackCommand`, `hasUpdateCheck`, `hasPiperTTS`, `hasVercelTerminal`, `hasCuratorAux`, `hasTeamsPlatform`, `hasYuanbaoPlatform`, `hasCronWorkdir`, `hasPromptCacheTTL`, `hasRedactionToggle`, `hasFlushMemoriesAux`).
+- `HermesCapabilitiesStore` (`@Observable @MainActor`) caches per-server capabilities. Injected on `ContextBoundRoot` (Mac) and `ScarfGoTabRoot` (iOS) via `.environment(_:)` and `.hermesCapabilities(_:)`.
+- 12 parser tests + 6 curator-output parser tests lock the v0.12 / v0.11 / fallback flag matrices.
+
+### Bug fixes
+
+#### Chat composer + transcript (post-merge round)
+
+- **Typing lag in the chat composer (#67)** — `RichChatInputBar.updateMenuState()` ran on every keystroke and unconditionally wrote both `showMenu` and `selectedIndex`, tripping SwiftUI's "action tried to update multiple times per frame" warning and stalling input. Composer now coalesces writes to deltas, short-circuits when not in slash mode (the common case), and watches `commands.count` instead of re-allocating `commands.map(\.id)` per keystroke.
+- **Chat font-size slider had no visible effect (#68)** — `RichChatView` only set `\.dynamicTypeSize`, but `ScarfFont` tokens are fixed-point (`Font.system(size: 14, …)`) so dynamic type didn't reach bubble text, reasoning, tool chips, code blocks, or markdown headings. New `\.chatFontScale` env value plumbed through `RichMessageBubble`, `MarkdownContentView`, and `CodeBlockView`; `ChatFontScale.{body, caption, captionStrong, caption2, mono, monoSmall, codeBlock, codeInline}(_:)` helpers mirror the ScarfFont base sizes so 100% is byte-for-byte identical to today's UI.
+- **Placeholder ghosting on first keystroke (#65)** — `TextEditor`'s NSTextView surfaces a typed glyph one frame before the SwiftUI binding propagates, so the bare `if text.isEmpty` overlay rendered the translucent placeholder text on top of the just-typed character. Pinned an opaque background behind the placeholder rect and switched the conditional to `.opacity(...)` so the view tree stays stable per keystroke.
+- **Draft text leaked between conversations (#62)** — composer `@State` survived session switches because the surrounding view tree was structurally identical. Bound `RichChatInputBar`'s identity to `richChat.sessionId` so SwiftUI rebuilds the view (and its `@State`) on session change. Stable fallback string for the "no session selected" window — `UUID()` would have minted a new id per body re-eval and trashed the composer mid-typing.
+- **Sent message rendered blank after navigating away (#63)** — when a user sent a prompt and immediately resumed a different session before Hermes flushed the row to state.db, `resumeSession`'s `reset()` cleared `messages` and `loadSessionHistory` then read an as-yet-empty DB. New per-session pending-user-messages cache survives `reset()` and re-injects still-pending entries on load; entries clear themselves as soon as a matching DB row catches up.
+- **No completion notification (#64)** — sending a long prompt and switching to other work required polling the chat to know when the response landed. New `ChatNotificationService` fires a local `UNUserNotificationCenter` banner on prompt completion when Scarf isn't the foreground app. Settings → Display → Feedback → "Notify when Hermes finishes" toggle, default on.
+- **Per-message TTS playback (#66)** — small speaker glyph in each settled assistant bubble's metadata footer; uses `AVSpeechSynthesizer` with the user's macOS Spoken Content default voice, picks up offline. Markdown control characters stripped before speech. The deeper Settings → Voice provider integration (Edge / ElevenLabs / OpenAI / NeuTTS / Piper) is queued as a v2.7 follow-up.
+- **ACP control-message timeout under gateway concurrency (#61)** — bumped 30s → 60s. State.db lock contention on a healthy host clears in seconds, but the previous 30s watchdog tripped under realistic gateway+ACP concurrency (Discord sync / skill registration / cron scheduling holding write locks during ACP `initialize` / `session/new` / `session/load`). 60s gives lock resolution headroom while still surfacing genuinely broken transports.
+
+#### Pre-merge
+
+- **Test target compile** — `M5FeatureVMTests.ScriptedTransport` had drifted off the `ServerTransport` protocol after `cachedSnapshotPath` landed in v2.5.2; added the missing stub. `M0dViewModelsTests` got the `ConnectionStatusViewModel.Status.degraded` argument-name update. `CredentialPoolsGatingTests` got the missing `import ScarfCore`. The full `swift test` suite now runs (and passes — 215 tests across 17 suites).
+- **iOS package compile** — `RemoteBackupService.zipDirectory` and `RemoteRestoreService.unzipArchive` used `Foundation.Process` unconditionally, breaking the iOS build entirely (Process is unavailable on the iOS SDK). Wrapped in `#if !os(iOS)` with iOS stubs that throw — backup/restore is Mac-only by design.
+
+### Hermes version
+
+Targets Hermes **v2026.4.30 (v0.12.0)**. v2026.4.23 (v0.11.0) hosts continue to work — every v0.12 surface is gated on capability detection, so Scarf v2.6 against v0.11 looks identical to Scarf v2.5.2 against v0.11. Update Hermes (`hermes update`) to unlock the new surfaces.
+
+### Compatibility
+
+- macOS 14+ (unchanged)
+- iOS 17+ (unchanged)
+- Hermes v0.11+ for the v2.5 surface; v0.12+ for the new features above.
+- No data migrations.

releases/v2.6.5/RELEASE_NOTES.md

@@ -0,0 +1,78 @@
+## What's in 2.6.5
+
+A patch release that ships **template discoverability**, **cron observability**, and an **end-to-end UI test harness** that locks the new install path against regression. No breaking changes; every Hermes capability target is unchanged from 2.6.0.
+
+### In-app Template Catalog
+
+The catalog is no longer web-only. **Templates → Browse Catalog…** opens a sheet that fetches the live catalog from `awizemann.github.io/scarf/templates/`, renders one row per published template with name + version + tags, and one-click installs through the existing flow. Search filters across name / description / tags; the category picker constrains to whatever categories the loaded catalog actually carries.
+
+- **Install-state badges** — each row shows "Installed v1.2.0" (green) or "Update v1.3.0" (amber) when the catalog version is newer than what's in `~/.hermes/scarf/projects.json`. Update is "uninstall + reinstall" today; in-place upgrade is on the v3 backlog.
+- **24h cache** at `~/.hermes/scarf/catalog_cache.json` so opening the sheet repeatedly doesn't re-hit the network. Refresh icon force-fetches.
+- **Bundled fallback** — fresh-install / offline users still see the official templates as a hardcoded list. Network failures serve stale cache with a "refresh failed" hint.
+- **Catalog-schema decoder fault tolerance** — one malformed entry on the live catalog can't bring down the whole list. The bad row is dropped with a logged warning; the rest survive.
+
+### HackerNews Daily Digest template
+
+First template added under the new dogfooding-templates loop. Configurable `min_score`, `max_items`, `topics`; one daily-at-08:00 cron job (paused on install) that pulls the HN Firebase API, filters, and prepends a markdown digest to the project's `digest.md`. No API keys required. Live at the catalog URL above.
+
+### Cron observability — auth-error banner + running indicator + log tail
+
+Cron rows now surface the same OAuth-refresh-revoked recovery flow as Chat instead of a generic red dot, plus three previously-missing observability cues:
+
+- **OAuth re-auth.** `ACPErrorHint.classify` runs on `job.lastError`; when it returns `oauthRefreshRevoked(provider)` the detail pane shows the human-readable hint + a **Re-authenticate** button that drops the user into Credential Pools — same wiring ChatView's banner uses. Unrecognized errors fall back to the legacy red `lastError` text.
+- **Running indicator.** The row dot turns blue + pulses when `state == "running"` (precedence over disabled / error / success); the detail header gains a "running…" badge next to active/paused. No new polling — `HermesFileWatcher.lastChangeDate` already drives `CronViewModel.load()`.
+- **Last run output.** Collapsible panel replacing the inline log: a one-line summary (`<timestamp> — ok|error|running…`) always visible, full monospaced terminal-style scroll on expand, auto-scrolls to bottom when new runs land.
+
+Also fixes a pre-existing bug in `HermesFileService.loadCronOutput` that returned the wrong file under Hermes's per-job-id output nesting.
+
+### Layer B install-drive XCUITest harness
+
+The dogfooding-templates initiative ships its first end-to-end UI test that drives the install pipeline:
+
+```
+Launch with --scarf-test-mode → Sidebar → Projects → Install sheet
+(via --scarf-test-install-url launch arg) → Configure → Open Project
+→ Right-click → Uninstall Template → Confirm Remove → Done
+```
+
+Runs ~30 s green on the dev Mac, validates 9 assertion points across the user journey. Covers the new accessibility identifiers wired in this release: `templateConfig.commitButton`, `projects.row.<name>`, `sidebar.section.<rawValue>`, `projects.contextMenu.uninstallTemplate`, `templateUninstall.confirmRemove`, `templateInstall.success.openProject`, `templateUninstall.success.done`. The `--scarf-test-install-url` launch arg + `TestModeFlags.isTestMode` gating lets XCUITest skip SwiftUI Menu / NSToolbarItem accessibility-bridging quirks that otherwise block toolbar-menu driving.
+
+Wiki [Test-Harness](https://github.com/awizemann/scarf/wiki/Test-Harness) documents how to extend the harness for the next template.
+
+### Sentinel-marker test isolation (incident-response hardening)
+
+`SCARF_HERMES_HOME` override now requires the path to contain a `.scarf-test-home-marker` file to activate. Without the marker, production code falls through to the user's real `~/.hermes/`. Lands belt-and-braces protection for cases where a test crashes mid-teardown leaving the env var set, an env var inherits from a parent shell, or a misconfigured launchctl plist exports the variable. The override remains the seam every E2E test relies on; the marker file ensures it can't accidentally pivot a non-test process off the user's data.
+
+### Chat fixes
+
+- **OAuth refresh-revoked surface.** Chat-side error banner now classifies the message via `ACPErrorHint.classify` and offers an in-app **Re-authenticate** button that routes through Credential Pools (#65). Same primitive the new cron banner reuses.
+- **Placeholder ghosting fix.** TextEditor's placeholder now clips to the editor's bounds and clears on focus instead of bleeding past the cursor area when the user types fast (#67).
+
+### Profile chip + structured logs
+
+- **Active-profile chip in the sidebar header.** Click → routes to Profiles. Local contexts only (remote SSH would mislead).
+- **Switch & Relaunch** flow now writes `~/.hermes/active_profile` and relaunches Scarf in a single click instead of asking the user to quit+reopen.
+- Profile-resolver logs are now structured (key=value form) so `log show … | grep ProfileResolver` can pull "which profile did Scarf resolve to and why" out of support requests.
+
+### Swift 6 cleanup
+
+- `MessageSpeechService` — drop `@preconcurrency` on the AVSpeechSynthesizerDelegate conformance now that the protocol's Sendable annotations are upstreamed.
+- `ChatView` — `RichChatViewModel.PendingPermission: @retroactive Identifiable`. Quiets the Swift 6 compiler so downstream breakage would be loud if ScarfCore ever adds the conformance upstream.
+- `CredentialPoolsView` — `.help(Text(verbatim:))` so backticks render literally instead of being treated as markdown inline-code.
+
+### iOS
+
+- Composer redesigned with HIG touch targets + clear disabled state.
+- Portrait lock retained.
+- Chat-start preflight moved off MainActor.
+
+### Known caveats
+
+- **Cron-job-uninstall by name is ambiguous** when two projects share the same template id. The Layer B test surfaced this — manifests as: the test passes, but if you've manually installed the same template before running the test, your real cron job can disappear. Recovery is `hermes cron create`. Fix is queued: store cron-job IDs in `<project>/.scarf/template.lock.json` at install time and resolve by ID at uninstall time.
+- **Full-suite parallel test runs intermittently hang** — pre-existing flaky test infrastructure unrelated to this release. Individual suites all pass; the hang only manifests on `xcodebuild test` with everything concurrent. The sentinel-marker hardening prevents user-data damage from any race.
+
+### Compatibility
+
+- **Hermes target unchanged from 2.6.0**: v2026.4.30 (v0.12.0). Pre-v0.12 Hermes hosts continue to work — no new capability gates added in this release.
+- **Min macOS unchanged**: 14.6.
+- **No schema changes** to anything in `~/.hermes/`. The two new Scarf-owned files (`scarf/catalog_cache.json` and the template-installer's `.scarf-test-home-marker` for tests) are additive.

releases/v2.7.0/RELEASE_NOTES.md

@@ -0,0 +1,155 @@
+## What's in 2.7.0
+
+The biggest release since 2.6.0 — a six-week stretch covering **remote-context performance**, a **new project authoring flow**, **dashboard widgets**, **OAuth resilience**, and a top-to-bottom **performance instrumentation harness** that drove the bulk of the rest. 36 commits, no schema bump, no Hermes capability bump.
+
+The throughline: Scarf got materially faster and more honest on slow remote SSH links, where 30-second sqlite timeouts and silently-empty UI used to be common. The skeleton-then-hydrate pattern, SSH cancellation propagation, and ScarfMon-driven diagnosis are the shape of how that work gets done now.
+
+---
+
+### Remote-context performance — chats and Activity in seconds, not 30s timeouts
+
+Resuming a chat on a slow remote (a 420ms-RTT droplet, an underprovisioned VPS, a tunnel through 4G) used to fetch the full message column set in one shot, which routinely tripped the 30s SSH timeout on chats with multi-page tool result blobs. The 160-message session was broken; the 30-message session was broken too. Activity didn't load at all.
+
+v2.7 introduces a **skeleton-then-hydrate pattern** that bounds the wire payload by what the user actually needs to see RIGHT NOW, then fills in the heavy stuff in the background:
+
+- **Chat skeleton.** [`fetchSkeletonMessages`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesDataService.swift) selects user + assistant rows only (skips `role='tool'`) with `tool_calls` / `reasoning` / `reasoning_content` hard-NULLed at the SQL level. Wire payload bounded by conversational text alone — typically a few KB. The chat appears in seconds. Background `startToolHydration` pages through `hydrateAssistantToolCalls` in 5-id batches to splice tool calls in. Tool-result CONTENT is **opt-in** via Settings → Display → "Load tool results in past chats" (default off); the inspector pane lazy-fetches per-result content via `fetchToolResult(callId:)` when you open a card.
+- **Activity skeleton.** [`fetchRecentToolCallSkeleton`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesDataService.swift) returns metadata-only rows (id + session_id + role + timestamp; everything else NULLed). Activity opens in <1s on remote with placeholder rows; real per-call entries swap in as paged hydration completes. New "Loading tool details…" pill in the page header surfaces hydration progress.
+- **Single-id whale recovery.** When a 5-id batch trips the 30s timeout (one row carries an oversized `tool_calls` blob — a long Edit's args, a big diff), an L1 single-id retry isolates the offending row so the rest of the batch still hydrates. Whale row stays bare; assistant message stays readable.
+- **Lazy tool result loading in the inspector.** Default-off avoids the bulk fetch. When you focus a tool call card, ChatInspectorPane fires `loadToolResultIfMissing(callId:)` which splices a single result into the message stream without re-fetching anything else.
+
+Effect: a 160-message thinking-model session that used to time out at exactly 30s now opens in under 2 seconds with placeholder cards filling in over the next few. Activity loads in 500-800ms.
+
+#### SSH cancellation that actually cancels
+
+`Task.detached { … }` doesn't inherit cancellation from the awaiting parent, and `Task<…> { … }` (unstructured) also drops the signal. Without explicit bridging, cancelling a chat-load Task only unwinds Swift state — the underlying ssh subprocess kept running for the full 30s, pinning a remote sqlite query and a ControlMaster session slot. This produced the "third chat hangs" / "dashboard spins after rapid switching" symptom.
+
+v2.7 wires `withTaskCancellationHandler` through [`SSHScriptRunner.run`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Transport/SSHScriptRunner.swift) and [`RemoteSQLiteBackend.query`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/RemoteSQLiteBackend.swift) so parent cancellation reaches the `Process` and calls `proc.terminate()` within 100ms. New `ssh.cancelled` ScarfMon event surfaces this.
+
+#### In-flight coalescing for `loadRecentSessions`
+
+File-watcher deltas during an active stream used to stack 2-3 parallel sessions-list reload tasks (the 500ms `scheduleSessionsRefresh` debounce only suppresses a pending tick, not one already executing). Subsequent callers now await the in-flight load instead of spawning a parallel SSH subprocess. New `mac.loadRecentSessions.coalesced` event tracks dedup hits.
+
+#### Loading-state UX hardening
+
+The Mac chat sidebar greys out and disables row taps the moment a session-switch is initiated (synchronously, before `client.start()` returns), with a floating ProgressView showing the current phase: **"Spawning hermes acp…"** → **"Authenticating…"** → **"Loading session…"** → **"Loading history…"** → **"Ready"**. Pre-fix the sidebar looked engageable while the 5-7 second SSH+ACP boot was still in flight, and the user could queue up a second session-switch behind the first. New `isStartingSession` flag flips on user click for instant feedback.
+
+#### Partial-result + mismatch + pinned-model banners
+
+- **Partial-result banner.** When the skeleton fetch trips an SSH transport failure (rather than a clean empty result), the chat surfaces "Couldn't load full chat history — the connection to *server* timed out" through the existing `acpError` triplet, plus forces `hasMoreHistory = true` so the "Load earlier" affordance shows up. Replaces the pre-fix silent empty transcript.
+- **Model/provider mismatch banner.** [`ModelPreflight.detectMismatch`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ModelPreflight.swift) recognizes when `model.default` carries a `<provider>/...` prefix that disagrees with `model.provider` (e.g. `anthropic/claude-sonnet-4.6` + `provider: nous` after switching OAuth via Credential Pools). Banner offers one-click fix in either direction.
+- **Pinned-model failure hint.** ACP error classifier now recognizes `model_not_found` / `404 messages` / `model is not available` and surfaces "This session was created with a model the provider no longer offers — start a new chat to use your current model" so the pinned-model failure mode has a clear recovery path.
+- **OAuth-completion provider swap.** After a successful OAuth in Credential Pools, if the just-authed provider differs from `model.provider`, surface "Switch active provider to *name*?" with [Switch] / [Keep current] instead of auto-dismissing.
+
+---
+
+### New Project from Scratch wizard + Keychain-backed cron secrets
+
+A **third project entry point** alongside Browse Catalog and Add Existing Project: a wizard that scaffolds a Scarf-standard project skeleton (`<project>/.scarf/dashboard.json` + AGENTS.md marker block), registers it, and hands off to a chat session that auto-activates the bundled `scarf-template-author` skill. The skill drives the rest conversationally — widgets, optional config schema, optional cron — and writes the final files itself. Wizard stays minimal because the agent does configuration better than a multi-step form. The skill ships bundled inside `Scarf.app/Contents/Resources/BuiltinSkills.bundle/` and copies into `~/.hermes/skills/` on launch (idempotent + version-gated).
+
+**Cron + Keychain — `$SCARF_<SLUG>_<FIELD>` env vars.** Cron prompts that referenced `secret`-typed config fields used to get the literal `keychain://...` URI back when reading `config.json`, producing 401s. v2.7 mirrors resolved Keychain values into `~/.hermes/.env` under a marker-bounded block keyed by template slug:
+
+```sh
+# scarf-secrets:begin local-news-aggregator
+SCARF_LOCAL_NEWS_AGGREGATOR_API_TOKEN=actual-value
+SCARF_LOCAL_NEWS_AGGREGATOR_RSS_URL=https://example.com/feed
+# scarf-secrets:end local-news-aggregator
+```
+
+Hermes already reloads `~/.hermes/.env` per cron tick, so credential rotation is automatic — just edit the value in Configuration → next tick sees it. The mirror runs at every state-change point: install, post-install Configuration save, uninstall, "Remove from List", and on app launch (reconciliation pass over registered projects). Source of truth stays in the Keychain — `config.json` keeps `keychain://` URIs unchanged. Mode 0600 enforced on `~/.hermes/.env`.
+
+Cron prompts now reference these env vars directly:
+
+```json
+{
+  "prompt": "Use the terminal: curl -sS -H \"Authorization: Bearer $SCARF_LOCAL_NEWS_AGGREGATOR_API_TOKEN\" \"$SCARF_LOCAL_NEWS_AGGREGATOR_RSS_URL\" -o {{PROJECT_DIR}}/.scarf/feed.xml"
+}
+```
+
+**Migration.** First launch of v2.7 walks the project registry and writes the managed block per schemaful project — automatic. Existing cron prompts you wrote against the old (broken) `config.json` pattern still need updating: open the cron job in Scarf's Cron sidebar and edit the prompt, or ask the agent in chat ("Update my Local News cron job's prompt to use the new env var convention") — the bundled `scarf-template-author` skill (now v1.1.0) documents the convention with worked examples.
+
+Also fixes [#75](https://github.com/awizemann/scarf/issues/75) — `_NSDetectedLayoutRecursion` on the Configuration form for projects whose form transitioned between stages with different intrinsic heights.
+
+---
+
+### Project dashboards — file-reading widgets, sparklines, typed status
+
+Five new widget types, project-wide auto-refresh, and a structured error card for unknown widgets. Backwards-compatible — every existing `dashboard.json` renders byte-identically.
+
+- **Project-wide auto-refresh.** [`HermesFileWatcher`](https://github.com/awizemann/scarf/blob/main/scarf/scarf/Core/Services/HermesFileWatcher.swift) used to watch each project's `dashboard.json` specifically. v2.7 promotes that to a watch on the entire `<project>/.scarf/` directory. A `markdown_file` or `log_tail` widget pointing at `<project>/.scarf/reports/foo.md` refreshes the moment a cron job rewrites the file. **By convention, place files the dashboard reads inside `.scarf/`** so the watch picks them up.
+- **`markdown_file`** — renders a markdown file from disk through the same `MarkdownContentView` pipeline used by inline `text` widgets.
+- **`log_tail`** — last `lines` of a file (default 20, max 200), monospaced, ANSI codes stripped.
+- **`cron_status`** — last run / next run / state for one Hermes cron job by `jobId`, plus a small inline log tail. Read-only — Run/Pause/Resume controls stay on the Cron tab.
+- **`image`** — local file (`path` relative to project root) or remote `url`. Optional `height` cap. Useful for matplotlib/Plotly PNGs the cron job generates.
+- **`status_grid`** — compact NxM grid of colored cells, one per service / item, with hover labels.
+- **`stat` widget gains inline sparklines.** Optional `sparkline: [Number]` field. SVG-only render, dozens per dashboard cost nothing.
+- **Typed status badges.** `list` items and `status_grid` cells share a typed enum (`success`, `warning`, `danger`, `info`, `pending`, `done`, `neutral`) with lenient decode for synonyms (`ok`/`up` → success, `down`/`error` → danger). Unknown strings render as plain text.
+- **Structured widget error card.** Replaces the legacy "Unknown: \<type\>" placeholder with a card surfacing the title, specific reason, and a hint.
+- **Schema mirror.** The widget vocabulary lives once at [`tools/widget-schema.json`](https://github.com/awizemann/scarf/blob/main/tools/widget-schema.json); the catalog validator reads from it and enforces per-type required fields.
+
+---
+
+### OAuth resilience + Credential Pools
+
+- **Daily OAuth keepalive cron.** Prevents Anthropic OAuth refresh tokens from expiring after weeks of inactivity. New cron job `[scarf:oauth-keepalive]` (managed by Scarf) pings Hermes on a daily cadence; the in-app Refresh All Sessions action mirrors the same path on demand.
+- **Remote re-auth.** Re-authenticating against a remote droplet's OAuth provider used to be blocked by the lack of a stdin path through SSHTransport. The OAuth flow now drives a remote `hermes auth add` correctly with stdin forwarded.
+- **OAuth remove button.** Per-provider remove action in Credential Pools (auth.json edit), with confirmation dialog. Companion auto-refresh of the view when `auth.json` changes externally (file-watcher).
+- **`resolve_provider_client` error classification.** When an auxiliary task references a provider whose credentials aren't loaded, Hermes prints `resolve_provider_client: <name> requested but <Display Name> not configured` to stderr — pre-fix this surfaced in chat as the opaque `-32603 Internal error` with no actionable detail. Now classified into a clear hint pointing at Settings → Aux Models.
+- **Aux Tab unknown-task surface.** When `config.yaml` has an `auxiliary.<task>` block for a task Scarf doesn't know about (newer Hermes added it; Scarf hasn't caught up), render it as a plain row with the raw provider/model values instead of dropping it silently.
+- **Credential Pools refresh after OAuth sheet dismiss.** Closing the OAuth sheet after a successful add now refreshes the list immediately instead of leaving the just-added pool hidden until the next file-watcher tick.
+
+---
+
+### ScarfMon — performance instrumentation harness
+
+The diagnostic surface that drove the bulk of the v2.7 perf work. Off by default; signpost-only mode (Instruments-friendly) is free; Full mode (4096-entry in-memory ring buffer + os.Logger) is a click away in Settings → Diagnostics → Performance. Wiki: https://github.com/awizemann/scarf/wiki/Performance-Monitoring
+
+- **Phases 1-3** built the core: dispatcher + ring buffer + 3 backends, chat / transport / sqlite measure points, diagnostic counters for chat-render bursts, finalize-burst dampening.
+- **Tier A + B** added per-feature instrumentation: iOS file watcher, sessions list, model catalog, dashboard widgets, image encoder, message hydration.
+- **Nous picker investigation** localized a 60s + 120s beach-ball to a specific path (Nous catalog `readCache`), then killed the 120s one with dedupe + 5s timeout.
+- **Tier C catch-up** (this release): instrumented Memory / Skills / Cron / Curator load paths so future captures show how often these tabs cost multiple sequential SFTP RTTs on remote.
+- **Per-call bytes recorded** on transport + sqlite events so captures show payload sizes alongside latencies.
+- **`mac.emptyAssistantTurn` event** documents the Nous quirk where the model returns a thought stream with no body (the bubble looks like Hermes is "still thinking" but the turn already finished).
+
+Adding a new measure point is two lines. The harness covers Mac and iOS uniformly. The "Copy as JSON" button exports the ring buffer for paste-into-issue diagnosis.
+
+---
+
+### Other fixes + polish
+
+- **Sessions sidebar reload debounce** — file-watcher deltas during streaming used to flicker the sessions list. Coalesced into one trailing fetch ~500ms after the last tick.
+- **Session-load pagination + race guard** — switching to a small chat while a larger one is mid-fetch could last-write-wins the small chat away. Three race-checks against `self.sessionId` prevent the stale fetch from overwriting.
+- **Sessions + previews batched** — two separate SSH calls folded into one `queryBatch` round trip, halving the round-trips for every sidebar refresh.
+- **Remote SQLite query timeout** bumped 15→30s to better tolerate slow links; in-flight query coalescing dedupes concurrent identical queries.
+- **`Thread.sleep` spin replaced** with a kernel-wait via `DispatchGroup` for `runLocal` timeout; under concurrent SSH load the old loop accumulated spin-blocked threads and produced 7-second outliers in `loadRecentSessions`.
+- **Window position + size** persists across launches.
+- **Sidebar reorder** — Projects promoted to first section; profile chip moved under server name.
+- **`stop` badge suppressed** on metadata footer for normal turn ends (it was firing for every clean completion, looking like an error).
+- **Nous picker search field** + `model-picker` filter for the long Nous overlay model list.
+- **`oauth-keepalive` cron create** — drop the `--silent` flag Hermes doesn't accept.
+- **Snapshot pipeline rewritten** — replaced the `sqlite3 .backup`-then-download pipeline with direct SSH-streamed query execution (issue [#74](https://github.com/awizemann/scarf/issues/74)). Eliminates the multi-minute snapshot wait on multi-GB state.db files. Companion fix: pre-expand `~/` in Swift via `resolvedUserHome` so sqlite3 finds the DB without depending on the remote shell's tilde expansion.
+- **Aux nested-YAML parser** — corrected the parser so the unknown-task surface works on remote (was previously dropping aux blocks whose `provider:` value lived on a separate line).
+- **`ModelPreflight` newline trim bug** — `.whitespaces` doesn't strip newlines; switched both trims to `.whitespacesAndNewlines` so a stray `\n` in a hand-edited config.yaml doesn't false-positive the mismatch banner.
+
+---
+
+### What's measured today
+
+321 ScarfCore tests pass (302 prior + 19 new ModelPreflight). New ScarfMon events documented in the [Performance-Monitoring wiki](https://github.com/awizemann/scarf/wiki/Performance-Monitoring).
+
+### Compatibility
+
+- macOS 14+ (unchanged).
+- Hermes target: still **v2026.4.30 (v0.12.0)**. No new Hermes capability gates added.
+- Existing `dashboard.json` files render unchanged.
+- Existing `.scarftemplate` bundles install unchanged. Catalog manifest schemaVersion stays at 1/2/3 — no bump.
+- Existing `~/.hermes/.env` content is preserved byte-identically — Scarf only writes inside its `# scarf-secrets:begin <slug>` / `# scarf-secrets:end <slug>` regions.
+- The skeleton-then-hydrate chat loader and SSH cancellation propagation are **Mac-only** in this release; ScarfGo (iOS) keeps its existing chat path.
+
+### What's deferred
+
+- **Per-widget data sources + per-widget refresh granularity.** The general "widget points at a typed data source" abstraction is the next-largest win in dashboards but materially expands the model + JS mirror + validator surface. The project-wide watch covers the common cron-driven workflow without it.
+- **Cross-project health digest sidebar rollup.** Counting attention-needed projects across the registry — scoped but didn't pull its weight. The typed status enum makes it cheap to add later.
+- **Automatic cron-prompt rewriter on upgrade.** Heuristic rewrites of free-form prompts are risky; the docs + agent-assisted path ships in v2.7. Revisit a "scan + fix" UI in v2.8 if real users miss the migration.
+- **iOS New Project wizard + iOS Keychain-env mirror.** ScarfGo's project surface is read-only; the wizard's chat-handoff pattern depends on Mac-only ACP plumbing.
+- **iOS skeleton-then-hydrate loaders.** Same data-service surfaces are public, but the iOS chat lifecycle is structured differently. Defer until iOS dogfooding shows the same payload-size pain.
+- **Tier C redesigns (Memory/Skills/Cron/Curator).** Instrumented in v2.7; redesign waits for capture data showing which path actually needs the skeleton-then-hydrate treatment.

releases/v2.7.1/RELEASE_NOTES.md

@@ -0,0 +1,34 @@
+## What's in 2.7.1
+
+A patch release covering three bug reports filed against 2.7.0, plus follow-up cleanups in the same neighborhood. No data migrations, no UI surface changes — drop-in replacement for 2.7.0 on Mac.
+
+### Bug fixes
+
+#### Mac
+
+- **[#77](https://github.com/awizemann/scarf/issues/77) — Sessions screen renders empty even when Dashboard reports sessions exist.** v2.7.0 folded the Sessions tab's two SQL queries (sessions list + previews) into a single batched SSH round-trip for perf. The combined wire payload for any user with ~150+ sessions crossed macOS's 16–64 KB pipe-buffer threshold; without a concurrent reader draining the pipe, the remote `sqlite3 -json` blocked, the script never finished, our 30-second timeout fired, and the call returned an empty result. `SSHScriptRunner` now drains stdout/stderr concurrently with the running process via `FileHandle.readabilityHandler`, so the kernel pipe never fills. Same fix applied to the local-execution path. New regression test pushes 256 KB of synthetic output through the runner and asserts full delivery — would have wedged pre-fix.
+
+- **[#78](https://github.com/awizemann/scarf/issues/78) — Skills "What's New" pill contradicts the Updates sub-tab.** The pill at the top of the Skills page was rendering on every sub-tab, including Updates. It counts **local** file deltas since the user last clicked "Mark as seen" (e.g. "18 new" = 18 skills landed on disk that you haven't acknowledged), while the Updates body runs `hermes skills check` to find skills with newer **upstream** versions available — a different concept. Two surfaces using the word "update" for two different things made the screen contradict itself. Two changes: the pill now renders only on the Installed sub-tab (Mac and ScarfGo), and its label says "X **changed** since you last looked" instead of "X updated" so the local-file vocabulary doesn't collide with upstream-update vocabulary anywhere on the page.
+
+- **[#79](https://github.com/awizemann/scarf/issues/79) — Skills hub search returns nothing for terms visible in Browse.** With the source picker on "All Sources", `hermes skills search <query>` (no `--source` flag) routes through Hermes's centralized index and skips external API sources (skills-sh, github, clawhub, lobehub, well-known) — but Browse still aggregates from those sources, so a skill like `honcho` would show up in Browse and disappear in search. Same picker, same query, contradictory results. Rather than chase Hermes's index gaps, "All Sources" search now means "filter what you can already see": Scarf caches the most recent Browse payload and runs a client-side substring filter (case-insensitive against name, description, and identifier) against it, instantly. Source-specific searches still shell out to `hermes skills search --source <s>` for full upstream search semantics. Five new tests cover the filter behavior.
+
+- **`hermesPIDResult()` — narrow the Hermes "is it running?" probe to the gateway.** Previously `pgrep -f hermes`, which matched any process with "hermes" in its argv: chat sessions Scarf itself spawns, `hermes -z` one-shots, log tails, even the README in an editor. The Dashboard "Hermes is running" badge could read true even when the gateway daemon was down. Tightened to a regex that matches only the gateway shape — `python -m hermes_cli.main gateway run …` and `/path/to/hermes gateway run …`. All callers (DashboardViewModel, HealthViewModel, SettingsViewModel, scarfApp, stopHermes) want the gateway PID specifically. Cherry-picked from [#76](https://github.com/awizemann/scarf/pull/76) — thanks to [@unixwzrd](https://github.com/unixwzrd) for the diagnosis and regex.
+
+- **`HealthViewModel.stopDashboard()` — stop the dashboard by port, not `pkill -f`.** External-instance fallback used to be `pkill -f "hermes dashboard"`, broad enough to match shell history, log tails, README readers — anything with the substring in its argv. Now `lsof -tiTCP:<port> -sTCP:LISTEN` resolves the PID actually bound to the dashboard port and only that one process gets `SIGTERM`. Trusting the port is correct here: Scarf owns the configured port and the user-visible intent is "stop the thing on this port." Direction cherry-picked from [#76](https://github.com/awizemann/scarf/pull/76); the `-c hermes` filter from the original was dropped because Hermes installs as a Python shebang script and the kernel COMM is `python`, not `hermes` — `-c hermes` would silently miss every standard install.
+
+### Documentation + tooling
+
+- **`scripts/local-build.sh` + `BUILDING.md` for contributor builds.** New unsigned single-arch Debug build script for contributors without an Apple Developer account. Detects arm64 / x86_64, verifies xcode-select / xcrun / xcodebuild, probes the Metal toolchain (offers an interactive install on TTY, errors cleanly on CI), resolves Swift packages, builds Debug with signing disabled. Optional one-touch `ditto` to `/Applications/scarf.app` on explicit y/N. The canonical Release universal CLI in `README.md` is unchanged — `local-build.sh` is an alternative for contributors, not a replacement for the shipping build. Cherry-picked from [#76](https://github.com/awizemann/scarf/pull/76).
+
+- **`BUILDING.md` + `CONTRIBUTING.md` — restored Sonoma compatibility messaging.** The runtime min is **macOS 14.6 (Sonoma)** — that's the `MACOSX_DEPLOYMENT_TARGET` on the main `scarf` target and is intentional. Build min is **Xcode 16.0** (needed for Swift 6 strict-concurrency features). The legacy CONTRIBUTING.md line had drifted to "Xcode 26.3+ / macOS 26.2+", which would have steered Sonoma contributors and users away from a build that actually runs on their box. Corrected, with a load-bearing-callout in BUILDING.md so future doc edits don't silently raise the floor again.
+
+### Migrating from 2.7.0
+
+Sparkle will offer the update automatically. No config migration, no schema changes. Existing sessions, skills, and projects are untouched.
+
+If you've been working around #77 by collapsing the sidebar or restarting Scarf to repopulate the Sessions list, you can stop — sessions should load reliably now.
+
+### Acknowledgements
+
+- [@bricelb](https://github.com/bricelb) for the three v2.7.0 bug reports ([#77](https://github.com/awizemann/scarf/issues/77), [#78](https://github.com/awizemann/scarf/issues/78), [#79](https://github.com/awizemann/scarf/issues/79)) — well-instrumented reproductions including screenshots and environment details made the diagnosis straightforward.
+- [@unixwzrd](https://github.com/unixwzrd) for [#76](https://github.com/awizemann/scarf/pull/76) — the gateway-pgrep tighten, the `pkill -f "hermes dashboard"` direction, and the `local-build.sh` contributor flow are all cherry-picked from that PR.

scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPChannel.swift

@@ -47,6 +47,23 @@ public protocol ACPChannel: Sendable {
     /// SSH exec channels return the SSH channel id or `nil` when not
     /// applicable.
     var diagnosticID: String? { get async }
+
+    /// Exit status of the underlying transport once it has terminated.
+    /// `nil` while the channel is still alive, or for transports that
+    /// don't have a meaningful integer exit code (Citadel SSH-exec).
+    /// Read by `ACPClient` when populating `processTerminated` so the
+    /// user-facing error can name the actual exit code (e.g. `exit
+    /// 255` for SSH connect failures, `exit 127` for missing remote
+    /// binary).
+    var lastExitCode: Int32? { get async }
+}
+
+public extension ACPChannel {
+    /// Default: channels that don't track an exit code report `nil`.
+    /// Concrete `ProcessACPChannel` overrides this.
+    var lastExitCode: Int32? {
+        get async { nil }
+    }
 }
 
 /// Errors raised by `ACPChannel` implementations when the underlying

scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPClient.swift

@@ -266,14 +266,47 @@ public actor ACPClient {
     // MARK: - Messaging
 
     public func sendPrompt(sessionId: String, text: String) async throws -> ACPPromptResult {
+        try await sendPrompt(sessionId: sessionId, text: text, images: [])
+    }
+
+    /// v0.12+ overload: forward zero or more image attachments alongside
+    /// the user's text. Each attachment becomes a separate
+    /// `ImageContentBlock` in the ACP `prompt` content array — matches
+    /// the shape Hermes' `acp_adapter/server.py` expects (text first,
+    /// then image blocks). Hermes routes the resulting payload to a
+    /// vision-capable model automatically; the producer side only has
+    /// to deliver the bytes.
+    ///
+    /// Pre-v0.12 Hermes installs accepted only a single `text` block.
+    /// Callers gate this overload on
+    /// `HermesCapabilitiesStore.capabilities.hasACPImagePrompts` so we
+    /// don't send blocks an older agent would silently drop.
+    public func sendPrompt(
+        sessionId: String,
+        text: String,
+        images: [ChatImageAttachment]
+    ) async throws -> ACPPromptResult {
         statusMessage = "Sending prompt..."
         let messageId = UUID().uuidString
+
+        // Always include the text block, even when empty — keeps the
+        // server-side text-extraction path stable regardless of whether
+        // the user sent text alongside the image(s).
+        var promptBlocks: [[String: Any]] = [
+            ["type": "text", "text": text] as [String: Any],
+        ]
+        for image in images {
+            promptBlocks.append([
+                "type": "image",
+                "data": image.base64Data,
+                "mimeType": image.mimeType,
+            ] as [String: Any])
+        }
+
         let params: [String: AnyCodable] = [
             "sessionId": AnyCodable(sessionId),
             "messageId": AnyCodable(messageId),
-            "prompt": AnyCodable([
-                ["type": "text", "text": text] as [String: Any],
-            ] as [Any]),
+            "prompt": AnyCodable(promptBlocks as [Any]),
         ]
         let result = try await sendRequest(method: "session/prompt", params: params)
         let dict = result?.dictValue ?? [:]
@@ -329,10 +362,17 @@ public actor ACPClient {
         #endif
 
         // session/prompt streams events and can run for minutes — no hard
-        // timeout. Control messages get a 30s watchdog.
+        // timeout. Control messages get a 60s watchdog. Older versions
+        // capped at 30s, which the field reported (#61) was tripping
+        // under realistic gateway+ACP concurrency: the gateway holds
+        // state.db locks for Discord sync / skill registration / cron
+        // scheduling, and ACP's `initialize` / `session/new` /
+        // `session/load` stall waiting for the lock. SQLite contention
+        // on a healthy host clears in seconds; 60s gives that headroom
+        // while still surfacing genuinely broken transports promptly.
         let timeoutTask: Task<Void, Error>? = if method != "session/prompt" {
             Task { [weak self] in
-                try await Task.sleep(nanoseconds: 30 * 1_000_000_000)
+                try await Task.sleep(nanoseconds: 60 * 1_000_000_000)
                 await self?.timeoutRequest(id: requestId, method: method)
             }
         } else {
@@ -468,35 +508,48 @@ public actor ACPClient {
     // MARK: - Disconnect Cleanup
 
     /// Single idempotent cleanup path for all disconnect scenarios.
-    private func performDisconnectCleanup(reason: String) {
+    /// Captures the channel's exit code + recent stderr BEFORE we drop
+    /// the reference, so the `processTerminated` error rides with
+    /// diagnostics — the user banner shows "exit 255 — ssh: connect to
+    /// host …: Connection refused" instead of a bare opaque timeout.
+    private func performDisconnectCleanup(reason: String) async {
         guard isConnected else { return }
         #if canImport(os)
         logger.warning("ACP disconnecting: \(reason)")
         #endif
+        let exitCode = await channel?.lastExitCode
+        let tail = recentStderr
         isConnected = false
         statusMessage = "Connection lost"
         for (_, continuation) in pendingRequests {
-            continuation.resume(throwing: ACPClientError.processTerminated)
+            continuation.resume(throwing: ACPClientError.processTerminated(
+                exitCode: exitCode,
+                stderrTail: tail
+            ))
         }
         pendingRequests.removeAll()
         eventContinuation?.finish()
         eventContinuation = nil
     }
 
-    private func handleReadLoopEnded(cleanly: Bool, error: Error? = nil) {
+    private func handleReadLoopEnded(cleanly: Bool, error: Error? = nil) async {
         let reason = cleanly ? "read loop ended (EOF)" : "read loop failed: \(error?.localizedDescription ?? "unknown")"
-        performDisconnectCleanup(reason: reason)
+        await performDisconnectCleanup(reason: reason)
     }
 
-    private func handleWriteFailed() {
-        performDisconnectCleanup(reason: "write failed (broken pipe)")
+    private func handleWriteFailed() async {
+        await performDisconnectCleanup(reason: "write failed (broken pipe)")
     }
 
-    private func handleWriteFailedForRequest(id: Int) {
+    private func handleWriteFailedForRequest(id: Int) async {
         if let continuation = pendingRequests.removeValue(forKey: id) {
-            continuation.resume(throwing: ACPClientError.processTerminated)
+            let exitCode = await channel?.lastExitCode
+            continuation.resume(throwing: ACPClientError.processTerminated(
+                exitCode: exitCode,
+                stderrTail: recentStderr
+            ))
         }
-        performDisconnectCleanup(reason: "write failed (broken pipe)")
+        await performDisconnectCleanup(reason: "write failed (broken pipe)")
     }
 }
 
@@ -507,7 +560,7 @@ public enum ACPClientError: Error, LocalizedError {
     case encodingFailed
     case invalidResponse(String)
     case rpcError(code: Int, message: String)
-    case processTerminated
+    case processTerminated(exitCode: Int32?, stderrTail: String)
     case requestTimeout(method: String)
 
     public var errorDescription: String? {
@@ -516,25 +569,152 @@ public enum ACPClientError: Error, LocalizedError {
         case .encodingFailed: return "Failed to encode JSON-RPC request"
         case .invalidResponse(let msg): return "Invalid ACP response: \(msg)"
         case .rpcError(let code, let msg): return "ACP error \(code): \(msg)"
-        case .processTerminated: return "ACP process terminated unexpectedly"
+        case .processTerminated(let exit, let tail):
+            let exitPart = exit.map { "exit \($0)" } ?? "no exit code"
+            let tailPart = Self.firstNonEmptyLine(in: tail).map { " — \($0)" } ?? ""
+            return "ACP process terminated unexpectedly (\(exitPart))\(tailPart)"
         case .requestTimeout(let method): return "ACP request '\(method)' timed out"
         }
     }
+
+    /// Pluck the first non-empty stderr line for the user-facing
+    /// summary. Full tail still rides through on `acpErrorDetails`,
+    /// but the description itself stays single-line.
+    private static func firstNonEmptyLine(in s: String) -> String? {
+        for raw in s.split(separator: "\n") {
+            let line = raw.trimmingCharacters(in: .whitespaces)
+            if !line.isEmpty { return line }
+        }
+        return nil
+    }
 }
 
 /// Maps a raw error message (RPC message or captured stderr) to a short
 /// human-readable hint for the chat UI. Pattern-matches the most common
 /// fresh-install failure modes. Returns nil when no known pattern matches.
 public enum ACPErrorHint {
-    public static func classify(errorMessage: String, stderrTail: String) -> String? {
+    /// Result of a classifier hit. `hint` is the user-facing copy; when
+    /// the failure is an OAuth refresh-revocation, `oauthProvider` names
+    /// the affected provider (lowercase, matching `auth.json` keys) so
+    /// the UI can offer a one-click re-authenticate affordance. `nil`
+    /// `oauthProvider` means "we matched a non-OAuth failure mode, or
+    /// we matched OAuth but couldn't identify which provider."
+    public struct Classification: Sendable, Equatable {
+        public let hint: String
+        public let oauthProvider: String?
+
+        public init(hint: String, oauthProvider: String? = nil) {
+            self.hint = hint
+            self.oauthProvider = oauthProvider
+        }
+    }
+
+    /// Known OAuth-authed providers Hermes ships. Listed lowercase to
+    /// match `auth.json.providers.<key>` and the values
+    /// `OAuthFlowController.start(provider:)` accepts.
+    private static let oauthProviders = [
+        "nous", "claude", "anthropic", "qwen", "gemini", "google", "copilot", "github",
+    ]
+
+    public static func classify(errorMessage: String, stderrTail: String) -> Classification? {
         let haystack = errorMessage + "\n" + stderrTail
+
+        // SSH-level failures come first — they apply only to remote
+        // contexts and the patterns are unambiguous (system ssh prints
+        // them verbatim to stderr). Without these classifications a
+        // vanished droplet, a wrong key, or a missing remote `hermes`
+        // all surface as opaque "ACP process terminated" / "request
+        // timed out", and the user has no idea where to look.
+        if haystack.contains("Connection refused") {
+            return Classification(hint: "Couldn't reach the remote host — the SSH port is closed or the droplet is down. Check the host is running and reachable.")
+        }
+        if haystack.localizedCaseInsensitiveContains("Operation timed out")
+            || haystack.localizedCaseInsensitiveContains("Connection timed out")
+            || haystack.contains("Network is unreachable")
+            || haystack.contains("No route to host") {
+            return Classification(hint: "Couldn't reach the remote host — the network connection timed out. Check the host is running and your network is up.")
+        }
+        if haystack.contains("Permission denied (publickey")
+            || haystack.contains("Permission denied, please try again") {
+            return Classification(hint: "SSH rejected the key. Make sure the right identity file is selected and that ssh-agent has the key loaded — open Terminal and run `ssh-add -l`.")
+        }
+        if haystack.contains("Host key verification failed")
+            || haystack.contains("REMOTE HOST IDENTIFICATION HAS CHANGED") {
+            return Classification(hint: "The remote host's SSH key changed. If you just rebuilt the droplet, remove the old entry with `ssh-keygen -R <host>`, then try again.")
+        }
+        if haystack.contains("Could not resolve hostname")
+            || haystack.contains("Name or service not known") {
+            return Classification(hint: "Couldn't resolve the host name. Check the host in this server's settings.")
+        }
+        if haystack.localizedCaseInsensitiveContains("command not found")
+            || haystack.contains("hermes: not found")
+            || haystack.contains("exit 127") {
+            return Classification(hint: "The remote shell couldn't find `hermes`. Either install Hermes on the remote (`pipx install hermes-agent`) or set an absolute binary path in this server's settings.")
+        }
+
+        // OAuth refresh-token revocation. Hermes prints
+        // "Refresh session has been revoked. Run `hermes model` to
+        // re-authenticate." to stderr/stdout when an OAuth-authed
+        // provider's refresh token can no longer mint access tokens
+        // (user revoked, server rotated keys, etc.). We can't drive
+        // `hermes model` interactively, but `hermes auth add <provider>
+        // --type oauth` is the same code path Scarf already drives via
+        // `OAuthFlowController` for first-time setup, so we surface a
+        // re-authenticate affordance instead. Checked BEFORE the
+        // generic "no credentials found" path because the message
+        // contains the word "credentials" via the surrounding context.
+        if haystack.localizedCaseInsensitiveContains("refresh session has been revoked")
+            || haystack.range(of: #"refresh.*revoked"#, options: [.regularExpression, .caseInsensitive]) != nil
+            || haystack.localizedCaseInsensitiveContains("re-authenticate")
+            || haystack.localizedCaseInsensitiveContains("reauthenticate")
+            || (haystack.contains("401") && oauthProvider(in: haystack) != nil)
+            || (haystack.localizedCaseInsensitiveContains("unauthorized") && oauthProvider(in: haystack) != nil) {
+            let provider = oauthProvider(in: haystack)
+            let suffix = provider.map { " (affected provider: \($0))." } ?? "."
+            return Classification(
+                hint: "Your OAuth session has expired or been revoked\(suffix) Click Re-authenticate below to sign in again.",
+                oauthProvider: provider
+            )
+        }
+
+        // Auxiliary task references a provider that isn't authenticated.
+        // Hermes prints `resolve_provider_client: <name> requested but
+        // <Display Name> not configured` when an aux task (compression,
+        // summarization, memory_flush, curator, vision, web_extract,
+        // session_search, skills_hub) has `provider: <name>` set in
+        // config.yaml but that provider's credentials aren't loaded.
+        // Common after a user removes one OAuth provider while their
+        // existing config.yaml still names it for an aux task. The
+        // chat banner used to surface this as `-32603 Internal error`
+        // with no actionable detail; surface a clear path now.
+        if let match = haystack.range(
+            of: #"resolve_provider_client:\s*([a-zA-Z0-9_-]+)\s+requested\s+but"#,
+            options: .regularExpression
+        ) {
+            let line = String(haystack[match])
+            // Pull the captured provider name out of the matched line.
+            // First word after "resolve_provider_client:" is the value.
+            let provider: String = {
+                let parts = line.split(whereSeparator: { $0.isWhitespace })
+                if let idx = parts.firstIndex(where: { $0.contains("resolve_provider_client") }),
+                   parts.index(after: idx) < parts.endIndex {
+                    let candidate = parts[parts.index(after: idx)]
+                    return String(candidate)
+                }
+                return "an unauthenticated provider"
+            }()
+            return Classification(
+                hint: "An auxiliary task is configured to use `\(provider)` but that provider isn't authenticated. Open Settings → Aux Models, or check `~/.hermes/config.yaml` for `auxiliary.<task>.provider: \(provider)` and switch it to your active provider (or set it to `auto`)."
+            )
+        }
+
         if haystack.range(of: #"No\s+(Anthropic|OpenAI|OpenRouter|Gemini|Google|Groq|Mistral|XAI)?\s*credentials\s+found"#,
                           options: .regularExpression) != nil
             || haystack.contains("ANTHROPIC_API_KEY")
             || haystack.contains("ANTHROPIC_TOKEN")
             || haystack.contains("claude setup-token")
             || haystack.contains("claude /login") {
-            return "Hermes can't find your AI provider credentials. Set `ANTHROPIC_API_KEY` (or similar) in `~/.hermes/.env` or your shell profile, then restart Scarf."
+            return Classification(hint: "Hermes can't find your AI provider credentials. Set `ANTHROPIC_API_KEY` (or similar) in `~/.hermes/.env` or your shell profile, then restart Scarf.")
         }
         if let match = haystack.range(of: #"No such file or directory:\s*'([^']+)'"#,
                                       options: .regularExpression) {
@@ -542,13 +722,47 @@ public enum ACPErrorHint {
             if let nameStart = matched.range(of: "'"),
                let nameEnd = matched.range(of: "'", range: nameStart.upperBound..<matched.endIndex) {
                 let name = String(matched[nameStart.upperBound..<nameEnd.lowerBound])
-                return "Hermes couldn't find `\(name)` on PATH. If you use nvm/asdf/mise, make sure it's exported in `~/.zprofile` (not only `~/.zshrc`), then restart Scarf."
+                return Classification(hint: "Hermes couldn't find `\(name)` on PATH. If you use nvm/asdf/mise, make sure it's exported in `~/.zprofile` (not only `~/.zshrc`), then restart Scarf.")
             }
-            return "Hermes couldn't find a required binary on PATH. Check that your shell's PATH is exported in `~/.zprofile`, then restart Scarf."
+            return Classification(hint: "Hermes couldn't find a required binary on PATH. Check that your shell's PATH is exported in `~/.zprofile`, then restart Scarf.")
         }
         if haystack.localizedCaseInsensitiveContains("rate limit")
             || haystack.localizedCaseInsensitiveContains("429") {
-            return "Your AI provider returned a rate-limit error. Try again in a moment."
+            return Classification(hint: "Your AI provider returned a rate-limit error. Try again in a moment.")
+        }
+        // Model-availability failure. Hermes pins each session to the
+        // model that opened it, so resuming an old session whose model
+        // is no longer available (provider deprecation, OAuth swapped
+        // to a different provider, model name changed) returns a 404
+        // / model_not_found from the upstream provider — surfaced as
+        // an opaque "-32603 Internal error" in chat. v2.8 surfaces a
+        // clear "session is pinned" hint with the recovery path.
+        if haystack.localizedCaseInsensitiveContains("model_not_found")
+            || haystack.localizedCaseInsensitiveContains("model not found")
+            || haystack.localizedCaseInsensitiveContains("invalid_model")
+            || haystack.localizedCaseInsensitiveContains("model is not available")
+            || haystack.localizedCaseInsensitiveContains("unknown model")
+            || (haystack.contains("404") && (haystack.localizedCaseInsensitiveContains("model")
+                                              || haystack.localizedCaseInsensitiveContains("messages"))) {
+            return Classification(hint: "This session was created with a model the provider no longer offers. Hermes pins each session to its original model — start a new chat to use your current model, or run `hermes sessions clone` in Terminal to copy this conversation onto the new model.")
+        }
+        return nil
+    }
+
+    /// Best-effort extraction of an OAuth provider name from raw error
+    /// text. Returns the lowercase provider key (`"nous"`, `"claude"`,
+    /// etc.) when one of the known OAuth providers appears as a whole
+    /// word. The first match wins — Hermes typically logs the active
+    /// provider name once, near the failure.
+    private static func oauthProvider(in haystack: String) -> String? {
+        let lowered = haystack.lowercased()
+        for provider in oauthProviders {
+            // Whole-word match so substrings like "anthropicapi" don't
+            // false-trigger on "anthropic".
+            let pattern = "\\b" + NSRegularExpression.escapedPattern(for: provider) + "\\b"
+            if lowered.range(of: pattern, options: .regularExpression) != nil {
+                return provider
+            }
         }
         return nil
     }

scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ProcessACPChannel.swift

@@ -36,6 +36,17 @@ public actor ProcessACPChannel: ACPChannel {
     private var readerTask: Task<Void, Never>?
     private var stderrTask: Task<Void, Never>?
 
+    /// Read by `ACPClient` to fill in `processTerminated(exitCode:…)`
+    /// so the error names the actual exit code rather than reporting a
+    /// bare timeout. Sourced directly from `Process` — `Process` is
+    /// thread-safe for this read and reflects the actual reap state,
+    /// so we sidestep the race between the OS-side `terminationHandler`
+    /// callback and the EOF-driven disconnect cleanup that would
+    /// otherwise need an atomic to coordinate.
+    public var lastExitCode: Int32? {
+        process.isRunning ? nil : process.terminationStatus
+    }
+
     /// The subprocess's PID as a human-readable string.
     public var diagnosticID: String? {
         "pid=\(process.processIdentifier)"
@@ -58,7 +69,7 @@ public actor ProcessACPChannel: ACPChannel {
         proc.executableURL = URL(fileURLWithPath: executable)
         proc.arguments = args
         proc.environment = env
-        try await Self.launch(process: proc, self_: nil)
+        try await Self.launch(process: proc)
         try Self.ignoreSIGPIPE_once()
 
         self.process = proc
@@ -75,14 +86,15 @@ public actor ProcessACPChannel: ACPChannel {
         self.stderr = errStream
         self.stderrContinuation = errContinuation
 
-        await startReaders()
+        startReaders()
+        installTerminationHandler()
     }
 
     /// Secondary entry point for callers that have a pre-configured
     /// `Process` (typically from `SSHTransport.makeProcess`). The process
     /// must NOT already be running — this initializer calls `run()`.
     public init(process: Process) async throws {
-        try await Self.launch(process: process, self_: nil)
+        try await Self.launch(process: process)
         try Self.ignoreSIGPIPE_once()
 
         self.process = process
@@ -99,15 +111,13 @@ public actor ProcessACPChannel: ACPChannel {
         self.stderr = errStream
         self.stderrContinuation = errContinuation
 
-        await startReaders()
+        startReaders()
+        installTerminationHandler()
     }
 
     /// Wire fresh stdin/stdout/stderr pipes (overwriting any the caller
-    /// set) and start the subprocess. `self_` is unused today — the
-    /// placeholder keeps the signature ready for a future hook that
-    /// captures termination in `proc.terminationHandler` and routes it
-    /// into the channel's actor state.
-    private static func launch(process: Process, self_: Any?) async throws {
+    /// set) and start the subprocess.
+    private static func launch(process: Process) async throws {
         process.standardInput  = Pipe()
         process.standardOutput = Pipe()
         process.standardError  = Pipe()
@@ -118,6 +128,22 @@ public actor ProcessACPChannel: ACPChannel {
         }
     }
 
+    /// Install a `terminationHandler` that closes the stdout read end
+    /// the moment the OS reaps the child. Without this, the reader
+    /// loop's `availableData` keeps blocking until the kernel tears
+    /// the pipe down on its own schedule — visible to the user as a
+    /// 30s ACP `initialize` timeout where a fast SSH-side failure
+    /// (Connection refused, exit 127) should surface in under a
+    /// second. The exit code itself is read on demand from
+    /// `Process.terminationStatus` (see `lastExitCode`), so this
+    /// callback doesn't need to touch actor state.
+    private func installTerminationHandler() {
+        let stdoutFh = stdoutPipe.fileHandleForReading
+        process.terminationHandler = { _ in
+            try? stdoutFh.close()
+        }
+    }
+
     /// Ignore SIGPIPE once per process so a broken-pipe write returns
     /// `EPIPE` (which we surface as `.writeEndClosed`) instead of
     /// delivering SIGPIPE and tearing the app down. Idempotent; the

scarf/Packages/ScarfCore/Sources/ScarfCore/Diagnostics/ScarfMon.swift

@@ -0,0 +1,277 @@
+import Foundation
+#if canImport(os)
+import os
+import os.signpost
+#endif
+
+/// Lightweight performance instrumentation for the Scarf app family.
+///
+/// Three primitives — `measure(...)`, `measureAsync(...)`, `event(...)` — drop
+/// timing samples through whatever set of backends is currently active.
+/// Backends are pluggable: an always-on `os_signpost` backend (free outside
+/// Instruments), an in-memory ring buffer (drives the in-app panel), and an
+/// `os.Logger` debug backend (off by default).
+///
+/// **Cost when off.** When no backends are registered, every entry point is
+/// `@inline(__always)` and short-circuits to the body call without taking the
+/// `ContinuousClock.now` reading. Open source build defaults to "signpost
+/// only" — that backend pays one signpost emit per call, which Apple's runtime
+/// elides when no Instruments session is recording.
+///
+/// **Privacy.** Names are `StaticString` so we cannot accidentally pass user
+/// content through a metric tag. Optional `bytes:` field on `event` tracks
+/// payload size, never payload contents. The ring buffer never leaves the
+/// device unless the user explicitly hits "Copy as JSON" in the Diagnostics
+/// panel.
+public enum ScarfMon {
+
+    // MARK: - Public API
+
+    /// Synchronous timing wrapper. The body's return value flows through
+    /// untouched; the time it took plus `(category, name)` are recorded.
+    @inline(__always)
+    public static func measure<T>(
+        _ category: Category,
+        _ name: StaticString,
+        _ body: () throws -> T
+    ) rethrows -> T {
+        guard isActive else { return try body() }
+        let start = ContinuousClock.now
+        defer { record(category, name, start: start, end: ContinuousClock.now) }
+        return try body()
+    }
+
+    /// Async variant. Same shape — the `defer` block fires after the body
+    /// returns whether or not it threw, so cancelled / failed work still
+    /// records its duration.
+    @inline(__always)
+    public static func measureAsync<T>(
+        _ category: Category,
+        _ name: StaticString,
+        _ body: () async throws -> T
+    ) async rethrows -> T {
+        guard isActive else { return try await body() }
+        let start = ContinuousClock.now
+        defer { record(category, name, start: start, end: ContinuousClock.now) }
+        return try await body()
+    }
+
+    /// Single-shot timestamped event. Use for things that aren't intervals
+    /// (token arrivals, buffer flushes) where count + optional payload size
+    /// is the useful signal.
+    @inline(__always)
+    public static func event(
+        _ category: Category,
+        _ name: StaticString,
+        count: Int = 1,
+        bytes: Int? = nil
+    ) {
+        guard isActive else { return }
+        recordEvent(category, name, count: count, bytes: bytes)
+    }
+
+    // MARK: - Backend management
+
+    /// Install the desired backend set. Replaces the current set atomically.
+    /// Call once at app boot from the launch sequence; safe to call again
+    /// when the user toggles a setting on or off.
+    public static func install(_ backends: [ScarfMonBackend]) {
+        lock.lock()
+        defer { lock.unlock() }
+        installed = backends
+        cachedActive = !backends.isEmpty
+    }
+
+    /// Currently-installed backends. Test-only — callers should not iterate
+    /// this in production.
+    public static var currentBackends: [ScarfMonBackend] {
+        lock.lock()
+        defer { lock.unlock() }
+        return installed
+    }
+
+    /// Cheap "are we recording anything?" check. The flag is updated only
+    /// when `install(...)` runs, so the hot path doesn't take the lock.
+    @inline(__always)
+    public static var isActive: Bool { cachedActive }
+
+    // MARK: - Internals
+
+    private static let lock = ScarfMonLock()
+    nonisolated(unsafe) private static var installed: [ScarfMonBackend] = []
+    nonisolated(unsafe) private static var cachedActive: Bool = false
+
+    @inline(__always)
+    private static func record(
+        _ category: Category,
+        _ name: StaticString,
+        start: ContinuousClock.Instant,
+        end: ContinuousClock.Instant
+    ) {
+        let duration = end - start
+        let nanos = nanoseconds(of: duration)
+        let backends = snapshotBackends()
+        let sample = Sample(
+            category: category,
+            name: name,
+            kind: .interval,
+            timestamp: Date(),
+            durationNanos: nanos,
+            count: 1,
+            bytes: nil
+        )
+        for backend in backends {
+            backend.record(sample)
+        }
+    }
+
+    @inline(__always)
+    private static func recordEvent(
+        _ category: Category,
+        _ name: StaticString,
+        count: Int,
+        bytes: Int?
+    ) {
+        let backends = snapshotBackends()
+        let sample = Sample(
+            category: category,
+            name: name,
+            kind: .event,
+            timestamp: Date(),
+            durationNanos: 0,
+            count: count,
+            bytes: bytes
+        )
+        for backend in backends {
+            backend.record(sample)
+        }
+    }
+
+    private static func snapshotBackends() -> [ScarfMonBackend] {
+        lock.lock()
+        defer { lock.unlock() }
+        return installed
+    }
+
+    private static func nanoseconds(of duration: Duration) -> UInt64 {
+        // Duration is (seconds: Int64, attoseconds: Int64). Avoid Double
+        // for the seconds term to keep precision on long intervals.
+        let comps = duration.components
+        let secondsAsNanos = UInt64(max(0, comps.seconds)) &* 1_000_000_000
+        let attoAsNanos = UInt64(max(0, comps.attoseconds) / 1_000_000_000)
+        return secondsAsNanos &+ attoAsNanos
+    }
+}
+
+// MARK: - Categories
+
+extension ScarfMon {
+    /// Stable category vocabulary. Add cases here when new subsystems get
+    /// instrumented; renames are breaking changes for any saved JSON dumps
+    /// users have shared, so prefer adding over renaming.
+    public enum Category: String, CaseIterable, Sendable, Codable {
+        case chatRender
+        case chatStream
+        case sessionLoad
+        case transport
+        case sqlite
+        case diskIO
+        case render
+        case other
+    }
+}
+
+// MARK: - Sample
+
+/// One recorded sample. All fields are value types so the struct is trivially
+/// `Sendable` across backend queues without locks.
+public struct ScarfMonSample: Sendable, Hashable {
+    public enum Kind: String, Sendable, Codable {
+        case interval
+        case event
+    }
+    public let category: ScarfMon.Category
+    /// Static name string captured at the call site. Not a `String` — keeping
+    /// it `StaticString` proves at compile time that names cannot leak user
+    /// data through this channel.
+    public let name: StaticString
+    public let kind: Kind
+    public let timestamp: Date
+    public let durationNanos: UInt64
+    public let count: Int
+    public let bytes: Int?
+
+    public init(
+        category: ScarfMon.Category,
+        name: StaticString,
+        kind: Kind,
+        timestamp: Date,
+        durationNanos: UInt64,
+        count: Int,
+        bytes: Int?
+    ) {
+        self.category = category
+        self.name = name
+        self.kind = kind
+        self.timestamp = timestamp
+        self.durationNanos = durationNanos
+        self.count = count
+        self.bytes = bytes
+    }
+
+    /// `StaticString` does not conform to `Hashable` natively (it doesn't
+    /// promise a stable hash). We hash via its UTF-8 representation so two
+    /// samples with the same source-literal name compare equal.
+    public static func == (lhs: ScarfMonSample, rhs: ScarfMonSample) -> Bool {
+        lhs.category == rhs.category
+            && lhs.kind == rhs.kind
+            && lhs.timestamp == rhs.timestamp
+            && lhs.durationNanos == rhs.durationNanos
+            && lhs.count == rhs.count
+            && lhs.bytes == rhs.bytes
+            && lhs.name.description == rhs.name.description
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(category)
+        hasher.combine(kind)
+        hasher.combine(timestamp)
+        hasher.combine(durationNanos)
+        hasher.combine(count)
+        hasher.combine(bytes)
+        hasher.combine(name.description)
+    }
+}
+
+extension ScarfMon {
+    public typealias Sample = ScarfMonSample
+}
+
+// MARK: - Backend protocol
+
+/// One sink for samples. Implementations must be cheap on the hot path —
+/// callers hold no lock while invoking `record`, but the hot path runs from
+/// every instrumented site, so allocations and disk I/O are off-limits here.
+public protocol ScarfMonBackend: Sendable {
+    func record(_ sample: ScarfMon.Sample)
+}
+
+// MARK: - Lock
+
+/// Tiny `os_unfair_lock` wrapper. CLAUDE.md says "Use os_unfair_lock (not
+/// NSLock) for simple boolean flags accessed from multiple threads."
+@usableFromInline
+final class ScarfMonLock: @unchecked Sendable {
+    private let _lock: UnsafeMutablePointer<os_unfair_lock>
+
+    init() {
+        _lock = .allocate(capacity: 1)
+        _lock.initialize(to: os_unfair_lock())
+    }
+    deinit {
+        _lock.deinitialize(count: 1)
+        _lock.deallocate()
+    }
+    @usableFromInline func lock()   { os_unfair_lock_lock(_lock) }
+    @usableFromInline func unlock() { os_unfair_lock_unlock(_lock) }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Diagnostics/ScarfMonBoot.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+/// Boot-time wiring for ScarfMon. Both app targets call
+/// `ScarfMonBoot.configure(...)` at launch and again whenever the user
+/// flips the Diagnostics → Performance toggle.
+///
+/// Three modes:
+/// - `.off` — nothing is recorded. Hot path is one branch + return.
+/// - `.signpostOnly` — Instruments-only. Default in the open-source build.
+///   Free outside an Instruments session.
+/// - `.full` — signpost + ring buffer + os.Logger debug stream. Drives the
+///   in-app panel and the "Copy as JSON" button. Opt-in.
+public enum ScarfMonBoot {
+    public enum Mode: String, Sendable, CaseIterable {
+        case off
+        case signpostOnly
+        case full
+    }
+
+    /// User-defaults key for the persisted toggle. Same key on iOS + Mac
+    /// so `defaults read com.scarf.app ScarfMonMode` works on either.
+    public static let userDefaultsKey = "ScarfMonMode"
+
+    /// Read the persisted mode, defaulting to `.signpostOnly` so users
+    /// always get Instruments-visible signposts unless they explicitly
+    /// turn them off.
+    public static func currentMode(_ defaults: UserDefaults = .standard) -> Mode {
+        if let raw = defaults.string(forKey: userDefaultsKey),
+           let mode = Mode(rawValue: raw) {
+            return mode
+        }
+        return .signpostOnly
+    }
+
+    /// Persist a new mode and reinstall the backend set.
+    public static func setMode(_ mode: Mode, _ defaults: UserDefaults = .standard) {
+        defaults.set(mode.rawValue, forKey: userDefaultsKey)
+        configure(mode: mode)
+    }
+
+    /// Install the backend set for a given mode. Returns the active ring
+    /// buffer (if any) so the in-app Diagnostics panel can read from it.
+    @discardableResult
+    public static func configure(mode: Mode) -> ScarfMonRingBuffer? {
+        switch mode {
+        case .off:
+            ScarfMon.install([])
+            sharedRingBuffer = nil
+            return nil
+        case .signpostOnly:
+            ScarfMon.install([ScarfMonSignpostBackend()])
+            sharedRingBuffer = nil
+            return nil
+        case .full:
+            let ring = ScarfMonRingBuffer()
+            sharedRingBuffer = ring
+            ScarfMon.install([
+                ScarfMonSignpostBackend(),
+                ring,
+                ScarfMonLoggerBackend()
+            ])
+            return ring
+        }
+    }
+
+    /// Process-wide ring buffer when running in `.full` mode. Nil otherwise.
+    /// Read by the Diagnostics panel; writes happen through the backend
+    /// dispatcher so this property is read-only.
+    ///
+    /// `nonisolated(unsafe)` because the value is only mutated by
+    /// `configure(...)` (which itself runs on whichever actor invokes
+    /// the boot helper at app launch — single-writer in practice) and
+    /// read from the panel UI on the main actor. Adding a lock here
+    /// would just add overhead with no real safety win.
+    nonisolated(unsafe) public private(set) static var sharedRingBuffer: ScarfMonRingBuffer?
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Diagnostics/ScarfMonLoggerBackend.swift

@@ -0,0 +1,41 @@
+import Foundation
+#if canImport(os)
+import os
+#endif
+
+/// `os.Logger`-backed sink. Off by default — opt-in via the Diagnostics
+/// settings toggle. Writes one `.debug` line per sample at the
+/// `com.scarf.mon` subsystem, so users can stream the output via
+/// `log stream --predicate 'subsystem == "com.scarf.mon"'` without
+/// enabling private-data redaction overrides.
+///
+/// Only meaningful for users running their own debug build or with the
+/// "verbose performance logging" toggle on.
+public final class ScarfMonLoggerBackend: ScarfMonBackend, @unchecked Sendable {
+    #if canImport(os)
+    private let logger: Logger
+
+    public init(category: String = "perf") {
+        self.logger = Logger(subsystem: "com.scarf.mon", category: category)
+    }
+
+    public func record(_ sample: ScarfMon.Sample) {
+        switch sample.kind {
+        case .interval:
+            // `\(static:)` interpolation keeps the StaticString out of the
+            // private-data redaction path — names are public, durations
+            // are public, the user's content never touches this channel.
+            logger.debug(
+                "\(sample.category.rawValue, privacy: .public) \(sample.name.description, privacy: .public) ms=\(Double(sample.durationNanos) / 1_000_000.0, privacy: .public)"
+            )
+        case .event:
+            logger.debug(
+                "\(sample.category.rawValue, privacy: .public) \(sample.name.description, privacy: .public) count=\(sample.count, privacy: .public) bytes=\(sample.bytes ?? -1, privacy: .public)"
+            )
+        }
+    }
+    #else
+    public init(category: String = "perf") {}
+    public func record(_ sample: ScarfMon.Sample) { /* no-op off-Apple */ }
+    #endif
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Diagnostics/ScarfMonRingBuffer.swift

@@ -0,0 +1,176 @@
+import Foundation
+
+/// Fixed-size, lock-protected ring of recent samples. Drives the in-app
+/// Diagnostics panel and the export-as-JSON button.
+///
+/// Capacity is a compile-time choice; 4096 entries × ~80 bytes per sample =
+/// ~320 KB resident. That's enough for several minutes of streaming-chat
+/// activity at 200 samples/s without overwriting interesting context.
+///
+/// The hot path takes one `os_unfair_lock` per `record`. Aggregation (the
+/// `summary(...)` reader) builds a fresh dictionary each call — only invoked
+/// from the panel UI, which polls at a human cadence.
+public final class ScarfMonRingBuffer: ScarfMonBackend, @unchecked Sendable {
+    public let capacity: Int
+
+    private let lock = ScarfMonLock()
+    private var storage: [ScarfMon.Sample?]
+    /// Next write index. Wraps around `capacity` so the buffer never grows.
+    private var head: Int = 0
+    /// True once we've wrapped at least once — switches the read order from
+    /// `[0..<head]` to `[head..<capacity] + [0..<head]`.
+    private var didWrap: Bool = false
+
+    public init(capacity: Int = 4096) {
+        precondition(capacity > 0, "ring buffer needs a positive capacity")
+        self.capacity = capacity
+        self.storage = Array(repeating: nil, count: capacity)
+    }
+
+    public func record(_ sample: ScarfMon.Sample) {
+        lock.lock()
+        defer { lock.unlock() }
+        storage[head] = sample
+        head += 1
+        if head >= capacity {
+            head = 0
+            didWrap = true
+        }
+    }
+
+    /// Snapshot of all currently-resident samples in chronological order.
+    public func samples() -> [ScarfMon.Sample] {
+        lock.lock()
+        defer { lock.unlock() }
+        if !didWrap {
+            return storage[0..<head].compactMap { $0 }
+        }
+        let tail = storage[head..<capacity].compactMap { $0 }
+        let leading = storage[0..<head].compactMap { $0 }
+        return tail + leading
+    }
+
+    /// Wipe the buffer. Used by the "Reset" button in the Diagnostics
+    /// panel and at the top of every test case.
+    public func reset() {
+        lock.lock()
+        defer { lock.unlock() }
+        for i in 0..<capacity { storage[i] = nil }
+        head = 0
+        didWrap = false
+    }
+
+    /// Aggregated stats over the current buffer. Buckets by
+    /// `(category, name)`; computes count, total nanos, mean, p50, p95.
+    public func summary() -> [ScarfMonStat] {
+        let snapshot = samples()
+        var buckets: [BucketKey: [UInt64]] = [:]
+        var counts: [BucketKey: Int] = [:]
+        var byteTotals: [BucketKey: Int] = [:]
+        var kinds: [BucketKey: ScarfMon.Sample.Kind] = [:]
+
+        for sample in snapshot {
+            let key = BucketKey(category: sample.category, name: sample.name.description)
+            kinds[key] = sample.kind
+            counts[key, default: 0] += sample.count
+            if let b = sample.bytes { byteTotals[key, default: 0] += b }
+            if sample.kind == .interval {
+                buckets[key, default: []].append(sample.durationNanos)
+            }
+        }
+
+        var stats: [ScarfMonStat] = []
+        for (key, _) in counts {
+            let durations = buckets[key] ?? []
+            let kind = kinds[key] ?? .event
+            stats.append(ScarfMonStat(
+                category: key.category,
+                name: key.name,
+                kind: kind,
+                count: counts[key] ?? 0,
+                totalNanos: durations.reduce(0, &+),
+                p50Nanos: percentile(durations, 0.50),
+                p95Nanos: percentile(durations, 0.95),
+                maxNanos: durations.max() ?? 0,
+                totalBytes: byteTotals[key] ?? 0
+            ))
+        }
+        stats.sort { $0.p95Nanos > $1.p95Nanos }
+        return stats
+    }
+
+    private struct BucketKey: Hashable {
+        let category: ScarfMon.Category
+        let name: String
+    }
+
+    private func percentile(_ values: [UInt64], _ p: Double) -> UInt64 {
+        guard !values.isEmpty else { return 0 }
+        let sorted = values.sorted()
+        // Nearest-rank percentile — good enough for triage and avoids
+        // interpolation edge cases on tiny samples.
+        let rank = max(1, min(sorted.count, Int((p * Double(sorted.count)).rounded(.up))))
+        return sorted[rank - 1]
+    }
+}
+
+/// Per-bucket stats surfaced to the in-app panel.
+public struct ScarfMonStat: Sendable, Hashable, Codable {
+    public let category: ScarfMon.Category
+    public let name: String
+    public let kind: ScarfMon.Sample.Kind
+    public let count: Int
+    public let totalNanos: UInt64
+    public let p50Nanos: UInt64
+    public let p95Nanos: UInt64
+    public let maxNanos: UInt64
+    public let totalBytes: Int
+
+    public var totalMs: Double { Double(totalNanos) / 1_000_000.0 }
+    public var p50Ms: Double { Double(p50Nanos) / 1_000_000.0 }
+    public var p95Ms: Double { Double(p95Nanos) / 1_000_000.0 }
+    public var maxMs: Double { Double(maxNanos) / 1_000_000.0 }
+}
+
+// MARK: - JSON export
+
+extension ScarfMonRingBuffer {
+    /// Compact JSON dump for the "Copy as JSON" button. One line per sample
+    /// keeps the output greppable when the user pastes it into a feedback
+    /// thread.
+    public func exportJSON() -> String {
+        struct Wire: Codable {
+            let category: String
+            let name: String
+            let kind: String
+            let timestampMs: Double
+            let durationNanos: UInt64
+            let count: Int
+            let bytes: Int?
+        }
+        let snapshot = samples()
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys]
+        var lines: [String] = []
+        lines.reserveCapacity(snapshot.count + 1)
+        lines.append("[")
+        for (i, s) in snapshot.enumerated() {
+            let wire = Wire(
+                category: s.category.rawValue,
+                name: s.name.description,
+                kind: s.kind.rawValue,
+                timestampMs: s.timestamp.timeIntervalSince1970 * 1000,
+                durationNanos: s.durationNanos,
+                count: s.count,
+                bytes: s.bytes
+            )
+            if let data = try? encoder.encode(wire),
+               let line = String(data: data, encoding: .utf8) {
+                let suffix = i == snapshot.count - 1 ? "" : ","
+                lines.append("  " + line + suffix)
+            }
+        }
+        lines.append("]")
+        return lines.joined(separator: "\n")
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Diagnostics/ScarfMonSignpostBackend.swift

@@ -0,0 +1,54 @@
+import Foundation
+#if canImport(os)
+import os
+import os.signpost
+#endif
+
+/// Always-on signpost backend. Emits an `os_signpost` event per sample so
+/// users can attach Instruments and see Scarf's instrumentation in the
+/// Points of Interest track without a debug build.
+///
+/// `os_signpost` is elided by the runtime when no Instruments session is
+/// recording the relevant subsystem — the backend pays the cost of one
+/// `OSLog` lookup per emit and nothing else.
+public final class ScarfMonSignpostBackend: ScarfMonBackend, @unchecked Sendable {
+    #if canImport(os)
+    private let log: OSLog
+
+    public init(subsystem: String = "com.scarf.mon") {
+        self.log = OSLog(subsystem: subsystem, category: .pointsOfInterest)
+    }
+
+    public func record(_ sample: ScarfMon.Sample) {
+        // Signposts want a `StaticString` name — we already require
+        // exactly that on the API. Format string is also static; the
+        // dynamic values flow as printf-style args, so no allocations
+        // for the event name itself.
+        switch sample.kind {
+        case .interval:
+            os_signpost(
+                .event,
+                log: log,
+                name: sample.name,
+                "category=%{public}@ ms=%{public}.3f count=%d",
+                sample.category.rawValue,
+                Double(sample.durationNanos) / 1_000_000.0,
+                sample.count
+            )
+        case .event:
+            os_signpost(
+                .event,
+                log: log,
+                name: sample.name,
+                "category=%{public}@ count=%d bytes=%d",
+                sample.category.rawValue,
+                sample.count,
+                sample.bytes ?? -1
+            )
+        }
+    }
+    #else
+    public init(subsystem: String = "com.scarf.mon") {}
+    public func record(_ sample: ScarfMon.Sample) { /* no-op off-Apple */ }
+    #endif
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/BackupManifest.swift

@@ -0,0 +1,183 @@
+import Foundation
+
+/// Top-level manifest for a `.scarfbackup` archive.
+///
+/// **Archive layout** (`.scarfbackup` is a plain ZIP):
+/// ```
+/// <name>.scarfbackup
+/// ├── manifest.json           — this struct, JSON-encoded
+/// ├── hermes.tar.gz            — gzipped tar of `~/.hermes/` (minus exclusions)
+/// └── projects/
+///     ├── <project-id>.tar.gz — one inner tarball per registered project
+///     └── ...
+/// ```
+///
+/// **Why two layers (outer ZIP + inner tarballs).** The inner tarballs are
+/// produced by streaming `tar -czf - …` over SSH — that's the only way to
+/// keep memory bounded for multi-GB hermes homes. The outer ZIP exists so
+/// the manifest sits at a fixed, easy-to-inspect location and so users on
+/// macOS can double-click in Finder and see the structure. ZIP also has a
+/// central directory at the end, which makes "validate without extracting"
+/// cheap.
+///
+/// **What rides along.** Hermes home (state.db + sessions + skills + cron +
+/// memories + scarf sidecars + plugins/profiles), each project's full file
+/// tree (the user's code), and the manifest itself. **What does NOT ride
+/// along by default**: `auth.json` (provider credentials), `mcp-tokens/`
+/// (per-host OAuth bearer tokens), `logs/` (size, low restore value),
+/// `state.db-wal` / `state.db-shm` (in-flight WAL siblings — we checkpoint
+/// before the archive). The `options` block records exactly which
+/// exclusions were applied so the restore flow can warn the user.
+public struct BackupManifest: Codable, Sendable, Equatable {
+    /// Bumped when the on-disk shape changes incompatibly. v1 is the only
+    /// shape today; restores refuse anything they don't recognize.
+    public var schemaVersion: Int
+    /// Magic string. Lets a future Scarf reject `.zip` files that aren't
+    /// our backups before unpacking them as if they were.
+    public var kind: String
+    /// ISO-8601 UTC timestamp the archive was produced.
+    public var createdAt: String
+    /// Identifies the server the backup came from. The display name is for
+    /// the restore preview sheet; serverID is for de-dupe and lineage.
+    public var source: Source
+    /// Hermes home tree metadata. Always present (even an empty Hermes
+    /// install ships an empty tarball — the restore replaces nothing
+    /// rather than refusing).
+    public var hermes: HermesTree
+    /// One entry per registered project at backup time. Empty array
+    /// when the user never registered any projects.
+    public var projects: [ProjectEntry]
+    /// What was included / excluded from the Hermes tree. Flagged so the
+    /// restore preview honestly reports "auth.json was not in this
+    /// backup — you'll re-authenticate after restore".
+    public var options: Options
+
+    public init(
+        schemaVersion: Int = BackupManifest.currentSchemaVersion,
+        kind: String = BackupManifest.kindMagic,
+        createdAt: String,
+        source: Source,
+        hermes: HermesTree,
+        projects: [ProjectEntry],
+        options: Options
+    ) {
+        self.schemaVersion = schemaVersion
+        self.kind = kind
+        self.createdAt = createdAt
+        self.source = source
+        self.hermes = hermes
+        self.projects = projects
+        self.options = options
+    }
+
+    public static let currentSchemaVersion = 1
+    public static let kindMagic = "scarf-server-backup"
+
+    public struct Source: Codable, Sendable, Equatable {
+        public var serverID: String
+        public var displayName: String
+        public var host: String
+        public var user: String?
+        /// Output of `hermes --version` on the source host at backup
+        /// time. Restore warns if the target installs an older version
+        /// (state.db schema differences could break things silently).
+        public var hermesVersion: String?
+
+        public init(serverID: String, displayName: String, host: String, user: String?, hermesVersion: String?) {
+            self.serverID = serverID
+            self.displayName = displayName
+            self.host = host
+            self.user = user
+            self.hermesVersion = hermesVersion
+        }
+    }
+
+    public struct HermesTree: Codable, Sendable, Equatable {
+        /// Absolute path of `~/.hermes/` on the source host (e.g.
+        /// `/root/.hermes` or `/home/alan/.hermes`). Used by restore to
+        /// detect path drift when targeting a different user account.
+        public var homePath: String
+        /// Path inside the outer ZIP (always `hermes.tar.gz`).
+        public var tarballPath: String
+        /// Compressed bytes — for the preview sheet's size summary.
+        public var tarballSize: Int64
+        /// Hex SHA-256 of the inner tarball. Restore verifies before
+        /// extracting; corruption surfaces as a single bad path
+        /// rather than a half-extracted home.
+        public var tarballSHA256: String
+
+        public init(homePath: String, tarballPath: String, tarballSize: Int64, tarballSHA256: String) {
+            self.homePath = homePath
+            self.tarballPath = tarballPath
+            self.tarballSize = tarballSize
+            self.tarballSHA256 = tarballSHA256
+        }
+    }
+
+    public struct ProjectEntry: Codable, Sendable, Equatable {
+        /// Stable UUID for the project. Used to namespace the inner
+        /// tarball so a project with `name = "scratch"` in two
+        /// different directories doesn't collide.
+        public var id: String
+        public var name: String
+        /// Absolute path on the source host. Restore re-anchors this if
+        /// the target has a different home (e.g. backup from `/root`,
+        /// restore to `/home/ubuntu`).
+        public var path: String
+        /// Path inside the outer ZIP (e.g. `projects/<id>.tar.gz`).
+        public var tarballPath: String
+        public var tarballSize: Int64
+        public var tarballSHA256: String
+
+        public init(id: String, name: String, path: String, tarballPath: String, tarballSize: Int64, tarballSHA256: String) {
+            self.id = id
+            self.name = name
+            self.path = path
+            self.tarballPath = tarballPath
+            self.tarballSize = tarballSize
+            self.tarballSHA256 = tarballSHA256
+        }
+    }
+
+    public struct Options: Codable, Sendable, Equatable {
+        public var includeAuth: Bool
+        public var includeMcpTokens: Bool
+        public var includeLogs: Bool
+        /// True if `sqlite3 PRAGMA wal_checkpoint(TRUNCATE)` was run on
+        /// the remote before tarballing the Hermes home. False means the
+        /// archive may contain a `state.db` mid-write — usually fine
+        /// (SQLite tolerates restarted reads from a quiesced DB) but
+        /// flagged for forensics.
+        public var checkpointedWAL: Bool
+
+        public init(includeAuth: Bool, includeMcpTokens: Bool, includeLogs: Bool, checkpointedWAL: Bool) {
+            self.includeAuth = includeAuth
+            self.includeMcpTokens = includeMcpTokens
+            self.includeLogs = includeLogs
+            self.checkpointedWAL = checkpointedWAL
+        }
+
+        public static let safeDefault = Options(
+            includeAuth: false,
+            includeMcpTokens: false,
+            includeLogs: false,
+            checkpointedWAL: true
+        )
+    }
+}
+
+/// Canonical layout strings — referenced by both the producer and the
+/// consumer so the on-disk paths stay in sync.
+public enum BackupArchiveLayout {
+    public static let manifestPath = "manifest.json"
+    public static let hermesTarballPath = "hermes.tar.gz"
+    public static let projectsTarballPrefix = "projects/"
+    public static let archiveExtension = "scarfbackup"
+
+    /// Returns `projects/<id>.tar.gz`. The id is the `ProjectEntry.id`
+    /// (stable UUID), not the project name — names are renamed all the
+    /// time and would collide.
+    public static func projectTarballPath(for id: String) -> String {
+        projectsTarballPrefix + id + ".tar.gz"
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ChatImageAttachment.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+/// One image attached to an outgoing chat prompt.
+///
+/// Hermes v0.12 ACP advertises `prompt_capabilities.image = true` and
+/// accepts content-block arrays in `session/prompt`. Scarf produces these
+/// blocks from drag-dropped / pasted / picker-selected images. We
+/// downsample + JPEG-encode at the producer side so the wire payload
+/// stays under a few hundred kilobytes per image even when the user
+/// drops a 12 MP screenshot.
+///
+/// Constructed via `ImageEncoder.encode(...)`. The store-the-bytes-once
+/// shape means `RichChatViewModel` can keep the array between turns
+/// (e.g. while the agent is responding) without holding `NSImage` /
+/// `UIImage` references that would pin the originals in memory.
+public struct ChatImageAttachment: Sendable, Equatable, Identifiable {
+    public let id: String
+    /// IANA MIME type — matches the `mimeType` field on ACP `ImageContentBlock`.
+    /// Currently always `image/jpeg` after re-encoding; PNG-only originals
+    /// keep their type when small enough to skip the JPEG step.
+    public let mimeType: String
+    /// Base64-encoded payload. NOT prefixed with `data:` — Hermes wraps it
+    /// when forwarding to OpenAI multimodal payloads (see
+    /// `_image_block_to_openai_part` in `acp_adapter/server.py`).
+    public let base64Data: String
+    /// Small inline thumbnail for the composer's preview strip. Same MIME
+    /// type as `base64Data`. Nil when the source was already small enough
+    /// to use directly.
+    public let thumbnailBase64: String?
+    /// Original filename, when known (drag-drop carries it; paste doesn't).
+    /// Surfaced as a tooltip on the preview chip.
+    public let filename: String?
+    /// Approximate decoded byte count, kept for the composer's
+    /// "X images, Y KB" status pill.
+    public let approximateByteCount: Int
+
+    public init(
+        id: String = UUID().uuidString,
+        mimeType: String,
+        base64Data: String,
+        thumbnailBase64: String?,
+        filename: String?,
+        approximateByteCount: Int
+    ) {
+        self.id = id
+        self.mimeType = mimeType
+        self.base64Data = base64Data
+        self.thumbnailBase64 = thumbnailBase64
+        self.filename = filename
+        self.approximateByteCount = approximateByteCount
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesConfig.swift

@@ -258,7 +258,16 @@ public struct VoiceSettings: Sendable, Equatable {
     )
 }
 
-/// Eight sub-models that share the same provider/model/base_url/api_key/timeout shape.
+/// Per-task auxiliary model overrides.
+///
+/// `flush_memories` was removed in Hermes v0.12 but remains alive on
+/// pre-v0.12 hosts — the field is preserved here so the YAML parser
+/// can round-trip it and `AuxiliaryTab` can render the row when
+/// `HermesCapabilities.hasFlushMemoriesAux` is set. On v0.12+ the
+/// field stays empty and is never surfaced.
+/// `curator` was added in v0.12 — Curator's review fork uses its own
+/// model so users can keep main-model spend separate from background
+/// maintenance.
 public struct AuxiliarySettings: Sendable, Equatable {
     public var vision: AuxiliaryModel
     public var webExtract: AuxiliaryModel
@@ -267,7 +276,10 @@ public struct AuxiliarySettings: Sendable, Equatable {
     public var skillsHub: AuxiliaryModel
     public var approval: AuxiliaryModel
     public var mcp: AuxiliaryModel
+    /// pre-v0.12 only; on v0.12+ this stays `.empty` and the row is hidden.
     public var flushMemories: AuxiliaryModel
+    /// v0.12+; pre-v0.12 Hermes installs ignore this slot.
+    public var curator: AuxiliaryModel
 
 
     public init(
@@ -278,7 +290,8 @@ public struct AuxiliarySettings: Sendable, Equatable {
         skillsHub: AuxiliaryModel,
         approval: AuxiliaryModel,
         mcp: AuxiliaryModel,
-        flushMemories: AuxiliaryModel
+        flushMemories: AuxiliaryModel,
+        curator: AuxiliaryModel
     ) {
         self.vision = vision
         self.webExtract = webExtract
@@ -288,6 +301,7 @@ public struct AuxiliarySettings: Sendable, Equatable {
         self.approval = approval
         self.mcp = mcp
         self.flushMemories = flushMemories
+        self.curator = curator
     }
     public nonisolated static let empty = AuxiliarySettings(
         vision: .empty,
@@ -297,7 +311,8 @@ public struct AuxiliarySettings: Sendable, Equatable {
         skillsHub: .empty,
         approval: .empty,
         mcp: .empty,
-        flushMemories: .empty
+        flushMemories: .empty,
+        curator: .empty
     )
 }
 
@@ -634,6 +649,24 @@ public struct HermesConfig: Sendable {
     /// platform. Scarf reads for display; edits go through Hermes CLI.
     public var platformToolsets: [String: [String]]
 
+    // -- Hermes v0.12 additions ----------------------------------------
+    // Defaults match the Hermes v0.12 defaults so that an absent key in
+    // config.yaml looks identical to a freshly-installed v0.12 host.
+
+    /// `prompt_caching.cache_ttl` — `"5m"` (default) or `"1h"`. Hermes
+    /// v0.12 added the 1-hour ceiling for users with prompt-cache-heavy
+    /// workloads (long agent loops with stable system prompts).
+    public var cacheTTL: String
+    /// `redaction.enabled` — flipped from `true` to `false` as the
+    /// upstream default in v0.12 because the substitution corrupted
+    /// patches and API payloads. Surface a toggle so users with hard
+    /// redaction requirements can opt back in.
+    public var redactionEnabled: Bool
+    /// `agent.runtime_metadata_footer` — opt-in compact footer on each
+    /// final reply (provider/model/cost/turn count). Off by default;
+    /// useful for cost auditing and screen-recording demos.
+    public var runtimeMetadataFooter: Bool
+
     // Grouped blocks
     public var display: DisplaySettings
     public var terminal: TerminalSettings
@@ -711,8 +744,14 @@ public struct HermesConfig: Sendable {
         matrix: MatrixSettings,
         mattermost: MattermostSettings,
         whatsapp: WhatsAppSettings,
-        homeAssistant: HomeAssistantSettings
+        homeAssistant: HomeAssistantSettings,
+        cacheTTL: String = "5m",
+        redactionEnabled: Bool = false,
+        runtimeMetadataFooter: Bool = false
     ) {
+        self.cacheTTL = cacheTTL
+        self.redactionEnabled = redactionEnabled
+        self.runtimeMetadataFooter = runtimeMetadataFooter
         self.model = model
         self.provider = provider
         self.maxTurns = maxTurns

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesConstants.swift

@@ -27,6 +27,39 @@ public enum QueryDefaults: Sendable {
     public nonisolated static let defaultSilenceThreshold = 200
 }
 
+/// Page sizes for `HermesDataService.fetchMessages(sessionId:limit:before:)`.
+/// Centralized so iOS, Mac, and the polling code paths can pick a
+/// consistent budget — and so we have one knob to retune if perf
+/// concerns shift.
+public enum HistoryPageSize: Sendable {
+    /// Initial chat-history load. **Sized to fit the SSH wire payload
+    /// inside a 30-second `RemoteSQLiteBackend.queryTimeout`.** A
+    /// 157-message session at 200-row page size produced enough
+    /// JSON (with `reasoning_content` for thinking models) to time
+    /// out at exactly 30 s on a 420 ms-RTT remote. Dropped to 50,
+    /// then to 25 in v2.7 after a 160-message session still timed
+    /// out at 50 — `reasoning_content` for thinking-model turns can
+    /// run 20+ KB per row, so 50 rows × 30 KB = 1.5 MB JSON which
+    /// over a slow SSH channel still trips the 30s budget. Pair
+    /// with `messageColumnsLight` (excludes `reasoning_content`)
+    /// so the on-wire payload is small even at this size; the
+    /// inspector pane lazy-loads via `fetchReasoningContent(for:)`
+    /// when the user expands a disclosure. The "Load earlier"
+    /// affordance pages back through older messages on demand.
+    public nonisolated static let initial = 25
+    /// Reconnection reconcile against the DB. 200 rows is plenty —
+    /// disconnects don't generate hundreds of unseen messages.
+    public nonisolated static let reconcile = 200
+    /// Mac sessions detail view. Larger to reduce paging UX in the
+    /// desktop browser-style read; the desktop has the screen real
+    /// estate and memory headroom for it.
+    public nonisolated static let macSessionDetail = 500
+    /// Terminal-mode polling refresh. Same 500-row budget as Mac
+    /// detail; covers sessions long enough that the user is actively
+    /// scrolling but bounded to keep each poll tick cheap.
+    public nonisolated static let polling = 500
+}
+
 // MARK: - File Size Formatting
 
 public enum FileSizeUnit: Sendable {

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesCronJob.swift

@@ -19,6 +19,15 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
     public nonisolated let timeoutType: String?
     public nonisolated let timeoutSeconds: Int?
     public nonisolated let silent: Bool?
+    /// Hermes v0.12+ — the directory the job runs from. Hermes injects
+    /// AGENTS.md / CLAUDE.md / .cursorrules from this dir and uses it
+    /// as cwd for terminal/file/code_exec tools. `nil` preserves the
+    /// pre-v0.12 behaviour (no project context files).
+    public nonisolated let workdir: String?
+    /// Hermes v0.12+ — chain another cron job's last output into this
+    /// job's prompt. YAML-only field today (no `--context-from` CLI
+    /// flag yet) — Scarf displays it but doesn't write it.
+    public nonisolated let contextFrom: [String]?
 
     public enum CodingKeys: String, CodingKey {
         case id, name, prompt, skills, model, schedule, enabled, state, deliver, silent
@@ -30,6 +39,8 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
         case lastDeliveryError = "last_delivery_error"
         case timeoutType = "timeout_type"
         case timeoutSeconds = "timeout_seconds"
+        case workdir
+        case contextFrom = "context_from"
     }
 
     /// Memberwise init. Swift doesn't synthesize one for us because
@@ -53,7 +64,9 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
         lastDeliveryError: String? = nil,
         timeoutType: String? = nil,
         timeoutSeconds: Int? = nil,
-        silent: Bool? = nil
+        silent: Bool? = nil,
+        workdir: String? = nil,
+        contextFrom: [String]? = nil
     ) {
         self.id = id
         self.name = name
@@ -73,6 +86,8 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
         self.timeoutType = timeoutType
         self.timeoutSeconds = timeoutSeconds
         self.silent = silent
+        self.workdir = workdir
+        self.contextFrom = contextFrom
     }
 
     public nonisolated init(from decoder: any Decoder) throws {
@@ -95,6 +110,8 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
         self.timeoutType       = try c.decodeIfPresent(String.self, forKey: .timeoutType)
         self.timeoutSeconds    = try c.decodeIfPresent(Int.self, forKey: .timeoutSeconds)
         self.silent            = try c.decodeIfPresent(Bool.self, forKey: .silent)
+        self.workdir           = try c.decodeIfPresent(String.self, forKey: .workdir)
+        self.contextFrom       = try c.decodeIfPresent([String].self, forKey: .contextFrom)
     }
 
     public nonisolated func encode(to encoder: any Encoder) throws {
@@ -117,6 +134,8 @@ public struct HermesCronJob: Identifiable, Sendable, Codable {
         try c.encodeIfPresent(timeoutType, forKey: .timeoutType)
         try c.encodeIfPresent(timeoutSeconds, forKey: .timeoutSeconds)
         try c.encodeIfPresent(silent, forKey: .silent)
+        try c.encodeIfPresent(workdir, forKey: .workdir)
+        try c.encodeIfPresent(contextFrom, forKey: .contextFrom)
     }
 
     public nonisolated var stateIcon: String {

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesCuratorReport.swift

@@ -0,0 +1,361 @@
+import Foundation
+
+/// Parsed view of `hermes curator status` text + the on-disk
+/// `~/.hermes/skills/.curator_state` JSON.
+///
+/// Hermes v0.12 doesn't ship a `--json` flag for `curator status` — the
+/// CLI writes a human-readable report. CuratorViewModel parses the text
+/// output for the human-readable bits ("least recently active", "most
+/// active") and reads the state file directly for last-run metadata.
+public struct HermesCuratorStatus: Sendable, Equatable {
+    public enum RunState: String, Sendable, Equatable {
+        case enabled
+        case paused
+        case disabled
+        case unknown
+    }
+
+    public let state: RunState
+    public let runCount: Int
+    public let lastRunISO: String?         // raw timestamp string, parsed by callers
+    public let lastSummary: String?        // free-text summary line
+    public let lastReportPath: String?     // absolute path to <YYYYMMDD-HHMMSS>/ dir
+    public let intervalLabel: String       // e.g. "every 7d"
+    public let staleAfterLabel: String     // e.g. "30d unused"
+    public let archiveAfterLabel: String   // e.g. "90d unused"
+
+    public let totalSkills: Int
+    public let activeSkills: Int
+    public let staleSkills: Int
+    public let archivedSkills: Int
+
+    public let pinnedNames: [String]
+
+    /// Top-5 lists rendered in the curator output. Each row carries the
+    /// skill name + the four counters Hermes prints.
+    public let leastRecentlyActive: [HermesCuratorSkillRow]
+    public let mostActive: [HermesCuratorSkillRow]
+    public let leastActive: [HermesCuratorSkillRow]
+
+    public init(
+        state: RunState,
+        runCount: Int,
+        lastRunISO: String?,
+        lastSummary: String?,
+        lastReportPath: String?,
+        intervalLabel: String,
+        staleAfterLabel: String,
+        archiveAfterLabel: String,
+        totalSkills: Int,
+        activeSkills: Int,
+        staleSkills: Int,
+        archivedSkills: Int,
+        pinnedNames: [String],
+        leastRecentlyActive: [HermesCuratorSkillRow],
+        mostActive: [HermesCuratorSkillRow],
+        leastActive: [HermesCuratorSkillRow]
+    ) {
+        self.state = state
+        self.runCount = runCount
+        self.lastRunISO = lastRunISO
+        self.lastSummary = lastSummary
+        self.lastReportPath = lastReportPath
+        self.intervalLabel = intervalLabel
+        self.staleAfterLabel = staleAfterLabel
+        self.archiveAfterLabel = archiveAfterLabel
+        self.totalSkills = totalSkills
+        self.activeSkills = activeSkills
+        self.staleSkills = staleSkills
+        self.archivedSkills = archivedSkills
+        self.pinnedNames = pinnedNames
+        self.leastRecentlyActive = leastRecentlyActive
+        self.mostActive = mostActive
+        self.leastActive = leastActive
+    }
+
+    public static let empty = HermesCuratorStatus(
+        state: .unknown,
+        runCount: 0,
+        lastRunISO: nil,
+        lastSummary: nil,
+        lastReportPath: nil,
+        intervalLabel: "—",
+        staleAfterLabel: "—",
+        archiveAfterLabel: "—",
+        totalSkills: 0,
+        activeSkills: 0,
+        staleSkills: 0,
+        archivedSkills: 0,
+        pinnedNames: [],
+        leastRecentlyActive: [],
+        mostActive: [],
+        leastActive: []
+    )
+}
+
+public struct HermesCuratorSkillRow: Sendable, Equatable, Identifiable {
+    public var id: String { name }
+    public let name: String
+    public let activityCount: Int
+    public let useCount: Int
+    public let viewCount: Int
+    public let patchCount: Int
+    public let lastActivityLabel: String   // raw label as printed (e.g. "never", "2d ago")
+
+    public init(
+        name: String,
+        activityCount: Int,
+        useCount: Int,
+        viewCount: Int,
+        patchCount: Int,
+        lastActivityLabel: String
+    ) {
+        self.name = name
+        self.activityCount = activityCount
+        self.useCount = useCount
+        self.viewCount = viewCount
+        self.patchCount = patchCount
+        self.lastActivityLabel = lastActivityLabel
+    }
+}
+
+/// Pure parser for `hermes curator status` stdout. Public for tests.
+///
+/// Format is stable enough to text-parse; we never error on missing
+/// sections — we just leave the corresponding field empty so
+/// CuratorView can render "—" without crashing on a future layout
+/// tweak. State file overrides text-parsed values when both are present.
+public enum HermesCuratorStatusParser {
+    public static func parse(text: String, stateFileJSON: Data? = nil) -> HermesCuratorStatus {
+        let lines = text.components(separatedBy: "\n")
+        var status = HermesCuratorStatus.empty
+
+        // Header section: `curator: ENABLED` / `runs:` / `last run:` /
+        // `last summary:` / `interval:` / `stale after:` / `archive after:`
+        var state = HermesCuratorStatus.RunState.unknown
+        var runCount = 0
+        var lastRunISO: String?
+        var lastSummary: String?
+        var lastReportPath: String?
+        var interval = "—"
+        var stale = "—"
+        var archive = "—"
+
+        // Skill counts: `agent-created skills: N total` then
+        // `  active     N` / `  stale      N` / `  archived   N`
+        var total = 0
+        var active = 0
+        var staleCount = 0
+        var archived = 0
+
+        var pinned: [String] = []
+
+        // Lists: `least recently active (top 5):` / `most active (top 5):` /
+        // `least active (top 5):` followed by indented row lines.
+        enum Section {
+            case header
+            case leastRecent
+            case mostActive
+            case leastActive
+        }
+        var section = Section.header
+        var leastRecent: [HermesCuratorSkillRow] = []
+        var mostActiveRows: [HermesCuratorSkillRow] = []
+        var leastActiveRows: [HermesCuratorSkillRow] = []
+
+        for raw in lines {
+            let line = raw.trimmingCharacters(in: .whitespaces)
+            // Section markers
+            if line.hasPrefix("least recently active") {
+                section = .leastRecent
+                continue
+            }
+            if line.hasPrefix("most active") {
+                section = .mostActive
+                continue
+            }
+            if line.hasPrefix("least active") {
+                section = .leastActive
+                continue
+            }
+
+            // Header section single-line keys
+            if line.hasPrefix("curator:") {
+                let val = String(line.dropFirst("curator:".count)).trimmingCharacters(in: .whitespaces).uppercased()
+                switch val {
+                case "ENABLED": state = .enabled
+                case "PAUSED": state = .paused
+                case "DISABLED": state = .disabled
+                default: state = .unknown
+                }
+                continue
+            }
+            if line.hasPrefix("runs:") {
+                runCount = Int(line.dropFirst("runs:".count).trimmingCharacters(in: .whitespaces)) ?? 0
+                continue
+            }
+            if line.hasPrefix("last run:") {
+                let val = String(line.dropFirst("last run:".count)).trimmingCharacters(in: .whitespaces)
+                lastRunISO = val == "never" ? nil : val
+                continue
+            }
+            if line.hasPrefix("last summary:") {
+                let val = String(line.dropFirst("last summary:".count)).trimmingCharacters(in: .whitespaces)
+                lastSummary = (val == "(none)" || val.isEmpty) ? nil : val
+                continue
+            }
+            if line.hasPrefix("last report:") {
+                let val = String(line.dropFirst("last report:".count)).trimmingCharacters(in: .whitespaces)
+                lastReportPath = val.isEmpty ? nil : val
+                continue
+            }
+            if line.hasPrefix("interval:") {
+                interval = String(line.dropFirst("interval:".count)).trimmingCharacters(in: .whitespaces)
+                continue
+            }
+            if line.hasPrefix("stale after:") {
+                stale = String(line.dropFirst("stale after:".count)).trimmingCharacters(in: .whitespaces)
+                continue
+            }
+            if line.hasPrefix("archive after:") {
+                archive = String(line.dropFirst("archive after:".count)).trimmingCharacters(in: .whitespaces)
+                continue
+            }
+
+            // `agent-created skills: 18 total`
+            if line.hasPrefix("agent-created skills:") {
+                let after = line.dropFirst("agent-created skills:".count).trimmingCharacters(in: .whitespaces)
+                if let n = Int(after.split(separator: " ").first ?? "") {
+                    total = n
+                }
+                section = .header
+                continue
+            }
+            // Counts: "active     18" / "stale      0" / "archived   0"
+            if let row = parseStateCountRow(line) {
+                switch row.state {
+                case "active":   active = row.count
+                case "stale":    staleCount = row.count
+                case "archived": archived = row.count
+                default: break
+                }
+                continue
+            }
+            // pinned (3): foo, bar, baz
+            if line.hasPrefix("pinned (") {
+                if let colon = line.firstIndex(of: ":") {
+                    let names = line[line.index(after: colon)...]
+                        .split(separator: ",")
+                        .map { $0.trimmingCharacters(in: .whitespaces) }
+                        .filter { !$0.isEmpty }
+                    pinned = names
+                }
+                continue
+            }
+
+            // Skill rows like:
+            //   <name>  activity= N  use= N  view= N  patches= N  last_activity=<label>
+            if section != .header, let parsed = parseSkillRow(line) {
+                switch section {
+                case .leastRecent:  leastRecent.append(parsed)
+                case .mostActive:   mostActiveRows.append(parsed)
+                case .leastActive:  leastActiveRows.append(parsed)
+                case .header:       break
+                }
+            }
+        }
+
+        // Apply state-file overrides if present. The .curator_state JSON
+        // is authoritative for last_run_at / last_run_summary /
+        // last_report_path because those carry timestamps the text
+        // output rounds.
+        if let json = stateFileJSON,
+           let obj = try? JSONSerialization.jsonObject(with: json) as? [String: Any] {
+            if obj["paused"] as? Bool == true { state = .paused }
+            if let count = obj["run_count"] as? Int { runCount = count }
+            if let lr = obj["last_run_at"] as? String { lastRunISO = lr }
+            if let summary = obj["last_run_summary"] as? String, !summary.isEmpty { lastSummary = summary }
+            if let path = obj["last_report_path"] as? String, !path.isEmpty { lastReportPath = path }
+        }
+
+        status = HermesCuratorStatus(
+            state: state,
+            runCount: runCount,
+            lastRunISO: lastRunISO,
+            lastSummary: lastSummary,
+            lastReportPath: lastReportPath,
+            intervalLabel: interval,
+            staleAfterLabel: stale,
+            archiveAfterLabel: archive,
+            totalSkills: total,
+            activeSkills: active,
+            staleSkills: staleCount,
+            archivedSkills: archived,
+            pinnedNames: pinned,
+            leastRecentlyActive: leastRecent,
+            mostActive: mostActiveRows,
+            leastActive: leastActiveRows
+        )
+        return status
+    }
+
+    /// `active     18` style row inside the skill-count block.
+    private static func parseStateCountRow(_ line: String) -> (state: String, count: Int)? {
+        let parts = line.split(whereSeparator: { $0 == " " || $0 == "\t" }).map(String.init)
+        guard parts.count >= 2,
+              ["active", "stale", "archived"].contains(parts[0]),
+              let count = Int(parts[1])
+        else { return nil }
+        return (parts[0], count)
+    }
+
+    /// Skill-list row parser. Tolerates Hermes's whitespace-padded
+    /// layout — `activity=  0` has two spaces between `=` and the
+    /// number, so we can't split-on-space-then-split-on-`=`. Instead
+    /// we slide a key-detection cursor across the row and grab the
+    /// next non-whitespace token after each known key.
+    private static func parseSkillRow(_ line: String) -> HermesCuratorSkillRow? {
+        guard let activityRange = line.range(of: "activity=") else { return nil }
+        let name = String(line[..<activityRange.lowerBound]).trimmingCharacters(in: .whitespaces)
+        guard !name.isEmpty else { return nil }
+
+        // Map each known key to its value substring. Read positionally
+        // by slicing between consecutive known keys — handles arbitrary
+        // whitespace padding without depending on column positions.
+        let knownKeys = ["activity=", "use=", "view=", "patches=", "last_activity="]
+        var positions: [(key: String, range: Range<String.Index>)] = []
+        for key in knownKeys {
+            if let r = line.range(of: key) {
+                positions.append((key, r))
+            }
+        }
+        positions.sort { $0.range.lowerBound < $1.range.lowerBound }
+
+        var activity = 0, use = 0, view = 0, patch = 0
+        var lastActivity = ""
+
+        for (idx, entry) in positions.enumerated() {
+            let valueStart = entry.range.upperBound
+            let valueEnd = idx + 1 < positions.count
+                ? positions[idx + 1].range.lowerBound
+                : line.endIndex
+            let raw = String(line[valueStart..<valueEnd]).trimmingCharacters(in: .whitespaces)
+            switch entry.key {
+            case "activity=":      activity = Int(raw) ?? 0
+            case "use=":           use = Int(raw) ?? 0
+            case "view=":          view = Int(raw) ?? 0
+            case "patches=":       patch = Int(raw) ?? 0
+            case "last_activity=": lastActivity = raw
+            default:               break
+            }
+        }
+        return HermesCuratorSkillRow(
+            name: name,
+            activityCount: activity,
+            useCount: use,
+            viewCount: view,
+            patchCount: patch,
+            lastActivityLabel: lastActivity
+        )
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesKanbanTask.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// One task from `hermes kanban list --json` (v0.12+).
+///
+/// Hermes ships a SQLite-backed task board under `~/.hermes/kanban.db`
+/// — multi-profile collaboration was reverted upstream while the
+/// design is reworked, so Scarf v2.6 surfaces this as a read-only
+/// list. Create / claim / dispatch / dependency-link UI is deferred
+/// until upstream stabilizes.
+public struct HermesKanbanTask: Sendable, Equatable, Identifiable, Codable {
+    public let id: String
+    public let title: String
+    public let body: String?
+    public let assignee: String?
+    public let status: String          // archived | blocked | done | ready | running | todo | triage
+    public let priority: Int?
+    public let tenant: String?
+    public let workspaceKind: String?  // scratch | worktree | dir
+    public let workspacePath: String?
+    public let createdBy: String?
+    public let createdAt: String?      // ISO timestamp
+    public let startedAt: String?
+    public let completedAt: String?
+    public let result: String?
+    public let skills: [String]
+
+    public init(
+        id: String,
+        title: String,
+        body: String? = nil,
+        assignee: String? = nil,
+        status: String,
+        priority: Int? = nil,
+        tenant: String? = nil,
+        workspaceKind: String? = nil,
+        workspacePath: String? = nil,
+        createdBy: String? = nil,
+        createdAt: String? = nil,
+        startedAt: String? = nil,
+        completedAt: String? = nil,
+        result: String? = nil,
+        skills: [String] = []
+    ) {
+        self.id = id
+        self.title = title
+        self.body = body
+        self.assignee = assignee
+        self.status = status
+        self.priority = priority
+        self.tenant = tenant
+        self.workspaceKind = workspaceKind
+        self.workspacePath = workspacePath
+        self.createdBy = createdBy
+        self.createdAt = createdAt
+        self.startedAt = startedAt
+        self.completedAt = completedAt
+        self.result = result
+        self.skills = skills
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case id, title, body, assignee, status, priority, tenant
+        case workspaceKind = "workspace_kind"
+        case workspacePath = "workspace_path"
+        case createdBy = "created_by"
+        case createdAt = "created_at"
+        case startedAt = "started_at"
+        case completedAt = "completed_at"
+        case result, skills
+    }
+
+    public init(from decoder: any Decoder) throws {
+        let c = try decoder.container(keyedBy: CodingKeys.self)
+        self.id = try c.decode(String.self, forKey: .id)
+        self.title = try c.decode(String.self, forKey: .title)
+        self.body = try c.decodeIfPresent(String.self, forKey: .body)
+        self.assignee = try c.decodeIfPresent(String.self, forKey: .assignee)
+        self.status = try c.decodeIfPresent(String.self, forKey: .status) ?? "unknown"
+        self.priority = try c.decodeIfPresent(Int.self, forKey: .priority)
+        self.tenant = try c.decodeIfPresent(String.self, forKey: .tenant)
+        self.workspaceKind = try c.decodeIfPresent(String.self, forKey: .workspaceKind)
+        self.workspacePath = try c.decodeIfPresent(String.self, forKey: .workspacePath)
+        self.createdBy = try c.decodeIfPresent(String.self, forKey: .createdBy)
+        self.createdAt = try c.decodeIfPresent(String.self, forKey: .createdAt)
+        self.startedAt = try c.decodeIfPresent(String.self, forKey: .startedAt)
+        self.completedAt = try c.decodeIfPresent(String.self, forKey: .completedAt)
+        self.result = try c.decodeIfPresent(String.self, forKey: .result)
+        self.skills = try c.decodeIfPresent([String].self, forKey: .skills) ?? []
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesMessage.swift

@@ -64,6 +64,28 @@ public struct HermesMessage: Identifiable, Sendable {
         if let rc = reasoningContent, !rc.isEmpty { return rc }
         return reasoning
     }
+
+    /// Return a copy of this message with `toolCalls` replaced. Used
+    /// by the v2.8 two-phase chat loader: skeleton fetch returns
+    /// messages with empty `toolCalls`; the background hydrate splices
+    /// the parsed values in without re-fetching the conversational
+    /// columns.
+    public func withToolCalls(_ newCalls: [HermesToolCall]) -> HermesMessage {
+        HermesMessage(
+            id: id,
+            sessionId: sessionId,
+            role: role,
+            content: content,
+            toolCallId: toolCallId,
+            toolCalls: newCalls,
+            toolName: toolName,
+            timestamp: timestamp,
+            tokenCount: tokenCount,
+            finishReason: finishReason,
+            reasoning: reasoning,
+            reasoningContent: reasoningContent
+        )
+    }
 }
 
 public struct HermesToolCall: Identifiable, Sendable, Codable {
@@ -210,3 +232,23 @@ public enum ToolKind: String, Sendable, CaseIterable {
         }
     }
 }
+
+/// Outcome of a `fetchMessagesOutcome` call. `transportError` is non-nil
+/// only when the underlying SSH/SQLite call hit a transport-layer
+/// failure (timeout, ControlMaster drop) — distinguishes a genuine
+/// empty session from a silent partial-load. The chat resume path uses
+/// it to surface a "couldn't load full history" banner.
+public struct MessageFetchOutcome: Sendable {
+    public let messages: [HermesMessage]
+    public let transportError: String?
+
+    public init(messages: [HermesMessage], transportError: String?) {
+        self.messages = messages
+        self.transportError = transportError
+    }
+
+    /// True when the fetch tripped a transport failure. Distinct from
+    /// `messages.isEmpty` — an empty session is a successful zero-row
+    /// result, while a transport error is "we don't know what's there."
+    public var didTimeOut: Bool { transportError != nil }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesPathSet.swift

@@ -35,10 +35,22 @@ public struct HermesPathSet: Sendable, Hashable {
         self.isRemote = isRemote
         self.binaryHint = binaryHint
     }
-    public nonisolated static let defaultLocalHome: String = {
-        let user = ProcessInfo.processInfo.environment["HOME"] ?? NSHomeDirectory()
-        return user + "/.hermes"
-    }()
+    /// Resolved path to the active local Hermes profile (issue #50).
+    ///
+    /// Hermes v0.11+ supports multiple profiles via `hermes profile use`;
+    /// each profile is a fully independent `HERMES_HOME` directory. We
+    /// delegate to `HermesProfileResolver` (which reads
+    /// `~/.hermes/active_profile`) so every derived path — `state.db`,
+    /// `sessions/`, `config.yaml`, `memories/`, etc. — automatically
+    /// follows the active profile. Returns the pre-profile default
+    /// `~/.hermes` whenever no named profile is active, so existing
+    /// (non-profile) installations are unaffected.
+    ///
+    /// Backed by a 5-second cache inside the resolver, so frequent
+    /// `HermesPathSet` constructions don't hammer the filesystem.
+    public nonisolated static var defaultLocalHome: String {
+        HermesProfileResolver.resolveLocalHome()
+    }
 
     /// Default remote home when the user doesn't override it in `SSHConfig`.
     /// We leave `~` unexpanded on purpose — the remote shell resolves it.
@@ -63,12 +75,35 @@ public struct HermesPathSet: Sendable, Hashable {
     public nonisolated var errorsLog: String { home + "/logs/errors.log" }
     public nonisolated var agentLog: String { home + "/logs/agent.log" }
     public nonisolated var gatewayLog: String { home + "/logs/gateway.log" }
+    /// Curator run-reports root (v0.12+). Hermes writes per-cycle dirs
+    /// under here named `<YYYYMMDD-HHMMSS>/` containing `run.json` and
+    /// `REPORT.md`. The `last_report_path` field on `curator_state`
+    /// points at the most recent dir; `CuratorViewModel` resolves the
+    /// JSON/Markdown files relative to it.
+    public nonisolated var curatorLogsDir: String { home + "/logs/curator" }
+    /// JSON-encoded curator state (v0.12+). Filename has no extension
+    /// despite holding JSON — Hermes writes it via
+    /// `~/.hermes/skills/.curator_state`. Carries last-run metadata,
+    /// run count, pause flag, and the path to the most recent report.
+    public nonisolated var curatorStateFile: String { home + "/skills/.curator_state" }
     public nonisolated var scarfDir: String { home + "/scarf" }
     public nonisolated var projectsRegistry: String { scarfDir + "/projects.json" }
 
     /// Maps Hermes session IDs to the Scarf project path a chat was
     /// started for. Scarf-owned; Hermes never touches this file.
     public nonisolated var sessionProjectMap: String { scarfDir + "/session_project_map.json" }
+    /// Cached list of available Nous Portal models. Populated by
+    /// `NousModelCatalogService` from `GET https://inference-api.nousresearch.com/v1/models`
+    /// using the bearer token in `auth.json`. Refreshed on a 24h TTL or
+    /// on user request from the model picker. Survives offline runs so
+    /// the picker still has something to render.
+    public nonisolated var nousModelsCache: String { scarfDir + "/nous_models_cache.json" }
+    /// Cached `templates/catalog.json` from awizemann.github.io. Populated
+    /// by `CatalogService` on first sheet-open and refreshed on a 24h TTL
+    /// or on explicit user click. Mirrors `nousModelsCache` exactly:
+    /// JSON, scarf-owned, survives offline runs so the catalog browser
+    /// still has something to render. Wiped by a Hermes home reset.
+    public nonisolated var catalogCache: String { scarfDir + "/catalog_cache.json" }
     public nonisolated var mcpTokensDir: String { home + "/mcp-tokens" }
 
     // MARK: - Binary resolution

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesSkill.swift

@@ -37,6 +37,16 @@ public struct HermesSkill: Identifiable, Sendable {
     /// Python packages). Used by `SkillPrereqService` to know what to
     /// probe; nil when the field is absent.
     public let dependencies: [String]?
+    /// `false` when the skill name appears in `skills.disabled` in
+    /// `~/.hermes/config.yaml`. Hermes v0.12 stores disable state in
+    /// the config rather than per-skill markers; this is read-only
+    /// from Scarf's side until the toggle UI lands. Defaults to `true`.
+    public let enabled: Bool
+    /// `true` when the skill is pinned via `hermes curator pin <name>`.
+    /// Pinned skills are protected from auto-archive / consolidation.
+    /// Read from `CuratorViewModel.status.pinnedNames`; defaults to
+    /// `false` when curator state is unavailable.
+    public let pinned: Bool
 
     public init(
         id: String,
@@ -47,7 +57,9 @@ public struct HermesSkill: Identifiable, Sendable {
         requiredConfig: [String],
         allowedTools: [String]? = nil,
         relatedSkills: [String]? = nil,
-        dependencies: [String]? = nil
+        dependencies: [String]? = nil,
+        enabled: Bool = true,
+        pinned: Bool = false
     ) {
         self.id = id
         self.name = name
@@ -58,5 +70,7 @@ public struct HermesSkill: Identifiable, Sendable {
         self.allowedTools = allowedTools
         self.relatedSkills = relatedSkills
         self.dependencies = dependencies
+        self.enabled = enabled
+        self.pinned = pinned
     }
 }

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesTool.swift

@@ -53,6 +53,13 @@ public enum KnownPlatforms {
         HermesToolPlatform(name: "feishu", displayName: "Feishu", icon: "message.badge.circle"),
         HermesToolPlatform(name: "mattermost", displayName: "Mattermost", icon: "bubble.left.and.exclamationmark.bubble.right"),
         HermesToolPlatform(name: "imessage", displayName: "iMessage", icon: "message.fill"),
+        // -- v0.12 additions ---------------------------------------------
+        // Yuanbao is a native gateway adapter (18th platform); Microsoft
+        // Teams ships as a plugin (19th). PlatformDetail surfaces the
+        // distinction in the setup copy. Names match Hermes's gateway
+        // platform identifiers.
+        HermesToolPlatform(name: "yuanbao", displayName: "Yuanbao 元宝", icon: "bubble.left.and.bubble.right.fill"),
+        HermesToolPlatform(name: "microsoft-teams", displayName: "Microsoft Teams", icon: "person.2.fill"),
     ]
 
     public static func icon(for platform: String) -> String {
@@ -70,6 +77,8 @@ public enum KnownPlatforms {
         case "feishu": return "message.badge.circle"
         case "mattermost": return "bubble.left.and.exclamationmark.bubble.right"
         case "imessage": return "message.fill"
+        case "yuanbao": return "bubble.left.and.bubble.right.fill"
+        case "microsoft-teams": return "person.2.fill"
         default: return "bubble.left"
         }
     }

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ProjectDashboard.swift

@@ -39,6 +39,13 @@ public struct ProjectEntry: Codable, Sendable, Identifiable, Hashable {
 
     public var dashboardPath: String { path + "/.scarf/dashboard.json" }
 
+    /// Directory holding the project's Scarf-managed sidecar files
+    /// (dashboard.json, manifest.json, template.lock.json, config.json,
+    /// plus any cron-job-written reports the dashboard widgets reference).
+    /// Watched as a unit by `HermesFileWatcher` so any file added /
+    /// removed / renamed inside refreshes the dashboard automatically.
+    public var scarfDir: String { path + "/.scarf" }
+
     // MARK: - Codable (custom for backward compat)
 
     private enum CodingKeys: String, CodingKey {
@@ -152,29 +159,54 @@ public struct DashboardWidget: Codable, Sendable, Identifiable {
     // List
     public let items: [ListItem]?
 
-    // Webview
+    // Webview / Image (image reuses `url` for remote, `path` for local)
     public let url: String?
     public let height: Double?
 
+    // v2.7 — file-reading widgets (markdown_file, log_tail, image-local).
+    // `path` is resolved relative to the project root (the directory that
+    // contains `.scarf/`). Renderers must reject `..` segments after
+    // normalization to prevent escape from the project boundary.
+    public let path: String?
+    public let lines: Int?
+
+    // v2.7 — cron_status widget; `jobId` matches HermesCronJob.id.
+    public let jobId: String?
+
+    // v2.7 — status_grid widget; `cells` carries label + status per square,
+    // `gridColumns` overrides the auto-fit column count (keep distinct
+    // from `columns` which is the table-widget header list).
+    public let cells: [StatusGridCell]?
+    public let gridColumns: Int?
+
+    // v2.7 — optional sparkline trend on `stat` widgets.
+    public let sparkline: [Double]?
+
     public init(
         type: String,
         title: String,
-        value: WidgetValue?,
-        icon: String?,
-        color: String?,
-        subtitle: String?,
-        label: String?,
-        content: String?,
-        format: String?,
-        columns: [String]?,
-        rows: [[String]]?,
-        chartType: String?,
-        xLabel: String?,
-        yLabel: String?,
-        series: [ChartSeries]?,
-        items: [ListItem]?,
-        url: String?,
-        height: Double?
+        value: WidgetValue? = nil,
+        icon: String? = nil,
+        color: String? = nil,
+        subtitle: String? = nil,
+        label: String? = nil,
+        content: String? = nil,
+        format: String? = nil,
+        columns: [String]? = nil,
+        rows: [[String]]? = nil,
+        chartType: String? = nil,
+        xLabel: String? = nil,
+        yLabel: String? = nil,
+        series: [ChartSeries]? = nil,
+        items: [ListItem]? = nil,
+        url: String? = nil,
+        height: Double? = nil,
+        path: String? = nil,
+        lines: Int? = nil,
+        jobId: String? = nil,
+        cells: [StatusGridCell]? = nil,
+        gridColumns: Int? = nil,
+        sparkline: [Double]? = nil
     ) {
         self.type = type
         self.title = title
@@ -194,6 +226,29 @@ public struct DashboardWidget: Codable, Sendable, Identifiable {
         self.items = items
         self.url = url
         self.height = height
+        self.path = path
+        self.lines = lines
+        self.jobId = jobId
+        self.cells = cells
+        self.gridColumns = gridColumns
+        self.sparkline = sparkline
+    }
+}
+
+// MARK: - Status Grid Data (v2.7)
+
+/// One cell of a `status_grid` widget. Status semantics match `ListItem.status`
+/// — parsed via `ListItemStatus(raw:)` so the same vocabulary + synonyms apply.
+public struct StatusGridCell: Codable, Sendable, Identifiable, Hashable {
+    public var id: String { label }
+    public let label: String
+    public let status: String?
+    public let tooltip: String?
+
+    public init(label: String, status: String? = nil, tooltip: String? = nil) {
+        self.label = label
+        self.status = status
+        self.tooltip = tooltip
     }
 }
 
@@ -284,3 +339,47 @@ public struct ListItem: Codable, Sendable, Identifiable {
         self.status = status
     }
 }
+
+/// Typed semantic status for `ListItem` (and `status_grid` cells in v2.7+).
+///
+/// Wire format stays a free `String?` on `ListItem` for backwards compatibility —
+/// pre-existing dashboards never break. Renderers call `ListItemStatus(raw:)`
+/// to map known values + synonyms to a canonical case; unknown values return
+/// `nil` and render as plain neutral text.
+public enum ListItemStatus: String, Sendable, Hashable, CaseIterable {
+    case success
+    case warning
+    case danger
+    case info
+    case pending
+    case done
+    case neutral
+
+    /// Lenient parse — accepts canonical names plus common synonyms seen in
+    /// real-world dashboards (`ok`/`up` → success, `down`/`error`/`failed` →
+    /// danger, `active` → info). Returns `nil` for unrecognized strings so
+    /// the renderer can fall back to plain text.
+    public init?(raw: String?) {
+        guard let raw = raw?.trimmingCharacters(in: .whitespaces).lowercased(), !raw.isEmpty else {
+            return nil
+        }
+        switch raw {
+        case "success", "ok", "up", "green", "passing":
+            self = .success
+        case "warning", "warn", "yellow", "degraded":
+            self = .warning
+        case "danger", "down", "error", "failed", "failure", "red", "critical":
+            self = .danger
+        case "info", "active", "blue":
+            self = .info
+        case "pending", "queued", "waiting", "scheduled":
+            self = .pending
+        case "done", "complete", "completed", "finished":
+            self = .done
+        case "neutral", "muted", "gray":
+            self = .neutral
+        default:
+            return nil
+        }
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift

@@ -25,6 +25,10 @@ public struct SSHConfig: Sendable, Hashable, Codable {
     /// `HermesPathSet.defaultRemoteHome` (`~/.hermes`, shell-expanded on the
     /// remote side).
     public var remoteHome: String?
+    /// Override for where Scarf installs new project templates on this host.
+    /// `nil` uses `~/projects` (unexpanded — remote shell resolves it).
+    /// Created on first install if missing.
+    public var projectsRoot: String?
     /// Resolved remote path to the `hermes` binary. Populated by
     /// `SSHTransport` after the first `command -v hermes` probe; cached here
     /// so subsequent calls skip the round trip.
@@ -36,6 +40,7 @@ public struct SSHConfig: Sendable, Hashable, Codable {
         port: Int? = nil,
         identityFile: String? = nil,
         remoteHome: String? = nil,
+        projectsRoot: String? = nil,
         hermesBinaryHint: String? = nil
     ) {
         self.host = host
@@ -43,6 +48,7 @@ public struct SSHConfig: Sendable, Hashable, Codable {
         self.port = port
         self.identityFile = identityFile
         self.remoteHome = remoteHome
+        self.projectsRoot = projectsRoot
         self.hermesBinaryHint = hermesBinaryHint
     }
 }
@@ -106,6 +112,27 @@ public struct ServerContext: Sendable, Hashable, Identifiable {
         return false
     }
 
+    /// Default parent directory under which `ProjectTemplateInstaller` lays
+    /// out new projects. Per-host configurable on `.ssh` via
+    /// `SSHConfig.projectsRoot`; local always resolves to `~/Projects` on the
+    /// user's Mac. The remote default is left as an unexpanded `~/projects`
+    /// — the remote shell resolves the tilde, same convention as
+    /// `HermesPathSet.defaultRemoteHome`. The installer calls
+    /// `transport.createDirectory(_:)` at install time so a missing dir on a
+    /// fresh host is bootstrapped on first use rather than treated as an error.
+    public nonisolated var defaultProjectsRoot: String {
+        switch kind {
+        case .local:
+            return NSHomeDirectory() + "/Projects"
+        case .ssh(let config):
+            if let configured = config.projectsRoot,
+               !configured.trimmingCharacters(in: .whitespaces).isEmpty {
+                return configured
+            }
+            return "~/projects"
+        }
+    }
+
     /// Construct the `ServerTransport` for this context. Local contexts get
     /// a `LocalTransport`; SSH contexts get an `SSHTransport` configured
     /// from `SSHConfig` by default, OR whatever `sshTransportFactory`

scarf/Packages/ScarfCore/Sources/ScarfCore/Parsing/HermesConfig+YAML.swift

@@ -122,7 +122,8 @@ public extension HermesConfig {
             skillsHub: aux("skills_hub"),
             approval: aux("approval"),
             mcp: aux("mcp"),
-            flushMemories: aux("flush_memories")
+            flushMemories: aux("flush_memories"),
+            curator: aux("curator")
         )
 
         let security = SecuritySettings(
@@ -280,7 +281,10 @@ public extension HermesConfig {
             matrix: matrix,
             mattermost: mattermost,
             whatsapp: whatsapp,
-            homeAssistant: homeAssistant
+            homeAssistant: homeAssistant,
+            cacheTTL: str("prompt_caching.cache_ttl", default: "5m"),
+            redactionEnabled: bool("redaction.enabled", default: false),
+            runtimeMetadataFooter: bool("agent.runtime_metadata_footer", default: false)
         )
     }
 }

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/HermesQueryBackend.swift

@@ -0,0 +1,113 @@
+import Foundation
+
+/// Pluggable query engine for `HermesDataService`. Two implementations
+/// today:
+///
+/// * `LocalSQLiteBackend` — opens the local `~/.hermes/state.db` via
+///   libsqlite3 and runs queries in-process. Microseconds per query.
+/// * `RemoteSQLiteBackend` — invokes `sqlite3 -readonly -json` over an
+///   SSH session (ControlMaster keeps the channel warm), parses the
+///   JSON response into `Row`s. ~50–100 ms per query.
+///
+/// The data service picks one based on `ServerContext.isRemote`. View
+/// models are oblivious — they keep calling `await dataService.fetch…`
+/// like before.
+///
+/// **Why a protocol, not a class hierarchy.** Backends have very
+/// different internals (libsqlite3 handles vs. SSH script piping) but
+/// the call-site shape is identical. A protocol lets us hand the data
+/// service either backend through one stored property without
+/// abstract-class ceremony, and keeps the test mock (see
+/// `MockHermesQueryBackend` in tests) free of inheritance baggage.
+///
+/// **Sendable.** Concrete impls are actors, so they're trivially
+/// `Sendable`. The protocol conforms to `Sendable` to satisfy Swift 6
+/// strict-concurrency for the data-service stored property.
+public protocol HermesQueryBackend: Sendable {
+
+    /// True iff the connected DB has the v0.7 columns (`reasoning_tokens`,
+    /// `actual_cost_usd`, `cost_status`, `billing_provider` on
+    /// `sessions` plus `reasoning` on `messages`). Detected once at
+    /// `open()` time.
+    var hasV07Schema: Bool { get async }
+
+    /// True iff the connected DB has the v0.11 columns
+    /// (`api_call_count` on `sessions`, `reasoning_content` on
+    /// `messages`). Belt-and-braces: BOTH must be present (a
+    /// partially-migrated DB stays on the v0.7 path to avoid "no such
+    /// column" failures).
+    var hasV011Schema: Bool { get async }
+
+    /// User-presentable error from the most recent `open()` (or the
+    /// most recent failed query for the remote backend's
+    /// connectivity-loss codepath). `nil` means everything is healthy.
+    var lastOpenError: String? { get async }
+
+    /// One-time setup. Local: `sqlite3_open_v2` + `PRAGMA table_info`
+    /// schema detection. Remote: one SSH round-trip running
+    /// `sqlite3 --version` plus the two PRAGMA queries.
+    ///
+    /// Returns `false` on any failure; detail is in `lastOpenError`.
+    /// Calling `open()` on an already-open backend is a no-op that
+    /// returns `true`.
+    func open() async -> Bool
+
+    /// Local backend: `close()` then `open(forceFresh:)` — re-pulls
+    /// the SQLite handle so a Hermes-side migration becomes visible.
+    /// Remote backend: a no-op when `forceFresh: false` (every query
+    /// is already fresh — there's nothing to refresh). `forceFresh:
+    /// true` re-runs the schema preflight, covering the rare "user
+    /// upgraded Hermes on the remote, my schema flags are stale" case.
+    @discardableResult
+    func refresh(forceFresh: Bool) async -> Bool
+
+    /// Drop any persistent resources. Idempotent.
+    func close() async
+
+    /// Run a single SQL statement and collect every row before
+    /// returning. SQL uses `?` placeholders; `params` is bound
+    /// positionally (one entry per `?`).
+    ///
+    /// Local backend: `sqlite3_prepare_v2` + `sqlite3_bind_*` +
+    /// `sqlite3_step` loop, materialising each row into a `Row`.
+    /// Remote backend: inlines params via `SQLValueInliner` to produce
+    /// a final SQL string, runs `sqlite3 -readonly -json` over SSH,
+    /// parses the resulting JSON array.
+    ///
+    /// Throws `BackendError` on any failure. The data-service façade
+    /// generally catches and returns empty results to preserve the
+    /// existing "show empty UI on error" behaviour.
+    func query(_ sql: String, params: [SQLValue]) async throws -> [Row]
+
+    /// Run several statements in one round-trip, returning each
+    /// statement's row set in order. Lets multi-query view loads
+    /// (Dashboard's 4-query pattern, Insights' 5-query pattern)
+    /// amortise the SSH/sqlite3 cold-start cost.
+    ///
+    /// Each `(sql, params)` pair has the same shape as `query` —
+    /// `?` placeholders bound positionally per pair.
+    func queryBatch(_ statements: [(sql: String, params: [SQLValue])]) async throws -> [[Row]]
+}
+
+/// Errors that backends raise. Mapped into user-facing messages by the
+/// `humanize` helper that lives alongside `HermesDataService`.
+public enum BackendError: Error, Sendable, Equatable {
+    /// Backend is not open — caller should `open()` first.
+    case notOpen
+
+    /// Connectivity failure (SSH down, ControlMaster dead, transport
+    /// can't reach the host). Carries a short human-readable reason.
+    /// Triggers the data-service's `lastOpenError` populate path.
+    case transport(String)
+
+    /// sqlite3 itself reported an error — non-zero exit, parse failure,
+    /// schema mismatch. `exitCode` is the sqlite3 process exit (or
+    /// libsqlite3 result code on the local backend); `stderr` is the
+    /// sqlite3-emitted message (already user-readable in most cases).
+    case sqlite(exitCode: Int32, stderr: String)
+
+    /// JSON-parsing failed on remote-backend output. Indicates either a
+    /// sqlite3 binary that didn't honour `-json`, or output corruption
+    /// (rare). Carries the first 200 bytes of stdout for diagnostics.
+    case parseFailure(stdoutHead: String)
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/LocalSQLiteBackend.swift

@@ -0,0 +1,254 @@
+// MARK: - Platform gate
+//
+// libsqlite3 is a system module on macOS/iOS but not on swift-corelibs
+// foundation. Gate the entire backend so ScarfCore still compiles for
+// any future Linux target. Apple platforms — the runtime targets — get
+// the full implementation.
+#if canImport(SQLite3)
+
+import Foundation
+import SQLite3
+#if canImport(os)
+import os
+#endif
+
+/// `HermesQueryBackend` that opens a local SQLite file via libsqlite3
+/// and runs queries in-process. Microseconds per query.
+///
+/// Used for `ServerContext.local` (the user's own `~/.hermes/state.db`)
+/// — the previous behaviour of `HermesDataService` lifted out unchanged.
+/// For `.ssh` contexts the data service constructs `RemoteSQLiteBackend`
+/// instead.
+///
+/// Actor isolation matches the parent `HermesDataService` actor: queries
+/// serialise on this backend's executor, and the data service hops once
+/// (`await backend.query…`) per public method call.
+public actor LocalSQLiteBackend: HermesQueryBackend {
+
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf", category: "LocalSQLiteBackend")
+    #endif
+
+    private var db: OpaquePointer?
+    private var openedAtPath: String?
+    private(set) public var hasV07Schema = false
+    private(set) public var hasV011Schema = false
+    private(set) public var lastOpenError: String?
+
+    private let context: ServerContext
+
+    public init(context: ServerContext) {
+        self.context = context
+    }
+
+    // MARK: - Lifecycle
+
+    public func open() async -> Bool {
+        if db != nil { return true }
+        let path = context.paths.stateDB
+        guard FileManager.default.fileExists(atPath: path) else {
+            lastOpenError = "Hermes state database not found at \(path)."
+            return false
+        }
+        let flags: Int32 = SQLITE_OPEN_READONLY | SQLITE_OPEN_NOMUTEX
+        let rc = sqlite3_open_v2(path, &db, flags, nil)
+        guard rc == SQLITE_OK else {
+            let msg: String
+            if let db {
+                msg = String(cString: sqlite3_errmsg(db))
+            } else {
+                msg = "sqlite3_open_v2 returned \(rc)"
+            }
+            lastOpenError = "Couldn't open state.db: \(msg)"
+            #if canImport(os)
+            Self.logger.warning("sqlite3_open_v2 failed (\(rc)) at \(path, privacy: .public): \(msg, privacy: .public)")
+            #endif
+            db = nil
+            return false
+        }
+        openedAtPath = path
+        lastOpenError = nil
+        detectSchema()
+        return true
+    }
+
+    @discardableResult
+    public func refresh(forceFresh: Bool) async -> Bool {
+        // Local always close-and-reopen — the file may have been swapped
+        // by Hermes (rare) or we want to pick up a schema migration.
+        // `forceFresh` is irrelevant locally; included for protocol
+        // parity with the remote backend.
+        await close()
+        return await open()
+    }
+
+    public func close() async {
+        if let db {
+            sqlite3_close(db)
+        }
+        db = nil
+        openedAtPath = nil
+    }
+
+    // MARK: - Schema detection
+
+    private func detectSchema() {
+        guard let db else { return }
+
+        // sessions schema
+        var stmt: OpaquePointer?
+        if sqlite3_prepare_v2(db, "PRAGMA table_info(sessions)", -1, &stmt, nil) == SQLITE_OK {
+            defer { sqlite3_finalize(stmt) }
+            while sqlite3_step(stmt) == SQLITE_ROW {
+                if let name = sqlite3_column_text(stmt, 1) {
+                    let column = String(cString: name)
+                    if column == "reasoning_tokens" {
+                        hasV07Schema = true
+                    }
+                    if column == "api_call_count" {
+                        hasV011Schema = true
+                    }
+                }
+            }
+        }
+
+        // messages schema — confirm `reasoning_content` is present too.
+        // Belt-and-braces: a partially-migrated DB (sessions migrated,
+        // messages not) shouldn't blow up reads with "no such column".
+        if hasV011Schema {
+            var msgStmt: OpaquePointer?
+            var sawReasoningContent = false
+            if sqlite3_prepare_v2(db, "PRAGMA table_info(messages)", -1, &msgStmt, nil) == SQLITE_OK {
+                defer { sqlite3_finalize(msgStmt) }
+                while sqlite3_step(msgStmt) == SQLITE_ROW {
+                    if let name = sqlite3_column_text(msgStmt, 1),
+                       String(cString: name) == "reasoning_content" {
+                        sawReasoningContent = true
+                        break
+                    }
+                }
+            }
+            if !sawReasoningContent {
+                hasV011Schema = false
+            }
+        }
+    }
+
+    // MARK: - Queries
+
+    public func query(_ sql: String, params: [SQLValue]) async throws -> [Row] {
+        guard let db else { throw BackendError.notOpen }
+        return try executeOne(db: db, sql: sql, params: params)
+    }
+
+    public func queryBatch(_ statements: [(sql: String, params: [SQLValue])]) async throws -> [[Row]] {
+        guard let db else { throw BackendError.notOpen }
+        // Local backend has no SSH/process round-trip cost — running
+        // sequentially against the open handle is exactly equivalent
+        // to running each via `query`. The protocol method exists for
+        // remote-backend amortisation; locally we just satisfy the
+        // signature.
+        var out: [[Row]] = []
+        out.reserveCapacity(statements.count)
+        for (sql, params) in statements {
+            out.append(try executeOne(db: db, sql: sql, params: params))
+        }
+        return out
+    }
+
+    // MARK: - Internals
+
+    private func executeOne(db: OpaquePointer, sql: String, params: [SQLValue]) throws -> [Row] {
+        var stmt: OpaquePointer?
+        let prepRC = sqlite3_prepare_v2(db, sql, -1, &stmt, nil)
+        guard prepRC == SQLITE_OK, let stmt else {
+            let msg = String(cString: sqlite3_errmsg(db))
+            throw BackendError.sqlite(exitCode: prepRC, stderr: msg)
+        }
+        defer { sqlite3_finalize(stmt) }
+
+        for (i, value) in params.enumerated() {
+            let col = Int32(i + 1)
+            let rc: Int32
+            switch value {
+            case .null:
+                rc = sqlite3_bind_null(stmt, col)
+            case .integer(let n):
+                rc = sqlite3_bind_int64(stmt, col, n)
+            case .real(let d):
+                rc = sqlite3_bind_double(stmt, col, d)
+            case .text(let s):
+                rc = sqlite3_bind_text(stmt, col, s, -1, sqliteTransient)
+            case .blob(let d):
+                rc = d.withUnsafeBytes { buf -> Int32 in
+                    guard let base = buf.baseAddress else {
+                        return sqlite3_bind_zeroblob(stmt, col, 0)
+                    }
+                    return sqlite3_bind_blob(stmt, col, base, Int32(buf.count), sqliteTransient)
+                }
+            }
+            if rc != SQLITE_OK {
+                let msg = String(cString: sqlite3_errmsg(db))
+                throw BackendError.sqlite(exitCode: rc, stderr: msg)
+            }
+        }
+
+        // Build column-name → index map once per result set, lazily on
+        // first row (sqlite3_column_name needs the prepared stmt; cheap
+        // either way). For a 0-row result set we still build it so
+        // callers that read column names from the first hypothetical
+        // row don't error — though `Row.columnIndex` on an empty
+        // `[Row]` is moot.
+        let columnCount = Int(sqlite3_column_count(stmt))
+        var columnIndex: [String: Int] = [:]
+        columnIndex.reserveCapacity(columnCount)
+        for i in 0..<columnCount {
+            if let cstr = sqlite3_column_name(stmt, Int32(i)) {
+                columnIndex[String(cString: cstr)] = i
+            }
+        }
+
+        var rows: [Row] = []
+        while true {
+            let stepRC = sqlite3_step(stmt)
+            if stepRC == SQLITE_DONE { break }
+            if stepRC != SQLITE_ROW {
+                let msg = String(cString: sqlite3_errmsg(db))
+                throw BackendError.sqlite(exitCode: stepRC, stderr: msg)
+            }
+            var values: [SQLValue] = []
+            values.reserveCapacity(columnCount)
+            for i in 0..<columnCount {
+                let col = Int32(i)
+                let type = sqlite3_column_type(stmt, col)
+                switch type {
+                case SQLITE_NULL:
+                    values.append(.null)
+                case SQLITE_INTEGER:
+                    values.append(.integer(sqlite3_column_int64(stmt, col)))
+                case SQLITE_FLOAT:
+                    values.append(.real(sqlite3_column_double(stmt, col)))
+                case SQLITE_TEXT:
+                    if let cstr = sqlite3_column_text(stmt, col) {
+                        values.append(.text(String(cString: cstr)))
+                    } else {
+                        values.append(.text(""))
+                    }
+                case SQLITE_BLOB:
+                    let n = Int(sqlite3_column_bytes(stmt, col))
+                    if n > 0, let p = sqlite3_column_blob(stmt, col) {
+                        values.append(.blob(Data(bytes: p, count: n)))
+                    } else {
+                        values.append(.blob(Data()))
+                    }
+                default:
+                    values.append(.null)
+                }
+            }
+            rows.append(Row(values: values, columnIndex: columnIndex))
+        }
+        return rows
+    }
+}
+
+#endif // canImport(SQLite3)

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/RemoteSQLiteBackend.swift

@@ -0,0 +1,651 @@
+#if canImport(SQLite3)
+
+import Foundation
+#if canImport(os)
+import os
+#endif
+
+/// `HermesQueryBackend` that runs `sqlite3 -readonly -json` over an
+/// SSH session per query. Replaces the old snapshot-then-open pipeline
+/// (issue #74): no full-DB transfers, no local cache, every query
+/// against the live remote DB.
+///
+/// **Why one round-trip per query is OK.** ControlMaster keeps the SSH
+/// session warm — first connect spins up the master socket; subsequent
+/// queries reuse it at ~5 ms overhead. sqlite3 cold-start is ~30–50 ms,
+/// query execution is sub-millisecond for indexed queries, JSON
+/// serialisation is small. End-to-end ~50–100 ms per query, dominated
+/// by sqlite3 process spawn. Multi-query view loads (Dashboard,
+/// Insights) batch via `queryBatch` — one cold-start, all statements
+/// in a single sqlite3 invocation, ~80–100 ms total.
+///
+/// **Result format**. `sqlite3 -json` emits one JSON array per
+/// statement that returns rows: `[{"col":val,...}, ...]`. Multi-statement
+/// scripts emit each array on its own. We separate batched queries
+/// with a `SELECT '__SCARF_RS_BEGIN__N' AS marker;` synthesised line so
+/// the parser can split on the markers — sqlite3's marker rows
+/// preserve order and let us pair each result-set with the originating
+/// statement index.
+public actor RemoteSQLiteBackend: HermesQueryBackend {
+
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf", category: "RemoteSQLiteBackend")
+    #endif
+
+    private let context: ServerContext
+    private let transport: any ServerTransport
+    private(set) public var hasV07Schema = false
+    private(set) public var hasV011Schema = false
+    private(set) public var lastOpenError: String?
+    private var isOpen = false
+    /// Captured `sqlite3 --version` line from the most recent preflight.
+    /// Stashed for diagnostic logs and a future "remote sqlite3 too old"
+    /// error path.
+    private var sqliteVersion: String?
+    /// Resolved absolute remote `$HOME`, populated on `open()` via
+    /// `context.resolvedUserHome()` so that `~/` paths can be expanded
+    /// in Swift up front rather than relying on shell expansion across
+    /// the streamScript pipeline. The base64 + pipe path through
+    /// Citadel does not reliably propagate `$HOME` into the inner
+    /// `/bin/sh` on every host — keeping this client-side avoids the
+    /// issue (and matches how `RemoteBackupService.expandTilde` already
+    /// handles the same problem). `nil` only when the probe failed,
+    /// in which case `quoteForRemoteShell` falls back to `"$HOME/..."`
+    /// shell expansion.
+    private var resolvedHome: String?
+
+    /// In-flight query coalescing — keyed on the inlined SQL text,
+    /// value is the Task currently fetching that exact result set.
+    /// When two concurrent callers ask for the same query (common
+    /// pattern: file watcher tick + chat-finalize debounce both
+    /// firing `loadRecentSessions` within ~100 ms), the second
+    /// caller awaits the first call's task instead of spawning a
+    /// fresh SSH subprocess. Cleared on task completion. Drops
+    /// duplicate `mac.loadRecentSessions` traces observed at
+    /// t=960450 / t=960584 in the perf capture (two parallel 3-s
+    /// loads for the same data, finishing 134 ms apart).
+    ///
+    /// Coalescing is *only* applied to single `query` calls, not
+    /// `queryBatch` — batches are larger payloads with caller-
+    /// specific timeout scaling, and concurrent callers wanting
+    /// "the same batch" is rare in practice. Keep coalescing
+    /// surgical so we don't accidentally serialize independent
+    /// work that just happens to match.
+    private var inFlightQueries: [String: Task<[Row], Error>] = [:]
+
+    /// Per-query timeout for `query`. Healthy local queries are
+    /// <100 ms; remote ones over 420 ms-RTT SSH amortize one round
+    /// trip per call PLUS the wire payload time. A `fetchMessages`
+    /// over a 157-message session (~50KB JSON encoded) exceeded
+    /// the previous 15 s ceiling, silently returned 0 rows, and the
+    /// chat appeared empty — a worse failure than the wait it was
+    /// guarding against. Bumped to 30 s; the `streamScript`
+    /// transport-level timeout still fires on truly wedged hosts.
+    private let queryTimeout: TimeInterval = 30
+
+    /// Preflight timeout. First SSH round-trip may include cold
+    /// ControlMaster establishment (~1–3 s) plus the schema PRAGMA
+    /// queries; 30 s is generous.
+    private let preflightTimeout: TimeInterval = 30
+
+    /// Marker prefix used to split `queryBatch` result sets. Picked to
+    /// be very unlikely to collide with a real session_id, role string,
+    /// or content fragment.
+    private static let batchMarkerPrefix = "__SCARF_RS_BEGIN__"
+
+    public init(context: ServerContext, transport: any ServerTransport) {
+        self.context = context
+        self.transport = transport
+    }
+
+    // MARK: - Lifecycle
+
+    public func open() async -> Bool {
+        if isOpen { return true }
+        // Resolve remote $HOME once (cached process-wide via
+        // ServerContext.UserHomeCache so concurrent backends share
+        // the probe result). Lets us hand sqlite3 absolute paths and
+        // skip the unreliable nested-shell expansion altogether. A
+        // probe failure leaves `resolvedHome == nil` and falls back
+        // to "$HOME/..."-quoted args; the data-service open() will
+        // surface whatever sqlite3 errors out with.
+        let probedHome = await context.resolvedUserHome()
+        if probedHome != "~" && !probedHome.isEmpty {
+            resolvedHome = probedHome
+        }
+        let dbPath = context.paths.stateDB
+        // One SSH round-trip running:
+        //   1. sqlite3 --version  (sanity + capture for diagnostics)
+        //   2. PRAGMA table_info(sessions) | sessions schema
+        //   3. PRAGMA table_info(messages) | messages schema
+        // sqlite3 -json emits two arrays back-to-back for the two PRAGMA
+        // statements; we parse them as separate result sets.
+        let preflight = """
+        set -e
+        sqlite3 --version
+        sqlite3 -readonly -json \(quoteForRemoteShell(dbPath)) "PRAGMA table_info(sessions); PRAGMA table_info(messages);"
+        """
+
+        do {
+            let result = try await transport.streamScript(preflight, timeout: preflightTimeout)
+            if result.exitCode != 0 {
+                lastOpenError = errorMessage(stderr: result.stderrString, stdout: result.stdoutString, exitCode: result.exitCode)
+                #if canImport(os)
+                Self.logger.warning("Remote preflight failed (exit \(result.exitCode)): \(self.lastOpenError ?? "", privacy: .public)")
+                #endif
+                return false
+            }
+            try parsePreflightOutput(result.stdoutString)
+            lastOpenError = nil
+            isOpen = true
+            #if canImport(os)
+            Self.logger.info("Remote SQLite backend ready: sqlite3=\(self.sqliteVersion ?? "?", privacy: .public), v0.7=\(self.hasV07Schema), v0.11=\(self.hasV011Schema)")
+            #endif
+            return true
+        } catch {
+            lastOpenError = error.localizedDescription
+            #if canImport(os)
+            Self.logger.warning("Remote preflight transport error: \(error.localizedDescription, privacy: .public)")
+            #endif
+            return false
+        }
+    }
+
+    @discardableResult
+    public func refresh(forceFresh: Bool) async -> Bool {
+        // Streaming queries are always fresh. The watcher tick still
+        // fires `dataService.refresh()` on every observed file change
+        // — locally that re-opens the SQLite handle; here it's a
+        // no-op. `forceFresh: true` is the escape hatch for when the
+        // user explicitly wants a re-preflight (e.g. they upgraded
+        // Hermes on the remote). Drop the open state and re-run.
+        if forceFresh {
+            isOpen = false
+            return await open()
+        }
+        return isOpen ? true : await open()
+    }
+
+    public func close() async {
+        isOpen = false
+    }
+
+    // MARK: - Queries
+
+    public func query(_ sql: String, params: [SQLValue]) async throws -> [Row] {
+        guard isOpen else { throw BackendError.notOpen }
+        let inlined = SQLValueInliner.inline(sql, params: params)
+        // In-flight coalescing — if a query with the exact same
+        // inlined SQL is already pending, await its task instead
+        // of spawning a new SSH subprocess. Surfaces in ScarfMon as
+        // a `sqlite.query.coalesced` event so we can see how often
+        // the dedup actually fires in the wild.
+        if let existing = inFlightQueries[inlined] {
+            ScarfMon.event(.sqlite, "query.coalesced", count: 1)
+            return try await withTaskCancellationHandler(
+                operation: { try await existing.value },
+                onCancel: { existing.cancel() }
+            )
+        }
+        let task = Task<[Row], Error> { [self] in
+            try await ScarfMon.measureAsync(.sqlite, "query") {
+                let dbPath = context.paths.stateDB
+                let script = """
+                sqlite3 -readonly -json \(quoteForRemoteShell(dbPath)) <<'__SCARF_SQL__'
+                \(inlined)
+                __SCARF_SQL__
+                """
+                let result: ProcessResult
+                do {
+                    result = try await transport.streamScript(script, timeout: queryTimeout)
+                } catch {
+                    throw BackendError.transport(error.localizedDescription)
+                }
+                if result.exitCode != 0 {
+                    throw BackendError.sqlite(exitCode: result.exitCode, stderr: result.stderrString)
+                }
+                let rows = try parseSingleResultSet(result.stdoutString)
+                ScarfMon.event(.sqlite, "query.rows", count: rows.count, bytes: result.stdout.count)
+                return rows
+            }
+        }
+        inFlightQueries[inlined] = task
+        defer { inFlightQueries[inlined] = nil }
+        // v2.8 — propagate parent task cancellation INTO the
+        // unstructured `task`. `Task<...>{ ... }` doesn't inherit
+        // cancellation from the awaiting context, so without this a
+        // cancelled chat-hydration / dashboard-refresh would keep
+        // the ssh subprocess alive for the full 30s queryTimeout
+        // — pinning a remote sqlite query and a ControlMaster
+        // session slot. With the bridge, the inner task's awaits
+        // see a cancelled parent and `SSHScriptRunner.run`'s own
+        // cancellation handler (v2.8) kills the ssh process inside
+        // the next 100ms poll.
+        return try await withTaskCancellationHandler(
+            operation: { try await task.value },
+            onCancel: { task.cancel() }
+        )
+    }
+
+    public func queryBatch(_ statements: [(sql: String, params: [SQLValue])]) async throws -> [[Row]] {
+        try await ScarfMon.measureAsync(.sqlite, "queryBatch") {
+            try await _queryBatchImpl(statements)
+        }
+    }
+
+    private func _queryBatchImpl(_ statements: [(sql: String, params: [SQLValue])]) async throws -> [[Row]] {
+        guard isOpen else { throw BackendError.notOpen }
+        if statements.isEmpty { return [] }
+        // Build one sqlite3 invocation with marker SELECTs separating
+        // each statement's result set. `SELECT '__SCARF_RS_BEGIN__N'`
+        // emits a one-row JSON array we use as a sentinel.
+        var sqlBlocks: [String] = []
+        for (i, stmt) in statements.enumerated() {
+            let inlined = SQLValueInliner.inline(stmt.sql, params: stmt.params)
+            // Marker first (so we know which result-set follows even
+            // if a query returns zero rows — sqlite3 -json prints
+            // nothing for empty result sets, which would otherwise
+            // make the parser drift).
+            sqlBlocks.append("SELECT '\(Self.batchMarkerPrefix)\(i)' AS marker;")
+            sqlBlocks.append(ensureTrailingSemicolon(inlined))
+        }
+        let combined = sqlBlocks.joined(separator: "\n")
+        let dbPath = context.paths.stateDB
+        let script = """
+        sqlite3 -readonly -json \(quoteForRemoteShell(dbPath)) <<'__SCARF_SQL__'
+        \(combined)
+        __SCARF_SQL__
+        """
+        let result: ProcessResult
+        do {
+            // Batched timeout: scale with statement count, capped at
+            // a comfortable 30 s. Most batches are 4–5 statements.
+            let timeout = min(30, queryTimeout + Double(statements.count) * 2)
+            result = try await transport.streamScript(script, timeout: timeout)
+        } catch {
+            throw BackendError.transport(error.localizedDescription)
+        }
+        if result.exitCode != 0 {
+            throw BackendError.sqlite(exitCode: result.exitCode, stderr: result.stderrString)
+        }
+        return try parseBatchResultSets(result.stdoutString, expectedCount: statements.count)
+    }
+
+    // MARK: - Preflight parsing
+
+    private func parsePreflightOutput(_ stdout: String) throws {
+        // Expected output:
+        //   <sqlite3 version line>
+        //   [<sessions PRAGMA result>]
+        //   [<messages PRAGMA result>]
+        let lines = stdout.split(separator: "\n", omittingEmptySubsequences: false)
+        guard let firstLine = lines.first, !firstLine.isEmpty else {
+            throw BackendError.parseFailure(stdoutHead: String(stdout.prefix(200)))
+        }
+        sqliteVersion = String(firstLine).trimmingCharacters(in: .whitespacesAndNewlines)
+
+        // The remaining lines should contain two JSON arrays. sqlite3
+        // -json emits each on its own — though it can wrap long arrays
+        // across multiple lines. We split on `][` boundaries to be
+        // robust. Walk the stream looking for two top-level arrays.
+        let rest = lines.dropFirst().joined(separator: "\n")
+        let arrays = splitTopLevelJSONArrays(rest)
+        guard arrays.count >= 2 else {
+            throw BackendError.parseFailure(stdoutHead: String(stdout.prefix(200)))
+        }
+        let sessionsTable = try parseTableInfo(arrays[0])
+        let messagesTable = try parseTableInfo(arrays[1])
+
+        // v0.7: sessions has `reasoning_tokens`.
+        hasV07Schema = sessionsTable.contains("reasoning_tokens")
+        // v0.11: BOTH sessions has `api_call_count` AND messages has
+        // `reasoning_content`. Belt-and-braces against partial migrations.
+        let sessionsHasV011 = sessionsTable.contains("api_call_count")
+        let messagesHasV011 = messagesTable.contains("reasoning_content")
+        hasV011Schema = sessionsHasV011 && messagesHasV011
+    }
+
+    /// Extract column names from a `PRAGMA table_info(...)` result set.
+    private func parseTableInfo(_ json: String) throws -> Set<String> {
+        guard let data = json.data(using: .utf8),
+              let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
+            throw BackendError.parseFailure(stdoutHead: String(json.prefix(200)))
+        }
+        var names: Set<String> = []
+        for row in arr {
+            if let name = row["name"] as? String {
+                names.insert(name)
+            }
+        }
+        return names
+    }
+
+    // MARK: - Result-set parsing
+
+    private func parseSingleResultSet(_ stdout: String) throws -> [Row] {
+        // sqlite3 -json prints nothing for empty result sets, so an
+        // empty stdout is valid and means "0 rows".
+        let trimmed = stdout.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return [] }
+        return try rowsFromJSONArray(trimmed)
+    }
+
+    private func parseBatchResultSets(_ stdout: String, expectedCount: Int) throws -> [[Row]] {
+        // Scan the output as a sequence of JSON arrays. Each marker
+        // SELECT emits a one-row array `[{"marker":"__SCARF_RS_BEGIN__N"}]`;
+        // the following array (if present) is statement N's result set.
+        let arrays = splitTopLevelJSONArrays(stdout)
+        var result: [[Row]] = Array(repeating: [], count: expectedCount)
+        var i = 0
+        while i < arrays.count {
+            let chunk = arrays[i]
+            // Try to read this chunk as a marker. A marker row is one
+            // object with exactly the `marker` field. Anything else
+            // is a real result set (which we attribute to the most
+            // recent marker we saw).
+            if let idx = markerIndex(in: chunk) {
+                // Next array (if any) is this statement's result set.
+                // If the next array is ALSO a marker, the current
+                // statement returned zero rows.
+                let next = i + 1
+                if next < arrays.count, markerIndex(in: arrays[next]) == nil {
+                    result[idx] = try rowsFromJSONArray(arrays[next])
+                    i = next + 1
+                } else {
+                    // Empty result set for this statement.
+                    i = next
+                }
+            } else {
+                // Stray array (no preceding marker). Skip — shouldn't
+                // happen in practice given how we build the script.
+                i += 1
+            }
+        }
+        return result
+    }
+
+    /// If the array's single row is a marker `{"marker":"__SCARF_RS_BEGIN__N"}`,
+    /// return N. Otherwise nil.
+    private func markerIndex(in json: String) -> Int? {
+        guard let data = json.data(using: .utf8),
+              let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]],
+              arr.count == 1,
+              let marker = arr[0]["marker"] as? String,
+              marker.hasPrefix(Self.batchMarkerPrefix) else { return nil }
+        let suffix = marker.dropFirst(Self.batchMarkerPrefix.count)
+        return Int(suffix)
+    }
+
+    private func rowsFromJSONArray(_ json: String) throws -> [Row] {
+        guard let data = json.data(using: .utf8),
+              let arr = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]] else {
+            throw BackendError.parseFailure(stdoutHead: String(json.prefix(200)))
+        }
+        if arr.isEmpty { return [] }
+        // `[String: Any]` does NOT preserve insertion order on macOS
+        // (NSDictionary backing). To keep the SELECT column order
+        // intact — which the data-service row parsers depend on
+        // (`row.string(at: 0)` for `id`, etc.) — we extract the key
+        // order from the FIRST object's raw JSON bytes. Subsequent
+        // rows reuse that key list to look up values by name from
+        // their parsed dictionaries.
+        let firstObjectRaw = extractFirstJSONObject(from: json)
+        let orderedKeys = firstObjectRaw.flatMap(extractKeysInOrder) ?? Array(arr[0].keys)
+        var columnIndex: [String: Int] = [:]
+        columnIndex.reserveCapacity(orderedKeys.count)
+        for (i, k) in orderedKeys.enumerated() { columnIndex[k] = i }
+
+        var rows: [Row] = []
+        rows.reserveCapacity(arr.count)
+        for obj in arr {
+            var values: [SQLValue] = []
+            values.reserveCapacity(orderedKeys.count)
+            for key in orderedKeys {
+                values.append(decode(obj[key]))
+            }
+            rows.append(Row(values: values, columnIndex: columnIndex))
+        }
+        return rows
+    }
+
+    /// Extract the substring of the first `{...}` object in a JSON
+    /// array string. Used so we can scan its keys in original order
+    /// before NSJSONSerialization's hash-table conversion strips the
+    /// ordering. Tolerates nested objects/arrays via depth tracking.
+    private func extractFirstJSONObject(from json: String) -> String? {
+        guard let openIdx = json.firstIndex(of: "{") else { return nil }
+        var depth = 0
+        var inString = false
+        var escape = false
+        var i = openIdx
+        while i < json.endIndex {
+            let c = json[i]
+            if inString {
+                if escape { escape = false }
+                else if c == "\\" { escape = true }
+                else if c == "\"" { inString = false }
+                i = json.index(after: i)
+                continue
+            }
+            switch c {
+            case "\"":
+                inString = true
+            case "{":
+                depth += 1
+            case "}":
+                depth -= 1
+                if depth == 0 {
+                    let end = json.index(after: i)
+                    return String(json[openIdx..<end])
+                }
+            default:
+                break
+            }
+            i = json.index(after: i)
+        }
+        return nil
+    }
+
+    /// Walk an object literal `{"k1": v1, "k2": v2, ...}` and return
+    /// the keys in their literal order. Doesn't decode the values —
+    /// that's what NSJSONSerialization handles. Just extracts
+    /// `["k1", "k2", ...]` so we know the column ordering.
+    private func extractKeysInOrder(_ objectJSON: String) -> [String] {
+        var keys: [String] = []
+        var i = objectJSON.startIndex
+        // Skip past the leading `{`.
+        while i < objectJSON.endIndex, objectJSON[i] != "{" {
+            i = objectJSON.index(after: i)
+        }
+        if i < objectJSON.endIndex { i = objectJSON.index(after: i) }
+        var depth = 0
+        var inString = false
+        var escape = false
+        var keyStart: String.Index?
+        // We're at the start of object body. Looking for `"key":` patterns
+        // at depth 0. Toggle `expectingKey` after each `:`/`,`.
+        var expectingKey = true
+        while i < objectJSON.endIndex {
+            let c = objectJSON[i]
+            if inString {
+                if escape {
+                    escape = false
+                } else if c == "\\" {
+                    escape = true
+                } else if c == "\"" {
+                    inString = false
+                    if expectingKey && depth == 0, let start = keyStart {
+                        keys.append(String(objectJSON[start..<i]))
+                        expectingKey = false
+                        keyStart = nil
+                    }
+                }
+                i = objectJSON.index(after: i)
+                continue
+            }
+            switch c {
+            case "\"":
+                inString = true
+                if expectingKey && depth == 0 {
+                    keyStart = objectJSON.index(after: i)
+                }
+            case "{", "[":
+                depth += 1
+            case "}", "]":
+                if depth == 0 { return keys } // end of outer object
+                depth -= 1
+            case ",":
+                if depth == 0 { expectingKey = true }
+            case ":":
+                if depth == 0 { expectingKey = false }
+            default:
+                break
+            }
+            i = objectJSON.index(after: i)
+        }
+        return keys
+    }
+
+    private func decode(_ v: Any?) -> SQLValue {
+        guard let v else { return .null }
+        if v is NSNull { return .null }
+        if let n = v as? NSNumber {
+            // NSJSONSerialization decodes both ints and doubles into
+            // NSNumber. Distinguish: if it round-trips through Int64
+            // unchanged, treat as integer; else real.
+            // A leading-zero-after-dot Double like 1.0 still has
+            // .doubleValue == 1.0 and Int64(1.0) == 1, so the round-
+            // trip check correctly bins integral doubles as integer
+            // (which sqlite3 -json does too — `1` in JSON, not `1.0`).
+            let asInt64 = n.int64Value
+            if Double(asInt64) == n.doubleValue {
+                return .integer(asInt64)
+            }
+            return .real(n.doubleValue)
+        }
+        if let s = v as? String {
+            return .text(s)
+        }
+        // Fall-through: stringify whatever it is so we don't lose data
+        // silently. SQLite -json doesn't emit booleans or nested
+        // objects from PRAGMA / SELECT outputs in our usage.
+        return .text(String(describing: v))
+    }
+
+    // MARK: - JSON helpers
+
+    /// Walk a string of one or more concatenated JSON arrays at the top
+    /// level (sqlite3 -json's batched output) and return each array as
+    /// a separate substring. Tolerates whitespace/newlines between
+    /// arrays.
+    private func splitTopLevelJSONArrays(_ s: String) -> [String] {
+        var out: [String] = []
+        var depth = 0
+        var inString = false
+        var escape = false
+        var start: String.Index?
+        var i = s.startIndex
+        while i < s.endIndex {
+            let c = s[i]
+            if inString {
+                if escape {
+                    escape = false
+                } else if c == "\\" {
+                    escape = true
+                } else if c == "\"" {
+                    inString = false
+                }
+                i = s.index(after: i)
+                continue
+            }
+            switch c {
+            case "\"":
+                inString = true
+            case "[":
+                if depth == 0 { start = i }
+                depth += 1
+            case "]":
+                depth -= 1
+                if depth == 0, let begin = start {
+                    let end = s.index(after: i)
+                    out.append(String(s[begin..<end]))
+                    start = nil
+                }
+            default:
+                break
+            }
+            i = s.index(after: i)
+        }
+        return out
+    }
+
+    private func ensureTrailingSemicolon(_ sql: String) -> String {
+        let trimmed = sql.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.hasSuffix(";") { return trimmed }
+        return trimmed + ";"
+    }
+
+    // MARK: - Quoting + error mapping
+
+    /// Build the shell argument that the remote `sh -c` will see for
+    /// the SQLite path. Three cases, in priority order:
+    ///
+    /// 1. **`~`-prefixed AND we have a `resolvedHome`** — the common
+    ///    case. Pre-expand to an absolute path in Swift, then single-
+    ///    quote. Sqlite3 receives a literal absolute path; no shell
+    ///    expansion needed.
+    /// 2. **`~`-prefixed AND no `resolvedHome`** (probe failed) —
+    ///    fall back to `"$HOME/..."` and hope the remote shell expands
+    ///    it. Works on Mac SSHTransport (login shell with $HOME set);
+    ///    less reliable through Citadel's exec-channel + base64 +
+    ///    inner-`/bin/sh` pipeline on iOS, which is precisely why
+    ///    we prefer the resolved-home path above.
+    /// 3. **Absolute** (`/home/agent/.hermes/state.db`) — single-quote
+    ///    with the standard sh escape for any embedded single-quote.
+    ///
+    /// sqlite3 doesn't expand `~` itself (that's a shell affordance),
+    /// so a default-config remote with `paths.stateDB ==
+    /// "~/.hermes/state.db"` would produce `unable to open database
+    /// "~/.hermes/state.db"` without one of these rewrites — issue
+    /// reported on iOS Citadel against `127.0.0.1`.
+    private func quoteForRemoteShell(_ path: String) -> String {
+        if let home = resolvedHome {
+            let expanded: String
+            if path == "~" {
+                expanded = home
+            } else if path.hasPrefix("~/") {
+                expanded = home + "/" + String(path.dropFirst(2))
+            } else {
+                expanded = path
+            }
+            return "'" + expanded.replacingOccurrences(of: "'", with: "'\\''") + "'"
+        }
+        // Probe-failed fallback: rely on remote-shell `$HOME` expansion.
+        if path == "~" {
+            return "\"$HOME\""
+        }
+        if path.hasPrefix("~/") {
+            let rest = String(path.dropFirst(2))
+            let escaped = rest
+                .replacingOccurrences(of: "\\", with: "\\\\")
+                .replacingOccurrences(of: "\"", with: "\\\"")
+                .replacingOccurrences(of: "$", with: "\\$")
+                .replacingOccurrences(of: "`", with: "\\`")
+            return "\"$HOME/\(escaped)\""
+        }
+        return "'" + path.replacingOccurrences(of: "'", with: "'\\''") + "'"
+    }
+
+    /// Translate a non-zero sqlite3 exit into a user-presentable
+    /// message. Mirrors substrings that `HermesDataService.humanize`
+    /// keys off so the existing dashboard banner renders correctly.
+    private func errorMessage(stderr: String, stdout: String, exitCode: Int32) -> String {
+        let combined = (stderr.isEmpty ? stdout : stderr).trimmingCharacters(in: .whitespacesAndNewlines)
+        if combined.isEmpty {
+            return "sqlite3 exited \(exitCode) with no output"
+        }
+        return combined
+    }
+}
+
+#endif // canImport(SQLite3)

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/SQLValue.swift

@@ -0,0 +1,136 @@
+import Foundation
+
+/// Typed SQLite column value. Mirrors SQLite's storage classes
+/// (`SQLITE_NULL`, `SQLITE_INTEGER`, `SQLITE_FLOAT`, `SQLITE_TEXT`,
+/// `SQLITE_BLOB`) so both backends — libsqlite3 (`LocalSQLiteBackend`)
+/// and remote `sqlite3 -json` parsing (`RemoteSQLiteBackend`) — can
+/// produce and consume the same `Row` shape.
+///
+/// Used in two places:
+///
+/// 1. **Bound parameters**: callers hand `[SQLValue]` to
+///    `HermesQueryBackend.query(_:params:)`. The local backend feeds
+///    them into `sqlite3_bind_*`; the remote backend inlines them as
+///    SQLite literals via `SQLValueInliner.inline(_:into:)`.
+/// 2. **Result columns**: each `Row.values` entry is one of these.
+///    Parsers (`sessionFromRow`, `messageFromRow` in HermesDataService)
+///    read positional accessors like `row.string(at: 3)` to get the
+///    typed value.
+public enum SQLValue: Sendable, Equatable {
+    case null
+    case integer(Int64)
+    case real(Double)
+    case text(String)
+    case blob(Data)
+}
+
+/// One result row from a query. Indexable both by position (matching the
+/// libsqlite3 `sqlite3_column_*` ergonomics that `HermesDataService`'s
+/// existing parsers expect) and by name (more readable for new code).
+///
+/// `columnIndex` is built once per result-set, not per row, so the
+/// per-row overhead is just the `[SQLValue]` allocation.
+public struct Row: Sendable {
+    /// Ordered column values, indexable by their position in the
+    /// underlying SELECT.
+    public let values: [SQLValue]
+
+    /// Column-name → position map. Built once per result-set by the
+    /// backend, then shared (by reference) across every row in the
+    /// set. Lookups are case-sensitive — match SQLite's default.
+    public let columnIndex: [String: Int]
+
+    public init(values: [SQLValue], columnIndex: [String: Int]) {
+        self.values = values
+        self.columnIndex = columnIndex
+    }
+
+    public subscript(_ position: Int) -> SQLValue {
+        guard position >= 0, position < values.count else { return .null }
+        return values[position]
+    }
+
+    public subscript(_ name: String) -> SQLValue {
+        guard let i = columnIndex[name] else { return .null }
+        return values[i]
+    }
+
+    // MARK: - Typed positional accessors
+    //
+    // These mirror the `columnText(stmt, i)` / `columnDate(stmt, i)`
+    // helpers that lived in HermesDataService so the row-parser
+    // migrations from `OpaquePointer` to `Row` are line-for-line.
+
+    public func string(at i: Int) -> String {
+        if case .text(let s) = self[i] { return s }
+        return ""
+    }
+
+    public func optionalString(at i: Int) -> String? {
+        switch self[i] {
+        case .text(let s): return s
+        case .null: return nil
+        default: return nil
+        }
+    }
+
+    public func int(at i: Int) -> Int {
+        switch self[i] {
+        case .integer(let n): return Int(n)
+        case .real(let d): return Int(d)
+        case .text(let s): return Int(s) ?? 0
+        default: return 0
+        }
+    }
+
+    public func optionalInt(at i: Int) -> Int? {
+        switch self[i] {
+        case .integer(let n): return Int(n)
+        case .real(let d): return Int(d)
+        case .text(let s): return Int(s)
+        case .null: return nil
+        default: return nil
+        }
+    }
+
+    public func int64(at i: Int) -> Int64 {
+        switch self[i] {
+        case .integer(let n): return n
+        case .real(let d): return Int64(d)
+        case .text(let s): return Int64(s) ?? 0
+        default: return 0
+        }
+    }
+
+    public func double(at i: Int) -> Double {
+        switch self[i] {
+        case .real(let d): return d
+        case .integer(let n): return Double(n)
+        case .text(let s): return Double(s) ?? 0
+        default: return 0
+        }
+    }
+
+    public func optionalDouble(at i: Int) -> Double? {
+        switch self[i] {
+        case .real(let d): return d
+        case .integer(let n): return Double(n)
+        case .text(let s): return Double(s)
+        case .null: return nil
+        default: return nil
+        }
+    }
+
+    /// Interpret the column as a Unix-epoch timestamp (seconds, fractional
+    /// allowed). Returns `nil` when the column is NULL or unparseable.
+    /// Mirrors the existing `columnDate` helper exactly.
+    public func date(at i: Int) -> Date? {
+        guard let secs = optionalDouble(at: i) else { return nil }
+        return Date(timeIntervalSince1970: secs)
+    }
+
+    public func isNull(at i: Int) -> Bool {
+        if case .null = self[i] { return true }
+        return false
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/Backends/SQLValueInliner.swift

@@ -0,0 +1,107 @@
+import Foundation
+
+/// Replaces `?` placeholders in a SQL string with SQLite-escaped
+/// literal values, in order. Used by `RemoteSQLiteBackend` because
+/// the `sqlite3` CLI doesn't accept `?`-bound parameters on the
+/// command line — it would need stdin `.parameter set @name` dot-
+/// commands, which require a multi-line script for every query and
+/// add round-trip overhead with no upside for our use case.
+///
+/// **Trust model.** This is a literal-encoder for in-tree, trusted
+/// callers — every current param source is either an integer (`limit`,
+/// `before`, `since.timeIntervalSince1970`), a Hermes-internal ID
+/// (UUID-shaped session/tool IDs that come back from the same DB), or
+/// a search query that already passes through `sanitizeFTSQuery` in
+/// HermesDataService. It is **NOT** a general SQL-injection defense.
+/// Don't extend the data-service surface with methods that accept raw
+/// untrusted user input as a `.text` param without first validating
+/// upstream. The local backend skips inlining entirely (uses
+/// `sqlite3_bind_*`) so this only affects the remote path.
+///
+/// Escape rules mirror SQLite's literal syntax:
+/// * `.null` → `NULL`
+/// * `.integer(n)` → `<n>` (no quoting)
+/// * `.real(d)` → `%.17g`-formatted (round-trips Double via decimal)
+/// * `.text(s)` → `'<s with single-quotes doubled>'`
+/// * `.blob(d)` → `X'<hex>'`
+public enum SQLValueInliner {
+
+    /// Walk `sql`, replacing each `?` (outside SQL string literals) with
+    /// the corresponding `params` entry's encoded form. Throws via
+    /// fatalError if the placeholder count doesn't match `params.count`
+    /// — a programmer error, not a runtime condition.
+    ///
+    /// `?` inside string literals (e.g. `WHERE name = '?'`) is preserved
+    /// unchanged. We track quote state with a tiny scanner so existing
+    /// SQL with literal `?` chars in strings doesn't get mis-bound.
+    public static func inline(_ sql: String, params: [SQLValue]) -> String {
+        var out = ""
+        out.reserveCapacity(sql.count + params.count * 16)
+        var paramIndex = 0
+        var inSingleQuote = false
+        var inDoubleQuote = false
+        var i = sql.startIndex
+        while i < sql.endIndex {
+            let c = sql[i]
+            if c == "'" && !inDoubleQuote {
+                // Check for SQL's `''` escape (a doubled single-quote
+                // INSIDE a string literal stays inside; we don't toggle
+                // out). The next char being another `'` keeps us in.
+                let next = sql.index(after: i)
+                if inSingleQuote && next < sql.endIndex && sql[next] == "'" {
+                    out.append("'")
+                    out.append("'")
+                    i = sql.index(after: next)
+                    continue
+                }
+                inSingleQuote.toggle()
+                out.append(c)
+                i = sql.index(after: i)
+                continue
+            }
+            if c == "\"" && !inSingleQuote {
+                inDoubleQuote.toggle()
+                out.append(c)
+                i = sql.index(after: i)
+                continue
+            }
+            if c == "?" && !inSingleQuote && !inDoubleQuote {
+                // Bind placeholder.
+                if paramIndex >= params.count {
+                    fatalError("SQLValueInliner: more `?` placeholders in SQL than provided params (\(params.count)). SQL: \(sql)")
+                }
+                out.append(encode(params[paramIndex]))
+                paramIndex += 1
+                i = sql.index(after: i)
+                continue
+            }
+            out.append(c)
+            i = sql.index(after: i)
+        }
+        if paramIndex != params.count {
+            fatalError("SQLValueInliner: \(params.count) params provided but only \(paramIndex) `?` placeholders consumed. SQL: \(sql)")
+        }
+        return out
+    }
+
+    /// Encode a single value as a SQLite literal. Public so callers
+    /// that build SQL strings by hand (rare — prefer `inline`) can
+    /// reuse the same escape rules.
+    public static func encode(_ value: SQLValue) -> String {
+        switch value {
+        case .null:
+            return "NULL"
+        case .integer(let n):
+            return String(n)
+        case .real(let d):
+            // %.17g round-trips a Double precisely as a decimal.
+            return String(format: "%.17g", d)
+        case .text(let s):
+            return "'" + s.replacingOccurrences(of: "'", with: "''") + "'"
+        case .blob(let d):
+            // SQLite blob literal: X'<hex>' (case-insensitive prefix).
+            let hex = d.map { String(format: "%02x", $0) }.joined()
+            return "X'\(hex)'"
+        }
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift

@@ -0,0 +1,314 @@
+import Foundation
+import Observation
+#if canImport(os)
+import os
+#endif
+
+/// What this Hermes installation can do, derived from `hermes --version`.
+///
+/// Scarf tracks Hermes feature releases by date-version + semver. v0.12 added
+/// a dozen surfaces (Curator, Kanban, multimodal ACP, ...) and removed a few
+/// (`flush_memories` aux task). UI that branches on these surfaces calls
+/// the boolean accessors here so older Hermes installs degrade silently
+/// instead of throwing on an unknown CLI subcommand.
+///
+/// Pure value type — no side effects. The async detection lives in
+/// `HermesCapabilitiesStore`.
+public struct HermesCapabilities: Sendable, Equatable {
+    /// Raw version line as printed by `hermes --version`. Preserved verbatim
+    /// so diagnostics views can show the exact string Scarf saw.
+    public let versionLine: String
+    /// Parsed `0.X.Y`. `nil` when the output didn't match the expected format
+    /// (e.g. Hermes returned an error, or a future format change).
+    public let semver: SemVer?
+    /// Parsed `YYYY.M.D` from the parenthesized date suffix. `nil` when
+    /// absent — older Hermes builds didn't always emit it.
+    public let dateVersion: DateVersion?
+
+    public init(versionLine: String, semver: SemVer?, dateVersion: DateVersion?) {
+        self.versionLine = versionLine
+        self.semver = semver
+        self.dateVersion = dateVersion
+    }
+
+    /// Sentinel for "not yet detected" / "detection failed". All capability
+    /// flags resolve to `false` so unguarded UI stays hidden until the real
+    /// version lands.
+    public static let empty = HermesCapabilities(
+        versionLine: "",
+        semver: nil,
+        dateVersion: nil
+    )
+
+    public var detected: Bool { semver != nil }
+
+    // MARK: - Capability flags
+    //
+    // Add a new flag here when Scarf gains UI that conditionally branches on
+    // a Hermes capability. Keep the comparison conservative: `>= 0.12.0`
+    // covers users still on the 0.12 line who haven't upgraded to 0.13 yet.
+
+    /// `hermes curator` autonomous skill maintenance (v0.12+).
+    public var hasCurator: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `hermes fallback` provider management (v0.12+).
+    public var hasFallbackCommand: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `hermes kanban` task board CLI (v0.12+).
+    public var hasKanban: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `hermes -z <prompt>` non-interactive one-shot mode (v0.12+).
+    public var hasOneShot: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `hermes skills install <https-url>` direct-URL install (v0.12+).
+    public var hasSkillURLInstall: Bool { atLeastSemver(0, 12, 0) }
+
+    /// ACP `session/prompt` accepts image content blocks (v0.12+).
+    public var hasACPImagePrompts: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `hermes update --check` preflight (v0.12+).
+    public var hasUpdateCheck: Bool { atLeastSemver(0, 12, 0) }
+
+    /// Pluggable TTS providers including native Piper (v0.12+).
+    public var hasPiperTTS: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `terminal.backend = vercel` Vercel Sandbox option (v0.12+).
+    public var hasVercelTerminal: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `auxiliary.flush_memories` config row was removed in v0.12.
+    /// Inverse semantics — `true` means the row should still be shown.
+    public var hasFlushMemoriesAux: Bool {
+        guard let s = semver else { return false }       // unknown → hide
+        return s < SemVer(major: 0, minor: 12, patch: 0) // pre-v0.12 only
+    }
+
+    /// `auxiliary.curator` aux task is configurable (v0.12+).
+    public var hasCuratorAux: Bool { atLeastSemver(0, 12, 0) }
+
+    /// Microsoft Teams (19th platform) and Yuanbao (18th) added in v0.12.
+    public var hasTeamsPlatform: Bool { atLeastSemver(0, 12, 0) }
+    public var hasYuanbaoPlatform: Bool { atLeastSemver(0, 12, 0) }
+
+    /// Cron jobs accept `--workdir` and `--context-from` flags (v0.12+).
+    public var hasCronWorkdir: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `prompt_caching.cache_ttl` config knob (v0.12+).
+    public var hasPromptCacheTTL: Bool { atLeastSemver(0, 12, 0) }
+
+    /// `redaction.enabled` is now off by default in v0.12 — Scarf surfaces
+    /// the toggle so users can flip it back on.
+    public var hasRedactionToggle: Bool { atLeastSemver(0, 12, 0) }
+
+    private func atLeastSemver(_ major: Int, _ minor: Int, _ patch: Int) -> Bool {
+        guard let s = semver else { return false }
+        return s >= SemVer(major: major, minor: minor, patch: patch)
+    }
+
+    public struct SemVer: Sendable, Equatable, Comparable, CustomStringConvertible {
+        public let major: Int
+        public let minor: Int
+        public let patch: Int
+
+        public init(major: Int, minor: Int, patch: Int) {
+            self.major = major
+            self.minor = minor
+            self.patch = patch
+        }
+
+        public var description: String { "\(major).\(minor).\(patch)" }
+
+        public static func < (a: SemVer, b: SemVer) -> Bool {
+            if a.major != b.major { return a.major < b.major }
+            if a.minor != b.minor { return a.minor < b.minor }
+            return a.patch < b.patch
+        }
+    }
+
+    public struct DateVersion: Sendable, Equatable, Comparable, CustomStringConvertible {
+        public let year: Int
+        public let month: Int
+        public let day: Int
+
+        public init(year: Int, month: Int, day: Int) {
+            self.year = year
+            self.month = month
+            self.day = day
+        }
+
+        public var description: String { "\(year).\(month).\(day)" }
+
+        public static func < (a: DateVersion, b: DateVersion) -> Bool {
+            if a.year != b.year { return a.year < b.year }
+            if a.month != b.month { return a.month < b.month }
+            return a.day < b.day
+        }
+    }
+
+    /// Parse a `Hermes Agent v0.12.0 (2026.4.30)` line out of `hermes --version`
+    /// output. Tolerates leading/trailing whitespace, extra header lines
+    /// (e.g. `Project:`, `Python:`), and the absence of the parenthesized
+    /// date suffix.
+    ///
+    /// Returns `.empty` when no recognizable version line is present so
+    /// callers don't have to special-case nil.
+    public static func parse(_ output: String) -> HermesCapabilities {
+        for raw in output.components(separatedBy: "\n") {
+            let line = raw.trimmingCharacters(in: .whitespaces)
+            guard line.contains("Hermes Agent v") else { continue }
+            return parseLine(line)
+        }
+        return .empty
+    }
+
+    /// `Hermes Agent v0.12.0 (2026.4.30)` → semver + date. Returns `.empty`
+    /// when the line doesn't match. Public for unit tests; production callers
+    /// should use `parse(_:)`.
+    public static func parseLine(_ line: String) -> HermesCapabilities {
+        // Locate the "v" right after "Hermes Agent ". Don't anchor at line
+        // start — older builds prefix with ANSI color codes Scarf would
+        // need to strip.
+        guard let vRange = line.range(of: "Hermes Agent v") else { return .empty }
+        let tail = String(line[vRange.upperBound...])
+
+        // Read digits separated by dots until we hit non-version content.
+        // First three components are semver. A trailing `(Y.M.D)` is the
+        // date version.
+        let semverEnd = tail.firstIndex(where: { c in
+            !(c.isNumber || c == ".")
+        }) ?? tail.endIndex
+        let semverStr = String(tail[..<semverEnd])
+        let semverParts = semverStr.split(separator: ".").compactMap { Int($0) }
+        guard semverParts.count >= 3 else { return .empty }
+        let semver = SemVer(
+            major: semverParts[0],
+            minor: semverParts[1],
+            patch: semverParts[2]
+        )
+
+        // Optional date suffix.
+        var dateVersion: DateVersion?
+        if let openParen = tail.firstIndex(of: "("),
+           let closeParen = tail.firstIndex(of: ")"),
+           openParen < closeParen {
+            let dateStr = tail[tail.index(after: openParen)..<closeParen]
+            let dateParts = dateStr.split(separator: ".").compactMap { Int($0) }
+            if dateParts.count == 3 {
+                dateVersion = DateVersion(
+                    year: dateParts[0],
+                    month: dateParts[1],
+                    day: dateParts[2]
+                )
+            }
+        }
+
+        return HermesCapabilities(
+            versionLine: line,
+            semver: semver,
+            dateVersion: dateVersion
+        )
+    }
+}
+
+/// Per-server capability cache. One per `ContextBoundRoot` (Mac) / iOS scene
+/// root, injected via `.environment(_:)`. Refreshes once on init; callers
+/// invoke `refresh()` after a Hermes update or when the server changes.
+///
+/// Not thread-safe across instances — each server gets its own store, and
+/// the underlying `runHermesCLI` call is detached so we never block
+/// MainActor.
+@Observable
+@MainActor
+public final class HermesCapabilitiesStore {
+    #if canImport(os)
+    private let logger = Logger(subsystem: "com.scarf", category: "HermesCapabilities")
+    #endif
+
+    public private(set) var capabilities: HermesCapabilities = .empty
+    public private(set) var isLoading = true
+
+    public let context: ServerContext
+    private var refreshTask: Task<Void, Never>?
+
+    public init(context: ServerContext) {
+        self.context = context
+        // Kick off a one-shot detection. Subsequent refreshes are explicit.
+        // Task captures `[weak self]`, so if the store is freed before
+        // detection completes the closure simply no-ops.
+        refreshTask = Task { [weak self] in
+            await self?.refresh()
+        }
+    }
+
+    public func refresh() async {
+        isLoading = true
+        let context = self.context
+        let parsed = await Task.detached(priority: .utility) { () -> HermesCapabilities in
+            return Self.detectSync(context: context)
+        }.value
+
+        self.capabilities = parsed
+        self.isLoading = false
+
+        #if canImport(os)
+        if parsed.detected {
+            logger.info("Hermes \(parsed.versionLine, privacy: .public) detected on \(self.context.displayName, privacy: .public)")
+        } else {
+            logger.warning("Hermes version not detected on \(self.context.displayName, privacy: .public)")
+        }
+        #endif
+    }
+
+    /// Synchronous detection helper. Lives here (not on `HermesCapabilities`)
+    /// because `ServerContext.makeTransport()` is a side-effecting call that
+    /// pulls in the platform-appropriate transport (LocalTransport on Mac,
+    /// CitadelServerTransport on iOS). The pure parser remains side-effect-free.
+    nonisolated private static func detectSync(context: ServerContext) -> HermesCapabilities {
+        let transport = context.makeTransport()
+        let executable = context.paths.hermesBinary
+        do {
+            let result = try transport.runProcess(
+                executable: executable,
+                args: ["--version"],
+                stdin: nil,
+                timeout: 10
+            )
+            // `hermes --version` writes to stdout but Scarf's transport
+            // helpers occasionally split error output across stderr — fold
+            // both so the parser sees whichever stream the line lands on.
+            let combined = result.stdoutString + result.stderrString
+            guard result.exitCode == 0 else { return .empty }
+            return HermesCapabilities.parse(combined)
+        } catch {
+            return .empty
+        }
+    }
+}
+
+// MARK: - SwiftUI environment wiring
+
+#if canImport(SwiftUI)
+import SwiftUI
+
+private struct HermesCapabilitiesStoreKey: EnvironmentKey {
+    static let defaultValue: HermesCapabilitiesStore? = nil
+}
+
+extension EnvironmentValues {
+    /// The active server's capability store. `nil` outside the per-server
+    /// `ContextBoundRoot`. Callers should treat `nil` and `.empty` capabilities
+    /// the same — defensive code for harness scenarios (Previews, smoke tests).
+    public var hermesCapabilities: HermesCapabilitiesStore? {
+        get { self[HermesCapabilitiesStoreKey.self] }
+        set { self[HermesCapabilitiesStoreKey.self] = newValue }
+    }
+}
+
+extension View {
+    /// Inject a `HermesCapabilitiesStore` into the environment. Mirrors the
+    /// usual `.environment(_:)` shape but routes through the typed key
+    /// above so callers don't need to import the key.
+    public func hermesCapabilities(_ store: HermesCapabilitiesStore) -> some View {
+        environment(\.hermesCapabilities, store)
+    }
+}
+#endif

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesProfileResolver.swift

@@ -0,0 +1,206 @@
+import Foundation
+import os
+
+/// Resolves Hermes's active profile (v0.11+) for local installations.
+///
+/// Hermes v0.11 introduced `hermes profile`: each profile is an independent
+/// `HERMES_HOME` directory. The "default" profile is `~/.hermes` itself;
+/// named profiles live at `~/.hermes/profiles/<name>/` and have their own
+/// `state.db`, `sessions/`, `config.yaml`, `.env`, `memories/`, `cron/`,
+/// `gateway_state.json`, etc.
+///
+/// The active profile is recorded in `~/.hermes/active_profile` (a single
+/// line text file containing the profile name, or absent / empty when the
+/// default profile is active). The Hermes CLI consults this file to set
+/// `HERMES_HOME` for each invocation.
+///
+/// Pre-v0.11 Scarf hardcoded `~/.hermes` and ignored `active_profile`,
+/// which meant `hermes profile use <name>` left Scarf reading the wrong
+/// state.db (issue #50). This resolver is the single seam: it reads
+/// `active_profile` and returns the effective home directory; everything
+/// else in `HermesPathSet` derives from `home`, so once the seam is
+/// correct every read path follows automatically.
+///
+/// **Caching.** The resolver is called from `HermesPathSet.defaultLocalHome`,
+/// which is in turn called whenever a `HermesPathSet` is constructed via
+/// the default helper. To avoid filesystem hits on hot paths we cache the
+/// resolved name for `cacheTTL` seconds (default 5s). That's tight enough
+/// that `hermes profile use other` followed by a Scarf operation picks up
+/// the change within seconds, and loose enough that no realistic UI loop
+/// causes more than a handful of file reads per minute.
+public enum HermesProfileResolver {
+
+    /// Cache lifetime for resolved profile state. Tunable for tests.
+    public static var cacheTTL: TimeInterval = 5
+
+    private static let lock = OSAllocatedUnfairLock(initialState: CacheState())
+    private static let logger = Logger(subsystem: "com.scarf.app", category: "HermesProfileResolver")
+
+    private static let profileNameRegex: NSRegularExpression = {
+        // Mirrors Hermes's own validation in hermes_cli/profiles.py.
+        try! NSRegularExpression(pattern: "^[a-z0-9][a-z0-9_-]{0,63}$")
+    }()
+
+    private struct CacheState {
+        var resolvedName: String = "default"
+        var resolvedHome: String = HermesProfileResolver.defaultRootHome()
+        var resolvedAt: Date = .distantPast
+    }
+
+    /// Effective Hermes home directory for the active profile.
+    /// Returns the default `~/.hermes` when no profile is active OR when
+    /// the configured profile is invalid (logged) — so the worst-case
+    /// failure mode is "Scarf shows what it always showed before."
+    ///
+    /// **Test override.** Setting `SCARF_HERMES_HOME` in the environment
+    /// pins this resolver to the supplied absolute path and bypasses both
+    /// the cache and the `active_profile` lookup. Used by the E2E test
+    /// harness (`TemplateE2ETests`, `TemplateInstallUITests`) to drive
+    /// Scarf against an isolated tmpdir Hermes home so the user's real
+    /// `~/.hermes` is never touched. Read on every call (cheap; a single
+    /// `ProcessInfo` lookup) so tests can flip it across test methods
+    /// without stale-cache surprises.
+    public static func resolveLocalHome() -> String {
+        if let override = scarfHermesHomeOverride() {
+            return override
+        }
+        return refreshIfNeeded().home
+    }
+
+    /// Name of the active profile — `"default"` or the profile id.
+    /// Surfaced in UI chrome so users can see which profile Scarf is
+    /// reading from (issue #50 follow-up: prevents the next variant
+    /// of "where's my data — wrong profile" by making it visible).
+    public static func activeProfileName() -> String {
+        if scarfHermesHomeOverride() != nil {
+            return "test-override"
+        }
+        return refreshIfNeeded().name
+    }
+
+    /// Sentinel filename that the override path MUST contain for the
+    /// override to be honored. Without it, production code refuses to
+    /// pivot off the user's real `~/.hermes` even if the env var is
+    /// set. This is the "even if a test leaks the env var, even if
+    /// some non-test process inherits it, the user's data is safe"
+    /// belt-and-braces guard. Tests create this marker before
+    /// `setenv("SCARF_HERMES_HOME", ...)`.
+    public static let testHomeMarkerFilename = ".scarf-test-home-marker"
+
+    /// Read `SCARF_HERMES_HOME` from the environment. Returns `nil` when
+    /// unset or empty so production callers fall through to the profile
+    /// resolver. The override must:
+    ///   1. Be an absolute path — relative paths are rejected (they'd
+    ///      land relative to the cwd of whatever process happened to
+    ///      invoke the resolver, which is not what tests want).
+    ///   2. Contain the sentinel marker file
+    ///      `<path>/<testHomeMarkerFilename>`. Without the marker we
+    ///      treat the env var as untrusted and ignore it. This protects
+    ///      the user's real `~/.hermes/` from any code path that
+    ///      accidentally exports `SCARF_HERMES_HOME` to the wrong value
+    ///      (e.g. a test crashed mid-teardown, an env var inherited
+    ///      from a parent shell, a misconfigured launchctl plist).
+    /// Both checks are cheap — `FileManager.fileExists` against a
+    /// known path is microseconds. The override is hot but not
+    /// hot-hot, so an extra stat per call is negligible.
+    private static func scarfHermesHomeOverride() -> String? {
+        guard let raw = ProcessInfo.processInfo.environment["SCARF_HERMES_HOME"] else {
+            return nil
+        }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        guard trimmed.hasPrefix("/") else {
+            logger.warning("SCARF_HERMES_HOME=\(trimmed, privacy: .public) is not absolute; ignoring.")
+            return nil
+        }
+        let markerPath = trimmed + "/" + testHomeMarkerFilename
+        guard FileManager.default.fileExists(atPath: markerPath) else {
+            logger.warning("SCARF_HERMES_HOME=\(trimmed, privacy: .public) lacks sentinel marker (\(testHomeMarkerFilename, privacy: .public)); ignoring to protect real ~/.hermes.")
+            return nil
+        }
+        return trimmed
+    }
+
+    /// Force a re-read on the next call, regardless of TTL. Test helper.
+    public static func invalidateCache() {
+        lock.withLock { $0.resolvedAt = .distantPast }
+    }
+
+    // MARK: - Internals
+
+    private static func refreshIfNeeded() -> (name: String, home: String) {
+        let now = Date()
+        let snapshot = lock.withLock { state -> CacheState? in
+            if now.timeIntervalSince(state.resolvedAt) < cacheTTL {
+                return state
+            }
+            return nil
+        }
+        if let snapshot {
+            return (snapshot.resolvedName, snapshot.resolvedHome)
+        }
+
+        let (name, home) = readActiveProfileFromDisk()
+        lock.withLock { state in
+            state.resolvedName = name
+            state.resolvedHome = home
+            state.resolvedAt = now
+        }
+        return (name, home)
+    }
+
+    private static func readActiveProfileFromDisk() -> (name: String, home: String) {
+        let defaultHome = defaultRootHome()
+        let activeFile = defaultHome + "/active_profile"
+
+        // Absent file → default profile. Common case for users who
+        // haven't run `hermes profile use ...`. We still log at
+        // `.info` (key=value, not warning) so support requests can
+        // pull `log show … | grep ProfileResolver` and confirm the
+        // resolver IS running and IS resolving to the default —
+        // distinguishing "feature didn't fire" from "feature fired
+        // and chose default" (issue #70).
+        guard FileManager.default.fileExists(atPath: activeFile) else {
+            logger.info("Resolved active Hermes profile: name=default, home=\(defaultHome, privacy: .public), source=default-no-file")
+            return ("default", defaultHome)
+        }
+
+        guard let raw = try? String(contentsOfFile: activeFile, encoding: .utf8) else {
+            logger.warning("Found active_profile but could not read it; falling back to default. home=\(defaultHome, privacy: .public)")
+            return ("default", defaultHome)
+        }
+
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        // Empty file or explicit "default" → default profile.
+        if trimmed.isEmpty || trimmed == "default" {
+            logger.info("Resolved active Hermes profile: name=default, home=\(defaultHome, privacy: .public), source=file-default")
+            return ("default", defaultHome)
+        }
+
+        // Validate format. Hermes itself rejects malformed names, so this
+        // would only fire if the file is corrupted or hand-edited.
+        let range = NSRange(trimmed.startIndex..<trimmed.endIndex, in: trimmed)
+        guard profileNameRegex.firstMatch(in: trimmed, range: range) != nil else {
+            logger.warning("active_profile contains invalid name \(trimmed, privacy: .public); falling back to default profile.")
+            return ("default", defaultHome)
+        }
+
+        let profileHome = defaultHome + "/profiles/" + trimmed
+        var isDir: ObjCBool = false
+        guard FileManager.default.fileExists(atPath: profileHome, isDirectory: &isDir), isDir.boolValue else {
+            logger.warning("active_profile points to \(trimmed, privacy: .public) but \(profileHome, privacy: .public) does not exist; falling back to default profile.")
+            return ("default", defaultHome)
+        }
+
+        logger.info("Resolved active Hermes profile: name=\(trimmed, privacy: .public), home=\(profileHome, privacy: .public), source=file")
+        return (trimmed, profileHome)
+    }
+
+    /// Pre-profile default hermes home (`~/.hermes`). The reference point
+    /// for both the active_profile lookup and the fallback case.
+    fileprivate static func defaultRootHome() -> String {
+        let user = ProcessInfo.processInfo.environment["HOME"] ?? NSHomeDirectory()
+        return user + "/.hermes"
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ImageEncoder.swift

@@ -0,0 +1,167 @@
+import Foundation
+#if canImport(AppKit)
+import AppKit
+#endif
+#if canImport(UIKit)
+import UIKit
+#endif
+#if canImport(CoreImage)
+import CoreImage
+#endif
+
+/// Downsamples + base64-encodes user-supplied images for ACP transport.
+///
+/// **Why downsample on the producer side.** Hermes happily forwards the
+/// bytes to a vision model, but a 12 MP screenshot at 4 MB is wasteful
+/// — it eats 5–6× more tokens than a 1024×1024 thumbnail and gives the
+/// model no extra signal. Cap the long edge at 1568 px (Anthropic's
+/// recommended max for Claude vision) and drop quality to JPEG 0.85,
+/// which keeps screenshot text crisp while landing under ~300 KB per
+/// image. The 5-image-per-message limit (chosen on the producer side)
+/// keeps the total prompt payload below ~2 MB.
+///
+/// **Why detached.** Image loading + downsampling is CPU-bound. Run only
+/// from a `Task.detached` context (the encoder type is `Sendable` and
+/// every method is `nonisolated`). The companion `ChatImageAttachment`
+/// is a Sendable value type so the result hops back to MainActor cleanly.
+public struct ImageEncoder: Sendable {
+    /// Long-edge pixel cap. 1568 is Anthropic's recommended ceiling for
+    /// Claude vision input — past it, the provider downsamples server-side
+    /// and we just paid for the extra bytes. Tweak only with vision-model
+    /// guidance from Hermes side.
+    public static let maxLongEdge: CGFloat = 1568
+    /// JPEG quality factor. 0.85 is the inflection point above which
+    /// file size jumps quickly without obvious visual gain on screenshots
+    /// or photographs.
+    public static let jpegQuality: CGFloat = 0.85
+    /// Long-edge cap for the inline thumbnail rendered in the composer
+    /// chip. Kept under the system thumbnail size so `Image(data:)`
+    /// renders without extra resampling.
+    public static let thumbnailLongEdge: CGFloat = 256
+
+    public init() {}
+
+    public enum EncoderError: Error, LocalizedError {
+        case unsupportedFormat
+        case decodeFailed
+        case encodeFailed
+        case empty
+
+        public var errorDescription: String? {
+            switch self {
+            case .unsupportedFormat: return "Image format not recognized"
+            case .decodeFailed: return "Couldn't decode image data"
+            case .encodeFailed: return "Couldn't encode image as JPEG"
+            case .empty: return "Image data was empty"
+            }
+        }
+    }
+
+    /// Encode raw bytes (from a paste/drop/picker) into a wire-ready
+    /// attachment. Detached-only — never call from MainActor. The
+    /// originating bytes are not retained beyond this call.
+    public nonisolated func encode(
+        rawBytes: Data,
+        sourceFilename: String? = nil
+    ) throws -> ChatImageAttachment {
+        guard !rawBytes.isEmpty else { throw EncoderError.empty }
+        ScarfMon.event(.render, "imageEncoder.input.bytes", count: 1, bytes: rawBytes.count)
+        return try ScarfMon.measure(.render, "imageEncoder.downsample") {
+        #if canImport(AppKit)
+        guard let nsImage = NSImage(data: rawBytes) else { throw EncoderError.decodeFailed }
+        let targetSize = Self.fittedSize(for: nsImage.size, maxLongEdge: Self.maxLongEdge)
+        let mainData = try Self.jpegBytes(from: nsImage, size: targetSize)
+        let thumbSize = Self.fittedSize(for: nsImage.size, maxLongEdge: Self.thumbnailLongEdge)
+        let thumbData = try? Self.jpegBytes(from: nsImage, size: thumbSize)
+        ScarfMon.event(.render, "imageEncoder.bytes", count: 1, bytes: mainData.count)
+        return ChatImageAttachment(
+            mimeType: "image/jpeg",
+            base64Data: mainData.base64EncodedString(),
+            thumbnailBase64: thumbData?.base64EncodedString(),
+            filename: sourceFilename,
+            approximateByteCount: mainData.count
+        )
+
+        #elseif canImport(UIKit)
+        guard let uiImage = UIImage(data: rawBytes) else { throw EncoderError.decodeFailed }
+        let targetSize = Self.fittedSize(for: uiImage.size, maxLongEdge: Self.maxLongEdge)
+        let mainData = try Self.jpegBytes(from: uiImage, size: targetSize)
+        let thumbSize = Self.fittedSize(for: uiImage.size, maxLongEdge: Self.thumbnailLongEdge)
+        let thumbData = try? Self.jpegBytes(from: uiImage, size: thumbSize)
+        ScarfMon.event(.render, "imageEncoder.bytes", count: 1, bytes: mainData.count)
+        return ChatImageAttachment(
+            mimeType: "image/jpeg",
+            base64Data: mainData.base64EncodedString(),
+            thumbnailBase64: thumbData?.base64EncodedString(),
+            filename: sourceFilename,
+            approximateByteCount: mainData.count
+        )
+
+        #else
+        // Linux CI / unknown platforms: pass through raw bytes if the
+        // input already looks like a JPEG, else refuse. Keeps the
+        // package compiling without a hard AppKit/UIKit dep.
+        if rawBytes.starts(with: [0xFF, 0xD8]) {
+            ScarfMon.event(.render, "imageEncoder.bytes", count: 1, bytes: rawBytes.count)
+            return ChatImageAttachment(
+                mimeType: "image/jpeg",
+                base64Data: rawBytes.base64EncodedString(),
+                thumbnailBase64: nil,
+                filename: sourceFilename,
+                approximateByteCount: rawBytes.count
+            )
+        }
+        throw EncoderError.unsupportedFormat
+        #endif
+        }
+    }
+
+    nonisolated private static func fittedSize(for source: CGSize, maxLongEdge: CGFloat) -> CGSize {
+        let longest = max(source.width, source.height)
+        if longest <= maxLongEdge { return source }
+        let scale = maxLongEdge / longest
+        return CGSize(
+            width: floor(source.width * scale),
+            height: floor(source.height * scale)
+        )
+    }
+
+    #if canImport(AppKit)
+    nonisolated private static func jpegBytes(from image: NSImage, size: CGSize) throws -> Data {
+        let resized = NSImage(size: size)
+        resized.lockFocus()
+        NSGraphicsContext.current?.imageInterpolation = .high
+        image.draw(
+            in: CGRect(origin: .zero, size: size),
+            from: .zero,
+            operation: .copy,
+            fraction: 1.0
+        )
+        resized.unlockFocus()
+        guard let tiff = resized.tiffRepresentation,
+              let rep = NSBitmapImageRep(data: tiff),
+              let data = rep.representation(
+                using: .jpeg,
+                properties: [.compressionFactor: jpegQuality]
+              )
+        else {
+            throw EncoderError.encodeFailed
+        }
+        return data
+    }
+    #elseif canImport(UIKit)
+    nonisolated private static func jpegBytes(from image: UIImage, size: CGSize) throws -> Data {
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = 1
+        format.opaque = true
+        let renderer = UIGraphicsImageRenderer(size: size, format: format)
+        let resized = renderer.image { _ in
+            image.draw(in: CGRect(origin: .zero, size: size))
+        }
+        guard let data = resized.jpegData(compressionQuality: jpegQuality) else {
+            throw EncoderError.encodeFailed
+        }
+        return data
+    }
+    #endif
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ModelCatalogService.swift

@@ -169,6 +169,23 @@ public struct ModelCatalogService: Sendable {
         Self.overlayOnlyProviders[providerID]
     }
 
+    /// Async wrapper around `loadProviders()` for use from MainActor view
+    /// code. The sync method does a transport-backed file read that on a
+    /// remote SSH context can take 1–2 minutes (ControlMaster setup +
+    /// pulling the multi-megabyte models.dev JSON), and on local contexts
+    /// still parses ~1500 models — both unsuitable for the main thread.
+    /// Issue #59. Existing call sites (tests, any non-View consumers)
+    /// can keep using the sync method.
+    public nonisolated func loadProvidersAsync() async -> [HermesProviderInfo] {
+        await Task.detached { [self] in
+            let providers = ScarfMon.measure(.diskIO, "modelCatalog.loadProviders") {
+                self.loadProviders()
+            }
+            ScarfMon.event(.diskIO, "modelCatalog.providers.count", count: providers.count)
+            return providers
+        }.value
+    }
+
     /// Models for one provider, sorted by release date (newest first), then name.
     public func loadModels(for providerID: String) -> [HermesModelInfo] {
         guard let catalog = loadCatalog(), let provider = catalog[providerID] else { return [] }
@@ -198,6 +215,21 @@ public struct ModelCatalogService: Sendable {
         }
     }
 
+    /// Async wrapper around `loadModels(for:)`. Same rationale as
+    /// `loadProvidersAsync()` — the View call site that fires on every
+    /// provider-switch click in the picker sheet was reading the catalog
+    /// synchronously on the MainActor, freezing the UI on remote contexts.
+    /// Issue #59.
+    public nonisolated func loadModelsAsync(for providerID: String) async -> [HermesModelInfo] {
+        await Task.detached { [self] in
+            let models = ScarfMon.measure(.diskIO, "modelCatalog.loadModels") {
+                self.loadModels(for: providerID)
+            }
+            ScarfMon.event(.diskIO, "modelCatalog.models.count", count: models.count)
+            return models
+        }.value
+    }
+
     /// Find the provider that ships a given model ID. Useful for auto-syncing
     /// provider when the user picks a model from a flat list or types one in.
     public func provider(for modelID: String) -> HermesProviderInfo? {
@@ -311,47 +343,49 @@ public struct ModelCatalogService: Sendable {
     /// Nous's catalog has no such model and Hermes later failed with
     /// HTTP 404 at runtime. Catch that at save time, not 6 hours later.
     public func validateModel(_ modelID: String, for providerID: String) -> ModelValidation {
-        let trimmed = modelID.trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !trimmed.isEmpty else {
-            return .invalid(providerName: providerID, suggestions: [])
-        }
+        ScarfMon.measure(.diskIO, "modelCatalog.validateModel") {
+            let trimmed = modelID.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else {
+                return .invalid(providerName: providerID, suggestions: [])
+            }
 
-        // Overlay-only providers (Nous Portal, OpenAI Codex, Qwen
-        // OAuth, …) serve their own catalogs that aren't mirrored to
-        // models.dev, so we don't have a reliable way to check model
-        // IDs locally. Treat any non-empty value as provisionally
-        // valid — the worst case is the runtime 404 we hit in pass-1,
-        // but the UI has the error banner now (M7 #2) to surface that
-        // cleanly.
-        //
-        // Exception: if an overlay-only provider DOES appear in the
-        // models.dev cache (unlikely but possible as catalogs evolve),
-        // we fall through to the real check below.
-        let models = loadModels(for: providerID)
-        if models.isEmpty {
-            if Self.overlayOnlyProviders[providerID] != nil {
+            // Overlay-only providers (Nous Portal, OpenAI Codex, Qwen
+            // OAuth, …) serve their own catalogs that aren't mirrored to
+            // models.dev, so we don't have a reliable way to check model
+            // IDs locally. Treat any non-empty value as provisionally
+            // valid — the worst case is the runtime 404 we hit in pass-1,
+            // but the UI has the error banner now (M7 #2) to surface that
+            // cleanly.
+            //
+            // Exception: if an overlay-only provider DOES appear in the
+            // models.dev cache (unlikely but possible as catalogs evolve),
+            // we fall through to the real check below.
+            let models = loadModels(for: providerID)
+            if models.isEmpty {
+                if Self.overlayOnlyProviders[providerID] != nil {
+                    return .valid
+                }
+                return .unknownProvider(providerID: providerID)
+            }
+
+            if models.contains(where: { $0.modelID == trimmed }) {
                 return .valid
             }
-            return .unknownProvider(providerID: providerID)
-        }
 
-        if models.contains(where: { $0.modelID == trimmed }) {
-            return .valid
+            // No exact match — offer the closest names (by prefix) as
+            // suggestions. Up to 5, ordered by release date (newest
+            // first — already the sort order of loadModels).
+            let lowerTrimmed = trimmed.lowercased()
+            let byPrefix = models
+                .filter { $0.modelID.lowercased().hasPrefix(String(lowerTrimmed.prefix(3))) }
+                .prefix(5)
+                .map(\.modelID)
+            let suggestions = byPrefix.isEmpty
+                ? Array(models.prefix(5).map(\.modelID))
+                : Array(byPrefix)
+            let providerName = providerByID(providerID)?.providerName ?? providerID
+            return .invalid(providerName: providerName, suggestions: suggestions)
         }
-
-        // No exact match — offer the closest names (by prefix) as
-        // suggestions. Up to 5, ordered by release date (newest
-        // first — already the sort order of loadModels).
-        let lowerTrimmed = trimmed.lowercased()
-        let byPrefix = models
-            .filter { $0.modelID.lowercased().hasPrefix(String(lowerTrimmed.prefix(3))) }
-            .prefix(5)
-            .map(\.modelID)
-        let suggestions = byPrefix.isEmpty
-            ? Array(models.prefix(5).map(\.modelID))
-            : Array(byPrefix)
-        let providerName = providerByID(providerID)?.providerName ?? providerID
-        return .invalid(providerName: providerName, suggestions: suggestions)
     }
 
     // MARK: - Decoding
@@ -401,15 +435,17 @@ public struct ModelCatalogService: Sendable {
 
     // MARK: - Hermes overlay providers
 
-    /// The six providers Hermes surfaces via `hermes model` that have no
+    /// The 11 providers Hermes surfaces via `hermes model` that have no
     /// entry in `models_dev_cache.json` (models.dev doesn't mirror them).
     /// Mirrors the overlay-only subset of `HERMES_OVERLAYS` in
-    /// `hermes-agent/hermes_cli/providers.py`. The other ~19 overlay entries
+    /// `hermes-agent/hermes_cli/providers.py`. The other overlay entries
     /// already ship in the cache and only add augmentation (base-URL
     /// override, extra env vars) that Scarf doesn't currently display.
     ///
-    /// Keep this in sync with the Python side on Hermes version bumps.
-    static let overlayOnlyProviders: [String: HermesProviderOverlay] = [
+    /// Keep this in sync with the Python side on Hermes version bumps —
+    /// see `ToolGatewayTests.v012OverlayProvidersCarryCorrectAuthTypes`
+    /// for the auth-type lock-in.
+    public static let overlayOnlyProviders: [String: HermesProviderOverlay] = [
         "nous": HermesProviderOverlay(
             displayName: "Nous Portal",
             baseURL: "https://inference-api.nousresearch.com/v1",
@@ -452,6 +488,53 @@ public struct ModelCatalogService: Sendable {
             subscriptionGated: false,
             docURL: nil
         ),
+        // -- v0.12 additions ---------------------------------------------
+        // Hermes v2026.4.30 added five overlay-only providers that
+        // models.dev doesn't mirror. Provider IDs match HERMES_OVERLAYS
+        // verbatim — drift here means the picker can't reach them.
+        "gmi": HermesProviderOverlay(
+            displayName: "GMI Cloud",
+            baseURL: "https://api.gmi-serving.com/v1",
+            authType: .apiKey,
+            subscriptionGated: false,
+            docURL: nil
+        ),
+        "azure-foundry": HermesProviderOverlay(
+            displayName: "Azure AI Foundry",
+            // Base URL is per-tenant — Hermes resolves it from the
+            // AZURE_FOUNDRY_BASE_URL env var at runtime. Leave nil so the
+            // settings UI shows "Tenant URL — set via env" instead of a
+            // misleading default.
+            baseURL: nil,
+            authType: .apiKey,
+            subscriptionGated: false,
+            docURL: nil
+        ),
+        "lmstudio": HermesProviderOverlay(
+            displayName: "LM Studio",
+            // v0.12 promotes LM Studio from custom-endpoint alias to a
+            // first-class provider. 1234 is the LM Studio default port;
+            // users with a non-default port set LM_BASE_URL.
+            baseURL: "http://127.0.0.1:1234/v1",
+            authType: .apiKey,
+            subscriptionGated: false,
+            docURL: nil
+        ),
+        "minimax-oauth": HermesProviderOverlay(
+            displayName: "MiniMax (OAuth)",
+            baseURL: "https://api.minimax.io/anthropic",
+            authType: .oauthExternal,
+            subscriptionGated: false,
+            docURL: nil
+        ),
+        "tencent-tokenhub": HermesProviderOverlay(
+            displayName: "Tencent TokenHub",
+            // Resolved from TOKENHUB_BASE_URL at runtime.
+            baseURL: nil,
+            authType: .apiKey,
+            subscriptionGated: false,
+            docURL: nil
+        ),
     ]
 }
 

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ModelPreflight.swift

@@ -0,0 +1,97 @@
+import Foundation
+
+/// Pre-flight check used before opening an ACP session. Hermes resolves the
+/// model+provider from `config.yaml` at session boot; on a fresh install that
+/// file is missing or has neither key set, and the chat fails with an opaque
+/// "Model parameter is required" 400 from the upstream provider only after the
+/// user has typed a prompt and hit send. Catching the missing config here lets
+/// the UI surface a real "pick a model" sheet before any ACP work starts.
+///
+/// `HermesConfig.empty` (returned on read failure) and the YAML parser's
+/// missing-key fallback both use the literal string `"unknown"`, so the check
+/// has to treat `""` and `"unknown"` as equivalent. Anything else is
+/// considered configured — we don't try to validate the model against the
+/// provider's catalog here; that happens later in `ModelPickerSheet`.
+public enum ModelPreflight: Sendable {
+    public enum Result: Equatable, Sendable {
+        case configured
+        case missingModel
+        case missingProvider
+        case missingBoth
+
+        public var isConfigured: Bool {
+            self == .configured
+        }
+
+        /// Short user-facing reason. Long enough to be honest, short enough
+        /// for a sheet header — full messaging belongs to the picker UI.
+        public var reason: String {
+            switch self {
+            case .configured:     return ""
+            case .missingModel:   return "No primary model is set in this server's config."
+            case .missingProvider:return "No primary provider is set in this server's config."
+            case .missingBoth:    return "No model is configured on this server yet."
+            }
+        }
+    }
+
+    /// Treat `""` and the YAML parser's `"unknown"` fallback as missing.
+    /// Trim whitespace so a stray newline in a hand-edited config.yaml
+    /// doesn't read as "configured."
+    public static func check(_ config: HermesConfig) -> Result {
+        let modelMissing = isUnset(config.model)
+        let providerMissing = isUnset(config.provider)
+        switch (modelMissing, providerMissing) {
+        case (true, true):   return .missingBoth
+        case (true, false):  return .missingModel
+        case (false, true):  return .missingProvider
+        case (false, false): return .configured
+        }
+    }
+
+    private static func isUnset(_ value: String) -> Bool {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed.isEmpty || trimmed == "unknown"
+    }
+
+    /// Result of a `model.default` ↔ `model.provider` mismatch check.
+    /// Captures the case where `model.default` carries a `<provider>/...`
+    /// prefix that doesn't match the standalone `model.provider` key —
+    /// observed in 2026-05-05 dogfooding when switching OAuth providers
+    /// via Credential Pools left the prior provider's model name
+    /// stranded in `model.default`. Hermes can't reconcile the two and
+    /// chats die with an opaque `-32603 Internal error` at first prompt.
+    public struct Mismatch: Sendable, Equatable {
+        /// The provider prefix found in `model.default` (e.g. `"anthropic"`).
+        public let prefixProvider: String
+        /// The standalone `model.provider` value (e.g. `"nous"`).
+        public let activeProvider: String
+        /// The full `model.default` string as configured.
+        public let modelDefault: String
+        /// The bare model id (with the prefix stripped) — what the user
+        /// would see if Scarf rewrites `model.default` for them.
+        public let bareModel: String
+    }
+
+    /// Detect a `model.default` / `model.provider` mismatch. Returns
+    /// `nil` when there's no provider prefix on `model.default`, when
+    /// either field is unset, or when the prefix matches the provider.
+    /// Uses case-insensitive comparison — Hermes accepts both
+    /// `Anthropic/...` and `anthropic/...` casings in the wild.
+    public static func detectMismatch(_ config: HermesConfig) -> Mismatch? {
+        let modelDefault = config.model.trimmingCharacters(in: .whitespacesAndNewlines)
+        let activeProvider = config.provider.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !isUnset(modelDefault), !isUnset(activeProvider) else { return nil }
+        guard let slash = modelDefault.firstIndex(of: "/") else { return nil }
+        let prefix = String(modelDefault[..<slash])
+        let bare = String(modelDefault[modelDefault.index(after: slash)...])
+        guard !prefix.isEmpty, !bare.isEmpty else { return nil }
+        guard prefix.caseInsensitiveCompare(activeProvider) != .orderedSame else { return nil }
+        return Mismatch(
+            prefixProvider: prefix,
+            activeProvider: activeProvider,
+            modelDefault: modelDefault,
+            bareModel: bare
+        )
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/NousModelCatalogService.swift

@@ -0,0 +1,313 @@
+import Foundation
+import os
+
+/// One Nous Portal model as exposed by `GET /v1/models`. The shape
+/// mirrors the OpenAI-compatible response schema — Nous's inference
+/// API uses the same envelope. Optional fields stay optional because
+/// not every entry includes them; `id` is the only field we strictly
+/// need (it's what Hermes passes through to the provider).
+public struct NousModel: Codable, Equatable, Sendable, Identifiable {
+    public let id: String
+    public let owned_by: String?
+    public let created: Int?
+    /// Free-text description if the API ships one. Nous's current
+    /// catalog doesn't include this, but the field is here so future
+    /// shape changes don't drop user-visible context on the floor.
+    public let description: String?
+
+    public init(id: String, owned_by: String? = nil, created: Int? = nil, description: String? = nil) {
+        self.id = id
+        self.owned_by = owned_by
+        self.created = created
+        self.description = description
+    }
+}
+
+/// On-disk cache shape. Versioned so a future schema change can lift
+/// stale caches gracefully — bump `version` and the loader rejects
+/// anything older without trying to migrate. Stored as JSON next to
+/// the projects registry so a Hermes wipe takes it with the rest of
+/// the Scarf-owned state.
+public struct NousModelsCache: Codable, Sendable {
+    public static let currentVersion = 1
+    public let version: Int
+    public let fetchedAt: Date
+    public let models: [NousModel]
+
+    public init(version: Int = NousModelsCache.currentVersion, fetchedAt: Date, models: [NousModel]) {
+        self.version = version
+        self.fetchedAt = fetchedAt
+        self.models = models
+    }
+}
+
+/// Result of a `loadModels` call. Distinguishes "fetched fresh from
+/// the API" from "cache served, network failed" so the picker UI can
+/// surface a "could not refresh" hint without hiding the cached list.
+public enum NousModelsLoadResult: Sendable {
+    case fresh(models: [NousModel], fetchedAt: Date)
+    case cache(models: [NousModel], fetchedAt: Date, refreshError: String?)
+    case fallback(models: [NousModel], reason: String)
+}
+
+/// Fetches + caches the list of available Nous Portal models. Runs in
+/// the Scarf process (not on the remote), authenticated with the
+/// bearer token from `~/.hermes/auth.json` on the active server —
+/// `NousSubscriptionService` reads that file via the active transport,
+/// so a remote droplet's token comes back over SSH and the network
+/// call to Nous still happens from the user's Mac. That's correct:
+/// we want the model list visible whenever the user has subscription
+/// credentials, regardless of where Hermes will eventually run the
+/// chat from.
+public struct NousModelCatalogService: Sendable {
+    public static let baseURL = URL(string: "https://inference-api.nousresearch.com/v1/models")!
+    public static let cacheTTL: TimeInterval = 24 * 60 * 60   // 24h
+    public static let requestTimeout: TimeInterval = 10        // seconds
+
+    /// Hard-coded fallback for offline-with-no-cache. Short on purpose
+    /// — only the canonical Hermes models (the family the user is most
+    /// likely to want) plus a reminder that fresh data is one
+    /// successful refresh away. Update when Nous releases a new
+    /// flagship; deliberately not exhaustive — the API is the source
+    /// of truth, this just keeps the picker non-empty.
+    public static let fallbackModels: [NousModel] = [
+        NousModel(id: "Hermes-3-Llama-3.1-405B"),
+        NousModel(id: "Hermes-3-Llama-3.1-70B"),
+        NousModel(id: "Hermes-3-Llama-3.1-8B"),
+        NousModel(id: "DeepHermes-3-Llama-3-8B-Preview")
+    ]
+
+    private static let logger = Logger(subsystem: "com.scarf", category: "NousModelCatalogService")
+
+    public let context: ServerContext
+    private let session: URLSession
+    private let cachePath: String
+
+    public init(context: ServerContext, session: URLSession = .shared) {
+        self.context = context
+        self.session = session
+        self.cachePath = context.paths.nousModelsCache
+    }
+
+    // MARK: - Cache I/O
+
+    /// Read the cache via the active transport (so a remote droplet's
+    /// cache lands on the droplet, not the user's Mac). Missing or
+    /// malformed cache → nil; the loader treats that as "no cache" and
+    /// kicks off a fresh fetch.
+    /// Race readCache against a sleep so a hung remote `cat` doesn't
+    /// stall the picker for the full transport-level timeout (60 s).
+    /// On timeout returns nil — the caller treats that as "no usable
+    /// cache" and falls through to the network fetch.
+    public func readCacheWithTimeout(seconds: TimeInterval) async -> NousModelsCache? {
+        await withTaskGroup(of: NousModelsCache?.self) { group in
+            group.addTask { [self] in
+                // Detached because readCache is sync + does blocking
+                // SSH I/O; running on the cooperative pool is fine
+                // for one task but we don't want to fight executor
+                // scheduling with the timer task below.
+                await Task.detached { [self] in
+                    readCache()
+                }.value
+            }
+            group.addTask {
+                try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+                ScarfMon.event(.diskIO, "nous.readCache.timeoutFired", count: 1)
+                return nil
+            }
+            // First completion wins; cancel the other.
+            let first = await group.next() ?? nil
+            group.cancelAll()
+            return first
+        }
+    }
+
+    public func readCache() -> NousModelsCache? {
+        ScarfMon.measure(.diskIO, "nous.readCache") {
+            let transport = context.makeTransport()
+            // Split into separate measure points so the next perf
+            // capture localizes the 60-second observed beach ball
+            // — was it the fileExists probe, the read itself, or
+            // the JSON decode? Each on its own ScarfMon row.
+            let exists = ScarfMon.measure(.diskIO, "nous.readCache.fileExists") {
+                transport.fileExists(cachePath)
+            }
+            guard exists else { return nil }
+            do {
+                let data = try ScarfMon.measure(.diskIO, "nous.readCache.readFile") {
+                    try transport.readFile(cachePath)
+                }
+                ScarfMon.event(.diskIO, "nous.readCache.bytes", count: 1, bytes: data.count)
+                return ScarfMon.measure(.diskIO, "nous.readCache.decode") {
+                    let decoder = JSONDecoder()
+                    decoder.dateDecodingStrategy = .iso8601
+                    do {
+                        let cache = try decoder.decode(NousModelsCache.self, from: data)
+                        guard cache.version == NousModelsCache.currentVersion else {
+                            Self.logger.info("nous models cache schema mismatch (got v\(cache.version), expected v\(NousModelsCache.currentVersion)); ignoring")
+                            return Optional<NousModelsCache>.none
+                        }
+                        return cache
+                    } catch {
+                        Self.logger.warning("couldn't decode nous models cache: \(error.localizedDescription, privacy: .public)")
+                        return Optional<NousModelsCache>.none
+                    }
+                }
+            } catch {
+                Self.logger.warning("couldn't read nous models cache: \(error.localizedDescription, privacy: .public)")
+                return nil
+            }
+        }
+    }
+
+    private func writeCache(_ cache: NousModelsCache) {
+        let transport = context.makeTransport()
+        do {
+            let encoder = JSONEncoder()
+            encoder.dateEncodingStrategy = .iso8601
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            let data = try encoder.encode(cache)
+            // Make sure the parent dir exists — fresh remote installs
+            // may not yet have `~/.hermes/scarf/`. mkdir -p is cheap
+            // and idempotent on both transports.
+            let parent = (cachePath as NSString).deletingLastPathComponent
+            if !parent.isEmpty {
+                try? transport.createDirectory(parent)
+            }
+            try transport.writeFile(cachePath, data: data)
+        } catch {
+            Self.logger.warning("couldn't write nous models cache: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    public func isCacheStale(_ cache: NousModelsCache) -> Bool {
+        Date().timeIntervalSince(cache.fetchedAt) > Self.cacheTTL
+    }
+
+    // MARK: - Network fetch
+
+    /// Read the bearer token from `auth.json` on the active server.
+    /// Returns nil when the user isn't signed in to Nous, in which
+    /// case `loadModels` skips the network call and falls through to
+    /// cache or fallback.
+    private func bearerToken() -> String? {
+        // The subscription service already checks for `present`; we
+        // re-read the raw token here because we need the actual string,
+        // not just a Bool. Mirrors the SubscriptionService parse path.
+        // ScarfMon: separate `nous.bearerToken` measure point because
+        // this is the second auth.json read of the picker's open
+        // sequence (subscriptionService.loadState() did the first).
+        // Together with `nous.subscription.loadState`, total two SSH
+        // round-trips of the same file — candidate for caching.
+        ScarfMon.measure(.diskIO, "nous.bearerToken") {
+            let transport = context.makeTransport()
+            guard transport.fileExists(context.paths.authJSON) else { return nil }
+            guard let data = try? transport.readFile(context.paths.authJSON) else { return nil }
+            guard let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
+            let providers = root["providers"] as? [String: Any] ?? [:]
+            let nous = providers["nous"] as? [String: Any]
+            let token = nous?["access_token"] as? String
+            guard let token, !token.isEmpty else { return nil }
+            return token
+        }
+    }
+
+    /// Make the API call. Times out after `requestTimeout` so a hung
+    /// network doesn't block the picker indefinitely. Returns the raw
+    /// `[NousModel]` on success, throws on any HTTP / decode error so
+    /// the caller can log + fall back.
+    public func fetchModels() async throws -> [NousModel] {
+        try await ScarfMon.measureAsync(.transport, "nous.fetchModels") {
+            guard let token = bearerToken() else {
+                throw NousModelCatalogError.notAuthenticated
+            }
+            var request = URLRequest(url: Self.baseURL)
+            request.httpMethod = "GET"
+            request.timeoutInterval = Self.requestTimeout
+            request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+            request.setValue("application/json", forHTTPHeaderField: "Accept")
+
+            let (data, response) = try await session.data(for: request)
+            guard let http = response as? HTTPURLResponse else {
+                throw NousModelCatalogError.transport("non-HTTP response")
+            }
+            guard (200..<300).contains(http.statusCode) else {
+                throw NousModelCatalogError.http(status: http.statusCode)
+            }
+            struct Envelope: Decodable { let data: [NousModel] }
+            let envelope = try JSONDecoder().decode(Envelope.self, from: data)
+            ScarfMon.event(.transport, "nous.fetchModels.bytes", count: envelope.data.count, bytes: data.count)
+            return envelope.data
+        }
+    }
+
+    // MARK: - Public entry
+
+    /// Top-level "give me models" entry point. Cache-first: serve from
+    /// cache if fresh, fetch + write through if stale or empty, fall
+    /// back to the hard-coded list when both fail. The caller renders
+    /// based on the case so it can show a "could not refresh" hint
+    /// next to a stale-but-still-useful list.
+    public func loadModels(forceRefresh: Bool = false) async -> NousModelsLoadResult {
+        // Cache-read with a short timeout. The underlying SSH `cat`
+        // can hang on a corrupted or oversized cache file (a
+        // 120-second picker stall observed in the wild — two 60 s
+        // timeouts stacked from a duplicated read; perf capture
+        // localized to `nous.readCache.readFile`). Cache is a
+        // performance hint, not a correctness requirement; if it
+        // doesn't return in 5 s, fall through to the network fetch
+        // and let writeCache rebuild it. The runaway `cat` keeps
+        // running on its own 60 s transport timeout but no longer
+        // blocks the picker.
+        let cached = await readCacheWithTimeout(seconds: 5)
+
+        if let cached, !forceRefresh, !isCacheStale(cached) {
+            return .cache(models: cached.models, fetchedAt: cached.fetchedAt, refreshError: nil)
+        }
+
+        do {
+            let models = try await fetchModels()
+            let now = Date()
+            writeCache(NousModelsCache(fetchedAt: now, models: models))
+            return .fresh(models: models, fetchedAt: now)
+        } catch let error as NousModelCatalogError {
+            // Fetch failed but we may still have *something* useful.
+            if let cached {
+                return .cache(
+                    models: cached.models,
+                    fetchedAt: cached.fetchedAt,
+                    refreshError: error.userMessage
+                )
+            }
+            return .fallback(models: Self.fallbackModels, reason: error.userMessage)
+        } catch {
+            if let cached {
+                return .cache(
+                    models: cached.models,
+                    fetchedAt: cached.fetchedAt,
+                    refreshError: error.localizedDescription
+                )
+            }
+            return .fallback(models: Self.fallbackModels, reason: error.localizedDescription)
+        }
+    }
+}
+
+public enum NousModelCatalogError: Error, Sendable {
+    case notAuthenticated
+    case http(status: Int)
+    case transport(String)
+
+    public var userMessage: String {
+        switch self {
+        case .notAuthenticated:
+            return "Sign in to Nous Portal to fetch the latest model list."
+        case .http(let status) where status == 401:
+            return "Nous rejected the saved token (401). Sign in again."
+        case .http(let status):
+            return "Nous returned HTTP \(status)."
+        case .transport(let detail):
+            return "Couldn't reach Nous: \(detail)."
+        }
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ProjectDashboardService.swift

@@ -15,14 +15,18 @@ public struct ProjectDashboardService: Sendable {
     // MARK: - Registry
 
     public func loadRegistry() -> ProjectRegistry {
-        guard let data = try? transport.readFile(context.paths.projectsRegistry) else {
-            return ProjectRegistry(projects: [])
-        }
-        do {
-            return try JSONDecoder().decode(ProjectRegistry.self, from: data)
-        } catch {
-            Self.logger.error("Failed to decode project registry: \(error.localizedDescription, privacy: .public)")
-            return ProjectRegistry(projects: [])
+        // Tracks time spent reading + decoding projects.json from the transport
+        // (local file or SSH). Helps spot slow remote round-trips.
+        ScarfMon.measure(.diskIO, "dashboard.loadRegistry") {
+            guard let data = try? transport.readFile(context.paths.projectsRegistry) else {
+                return ProjectRegistry(projects: [])
+            }
+            do {
+                return try JSONDecoder().decode(ProjectRegistry.self, from: data)
+            } catch {
+                Self.logger.error("Failed to decode project registry: \(error.localizedDescription, privacy: .public)")
+                return ProjectRegistry(projects: [])
+            }
         }
     }
 

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/ProjectHermesShadowDetector.swift

@@ -0,0 +1,155 @@
+import Foundation
+#if canImport(os)
+import os
+#endif
+
+/// Detects when a registered project directory contains its own `.hermes/`
+/// subdirectory. Hermes' CLI uses the closest `.hermes/` as `$HERMES_HOME`
+/// when invoked from inside such a directory, which **shadows** the user's
+/// global Hermes home — credentials, config, sessions, skills, memories
+/// all bind to the project-local copy without warning.
+///
+/// This causes confusing failure modes: the user runs `hermes auth add nous`
+/// during setup expecting a global registration, but if their cwd happens to
+/// be inside a project that already has a `.hermes/` (e.g. seeded by a
+/// previous workflow, copied from another machine, or checked into git),
+/// Hermes writes the credentials to the project-local `.hermes/auth.json`.
+/// Scarf then reads the global path on every dashboard tick and shows
+/// "missing provider" warnings even though the user did sign in successfully.
+///
+/// The detector enumerates the registered projects on a given server and
+/// reports which ones carry a shadowing `.hermes/`. Views surface a yellow
+/// banner so the user can consolidate.
+public struct ProjectHermesShadowDetector: Sendable {
+    public struct Shadow: Sendable, Hashable, Identifiable {
+        public var id: String { projectPath }
+        /// Project name from the registry (`ProjectEntry.name`).
+        public let projectName: String
+        /// Absolute path to the project on the target server.
+        public let projectPath: String
+        /// Absolute path to the shadowing `.hermes/` directory.
+        public let shadowPath: String
+        /// `true` when the shadow `.hermes/auth.json` exists. Strong signal
+        /// that user credentials are landing in the wrong place.
+        public let hasAuthJSON: Bool
+        /// `true` when the shadow `.hermes/state.db` exists. Hermes wrote
+        /// session state to the project-local home — the user's chat
+        /// history is invisible to Scarf's global Dashboard for this slice.
+        public let hasStateDB: Bool
+
+        public init(
+            projectName: String,
+            projectPath: String,
+            shadowPath: String,
+            hasAuthJSON: Bool,
+            hasStateDB: Bool
+        ) {
+            self.projectName = projectName
+            self.projectPath = projectPath
+            self.shadowPath = shadowPath
+            self.hasAuthJSON = hasAuthJSON
+            self.hasStateDB = hasStateDB
+        }
+    }
+
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf", category: "ProjectHermesShadowDetector")
+    #endif
+
+    private let context: ServerContext
+    private let transport: any ServerTransport
+
+    public init(context: ServerContext) {
+        self.context = context
+        self.transport = context.makeTransport()
+    }
+
+    /// Probe every project in `projects` for a shadowing `.hermes/`. Skips
+    /// archived projects and projects whose absolute path equals the
+    /// resolved Hermes home (rare but possible — a project literally
+    /// rooted at `~/.hermes` shouldn't trigger a self-warning).
+    public func detect(in projects: [ProjectEntry]) async -> [Shadow] {
+        let hermesHome = await context.resolvedUserHome() + "/.hermes"
+        var found: [Shadow] = []
+        for project in projects where !project.archived {
+            // A project nested inside the Hermes home itself is a weird
+            // edge case (someone made `~/.hermes/notes` a Scarf project).
+            // The project is BELOW the Hermes home, so its `.hermes` is
+            // the same dir as `~/.hermes/.hermes` — almost certainly not
+            // present and definitely not a shadow.
+            if project.path.hasPrefix(hermesHome) { continue }
+            let shadowPath = project.path + "/.hermes"
+            guard transport.fileExists(shadowPath) else { continue }
+            // It's only a shadow if the path is a directory; a stray
+            // `.hermes` file would be filtered out here.
+            guard transport.stat(shadowPath)?.isDirectory == true else { continue }
+            let hasAuth = transport.fileExists(shadowPath + "/auth.json")
+            let hasDB   = transport.fileExists(shadowPath + "/state.db")
+            #if canImport(os)
+            Self.logger.warning(
+                "Detected shadow Hermes home at \(shadowPath, privacy: .public) (auth: \(hasAuth), state.db: \(hasDB))"
+            )
+            #endif
+            found.append(Shadow(
+                projectName: project.name,
+                projectPath: project.path,
+                shadowPath: shadowPath,
+                hasAuthJSON: hasAuth,
+                hasStateDB: hasDB
+            ))
+        }
+        return found
+    }
+
+    /// Suggested shell one-liner that consolidates a project shadow into
+    /// the global Hermes home AND clears the warning on the next
+    /// refresh. Two ordered steps:
+    ///
+    /// 1. Copy `auth.json` into the global home (only when present).
+    ///    Hermes credentials live in this single file; preserving them
+    ///    is the load-bearing part of "consolidate" — every other
+    ///    project-local file is either replaceable or scoped to the
+    ///    project anyway.
+    /// 2. Rename the project-local `.hermes/` to
+    ///    `.hermes.scarf-bak.<UTC-stamp>/`. Hermes' CLI stops seeing it
+    ///    as `$HERMES_HOME` (it scans for a dir literally named
+    ///    `.hermes`), so the global home wins from now on. The
+    ///    user's project-local data — `state.db`, `sessions/`,
+    ///    `skills/` — survives untouched in the renamed folder, so
+    ///    they can inspect/recover/delete it later without us making
+    ///    that decision for them.
+    ///
+    /// **Why not delete instead of rename.** A project's shadow can
+    /// hold uncommitted session history the user hasn't audited yet.
+    /// `rm -rf` would be unrecoverable; the rename keeps everything
+    /// addressable while still removing the shadow effect. The user
+    /// can delete the `.bak` once they're confident.
+    ///
+    /// Returns a single shell line, suitable for the user to paste
+    /// into a remote terminal. The rename uses `date -u +%Y%m%d-%H%M%S`
+    /// for a deterministic UTC suffix so two consecutive consolidations
+    /// don't collide on the same second.
+    public static func consolidationCommand(for shadow: Shadow, hermesHome: String) -> String? {
+        var parts: [String] = []
+        if shadow.hasAuthJSON {
+            parts.append("mkdir -p \(shellQuote(hermesHome))")
+            parts.append("cp \(shellQuote(shadow.shadowPath + "/auth.json")) \(shellQuote(hermesHome + "/auth.json"))")
+            parts.append("chmod 600 \(shellQuote(hermesHome + "/auth.json"))")
+        }
+        // The rename is unconditional: even shadows without auth.json
+        // still bind as $HERMES_HOME and need to move out of the way.
+        // `$(date -u +%Y%m%d-%H%M%S)` runs on the remote shell when
+        // the user pastes the command, producing the timestamp at
+        // exec time rather than at command-construction time.
+        parts.append("mv \(shellQuote(shadow.shadowPath)) \(shellQuote(shadow.shadowPath))\".scarf-bak.$(date -u +%Y%m%d-%H%M%S)\"")
+        return parts.joined(separator: " && ")
+    }
+
+    /// Single-quote a path for embedding in a `bash -c '…'` string.
+    /// POSIX-safe single quotes with escape for embedded quotes
+    /// (`'` → `'\\''`). Matches the convention in
+    /// `RemoteBackupService.shellQuote`.
+    private static func shellQuote(_ s: String) -> String {
+        "'" + s.replacingOccurrences(of: "'", with: "'\\''") + "'"
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/RemoteBackupService.swift

@@ -0,0 +1,539 @@
+import Foundation
+import CryptoKit
+#if canImport(os)
+import os
+#endif
+
+/// Streams a Hermes home + project trees off a (local or remote) server
+/// into a single `.scarfbackup` archive on disk.
+///
+/// **Why not just run `hermes backup`.** Hermes's CLI captures `~/.hermes/`
+/// only; project file trees (the user's actual code) live outside that
+/// home and aren't included. A "rebuild this droplet from scratch" flow
+/// needs both. This service does both — Hermes home as one inner tarball,
+/// each registered project as its own — and writes a manifest pinning the
+/// source server, hermes version, and per-tarball SHA-256s so restore can
+/// detect corruption before it half-extracts.
+///
+/// **Memory profile.** Tarballs stream over SSH (`tar -czf -`) and into
+/// disk-backed temp files chunk-by-chunk via `streamRawBytes`. We never
+/// hold a multi-GB buffer in RAM. The final ZIP step shells out to
+/// `/usr/bin/zip`, which also streams from disk.
+///
+/// **Cleanup.** The temp dir lives under
+/// `FileManager.default.temporaryDirectory` and is removed on every exit
+/// path (success, failure, cancellation) via `defer`.
+public final class RemoteBackupService: @unchecked Sendable {
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf", category: "RemoteBackupService")
+    #endif
+
+    public let context: ServerContext
+
+    public init(context: ServerContext) {
+        self.context = context
+    }
+
+    /// Coarse stages the UI binds to. The service publishes one of these
+    /// per meaningful state change so a progress sheet can render
+    /// "Archiving Hermes home — 412 MB so far" without polling.
+    public enum Progress: Sendable, Equatable {
+        case preflight
+        case checkpointingDB
+        case archivingHermes(bytesWritten: Int64)
+        case archivingProject(name: String, bytesWritten: Int64)
+        case bundling
+        case finalizing
+    }
+
+    public enum BackupError: Error, LocalizedError {
+        case preflightFailed(String)
+        case remoteCommandFailed(String)
+        case localIO(String)
+        case zipFailed(String)
+        case cancelled
+
+        public var errorDescription: String? {
+            switch self {
+            case .preflightFailed(let m): return "Backup preflight failed: \(m)"
+            case .remoteCommandFailed(let m): return "Remote command failed during backup: \(m)"
+            case .localIO(let m): return "Local file I/O failed during backup: \(m)"
+            case .zipFailed(let m): return "Couldn't assemble the backup archive: \(m)"
+            case .cancelled: return "Backup cancelled."
+            }
+        }
+    }
+
+    /// What the UI displays before any archiving starts. Populated by
+    /// `preflight()` so the user can see (and confirm) total size +
+    /// project count + hermes version before committing 4 minutes of
+    /// SSH traffic.
+    public struct PreflightSummary: Sendable, Equatable {
+        public var hermesVersion: String?
+        public var hermesHomePath: String
+        public var hermesHomeBytes: Int64?
+        public var projects: [ProjectSummary]
+        public var sqliteAvailable: Bool
+
+        public struct ProjectSummary: Sendable, Equatable {
+            public var id: String
+            public var name: String
+            public var path: String
+            public var sizeBytes: Int64?
+            public var reachable: Bool
+        }
+
+        public var totalSizeBytes: Int64? {
+            let parts: [Int64] = [hermesHomeBytes ?? 0] + projects.compactMap { $0.sizeBytes }
+            let sum = parts.reduce(0, +)
+            return sum > 0 ? sum : nil
+        }
+    }
+
+    public struct BackupResult: Sendable {
+        public var manifest: BackupManifest
+        public var archiveURL: URL
+        public var archiveSize: Int64
+    }
+
+    /// Probe the remote (or local) before committing to the full
+    /// archive. Cheap — three short SSH calls and one file read. Safe
+    /// to call repeatedly; nothing is mutated on the source side.
+    public func preflight() async throws -> PreflightSummary {
+        let transport = context.makeTransport()
+
+        // 1. Resolve $HOME so the absolute paths in the manifest are
+        //    canonical (e.g. `/home/alan/.hermes`, not the
+        //    `~`-prefixed `HermesPathSet.home`).
+        let homeResult = try transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", "echo \"$HOME\""],
+            stdin: nil,
+            timeout: 30
+        )
+        guard homeResult.exitCode == 0 else {
+            throw BackupError.preflightFailed("Couldn't resolve remote $HOME (exit \(homeResult.exitCode)): \(homeResult.stderrString)")
+        }
+        let resolvedHome = homeResult.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        // 2. Hermes version. Optional — older builds may not implement
+        //    `--version`. Empty/missing isn't fatal; the manifest just
+        //    won't carry a version stamp.
+        let versionResult = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", "hermes --version 2>/dev/null || true"],
+            stdin: nil,
+            timeout: 30
+        )
+        let hermesVersion: String? = {
+            guard let r = versionResult, r.exitCode == 0 else { return nil }
+            let trimmed = r.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)
+            return trimmed.isEmpty ? nil : trimmed
+        }()
+
+        // 3. Hermes home size + canonical path. `context.paths.home`
+        //    can be `~/.hermes` for remotes that didn't pin
+        //    `SSHConfig.remoteHome`; tar doesn't expand `~`, so we
+        //    resolve every path against the just-fetched $HOME
+        //    BEFORE storing it in the summary. `tar -C '~'` would
+        //    fail with "No such file or directory" otherwise (and
+        //    `du -sb '~/.hermes' 2>/dev/null` swallows the same
+        //    error silently — that's why preflight looked green).
+        let hermesHome = Self.expandTilde(context.paths.home, home: resolvedHome)
+        let hermesSize = Self.estimateBytes(transport: transport, path: hermesHome)
+
+        // 4. Enumerate projects via the existing transport-aware
+        //    service. Empty registry → empty list, not an error.
+        //    Same tilde expansion as above so project paths stored
+        //    in `~/.hermes/scarf/projects.json` with `~/projects/foo`
+        //    don't blow up later in `tar -C`.
+        let registry = ProjectDashboardService(context: context).loadRegistry()
+        var projectSummaries: [PreflightSummary.ProjectSummary] = []
+        for project in registry.projects where !project.archived {
+            let expanded = Self.expandTilde(project.path, home: resolvedHome)
+            let reachable = transport.fileExists(expanded)
+            let bytes = reachable ? Self.estimateBytes(transport: transport, path: expanded) : nil
+            projectSummaries.append(PreflightSummary.ProjectSummary(
+                id: project.path,                       // path is the registry's stable handle
+                name: project.name,
+                path: expanded,
+                sizeBytes: bytes,
+                reachable: reachable
+            ))
+        }
+
+        // 5. Is `sqlite3` on PATH? Drives the WAL-checkpoint toggle.
+        //    Missing → we still archive, just without quiescing.
+        let sqliteCheck = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", "command -v sqlite3 >/dev/null 2>&1 && echo yes || echo no"],
+            stdin: nil,
+            timeout: 30
+        )
+        let sqliteAvailable = sqliteCheck?.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines) == "yes"
+
+        return PreflightSummary(
+            hermesVersion: hermesVersion,
+            hermesHomePath: hermesHome,
+            hermesHomeBytes: hermesSize,
+            projects: projectSummaries,
+            sqliteAvailable: sqliteAvailable
+        )
+    }
+
+    /// Replace a leading `~` or `~/` with the resolved remote home.
+    /// Tar (and most non-shell tools) don't expand tildes — only the
+    /// shell does, and we deliberately single-quote paths in the
+    /// command string for whitespace-safety, which then suppresses
+    /// shell expansion. So we expand here, in Swift, with a
+    /// known-good `$HOME` value.
+    static func expandTilde(_ path: String, home: String) -> String {
+        guard !home.isEmpty else { return path }
+        if path == "~" { return home }
+        if path.hasPrefix("~/") { return home + String(path.dropFirst(1)) }
+        return path
+    }
+
+    /// Run the full backup: stream Hermes home + each project tarball,
+    /// build the manifest, ZIP everything into `archiveURL`. Caller
+    /// holds the `Task` and can cancel; cooperative checks fire between
+    /// stages.
+    public func run(
+        preflight: PreflightSummary,
+        options: BackupManifest.Options,
+        archiveURL: URL,
+        progress: @Sendable @escaping (Progress) -> Void
+    ) async throws -> BackupResult {
+        let transport = context.makeTransport()
+
+        let workDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scarf-backup-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: workDir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: workDir) }
+
+        try Task.checkCancellation()
+        progress(.preflight)
+
+        // Stage 1: WAL checkpoint (best effort). Build the state.db
+        // path from the already-expanded hermesHomePath rather than
+        // `context.paths.stateDB`, which can still carry a literal
+        // `~` for remotes that didn't pin `remoteHome` — sqlite3
+        // would fail to open the file and leave the WAL un-flushed.
+        var checkpointed = false
+        if options.checkpointedWAL && preflight.sqliteAvailable {
+            progress(.checkpointingDB)
+            let stateDB = preflight.hermesHomePath + "/state.db"
+            let cmd = "sqlite3 \(Self.shellQuote(stateDB)) 'PRAGMA wal_checkpoint(TRUNCATE);' || true"
+            let result = try? transport.runProcess(
+                executable: "/bin/bash",
+                args: ["-lc", cmd],
+                stdin: nil,
+                timeout: 60
+            )
+            checkpointed = (result?.exitCode == 0)
+        }
+
+        // Stage 2: Hermes home tarball.
+        try Task.checkCancellation()
+        let hermesTarball = workDir.appendingPathComponent("hermes.tar.gz")
+        let hermesExcludes = Self.hermesExcludes(options: options)
+        let hermesTarCmd = Self.tarCommand(
+            workDir: preflight.hermesHomePath.deletingLastPathComponent_String(),
+            target: ".hermes",
+            excludes: hermesExcludes
+        )
+        let hermesHash = try await streamToFile(
+            transport: transport,
+            command: hermesTarCmd,
+            destination: hermesTarball
+        ) { written in
+            progress(.archivingHermes(bytesWritten: written))
+        }
+        let hermesSize = (try? FileManager.default.attributesOfItem(atPath: hermesTarball.path)[.size] as? Int64) ?? 0
+
+        // Stage 3: per-project tarballs.
+        let projectsDir = workDir.appendingPathComponent("projects", isDirectory: true)
+        try FileManager.default.createDirectory(at: projectsDir, withIntermediateDirectories: true)
+
+        var projectEntries: [BackupManifest.ProjectEntry] = []
+        for summary in preflight.projects where summary.reachable {
+            try Task.checkCancellation()
+            let projID = Self.stableID(forPath: summary.path)
+            let outerName = "\(projID).tar.gz"
+            let dest = projectsDir.appendingPathComponent(outerName)
+            let parent = (summary.path as NSString).deletingLastPathComponent
+            let leaf = (summary.path as NSString).lastPathComponent
+            let cmd = Self.tarCommand(
+                workDir: parent,
+                target: leaf,
+                excludes: Self.projectExcludes()
+            )
+            let hash = try await streamToFile(
+                transport: transport,
+                command: cmd,
+                destination: dest
+            ) { written in
+                progress(.archivingProject(name: summary.name, bytesWritten: written))
+            }
+            let size = (try? FileManager.default.attributesOfItem(atPath: dest.path)[.size] as? Int64) ?? 0
+            projectEntries.append(BackupManifest.ProjectEntry(
+                id: projID,
+                name: summary.name,
+                path: summary.path,
+                tarballPath: BackupArchiveLayout.projectTarballPath(for: projID),
+                tarballSize: size,
+                tarballSHA256: hash
+            ))
+        }
+
+        // Stage 4: build manifest, write to workDir.
+        try Task.checkCancellation()
+        let manifest = BackupManifest(
+            createdAt: ISO8601DateFormatter().string(from: Date()),
+            source: BackupManifest.Source(
+                serverID: context.id.uuidString,
+                displayName: context.displayName,
+                host: Self.host(for: context),
+                user: Self.user(for: context),
+                hermesVersion: preflight.hermesVersion
+            ),
+            hermes: BackupManifest.HermesTree(
+                homePath: preflight.hermesHomePath,
+                tarballPath: BackupArchiveLayout.hermesTarballPath,
+                tarballSize: hermesSize,
+                tarballSHA256: hermesHash
+            ),
+            projects: projectEntries,
+            options: BackupManifest.Options(
+                includeAuth: options.includeAuth,
+                includeMcpTokens: options.includeMcpTokens,
+                includeLogs: options.includeLogs,
+                checkpointedWAL: checkpointed
+            )
+        )
+        let manifestData: Data
+        do {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            manifestData = try encoder.encode(manifest)
+        } catch {
+            throw BackupError.localIO("Couldn't encode manifest: \(error.localizedDescription)")
+        }
+        let manifestURL = workDir.appendingPathComponent(BackupArchiveLayout.manifestPath)
+        do {
+            try manifestData.write(to: manifestURL, options: .atomic)
+        } catch {
+            throw BackupError.localIO("Couldn't write manifest: \(error.localizedDescription)")
+        }
+
+        // Stage 5: ZIP everything in workDir into the user-chosen
+        // destination. Atomic via temp file + rename so a half-written
+        // archive isn't visible.
+        try Task.checkCancellation()
+        progress(.bundling)
+        let tempArchive = archiveURL.deletingLastPathComponent()
+            .appendingPathComponent(".\(archiveURL.lastPathComponent).inflight-\(UUID().uuidString).zip")
+        try Self.zipDirectory(workDir: workDir, into: tempArchive)
+        progress(.finalizing)
+        do {
+            if FileManager.default.fileExists(atPath: archiveURL.path) {
+                try FileManager.default.removeItem(at: archiveURL)
+            }
+            try FileManager.default.moveItem(at: tempArchive, to: archiveURL)
+        } catch {
+            try? FileManager.default.removeItem(at: tempArchive)
+            throw BackupError.localIO("Couldn't move archive into place: \(error.localizedDescription)")
+        }
+
+        let archiveSize = (try? FileManager.default.attributesOfItem(atPath: archiveURL.path)[.size] as? Int64) ?? 0
+        return BackupResult(
+            manifest: manifest,
+            archiveURL: archiveURL,
+            archiveSize: archiveSize
+        )
+    }
+
+    // MARK: - Streaming
+
+    /// Spawn a remote (or local) `bash -lc <cmd>` and pump its stdout
+    /// into `destination`, computing SHA-256 incrementally as bytes
+    /// arrive. Returns the hex digest. The process gets a fresh
+    /// `bash -lc` shell on each invocation — same login-shell story
+    /// as `streamRawBytes` so PATH picks up pipx installs etc.
+    private func streamToFile(
+        transport: any ServerTransport,
+        command: String,
+        destination: URL,
+        onProgress: @Sendable @escaping (Int64) -> Void
+    ) async throws -> String {
+        FileManager.default.createFile(atPath: destination.path, contents: nil)
+        guard let fh = try? FileHandle(forWritingTo: destination) else {
+            throw BackupError.localIO("Couldn't open \(destination.lastPathComponent) for writing")
+        }
+        defer { try? fh.close() }
+        var hasher = SHA256()
+        var written: Int64 = 0
+        let stream = transport.streamRawBytes(
+            executable: "/bin/bash",
+            args: ["-lc", command]
+        )
+        do {
+            for try await chunk in stream {
+                try Task.checkCancellation()
+                try fh.write(contentsOf: chunk)
+                hasher.update(data: chunk)
+                written += Int64(chunk.count)
+                onProgress(written)
+            }
+        } catch is CancellationError {
+            throw BackupError.cancelled
+        } catch let err as TransportError {
+            throw BackupError.remoteCommandFailed(err.localizedDescription)
+        } catch {
+            throw BackupError.remoteCommandFailed(error.localizedDescription)
+        }
+        let digest = hasher.finalize()
+        return digest.map { String(format: "%02x", $0) }.joined()
+    }
+
+    // MARK: - Tar / shell helpers
+
+    private static func tarCommand(workDir: String, target: String, excludes: [String]) -> String {
+        var parts: [String] = ["tar -czf -"]
+        for ex in excludes {
+            parts.append("--exclude=\(shellQuote(ex))")
+        }
+        parts.append("-C \(shellQuote(workDir))")
+        parts.append(shellQuote(target))
+        return parts.joined(separator: " ")
+    }
+
+    /// Always-on Hermes-tree exclusions, regardless of options:
+    /// SQLite WAL siblings (would carry mid-flight writes) and runtime
+    /// state files (`gateway_state.json`).
+    private static func hermesExcludes(options: BackupManifest.Options) -> [String] {
+        var excludes: [String] = [
+            ".hermes/state.db-wal",
+            ".hermes/state.db-shm",
+            ".hermes/gateway_state.json",
+        ]
+        if !options.includeAuth { excludes.append(".hermes/auth.json") }
+        if !options.includeMcpTokens { excludes.append(".hermes/mcp-tokens") }
+        if !options.includeLogs { excludes.append(".hermes/logs") }
+        return excludes
+    }
+
+    /// Default project-tree exclusions: things that don't restore well
+    /// (compiled object stores, virtualenvs that hard-code absolute
+    /// paths, system-specific build outputs). Users can opt in via
+    /// the future "include build artefacts" toggle in the Backup
+    /// sheet — for now we always exclude these.
+    private static func projectExcludes() -> [String] {
+        [
+            "*/node_modules",
+            "*/.venv",
+            "*/venv",
+            "*/__pycache__",
+            "*/.git/objects",
+            "*/.next",
+            "*/dist",
+            "*/.DS_Store",
+        ]
+    }
+
+    /// Single-quote a path / argument for embedding in a `bash -lc`
+    /// string. Uses POSIX-safe single quotes with escape for embedded
+    /// quotes (`'` → `'\''`).
+    private static func shellQuote(_ s: String) -> String {
+        "'" + s.replacingOccurrences(of: "'", with: "'\\''") + "'"
+    }
+
+    /// Convenience: same idea as ServerContext.host, but tolerates the
+    /// local case (no host) by returning `"localhost"`.
+    private static func host(for context: ServerContext) -> String {
+        if case .ssh(let cfg) = context.kind {
+            return cfg.host
+        }
+        return "localhost"
+    }
+
+    private static func user(for context: ServerContext) -> String? {
+        if case .ssh(let cfg) = context.kind {
+            return cfg.user
+        }
+        return nil
+    }
+
+    /// `du -sb` (GNU) is the most portable way to get raw bytes —
+    /// on macOS `du -sk` returns kilobytes. Returns nil if neither
+    /// works.
+    private static func estimateBytes(transport: any ServerTransport, path: String) -> Int64? {
+        let cmd = "du -sb \(shellQuote(path)) 2>/dev/null | awk '{print $1}'"
+        guard let r = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", cmd],
+            stdin: nil,
+            timeout: 60
+        ), r.exitCode == 0 else { return nil }
+        let s = r.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)
+        return Int64(s)
+    }
+
+    /// Stable ID for a project. The project registry tracks projects
+    /// by absolute path, but paths can differ between source and
+    /// target (different `$HOME`). We hash the path to get a stable
+    /// 16-hex-char identifier that's safe to use as a tarball
+    /// filename. Collisions are vanishingly unlikely — a Mac's path
+    /// space is small and SHA-256 truncated to 64 bits has good
+    /// properties for non-adversarial input.
+    private static func stableID(forPath path: String) -> String {
+        let digest = SHA256.hash(data: Data(path.utf8))
+        let bytes = digest.map { String(format: "%02x", $0) }.joined()
+        return String(bytes.prefix(16))
+    }
+
+    /// Shell out to `/usr/bin/zip` to assemble the outer archive.
+    /// macOS ships `zip` at this fixed path so we don't need a PATH
+    /// search. `-r` recurse, `-q` quiet, `-X` strip extended attrs
+    /// for reproducibility.
+    ///
+    /// Mac-only: iOS doesn't ship `/usr/bin/zip` and Foundation's `Process`
+    /// is unavailable in the iOS SDK. The whole backup flow is a Mac-side
+    /// operation; the iOS stub throws so any accidental call surfaces a
+    /// clear message instead of an opaque link error.
+    private static func zipDirectory(workDir: URL, into archive: URL) throws {
+        #if os(iOS)
+        throw BackupError.zipFailed("Backup zip is not supported on iOS — run the backup from the Mac app.")
+        #else
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: "/usr/bin/zip")
+        proc.currentDirectoryURL = workDir
+        proc.arguments = ["-rqX", archive.path, "."]
+        let errPipe = Pipe()
+        proc.standardError = errPipe
+        proc.standardOutput = Pipe()
+        do {
+            try proc.run()
+        } catch {
+            throw BackupError.zipFailed("Couldn't launch zip: \(error.localizedDescription)")
+        }
+        proc.waitUntilExit()
+        if proc.terminationStatus != 0 {
+            let tail = (try? errPipe.fileHandleForReading.readToEnd())
+                .flatMap { String(data: $0 ?? Data(), encoding: .utf8) } ?? ""
+            throw BackupError.zipFailed("zip exited \(proc.terminationStatus): \(tail)")
+        }
+        #endif
+    }
+}
+
+// MARK: - Path helpers
+
+private extension String {
+    /// `(somePath as NSString).deletingLastPathComponent` lifted to a
+    /// String extension. Used during preflight to derive the
+    /// remote `$HOME` from `$HOME/.hermes`.
+    func deletingLastPathComponent_String() -> String {
+        (self as NSString).deletingLastPathComponent
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/RemoteRestoreService.swift

@@ -0,0 +1,501 @@
+import Foundation
+import CryptoKit
+#if canImport(os)
+import os
+#endif
+
+/// Reverses a `.scarfbackup` archive into a target server: validates,
+/// streams tarballs into place over SSH, and re-anchors path-bearing
+/// JSON sidecars so the restored Hermes home references the new layout.
+///
+/// **Validation gates.** No bytes are written to the target until the
+/// manifest's `kind` magic + `schemaVersion` match, and every inner
+/// tarball's SHA-256 matches what the manifest claims. A corrupt
+/// archive surfaces a single named-path error instead of a half-extracted
+/// home.
+///
+/// **Path re-anchoring.** Project absolute paths in
+/// `~/.hermes/scarf/projects.json` reference the source server's home
+/// (e.g. `/root/projects/foo`). After extraction the project lives at
+/// `<targetProjectsRoot>/foo`, so the restore rewrites `path` for each
+/// entry. Same logic for `<project>/.scarf/manifest.json` if it carries
+/// self-references.
+///
+/// **Cron paused on restore.** Every job in `cron/jobs.json` is flipped
+/// to `enabled = false` after restore. Restored cron jobs may carry
+/// stale credentials (Slack tokens, webhooks) or run on schedules the
+/// user no longer wants — auto-running them on a fresh droplet is
+/// surprising. The user re-enables what they want from the Cron view.
+public final class RemoteRestoreService: @unchecked Sendable {
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf", category: "RemoteRestoreService")
+    #endif
+
+    public let context: ServerContext
+
+    public init(context: ServerContext) {
+        self.context = context
+    }
+
+    public enum Progress: Sendable, Equatable {
+        case validating
+        case verifyingHashes
+        case planning
+        case restoringHermes(bytesPushed: Int64)
+        case restoringProject(name: String, bytesPushed: Int64)
+        case reanchoringPaths
+        case pausingCron
+        case finalizing
+    }
+
+    public enum RestoreError: Error, LocalizedError {
+        case archiveUnreadable(String)
+        case unsupportedSchema(Int)
+        case wrongKind(String)
+        case integrityCheckFailed(path: String, expected: String, actual: String)
+        case remoteCommandFailed(String)
+        case localIO(String)
+        case cancelled
+
+        public var errorDescription: String? {
+            switch self {
+            case .archiveUnreadable(let m): return "Couldn't read the backup archive: \(m)"
+            case .unsupportedSchema(let v): return "Backup uses schema v\(v), which this version of Scarf doesn't recognize."
+            case .wrongKind(let k): return "This file isn't a Scarf server backup (kind: \(k))."
+            case .integrityCheckFailed(let p, let exp, let act): return "Backup is corrupt — \(p) hash mismatch (expected \(exp.prefix(12))…, got \(act.prefix(12))…)."
+            case .remoteCommandFailed(let m): return "Remote command failed during restore: \(m)"
+            case .localIO(let m): return "Local file I/O failed during restore: \(m)"
+            case .cancelled: return "Restore cancelled."
+            }
+        }
+    }
+
+    /// What `inspect()` returns to drive the restore-plan sheet. The
+    /// caller picks `targetProjectsRoot`, optionally tweaks the cron
+    /// pause toggle, then calls `run()` with the same archive URL.
+    public struct InspectionResult: Sendable {
+        public var manifest: BackupManifest
+        public var workDir: URL          // unzipped temp dir; reused by run()
+        public var targetHomeResolved: String?
+        public var targetHermesVersion: String?
+    }
+
+    public struct RestoreOptions: Sendable {
+        /// Where to drop project tarballs. Each project lands at
+        /// `<targetProjectsRoot>/<basename>`. Defaults to
+        /// `<targetHome>/projects` when not specified.
+        public var targetProjectsRoot: String?
+        /// Override the resolved target home (rarely needed; the
+        /// default is whatever `bash -lc 'echo $HOME'` returned).
+        public var targetHomeOverride: String?
+        /// Pause every cron job after restore. Strongly recommended
+        /// (the user re-enables intentionally).
+        public var pauseCronJobs: Bool
+
+        public init(
+            targetProjectsRoot: String? = nil,
+            targetHomeOverride: String? = nil,
+            pauseCronJobs: Bool = true
+        ) {
+            self.targetProjectsRoot = targetProjectsRoot
+            self.targetHomeOverride = targetHomeOverride
+            self.pauseCronJobs = pauseCronJobs
+        }
+    }
+
+    public struct RestoreResult: Sendable {
+        public var manifest: BackupManifest
+        public var hermesHome: String
+        public var projectsRestored: [RestoredProject]
+        public var cronJobsPaused: Int
+
+        public struct RestoredProject: Sendable {
+            public var name: String
+            public var sourcePath: String
+            public var targetPath: String
+        }
+    }
+
+    /// Unzip + manifest-validate + hash-verify in a temp dir. Cheap
+    /// enough to call from a sheet's appearance handler so the user
+    /// sees a populated preview before committing.
+    public func inspect(archiveURL: URL) async throws -> InspectionResult {
+        let workDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scarf-restore-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: workDir, withIntermediateDirectories: true)
+
+        // Unzip outer archive.
+        try Self.unzipArchive(at: archiveURL, into: workDir)
+
+        // Decode + validate manifest.
+        let manifestURL = workDir.appendingPathComponent(BackupArchiveLayout.manifestPath)
+        guard let data = try? Data(contentsOf: manifestURL) else {
+            throw RestoreError.archiveUnreadable("missing manifest.json")
+        }
+        let manifest: BackupManifest
+        do {
+            manifest = try JSONDecoder().decode(BackupManifest.self, from: data)
+        } catch {
+            throw RestoreError.archiveUnreadable("manifest.json malformed: \(error.localizedDescription)")
+        }
+        guard manifest.kind == BackupManifest.kindMagic else {
+            throw RestoreError.wrongKind(manifest.kind)
+        }
+        guard manifest.schemaVersion == BackupManifest.currentSchemaVersion else {
+            throw RestoreError.unsupportedSchema(manifest.schemaVersion)
+        }
+
+        // Hash-verify every inner tarball before any remote bytes are
+        // pushed.
+        try await Self.verifyHash(file: workDir.appendingPathComponent(manifest.hermes.tarballPath), expected: manifest.hermes.tarballSHA256)
+        for project in manifest.projects {
+            try await Self.verifyHash(file: workDir.appendingPathComponent(project.tarballPath), expected: project.tarballSHA256)
+        }
+
+        // Probe the target for $HOME + hermes version. Doesn't fail
+        // restore if the probe times out — the user can still pick
+        // an override.
+        let transport = context.makeTransport()
+        let homeProbe = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", "echo \"$HOME\""],
+            stdin: nil,
+            timeout: 30
+        )
+        let resolvedHome = homeProbe?.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)
+        let versionProbe = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", "hermes --version 2>/dev/null || true"],
+            stdin: nil,
+            timeout: 30
+        )
+        let resolvedVersion = versionProbe?.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        return InspectionResult(
+            manifest: manifest,
+            workDir: workDir,
+            targetHomeResolved: (resolvedHome?.isEmpty == false) ? resolvedHome : nil,
+            targetHermesVersion: (resolvedVersion?.isEmpty == false) ? resolvedVersion : nil
+        )
+    }
+
+    /// Run the restore. Pushes tarballs, re-anchors paths, optionally
+    /// pauses cron. Caller owns the `workDir` URL from `inspect()` and
+    /// is responsible for cleanup if `run` throws — on success this
+    /// method removes the temp dir.
+    public func run(
+        inspection: InspectionResult,
+        options: RestoreOptions,
+        progress: @Sendable @escaping (Progress) -> Void
+    ) async throws -> RestoreResult {
+        defer { try? FileManager.default.removeItem(at: inspection.workDir) }
+        let transport = context.makeTransport()
+        let manifest = inspection.manifest
+
+        try Task.checkCancellation()
+        progress(.planning)
+
+        let targetHome = options.targetHomeOverride
+            ?? inspection.targetHomeResolved
+            ?? (manifest.hermes.homePath as NSString).deletingLastPathComponent
+        let projectsRoot = options.targetProjectsRoot ?? (targetHome + "/projects")
+
+        // Make sure the projects root exists so `tar -xzf` doesn't
+        // fail on a missing -C target.
+        let mkdirCmd = "mkdir -p \(Self.shellQuote(projectsRoot))"
+        let mkdirResult = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", mkdirCmd],
+            stdin: nil,
+            timeout: 30
+        )
+        if let r = mkdirResult, r.exitCode != 0 {
+            throw RestoreError.remoteCommandFailed("mkdir \(projectsRoot) failed: \(r.stderrString)")
+        }
+
+        // Stage 1: hermes home. Pushes into $HOME so the inner
+        // `.hermes/...` paths land at `<targetHome>/.hermes/...`.
+        try Task.checkCancellation()
+        let hermesTar = inspection.workDir.appendingPathComponent(manifest.hermes.tarballPath)
+        try await pushTarball(
+            transport: transport,
+            tarball: hermesTar,
+            extractInto: targetHome
+        ) { written in
+            progress(.restoringHermes(bytesPushed: written))
+        }
+
+        // Stage 2: per-project tarballs.
+        var restoredProjects: [RestoreResult.RestoredProject] = []
+        for project in manifest.projects {
+            try Task.checkCancellation()
+            let tar = inspection.workDir.appendingPathComponent(project.tarballPath)
+            try await pushTarball(
+                transport: transport,
+                tarball: tar,
+                extractInto: projectsRoot
+            ) { written in
+                progress(.restoringProject(name: project.name, bytesPushed: written))
+            }
+            let basename = (project.path as NSString).lastPathComponent
+            restoredProjects.append(RestoreResult.RestoredProject(
+                name: project.name,
+                sourcePath: project.path,
+                targetPath: projectsRoot + "/" + basename
+            ))
+        }
+
+        // Stage 3: re-anchor `~/.hermes/scarf/projects.json` so the
+        // restored Hermes references the new project paths instead
+        // of the source droplet's paths.
+        try Task.checkCancellation()
+        progress(.reanchoringPaths)
+        try await reanchorProjectsRegistry(
+            transport: transport,
+            targetHome: targetHome,
+            mapping: Dictionary(
+                uniqueKeysWithValues: restoredProjects.map { ($0.sourcePath, $0.targetPath) }
+            )
+        )
+
+        // Stage 4: pause cron jobs.
+        var paused = 0
+        if options.pauseCronJobs {
+            try Task.checkCancellation()
+            progress(.pausingCron)
+            paused = try await pauseAllCronJobs(transport: transport, targetHome: targetHome)
+        }
+
+        progress(.finalizing)
+        return RestoreResult(
+            manifest: manifest,
+            hermesHome: targetHome + "/.hermes",
+            projectsRestored: restoredProjects,
+            cronJobsPaused: paused
+        )
+    }
+
+    // MARK: - Push (tarball -> remote stdin)
+
+    /// Stream a local `.tar.gz` into `tar -xzf - -C <target>` on the
+    /// destination. We use `transport.makeProcess` so the command is
+    /// shell-wrapped the same way the rest of the app talks to remotes
+    /// (`bash -lc` for SSH, direct invocation for local).
+    private func pushTarball(
+        transport: any ServerTransport,
+        tarball: URL,
+        extractInto target: String,
+        onProgress: @Sendable @escaping (Int64) -> Void
+    ) async throws {
+        #if os(iOS)
+        throw RestoreError.remoteCommandFailed("Remote restore is not supported on iOS in this build.")
+        #else
+        let cmd = "tar -xzf - -C \(Self.shellQuote(target))"
+        let proc = transport.makeProcess(executable: "/bin/bash", args: ["-lc", cmd])
+
+        // standardInput: read end of an OS pipe whose write end we
+        // pump from the local tarball file. Going through a pipe (vs
+        // setting standardInput to a FileHandle directly) gives us
+        // cooperative chunk-by-chunk control + cancellation.
+        let inPipe = Pipe()
+        let outPipe = Pipe()
+        let errPipe = Pipe()
+        proc.standardInput = inPipe
+        proc.standardOutput = outPipe
+        proc.standardError = errPipe
+
+        do {
+            try proc.run()
+        } catch {
+            throw RestoreError.remoteCommandFailed("Couldn't start remote tar: \(error.localizedDescription)")
+        }
+
+        let writer = inPipe.fileHandleForWriting
+        let reader: FileHandle
+        do {
+            reader = try FileHandle(forReadingFrom: tarball)
+        } catch {
+            try? writer.close()
+            proc.terminate()
+            throw RestoreError.localIO("Couldn't open tarball: \(error.localizedDescription)")
+        }
+        defer { try? reader.close() }
+
+        var written: Int64 = 0
+        let chunkSize = 64 * 1024
+        do {
+            while true {
+                try Task.checkCancellation()
+                let chunk = reader.readData(ofLength: chunkSize)
+                if chunk.isEmpty { break }
+                try writer.write(contentsOf: chunk)
+                written += Int64(chunk.count)
+                onProgress(written)
+            }
+        } catch is CancellationError {
+            try? writer.close()
+            proc.terminate()
+            throw RestoreError.cancelled
+        } catch {
+            try? writer.close()
+            proc.terminate()
+            throw RestoreError.localIO("Couldn't pump tarball into remote: \(error.localizedDescription)")
+        }
+        try? writer.close() // signals EOF to the remote tar
+
+        proc.waitUntilExit()
+        if proc.terminationStatus != 0 {
+            let tail = (try? errPipe.fileHandleForReading.readToEnd())
+                .flatMap { $0.flatMap { String(data: $0, encoding: .utf8) } } ?? ""
+            throw RestoreError.remoteCommandFailed("tar -x exited \(proc.terminationStatus): \(tail)")
+        }
+        #endif
+    }
+
+    // MARK: - Path re-anchor
+
+    /// Rewrite each entry's `path` in `~/.hermes/scarf/projects.json`
+    /// from source-host paths to target-host paths. We do this on the
+    /// remote rather than mutating the tarball locally — the Hermes
+    /// home tarball can be GBs and re-packing would double the
+    /// transfer cost. Python is universally present on droplets and
+    /// keeps the JSON shape intact (preserves keys we don't know
+    /// about).
+    private func reanchorProjectsRegistry(
+        transport: any ServerTransport,
+        targetHome: String,
+        mapping: [String: String]
+    ) async throws {
+        guard !mapping.isEmpty else { return }
+        let registryPath = targetHome + "/.hermes/scarf/projects.json"
+        let mappingJSON: String
+        do {
+            let data = try JSONSerialization.data(withJSONObject: mapping)
+            mappingJSON = String(data: data, encoding: .utf8) ?? "{}"
+        } catch {
+            throw RestoreError.localIO("Couldn't encode path mapping: \(error.localizedDescription)")
+        }
+        let script = """
+        import json, os, sys
+        path = os.path.expanduser(\(Self.pythonQuote(registryPath)))
+        if not os.path.exists(path):
+            sys.exit(0)
+        try:
+            with open(path) as f: data = json.load(f)
+        except Exception as e:
+            print(f"projects.json parse failed: {e}", file=sys.stderr); sys.exit(1)
+        mapping = json.loads(\(Self.pythonQuote(mappingJSON)))
+        for entry in data.get('projects', []):
+            old = entry.get('path')
+            if old in mapping: entry['path'] = mapping[old]
+        with open(path, 'w') as f: json.dump(data, f, indent=2)
+        """
+        let cmd = "python3 -c \(Self.shellQuote(script))"
+        let result = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", cmd],
+            stdin: nil,
+            timeout: 60
+        )
+        if let r = result, r.exitCode != 0 {
+            throw RestoreError.remoteCommandFailed("Path re-anchor failed: \(r.stderrString)")
+        }
+    }
+
+    /// Set `enabled: false` on every cron job. Returns the count
+    /// flipped (0 if jobs.json is absent).
+    private func pauseAllCronJobs(transport: any ServerTransport, targetHome: String) async throws -> Int {
+        let path = targetHome + "/.hermes/cron/jobs.json"
+        let script = """
+        import json, os, sys
+        path = os.path.expanduser(\(Self.pythonQuote(path)))
+        if not os.path.exists(path):
+            print(0); sys.exit(0)
+        with open(path) as f: data = json.load(f)
+        count = 0
+        for job in data.get('jobs', []):
+            if job.get('enabled', False):
+                job['enabled'] = False
+                count += 1
+        with open(path, 'w') as f: json.dump(data, f, indent=2)
+        print(count)
+        """
+        let cmd = "python3 -c \(Self.shellQuote(script))"
+        let result = try? transport.runProcess(
+            executable: "/bin/bash",
+            args: ["-lc", cmd],
+            stdin: nil,
+            timeout: 60
+        )
+        if let r = result, r.exitCode == 0 {
+            let count = Int(r.stdoutString.trimmingCharacters(in: .whitespacesAndNewlines)) ?? 0
+            return count
+        }
+        return 0
+    }
+
+    // MARK: - Helpers
+
+    /// Mac-only: iOS doesn't ship `/usr/bin/unzip` and Foundation's
+    /// `Process` is unavailable in the iOS SDK. Restore is initiated from
+    /// the Mac app; the iOS stub throws so any accidental call surfaces a
+    /// clear message instead of a link-time failure.
+    private static func unzipArchive(at archive: URL, into dest: URL) throws {
+        #if os(iOS)
+        throw RestoreError.archiveUnreadable("Restore unzip is not supported on iOS — run the restore from the Mac app.")
+        #else
+        let proc = Process()
+        proc.executableURL = URL(fileURLWithPath: "/usr/bin/unzip")
+        proc.arguments = ["-q", archive.path, "-d", dest.path]
+        let errPipe = Pipe()
+        proc.standardError = errPipe
+        proc.standardOutput = Pipe()
+        do {
+            try proc.run()
+        } catch {
+            throw RestoreError.archiveUnreadable("Couldn't launch unzip: \(error.localizedDescription)")
+        }
+        proc.waitUntilExit()
+        if proc.terminationStatus != 0 {
+            let tail = (try? errPipe.fileHandleForReading.readToEnd())
+                .flatMap { $0.flatMap { String(data: $0, encoding: .utf8) } } ?? ""
+            throw RestoreError.archiveUnreadable("unzip exited \(proc.terminationStatus): \(tail)")
+        }
+        #endif
+    }
+
+    /// Hash a local file in 1 MB chunks. We avoid loading the whole
+    /// file into memory because tarballs can be multi-GB.
+    private static func verifyHash(file: URL, expected: String) async throws {
+        guard let fh = try? FileHandle(forReadingFrom: file) else {
+            throw RestoreError.archiveUnreadable("missing inner file: \(file.lastPathComponent)")
+        }
+        defer { try? fh.close() }
+        var hasher = SHA256()
+        let chunkSize = 1024 * 1024
+        while true {
+            let chunk = fh.readData(ofLength: chunkSize)
+            if chunk.isEmpty { break }
+            hasher.update(data: chunk)
+        }
+        let actual = hasher.finalize().map { String(format: "%02x", $0) }.joined()
+        if actual != expected {
+            throw RestoreError.integrityCheckFailed(path: file.lastPathComponent, expected: expected, actual: actual)
+        }
+    }
+
+    private static func shellQuote(_ s: String) -> String {
+        "'" + s.replacingOccurrences(of: "'", with: "'\\''") + "'"
+    }
+
+    /// Python source-literal quoting. Triple-quoted with backslash
+    /// escapes for embedded triple-quotes, backslashes, and the
+    /// language's own escape sequences. Used to safely embed JSON +
+    /// path strings into a `python3 -c '...'` invocation.
+    private static func pythonQuote(_ s: String) -> String {
+        let escaped = s
+            .replacingOccurrences(of: "\\", with: "\\\\")
+            .replacingOccurrences(of: "\"\"\"", with: "\\\"\\\"\\\"")
+        return "\"\"\"" + escaped + "\"\"\""
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/SecretsEnvBlock.swift

@@ -0,0 +1,251 @@
+import Foundation
+
+/// Pure block-splice logic for Scarf's managed regions inside
+/// `~/.hermes/.env`. Each registered project that has at least one
+/// resolved secret carries one block, bounded by:
+///
+/// ```
+/// # scarf-secrets:begin <slug>
+/// SCARF_<UPPER_SLUG>_<UPPER_FIELDKEY>=<value>
+/// ...
+/// # scarf-secrets:end <slug>
+/// ```
+///
+/// The Mac wraps this in `KeychainEnvMirror` (Keychain-aware, atomic
+/// write, mode-0600 enforcement). This file handles only the marker
+/// contract + key naming + splice — logic that's testable in isolation
+/// against an in-memory string and shared across hosts.
+///
+/// **Why `~/.hermes/.env`.** Hermes's cron scheduler reloads that file
+/// fresh on every tick (cron/scheduler.py:897-903), so values become
+/// available to the agent's tool-invoked subprocesses (terminal,
+/// code_exec) without any Hermes-side change. Per-project `.env` is
+/// not loaded at cron time today, hence we mirror into the global
+/// file with namespaced keys.
+///
+/// **Marker contract is load-bearing.** Both markers carry the slug on
+/// the same line so a multi-project file is parsed deterministically
+/// and one project's edits can't disturb another's block.
+public enum SecretsEnvBlock {
+
+    /// Stable across releases — entries on disk reference these
+    /// strings and a marker change would orphan every existing block.
+    public static let beginMarkerPrefix = "# scarf-secrets:begin "
+    public static let endMarkerPrefix = "# scarf-secrets:end "
+
+    // MARK: - Key naming
+
+    /// Build the env-var name for a (slug, fieldKey) pair. Uppercases,
+    /// replaces every non-alphanumeric character with `_`, prefixes
+    /// `SCARF_`. Stable: rotating a value writes to the same key.
+    public static func envKeyName(slug: String, fieldKey: String) -> String {
+        "SCARF_" + sanitize(slug) + "_" + sanitize(fieldKey)
+    }
+
+    private static func sanitize(_ s: String) -> String {
+        var out = ""
+        for scalar in s.unicodeScalars {
+            let c = Character(scalar)
+            let isAlpha = ("A"..."Z").contains(c) || ("a"..."z").contains(c)
+            let isDigit = ("0"..."9").contains(c)
+            if isAlpha || isDigit {
+                out.append(Character(scalar.properties.uppercaseMapping))
+            } else {
+                out.append("_")
+            }
+        }
+        // Collapse runs of underscores so `foo--bar` doesn't become
+        // `FOO__BAR` (two underscores trips dotenv parsers more often
+        // than one). Trim leading/trailing underscores too.
+        while out.contains("__") {
+            out = out.replacingOccurrences(of: "__", with: "_")
+        }
+        while out.hasPrefix("_") { out.removeFirst() }
+        while out.hasSuffix("_") { out.removeLast() }
+        return out.isEmpty ? "UNNAMED" : out
+    }
+
+    // MARK: - Block render
+
+    /// Render the bounded block for a single project. Empty `entries`
+    /// produces an empty string — callers should treat that as
+    /// "remove the project's block" rather than "write an empty
+    /// block." `entries` are emitted in stable sort order so two
+    /// runs with the same input produce byte-identical output.
+    public static func renderBlock(
+        slug: String,
+        entries: [(key: String, value: String)]
+    ) -> String {
+        guard !entries.isEmpty else { return "" }
+        let sorted = entries.sorted { $0.key < $1.key }
+        var lines: [String] = []
+        lines.append(beginMarkerPrefix + slug)
+        for entry in sorted {
+            lines.append("\(entry.key)=\(escape(entry.value))")
+        }
+        lines.append(endMarkerPrefix + slug)
+        return lines.joined(separator: "\n")
+    }
+
+    /// Quote values that would confuse python-dotenv: anything with
+    /// whitespace, `#`, `$`, or quote characters. Single quotes around
+    /// the value are dotenv-canonical and preserve `$`-style
+    /// references literally (no shell expansion). Backslash-escape
+    /// embedded single quotes by closing+reopening: `'foo'\''bar'`.
+    private static func escape(_ value: String) -> String {
+        let needsQuoting = value.contains(where: { c in
+            c.isWhitespace || c == "#" || c == "$" || c == "\"" || c == "'" || c == "\\"
+        })
+        if !needsQuoting { return value }
+        let escaped = value.replacingOccurrences(of: "'", with: "'\\''")
+        return "'" + escaped + "'"
+    }
+
+    // MARK: - Splice
+
+    /// Splice `block` (already-rendered, with markers) into `existing`
+    /// for the named `slug`. Three cases:
+    /// 1. `existing` already has a `# scarf-secrets:begin <slug>` /
+    ///    `# scarf-secrets:end <slug>` pair → replace the inclusive
+    ///    region. Other slugs' blocks are preserved byte-identically.
+    /// 2. `existing` has no block for this slug → append after a
+    ///    blank line at the end of file.
+    /// 3. `block` is empty → behave like `removeBlock`.
+    ///
+    /// Idempotent: feeding the output of one call back through
+    /// `applyBlock` with the same inputs produces the same string.
+    public static func applyBlock(
+        _ block: String,
+        forSlug slug: String,
+        to existing: String
+    ) -> String {
+        if block.isEmpty {
+            return removeBlock(forSlug: slug, from: existing)
+        }
+        if let region = blockRange(forSlug: slug, in: existing) {
+            // Replace the inclusive region. `blockRange` covers the
+            // begin marker line through the end marker line plus any
+            // trailing newline so `removeBlock` doesn't leave a
+            // dangling blank line — but for `applyBlock`, we need to
+            // re-emit that trailing newline so a round-trip
+            // (mirror→read→mirror with identical entries) produces
+            // byte-identical output. Without this, the second mirror
+            // would write a file shorter by one newline byte and
+            // bump the file's mtime, breaking the
+            // no-op-when-unchanged contract that the launch
+            // reconciler relies on.
+            let before = String(existing[existing.startIndex..<region.lowerBound])
+            let after = String(existing[region.upperBound..<existing.endIndex])
+            // Restore a trailing newline only when the consumed region
+            // had one (i.e., the block wasn't at end-of-string with
+            // no terminating newline).
+            let consumedTrailingNewline = region.upperBound > existing.startIndex
+                && existing[existing.index(before: region.upperBound)] == "\n"
+            let separator = consumedTrailingNewline ? "\n" : ""
+            return before + block + separator + after
+        }
+        // Append at end of file, separated from preceding content by
+        // a blank line. Empty-or-whitespace files just become the
+        // block plus a trailing newline.
+        let trimmed = existing.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return block + "\n"
+        }
+        let normalized = trimmingRightNewlines(existing)
+        return normalized + "\n\n" + block + "\n"
+    }
+
+    /// Strip the bounded block for `slug` from `existing`. No-op when
+    /// absent. Preserves all other slugs' blocks and user-authored
+    /// content byte-identically.
+    public static func removeBlock(forSlug slug: String, from existing: String) -> String {
+        guard let region = blockRange(forSlug: slug, in: existing) else {
+            return existing
+        }
+        let before = String(existing[existing.startIndex..<region.lowerBound])
+        let after = String(existing[region.upperBound..<existing.endIndex])
+        // Collapse the blank line we may have inserted at append time
+        // so repeated install/uninstall cycles don't accumulate
+        // blank lines. Specifically: if `before` ends in `\n\n` and
+        // `after` starts with `\n`, drop one of the newlines.
+        var trimmedBefore = before
+        var trimmedAfter = after
+        if trimmedBefore.hasSuffix("\n\n") && trimmedAfter.hasPrefix("\n") {
+            trimmedAfter.removeFirst()
+        } else if trimmedBefore.hasSuffix("\n\n") {
+            trimmedBefore.removeLast()
+        }
+        return trimmedBefore + trimmedAfter
+    }
+
+    // MARK: - Range scan
+
+    /// Locate the inclusive character range covering one project's
+    /// block, including a trailing newline if present so removal
+    /// doesn't leave a dangling empty line. Returns nil when the
+    /// block isn't present.
+    private static func blockRange(
+        forSlug slug: String,
+        in existing: String
+    ) -> Range<String.Index>? {
+        let beginLine = beginMarkerPrefix + slug
+        let endLine = endMarkerPrefix + slug
+        // Match begin marker as a full line — guard against false
+        // positives where a slug is a prefix of another slug
+        // (e.g. "foo" vs "foo-bar"). Require the marker to be
+        // followed immediately by `\n` or end-of-string.
+        guard let beginRange = lineRange(of: beginLine, in: existing) else {
+            return nil
+        }
+        // Search for the matching end marker AFTER the begin range —
+        // can't use a leading-anchor scan because there may be other
+        // slugs' end markers between begin and the matching end.
+        let searchStart = beginRange.upperBound
+        guard let endRange = lineRange(of: endLine, in: existing, startingAt: searchStart) else {
+            return nil
+        }
+        // Include a trailing newline if the file has one immediately
+        // after the end marker — keeps the file shape clean across
+        // remove operations.
+        var upper = endRange.upperBound
+        if upper < existing.endIndex, existing[upper] == "\n" {
+            upper = existing.index(after: upper)
+        }
+        return beginRange.lowerBound..<upper
+    }
+
+    /// Find a substring that appears as a complete line — bounded by
+    /// start-of-string or `\n` on the left and `\n` or end-of-string
+    /// on the right. Returns the range of the substring itself, not
+    /// including any surrounding newlines.
+    private static func lineRange(
+        of needle: String,
+        in haystack: String,
+        startingAt start: String.Index? = nil
+    ) -> Range<String.Index>? {
+        var searchStart = start ?? haystack.startIndex
+        while searchStart <= haystack.endIndex {
+            guard let range = haystack.range(of: needle, range: searchStart..<haystack.endIndex) else {
+                return nil
+            }
+            let leftOK = range.lowerBound == haystack.startIndex
+                || haystack[haystack.index(before: range.lowerBound)] == "\n"
+            let rightOK = range.upperBound == haystack.endIndex
+                || haystack[range.upperBound] == "\n"
+            if leftOK && rightOK {
+                return range
+            }
+            // Advance past this false positive and keep searching.
+            searchStart = range.upperBound
+        }
+        return nil
+    }
+
+    private static func trimmingRightNewlines(_ s: String) -> String {
+        var result = s
+        while let last = result.last, last.isNewline {
+            result.removeLast()
+        }
+        return result
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/SkillSnapshotService.swift

@@ -133,12 +133,20 @@ public struct SkillSnapshotDiff: Sendable, Equatable {
     }
 
     /// Compact label for the "What's New" pill, e.g.
-    /// "2 new, 4 updated since you last looked" or "1 new skill".
+    /// "2 new, 4 changed since you last looked" or "1 new skill".
+    ///
+    /// Wording note (issue #78): we used to say "X updated since you
+    /// last looked" but the same screen also surfaces an "Updates"
+    /// sub-tab driven by `hermes skills check` (skills with newer
+    /// **upstream** versions available). Two surfaces with the word
+    /// "update" meaning two different things read as a contradiction
+    /// to the user. "Changed" describes the local file delta without
+    /// colliding with upstream-update vocabulary.
     public var label: String {
         switch (newCount, updatedCount) {
         case (let n, 0): return n == 1 ? "1 new skill since you last looked" : "\(n) new skills since you last looked"
-        case (0, let u): return u == 1 ? "1 updated skill since you last looked" : "\(u) updated skills since you last looked"
-        default: return "\(newCount) new, \(updatedCount) updated since you last looked"
+        case (0, let u): return u == 1 ? "1 changed skill since you last looked" : "\(u) changed skills since you last looked"
+        default: return "\(newCount) new, \(updatedCount) changed since you last looked"
         }
     }
 }

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/SkillsScanner.swift

@@ -13,7 +13,12 @@ import os
 public enum SkillsScanner: Sendable {
     private static let logger = Logger(subsystem: "com.scarf", category: "SkillsScanner")
 
-    public static func scan(context: ServerContext, transport: any ServerTransport) -> [HermesSkillCategory] {
+    public static func scan(
+        context: ServerContext,
+        transport: any ServerTransport,
+        disabledNames: Set<String> = [],
+        pinnedNames: Set<String> = []
+    ) -> [HermesSkillCategory] {
         let dir = context.paths.skillsDir
         // Fresh install: skills/ may not exist yet — return [] without
         // logging an error.
@@ -59,7 +64,9 @@ public enum SkillsScanner: Sendable {
                             requiredConfig: requiredConfig,
                             allowedTools: v011.allowedTools,
                             relatedSkills: v011.relatedSkills,
-                            dependencies: v011.dependencies
+                            dependencies: v011.dependencies,
+                            enabled: !disabledNames.contains(skillName),
+                            pinned: pinnedNames.contains(skillName)
                         )
                     }
 

scarf/Packages/ScarfCore/Sources/ScarfCore/Services/TestModeFlags.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+/// Process-wide toggles for test-mode launches.
+///
+/// Read `CommandLine.arguments` once at first access and cache the result so
+/// any code path can ask `TestModeFlags.shared.isTestMode` without paying for
+/// a re-scan. The harness sets `--scarf-test-mode` from XCUITest's
+/// `XCUIApplication.launchArguments` and pairs it with `SCARF_HERMES_HOME`
+/// (read by `HermesProfileResolver`) to drive Scarf against an isolated
+/// Hermes home.
+///
+/// The flags themselves don't do anything on their own — they're hook points
+/// for production code paths to gate behavior. v1 lands the wiring; the
+/// gating sites (Sparkle update prompt, capability live-probe, first-run
+/// walkthrough) are added incrementally as the harness exercises them and
+/// surfaces flakes.
+public struct TestModeFlags: Sendable {
+    /// True when the process was launched with `--scarf-test-mode`. Read
+    /// once from `CommandLine.arguments`; never mutated.
+    public let isTestMode: Bool
+
+    /// Default singleton — cached on first access. Production code reads
+    /// this; tests that need a different shape construct their own value.
+    public static let shared: TestModeFlags = TestModeFlags(
+        arguments: CommandLine.arguments
+    )
+
+    /// Constructor exposed for tests so a synthetic argv can be passed
+    /// without involving the real `CommandLine`. Production callers use
+    /// `.shared`.
+    public init(arguments: [String]) {
+        self.isTestMode = arguments.contains("--scarf-test-mode")
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Transport/LocalTransport.swift

@@ -176,6 +176,55 @@ public struct LocalTransport: ServerTransport {
     }
     #endif
 
+    public func streamRawBytes(executable: String, args: [String]) -> AsyncThrowingStream<Data, Error> {
+        #if os(iOS)
+        return AsyncThrowingStream { $0.finish() }
+        #else
+        return AsyncThrowingStream { continuation in
+            Task.detached {
+                let proc = Process()
+                proc.executableURL = URL(fileURLWithPath: executable)
+                proc.arguments = args
+                let outPipe = Pipe()
+                let errPipe = Pipe()
+                proc.standardOutput = outPipe
+                proc.standardError = errPipe
+                do {
+                    try proc.run()
+                } catch {
+                    continuation.finish(throwing: error)
+                    return
+                }
+                try? outPipe.fileHandleForWriting.close()
+                try? errPipe.fileHandleForWriting.close()
+                let handle = outPipe.fileHandleForReading
+                while true {
+                    let chunk = handle.availableData
+                    if chunk.isEmpty { break }
+                    continuation.yield(chunk)
+                }
+                proc.waitUntilExit()
+                let stderrTail: String
+                if proc.terminationStatus != 0 {
+                    stderrTail = (try? errPipe.fileHandleForReading.readToEnd())
+                        .flatMap { String(data: $0 ?? Data(), encoding: .utf8) } ?? ""
+                } else {
+                    stderrTail = ""
+                }
+                try? outPipe.fileHandleForReading.close()
+                try? errPipe.fileHandleForReading.close()
+                if proc.terminationStatus != 0 {
+                    continuation.finish(throwing: TransportError.commandFailed(
+                        exitCode: proc.terminationStatus, stderr: stderrTail
+                    ))
+                } else {
+                    continuation.finish()
+                }
+            }
+        }
+        #endif
+    }
+
     public func streamLines(executable: String, args: [String]) -> AsyncThrowingStream<String, Error> {
         #if os(iOS)
         // LocalTransport doesn't run on iOS at runtime — the iOS app
@@ -240,11 +289,33 @@ public struct LocalTransport: ServerTransport {
         #endif
     }
 
-    // MARK: - SQLite
+    // MARK: - Script streaming
 
-    public func snapshotSQLite(remotePath: String) throws -> URL {
-        // Local case: no copy needed. Services open the path directly.
-        URL(fileURLWithPath: remotePath)
+    /// Run `script` through `/bin/sh -c` locally. Local data path
+    /// doesn't actually call this in production (the data service
+    /// hands `LocalSQLiteBackend` the libsqlite3-direct path) — kept
+    /// for protocol parity and for tooling that wants a uniform
+    /// "run a script" entry on either context kind.
+    public func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+        #if os(iOS)
+        throw TransportError.other(message: "LocalTransport.streamScript is unavailable on iOS")
+        #else
+        let outcome = await SSHScriptRunner.run(
+            script: script,
+            context: ServerContext(id: contextID, displayName: "Local", kind: .local),
+            timeout: timeout
+        )
+        switch outcome {
+        case .connectFailure(let reason):
+            throw TransportError.other(message: reason)
+        case .completed(let stdout, let stderr, let exitCode):
+            return ProcessResult(
+                exitCode: exitCode,
+                stdout: Data(stdout.utf8),
+                stderr: Data(stderr.utf8)
+            )
+        }
+        #endif
     }
 
     // MARK: - Watching

scarf/Packages/ScarfCore/Sources/ScarfCore/Transport/SSHScriptRunner.swift

@@ -0,0 +1,345 @@
+import Foundation
+
+/// Runs multi-line shell scripts on a server (local or SSH) without
+/// going through `ServerTransport.runProcess`.
+///
+/// **Why this exists.** `SSHTransport.runProcess` quotes every argument
+/// via `remotePathArg` (it rewrites `~/` → `$HOME/`), which is correct
+/// for path arguments but mangles a multi-line script containing
+/// `"$VAR"` references, nested quotes, and control structures. The
+/// remote receives a scrambled string and the script silently
+/// produces no useful output.
+///
+/// `RemoteDiagnosticsViewModel` originally documented this and worked
+/// around it locally. Issue #44 surfaced the same bug for the
+/// connection-status pill (multi-line probe script through
+/// `runProcess` → tier 2 always reads as failed even when the file
+/// is readable, while diagnostics — which used the workaround —
+/// reports 14/14 passing). This helper centralises the workaround so
+/// any future caller running a script gets it for free.
+///
+/// **Approach.** We invoke `/usr/bin/ssh ... -- /bin/sh -s` directly
+/// and pipe the script via stdin, so the script travels as a single
+/// opaque byte stream that the remote shell parses unchanged. Local
+/// contexts skip ssh and just pipe to `/bin/sh -s` — same shape so
+/// callers can treat both uniformly.
+public enum SSHScriptRunner {
+
+    /// Thread-safe boolean flag used to bridge parent-task cancellation
+    /// into the detached `Task` body that owns the ssh subprocess.
+    /// `Task.detached { ... }` does NOT inherit cancellation from the
+    /// awaiting parent; without this flag, cancelling a chat-load /
+    /// hydration / activity-fetch Task only throws `CancellationError`
+    /// at the chat layer while the ssh subprocess keeps running until
+    /// its 30s timeout fires — pinning a remote sqlite query (and a
+    /// ControlMaster session slot) for the full deadline. v2.8 fix
+    /// observed in 2026-05-05 dogfooding: rapid chat-switching left a
+    /// chain of stale 30s ssh subprocesses behind, blocking the
+    /// dashboard's queryBatch and producing a "spinning" load.
+    private final class CancelFlag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _cancelled = false
+        var isCancelled: Bool {
+            lock.lock(); defer { lock.unlock() }
+            return _cancelled
+        }
+        func cancel() {
+            lock.lock(); defer { lock.unlock() }
+            _cancelled = true
+        }
+    }
+
+    /// Lock-protected `Data` accumulator used by the stdout/stderr
+    /// readability handlers below. Two of these per script run, one per
+    /// stream. `@unchecked Sendable` because mutation goes through the
+    /// `NSLock` — Swift can't see that.
+    ///
+    /// Why this exists (issue #77): the previous implementation read
+    /// stdout/stderr via `readToEnd()` *after* the subprocess exited.
+    /// On macOS pipes default to a 16–64 KB kernel buffer; once
+    /// `sqlite3 -json` writes more than that, the SSH client back-
+    /// pressures over the wire, the remote sqlite3 blocks, the script
+    /// never finishes, the 30 s timeout fires, and the caller sees
+    /// "Script timed out" + an empty result set. v2.7's
+    /// `sessionListSnapshot(limit: 500)` crossed that threshold for
+    /// any user with ~150+ sessions. Draining concurrently with
+    /// `readabilityHandler` removes the back-pressure.
+    private final class LockedData: @unchecked Sendable {
+        private let lock = NSLock()
+        private var buf = Data()
+        func append(_ chunk: Data) {
+            lock.lock(); defer { lock.unlock() }
+            buf.append(chunk)
+        }
+        func snapshot() -> Data {
+            lock.lock(); defer { lock.unlock() }
+            return buf
+        }
+    }
+
+    public enum Outcome: Sendable {
+        /// Couldn't even reach the remote (process spawn failed,
+        /// timeout before any output, network refused). Carries the
+        /// human-readable reason.
+        case connectFailure(String)
+        /// Script ran to completion (or until timeout cut it short
+        /// after producing partial output). Exit code, stdout, stderr
+        /// are reported as captured.
+        case completed(stdout: String, stderr: String, exitCode: Int32)
+    }
+
+    /// Run `script` against the given context. Times out after
+    /// `timeout` seconds, killing the subprocess if it overruns.
+    ///
+    /// **Platforms.** Real implementation is macOS-only — relies on
+    /// `Foundation.Process` which iOS doesn't ship. iOS callers
+    /// (ScarfGo) use Citadel-backed SSH transports for their own
+    /// flows; they never reach this entry point. To keep ScarfCore
+    /// cross-platform we return a connect failure on non-macOS so
+    /// the file compiles everywhere.
+    public static func run(script: String, context: ServerContext, timeout: TimeInterval = 30) async -> Outcome {
+        await ScarfMon.measureAsync(.transport, "ssh.run") {
+            // Bridge parent cancellation into the detached subprocess
+            // task. Without this, killing a chat-hydration Task on a
+            // session switch only unwinds Swift state — the ssh
+            // subprocess keeps holding a remote sqlite query + a
+            // ControlMaster session for the full 30s timeout. v2.8.
+            let cancelFlag = CancelFlag()
+            return await withTaskCancellationHandler(
+                operation: {
+                    #if os(macOS)
+                    switch context.kind {
+                    case .local:
+                        return await runLocally(script: script, timeout: timeout, cancelFlag: cancelFlag)
+                    case .ssh(let config):
+                        return await runOverSSH(script: script, config: config, timeout: timeout, cancelFlag: cancelFlag)
+                    }
+                    #else
+                    return .connectFailure("SSHScriptRunner is only available on macOS")
+                    #endif
+                },
+                onCancel: {
+                    cancelFlag.cancel()
+                    ScarfMon.event(.transport, "ssh.cancelled", count: 1)
+                }
+            )
+        }
+    }
+
+    // MARK: - SSH path
+
+    #if os(macOS)
+    private static func runOverSSH(script: String, config: SSHConfig, timeout: TimeInterval, cancelFlag: CancelFlag) async -> Outcome {
+        var sshArgv: [String] = [
+            "-o", "ControlMaster=auto",
+            "-o", "ControlPath=\(SSHTransport.controlDirPath())/%C",
+            "-o", "ControlPersist=600",
+            "-o", "ServerAliveInterval=30",
+            "-o", "ConnectTimeout=10",
+            "-o", "StrictHostKeyChecking=accept-new",
+            "-o", "LogLevel=QUIET",
+            "-o", "BatchMode=yes",
+            "-T",  // no pty — keep stdin/stdout a clean byte stream
+        ]
+        if let port = config.port { sshArgv += ["-p", String(port)] }
+        if let id = config.identityFile, !id.isEmpty {
+            sshArgv += ["-i", id]
+        }
+        let hostSpec: String
+        if let user = config.user, !user.isEmpty { hostSpec = "\(user)@\(config.host)" }
+        else { hostSpec = config.host }
+        sshArgv.append(hostSpec)
+        sshArgv.append("--")
+        sshArgv.append("/bin/sh")
+        sshArgv.append("-s")  // read script from stdin
+
+        return await Task.detached { () -> Outcome in
+            let proc = Process()
+            proc.executableURL = URL(fileURLWithPath: "/usr/bin/ssh")
+            proc.arguments = sshArgv
+
+            // Inherit shell-derived SSH_AUTH_SOCK so ssh-agent reaches.
+            // Same path SSHTransport uses internally — see
+            // `environmentEnricher` set at app boot.
+            var env = ProcessInfo.processInfo.environment
+            if let enricher = SSHTransport.environmentEnricher {
+                let shellEnv = enricher()
+                for key in ["SSH_AUTH_SOCK", "SSH_AGENT_PID"] {
+                    if env[key] == nil, let v = shellEnv[key], !v.isEmpty {
+                        env[key] = v
+                    }
+                }
+            }
+            proc.environment = env
+
+            let stdinPipe = Pipe()
+            let stdoutPipe = Pipe()
+            let stderrPipe = Pipe()
+            proc.standardInput = stdinPipe
+            proc.standardOutput = stdoutPipe
+            proc.standardError = stderrPipe
+
+            // Drain stdout/stderr concurrently with the running process —
+            // see the LockedData docstring above for the issue-#77
+            // back-story. Without these handlers a >64 KB script output
+            // wedges the pipe + ssh + remote sqlite3 chain and the only
+            // visible symptom is a timeout.
+            let outBuf = LockedData()
+            let errBuf = LockedData()
+            stdoutPipe.fileHandleForReading.readabilityHandler = { handle in
+                let chunk = handle.availableData
+                if chunk.isEmpty {
+                    handle.readabilityHandler = nil
+                } else {
+                    outBuf.append(chunk)
+                }
+            }
+            stderrPipe.fileHandleForReading.readabilityHandler = { handle in
+                let chunk = handle.availableData
+                if chunk.isEmpty {
+                    handle.readabilityHandler = nil
+                } else {
+                    errBuf.append(chunk)
+                }
+            }
+
+            do {
+                try proc.run()
+            } catch {
+                stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                stderrPipe.fileHandleForReading.readabilityHandler = nil
+                return .connectFailure("Failed to launch ssh: \(error.localizedDescription)")
+            }
+
+            if let data = script.data(using: .utf8) {
+                try? stdinPipe.fileHandleForWriting.write(contentsOf: data)
+            }
+            try? stdinPipe.fileHandleForWriting.close()
+
+            let deadline = Date().addingTimeInterval(timeout)
+            while proc.isRunning && Date() < deadline {
+                // Honor BOTH the detached-task's own cancellation flag
+                // (set by the parent's `withTaskCancellationHandler`)
+                // and the legacy `Task.isCancelled` check in case the
+                // detached body gets cancelled directly. The flag is
+                // the load-bearing path; Task.isCancelled is harmless
+                // belt-and-suspenders.
+                if cancelFlag.isCancelled || Task.isCancelled {
+                    proc.terminate()
+                    stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                    stderrPipe.fileHandleForReading.readabilityHandler = nil
+                    try? stdoutPipe.fileHandleForReading.close()
+                    try? stderrPipe.fileHandleForReading.close()
+                    return .connectFailure("Script cancelled")
+                }
+                try? await Task.sleep(nanoseconds: 100_000_000)
+            }
+            if proc.isRunning {
+                proc.terminate()
+                stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                stderrPipe.fileHandleForReading.readabilityHandler = nil
+                // Pipe fds leak otherwise — closing on the timeout branch
+                // matches the success-path discipline (see CLAUDE.md
+                // "Always close both fileHandleForReading and
+                // fileHandleForWriting on Pipe objects").
+                try? stdoutPipe.fileHandleForReading.close()
+                try? stderrPipe.fileHandleForReading.close()
+                return .connectFailure("Script timed out after \(Int(timeout))s")
+            }
+            // Detach the readabilityHandlers and capture whatever the
+            // accumulator has. The handler may have already seen EOF
+            // (`chunk.isEmpty`) and self-cleared, but assigning nil is
+            // idempotent and guards against a late tick from the queue.
+            stdoutPipe.fileHandleForReading.readabilityHandler = nil
+            stderrPipe.fileHandleForReading.readabilityHandler = nil
+            let out = outBuf.snapshot()
+            let err = errBuf.snapshot()
+            // Best-effort fd close — Pipe leaks fd's otherwise.
+            try? stdoutPipe.fileHandleForReading.close()
+            try? stderrPipe.fileHandleForReading.close()
+            return .completed(
+                stdout: String(data: out, encoding: .utf8) ?? "",
+                stderr: String(data: err, encoding: .utf8) ?? "",
+                exitCode: proc.terminationStatus
+            )
+        }.value
+    }
+
+    // MARK: - Local path
+
+    private static func runLocally(script: String, timeout: TimeInterval, cancelFlag: CancelFlag) async -> Outcome {
+        return await Task.detached { () -> Outcome in
+            let proc = Process()
+            proc.executableURL = URL(fileURLWithPath: "/bin/sh")
+            proc.arguments = ["-c", script]
+
+            let stdoutPipe = Pipe()
+            let stderrPipe = Pipe()
+            proc.standardOutput = stdoutPipe
+            proc.standardError = stderrPipe
+
+            // Drain concurrently — same pipe-buffer fix as runOverSSH.
+            // Local scripts can also blow past the 16–64 KB pipe buffer
+            // (e.g. local `sqlite3 -json` over a fat result set) and
+            // would wedge in exactly the same way.
+            let outBuf = LockedData()
+            let errBuf = LockedData()
+            stdoutPipe.fileHandleForReading.readabilityHandler = { handle in
+                let chunk = handle.availableData
+                if chunk.isEmpty {
+                    handle.readabilityHandler = nil
+                } else {
+                    outBuf.append(chunk)
+                }
+            }
+            stderrPipe.fileHandleForReading.readabilityHandler = { handle in
+                let chunk = handle.availableData
+                if chunk.isEmpty {
+                    handle.readabilityHandler = nil
+                } else {
+                    errBuf.append(chunk)
+                }
+            }
+
+            do {
+                try proc.run()
+            } catch {
+                stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                stderrPipe.fileHandleForReading.readabilityHandler = nil
+                return .connectFailure("Failed to launch /bin/sh: \(error.localizedDescription)")
+            }
+            let deadline = Date().addingTimeInterval(timeout)
+            while proc.isRunning && Date() < deadline {
+                if cancelFlag.isCancelled || Task.isCancelled {
+                    proc.terminate()
+                    stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                    stderrPipe.fileHandleForReading.readabilityHandler = nil
+                    try? stdoutPipe.fileHandleForReading.close()
+                    try? stderrPipe.fileHandleForReading.close()
+                    return .connectFailure("Script cancelled")
+                }
+                try? await Task.sleep(nanoseconds: 100_000_000)
+            }
+            if proc.isRunning {
+                proc.terminate()
+                stdoutPipe.fileHandleForReading.readabilityHandler = nil
+                stderrPipe.fileHandleForReading.readabilityHandler = nil
+                try? stdoutPipe.fileHandleForReading.close()
+                try? stderrPipe.fileHandleForReading.close()
+                return .connectFailure("Script timed out after \(Int(timeout))s")
+            }
+            stdoutPipe.fileHandleForReading.readabilityHandler = nil
+            stderrPipe.fileHandleForReading.readabilityHandler = nil
+            let out = outBuf.snapshot()
+            let err = errBuf.snapshot()
+            try? stdoutPipe.fileHandleForReading.close()
+            try? stderrPipe.fileHandleForReading.close()
+            return .completed(
+                stdout: String(data: out, encoding: .utf8) ?? "",
+                stderr: String(data: err, encoding: .utf8) ?? "",
+                exitCode: proc.terminationStatus
+            )
+        }.value
+    }
+    #endif // os(macOS)
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/Transport/SSHTransport.swift

@@ -425,14 +425,18 @@ public struct SSHTransport: ServerTransport {
     public func makeProcess(executable: String, args: [String]) -> Process {
         ensureControlDir()
         // `-T` disables pty allocation — critical for binary-clean stdin/stdout
-        // (ACP JSON-RPC, log tail bytes). Same sh -c wrapping as runProcess
-        // so home-relative paths in `executable`/`args` actually expand.
+        // (ACP JSON-RPC, log tail bytes). `bash -lc` (login shell) sources the
+        // user's profile so PATH picks up pipx's `~/.local/bin`, Homebrew on
+        // Linux, asdf shims, and conda envs. Plain `sh -c` is non-login, so
+        // pipx-installed `hermes` isn't on PATH unless `hermesBinaryHint` was
+        // set explicitly — exactly the failure that surfaces as a
+        // "command not found" / opaque init timeout against fresh droplets.
         let cmd = ([executable] + args).map { Self.remotePathArg($0) }.joined(separator: " ")
         var sshArgv = sshArgs()
         sshArgv.insert("-T", at: 0)
         sshArgv.append(hostSpec)
-        sshArgv.append("sh")
-        sshArgv.append("-c")
+        sshArgv.append("bash")
+        sshArgv.append("-lc")
         sshArgv.append(Self.shellQuote(cmd))
         let proc = Process()
         proc.executableURL = URL(fileURLWithPath: sshBinary)
@@ -453,12 +457,17 @@ public struct SSHTransport: ServerTransport {
         return AsyncThrowingStream { continuation in
             Task.detached { [self] in
                 ensureControlDir()
+                // `bash -lc` (login shell) so PATH picks up profile-only
+                // entries like pipx's `~/.local/bin` — same rationale as
+                // `makeProcess` above. Streaming consumers (log tails)
+                // don't tolerate a missing-binary failure any better than
+                // ACP does.
                 let cmd = ([executable] + args).map { Self.remotePathArg($0) }.joined(separator: " ")
                 var sshArgv = sshArgs()
                 sshArgv.insert("-T", at: 0)
                 sshArgv.append(hostSpec)
-                sshArgv.append("sh")
-                sshArgv.append("-c")
+                sshArgv.append("bash")
+                sshArgv.append("-lc")
                 sshArgv.append(Self.shellQuote(cmd))
                 let proc = Process()
                 proc.executableURL = URL(fileURLWithPath: sshBinary)
@@ -514,6 +523,69 @@ public struct SSHTransport: ServerTransport {
         #endif
     }
 
+    public func streamRawBytes(executable: String, args: [String]) -> AsyncThrowingStream<Data, Error> {
+        #if os(iOS)
+        return AsyncThrowingStream { $0.finish() }
+        #else
+        return AsyncThrowingStream { continuation in
+            Task.detached { [self] in
+                ensureControlDir()
+                // Same `bash -lc` wrapping as `streamLines` so PATH picks
+                // up profile-only entries (pipx, asdf, conda). The
+                // difference here is we yield raw `Data` chunks — no
+                // newline framing, no UTF-8 decoding. Required for
+                // backup tarballs.
+                let cmd = ([executable] + args).map { Self.remotePathArg($0) }.joined(separator: " ")
+                var sshArgv = sshArgs()
+                sshArgv.insert("-T", at: 0)
+                sshArgv.append(hostSpec)
+                sshArgv.append("bash")
+                sshArgv.append("-lc")
+                sshArgv.append(Self.shellQuote(cmd))
+                let proc = Process()
+                proc.executableURL = URL(fileURLWithPath: sshBinary)
+                proc.arguments = sshArgv
+                proc.environment = Self.sshSubprocessEnvironment()
+                let outPipe = Pipe()
+                let errPipe = Pipe()
+                proc.standardOutput = outPipe
+                proc.standardError = errPipe
+                do {
+                    try proc.run()
+                } catch {
+                    continuation.finish(throwing: error)
+                    return
+                }
+                try? outPipe.fileHandleForWriting.close()
+                try? errPipe.fileHandleForWriting.close()
+                let handle = outPipe.fileHandleForReading
+                while true {
+                    let chunk = handle.availableData
+                    if chunk.isEmpty { break }
+                    continuation.yield(chunk)
+                }
+                proc.waitUntilExit()
+                let stderrTail: String
+                if proc.terminationStatus != 0 {
+                    stderrTail = (try? errPipe.fileHandleForReading.readToEnd())
+                        .flatMap { String(data: $0 ?? Data(), encoding: .utf8) } ?? ""
+                } else {
+                    stderrTail = ""
+                }
+                try? outPipe.fileHandleForReading.close()
+                try? errPipe.fileHandleForReading.close()
+                if proc.terminationStatus != 0 {
+                    continuation.finish(throwing: TransportError.classifySSHFailure(
+                        host: config.host, exitCode: proc.terminationStatus, stderr: stderrTail
+                    ))
+                } else {
+                    continuation.finish()
+                }
+            }
+        }
+        #endif
+    }
+
     /// Injection point for ssh/scp subprocess environment enrichment.
     ///
     /// On the Mac app, this is wired at startup to
@@ -548,59 +620,26 @@ public struct SSHTransport: ServerTransport {
         return env
     }
 
-    // MARK: - SQLite snapshot
+    // MARK: - Script streaming
 
-    public func snapshotSQLite(remotePath: String) throws -> URL {
-        try? FileManager.default.createDirectory(atPath: snapshotDir, withIntermediateDirectories: true)
-        let localPath = snapshotDir + "/state.db"
-        // `.backup` is WAL-safe: sqlite takes a consistent snapshot without
-        // blocking writers. A plain `cp` of a WAL-mode DB could corrupt.
-        let remoteTmp = "/tmp/scarf-snapshot-\(UUID().uuidString).db"
-        // sqlite3's `.backup` is a dot-command, not a CLI arg. The whole
-        // dot-command must be one shell argument (double-quoted) so sqlite3
-        // receives it as a single command; the backup path inside it is
-        // single-quoted so sqlite3 parses it correctly. The DB path is a
-        // separate shell argument and goes through `remotePathArg`
-        // (double-quoted, $HOME-aware) so `~/.hermes/state.db` actually
-        // resolves on the remote.
-        //
-        // The second sqlite3 invocation flips the snapshot out of WAL mode
-        // so the scp'd file is self-contained: `.backup` preserves the
-        // source's journal_mode in the destination header, so without this
-        // step the client would need the `-wal`/`-shm` sidecars too, and
-        // every read would fail with "unable to open database file".
-        //
-        // Final shell command on the remote:
-        //   sqlite3 "$HOME/.hermes/state.db" ".backup '/tmp/scarf-snapshot-XYZ.db'" \
-        //     && sqlite3 '/tmp/scarf-snapshot-XYZ.db' "PRAGMA journal_mode=DELETE;"
-        let backupScript = #"sqlite3 \#(Self.remotePathArg(remotePath)) ".backup '\#(remoteTmp)'" && sqlite3 '\#(remoteTmp)' "PRAGMA journal_mode=DELETE;" > /dev/null"#
-        let backup = try runRemoteShell(backupScript)
-        if backup.exitCode != 0 {
-            throw TransportError.classifySSHFailure(host: config.host, exitCode: backup.exitCode, stderr: backup.stderrString)
+    /// Pipe `script` to `/bin/sh -s` over the ControlMaster-shared SSH
+    /// channel. Used by `RemoteSQLiteBackend` to invoke `sqlite3 -json`
+    /// per query without the per-arg quoting that `runProcess` would
+    /// apply. Delegates to `SSHScriptRunner` which already implements
+    /// the ssh-stdin-pipe pattern correctly.
+    public func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+        let context = ServerContext(id: contextID, displayName: displayName, kind: .ssh(config))
+        let outcome = await SSHScriptRunner.run(script: script, context: context, timeout: timeout)
+        switch outcome {
+        case .connectFailure(let reason):
+            throw TransportError.other(message: reason)
+        case .completed(let stdout, let stderr, let exitCode):
+            return ProcessResult(
+                exitCode: exitCode,
+                stdout: Data(stdout.utf8),
+                stderr: Data(stderr.utf8)
+            )
         }
-        // scp the backup down. scp/sftp expands `~` natively (it goes
-        // through the SSH file-transfer protocol, not a remote shell), so
-        // remoteTmp's `/tmp/...` absolute path round-trips as-is.
-        ensureControlDir()
-        var scpArgs: [String] = [
-            "-o", "ControlMaster=auto",
-            "-o", "ControlPath=\(controlDir)/%C",
-            "-o", "ControlPersist=600",
-            "-o", "StrictHostKeyChecking=accept-new",
-            "-o", "LogLevel=QUIET",
-            "-o", "BatchMode=yes"
-        ]
-        if let port = config.port { scpArgs += ["-P", String(port)] }
-        if let id = config.identityFile, !id.isEmpty { scpArgs += ["-i", id] }
-        scpArgs.append("\(hostSpec):\(remoteTmp)")
-        scpArgs.append(localPath)
-        let pull = try runLocal(executable: scpBinary, args: scpArgs, stdin: nil, timeout: 120)
-        // Regardless of pull outcome, try to clean up the remote tmp.
-        _ = try? runRemoteShell("rm -f \(Self.remotePathArg(remoteTmp))")
-        if pull.exitCode != 0 {
-            throw TransportError.classifySSHFailure(host: config.host, exitCode: pull.exitCode, stderr: pull.stderrString)
-        }
-        return URL(fileURLWithPath: localPath)
     }
 
     // MARK: - Watching
@@ -685,12 +724,28 @@ public struct SSHTransport: ServerTransport {
             try? stdinPipe.fileHandleForWriting.close()
         }
         if let timeout {
-            let deadline = Date().addingTimeInterval(timeout)
-            while proc.isRunning && Date() < deadline {
-                Thread.sleep(forTimeInterval: 0.1)
-            }
-            if proc.isRunning {
+            // Kernel-wait via DispatchGroup + terminationHandler instead
+            // of a 100ms Thread.sleep spin loop. The old loop burned a
+            // cooperative-pool thread for the full timeout duration AND
+            // had 100ms granularity on the deadline; this version blocks
+            // once on a semaphore that the OS wakes when the process
+            // terminates (or when the timeout fires). Net effect: under
+            // concurrent SSH load (sidebar reload + chat finalize +
+            // watcher poll all firing together) we don't accumulate
+            // multiple spin-blocked threads, which was the mechanism
+            // behind the 7-second `loadRecentSessions` outliers
+            // observed in remote-context perf captures.
+            let waitGroup = DispatchGroup()
+            waitGroup.enter()
+            proc.terminationHandler = { _ in waitGroup.leave() }
+            let outcome = waitGroup.wait(timeout: .now() + timeout)
+            proc.terminationHandler = nil
+            if outcome == .timedOut {
                 proc.terminate()
+                // Brief block until the kill actually lands so we can
+                // collect partial stdout. terminate() is async; without
+                // this wait the readToEnd below could race the close.
+                proc.waitUntilExit()
                 let partial = (try? stdoutPipe.fileHandleForReading.readToEnd()) ?? Data()
                 try? stdoutPipe.fileHandleForReading.close()
                 try? stderrPipe.fileHandleForReading.close()

scarf/Packages/ScarfCore/Sources/ScarfCore/Transport/ServerTransport.swift

@@ -81,14 +81,40 @@ public protocol ServerTransport: Sendable {
         args: [String]
     ) -> AsyncThrowingStream<String, Error>
 
-    // MARK: - SQLite
+    /// Binary-safe streaming exec. Same shape as `streamLines` but yields
+    /// arbitrary `Data` chunks of stdout instead of newline-delimited
+    /// strings. Required by the backup feature: `tar -czf -` produces
+    /// gzipped tar bytes that must NOT be decoded as UTF-8 / split on
+    /// `\n` — `streamLines` would silently corrupt the archive.
+    ///
+    /// Stream finishes on EOF / clean exit; errors with
+    /// `TransportError.commandFailed` on non-zero exit (carrying the
+    /// captured stderr tail). Chunk sizes are whatever the underlying
+    /// pipe returns from `availableData`, typically 4–64 KB on macOS.
+    nonisolated func streamRawBytes(
+        executable: String,
+        args: [String]
+    ) -> AsyncThrowingStream<Data, Error>
 
-    /// Return a local filesystem URL pointing at a fresh, consistent copy of
-    /// the SQLite database at `remotePath`. For local transports this is
-    /// just the remote path unchanged. For SSH transports this performs
-    /// `sqlite3 .backup` on the remote side and scp's the backup into
-    /// `~/Library/Caches/scarf/<serverID>/state.db`, returning that URL.
-    nonisolated func snapshotSQLite(remotePath: String) throws -> URL
+    /// Pipe a multi-line shell script through `/bin/sh -s` on the
+    /// target and return its captured output. The script travels as a
+    /// single opaque byte stream — no per-line shell interpolation,
+    /// no per-arg quoting — so `"$VAR"` references, here-docs, and
+    /// nested quotes survive untouched.
+    ///
+    /// Replaces the old `snapshotSQLite` + scp pipeline. Used by
+    /// `RemoteSQLiteBackend` to invoke `sqlite3 -readonly -json` over
+    /// SSH per query (or per batch). Local transport runs the script
+    /// in-process via `/bin/sh -c`. SSH transport delegates to
+    /// `SSHScriptRunner` (ControlMaster-shared channel). Citadel
+    /// transport (iOS) base64-encodes the script + decodes remotely
+    /// to skirt Citadel's missing-stdin support.
+    ///
+    /// Throws on transport failures (host unreachable, ssh exit 255,
+    /// timeout). Returns `ProcessResult` with the script's exit code
+    /// + stdout + stderr on completion — non-zero exit is NOT a
+    /// throw; callers inspect `exitCode` and decide.
+    nonisolated func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult
 
     // MARK: - Watching
 
@@ -97,6 +123,25 @@ public protocol ServerTransport: Sendable {
     nonisolated func watchPaths(_ paths: [String]) -> AsyncStream<WatchEvent>
 }
 
+public extension ServerTransport {
+    /// Default: backup-class binary streaming isn't implemented for
+    /// every transport (notably the iOS `CitadelServerTransport`,
+    /// which doesn't expose a raw stdout pipe). Concrete Mac
+    /// transports override this. The fallback yields a stream that
+    /// throws on first iteration so callers fail fast rather than
+    /// hanging silently.
+    nonisolated func streamRawBytes(
+        executable: String,
+        args: [String]
+    ) -> AsyncThrowingStream<Data, Error> {
+        AsyncThrowingStream { continuation in
+            continuation.finish(throwing: TransportError.other(
+                message: "streamRawBytes is not supported on this transport"
+            ))
+        }
+    }
+}
+
 /// Stat-style file metadata. `nil` (return value) means the file does not
 /// exist or couldn't be queried.
 public struct FileStat: Sendable, Hashable {

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ActivityViewModel.swift

@@ -23,6 +23,13 @@ public final class ActivityViewModel {
     public var toolResult: String?
     public var sessionPreviews: [String: String] = [:]
     public var isLoading = true
+    /// True while the Phase 2 background fill is paging through
+    /// `hydrateAssistantToolCalls`. Drives a "Loading tool details…"
+    /// pill in the page header so the user knows the placeholder
+    /// rows on screen will fill in. v2.8.
+    public var isHydratingToolCalls = false
+    @ObservationIgnored
+    private var hydrationTask: Task<Void, Never>?
 
     public var availableSessions: [(id: String, label: String)] {
         var seen = Set<String>()
@@ -34,8 +41,29 @@ public final class ActivityViewModel {
     }
 
     public var filteredActivity: [ActivityEntry] {
-        let entries = toolMessages.flatMap { message in
-            message.toolCalls.map { call in
+        let entries = toolMessages.flatMap { message -> [ActivityEntry] in
+            // v2.8 — emit a single "Loading tool calls…" placeholder
+            // entry per skeleton message (one whose tool_calls JSON
+            // hasn't been hydrated yet). The user sees the timeline
+            // shape immediately; real entries replace the placeholder
+            // in-place when `hydrateAssistantToolCalls` returns.
+            // Filtering still works (we apply the session filter
+            // below) but kind filter hides placeholders since
+            // .other is the placeholder's default kind.
+            guard !message.toolCalls.isEmpty else {
+                return [ActivityEntry(
+                    id: "skeleton-\(message.id)",
+                    sessionId: message.sessionId,
+                    toolName: "Loading tool details…",
+                    kind: .other,
+                    summary: "",
+                    arguments: "",
+                    messageContent: "",
+                    timestamp: message.timestamp,
+                    isPlaceholder: true
+                )]
+            }
+            return message.toolCalls.map { call in
                 ActivityEntry(
                     id: call.callId,
                     sessionId: message.sessionId,
@@ -49,14 +77,34 @@ public final class ActivityViewModel {
             }
         }
         return entries.filter { entry in
-            let kindOk = filterKind == nil || entry.kind == filterKind
+            // Placeholders bypass the kind filter so they don't all
+            // disappear when the user picks a non-`.other` filter
+            // chip — they still represent rows that may resolve to
+            // the matching kind once hydrated.
+            let kindOk = filterKind == nil || entry.isPlaceholder || entry.kind == filterKind
             let sessionOk = filterSessionId == nil || entry.sessionId == filterSessionId
             return kindOk && sessionOk
         }
     }
 
+    /// Last load's transport-failure reason, if any. Activity surfaces
+    /// this to the user instead of leaving the empty-state visible
+    /// (which the user reads as "no activity" rather than "couldn't
+    /// reach the host"). v2.8.
+    public var loadError: String?
+
     public func load() async {
+        // Cancel any in-flight hydration from a prior load (e.g. a
+        // file-watcher delta firing while the prior pass was still
+        // paging). The new skeleton replaces the message set, so
+        // hydrating against the old ids would just splice into rows
+        // that no longer exist.
+        hydrationTask?.cancel()
+        hydrationTask = nil
+        isHydratingToolCalls = false
+
         isLoading = true
+        loadError = nil
         // refresh() = close + reopen, which forces a fresh snapshot pull on
         // remote contexts. Using open() here would short-circuit after the
         // first load and show stale data for the view's lifetime. The DB
@@ -64,12 +112,68 @@ public final class ActivityViewModel {
         // results without re-opening — cleanup() closes on disappear.
         let opened = await dataService.refresh()
         guard opened else {
+            loadError = "Couldn't reach \(context.displayName) — check the SSH connection and pull-to-refresh to retry."
             isLoading = false
             return
         }
-        toolMessages = await dataService.fetchRecentToolCalls(limit: 200)
-        sessionPreviews = await dataService.fetchSessionPreviews(limit: 200)
+        // v2.8 Phase L — skeleton-then-hydrate. Phase 1 metadata
+        // fetch is bounded by 50 rows × ~50 bytes (id + session_id +
+        // role + timestamp; tool_calls JSON is NULLed at the SQL
+        // level) ≈ 3 KB on the wire regardless of how big the
+        // underlying tool_calls blobs are. Comes back in
+        // sub-second on healthy remotes; placeholder rows render
+        // immediately. Phase 2 (paged hydrate) fills the real
+        // tool details in via 5-id batches in the background.
+        let outcome = await dataService.fetchRecentToolCallSkeleton(limit: 50)
+        toolMessages = outcome.messages
+        if let reason = outcome.transportError {
+            loadError = "Couldn't load activity from \(context.displayName) — the connection timed out (\(reason)). Pull to refresh to retry."
+            isLoading = false
+            return
+        }
+        sessionPreviews = await dataService.fetchSessionPreviews(limit: 50)
         isLoading = false
+
+        // Phase 2 — background hydrate. Mirrors the chat path's
+        // `startToolHydration`. Newest-first (the splice happens in
+        // batch order), cancellable via `cleanup()` / next `load()`.
+        startToolCallHydration()
+    }
+
+    /// Phase 2 of the v2.8 Activity loader. Pages through
+    /// `hydrateAssistantToolCalls` in batches of 5 ids and splices
+    /// the parsed `[HermesToolCall]` arrays into the existing
+    /// `toolMessages` skeleton. Once a message has its tool calls,
+    /// `filteredActivity` swaps the placeholder entry for the real
+    /// per-call entries on the next observation tick.
+    private func startToolCallHydration() {
+        let messageIds = toolMessages
+            .filter { $0.toolCalls.isEmpty && $0.id > 0 }
+            .map(\.id)
+        guard !messageIds.isEmpty else {
+            isHydratingToolCalls = false
+            return
+        }
+        isHydratingToolCalls = true
+        let dataService = self.dataService
+        hydrationTask = Task { @MainActor [weak self] in
+            defer { self?.isHydratingToolCalls = false }
+            // Page in 5-id batches matching the chat path —
+            // hydrateAssistantToolCalls already does the paging
+            // internally; here we just hand it all the ids and
+            // let it return whatever it could pull. Parent task
+            // cancellation propagates down via the v2.8 SSH
+            // cancellation handler we wired through SSHScriptRunner.
+            let map = await dataService.hydrateAssistantToolCalls(messageIds: messageIds)
+            guard let self else { return }
+            if Task.isCancelled { return }
+            if !map.isEmpty {
+                self.toolMessages = self.toolMessages.map { msg in
+                    guard msg.toolCalls.isEmpty, let calls = map[msg.id] else { return msg }
+                    return msg.withToolCalls(calls)
+                }
+            }
+        }
     }
 
     public func selectEntry(_ entry: ActivityEntry?) async {
@@ -82,6 +186,9 @@ public final class ActivityViewModel {
     }
 
     public func cleanup() async {
+        hydrationTask?.cancel()
+        hydrationTask = nil
+        isHydratingToolCalls = false
         await dataService.close()
     }
 }
@@ -95,6 +202,13 @@ public struct ActivityEntry: Identifiable, Sendable {
     public let arguments: String
     public let messageContent: String
     public let timestamp: Date?
+    /// True for skeleton entries emitted while the v2.8 two-phase
+    /// loader is still hydrating tool_calls JSON for the underlying
+    /// message. ActivityRow renders these as greyed "Loading…" rows
+    /// so the user sees the timeline shape without the per-call
+    /// detail. Splice happens in-place when hydration completes —
+    /// the placeholder vanishes and the real entries take its slot.
+    public let isPlaceholder: Bool
 
     public init(
         id: String,
@@ -104,7 +218,8 @@ public struct ActivityEntry: Identifiable, Sendable {
         summary: String,
         arguments: String,
         messageContent: String,
-        timestamp: Date?
+        timestamp: Date?,
+        isPlaceholder: Bool = false
     ) {
         self.id = id
         self.sessionId = sessionId
@@ -114,6 +229,7 @@ public struct ActivityEntry: Identifiable, Sendable {
         self.arguments = arguments
         self.messageContent = messageContent
         self.timestamp = timestamp
+        self.isPlaceholder = isPlaceholder
     }
 
     public var prettyArguments: String {

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ConnectionStatusViewModel.swift

@@ -16,12 +16,17 @@ public final class ConnectionStatusViewModel {
     #endif
 
     public enum Status: Equatable {
-        /// Healthy: SSH connected AND we can read `~/.hermes/config.yaml`.
+        /// Healthy: SSH connected AND we can read `~/.hermes/state.db`.
         case connected
         /// SSH connects but the follow-up read-access probe failed. Data
-        /// views will be empty until this is resolved. `reason` is shown
-        /// in the pill tooltip; users click the pill to open diagnostics.
-        case degraded(reason: String)
+        /// views will be empty until this is resolved.
+        ///
+        /// `reason` is the short pill copy (e.g. `"can't read ~/.hermes/
+        /// config.yaml"`); `hint` is a longer actionable string surfaced
+        /// in the pill's quick popover so users see *why* and *what to do*
+        /// without diving into the diagnostics sheet (issue #53). `cause`
+        /// classifies the failure for UI branching.
+        case degraded(reason: String, hint: String, cause: DegradedCause)
         /// No probe yet or the previous probe timed out but we haven't
         /// confirmed failure. Shown as yellow to tell the user "checking…".
         case idle
@@ -30,6 +35,32 @@ public final class ConnectionStatusViewModel {
         case error(message: String, stderr: String)
     }
 
+    /// Specific tier-2 failure mode emitted by the probe script. Used to
+    /// drive both the pill copy and the popover hint (issue #53).
+    public enum DegradedCause: Equatable {
+        /// `state.db` is missing entirely. Most common cause: Hermes
+        /// is installed but no session has run on this remote yet.
+        /// Case name kept as `configMissing` for back-compat with
+        /// callers that pattern-match on it; "config" here is loose
+        /// for "Scarf's required state file."
+        case configMissing
+        /// `~/.hermes` itself doesn't exist. Hermes isn't installed for
+        /// the SSH user on this host.
+        case homeMissing
+        /// File exists but the SSH user can't read it. Permission /
+        /// ownership mismatch. Same back-compat note as above.
+        case configUnreadable
+        /// `~/.hermes/active_profile` points at a non-default Hermes
+        /// profile and the configured Hermes home doesn't carry the
+        /// real config — the user is reading the wrong directory.
+        /// Carries the active profile name so the hint can name it.
+        case profileActive(name: String)
+        /// Probe couldn't classify the failure precisely (e.g. older
+        /// remote returned a binary `TIER2:1` without a tag). Falls
+        /// back to a generic hint.
+        case unknown
+    }
+
     public private(set) var status: Status = .idle
     /// Timestamp of the last successful probe. Used by the UI to show how
     /// fresh the status indicator is ("just now", "2m ago"…).
@@ -42,12 +73,10 @@ public final class ConnectionStatusViewModel {
     private let consecutiveFailureThreshold = 2
 
     public let context: ServerContext
-    private let transport: any ServerTransport
     private var probeTask: Task<Void, Never>?
 
     public init(context: ServerContext) {
         self.context = context
-        self.transport = context.makeTransport()
         if !context.isRemote {
             // Local contexts are always considered connected — no network
             // or auth can fail.
@@ -80,14 +109,22 @@ public final class ConnectionStatusViewModel {
     }
 
     private func probeOnce() async {
-        let snapshot = transport
+        let snapshot = context
         let hermesHome = context.paths.home
         // Two-tier probe in one SSH round-trip:
         //   tier 1: `true` — raw connectivity / auth / ControlMaster path
-        //   tier 2: `test -r $HERMESHOME/config.yaml` — can we actually
-        //           read the file Dashboard reads on every tick? Green pill
-        //           only if both pass; yellow "degraded" if tier 1 passes
-        //           but tier 2 fails (the exact symptom in issue #19).
+        //   tier 2: `test -r $HERMESHOME/state.db` — can we actually read
+        //           the file Dashboard / Sessions / Activity all hit on
+        //           every tick? Green pill only if both pass.
+        //
+        // Probe historically targeted `config.yaml`, but Hermes v0.11+
+        // doesn't materialize that file eagerly — it ships with sane
+        // defaults and only writes config.yaml when the user actually
+        // changes something. Result: a freshly-installed Hermes that's
+        // running, persisting sessions, and serving Scarf was being
+        // marked "degraded — config missing" indefinitely. `state.db`
+        // is created on first agent run and is the actual surface
+        // Scarf depends on, so we probe that instead.
         // Script emits two lines: TIER1:<exitcode> and TIER2:<exitcode>.
         let homeArg: String
         if hermesHome.hasPrefix("~/") {
@@ -97,57 +134,82 @@ public final class ConnectionStatusViewModel {
         } else {
             homeArg = "\"\(hermesHome.replacingOccurrences(of: "\"", with: "\\\""))\""
         }
+        // Probe emits a granular `TIER2:1:<cause>` code so the pill can
+        // surface a specific hint (issue #53). Causes:
+        //   no-home — $H itself doesn't exist
+        //   missing — state.db absent (Hermes hasn't been run yet)
+        //   perm    — exists but unreadable by SSH user
+        //   profile:<name> — state.db missing AND ~/.hermes/active_profile
+        //                    points at a Hermes profile, suggesting Scarf
+        //                    is reading the wrong dir
         let script = """
         echo TIER1:0
         H=\(homeArg)
-        if [ -r "$H/config.yaml" ]; then echo TIER2:0; else echo TIER2:1; fi
+        if [ -r "$H/state.db" ]; then
+          echo TIER2:0
+        elif [ ! -d "$H" ]; then
+          echo TIER2:1:no-home
+        elif [ ! -e "$H/state.db" ]; then
+          ACTIVE=""
+          if [ -r "$HOME/.hermes/active_profile" ]; then
+            ACTIVE=$(head -n1 "$HOME/.hermes/active_profile" 2>/dev/null | tr -d ' \\t\\r\\n')
+          fi
+          if [ -n "$ACTIVE" ] && [ "$ACTIVE" != "default" ]; then
+            echo TIER2:1:profile:$ACTIVE
+          else
+            echo TIER2:1:missing
+          fi
+        else
+          echo TIER2:1:perm
+        fi
         """
 
         enum ProbeOutcome {
             case connected
-            case degraded(reason: String)
+            case degraded(reason: String, hint: String, cause: DegradedCause)
             case failure(TransportError)
         }
 
-        let outcome: ProbeOutcome = await Task.detached {
-            do {
-                let probe = try snapshot.runProcess(
-                    executable: "/bin/sh",
-                    args: ["-c", script],
-                    stdin: nil,
-                    timeout: 10
-                )
-                guard probe.exitCode == 0 else {
-                    return .failure(.commandFailed(exitCode: probe.exitCode, stderr: probe.stderrString))
+        // Issue #44: previously this used `transport.runProcess(executable:
+        // "/bin/sh", args: ["-c", script])`, which goes through
+        // SSHTransport's `remotePathArg` quoting. That mangles multi-line
+        // shell scripts containing `"$VAR"` references and nested
+        // quotes — the remote received a scrambled string and the if-test
+        // for config.yaml readability silently failed even when the file
+        // was readable. Result: 14/14 diagnostics passing AND a stuck
+        // "Connected — can't read Hermes state" pill, simultaneously,
+        // because diagnostics had its own runOverSSH workaround. Now
+        // both paths use SSHScriptRunner so they always agree.
+        let outcome: ProbeOutcome = await {
+            let result = await SSHScriptRunner.run(script: script, context: snapshot, timeout: 10)
+            switch result {
+            case .connectFailure(let msg):
+                return .failure(.other(message: msg))
+            case .completed(let out, let stderr, let exitCode):
+                guard exitCode == 0 else {
+                    return .failure(.commandFailed(exitCode: exitCode, stderr: stderr))
                 }
-                let out = probe.stdoutString
                 let tier1 = out.contains("TIER1:0")
                 let tier2 = out.contains("TIER2:0")
                 if !tier1 {
-                    // The script itself didn't reach tier 1 — treat as connection failure.
                     return .failure(.commandFailed(exitCode: 1, stderr: out))
                 }
                 if tier2 {
                     return .connected
                 }
-                // Connected but can't read config.yaml — the core issue #19
-                // symptom. Give the pill a short reason; the full story goes
-                // into Remote Diagnostics.
-                return .degraded(reason: "can't read ~/.hermes/config.yaml")
-            } catch let e as TransportError {
-                return .failure(e)
-            } catch {
-                return .failure(.other(message: error.localizedDescription))
+                let cause = Self.parseDegradedCause(stdout: out)
+                let (reason, hint) = Self.describe(cause: cause, hermesHome: hermesHome)
+                return .degraded(reason: reason, hint: hint, cause: cause)
             }
-        }.value
+        }()
 
         switch outcome {
         case .connected:
             status = .connected
             lastSuccess = Date()
             consecutiveFailures = 0
-        case .degraded(let reason):
-            status = .degraded(reason: reason)
+        case .degraded(let reason, let hint, let cause):
+            status = .degraded(reason: reason, hint: hint, cause: cause)
             lastSuccess = Date()   // SSH itself is fine, reset failure count
             consecutiveFailures = 0
         case .failure(let err):
@@ -176,4 +238,59 @@ public final class ConnectionStatusViewModel {
             }
         }
     }
+
+    /// Pull a `DegradedCause` out of the probe stdout. Looks for the
+    /// `TIER2:1:<code>[:detail]` line; falls back to `.unknown` when
+    /// only the legacy binary `TIER2:1` is present (older remotes,
+    /// future-proofs against accidental tag drops).
+    nonisolated static func parseDegradedCause(stdout: String) -> DegradedCause {
+        for raw in stdout.split(separator: "\n") {
+            let line = raw.trimmingCharacters(in: .whitespaces)
+            guard line.hasPrefix("TIER2:1:") else { continue }
+            let body = String(line.dropFirst("TIER2:1:".count))
+            if body == "no-home" { return .homeMissing }
+            if body == "missing" { return .configMissing }
+            if body == "perm"    { return .configUnreadable }
+            if body.hasPrefix("profile:") {
+                let name = String(body.dropFirst("profile:".count))
+                if !name.isEmpty {
+                    return .profileActive(name: name)
+                }
+            }
+        }
+        return .unknown
+    }
+
+    /// Map a `DegradedCause` into the pill's short `reason` (single line,
+    /// fits in a tooltip) and longer `hint` (popover body, can carry
+    /// commands the user can copy).
+    nonisolated static func describe(cause: DegradedCause, hermesHome: String) -> (reason: String, hint: String) {
+        switch cause {
+        case .homeMissing:
+            return (
+                "Hermes not installed on remote",
+                "`\(hermesHome)` doesn't exist on the remote. Install Hermes for the SSH user, or — if Hermes is already installed under a different path — set this server's Hermes home in Manage Servers."
+            )
+        case .configMissing:
+            return (
+                "Hermes hasn't been run yet",
+                "`\(hermesHome)/state.db` is missing — Hermes creates it on first agent run. Start any session on the remote (e.g. `hermes chat`) and Scarf will go green automatically."
+            )
+        case .configUnreadable:
+            return (
+                "Permission denied on state.db",
+                "`\(hermesHome)/state.db` exists but the SSH user can't read it. Check ownership: `ls -l \(hermesHome)/state.db`. Either run Hermes as the SSH user, `chmod a+r` the file, or SSH as the Hermes user."
+            )
+        case .profileActive(let name):
+            return (
+                "Hermes profile \"\(name)\" is active",
+                "The remote is using Hermes profile `\(name)` — its state lives at `~/.hermes/profiles/\(name)/state.db`, not `\(hermesHome)/state.db`. Either set this server's Hermes home to `~/.hermes/profiles/\(name)` in Manage Servers → Edit, or run `hermes profile use default` on the remote to revert."
+            )
+        case .unknown:
+            return (
+                "Can't read Hermes state",
+                "SSH is fine but Scarf can't reach `\(hermesHome)/state.db`. Run diagnostics for a full breakdown."
+            )
+        }
+    }
 }

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/CuratorViewModel.swift

@@ -0,0 +1,137 @@
+import Foundation
+import Observation
+#if canImport(os)
+import os
+#endif
+
+/// Mac + iOS view model for the v0.12 Curator surface.
+///
+/// Drives `hermes curator status / run / pause / resume / pin / unpin /
+/// restore` plus a parsed view of `~/.hermes/skills/.curator_state`
+/// JSON. The CLI doesn't ship a `--json` flag for `status`, so we
+/// text-parse stdout (HermesCuratorStatusParser) and use the state
+/// file for richer last-run metadata.
+///
+/// Capability-gated: callers should construct this only when
+/// `HermesCapabilities.hasCurator` is true. The view model does not
+/// gate itself — the gate happens at sidebar/tab routing time.
+@Observable
+@MainActor
+public final class CuratorViewModel {
+    #if canImport(os)
+    private let logger = Logger(subsystem: "com.scarf", category: "CuratorViewModel")
+    #endif
+
+    public let context: ServerContext
+
+    public private(set) var status: HermesCuratorStatus = .empty
+    public private(set) var isLoading = false
+    public private(set) var lastReportMarkdown: String?
+    public var transientMessage: String?
+
+    public init(context: ServerContext) {
+        self.context = context
+    }
+
+    public func load() async {
+        isLoading = true
+        defer { isLoading = false }
+        let context = self.context
+        // v2.8 — instrumented. Curator load fires `hermes curator
+        // status` (CLI subprocess) plus 1-2 file reads; on remote
+        // each is a separate SSH RTT. Visibility lets future captures
+        // show how often the report file is missing or oversized.
+        let parsed = await ScarfMon.measureAsync(.diskIO, "curator.load") {
+            await Task.detached(priority: .userInitiated) { () -> (HermesCuratorStatus, String?) in
+                let textResult = Self.runCuratorStatus(context: context)
+                let stateData = context.readData(context.paths.curatorStateFile)
+                let parsed = HermesCuratorStatusParser.parse(text: textResult, stateFileJSON: stateData)
+                // Best-effort markdown report: the state file points at the
+                // most recent <YYYYMMDD-HHMMSS>/ dir; load REPORT.md from
+                // there. Missing on first run, which is fine.
+                var report: String?
+                if let reportDir = parsed.lastReportPath {
+                    let reportPath = reportDir.hasSuffix("/")
+                        ? "\(reportDir)REPORT.md"
+                        : "\(reportDir)/REPORT.md"
+                    report = context.readText(reportPath)
+                }
+                return (parsed, report)
+            }.value
+        }
+        ScarfMon.event(
+            .diskIO,
+            "curator.load.bytes",
+            count: 0,
+            bytes: parsed.1?.utf8.count ?? 0
+        )
+        self.status = parsed.0
+        self.lastReportMarkdown = parsed.1
+    }
+
+    public func runNow() async {
+        await runAndReload(args: ["curator", "run"], successMessage: "Curator run started")
+    }
+
+    public func pause() async {
+        await runAndReload(args: ["curator", "pause"], successMessage: "Curator paused")
+    }
+
+    public func resume() async {
+        await runAndReload(args: ["curator", "resume"], successMessage: "Curator resumed")
+    }
+
+    public func pin(_ skill: String) async {
+        await runAndReload(args: ["curator", "pin", skill], successMessage: "Pinned \(skill)")
+    }
+
+    public func unpin(_ skill: String) async {
+        await runAndReload(args: ["curator", "unpin", skill], successMessage: "Unpinned \(skill)")
+    }
+
+    public func restore(_ skill: String) async {
+        await runAndReload(args: ["curator", "restore", skill], successMessage: "Restored \(skill)")
+    }
+
+    private func runAndReload(args: [String], successMessage: String) async {
+        let context = self.context
+        let exitCode = await Task.detached(priority: .userInitiated) {
+            Self.runHermes(context: context, args: args).exitCode
+        }.value
+        transientMessage = exitCode == 0 ? successMessage : "Command failed"
+        await load()
+        // Auto-clear toast after 3s.
+        Task { @MainActor [weak self] in
+            try? await Task.sleep(nanoseconds: 3_000_000_000)
+            self?.transientMessage = nil
+        }
+    }
+
+    /// Wrap the transport-level `runProcess` so the call sites don't
+    /// have to reach for it directly. Combined stdout+stderr.
+    nonisolated private static func runHermes(
+        context: ServerContext,
+        args: [String]
+    ) -> (exitCode: Int32, output: String) {
+        let transport = context.makeTransport()
+        do {
+            let result = try transport.runProcess(
+                executable: context.paths.hermesBinary,
+                args: args,
+                stdin: nil,
+                timeout: 30
+            )
+            return (result.exitCode, result.stdoutString + result.stderrString)
+        } catch let error as TransportError {
+            return (-1, error.diagnosticStderr.isEmpty
+                ? (error.errorDescription ?? "transport error")
+                : error.diagnosticStderr)
+        } catch {
+            return (-1, error.localizedDescription)
+        }
+    }
+
+    nonisolated private static func runCuratorStatus(context: ServerContext) -> String {
+        runHermes(context: context, args: ["curator", "status"]).output
+    }
+}

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/IOSCronViewModel.swift

@@ -29,17 +29,24 @@ public final class IOSCronViewModel {
         let ctx = context
         let path = ctx.paths.cronJobsJSON
 
-        let result: Result<CronJobsFile, Error> = await Task.detached {
-            do {
-                guard let data = ctx.readData(path) else {
-                    throw LoadError.missingFile(path: path)
+        // v2.7 — instrumented for parity with Mac `cron.load`. iOS
+        // Cron load is a single SFTP read of jobs.json so should be
+        // snappy on most remotes; this measure point makes the cost
+        // visible in ScarfMon traces alongside the rest of the iOS
+        // load paths.
+        let result: Result<CronJobsFile, Error> = await ScarfMon.measureAsync(.diskIO, "ios.cron.load") {
+            await Task.detached {
+                do {
+                    guard let data = ctx.readData(path) else {
+                        throw LoadError.missingFile(path: path)
+                    }
+                    let decoded = try JSONDecoder().decode(CronJobsFile.self, from: data)
+                    return .success(decoded)
+                } catch {
+                    return Result<CronJobsFile, Error>.failure(error)
                 }
-                let decoded = try JSONDecoder().decode(CronJobsFile.self, from: data)
-                return .success(decoded)
-            } catch {
-                return .failure(error)
-            }
-        }.value
+            }.value
+        }
 
         switch result {
         case .success(let file):

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/IOSMemoryViewModel.swift

@@ -96,15 +96,24 @@ public final class IOSMemoryViewModel {
         // Run the file read on a detached task — `readTextThrowing`
         // blocks on transport I/O, and we don't want the MainActor
         // hanging during a remote SFTP fetch.
+        // v2.7 — instrumented for parity with Mac `memory.load`.
+        // iOS path is one SFTP read per Memory tab open (per kind:
+        // memory / user / soul); the bytes counter shows payload
+        // size alongside latency.
         let ctx = context
         let path = kind.path(on: context)
-        let result: Result<String?, Error> = await Task.detached {
-            do {
-                return .success(try ctx.readTextThrowing(path))
-            } catch {
-                return .failure(error)
-            }
-        }.value
+        let result: Result<String?, Error> = await ScarfMon.measureAsync(.diskIO, "ios.memory.load") {
+            await Task.detached {
+                do {
+                    return Result<String?, Error>.success(try ctx.readTextThrowing(path))
+                } catch {
+                    return Result<String?, Error>.failure(error)
+                }
+            }.value
+        }
+        if case .success(.some(let loaded)) = result {
+            ScarfMon.event(.diskIO, "ios.memory.load.bytes", count: 0, bytes: loaded.utf8.count)
+        }
 
         switch result {
         case .success(.some(let loaded)):

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/InsightsViewModel.swift

@@ -117,12 +117,19 @@ public final class InsightsViewModel {
         }
 
         let since = period.sinceDate
+        // The four insights queries (user-message count, tool usage,
+        // hourly + daily activity histograms) batch through one
+        // `insightsSnapshot` round-trip. Sessions and session-previews
+        // stay separate — they're large result sets and stay on their
+        // own calls. For remote contexts this turns ~5 SSH round-trips
+        // into 3.
         sessions = await dataService.fetchSessionsInPeriod(since: since)
         sessionPreviews = await dataService.fetchSessionPreviews(limit: 500)
-        userMessageCount = await dataService.fetchUserMessageCount(since: since)
-        let tools = await dataService.fetchToolUsage(since: since)
-        hourlyActivity = await dataService.fetchSessionStartHours(since: since)
-        dailyActivity = await dataService.fetchSessionDaysOfWeek(since: since)
+        let snapshot = await dataService.insightsSnapshot(since: since)
+        userMessageCount = snapshot.userMessageCount
+        let tools = snapshot.toolUsage
+        hourlyActivity = snapshot.startHours
+        dailyActivity = snapshot.daysOfWeek
 
         await dataService.close()
 

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ProjectsViewModel.swift

@@ -164,6 +164,16 @@ public final class ProjectsViewModel {
         projects.map(\.dashboardPath)
     }
 
+    /// Per-project `.scarf/` directories — watched alongside `dashboardPaths`
+    /// so that file-reading widgets (markdown_file, log_tail, image) refresh
+    /// when their underlying files are added / removed / renamed inside the
+    /// directory by a cron job. In-place file appends within an existing
+    /// file are NOT detected here; the cron job should write atomically
+    /// (write-then-rename) or `touch` dashboard.json after each run.
+    public var projectScarfDirs: [String] {
+        projects.map(\.scarfDir)
+    }
+
     private func loadDashboard(for project: ProjectEntry) {
         dashboardError = nil
         if !service.dashboardExists(for: project) {

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift

@@ -5,6 +5,7 @@
 
 import Foundation
 import Observation
+import SwiftUI
 
 public enum ChatDisplayMode: String, CaseIterable {
     case terminal
@@ -27,6 +28,21 @@ public struct MessageGroup: Identifiable {
     public var toolCallCount: Int {
         assistantMessages.reduce(0) { $0 + $1.toolCalls.count }
     }
+
+    /// Aggregated `ToolKind → count` over all assistant tool calls in
+    /// this group. Lives on the model so SwiftUI's Equatable
+    /// short-circuit (issue #46) covers it — previously this was a
+    /// `MessageGroupView` computed property that re-walked O(m × k)
+    /// per group on every body re-evaluation.
+    public var toolKindCounts: [ToolKind: Int] {
+        var counts: [ToolKind: Int] = [:]
+        for msg in assistantMessages where msg.isAssistant {
+            for call in msg.toolCalls {
+                counts[call.toolKind, default: 0] += 1
+            }
+        }
+        return counts
+    }
 }
 
 @Observable
@@ -48,6 +64,23 @@ public final class RichChatViewModel {
     public var messages: [HermesMessage] = []
     public var currentSession: HermesSession?
     public var messageGroups: [MessageGroup] = []
+    /// True while the v2.8 two-phase loader's background hydration
+    /// (tool_calls JSON + tool result rows) is in flight. Chat header
+    /// shows "Loading tool details…" so the user knows the bare
+    /// transcript they're looking at will fill in. Cleared once both
+    /// hydration passes finish or the session-id changes underneath.
+    public var isHydratingTools: Bool = false
+    @ObservationIgnored
+    private var hydrationTask: Task<Void, Never>?
+
+    /// UserDefaults key controlling whether the chat resume path
+    /// auto-fetches the CONTENT of tool result rows (`role='tool'`) for
+    /// past messages. Defaults false — a single tool result blob
+    /// (file dump, stack trace) can be hundreds of KB; bulk-fetching
+    /// all of them during chat resume on a slow remote can blow past
+    /// the 30s SSH timeout. The Mac Settings → Display tab exposes
+    /// the toggle (mirror string in `ChatDensityKeys`).
+    public static let loadHistoricalToolResultsKey = "scarf.chat.loadHistoricalToolResults"
     /// True from the moment the user sends a prompt until the ACP
     /// `promptComplete` event arrives. Covers the whole round-trip
     /// including auxiliary post-processing (title generation, usage
@@ -105,6 +138,12 @@ public final class RichChatViewModel {
     /// users can copy-paste the raw output into a bug report.
     public var acpErrorDetails: String?
 
+    /// Lowercase OAuth provider name (`"nous"`, `"claude"`, …) when the
+    /// most recent failure was an OAuth refresh-revocation Hermes asked
+    /// the user to fix via re-authentication. Drives the chat banner's
+    /// "Re-authenticate" button. Nil for any other failure mode.
+    public var acpErrorOAuthProvider: String?
+
     /// Optional stderr-tail provider the controller can hook up when it
     /// creates the ACPClient. Used by `handlePromptComplete` to enrich
     /// the error banner on non-retryable stopReasons. The closure is
@@ -119,6 +158,7 @@ public final class RichChatViewModel {
         acpError = nil
         acpErrorHint = nil
         acpErrorDetails = nil
+        acpErrorOAuthProvider = nil
     }
 
     /// Populate the error triplet from a thrown Error + the ACPClient
@@ -139,10 +179,11 @@ public final class RichChatViewModel {
         }
         let msg = error.localizedDescription
         let stderrTail = await client?.recentStderr ?? ""
-        let hint = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
+        let cls = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
         acpError = msg
-        acpErrorHint = hint
+        acpErrorHint = cls?.hint
         acpErrorDetails = stderrTail.isEmpty ? nil : stderrTail
+        acpErrorOAuthProvider = cls?.oauthProvider
     }
 
     /// Populate the error triplet when `handlePromptComplete` sees a
@@ -153,11 +194,11 @@ public final class RichChatViewModel {
     public func recordPromptStopFailure(stopReason: String, client: ACPClient?) async {
         let msg = "Prompt ended without a response (stopReason: \(stopReason))."
         let stderrTail = await client?.recentStderr ?? ""
-        let hint = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
-            ?? Self.fallbackHint(for: stopReason)
+        let cls = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
         acpError = msg
-        acpErrorHint = hint
+        acpErrorHint = cls?.hint ?? Self.fallbackHint(for: stopReason)
         acpErrorDetails = stderrTail.isEmpty ? nil : stderrTail
+        acpErrorOAuthProvider = cls?.oauthProvider
     }
 
     /// Same as `recordPromptStopFailure` but pulls stderr from the
@@ -167,11 +208,11 @@ public final class RichChatViewModel {
     private func recordPromptStopFailureUsingProvider(stopReason: String) async {
         let msg = "Prompt ended without a response (stopReason: \(stopReason))."
         let stderrTail = await acpStderrProvider?() ?? ""
-        let hint = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
-            ?? Self.fallbackHint(for: stopReason)
+        let cls = ACPErrorHint.classify(errorMessage: msg, stderrTail: stderrTail)
         acpError = msg
-        acpErrorHint = hint
+        acpErrorHint = cls?.hint ?? Self.fallbackHint(for: stopReason)
         acpErrorDetails = stderrTail.isEmpty ? nil : stderrTail
+        acpErrorOAuthProvider = cls?.oauthProvider
     }
 
     private static func fallbackHint(for stopReason: String) -> String? {
@@ -324,11 +365,51 @@ public final class RichChatViewModel {
     /// The original CLI session ID when resuming a CLI session via ACP.
     /// Used to combine old CLI messages with new ACP messages.
     public private(set) var originSessionId: String?
+    /// Smallest DB id currently loaded for the *current session* (i.e.
+    /// `sessionId`). Drives `loadEarlier()`: page back with
+    /// `before: oldestLoadedMessageID`. `nil` when nothing has been
+    /// loaded yet or the session has no DB-persisted messages.
+    public private(set) var oldestLoadedMessageID: Int?
+    /// Whether the most recent fetch suggests there are more older
+    /// messages on disk that haven't been loaded into `messages` yet.
+    /// Set to `true` when the initial fetch returned exactly `limit`
+    /// rows (a strong hint the table has more). Drives the "Load
+    /// earlier" button visibility in chat views.
+    public private(set) var hasMoreHistory: Bool = false
+    /// Cleared during a `loadEarlier()` fetch so the UI can show a
+    /// spinner and we don't fan out duplicate page requests.
+    public private(set) var isLoadingEarlier: Bool = false
     private var nextLocalId = -1
+
+    /// Issue #63: locally-created user messages awaiting state.db
+    /// persistence, keyed by session id. ACP roundtrips Hermes' DB
+    /// write asynchronously, so a user who sends a prompt and
+    /// immediately switches to another session triggers `reset()`
+    /// before Hermes flushes the row — `loadSessionHistory` then reads
+    /// from a DB that doesn't have the message yet, and the bubble
+    /// renders blank or vanishes on return. We hold a per-session
+    /// copy here that survives `reset()` so `loadSessionHistory` can
+    /// re-inject anything still in flight, and clean entries out as
+    /// soon as a matching DB row appears.
+    private var pendingLocalUserMessages: [String: [HermesMessage]] = [:]
+
     private var streamingAssistantText = ""
     private var streamingThinkingText = ""
     private var streamingToolCalls: [HermesToolCall] = []
 
+    /// True while a turn is in flight, has emitted thought-stream
+    /// bytes, but has NOT yet produced any visible assistant text.
+    /// Surfaces the user-facing "Thinking…" status promotion (the
+    /// model is reasoning before answering — Hermes reasoning models
+    /// commonly take 3–8 s here, which the ScarfMon `firstThoughtByte`
+    /// vs `firstByte` split makes visible). Becomes false the moment
+    /// the first message chunk arrives or the turn ends.
+    public var isStreamingThoughtsOnly: Bool {
+        currentTurnStart != nil
+            && !streamingThinkingText.isEmpty
+            && streamingAssistantText.isEmpty
+    }
+
     // DB polling state (used in terminal mode fallback)
     private var lastKnownFingerprint: HermesDataService.MessageFingerprint?
     private var debounceTask: Task<Void, Never>?
@@ -359,6 +440,9 @@ public final class RichChatViewModel {
 
     public func reset() {
         debounceTask?.cancel()
+        hydrationTask?.cancel()
+        hydrationTask = nil
+        isHydratingTools = false
         stopActivePolling()
         Task { await dataService.close() }
         messages = []
@@ -367,6 +451,9 @@ public final class RichChatViewModel {
         lastKnownFingerprint = nil
         sessionId = nil
         originSessionId = nil
+        oldestLoadedMessageID = nil
+        hasMoreHistory = false
+        isLoadingEarlier = false
         isAgentWorking = false
         userSendPending = false
         resetTimestamp = Date()
@@ -403,13 +490,15 @@ public final class RichChatViewModel {
 
     /// Re-fetch session metadata from DB to pick up cost/token updates.
     public func refreshSessionFromDB() async {
-        guard let sessionId else { return }
-        let opened = await dataService.open()
-        guard opened else { return }
-        if let session = await dataService.fetchSession(id: sessionId) {
-            currentSession = session
+        await ScarfMon.measureAsync(.sessionLoad, "mac.refreshSessionFromDB") {
+            guard let sessionId else { return }
+            let opened = await dataService.open()
+            guard opened else { return }
+            if let session = await dataService.fetchSession(id: sessionId) {
+                currentSession = session
+            }
+            await dataService.close()
         }
-        await dataService.close()
     }
 
     // MARK: - ACP Event Handling
@@ -436,6 +525,12 @@ public final class RichChatViewModel {
             reasoning: nil
         )
         messages.append(message)
+        // Track the local message in the pending-user-messages cache
+        // so a reset/resume cycle on this session before Hermes
+        // persists the row can still re-inject it on return (#63).
+        if let sid = sessionId {
+            pendingLocalUserMessages[sid, default: []].append(message)
+        }
         // Per-turn stopwatch (v2.5): record the start time only when
         // we're entering a fresh agent turn. /steer-style mid-run sends
         // arrive while isAgentWorking is already true; preserve the
@@ -582,11 +677,23 @@ public final class RichChatViewModel {
     }
 
     private func appendMessageChunk(text: String) {
+        // ScarfMon "first byte" — fires once per turn, on the first
+        // visible message chunk. Splits "user tap → first byte"
+        // (network + Hermes thinking) from "first byte → turn end"
+        // (streaming + Scarf rendering) so we can attribute slow-feel
+        // bugs to the right side. `bytes` carries the first chunk's
+        // size, not the full turn.
+        if streamingAssistantText.isEmpty && currentTurnStart != nil {
+            ScarfMon.event(.chatStream, "firstByte", count: 1, bytes: text.utf8.count)
+        }
         streamingAssistantText += text
         upsertStreamingMessage()
     }
 
     private func appendThoughtChunk(text: String) {
+        if streamingThinkingText.isEmpty && currentTurnStart != nil {
+            ScarfMon.event(.chatStream, "firstThoughtByte", count: 1, bytes: text.utf8.count)
+        }
         streamingThinkingText += text
         upsertStreamingMessage()
     }
@@ -759,11 +866,52 @@ public final class RichChatViewModel {
         } else {
             messages.append(msg)
         }
-        buildMessageGroups()
+        patchTrailingGroupForStreaming(streamingMsg: msg)
+    }
+
+    /// Per-chunk fast path for `messageGroups` (issue #46). Mutates
+    /// only the trailing group's assistant entry instead of rebuilding
+    /// the entire `messageGroups` array via `buildMessageGroups()` on
+    /// every streamed token.
+    ///
+    /// Falls back to a full rebuild whenever it can't safely patch:
+    ///  - no trailing group exists yet (e.g. first chunk after `reset`)
+    ///  - the trailing group is a user-only group (the very first chunk
+    ///    of a brand-new turn — we need a full rebuild so the assistant
+    ///    is grouped under the right user message)
+    ///
+    /// Other call sites of `buildMessageGroups()` are intentionally
+    /// untouched: they handle structural events (user message, tool
+    /// call complete, finalize, session resume) where group boundaries
+    /// can change, and a full rebuild is the right move there.
+    private func patchTrailingGroupForStreaming(streamingMsg: HermesMessage) {
+        guard let lastIdx = messageGroups.indices.last else {
+            buildMessageGroups()
+            return
+        }
+        let trailing = messageGroups[lastIdx]
+        var assistants = trailing.assistantMessages
+        if let i = assistants.firstIndex(where: { $0.id == Self.streamingId }) {
+            assistants[i] = streamingMsg
+        } else {
+            assistants.append(streamingMsg)
+        }
+        messageGroups[lastIdx] = MessageGroup(
+            id: trailing.id,
+            userMessage: trailing.userMessage,
+            assistantMessages: assistants,
+            toolResults: trailing.toolResults
+        )
     }
 
     /// Convert the streaming message (id=0) into a permanent message and reset streaming state.
     private func finalizeStreamingMessage() {
+        ScarfMon.measure(.chatStream, "finalizeStreamingMessage") {
+            _finalizeStreamingMessageImpl()
+        }
+    }
+
+    private func _finalizeStreamingMessageImpl() {
         guard let idx = messages.firstIndex(where: { $0.id == Self.streamingId }) else { return }
 
         // Only finalize if there's actual content
@@ -771,22 +919,52 @@ public final class RichChatViewModel {
             || !streamingThinkingText.isEmpty
             || !streamingToolCalls.isEmpty
 
+        // ScarfMon — surface turns that finalize with NO visible
+        // assistant text. Common Nous-model failure mode: model
+        // emits a few thought-stream bytes then falls silent;
+        // Hermes finalizes with empty content; the user sees a
+        // stuck "(°□°) deliberating..." placeholder bubble. The
+        // event fires for both the all-empty case (which gets
+        // removed below) and the thoughts-only case (which is
+        // kept as a permanent message with empty body) — both
+        // are user-visible failures worth tracking.
+        if streamingAssistantText.isEmpty && streamingToolCalls.isEmpty {
+            ScarfMon.event(
+                .chatStream,
+                "emptyAssistantTurn",
+                count: 1,
+                bytes: streamingThinkingText.utf8.count
+            )
+        }
+
         if hasContent {
             let id = nextLocalId
             nextLocalId -= 1
-            messages[idx] = HermesMessage(
-                id: id,
-                sessionId: sessionId ?? "",
-                role: "assistant",
-                content: streamingAssistantText,
-                toolCallId: nil,
-                toolCalls: streamingToolCalls,
-                toolName: nil,
-                timestamp: Date(),
-                tokenCount: nil,
-                finishReason: streamingToolCalls.isEmpty ? "stop" : nil,
-                reasoning: streamingThinkingText.isEmpty ? nil : streamingThinkingText
-            )
+            // Wrap the streaming-id rewrite in a no-animation
+            // transaction. Without this SwiftUI sees an identity
+            // change for the streaming ForEach element (id 0 → new
+            // permanent id) and runs an animated diff against
+            // adjacent elements, which costs ~5–8 RichMessageBubble
+            // body re-evaluations per turn-end (visible in the
+            // ScarfMon ring as a 1–2 ms burst right after every
+            // `finalizeStreamingMessage` interval). The new message
+            // is content-equal to the streaming one — there is no
+            // animation worth running.
+            withTransaction(Transaction(animation: nil)) {
+                messages[idx] = HermesMessage(
+                    id: id,
+                    sessionId: sessionId ?? "",
+                    role: "assistant",
+                    content: streamingAssistantText,
+                    toolCallId: nil,
+                    toolCalls: streamingToolCalls,
+                    toolName: nil,
+                    timestamp: Date(),
+                    tokenCount: nil,
+                    finishReason: streamingToolCalls.isEmpty ? "stop" : nil,
+                    reasoning: streamingThinkingText.isEmpty ? nil : streamingThinkingText
+                )
+            }
             // Capture per-turn duration so the chat UI can render the
             // stopwatch pill (v2.5). Skips assistants we don't have a
             // start time for — e.g., the .promptComplete fired but the
@@ -797,8 +975,12 @@ public final class RichChatViewModel {
                 currentTurnStart = nil
             }
         } else {
-            // Remove empty streaming placeholder
-            messages.remove(at: idx)
+            // Remove empty streaming placeholder. Same no-animation
+            // transaction pattern — empty-finalize used to ripple the
+            // ForEach diff to every following bubble.
+            withTransaction(Transaction(animation: nil)) {
+                messages.remove(at: idx)
+            }
         }
 
         // Reset streaming state for next chunk
@@ -825,12 +1007,15 @@ public final class RichChatViewModel {
         let opened = await dataService.open()
         guard opened else { return }
 
-        var dbMessages = await dataService.fetchMessages(sessionId: sessionId)
+        // Reconnects don't generate hundreds of unseen messages, so a
+        // 200-row tail is plenty for the merge — and it keeps us from
+        // re-materializing 1000+ message sessions on every reconnect.
+        var dbMessages = await dataService.fetchMessages(sessionId: sessionId, limit: HistoryPageSize.reconcile)
 
         // If we have an origin session (CLI session continued via ACP),
         // include those messages too
         if let origin = originSessionId, origin != sessionId {
-            let originMessages = await dataService.fetchMessages(sessionId: origin)
+            let originMessages = await dataService.fetchMessages(sessionId: origin, limit: HistoryPageSize.reconcile)
             if !originMessages.isEmpty {
                 dbMessages = originMessages + dbMessages
                 dbMessages.sort { ($0.timestamp ?? .distantPast) < ($1.timestamp ?? .distantPast) }
@@ -870,15 +1055,57 @@ public final class RichChatViewModel {
     /// Load message history from the DB, optionally combining an origin session
     /// (e.g., CLI session) with the current ACP session.
     public func loadSessionHistory(sessionId: String, acpSessionId: String? = nil) async {
+        await ScarfMon.measureAsync(.sessionLoad, "mac.hydrateMessages") {
         self.sessionId = sessionId
+        // Capture the session-id we're loading FOR so we can verify
+        // it's still the active one before assigning to `messages`.
+        // Without this guard, switching to a small chat while a
+        // larger one is mid-fetch can result in last-write-wins:
+        // the slow fetch finishes after the small chat's, drops
+        // the user back into the big chat's transcript, and the
+        // user has to reselect the small one. Observed in remote
+        // perf captures (parallel fetchMessages calls, one timing
+        // out at 30s for a 157-message session, the other 2-message
+        // chat completing in 425ms; the 30s one's assignment
+        // overwrote the small chat).
+        let loadingForSession = sessionId
         // Force a fresh snapshot pull on remote contexts. An earlier open()
         // would have cached a stale copy — on resume we need whatever
         // Hermes has actually persisted since then, or the resumed session
         // will show only history up to the moment the snapshot was taken.
-        let opened = await dataService.refresh()
+        // `forceFresh: true` refuses the stale-snapshot fallback the data
+        // service grew in M11 — falling back here would silently hide
+        // messages the agent streamed during the user's offline window.
+        let opened = await dataService.refresh(forceFresh: true)
         guard opened else { return }
+        // Race-check #1: session id may have changed during refresh.
+        guard self.sessionId == loadingForSession else {
+            ScarfMon.event(.sessionLoad, "mac.hydrateMessages.dropped", count: 1)
+            return
+        }
 
-        var allMessages = await dataService.fetchMessages(sessionId: sessionId)
+        // v2.8 two-phase loader. Phase 1 — skeleton: user + assistant
+        // rows only, no tool_calls JSON, no reasoning, no
+        // reasoning_content. Wire payload bounded by conversational
+        // text alone so chats with multi-page tool result blobs (the
+        // 30s-timeout case) come up in seconds. Phase 2 (kicked off
+        // below in a Task.detached) fills tool calls + tool results in
+        // the background — the chat is usable while it runs.
+        let pageSize = HistoryPageSize.initial
+        let originOutcome = await dataService.fetchSkeletonMessages(sessionId: sessionId, limit: pageSize)
+        var allMessages = originOutcome.messages
+        var transportFailure: String? = originOutcome.transportError
+        // Race-check #2: session id may have changed during the
+        // long fetch (the most common race — a 30s timeout on a
+        // big session lets the user switch to a small one and back).
+        guard self.sessionId == loadingForSession else {
+            ScarfMon.event(.sessionLoad, "mac.hydrateMessages.dropped", count: 1)
+            return
+        }
+        // The DB has more on-disk history when the initial fetch
+        // saturated the limit. The "Load earlier" affordance reads
+        // this flag.
+        var moreHistory = allMessages.count >= pageSize
         let session = await dataService.fetchSession(id: sessionId)
 
         // If the ACP session is different from the origin, load its messages too
@@ -886,17 +1113,284 @@ public final class RichChatViewModel {
         if let acpId = acpSessionId, acpId != sessionId {
             originSessionId = sessionId
             self.sessionId = acpId
-            let acpMessages = await dataService.fetchMessages(sessionId: acpId)
-            if !acpMessages.isEmpty {
-                allMessages.append(contentsOf: acpMessages)
+            let acpOutcome = await dataService.fetchSkeletonMessages(sessionId: acpId, limit: pageSize)
+            // Race-check #3: same guard, after the second fetch.
+            guard self.sessionId == acpId else {
+                ScarfMon.event(.sessionLoad, "mac.hydrateMessages.dropped", count: 1)
+                return
+            }
+            if let acpErr = acpOutcome.transportError, transportFailure == nil {
+                transportFailure = acpErr
+            }
+            if !acpOutcome.messages.isEmpty {
+                allMessages.append(contentsOf: acpOutcome.messages)
                 allMessages.sort { ($0.timestamp ?? .distantPast) < ($1.timestamp ?? .distantPast) }
+                moreHistory = moreHistory || acpOutcome.messages.count >= pageSize
             }
         }
 
-        messages = allMessages
+        // Issue #63 — re-inject any locally-created user messages
+        // we still have on file for this session that haven't yet
+        // shown up in state.db. Covers two paths:
+        //   1. The user just sent a prompt then resumed a different
+        //      session before Hermes persisted the row. `reset()` had
+        //      cleared `messages` but the per-session pending cache
+        //      survived; restore the row here so the bubble doesn't
+        //      come back blank.
+        //   2. The DB-resume path on first load — a previously-pending
+        //      message Hermes is still mid-write may not appear in
+        //      this fetch. We merge it in, and drop it from the cache
+        //      as soon as a matching DB row (same content, persisted
+        //      id ≥ 0) shows up.
+        let pendingForSession = pendingLocalUserMessages[sessionId] ?? []
+        if pendingForSession.isEmpty {
+            messages = allMessages
+        } else {
+            var merged = allMessages
+            var stillPending: [HermesMessage] = []
+            for local in pendingForSession {
+                let persisted = merged.contains { msg in
+                    msg.isUser && msg.id >= 0 && msg.content == local.content
+                }
+                if persisted {
+                    continue // DB caught up — drop the local copy
+                }
+                if !merged.contains(where: { $0.id == local.id }) {
+                    merged.append(local)
+                }
+                stillPending.append(local)
+            }
+            merged.sort { ($0.timestamp ?? .distantPast) < ($1.timestamp ?? .distantPast) }
+            messages = merged
+            if stillPending.isEmpty {
+                pendingLocalUserMessages.removeValue(forKey: sessionId)
+            } else {
+                pendingLocalUserMessages[sessionId] = stillPending
+            }
+        }
         currentSession = session
-        let minId = allMessages.map(\.id).min() ?? 0
+        let minId = messages.map(\.id).min() ?? 0
         nextLocalId = min(minId - 1, -1)
+        // Track the oldest loaded id from THIS session (not the merged
+        // origin) so `loadEarlier()` pages back through the live ACP
+        // session's history. Cross-session backfill (paging into the
+        // CLI origin) isn't supported in v1 — the merged 2× pageSize
+        // is enough headroom for the dashboard-resume case.
+        let currentSessionId = self.sessionId ?? sessionId
+        oldestLoadedMessageID = allMessages
+            .filter { $0.sessionId == currentSessionId }
+            .map(\.id)
+            .min()
+        hasMoreHistory = moreHistory
+        ScarfMon.event(.sessionLoad, "mac.hydrateMessages.rows", count: messages.count)
+        buildMessageGroups()
+
+        // Partial-result detection — if a fetch tripped a transport
+        // failure (SSH timeout / ControlMaster drop) the user is now
+        // looking at zero or near-zero messages with no idea why. The
+        // pre-v2.8 behavior was a silent empty transcript. Surface a
+        // banner via the existing acpError triplet so the user sees
+        // "couldn't load full history — connection slow." We assume
+        // more history exists (so the "Load earlier" affordance is
+        // honest about the gap) — caller can retry by reopening the
+        // session.
+        if let reason = transportFailure {
+            acpError = "Couldn't load full chat history — the connection to \(dataService.context.displayName) timed out."
+            acpErrorHint = "Reopen the session to retry, or check the SSH link if this keeps happening."
+            acpErrorDetails = reason
+            acpErrorOAuthProvider = nil
+            hasMoreHistory = true
+        } else {
+            // v2.8 — kick off background hydration of tool_calls JSON
+            // and tool result rows for the just-loaded skeleton.
+            // Non-blocking on the main load path (chat is usable).
+            startToolHydration(loadingForSession: self.sessionId ?? sessionId)
+        }
+        } // end measureAsync(.sessionLoad, "mac.hydrateMessages")
+    }
+
+    /// Phase 2 of the two-phase chat loader. Pulls `tool_calls` JSON
+    /// for the loaded assistant rows, then fetches `role='tool'` rows
+    /// in the loaded id range and splices both into `messages` /
+    /// `messageGroups` without disturbing what the user is already
+    /// reading. Cancellable — restarting (a session switch, a
+    /// `reset()`) drops any in-flight pass.
+    ///
+    /// Tool calls go in first because they live ON the existing
+    /// assistant message and surface the most-visible UI affordance
+    /// (the tool card chips). Tool result content rows go in second
+    /// because they're the heaviest payload and the UI degrades
+    /// gracefully without them (the cards still show "running" /
+    /// "complete" state; only the result body is missing).
+    private func startToolHydration(loadingForSession: String) {
+        hydrationTask?.cancel()
+        let sessionForLoad = loadingForSession
+        let dataService = self.dataService
+        hydrationTask = Task { @MainActor [weak self] in
+            guard let self else { return }
+            self.isHydratingTools = true
+            defer { self.isHydratingTools = false }
+
+            // Snapshot the assistant ids + id range from the messages
+            // we just loaded. Doing this on MainActor keeps us in step
+            // with the observable view of `messages`; the actual
+            // SQL calls happen in `await` slots that release the actor.
+            let assistantIds = self.messages
+                .filter { $0.isAssistant && $0.id > 0 }
+                .map(\.id)
+            guard let minId = self.messages.map(\.id).min(),
+                  let maxId = self.messages.map(\.id).max(),
+                  !assistantIds.isEmpty || minId < maxId else {
+                return
+            }
+
+            // Phase 2a — tool_calls JSON. Splice parsed values into
+            // each assistant message that has them.
+            let toolCallMap = await dataService.hydrateAssistantToolCalls(messageIds: assistantIds)
+            if Task.isCancelled || self.sessionId != sessionForLoad {
+                ScarfMon.event(.sessionLoad, "mac.hydrateTools.dropped", count: 1)
+                return
+            }
+            if !toolCallMap.isEmpty {
+                self.messages = self.messages.map { msg in
+                    guard msg.isAssistant, let calls = toolCallMap[msg.id] else { return msg }
+                    return msg.withToolCalls(calls)
+                }
+                self.buildMessageGroups()
+            }
+
+            // Phase 2b — tool result rows. Default OFF (v2.8). A
+            // single tool result blob (file dump, stack trace) can run
+            // hundreds of KB; bulk-fetching all of them during chat
+            // resume on a slow remote was the cause of the 30s timeout
+            // observed in 2026-05-05 dogfooding. Users can opt in via
+            // Settings → Display → "Load tool results in past chats"
+            // when bandwidth is plentiful. Tool call CARDS still
+            // render either way (`tool_calls` JSON loads in Phase 2a);
+            // only the inspector pane's "Output" section is empty
+            // until the user opens a card, at which point a per-call
+            // lazy fetch fills it in.
+            let loadResults = UserDefaults.standard.bool(
+                forKey: Self.loadHistoricalToolResultsKey
+            )
+            guard loadResults else {
+                ScarfMon.event(.sessionLoad, "mac.hydrateTools.skippedToolResults", count: 1)
+                return
+            }
+            let toolResults = await dataService.fetchToolResultsInRange(
+                sessionId: sessionForLoad,
+                minId: minId,
+                maxId: maxId
+            )
+            if Task.isCancelled || self.sessionId != sessionForLoad {
+                ScarfMon.event(.sessionLoad, "mac.hydrateTools.dropped", count: 1)
+                return
+            }
+            if !toolResults.isEmpty {
+                var merged = self.messages
+                let existingIds = Set(merged.map(\.id))
+                for tr in toolResults where !existingIds.contains(tr.id) {
+                    merged.append(tr)
+                }
+                merged.sort { lhs, rhs in
+                    let lt = lhs.timestamp ?? .distantPast
+                    let rt = rhs.timestamp ?? .distantPast
+                    if lt != rt { return lt < rt }
+                    return lhs.id < rhs.id
+                }
+                self.messages = merged
+                self.buildMessageGroups()
+            }
+            ScarfMon.event(.sessionLoad, "mac.hydrateTools.complete", count: 1)
+        }
+    }
+
+    /// Lazy-load the content of a single tool result by call id and
+    /// splice it into `messages` / `messageGroups` as a synthetic
+    /// `role='tool'` row. Used by `ChatInspectorPane` when the user
+    /// opens a tool call card whose result hasn't been hydrated yet
+    /// (auto-hydrate is opt-in via `loadHistoricalToolResultsKey`).
+    /// No-op when the result is already present in the transcript or
+    /// the session id has changed underneath us.
+    @MainActor
+    public func loadToolResultIfMissing(callId: String) async {
+        guard let sessionForLoad = sessionId else { return }
+        // Already in the transcript? Done.
+        if messages.contains(where: { $0.toolCallId == callId && $0.isToolResult }) {
+            return
+        }
+        guard let content = await dataService.fetchToolResult(callId: callId) else {
+            return
+        }
+        guard self.sessionId == sessionForLoad else { return }
+        // Build a synthetic tool result row. We don't have the original
+        // row id (would need a second SELECT) so we use a negative
+        // local id that won't collide with persisted rows. The bubble
+        // and inspector both key on `toolCallId`, not `id`, for tool
+        // results — so this is enough to render correctly.
+        let placeholderId = nextLocalId
+        nextLocalId -= 1
+        let synthetic = HermesMessage(
+            id: placeholderId,
+            sessionId: sessionForLoad,
+            role: "tool",
+            content: content,
+            toolCallId: callId,
+            toolCalls: [],
+            toolName: nil,
+            timestamp: Date(),
+            tokenCount: nil,
+            finishReason: nil,
+            reasoning: nil,
+            reasoningContent: nil
+        )
+        messages.append(synthetic)
+        // Re-sort so the tool result lands next to its assistant
+        // parent. ID-based ordering preserves the chronological order
+        // of all the persisted rows; the synthetic placeholder uses a
+        // negative id so it slots in last — fine for inspector display
+        // since the inspector keys on toolCallId.
+        messages.sort { lhs, rhs in
+            let lt = lhs.timestamp ?? .distantPast
+            let rt = rhs.timestamp ?? .distantPast
+            if lt != rt { return lt < rt }
+            return lhs.id < rhs.id
+        }
+        buildMessageGroups()
+        ScarfMon.event(.sessionLoad, "mac.lazyToolResult.fetched", count: 1)
+    }
+
+    // MARK: - Load Earlier (pagination)
+
+    /// Page back through the current session's DB-persisted history
+    /// before `oldestLoadedMessageID` and prepend the page to
+    /// `messages`. Cheap on the SQLite side (`id` is the primary
+    /// key); the cost is the data-service `open()` round-trip on
+    /// remote contexts. `pageSize` defaults to the same 200-row
+    /// budget as the initial load.
+    public func loadEarlier(pageSize: Int = HistoryPageSize.initial) async {
+        guard !isLoadingEarlier, hasMoreHistory else { return }
+        guard let sessionId, let oldest = oldestLoadedMessageID else { return }
+        isLoadingEarlier = true
+        defer { isLoadingEarlier = false }
+
+        let opened = await dataService.open()
+        guard opened else { return }
+
+        let older = await dataService.fetchMessages(
+            sessionId: sessionId,
+            limit: pageSize,
+            before: oldest
+        )
+        guard !older.isEmpty else {
+            hasMoreHistory = false
+            return
+        }
+        messages.insert(contentsOf: older, at: 0)
+        oldestLoadedMessageID = older.first?.id
+        // If this fetch returned fewer than the page size we've hit
+        // the bottom of the table — no further pages worth fetching.
+        hasMoreHistory = older.count >= pageSize
         buildMessageGroups()
     }
 
@@ -940,7 +1434,7 @@ public final class RichChatViewModel {
         let fingerprint = await dataService.fetchMessageFingerprint(sessionId: sessionId)
 
         if fingerprint != lastKnownFingerprint {
-            let fetched = await dataService.fetchMessages(sessionId: sessionId)
+            let fetched = await dataService.fetchMessages(sessionId: sessionId, limit: HistoryPageSize.polling)
             let session = await dataService.fetchSession(id: sessionId)
             lastKnownFingerprint = fingerprint
 

scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/SkillsViewModel.swift

@@ -49,6 +49,18 @@ public final class SkillsViewModel {
     public var hubMessage: String?
     public var hubSource: String = "all"
 
+    /// Last successful `browseHub` payload, kept around so that the
+    /// "All Sources" search path can filter client-side (issue #79).
+    /// `hermes skills search` with no `--source` flag routes through
+    /// the centralized `hermes-index` source which can miss skills
+    /// that are visible in browse — we'd rather give the user the
+    /// canonical "type-to-filter" UX than chase Hermes's index gaps.
+    /// Source-specific searches still shell out to the CLI for full
+    /// upstream semantics. Setter is `internal` so the in-tree test
+    /// suite can seed the cache without invoking the live CLI;
+    /// out-of-module callers can still only read.
+    public internal(set) var lastBrowseResults: [HermesHubSkill] = []
+
     public let hubSources = ["all", "official", "skills-sh", "well-known", "github", "clawhub", "lobehub"]
 
     public var filteredCategories: [HermesSkillCategory] {
@@ -70,19 +82,116 @@ public final class SkillsViewModel {
     /// Awaitable scan. iOS's `.task { await vm.load() }` and the
     /// ScarfCore unit tests use this directly; Mac call sites wrap in
     /// `Task { await ... }` from `onAppear`.
+    ///
+    /// Pinned-name set is auto-fetched from the curator state file on
+    /// v0.12+ hosts; callers can override by passing an explicit set
+    /// (the Curator screen does this when it has a fresher snapshot in
+    /// hand).
     @MainActor
-    public func load() async {
+    public func load(pinnedNames: Set<String>? = nil) async {
         isLoading = true
         lastError = nil
         let ctx = context
         let xport = transport
-        let cats: [HermesSkillCategory] = await Task.detached {
-            SkillsScanner.scan(context: ctx, transport: xport)
-        }.value
+        let pins = pinnedNames
+        // v2.8 — instrumented so future captures show how many SSH
+        // RTTs the SkillsScanner walk costs on remote (it stats
+        // every ~/.hermes/skills/* directory + reads SKILL.md per).
+        let cats: [HermesSkillCategory] = await ScarfMon.measureAsync(.diskIO, "skills.load") {
+            await Task.detached {
+                let disabled = Self.readDisabledSkillNames(context: ctx)
+                let pinned = pins ?? Self.readPinnedSkillNames(context: ctx)
+                return SkillsScanner.scan(
+                    context: ctx,
+                    transport: xport,
+                    disabledNames: disabled,
+                    pinnedNames: pinned
+                )
+            }.value
+        }
+        let totalSkills = cats.reduce(0) { $0 + $1.skills.count }
+        ScarfMon.event(.diskIO, "skills.load.count", count: totalSkills)
         categories = cats
         isLoading = false
     }
 
+    /// Read the curator's pinned-skills list from
+    /// `~/.hermes/skills/.curator_state` (JSON despite the lack of an
+    /// extension). Pre-v0.12 hosts won't have this file yet — return
+    /// an empty set so the pin badge stays hidden.
+    nonisolated static func readPinnedSkillNames(context: ServerContext) -> Set<String> {
+        guard let data = context.readData(context.paths.curatorStateFile),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return [] }
+        // Curator stores pins in either `pinned: [name, ...]` or
+        // `pinned_skills: [name, ...]` depending on Hermes version —
+        // accept both shapes so we don't break on a future rename.
+        let raw = (obj["pinned"] as? [String]) ?? (obj["pinned_skills"] as? [String]) ?? []
+        return Set(raw)
+    }
+
+    /// Read the `skills.disabled:` array from `~/.hermes/config.yaml`.
+    /// Hermes v0.12 stores skill disable state there (one global list
+    /// + optional `skills.platform_disabled` overrides). Returns the
+    /// global list only — Scarf doesn't surface platform overrides
+    /// today. Empty set on missing file / parse failure.
+    nonisolated static func readDisabledSkillNames(context: ServerContext) -> Set<String> {
+        guard let yaml = context.readText(context.paths.configYAML) else { return [] }
+        // Lightweight match: find `skills:` block, then `disabled:` array
+        // inside it. The full YAML parser is overkill for one nested array.
+        var inSkillsBlock = false
+        var disabledIndent: Int?
+        var collected: [String] = []
+        for raw in yaml.components(separatedBy: "\n") {
+            // Top-level `skills:` declaration.
+            if raw.hasPrefix("skills:") {
+                inSkillsBlock = true
+                continue
+            }
+            if inSkillsBlock {
+                // A new top-level block ends the `skills:` scope.
+                if !raw.hasPrefix(" ") && !raw.hasPrefix("\t") && raw.contains(":") {
+                    break
+                }
+                let trimmed = raw.trimmingCharacters(in: .whitespaces)
+                if trimmed.hasPrefix("disabled:") {
+                    // Inline form `disabled: [a, b, c]`
+                    let after = trimmed.dropFirst("disabled:".count).trimmingCharacters(in: .whitespaces)
+                    if after.hasPrefix("[") && after.hasSuffix("]") {
+                        let body = after.dropFirst().dropLast()
+                        let parts = body.split(separator: ",").map { String($0).trimmingCharacters(in: .whitespaces) }
+                        for p in parts where !p.isEmpty {
+                            collected.append(p.trimmingCharacters(in: CharacterSet(charactersIn: "\"' ")))
+                        }
+                        return Set(collected)
+                    }
+                    // Block form: `disabled:` followed by `  - name`
+                    disabledIndent = raw.prefix { $0 == " " || $0 == "\t" }.count
+                    continue
+                }
+                if let baseIndent = disabledIndent {
+                    let leading = raw.prefix { $0 == " " || $0 == "\t" }.count
+                    if !trimmed.isEmpty {
+                        // PyYAML's default `yaml.dump` emits list items at the
+                        // same indent as the parent key, so `- foo` lines for
+                        // `disabled:` arrive at `leading == baseIndent`. Only
+                        // a strictly shallower indent — or a same-indent line
+                        // that isn't a list item (sibling key) — ends the block.
+                        if leading < baseIndent { break }
+                        if leading == baseIndent && !trimmed.hasPrefix("- ") { break }
+                    }
+                    if trimmed.hasPrefix("- ") {
+                        let name = trimmed.dropFirst(2).trimmingCharacters(in: CharacterSet(charactersIn: "\"' "))
+                        if !name.isEmpty {
+                            collected.append(String(name))
+                        }
+                    }
+                }
+            }
+        }
+        return Set(collected)
+    }
+
     public func selectSkill(_ skill: HermesSkill) {
         selectedSkill = skill
         let mainFile = skill.files.first(where: { $0.hasSuffix(".md") }) ?? skill.files.first
@@ -163,14 +272,34 @@ public final class SkillsViewModel {
             browseHub()
             return
         }
+        let source = hubSource
+        let query = hubQuery
+        // Issue #79 — for "All Sources", filter the cached browse list
+        // client-side instead of shelling out. Hermes's all-source
+        // search routes through its centralized index which can miss
+        // skills (e.g. honcho) that browse surfaces from non-indexed
+        // registries. Specific-source searches keep the CLI path so
+        // power users still get full upstream search semantics.
+        if source == "all" {
+            if lastBrowseResults.isEmpty {
+                // No cache yet — kick off a browse, then filter on
+                // completion. The chained call lets the user type a
+                // query before ever clicking Browse.
+                browseHubThenFilter(query: query)
+            } else {
+                // Pure in-memory filter — runs synchronously on the
+                // calling actor (UI invocations are already on
+                // MainActor) so the user sees the narrowed list
+                // without a render-tick gap.
+                applyClientSideFilter(query: query, against: lastBrowseResults)
+            }
+            return
+        }
         isHubLoading = true
         let bin = context.paths.hermesBinary
         let xport = transport
-        let source = hubSource
-        let query = hubQuery
         Task.detached { [weak self] in
-            var args = ["skills", "search", query, "--limit", "40"]
-            if source != "all" { args += ["--source", source] }
+            let args = ["skills", "search", query, "--limit", "40", "--source", source]
             let result = Self.runHermes(executable: bin, args: args, transport: xport, timeout: 30)
             let parsed = HermesSkillsHubParser.parseHubList(result.output)
             await self?.finishBrowse(
@@ -182,6 +311,66 @@ public final class SkillsViewModel {
         }
     }
 
+    /// Run a browse fetch and then immediately apply a client-side
+    /// filter. Used by `searchHub` when the user types into search
+    /// before any browse has cached results.
+    private func browseHubThenFilter(query: String) {
+        isHubLoading = true
+        let bin = context.paths.hermesBinary
+        let xport = transport
+        Task.detached { [weak self] in
+            let args = ["skills", "browse", "--size", "40"]
+            let result = Self.runHermes(executable: bin, args: args, transport: xport, timeout: 30)
+            let parsed = HermesSkillsHubParser.parseHubList(result.output)
+            await self?.finishBrowseThenFilter(
+                browseResults: parsed,
+                query: query,
+                exitCode: result.exitCode,
+                rawOutput: result.output
+            )
+        }
+    }
+
+    @MainActor
+    private func finishBrowseThenFilter(
+        browseResults: [HermesHubSkill],
+        query: String,
+        exitCode: Int32,
+        rawOutput: String
+    ) async {
+        if exitCode == 0 {
+            lastBrowseResults = browseResults
+            applyClientSideFilter(query: query, against: browseResults)
+        } else {
+            // Surface the underlying browse failure rather than a
+            // blank "no matches" state — the user typed a query, not
+            // a browse request, but the cache was empty so we tried.
+            isHubLoading = false
+            hubResults = []
+            let detail = Self.firstSignificantLine(rawOutput)
+            hubMessage = detail.isEmpty
+                ? "Search failed (exit \(exitCode))"
+                : "Search failed: \(detail)"
+        }
+    }
+
+    private func applyClientSideFilter(query: String, against pool: [HermesHubSkill]) {
+        let needle = query.trimmingCharacters(in: .whitespaces)
+        let matches: [HermesHubSkill]
+        if needle.isEmpty {
+            matches = pool
+        } else {
+            matches = pool.filter { skill in
+                skill.name.localizedCaseInsensitiveContains(needle)
+                    || skill.description.localizedCaseInsensitiveContains(needle)
+                    || skill.identifier.localizedCaseInsensitiveContains(needle)
+            }
+        }
+        isHubLoading = false
+        hubResults = matches
+        hubMessage = matches.isEmpty ? "No matches" : nil
+    }
+
     public func installHubSkill(_ skill: HermesHubSkill) {
         isHubLoading = true
         hubMessage = "Installing \(skill.identifier)…"
@@ -200,6 +389,68 @@ public final class SkillsViewModel {
         }
     }
 
+    /// v0.12: install a skill from a direct HTTPS URL pointing at a
+    /// SKILL.md (or a tarball). Hermes pulls + installs without going
+    /// through the registry indirection. The Mac UI gates this on
+    /// `HermesCapabilities.hasSkillURLInstall` so a v0.11 host doesn't
+    /// see a button that errors out with "unrecognized argument".
+    ///
+    /// `categoryOverride` and `nameOverride` map to `--category` /
+    /// `--name` flags Hermes ships for direct-URL installs (the URL's
+    /// SKILL.md may not declare those, especially for one-off scripts).
+    public func installFromURL(
+        _ url: String,
+        categoryOverride: String? = nil,
+        nameOverride: String? = nil
+    ) {
+        isHubLoading = true
+        hubMessage = "Installing from URL…"
+        let bin = context.paths.hermesBinary
+        let xport = transport
+        Task.detached { [weak self] in
+            var args = ["skills", "install", url, "--yes"]
+            if let category = categoryOverride, !category.isEmpty {
+                args += ["--category", category]
+            }
+            if let name = nameOverride, !name.isEmpty {
+                args += ["--name", name]
+            }
+            let result = Self.runHermes(
+                executable: bin,
+                args: args,
+                transport: xport,
+                timeout: 180
+            )
+            await self?.finishInstall(identifier: url, exitCode: result.exitCode)
+        }
+    }
+
+    /// v0.12: trigger a hot reload of `~/.hermes/skills/` so the agent
+    /// picks up file edits without a session restart. Hermes ships
+    /// `/reload-skills` as a slash command in chat AND `hermes skills
+    /// audit` as a CLI form. We use `audit` here so the reload works
+    /// even when no chat session is active.
+    public func reloadSkills() async {
+        isHubLoading = true
+        let bin = context.paths.hermesBinary
+        let xport = transport
+        let result = await Task.detached {
+            Self.runHermes(
+                executable: bin,
+                args: ["skills", "audit"],
+                transport: xport,
+                timeout: 30
+            )
+        }.value
+        hubMessage = result.exitCode == 0 ? "Skills reloaded" : "Reload failed"
+        isHubLoading = false
+        await load()
+        Task { @MainActor [weak self] in
+            try? await Task.sleep(nanoseconds: 3_000_000_000)
+            self?.hubMessage = nil
+        }
+    }
+
     public func uninstallHubSkill(_ identifier: String) {
         let bin = context.paths.hermesBinary
         let xport = transport
@@ -262,6 +513,13 @@ public final class SkillsViewModel {
     ) async {
         isHubLoading = false
         hubResults = results
+        // Cache the fresh browse payload so the "All Sources" search
+        // path can filter client-side (issue #79). Search results are
+        // not cached — they're already filtered by the user's query
+        // and would poison the filter pool.
+        if !isSearch && exitCode == 0 {
+            lastBrowseResults = results
+        }
         if results.isEmpty {
             if exitCode == 0 {
                 hubMessage = isSearch ? "No matches" : "No results"

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/Helpers/MockHermesQueryBackend.swift

@@ -0,0 +1,150 @@
+#if canImport(SQLite3)
+
+import Foundation
+@testable import ScarfCore
+
+/// Test double for `HermesQueryBackend`. Lets the data-service-façade
+/// tests assert which SQL gets emitted, with which params, and feed
+/// scripted result rows back.
+///
+/// Implemented as an `actor` to satisfy the protocol's `Sendable`
+/// requirement and to mirror how the real backends serialize state.
+/// Marked `final` to prevent accidental subclassing — Swift Testing
+/// instances are short-lived per-`@Test`, but a stray subclass could
+/// hide override quirks.
+final actor MockHermesQueryBackend: HermesQueryBackend {
+
+    // MARK: - Knobs
+
+    var openShouldSucceed: Bool = true
+    var hasV07Schema: Bool = false
+    var hasV011Schema: Bool = false
+    var lastOpenError: String? = nil
+
+    /// Map of SQL prefix → rows. Lookup picks the longest matching
+    /// prefix, so callers can register both broad ("SELECT") and
+    /// narrow ("SELECT id, source FROM sessions") matchers without
+    /// the broad one swallowing the narrow one.
+    private var scriptedResults: [String: [Row]] = [:]
+
+    /// Map of SQL prefix → backend error to throw instead of returning
+    /// rows. Used to test the data-service's error-swallowing paths.
+    private var scriptedFailures: [String: BackendError] = [:]
+
+    /// Every `query(_:params:)` call lands here in order — assertion
+    /// material for "did the façade emit the SQL we expected".
+    private(set) var queryLog: [(sql: String, params: [SQLValue])] = []
+
+    /// Every `queryBatch` call lands here in order, one outer entry
+    /// per call, inner entries for each statement in that batch.
+    private(set) var batchLog: [[(sql: String, params: [SQLValue])]] = []
+
+    /// Track open/refresh/close lifecycle for a couple of tests that
+    /// want to assert "façade really did call open()".
+    private(set) var openCallCount = 0
+    private(set) var refreshCallCount = 0
+    private(set) var closeCallCount = 0
+
+    // MARK: - Knob mutators (called from tests)
+
+    func setOpenShouldSucceed(_ value: Bool) { openShouldSucceed = value }
+    func setHasV07Schema(_ value: Bool) { hasV07Schema = value }
+    func setHasV011Schema(_ value: Bool) { hasV011Schema = value }
+    func setLastOpenError(_ value: String?) { lastOpenError = value }
+
+    /// Build a one-row result keyed on `prefix`. `columns` is the
+    /// column-name → position map; `values` must be the same length.
+    func _seedRow(forSQLPrefix prefix: String, columns: [String: Int], values: [SQLValue]) {
+        let row = Row(values: values, columnIndex: columns)
+        scriptedResults[prefix] = [row]
+    }
+
+    /// Seed an arbitrary row sequence for queries that share `prefix`.
+    func _seedRows(forSQLPrefix prefix: String, _ rows: [Row]) {
+        scriptedResults[prefix] = rows
+    }
+
+    /// Make `query` throw the specified `error` whenever it sees a SQL
+    /// that begins with `prefix`.
+    func _seedFailure(forSQLPrefix prefix: String, error: BackendError) {
+        scriptedFailures[prefix] = error
+    }
+
+    // MARK: - HermesQueryBackend conformance
+
+    func open() async -> Bool {
+        openCallCount += 1
+        return openShouldSucceed
+    }
+
+    @discardableResult
+    func refresh(forceFresh: Bool) async -> Bool {
+        refreshCallCount += 1
+        return openShouldSucceed
+    }
+
+    func close() async {
+        closeCallCount += 1
+    }
+
+    func query(_ sql: String, params: [SQLValue]) async throws -> [Row] {
+        queryLog.append((sql: sql, params: params))
+        if let failure = longestMatchingFailure(for: sql) {
+            throw failure
+        }
+        return longestMatchingRows(for: sql) ?? []
+    }
+
+    func queryBatch(_ statements: [(sql: String, params: [SQLValue])]) async throws -> [[Row]] {
+        batchLog.append(statements)
+        var out: [[Row]] = []
+        out.reserveCapacity(statements.count)
+        for stmt in statements {
+            if let failure = longestMatchingFailure(for: stmt.sql) {
+                throw failure
+            }
+            out.append(longestMatchingRows(for: stmt.sql) ?? [])
+        }
+        return out
+    }
+
+    // MARK: - Internals
+
+    /// Pick the longest registered prefix that `sql` starts with.
+    /// Ties go to whichever ordering Dictionary iteration produced —
+    /// callers should not register two equal-length matchers for the
+    /// same SQL because the resolution order is undefined.
+    private func longestMatchingRows(for sql: String) -> [Row]? {
+        var bestMatch: (key: String, rows: [Row])?
+        for (prefix, rows) in scriptedResults {
+            if sql.hasPrefix(prefix) {
+                if let current = bestMatch {
+                    if prefix.count > current.key.count {
+                        bestMatch = (prefix, rows)
+                    }
+                } else {
+                    bestMatch = (prefix, rows)
+                }
+            }
+        }
+        return bestMatch?.rows
+    }
+
+    private func longestMatchingFailure(for sql: String) -> BackendError? {
+        var bestMatch: (key: String, error: BackendError)?
+        for (prefix, error) in scriptedFailures {
+            if sql.hasPrefix(prefix) {
+                if let current = bestMatch {
+                    if prefix.count > current.key.count {
+                        bestMatch = (prefix, error)
+                    }
+                } else {
+                    bestMatch = (prefix, error)
+                }
+            }
+        }
+        return bestMatch?.error
+    }
+}
+
+#endif // canImport(SQLite3)

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/HermesCapabilitiesTests.swift

@@ -0,0 +1,136 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Pure parser tests for `HermesCapabilities`. The detection store
+/// (`HermesCapabilitiesStore`) is exercised separately under integration
+/// tests since it spawns `hermes --version`.
+@Suite struct HermesCapabilitiesTests {
+
+    // MARK: - Version line parsing
+
+    @Test func parseV012ReleaseLine() {
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.12.0 (2026.4.30)")
+        #expect(caps.semver == HermesCapabilities.SemVer(major: 0, minor: 12, patch: 0))
+        #expect(caps.dateVersion == HermesCapabilities.DateVersion(year: 2026, month: 4, day: 30))
+        #expect(caps.detected)
+    }
+
+    @Test func parseV011ReleaseLine() {
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.11.0 (2026.4.23)")
+        #expect(caps.semver == HermesCapabilities.SemVer(major: 0, minor: 11, patch: 0))
+        #expect(caps.dateVersion == HermesCapabilities.DateVersion(year: 2026, month: 4, day: 23))
+    }
+
+    @Test func parseSemverWithoutDate() {
+        // Some older Hermes builds emit only the semver suffix.
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.10.5")
+        #expect(caps.semver == HermesCapabilities.SemVer(major: 0, minor: 10, patch: 5))
+        #expect(caps.dateVersion == nil)
+    }
+
+    @Test func parseFullStdoutBlock() {
+        // Real `hermes --version` output is multi-line; the version sits on
+        // the first line and the rest is metadata.
+        let stdout = """
+        Hermes Agent v0.12.0 (2026.4.30)
+        Project: /Users/alan/.hermes/hermes-agent
+        Python: 3.11.15
+        OpenAI SDK: 2.31.0
+        Up to date
+        """
+        let caps = HermesCapabilities.parse(stdout)
+        #expect(caps.semver?.minor == 12)
+        #expect(caps.dateVersion?.year == 2026)
+    }
+
+    @Test func parseRejectsUnrelatedOutput() {
+        let caps = HermesCapabilities.parse("hermes: command not found")
+        #expect(caps.semver == nil)
+        #expect(!caps.detected)
+    }
+
+    @Test func parseHandlesEmptyString() {
+        let caps = HermesCapabilities.parse("")
+        #expect(caps == .empty)
+    }
+
+    @Test func parseHandlesPartialSemver() {
+        // "v0.11" without the patch component shouldn't accidentally match.
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.11")
+        #expect(caps.semver == nil)
+    }
+
+    // MARK: - SemVer ordering
+
+    @Test func semverOrdering() {
+        let v0_11_0 = HermesCapabilities.SemVer(major: 0, minor: 11, patch: 0)
+        let v0_12_0 = HermesCapabilities.SemVer(major: 0, minor: 12, patch: 0)
+        let v0_12_5 = HermesCapabilities.SemVer(major: 0, minor: 12, patch: 5)
+        let v1_0_0 = HermesCapabilities.SemVer(major: 1, minor: 0, patch: 0)
+        #expect(v0_11_0 < v0_12_0)
+        #expect(v0_12_0 < v0_12_5)
+        #expect(v0_12_5 < v1_0_0)
+    }
+
+    // MARK: - Capability flags
+
+    @Test func v012FlagsAllOn() {
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.12.0 (2026.4.30)")
+        #expect(caps.hasCurator)
+        #expect(caps.hasFallbackCommand)
+        #expect(caps.hasKanban)
+        #expect(caps.hasOneShot)
+        #expect(caps.hasSkillURLInstall)
+        #expect(caps.hasACPImagePrompts)
+        #expect(caps.hasUpdateCheck)
+        #expect(caps.hasPiperTTS)
+        #expect(caps.hasVercelTerminal)
+        #expect(caps.hasCuratorAux)
+        #expect(caps.hasTeamsPlatform)
+        #expect(caps.hasYuanbaoPlatform)
+        #expect(caps.hasCronWorkdir)
+        #expect(caps.hasPromptCacheTTL)
+        #expect(caps.hasRedactionToggle)
+        // flush_memories was REMOVED in v0.12 — flag inverts.
+        #expect(!caps.hasFlushMemoriesAux)
+    }
+
+    @Test func v011FlagsAllOff() {
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.11.0 (2026.4.23)")
+        #expect(!caps.hasCurator)
+        #expect(!caps.hasFallbackCommand)
+        #expect(!caps.hasKanban)
+        #expect(!caps.hasOneShot)
+        #expect(!caps.hasSkillURLInstall)
+        #expect(!caps.hasACPImagePrompts)
+        #expect(!caps.hasUpdateCheck)
+        #expect(!caps.hasPiperTTS)
+        #expect(!caps.hasVercelTerminal)
+        #expect(!caps.hasCuratorAux)
+        #expect(!caps.hasTeamsPlatform)
+        #expect(!caps.hasYuanbaoPlatform)
+        #expect(!caps.hasCronWorkdir)
+        #expect(!caps.hasPromptCacheTTL)
+        #expect(!caps.hasRedactionToggle)
+        // flush_memories aux row was still alive on v0.11.
+        #expect(caps.hasFlushMemoriesAux)
+    }
+
+    @Test func emptyCapabilitiesAllOff() {
+        // Undetected installs should hide every gated UI surface.
+        let caps = HermesCapabilities.empty
+        #expect(!caps.hasCurator)
+        #expect(!caps.hasFlushMemoriesAux)   // unknown → hide either way
+        #expect(!caps.detected)
+    }
+
+    @Test func futureVersionRetainsCapabilities() {
+        // A v0.13 (hypothetical) should still see all v0.12 capabilities on.
+        let caps = HermesCapabilities.parseLine("Hermes Agent v0.13.0 (2026.6.1)")
+        #expect(caps.hasCurator)
+        #expect(caps.hasACPImagePrompts)
+        // And flush_memories stays gone.
+        #expect(!caps.hasFlushMemoriesAux)
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/HermesCuratorParserTests.swift

@@ -0,0 +1,154 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+@Suite struct HermesCuratorParserTests {
+
+    /// Real `hermes curator status` output captured from a v0.12.0
+    /// install with no curator runs yet. Locks in the empty-state
+    /// happy path so a Hermes layout tweak surfaces here before
+    /// CuratorView starts rendering "—" placeholders silently.
+    private static let realFreshOutput = """
+    curator: ENABLED
+      runs:           0
+      last run:       never
+      last summary:   (none)
+      interval:       every 7d
+      stale after:    30d unused
+      archive after:  90d unused
+
+    agent-created skills: 18 total
+      active     18
+      stale      0
+      archived   0
+
+    least recently active (top 5):
+      Scarf Dashboard Chart Widget Parse Error Fix  activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      Scarf Project Registry Format Fix         activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      clip                                      activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      find-nearby                               activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      gguf-quantization                         activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+
+    least active (top 5):
+      Scarf Dashboard Chart Widget Parse Error Fix  activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      Scarf Project Registry Format Fix         activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      clip                                      activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      find-nearby                               activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+      gguf-quantization                         activity=  0  use=  0  view=  0  patches=  0  last_activity=never
+    """
+
+    @Test func parseRealFreshOutput() {
+        let s = HermesCuratorStatusParser.parse(text: Self.realFreshOutput)
+        #expect(s.state == .enabled)
+        #expect(s.runCount == 0)
+        #expect(s.lastRunISO == nil)
+        #expect(s.lastSummary == nil)
+        #expect(s.intervalLabel == "every 7d")
+        #expect(s.staleAfterLabel == "30d unused")
+        #expect(s.archiveAfterLabel == "90d unused")
+        #expect(s.totalSkills == 18)
+        #expect(s.activeSkills == 18)
+        #expect(s.staleSkills == 0)
+        #expect(s.archivedSkills == 0)
+        #expect(s.pinnedNames.isEmpty)
+        #expect(s.leastRecentlyActive.count == 5)
+        #expect(s.leastActive.count == 5)
+        #expect(s.mostActive.isEmpty)
+        let firstRow = s.leastRecentlyActive.first
+        #expect(firstRow?.name == "Scarf Dashboard Chart Widget Parse Error Fix")
+        #expect(firstRow?.activityCount == 0)
+        #expect(firstRow?.lastActivityLabel == "never")
+    }
+
+    @Test func parsedPausedState() {
+        let text = """
+        curator: PAUSED
+          runs:           5
+          last run:       2026-04-29T03:10:00Z
+          last summary:   pruned 2 skills, consolidated 1
+          interval:       every 7d
+          stale after:    30d unused
+          archive after:  90d unused
+
+        agent-created skills: 12 total
+          active     8
+          stale      3
+          archived   1
+
+        pinned (2): kanban-orchestrator, scarf-template-author
+        """
+        let s = HermesCuratorStatusParser.parse(text: text)
+        #expect(s.state == .paused)
+        #expect(s.runCount == 5)
+        #expect(s.lastRunISO == "2026-04-29T03:10:00Z")
+        #expect(s.lastSummary == "pruned 2 skills, consolidated 1")
+        #expect(s.totalSkills == 12)
+        #expect(s.activeSkills == 8)
+        #expect(s.staleSkills == 3)
+        #expect(s.archivedSkills == 1)
+        #expect(s.pinnedNames == ["kanban-orchestrator", "scarf-template-author"])
+    }
+
+    @Test func stateFileOverridesTextSummary() {
+        // The state file is authoritative for last_run_at /
+        // last_run_summary / last_report_path because it carries full
+        // ISO timestamps the text output may have rounded. Verify that
+        // a state file with richer values overrides parsed text.
+        let text = """
+        curator: ENABLED
+          runs:           1
+          last run:       2026-04-30T11:00:00Z
+          last summary:   short
+          interval:       every 7d
+          stale after:    30d unused
+          archive after:  90d unused
+
+        agent-created skills: 3 total
+          active     3
+          stale      0
+          archived   0
+        """
+        let stateJSON: [String: Any] = [
+            "run_count": 4,
+            "last_run_at": "2026-04-30T18:42:13.001Z",
+            "last_run_summary": "richer summary from state file",
+            "last_report_path": "/Users/u/.hermes/logs/curator/20260430-184213"
+        ]
+        let data = try! JSONSerialization.data(withJSONObject: stateJSON)
+        let s = HermesCuratorStatusParser.parse(text: text, stateFileJSON: data)
+        #expect(s.runCount == 4)
+        #expect(s.lastRunISO == "2026-04-30T18:42:13.001Z")
+        #expect(s.lastSummary == "richer summary from state file")
+        #expect(s.lastReportPath == "/Users/u/.hermes/logs/curator/20260430-184213")
+    }
+
+    @Test func parsedDisabledStatus() {
+        let s = HermesCuratorStatusParser.parse(text: "curator: DISABLED\n  runs:           0\n")
+        #expect(s.state == .disabled)
+    }
+
+    @Test func parsedEmptyOutputStaysSafe() {
+        let s = HermesCuratorStatusParser.parse(text: "")
+        #expect(s.state == .unknown)
+        #expect(s.totalSkills == 0)
+        #expect(s.leastRecentlyActive.isEmpty)
+    }
+
+    @Test func skillRowParserHandlesMultiWordNames() {
+        // Names with spaces are common (Scarf Dashboard Chart Widget…)
+        // The parser slices at the first `activity=` so names can be
+        // arbitrary length without breaking the counter columns.
+        let row = "  Some Long Skill Name v2  activity= 12  use= 4  view= 6  patches= 2  last_activity=2026-04-25"
+        let s = HermesCuratorStatusParser.parse(text: """
+        least recently active (top 5):
+        \(row)
+        """)
+        let parsed = s.leastRecentlyActive.first
+        #expect(parsed?.name == "Some Long Skill Name v2")
+        #expect(parsed?.activityCount == 12)
+        #expect(parsed?.useCount == 4)
+        #expect(parsed?.viewCount == 6)
+        #expect(parsed?.patchCount == 2)
+        #expect(parsed?.lastActivityLabel == "2026-04-25")
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/HermesDataServiceBackendTests.swift

@@ -0,0 +1,338 @@
+#if canImport(SQLite3)
+
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Exercises the `HermesDataService` façade against a `MockHermesQueryBackend`
+/// via the `internal init(context:backend:)` test seam. Focus is the SQL
+/// the façade emits + how it consumes the rows that come back.
+@Suite struct HermesDataServiceBackendTests {
+
+    // MARK: - Helpers
+
+    /// Build a `Row` from `(name, value)` pairs in column order.
+    /// Mirrors the shape `LocalSQLiteBackend.executeOne` produces.
+    private func makeRow(_ pairs: [(String, SQLValue)]) -> Row {
+        var values: [SQLValue] = []
+        var columnIndex: [String: Int] = [:]
+        values.reserveCapacity(pairs.count)
+        for (i, pair) in pairs.enumerated() {
+            values.append(pair.1)
+            columnIndex[pair.0] = i
+        }
+        return Row(values: values, columnIndex: columnIndex)
+    }
+
+    /// Default 16-column session row matching `sessionColumns` for
+    /// the bare base schema. Uses `.text("s1")` for id by default.
+    private func makeBaseSessionRow(id: String = "s1") -> Row {
+        makeRow([
+            ("id", .text(id)),
+            ("source", .text("acp")),
+            ("user_id", .null),
+            ("model", .text("gpt-5")),
+            ("title", .text("hello")),
+            ("parent_session_id", .null),
+            ("started_at", .real(1_700_000_000.0)),
+            ("ended_at", .null),
+            ("end_reason", .null),
+            ("message_count", .integer(5)),
+            ("tool_call_count", .integer(2)),
+            ("input_tokens", .integer(100)),
+            ("output_tokens", .integer(200)),
+            ("cache_read_tokens", .integer(0)),
+            ("cache_write_tokens", .integer(0)),
+            ("estimated_cost_usd", .real(0.05))
+        ])
+    }
+
+    /// 10-column message row matching `messageColumns` for the bare base schema.
+    private func makeBaseMessageRow(id: Int, sessionId: String = "s1", timestamp: Double = 1_700_000_001.0) -> Row {
+        makeRow([
+            ("id", .integer(Int64(id))),
+            ("session_id", .text(sessionId)),
+            ("role", .text("user")),
+            ("content", .text("hi #\(id)")),
+            ("tool_call_id", .null),
+            ("tool_calls", .null),
+            ("tool_name", .null),
+            ("timestamp", .real(timestamp)),
+            ("token_count", .integer(10)),
+            ("finish_reason", .null)
+        ])
+    }
+
+    /// Use a real `ServerContext.local` so the data service has a
+    /// transport to construct (it's never used by these tests — every
+    /// I/O path goes through the injected backend).
+    private let context: ServerContext = .local
+
+    // MARK: - fetchSessions
+
+    @Test func fetchSessionsEmitsExpectedSQLPrefixAndDefaultLimit() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.fetchSessions()
+
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+        let first = log[0]
+        #expect(first.sql.hasPrefix("SELECT id, source"))
+        #expect(first.sql.contains("FROM sessions WHERE parent_session_id IS NULL ORDER BY started_at DESC LIMIT ?"))
+        // QueryDefaults.sessionLimit == 100.
+        #expect(first.params == [.integer(100)])
+    }
+
+    @Test func fetchSessionsBareSchemaUsesBaseColumnList() async {
+        let mock = MockHermesQueryBackend()
+        // Both schema flags off — neither v0.7 nor v0.11 columns selected.
+        await mock.setHasV07Schema(false)
+        await mock.setHasV011Schema(false)
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+        _ = await service.fetchSessions()
+
+        let sql = await mock.queryLog[0].sql
+        #expect(!sql.contains("reasoning_tokens"))
+        #expect(!sql.contains("api_call_count"))
+        // Sanity: base columns are still all there.
+        #expect(sql.contains("estimated_cost_usd"))
+    }
+
+    @Test func fetchSessionsWithV07SchemaIncludesReasoningTokens() async {
+        let mock = MockHermesQueryBackend()
+        await mock.setHasV07Schema(true)
+        await mock.setHasV011Schema(false)
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+        _ = await service.fetchSessions()
+
+        let sql = await mock.queryLog[0].sql
+        #expect(sql.contains("reasoning_tokens"))
+        #expect(sql.contains("actual_cost_usd"))
+        #expect(sql.contains("cost_status"))
+        #expect(sql.contains("billing_provider"))
+        #expect(!sql.contains("api_call_count"))
+    }
+
+    @Test func fetchSessionsWithV011SchemaIncludesApiCallCount() async {
+        let mock = MockHermesQueryBackend()
+        await mock.setHasV07Schema(true)
+        await mock.setHasV011Schema(true)
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+        _ = await service.fetchSessions()
+
+        let sql = await mock.queryLog[0].sql
+        #expect(sql.contains("reasoning_tokens"))
+        #expect(sql.contains("api_call_count"))
+    }
+
+    // MARK: - fetchSession(id:)
+
+    @Test func fetchSessionByIdBindsTextParam() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        await mock._seedRow(
+            forSQLPrefix: "SELECT id, source",
+            columns: makeBaseSessionRow().columnIndex,
+            values: makeBaseSessionRow().values
+        )
+
+        let session = await service.fetchSession(id: "abc-123")
+        #expect(session?.id == "s1") // From the seeded row.
+
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+        #expect(log[0].sql.contains("FROM sessions WHERE id = ? LIMIT 1"))
+        #expect(log[0].params == [.text("abc-123")])
+    }
+
+    // MARK: - fetchMessages
+
+    @Test func fetchMessagesWithoutBeforeBindsSessionAndLimit() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.fetchMessages(sessionId: "s1", limit: 25, before: nil)
+
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+        #expect(!log[0].sql.contains("id < ?"))
+        #expect(log[0].sql.contains("WHERE session_id = ? ORDER BY id DESC LIMIT ?"))
+        #expect(log[0].params == [.text("s1"), .integer(25)])
+    }
+
+    @Test func fetchMessagesWithBeforeIncludesIdLessThanClause() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.fetchMessages(sessionId: "s1", limit: 25, before: 999)
+
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+        #expect(log[0].sql.contains("WHERE session_id = ? AND id < ? ORDER BY id DESC LIMIT ?"))
+        #expect(log[0].params == [.text("s1"), .integer(999), .integer(25)])
+    }
+
+    @Test func fetchMessagesReversesDescResultsToChronological() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        // Backend returns DESC (newest first); service should reverse to
+        // chronological (oldest first) for display.
+        let row3 = makeBaseMessageRow(id: 3, timestamp: 1_700_000_003.0)
+        let row2 = makeBaseMessageRow(id: 2, timestamp: 1_700_000_002.0)
+        let row1 = makeBaseMessageRow(id: 1, timestamp: 1_700_000_001.0)
+        await mock._seedRows(forSQLPrefix: "SELECT id, session_id", [row3, row2, row1])
+
+        let result = await service.fetchMessages(sessionId: "s1", limit: 10, before: nil)
+        #expect(result.count == 3)
+        #expect(result.map { $0.id } == [1, 2, 3])
+    }
+
+    // MARK: - dashboardSnapshot
+
+    @Test func dashboardSnapshotUsesQueryBatchNotIndividualQueries() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.dashboardSnapshot()
+
+        let queries = await mock.queryLog
+        let batches = await mock.batchLog
+        #expect(queries.isEmpty)
+        #expect(batches.count == 1)
+        #expect(batches[0].count == 4)
+    }
+
+    @Test func dashboardSnapshotBatchOrderIsStatsRecentSessionsPreviewsToolCalls() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.dashboardSnapshot()
+
+        let batches = await mock.batchLog
+        #expect(batches.count == 1)
+        let stmts = batches[0]
+        // 0: stats — selects COUNT(*), SUM(...) from sessions.
+        #expect(stmts[0].sql.contains("COUNT(*)"))
+        #expect(stmts[0].sql.contains("FROM sessions"))
+        // 1: recent sessions — selects session columns with a LIMIT param.
+        #expect(stmts[1].sql.hasPrefix("SELECT id, source"))
+        #expect(stmts[1].sql.contains("ORDER BY started_at DESC LIMIT ?"))
+        // 2: session previews — joins messages with first user message.
+        #expect(stmts[2].sql.contains("INNER JOIN"))
+        #expect(stmts[2].sql.contains("MIN(id)"))
+        // 3: recent tool calls — selects messages WHERE tool_calls IS NOT NULL.
+        #expect(stmts[3].sql.contains("WHERE tool_calls IS NOT NULL"))
+    }
+
+    @Test func dashboardSnapshotAssemblesDataFromFourResultSets() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        // Stats row (6 cols on bare schema).
+        let statsRow = makeRow([
+            ("c0", .integer(7)),  // totalSessions
+            ("c1", .integer(50)), // totalMessages
+            ("c2", .integer(12)), // totalToolCalls
+            ("c3", .integer(1000)), // totalInputTokens
+            ("c4", .integer(2000)), // totalOutputTokens
+            ("c5", .real(1.25))   // totalCostUSD
+        ])
+        await mock._seedRow(forSQLPrefix: "SELECT COUNT(*),", columns: statsRow.columnIndex, values: statsRow.values)
+
+        // Recent sessions: one base session row.
+        await mock._seedRows(forSQLPrefix: "SELECT id, source", [makeBaseSessionRow(id: "sess-A")])
+
+        // Previews: two-column rows (session_id, content slice).
+        let p1 = makeRow([("session_id", .text("sess-A")), ("preview", .text("first user msg"))])
+        await mock._seedRows(forSQLPrefix: "SELECT m.session_id", [p1])
+
+        // Recent tool calls: one message row with non-empty tool_calls.
+        var toolRow = makeBaseMessageRow(id: 99, sessionId: "sess-A")
+        // Manually rewrite tool_calls column (idx 5) to non-null/non-empty.
+        let toolRowValues: [SQLValue] = [
+            .integer(99), .text("sess-A"), .text("assistant"), .text("Calling tool"),
+            .null, .text("[{\"id\":\"t1\",\"name\":\"bash\"}]"), .text("bash"),
+            .real(1_700_000_010.0), .integer(15), .text("stop")
+        ]
+        toolRow = Row(values: toolRowValues, columnIndex: toolRow.columnIndex)
+        // Both `fetchRecentToolCalls` and the dashboard batch slot start
+        // with the same `messageColumns` prefix; match on a shorter
+        // common substring that's whitespace-stable across the two
+        // SQL builders.
+        await mock._seedRows(forSQLPrefix: "SELECT id, session_id, role, content, tool_call_id, tool_calls,\ntool_name", [toolRow])
+
+        let snapshot = await service.dashboardSnapshot()
+        #expect(snapshot.stats.totalSessions == 7)
+        #expect(snapshot.stats.totalMessages == 50)
+        #expect(snapshot.recentSessions.map { $0.id } == ["sess-A"])
+        #expect(snapshot.sessionPreviews["sess-A"] == "first user msg")
+        #expect(snapshot.recentToolCalls.count == 1)
+        #expect(snapshot.recentToolCalls[0].id == 99)
+    }
+
+    // MARK: - searchMessages
+
+    @Test func searchMessagesEmptyInputReturnsEmptyAndSkipsBackend() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        let result = await service.searchMessages(query: "   ")
+        #expect(result.isEmpty)
+
+        let log = await mock.queryLog
+        #expect(log.isEmpty)
+    }
+
+    @Test func searchMessagesWrapsTokensInDoubleQuotes() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+
+        _ = await service.searchMessages(query: "config.yaml v0.7.0")
+
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+        // FTS query is the first param.
+        guard case .text(let fts) = log[0].params[0] else {
+            Issue.record("Expected first FTS search param to be .text")
+            return
+        }
+        // Each whitespace-delimited token gets wrapped in double-quotes
+        // and joined with spaces.
+        #expect(fts == "\"config.yaml\" \"v0.7.0\"")
+    }
+
+    // MARK: - Error swallowing
+
+    @Test func fetchSessionsReturnsEmptyOnBackendTransportError() async {
+        let mock = MockHermesQueryBackend()
+        let service = HermesDataService(context: context, backend: mock)
+        _ = await service.open()
+        await mock._seedFailure(forSQLPrefix: "SELECT id, source", error: .transport("ssh dropped"))
+
+        let result = await service.fetchSessions()
+        #expect(result.isEmpty)
+
+        // Sanity: the error reached the backend (the call was made).
+        let log = await mock.queryLog
+        #expect(log.count == 1)
+    }
+}
+
+#endif // canImport(SQLite3)

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/HermesProfileResolverTests.swift

@@ -0,0 +1,119 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Exercises the `SCARF_HERMES_HOME` test-mode override on `HermesProfileResolver`.
+/// The override is the seam every E2E test relies on — without it, tests would
+/// touch the user's real `~/.hermes`. Serialized because we mutate process-wide
+/// environment.
+///
+/// **Marker file requirement.** As of v2.8 the override only activates when the
+/// path contains the sentinel `HermesProfileResolver.testHomeMarkerFilename`.
+/// Tests that want the override active drop the marker before `setenv`. Tests
+/// that want to verify the override is rejected (relative path, missing
+/// marker, empty value) skip the marker. The hardening prevents a leaked env
+/// var from ever pivoting Scarf off the user's real `~/.hermes`.
+@Suite(.serialized)
+struct HermesProfileResolverOverrideTests {
+
+    private static let envKey = "SCARF_HERMES_HOME"
+
+    @Test func absoluteOverrideTakesPrecedenceWhenMarkerPresent() throws {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        let tmp = NSTemporaryDirectory().appending("scarf-test-home-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(atPath: tmp, withIntermediateDirectories: true)
+        try Data().write(to: URL(fileURLWithPath: tmp + "/" + HermesProfileResolver.testHomeMarkerFilename))
+        defer { try? FileManager.default.removeItem(atPath: tmp) }
+        setenv(Self.envKey, tmp, 1)
+
+        #expect(HermesProfileResolver.resolveLocalHome() == tmp)
+        #expect(HermesProfileResolver.activeProfileName() == "test-override")
+    }
+
+    @Test func overrideIsIgnoredWhenMarkerMissing() throws {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        // Real-looking dir, no marker — exactly the shape a leaked env
+        // var or misconfigured launchctl plist would produce. Must NOT
+        // override; must fall through to the real resolver.
+        let tmp = NSTemporaryDirectory().appending("scarf-no-marker-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(atPath: tmp, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(atPath: tmp) }
+        setenv(Self.envKey, tmp, 1)
+        HermesProfileResolver.invalidateCache()
+
+        let resolved = HermesProfileResolver.resolveLocalHome()
+        #expect(resolved != tmp)
+        #expect(resolved.hasSuffix("/.hermes") || resolved.contains("/.hermes/profiles/"))
+    }
+
+    @Test func emptyOverrideFallsThrough() {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        setenv(Self.envKey, "", 1)
+        HermesProfileResolver.invalidateCache()
+
+        let resolved = HermesProfileResolver.resolveLocalHome()
+        #expect(!resolved.isEmpty)
+        #expect(resolved.hasSuffix("/.hermes") || resolved.contains("/.hermes/profiles/"))
+    }
+
+    @Test func relativeOverrideIsRejected() {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        setenv(Self.envKey, "relative/path", 1)
+        HermesProfileResolver.invalidateCache()
+
+        let resolved = HermesProfileResolver.resolveLocalHome()
+        #expect(!resolved.hasSuffix("relative/path"))
+    }
+
+    @Test func unsetOverrideUsesProfileResolver() {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        unsetenv(Self.envKey)
+        HermesProfileResolver.invalidateCache()
+
+        let resolved = HermesProfileResolver.resolveLocalHome()
+        #expect(!resolved.isEmpty)
+    }
+
+    @Test func overrideBypassesCacheWhenMarkerPresent() throws {
+        let saved = ProcessInfo.processInfo.environment[Self.envKey]
+        defer { restore(saved) }
+
+        let first = NSTemporaryDirectory().appending("scarf-cache-bypass-1-\(UUID().uuidString)")
+        let second = NSTemporaryDirectory().appending("scarf-cache-bypass-2-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(atPath: first, withIntermediateDirectories: true)
+        try FileManager.default.createDirectory(atPath: second, withIntermediateDirectories: true)
+        try Data().write(to: URL(fileURLWithPath: first + "/" + HermesProfileResolver.testHomeMarkerFilename))
+        try Data().write(to: URL(fileURLWithPath: second + "/" + HermesProfileResolver.testHomeMarkerFilename))
+        defer {
+            try? FileManager.default.removeItem(atPath: first)
+            try? FileManager.default.removeItem(atPath: second)
+        }
+
+        setenv(Self.envKey, first, 1)
+        #expect(HermesProfileResolver.resolveLocalHome() == first)
+
+        // Flip env var without invalidating the cache. Override is read
+        // fresh on every call, so the new value takes effect immediately.
+        setenv(Self.envKey, second, 1)
+        #expect(HermesProfileResolver.resolveLocalHome() == second)
+    }
+
+    private func restore(_ saved: String?) {
+        if let saved {
+            setenv(Self.envKey, saved, 1)
+        } else {
+            unsetenv(Self.envKey)
+        }
+        HermesProfileResolver.invalidateCache()
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/ListItemStatusTests.swift

@@ -0,0 +1,48 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Verifies the lenient `ListItemStatus(raw:)` parser. Real dashboards on
+/// disk use a mix of canonical names + synonyms (`done`, `info`, `ok`,
+/// `pending`, `up` are seen on the dev's machine today) — the parser must
+/// fold those onto the canonical case set without throwing or returning nil
+/// for the common synonyms. Unknown strings → nil so the renderer can fall
+/// back to plain text without losing the original.
+@Suite struct ListItemStatusTests {
+    @Test func canonicalNamesParse() {
+        for c in ListItemStatus.allCases {
+            #expect(ListItemStatus(raw: c.rawValue) == c)
+        }
+    }
+
+    @Test func synonymsCollapseToCanonical() {
+        #expect(ListItemStatus(raw: "ok") == .success)
+        #expect(ListItemStatus(raw: "OK") == .success)        // case-insensitive
+        #expect(ListItemStatus(raw: " up ") == .success)      // whitespace trim
+        #expect(ListItemStatus(raw: "down") == .danger)
+        #expect(ListItemStatus(raw: "error") == .danger)
+        #expect(ListItemStatus(raw: "failed") == .danger)
+        #expect(ListItemStatus(raw: "warn") == .warning)
+        #expect(ListItemStatus(raw: "degraded") == .warning)
+        #expect(ListItemStatus(raw: "active") == .info)
+        #expect(ListItemStatus(raw: "queued") == .pending)
+        #expect(ListItemStatus(raw: "complete") == .done)
+    }
+
+    @Test func unknownReturnsNilNotThrows() {
+        #expect(ListItemStatus(raw: "hologram") == nil)
+        #expect(ListItemStatus(raw: "") == nil)
+        #expect(ListItemStatus(raw: nil) == nil)
+        #expect(ListItemStatus(raw: "   ") == nil)
+    }
+
+    @Test func listItemStillDecodesUnknownStatusString() throws {
+        // Backwards-compat invariant: `ListItem.status` stays a free String? on
+        // the wire. Decoding a v2.6 dashboard with a non-canonical status must
+        // succeed and preserve the original string (renderer falls back).
+        let json = #"{"text":"foo","status":"weird"}"#.data(using: .utf8)!
+        let item = try JSONDecoder().decode(ListItem.self, from: json)
+        #expect(item.status == "weird")
+        #expect(ListItemStatus(raw: item.status) == nil)
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/M0bTransportTests.swift

@@ -219,12 +219,6 @@ import Foundation
         try transport.removeFile(tmp.path)
     }
 
-    @Test func localTransportSnapshotSQLiteReturnsPathUnchanged() throws {
-        let transport = LocalTransport()
-        let url = try transport.snapshotSQLite(remotePath: "/tmp/some/state.db")
-        #expect(url.path == "/tmp/some/state.db")
-    }
-
     /// The Mac target wires `SSHTransport.environmentEnricher` at launch to
     /// `HermesFileService.enrichedEnvironment()` so SSH subprocesses
     /// inherit SSH_AUTH_SOCK from the user's login shell (1Password /

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/M0dViewModelsTests.swift

@@ -37,8 +37,8 @@ import Foundation
         let b: ConnectionStatusViewModel.Status = .connected
         #expect(a == b)
 
-        let c: ConnectionStatusViewModel.Status = .degraded(reason: "x")
-        let d: ConnectionStatusViewModel.Status = .degraded(reason: "x")
+        let c: ConnectionStatusViewModel.Status = .degraded(reason: "x", hint: "y", cause: .unknown)
+        let d: ConnectionStatusViewModel.Status = .degraded(reason: "x", hint: "y", cause: .unknown)
         #expect(c == d)
 
         let e: ConnectionStatusViewModel.Status = .idle

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/M1ACPTests.swift

@@ -265,19 +265,20 @@ import Foundation
             errorMessage: "No Anthropic credentials found",
             stderrTail: ""
         )
-        #expect(noCreds?.contains("ANTHROPIC_API_KEY") == true)
+        #expect(noCreds?.hint.contains("ANTHROPIC_API_KEY") == true)
+        #expect(noCreds?.oauthProvider == nil)
 
         let missingBinary = ACPErrorHint.classify(
             errorMessage: "",
             stderrTail: "No such file or directory: 'npx'"
         )
-        #expect(missingBinary?.contains("npx") == true)
+        #expect(missingBinary?.hint.contains("npx") == true)
 
         let rateLimit = ACPErrorHint.classify(
             errorMessage: "",
             stderrTail: "HTTP 429 Too Many Requests: rate limit"
         )
-        #expect(rateLimit?.contains("rate-limit") == true)
+        #expect(rateLimit?.hint.contains("rate-limit") == true)
 
         let unknown = ACPErrorHint.classify(
             errorMessage: "weird thing",
@@ -286,6 +287,53 @@ import Foundation
         #expect(unknown == nil)
     }
 
+    @Test func errorHintsClassifyOAuthRefreshRevoked() {
+        // Primary trigger — Hermes's verbatim message when an OAuth
+        // refresh token can't mint a new access token. Provider name
+        // appears alongside; classifier should extract it.
+        let revoked = ACPErrorHint.classify(
+            errorMessage: "",
+            stderrTail: "Refresh session has been revoked. Run `hermes model` to re-authenticate."
+        )
+        #expect(revoked?.hint.contains("Re-authenticate") == true)
+
+        // With provider context — surfaces the affected provider name
+        // so the chat banner can offer a one-click re-auth that targets
+        // the right OAuth flow.
+        let revokedWithProvider = ACPErrorHint.classify(
+            errorMessage: "",
+            stderrTail: "Provider claude: Refresh session has been revoked. Run `hermes model` to re-authenticate."
+        )
+        #expect(revokedWithProvider?.oauthProvider == "claude")
+
+        // 401 + OAuth provider name — broader catchall for providers
+        // that don't print the verbatim "revoked" string.
+        let unauthorized = ACPErrorHint.classify(
+            errorMessage: "",
+            stderrTail: "HTTP 401 Unauthorized from nous portal"
+        )
+        #expect(unauthorized?.oauthProvider == "nous")
+        #expect(unauthorized?.hint.contains("OAuth") == true)
+
+        // Unauthorized on a non-OAuth provider (API-key based) should
+        // NOT classify as OAuth revocation — no `oauthProvider` known
+        // to dispatch the re-auth flow against.
+        let unauthorizedNonOAuth = ACPErrorHint.classify(
+            errorMessage: "",
+            stderrTail: "HTTP 401 Unauthorized for groq"
+        )
+        #expect(unauthorizedNonOAuth?.oauthProvider == nil)
+
+        // Word-boundary check — "anthropicapi" must not false-trigger
+        // on "anthropic". Without word boundaries this catches the
+        // wrong cases.
+        let substringNoMatch = ACPErrorHint.classify(
+            errorMessage: "",
+            stderrTail: "401 unauthorized: anthropicapi.example.com"
+        )
+        #expect(substringNoMatch?.oauthProvider != "anthropic")
+    }
+
     // MARK: - Helpers
 
     /// Poll `predicate` every ~20ms up to `timeout` seconds. Fails if

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/M5FeatureVMTests.swift

@@ -455,7 +455,9 @@ import Foundation
                 }
             }
         }
-        func snapshotSQLite(remotePath: String) throws -> URL { URL(fileURLWithPath: remotePath) }
+        func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+            ProcessResult(exitCode: 0, stdout: Data(), stderr: Data())
+        }
         func watchPaths(_ paths: [String]) -> AsyncStream<WatchEvent> {
             AsyncStream { $0.finish() }
         }

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/ModelPreflightTests.swift

@@ -0,0 +1,182 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Pure tests for `ModelPreflight` — both the `check(_:)` configured-vs-
+/// missing classifier and the v2.8 `detectMismatch(_:)` provider/prefix
+/// reconciliation. The mismatch path is what surfaces the orange
+/// "Model/provider mismatch in config.yaml" banner in ChatView when the
+/// user switches OAuth providers via Credential Pools and `model.default`
+/// is left carrying the old provider's prefix.
+@Suite struct ModelPreflightTests {
+
+    // MARK: - check(_:) — missing-field classifier
+
+    @Test func bothModelAndProviderEmptyReportsMissingBoth() {
+        var cfg = HermesConfig.empty
+        cfg.model = ""
+        cfg.provider = ""
+        #expect(ModelPreflight.check(cfg) == .missingBoth)
+    }
+
+    @Test func bothModelAndProviderUnknownReportsMissingBoth() {
+        // `HermesConfig.empty` defaults model/provider to the literal
+        // "unknown" — the classifier must treat that the same as "".
+        let cfg = HermesConfig.empty
+        #expect(ModelPreflight.check(cfg) == .missingBoth)
+    }
+
+    @Test func providerSetButModelEmptyReportsMissingModel() {
+        var cfg = HermesConfig.empty
+        cfg.model = ""
+        cfg.provider = "anthropic"
+        #expect(ModelPreflight.check(cfg) == .missingModel)
+    }
+
+    @Test func modelSetButProviderEmptyReportsMissingProvider() {
+        var cfg = HermesConfig.empty
+        cfg.model = "claude-sonnet-4.6"
+        cfg.provider = ""
+        #expect(ModelPreflight.check(cfg) == .missingProvider)
+    }
+
+    @Test func bothSetReportsConfigured() {
+        var cfg = HermesConfig.empty
+        cfg.model = "claude-sonnet-4.6"
+        cfg.provider = "anthropic"
+        #expect(ModelPreflight.check(cfg) == .configured)
+    }
+
+    @Test func whitespaceTreatedAsUnsetForBothFields() {
+        var cfg = HermesConfig.empty
+        cfg.model = "  "
+        cfg.provider = "\n"
+        #expect(ModelPreflight.check(cfg) == .missingBoth)
+    }
+
+    @Test func resultIsConfiguredOnlyForConfiguredCase() {
+        #expect(ModelPreflight.Result.configured.isConfigured)
+        #expect(!ModelPreflight.Result.missingBoth.isConfigured)
+        #expect(!ModelPreflight.Result.missingModel.isConfigured)
+        #expect(!ModelPreflight.Result.missingProvider.isConfigured)
+    }
+
+    // MARK: - detectMismatch(_:)
+
+    @Test func detectMismatchReturnsNilWhenNoPrefixOnModelDefault() {
+        var cfg = HermesConfig.empty
+        cfg.model = "claude-sonnet-4.6"
+        cfg.provider = "anthropic"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchReturnsNilWhenPrefixMatchesProvider() {
+        var cfg = HermesConfig.empty
+        cfg.model = "anthropic/claude-sonnet-4.6"
+        cfg.provider = "anthropic"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchReturnsNilWhenModelDefaultIsUnset() {
+        var cfg = HermesConfig.empty
+        cfg.model = ""
+        cfg.provider = "nous"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchReturnsNilWhenProviderIsUnset() {
+        var cfg = HermesConfig.empty
+        cfg.model = "anthropic/claude-sonnet-4.6"
+        cfg.provider = ""
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchReturnsNilWhenBothUnknown() {
+        // The literal "unknown" sentinel from the YAML parser fallback
+        // counts as unset on both sides — no mismatch to report.
+        let cfg = HermesConfig.empty // model + provider both "unknown"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchSurfacesPrefixVsActiveProvider() {
+        // The dogfooding scenario: Anthropic-prefixed model still sitting
+        // in config.yaml after the user OAuth'd into Nous via Credential
+        // Pools. Hermes can't reconcile and chats die with -32603 at
+        // first prompt. The banner offers a one-click fix in either
+        // direction; this test pins the data the banner reads.
+        var cfg = HermesConfig.empty
+        cfg.model = "anthropic/claude-sonnet-4.6"
+        cfg.provider = "nous"
+        let mismatch = ModelPreflight.detectMismatch(cfg)
+        #expect(mismatch != nil)
+        #expect(mismatch?.prefixProvider == "anthropic")
+        #expect(mismatch?.activeProvider == "nous")
+        #expect(mismatch?.modelDefault == "anthropic/claude-sonnet-4.6")
+        #expect(mismatch?.bareModel == "claude-sonnet-4.6")
+    }
+
+    @Test func detectMismatchIsCaseInsensitiveOnPrefixMatch() {
+        // Hermes accepts both `Anthropic/...` and `anthropic/...` casings
+        // in the wild — case-only differences must NOT surface as a
+        // mismatch (would be a false-positive banner).
+        var cfg = HermesConfig.empty
+        cfg.model = "Anthropic/claude-sonnet-4.6"
+        cfg.provider = "anthropic"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchHandlesNonAnthropicProviders() {
+        // The mismatch banner needs to work for any provider pair —
+        // not just the dogfooding case. Pin the openai+nous shape.
+        var cfg = HermesConfig.empty
+        cfg.model = "openai/gpt-5"
+        cfg.provider = "nous"
+        let mismatch = ModelPreflight.detectMismatch(cfg)
+        #expect(mismatch?.prefixProvider == "openai")
+        #expect(mismatch?.activeProvider == "nous")
+        #expect(mismatch?.bareModel == "gpt-5")
+    }
+
+    @Test func detectMismatchReturnsNilForEmptyBareModel() {
+        // A pathological "anthropic/" with no model name after the
+        // slash isn't a valid mismatch — caller has no bare model to
+        // write back. The classifier should refuse to surface it
+        // rather than emit a useless fix button.
+        var cfg = HermesConfig.empty
+        cfg.model = "anthropic/"
+        cfg.provider = "nous"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchReturnsNilForEmptyPrefix() {
+        // Symmetric pathological case — leading slash, no provider
+        // prefix. Don't fire.
+        var cfg = HermesConfig.empty
+        cfg.model = "/claude-sonnet-4.6"
+        cfg.provider = "nous"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+
+    @Test func detectMismatchHandlesModelsWithMultipleSlashes() {
+        // Some provider/model strings carry path-style segments after
+        // the first slash (e.g. an OpenRouter style path). The first
+        // slash separates prefix from bare model; the rest of the
+        // string is the bare model verbatim.
+        var cfg = HermesConfig.empty
+        cfg.model = "openrouter/anthropic/claude-sonnet-4.6"
+        cfg.provider = "anthropic"
+        let mismatch = ModelPreflight.detectMismatch(cfg)
+        #expect(mismatch?.prefixProvider == "openrouter")
+        #expect(mismatch?.activeProvider == "anthropic")
+        #expect(mismatch?.bareModel == "anthropic/claude-sonnet-4.6")
+    }
+
+    @Test func detectMismatchTrimsWhitespaceBeforeComparing() {
+        // A stray newline in a hand-edited config.yaml shouldn't read
+        // as a mismatch when the trimmed values agree.
+        var cfg = HermesConfig.empty
+        cfg.model = "anthropic/claude-sonnet-4.6  "
+        cfg.provider = " anthropic\n"
+        #expect(ModelPreflight.detectMismatch(cfg) == nil)
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/RemoteSQLiteBackendTests.swift

@@ -0,0 +1,565 @@
+#if canImport(SQLite3)
+
+import Testing
+import Foundation
+import SQLite3
+@testable import ScarfCore
+
+// MARK: - LocalSQLite3Transport
+
+/// Test-only transport that runs the script through `/bin/sh -c` on the
+/// local machine. Lets `RemoteSQLiteBackend`'s production codepath
+/// (which calls `transport.streamScript`) drive a real local sqlite3
+/// invocation against a tmp fixture DB. No SSH, no Citadel — the
+/// backend doesn't care how `streamScript` gets its bytes.
+private struct LocalSQLite3Transport: ServerTransport {
+    let contextID: ServerID
+    let isRemote: Bool = false
+
+    init(contextID: ServerID = ServerContext.local.id) {
+        self.contextID = contextID
+    }
+
+    func readFile(_ path: String) throws -> Data {
+        try Data(contentsOf: URL(fileURLWithPath: path))
+    }
+    func writeFile(_ path: String, data: Data) throws {
+        try data.write(to: URL(fileURLWithPath: path), options: .atomic)
+    }
+    func fileExists(_ path: String) -> Bool {
+        FileManager.default.fileExists(atPath: path)
+    }
+    func stat(_ path: String) -> FileStat? {
+        guard let attrs = try? FileManager.default.attributesOfItem(atPath: path) else { return nil }
+        let size = (attrs[.size] as? Int64) ?? Int64((attrs[.size] as? Int) ?? 0)
+        let mtime = (attrs[.modificationDate] as? Date) ?? Date(timeIntervalSince1970: 0)
+        let isDir = (attrs[.type] as? FileAttributeType) == .typeDirectory
+        return FileStat(size: size, mtime: mtime, isDirectory: isDir)
+    }
+    func listDirectory(_ path: String) throws -> [String] {
+        try FileManager.default.contentsOfDirectory(atPath: path)
+    }
+    func createDirectory(_ path: String) throws {
+        try FileManager.default.createDirectory(atPath: path, withIntermediateDirectories: true)
+    }
+    func removeFile(_ path: String) throws {
+        guard FileManager.default.fileExists(atPath: path) else { return }
+        try FileManager.default.removeItem(atPath: path)
+    }
+
+    func runProcess(executable: String, args: [String], stdin: Data?, timeout: TimeInterval?) throws -> ProcessResult {
+        throw TransportError.other(message: "LocalSQLite3Transport.runProcess unused in tests")
+    }
+
+    #if !os(iOS)
+    func makeProcess(executable: String, args: [String]) -> Process {
+        let p = Process()
+        p.executableURL = URL(fileURLWithPath: executable)
+        p.arguments = args
+        return p
+    }
+    #endif
+
+    func streamLines(executable: String, args: [String]) -> AsyncThrowingStream<String, Error> {
+        AsyncThrowingStream { $0.finish() }
+    }
+
+    /// The actual workhorse: feed the script to `/bin/sh -c` so heredocs
+    /// and command substitution behave exactly as they would on the
+    /// remote end of an SSH session. Capture stdout / stderr / exit
+    /// code into a `ProcessResult`.
+    func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+        return try await withCheckedThrowingContinuation { continuation in
+            DispatchQueue.global().async {
+                let proc = Process()
+                proc.executableURL = URL(fileURLWithPath: "/bin/sh")
+                proc.arguments = ["-c", script]
+                let outPipe = Pipe()
+                let errPipe = Pipe()
+                proc.standardOutput = outPipe
+                proc.standardError = errPipe
+                do {
+                    try proc.run()
+                } catch {
+                    continuation.resume(throwing: TransportError.other(
+                        message: "Failed to launch /bin/sh: \(error.localizedDescription)"
+                    ))
+                    return
+                }
+                try? outPipe.fileHandleForWriting.close()
+                try? errPipe.fileHandleForWriting.close()
+                proc.waitUntilExit()
+                let stdout = (try? outPipe.fileHandleForReading.readToEnd()) ?? Data()
+                let stderr = (try? errPipe.fileHandleForReading.readToEnd()) ?? Data()
+                try? outPipe.fileHandleForReading.close()
+                try? errPipe.fileHandleForReading.close()
+                continuation.resume(returning: ProcessResult(
+                    exitCode: proc.terminationStatus,
+                    stdout: stdout,
+                    stderr: stderr
+                ))
+            }
+        }
+    }
+
+    func watchPaths(_ paths: [String]) -> AsyncStream<WatchEvent> {
+        AsyncStream { $0.finish() }
+    }
+}
+
+// MARK: - Suite
+
+/// Integration tests for `RemoteSQLiteBackend`. Drives the real backend
+/// against a local sqlite3 binary (via `LocalSQLite3Transport`) and a
+/// per-test fixture state.db on disk.
+@Suite struct RemoteSQLiteBackendTests {
+
+    // MARK: - Fixture builders
+
+    /// Build a minimal v0.6 baseline state.db (no v0.7, no v0.11 columns).
+    /// Each test takes ownership of cleanup via `defer`.
+    private func makeFixtureStateDB(
+        addV07Columns: Bool = false,
+        addV011SessionsColumn: Bool = false,
+        addV011MessagesColumn: Bool = false
+    ) throws -> URL {
+        // Each test gets its own isolated parent dir. We can't dump the
+        // fixture directly into `temporaryDirectory` because the symlink
+        // we create alongside (`<parent>/state.db`) would clobber a
+        // sibling test's symlink when the suite runs in parallel.
+        let testDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scarf-test-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: testDir, withIntermediateDirectories: true)
+        let url = testDir.appendingPathComponent("fixture.db")
+        var db: OpaquePointer?
+        guard sqlite3_open_v2(url.path, &db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, nil) == SQLITE_OK else {
+            throw TransportError.other(message: "sqlite3_open_v2 failed")
+        }
+        defer { sqlite3_close(db) }
+
+        var sessionsExtra = ""
+        if addV07Columns {
+            sessionsExtra += ", reasoning_tokens INTEGER, actual_cost_usd REAL, cost_status TEXT, billing_provider TEXT"
+        }
+        if addV011SessionsColumn {
+            sessionsExtra += ", api_call_count INTEGER"
+        }
+        var messagesExtra = ""
+        if addV011MessagesColumn {
+            messagesExtra += ", reasoning_content TEXT"
+        }
+
+        let schema = """
+        CREATE TABLE sessions (
+            id TEXT PRIMARY KEY,
+            source TEXT,
+            user_id TEXT,
+            model TEXT,
+            title TEXT,
+            parent_session_id TEXT,
+            started_at REAL,
+            ended_at REAL,
+            end_reason TEXT,
+            message_count INTEGER,
+            tool_call_count INTEGER,
+            input_tokens INTEGER,
+            output_tokens INTEGER,
+            cache_read_tokens INTEGER,
+            cache_write_tokens INTEGER,
+            estimated_cost_usd REAL\(sessionsExtra)
+        );
+        INSERT INTO sessions (id, source, user_id, model, title, parent_session_id, started_at, ended_at, end_reason, message_count, tool_call_count, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, estimated_cost_usd)
+        VALUES ('s1', 'acp', 'u1', 'gpt-5', 'Test', NULL, 1700000000.0, NULL, NULL, 5, 2, 100, 200, 0, 0, 0.05);
+        CREATE TABLE messages (
+            id INTEGER PRIMARY KEY,
+            session_id TEXT,
+            role TEXT,
+            content TEXT,
+            tool_call_id TEXT,
+            tool_calls TEXT,
+            tool_name TEXT,
+            timestamp REAL,
+            token_count INTEGER,
+            finish_reason TEXT\(messagesExtra)
+        );
+        INSERT INTO messages (id, session_id, role, content, tool_call_id, tool_calls, tool_name, timestamp, token_count, finish_reason)
+        VALUES (1, 's1', 'user', 'hi', NULL, NULL, NULL, 1700000001.0, NULL, NULL);
+        """
+        var errMsg: UnsafeMutablePointer<CChar>?
+        let rc = sqlite3_exec(db, schema, nil, nil, &errMsg)
+        if rc != SQLITE_OK {
+            let msg = errMsg.flatMap { String(cString: $0) } ?? "unknown"
+            sqlite3_free(errMsg)
+            throw TransportError.other(message: "sqlite3_exec failed: \(msg)")
+        }
+        return url
+    }
+
+    /// Construct a remote-shaped context whose `paths.stateDB` points at
+    /// the fixture file. We embed the absolute path under a fake
+    /// `remoteHome` whose final `/.hermes/state.db` resolves to our
+    /// real DB on disk.
+    private func makeFixtureContext(dbURL: URL) -> ServerContext {
+        // The DB the backend opens is `<paths.home>/state.db`. We point
+        // `remoteHome` at the parent dir of the fixture file and then
+        // symlink `state.db` to the fixture so the backend's resolved
+        // path lands on it.
+        let parent = dbURL.deletingLastPathComponent()
+        let stateLink = parent.appendingPathComponent("state.db")
+        // Replace any prior symlink/file at the canonical "state.db" path.
+        try? FileManager.default.removeItem(at: stateLink)
+        try? FileManager.default.createSymbolicLink(at: stateLink, withDestinationURL: dbURL)
+        return ServerContext(
+            id: UUID(),
+            displayName: "fixture",
+            kind: .ssh(SSHConfig(host: "fake.invalid", remoteHome: parent.path))
+        )
+    }
+
+    /// Construct a remote-shaped context that uses the default
+    /// `~/.hermes` remote home — exercises the tilde-expansion path
+    /// in `RemoteSQLiteBackend.quoteForRemoteShell`. The fixture DB
+    /// is symlinked at `$HOME/.hermes/state.db` so the shell-expanded
+    /// path resolves correctly. Cleanup restores anything we move.
+    /// Returns the original-symlink (or absent state) so the caller
+    /// can restore on teardown.
+    private struct DefaultHomeFixture {
+        let dbURL: URL
+        let stateLink: URL
+        let backupURL: URL?
+        let context: ServerContext
+    }
+    private func makeDefaultHomeFixtureContext(dbURL: URL) throws -> DefaultHomeFixture {
+        let homeURL = URL(fileURLWithPath: NSHomeDirectory())
+        let hermesDir = homeURL.appendingPathComponent(".hermes", isDirectory: true)
+        try FileManager.default.createDirectory(at: hermesDir, withIntermediateDirectories: true)
+        let stateLink = hermesDir.appendingPathComponent("state.db")
+        // If something is already at ~/.hermes/state.db (the user's
+        // real Hermes install on dev machines), move it aside so we
+        // can put our fixture in its place. Restore on teardown.
+        var backupURL: URL?
+        if FileManager.default.fileExists(atPath: stateLink.path) {
+            let bak = hermesDir.appendingPathComponent("state.db.scarf-test-bak-\(UUID().uuidString)")
+            try FileManager.default.moveItem(at: stateLink, to: bak)
+            backupURL = bak
+        }
+        try FileManager.default.createSymbolicLink(at: stateLink, withDestinationURL: dbURL)
+        let ctx = ServerContext(
+            id: UUID(),
+            displayName: "fixture",
+            kind: .ssh(SSHConfig(host: "fake.invalid"))
+            // No remoteHome override → defaults to "~/.hermes".
+        )
+        return DefaultHomeFixture(dbURL: dbURL, stateLink: stateLink, backupURL: backupURL, context: ctx)
+    }
+    private func cleanupDefaultHomeFixture(_ fixture: DefaultHomeFixture) {
+        try? FileManager.default.removeItem(at: fixture.stateLink)
+        if let bak = fixture.backupURL {
+            try? FileManager.default.moveItem(at: bak, to: fixture.stateLink)
+        }
+    }
+
+    /// Skip the test if /usr/bin/sqlite3 isn't available. Mirrors how
+    /// other Apple-only tests gate on system tooling.
+    private func requireSqlite3() throws {
+        let path = "/usr/bin/sqlite3"
+        let exists = FileManager.default.isExecutableFile(atPath: path)
+        try #require(exists, "Test requires /usr/bin/sqlite3")
+    }
+
+    // MARK: - open() / schema detection
+
+    /// Regression: a default-config remote with `paths.stateDB ==
+    /// "~/.hermes/state.db"` previously hit `unable to open database
+    /// "~/.hermes/state.db"` because the backend single-quoted the
+    /// path and sqlite3 doesn't expand `~` itself. Verify the
+    /// $HOME-rewrite path works against a real shell.
+    @Test func openWithDefaultTildeHomeExpands() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        let fixture = try makeDefaultHomeFixtureContext(dbURL: dbURL)
+        defer {
+            cleanupDefaultHomeFixture(fixture)
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent())
+        }
+        let backend = RemoteSQLiteBackend(context: fixture.context, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened)
+        let err = await backend.lastOpenError
+        #expect(err == nil)
+
+        // And actually run a query through the same expansion path.
+        let rows = try await backend.query("SELECT id FROM sessions", params: [])
+        #expect(rows.count == 1)
+    }
+
+    @Test func openProbesSchemaSuccessfully() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened)
+        let v07 = await backend.hasV07Schema
+        let v011 = await backend.hasV011Schema
+        #expect(v07 == false)
+        #expect(v011 == false)
+        let err = await backend.lastOpenError
+        #expect(err == nil)
+    }
+
+    @Test func openOnV07SchemaDB() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB(addV07Columns: true)
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened)
+        let v07 = await backend.hasV07Schema
+        let v011 = await backend.hasV011Schema
+        #expect(v07 == true)
+        #expect(v011 == false)
+    }
+
+    @Test func openOnV011SchemaDB() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB(
+            addV07Columns: true,
+            addV011SessionsColumn: true,
+            addV011MessagesColumn: true
+        )
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened)
+        let v011 = await backend.hasV011Schema
+        #expect(v011 == true)
+    }
+
+    @Test func partialMigrationStaysOnV07() async throws {
+        try requireSqlite3()
+        // sessions has api_call_count but messages lacks reasoning_content
+        // — the belt-and-braces guard should keep hasV011Schema false.
+        let dbURL = try makeFixtureStateDB(
+            addV07Columns: true,
+            addV011SessionsColumn: true,
+            addV011MessagesColumn: false
+        )
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened)
+        let v011 = await backend.hasV011Schema
+        #expect(v011 == false)
+        let v07 = await backend.hasV07Schema
+        #expect(v07 == true)
+    }
+
+    // MARK: - query()
+
+    @Test func queryReturnsRows() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        let rows = try await backend.query("SELECT id FROM sessions", params: [])
+        #expect(rows.count == 1)
+        if case .text(let id) = rows[0][0] {
+            #expect(id == "s1")
+        } else {
+            Issue.record("Expected .text id, got \(rows[0][0])")
+        }
+    }
+
+    @Test func queryWithIntParam() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        let rows = try await backend.query(
+            "SELECT id FROM sessions WHERE message_count >= ?",
+            params: [.integer(5)]
+        )
+        #expect(rows.count == 1)
+    }
+
+    @Test func queryWithTextParamEscapesQuotes() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        // Injection-shaped value — should be escaped to a harmless literal,
+        // matching nothing in the fixture.
+        let rows = try await backend.query(
+            "SELECT id FROM sessions WHERE id = ?",
+            params: [.text("s' OR 1=1 --")]
+        )
+        #expect(rows.isEmpty)
+    }
+
+    @Test func queryEmptyResultSet() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        let rows = try await backend.query(
+            "SELECT id FROM sessions WHERE id = ?",
+            params: [.text("does-not-exist")]
+        )
+        #expect(rows.isEmpty)
+    }
+
+    @Test func queryNullValuesPreserved() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        let rows = try await backend.query(
+            "SELECT id, ended_at, end_reason FROM sessions WHERE id = ?",
+            params: [.text("s1")]
+        )
+        #expect(rows.count == 1)
+        // ended_at and end_reason are NULL in the fixture row.
+        #expect(rows[0].isNull(at: 1))
+        #expect(rows[0].isNull(at: 2))
+    }
+
+    // MARK: - queryBatch()
+
+    @Test func queryBatchSplitsResultsCorrectly() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        let results = try await backend.queryBatch([
+            (sql: "SELECT id FROM sessions", params: []),
+            (sql: "SELECT id FROM messages WHERE session_id = ?", params: [.text("s1")]),
+            (sql: "SELECT COUNT(*) FROM sessions", params: [])
+        ])
+        #expect(results.count == 3)
+        // Slot 0: one session row.
+        #expect(results[0].count == 1)
+        if case .text(let sid) = results[0][0][0] {
+            #expect(sid == "s1")
+        } else {
+            Issue.record("Expected .text in slot 0")
+        }
+        // Slot 1: one message row.
+        #expect(results[1].count == 1)
+        // Slot 2: one count row with integer 1.
+        #expect(results[2].count == 1)
+        if case .integer(let n) = results[2][0][0] {
+            #expect(n == 1)
+        } else {
+            Issue.record("Expected .integer in slot 2")
+        }
+    }
+
+    @Test func queryBatchHandlesEmptyResultSets() async throws {
+        try requireSqlite3()
+        let dbURL = try makeFixtureStateDB()
+        defer {
+            try? FileManager.default.removeItem(at: dbURL)
+            try? FileManager.default.removeItem(at: dbURL.deletingLastPathComponent().appendingPathComponent("state.db"))
+        }
+        let ctx = makeFixtureContext(dbURL: dbURL)
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+        _ = await backend.open()
+
+        // Middle statement returns 0 rows; outer slots should still be
+        // populated correctly.
+        let results = try await backend.queryBatch([
+            (sql: "SELECT id FROM sessions", params: []),
+            (sql: "SELECT id FROM messages WHERE session_id = ?", params: [.text("does-not-exist")]),
+            (sql: "SELECT COUNT(*) FROM messages", params: [])
+        ])
+        #expect(results.count == 3)
+        #expect(results[0].count == 1)
+        #expect(results[1].isEmpty)
+        #expect(results[2].count == 1)
+    }
+
+    // MARK: - Failure paths
+
+    @Test func nonZeroExitThrowsSqliteError() async throws {
+        try requireSqlite3()
+        // Point at a parent dir with no state.db symlink — sqlite3 will
+        // open a brand-new empty DB, so the schema PRAGMAs return empty
+        // tables. That actually succeeds. Instead, point remoteHome at
+        // a path under a non-existent directory so sqlite3 can't open
+        // the file at all.
+        let nonExistentParent = "/var/empty/scarf-test-no-such-dir-\(UUID().uuidString)"
+        let ctx = ServerContext(
+            id: UUID(),
+            displayName: "broken",
+            kind: .ssh(SSHConfig(host: "fake.invalid", remoteHome: nonExistentParent))
+        )
+        let backend = RemoteSQLiteBackend(context: ctx, transport: LocalSQLite3Transport())
+
+        let opened = await backend.open()
+        #expect(opened == false)
+        let err = await backend.lastOpenError
+        #expect(err != nil)
+        #expect(!(err ?? "").isEmpty)
+    }
+}
+
+#endif // canImport(SQLite3)

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/SQLValueInlinerTests.swift

@@ -0,0 +1,147 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Pure unit tests on `SQLValueInliner.inline(_:params:)` and
+/// `SQLValueInliner.encode(_:)`. No backend, no transport, no actor —
+/// these are the lexical-substitution rules that drive the remote
+/// SQLite backend's `?` → literal pipeline.
+@Suite struct SQLValueInlinerTests {
+
+    // MARK: - encode(_:) per SQLValue case
+
+    @Test func encodeNullProducesNULL() {
+        #expect(SQLValueInliner.encode(.null) == "NULL")
+    }
+
+    @Test func encodeIntegerProducesUnquotedDigits() {
+        #expect(SQLValueInliner.encode(.integer(42)) == "42")
+        #expect(SQLValueInliner.encode(.integer(-7)) == "-7")
+        #expect(SQLValueInliner.encode(.integer(0)) == "0")
+        #expect(SQLValueInliner.encode(.integer(Int64.max)) == "9223372036854775807")
+    }
+
+    @Test func encodeRealUsesPercent17gFormat() {
+        // %.17g round-trips a Double precisely as decimal. Verify the
+        // formatted string parses back to the exact same Double.
+        let original: Double = 3.14
+        let encoded = SQLValueInliner.encode(.real(original))
+        #expect(encoded == String(format: "%.17g", original))
+        // Round-trip: encoded value re-parsed must equal the source.
+        #expect(Double(encoded) == original)
+
+        // Tricky case: 0.1 + 0.2 has imprecise binary representation.
+        let imprecise = 0.1 + 0.2
+        let encodedImprecise = SQLValueInliner.encode(.real(imprecise))
+        #expect(Double(encodedImprecise) == imprecise)
+    }
+
+    @Test func encodeTextWrapsInSingleQuotes() {
+        #expect(SQLValueInliner.encode(.text("hi")) == "'hi'")
+        #expect(SQLValueInliner.encode(.text("")) == "''")
+    }
+
+    @Test func encodeTextDoublesEmbeddedSingleQuotes() {
+        // SQL literal escape: `it's` becomes `'it''s'`.
+        #expect(SQLValueInliner.encode(.text("it's")) == "'it''s'")
+        // Multiple embedded quotes — each one is doubled.
+        #expect(SQLValueInliner.encode(.text("a'b'c")) == "'a''b''c'")
+        // The classic injection-shaped value gets escaped to harmless.
+        #expect(SQLValueInliner.encode(.text("' OR 1=1 --")) == "''' OR 1=1 --'")
+    }
+
+    @Test func encodeBlobProducesHexLiteral() {
+        // Two-byte blob: `X'dead'`.
+        #expect(SQLValueInliner.encode(.blob(Data([0xde, 0xad]))) == "X'dead'")
+        // Empty blob: `X''`.
+        #expect(SQLValueInliner.encode(.blob(Data())) == "X''")
+        // Lowercase hex, full byte range, with leading zero preserved.
+        #expect(SQLValueInliner.encode(.blob(Data([0x00, 0x0f, 0xff]))) == "X'000fff'")
+    }
+
+    // MARK: - inline(_:params:) substitution rules
+
+    @Test func inlineSubstitutesPlaceholdersInOrder() {
+        let out = SQLValueInliner.inline(
+            "INSERT INTO t VALUES (?, ?, ?)",
+            params: [.integer(1), .text("two"), .real(3.0)]
+        )
+        // Order is preserved: integer 1, text 'two', real 3.0.
+        #expect(out.hasPrefix("INSERT INTO t VALUES ("))
+        #expect(out.contains("1"))
+        #expect(out.contains("'two'"))
+        // Real 3.0 should round-trip via %.17g.
+        let real3 = String(format: "%.17g", 3.0)
+        #expect(out.contains(real3))
+    }
+
+    @Test func inlineSkipsPlaceholderInsideStringLiteral() {
+        // The `?` inside `'?'` is part of a string and must not be bound.
+        // Only the trailing `?` (outside the quotes) consumes the param.
+        let out = SQLValueInliner.inline(
+            "WHERE name = '?' AND id = ?",
+            params: [.integer(7)]
+        )
+        #expect(out == "WHERE name = '?' AND id = 7")
+    }
+
+    @Test func inlineSkipsPlaceholderInsideDoubleQuotedIdentifier() {
+        // Double-quoted identifiers (column / table names with special chars)
+        // are also a quoted region — `?` inside them is literal.
+        let out = SQLValueInliner.inline(
+            "SELECT \"col?\" FROM t WHERE x = ?",
+            params: [.integer(1)]
+        )
+        #expect(out == "SELECT \"col?\" FROM t WHERE x = 1")
+    }
+
+    @Test func inlineHandlesDoubledSingleQuoteEscapeInString() {
+        // `'it''s ?'` is a single SQL string literal containing `it's ?`.
+        // The doubled single-quote is the SQL escape for an embedded
+        // apostrophe — the scanner must NOT toggle out of string state
+        // at the doubled quote, and the trailing `?` is inside the string.
+        // No params consumed.
+        let out = SQLValueInliner.inline(
+            "WHERE x = 'it''s ?'",
+            params: []
+        )
+        #expect(out == "WHERE x = 'it''s ?'")
+    }
+
+    @Test func inlineSelectShapeMatchesDataServicePattern() {
+        // Sanity check: the SELECT shape `HermesDataService.fetchSessions`
+        // generates inlines cleanly for the typical `[.integer(100)]`
+        // limit param.
+        let sql = "SELECT id, source FROM sessions WHERE parent_session_id IS NULL ORDER BY started_at DESC LIMIT ?"
+        let out = SQLValueInliner.inline(sql, params: [.integer(100)])
+        #expect(out == "SELECT id, source FROM sessions WHERE parent_session_id IS NULL ORDER BY started_at DESC LIMIT 100")
+    }
+
+    @Test func inlineWithNoPlaceholdersReturnsInputUnchanged() {
+        let sql = "SELECT COUNT(*) FROM messages"
+        #expect(SQLValueInliner.inline(sql, params: []) == sql)
+    }
+
+    @Test func inlinePreservesAllOtherCharacters() {
+        // Make sure we're not mangling whitespace, semicolons, parens.
+        let sql = "  SELECT  *\n  FROM   t  WHERE id = ?  ;  "
+        let out = SQLValueInliner.inline(sql, params: [.integer(5)])
+        #expect(out == "  SELECT  *\n  FROM   t  WHERE id = 5  ;  ")
+    }
+
+    @Test func inlineSubstitutesNullPlaceholder() {
+        let out = SQLValueInliner.inline(
+            "UPDATE t SET col = ? WHERE id = ?",
+            params: [.null, .integer(1)]
+        )
+        #expect(out == "UPDATE t SET col = NULL WHERE id = 1")
+    }
+
+    @Test func inlineSubstitutesBlobPlaceholder() {
+        let out = SQLValueInliner.inline(
+            "INSERT INTO t (data) VALUES (?)",
+            params: [.blob(Data([0x01, 0x02, 0x03]))]
+        )
+        #expect(out == "INSERT INTO t (data) VALUES (X'010203')")
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/SSHScriptRunnerTests.swift

@@ -0,0 +1,85 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Regression tests for `SSHScriptRunner`. Mac-only because the
+/// implementation relies on `Foundation.Process`, which doesn't exist
+/// on Swift Linux. Drives the `runLocally` path so we don't need an
+/// SSH endpoint in CI.
+#if os(macOS)
+@Suite struct SSHScriptRunnerTests {
+
+    /// Issue #77 regression. Pre-fix the runner read stdout via
+    /// `readToEnd()` *after* the subprocess exited; once the script's
+    /// output crossed the kernel's pipe buffer (16–64 KB on macOS) the
+    /// process wedged because nothing was draining the read end. The
+    /// only visible symptom was a 30-second timeout and an empty
+    /// result.
+    ///
+    /// This script writes ~256 KB of bytes — comfortably past every
+    /// pipe-buffer threshold. With the readabilityHandler drain in
+    /// place the run should complete in well under a second and
+    /// return the full payload.
+    @Test func drainsLargeStdoutWithoutTimeout() async throws {
+        // 256 lines × 1024 bytes/line = 256 KB.
+        let script = """
+        for i in $(seq 1 256); do
+            printf '%04d:' "$i"
+            printf '%.0sx' $(seq 1 1018)
+            printf '\\n'
+        done
+        """
+        let outcome = await SSHScriptRunner.run(
+            script: script,
+            context: .local,
+            timeout: 10
+        )
+        switch outcome {
+        case .completed(let stdout, _, let exitCode):
+            #expect(exitCode == 0)
+            // 256 lines + final newline.
+            let lines = stdout.split(separator: "\n", omittingEmptySubsequences: false)
+            #expect(lines.count >= 256)
+            #expect(stdout.utf8.count >= 256 * 1024)
+        case .connectFailure(let reason):
+            Issue.record("Expected completion, got connectFailure: \(reason)")
+        }
+    }
+
+    /// Sanity check that small scripts still come back the way they
+    /// did before the drain refactor. Guards against an off-by-one in
+    /// the readability handler that swallowed trailing bytes.
+    @Test func smallScriptPayloadRoundTrips() async throws {
+        let outcome = await SSHScriptRunner.run(
+            script: "printf 'hello\\n' && printf 'world\\n' >&2 && exit 0",
+            context: .local,
+            timeout: 5
+        )
+        switch outcome {
+        case .completed(let stdout, let stderr, let exitCode):
+            #expect(exitCode == 0)
+            #expect(stdout == "hello\n")
+            #expect(stderr == "world\n")
+        case .connectFailure(let reason):
+            Issue.record("Expected completion, got connectFailure: \(reason)")
+        }
+    }
+
+    /// Non-zero exit codes should still be reported as `.completed`
+    /// with the captured stdout/stderr — unchanged contract.
+    @Test func nonZeroExitIsReportedAsCompleted() async throws {
+        let outcome = await SSHScriptRunner.run(
+            script: "echo nope >&2 && exit 7",
+            context: .local,
+            timeout: 5
+        )
+        switch outcome {
+        case .completed(_, let stderr, let exitCode):
+            #expect(exitCode == 7)
+            #expect(stderr.contains("nope"))
+        case .connectFailure(let reason):
+            Issue.record("Expected completion, got connectFailure: \(reason)")
+        }
+    }
+}
+#endif

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/ScarfMonTests.swift

@@ -0,0 +1,202 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// `.serialized` because every test that exercises the wrappers
+/// (`measure`, `measureAsync`, `event`) installs and uninstalls the
+/// process-wide backend set, and parallel tests would race on that
+/// shared state. Tests of the ring buffer in isolation don't need
+/// serialization, but the suite-level annotation is the simplest way
+/// to keep the global-state ones honest.
+@Suite(.serialized) struct ScarfMonTests {
+
+    /// Ring-buffer ordering — fewer than capacity, no wrap.
+    @Test func ringBufferKeepsOrderBeforeWrap() {
+        let ring = ScarfMonRingBuffer(capacity: 8)
+        ring.record(.fixture(name: "a"))
+        ring.record(.fixture(name: "b"))
+        ring.record(.fixture(name: "c"))
+        let names = ring.samples().map { $0.name.description }
+        #expect(names == ["a", "b", "c"])
+    }
+
+    /// Ring-buffer wrap-around — the oldest entries are dropped, the
+    /// newest entries appear at the end.
+    @Test func ringBufferWrapsCorrectly() {
+        let ring = ScarfMonRingBuffer(capacity: 4)
+        ring.record(.fixture(name: "a"))
+        ring.record(.fixture(name: "b"))
+        ring.record(.fixture(name: "c"))
+        ring.record(.fixture(name: "d"))
+        ring.record(.fixture(name: "e"))
+        ring.record(.fixture(name: "f"))
+        let names = ring.samples().map { $0.name.description }
+        #expect(names == ["c", "d", "e", "f"])
+    }
+
+    /// Reset clears the buffer and resets wrap state — subsequent reads
+    /// see only post-reset entries.
+    @Test func ringBufferResetClearsState() {
+        let ring = ScarfMonRingBuffer(capacity: 4)
+        ring.record(.fixture(name: "a"))
+        ring.record(.fixture(name: "b"))
+        ring.record(.fixture(name: "c"))
+        ring.record(.fixture(name: "d"))
+        ring.record(.fixture(name: "e"))
+        ring.reset()
+        ring.record(.fixture(name: "x"))
+        let names = ring.samples().map { $0.name.description }
+        #expect(names == ["x"])
+    }
+
+    /// Summary aggregates per (category, name) and computes percentiles.
+    @Test func summaryAggregatesByCategoryAndName() {
+        let ring = ScarfMonRingBuffer(capacity: 16)
+        // Three "fast" intervals + two "slow" intervals on the same key.
+        for nanos: UInt64 in [1_000_000, 2_000_000, 3_000_000, 50_000_000, 100_000_000] {
+            ring.record(.fixture(name: "render", durationNanos: nanos))
+        }
+        let stats = ring.summary()
+        #expect(stats.count == 1)
+        let s = stats[0]
+        #expect(s.count == 5)
+        #expect(s.totalNanos == 156_000_000)
+        // Nearest-rank p95 with 5 samples picks the 5th sorted value
+        // (rank = ceil(5 * 0.95) = 5).
+        #expect(s.p95Nanos == 100_000_000)
+        // p50 with 5 samples picks the 3rd sorted value.
+        #expect(s.p50Nanos == 3_000_000)
+    }
+
+    /// Events accumulate count + bytes without contributing to interval
+    /// percentiles.
+    @Test func eventsAccumulateBytesNotDuration() {
+        let ring = ScarfMonRingBuffer(capacity: 16)
+        ring.record(ScarfMon.Sample(
+            category: .chatStream, name: "token", kind: .event,
+            timestamp: Date(), durationNanos: 0, count: 1, bytes: 256
+        ))
+        ring.record(ScarfMon.Sample(
+            category: .chatStream, name: "token", kind: .event,
+            timestamp: Date(), durationNanos: 0, count: 1, bytes: 128
+        ))
+        let stats = ring.summary()
+        #expect(stats.count == 1)
+        #expect(stats[0].count == 2)
+        #expect(stats[0].totalBytes == 384)
+        #expect(stats[0].p95Nanos == 0)
+    }
+
+    /// `isActive` flips off when the backend set is empty so the
+    /// hot-path short-circuit kicks in.
+    @Test func installEmptyBackendsDeactivates() {
+        ScarfMon.install([])
+        #expect(ScarfMon.isActive == false)
+        ScarfMon.install([ScarfMonRingBuffer(capacity: 4)])
+        #expect(ScarfMon.isActive == true)
+        ScarfMon.install([])
+    }
+
+    /// `measure` records a duration into every installed backend.
+    @Test func measureFlowsThroughInstalledBackends() throws {
+        let ring = ScarfMonRingBuffer(capacity: 8)
+        ScarfMon.install([ring])
+        defer { ScarfMon.install([]) }
+
+        let result: Int = ScarfMon.measure(.render, "unit") {
+            return 42
+        }
+        #expect(result == 42)
+        let samples = ring.samples()
+        #expect(samples.count == 1)
+        #expect(samples[0].kind == .interval)
+        #expect(samples[0].name.description == "unit")
+    }
+
+    /// `measureAsync` records duration even when the body throws — the
+    /// `defer` in the wrapper must fire on rethrow.
+    @Test func measureAsyncRecordsDurationEvenOnThrow() async {
+        struct Boom: Error {}
+        let ring = ScarfMonRingBuffer(capacity: 8)
+        ScarfMon.install([ring])
+        defer { ScarfMon.install([]) }
+
+        await #expect(throws: Boom.self) {
+            try await ScarfMon.measureAsync(.chatStream, "throws") {
+                throw Boom()
+            }
+        }
+        let samples = ring.samples()
+        #expect(samples.count == 1)
+        #expect(samples[0].name.description == "throws")
+    }
+
+    /// `event(...)` records a count entry without taking a clock reading.
+    @Test func eventRecordsCountSample() {
+        let ring = ScarfMonRingBuffer(capacity: 8)
+        ScarfMon.install([ring])
+        defer { ScarfMon.install([]) }
+
+        ScarfMon.event(.chatStream, "token", count: 1, bytes: 32)
+        let samples = ring.samples()
+        #expect(samples.count == 1)
+        #expect(samples[0].kind == .event)
+        #expect(samples[0].count == 1)
+        #expect(samples[0].bytes == 32)
+        #expect(samples[0].durationNanos == 0)
+    }
+
+    /// Boot configure flips the active backend set without leaking
+    /// across tests.
+    @Test func bootConfigureModesInstallExpectedBackends() {
+        defer { ScarfMon.install([]) }
+
+        ScarfMonBoot.configure(mode: .off)
+        #expect(ScarfMon.currentBackends.isEmpty)
+        #expect(ScarfMonBoot.sharedRingBuffer == nil)
+
+        ScarfMonBoot.configure(mode: .signpostOnly)
+        #expect(ScarfMon.currentBackends.count == 1)
+        #expect(ScarfMonBoot.sharedRingBuffer == nil)
+
+        let ring = ScarfMonBoot.configure(mode: .full)
+        #expect(ring != nil)
+        #expect(ScarfMon.currentBackends.count == 3)
+        #expect(ScarfMonBoot.sharedRingBuffer === ring)
+    }
+
+    /// JSON export round-trips through `JSONSerialization` — proves the
+    /// per-line format is valid JSON the user can paste into a feedback
+    /// tool.
+    @Test func exportJSONIsParseable() throws {
+        let ring = ScarfMonRingBuffer(capacity: 8)
+        ring.record(.fixture(name: "a", durationNanos: 1_500_000))
+        ring.record(ScarfMon.Sample(
+            category: .chatStream, name: "token", kind: .event,
+            timestamp: Date(), durationNanos: 0, count: 1, bytes: 64
+        ))
+        let json = ring.exportJSON()
+        let data = json.data(using: .utf8)!
+        let parsed = try JSONSerialization.jsonObject(with: data, options: [])
+        let arr = parsed as? [[String: Any]]
+        #expect(arr?.count == 2)
+    }
+}
+
+private extension ScarfMon.Sample {
+    static func fixture(
+        category: ScarfMon.Category = .render,
+        name: StaticString,
+        durationNanos: UInt64 = 1_000_000
+    ) -> ScarfMon.Sample {
+        ScarfMon.Sample(
+            category: category,
+            name: name,
+            kind: .interval,
+            timestamp: Date(),
+            durationNanos: durationNanos,
+            count: 1,
+            bytes: nil
+        )
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/SecretsEnvBlockTests.swift

@@ -0,0 +1,312 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Pure-logic tests for the marker-block splice helpers in
+/// `SecretsEnvBlock`. No Keychain access, no filesystem I/O — just
+/// strings in, strings out. The Mac-side `KeychainEnvMirror` wraps
+/// these with Keychain resolution + transport-aware writes; that
+/// integration is covered separately in `KeychainEnvMirrorTests`.
+@Suite("SecretsEnvBlock")
+struct SecretsEnvBlockTests {
+
+    // MARK: - envKeyName
+
+    @Test func envKeyNameStandardCase() {
+        #expect(
+            SecretsEnvBlock.envKeyName(slug: "local-news", fieldKey: "api_token")
+                == "SCARF_LOCAL_NEWS_API_TOKEN"
+        )
+    }
+
+    @Test func envKeyNameNonAlphanumericChars() {
+        // Dashes, underscores, dots, spaces all fold to single underscores.
+        #expect(
+            SecretsEnvBlock.envKeyName(slug: "foo.bar baz", fieldKey: "x-y-z")
+                == "SCARF_FOO_BAR_BAZ_X_Y_Z"
+        )
+    }
+
+    @Test func envKeyNameRunsCollapse() {
+        // Three consecutive special chars produce a single underscore,
+        // not three.
+        #expect(
+            SecretsEnvBlock.envKeyName(slug: "foo---bar", fieldKey: "a__b")
+                == "SCARF_FOO_BAR_A_B"
+        )
+    }
+
+    @Test func envKeyNameLeadingTrailingTrim() {
+        // Leading/trailing dashes on the slug shouldn't produce
+        // SCARF__... or trailing _ in the result.
+        let key = SecretsEnvBlock.envKeyName(slug: "-foo-", fieldKey: "-bar-")
+        #expect(key == "SCARF_FOO_BAR")
+        #expect(!key.hasSuffix("_"))
+        #expect(!key.contains("__"))
+    }
+
+    @Test func envKeyNameAllSymbolsFallsBackToUnnamed() {
+        // Pathological input — slug is all special chars. Sanitizer
+        // emits `UNNAMED` rather than the empty string, so the env
+        // var name is still parseable.
+        #expect(
+            SecretsEnvBlock.envKeyName(slug: "!!!", fieldKey: "...")
+                == "SCARF_UNNAMED_UNNAMED"
+        )
+    }
+
+    // MARK: - renderBlock
+
+    @Test func renderBlockEmptyEntriesReturnsEmpty() {
+        // Empty entries is the documented "use removeBlock instead"
+        // sentinel — renderBlock should not produce a block with
+        // dangling markers.
+        let result = SecretsEnvBlock.renderBlock(slug: "foo", entries: [])
+        #expect(result.isEmpty)
+    }
+
+    @Test func renderBlockSortsEntries() {
+        // Output is deterministic regardless of input order so two
+        // runs with the same logical content produce byte-identical
+        // bytes — load-bearing for the no-op-when-unchanged check
+        // in the mirror's writeIfChanged.
+        let aFirst = SecretsEnvBlock.renderBlock(
+            slug: "foo",
+            entries: [("ALPHA", "1"), ("BRAVO", "2")]
+        )
+        let bFirst = SecretsEnvBlock.renderBlock(
+            slug: "foo",
+            entries: [("BRAVO", "2"), ("ALPHA", "1")]
+        )
+        #expect(aFirst == bFirst)
+        // Sanity: ALPHA precedes BRAVO in the output regardless of
+        // insertion order.
+        let alphaIdx = aFirst.range(of: "ALPHA")
+        let bravoIdx = aFirst.range(of: "BRAVO")
+        #expect(alphaIdx != nil && bravoIdx != nil)
+        #expect(alphaIdx!.lowerBound < bravoIdx!.lowerBound)
+    }
+
+    @Test func renderBlockEmitsMarkersAroundEntries() {
+        let result = SecretsEnvBlock.renderBlock(
+            slug: "site-status-checker",
+            entries: [("SCARF_SITE_STATUS_CHECKER_TOKEN", "abc")]
+        )
+        #expect(result.hasPrefix("# scarf-secrets:begin site-status-checker"))
+        #expect(result.hasSuffix("# scarf-secrets:end site-status-checker"))
+        #expect(result.contains("SCARF_SITE_STATUS_CHECKER_TOKEN=abc"))
+    }
+
+    @Test func renderBlockQuotesValuesWithWhitespace() {
+        let result = SecretsEnvBlock.renderBlock(
+            slug: "x",
+            entries: [("KEY", "hello world")]
+        )
+        // Whitespace forces single-quoting (dotenv canonical) so the
+        // value survives shell expansion and dotenv parsing.
+        #expect(result.contains("KEY='hello world'"))
+    }
+
+    @Test func renderBlockQuotesValuesWithSpecialChars() {
+        let cases: [(input: String, mustContain: String)] = [
+            ("a#b", "KEY='a#b'"),     // # is dotenv comment marker
+            ("a$b", "KEY='a$b'"),     // $ is shell expansion
+            ("a\"b", "KEY='a\"b'"),   // " conflicts with double-quote literal
+            ("a\\b", "KEY='a\\b'"),   // backslash needs escaping
+        ]
+        for (input, mustContain) in cases {
+            let result = SecretsEnvBlock.renderBlock(
+                slug: "x",
+                entries: [("KEY", input)]
+            )
+            #expect(
+                result.contains(mustContain),
+                "value '\(input)' produced wrong escaping: \(result)"
+            )
+        }
+    }
+
+    @Test func renderBlockEscapesSingleQuotesViaCloseReopen() {
+        // A literal single quote inside a single-quoted string is
+        // dotenv-encoded as `'\''` (close, escape, reopen) — the
+        // canonical sh/dotenv pattern.
+        let result = SecretsEnvBlock.renderBlock(
+            slug: "x",
+            entries: [("KEY", "it's fine")]
+        )
+        #expect(result.contains("KEY='it'\\''s fine'"))
+    }
+
+    @Test func renderBlockLeavesPlainValuesUnquoted() {
+        // No-special-chars values stay unquoted — readability + matches
+        // the convention Hermes's existing ANTHROPIC_API_KEY entries
+        // follow.
+        let result = SecretsEnvBlock.renderBlock(
+            slug: "x",
+            entries: [("KEY", "abc-123_def")]
+        )
+        #expect(result.contains("\nKEY=abc-123_def\n"))
+        #expect(!result.contains("KEY='abc-123_def'"))
+    }
+
+    // MARK: - applyBlock
+
+    @Test func applyBlockToEmptyFile() {
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let result = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: "")
+        #expect(result == block + "\n")
+    }
+
+    @Test func applyBlockToWhitespaceOnlyFile() {
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let result = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: "   \n  \n")
+        // Whitespace-only treated like empty — block + newline, no
+        // attempt to preserve the leading whitespace.
+        #expect(result == block + "\n")
+    }
+
+    @Test func applyBlockAppendsToFileWithUserContent() {
+        let existing = "ANTHROPIC_API_KEY=sk-test\nOPENAI_API_KEY=sk-other\n"
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let result = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: existing)
+        // User content is preserved at the top.
+        #expect(result.hasPrefix("ANTHROPIC_API_KEY=sk-test"))
+        #expect(result.contains("OPENAI_API_KEY=sk-other"))
+        // Block appended after a blank-line separator.
+        #expect(result.contains("OPENAI_API_KEY=sk-other\n\n# scarf-secrets:begin foo"))
+        // And ends with a trailing newline.
+        #expect(result.hasSuffix("\n"))
+    }
+
+    @Test func applyBlockReplacesExistingBlockForSameSlug() {
+        let oldBlock = sampleBlock(slug: "foo", entries: [("KEY", "old")])
+        let newBlock = sampleBlock(slug: "foo", entries: [("KEY", "new")])
+        let existing = "USER_VAR=something\n\n" + oldBlock + "\n"
+        let result = SecretsEnvBlock.applyBlock(newBlock, forSlug: "foo", to: existing)
+        #expect(result.contains("KEY=new"))
+        #expect(!result.contains("KEY=old"))
+        // User content above the block is preserved.
+        #expect(result.contains("USER_VAR=something"))
+    }
+
+    @Test func applyBlockPreservesOtherSlugBlocks() {
+        // The most important invariant — multiple project blocks
+        // coexist in one file and editing one mustn't disturb the
+        // other.
+        let blockA = sampleBlock(slug: "alpha", entries: [("A_KEY", "1")])
+        let blockB = sampleBlock(slug: "bravo", entries: [("B_KEY", "2")])
+        let existing = blockA + "\n\n" + blockB + "\n"
+        let updatedA = sampleBlock(slug: "alpha", entries: [("A_KEY", "1-updated")])
+        let result = SecretsEnvBlock.applyBlock(updatedA, forSlug: "alpha", to: existing)
+        // A was updated.
+        #expect(result.contains("A_KEY=1-updated"))
+        #expect(!result.contains("A_KEY=1\n"))
+        // B is byte-identical.
+        #expect(result.contains(blockB))
+    }
+
+    @Test func applyBlockIdempotent() {
+        // Applying the output of one call back through applyBlock
+        // with the same inputs produces the same string. Critical
+        // for the launch reconciler — a no-op pass shouldn't keep
+        // mutating the file.
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let existing = "USER_VAR=x\n"
+        let once = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: existing)
+        let twice = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: once)
+        #expect(once == twice)
+    }
+
+    @Test func applyBlockEmptyBlockBehavesLikeRemove() {
+        // Documented behaviour: passing an empty block is the same as
+        // calling removeBlock — the splice path uses this when a
+        // project's secrets are all cleared.
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let withBlock = "USER=x\n\n" + block + "\n"
+        let viaApply = SecretsEnvBlock.applyBlock("", forSlug: "foo", to: withBlock)
+        let viaRemove = SecretsEnvBlock.removeBlock(forSlug: "foo", from: withBlock)
+        #expect(viaApply == viaRemove)
+    }
+
+    // MARK: - removeBlock
+
+    @Test func removeBlockNoOpWhenAbsent() {
+        let existing = "USER_VAR=hello\nOTHER=world\n"
+        let result = SecretsEnvBlock.removeBlock(forSlug: "foo", from: existing)
+        #expect(result == existing)
+    }
+
+    @Test func removeBlockStripsBlockOnly() {
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let existing = "USER_VAR=x\n\n" + block + "\n\nMORE_USER=y\n"
+        let result = SecretsEnvBlock.removeBlock(forSlug: "foo", from: existing)
+        #expect(!result.contains("scarf-secrets"))
+        #expect(result.contains("USER_VAR=x"))
+        #expect(result.contains("MORE_USER=y"))
+    }
+
+    @Test func removeBlockCollapsesAppendedBlankLineSeparator() {
+        // Round-trip: append a block, then remove it. The blank line
+        // we inserted at append time should be absorbed so repeated
+        // install/uninstall cycles don't accumulate blank lines.
+        let block = sampleBlock(slug: "foo", entries: [("KEY", "value")])
+        let original = "USER_VAR=x\n"
+        let appended = SecretsEnvBlock.applyBlock(block, forSlug: "foo", to: original)
+        let removed = SecretsEnvBlock.removeBlock(forSlug: "foo", from: appended)
+        // Removed content should be very close to the original — at
+        // most one trailing newline difference. No accumulation of
+        // blank lines across the cycle.
+        #expect(removed.trimmingCharacters(in: .whitespacesAndNewlines)
+                == original.trimmingCharacters(in: .whitespacesAndNewlines))
+    }
+
+    // MARK: - Slug-prefix collision
+
+    @Test func slugPrefixCollisionIsolated() {
+        // A file with both `foo` and `foo-bar` blocks; editing `foo`
+        // must not match the `foo-bar` markers as a prefix-substring
+        // of the begin-line.
+        let blockShort = sampleBlock(slug: "foo", entries: [("SHORT", "1")])
+        let blockLong = sampleBlock(slug: "foo-bar", entries: [("LONG", "2")])
+        let existing = blockShort + "\n\n" + blockLong + "\n"
+        let updatedShort = sampleBlock(slug: "foo", entries: [("SHORT", "1-updated")])
+        let result = SecretsEnvBlock.applyBlock(updatedShort, forSlug: "foo", to: existing)
+        // Short was updated.
+        #expect(result.contains("SHORT=1-updated"))
+        #expect(!result.contains("SHORT=1\n"))
+        // Long block is byte-identical.
+        #expect(result.contains(blockLong))
+        // Both markers still present, exactly once each.
+        #expect(occurrences(of: "# scarf-secrets:begin foo\n", in: result) == 1)
+        #expect(occurrences(of: "# scarf-secrets:begin foo-bar\n", in: result) == 1)
+    }
+
+    @Test func removeBlockRespectsSlugPrefixIsolation() {
+        let blockShort = sampleBlock(slug: "foo", entries: [("SHORT", "1")])
+        let blockLong = sampleBlock(slug: "foo-bar", entries: [("LONG", "2")])
+        let existing = blockShort + "\n\n" + blockLong + "\n"
+        let result = SecretsEnvBlock.removeBlock(forSlug: "foo", from: existing)
+        // foo gone, foo-bar preserved byte-identically.
+        #expect(!result.contains("SHORT=1"))
+        #expect(result.contains(blockLong))
+    }
+
+    // MARK: - Helpers
+
+    private func sampleBlock(
+        slug: String,
+        entries: [(key: String, value: String)]
+    ) -> String {
+        SecretsEnvBlock.renderBlock(slug: slug, entries: entries)
+    }
+
+    private func occurrences(of needle: String, in haystack: String) -> Int {
+        var count = 0
+        var search = haystack.startIndex
+        while let range = haystack.range(of: needle, range: search..<haystack.endIndex) {
+            count += 1
+            search = range.upperBound
+        }
+        return count
+    }
+}

scarf/Packages/ScarfCore/Tests/ScarfCoreTests/SkillsViewModelHubFilterTests.swift

@@ -0,0 +1,98 @@
+import Testing
+import Foundation
+@testable import ScarfCore
+
+/// Issue #79 regression. `searchHub()` with `hubSource == "all"` must
+/// filter the cached browse list client-side (instead of shelling out
+/// to `hermes skills search`, which routes through Hermes's
+/// centralized index and can miss skills that browse aggregates from
+/// non-indexed registries — `honcho` was the user-reported example).
+///
+/// Source-specific searches keep the CLI path; that's not exercised
+/// here because it requires a live `hermes` binary — the existing
+/// HermesSkillsHubParser tests cover the parser side.
+@Suite("SkillsViewModel hub filter")
+@MainActor
+struct SkillsViewModelHubFilterTests {
+
+    private func makeViewModel() -> SkillsViewModel {
+        SkillsViewModel(context: .local)
+    }
+
+    private let stubBrowse: [HermesHubSkill] = [
+        HermesHubSkill(
+            identifier: "honcho",
+            name: "honcho",
+            description: "Memory provider for chat-scoped facts.",
+            source: "github"
+        ),
+        HermesHubSkill(
+            identifier: "1password",
+            name: "1password",
+            description: "Set up and use 1Password integration.",
+            source: "official"
+        ),
+        HermesHubSkill(
+            identifier: "spotify",
+            name: "spotify",
+            description: "Spotify skill — playback control via OAuth.",
+            source: "official"
+        ),
+    ]
+
+    @Test func allSourcesFilterMatchesByName() {
+        let vm = makeViewModel()
+        vm.lastBrowseResults = stubBrowse
+        vm.hubSource = "all"
+        vm.hubQuery = "honcho"
+        vm.searchHub()
+        #expect(vm.hubResults.count == 1)
+        #expect(vm.hubResults.first?.identifier == "honcho")
+        #expect(vm.isHubLoading == false)
+        #expect(vm.hubMessage == nil)
+    }
+
+    @Test func allSourcesFilterMatchesByDescription() {
+        let vm = makeViewModel()
+        vm.lastBrowseResults = stubBrowse
+        vm.hubSource = "all"
+        vm.hubQuery = "OAuth"
+        vm.searchHub()
+        #expect(vm.hubResults.count == 1)
+        #expect(vm.hubResults.first?.identifier == "spotify")
+    }
+
+    @Test func allSourcesFilterIsCaseInsensitive() {
+        let vm = makeViewModel()
+        vm.lastBrowseResults = stubBrowse
+        vm.hubSource = "all"
+        vm.hubQuery = "HONCHO"
+        vm.searchHub()
+        #expect(vm.hubResults.count == 1)
+        #expect(vm.hubResults.first?.identifier == "honcho")
+    }
+
+    @Test func allSourcesFilterEmptyMatchSetsMessage() {
+        let vm = makeViewModel()
+        vm.lastBrowseResults = stubBrowse
+        vm.hubSource = "all"
+        vm.hubQuery = "ringtone"
+        vm.searchHub()
+        #expect(vm.hubResults.isEmpty)
+        #expect(vm.hubMessage == "No matches")
+    }
+
+    /// Empty query should fall through to `browseHub()`, which on
+    /// `.local` with no Hermes installed will set isHubLoading=true
+    /// and not block the test. We just assert the early-return guard
+    /// kicked in by checking the cache was untouched.
+    @Test func emptyQueryFallsThroughToBrowse() {
+        let vm = makeViewModel()
+        vm.lastBrowseResults = stubBrowse
+        vm.hubSource = "all"
+        vm.hubQuery = ""
+        let cacheBefore = vm.lastBrowseResults
+        vm.searchHub()
+        #expect(vm.lastBrowseResults == cacheBefore)
+    }
+}

scarf/Packages/ScarfIOS/Sources/ScarfIOS/CitadelServerTransport.swift

@@ -58,6 +58,9 @@ public final class CitadelServerTransport: ServerTransport, @unchecked Sendable
 
     /// Shared directory under which cached SQLite snapshots land. On
     /// iOS this maps to `<Caches>/scarf/snapshots/<server-id>/`.
+    /// Stable per-server cache directory. Was used by the snapshot
+    /// pipeline pre-v2.7; kept for the cache-cleanup migration that
+    /// purges old snapshot files at first launch on the new build.
     private let snapshotBaseDir: URL
 
     /// Actor-serialized access to the one shared `SSHClient`. Opens
@@ -159,10 +162,108 @@ public final class CitadelServerTransport: ServerTransport, @unchecked Sendable
         AsyncThrowingStream { $0.finish() }
     }
 
-    // MARK: - ServerTransport: SQLite snapshot
+    // MARK: - ServerTransport: script streaming
 
-    public func snapshotSQLite(remotePath: String) throws -> URL {
-        try runSync { try await self.asyncSnapshotSQLite(remotePath: remotePath) }
+    /// Pipe `script` to `/bin/sh -s` over Citadel's exec channel.
+    ///
+    /// **Why base64.** Citadel's `executeCommandStream` doesn't expose
+    /// stdin in the version we're on, so we can't just open `sh -s` and
+    /// write the script. Instead we encode the script as base64, decode
+    /// it on the remote inline, and pipe the result into `sh`:
+    ///
+    ///     printf '%s' '<b64>' | base64 -d | /bin/sh
+    ///
+    /// `base64 -d` is universally available on Linux/macOS. The base64
+    /// blob travels as a single shell-safe argv token, so multi-line
+    /// scripts with `"$VAR"` references and nested quotes survive
+    /// untouched — same correctness guarantee as `SSHScriptRunner`'s
+    /// stdin-pipe approach.
+    public func streamScript(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+        try await ScarfMon.measureAsync(.transport, "ssh.streamScript") {
+            try await _streamScriptImpl(script, timeout: timeout)
+        }
+    }
+
+    private func _streamScriptImpl(_ script: String, timeout: TimeInterval) async throws -> ProcessResult {
+        let scriptBytes = Data(script.utf8)
+        let b64 = scriptBytes.base64EncodedString()
+        // Prepend the same PATH guard that `asyncRunProcess` uses so
+        // base64 + sh resolve on hosts where they live in non-default
+        // prefixes. Most distros have base64 in /usr/bin but
+        // homebrew-installed coreutils in /opt/homebrew/bin would
+        // otherwise be invisible from a stripped-PATH exec channel.
+        let cmd = "PATH=\"$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH\" "
+            + "printf '%s' '\(b64)' | base64 -d | /bin/sh"
+        return try await runScript(cmd, timeout: timeout)
+    }
+
+    private func runScript(_ cmd: String, timeout: TimeInterval) async throws -> ProcessResult {
+        let client = try await connectionHolder.ssh()
+        let stream: AsyncThrowingStream<ExecCommandOutput, Error>
+        do {
+            stream = try await client.executeCommandStream(cmd)
+        } catch {
+            throw TransportError.other(message: "Failed to start exec stream: \(error.localizedDescription)")
+        }
+        // Drain in a child task and race against a sleep so a wedged remote
+        // sqlite3 (or a mid-stream Citadel transport failure) can't hang the
+        // caller indefinitely. Mirrors the busy-wait deadline that
+        // SSHScriptRunner enforces on Mac.
+        return try await withThrowingTaskGroup(of: ProcessResult?.self) { group in
+            group.addTask {
+                var stdout = Data()
+                var stderr = Data()
+                var exitCode: Int32 = 0
+                do {
+                    for try await chunk in stream {
+                        try Task.checkCancellation()
+                        switch chunk {
+                        case .stdout(var buf):
+                            if let s = buf.readString(length: buf.readableBytes) {
+                                stdout.append(Data(s.utf8))
+                            }
+                        case .stderr(var buf):
+                            if let s = buf.readString(length: buf.readableBytes) {
+                                stderr.append(Data(s.utf8))
+                            }
+                        }
+                    }
+                } catch let failed as SSHClient.CommandFailed {
+                    // Genuine remote non-zero exit — surface as
+                    // ProcessResult so the caller's existing exit-code
+                    // handling fires (mapped to BackendError.sqlite by
+                    // RemoteSQLiteBackend).
+                    exitCode = Int32(failed.exitCode)
+                } catch is CancellationError {
+                    throw TransportError.timeout(seconds: timeout, partialStdout: stdout)
+                } catch {
+                    // Transport-level failure (host unreachable, channel
+                    // dropped, ControlMaster died, NIO read error). Throw
+                    // as a typed TransportError so RemoteSQLiteBackend
+                    // routes it to BackendError.transport rather than
+                    // misclassifying as a sqlite crash via a fake -1 exit.
+                    throw TransportError.other(
+                        message: "SSH stream failed: \(error.localizedDescription)"
+                    )
+                }
+                return ProcessResult(exitCode: exitCode, stdout: stdout, stderr: stderr)
+            }
+            group.addTask {
+                try await Task.sleep(nanoseconds: UInt64(timeout * 1_000_000_000))
+                return nil
+            }
+            guard let first = try await group.next() else {
+                group.cancelAll()
+                throw TransportError.other(message: "SSH stream produced no result")
+            }
+            group.cancelAll()
+            if let result = first {
+                return result
+            }
+            // Timeout fired first — drain task gets cancelled by the
+            // group cancel above; surface as a typed timeout.
+            throw TransportError.timeout(seconds: timeout, partialStdout: Data())
+        }
     }
 
     // MARK: - ServerTransport: watching
@@ -171,14 +272,32 @@ public final class CitadelServerTransport: ServerTransport, @unchecked Sendable
         // Polling-based, identical in shape to `SSHTransport`'s remote-
         // watch fallback: stat each path, yield `.anyChanged` when any
         // mtime shifts. 3s tick keeps bandwidth low.
+        //
+        // ScarfMon — A1 instrumentation:
+        // - `ios.fileWatcher.tick` (interval) — full poll cycle latency,
+        //   includes the SSH stat round-trips. Pre-fix this is what an
+        //   "out of sync" user is feeling: anything > 1500 ms means
+        //   the channel is congested or the host is slow.
+        // - `ios.fileWatcher.delta` (event) — fires only when the
+        //   signature actually changed. Low ratio (delta count / tick
+        //   count) means we're polling more aggressively than the
+        //   change rate warrants — opens the door to dropping the 3s
+        //   cadence on LAN.
+        // - `ios.fileWatcher.paths` (event with bytes=count) — number
+        //   of paths watched per cycle, helps explain a slow tick when
+        //   the project list grows.
         AsyncStream { continuation in
             let task = Task.detached { [weak self] in
                 var lastSignature = ""
                 while !Task.isCancelled {
                     guard let self else { break }
-                    let current = await self.buildWatchSignature(for: paths)
+                    ScarfMon.event(.transport, "ios.fileWatcher.paths", count: 1, bytes: paths.count)
+                    let current = await ScarfMon.measureAsync(.transport, "ios.fileWatcher.tick") {
+                        await self.buildWatchSignature(for: paths)
+                    }
                     if !current.isEmpty, current != lastSignature {
                         if !lastSignature.isEmpty {
+                            ScarfMon.event(.transport, "ios.fileWatcher.delta", count: 1)
                             continuation.yield(.anyChanged)
                         }
                         lastSignature = current
@@ -388,33 +507,6 @@ public final class CitadelServerTransport: ServerTransport, @unchecked Sendable
         return ProcessResult(exitCode: exitCode, stdout: stdout, stderr: stderr)
     }
 
-    private func asyncSnapshotSQLite(remotePath: String) async throws -> URL {
-        // Same flow as SSHTransport: run `sqlite3 .backup` on the remote
-        // (WAL-safe), flip out of WAL mode on the snapshot, then SFTP
-        // the backup file down to the local cache.
-        try? FileManager.default.createDirectory(at: snapshotBaseDir, withIntermediateDirectories: true)
-        let localURL = snapshotBaseDir.appendingPathComponent("state.db")
-        let client = try await connectionHolder.ssh()
-        let remoteTmp = "/tmp/scarf-snapshot-\(UUID().uuidString).db"
-        // Double-quote paths; $HOME expansion happens inside double quotes.
-        let rewritten = Self.rewriteHomeRelative(remotePath)
-        let backupScript = #"sqlite3 "\#(rewritten)" ".backup '\#(remoteTmp)'" && sqlite3 '\#(remoteTmp)' "PRAGMA journal_mode=DELETE;" > /dev/null"#
-        _ = try await client.executeCommand(backupScript + " 2>&1")
-
-        // SFTP-download the remote tmp into our local snapshot cache.
-        let sftp = try await connectionHolder.sftp()
-        let data: Data = try await sftp.withFile(filePath: remoteTmp, flags: [.read]) { file in
-            let buf = try await file.readAll()
-            return Data(buffer: buf)
-        }
-        try data.write(to: localURL, options: .atomic)
-
-        // Best-effort cleanup of the remote tmp.
-        _ = try? await client.executeCommand("rm -f '\(remoteTmp)'")
-
-        return localURL
-    }
-
     // MARK: - Shell helpers
 
     /// Minimal shell-argument joiner. Handles spaces + quotes; sufficient

scarf/Packages/ScarfIOS/Sources/ScarfIOS/IOSDashboardViewModel.swift

@@ -70,10 +70,13 @@ public final class IOSDashboardViewModel {
             return
         }
 
-        stats = await dataService.fetchStats()
-        recentSessions = await dataService.fetchSessions(limit: 5)
-        allSessions = await dataService.fetchSessions(limit: 25)
-        sessionPreviews = await dataService.fetchSessionPreviews(limit: 25)
+        await ScarfMon.measureAsync(.sessionLoad, "ios.loadDashboard") {
+            stats = await dataService.fetchStats()
+            recentSessions = await dataService.fetchSessions(limit: 5)
+            allSessions = await dataService.fetchSessions(limit: 25)
+            sessionPreviews = await dataService.fetchSessionPreviews(limit: 25)
+        }
+        ScarfMon.event(.sessionLoad, "ios.allSessions.count", count: allSessions.count)
 
         // Attribution lookup (pass-2 UX): load the session→project
         // sidecar + project registry once so Dashboard rows can show
@@ -126,6 +129,7 @@ public final class IOSDashboardViewModel {
 
     /// Called from the pull-to-refresh gesture.
     public func refresh() async {
+        ScarfMon.event(.sessionLoad, "ios.dashboardRefresh.trigger", count: 1)
         await load()
     }
 }

scarf/Packages/ScarfIOS/Sources/ScarfIOS/KeychainSSHKeyStore.swift

@@ -17,9 +17,18 @@ import ScarfCore
 ///   go here; v1 item is migrated into v2 on first `listAll()` after
 ///   the upgrade, then removed.
 ///
-/// All items use `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
-/// so they're reachable after a single device unlock (background
-/// tasks, notification actions) but never sync to iCloud Keychain.
+/// **Accessibility / sync attributes.** Default behavior pins items
+/// to this device with `kSecAttrAccessibleAfterFirstUnlockThisDevice
+/// Only` + `kSecAttrSynchronizable=false`. Users can opt into iCloud
+/// Keychain sync via `SSHKeyICloudPreference` (issue #52); when
+/// enabled, writes use `kSecAttrAccessibleAfterFirstUnlock` (no
+/// `ThisDeviceOnly` suffix) + `kSecAttrSynchronizable=true` so the
+/// key is picked up by iCloud Keychain on every signed-in device.
+///
+/// All read / list / delete queries pass `kSecAttrSynchronizable =
+/// kSecAttrSynchronizableAny` so they match items regardless of
+/// sync state — load-bearing during the migration window when
+/// device-only and synced items can briefly coexist.
 public struct KeychainSSHKeyStore: SSHKeyStore {
     public static let defaultService = "com.scarf.ssh-key"
     public static let legacyV1Account = "primary"
@@ -56,10 +65,12 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
 
     public func delete() async throws {
         // Wipe every v2 entry + the legacy v1 entry. Single-query delete
-        // that matches any account under our service.
+        // that matches any account under our service. Pass `Any` so the
+        // wipe catches synced + device-only items uniformly (issue #52).
         let query: [String: Any] = [
-            kSecClass as String:        kSecClassGenericPassword,
-            kSecAttrService as String:  service,
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
         ]
         let status = SecItemDelete(query as CFDictionary)
         if status != errSecSuccess && status != errSecItemNotFound {
@@ -74,10 +85,13 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
     public func listAll() async throws -> [ServerID] {
         migrateLegacyIfNeeded()
         let query: [String: Any] = [
-            kSecClass as String:             kSecClassGenericPassword,
-            kSecAttrService as String:       service,
-            kSecReturnAttributes as String:  true,
-            kSecMatchLimit as String:        kSecMatchLimitAll,
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecReturnAttributes as String:        true,
+            kSecMatchLimit as String:              kSecMatchLimitAll,
+            // Match items regardless of sync state (issue #52). Without
+            // this the listing silently misses synced items.
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
         ]
         var items: CFTypeRef?
         let status = SecItemCopyMatching(query as CFDictionary, &items)
@@ -115,15 +129,60 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
         try deleteBundle(account: Self.multiAccountPrefix + id.uuidString)
     }
 
+    // MARK: - iCloud sync migration (issue #52)
+
+    /// Migrate every stored key bundle to the requested sync state and
+    /// persist the user's preference for future writes.
+    ///
+    /// Idempotent: if the user enables sync twice in a row the second
+    /// call simply re-saves with the same attributes. Safe to call
+    /// from a UI toggle handler. Errors thrown by individual key
+    /// re-writes propagate; partial migrations are tolerable because
+    /// the read paths use `kSecAttrSynchronizableAny` and pick up
+    /// either copy on the next read.
+    ///
+    /// Side effects:
+    /// - Each stored key is read with `Any`, deleted with `Any`, then
+    ///   re-saved with the target sync attributes via `writeBundle(_:account:syncToICloud:)`.
+    /// - The legacy v1 entry (if present) is migrated to the v2 layout
+    ///   with the new attributes in passing.
+    /// - `SSHKeyICloudPreference.isEnabled` is set BEFORE the rewrite
+    ///   loop so any concurrent `save(_:)` call from another path
+    ///   already uses the right attributes.
+    public func migrateAllItems(toICloudSync enabled: Bool) async throws {
+        SSHKeyICloudPreference.isEnabled = enabled
+
+        // Pull every v2 + v1 bundle into memory first. We can't iterate
+        // and rewrite simultaneously: deleting an item we're about to
+        // re-add would race with the listing query.
+        var bundles: [(account: String, bundle: SSHKeyBundle)] = []
+        for id in try await listAll() {
+            if let bundle = try await load(for: id) {
+                bundles.append((Self.multiAccountPrefix + id.uuidString, bundle))
+            }
+        }
+        if let legacy = try? readLegacy() {
+            bundles.append((Self.legacyV1Account, legacy))
+        }
+
+        for (account, bundle) in bundles {
+            try writeBundle(bundle, account: account, syncToICloud: enabled)
+        }
+    }
+
     // MARK: - Private — Keychain plumbing per-account
 
     private func readBundle(account: String) throws -> SSHKeyBundle? {
         let query: [String: Any] = [
-            kSecClass as String:            kSecClassGenericPassword,
-            kSecAttrService as String:      service,
-            kSecAttrAccount as String:      account,
-            kSecReturnData as String:       true,
-            kSecMatchLimit as String:       kSecMatchLimitOne,
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecAttrAccount as String:             account,
+            kSecReturnData as String:              true,
+            kSecMatchLimit as String:              kSecMatchLimitOne,
+            // Match items regardless of sync state (issue #52). Without
+            // this the query implicitly defaults to false and orphans
+            // any items that have been migrated to iCloud sync.
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
         ]
         var item: CFTypeRef?
         let status = SecItemCopyMatching(query as CFDictionary, &item)
@@ -149,6 +208,13 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
     }
 
     private func writeBundle(_ bundle: SSHKeyBundle, account: String) throws {
+        try writeBundle(bundle, account: account, syncToICloud: SSHKeyICloudPreference.isEnabled)
+    }
+
+    /// Write path with explicit sync control. Used by the public
+    /// migration helper to force a target sync state regardless of
+    /// the current preference.
+    private func writeBundle(_ bundle: SSHKeyBundle, account: String, syncToICloud: Bool) throws {
         let data: Data
         do {
             data = try JSONEncoder().encode(bundle)
@@ -157,17 +223,34 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
                 message: "Encode failed: \(error.localizedDescription)", osStatus: nil
             )
         }
-        let baseQuery: [String: Any] = [
+        // Delete with kSecAttrSynchronizableAny to clear out any prior
+        // copy regardless of its sync state — without this a flip from
+        // synced → device-only could leave the synced copy behind and
+        // create two competing items at the same (service, account).
+        let deleteQuery: [String: Any] = [
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecAttrAccount as String:             account,
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
+        ]
+        SecItemDelete(deleteQuery as CFDictionary)
+
+        var attributes: [String: Any] = [
             kSecClass as String:        kSecClassGenericPassword,
             kSecAttrService as String:  service,
             kSecAttrAccount as String:  account,
         ]
-        SecItemDelete(baseQuery as CFDictionary)
-
-        var attributes = baseQuery
         attributes[kSecValueData as String] = data
-        attributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
-        attributes[kSecAttrSynchronizable as String] = kCFBooleanFalse
+        if syncToICloud {
+            // iCloud Keychain requires the non-`ThisDeviceOnly` accessible
+            // class — items with the `ThisDeviceOnly` suffix are silently
+            // skipped by the sync engine.
+            attributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+            attributes[kSecAttrSynchronizable as String] = kCFBooleanTrue
+        } else {
+            attributes[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+            attributes[kSecAttrSynchronizable as String] = kCFBooleanFalse
+        }
 
         let addStatus = SecItemAdd(attributes as CFDictionary, nil)
         guard addStatus == errSecSuccess else {
@@ -179,9 +262,10 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
 
     private func deleteBundle(account: String) throws {
         let query: [String: Any] = [
-            kSecClass as String:        kSecClassGenericPassword,
-            kSecAttrService as String:  service,
-            kSecAttrAccount as String:  account,
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecAttrAccount as String:             account,
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
         ]
         let status = SecItemDelete(query as CFDictionary)
         if status != errSecSuccess && status != errSecItemNotFound {
@@ -217,10 +301,13 @@ public struct KeychainSSHKeyStore: SSHKeyStore {
     /// triggering a recursive migration.
     private func listAllInternal(skipMigration: Bool) throws -> [ServerID] {
         let query: [String: Any] = [
-            kSecClass as String:             kSecClassGenericPassword,
-            kSecAttrService as String:       service,
-            kSecReturnAttributes as String:  true,
-            kSecMatchLimit as String:        kSecMatchLimitAll,
+            kSecClass as String:                   kSecClassGenericPassword,
+            kSecAttrService as String:             service,
+            kSecReturnAttributes as String:        true,
+            kSecMatchLimit as String:              kSecMatchLimitAll,
+            // Match items regardless of sync state (issue #52). Without
+            // this the listing silently misses synced items.
+            kSecAttrSynchronizable as String:      kSecAttrSynchronizableAny,
         ]
         var items: CFTypeRef?
         let status = SecItemCopyMatching(query as CFDictionary, &items)

scarf/Packages/ScarfIOS/Sources/ScarfIOS/NetworkReachabilityService.swift

@@ -0,0 +1,88 @@
+import Foundation
+import Network
+import Observation
+#if canImport(os)
+import os
+#endif
+
+/// Process-wide reachability monitor wrapping `NWPathMonitor`. Used by
+/// `ChatController` to decide when to attempt a reconnect (on
+/// `.satisfied`) vs. mark the chat offline (on `.unsatisfied`).
+///
+/// Singleton because `NWPathMonitor` is per-process by design — there's
+/// no benefit to instantiating multiple monitors and the cost (a small
+/// background queue per instance) accumulates if every controller
+/// spawns its own.
+///
+/// ## Usage
+///
+/// Don't read the published state from a SwiftUI view body — the
+/// runtime samples through `NWPathMonitor`'s queue, but a `body`
+/// re-evaluation that touches `currentPath` directly would block. Read
+/// `isSatisfied` / observe `transitionTick` instead. Tests and
+/// non-iOS callers can use the no-op default behavior (`isSatisfied`
+/// reports `true`).
+@Observable
+@MainActor
+public final class NetworkReachabilityService {
+    public static let shared = NetworkReachabilityService()
+
+    /// `true` when the OS reports a usable network path (any
+    /// interface). Inverted via `!isSatisfied` for "we're offline."
+    public private(set) var isSatisfied: Bool = true
+
+    /// Mirrors `NWPath.isExpensive`. Useful as a hint to UI for not
+    /// auto-fetching big payloads on cellular. Not consumed yet —
+    /// reserved so callers don't have to add another property later.
+    public private(set) var isExpensive: Bool = false
+
+    /// Monotonic counter that bumps every time `isSatisfied` changes.
+    /// Views observe `transitionTick` rather than `isSatisfied` to
+    /// kick a `.onChange` even if the value is the same as before
+    /// (rare but possible during rapid network flapping).
+    public private(set) var transitionTick: Int = 0
+
+    private let monitor = NWPathMonitor()
+    private let queue = DispatchQueue(label: "com.scarf.ios.reachability")
+
+    #if canImport(os)
+    private static let logger = Logger(subsystem: "com.scarf.ios", category: "NetworkReachability")
+    #endif
+
+    private init() {
+        // Seed from the current path synchronously so first reads on
+        // launch don't show "satisfied" while the OS reports otherwise.
+        // `currentPath` is safe here at init (the monitor hasn't been
+        // started yet, no queue handler is firing).
+        let initial = monitor.currentPath
+        self.isSatisfied = (initial.status == .satisfied)
+        self.isExpensive = initial.isExpensive
+
+        monitor.pathUpdateHandler = { [weak self] path in
+            // Bounce back through MainActor — the `Observable`
+            // protocol's published-property invariants require main-
+            // thread mutation. The pathUpdateHandler is invoked on
+            // `queue`, which is a private background queue.
+            Task { @MainActor in
+                guard let self else { return }
+                let satisfied = (path.status == .satisfied)
+                if self.isSatisfied != satisfied {
+                    self.isSatisfied = satisfied
+                    self.transitionTick &+= 1
+                    #if canImport(os)
+                    Self.logger.info(
+                        "Reachability transition: \(satisfied ? "satisfied" : "unsatisfied", privacy: .public)"
+                    )
+                    #endif
+                }
+                self.isExpensive = path.isExpensive
+            }
+        }
+        monitor.start(queue: queue)
+    }
+
+    deinit {
+        // Singleton is process-lifetime; this only runs on shutdown.
+        monitor.cancel()
+    }
+}

scarf/Packages/ScarfIOS/Sources/ScarfIOS/SSHKeyICloudPreference.swift

@@ -0,0 +1,39 @@
+// Apple-only: Security.framework + UserDefaults are iOS/Mac only.
+// On Linux this file is skipped; tests don't exercise it.
+#if canImport(Security)
+
+import Foundation
+
+/// Device-local preference: should the SSH key bundle stored in the
+/// iOS Keychain sync to iCloud Keychain (issue #52)?
+///
+/// **Default `false`.** Existing installs see no change on update; the
+/// key remains pinned to the device with `kSecAttrAccessibleAfter
+/// FirstUnlockThisDeviceOnly` + `kSecAttrSynchronizable=false`. Users
+/// who opt in via Settings → Security trigger a one-shot migration
+/// that re-saves all stored keys with `kSecAttrAccessibleAfterFirst
+/// Unlock` + `kSecAttrSynchronizable=true` so iCloud Keychain picks
+/// them up.
+///
+/// **Trade-off the UI must surface clearly.**
+/// - On: convenient multi-device — iPhone + iPad + Mac all see the
+///   same key. End-to-end encrypted by iCloud Keychain (Apple-managed
+///   keys without ADP, user-managed keys with ADP). Requires iCloud
+///   Keychain enabled on every device.
+/// - Off (default): key never leaves this device. Each device must
+///   onboard separately (generate its own key, append its pubkey to
+///   `authorized_keys`).
+public enum SSHKeyICloudPreference {
+
+    /// UserDefaults key. Stable string so a v2 future fix can read
+    /// existing values without migration.
+    public static let key = "scarf.icloud.syncSSHKey"
+
+    /// Read the current preference. Defaults to `false`.
+    public static var isEnabled: Bool {
+        get { UserDefaults.standard.bool(forKey: key) }
+        set { UserDefaults.standard.set(newValue, forKey: key) }
+    }
+}
+
+#endif // canImport(Security)

scarf/Scarf iOS/App/ScarfGoCoordinator.swift

@@ -31,6 +31,28 @@ final class ScarfGoCoordinator {
     /// `AppCoordinator.pendingProjectChat`.
     var pendingProjectChat: String?
 
+    /// Most-recent scene-phase value observed at the WindowGroup
+    /// level. Tab-specific view models (e.g. `ChatController`)
+    /// observe `scenePhaseTick` to react to transitions even when
+    /// they're on a non-foreground tab — `.onChange(of: ScenePhase)`
+    /// alone wouldn't fire for views that aren't on screen.
+    private(set) var scenePhase: ScenePhase = .active
+    private(set) var scenePhaseTick: Int = 0
+    /// Wallclock when we last observed `.background`. Used by tab
+    /// view-models to decide whether a quick `.active` transition is
+    /// worth a full re-verify (long suspensions warrant it; brief
+    /// notification-center peeks don't). `nil` until the first
+    /// background transition.
+    private(set) var lastBackgroundedAt: Date?
+
+    func setScenePhase(_ phase: ScenePhase) {
+        if phase == .background, scenePhase != .background {
+            lastBackgroundedAt = Date()
+        }
+        scenePhase = phase
+        scenePhaseTick &+= 1
+    }
+
     enum Tab: Hashable {
         case dashboard, projects, chat, skills, system
     }

scarf/Scarf iOS/App/ScarfGoTabRoot.swift

@@ -30,12 +30,49 @@ struct ScarfGoTabRoot: View {
     let onSoftDisconnect: @MainActor () async -> Void
     let onForget: @MainActor () async -> Void
 
+    /// Stable per-tab context UUID — used for the System tab's Curator
+    /// row so its CuratorViewModel reuses the cached SSH connection
+    /// keyed by this id rather than building a fresh one. Same pattern
+    /// as `sharedContextID` on ChatView.
+    static let systemTabContextID: ServerID = ServerID(
+        uuidString: "00000000-0000-0000-0000-0000000000A2"
+    )!
+
     /// One coordinator per server-connected session. Cross-tab
     /// signalling (Dashboard row → Chat tab resume, Project Detail
     /// → in-project chat handoff, notification deep-link → Chat) flows
     /// through here.
     @State private var coordinator = ScarfGoCoordinator()
 
+    /// Hermes version + capability flags for this remote. Drives the
+    /// iOS version banner (v0.11 hosts get a yellow "update for new
+    /// features" banner) and capability-gated affordances like ACP
+    /// image attachments. Constructed once per server connection so
+    /// the detection runs over the active SSH transport.
+    @State private var capabilities: HermesCapabilitiesStore
+
+    init(
+        serverID: ServerID,
+        config: IOSServerConfig,
+        key: SSHKeyBundle,
+        onSoftDisconnect: @escaping @MainActor () async -> Void,
+        onForget: @escaping @MainActor () async -> Void
+    ) {
+        self.serverID = serverID
+        self.config = config
+        self.key = key
+        self.onSoftDisconnect = onSoftDisconnect
+        self.onForget = onForget
+        let ctx = config.toServerContext(id: serverID)
+        _capabilities = State(initialValue: HermesCapabilitiesStore(context: ctx))
+    }
+
+    /// SwiftUI's `.onChange(of: ScenePhase)` modifier on a non-active
+    /// tab doesn't fire while the tab is unmounted — the coordinator
+    /// is the single source of truth for scene-phase transitions
+    /// across all tabs.
+    @Environment(\.scenePhase) private var scenePhase
+
     var body: some View {
         // The transport factory is keyed by ServerID, so the correct
         // Keychain slot + config is picked automatically. Reuses the
@@ -112,6 +149,8 @@ struct ScarfGoTabRoot: View {
         .tabViewStyle(.sidebarAdaptable)
         .environment(\.serverContext, ctx)
         .environment(\.scarfGoCoordinator, coordinator)
+        .environment(capabilities)
+        .hermesCapabilities(capabilities)
         .onAppear {
             // Give the notification router a handle to this session's
             // coordinator so notification-taps can route across tabs.
@@ -119,6 +158,12 @@ struct ScarfGoTabRoot: View {
             // just observes.
             NotificationRouter.shared.coordinator = coordinator
         }
+        // Funnel scene-phase transitions through the coordinator so
+        // tab view-models (notably ChatController) can react even
+        // when their tab isn't currently on-screen.
+        .onChange(of: scenePhase) { _, newPhase in
+            coordinator.setScenePhase(newPhase)
+        }
     }
 }
 
@@ -135,9 +180,18 @@ private struct SystemTab: View {
     let onSoftDisconnect: @MainActor () async -> Void
     let onForget: @MainActor () async -> Void
 
+    @Environment(\.hermesCapabilities) private var capabilitiesStore
+
     @State private var showForgetConfirmation = false
     @State private var isForgetting = false
     @State private var isDisconnecting = false
+    /// Mirror of `SSHKeyICloudPreference.isEnabled` — drives the iCloud
+    /// Keychain sync toggle (issue #52). Initial value is read on view
+    /// init so the toggle reflects today's preference before the user
+    /// taps anything; flipping triggers `migrateAllItems(toICloudSync:)`.
+    @State private var iCloudSyncEnabled: Bool = SSHKeyICloudPreference.isEnabled
+    @State private var iCloudMigrationInFlight = false
+    @State private var iCloudMigrationError: String?
 
     var body: some View {
         List {
@@ -162,6 +216,15 @@ private struct SystemTab: View {
                 }
                 .scarfGoCompactListRow()
                 .listRowBackground(ScarfColor.backgroundSecondary)
+                if capabilitiesStore?.capabilities.hasCurator ?? false {
+                    NavigationLink {
+                        CuratorView(context: config.toServerContext(id: ScarfGoTabRoot.systemTabContextID))
+                    } label: {
+                        Label("Curator", systemImage: "sparkles")
+                    }
+                    .scarfGoCompactListRow()
+                    .listRowBackground(ScarfColor.backgroundSecondary)
+                }
                 NavigationLink {
                     CronListView(config: config)
                 } label: {
@@ -178,6 +241,97 @@ private struct SystemTab: View {
                 .listRowBackground(ScarfColor.backgroundSecondary)
             }
 
+            // v2.6: read-only mobile views over CLI-driven Hermes
+            // surfaces. Mac owns the create/edit paths; phones get a
+            // monitoring window into what the remote agent is honoring.
+            // None of these are capability-gated — the underlying
+            // `hermes plugins/profile/webhook list` verbs exist on
+            // both v0.11 and v0.12, so the read views work on either.
+            Section("Inspect") {
+                NavigationLink {
+                    WebhooksView(config: config)
+                } label: {
+                    Label("Webhooks", systemImage: "arrow.up.right.square")
+                }
+                .scarfGoCompactListRow()
+                .listRowBackground(ScarfColor.backgroundSecondary)
+                NavigationLink {
+                    PluginsView(config: config)
+                } label: {
+                    Label("Plugins", systemImage: "app.badge.checkmark")
+                }
+                .scarfGoCompactListRow()
+                .listRowBackground(ScarfColor.backgroundSecondary)
+                NavigationLink {
+                    ProfilesView(config: config)
+                } label: {
+                    Label("Profiles", systemImage: "person.2.crop.square.stack")
+                }
+                .scarfGoCompactListRow()
+                .listRowBackground(ScarfColor.backgroundSecondary)
+            }
+
+            Section {
+                Toggle(isOn: $iCloudSyncEnabled) {
+                    HStack(spacing: 10) {
+                        Image(systemName: "key.icloud.fill")
+                            .foregroundStyle(.tint)
+                        VStack(alignment: .leading, spacing: 2) {
+                            Text("Sync SSH key with iCloud Keychain")
+                            Text(iCloudSyncEnabled
+                                 ? "Synced — your other Apple devices with iCloud Keychain will see this key."
+                                 : "This device only — generate a separate key on each device.")
+                                .font(.caption)
+                                .foregroundStyle(ScarfColor.foregroundMuted)
+                        }
+                    }
+                }
+                .tint(ScarfColor.accent)
+                .disabled(iCloudMigrationInFlight)
+                .onChange(of: iCloudSyncEnabled) { _, newValue in
+                    Task {
+                        iCloudMigrationInFlight = true
+                        iCloudMigrationError = nil
+                        defer { iCloudMigrationInFlight = false }
+                        do {
+                            try await KeychainSSHKeyStore().migrateAllItems(toICloudSync: newValue)
+                        } catch {
+                            // Revert the toggle on failure so the UI
+                            // reflects what's actually in the Keychain;
+                            // surface the error inline so the user can
+                            // retry / report. Keychain failures here are
+                            // rare (typically `errSecDuplicateItem` if a
+                            // prior migration was interrupted — the
+                            // delete-with-Any in writeBundle prevents
+                            // that, but we still belt-and-brace).
+                            iCloudMigrationError = error.localizedDescription
+                            iCloudSyncEnabled = !newValue
+                            SSHKeyICloudPreference.isEnabled = !newValue
+                        }
+                    }
+                }
+                if iCloudMigrationInFlight {
+                    HStack(spacing: 8) {
+                        ProgressView()
+                            .controlSize(.small)
+                        Text("Updating Keychain…")
+                            .font(.caption)
+                            .foregroundStyle(ScarfColor.foregroundMuted)
+                    }
+                }
+                if let err = iCloudMigrationError {
+                    Label(err, systemImage: "exclamationmark.triangle.fill")
+                        .font(.caption)
+                        .foregroundStyle(ScarfColor.warning)
+                }
+            } header: {
+                Text("Security")
+            } footer: {
+                Text("End-to-end encrypted via iCloud Keychain. With Advanced Data Protection on, the encryption keys never leave your devices. Toggle off to keep the key device-only — each new device must onboard separately.")
+                    .font(.caption)
+            }
+            .listRowBackground(ScarfColor.backgroundSecondary)
+
             Section {
                 Button {
                     Task {

scarf/Scarf iOS/App/ScarfIOSApp.swift

@@ -14,6 +14,14 @@ struct ScarfIOSApp: App {
     )
 
     init() {
+        // ScarfMon — open-source perf instrumentation. Reads the
+        // user-toggled mode from UserDefaults and installs the
+        // matching backend set. Default is `.signpostOnly` so
+        // Instruments-attached profiling works without users having
+        // to opt in. The Diagnostics → Performance row in Settings
+        // flips this between off / signpost-only / full.
+        ScarfMonBoot.configure(mode: ScarfMonBoot.currentMode())
+
         // Wire ScarfCore's transport factory to produce Citadel-backed
         // `ServerTransport`s for every `.ssh` context. Without this,
         // `ServerContext.makeTransport()` would fall back to the
@@ -63,6 +71,13 @@ struct ScarfIOSApp: App {
                     // Hermes gains a push sender.
                     await MainActor.run { NotificationRouter.shared.setUpOnLaunch() }
                 }
+                .task {
+                    // Drop chat drafts older than 7 days so the
+                    // UserDefaults plist doesn't grow unbounded across
+                    // years of use. Cheap; UserDefaults is already in
+                    // memory by the time we read keys.
+                    ChatController.pruneStaleDrafts()
+                }
                 // Clamp Dynamic Type at the scene root. ScarfGo is a
                 // developer tool that needs more density than Apple's
                 // .xxxLarge default, but we still scale from .xSmall
@@ -185,8 +200,20 @@ final class RootModel {
 
     /// Cancel an in-progress onboarding and return to the list.
     /// Called by the sheet's Cancel affordance.
+    ///
+    /// Issue #55: prior versions had a defensive `servers.isEmpty`
+    /// fallback that re-presented onboarding when there was nothing
+    /// to fall back to. That made Cancel look broken on first-run.
+    /// `OnboardingRootView` now hides the Cancel button when
+    /// `canCancel == false`, so this path is only ever reached when
+    /// at least one server already exists. In debug we assert that
+    /// invariant; in release we still route to `.serverList` (which
+    /// renders an empty-state with the "+ Add server" button) rather
+    /// than re-presenting onboarding, so the worst case is "user
+    /// sees the empty server list" rather than "Cancel does nothing."
     func cancelOnboarding() {
-        state = servers.isEmpty ? .onboarding(forNewServer: ServerID()) : .serverList
+        assert(!servers.isEmpty, "cancelOnboarding called with no servers — Cancel button should be hidden via OnboardingRootView.canCancel")
+        state = .serverList
     }
 
     /// Called from OnboardingView when the flow finishes. Reload the
@@ -320,7 +347,14 @@ struct RootView: View {
         case .serverList:
             ServerListView(model: model)
         case .onboarding(let forNewServer):
-            OnboardingRootView(targetServerID: forNewServer) {
+            // canCancel is gated on whether there's a server list to
+            // return to (issue #55). On first-run the user MUST add
+            // their first server to use the app — the toolbar omits
+            // the Cancel button in that case.
+            OnboardingRootView(
+                targetServerID: forNewServer,
+                canCancel: !model.servers.isEmpty
+            ) {
                 await model.onboardingFinished(serverID: forNewServer)
             } onCancel: {
                 model.cancelOnboarding()

scarf/Scarf iOS/Components/HermesVersionBanner.swift

@@ -0,0 +1,77 @@
+import SwiftUI
+import ScarfCore
+import ScarfDesign
+
+/// Yellow banner that nudges users to upgrade Hermes when the remote
+/// is running pre-v0.12. Shown on the Dashboard tab; auto-dismissed
+/// for the rest of the session when the user taps the X. Persistent
+/// re-show on each app open keeps the prompt visible without nagging
+/// inside a single session.
+///
+/// Hidden entirely on v0.12+ (the new features are reachable) and
+/// while capability detection is still in flight.
+struct HermesVersionBanner: View {
+    @Environment(\.hermesCapabilities) private var capabilitiesStore
+    @State private var dismissedThisSession = false
+
+    /// Capability gate — only render when:
+    /// - the store finished its initial detection AND
+    /// - the host returned an actual version string AND
+    /// - that version is below v0.12 AND
+    /// - the user hasn't dismissed this banner during this session.
+    private var shouldShow: Bool {
+        guard let store = capabilitiesStore else { return false }
+        let caps = store.capabilities
+        guard caps.detected else { return false }    // skip while loading / on detection failure
+        guard !caps.hasCurator else { return false } // already on v0.12+
+        return !dismissedThisSession
+    }
+
+    var body: some View {
+        if shouldShow {
+            HStack(alignment: .top, spacing: 10) {
+                Image(systemName: "exclamationmark.triangle.fill")
+                    .foregroundStyle(ScarfColor.warning)
+                VStack(alignment: .leading, spacing: 2) {
+                    Text("Hermes update available")
+                        .font(.callout.weight(.semibold))
+                    Text("This server runs \(versionLabel). Update to v0.12 to unlock the autonomous curator, multimodal image input, GMI Cloud / Azure / LM Studio / MiniMax / Tencent providers, and more.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+                Spacer(minLength: 8)
+                Button {
+                    dismissedThisSession = true
+                } label: {
+                    Image(systemName: "xmark")
+                        .font(.system(size: 12, weight: .semibold))
+                        .foregroundStyle(.secondary)
+                }
+                .buttonStyle(.plain)
+                .accessibilityLabel("Dismiss this version notice for the rest of the session")
+            }
+            .padding(.horizontal, 12)
+            .padding(.vertical, 10)
+            .background(ScarfColor.warning.opacity(0.12))
+            .overlay(
+                Rectangle()
+                    .fill(ScarfColor.warning.opacity(0.4))
+                    .frame(height: 1),
+                alignment: .bottom
+            )
+            .transition(.opacity)
+        }
+    }
+
+    /// Pretty-print the detected version. Falls back to the raw line
+    /// if parsing didn't extract semver — keeps the banner honest
+    /// when Hermes ships an unexpected version string.
+    private var versionLabel: String {
+        let caps = capabilitiesStore?.capabilities
+        if let semver = caps?.semver {
+            return "Hermes v\(semver.description)"
+        }
+        return caps?.versionLine ?? "an older Hermes"
+    }
+}