@remits/remits-cli 0.1.167 → 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
-- L18308  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';
@@ -15234,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 {
@@ -15517,6 +15611,8 @@ 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'),
@@ -16063,7 +16159,24 @@ async function ticketCommand(flags, subcommand) {
     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,
@@ -16780,7 +16893,7 @@ function printTicketHelp() {
   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('  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.');
@@ -16794,7 +16907,15 @@ function printTicketHelp() {
   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('  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');
@@ -18836,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');
@@ -18851,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;
   }
@@ -18910,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.167",
+  "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

@@ -106,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

@@ -26,6 +26,7 @@
   - [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
 
@@ -592,6 +593,25 @@ The handoff is queued even if nobody is online, `--exclude` keeps you off it (in
 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 |
 |-----------|----------|-------------|