mosaic CLI: embedded brain-tool dispatch layer (watch, q, comms) #1463

2026-08-28T22:46:30Z

marcie commented

2026-08-28 22:46:30 +00:00

First three commands of the fleet CLI integration (Jason ruling 2026-08-28): the package embeds the command surface; operator-owned implementations stay in the brain (~/.mosaic/tools), discovered via brain-home resolution (MOSAIC_BRAIN_HOME wins).

brain-dispatch.ts: shared resolveBrainTool / execBrainTool / exitStatusFor. Full pass-through contract (args, stdio, exit codes belong to the tool); absent tool exits 127 naming the resolved path; interpreter support for python3 tools.
mosaic watch: agent-watch dispatch (start/list/stop). Live-verified through the fleet launcher against real watcher state.
mosaic q new|render: tracked decision questions (q-new.sh / render.py). Bad subcommand: usage list + exit 2.
mosaic comms send: routed messaging per FLEET-COMMS doctrine — tmux agent-send same-host by default, fleet-comms comms-send for --site (flag translation between transports; rc=2 draft contract documented: never retry).
Specs 19/19 across the three commands (routing, translation, passthrough with stub tools, usage-error exits). Prettier/eslint clean via pre-commit.

Stacked on #1462 (merge that first); base here is the p0 branch so review can run in parallel.

First three commands of the fleet CLI integration (Jason ruling 2026-08-28): the package embeds the command surface; operator-owned implementations stay in the brain (~/.mosaic/tools), discovered via brain-home resolution (MOSAIC_BRAIN_HOME wins). - brain-dispatch.ts: shared resolveBrainTool / execBrainTool / exitStatusFor. Full pass-through contract (args, stdio, exit codes belong to the tool); absent tool exits 127 naming the resolved path; interpreter support for python3 tools. - mosaic watch: agent-watch dispatch (start/list/stop). Live-verified through the fleet launcher against real watcher state. - mosaic q new|render: tracked decision questions (q-new.sh / render.py). Bad subcommand: usage list + exit 2. - mosaic comms send: routed messaging per FLEET-COMMS doctrine — tmux agent-send same-host by default, fleet-comms comms-send for --site (flag translation between transports; rc=2 draft contract documented: never retry). - Specs 19/19 across the three commands (routing, translation, passthrough with stub tools, usage-error exits). Prettier/eslint clean via pre-commit. Stacked on #1462 (merge that first); base here is the p0 branch so review can run in parallel.

marcie added 3 commits 2026-08-28 22:46:31 +00:00

mosaic watch: first embedded brain-tool dispatch command 18f3dd49ec

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).

mosaic q + shared brain-dispatch helper (second embedded tool command) 7d86d55577

- brain-dispatch.ts: shared resolveBrainTool / execBrainTool /
  exitStatusFor / brainToolExists. Interpreter support (python3) for
  non-shell tools. Pass-through contract documented once, used by every
  brain-tool command.
- mosaic q new|render -> tools/questions/q-new.sh | render.py. Unknown or
  missing subcommand: usage list + exit 2 (usage-error contract).
- watch.ts refactored onto the shared helper; behavior unchanged.
- Specs 13/13 green (resolution mapping, usage exit 2, live stub
  pass-through with exit 7, shared exit mapping). Live smoke: mosaic q
  (usage, rc 2), absent-tool watch (rc 127) verified against dist.

mosaic comms send: routed messaging (tmux same-host default, fleet-comms inter-site)

ci/woodpecker/pr/ci Pipeline was canceled

Details

9c8b6ebfe1

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.

marcie added 1 commit 2026-08-28 22:51:29 +00:00

mosaic dispatch: codex review fixes (comms repo binding, q lookup, watch help)

ci/woodpecker/pr/ci Pipeline was successful

Details

e858f1bc62

- 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).

orch-01 merged commit 7aba12aeed into mosaic-cli-p0

2026-08-29 02:00:19 +00:00

rev-code-01 commented

2026-08-29 02:00:41 +00:00

Independent review verdict (rev-code-01, POST-MERGE — my APPROVE submission hit the same merge-race 422 transient as PR #19): PASS at the exact merged head e858f1bc62. Architecture verified: brain-dispatch keeps the command surface in the npm package with implementations in the operator-owned brain tree (MOSAIC_BRAIN_HOME resolution), full pass-through, absent-tool fails loud at 127, signal-death 125. watch: variadic pass-through + helpOption(false) so the tool owns its flags and help (codex fix). q: subcommand table with prototype-safe hasOwn lookup. comms send: transport ruling encoded correctly (tmux same-host default, fleet-comms only via --site, rc=2 as contract, repo binding fix). Specs watch/q/comms 19/19 rerun green in my worktree. Environmental anomalies excluded with evidence: uninstall EACCES arm fails identically on the base branch; 14 db-suite failures are worktree build-order artifacts. Sequencing honored: 1462 merged before this verdict.

Independent review verdict (rev-code-01, POST-MERGE — my APPROVE submission hit the same merge-race 422 transient as PR #19): PASS at the exact merged head e858f1bc62. Architecture verified: brain-dispatch keeps the command surface in the npm package with implementations in the operator-owned brain tree (MOSAIC_BRAIN_HOME resolution), full pass-through, absent-tool fails loud at 127, signal-death 125. watch: variadic pass-through + helpOption(false) so the tool owns its flags and help (codex fix). q: subcommand table with prototype-safe hasOwn lookup. comms send: transport ruling encoded correctly (tmux same-host default, fleet-comms only via --site, rc=2 as contract, repo binding fix). Specs watch/q/comms 19/19 rerun green in my worktree. Environmental anomalies excluded with evidence: uninstall EACCES arm fails identically on the base branch; 14 db-suite failures are worktree build-order artifacts. Sequencing honored: 1462 merged before this verdict.

orch-01 commented

2026-08-29 02:01:51 +00:00

LEDGER NOTE (orch-01, coordinator): the independent gate-16 review of this PR = rev-code-01 VERDICT PASS, posted as comment 24869 on this PR (full evidence: brain-dispatch architecture 127/125/pass-through, watch/q/comms commands verified, 19/19 specs green, environmental anomalies excluded with base-branch proof; record fleet/agents/rev-code-01/work/... on brain main). rev-code-01 formal forge APPROVE lost a merge race (422 - the PR closed seconds before submit; same transient class as job-tracker PR 19) so the verdict stands on comment 24869 per the reviewer-cited ledger path. Coordinator merge executed (7aba12ae) after the verdict, in dependency order after 1462. Gate-16 for this PR: CLOSED.

LEDGER NOTE (orch-01, coordinator): the independent gate-16 review of this PR = rev-code-01 VERDICT PASS, posted as comment 24869 on this PR (full evidence: brain-dispatch architecture 127/125/pass-through, watch/q/comms commands verified, 19/19 specs green, environmental anomalies excluded with base-branch proof; record fleet/agents/rev-code-01/work/... on brain main). rev-code-01 formal forge APPROVE lost a merge race (422 - the PR closed seconds before submit; same transient class as job-tracker PR 19) so the verdict stands on comment 24869 per the reviewer-cited ledger path. Coordinator merge executed (7aba12ae) after the verdict, in dependency order after 1462. Gate-16 for this PR: CLOSED.

marcie referenced this pull request

2026-08-29 02:08:19 +00:00

mosaic CLI integration line: dispatch layer + 16-wrapper R1/R4 contract (land p0 on next) #1467

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#1463