@remits/remits-cli 0.1.166 → 0.1.167

package/index.js

@@ -15,7 +15,7 @@
 - L9873  Tokens, Tools, Verification, And Config
 - L11390  Service Dashboard And WebSocket Listener
 - L13900  Agent And Ticket Workflows
-- L18202  Help, Auto Update, And Command Dispatch
+- L18308  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -14613,8 +14613,50 @@ function agentSessionFor(flags, entry) {
   };
 }
 
-/** Every account repo checked out on this machine, as registration claims. The platform verifies them. */
-function agentAccountClaims(cwd) {
+/**
+ * `--accounts 33,52` -> { roots: [33, 52], descendants: true }; `--no-descendants` narrows each root to
+ * itself. Returns null when coverage was not declared, which keeps today's behaviour (every indexed repo).
+ */
+function parseAgentCoverage(flags) {
+  const raw = flags && (flags.accounts || flags['account-ids']);
+  if (raw === undefined || raw === null || raw === true || raw === false) {
+    return null;
+  }
+  const roots = String(raw).split(',')
+    .map((entry) => Number(String(entry).trim()))
+    .filter((id, index, all) => Number.isFinite(id) && id > 0 && all.indexOf(id) === index);
+  if (!roots.length) {
+    throw new Error('--accounts needs one or more numeric account ids, e.g. --accounts 33 or --accounts 33,52.');
+  }
+  const descendants = !(flagEnabled(flags['no-descendants']) || flags.descendants === false ||
+    String(flags.descendants || '').toLowerCase() === 'false');
+  return { roots, descendants };
+}
+
+/**
+ * Every account repo checked out on this machine, as registration claims. The platform verifies them.
+ *
+ * With declared coverage (`--accounts`), ONLY those roots are claimed — each with its descendants unless
+ * `--no-descendants` — whether or not a checkout of it is indexed. Without it, every indexed repository is
+ * claimed, which is the historical behaviour and is too wide for a fleet member meant to serve one tree.
+ * The session account (`--account-id`) is context, never coverage.
+ */
+function agentAccountClaims(cwd, coverage) {
+  if (coverage) {
+    const indexed = listAccountRepoEntries(readAccountRepoIndex());
+    return coverage.roots.map((accountId) => {
+      const entry = indexed.find((candidate) => Number(candidate.accountId) === accountId) || {};
+      return {
+        accountId,
+        name: entry.name || null,
+        type: entry.type || null,
+        platformAccountId: entry.platformAccountId || null,
+        directory: entry.directory || null,
+        routingScope: coverage.descendants ? 'self_and_descendants' : 'self',
+        source: 'coverage'
+      };
+    });
+  }
   const claims = listAccountRepoEntries(readAccountRepoIndex()).map((entry) => ({
     accountId: Number(entry.accountId),
     name: entry.name || null,
@@ -14662,6 +14704,7 @@ async function agentRegisterCommand(flags, options = {}) {
   try { discoverAccountRepos(); } catch (_) { /* best-effort */ }
 
   const { session, baseUrl, dataMode } = agentSessionFor(flags, null);
+  const coverage = parseAgentCoverage(Object.assign({}, options.serve && options.serve.coverageFlags, flags));
   const anchor = resolveAgentAnchorPid();
   if (!anchor.pid) {
     throw new Error(
@@ -14698,7 +14741,8 @@ async function agentRegisterCommand(flags, options = {}) {
     workspace: resolveWorkspace(cwd, flags) || undefined,
     dataMode,
     accountId: Number(session.accountId) || undefined,
-    accounts: agentAccountClaims(cwd),
+    accounts: agentAccountClaims(cwd, coverage),
+    coverageExplicit: coverage ? true : undefined,
     // Capacity is how many workers this session can actually RUN, which only this side knows. The
     // platform stops routing past it, so a supervisor at capacity is not handed work it cannot start.
     maxConcurrent: options.serve ? options.serve.maxConcurrent : (flags['max-concurrent'] ? parsePositiveInt(flags['max-concurrent'], 1) : undefined),
@@ -14733,6 +14777,7 @@ async function agentRegisterCommand(flags, options = {}) {
     // The accounts the platform ACCEPTED, so `agent list` can scope itself to the work this session
     // can actually be routed rather than to whichever session happened to be most recent.
     accountIds: response.accountIds || [],
+    coverage: coverage || null,
     accountId: Number(session.accountId) || null,
     anchorPid: anchor.pid,
     anchorSource: anchor.source,
@@ -14774,6 +14819,13 @@ async function agentRegisterCommand(flags, options = {}) {
   console.log('  data lane  ' + dataMode + (dataMode === 'prod' ? '  (live support tickets)' : '  (fixtures only)'));
   console.log('  accounts   ' + accepted.length + ' account(s) this session can be routed work for');
   console.log('             ' + accepted.join(', '));
+  // The scope the platform ACCEPTED, per claim — "33 + descendants" vs "every repo on this machine" is the
+  // difference between a bounded fleet member and one that takes any account it can reach.
+  const scopes = (response.accounts || []).map((entry) => entry.accountId +
+    (entry.routingScope === 'self_and_descendants' ? ' + descendants' : ''));
+  console.log('  coverage   ' + (coverage
+    ? 'declared (--accounts): ' + scopes.join(', ')
+    : 'every indexed account repo (bound it with --accounts <id>[,<id>] [--no-descendants]): ' + scopes.join(', ')));
   console.log('  heartbeat  every ' + Math.round(AGENT_HEARTBEAT_INTERVAL_MS / 1000) + 's, anchored to pid ' +
     anchor.pid + ' (' + anchor.source + '), ends when this session ends');
   if ((response.skippedAccounts || []).length) {
@@ -15010,6 +15062,14 @@ function startAgentHeartbeatDaemon(entry, serve = null) {
   if (entry.persona) {
     args.push('--persona', entry.persona);
   }
+  // Declared coverage travels with the daemon, so a re-registration after a TTL lapse cannot silently
+  // widen a fleet member back to every indexed repository.
+  if (entry.coverage && Array.isArray(entry.coverage.roots) && entry.coverage.roots.length) {
+    args.push('--accounts', entry.coverage.roots.join(','));
+    if (entry.coverage.descendants === false) {
+      args.push('--no-descendants', 'true');
+    }
+  }
   if (serve) {
     args.push(
       '--serve', 'true',
@@ -15185,6 +15245,9 @@ async function releaseTicketClaim(context, agentId, ticket, options = {}) {
         accountId: Number(ticket.accountId),
         outcome: options.outcome || null,
         notes: options.notes || null,
+        // The run whose claim this is. The platform ignores the call when a NEWER run holds the claim, so
+        // a late exit callback cannot drop a restarted supervisor's claim or erase a handoff it routed.
+        runId: options.runId || null,
         release: options.release === true,
         unroute: options.unroute === true
       }).then((r) => r.data);
@@ -15455,6 +15518,7 @@ async function spawnTicketWorker(context, ctx, ticket) {
       // it back to the queue) once it has genuinely failed enough times and is still not terminal.
       const giveUp = !ok && attempt >= AGENT_WORKER_MAX_ATTEMPTS;
       const result = await releaseTicketClaim(context, agentId, { ticketId, accountId: ticket.accountId }, {
+        runId: ctx.runId,
         outcome: ok ? 'completed' : (signal ? 'killed' : 'failed'),
         release: giveUp,
         // A clean exit that left the ticket short of terminal is a DELIVERED judgement, not a failure —
@@ -15551,7 +15615,7 @@ async function agentHeartbeatDaemonCommand(flags) {
       const context = agentSessionFor(flags, { cwd, baseUrl: flags['base-url'] });
       for (const [ticketId, entry] of inFlight.entries()) {
         await releaseTicketClaim(context, agentId,
-          { ticketId, accountId: entry.accountId }, { outcome: 'supervisor_stopped' });
+          { ticketId, accountId: entry.accountId }, { outcome: 'supervisor_stopped', runId: ctx.runId });
       }
       await buildAxios(context.baseUrl, context.session.token, 5000)
         .post('/cli/agentDeregister', { agentId });
@@ -15691,6 +15755,8 @@ async function agentHeartbeatDaemonCommand(flags) {
             'max-concurrent': String(ctx.maxConcurrent),
             role: ctx.role || undefined,
             persona: ctx.persona || undefined,
+            accounts: flags.accounts || undefined,
+            'no-descendants': flags['no-descendants'] || undefined,
             json: 'true'
           },
           // Re-register with THIS supervisor's declared bound and queues. The platform treats an absent
@@ -15990,6 +16056,26 @@ async function ticketCommand(flags, subcommand) {
     idempotencyKey: flags['idempotency-key'] || flags.idempotencyKey || undefined,
     providerMessageId: flags['provider-message-id'] || undefined,
     reason: flags.reason,
+    // Explicit requests and decisions. A request id is short (R1, R2); `2`, `r2` and `#2` all work.
+    request: flags.request || undefined,
+    decision: flags.decision || flags._?.[3] || undefined,
+    requestAction: flags.for || flags['request-action'] || undefined,
+    approvers: flags.approvers ? String(flags.approvers).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
+    reviewers: flags.reviewers ? String(flags.reviewers).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
+    expiresAt: flags['expires-at'] || undefined,
+    delivery: flags.delivery || undefined,
+    // The revision a call acts on or a decision looked at: a patch digest, a staged snapshot, a version.
+    revision: flags.revision || undefined,
+    note: flags.note,
+    // Handoff: who should take the next step, and whether this agent must be kept off it (independence).
+    exclude: flagEnabled(flags.exclude) ? true : undefined,
+    reviewAction: flags['review-action'] || flags.review || undefined,
+    findings: flags.findings ? String(flags.findings).split('|').map((v) => v.trim()).filter(Boolean) : undefined,
+    // `complete` after new input arrived during this run: say you read it.
+    acknowledgeInput: flagEnabled(flags['acknowledge-input']) ? true : undefined,
+    // `deliver`: bind the request to one conversation entry, and hold it for a person's approval.
+    messageId: flags['message-id'] || undefined,
+    requireApproval: flagEnabled(flags['require-approval']) ? true : undefined,
     // Lease operations act as the AGENT, not the user: the lease is held by a worker session, and a
     // human's email is not a thing that can hold one. Inside a worker these come from the environment
     // the supervisor set, so the commands need no flags.
@@ -16688,9 +16774,27 @@ function printTicketHelp() {
   console.log('  accept                                Claim it as yours before you start work.');
   console.log('  status --status in_progress|pending_review');
   console.log('  progress --summary "..." [--category investigation|fix|verification|...] [--next-step "..."]');
-  console.log('  complete --resolution "what you found and did"');
-  console.log('  ask --question "..." [--context "..."] [--to WHO]');
-  console.log('      Put a decision to a human and park. Use it when the CHOICE is not yours.');
+  console.log('  complete --resolution "what you found and did" [--revision R] [--acknowledge-input]');
+  console.log('      Refused when new input arrived after your run started and you have not read it;');
+  console.log('      read the ticket, then pass --acknowledge-input if your resolution still stands.');
+  console.log('  ask --question "..." [--context "..."] [--to WHO] [--visibility internal]');
+  console.log('      Put a question to a human and park. Use it when the CHOICE is not yours. Recorded as');
+  console.log('      request R<n>; answering it resumes the work even if no worker is online right now.');
+  console.log('  request-approval --for ACTION [--revision R | --delivery ID] [--approvers a@x,b@y] [--summary "..."]');
+  console.log('      Ask a PERSON to authorize one action on one revision (promote a patch, send a message).');
+  console.log('      An answer is not an approval: only an authenticated person can decide it, never an');
+  console.log('      agent run, and a changed revision needs a new approval.');
+  console.log('  request-review --for ACTION --revision R [--reviewers ...]');
+  console.log('      Ask another worker or a person to review exactly this revision. You cannot review your own.');
+  console.log('  decide --request R2 --decision approve|reject|changes [--revision R] [--note "..."]');
+  console.log('      Decide an approval or review. Name the revision you looked at; a stale one is refused.');
+  console.log('  cancel-request --request R2 [--reason "..."]');
+  console.log('  handoff --summary "what the next worker should do" [--workstream review] [--exclude]');
+  console.log('          [--review-action promote --revision R] [--next-step "..."] [--findings "a|b"]');
+  console.log('      Hand the next step to another session (queued if nobody is online). --exclude keeps');
+  console.log('      YOU off it — use it for independent review. Your exit will not erase this handoff.');
+  console.log('  continue [--reason requested]          Queue the ticket for the automation to work again.');
+  console.log('  reset-budget                          OPERATOR: restore a ticket\'s run budget after looking at it.');
   console.log('  answer --message "..." [--route false]   (alias: reply)');
   console.log('      Answer the open question a previous run asked. By default this re-routes the ticket,');
   console.log('      so a fresh worker resumes with your answer already in its brief. This is NOT how you');
@@ -16699,11 +16803,13 @@ function printTicketHelp() {
   console.log('  message --message "..." [--to a@x,b@y] [--subject "..."] [--channel email]');
   console.log('      A PUBLIC conversation entry the requester reads. Writing it does not send it:');
   console.log('      the record is vendor-agnostic and the account\'s own rule chooses the transport.');
-  console.log('  deliver --channel email --to a@x [--template T] [--subject "..."] [--idempotency-key K]');
+  console.log('  deliver --channel email --to a@x [--message-id M] [--require-approval] [--subject "..."] [--idempotency-key K]');
   console.log('      Ask for that entry to actually be SENT. It records an outbox request; an account-owned');
   console.log('      rule or scheduled Action delivers it and marks the result. Use it when a ticket is');
   console.log('      waiting on somebody who is not watching the queue.');
   console.log('  deliveries [--channel email]          What is queued to go out, and what already went.');
+  console.log('      Senders take a delivery exclusively (claimDelivery) before sending; a failure retries');
+  console.log('      with backoff; an "uncertain" or "blocked" one waits for a person to reconcile it.');
   console.log('  delivered --delivery-id ID  |  delivery-failed --delivery-id ID --reason "..."');
   console.log('  release [--notes "..."]               Hand it back to the queue.');
   console.log('  reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]');

package/package.json

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

package/skills/remits-cli/references/agent-sessions.md

@@ -26,6 +26,7 @@ independent of everything else — no background service is required, and every
 
 ```bash
 remits-cli agent serve               # routable AND autonomously working tickets — the usual choice
+remits-cli agent serve --accounts 33 # ...bounded to account 33 and its descendants
 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

package/skills/remits-cli/references/support-tickets.md

@@ -12,6 +12,7 @@
   - [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)
   - [Serving only some workstreams](#serving-only-some-workstreams)
+  - [Serving only some accounts](#serving-only-some-accounts)
   - [The manual loop](#the-manual-loop)
   - [If you are the worker](#if-you-are-the-worker)
   - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
@@ -24,6 +25,7 @@
   - [Agent components are workers too](#agent-components-are-workers-too)
   - [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)
+  - [Approvals, reviews and handing work on](#approvals-reviews-and-handing-work-on)
 
 ## Support Ticket Mental Model
 
@@ -155,6 +157,22 @@ than quietly overriding the declaration —
 **So after specialising a fleet, run `remits-cli agent map`** and confirm every workstream the
 account ingests is covered by something.
 
+### Serving only some accounts
+
+Without a bound, a session claims **every account repository indexed on this machine**. `--accounts`
+bounds it to named roots and their descendants:
+
+```bash
+remits-cli agent serve --accounts 33                 # account 33 and everything beneath it
+remits-cli agent serve --accounts 33,52 --no-descendants
+```
+
+`--account-id` only chooses which session context a command uses; it is not coverage. The registration
+output prints the coverage the platform **accepted** — check it before leaving a production supervisor
+running. The bound survives heartbeat re-registration. Only use it when the user asked for a bounded
+fleet member, and never register a production worker merely to look at configuration: registering makes
+the session routable.
+
 ### The manual loop
 
 Only when the session registered with `agent register` rather than `agent serve`.
@@ -542,6 +560,38 @@ Inside an autonomous worker `--ticket` defaults to the ticket that worker was la
 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.
 
+An answer resumes the work **even if no worker is online when it arrives**: the ticket records queued work
+(`pendingWork`) and the next eligible worker takes it, whatever its status and owner. Each question is a
+request with a short id (`R1`); answer a specific one with `ticket answer --request R1 --message "..."`.
+If new input arrives while you are working, `ticket complete` is refused and quotes it — read it, then
+complete with `--acknowledge-input` if your resolution still stands.
+
+### Approvals, reviews and handing work on
+
+An answer is not an authorization. When a person must **authorize** something — promoting a patch, a
+production data change, sending a sensitive message — request an approval bound to the exact revision:
+
+```bash
+remits-cli ticket request-approval --for promote --revision <patch-digest> --summary "what and why"
+remits-cli ticket request-approval --for deliver --delivery <delivery-id>     # approve exactly that message
+```
+
+You cannot decide it — a person does, with `remits-cli ticket decide --request R2 --decision approve
+--revision <rev>`. A changed patch needs a new approval. Record verification against the revision with
+`ticket progress --category verification --revision <rev>`; an account rule may require exactly that.
+
+When somebody else should do the next step — independent review, a different workstream:
+
+```bash
+remits-cli ticket handoff --summary "fix staged in ticket-19463; needs independent review" \
+  --workstream review --exclude --review-action promote --revision <patch-digest> \
+  --next-step "review the patch against the reported case"
+```
+
+The handoff is queued even if nobody is online, `--exclude` keeps you off it (independent review needs
+that), and your own exit will not undo it. A reviewer decides with `ticket decide --request R3 --decision
+approve|changes|reject --revision <rev>`; "changes" sends the work back with the reviewer's note.
+
 **`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