# 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