@remits/remits-cli 0.1.107 → 0.1.109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.107",
+  "version": "0.1.109",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -105,10 +105,12 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
   - [`mcp_jvm_spike_triage`](#mcp_jvm_spike_triage)
   - [`mcp_support_ticket_queue`](#mcp_support_ticket_queue)
 - [Multi-Session Support](#multi-session-support)
-- [Persistent Service, Control Center, and Agent Dispatch](#persistent-service-control-center-and-agent-dispatch)
-  - [Starting the Service](#starting-the-service)
+- [Registering This Session As An Agent](#registering-this-session-as-an-agent)
+  - [What registration actually does](#what-registration-actually-does)
+  - [Resolving which agent a command means](#resolving-which-agent-a-command-means)
+  - [Which agent gets a ticket](#which-agent-gets-a-ticket)
+- [Background Service and Control Center](#background-service-and-control-center)
   - [Control Center](#control-center)
-  - [Agent Dispatch](#agent-dispatch)
   - [Configuring the Preferred Agent](#configuring-the-preferred-agent)
 - [Local State Files](#local-state-files)
 - [Command Reference](#command-reference)
@@ -384,14 +386,16 @@ These files are decision inputs. Read them when the related decision depends on
   - Read when a support ticket references an account and you need to locate the correct local repo.
   - Read before concluding that a repo does not exist locally.
 - `~/.remits-cli/config.json`
-  - Read when service lifecycle, dashboard, listener, or agent-dispatch behavior matters.
+  - Read when service lifecycle, dashboard, or preferred-agent behavior matters.
 - `~/.remits-cli/service-state.json`
   - Read when the local control center URL, current dashboard port, repo-scan summary, or websocket status matters.
   - Read when the user asks whether the remits-cli service is running or where to open the browser view.
-- `~/.remits-cli/dispatch-panes.json`
-  - Read when support-ticket follow-up routing, pane reuse, or pane replacement behavior matters.
-- `~/.remits-cli/tmux-activity.log`
-  - Read when diagnosing service lifecycle, websocket, tmux, ticket-routing, or dispatch failures.
+- `~/.remits-cli/agents.json`
+  - The agent sessions registered from THIS machine, each with the process it is anchored to.
+  - Read when `remits-cli agent work` says no agent is registered, or when several agents are
+    registered and a command needs `--agent-id`.
+- `~/.remits-cli/activity.log`
+  - Read when diagnosing service lifecycle, websocket, agent registration, or ticket-routing failures.
 - `~/.remits-cli/sessions.json`
   - Read when authentication state, active accounts, base URLs, websocket topics, or per-account data mode matters.
 - `./.remits-cli/current-session.txt`
@@ -420,7 +424,7 @@ Think about remits-cli as two cooperating layers:
      - which repos exist locally
      - whether the background service is running
      - where the control center lives
-     - whether websocket/tmux dispatch is healthy
+     - which agent sessions are registered from this machine
 
 2. **Per-repo state** in `./.remits-cli/`
    - This is the request/response and cache layer for one specific working tree.
@@ -435,21 +439,77 @@ When a user asks an indirect question, map it to the right layer first:
 - "Why did this ticket open in the wrong repo?" → start in global state.
 - "What exact payload did this tool call send?" → start in per-repo state.
 - "Why is the dashboard showing stale repos?" → start in `service-state.json` and `account-repos.json`.
-- "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `tmux-activity.log`.
+- "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `activity.log`.
+- "Why is my agent not getting tickets?" → start in `agents.json`, then `remits-cli agent list`.
 
 Agents should use this mental model before guessing.
 
 ## Support Ticket Mental Model
 
-The local agent workflow includes a lightweight support-ticket system:
+Support tickets are a **first-class platform capability**, not an account convention. Every Remits
+account reads and writes the `support_tickets` collection without owning a Schema, tickets are anchor
+`Object`s on the account the work belongs to, and the lifecycle vocabulary is defined once in the
+platform.
 
-- Support tickets are Firestore documents in `support_tickets`.
-- Support tickets belong to the actual Remits account the work relates to.
-- Tickets are created centrally from support intake and pushed to local agents over the `remits-cli` WebSocket channel.
-- Each incoming ticket becomes a tmux workstream in the shared `remits-listener` session, so you can think of it as a localized Jira-style queue for active agent work.
-- Review centralized listener/tmux activity in `~/.remits-cli/tmux-activity.log`.
+**The platform is deliberately not the standard for ticket workflow.** Different Remits
+platforms and products integrate with different systems — Zendesk, Jira, a customer's own portal —
+and each end client has its own rules for how tickets move. Remits owns the *record* and the *verbs*;
+each front-stage platform builds its own workflow on top through its own Embeddables, Rules, and
+Actions. So what you see through `remits-cli` is the shared record underneath every one of those
+workflows, and never one product's view of it.
 
-Use `mcp_support_ticket` to manage lifecycle:
+### You are an agent, and you register yourself
+
+Work reaches you because **this terminal session registered itself as available**:
+
+```bash
+remits-cli agent register            # this tab is now a routable agent
+remits-cli agent work                # ask for the tickets routed to it
+```
+
+Three tabs running Claude are three agents. Each is independently routable, each reports its own
+activity, and each stops receiving work when its tab closes — a heartbeat process is anchored to the
+session and dies with it, so a crashed agent and a quit agent look identical to the platform.
+
+**Nothing is pushed at you.** A terminal mid-task cannot receive a push, so delivery is you asking.
+That is why the routing decision is a durable field on the ticket rather than a message: you can
+restart this terminal, register again, and the work is still there.
+
+Two facts about a ticket are separate and must stay separate:
+
+| Fact | Field | Means |
+|---|---|---|
+| **Routed** | `routedAgentId` | which agent session should pick this up — delivery |
+| **Owned** | `assignedTo` | who has claimed it — accountability |
+| **Status** | `status` | where it is in the workflow |
+
+A ticket routed to you is not yet yours. Claim it with `accept`, and the queue then shows it owned.
+
+### The loop
+
+```bash
+remits-cli agent register --label "claude@merchant-statements"
+remits-cli agent work --wait 300                    # blocks until something arrives
+remits-cli agent status --state working --ticket 22454 --activity "reproducing the upload failure"
+# ... investigate, fix, verify ...
+remits-cli agent status --activity "verifying the fix on localhost"
+# ... then close the ticket lifecycle through mcp_support_ticket ...
+remits-cli agent status --state idle                # ready for the next one
+```
+
+**Report what you are doing.** `agent status` is how an operator watching the dashboard, or another
+agent, knows this session is alive and what it is on. It costs one command and it is the difference
+between a visible queue and a silent one. Update it when you change what you are doing, not on a
+timer.
+
+### Seeing the queue as a human does
+
+`remits-cli start` opens a browser control center showing the same facts you are acting on: which
+agents are registered and what each is doing, which tickets are open, and which agent each is routed
+to. An operator can route a ticket to a specific agent from there. It is a view, not a second system —
+what it shows and what `remits-cli agent work` returns come from the same records.
+
+Use `mcp_support_ticket` to manage lifecycle:Use `mcp_support_ticket` to manage lifecycle:
 - `read` — always start here to load current state
 - `accept` — claim the ticket so other agents do not work it concurrently
 - `update_status` — move to `in_progress` or `pending_review`
@@ -462,7 +522,7 @@ Use `mcp_support_ticket` to manage lifecycle:
 Ticket-routing context:
 - `accountId` / `accountName` identify the account that owns the ticket.
 - If present, `implementationAccountId` / `implementationAccountName` identify the owning `PLATFORM` or `PRODUCT` implementation context.
-- The local listener should prefer `implementationAccountId` when choosing the initial working directory for a ticket, with fallback to `accountId` if the platform/product repo is not available locally.
+- Prefer `implementationAccountId` when choosing the working directory for a ticket, falling back to `accountId` when the platform/product repo is not available locally. Routing already uses that same ladder, so the repo you were routed through is usually the right one.
 - For enhancement work, prefer the platform/product implementation context when deciding where code changes belong.
 - For defect investigations, start from the owning ticket account, then move to the platform/product context if the root cause is in shared components.
 
@@ -2684,16 +2744,53 @@ unless you pass `--data-mode prod` explicitly. So `whoami` can read `prod` while
 lane — which is the safe direction, but not the one you would predict from the output alone. `whoami` says
 so in its own output; when a test run genuinely needs prod data, pass the flag.
 
-## Persistent Service, Control Center, and Agent Dispatch
+## Registering This Session As An Agent
 
-The current mental model is a **background remits-cli service**, not just a listener.
+`remits-cli agent` is how a terminal session makes itself available to work support tickets. It is
+independent of everything else — no background service is required, and every tab is its own agent.
 
-That service does three jobs:
-- Maintains persistent WebSocket connections to the Remits platform
-- Manages tmux-based agent dispatch for inbound `remits-cli` support messages
-- Hosts a localhost browser **control center** that shows the full local integration state
+```bash
+remits-cli agent register            # this session is now routable
+remits-cli agent work --wait 300     # ask for tickets routed here
+remits-cli agent status --state working --ticket 22454 --activity "reproducing"
+remits-cli agent list                # who else is available for this account
+remits-cli agent release             # stop receiving tickets right now
+```
+
+### What registration actually does
+
+- Mints an `agentId` for this session and tells the platform which account repos this machine has
+  checked out. The platform **verifies** those claims against what your user can access and returns
+  the ones it refused, so "I registered but never get tickets for account 52" is answerable from the
+  registration output alone.
+- Starts a small detached heartbeat process **anchored to the agent process that owns this terminal**
+  (it walks up the process tree to find `claude`/`codex`/`gemini`, then an interactive shell). When
+  that process ends, the heartbeat ends and the session stops being routable within a couple of
+  minutes. Closing the tab is a valid way to go offline; `agent release` just makes it immediate.
+- Registers in the session's **data lane**. A `test`-lane run only ever reaches a `test`-lane agent,
+  which is what keeps fixture traffic away from a production terminal.
+
+### Resolving which agent a command means
+
+Order: `--agent-id`, then `REMITS_AGENT_ID`, then the single agent registered for this working
+directory. With several registered and no way to tell them apart, the command **fails and lists the
+candidates** rather than guessing — routing work to the wrong tab is silent, and a message is not.
 
-### Starting the Service
+### Which agent gets a ticket
+
+The platform walks a ladder — the ticket's implementation account first (a defect seen on a client is
+usually fixed in the platform repo above it), then the ticket's own account, then its
+`PLATFORM`/`PRODUCT` ancestors — and takes the first account with an available agent. Among those it
+prefers an **idle** agent, then the one that has waited longest, so work spreads across your tabs
+instead of piling onto whichever one most recently ran a command. A `paused` agent stays visible and
+is never routed to.
+
+## Background Service and Control Center
+
+`remits-cli start` runs an optional background service for the **human** watching:
+
+- Maintains persistent WebSocket connections to the Remits platform
+- Hosts a localhost browser **control center** (typically `http://127.0.0.1:8787/`)
 
 ```bash
 remits-cli start
@@ -2711,50 +2808,27 @@ remits-cli listen status
 remits-cli listen stop
 ```
 
-The service:
-- Scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json`
-- Maintains one WebSocket connection per unique platform URL across all sessions
-- Subscribes to topics for every authenticated account
-- Handles `TestSuite` messages (test results) and `remits-cli` messages (agent dispatch)
-- Reconnects automatically if the connection drops
-- Uses a PID lock file (`~/.remits-cli/listener.pid`) to ensure only one service per machine
-- Writes `~/.remits-cli/service-state.json` so agents can discover the dashboard URL and current runtime status
+**The service is not part of ticket delivery.** Agents register and collect work on their own, so the
+dashboard being down never stops a ticket reaching an agent. What the service adds is visibility: it
+scans for `account-info.json` files to rebuild the repo index, keeps one WebSocket per platform URL,
+and holds a PID lock (`~/.remits-cli/listener.pid`) so only one runs per machine.
 
 ### Control Center
 
-`remits-cli start` should provide a localhost URL such as `http://127.0.0.1:8787/`.
-
-The control center is the fastest way to understand the whole integration surface in one browser view. It shows:
-- whether the remits-cli service is running
-- the current dashboard URL and port
+The control center shows, in one browser view:
+- which agent sessions are registered, what each is doing right now, and its recent activity
+- the open support-ticket queue, and which agent each ticket is routed to
+- a control to route a ticket at a specific available agent
 - websocket connection and topic health
-- tmux availability, session state, and tracked panes
-- the discovered account repo index
-- the important global JSON/log files
-- the important per-repo remits-cli files for every indexed account repo
-
-When a user asks a broad or vague question about remits-cli behavior, prefer opening or reasoning from the control center state before spelunking random files individually.
-
-### Agent Dispatch
-
-All dispatched agents run as **panes** within a single tmux session named `remits-listener`. This gives the user a single window where they can see and interact with all active agent workstreams side by side.
-
-When a `remits-cli` WebSocket message arrives from the platform:
+- the discovered account repo index and the important global/per-repo files
 
-1. The message's `accountId` is used to look up the account's local directory from the account repo index
-2. If the message has a `ticketId` that already has an active pane, the new message is **delivered to the existing pane** (the agent receives the follow-up in-context)
-3. If no pane exists for the `ticketId`, a new pane is **split into the `remits-listener` tmux session**, running the preferred AI coding agent with the message prompt at the account's directory
-4. Panes are automatically tiled for a clean layout
+**What it shows is what the agents see.** The ticket queue comes from the platform's own generic
+endpoint, not from any product's tool, so the control center reads the same on every Remits platform
+and never implies a workflow that a particular product does not have. Product-specific views belong
+in that product's Embeddables.
 
-**Ticket tracking:** Each support-ticket message should include a `ticketId`. The listener maps ticket workstreams to tmux pane IDs so follow-up messages for the same ticket are routed to the same agent session. Legacy payloads that only include `taskId` are still supported as a fallback. If the pane has been closed, a fresh pane is created.
-
-**Inspecting activity:** Use `tail -f ~/.remits-cli/tmux-activity.log` to watch service start/stop, WebSocket subscriptions, ticket dispatch receipt, pane creation, follow-up delivery, and failures.
-
-**Interacting with agents:** Attach to the tmux session to see all active agents:
-```bash
-tmux attach -t remits-listener
-```
-Use standard tmux navigation (`Ctrl-b` + arrow keys) to switch between panes.
+When a user asks a broad or vague question about remits-cli behavior, prefer reasoning from the
+control center state before spelunking individual files.
 
 ### Configuring the Preferred Agent
 
@@ -2788,11 +2862,13 @@ The agent preference is stored in `~/.remits-cli/config.json` and applies global
 - `listener.pid`
   - PID of the background remits-cli service process.
   - Use it only to confirm process presence; use `service-state.json` for richer service details.
-- `dispatch-panes.json`
-  - Maps active ticket routing keys (`ticket:<id>` or legacy `task:<id>`) to tmux pane IDs.
-  - Read this when follow-up messages appear to route to the wrong pane or when panes are being recreated.
-- `tmux-activity.log`
-  - Human-readable chronological event log for service lifecycle, websocket events, tmux actions, and dispatch behavior.
+- `agents.json`
+  - The agent sessions registered from this machine, each with the process it is anchored to.
+  - Read this when a command asks for `--agent-id`, or when an agent appears registered locally but
+    is missing from `remits-cli agent list` (that gap IS the "why am I not getting tickets" answer).
+- `activity.log`
+  - Human-readable chronological event log for service lifecycle, websocket events, agent
+    registration/heartbeat, and ticket routing.
   - This is usually the best forensic file for "what happened?" questions.
 
 **Per-repo** (`./.remits-cli/`):
@@ -2821,6 +2897,11 @@ Reading rules:
 remits-cli auth [--base-url URL] [--account-id ID] [--data-mode test|prod]
 remits-cli sessions [list|remove] [--account-id ID]
 remits-cli config [set] [--agent claude|codex|gemini]
+remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id ID]
+remits-cli agent work [--wait SECONDS] [--json]
+remits-cli agent status [--state idle|working|paused] [--ticket ID] [--activity "..."] [--step "..."]
+remits-cli agent list [--account-id ID] [--json]
+remits-cli agent release
 remits-cli start [--foreground true] [--port 8787]
 remits-cli stop
 remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
@@ -2946,7 +3027,6 @@ For tests specifically:
 | Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, inspect the staged payload with `mcp_cache` and escalate as a CLI/platform staging bug. |
 | Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
 | Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
-| tmux not installed | Install tmux (`brew install tmux` on macOS). Required for agent dispatch. |
 | Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |
 | Dashboard missing repos | Rebuild `~/.remits-cli/account-repos.json` with `remits-cli start` or the control center rescan action |
 | Agent dispatch to wrong directory | Check `~/.remits-cli/account-repos.json` has the correct directory and that you resolved the account type correctly. A `CLIENT` ticket may still belong to a parent `PLATFORM` or `PRODUCT` repo for code changes. |
@@ -3007,13 +3087,13 @@ which is the source served to every account repo. Better guides over time are an
      - the active repo session log from `./.remits-cli/sessions/`
      - any `./.remits-cli/tool-responses/<callId>.json` files involved
      - `~/.remits-cli/account-repos.json` if repo resolution may be relevant
-     - `~/.remits-cli/tmux-activity.log` if listener / websocket / dispatch behavior may be relevant
+     - `~/.remits-cli/activity.log` if service / websocket / agent-routing behavior may be relevant
 
 2. **Use the global Remits CLI state to make the bundle self-contained.**
    - Read `./.remits-cli/current-session.txt` to identify the active repo session log.
    - Record the exact repo directory and account context from `account-info.json`.
    - If repo selection or account targeting may be part of the issue, include the relevant entry from `~/.remits-cli/account-repos.json`.
-   - If the problem involves support-ticket delivery, tmux panes, or websocket events, include the relevant lines from `~/.remits-cli/tmux-activity.log`.
+   - If the problem involves support-ticket routing, agent registration, or websocket events, include the relevant lines from `~/.remits-cli/activity.log`.
    - If a tool call stored its full response externally, include that file path and summarize the important fields in `summary.md`.
 
 3. **Stop and document the issue clearly for the user.**