@remits/remits-cli 0.1.110 → 0.1.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.110",
+  "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

@@ -21,7 +21,11 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - [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)
+  - [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)
@@ -109,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)
@@ -291,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** |
@@ -306,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
@@ -462,17 +468,21 @@ workflows, and never one product's view of it.
 
 ### 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:**
+**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
+remits-cli agent serve
 ```
 
 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.
+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
@@ -487,27 +497,67 @@ 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 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.
 
-After `register`, **no agent command needs a flag** — they reuse the platform, lane and identity this
-session registered with.
+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 — keep `status` current as what you are doing changes ...
-# ... close the ticket lifecycle through mcp_support_ticket (accept -> update_status -> complete) ...
+# ... 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
 ```
 
-**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.
+**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
@@ -519,10 +569,24 @@ timer.
 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.
+**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
@@ -530,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`
@@ -1071,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
@@ -1151,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:
@@ -1203,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`,
@@ -1284,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
@@ -2729,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 |
 
@@ -2771,13 +2953,18 @@ 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 — 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 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 receiving tickets right now
+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"
 ```
 
+`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
@@ -2798,6 +2985,48 @@ platform, lane and identity it registered with.
   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
 
@@ -2812,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
 
@@ -2926,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