@remits/remits-cli 0.1.124 → 0.1.126

package/README.md

@@ -64,6 +64,9 @@ remits-cli install --skills --overwrite true
 
 ## How It Works
 
+- `cli/index.js` opens with a line-numbered code Table of Contents. Section entries are generated from
+  the `##` section marker comments in the file. Run `npm run prepare:index-toc` after moving sections;
+  `npm test` checks that the prepared line numbers still point at the real headings.
 - `components stage` has three modes, and the difference decides what a run in the lane resolves:
   - **default (full snapshot)** — uploads the whole repository manifest and reconciles the lane to it, so stale aliases from prior stages are removed. Correct as a complete snapshot and as a "what is stale here?" reset; a poor progress signal, because the lane then holds every component in the repo.
   - **`--workset`** — uploads only the components git reports changed and reconciles the lane to exactly those. The normal iteration mode. `--changed-only --replace-lane` is the explicit spelling.
@@ -89,7 +92,7 @@ remits-cli install --skills --overwrite true
 - `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
 - Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/front-stage/remits-components-zip-readme.md`).
 - Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
-- During account-repo discovery, `remits-cli` also overwrites the installed remits-cli `SKILL.md` for `claude`, `codex`, and `gemini` so local agents stay on the latest packaged instructions.
+- On every command, `remits-cli` refreshes the installed remits-cli `SKILL.md` and reference files for `claude`, `codex`, and `gemini` so local agents stay on the latest packaged instructions.
 - The platform repo's `docs/front-stage/` tree remains the single source of truth; the platform serves it from the classpath, so published CLI versions never carry guide content.
 - Authenticated users also get the **core Remits platform repo** locally. After guide sync (and on `auth` / discovery), `remits-cli` first reuses any existing local copy it already knows about, can detect directly (`REMITS_PLATFORM_DIR`, the running CLI source in dev, `~/remits`), or can discover under the configured scan roots; only if none is found does it clone `git@github.com:tmillhouse/remits.git` (default `~/remits`, override with `REMITS_PLATFORM_DIR`; cloning only runs in an interactive terminal). On each authenticated run it also fast-forwards the repo (`git pull --ff-only`, once per process) so back-stage analysis runs against current code — skipped automatically if the working tree is dirty, so local work is never clobbered. The repo is tracked in `~/.remits-cli/account-repos.json` under the reserved `platform` entry so agents can analyze back-stage seams and open a fix PR when a front-stage failure turns out to be platform brittleness.
 - Branch defaults to the current local git branch.
@@ -106,7 +109,7 @@ remits-cli install --skills --overwrite true
 - `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.
 - On `test run`, `--branch <name>` is only the Redis staging namespace. Pair an unused value with `--variant-branch none` when existing staged entries on the real git branch would shadow committed trunk/variant rows. Do not apply that shortcut to `components sync` or `components commit`, where `--branch` names the GitHub branch to reconcile.
 
-## Service, Dashboard, WebSocket, and Tmux Lifecycle
+## Service, Dashboard, and WebSocket Lifecycle
 
 - The primary lifecycle commands are `remits-cli start`, `remits-cli stop`, and `remits-cli status`.
 - `remits-cli listen`, `remits-cli listen stop`, and `remits-cli listen status` still work as compatibility aliases.
@@ -116,16 +119,14 @@ remits-cli install --skills --overwrite true
 - `remits-cli status` reports whether the background service is alive, prints the dashboard URL when available, and prints the resolved session tuple: Account ID, User ID, current git branch, and active data mode.
 - `remits-cli whoami` prints only the resolved session tuple. Use `--base-url`, `--account-id`, and `--data-mode` to prove the exact host/account/lane before running a tool or test.
 - Both print **two** data modes. "Data mode" governs `tool` / `tools` / `token` and falls back to the stored session lane; "Data mode (test run)" governs `test run`, which ignores the session and defaults to `test` unless `--data-mode prod` is passed. The test-run line also reports its source, such as `cliDefault` or `explicitFlag`.
-- `remits-cli stop` stops the background service, kills the shared tmux session, and clears pane tracking state.
+- `remits-cli stop` stops the background service.
 - The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
-- The dashboard shows websocket connection health, topic subscriptions, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.
-- If websocket connections are disconnected or the tmux session is missing, the dashboard exposes actions to reconnect websockets or recreate the tmux session.
+- The dashboard shows websocket connection health, topic subscriptions, registered agents, live and recent worker runs, the discovered account repo index, global state files, and per-repo remits-cli files.
+- If websocket connections are disconnected, the dashboard exposes an action to reconnect them.
 - The service groups sessions by `baseUrl` so one websocket connection can service multiple authenticated accounts on the same Remits environment.
 - Websocket subscriptions are deduplicated by user topic. If multiple authenticated accounts share the same websocket topic, the listener subscribes once and maps that topic back to all related accounts.
-- The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections and recreates the shared tmux session if it disappears.
+- The daemon keeps STOMP heartbeats enabled and runs a maintenance watchdog that recreates unhealthy websocket connections.
 - If the machine sleeps, the network drops, or auth sessions change while the daemon is already running, the service now attempts to reconnect and resubscribe automatically once connectivity returns.
-- Incoming websocket messages of type `remits-cli` are dispatched into dedicated tmux windows so the selected agent can continue working interactively with a full terminal view.
-- The listener creates a shared tmux session named `remits-listener`.
 - Support tickets are the primary unit of dispatched work. A serving agent launches one fresh worker process per routed ticket.
 - Agent sessions register themselves with `remits-cli agent register` or `remits-cli agent serve`; `serve` also starts the local supervisor.
 - Tickets are delivered by durable routing on the ticket record, then the agent asks for routed work with `remits-cli agent work`.
@@ -179,12 +180,14 @@ There are two separate state areas:
   PID for the background remits-cli service process.
 - `~/.remits-cli/service-state.json`
   Dashboard URL, repo scan summary, and websocket state snapshot for the running service.
-- `~/.remits-cli/dispatch-panes.json`
-  Persistent map of support ticket routing key to the active tmux pane id for that ticket's dedicated window. `ticketId` is preferred, with legacy `taskId` fallback.
 - `~/.remits-cli/account-repos.json`
   Index of known account repositories on this machine, rebuilt by `remits-cli start` via account-info discovery and also refreshed when commands run inside an account repo.
-- `~/.remits-cli/tmux-activity.log`
-  Human-readable global activity log for listener and tmux lifecycle events.
+- `~/.remits-cli/agents.json`
+  Agent sessions registered from this machine, including the process each one is anchored to.
+- `~/.remits-cli/workers.json`
+  Active and recent ticket worker state for serving agents.
+- `~/.remits-cli/activity.log`
+  Human-readable global activity log for service lifecycle, websocket events, agent registration, and ticket routing.
 
 ## Control Center
 
@@ -192,21 +195,20 @@ There are two separate state areas:
 - Open that page in a browser to inspect the full local remits-cli integration state without manually opening JSON files.
 - The page refreshes automatically and includes the latest global state files plus per-repo `account-info.json`, local tools snapshot, and current session log tail for every indexed account repo. Large account configuration fields live in `account-configurations.json` and should be opened only when needed.
 
-## Tmux Activity Log
+## Activity Log
 
-- `~/.remits-cli/tmux-activity.log` is the quickest way to understand what the listener is doing.
-- It records timestamped lifecycle events such as listener start/stop, websocket connect/disconnect, topic subscription, dispatch receipt, pane creation, follow-up delivery, pane replacement, and dispatch failures.
-- Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as `accountId`, `ticketId`, any legacy `taskId`, available keys, and prompt length.
+- `~/.remits-cli/activity.log` is the quickest way to understand what the service, websocket clients, and local agents are doing.
+- It records timestamped lifecycle events such as service start/stop, websocket connect/disconnect, topic subscription, agent registration/heartbeat, ticket routing, worker launch, and worker completion.
+- Prompt bodies are not written verbatim to this log. The log stores summarized metadata such as `accountId`, `ticketId`, available keys, and prompt length.
 - Typical inspection commands:
 
 ```bash
-tail -f ~/.remits-cli/tmux-activity.log
-tail -n 200 ~/.remits-cli/tmux-activity.log
+tail -f ~/.remits-cli/activity.log
+tail -n 200 ~/.remits-cli/activity.log
 ```
 
 ## Operational Notes
 
-- `tmux` must be installed for agent dispatch to work. Without it, websocket dispatch is received but agent panes cannot be created.
 - In sandboxed local agent environments, `remits-cli` network calls may fail with `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar errors even when dispatch worked correctly. That means the command needs escalated permissions or must be run outside the sandbox.
 - If the platform returns a 500 or other unexpected server-side failure, stop normal task execution and escalate to a Remits system admin. Agents should not invent workarounds for platform faults.
 - Recommended durable update flow for agents: `components stage --workset` for testing, then `git add/commit/push`, then `remits-cli components sync --safe`, then `git pull --ff-only` to confirm platform-generated files like `account-info.json`. To verify the COMMITTED variant rather than your staging, run `components clear --all` first — staged entries still win for CLI-scoped runs.