[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7583H3DD766GD3FPDMH65X3":3,"skill-same:01M7583H3DD766GD3FPDMH65X3":67},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":34,"commitSha":35,"skillDirectory":36,"forksCount":37,"repositoryHtmlUrl":38,"repositoryHomepageUrl":39,"ownerHtmlUrl":40,"ownerBlogUrl":6,"ownerDescription":41,"updatedAt":42,"install":43,"resources":56},"01M7583H3DD766GD3FPDMH65X3","cross-agent-design",null,"Before designing any cross-agent feature, protocol, or workflow: trace the receiving agent's end-to-end connectivity, auth, consumption, and permission path. This skill prevents the most expensive mistake in multi-agent systems — assuming that because Message A reaches Queue B, Agent C sees it and processes it.","lukemcqueen\u002Fsteadfaste-fleet","lukemcqueen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F405240?v=4","01M757MHPAGRXTJAT46SKZP98R","Luke McQueen","01M757MHPZ573KP8DT9GB8SBQ7",4,"MIT","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fcross-agent-design\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: cross-agent-design\ndescription: >-\n  Before designing any cross-agent feature, protocol, or workflow: trace the\n  receiving agent's end-to-end connectivity, auth, consumption, and permission\n  path. This skill prevents the most expensive mistake in multi-agent systems\n  — assuming that because Message A reaches Queue B, Agent C sees it and\n  processes it.\nversion: 1.0.0\ncategory: devops\nauthor: Steadfaste Fleet\ncreated_from_session: fleet-bus-architecture-survey\nrelated_skills:\n  - survey-before-action\n  - fleet-preflight\n  - fleet-bus\n  - agent-contract\n  - session-start-discipline\n---\n\n# Cross-Agent Design — Fleet-Aware Protocol Design\n\n## When to Load\n\nLoad this skill BEFORE:\n- Proposing any feature that involves another agent\n- Creating a new message type, topic, or protocol\n- Designing a workflow that delegates to another agent\n- Sending commands or requests to another agent's inbox\n- Writing any code that assumes another agent will see the message\n\n## The Core Principle\n\n**Messages don't \"arrive\" — they wait.**\n\nWhen you send a message to `inbox_esther`, it sits in a Postgres queue on your\nmachine. Whether Esther sees it depends on a chain of infrastructure that is\nNOT under your control:\n\n```\nYour send → Bus auth → ACL check → Queue write\n                                         │\n              ┌──────────────────────────┘\n              ▼\n    Does Esther connect to this Postgres?\n         │                    │\n        YES                   NO\n         │                    │\n    Does she have a        Message is orphaned.\n    consumer running?      Only the forwarder\n         │                 would move it, and\n        YES                it's paused.\n         │\n    Does the ACL allow\n    her to read this\n    queue?\n```\n\n## Pre-Flight Checklist\n\n### 0. Prove it on your own system first\n\nBefore ANY cross-agent design, protocol, or command: prove the identical flow works on your own machine first. A test that skips the local step is not a test.\n\n**The trap:** \"I sent the EXEC to Esther, the message landed in her queue with msg_id returned, so it's working.\" This proves SQL works, not orchestration. You must verify the full send→process→respond→read cycle on yourself before involving another machine.\n\n**Local proof checklist:**\n1. Send the message to your own inbox (`inbox_moses`) with a unique `correlation_id`\n2. Run the consumer manually to process it\n3. Verify the response landed back in your inbox\n4. Read the response — extract structured fields (exit_code, stdout, success)\n5. Archive the test message\n6. Only then send to a fleet agent\n\n### 1. Trace the receiving agent's connectivity\n\n```bash\n# How does the remote agent connect?\n#   - Same Postgres (orchestrators only)? → localhost:15432, Bearer token\n#   - External URL (all workers)?         → FLEET_BUS_URL, Basic Auth\n#\n# Check the receiving agent's .env\n#   FLEET_BUS_URL=https:\u002F\u002Fexample.com:13004  (or :14004 for Esther)\n#   FLEET_BASIC_AUTH=agentname:password\n#   AGENT_NAME=esther\n```\n\n**Never assume remote agents have localhost Postgres access.** Only Moses and\nEsther (the orchestrators) do. Worker agents connect through nginx with\nBasic Auth — a completely different auth path.\n\n### 2. Trace the auth flow\n\nEvery agent has exactly ONE of these auth modes:\n\n| Mode | Token type | When used | Who has it |\n|------|-----------|-----------|------------|\n| Basic Auth | `user:password` (htpasswd) | Through nginx | ALL agents |\n| Bearer | `hbus_...` | Direct localhost | Orchestrators only |\n\n**Before sending a command to another agent, verify their auth mode.**\nA Bearer-token-based MCP tool won't work on an agent that only has Basic Auth\nunless the MCP server is configured to fall back to Basic.\n\n### 3. Verify the consumption pipeline\n\nA message in an agent's inbox is only processed if the agent has a consumer:\n\n| Consumer type | Reads every | Handles | Configured on |\n|--------------|-------------|---------|---------------|\n| LLM-driven cron | 10-60 min | All message types | Moses (fleet-bus-workday\u002Fevening\u002Fovernight) |\n| agent-worker service | ~30 sec | Only `workflow_step` type | Some agents (may cause competing consumer problem) |\n| Manual MCP tools | On-demand | All message types | All agents (but only when they read their inbox) |\n\n**If the target agent has no bus-processor cron, your message sits unprocessed\nuntil it times out and goes to DLQ.** The `fleet-bus-*` cron jobs are only\nconfigured on Moses by default.\n\n### 4. Verify the ACL allows it\n\nFrom `bus.permissions` (Postgres table):\n\n```sql\n-- Only Moses can send to arbitrary queues.\n-- All other agents can only READ their own inbox and SEND to `inbox_orchestrator` (the shared orchestrator inbox — default target) or reply to a specific orchestrator via `inbox_moses`.\nSELECT agent_name, can_read, can_write, is_admin FROM bus.permissions;\n```\n\n| Agent | Can send to |\n|-------|-------------|\n| **Moses** | **Every queue** — all inboxes, workflow queues, health |\n| **Everyone else** | `inbox_orchestrator` (default), `inbox_moses` (point-to-point replies), own inbox, `workflow_step_result`, `inbox_health_check` |\n\n**If you need an agent to reply**, they send to `inbox_orchestrator` (or the originating orchestrator's queue, e.g. `inbox_moses`).\nThey cannot send to any other agent's inbox.\n\n### 5. Trace the reply path\n\nWhen the receiving agent replies, verify the path:\n\n```bash\n# The agent sends to inbox_orchestrator (or inbox_moses for point-to-point replies)\n# What URL do they use?\n#   - FLEET_BUS_URL (through nginx, port 13004)?\n#   - Direct localhost (port 8903)?\n# What auth?\n#   - Basic Auth for nginx?\n#   - Bearer token for localhost?\n```\n\n### 6. Account for the bus forwarder (if applicable)\n\nThe forwarder (`orch-bus-forwarder.py`, cron `orch-bus-forwarder-sync` every\n2m) mirrors messages between Moses' and Esther's Postgres instances —\nrole-aware PEER resolution since 2026-08-03 (Esther's peer = Moses :13004,\nMoses's peer = Esther :14004; `PEER_AUTH` = nginx Basic creds).\n\n- Without the forwarder, all messages live only in the local Postgres\n- Agents connecting to Esther's bus see only Esther-local messages\n- Cross-server message sync requires the forwarder to be running\n\n## Designing for N HETEROGENEOUS CODING AGENTS (the second axis)\n\nThe rest of this skill is about agents on the **bus**. This section is about\nagents consuming a **capability** — Pi, Hermes, Claude Code, Codex, whatever\nappears next. Standing constraint (Luke 2026-10-02): *\"fix things for\ninteroperability with different coding agents. always be thinking this.\"*\n\n**The rule: ONE implementation, per-host ADAPTERS.** A capability is implemented\nonce in a host-neutral contract; each host gets a thin adapter that converts its\ncalling convention and adds **no semantics**.\n\nThe failure this prevents is real and was shipped: `mem_context` existed in BOTH\nthe Hermes plugin and the MCP server, so whichever the runtime resolved, the\nother **silently did not exist**. An agent concluded \"memory is broken\", fell\nback to raw SQL, and reported the backend as the working path.\n\nRules, each of which is a bug that actually happened:\n\n1. **One implementation per capability.** Two implementations of one tool NAME\n   is worse than none — the runtime picks one silently and the other becomes a\n   phantom. Enforce with a test.\n2. **The contract may not import a harness.** If it needs one, either extract it\n   or declare it a **host-local extra** that names the reason (e.g. a tool that\n   needs the host's own LLM).\n3. **Schemas are DERIVED, never hand-written** — a hand-written schema list *is*\n   a second definition and drifts immediately.\n4. **Never substitute a fallback implementation on failure.** Fail-open is for\n   *availability* (\"carry on without memory\"), never for *semantics*. A fallback\n   is how the duplicate starts.\n5. **Fail loudly, never silently-empty.** An empty result that *looks* like \"no\n   data\" when the backend is down is worse than an error.\n6. **Verify the host's OWN API before writing its adapter** — never infer it from\n   a skill or a doc. Pi's first adapter failed TWICE, silently: the handler's\n   first parameter is the event (not a ctx), and prompt injection is the RETURN\n   VALUE (there is no ctx method). Both were masked by optional chaining.\n\n   Same rule when an adapter's session-uniqueness depends on env propagation:\n   a variable's presence on the host is NOT proof it reaches the consumer that\n   matters — inspect the propagation seam for the EXACT consumer, never a source\n   map or a documented merge. Two variants dead-end a resolver's env read: an\n   MCP `env` block that REPLACES the child environment (strips the harness's own\n   session id), and the subtler one — the merge is fine but the harness never\n   exports the id to its OWN process.env (Pi injects `PI_SESSION_ID` only into\n   bash-tool commands, so the governor's MCP child inherits nothing); verify on\n   the host which one you are facing. A static MCP `env` block cannot hold a\n   per-session value, so set the identity in the harness's lifecycle hook from\n   its own session manager (`ctx.sessionManager.getSessionId()`), which runs\n   BEFORE the consumer spawns and writes the env var the resolver reads\n   (measured: resolver answers \"per-repo, shared\" with no key and \"env,\n   unique\" once the key is set).\n\n   **The env-var NAME differs per harness — survey the exact name, never guess.**\n   Verified (2026-11-11) from each harness's own source: Claude Code injects\n   `CLAUDE_CODE_SESSION_ID` (note `CODE` in the middle — `CLAUDE_SESSION_ID` is\n   NOT set) into stdio MCP children since v2.1.154; Codex sets `CODEX_SESSION_ID`\n   but does NOT forward it to MCP children by default (shell commands only), so it\n   needs a `[mcp_servers..env]` pin or an upstream change. The resolver honours all\n   of them (`_ENV_SESSION_ID_SOURCES` in loop-gov-mcp.py), so a harness that reaches\n   the MCP child with its own id gets a unique session with no adapter — and a\n   a harness that does not silently shares the per-repo id (fail-closed since\n   2026-11-10). Per-harness session-id table (which env var, and whether it\n   reaches the MCP child): `references\u002Fharness-session-identity.md`.\n7. **Never let the model own a lifecycle guarantee.** Triggers (`turn_end`, stop\n   hooks, crons) belong to the host — \"remember to save\" is not a mechanism.\n8. **A registry, not per-host prose.** At N hosts the failure mode is N docs that\n   disagree; declare hosts in one file and GENERATE their docs from it.\n9. **Registering is not executing.** A deploy that COPIES a per-host adapter into the\n   scripts directory has wired NOTHING — wiring is a step that RUNS. Gate it on the\n   harness's PRESENCE (its agent dir or launcher), run every half of the adapter, and\n   report the outcome per half: a host without the harness is not a fault, while a host\n   that HAS it and comes out of a deploy unwired is. Pair the run with one line in that\n   host's doctor, so \"harness present but unwired\" is a reported state rather than a\n   silence nobody reads. An installer reaching a host is not evidence that it ever ran.\n\n### The GATE half of a capability\n\nA capability a host must satisfy is not only code the host RUNS — it is often also a gate\nthe host must PASS (a pre-commit check, an evidence record, a policy its commits are judged\nby). Design that gate for the host's REAL mechanism, or the host is refused forever while\nnothing anywhere reports a fault:\n\n- **A gate keyed on another host's tool NAME is unsatisfiable here.** Establish what the\n  host actually does by driving the host's own package — its exported tool factories and\n  the instruction its own system prompt emits. A name that is ordinary vocabulary in one\n  harness may appear NOWHERE in another's bundle; grep the bundle and treat zero matches as\n  the measurement it is.\n- **Record what the host actually did, under its true name**, and give the checker one\n  predicate per real mechanism. Never normalise a host's action into another host's verb:\n  the store is evidence, so a row asserting an action that never happened is worse than a\n  missing row.\n- **Ask the shared implementation for the identity the gate queries** rather than deriving a\n  second key from an env var or a state file — and resolve it for the timing case where the\n  host acts BEFORE the gate's context exists.\n- **A host refused for a reason it cannot observe looks broken to its operator.** When a\n  host reports \"I cannot do X\", check FIRST whether the gate demands a mechanism that host\n  does not have: the agent's behaviour is often correct and the gate is the defect.\n\nProcedure, predicates and the probe recipe:\n`enforcement-gate-migration > references\u002Fmulti-harness-evidence-writer.md`.\n\n### Choosing the implementation of a SHARED capability\n\nA capability both systems consume is a design decision before it is a build. Decide in this order,\nand let MEASUREMENT make the call:\n\n10. **Budget the LANGUAGE by measuring, not by preference.** Check the toolchains that actually\n    exist (`cargo --version`, `go version`, the interpreter) and what the systems you are serving\n    are written in. A capability that adds a THIRD language to a two-language fleet costs a\n    toolchain, a build path and a dependency surface on every host — and the \"lowest memory\" option\n    is worthless if its toolchain is not installed. Prefer the language of the system the capability\n    serves: a binary in that language is also the one its consumers can link in-process.\n11. **Keep the runtime dependency set inside what a constrained host already has.** A build that\n    needs a registry fetch, or a cache that shells out to a tool that may be absent, is unavailable\n    exactly when that host cannot repair it. Prefer dependencies resolvable from the local cache,\n    and where a component can be compiled IN rather than called OUT to (a bundled engine), compile\n    it in: one build-time cost beats an unavailability that renders as \"no data\".\n12. **Every external provider is OPTIONAL, and its absence is LOUD and NAMED.** An unconfigured\n    provider exits with its OWN status (never a generic failure) and names the variable that unlocks\n    it, so \"could not look\" cannot render as \"found nothing\". Say what still works without it — the\n    offline half of a capability is usually the durable half, and it must not depend on the\n    provider being reachable.\n13. **One dispatch, two surfaces.** Expose a CLI and an MCP stdio server over the SAME functions,\n    and generate both surfaces' metadata from ONE table, so no surface can describe an operation\n    differently or drift from the other. A daemon is a third surface nobody asked for: a process\n    that starts, does one thing and exits needs no port, no health check and no listener to secure.\n14. **Measure the envelope on a real host before quoting one.** A sizing table describes someone\n    else's machine; report the binary size and the STEADY-STATE footprint you measured, and when the\n    decision turns on a number the operator named, go and test THAT number instead of arguing from\n    the table.\n\nChecklist before shipping anything agent-facing:\n- [ ] works from **at least two different harnesses** (prove it, don't claim it)\n- [ ] any gate the host must PASS keys on something that host **has** — proven by driving\n      the host's own package, never inferred from a doc or from another harness's vocabulary\n- [ ] semantics in **one** place; adapters add none\n- [ ] metadata **derived**, not duplicated\n- [ ] unreachable dependency → **visible message**, never a silent empty\n- [ ] Linux **and macOS**\n- [ ] a **drift guard test**, not just a doc\n- [ ] the deploy **RUNS** the adapter where the harness is present, and the host doctor reports it\n\nReference: `docs\u002Fdesign\u002Fagent-interop.md`.\n\n### Migrating a host-bound capability so ALL hosts reach it — and rule changes load without a host restart\n\nA capability that lives only inside one harness's plugin (the enforcement gate, memory, context)\nhas **no access layer for other agents** — only that harness reaches it, and its code is frozen at\nthat host's startup, so a rule change forces a host restart (the \"deploy ≠ load\" trap). To expose\nit to N heterogeneous coding agents AND make a rule change live on the next call instead of a\nrestart, follow the order that was proven on the governance write-gate:\n\n1. **Extract the semantics into a host-neutral contract** under `ops\u002Fservices\u002F\u003Cname>\u002F\u003Cmodule>.py`\n   — stdlib-only, no harness import, loadable via `importlib.util.spec_from_file_location`.\n   Register it in the deploy map (`fleet-update.sh`) beside the established\n   `ops\u002Fservices\u002Fmycortex-mem\u002Fcontext_tools.py` contract. This is the ONE implementation both the\n   current host plugin and every adapter call.\n2. **Build the PARITY gate first, before integrating.** The migration arbiter is a test that loads\n   the ORIGINAL implementation from its real file (importlib) and asserts the contract returns the\n   identical verdict on a corpus spanning the whole surface — the allowlists, the write-class\n   rules, every sanctioned lane, and the evasions. \"Works as well as X\" is then a test, not a\n   promise. When a corpus expectation diverges from parity, the ORIGINAL is the spec: correct the\n   TEST, not the extraction — the divergence is normally a latent quirk of the original (below),\n   not a loss.\n3. **Reach the contract by subprocess on the decision path** — a fresh CLI invocation per call\n   (a `loop-gov.py`-style CLI over the one dispatch). A new process always loads the current file,\n   so a rule change takes effect on the next call with no host restart. This is the mechanism that\n   actually removes \"restart the gateway to load new enforcement rules\"; it is the same shape\n   pi's adapter already uses, and it is why no long-lived daemon is needed (rule 13).\n4. **Make every host a thin adapter** over the contract; a host with no matching interception hook\n   is declared in the harness registry (`ops\u002Finstall\u002Fharnesses\u002Fregistry.yaml`) WITH a reason, never\n   left silently ungated.\n\nPitfalls that cost a cycle here:\n- **An allowlist that anchors the head command couples the subcommand's position.** A rule\n  `systemctl (status|show|...)` matches only when the subcommand comes immediately after\n  `systemctl`; `systemctl --user show x` is therefore write-class in BOTH the original and the\n  contract. Preserve the limitation in the migration — parity is the goal, not improved\n  classification — and do not \"fix\" it as part of a faithful extraction.\n- **Corpus fixtures must not carry a `\u002Fhome\u002F`-prefixed literal path, even a generic one.** The PII\n  guard refuses the `write_file` on it. Use `~` verbatim or a `\u002Fvar`\u002F`\u002Fsrv`\u002F`\u002Ftmp` path when a\n  fixture needs a filesystem shape.\n- **An adapter that classifies locally still carries governance semantics.** \"The adapter delegates\n  the X decision\" and \"the adapter has no semantics of its own\" are different claims: a local\n  classifier (an allowlist, a decision rule) IS a governance semantic even when it forwards the\n  lock check to the shared impl. State precisely which decision is delegated and which is still\n  implemented locally, or a plan review (and the migration) will contradict itself.\n\n## Common Pitfalls\n\n### ❌ \"I sent a message to inbox_esther, why didn't she respond?\"\n\nCheck, in order:\n1. Does Esther connect to the same Postgres instance? (She uses `FLEET_BUS_URL`)\n2. Does she have a bus-processor cron? (`fleet-bus-*` jobs in her cron list)\n3. Does her ACL allow reading `inbox_esther`? (Yes — every agent reads their own)\n4. Was the message consumed by `agent-worker` without being archived? (Competing consumer)\n\n### ❌ \"The message was consumed but no response came back — and the queue is empty\"\n\nThis is the trickiest failure: no evidence left behind. The handler consumed the message, archived it, and exited cleanly — but `send_bus_result` never delivered the reply.\n\n**Diagnostic chain:**\n\n1. **Check `archived_by`** — `bus.archive(queue, msg_id, agent_name)` stores the archiver. Query recent archives to confirm the expected agent consumed it, not a forwarder or admin cleanup:\n   ```bash\n   sg docker -c \"docker exec mycortex-postgres psql -U mycortex -d mycortex -t\" \u003C\u003C 'EOF'\n   SELECT queue_name, body->>'subject' as subject,\n          archived_at::timestamptz(0), archived_by\n   FROM bus.archives\n   WHERE archived_at > now() - interval '30 minutes'\n   ORDER BY archived_at DESC;\n   EOF\n   ```\n   If `archived_by` matches the target agent → handler ran, reply path is broken.\n   If `archived_by` is `moses` or `pre-cleanup` → something else ate it.\n\n2. **Check handler state file** — The handler logs processed correlation_ids:\n   ```bash\n   cat ~\u002F.steadfaste-fleet\u002Fstate\u002Fagent-message-state.json\n   ```\n   If your correlation_id is in `processed_ids` → handler ran. The gap is in `send_bus_result`.\n\n3. **Test `bus_send` independently** — If the handler ran but no reply came, test whether the agent's `bus_send` works:\n   ```bash\n   python3 -c \"\n   import sys; sys.path.insert(0, '$HOME\u002Fsteadfaste-fleet\u002Fops\u002Fscripts')\n   from lib.fleet_bus import bus_send\n   r = bus_send('inbox_orchestrator', {'from':'test','subject':'TEST','body':{},\n                                'correlation_id':'diag'})\n   print(f'Send: {r}')\n   \"\n   ```\n   Returns `{'msg_id': '...'}` → send works interactively. The cron environment differs.\n   Returns `None` → bus_send is broken. Check config, auth, and URL.\n\n4. **AGENT_NAME misconfiguration** — The handler polls `inbox_{AGENT_NAME}`. If AGENT_NAME falls back to hostname (older code) instead of being set in `.env`, the handler polled `inbox_cisnet03` while you sent to `inbox_gisu`. Check the agent's `.env` has `AGENT_NAME=\u003Cname>`.\n\n5. **Known silent-failure gap** — `send_bus_result()` catches all exceptions internally and returns `False` without propagating. The crash guard's except block is never triggered. The handler logs \"Failed to send\" to stdout (which the cron runner captures) but returns `True` (all done). The message is archived with no result sent. Being actively fixed.\n\n### ❌ \"The message vanished — consumed but I never asked for it\"\n\n### ❌ \"The MCP tool works on my machine but not on the remote agent\"\n\nYour machine (Moses) has a Bearer token for direct localhost access. Remote\nagents only have Basic Auth through nginx. The MCP tool resolves auth from\n`.env` — verify the remote agent's config matches their actual\nauth mode.\n\n### ❌ \"I designed a protocol where Agent X sends to Agent Y directly\"\n\nOnly Moses can send to arbitrary inboxes. All other agents can only send to\n`inbox_moses`. If your protocol requires Esther → Gisu direct messaging,\nit won't work at the ACL level. Route through Moses as an intermediary.\n\n### ❌ \"I created a new fleet-wide cron without checking what already runs\"\n\nBefore creating any `agent-*` or `local-*` cron, run `cronjob(action='list')`\nand `search_files()` with 3+ terms for the script purpose. The\n`scoring-activity-watchdog` already existed when `local-cron-cost-report` and\n`local-trace-quality-watchdog` were created — extending the watchdog was the\ncorrect call. Creating new parallel crons fragments the system and creates\nduplicate maintenance burden. See `session-start-discipline > references\u002Fsurvey-before-creating.md`.\n\n### ❌ \"bus_mode defines how agents communicate\"\n\nThe field was renamed to `bus_access` (values `host`\u002F`client`) because\n`bus_mode` sounded like a configuration instruction to install a bus daemon.\n`bus_access` describes capability: does this agent run the bus server (`host`)\nor connect to a shared one (`client`)? All agents use `client` except\norchestrators (Moses, Esther) who use `host`.\n\n## Reference\n\n- `fleet-bus` skill — bus operations, DLQ management, recovery\n- `fleet-preflight` skill — general pre-flight checks (manually authored)\n- `docs\u002Freference\u002Ffleet-bus-config.md` — detailed config and auth resolution\n- `docs\u002Forch-bus-setup.md` — full setup guide with architecture overview\n- `agent-message-handler.py` — fleet-wide no_agent consumer (every 5 min)\n\n## Deployment Pattern: Fleet-Wide Features\n\nWhen a new cross-agent feature needs every agent to support it:\n\n1. **Add handler to `agent-message-handler.py`** — add a new `subject` case\n   (e.g. `subject == \"EXEC\"`) to the existing dispatch chain. This is the\n   only consumer that exists on every agent in the fleet.\n2. **Register** new or updated files in `fleet-update.sh`\n3. **Deploy** via `fleet-update.sh` on each agent\n4. **~5 min response time** (handler polls every 5 min)\n5. **No LLM cost** (no_agent script — subprocess only)\n\n### Example: EXEC Command (added 2026-07-21)\n\n```\nMoses: fleet exec esther fleet-doctor.py --json\n  → sends EXEC to inbox_esther\n  → handler picks up within 5 min\n  → runs ~\u002F.steadfaste-fleet\u002Fscripts\u002Ffleet-doctor.py --json\n  → sends EXEC_RESULT back to inbox_moses\n  → fleet exec polls and displays result\n```\n\nMessage schema:\n- `subject: EXEC` — body: `{ command: str, params: list, timeout: int }`\n- `reply: EXEC_RESULT` — body: `{ success: bool, stdout, stderr, exit_code }`\n\n### Repo-Wide Search for Config\u002FVariable Changes\n\nWhen fixing a port number, URL, env var name, or file path — **do not fix\njust the file you're editing**. Search the entire repo first:\n\n```bash\ngrep -rn \"\u003Cold-value>\" ~\u002Fsteadfaste-fleet \\\n  --include=\"*.py\" --include=\"*.md\" --include=\"*.sh\" \\\n  --include=\"*.yaml\" --include=\"*.conf\" \\\n  2>\u002Fdev\u002Fnull | grep -v \".git\u002F\" | grep -v \"__pycache__\"\n```\n\n**Why:** The 8905→8903 bus port fix found 4 stale files across 3 directories\n(workflow YAML, server.py default, MCP docstring, architecture doc) that a\nsingle-file fix would have missed. Workflow YAMLs, code docstrings, and\nhistorical plan documents are the most common hiding places.\n\n### Test Like an Agent Would\n\nAfter making changes, verify through the correct path:\n\n| Path | What it proves | When to use |\n|------|---------------|-------------|\n| `fleet send` (docker exec SQL) | SQL function works | Local dev only — not representative |\n| `curl 127.0.0.1:8903 + Bearer` | MCP tools path works | Testing Moses\u002FEsther MCP |\n| `curl domain:13004 + Basic` | **External agent path works** | Testing remote agent connectivity |\n| `agent-message-handler.py --once` | Consumer picks it up | Testing handler dispatch |\n\nThe external path (nginx :13004 + Basic auth) is the only one that proves\na remote agent can send\u002Freceive. Always test through the path the\nreceiving agent would use.\n","# Cross-Agent Design — Fleet-Aware Protocol Design\n\n## When to Load\n\nLoad this skill BEFORE:\n- Proposing any feature that involves another agent\n- Creating a new message type, topic, or protocol\n- Designing a workflow that delegates to another agent\n- Sending commands or requests to another agent's inbox\n- Writing any code that assumes another agent will see the message\n\n## The Core Principle\n\n**Messages don't \"arrive\" — they wait.**\n\nWhen you send a message to `inbox_esther`, it sits in a Postgres queue on your\nmachine. Whether Esther sees it depends on a chain of infrastructure that is\nNOT under your control:\n\n```\nYour send → Bus auth → ACL check → Queue write\n                                         │\n              ┌──────────────────────────┘\n              ▼\n    Does Esther connect to this Postgres?\n         │                    │\n        YES                   NO\n         │                    │\n    Does she have a        Message is orphaned.\n    consumer running?      Only the forwarder\n         │                 would move it, and\n        YES                it's paused.\n         │\n    Does the ACL allow\n    her to read this\n    queue?\n```\n\n## Pre-Flight Checklist\n\n### 0. Prove it on your own system first\n\nBefore ANY cross-agent design, protocol, or command: prove the identical flow works on your own machine first. A test that skips the local step is not a test.\n\n**The trap:** \"I sent the EXEC to Esther, the message landed in her queue with msg_id returned, so it's working.\" This proves SQL works, not orchestration. You must verify the full send→process→respond→read cycle on yourself before involving another machine.\n\n**Local proof checklist:**\n1. Send the message to your own inbox (`inbox_moses`) with a unique `correlation_id`\n2. Run the consumer manually to process it\n3. Verify the response landed back in your inbox\n4. Read the response — extract structured fields (exit_code, stdout, success)\n5. Archive the test message\n6. Only then send to a fleet agent\n\n### 1. Trace the receiving agent's connectivity\n\n```bash\n# How does the remote agent connect?\n#   - Same Postgres (orchestrators only)? → localhost:15432, Bearer token\n#   - External URL (all workers)?         → FLEET_BUS_URL, Basic Auth\n#\n# Check the receiving agent's .env\n#   FLEET_BUS_URL=https:\u002F\u002Fexample.com:13004  (or :14004 for Esther)\n#   FLEET_BASIC_AUTH=agentname:password\n#   AGENT_NAME=esther\n```\n\n**Never assume remote agents have localhost Postgres access.** Only Moses and\nEsther (the orchestrators) do. Worker agents connect through nginx with\nBasic Auth — a completely different auth path.\n\n### 2. Trace the auth flow\n\nEvery agent has exactly ONE of these auth modes:\n\n| Mode | Token type | When used | Who has it |\n|------|-----------|-----------|------------|\n| Basic Auth | `user:password` (htpasswd) | Through nginx | ALL agents |\n| Bearer | `hbus_...` | Direct localhost | Orchestrators only |\n\n**Before sending a command to another agent, verify their auth mode.**\nA Bearer-token-based MCP tool won't work on an agent that only has Basic Auth\nunless the MCP server is configured to fall back to Basic.\n\n### 3. Verify the consumption pipeline\n\nA message in an agent's inbox is only processed if the agent has a consumer:\n\n| Consumer type | Reads every | Handles | Configured on |\n|--------------|-------------|---------|---------------|\n| LLM-driven cron | 10-60 min | All message types | Moses (fleet-bus-workday\u002Fevening\u002Fovernight) |\n| agent-worker service | ~30 sec | Only `workflow_step` type | Some agents (may cause competing consumer problem) |\n| Manual MCP tools | On-demand | All message types | All agents (but only when they read their inbox) |\n\n**If the target agent has no bus-processor cron, your message sits unprocessed\nuntil it times out and goes to DLQ.** The `fleet-bus-*` cron jobs are only\nconfigured on Moses by default.\n\n### 4. Verify the ACL allows it\n\nFrom `bus.permissions` (Postgres table):\n\n```sql\n-- Only Moses can send to arbitrary queues.\n-- All other agents can only READ their own inbox and SEND to `inbox_orchestrator` (the shared orchestrator inbox — default target) or reply to a specific orchestrator via `inbox_moses`.\nSELECT agent_name, can_read, can_write, is_admin FROM bus.permissions;\n```\n\n| Agent | Can send to |\n|-------|-------------|\n| **Moses** | **Every queue** — all inboxes, workflow queues, health |\n| **Everyone else** | `inbox_orchestrator` (default), `inbox_moses` (point-to-point replies), own inbox, `workflow_step_result`, `inbox_health_check` |\n\n**If you need an agent to reply**, they send to `inbox_orchestrator` (or the originating orchestrator's queue, e.g. `inbox_moses`).\nThey cannot send to any other agent's inbox.\n\n### 5. Trace the reply path\n\nWhen the receiving agent replies, verify the path:\n\n```bash\n# The agent sends to inbox_orchestrator (or inbox_moses for point-to-point replies)\n# What URL do they use?\n#   - FLEET_BUS_URL (through nginx, port 13004)?\n#   - Direct localhost (port 8903)?\n# What auth?\n#   - Basic Auth for nginx?\n#   - Bearer token for localhost?\n```\n\n### 6. Account for the bus forwarder (if applicable)\n\nThe forwarder (`orch-bus-forwarder.py`, cron `orch-bus-forwarder-sync` every\n2m) mirrors messages between Moses' and Esther's Postgres instances —\nrole-aware PEER resolution since 2026-08-03 (Esther's peer = Moses :13004,\nMoses's peer = Esther :14004; `PEER_AUTH` = nginx Basic creds).\n\n- Without the forwarder, all messages live only in the local Postgres\n- Agents connecting to Esther's bus see only Esther-local messages\n- Cross-server message sync requires the forwarder to be running\n\n## Designing for N HETEROGENEOUS CODING AGENTS (the second axis)\n\nThe rest of this skill is about agents on the **bus**. This section is about\nagents consuming a **capability** — Pi, Hermes, Claude Code, Codex, whatever\nappears next. Standing constraint (Luke 2026-10-02): *\"fix things for\ninteroperability with different coding agents. always be thinking this.\"*\n\n**The rule: ONE implementation, per-host ADAPTERS.** A capability is implemented\nonce in a host-neutral contract; each host gets a thin adapter that converts its\ncalling convention and adds **no semantics**.\n\nThe failure this prevents is real and was shipped: `mem_context` existed in BOTH\nthe Hermes plugin and the MCP server, so whichever the runtime resolved, the\nother **silently did not exist**. An agent concluded \"memory is broken\", fell\nback to raw SQL, and reported the backend as the working path.\n\nRules, each of which is a bug that actually happened:\n\n1. **One implementation per capability.** Two implementations of one tool NAME\n   is worse than none — the runtime picks one silently and the other becomes a\n   phantom. Enforce with a test.\n2. **The contract may not import a harness.** If it needs one, either extract it\n   or declare it a **host-local extra** that names the reason (e.g. a tool that\n   needs the host's own LLM).\n3. **Schemas are DERIVED, never hand-written** — a hand-written schema list *is*\n   a second definition and drifts immediately.\n4. **Never substitute a fallback implementation on failure.** Fail-open is for\n   *availability* (\"carry on without memory\"), never for *semantics*. A fallback\n   is how the duplicate starts.\n5. **Fail loudly, never silently-empty.** An empty result that *looks* like \"no\n   data\" when the backend is down is worse than an error.\n6. **Verify the host's OWN API before writing its adapter** — never infer it from\n   a skill or a doc. Pi's first adapter failed TWICE, silently: the handler's\n   first parameter is the event (not a ctx), and prompt injection is the RETURN\n   VALUE (there is no ctx method). Both were masked by optional chaining.\n\n   Same rule when an adapter's session-uniqueness depends on env propagation:\n   a variable's presence on the host is NOT proof it reaches the consumer that\n   matters — inspect the propagation seam for the EXACT consumer, never a source\n   map or a documented merge. Two variants dead-end a resolver's env read: an\n   MCP `env` block that REPLACES the child environment (strips the harness's own\n   session id), and the subtler one — the merge is fine but the harness never\n   exports the id to its OWN process.env (Pi injects `PI_SESSION_ID` only into\n   bash-tool commands, so the governor's MCP child inherits nothing); verify on\n   the host which one you are facing. A static MCP `env` block cannot hold a\n   per-session value, so set the identity in the harness's lifecycle hook from\n   its own session manager (`ctx.sessionManager.getSessionId()`), which runs\n   BEFORE the consumer spawns and writes the env var the resolver reads\n   (measured: resolver answers \"per-repo, shared\" with no key and \"env,\n   unique\" once the key is set).\n\n   **The env-var NAME differs per harness — survey the exact name, never guess.**\n   Verified (2026-11-11) from each harness's own source: Claude Code injects\n   `CLAUDE_CODE_SESSION_ID` (note `CODE` in the middle — `CLAUDE_SESSION_ID` is\n   NOT set) into stdio MCP children since v2.1.154; Codex sets `CODEX_SESSION_ID`\n   but does NOT forward it to MCP children by default (shell commands only), so it\n   needs a `[mcp_servers..env]` pin or an upstream change. The resolver honours all\n   of them (`_ENV_SESSION_ID_SOURCES` in loop-gov-mcp.py), so a harness that reaches\n   the MCP child with its own id gets a unique session with no adapter — and a\n   a harness that does not silently shares the per-repo id (fail-closed since\n   2026-11-10). Per-harness session-id table (which env var, and whether it\n   reaches the MCP child): `references\u002Fharness-session-identity.md`.\n7. **Never let the model own a lifecycle guarantee.** Triggers (`turn_end`, stop\n   hooks, crons) belong to the host — \"remember to save\" is not a mechanism.\n8. **A registry, not per-host prose.** At N hosts the failure mode is N docs that\n   disagree; declare hosts in one file and GENERATE their docs from it.\n9. **Registering is not executing.** A deploy that COPIES a per-host adapter into the\n   scripts directory has wired NOTHING — wiring is a step that RUNS. Gate it on the\n   harness's PRESENCE (its agent dir or launcher), run every half of the adapter, and\n   report the outcome per half: a host without the harness is not a fault, while a host\n   that HAS it and comes out of a deploy unwired is. Pair the run with one line in that\n   host's doctor, so \"harness present but unwired\" is a reported state rather than a\n   silence nobody reads. An installer reaching a host is not evidence that it ever ran.\n\n### The GATE half of a capability\n\nA capability a host must satisfy is not only code the host RUNS — it is often also a gate\nthe host must PASS (a pre-commit check, an evidence record, a policy its commits are judged\nby). Design that gate for the host's REAL mechanism, or the host is refused forever while\nnothing anywhere reports a fault:\n\n- **A gate keyed on another host's tool NAME is unsatisfiable here.** Establish what the\n  host actually does by driving the host's own package — its exported tool factories and\n  the instruction its own system prompt emits. A name that is ordinary vocabulary in one\n  harness may appear NOWHERE in another's bundle; grep the bundle and treat zero matches as\n  the measurement it is.\n- **Record what the host actually did, under its true name**, and give the checker one\n  predicate per real mechanism. Never normalise a host's action into another host's verb:\n  the store is evidence, so a row asserting an action that never happened is worse than a\n  missing row.\n- **Ask the shared implementation for the identity the gate queries** rather than deriving a\n  second key from an env var or a state file — and resolve it for the timing case where the\n  host acts BEFORE the gate's context exists.\n- **A host refused for a reason it cannot observe looks broken to its operator.** When a\n  host reports \"I cannot do X\", check FIRST whether the gate demands a mechanism that host\n  does not have: the agent's behaviour is often correct and the gate is the defect.\n\nProcedure, predicates and the probe recipe:\n`enforcement-gate-migration > references\u002Fmulti-harness-evidence-writer.md`.\n\n### Choosing the implementation of a SHARED capability\n\nA capability both systems consume is a design decision before it is a build. Decide in this order,\nand let MEASUREMENT make the call:\n\n10. **Budget the LANGUAGE by measuring, not by preference.** Check the toolchains that actually\n    exist (`cargo --version`, `go version`, the interpreter) and what the systems you are serving\n    are written in. A capability that adds a THIRD language to a two-language fleet costs a\n    toolchain, a build path and a dependency surface on every host — and the \"lowest memory\" option\n    is worthless if its toolchain is not installed. Prefer the language of the system the capability\n    serves: a binary in that language is also the one its consumers can link in-process.\n11. **Keep the runtime dependency set inside what a constrained host already has.** A build that\n    needs a registry fetch, or a cache that shells out to a tool that may be absent, is unavailable\n    exactly when that host cannot repair it. Prefer dependencies resolvable from the local cache,\n    and where a component can be compiled IN rather than called OUT to (a bundled engine), compile\n    it in: one build-time cost beats an unavailability that renders as \"no data\".\n12. **Every external provider is OPTIONAL, and its absence is LOUD and NAMED.** An unconfigured\n    provider exits with its OWN status (never a generic failure) and names the variable that unlocks\n    it, so \"could not look\" cannot render as \"found nothing\". Say what still works without it — the\n    offline half of a capability is usually the durable half, and it must not depend on the\n    provider being reachable.\n13. **One dispatch, two surfaces.** Expose a CLI and an MCP stdio server over the SAME functions,\n    and generate both surfaces' metadata from ONE table, so no surface can describe an operation\n    differently or drift from the other. A daemon is a third surface nobody asked for: a process\n    that starts, does one thing and exits needs no port, no health check and no listener to secure.\n14. **Measure the envelope on a real host before quoting one.** A sizing table describes someone\n    else's machine; report the binary size and the STEADY-STATE footprint you measured, and when the\n    decision turns on a number the operator named, go and test THAT number instead of arguing from\n    the table.\n\nChecklist before shipping anything agent-facing:\n- [ ] works from **at least two different harnesses** (prove it, don't claim it)\n- [ ] any gate the host must PASS keys on something that host **has** — proven by driving\n      the host's own package, never inferred from a doc or from another harness's vocabulary\n- [ ] semantics in **one** place; adapters add none\n- [ ] metadata **derived**, not duplicated\n- [ ] unreachable dependency → **visible message**, never a silent empty\n- [ ] Linux **and macOS**\n- [ ] a **drift guard test**, not just a doc\n- [ ] the deploy **RUNS** the adapter where the harness is present, and the host doctor reports it\n\nReference: `docs\u002Fdesign\u002Fagent-interop.md`.\n\n### Migrating a host-bound capability so ALL hosts reach it — and rule changes load without a host restart\n\nA capability that lives only inside one harness's plugin (the enforcement gate, memory, context)\nhas **no access layer for other agents** — only that harness reaches it, and its code is frozen at\nthat host's startup, so a rule change forces a host restart (the \"deploy ≠ load\" trap). To expose\nit to N heterogeneous coding agents AND make a rule change live on the next call instead of a\nrestart, follow the order that was proven on the governance write-gate:\n\n1. **Extract the semantics into a host-neutral contract** under `ops\u002Fservices\u002F\u003Cname>\u002F\u003Cmodule>.py`\n   — stdlib-only, no harness import, loadable via `importlib.util.spec_from_file_location`.\n   Register it in the deploy map (`fleet-update.sh`) beside the established\n   `ops\u002Fservices\u002Fmycortex-mem\u002Fcontext_tools.py` contract. This is the ONE implementation both the\n   current host plugin and every adapter call.\n2. **Build the PARITY gate first, before integrating.** The migration arbiter is a test that loads\n   the ORIGINAL implementation from its real file (importlib) and asserts the contract returns the\n   identical verdict on a corpus spanning the whole surface — the allowlists, the write-class\n   rules, every sanctioned lane, and the evasions. \"Works as well as X\" is then a test, not a\n   promise. When a corpus expectation diverges from parity, the ORIGINAL is the spec: correct the\n   TEST, not the extraction — the divergence is normally a latent quirk of the original (below),\n   not a loss.\n3. **Reach the contract by subprocess on the decision path** — a fresh CLI invocation per call\n   (a `loop-gov.py`-style CLI over the one dispatch). A new process always loads the current file,\n   so a rule change takes effect on the next call with no host restart. This is the mechanism that\n   actually removes \"restart the gateway to load new enforcement rules\"; it is the same shape\n   pi's adapter already uses, and it is why no long-lived daemon is needed (rule 13).\n4. **Make every host a thin adapter** over the contract; a host with no matching interception hook\n   is declared in the harness registry (`ops\u002Finstall\u002Fharnesses\u002Fregistry.yaml`) WITH a reason, never\n   left silently ungated.\n\nPitfalls that cost a cycle here:\n- **An allowlist that anchors the head command couples the subcommand's position.** A rule\n  `systemctl (status|show|...)` matches only when the subcommand comes immediately after\n  `systemctl`; `systemctl --user show x` is therefore write-class in BOTH the original and the\n  contract. Preserve the limitation in the migration — parity is the goal, not improved\n  classification — and do not \"fix\" it as part of a faithful extraction.\n- **Corpus fixtures must not carry a `\u002Fhome\u002F`-prefixed literal path, even a generic one.** The PII\n  guard refuses the `write_file` on it. Use `~` verbatim or a `\u002Fvar`\u002F`\u002Fsrv`\u002F`\u002Ftmp` path when a\n  fixture needs a filesystem shape.\n- **An adapter that classifies locally still carries governance semantics.** \"The adapter delegates\n  the X decision\" and \"the adapter has no semantics of its own\" are different claims: a local\n  classifier (an allowlist, a decision rule) IS a governance semantic even when it forwards the\n  lock check to the shared impl. State precisely which decision is delegated and which is still\n  implemented locally, or a plan review (and the migration) will contradict itself.\n\n## Common Pitfalls\n\n### ❌ \"I sent a message to inbox_esther, why didn't she respond?\"\n\nCheck, in order:\n1. Does Esther connect to the same Postgres instance? (She uses `FLEET_BUS_URL`)\n2. Does she have a bus-processor cron? (`fleet-bus-*` jobs in her cron list)\n3. Does her ACL allow reading `inbox_esther`? (Yes — every agent reads their own)\n4. Was the message consumed by `agent-worker` without being archived? (Competing consumer)\n\n### ❌ \"The message was consumed but no response came back — and the queue is empty\"\n\nThis is the trickiest failure: no evidence left behind. The handler consumed the message, archived it, and exited cleanly — but `send_bus_result` never delivered the reply.\n\n**Diagnostic chain:**\n\n1. **Check `archived_by`** — `bus.archive(queue, msg_id, agent_name)` stores the archiver. Query recent archives to confirm the expected agent consumed it, not a forwarder or admin cleanup:\n   ```bash\n   sg docker -c \"docker exec mycortex-postgres psql -U mycortex -d mycortex -t\" \u003C\u003C 'EOF'\n   SELECT queue_name, body->>'subject' as subject,\n          archived_at::timestamptz(0), archived_by\n   FROM bus.archives\n   WHERE archived_at > now() - interval '30 minutes'\n   ORDER BY archived_at DESC;\n   EOF\n   ```\n   If `archived_by` matches the target agent → handler ran, reply path is broken.\n   If `archived_by` is `moses` or `pre-cleanup` → something else ate it.\n\n2. **Check handler state file** — The handler logs processed correlation_ids:\n   ```bash\n   cat ~\u002F.steadfaste-fleet\u002Fstate\u002Fagent-message-state.json\n   ```\n   If your correlation_id is in `processed_ids` → handler ran. The gap is in `send_bus_result`.\n\n3. **Test `bus_send` independently** — If the handler ran but no reply came, test whether the agent's `bus_send` works:\n   ```bash\n   python3 -c \"\n   import sys; sys.path.insert(0, '$HOME\u002Fsteadfaste-fleet\u002Fops\u002Fscripts')\n   from lib.fleet_bus import bus_send\n   r = bus_send('inbox_orchestrator', {'from':'test','subject':'TEST','body':{},\n                                'correlation_id':'diag'})\n   print(f'Send: {r}')\n   \"\n   ```\n   Returns `{'msg_id': '...'}` → send works interactively. The cron environment differs.\n   Returns `None` → bus_send is broken. Check config, auth, and URL.\n\n4. **AGENT_NAME misconfiguration** — The handler polls `inbox_{AGENT_NAME}`. If AGENT_NAME falls back to hostname (older code) instead of being set in `.env`, the handler polled `inbox_cisnet03` while you sent to `inbox_gisu`. Check the agent's `.env` has `AGENT_NAME=\u003Cname>`.\n\n5. **Known silent-failure gap** — `send_bus_result()` catches all exceptions internally and returns `False` without propagating. The crash guard's except block is never triggered. The handler logs \"Failed to send\" to stdout (which the cron runner captures) but returns `True` (all done). The message is archived with no result sent. Being actively fixed.\n\n### ❌ \"The message vanished — consumed but I never asked for it\"\n\n### ❌ \"The MCP tool works on my machine but not on the remote agent\"\n\nYour machine (Moses) has a Bearer token for direct localhost access. Remote\nagents only have Basic Auth through nginx. The MCP tool resolves auth from\n`.env` — verify the remote agent's config matches their actual\nauth mode.\n\n### ❌ \"I designed a protocol where Agent X sends to Agent Y directly\"\n\nOnly Moses can send to arbitrary inboxes. All other agents can only send to\n`inbox_moses`. If your protocol requires Esther → Gisu direct messaging,\nit won't work at the ACL level. Route through Moses as an intermediary.\n\n### ❌ \"I created a new fleet-wide cron without checking what already runs\"\n\nBefore creating any `agent-*` or `local-*` cron, run `cronjob(action='list')`\nand `search_files()` with 3+ terms for the script purpose. The\n`scoring-activity-watchdog` already existed when `local-cron-cost-report` and\n`local-trace-quality-watchdog` were created — extending the watchdog was the\ncorrect call. Creating new parallel crons fragments the system and creates\nduplicate maintenance burden. See `session-start-discipline > references\u002Fsurvey-before-creating.md`.\n\n### ❌ \"bus_mode defines how agents communicate\"\n\nThe field was renamed to `bus_access` (values `host`\u002F`client`) because\n`bus_mode` sounded like a configuration instruction to install a bus daemon.\n`bus_access` describes capability: does this agent run the bus server (`host`)\nor connect to a shared one (`client`)? All agents use `client` except\norchestrators (Moses, Esther) who use `host`.\n\n## Reference\n\n- `fleet-bus` skill — bus operations, DLQ management, recovery\n- `fleet-preflight` skill — general pre-flight checks (manually authored)\n- `docs\u002Freference\u002Ffleet-bus-config.md` — detailed config and auth resolution\n- `docs\u002Forch-bus-setup.md` — full setup guide with architecture overview\n- `agent-message-handler.py` — fleet-wide no_agent consumer (every 5 min)\n\n## Deployment Pattern: Fleet-Wide Features\n\nWhen a new cross-agent feature needs every agent to support it:\n\n1. **Add handler to `agent-message-handler.py`** — add a new `subject` case\n   (e.g. `subject == \"EXEC\"`) to the existing dispatch chain. This is the\n   only consumer that exists on every agent in the fleet.\n2. **Register** new or updated files in `fleet-update.sh`\n3. **Deploy** via `fleet-update.sh` on each agent\n4. **~5 min response time** (handler polls every 5 min)\n5. **No LLM cost** (no_agent script — subprocess only)\n\n### Example: EXEC Command (added 2026-07-21)\n\n```\nMoses: fleet exec esther fleet-doctor.py --json\n  → sends EXEC to inbox_esther\n  → handler picks up within 5 min\n  → runs ~\u002F.steadfaste-fleet\u002Fscripts\u002Ffleet-doctor.py --json\n  → sends EXEC_RESULT back to inbox_moses\n  → fleet exec polls and displays result\n```\n\nMessage schema:\n- `subject: EXEC` — body: `{ command: str, params: list, timeout: int }`\n- `reply: EXEC_RESULT` — body: `{ success: bool, stdout, stderr, exit_code }`\n\n### Repo-Wide Search for Config\u002FVariable Changes\n\nWhen fixing a port number, URL, env var name, or file path — **do not fix\njust the file you're editing**. Search the entire repo first:\n\n```bash\ngrep -rn \"\u003Cold-value>\" ~\u002Fsteadfaste-fleet \\\n  --include=\"*.py\" --include=\"*.md\" --include=\"*.sh\" \\\n  --include=\"*.yaml\" --include=\"*.conf\" \\\n  2>\u002Fdev\u002Fnull | grep -v \".git\u002F\" | grep -v \"__pycache__\"\n```\n\n**Why:** The 8905→8903 bus port fix found 4 stale files across 3 directories\n(workflow YAML, server.py default, MCP docstring, architecture doc) that a\nsingle-file fix would have missed. Workflow YAMLs, code docstrings, and\nhistorical plan documents are the most common hiding places.\n\n### Test Like an Agent Would\n\nAfter making changes, verify through the correct path:\n\n| Path | What it proves | When to use |\n|------|---------------|-------------|\n| `fleet send` (docker exec SQL) | SQL function works | Local dev only — not representative |\n| `curl 127.0.0.1:8903 + Bearer` | MCP tools path works | Testing Moses\u002FEsther MCP |\n| `curl domain:13004 + Basic` | **External agent path works** | Testing remote agent connectivity |\n| `agent-message-handler.py --once` | Consumer picks it up | Testing handler dispatch |\n\nThe external path (nginx :13004 + Basic auth) is the only one that proves\na remote agent can send\u002Freceive. Always test through the path the\nreceiving agent would use.\n",{"name":5,"author":24,"version":25,"category":26,"description":7,"related_skills":27,"created_from_session":33},"Steadfaste Fleet","1.0.0","devops",[28,29,30,31,32],"survey-before-action","fleet-preflight","fleet-bus","agent-contract","session-start-discipline","fleet-bus-architecture-survey","main","9dc0e92c5fa81d4db5292b205716e8ea0c00d10e","skills\u002Fdevops\u002Fcross-agent-design",1,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet","steadfaste.com","https:\u002F\u002Fgithub.com\u002Flukemcqueen","AI Architect | Building Hermes Cortex: governed multi-agent AI for autonomous software engineering | Enterprise Tech Consultant","2026-11-14 22:33:34",{"source":8,"skillName":5,"commands":44,"prompt":54,"zipAvailable":55},[45,48,51],{"tool":46,"command":47},"npx","npx skills add lukemcqueen\u002Fsteadfaste-fleet --skill cross-agent-design",{"tool":49,"command":50},"bunx","bunx skills add lukemcqueen\u002Fsteadfaste-fleet --skill cross-agent-design",{"tool":52,"command":53},"pnpm","pnpm dlx skills add lukemcqueen\u002Fsteadfaste-fleet --skill cross-agent-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fcross-agent-design\u002FSKILL.md",true,[57,63],{"path":58,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Ffleet-bus-architecture.md","REFERENCE","参考文档",2826,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fcross-agent-design\u002Freferences\u002Ffleet-bus-architecture.md",{"path":64,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Fharness-session-identity.md",3765,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fcross-agent-design\u002Freferences\u002Fharness-session-identity.md",[68,76,83,90,97,104],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":75},"01M7DXY4G8NSVB59K8B6S2AQNP","macbook-linux-maintenance","Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fmacbook-linux-maintenance\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":75},"01M7DXXYJCXFJ3TGB84ZQ8KFE6","governance-regression-triage","Triage a host's governance issues: what changed.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fgovernance-regression-triage\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":75},"01M7DXXSAP1G8FDRJAMXQGBBMK","enforcement-immutability","Use when enforcement files lose their immutable flag.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fenforcement-immutability\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":75},"01M78SSDQVRYX64Y16X32TC0NS","steadfaste-fleet-repo-deploy","Use when committing to the steadfaste-fleet repo.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-repo-deploy\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":75},"01M78SS928F3R2RJAYVW4E30CE","steadfaste-fleet-maintenance","Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-maintenance\u002FSKILL.md",[],[],{"skillNo":105,"name":29,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":75},"01M78SP1CHW0T0BWE5ZT6JBPX8","DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its \"Repo-Specific Pre-Flight\" section covers git search, Hermes boundary, and deployment verification.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Ffleet-preflight\u002FSKILL.md",[],[]]