bus
Read or post to the coordination bus (append-only TSV message log).
SKILL.mdskills/bus/SKILL.md
GitHubContext Gathering
0. Emit SKILL_INVOKE
Post SKILL_INVOKE to the bus before any stateful action.
Type: SKILL_INVOKE
To: all
Message: host=agent-node surface=<observed-surface> lane=<lane> [skill=bus] [mode=side_effecting] [args_hash=<sha256>] [session=<session_id>]
(Use the caller's bare canonical identity as from; for Codex, use codex.
On agent-node, send the receipt with bus-post.ps1 as shown below. Replace metadata
placeholders with observed values; use unknown for an unevidenced surface.)
Before executing this skill, gather the following context:
On Windows (PowerShell):
- Run
python $HOME\bin\bus-global.py status(if error → "global bus status unavailable") - Run
python $HOME\bin\bus-global.py tail 5(if error → "global bus not readable")
On Unix (bash/zsh):
- Run
python ~/bin/bus-global.py status 2>/dev/null || echo "(global bus status unavailable)" - Run
python ~/bin/bus-global.py tail 5 2>/dev/null || echo "(global bus not readable)"
Bus Command
When to Use
Checking what agents have been doing
Posting coordination messages
Debugging agent communication issues
Monitoring multi-agent workflow progress
Searching for specific events or decisions The canonical coordination bus is hosted on
hummbl-vpsand exposed athttps://bus.hummbl-dev.com. Use the canonical client to read it:On agent-node:
python $HOME\bin\bus-global.py tail 20.Local read cache:
~/.cache/bus/messages.tsv(or%USERPROFILE%\.cache\bus\messages.tsvon Windows). A cache is never the bus authority or a direct write target.The founder-mode TSV is retired [RETIRED: 2026-09 remote-bus migration]. Never use it as authority or append to it.
CACHED_MIRRORoutput is cached evidence; preserve that label and its freshness information when reporting activity.
Usage
[bus] # Default: show global bus status
[bus] tail 20 # Show last 20 global bus entries
[bus] search "PATTERN" # Search global bus entries by pattern
[bus] post "MESSAGE" # Post to the global bus (default: caller -> all SITREP)
[bus] post "MESSAGE" TYPE # Post with an allowed type (STATUS, BLOCKED, REVIEW, etc.)
[bus] status # Report client bridge/cache status and freshness
Concrete commands on agent-node:
PowerShell (recommended on Windows):
# Use $HOME instead of ~ in PowerShell
python $HOME\bin\bus-global.py status
python $HOME\bin\bus-global.py tail 20
python $HOME\bin\bus-global.py search "SITREP" # bridge first; labeled cache fallback
# Inspect recent posts; preserve any CACHED_MIRROR warning in the result:
python $HOME\bin\bus-global.py tail 20 | Select-String -Pattern "^# CACHED_MIRROR|SITREP" -CaseSensitive:$false
# For regex/alternation (search is substring-only, not regex):
python $HOME\bin\bus-global.py tail 100 | Select-String -Pattern "^# CACHED_MIRROR|doc-cleanup|PR #738"
Git Bash / WSL (if preferred):
python ~/bin/bus-global.py status
python ~/bin/bus-global.py tail 20
python ~/bin/bus-global.py search "SITREP"
python ~/bin/bus-global.py tail 20 | grep -iE "^# CACHED_MIRROR|SITREP"
python ~/bin/bus-global.py tail 100 | grep -iE "^# CACHED_MIRROR|doc-cleanup|PR #738"
To post a SITREP to the bus:
Type: SITREP
To: all
Message: host=agent-node surface=<observed-surface> lane=<lane> Task complete. Ready for review.
(Send with the caller's bare canonical identity through the host's approved writer.)
Bus Format
The bus is a TSV file with these columns:
timestamp_utc from to type message
Rules (from CAES spec)
- UTC timestamps only:
- Unix:
date -u '+%Y-%m-%dT%H:%M:%SZ' - Windows PowerShell:
(Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
- Unix:
- Append-only -- NEVER edit or delete historical entries
- Z suffix -- use
Znot+0000for UTC indicator
Valid Types
The canonical client accepts SKILL_INVOKE and the operational message types
reported by python ~/bin/bus-global.py permissions (on Windows,
python $HOME\bin\bus-global.py permissions). DECISION and DIRECTIVE
require authenticated operator principal proof; the current client rejects
these types because it does not accept that proof. Use agent-authored
STATUS or REVIEW for findings, retaining the provenance of any operator
instruction. A bus type check does not replace the sender's actual scope or
credential restrictions.
Posting
On agent-node, use the Windows Credential Manager-backed wrapper. It requires four positional arguments: sender, recipient, type, and message.
& "$HOME\bin\bus-post.ps1" codex all SITREP "host=agent-node surface=<observed-surface> lane=<lane> Task complete. Ready for review."
For an invocation receipt:
& "$HOME\bin\bus-post.ps1" codex all SKILL_INVOKE "host=agent-node surface=<observed-surface> lane=<lane> [skill=bus] [mode=side_effecting] [args_hash=<sha256>] [session=<session_id>]"
- These examples are for Codex on agent-node. Other callers use their own canonical sender and observed host/surface; never infer identity from a model or executable.
- Skill shorthand defaults to
to=all,type=SITREP; the concrete wrapper requires both arguments explicitly. - The wrapper loads the bridge credential from Windows Credential Manager and invokes
bus-global.py post. Never put credentials in a message or command-line argument. - The client delivers through the configured bridge, with an existing SSH fallback for retryable bridge failures. Local cache refresh is not a local bus write.
- Never append directly to any mirror/cache or the retired founder-mode TSV [RETIRED: 2026-09 remote-bus migration].
- Read the delivery result: an exit code of 0 alone does not distinguish canonical delivery from local queue preservation.
Offline ordering for invocation receipts
SKILL_INVOKE is an allowed offline-queue type. For a retryable bridge
failure with no successful SSH delivery, or an active offline marker, the
client can preserve the intended type and message in the local queue for
ordered delayed replay. Authentication or other non-retryable failures are
not proof of a queued receipt.
When the assigned scope calls for preserving an offline invocation receipt,
the existing --queue option deliberately queues without a delivery attempt.
This is a queue-only client operation, not an alternative live writer:
python "$HOME\bin\bus-global.py" post codex all SKILL_INVOKE "host=agent-node surface=<observed-surface> lane=<lane> [skill=bus] [mode=side_effecting] [args_hash=<sha256>] [session=<session_id>]" --queue
A successful queue operation includes OFFLINE-QUEUED or
OFFLINE-QUEUED-DUPLICATE in its output. Automatic fallback can prefix that
receipt with POSTED; it still records local intent, not canonical delivery.
Report the queue receipt as pending until canonical delivery/replay is
evidenced. Never queue privileged DECISION or DIRECTIVE messages.
PROPOSAL posts — proposal_id generation
PROPOSAL messages should include a [proposal_id=<8-hex>] field for
threading. Use an existing proposal ID when following that proposal. The
client generates an ID when omitted, but currently prepends it ahead of the
message; provide the field after host=agent-node to preserve the required prefix.
& "$HOME\bin\bus-post.ps1" codex all PROPOSAL "host=agent-node surface=<observed-surface> lane=<lane> [proposal_id=<8-hex>] <proposal>"
Replace <8-hex> with the actual proposal ID; do not post placeholders.
For a new proposal, an available host-approved ID helper may supply the value.
Reading
On Windows (PowerShell), read through the canonical client:
python "$HOME\bin\bus-global.py" tail 20
On Unix (bash/zsh) with the approved client installed:
python ~/bin/bus-global.py tail N
The client tries the canonical bridge first. If it falls back to a local
cache, report its CACHED_MIRROR label and freshness rather than claiming
current live activity. status may refresh the cache; read operations do
not append messages to the canonical bus.
Concurrent Work Check
After scanning HANDOFFs for open items, check for active sessions that may be working on the same items before acting:
Check for active devin processes:
ps -eo pid,etime,cmd | grep "[d]evin"Long-running processes (etime > 10min) may indicate active sessions.
Check for unmatched SKILL_INVOKE [start-session]:
python ~/bin/bus-global.py tail 20 | grep -E "^# CACHED_MIRROR|SKILL_INVOKE.*start-session" python ~/bin/bus-global.py tail 20 | grep -E "^# CACHED_MIRROR|SKILL_INVOKE.*end-session"If there are start-session entries without matching end-session entries, those sessions may still be active.
Check for WIP_START or lane claims:
python ~/bin/bus-global.py tail 20 | grep -E "^# CACHED_MIRROR|WIP_START|lane="If another session has claimed a lane or started work on an item, do not start the same work. Coordinate via bus PROPOSAL/ACK instead.
Origin: 2026-09-02 AAR — sessions started work on items concurrent sessions were already completing because the bus scan protocol did not include a concurrent work check.
Constraint Verification Before Operator-Level Label
Before labeling an item as requiring operator action, identify the actual
constraint: the current assignment, applicable policy, effective credentials,
or a concrete service/repository restriction. Available credentials establish
technical capability, not permission for new work. Conversely, do not invent
an extra approval requirement for work already authorized by the operator.
Name the specific unmet constraint and supporting evidence when escalating.
Do not require a new bus DECISION merely to recognize an existing operator
instruction; authority and the receipt of that authority are distinct.
Status Check
For [bus] status, report the fields actually returned by the client:
canonical_live, configuredbridge_url, andhub_hostwhen present- Available hub count/write time and cache path/count/write time
- Any
CACHED_MIRROR, offline-marker, or unavailable-hub information - Last entry only when returned or separately read; do not invent missing fields
Do not claim whole-bus timestamp or TSV validation from a status response or a limited tail sample.
Constraints
- NEVER edit or delete existing bus entries.
- NEVER post empty or test messages to the bus.
- Always use UTC
Zsuffix timestamps. - Canonical authority:
https://bus.hummbl-dev.com, hosted onhummbl-vps. - Read-only cache on agent-node:
~/.cache/bus/messages.tsv(or%USERPROFILE%\.cache\bus\messages.tsvon Windows). - Use
$HOME\bin\bus-post.ps1for live posts from agent-node; the documentedbus-global.py post ... --queueexception only preserves local offline intent. - Keep
from=codexbare for Codex; start Workstation message bodies withhost=agent-node, then the observed surface and lane. - The founder-mode TSV [RETIRED: 2026-09 remote-bus migration] must never be a write target or bus authority.
- Never append to the global mirror file with raw echo/printf or direct local file writes.
Skill Chains
- For bridge posts delegation receipts to the coordination bus ->
[cross-runtime-bridge](sessions)
Mandatory
- No additional skill chain is required for ordinary bus coordination within the caller's assigned scope. Use the approved writer and respect actual sender/type/credential constraints; append-only storage does not grant authority.
Advisory
- After post: Inspect the receipt and distinguish canonical delivery from queued intent.
- Read operations:
tail,search,statusdo not append bus messages; the client may refresh its local cache. No chains needed. - For fleet coordination:
[fleet-status],[sitrep],[agent-roster]
Authority
- The operator is the sole owner and final binding authority. Follow the current owner-authorized scope and the canonical roster/operating model.
- Trust labels do not bypass sender admission, recipient/type restrictions, credentials, data boundaries, or the scope of an assignment.
- Client
permissionsoutput describes message-type handling, not a grant of authority or a live credential/bridge check. The current client rejectsDECISION/DIRECTIVEas requiring operator principal proof it cannot accept. - Preserve operator instructions as operator-authored evidence; do not impersonate the operator or treat an agent receipt as a new delegation.