Pokes one settled Herdr session when gateway/agent has pending stream events.
Appends due aggregate.deadline.reached events from agent-authored holdUntil values.
Refreshes a Redis heartbeat only after Herdr proves the pane and session exist and the latest poke settled before its deadline.
Retires a healthy idle session past wall-clock age (default 4h) or on repeated-token collapse, writes an advisory gateway.handoff, stops the agent in-place, and relaunches the successor in the same pane.
Requests a successor spawn when the session disappears. Empty labeled panes relaunch in place; it retries if no successor appears within the configured deadline.

It never chooses delivery, routing, grouping, suppression, or escalation. Recent terminal text is scanned only for degeneration detection.

Run

GATEWAY_AGENT_TARGET='<herdr pane id or unique agent name>' \
GATEWAY_HERDR_SESSION='system' \
GATEWAY_SUCCESSOR_BRIEF_PATH='<absolute gateway boot brief>' \
pnpm --filter @joelclaw/agent-comms-driver start

Optional settings:

GATEWAY_HERDR_SESSION defaults to system. Human work stays in Herdr's default session.
GATEWAY_HEARTBEAT_KEY defaults to gateway:agent:heartbeat.
GATEWAY_HEARTBEAT_REFRESH_MS defaults to 15000.
GATEWAY_HEARTBEAT_TTL_MS defaults to 60000.
GATEWAY_POKE_DEADLINE_MS defaults to 240000, matching the four-minute turn contract. A timed-out Herdr prompt is interrupted before the next pass.
GATEWAY_SUCCESSOR_DEADLINE_MS defaults to 120000.
GATEWAY_MAX_SESSION_AGE_MS defaults to 14400000 (4h). Set 0 to disable age retire.
GATEWAY_DRIVER_RECEIPT_PATH defaults to /tmp/joelclaw/agent-comms-driver.jsonl.

Tests and scratch proofs must set a test:* heartbeat key. Never run a proof against the production gateway target.

Morning digest beat

The daily digest beat is ready but unarmed. Steering arms it with:

pnpm --filter @joelclaw/agent-comms-driver arm-morning-digest

The command schedules one WAKE for the next 07:30 in America/Los_Angeles. joelclaw wake emits pane/schedule.requested. The pane/schedule function sends pane.schedule.due through pushGatewayEvent to joelclaw:events:gateway. Its source is inngest/pane-schedule, and it never starts a beat lane. The arm path returns an existing future [gateway-morning-digest] schedule instead of adding a duplicate, and verifies a new scheduleId by registry readback.

After a digest due signal succeeds, the gateway runs the same arm command to prove the next beat exists. It then cancels the current due schedule so the reconciler cannot fire it again.

Kill drill

The live drill is destructive. It closes the configured gateway pane and sends a real Telegram DM. Run it only during the supervised cutover sitting:

GATEWAY_AGENT_TARGET='<gateway pane id or unique agent name>' \
GATEWAY_HERDR_SESSION='system' \
GATEWAY_SUCCESSOR_BRIEF_PATH='<absolute gateway boot brief>' \
pnpm --filter @joelclaw/agent-comms-driver kill-drill

The script waits for the 60 s heartbeat TTL, runs all eight fallback-contract assertions, and exits non-zero if any stream or receipt evidence is missing. Receipts default to /tmp/joelclaw/agent-comms-kill-drill.jsonl.

The weekly drill is ready but unarmed. Arm its first run only after the supervised live drill passes:

pnpm --filter @joelclaw/agent-comms-driver arm-weekly-drill

The arm command schedules .brain/tasks/agent-comms-gateway-weekly-kill-drill.svx through joelclaw wake, then verifies the scheduleId by registry readback. A passing weekly task arms its successor seven days later. A failed drill does not re-arm itself.