hermes-grokbot-manual/FLEET-MANUAL.md

# Fleet Manual

Operator contract. Version 3.0 — 27 September 2026.

Changelog: v3.0 locks the fleet to jobs, not chat. The shared diary mailbox is retired as a bus. Wiring (Tailscale, SSH relay, `:8642`) is infra, not the operating model.

This file is the source of truth. `MANUAL.md` is historical.

## 1. What this is

Grok Bot is the front door you talk to. Hermes is the worker on your machine. Regis is an outside drafter. You are the Gatekeeper.

Agents do not chat. They pass jobs. A job has one owner, one state, one live surface, and an evidence slot. Anything irreversible is you.

## 2. Locked shape

```
You  →  CoS                 GO / no-go / "saved" / "stand down"
CoS  →  worker              open a job (what, who, done-when, live URL)
worker → CoS                event file: proposal | block | outcome
CoS  →  job file            the only rewrite: flip state
watcher → CoS routine       doorbell POST when a new event file appears
```

Illegal:

- Regis talking to Hermes
- Hermes talking to Regis
- A third agent joining a job without CoS opening a second job
- CURRENT text without a live URL and a `live_read_at`
- "Done" without an evidence path
- Secrets in git, chat, jobs, or events

## 3. Roles

| Role | Who | Does | Never |
|---|---|---|---|
| Gatekeeper | Human | GO, login, Save / Send / publish / spend, plant vault secrets | Pastes secrets into chat |
| CoS | One Grok Bot | Opens jobs, fact-checks, owns `state`, wakes on doorbell | Approves done without evidence; chats with workers |
| Worker (Regis) | Outside runtime | Reads live surface, drafts, drive-and-stop at login | Send, post, login, Save, talk to Hermes |
| Worker (Hermes) | Host agent | Audit, research, desktop hands, evidence packs | Page editing as the primary path; talk to Regis |
| Watcher | Script or local Hermes cron | Detects new event files, POSTs doorbell | Calls a model to see if a file grew |
| Fleet Ops | Optional later | Host doctor / disk / updates | Exists before a second host has been up 14 days |

One human conversation: you talk to CoS. CoS does not freelance package upgrades.

## 4. The record

Repo: `Tony_tech/personal-agent-os`

```
memory-systems/agent-os/04_projects/<project>/jobs/
  JOB-<YYYYMMDD>-<slug>.md          # CoS owns this file
  events/JOB-<YYYYMMDD>-<slug>/
    001-<from>-<type>.md            # anyone may add; nobody edits
```

Old shared logs (`regis-cos.md` and any append-only diary) are archives. Do not append work to them.

### Job file (CoS only)

```yaml
---
id: JOB-YYYYMMDD-slug
project: <project>
surface: <one page or one artifact>
state: open
owner: regis
gate: human-login
live_url:
live_read_at:
current_hash:
proposed_hash:
evidence: []
blocker: null
---

# JOB-YYYYMMDD-slug

what:
who:
done-when:
```

`state` values, in order:

`open` → `proposed` → `acked` → `ready_to_save` → `saved`

Side exits: `blocked` | `stand_down`

Only CoS writes this file. A worker that rewrites `state` is out of contract.

### Event file (workers and CoS)

```yaml
---
job: JOB-YYYYMMDD-slug
from: regis
to: cos
type: proposal
at: 2026-09-27T10:50:00-07:00
live_url:
live_read_at:
---
```

`type` is one of: `proposal` | `ack` | `reject` | `block` | `outcome` | `gatekeeper`.

`proposal` without `live_url` and `live_read_at` is invalid. CoS rejects it and does not discuss it.

Body holds CURRENT (from that URL at that time), PROPOSED, and evidence paths. No secrets. Relayed human words are quoted verbatim and labeled who / where / when.

## 5. Job loop

1. Gatekeeper says GO.
2. CoS creates the job file. `state: open`. Live URL required before any draft.
3. Worker reads that URL now. Writes `NNN-<from>-proposal.md`. If the live surface cannot be read, writes `block` instead of inventing CURRENT.
4. Watcher sees the new file and doorbells CoS.
5. CoS fact-checks against the project's canonical facts. Writes `ack` or `reject` event. Flips job `state` to `acked` or `blocked`.
6. Worker drives to the field and stops at login.
7. Gatekeeper logs in. Worker pastes only the ACK'd text. Stops before Save.
8. Gatekeeper clicks Save and tells CoS. CoS writes `outcome`, sets `saved`, attaches evidence.
9. CoS opens the next job. One surface per job.

Approvals count only as a CoS `ack`/`outcome` event or a `gatekeeper` event quoting you.

## 6. Wake path

Do not pay a model to see if a file grew.

Primary: watcher lists `jobs/events/**` (mtime or `git log --since`). On a new file, one HTTPS POST to the CoS routine.

```bash
curl -fsS -X POST "<WEBHOOK_URL>" \
  -H "Authorization: <AUTH_HEADER_FROM_VAULT>" \
  -H "Content-Type: text/plain" \
  --max-time 10 \
  --data "JOB-id type=proposal"
```

Body is a doorbell. No secrets. No draft text. CoS acts only on job + event files. Duplicate ping with nothing new: stay quiet.

Backup until the doorbell has fired clean twice: hourly hash check, not a 15-minute model poll.

Pinger is outbound only. No Funnel. No new open port on Hermes hosts. Human plants URL and header in the pinger vault. The bot never sees the key.

STATUS: doorbell planted but not proven as of 2026-09-27. Keep the hourly backup until two clean wakes are logged as `outcome` events on any job.

## 7. Hermes wiring (infra only)

Need Hermes from CoS? Use what already works on the host.

- Desktop-primary, no gateway: SSH relay MCP (`ask`, `health`).
- Gateway up: HTTP `http://<tailscale-host>:8642/v1`, bind the Tailscale IP, never `0.0.0.0`.
- Tailscale only. No Funnel.
- Grok may read Hermes memory plugins. Grok may not write them.
- Account-scoped MCP is visible to every bot on the account. Treat every identity bot as able to see every connector. Do not pretend a prompt is isolation.
- Do not add Fleet Ops or a second-host identity bot until a second host has been up 14 days.

Relay details and marketplace template URLs live in `MANUAL.md` if you need to rebuild a box. They are not the fleet.

## 8. Secrets

- Vault holds `API_SERVER_KEY`, mailbox/job-repo token, webhook header, SSH keys.
- Job-repo token: narrow, repo-scoped, planted by the human. Never an admin credential. Never pasted in chat.
- Nothing secret in jobs, events, or this manual.
- Rotate anything that appeared in a screenshot or a thread.

## 9. Cadence

- You talk to CoS when there is work or a Save.
- Watcher runs continuously or every few minutes. It does not use Grok.
- CoS runs when you speak or when a doorbell arrives.
- Workers run only on an open job.
- Weekly: one secrets check, one "any job stuck in `blocked`?" pass.

## 10. Hard rules

- One surface per job.
- Live read on the same surface before CURRENT.
- Evidence path before `saved`.
- Re-read live immediately before paste; `stand_down` if it is already done.
- Anything beyond the card (new account, payment, verification code, different listing): `block`.
- Jobs are not memory. Do not copy them into Hermes memory by default.
- Long goals go to a Hermes kanban or a project file, not a Grok thread.

## 11. Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Two agents fighting a SHA | Still writing one diary | Use a new event file |
| Stale CURRENT | Drafted from memory or another URL | Reject; demand `live_url` + `live_read_at` |
| "Done" with no proof | Prose status | Leave `state` where it is |
| No wake | Webhook unplanted or non-2xx | Check vault, fall back to hourly hash |
| Agent "doesn't see it" | Said in chat, not an event file | Post the event |
| Other bots calling a host | Account-scoped MCP | Assume shared; don't put irreversible tools on it |
| `tailscale ping` to Regis fails | Outbound-only by design | Not a fault |

## 12. Sources

- This contract supersedes v2.0 mailbox + 15-minute dual poll.
- Wiring appendix: [MANUAL.md](MANUAL.md)
- Bridge: https://github.com/shagghiesuperstar/hermes-grok-bridge
- Live job seat: `Tony_tech/personal-agent-os` → `memory-systems/agent-os/04_projects/<project>/jobs/`
- Archive only: `…/veripath/regis-cos.md`

Hostnames, URLs, keys, and ACL tags in any leftover examples are placeholders.