@remits/remits-cli 0.1.165 → 0.1.167

package/README.md

@@ -101,7 +101,8 @@ remits-cli install --skills --overwrite true
 - Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
 - Active verification envelopes are scoped per `baseUrl + accountId + branch + workspace + dataMode`, so a localhost envelope does not silently capture evidence from a production command. Pass `--verify-envelope <id>` for an intentional cross-context attachment.
 - `--base-url` and `--data-mode` are independent. `--base-url` chooses the Remits host (`http://localhost:8080` vs deployed prod), while `--data-mode` chooses the data segment on that host (`test` vs `prod`). Do not assume `--data-mode prod` means the deployed prod host, or that `--data-mode test` means localhost.
-- `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
+- `remits-cli start` scans for `account-info.json` files and updates `~/.remits-cli/account-repos.json` before bringing up the background service. While running, it rescans every five minutes using asynchronous directory reads, then reports the refreshed inventory to the platform. Repos cloned outside the CLI are discovered without a restart or a command run inside them. Both scans use `REMITS_CLI_SCAN_ROOTS` (default: the home directory), the same depth limit and directory exclusions. For immediate discovery, use `remits-cli agent repos --rescan` or **Rescan Account Repos** in the control center.
+- Scans preserve manually selected repository directories and record competing checkouts as ambiguity. `remits-cli agent repos --account-id <id> --forget` suppresses rediscovery until an explicit registration (`--directory <path>`) or a CLI command run from that account repo restores it.
 - Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/front-stage/remits-components-zip-readme.md`).
 - Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
 - On every command, `remits-cli` refreshes the installed remits-cli `SKILL.md` and reference files for `claude`, `codex`, `gemini`, and `antigravity` so local agents stay on the latest packaged instructions.

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- L125  Sessions, Account Resolution, And Production Guards
-- L631  Local State, Workspaces, And Verification Evidence
-- L2669  Account Repos, Guide Sync, And Platform Repo
-- L3509  Component Discovery And HTTP Logging
-- L4279  Skill Delivery And TOC Resolution
-- L4594  Auth And Component Staging
-- L5226  Component Summaries, Status, And Sync Gates
-- L7550  Branches, Promotion, Commit, And Test Runs
-- L9813  Tokens, Tools, Verification, And Config
-- L11330  Service Dashboard And WebSocket Listener
-- L13840  Agent And Ticket Workflows
-- L18101  Help, Auto Update, And Command Dispatch
+- L126  Sessions, Account Resolution, And Production Guards
+- L632  Local State, Workspaces, And Verification Evidence
+- L2670  Account Repos, Guide Sync, And Platform Repo
+- L3569  Component Discovery And HTTP Logging
+- L4339  Skill Delivery And TOC Resolution
+- L4654  Auth And Component Staging
+- L5286  Component Summaries, Status, And Sync Gates
+- L7610  Branches, Promotion, Commit, And Test Runs
+- L9873  Tokens, Tools, Verification, And Config
+- L11390  Service Dashboard And WebSocket Listener
+- L13900  Agent And Ticket Workflows
+- L18308  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -75,6 +75,7 @@ const DASHBOARD_HOST = '127.0.0.1';
 const DEFAULT_DASHBOARD_PORT = Number(process.env.REMITS_CLI_DASHBOARD_PORT || 8787);
 const DEFAULT_SCAN_MAX_DEPTH = Number(process.env.REMITS_CLI_SCAN_MAX_DEPTH || 8);
 const SERVICE_MAINTENANCE_INTERVAL_MS = Number(process.env.REMITS_CLI_SERVICE_MAINTENANCE_INTERVAL_MS || 15000);
+const ACCOUNT_REPO_RESCAN_INTERVAL_MS = 5 * 60 * 1000;
 const WEBSOCKET_RECONNECT_DELAY_MS = Number(process.env.REMITS_CLI_WEBSOCKET_RECONNECT_DELAY_MS || 5000);
 const WEBSOCKET_HEARTBEAT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_HEARTBEAT_MS || 10000);
 const WEBSOCKET_CONNECTION_TIMEOUT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_CONNECTION_TIMEOUT_MS || 15000);
@@ -3253,7 +3254,8 @@ function countAccountRepos(index) {
  */
 function mergeAccountRepoEntries(entries, options = {}) {
   const nextIndex = options.existingIndex ? { ...options.existingIndex } : {};
-  const rank = (entry) => (isAccountCheckout(entry.directory) ? 2 : 0) + (entry.source === 'cwd' ? 1 : 0);
+  const sourceRank = (entry) => entry.source === 'manual' ? 2 : (entry.source === 'cwd' ? 1 : 0);
+  const rank = (entry) => (isAccountCheckout(entry.directory) ? 3 : 0) + sourceRank(entry);
 
   for (const entry of entries) {
     if (!entry || !entry.accountId || !entry.directory) {
@@ -3261,8 +3263,15 @@ function mergeAccountRepoEntries(entries, options = {}) {
     }
     const key = String(entry.accountId);
     const current = nextIndex[key];
+    // Forget is an explicit opt-out, not a temporary absence until the next service scan.
+    if (current && current.source === 'forgotten' && entry.source === 'scan') continue;
     if (!current || !current.directory || current.directory === entry.directory) {
-      nextIndex[key] = { ...entry, ambiguousWith: (current && current.ambiguousWith) || [] };
+      nextIndex[key] = {
+        ...entry,
+        source: current && current.directory === entry.directory && sourceRank(current) > sourceRank(entry)
+          ? current.source : entry.source,
+        ambiguousWith: (current && current.ambiguousWith) || []
+      };
       continue;
     }
 
@@ -3305,19 +3314,17 @@ function defaultAccountScanRoots() {
   return [home].filter((dir) => fs.existsSync(dir));
 }
 
-function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+// Share traversal rules between the synchronous command path and asynchronous service scans.
+// The driver supplies directory entries so the service never blocks its WebSocket on readdirSync.
+function* accountRepoScanSteps(dir, depth, matches, visited, platformMatches) {
   const resolvedDir = path.resolve(dir);
   if (visited.has(resolvedDir)) {
     return;
   }
   visited.add(resolvedDir);
 
-  let entries;
-  try {
-    entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
-  } catch (_) {
-    return;
-  }
+  const entries = yield resolvedDir;
+  if (!entries) return;
 
   const names = new Set(entries.map((entry) => entry.name));
   for (const entry of entries) {
@@ -3347,7 +3354,17 @@ function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
     if (entry.name.startsWith('.') && entry.name !== '.config') {
       continue;
     }
-    walkForAccountInfo(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+    yield* accountRepoScanSteps(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+  }
+}
+
+function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+  const steps = accountRepoScanSteps(dir, depth, matches, visited, platformMatches);
+  let step = steps.next();
+  while (!step.done) {
+    let entries = null;
+    try { entries = fs.readdirSync(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+    step = steps.next(entries);
   }
 }
 
@@ -3359,7 +3376,29 @@ function discoverAccountRepos() {
   for (const root of roots) {
     walkForAccountInfo(root, 0, matches, visited, platformMatches);
   }
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches);
+}
 
+async function discoverAccountReposInBackground() {
+  const matches = [];
+  const platformMatches = [];
+  const visited = new Set();
+  const roots = defaultAccountScanRoots();
+  for (const root of roots) {
+    const steps = accountRepoScanSteps(root, 0, matches, visited, platformMatches);
+    let step = steps.next();
+    while (!step.done) {
+      let entries = null;
+      try { entries = await fs.promises.readdir(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+      step = steps.next(entries);
+    }
+  }
+  // Read the latest index only at reconciliation: CLI commands may register a repo during the scan.
+  // Background maintenance discovers existing files; it must never clone or pull repositories.
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches, { background: true });
+}
+
+function reconcileDiscoveredAccountRepos(roots, matches, platformMatches, options = {}) {
   const entries = [];
   for (const file of matches) {
     try {
@@ -3380,7 +3419,7 @@ function discoverAccountRepos() {
     const found = platformMatches.find(looksLikePlatformRepo);
     if (found) {
       setPlatformRepoEntry(found, 'scan');
-    } else {
+    } else if (!options.background) {
       try { ensurePlatformRepoLocal({ allowClone: true }); } catch (_) { /* best-effort */ }
     }
   }
@@ -3395,6 +3434,27 @@ function discoverAccountRepos() {
   };
 }
 
+let accountRepoDiscoveryInFlight = null;
+let lastAccountRepoDiscoveryAttemptAt = 0;
+
+function refreshAccountReposIfDue(now = Date.now()) {
+  if (accountRepoDiscoveryInFlight) return accountRepoDiscoveryInFlight;
+  const lastScanAt = Date.parse(runtimeState.discovery.scannedAt || '') || 0;
+  if (now - Math.max(lastScanAt, lastAccountRepoDiscoveryAttemptAt) < ACCOUNT_REPO_RESCAN_INTERVAL_MS) return;
+  lastAccountRepoDiscoveryAttemptAt = now;
+  accountRepoDiscoveryInFlight = discoverAccountReposInBackground()
+    .then((summary) => {
+      recordDiscoverySummary(summary);
+      // Publish the refreshed inventory on the next maintenance tick, even if presence isn't due yet.
+      for (const managedClient of managedClients) managedClient.lastPresenceAt = 0;
+    })
+    .catch((err) => {
+      appendGlobalActivityLog('listener', 'repos.discovery.failed', { error: describeError(err) }, 'error');
+    })
+    .finally(() => { accountRepoDiscoveryInFlight = null; });
+  return accountRepoDiscoveryInFlight;
+}
+
 function resolvePreferredAccountId(cwd, flags, session) {
   // Explicit --account-id wins over the repo's account-info.json so users can
   // target a child account (e.g. a customer) from a parent-account repo.
@@ -14553,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,
@@ -14602,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(
@@ -14638,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),
@@ -14673,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,
@@ -14714,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) {
@@ -14950,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',
@@ -15125,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);
@@ -15395,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 —
@@ -15491,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 });
@@ -15631,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
@@ -15911,6 +16037,7 @@ async function ticketCommand(flags, subcommand) {
     requiresRepositoryWork: firstDefined(flags['repo-work'], flags['requires-repository-work']),
     tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
     label: flags.label,
+    ...(action === 'artifact' ? ticketArtifactFields(flags) : {}),
     url: flags.url,
     body: flags.body,
     role: flags.role,
@@ -15929,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.
@@ -16627,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');
@@ -16638,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]');
@@ -16656,7 +16823,7 @@ function printTicketHelp() {
   console.log('  tag --tags a,b                        Mark it, for a HUMAN reading the queue. When the');
   console.log('      tickets genuinely share a cause, use `relate` instead or as well: the platform reads');
   console.log('      that one, and a tag it cannot read will not stop a cluster being worked N times.');
-  console.log('  artifact --type TYPE --label "..." [--url U | --content "..."]');
+  console.log('  artifact --type TYPE --label "..." (--content "..." | --file PATH | --url U) [--filename F] [--content-type T]');
   console.log('      Attach evidence — a log, a query result, a repro. Better than pasting it into a');
   console.log('      worklog summary, where it is neither typed nor retrievable.');
   console.log('  note --message "..."                  An INTERNAL note. The next worker and a reviewer');
@@ -16701,6 +16868,44 @@ function printTicketHelp() {
  * One helper so the lease, the claim and the registration cannot describe this process three ways —
  * the same reason the platform builds the tuple in exactly one class (AgentRunContext).
  */
+/**
+ * The evidence half of `ticket artifact`. Bytes always travel as `contentBase64`: it is the one form every
+ * deployed platform accepts (JSON cannot carry a byte[], and older platforms ignored a `content` string), so
+ * `--content "text"` and `--file path` behave the same against every host. The help promised `--type` and
+ * `--content` for a long time while neither was sent, and every artifact was refused as `type [null]`; the
+ * refusals here name the missing flag before anything reaches the platform.
+ */
+function ticketArtifactFields(flags = {}, readFile = (p) => fs.readFileSync(p)) {
+  const text = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+  const type = text(flags.type);
+  if (!type) {
+    throw new Error('ticket artifact needs --type (screenshot, pdf, trace, video, log, test_result, link or other).');
+  }
+  if (!text(flags.label)) {
+    throw new Error('ticket artifact needs --label "...".');
+  }
+  const fields = { type, filename: text(flags.filename), contentType: text(flags['content-type'] || flags.contentType) };
+  const filePath = text(flags.file);
+  const content = typeof flags.content === 'string' ? flags.content : undefined;
+  if (filePath) {
+    const bytes = readFile(filePath);
+    fields.contentBase64 = Buffer.from(bytes).toString('base64');
+    fields.filename = fields.filename || path.basename(filePath);
+    if (!fields.contentType) {
+      const ext = path.extname(filePath).toLowerCase();
+      fields.contentType = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.pdf': 'application/pdf',
+        '.json': 'application/json', '.zip': 'application/zip', '.webm': 'video/webm', '.html': 'text/html',
+        '.md': 'text/markdown', '.txt': 'text/plain', '.log': 'text/plain' })[ext];
+    }
+  } else if (content !== undefined) {
+    fields.contentBase64 = Buffer.from(content, 'utf8').toString('base64');
+    fields.contentType = fields.contentType || 'text/plain; charset=utf-8';
+  } else if (!text(flags.url)) {
+    throw new Error('ticket artifact needs something to attach: --content "...", --file PATH or --url URL.');
+  }
+  return fields;
+}
+
 function runContextPayload(flags = {}) {
   const cwd = process.cwd();
   return {
@@ -17504,7 +17709,7 @@ async function agentReposCommand(flags) {
   if (Number.isFinite(accountId) && accountId > 0 && flagEnabled(flags.forget)) {
     const index = readAccountRepoIndex();
     const previous = index[String(accountId)];
-    delete index[String(accountId)];
+    index[String(accountId)] = { accountId, source: 'forgotten', updatedAt: new Date().toISOString() };
     writeAccountRepoIndex(index);
     console.log(previous
       ? 'account ' + accountId + ' removed (was ' + previous.directory + '). Its tickets will now park ' +
@@ -18012,6 +18217,8 @@ async function listenCommand(flags) {
         activeSessionSignature = currentSignature;
       }
 
+      // Do not await the filesystem scan: a slow/unavailable volume must not stall socket upkeep.
+      refreshAccountReposIfDue();
       await runManagedWebsocketWatchdog();
       updateRuntimeServiceState();
     } catch (err) {

package/package.json

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

@@ -96,6 +96,13 @@ reference named after it.
   "branch" or "verified"; say what was actually proven: Test pass, browser journey, corpus measurement,
   sync mutation, or ticket lifecycle state. (`component-resolution.md`, `branch-variants.md`,
   `development-loop.md`, `support-tickets.md`)
+- **There are no environments to deploy to, so translate SDLC words before acting.** "Let me try it" means a
+  token link to your staged lane. "Put it in UAT" means a sync to the pre-production component branch, or
+  a link if UAT is a link on this account. "Push to prod" means the promotion loop. "Roll it back" means
+  `git revert` plus a sync, and it does not undo emails or external writes. People who simply sign in never
+  see staged code. Syncing a branch others use, every promotion gate, and a trunk edit on a release-train
+  account each need the person's go for that step. (the account repo's core platform guide → *How A Change Reaches People*,
+  `branch-variants.md`)
 - **Embeddable verification is browser verification.** For page, widget, form, upload, or other
   browser-facing changes, mint a URL with `remits-cli token` and drive it with `playwright-cli`.
   Prefer this over `curl`: `curl` can prove an HTTP response or inspect an action payload, but it does

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/cli-state.md

@@ -114,7 +114,7 @@ Agents should use this mental model before guessing.
 
 The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
 
-This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
+This JSON file is automatically maintained by `remits-cli` and tracks known Remits account repositories on this machine. It is updated when a CLI command runs from an account repo directory, at service startup, and by background discovery every five minutes while the service runs. Background scans use the same configured roots, depth limit and exclusions as startup; they report newly discovered repos to the platform without restarting. Use `remits-cli agent repos --rescan` for immediate discovery. The file maps account IDs to their metadata:
 
 ```json
 {
@@ -133,6 +133,8 @@ This JSON file is automatically maintained by `remits-cli` and tracks all known
 - Resolve account names and IDs without making remote API calls
 - Support cross-account workflows where an agent in one repo needs context from another
 
+Manual directory selections survive rescans; competing checkouts are recorded as ambiguity. `agent repos --account-id <id> --forget` stores an opt-out without a directory, so scans do not silently restore it. Explicitly register a directory or run a CLI command from that repo to restore registration.
+
 If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
 
 ## Local State Files

package/skills/remits-cli/references/command-reference.md

@@ -234,7 +234,7 @@ remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [-
 remits-cli ticket deliveries --ticket ID [--channel email]   # what is queued to go out, and what already went
 remits-cli ticket delivered --ticket ID --delivery-id ID | ticket delivery-failed --ticket ID --delivery-id ID --reason "..."
 remits-cli ticket tag --ticket ID --tags a,b           # make a cluster of near-identical tickets visible as one
-remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --content "..."]
+remits-cli ticket artifact --ticket ID --type TYPE --label "..." (--content "..." | --file PATH | --url U)
 remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
 remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
 remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket

package/skills/remits-cli/references/development-loop.md

@@ -808,3 +808,11 @@ Some users want to review every change before staging. Others want you to move f
 - If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
 
 The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.
+
+**Four steps always need the person's go for that step, whatever they said earlier:**
+- syncing a component branch that a pre-production or client account uses;
+- each promotion gate (`features/subscriber-branch-promotions.md` → *The three approval gates*);
+- unsubscribing an account or retiring a branch;
+- editing trunk on an account that runs a release-train branch.
+
+A general "just do it" covers staging and verifying, not these. Each one changes what live accounts run.

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

package/skills/remits-cli/references/tool-reference.md

@@ -32,6 +32,7 @@
   - [Component branches](#component-branches)
   - [`mcp_cache`](#mcp_cache)
   - [`mcp_sql_query`](#mcp_sql_query)
+  - [`mcp_usage`](#mcp_usage)
   - [`mcp_index_search`](#mcp_index_search)
   - [`mcp_get_guide`](#mcp_get_guide)
   - [`mcp_test_fixture`](#mcp_test_fixture)
@@ -931,6 +932,30 @@ SELECT u.id, u.username, u.enabled FROM user u
 Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
 resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
 
+### `mcp_usage`
+Administrator-only usage reports and configuration through the platform's `usageControl` API. The
+System Account owns this global tool; deploy the platform API before staging or syncing its wrapper.
+
+| Parameter | Description |
+|---|---|
+| `operation` | `status` (default), `report`, `gaps`, `savePrice`, `replacePrice`, `endPrice`, `saveBillingMap`, `deleteBillingMap`, `saveManualCharge`, `deleteManualCharge`, `configure`, `runSettle`, `runBilling`, `flushMeter` |
+| `query` | `usage(...)` selectors for reports/gaps: dates, accountId, includeDescendants, lanes, includeSuites, grouping. Omit accountId for platform scope. |
+| `values` | Rate, mapping, charge or settings fields; status lists supported units and allowed settings. `replacePrice` requires the old id and full successor rate. |
+| `apply` | `false` by default: mutations return their normalized plan. `true` applies the authorized change. Configuration is platform-wide, independently of the test/prod data selector. |
+
+Read `status.pricingNotes` first. Rates start at future UTC hour boundaries; overlapping or historical
+changes are refused. Use `replacePrice` for an atomic rate change. Do not price a storage byte counter
+as byte-months or wall time as billed CPU time. `gaps` returns account/provider/model grouping so exact
+missing rate keys are visible. Shared platform overhead is excluded from account hierarchies.
+Provider invoices and estimates remain separate when filters do not match invoice scope.
+
+```bash
+remits-cli tool --name mcp_usage --input '{"operation":"status"}'
+remits-cli tool --name mcp_usage --input '{"operation":"report","query":{"accountId":41,"includeDescendants":true,"from":"2026-10-01"}}'
+```
+
+The full field contract and examples are in `features/usage-and-cost.md` → Configuring usage through MCP.
+
 ### `mcp_index_search`
 Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
 RAG/search-backed component actually retrieves before blaming the component.

package/skills/remits-cli/references/troubleshooting.md

@@ -62,7 +62,7 @@
 | 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. |
 | 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 |
+| Dashboard or GitHub menu missing local repos | The running service rediscovers repos every five minutes. Use `remits-cli agent repos --rescan` or the control center rescan action for immediate discovery; allow the next presence update (normally within 30 seconds). Check scan roots if still absent. A forgotten account needs explicit registration with `agent repos --account-id <id> --directory <path>`. |
 | 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. |
 
 ### When Something Doesn't Work as Expected