- comms: bind comms-send.sh to the SELECTED repository via
FLEET_COMMS_REPO in the spawned env; without it, --comms-repo chose
the executable but the tool still operated on the default checkout
(codex on 9c8b6ebf). Spec asserts the stub observes the binding.
- q: Object.hasOwn subcommand lookup (reserved property names like
toString must not leak through the record); spec arm added.
- watch: .helpOption(false) — the tool owns help too; --help now passes
through to agent-watch.sh instead of commander's wrapper help
(verified against dist).
Per FLEET-COMMS.md doctrine (Jason 2026-08-28): same-host seats talk over
tmux agent-send.sh; fleet-comms only when the recipient is on another
site. The command owns routing + flag translation between the two
transports (agent-send -s/-C/-L/-f/-m vs comms-send -t site/agent -c/-m);
validation, delivery semantics, and exit codes belong to the tools.
- rc=2 draft contract documented in help: never retry, confirm with
capture-pane. Exit codes pass through both paths.
- --site requires MOSAIC_AGENT_NAME (exit 2 invocation defect when
missing); missing fleet-comms checkout exits 127 naming the path.
- Specs (routing + translation + passthrough with stub tools) green.
Architecture (fleet CLI integration, Jason ruling 2026-08-28): the
package embeds the command surface; operator-owned implementations stay
in the brain (tools/agent-watch). The command resolves the brain home
via resolveBrainHome (MOSAIC_BRAIN_HOME wins, canonical ~/.mosaic
adoption otherwise) and execs the tool there.
- Pass-through contract: allowUnknownOption + variadic args capture the
full ordered argument list (commander 13 measured behavior; no
passThroughOptions, which would force enablePositionalOptions on the
root program fleet-wide). Args, stdout/stderr, and the exit code
belong to the tool.
- Absent tool: exit 127 naming the resolved path (no guessing).
- Signal death / null spawn status: exit 125.
- Spec (6/6 green): brain-home precedence, exit mapping, absent-tool
path. Live smoke verified through the fleet launcher: mosaic watch list
returns real watcher state with exit-code passthrough.
Pre-existing local vitest failures in fleet-agent-crud/fleet-regen/
compose-contract specs measured identical on a clean origin/next stash;
not caused by this change (PR #1462 CI was terminal-green).
Codex review of a27b7dc9 (blocker): check-test-enumeration.sh rejects
unenumerated test files.
- test-issue-comment-usage-contract.sh enrolled in test:framework-shell
(hermetic by construction: PATH stubs, sandboxed runner, no network).
- test-issue-comment-readback.sh enrolled and its stale exclusion removed.
The exclusion's own note anticipated this: 'joins CI after the
wrapper-half hermeticity fix' - that fix (neutralizing seat-exported
MOSAIC_GIT_IDENTITY / MOSAIC_BRAIN_HOME that escape the sandboxed HOME)
landed in a27b7dc9. Suite green in brain and worktree trees tonight.
Enumeration guard: OK (population 73, enumerated 60, excluded 14).
Upstream of brain commits 08a00149 + 971586ef + the arm-6 sandbox fix
(brain 5th commit of 2026-08-28 series):
- R1: -b/--body is the canonical comment flag (matches issue-create,
issue-edit, pr-create, pr-edit); -c/--comment stays a compatible alias.
- R4: usage errors print to stderr and exit 2, distinct from provider,
credential, and verification failures (exit 1). Value-less flags fail
loudly (previously -c with no value died silently at rc=1 via set -e on
the failed shift 2). gh failures on the GitHub path normalize to exit 1
(gh's own usage errors exit 2 and would collide with the reserved code).
- Tests: new usage-contract suite (help rc, unknown/missing/value-less rc=2
on stderr, alias parse acceptance under a sandboxed runner, GitHub-path
exit normalization with a stubbed gh, zero provider contact on parser
failure); readback suite gains case 11 (full verified write via -b) and
neutralizes seat-exported MOSAIC_GIT_IDENTITY / MOSAIC_BRAIN_HOME that
escape the sandboxed HOME (documented HTTP 401 / fail-loud shapes).
Driver: a fleet seat full-stopped on an issue-comment usage error because
usage failures were indistinguishable from provider failures and the stop
gate treated every wrapper failure as blocking.
marcie