merge: T041 scout host spike — DECISION: Hermes plugin

scout/SPIKE.md

@@ -0,0 +1,218 @@
+# Scout Host Spike (T041)
+
+Time-boxed, read-mostly investigation of this host (m2, the machine this repo lives on)
+to pick where the Solution Scout (Story 5 / FR-011) should live. Evaluates the three
+options named in research.md §R6: (A) standalone supervised watcher, (B) Hermes plugin,
+(C) herdr plugin/hook — against (a) access to structured summaries without raw
+keystrokes, (b) opt-in enforcement point, (c) on-box summarization cost, (d) notification
+surface, (e) update/rollout story across the `primus` and `agent-latest` image classes.
+
+Note: `specs/S4-solution-scout.md` §5 already drafted a recommendation (Option A) before
+this spike ran. This report re-derives the decision from concrete file/path evidence
+gathered on the live host, and **overrides that draft** — see §5 for why.
+
+## 0. Fleet context confirmed on this host
+
+- Two desktop image classes exist, and they are **not** interchangeable for rollout:
+  - `primus` — built from `/home/m2/m2o/desktop/Dockerfile`, this repo's own supervisord
+    config, canary machine `chris-m2o`. System/image changes here mean re-baking primus
+    (`/home/m2/m2o/desktop/README.md:74`, `:95-104`).
+  - `agent-latest` — `ghcr.io/machine-machine/m2-desktop:agent-latest`, described
+    repeatedly in `/home/m2/m2o/.planning/federated-learning/*` as "legacy/Coolify",
+    a **different image lineage** this repo does not build
+    (`m2o/.planning/federated-learning/proposals/A4-propagation-rollout.md:5,17`).
+  - The federated-learning propagation ADR is explicit: *"image/system changes are baked
+    into `m2-desktop:primus`... This avoids pretending that `primus` and legacy/Coolify
+    `agent-latest` machines can be updated the same way"* (A4:5). Constitution VI says the
+    same: "runtime-sync is the only universal install path across mixed desktop images."
+  - Concretely on this host, every desktop-level supervised program (`hermes-gateway`,
+    `herdr-integrations`, `ttyd`) is wired in by `Dockerfile` `COPY ... >> supervisord.conf`
+    steps at **build time** (`m2o/desktop/Dockerfile:73-126`) into
+    `/etc/supervisor/conf.d/supervisord.conf`. That file is not part of any volume that
+    runtime-sync touches — it only exists post-bake, inside the image.
+
+This single fact is the crux of the spike: **adding a new supervised process is an
+image-bake operation**, reachable on `primus` (we own the Dockerfile) but not on
+`agent-latest` (we don't own that image's build) without a separate, per-machine,
+non-idempotent `docker exec` patch to a running container's supervisord config — exactly
+the kind of fleet-wide-blast / non-reversible operation constitution VI rules out.
+
+## 1. Option A — Standalone supervised watcher
+
+Evidence:
+
+- Pattern to copy: `hermes-gateway.supervisor.conf` (`m2o/desktop/hermes/hermes-gateway.supervisor.conf`)
+  — `[program:hermes-gateway]`, `autorestart=true`, `priority=45`, `sleep 12` boot stagger,
+  appended into the active `supervisord.conf` via `Dockerfile:79-82`.
+- Adding `m2-solution-scout` the same way means a third `COPY ... >> supervisord.conf`
+  block in `m2o/desktop/Dockerfile`, i.e. a `primus` image cut (`VERSION=vN ./build.sh`,
+  README.md:99).
+- **Rollout gap (the finding S4 missed):** there is no equivalent Dockerfile for
+  `agent-latest` in this repo — it's pulled pre-built from `ghcr.io`. Reaching it means
+  either waiting for whoever owns that image to add the program, or `docker exec`-patching
+  each running `agent-latest` container's `/etc/supervisor/conf.d/supervisord.conf` and
+  `supervisorctl update` by hand per machine. That is not idempotent/reversible/runtime-sync
+  in the sense constitution VI and the "Inherited Hard Constraints" section require.
+
+Scoring: strongest privacy isolation (a dedicated process only reads what it's told to),
+but the update/rollout story (e) is the weakest of the three on THIS fleet, not the
+strongest as S4 assumed.
+
+## 2. Option B — Hermes plugin
+
+Evidence:
+
+- Hermes already runs a real plugin on this host:
+  `/home/m2/.hermes/plugins/herdr-agent-state/{__init__.py,plugin.yaml}`, installed by
+  `herdr integration install hermes` (confirmed via `herdr integration` subcommand list;
+  this exact plugin ships with `# HERDR_INTEGRATION_ID=hermes` header). It registers
+  hooks via `ctx.register_hook(...)` for `on_session_start`, `pre_llm_call`,
+  `pre_tool_call`, `post_tool_call`, `pre_approval_request`, `post_approval_response`,
+  `post_llm_call`, `on_session_end`, `on_session_finalize` — reporting only lifecycle
+  state (`working|blocked|idle`) over the herdr Unix socket, never message content.
+- Plugin hook docs (`/home/m2/.hermes/hermes-agent/website/docs/user-guide/features/hooks.md`)
+  show the two hooks a Scout would actually want:
+  - `post_llm_call(session_id, user_message, assistant_response, conversation_history,
+    model, platform, **kwargs)` — fires once per turn, **already gives structured,
+    per-turn intent content** (not raw keystrokes — it's the resolved message/response
+    text, the same thing Hermes itself just processed).
+  - `pre_llm_call(...) -> {"context": str}` — could be reused later to inject a
+    "here's a matching Solution" hint directly into the next turn instead of only toasting.
+- Deployment is a pure file drop: `~/.hermes/plugins/m2-solution-scout/{__init__.py,plugin.yaml}`.
+  No supervisord, no image bake — this is exactly the "runtime fleet-sync agent into
+  persisted home volumes" path the federated-learning ADR (A4) calls out as the one
+  path that reaches BOTH image classes, **because Hermes itself is already supervised
+  on both** (hermes-gateway is the canonical per-desktop supervision pattern referenced
+  by this very task, and its plugin directory lives under `$HERMES_HOME` regardless of
+  which image booted it).
+- Opt-in enforcement point: hooks are in-process Python: a `pull-policy.toml` read at
+  plugin `register()` time can make every hook a no-op when `scout.enabled=false`,
+  exactly like the CLAUDE.md-documented pattern for other opt-in config.
+- On-box summarization cost: cheapest of the three — the plugin receives already-clean
+  turn text; no separate log-tailing/parsing/redaction pass over external files is needed
+  before summarizing, only redaction of the text it's handed directly (same
+  `redact_secrets`/`redact_client_identifiers` obligations from S4's `pull-policy.toml` draft).
+- Notification surface: none built in — the plugin still needs to shell out to
+  `notify-send` (XFCE) or the herdr toast socket (see Option C) for the actual popup.
+  This is a small, one-file bridge either way.
+
+Cons confirmed from the doc: plugin hooks run **in-process** with Hermes (same trust
+boundary — a crashing hook is caught and logged per the docs, "never crashing the agent",
+but a slow hook still adds latency to every turn). And it only sees Hermes sessions —
+OpenClaw-only or bare-herdr (Claude Code/Codex panes with no Hermes chat active) sessions
+are invisible to it.
+
+## 3. Option C — herdr plugin/hook
+
+Evidence:
+
+- `herdr agent list` (run once, per task instructions) returns a live, structured JSON
+  lifecycle feed today: `{agent, agent_status: working|idle|done, cwd, pane_id,
+  workspace_id, ...}` for every pane across every workspace on the box — genuinely
+  "structured run/lifecycle summary," zero raw keystrokes, already running, no code to write.
+- `~/.herdr/runs/*.md` (e.g. `2026-07-02-m2-market-first-wedge-gate.md`) are rich,
+  human/agent-authored narrative summaries — but they are a **manual convention** written
+  by an orchestrating session at the end of a herd run (see this repo's own recent runs),
+  not an automatic per-session artifact. Most single-agent sessions never produce one.
+  This makes Option C's "structured summary" source sparse and bursty rather than
+  continuous — a poor fit for "an operator is mid-session, starts building something... an
+  agent proposes the link right then" (CONCEPT.md §5).
+- `~/.claude/hooks/herdr-agent-state.sh` (installed by `herdr integration install claude`)
+  shows the wire protocol: a Claude Code hook posts `pane.report_agent_session` over
+  `$HERDR_SOCKET_PATH` — again lifecycle-only, no content.
+- `~/.config/herdr/config.toml` already has `[ui.toast] delivery = "herdr"` — confirms
+  herdr owns a native toast/notification surface today (this is also directly reusable
+  by Options A/B as the notification backend, independent of which host wins).
+- `herdr integration` subcommands (`install/uninstall {pi,omp,claude,codex,copilot,
+  opencode,hermes,qodercli}`, `status`) show integrations are themselves file-drops under
+  `~/.claude/hooks/`, `~/.hermes/plugins/`, etc. — same runtime-sync-friendly deploy story
+  as Option B.
+
+Scoring: best-in-class for (b) opt-in enforcement (a single socket message gate) and (d)
+notification, but weakest for (a) — the only *continuous* signal herdr exposes natively is
+coarse lifecycle state (working/idle/done + cwd), not intent. Getting real intent out of
+herdr alone means depending on the sparse `runs/*.md` convention, which most sessions
+don't produce.
+
+## 4. Scored comparison
+
+| Criterion | A: Standalone watcher | B: Hermes plugin | C: herdr plugin/hook |
+|---|---|---|---|
+| (a) structured intent w/o raw keystrokes | Depends entirely on tap sources it's given — none exist continuously today | **Best** — `post_llm_call` gives per-turn content already, every turn | Weak — only continuous signal is lifecycle state; real intent needs sparse `runs/*.md` |
+| (b) opt-in enforcement point | Own config file, own gate — clean but net-new | Clean — gate inside `register()` before any hook does work | **Best** — one socket message, herdr already gates its own integrations |
+| (c) on-box summarization cost | Highest — must tail/parse/redact multiple external files first | **Lowest** — handed clean text directly | Low for lifecycle, but high if it also has to parse `runs/*.md` |
+| (d) notification surface | Must shell out (herdr toast or XFCE) | Must shell out (herdr toast or XFCE) | **Native** — herdr toast is its own surface, `[ui.toast]` already configured |
+| (e) update/rollout, both image classes | **Weakest** — new supervisor program = image bake; no equivalent Dockerfile for `agent-latest` | **Best** — pure file drop under `$HERMES_HOME`, works wherever Hermes already runs (both classes) | Good — file drop under `~/.claude/hooks`/`~/.hermes/plugins` via `herdr integration install`, but only reaches herdr-managed panes |
+
+## 5. Recommendation
+
+**DECISION: Hermes plugin (Option B)**
+
+Rationale: FR-011 and Story 5's hardest constraints are (1) real per-turn intent
+without raw keystrokes, and (5) a rollout story that doesn't require rebuilding either
+image class. Concrete evidence on this host shows Option A fails (5) outright — the only
+mechanism this repo has for registering a new supervised program is a `Dockerfile` COPY
+into `supervisord.conf`, which has no `agent-latest` equivalent, making that option
+image-bake-only on one of the two live classes. Option C is native for opt-in/notification
+but its only continuous, low-cost signal is coarse lifecycle state — it would need Option
+B's or Option A's tap to get real intent anyway. Option B satisfies (1) directly
+(`post_llm_call` hands over already-resolved turn text, cheapest to summarize-on-box), and
+(5) matches proven fact: this host already runtime-installs a real Hermes plugin
+(`herdr-agent-state`) as a pure file drop, no image rebuild, and Hermes is the one
+component already supervised identically across both `primus` and `agent-latest`
+(that's the same "hermes-gateway pattern" this task was pointed at as reference).
+
+Caveat worth carrying into T042: a Hermes-hosted Scout is blind to bare-herdr sessions
+that never touch Hermes chat (a Claude Code/Codex pane with no Hermes turn). This does
+**not** violate the "Hermes first, never Hermes-only" inherited constraint — that
+constraint is about marketplace touchpoints in general (Store/CLI/catalog remain
+Hermes-independent), and Story 5's own acceptance criteria only require discovery "via
+Scout **or** Hermes/CLI." It is, however, a real coverage gap: pure-herdr desktops get no
+push-side discovery in v0. Cheap mitigation for a later phase, not blocking: also register
+`herdr integration install hermes`'s existing socket report as a secondary opt-in trigger
+so the same plugin can request the herdr toast surface (`[ui.toast] delivery = "herdr"`)
+instead of shelling to `notify-send`, without adding a second host.
+
+## 6. v0 implementation sketch
+
+Components:
+
+- `~/.hermes/plugins/m2-solution-scout/`
+  - `plugin.yaml` — `name: m2-solution-scout`, `description: Solution Scout intent watch`.
+  - `__init__.py` — `register(ctx)` wires `on_session_start` (load `pull-policy.toml`,
+    no-op immediately if `scout.enabled=false` or `tenant_id` missing — fail closed, per
+    S4's policy rules) and `post_llm_call` (the intent tap).
+- Config: reuse S4's existing `pull-policy.toml` schema verbatim
+  (`~/.config/m2-market/pull-policy.toml`, `[scout]` block, `raw_keystrokes`/
+  `raw_client_data` reserved-deny keys, `max_proposals_per_day`, cooldowns). No new
+  config format — the plugin is a new *host* for the same contract S4 already specified.
+- State/telemetry: same paths as S4 §3 (`~/.local/share/m2-market/scout/state.json`,
+  `outbox/YYYY-MM-DD.jsonl`) — the plugin process just runs inside Hermes instead of as
+  its own daemon.
+
+Event flow (per turn, inside `post_llm_call`):
+
+1. Gate: `scout.enabled` true, tenant_id present, rate cap and per-session cap not yet
+   hit, cooldown not active for the last dismissed listing → else return immediately.
+2. Take `user_message` + `assistant_response` (bounded to `summary.max_source_chars`),
+   redact secrets/client identifiers per `pull-policy.toml`, produce
+   `m2.scout.intent_summary.v1` (S4 schema, unchanged) — deterministic extractive summary
+   in v0, no extra LLM call needed since the plugin already has clean turn text.
+3. `POST /memory/search` to memory-api, `agent_id=market:catalog`, tenant-filtered (S4 §3
+   catalog query, unchanged).
+4. Score/coverage threshold check (S4's `m2.scout.match.v1`) → if it clears, build
+   `m2.scout.proposal.v1` and fire the toast (`notify-send` primary, herdr socket toast as
+   fallback/secondary surface) with the M2 Store deep link.
+5. Write `proposal_shown` telemetry to local outbox (batched flush to `market:evidence`,
+   same as S4 §3/§4) — Scout never calls `m2-market install` itself; Store/CLI own
+   debit→grant→apply and emit the accept/dismiss events this plugin later folds back in.
+6. All of steps 2-5 run off the hot path where possible (background thread, mirroring the
+   `boot-md` hook tutorial's pattern of not blocking the turn on non-essential work) so a
+   slow catalog query never adds latency to the operator's actual turn.
+
+Guardrails carried over unchanged from FR-011 / S4: default `enabled=false`; opt-in is
+per-desktop `pull-policy.toml`; `raw_keystrokes`/`raw_client_data` keys hard-refuse start
+if true; rate cap default 5/day; propose-only — install always requires the human's click
+through M2 Store.
+
+DECISION: Hermes plugin