fix(watch): fail loudly on shifted args instead of running with zero subscriptions

[Masashi-Ono0611]

Related to #475 (and the launch path introduced in #236, refined by #245).

Problem

A grok-build monitor watcher launched from the rule template can run with zero subscriptions, silently. The template bakes watch.sh "$GROK_SESSION_ID" '<project>' grok-build into the command line; grok's monitor tool re-evaluates that line in a shell where GROK_SESSION_ID is unset, and the quoted-but-empty expansion is dropped as a word — every later argument shifts one slot left. watch.sh then parses the project path as the session id, the type as the project, and the agent name as the type; identities.sh resolves no pairs, and the watcher polls forever delivering nothing. Observed in production (macOS zsh, v1.1.10-1-g5f8d0b7); full evidence in #475.

The existing empty-first-arg tolerance (#236) assumes the empty argument stays positionally present. It does not survive a caller shell that deletes the word entirely.

Fix (two minimal layers)

1. Caller side — the grok-build templates (_delivery.sh monitor rule, template.md x3) now pass "${GROK_SESSION_ID:--}". When unset, this yields the literal sentinel -, which survives re-evaluation as a real argument. watch.sh folds - into the existing empty-arg resolution path, so feat(grok-build): add opt-in explicit-launch monitor delivery #236 behavior (self-generated fallback id) is preserved bit-for-bit.
2. watch.sh defense — validate AGENT_TYPE against the registered types (discovered dynamically, no hardcoded list) and fail loudly when it is unknown, with a message that names the shifted-args cause and the sentinel remedy. Follows the Windows/Git Bash: native sqlite3.exe can't open MSYS /c/ DB path (inbox/send/watch fail) + 4 related findings #197 healthcheck pattern: one line on stdout (the monitor event stream), then exit 1. This guards every caller, not just grok. Cost design: a built-in type is confirmed by a single type.conf stat (watch.sh launches are a hot path — actas/drop/SessionStart relaunch it routinely); only a non-builtin name loads the type registry (agmsg_type_dir, so trusted external plugin types still validate), and the full type enumeration runs only inside the error message. An earlier draft used agmsg_is_known_type unconditionally and measurably tightened the 1s timing window of the excludes pairs held by another live session test; the stat fast path restored it to green 8/8.

Auto-detecting the shift (path-looking $1 + known-type $2) and re-shifting was considered and rejected: it stacks guessing on an already subtle launch path, and a loud error already surfaces the bug immediately with a precise remedy.

Tests

Review follow-ups folded in (multi-model review, 2 rounds): a shifted three-argument launch (no active_name) leaves only two args and the old ${3:?} guard died on stderr — invisible to a stdout-consuming monitor tool — so required-arg validation now fails explicitly on stdout; and a path-like value in the type slot (../types/claude-code) is rejected outright instead of reaching the registry where path concatenation could resolve it.

tests/test_watch.bats:

• shifted arguments (agent name in the type slot) exit non-zero with the unknown-agent-type error and never arm a pidfile;
• shifted three-arg launch (missing agent_type) fails loudly on stdout;
• path-like agent type is rejected outright;
• sentinel - resolves exactly like an empty session id (fallback agmsg-* pidfile appears, no --keyed run files, no error).

tests/test_delivery.bats:

• the grok monitor rule bakes watch.sh "${GROK_SESSION_ID:--}" (regression guard for the caller-side layer).

Ran locally: the two new watch tests and all 7 grok-build delivery tests pass; pre-existing environment-specific failures in test_watch.bats (1, 2, 3, 5 — watcher-delivery timing under a live agent ancestor) fail identically on a clean upstream/main checkout with this branch's changes stashed, i.e. unrelated to this change.

🤖 Generated with Claude Code