Hermes Client reference pattern for Mission Control

Status: reference note / adapter inspiration, not canonical runtime contract Owner: Luci / Lucienne Reviewed: 2026-05-22 Source repo: https://github.com/lotsoftick/hermes_client Source note: ~/workspace/mission-control/reports/mission-control-hermes-client-source-note.md

Why this exists

hermes_client is a useful concrete implementation of a Hermes web cockpit. It should inform Mission Control's Hermes adapter layer, but it should not replace Mission Control or become a second source of truth.

Mission Control remains responsible for tickets, WAT decisions, runtime_sessions, scheduled work visibility, review evidence, history harvesting, and runtime switch continuity.

Patterns worth borrowing

HermesProfileRuntimeAdapter

Map a UI-visible runtime option to a Hermes profile, but keep these concepts separate:

• MC role/persona: Luci, Lucienne, Atlas, Tessa, Scott, etc.
• MC runtime profile: MC-side launch/routing preset.
• Hermes profile: isolated Hermes home/config/session state selected with hermes -p <profile>.
• Invocation: one process/session spawned for one turn or workstream.

CliProcessInvocation

Invoke Hermes as an argv array, not as a shell string.

Minimum ledger data for each invocation:

• ticket/task/session id
• runtime profile
• Hermes profile, if used
• cwd
• argv with secrets redacted
• pid/process id when available
• started/ended timestamps
• exit code/status
• stdout/stderr transcript paths or harvested summary

SseTurnStream

A chat/workbench turn may stream stdout to the browser via Server-Sent Events, but streaming is only a display path.

Durable state must still be written to Mission Control before or during the turn:

• user message/comment first
• runtime injection second
• assistant/runtime output harvested into MC history
• final status/artifacts recorded in MC history or ticket metadata

Browser disconnect behavior must be explicit:

• kill child process, or
• detach and continue with harvest path, or
• mark interrupted with recovery instruction

It must never be accidental.

SessionFileReconciler

Hermes session JSON can be used as supporting truth for Hermes-originated turns, but MC remains the workflow source of truth.

Reconciliation should:

• import new Hermes turns into MC ticket/thread history
• avoid duplicate imports
• preserve soft-deleted or hidden rows
• tolerate active-write race windows
• record provenance that the turn came from Hermes session files

CronStateMirror

Hermes cron can be inspected and surfaced, but production scheduled work remains in MC/Luci scheduler unless a separate architecture decision changes that.

Allowed pattern:

• read Hermes cron state for visibility
• link Hermes cron jobs to MC/control-room documentation if used
• make Hermes cron runs visible as MC events when relevant

Not allowed by default:

• moving production scheduled tasks into Hermes cron because it is convenient
• duplicating scheduler definitions in the control room

PtySetupWorkbenchCard

A PTY-backed setup drawer/card is useful for real runtime setup flows that are hard to reimplement as forms.

Required safeguards:

• local/trusted by default
• authenticated if remotely reachable
• no unauthenticated PTY over LAN/Tailscale
• command allowlist or explicit operator confirmation for risky commands
• transcript/log capture with secrets redaction policy

Security defaults

Do not copy hermes_client's local-app defaults into production MC unchanged.

Mission Control defaults should be:

• no hardcoded admin password
• closed CORS unless explicitly opened
• no unauthenticated PTY
• no second Telegram poller
• secrets never written into docs/transcripts
• WebUI/config changes backed up and documented

Integration posture

Use this reference for the Hermes-specific adapter slice only.

Before code changes:

1. Add/confirm the MC runtime adapter contract.
2. Run runtime-profile inventory/lint.
3. Select a low-risk Hermes profile/session smoke test.
4. Verify runtime_sessions and MC history capture the invocation correctly.
5. Run Tessa validation if any Workbench/UI surface changes.
6. Run Atlas-style signoff if canonical MC runtime docs change.

Non-goals

• Forking hermes_client into Mission Control.
• Replacing MC tickets with Hermes sessions.
• Replacing MC scheduler with Hermes cron.
• Letting Hermes WebUI become a shadow control plane.
• Collapsing role/persona/runtimes/profiles into one ambiguous "agent" concept.