@remits/remits-cli 0.1.109 → 0.1.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.109",
+  "version": "0.1.112",
   "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,12 @@ 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)
+  - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
+  - [If you are the worker](#if-you-are-the-worker)
+  - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
+  - [When a worker needs a decision from a human](#when-a-worker-needs-a-decision-from-a-human)
+  - [The manual loop](#the-manual-loop)
 - [Efficiency Rules](#efficiency-rules)
 - [Account Repository Index](#account-repository-index)
 - [Two Workflows](#two-workflows)
@@ -107,8 +113,10 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - [Multi-Session Support](#multi-session-support)
 - [Registering This Session As An Agent](#registering-this-session-as-an-agent)
   - [What registration actually does](#what-registration-actually-does)
+  - [What `serve` adds](#what-serve-adds)
   - [Resolving which agent a command means](#resolving-which-agent-a-command-means)
   - [Which agent gets a ticket](#which-agent-gets-a-ticket)
+  - [Why a routed ticket might not have started](#why-a-routed-ticket-might-not-have-started)
 - [Background Service and Control Center](#background-service-and-control-center)
   - [Control Center](#control-center)
   - [Configuring the Preferred Agent](#configuring-the-preferred-agent)
@@ -289,8 +297,8 @@ every live component present at its real id, and nothing extra.
 | Command | What it touches | Danger |
 |---|---|---|
 | `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. | none |
-| `remits-cli components status` | Reads the local branch/user staging scope and branch resolution. | none |
-| `remits-cli components clear` | Clears the local branch/user staging cache without changing DB or git. | none |
+| `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
+| `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
 | `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
 | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
 | `remits-cli components commit` | **One shot:** `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
@@ -304,7 +312,7 @@ Key implications:
 - **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
   pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
 - After a successful non-dry-run `components sync` / `components commit`, the server clears the full
-  branch/user staging scope. This is the expected clean state: old Redis aliases should not keep shadowing
+  staging scope for that lane (account/user/branch/workspace). This is the expected clean state: old Redis aliases should not keep shadowing
   the newly synced DB rows. `components sync --dry-run` intentionally leaves staging untouched.
 
 ### Intended workflows
@@ -460,16 +468,25 @@ workflows, and never one product's view of it.
 
 ### You are an agent, and you register yourself
 
-Work reaches you because **this terminal session registered itself as available**:
+**If the user says anything like "register to become a support agent", or "work support tickets",
+run exactly this and nothing else first:**
 
 ```bash
-remits-cli agent register            # this tab is now a routable agent
-remits-cli agent work                # ask for the tickets routed to it
+remits-cli agent serve
 ```
 
-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.
+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 then **starts working tickets on its
+own**. It returns immediately; a background supervisor does the rest.
+
+Use `remits-cli agent register` instead **only** when the user wants presence without autonomy — a
+human, or you in this very tab, will work the tickets by hand. Registering alone starts nothing: it
+makes the session routable and then waits to be asked.
+
+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
@@ -480,28 +497,96 @@ Two facts about a ticket are separate and must stay separate:
 | Fact | Field | Means |
 |---|---|---|
 | **Routed** | `routedAgentId` | which agent session should pick this up — delivery |
+| **Claimed** | `claimedAgentId` | a worker process is running on it *right now* |
 | **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
+The **claim** is the supervisor's, not yours — it exists so two workers never start on one ticket,
+and it expires on its own so a killed worker cannot park a ticket forever. You do not manage it.
+
+### Autonomous: one ticket, one process
 
 ```bash
-remits-cli agent register --label "claude@merchant-statements"
-remits-cli agent work --wait 300                    # blocks until something arrives
+remits-cli agent serve                          # workers are whichever agent THIS session is
+remits-cli agent serve --worker-agent codex --max-concurrent 2
+remits-cli agent serve --mode investigate       # read-only workers: no file edits
+remits-cli agent workers                        # what is running right now
+remits-cli agent release                        # stop serving, go offline
+```
+
+**Run it in a plain terminal tab.** That tab becomes the agent host: `serve` returns immediately, a
+detached supervisor is anchored to the tab's shell, and closing the tab stops the agent. Nothing in
+that tab is an AI session — the AI only ever appears as the worker processes the supervisor spawns.
+
+Starting it from inside an AI session works too and self-detects the worker kind, but it is the
+lesser setup: it parks an interactive session as a heartbeat holder while its workers do the work.
+
+When a ticket is routed to this session, the supervisor launches **a fresh headless agent process
+for that ticket**, in that account's repo, with a brief the platform generates. That process exits
+when the ticket is done.
+
+**One ticket = one process is the point, and it is why nothing here ever needs `/clear`.** Context
+grooming cannot be a discipline: `/clear` and `/new` are commands a *human types into a TUI*, and no
+model can invoke them — so a long-lived session working ticket after ticket has no way to reset
+itself. A process that exits has nothing to reset. Do not try to solve context growth by being tidy
+inside one session; let the session end.
+
+**`serve` returns immediately, and that is correct.** Do not follow it with a wait, a poll, or a
+loop. The supervisor is detached precisely so this tab is free. Report that you are serving and
+stop; you have not left the job half done.
+
+What the supervisor handles for you, so you do not have to think about any of it: collecting routed
+work, claiming each ticket so no second worker starts on it, renewing that claim while the worker
+runs, reporting the worker's activity to the dashboard, dropping the claim when it exits, retrying a
+failed ticket once, and releasing a ticket back to the queue when it has failed too often. Closing
+the terminal stops everything and hands any in-flight work back.
+
+### The manual loop
+
+Only when the session registered with `agent register` rather than `agent serve`.
+
+```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 ...
-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
+# ... investigate, fix, verify — keep `status` current as what you are doing changes ...
+# ... close the ticket lifecycle through remits-cli ticket (accept -> status -> complete, ask, or release) ...
+remits-cli agent status --state idle                # then ask for work again
 ```
 
+**Nothing wakes this tab.** A routed ticket sits there until someone in this session asks for it, so
+if you are working the manual loop you have to keep asking. If you find yourself wishing you could
+be woken up, that is what `agent serve` is.
+
 **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.
+
+**Capacity is real, not advisory.** A serving session tells the platform how many workers it can run
+(`--max-concurrent`, default 1), and the router will not send it more than that. So a session at
+capacity is skipped in favour of one that is free, rather than accumulating tickets it will never
+start.
+
+**Lane note:** `register` and `serve` default 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.
+
+### If you are the worker
+
+You know you are one when `REMITS_SUPPORT_TICKET_ID` is set in your environment. Your whole job is
+that one ticket, and your brief is your prompt — follow it. Two things it says that are worth
+repeating: **report progress** with `remits-cli agent status --ticket <id> --activity "..."` (a
+headless run is invisible otherwise), and **end in a terminal state** — `complete` with a real
+resolution, or `update_status` with what you established and what the next agent should try. Exiting
+quietly leaves a ticket that looks in-flight forever.
+
 ### Seeing the queue as a human does
 
 `remits-cli start` opens a browser control center showing the same facts you are acting on: which
@@ -509,7 +594,79 @@ agents are registered and what each is doing, which tickets are open, and which
 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:
+### Agent components are workers too
+
+An Agent component that works support tickets must register itself in the same presence registry as
+CLI sessions. That makes it visible in `cliAgents()` and `remits-cli agent map`, and lets
+`dispatch(...)` / `ticket route` target it by the same `agentId` field:
+
+```groovy
+def me = workerId()                         // component:Agent:34
+registerWorker([agentId: me, label: 'Support Triage Agent'])
+def work = workerWork([agentId: me, runId: threadGroupingId()])
+workerStatus([agentId: me, ticketId: work.tickets[0]?.id, activity: 'investigating'])
+```
+
+`workerWork(...)` is the component-side analogue of `remits-cli agent work` — the same code runs behind
+both, so a component and a terminal session get the same answer to the same question. It reads tickets
+routed to that worker, claims what it may start, sweeps eligible unrouted work when it is idle (reported
+separately as `sweptTicketIds`), takes the repository edit lease when available, and returns `phase`,
+`brief`, `briefFacts`, and `editLease`. `phase:'editing'` means the component may edit and stage;
+`phase:'investigating'` means another worker holds the repo lease and the component must stay read-only.
+When a component reaches a resting point, pass `agentId` to `complete(...)`, `ask(...)`, or
+`release(...)` so the ticket verb frees the edit lease and drops its claim.
+
+Route to a component by its **id** (`component:Agent:34`) — that is what `workerId()` returns and what
+the component polls on. `ticket route --agent component:Agent:MyAgent` also works: the name is resolved
+and the id form is what gets stored.
+
+### Moving a ticket through its lifecycle
+
+**`remits-cli ticket` is the platform surface, and it is what you should reach for.** It reads and
+writes the platform's own ticket record, so the same commands work on every Remits platform.
+
+```bash
+remits-cli ticket read     --ticket 22454        # the full record
+remits-cli ticket accept   --ticket 22454        # claim it before changing anything
+remits-cli ticket progress --ticket 22454 --summary "Traced it to the posting Action" --category investigation
+remits-cli ticket status   --ticket 22454 --status in_progress
+remits-cli ticket complete --ticket 22454 --resolution "What you found and did"
+remits-cli ticket ask      --ticket 22454 --question "Re-issue or skip?" --context "412 affected"
+remits-cli ticket reply    --ticket 22454 --message "Skip them."
+remits-cli ticket release  --ticket 22454        # hand it back to the queue
+```
+
+### When a worker needs a decision from a human
+
+There are **three** ways a run can end, not two, and the third is what stops an agent guessing:
+
+| Outcome | Verb | Means |
+|---|---|---|
+| Done | `ticket complete --resolution` | finished, here is what I did |
+| **Blocked on a choice** | `ticket ask --question` | I understand the work; the DECISION is not mine |
+| Could not finish | `ticket status --status pending_review` + `ticket progress` | stuck, here is the hand-off |
+
+`ask` puts the question on the ticket as an outbound message and parks it. The queue then shows it as
+**awaiting a response** — distinct from "done, review me", which `pending_review` alone cannot express.
+
+Someone answers with `remits-cli ticket reply --message "..."` (or through an operator Embeddable).
+That **re-routes the ticket by default**, so the supervisor's next poll starts a **fresh worker whose
+brief already contains the exchange**. Resumption costs nothing because a worker is one process per
+ticket — there is no session to restore.
+
+Ask when the choice is genuinely not yours: which of two behaviours is wanted, whether to touch live
+data, an ambiguity in the request. Do not ask for reassurance about something you can determine
+yourself, and ask **once**, with the options laid out.
+
+Inside an autonomous worker `--ticket` defaults to the ticket that worker was launched for.
+
+A refusal is an **answer**: "accept it first", "already assigned to someone else", "reopen it
+first". Act on the sentence — do not go looking for another tool that lets you skip the step.
+
+**`mcp_support_ticket` is an account convention, not a platform guarantee.** It belongs to one
+particular System Account: it may not exist on the platform you are on, it scopes to its own
+account, and it will refuse a ticket owned by a different one. Use it only when you are working in
+that account and want its product-specific workflow on top of the record. It offers:
 - `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`
@@ -1050,7 +1207,7 @@ If verification reveals issues, repeat the loop: **edit → stage → run**. Eve
 Don't ask the user for permission to re-iterate — just do it. Only stop to ask if you're stuck or unsure about the intended behavior.
 
 If the work is tied to a support ticket:
-- Use `mcp_support_ticket` to mark the ticket `in_progress` once you have started substantive work.
+- Use `remits-cli ticket status --status in_progress` once you have started substantive work.
 - If a new reply arrives, re-read the ticket and incorporate the reply into your current plan.
 
 #### Step 6: Update Documentation
@@ -1130,8 +1287,8 @@ unexpectedly, stop and inspect the repo-local session log before running any mut
 If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:
 
 1. Re-read the ticket if needed to confirm the latest state and replies.
-2. If the work is done and verified, call `mcp_support_ticket` with `complete` and include a concise resolution summary.
-3. If you cannot finish, use `update_status` or `release` with clear notes so the next agent can continue.
+2. If the work is done and verified, call `remits-cli ticket complete` and include a concise resolution summary.
+3. If you cannot finish, use `remits-cli ticket status` or `remits-cli ticket release` with clear notes so the next agent can continue.
 4. Do this automatically. The human user should not need to instruct you to update the ticket.
 
 Options:
@@ -1182,10 +1339,17 @@ Plus the compile cache:
 ### Staging cache key format
 
 ```
+# default lane (no workspace)
 account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:id:<componentId>
 account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:name:<normalizedName>
+
+# workspace lane
+account:<accountId>:cli:<cliUserId>:components:<branch>:ws:<workspace>:<family>:id:<componentId>
 ```
 
+The staging scope is therefore **account + cli user + branch + workspace**. `workspace` is optional and
+absent by default; see "Working alongside other agents: the staging WORKSPACE" above.
+
 `<family>` is the lowercased component family (`reader`, `action`, `test`, `embeddable`, ...). Both an
 `id:` and a `name:` key are written per stage. The entry value carries: `kind` (the family), `type` (the
 component's OWN type enum such as `ObjectType`/`RuleType`, or absent — **never** the family), `hash`,
@@ -1263,15 +1427,51 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
   `No enum constant ObjectType.reader`).
 - **Confirm the DB version:** `mcp_component_view` reads the live DB source directly (no staging, no compile
   cache), so it is the source of truth for "what was committed."
-- **Ask the CLI what is staged:** `remits-cli components status` lists the current branch/user staged entries,
+- **Ask the CLI what is staged:** `remits-cli components status` lists this lane's staged entries,
   including staged fields, aliases, hashes, and TTLs. The default terminal output is concise; pass `--json` or
   `--verbose` when you need the full staged-entry payload. `remits-cli components clear` removes those entries
   when you intentionally want to fall back to DB source.
 
+### Working alongside other agents: the staging WORKSPACE
+
+Staging is scoped by `(account, cli user, branch, workspace)`. Account and user are fixed for a repo, so
+**without a workspace the git branch is the only isolation axis** — and `components stage` uploads the
+ENTIRE repo and REPLACES the lane rather than merging into it. Two agents on one branch therefore
+overwrite each other, and a `components commit` clears the lane out from under the other one.
+
+If more than one agent is working on the same branch, give each its own workspace:
+
+```bash
+git worktree add ../repo-agent-a forked      # one checkout per agent, same branch
+cd ../repo-agent-a
+remits-cli workspace use --auto              # names the lane after this directory
+remits-cli components stage                  # isolated: nobody else sees it, nobody overwrites it
+remits-cli test run --test 42
+remits-cli token --path /page/whatever
+```
+
+A workspace narrows STAGING and nothing else. A commit still targets the same branch and the same owner
+account, and the run still resolves whatever committed variant branch the account subscribes to — so it
+does **not** have the side effects of inventing a throwaway git branch per agent (which would make a
+commit write `ComponentVariant` overlays for a branch nobody subscribes to).
+
+- `.remits-cli/workspace` is per-checkout and gitignored, so each worktree keeps its own lane.
+- Precedence: `--workspace NAME` > `REMITS_WORKSPACE` > `.remits-cli/workspace` > shared default lane.
+- `--no-workspace` targets the shared lane for one command without clearing the file.
+- Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
+  effect, check that line FIRST. A mismatched lane resolves committed source, which looks identical to
+  "the stage did not work".
+- `remits-cli components status` lists every lane staged on the branch, so you can see whether another
+  agent is working alongside you.
+- `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
+
 ### Stage / sync / clear with remits-cli
 
 - `remits-cli components stage` writes local file changes into the Redis staging cache for the current
-  branch/user scope. This is the normal edit/test loop.
+  branch/user/workspace scope. This is the normal edit/test loop.
+- `remits-cli components stage --changed-only` stages just the components this working tree edited. It
+  does NOT reconcile, so entries for components it did not mention are left alone rather than deleted.
+  Useful on a large repo; a full stage is still the default and the safest.
 - `remits-cli components status` shows which branch/variant world the checkout resolves, plus staged entries,
   staged fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
 - **A full `stage` makes the `.meta.yml` AUTHORITATIVE.** Staging layers a payload over what is already
@@ -2708,8 +2908,11 @@ ticket with `mcp_support_ticket read` before lifecycle work and honor `mirrorOnl
 | `priorities` / `types` / `sources` / `tags` | no | Additional filters |
 | `assignedTo` / `unassigned` | no | Assignment filters |
 | `implementationAccountId` | no | Filter by owning `PLATFORM`/`PRODUCT` account |
-| `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags |
-| `sortBy` / `sortDirection` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `account` |
+| `workstream` / `plannedIn` / `boardStage` / `size` / `blockedBy` | no | SDLC-agnostic planning filters; exact matches on compact queue fields |
+| `rank` / `minRank` / `maxRank` | no | Exact or inclusive range filters for numeric planning rank |
+| `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags, workstream, and planning fields |
+| `sortBy` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `account`, `plannedIn`, `boardStage`, `rank`, `size` |
+| `sortDirection` | no | `asc` / `desc`, and it means the same thing on every axis. Natural order is `desc` for `triage`/`updated`/`priority` and `asc` for `status`/`account`/`rank`/`plannedIn`/`boardStage`/`size`, so pass it only to invert one |
 | `limit` / `offset` / `scanLimitPerAccount` | no | Paging and scan bounds |
 | `dataMode` | no | Normal agent work uses the **prod** ticket queue |
 
@@ -2750,25 +2953,80 @@ so in its own output; when a test run genuinely needs prod data, pass the flag.
 independent of everything else — no background service is required, and every tab is its own agent.
 
 ```bash
-remits-cli agent register            # this session is now routable
-remits-cli agent work --wait 300     # ask for tickets routed here
+remits-cli agent serve               # routable AND autonomously working tickets — the usual choice
+remits-cli agent workers             # what this session is running right now
+remits-cli agent list                # who else is available across the accounts you cover
+remits-cli agent release             # stop serving and stop receiving tickets right now
+
+remits-cli agent register            # presence ONLY — nothing starts on its own
+remits-cli agent work --wait 300     # ask for tickets routed here (manual loop)
 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
 ```
 
+`serve` is `register` plus a supervisor. Everything below about registration applies to both.
+
+**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. 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.
+  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.
+- Declares **capacity** — how many tickets this session can genuinely run at once (`--max-concurrent`,
+  default 1). The router will not exceed it.
+
+### What `serve` adds
+
+The same detached process that maintains presence also polls for work. On each poll it publishes the
+tickets it currently has running, renews their claims, and takes at most enough new ones to fill its
+capacity. For each new ticket it launches a headless worker:
+
+| | headless invocation | edit mode | investigate mode |
+|---|---|---|---|
+| `codex` | `codex exec --cd <repo>` | `--sandbox workspace-write` | `--sandbox read-only` |
+| `claude` | `claude -p --add-dir <repo>` | `--permission-mode acceptEdits` | `--permission-mode plan` |
+| `gemini` | `gemini -p` in `<repo>` | `--approval-mode auto_edit` | `--approval-mode plan` |
+
+**Which of the three it launches:** `--worker-agent` if you pass it, otherwise **whatever agent this
+session is** (detected from the process the agent anchored to — which finds nothing in a plain tab),
+otherwise `~/.remits-cli/config.json`'s `agent` (set it with `remits-cli config set --agent NAME`),
+otherwise `claude`. **It prints which it chose and why on startup**, because in the intended
+plain-tab setup the choice comes from a config file you may have set months ago. So running `agent serve` inside a Codex tab gives you Codex workers
+without a flag, and the label the operator sees (`codex@repo`) is resolved the same way — the label
+and the worker are one answer, not two.
+
+The brief always arrives on **stdin**, never in argv — it is a page of prose and argv has a hard
+length limit, so an argv brief would fail on exactly the detailed tickets that most need the detail.
+The brief itself is generated by the platform, so all three worker types are told the same thing.
+
+**Following a run.** `remits-cli start`'s control center lists every worker; **Follow live** streams
+that run's transcript into the page, rendering commands with their exit codes, file edits, and the
+agent's own messages as distinct things. It keeps working after the worker exits — a finished run is
+usually the one worth reading. For a terminal instead, each worker prints a `tail -f` for its log in
+`~/.remits-cli/workers/`.
+
+**There is no terminal to attach to, by design.** A worker is spawned with pipes and runs
+non-interactively (`codex exec`, `claude -p`), so there is no tty and no prompt to type at — the
+whole point is that it needs no supervision. Following the transcript is the way to watch, and it is
+strictly better than a terminal would be: the output is structured, so it can be read as events
+rather than scraped back out of ANSI text.
+
+**No worker ever commits.** The brief forbids `git commit`/`git push` and nothing in the supervisor
+runs git — a worker leaves its changes in the working tree and says so on the ticket, for a human to
+review.
 
 ### Resolving which agent a command means
 
@@ -2783,7 +3041,22 @@ usually fixed in the platform repo above it), then the ticket's own account, the
 `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.
+is never routed to, and so is one **at capacity** — those are different facts and stay separate:
+`paused` means a human stopped this session, at-capacity means its workers are all busy.
+
+### Why a routed ticket might not have started
+
+In order of likelihood:
+
+1. **The session registered but never served.** `agent register` starts nothing. `agent workers`
+   showing none while a ticket is routed here is this.
+2. **At capacity.** Check `agent workers`; the ticket starts when one finishes.
+3. **Another session is running it.** A claim held by a different agent blocks it until that claim is
+   dropped or expires.
+4. **No local checkout.** The worker still starts, and its brief tells it to locate the repo rather
+   than guess — but if the account genuinely is not on this machine it will say so and stop.
+5. **It failed twice already** and was released back to the queue. The transcripts in
+   `~/.remits-cli/workers/` say why.
 
 ## Background Service and Control Center
 
@@ -2897,18 +3170,25 @@ 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 serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--label NAME] [--data-mode test|prod]
+remits-cli agent workers [--json]
+remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id ID] [--max-concurrent N]
 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 map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane
 remits-cli agent release
+remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
+remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
+remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
 remits-cli start [--foreground true] [--port 8787]
 remits-cli stop
 remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
 remits-cli whoami [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
 remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
-remits-cli components stage [--branch <name>] [--data-mode test|prod] [--json|--verbose]
+remits-cli components stage [--branch <name>] [--workspace <name>] [--changed-only] [--data-mode test|prod] [--json|--verbose]
+remits-cli workspace [show | use <name> | use --auto | clear]
 remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only