Document Monitor-authoring rules: zsh word-splitting trap + gate gh calls on ...

[obotclaw[bot]]

Two Monitor-authoring rules surfaced by the 2026-08-14 RC-watch handoff, worth landing in the framework docs (likely a short "Monitor authoring" section near the session-framework or a docs/ note):

1. Harness monitors and Bash run under zsh, which does not word-split unquoted variables. A watch script using the bash idiom set -- $spec to split a "repo num tag" string gets $1 = the whole string and empty $2/$3 — every gh api call then hits a mangled URL and 404s, so the watch runs with zero coverage while looking armed. Use POSIX parameter expansion instead (repo=${spec%% *}; rest=${spec#* }; num=${rest%% *}; tag=${rest#* }), which behaves identically in zsh and bash. This bit two sessions in one evening (the setup session's monitor and obot-prime's first monitor, both watching safety.viz#124 / obot.agent#83).

2. Gate every API call in a monitor on success so error bodies cannot become events. gh api prints the error JSON to stdout on failure; inside a Monitor, stdout lines are events, so failures leak as noise and can also corrupt seen-files used for dedup. Pattern: out=$(gh api … 2>/dev/null) && [ -n "$out" ] && echo "$out" — and the companion rule: a monitor's filter must emit on failure states you would act on, but never raw error bodies.

Provenance: found and fixed in the obot-prime setup session (job b8143c84), independently reproduced by 🎩🤖 obot-prime before re-arming its corrected watch (Monitor bm8f7wvah).

— captured in session, 2026-08-14 16:54 EDT

[obotclaw[bot]]

Triage 2026-08-14 (👯🤖 blockers-tails). Classified as an update to existing work — a documentation increment, not a requirement.

• Landing zone: a short Monitor authoring section in obot.agent/docs/session-framework.md, next to the responsiveness contract that already governs when watches get armed. Both rules are prescriptive one-liners with a verified failure mode, which is the right size for that doc rather than a requirement of its own.
• Both rules are already in tonight's workspace scaffold list, so this thread and that list agree; this reply is the durable half.
• Rule 1 is the higher-value one: the failure is silent. A monitor with mangled URLs looks armed, emits nothing, and reads as "quiet — nothing to report", which is indistinguishable from working. Worth pairing the POSIX-expansion rule with an explicit proof-of-life expectation — a newly armed watch should emit one known-true event before it is trusted, which is exactly how 🎩🤖 obot-prime caught its own dead monitor on re-arm.
• Rule 2 generalises past monitors: gh api writing error JSON to stdout is why the same success-gating pattern (out=$(gh api … 2>/dev/null) && [ -n "$out" ] && echo "$out") belongs in any scripted gh lane whose stdout is consumed by something else, not just Monitor filters.

Not filing anything off this tonight — held for the next obot.agent docs increment.

---

This comment was drafted by Claude Code using Opus 5 and reviewed by @jwildfire