mosaicstack/stack
19
0
Fork 1
Code Issues 335 Pull Requests 16 Actions Packages Projects Releases 15 Wiki Activity

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

Open
marcie wants to merge 4 commits from mosaic-cli-p1-dispatch into mosaic-cli-p0
pull from: mosaic-cli-p1-dispatch
merge into: :mosaic-cli-p0
Conversation 0 Commits 4 Files Changed 8
+645
marcie commented 2026-08-28 22:46:30 +00:00
Member
Copy Link
Copy Source

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).
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin mosaic-cli-p1-dispatch:mosaic-cli-p1-dispatch
git checkout mosaic-cli-p1-dispatch
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1463