feat: Harness onboarding wizard + omp/dsh session sources

[kesslerio]

TL;DR

This PR adds the full harness/session stack to sparkDash: five coding-agent harness sources (OpenClaw, Hermes, OpenCode, oh-my-pi, DeepSeek Harness), a 3-step onboarding wizard, live session occupancy on LLM cards, and occupancy helper docs. Reviewers can connect their harnesses in under a minute and see which sessions are active on each Spark.

What Problem This Solves

sparkDash showed GPU and model metrics but had no visibility into which coding-agent sessions were running on each LLM port. Operators had to SSH into boxes or check each harness separately to know what was active. There was also no guided setup — connecting a harness required editing config files by hand.

Why This Change Was Made

I run multiple coding-agent harnesses across my fleet and wanted dashboard-level visibility into active sessions without leaving sparkDash. The wizard makes onboarding self-service for anyone I share the dashboard with. The occupancy helpers are part of the same feature surface, so their docs are folded in here rather than split into a separate PR.

User Impact

• New "Manage harnesses" button in the header opens a wizard (pick → configure → review)
• Each LLM card shows a conversation list with pulsating dots for generating/recent sessions
• Five harness types supported: OpenClaw (native API), Hermes (native API), OpenCode (helper), oh-my-pi (helper), DeepSeek Harness (helper, remote-only)
• Local and remote connection modes per harness, with agent-pasteable helper snippets
• UI renamed from "occupancy source" to "harness" throughout

Risk and Rollout

Low risk — this is additive (new session source collectors and a wizard modal). No existing behavior changes except the UI label rename. No migration needed; session sources default to empty. The occupancyHosts fix corrects a projector bug that was replacing existing hosts instead of merging. Rollout is opt-in: users connect harnesses via the wizard when ready.

Screenshots

Step 1 — Pick harnesses

Step 2 — Configure (local mode)

Step 2 — Configure (remote mode)

Step 3 — Review and save

Cleanshot

Demo

Feature demo video — wizard walkthrough

Evidence

• npm run typecheck — passes clean
• npm run build — passes (61 modules, 441 KB JS bundle)
• npm test — 370 server tests + 14 frontend tests pass (384 total, 0 fail)
• No bench/probe code leaked: git diff upstream/main..feat/harness-session-wizard -- server/collectors/LlmProbe.js is empty
• git diff upstream/main..feat/harness-session-wizard -- src/components/SparkPage/BenchmarkDialog.tsx is empty
• Gitleaks scan clean on commit
• Wizard verified via agent-browser: opens from header button, all 5 harnesses visible, local/remote modes render correctly, review step shows selected harnesses

[vincenzopalazzo]

I like this feature, and I like the design. Dashboard-level occupancy, tokens kept out of the public JSON, URLs through the existing host allowlist, and a wizard instead of hand-edited config is the right shape. The conversation list on the LLM card is the thing the dashboard is missing.

I am not merging this branch as-is. It is one commit from 19 Aug, CONFLICTING against current main (about 94 commits behind), and it rewrites server/index.js, SparkMonitor, and secretsStore on top of auth and security-bounds work that landed after the base. Please rebase onto current main before we take it, rather than merging the GitHub PR.

One question before that rebase, because it may shrink the patch a lot.

Can ACP get you closer to the providers, instead of a collector and a helper script per harness?

Agent Client Protocol session/list is the occupancy surface: after initialize, if the agent advertises sessionCapabilities.list, the client gets sessionId, cwd, title, updatedAt, and can take session_info_update instead of polling private files. Hermes Agent, OpenCode, and OpenClaw are already on the ACP agent list. Pi is there via pi-acp (oh-my-pi is not, as far as I can see). DeepSeek Harness is not.

ACP is a stdio JSON-RPC session you spawn, not an HTTP API the dashboard should poll. Do not start every harness binary on the LLM poll cadence — that fights the real sessions for the GPU. The useful cut is one small helper on the box that speaks ACP once and exposes the session list. That would replace the OpenCode / oh-my-pi / DeepSeek helper scripts with one protocol, and drop the local reads of ~/.openclaw, ~/.hermes, and the OpenCode SQLite file, for every harness that advertises session/list. Keep a private adapter only where the agent does not.

If you can show that Hermes, OpenCode, and OpenClaw answer session/list from a helper without spawning a second live agent, I would rather review that than five collectors. Happy to take the wizard and the LLM-card list either way — those stay.

— Vincent