@remits/remits-cli 0.1.108 → 0.1.110

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -20,6 +20,8 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - [Required Local Index Reads](#required-local-index-reads)
 - [Big Picture: How remits-cli State Is Organized](#big-picture-how-remits-cli-state-is-organized)
 - [Support Ticket Mental Model](#support-ticket-mental-model)
+  - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
+  - [The loop](#the-loop)
 - [Efficiency Rules](#efficiency-rules)
 - [Account Repository Index](#account-repository-index)
 - [Two Workflows](#two-workflows)
@@ -105,10 +107,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 +388,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 +426,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 +441,96 @@ 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
+
+**If the user says anything like "register to become a support agent", run exactly this and nothing
+else first:**
+
+```bash
+remits-cli agent register
+```
+
+No flags, no setup, **no need to be in an account repo** — run it from wherever the session started.
+It registers this terminal for every account repo indexed on this machine that your user can reach,
+against the production platform and the production lane, and prints the accounts it was accepted for.
+It also prints the support loop; follow it.
+
+Three tabs running an agent are three agents. Each is independently routable, each reports its own
+activity, and each stops receiving work when its tab closes — a heartbeat anchored to the session 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
+
+After `register`, **no agent command needs a flag** — they reuse the platform, lane and identity this
+session registered with.
+
+```bash
+remits-cli agent work --wait 600                    # returns as soon as work arrives
+remits-cli agent status --state working --ticket 22454 --activity "reproducing the upload failure"
+# ... investigate, fix, verify — keep `status` current as what you are doing changes ...
+# ... close the ticket lifecycle through mcp_support_ticket (accept -> update_status -> complete) ...
+remits-cli agent status --state idle                # then ask for work again
+```
+
+**Stay on duty.** When `agent work` returns nothing, ask again — do not stop and wait to be
+re-prompted. Registration persists for the life of the session (the heartbeat keeps you visible and
+routable even while you are not polling), but collecting work is something you have to do.
+
+**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.
+
+**Work the ticket in the right repo.** A ticket names its `accountId`, and often an
+`implementationAccountId` — the platform/product account whose repo holds the code. Resolve that to a
+local directory through `~/.remits-cli/account-repos.json` and `cd` there before making changes. You
+registered from anywhere; you do not fix anything from anywhere.
+
+**Lane note:** `register` defaults to the production lane because a support agent works real tickets.
+`--data-mode test` registers a fixture agent instead, which will never be routed a production ticket —
+use it only when you are deliberately testing the routing itself.
+
+### 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 +543,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 +2765,61 @@ 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 — no flags, any directory
+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 across the accounts you cover
+remits-cli agent release             # stop receiving tickets right now
+```
+
+**Defaults exist so the user does not have to type them.** With no flags, `register` targets the
+production platform (`REMITS_BASE_URL` when set) and the **prod** lane, and claims every account repo
+indexed on this machine. That is a deliberate exception to the CLI's test-first default: registering
+presence mutates no business data, and a test-lane agent is silently useless for support — it appears
+online and can never be routed a production ticket. Every command after `register` reuses the
+platform, lane and identity it registered with.
+
+### What registration actually does
+
+- Mints an `agentId` for this session and tells the platform which account repos this machine has
+  checked out — read from the machine-wide index (`~/.remits-cli/account-repos.json`), which is why
+  the working directory does not matter. 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.
+
+### 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
 
-### Starting the Service
+`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 +2837,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.
+- the discovered account repo index and the important global/per-repo files
 
-When a `remits-cli` WebSocket message arrives from the platform:
+**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.
 
-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
-
-**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 +2891,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 +2926,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 +3056,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 +3116,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.**