stack/packages/cli/README.md

CLI

Jason's front door to the bus (slice 1 row S4, #1521): mosaic inbox, decide, tasks, agents and trail, and the bus host mosaic bus start|stop|status with its Discord notifier (row S4, #1521); the session launcher in the host and mosaic talk, stop and launches (row S6, #1523); and mosaic with no argument, the full-screen app (queue row 55, #1544). Briefs: docs/plans/2026-10-04_slice-1.md, rows S4 and S6, and docs/plans/2026-10-10_design-implementation.md, "Full-screen terminal app". Rulings: lead decisions 70 and 77 in docs/plans/2026-09-26_lead-decisions.md.

Every command reads through the broker. None opens the SQLite file.

scripts/mosaic                         # the app, on a terminal
scripts/mosaic inbox
scripts/mosaic decide 3f2a9c1e yes --note "ship it"
scripts/mosaic trail 3f2a9c1e-…        # then: scripts/mosaic trail vikunja:1/7
scripts/mosaic bus status
node --test 'packages/cli/tests/*.test.mjs'

Human commands

mosaic inbox [--business <id>] [--json]
mosaic decide <decision> <option> [--note <text>] [--yes] [--business <id>]
mosaic tasks [--business <id>] [--json]
mosaic agents [--business <id>] [--json]
mosaic trail <task|decision> [--business <id>] [--json]
mosaic talk <role> <text> [--wait <seconds>] [--business <id>]
mosaic stop <run>
mosaic launches off|on [--business <id>]
mosaic launches list [--json]

• The business is --business, or else the business of the bus host running on this data root. With neither, the command exits 4.
• The transport is packages/bus/src/human-cli.mjs <socket>, run as a child. The command writes {business, verb, args} on its stdin and reads the JSON reply on its stdout. The child proves a human shell: it re-executes itself with a nonce, and the broker checks its process and ancestry for agent markers. The command carries no capability and the bus is unchanged.
• Each command refuses with exit 3 before it touches the bus when an agent marker is in its environment (REQ-DEC-3). The broker would refuse anyway; this check only gives a clear message first. Agent seats never run these commands. The tests use a stand-in transport.
• inbox lists the open decisions routed to the human, gated first, in broker order. For a gated decision it prints what approving authorizes: the action, its target, and the one choice that authorizes it.
• decide takes the full id, or a unique prefix of at least 8 characters, from the inbox. It prints the decision and whether the choice authorizes or declines, then asks [y/N] on a terminal. Without a terminal it needs --yes, else it exits 4. On outcome-unknown it does not resend: it exits 1 and asks you to check mosaic inbox or mosaic trail <id> first.
• trail prints rows in the broker's order (at, table, seq). A decision's trail ends with its task_ref and follow with: mosaic trail <task>. It does not pull in the task's rows.
• talk sends <text> to the role as a REQUEST, then polls the human's inbox every 2 s for up to --wait seconds (default 900). It prints every message that arrives and marks it read, and stops at the reply to its REQUEST. No reply in time exits 1; the reply still lands in the inbox. --wait 0 only sends.
• launches off and on are the broker's launch.revoke and launch.restore. While off, every role.launch refuses with launch-revoked; running sessions keep running. Stop them with stop. bus start --pm doesn't ask the broker (launchPm skips authorizeLaunch): the human launches the PM, so launches off doesn't stop it. The other checks in "Sessions" below still apply.
• stop and launches list read <dataRoot>/bus-host/sessions.json, not the bus (see "Sessions" below). stop refuses inside an agent run; launches list does not, because the file is readable to the same user anyway.

The app

mosaic

With no argument, on a terminal, mosaic opens a full-screen app over the same broker reads as the verbs: Inbox, Tasks, Agents, Trail and Help. src/app.mjs handles keys and reads; src/screens.mjs draws the frames and nothing else.

• In an agent run it exits 3 with the same refusal as the verbs, before anything else. Without a terminal on both stdin and stdout it exits 4 and prints the seat usage (mosaic launch, mosaic seat task) and the verbs above. A script never gets the app.
• The business is the one of the bus host on this data root. With no host the app says so and :business <id> picks one.
• Keys: c i t a r switch views (Talk, Inbox, Tasks, Agents, Trail). ↑↓ or j k move, PgUp and PgDn page, Enter opens the selection whole, v opens its trail, : the command line, ? help, Esc closes a box, q or Ctrl-C quits. On the command line, Esc or Ctrl-C closes it and the arrows type nothing. Commands: :decide <decision> <option>, :trail <task|decision>, :business <id>, :q.
• Deciding: in the Inbox, digit n picks the selected decision's nth option and runs resolveDecision in src/cli.mjs, the code mosaic decide runs. The box shows the same lines and the same [y/N] question. y or Y resolves; any other key answers No, and so does quitting. Keys that arrive within 200 ms of the question being drawn are type-ahead and are dropped: a paste such as 1 yes, or keys typed while a read held the screen, never answer it. After outcome unknown the app shows the CLI's sentence and offers the trail (v) or a re-read (r). No key sends the choice again.
• Reads happen on entering a view, after a decision, and every 30 s while no box is open. A failed read keeps the last list on screen and marks it stale. A refused read (exit 3 codes) says refused. Broker text goes through visible() from packages/conversation/src/terminal.mjs, so control characters and bidi overrides show as ^[ and <U+202E>.
• Talk (c) points to mosaic talk for now. The conversation pane and stop come in a later row.
• 16 ANSI colours. Under NO_COLOR the only escape codes in a frame are reverse video on the selected row (the design's tokens keep selection visible without colour). Frames fit 80x24; the layout is designed at 120x36, and under 100 columns the nav shows keys only and the Inbox drops RAISED BY. Below 40x10 the frame only says the terminal is too small. If the decide question is open then, the frame says so, and any key answers it No, y included. Widths count terminal cells: East Asian Width W and F characters and emoji 2, a one-cell emoji base with U+FE0F 2. ZWJ sequences and flags count more than they draw, so such a row can come out short, never too wide. Wrapping breaks between graphemes, so U+FE0F and combining marks stay with their base.
• A decide box taller than the screen cuts the end of the question and nothing else: the decision line, the options, the recommendation, the action and target, what the choice authorizes, the task, your choice and the [y/N] question stay. The cut line points to mosaic inbox --json. When even those lines don't fit, the box says only "Too small to show this decision. Any key answers No." y resolves only while the frame shows the whole box apart from the cut, and the app checks the size at each key, so a terminal shrunk after the question appeared answers No. A gated decision with a task needs 20 rows at 80 columns (21 with a cut question), and 29 rows at 40 columns.
• The transport is the verbs' spawnSync child, so the screen does not redraw while a read is in flight (up to its 30 s timeout).
• On quit, end of input, SIGTERM, SIGINT, SIGHUP or an error (one in a resize redraw included) the app restores the screen, the cursor and cooked mode. After anything but an error it then prints (app closed with q; N decisions resolved this session); an error goes to stderr instead.

Bus host

mosaic bus start <business> [--pm]
                                the host; run by the unit, not by hand.
                                --pm also launches the business's PM
mosaic bus stop                 SIGTERM to the recorded host, then wait
mosaic bus status [--json]      host state file, socket, writer.lock

bus start does the following:

1. It reads the system config through scripts/mosaic-config.mjs validate, the business file and the role files, and builds the broker's {op: 'boot'} message (src/config.mjs). The message has launches: [] and readers: [<business>]. It gets config.trackers (below) when a tracker is set.
2. It reads the notifier config (below).
3. It forks packages/bus/src/process.mjs and waits up to 30 s for the boot reply. If the broker answers {ok: false, error}, the host exits 3 and prints broker refused to start: <code>. A timeout or an early exit gives exit 1.
4. It forks src/notifier-process.mjs and hands it the reader capability over IPC in {op: 'start'}. A notifier refusal closes the broker, and the host exits 3.
5. It writes <dataRoot>/bus-host/host.json (0600): the pid, the process start time, the business, the start time as text and the notifier binding. The file holds no capability.
6. It starts the session launcher (src/launcher.mjs, "Sessions" below) and, with --pm, launches the business's launch.by instance. A PM launch that refuses closes the host with the refusal's exit code.

No capability appears in argv, stdout, the environment or a file. startHost() in src/host.mjs is also the in-process API the launcher uses: bindLaunch(record) binds a launched run's process identity (pid, startTime) and returns {business, run, cap}; op(message) sends one of the broker process's launch ops (identity, authorizeLaunch, refuse, endLaunch, credentialStatus); beforeClose(fn) runs fn before the broker closes, so the launcher stops its sessions first. Requests to the broker process go one at a time. Each carries an id, and the broker echoes it on the reply. If a reply doesn't arrive within 10 s, or arrives with an id no request is waiting for, the channel is broken: the waiting request refuses with broker-channel-broken, so does every later one, and the host stops with exit 1 for the unit to restart. A late reply never answers a later request, and a launch waiting on one refuses.

SIGTERM or SIGINT stops the notifier after its poll in flight, then closes the broker and removes host.json. If either child dies on its own, the host goes down with exit 1. The unit then restarts both. The host watches the children once both have started, and it checks each child's exit state at that point too, so a broker that dies while the notifier starts still takes the host down.

bus stop signals only a pid that still runs with the recorded start time and whose command line is …/packages/cli/src/cli.mjs bus start. bus status never removes a lock. A writer.lock whose pid is gone means a broker was killed hard. Check, then remove the lock by hand (packages/bus/README.md).

Sessions

The launcher (src/launcher.mjs) starts managed role sessions (packages/seat/src/session.mjs, packages/harness). It serves <dataRoot>/bus-host/launch.sock (0600), which the PM's launch tool calls through its runner. One request is one line, {"cap": "…", "instance": "<role instance>"}, at most 4096 bytes; the reply is {"ok": true, "result": {run, instance, harness, model}} or {"ok": false, "error": "<code>"}. Launches run one at a time. In order:

Check	Refusal
the request is one JSON line with a string instance	invalid-request
the capability is live and names a role of this business	unauthenticated, not-a-role
the business file has a launch block	launch-not-configured
launch.instances lists the instance (for --pm: it is launch.by)	instance-not-listed
the instance isn't running	instance-running
the instance resolves to pi or claude-code and a model	unsupported-harness
its role has a contract file	no-role-contract
its model names exactly one launch.max family	unknown-model-family
that family has room; every running session counts, the PM's too	capacity-full
the broker authorizes role.launch for the caller	the broker's code (launch-revoked, decision-required, …)
the bundle builds and the runner starts	launch-failed

Every refusal is an action.refused event (the broker's refuse, or its own refusal for the last broker check) and a line in the launch log. Then the launcher reads the instance's credential status from the broker (metadata only), builds the bundle in the run directory, spawns the runner under unshare, binds the outer process's pid and start time, adds the session to sessions.json, and writes the capability as one line on the runner's stdin. The capability is never on disk, in argv or in the environment. When the runner exits, the launcher sends endLaunch with the end reason from its exit code (packages/harness/README.md), which writes session.ended, releases the role and kills the run's capabilities.

The manifest records the Pi version from the repository's pin (the @earendil-works/pi-coding-agent dependency in the root package.json) and, for Claude Code, --version from the binary sessions run: MOSAIC_CLAUDE_BIN when set (the unit pins it, below), else claude on PATH.

On disk, under the data root: launches/<business>/<run>/ (0700) is the run directory; launches/<business>.jsonl (0600, append-only) logs every launch, refusal and end; workspaces/<business>/<instance>/ (0700) is kept across launches; bus-host/sessions.json (0600) lists the running sessions.

When the host closes, the launcher stops taking requests and drops every open launch.sock connection, so a client that never ends its side can't hold the close. It sends SIGTERM to every runner (again each second, see "Limits"), waits up to 30 s, then SIGKILLs what is left and ends those launches as killed.

A host that starts reads the sessions.json the last host left. An entry for this business means that host died without ending the launch, and its run would keep holding the role. Before the launch socket opens, the launcher SIGKILLs each such session that still runs (same start time, unshare on its command line), binds the run again with the recorded identity and ends it as host-lost, which releases the role. A sessions.json that can't be read refuses the host start with exit 3; move it aside after checking which sessions still run.

mosaic stop <run> checks that the runner in sessions.json still runs with the recorded start time and that its command line is the runner's, then sends SIGTERM until it exits (30 s). A stale entry prints "not running" and exits 0; an unknown run exits 2.

Trackers

config.trackers[<business>] is {baseUrl, project, pollSeconds, reconcileMinutes}, taken from the tracker.* variables. tracker.project is a project-layer variable, so the entry comes from the one declared project whose .mosaic/project.json sets it. The resulting entry depends on the variables:

Variables	Result
No tracker.baseUrl	No entry and no task verbs
tracker.baseUrl set, no project setting tracker.project	A warning on stderr and no entry
Two projects setting tracker.project	Refusal with exit 3, because the boot shape holds one tracker project per business

Unit

scripts/bus-service.sh render|install|uninstall|status installs the template systemd/mosaic-bus.service.in as the systemd user unit [email protected], one instance per business (mosaic-bus@<business>). The template's file name has no @ because queue candidate manifests refuse it. It is modelled on scripts/discord-service.sh:

• install [--dir DIR] [--no-reload] [--claude PATH] writes the unit through a temp file and a rename, then runs systemctl --user daemon-reload. It prints the pinned claude and its --version.
• render [--claude PATH] prints the unit without writing it.
• uninstall refuses while an instance is active.
• status <business> shows the unit's state and its Environment, which includes the pinned claude.

The unit settings:

• ExecStart=@REPO@/scripts/mosaic bus start %i
• Restart=on-failure
• RestartPreventExitStatus=2 3 4, so refusals are never retried
• KillSignal=SIGTERM
• TimeoutStopSec=60
• Environment=PATH=: /usr/local/bin:/usr/bin:/bin, with node's directory first when it isn't one of those
• Environment=MOSAIC_CLAUDE_BIN=: the Claude Code binary that managed sessions and the manifest's version run

MOSAIC_CLAUDE_BIN comes from --claude PATH, or else command -v claude in the installing shell. The path is kept as given, so the native install's ~/.local/bin/claude, a symlink into its versions directory, keeps following its updates; reinstall to change it. It must be absolute, an executable file, and only A-Z a-z 0-9 / . _ + -, because systemd expands % and splits Environment= on spaces; anything else refuses with exit 1 and writes nothing. With no claude found, the unit gets a comment line instead and sessions run claude from the unit's PATH. A running host keeps the environment it started with until it restarts.

The unit has no network-online.target ordering, since a user unit cannot order on that system target. The notifier needs no network at start: a send that fails is journaled and retried.

Notifier

The notifier is a child of the host. Each poll (every 30 s) it reads the inbox through the reader capability and does two things:

• DMs. It DMs each open blocking decision once. The DM holds the question, the options, the recommendation, what approving authorizes, the task, and mosaic decide <short id> <option>.
• Digest. It sends one digest a day at 08:00 America/Chicago. The hour comes from the IANA zone, so daylight saving time is handled. If the host starts after 08:00 and the day has no digest yet, the digest goes at once. The digest lists the inbox. It marks each blocking decision with one of three states: "DM sent", "DM pending" or "DM refused, not retried". An empty inbox gets one line. Each message stays within Discord's 2000 characters.

The notifier only reads the bus. Its memory is the journal <dataRoot>/notify/<business>/sent.jsonl (directory 0700, file 0600), with one line per send attempt:

{"at": "…", "kind": "dm", "decision": "<id>", "outcome": "confirmed", "messageId": "…"}
{"at": "…", "kind": "digest", "decision": null, "day": "2026-10-08", "outcome": "unknown", "messageId": null}

• A decision, or a day's digest, counts as sent once it has a confirmed line.
• A refused or unknown send is retried. After an unknown outcome the wait starts at 30 s and doubles up to 30 min. A duplicate costs less than a miss. Every retry carries the same Discord nonce, so a retry inside Discord's dedupe window returns the first message. A DM's nonce comes from the decision id. A digest's comes from the business and the day.
• A definite refusal is a DM refused with an HTTP 4xx other than 429. The next attempt waits the full 30 min, counted from the refusal's at in the journal, so a restart does not shorten it. After 5 of them for one decision, at least 2 hours apart end to end, the notifier appends one gave-up line, logs it once and never sends that DM again. The digest marks the decision "DM refused, not retried". The count comes from the journal, so a restart keeps it. An unknown outcome (network, 5xx or 429) retries without a limit (lead decisions 72 and 73).
• Recovery after a give-up is manual. Fixing the binding does not resend the DM, which stays given up. The decision stays open in mosaic inbox, the digest lists it, and the operator decides it with mosaic decide.
• On open, a final line without its newline is a torn write. The notifier copies those bytes to torn-<UTC stamp>.bin in the same directory (0600, a new file, synced), then truncates sent.jsonl to its last newline and syncs it. It logs both steps. A crash between the two leaves the torn tail in place, and the next open repairs it with a second copy. The next append therefore starts on a line of its own.
• A malformed complete line refuses with exit 3 and changes nothing. Each line is type-checked: at an ISO timestamp, kind dm or digest, decision a string (required for dm, null for digest), day a real YYYY-MM-DD date (required for digest), outcome one of confirmed, refused, unknown or gave-up (gave-up only for dm), messageId a string (required when confirmed) or null, status an integer when present.
• The journal refuses with exit 3 when its directory is looser than 0700, not yours, a symlink (dangling or not) or not writable, or cannot be created (for example, a parent is a file). It also refuses when sent.jsonl is a symlink, a directory or not writable, or is not a regular 0600 file you own. The message names the path.
• No Discord channel or user id goes in the journal, a log line or an error.

The Discord side is packages/discord/src/notify.mjs. It uses the connector's REST client and the binding's tokenFile, and sends to the binding's fixed dmRecipient, who must be one of the binding's users.

Notifier config

<dataRoot>/notify/<business>/notify.json, mode 0600, owned by you. The journal shares the directory, so create it 0700 first (mkdir -m 0700 -p <dataRoot>/notify/<business>). A host with a binding refuses with exit 3 on a looser directory.

{"notifyVersion": 1, "binding": "sage-seat"}

"binding": null runs the host without DMs. A missing file refuses with exit 3, so a host never starts until someone decides whether it DMs.

Exit codes

Code	Meaning
0	ok
1	failed, or outcome unknown: check before retrying
2	invalid input: unknown option, no such open decision, decision already closed, no such run, not a runner
3	refused or config problem: inside an agent run, human proof failed, unknown business, bad config, broker or notifier refused to start
4	usage

Limits

• One broker per data root. The bus store takes <dataRoot>/bus/writer.lock. The unit is a template per business, but only one instance can run on one data root.
• digest.sent is unused. The bus schema has this event kind, but decision 70 puts the notifier's memory in the journal, and a reader capability cannot write events.
• The real human transport is untested here. No test runs the real human-cli.mjs, because its proof needs a human shell. The live run covers it.
• stop is same-UID process control. It checks the start time and the command line, not authority. Any process of the same user can signal a runner directly.
• Signals before the runner's handlers. A session's runner is pid 1 of its PID namespace, and pid 1 ignores a signal it has no handler for. The runner installs its handlers first, but Node's startup leaves a short window, so the launcher and stop resend SIGTERM every second.
• If the host dies hard, its sessions keep running until their broker polls fail, then exit 23, and their launches stay open in the bus until the next host starts and ends them as host-lost ("Sessions" above). With no next host, nothing ends them.
• talk and the launches verbs are tested only with the in-process transport, as the other human commands are.
• Tracker boot is tested only without trackers. The trackers boot case is tested once S3's broker change lands.

Not in this piece

The WebUI (S5).