@remits/remits-cli 0.1.166 → 0.1.168

package/README.md

@@ -90,6 +90,7 @@ remits-cli install --skills --overwrite true
 - `components clear` clears staged entries. Scope it with `--component-type` and/or `--component-id`. Component ids are type-local, so an id alone clears that one component when the id is staged in only one family; if the same id is staged across multiple families it returns an ambiguity error asking you to add `--component-type`. With no filter it clears every staged entry for the current branch; pass `--all` to force the full-branch wipe explicitly.
 - `components stage`, `components status`, `components lanes`, `components entries`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
 - `activity inspect` is a read-only workstream view for operator/agent review. It joins staging lanes, verification envelopes, Test runs, corpus measurements, live agent presence, and heuristic smell signals. Use `--scope children` from a platform/root account and `--user-email` or `--user-id` to focus on one CLI user.
+- System → Activity captures CLI requests under the authenticated user. Declare an interactive agent with `REMITS_AGENT_ID` or `--agent-id`; supervised workers already carry agent/run/ticket identity. The page distinguishes declared agents, browser activity, and CLI calls without declared agent identity. `--local-agent` only chooses a local log folder. Request labels describe intent, not a background job's completion, and local edits between platform calls are not observed.
 - `components stage` and `components status` report three separate numbers, and they answer three different questions: the **workset** (components git reports this working tree changed), what was **submitted**, and the materialized **overlay** the lane now holds — which is what a run resolves. A number that could not be established prints as `unknown`, never as `0`.
 - `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
 - On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json`, `account-hierarchy.json`, and `account-configurations.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. Add `--summary` to dry-run output when you only need counts, removals/tombstones, errors, skipped items, and warnings. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- 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
-- L18202  Help, Auto Update, And Command Dispatch
+- L128  Sessions, Account Resolution, And Production Guards
+- L634  Local State, Workspaces, And Verification Evidence
+- L2672  Account Repos, Guide Sync, And Platform Repo
+- L3571  Component Discovery And HTTP Logging
+- L4350  Skill Delivery And TOC Resolution
+- L4665  Auth And Component Staging
+- L5301  Component Summaries, Status, And Sync Gates
+- L7625  Branches, Promotion, Commit, And Test Runs
+- L9889  Tokens, Tools, Verification, And Config
+- L11406  Service Dashboard And WebSocket Listener
+- L13916  Agent And Ticket Workflows
+- L18429  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -34,6 +34,8 @@ const { Client } = require('@stomp/stompjs');
 const WebSocket = require('ws');
 const { installWebsocketRetry } = require('./lib/websocket-retry');
 const YAML = require('yaml');
+// Invocation identity is separate from the local log-folder actor and staging workspace.
+let requestIdentityFlags = {};
 
 Object.assign(global, { WebSocket });
 const openBrowser = (openModule && typeof openModule === 'function')
@@ -4044,7 +4046,7 @@ function stageTimeoutMs(components, flags = {}) {
   return Math.min(600000, Math.max(60000, Math.round(60000 + (megabytes * 60000))));
 }
 
-function buildAxios(baseUrl, token, timeoutMs = 60000) {
+function cliRequestHeaders(token) {
   const headers = token ? { Authorization: 'Bearer ' + token } : {};
   // The CLI version on EVERY request, from the one place every request is built. It used to travel only on
   // `agent register`, so the platform knew the version of the sessions that registered - and the agents that
@@ -4055,10 +4057,19 @@ function buildAxios(baseUrl, token, timeoutMs = 60000) {
   // A worker's run identity rides on every call, so a verb whose payload does not repeat it (stage, commit,
   // a tool) is still attributed to the run. The ROLE is deliberately not sent: the platform reads it from
   // the session's registration, where the user's permission to declare it was checked.
-  if (process.env.REMITS_AGENT_ID) headers['X-Remits-Agent-Id'] = process.env.REMITS_AGENT_ID;
+  // ticket route historically accepts --agent-id as the TARGET; it is not the caller.
+  const targetAgent = requestIdentityFlags._?.[0] === 'ticket' && ['route', 'unroute'].includes(requestIdentityFlags._?.[1]);
+  const rawAgentFlag = requestIdentityFlags['agent-id'] || requestIdentityFlags.agentId;
+  const flagAgent = typeof rawAgentFlag === 'string' ? rawAgentFlag.trim() : '';
+  const agentId = (!targetAgent && flagAgent) || process.env.REMITS_AGENT_ID;
+  if (typeof agentId === 'string' && agentId.trim()) headers['X-Remits-Agent-Id'] = agentId.trim();
   if (process.env.REMITS_WORKER_RUN_ID) headers['X-Remits-Run-Id'] = process.env.REMITS_WORKER_RUN_ID;
   if (process.env.REMITS_SUPPORT_TICKET_ID) headers['X-Remits-Ticket-Id'] = process.env.REMITS_SUPPORT_TICKET_ID;
-  return axios.create({ baseURL: baseUrl, timeout: parsePositiveInt(timeoutMs, 60000), headers });
+  return headers;
+}
+
+function buildAxios(baseUrl, token, timeoutMs = 60000) {
+  return axios.create({ baseURL: baseUrl, timeout: parsePositiveInt(timeoutMs, 60000), headers: cliRequestHeaders(token) });
 }
 
 function describeError(err) {
@@ -4988,6 +4999,10 @@ async function pushComponentsCommand(flags) {
     ...runContextPayload(flags),
     agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
     acknowledge: flags.acknowledge || undefined,
+    // `commit` when this stage is the pre-push check of `components commit`: the platform then judges it as a
+    // LANDING (the account's committed `commit`-point rules, component rules included), so a refusal
+    // arrives before anything is pushed instead of after.
+    intent: flags.intent || undefined,
     // What this stage IS, stated rather than implied. The server derives the lane behavior from the mode
     // (CliComponentStaging.stageRequest) instead of from `replace`, which was overloaded: a partial
     // manifest with `replace: true` would make the reconcile pass delete nearly the whole lane, so
@@ -8073,7 +8088,7 @@ async function commitComponentsCommand(flags) {
   };
   try {
   if (!skipGit) {
-    emit('Phase 1/4: staged compile validation');
+    emit('Phase 1/4: staged compile validation and landing policy check');
     // MERGE semantics on purpose (`--changed-only`, never `--workset`). A workset stage RECONCILES the
     // lane — it deletes every entry outside the git changed set — and the lane is frequently shared. A
     // validation pass must not be able to delete another agent's staged work as a side effect of somebody
@@ -8085,7 +8100,8 @@ async function commitComponentsCommand(flags) {
       workset: false,
       'replace-lane': false,
       replaceLane: false,
-      'changed-only': true
+      'changed-only': true,
+      intent: 'commit'
     })));
 
     outcome.phase = 'git';
@@ -14613,8 +14629,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 +14720,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 +14757,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 +14793,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 +14835,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 +15078,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',
@@ -15174,6 +15250,84 @@ async function postWorkerSummary(context, agentId, ticket, summaryFile, options
   }
 }
 
+/**
+ * What a worker run cost, read from its own JSONL transcript — the only place a local model's spend is
+ * visible. A Claude run's `result` event carries `total_cost_usd` and token usage; a Codex run's
+ * `turn.completed` events carry token usage and no price. Returns null when the transcript says nothing,
+ * so an unknown cost is reported as unknown rather than as zero.
+ */
+function workerRunUsage(text) {
+  let usd = null;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let sawTokens = false;
+  String(text || '').split('\n').forEach((line) => {
+    let event;
+    try { event = JSON.parse(line.trim()); } catch (_) { return; }
+    if (!event || typeof event !== 'object') return;
+    if (event.type === 'result') {
+      if (typeof event.total_cost_usd === 'number') usd = event.total_cost_usd;
+      if (event.usage) {
+        inputTokens = Number(event.usage.input_tokens || 0) + Number(event.usage.cache_read_input_tokens || 0) +
+          Number(event.usage.cache_creation_input_tokens || 0);
+        outputTokens = Number(event.usage.output_tokens || 0);
+        sawTokens = true;
+      }
+    } else if (event.type === 'turn.completed' && event.usage) {
+      inputTokens += Number(event.usage.input_tokens || 0);
+      outputTokens += Number(event.usage.output_tokens || 0);
+      sawTokens = true;
+    }
+  });
+  if (usd === null && !sawTokens) return null;
+  return { usd, inputTokens: sawTokens ? inputTokens : null, outputTokens: sawTokens ? outputTokens : null };
+}
+
+/**
+ * The identity a worker attempt's cost is reported under. The platform keeps ONE report per identity (a
+ * re-sent report replaces itself), so it must be unique per ATTEMPT, not per supervisor: the supervisor's
+ * run id is constant for its whole life, and reusing it made each retry overwrite the previous attempt's
+ * spend. The attempt's transcript file is unique per spawn and stable for that attempt, which is exactly
+ * the identity a retried report must keep.
+ */
+function workerCostReportId(runId, logFile) {
+  return String(runId || 'run') + ':' + path.basename(String(logFile || 'attempt'), '.log');
+}
+
+/** Report a finished run's cost onto its ticket. Best-effort: a lost report under-counts, never fails a run. */
+async function reportWorkerCost(context, agentId, ticket, logFile, runId, agentType) {
+  let usage = null;
+  try {
+    usage = workerRunUsage(fs.readFileSync(logFile, 'utf8'));
+  } catch (_) {
+    return false;
+  }
+  if (!usage || !runId) return false;
+  try {
+    await buildAxios(context.baseUrl, context.session.token, 20000)
+      .post('/cli/ticket', {
+        action: 'cost',
+        ticketId: ticket.ticketId || ticket.id,
+        accountId: Number(ticket.accountId) || undefined,
+        dataMode: context.dataMode,
+        agentId,
+        runId,
+        costRunId: workerCostReportId(runId, logFile),
+        usd: usage.usd,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        provider: agentType || undefined,
+        costSource: 'remits-cli-worker'
+      });
+    return true;
+  } catch (err) {
+    appendGlobalActivityLog('agent', 'worker.cost_post_failed', {
+      agentId, ticketId: ticket.ticketId || ticket.id, error: describeError(err)
+    }, 'error');
+    return false;
+  }
+}
+
 /** Drop a claim on the platform. Best-effort: the claim expires on its own if this never lands. */
 async function releaseTicketClaim(context, agentId, ticket, options = {}) {
   try {
@@ -15185,6 +15339,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);
@@ -15454,7 +15611,10 @@ async function spawnTicketWorker(context, ctx, ticket) {
       // zero having done nothing. So the TICKET decides — unclaim always, and only give up (release
       // 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;
+      // Spend first, while this run still holds the claim it is reported against.
+      await reportWorkerCost(context, agentId, { ticketId, accountId: ticket.accountId }, logFile, ctx.runId, agentType);
       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 +15711,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 +15851,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 +16152,43 @@ 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,
+    // N-of-M: how many distinct people must approve before the request is approved.
+    minApprovals: flags['min-approvals'] ? Number(flags['min-approvals']) : undefined,
+    delivery: flags.delivery || undefined,
+    // `wake`: a durable timer. `--at` an instant, `--in` minutes, `--cancel` to clear it.
+    wakeAt: action === 'wake' ? (flags.at || undefined) : undefined,
+    wakeInMinutes: action === 'wake' && flags.in ? Number(flags.in) : undefined,
+    cancel: action === 'wake' && flagEnabled(flags.cancel) ? true : undefined,
+    // `depends-on`: the tickets this one waits on. The flag with no value clears them.
+    dependsOn: action === 'depends-on'
+      ? (flags.tickets === true || flags.tickets === '' ? [] : (flags.tickets ? String(flags.tickets).split(',').map((v) => v.trim()).filter(Boolean) : undefined))
+      : undefined,
+    // `cost`: what a run cost, reported by whoever can see it (a launcher, a person).
+    usd: action === 'cost' && flags.usd !== undefined ? Number(flags.usd) : undefined,
+    inputTokens: action === 'cost' && flags['input-tokens'] ? Number(flags['input-tokens']) : undefined,
+    outputTokens: action === 'cost' && flags['output-tokens'] ? Number(flags['output-tokens']) : undefined,
+    model: action === 'cost' ? (flags.model || undefined) : undefined,
+    provider: action === 'cost' ? (flags.provider || undefined) : undefined,
+    costRunId: action === 'cost' ? (flags['cost-run-id'] || undefined) : 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 +16887,35 @@ 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] [--min-approvals N] [--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 and spend budget after looking at it.');
+  console.log('  wake --in MINUTES | --at ISO-TIME [--reason "..."]   |   wake --cancel');
+  console.log('      A durable timer: when it is due the ticket is runnable work again (reason `timer`) and');
+  console.log('      the run that takes it is told why. Use it for "look again after X", never sleep-and-poll.');
+  console.log('  depends-on --tickets 101,102          This ticket waits on those; the sweep will not start it until');
+  console.log('      every one is resolved or closed. `--tickets` with no value clears it.');
+  console.log('  cost --usd 1.25 [--input-tokens N] [--output-tokens N] [--model M] [--cost-run-id R]');
+  console.log('      Record what a run cost. One report per run (a second replaces the first); the account\'s');
+  console.log('      supportRouting.maxTicketSpendUsd then stops automatic starts.');
   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 +16924,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]');
@@ -18730,6 +18957,7 @@ async function main() {
   migrateSessionIfNeeded();
   const originalArgv = process.argv.slice(2);
   const args = parseArgs(originalArgv);
+  requestIdentityFlags = args;
   configureLocalActor(args);
   const [command, subcommand] = args._;
   const wantsHelp = args.help === true || subcommand === 'help' || subcommand === '--help' || args._.includes('--help');
@@ -18745,7 +18973,7 @@ async function main() {
     requireAccountRepoContext(process.cwd(), flags, 'ai ' + subcommand, context);
     await localAi.command({
       subcommand, flags, context, root: SESSION_DIR, axios, Client, WebSocket,
-      defaultAgent: getPreferredAgent()
+      defaultAgent: getPreferredAgent(), requestHeaders: cliRequestHeaders
     });
     return;
   }
@@ -18804,7 +19032,9 @@ async function main() {
 
   if (!command || command === 'help' || command === '--help') {
     console.log('Usage: remits-cli <command>');
-    console.log('Global options: --no-auto-update, --local-agent NAME');
+    console.log('Global options: --no-auto-update, --local-agent NAME, --agent-id ID');
+    console.log('  --agent-id / REMITS_AGENT_ID declares the agent acting for the authenticated user on CLI requests.');
+    console.log('  --local-agent names only the local log folder; it does not declare an agent to the platform.');
     console.log('  remits-cli auth [--base-url URL] [--account-id ID] [--port 8765] [--data-mode test|prod]');
     console.log('  remits-cli sessions [list|remove] [--account-id ID] [--base-url URL] [--data-mode test|prod]');
     console.log('  remits-cli config [set] [--agent claude|codex|gemini]');

package/lib/local-ai.js

@@ -525,7 +525,7 @@ function help() {
   console.log('Decisions: {"content":"reply","toolCalls":[]} or {"content":null,"toolCalls":[{"name":"tool","arguments":{}}]}');
 }
 
-async function command({ subcommand, flags, context, root, axios, Client, WebSocket, defaultAgent = 'claude' }) {
+async function command({ subcommand, flags, context, root, axios, Client, WebSocket, defaultAgent = 'claude', requestHeaders }) {
   if (!subcommand || flags.help || subcommand === 'help') return help();
   if (!['serve', 'workers', 'work', 'request', 'respond', 'status', 'sessions', 'release'].includes(subcommand)) throw new Error('Unknown ai subcommand');
   const agent = flags.agent || defaultAgent;
@@ -545,7 +545,7 @@ async function command({ subcommand, flags, context, root, axios, Client, WebSoc
     try {
       const result = await axios.post(baseUrl.replace(/\/+$/, '') + '/cli/ai',
         { ...payload, command: action, workerId: worker.workerId, accountId, dataMode },
-        { headers: { Authorization: 'Bearer ' + session.token }, timeout: 15000, maxContentLength: MAX_BYTES, maxBodyLength: MAX_BYTES });
+        { headers: requestHeaders ? requestHeaders(session.token) : { Authorization: 'Bearer ' + session.token }, timeout: 15000, maxContentLength: MAX_BYTES, maxBodyLength: MAX_BYTES });
       if (!result.data?.success) throw new Error(result.data?.message || 'Local AI command failed');
       return result.data;
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.166",
+  "version": "0.1.168",
   "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
@@ -105,9 +106,26 @@ review.
 
 ### Resolving which agent a command means
 
-Order: `--agent-id`, then `REMITS_AGENT_ID`, then the single agent registered for this working
-directory. With several registered and no way to tell them apart, the command **fails and lists the
-candidates** rather than guessing — routing work to the wrong tab is silent, and a message is not.
+For agent lifecycle commands, explicit `--agent-id` or `REMITS_AGENT_ID` wins; otherwise the CLI looks
+for the registration anchored to this terminal's owning process. It never borrows another terminal's
+registration just because it shares the checkout.
+
+For platform request attribution, set `REMITS_AGENT_ID` for the agent's shell or pass `--agent-id` on
+each command. Both reach the shared HTTP client, including status, tools and local-AI requests.
+Supervised ticket workers receive `REMITS_AGENT_ID`, `REMITS_WORKER_RUN_ID` and
+`REMITS_SUPPORT_TICKET_ID` automatically. A manually named interactive agent does not need to register
+for ticket routing just to declare its identity. Registered roles and labels are accepted only from a
+registration owned by the authenticated user. `--local-agent` / `REMITS_LOCAL_AGENT_ID` remains a local
+folder choice and does not declare platform agent identity.
+
+System → Activity groups these requests under the authenticated user, with separate agent/run sessions
+and source filters. Undeclared CLI requests are labeled **CLI · no declared agent**, never assumed to be
+human. Browser sessions can also be automated. Only platform requests are observed, not local editing
+or reasoning between commands. Creating a preview token does not mark every subsequent browser user
+of that token as an agent.
+
+`ticket route --agent <target>` names the destination. Its legacy `--agent-id` alias also names the
+destination, not the caller; use `REMITS_AGENT_ID` to identify the agent making a routing request.
 
 ### Which agent gets a ticket
 

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

@@ -20,6 +20,7 @@
   - [Investigation Strategy](#investigation-strategy)
   - [Presenting Findings](#presenting-findings)
   - [Verifying a Production Issue Fix](#verifying-a-production-issue-fix)
+- [Missing or deleted business documents](#missing-or-deleted-business-documents)
 
 ## The Investigation Model
 
@@ -281,3 +282,23 @@ When a bug is reported from production, use this pattern:
 6. If useful, create or update a dedicated embeddable "playground" in test mode to reproduce the scenario in a controlled way.
 
 Do not move production customer data into another account's test collection as a routine verification strategy. If you cannot verify with a Test component, Playwright flow, or controlled test-mode embeddable, explain the gap clearly instead of improvising with live production validation.
+
+## Missing or deleted business documents
+
+`PROCESSED` is the MySQL object's processing outcome, not a guarantee that its Firestore document
+still exists. Read `documentEvidence` from `mcp_object_activity` or a current object `mcp_record_view`:
+it includes the resolved path, observed data lane, presence, recent revision metadata, and the latest
+Object `Document Delete` receipt when available. `state` is `present`, `missing`, `deleted`, `unknown`
+(read failed), or `out_of_scope`. `deleted` requires retained deletion evidence; absence alone is not proof.
+A `laneMismatch` means the requested read lane differs from the object's persisted lane.
+
+`Document Delete` ObjectLog entries expose structured `documentOperation` (outcome, document path,
+user/agent, component/action, node, data lane, scope, run and trace ids). The operation's
+`threadGroupingId` can differ from `request.traceId`; both are retained for correlation. Failed deletes
+never generate success revisions or downstream deletion messages. The processing status remains intact.
+
+To read retained history without a live parent document, call `mcp_firestore_search` with one
+`targetAccountId`, `collection`, `documentId`, and `includeHistory: true`. Use `historyLimit` (default 10,
+maximum 100), `includeRevisionSnapshots: true` for the pre-delete business snapshot, or `revisionId`
+for one exact revision. History is explicitly truncated when more rows exist. Legacy revisions may
+identify the user and time without the newer component/request provenance; do not invent missing facts.

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,8 @@
   - [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)
+  - [Coming back later, waiting on other tickets, and cost](#coming-back-later-waiting-on-other-tickets-and-cost)
 
 ## Support Ticket Mental Model
 
@@ -155,6 +158,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 +561,57 @@ 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.
+
+An approval or review can need several people: `request-approval ... --min-approvals 2` stays open until two
+different eligible deciders approve; one rejection settles it.
+
+### Coming back later, waiting on other tickets, and cost
+
+```bash
+remits-cli ticket wake --in 1440 --reason "requester promised logs tomorrow"   # or --at <ISO time>; --cancel
+remits-cli ticket depends-on --tickets 19463,19470                              # no value clears
+remits-cli ticket cost --usd 1.25                                                # usually reported for you
+```
+
+- **`wake` instead of waiting.** Never sleep or poll inside a run. Record what you are waiting for, set a
+  wake-up, and finish the run; when the time comes a fresh worker gets the ticket with `resumed for: timer`
+  and your reason in its brief.
+- **`depends-on`** when this ticket genuinely cannot start until others are resolved. The sweep holds it
+  until they are; nothing else has to remember to release it.
+- **Cost** is reported automatically by `agent serve` from each worker's transcript. An account can cap a
+  ticket's spend; when it is reached, starts are refused until a person resets the budget.
+
 **`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

@@ -141,6 +141,28 @@ The account-graph and user surface: the middle ground between `account-info.json
 compactly, because it is read into your context every session) and `mcp_account_view` (everything about one
 account).
 
+**Recurring schedules:** `action_schedules` lists the target account's Action schedules;
+`action_schedule_update` upserts by `targetAccountId` + `actionId` (or an account-scoped `scheduleId`);
+`action_schedule_delete` removes that schedule and its cloud job. Updates accept `cron`, `timeZone`,
+`enabled` and `dryRun`. `enabled:false` pauses; `enabled:true` resumes while preserving omitted settings.
+`regression_schedule` reads the per-account regression settings and latest report;
+`regression_schedule_update` accepts the same scheduling fields plus `resultAction`, `suiteConcurrency`
+(1–16) and explicit `ownerUserId`. Existing owners are preserved. Only admins may assign another owner;
+an eligible caller may take ownership themselves.
+
+Both use five-field cron and IANA time zones, default UTC. Existing Action schedules retain UTC.
+All writes require production mode; `dryRun:true` validates from either lane without writing or creating
+a cloud job. Action jobs resolve committed enabled `job:true` Actions on the target account; regression
+suites run committed source in test data. Optional `includeSchedulerStatus:true` on reads reports cloud
+registration/next delivery/last transport status; this does not prove Action or regression success.
+An empty regression update does not repair registration: explicitly pass cron/timeZone/enabled.
+
+```bash
+remits-cli tool --name mcp_account_user_admin --data-mode test --input '{"action":"action_schedule_update","targetAccountId":4655,"actionId":21,"cron":"0 1 * * *","timeZone":"America/New_York","enabled":true,"dryRun":true}'
+```
+
+Inspect the preview, then omit `dryRun` and use `--data-mode prod` when authorized to save the schedule.
+
 - `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
   are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
   edge (`direction: 'down'|'up'|'both'`). Nodes include `testAccount`. **This is how you get the deep tree
@@ -299,6 +321,11 @@ evidence at all, is in `investigation.md` → *HTTP audits*.
 remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collection": "http-audits/http-audits-2026-05/entries", "filters": [{"field": "direction", "operation": "EQUALS", "value": "OUTBOUND"}, {"field": "request.path", "operation": "EQUALS", "value": "/api/orders"}, {"field": "success", "operation": "EQUALS", "value": false}], "sort": [{"field": "timestamp", "direction": "DESC"}], "pagination": {"limit": 10}}' --data-mode prod
 ```
 
+Exact-account history reads also accept `includeHistory` (boolean), `historyLimit` (1–100, default 10),
+`includeRevisionSnapshots` (boolean, default false), and `revisionId` (exact Firestore revision id).
+These require one `targetAccountId`, a collection name and `documentId`. They return `documentEvidence`
+even when the live document is deleted. A normal exact-id miss also returns bounded evidence.
+
 ### `mcp_firestore_patch`
 Guarded exact-document Firestore patch tool for bounded repairs. It defaults to `dryRun:true` and refuses broad
 updates, wildcard collections, delete/remove operations, protected identity fields, and `_lastModified*` audit
@@ -329,7 +356,9 @@ Response fields include `dataMode`, `accountId`, `collection`, `documentId`, `dr
 `diff`. Switch to `"dryRun":false` only after the diff and preconditions are exactly what you intended.
 
 ### `mcp_object_activity`
-Object lifecycle timeline — metadata + recent activity.
+Object lifecycle timeline — metadata + recent activity. Object metadata includes `documentEvidence`
+with path, current presence/data lane, recent revisions and latest deletion receipt. Document Delete
+activity entries include structured `documentOperation` evidence; PROCESSED is independent of document presence.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|