@remits/remits-cli 0.1.167 → 0.1.169

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
+- L2802  Account Repos, Guide Sync, And Platform Repo
+- L3701  Component Discovery And HTTP Logging
+- L4484  Skill Delivery And TOC Resolution
+- L4799  Auth And Component Staging
+- L5435  Component Summaries, Status, And Sync Gates
+- L7759  Branches, Promotion, Commit, And Test Runs
+- L10072  Tokens, Tools, Verification, And Config
+- L11589  Service Dashboard And WebSocket Listener
+- L14099  Agent And Ticket Workflows
+- L18869  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')
@@ -2095,6 +2097,7 @@ function recordEvidenceEntry(cwd, packet, context = {}) {
     };
     fs.appendFileSync(paths.evidenceFile, JSON.stringify(entry) + '\n');
     trimEvidenceTrail(paths.evidenceFile);
+    queueEvidenceReceipt(cwd, entry, context);
     return entry;
   } catch (_) {
     // A trail write must never fail the command it is describing.
@@ -2102,6 +2105,135 @@ function recordEvidenceEntry(cwd, packet, context = {}) {
   }
 }
 
+/**
+ * Shared passive evidence: inside a work attempt (a supervised worker, or a command given a ticket), each
+ * trail entry is ALSO written to a durable local outbox and published to the work item as a client-reported
+ * receipt, so a successor on another machine can retrieve it. Write before upload; a stable receiptId makes
+ * a replay after a lost response record nothing twice. Never a verdict and never something to satisfy.
+ */
+const EVIDENCE_OUTBOX_MAX_LINES = 1000;
+
+function evidenceOutboxFile(cwd, actorId) {
+  // A supervisor drains its CHILD's outbox: the child's state lives under its own actor (REMITS_AGENT_ID),
+  // not under the supervisor's, so the actor can be named explicitly.
+  if (actorId) {
+    return path.join(cwd, '.remits-cli', 'actors', normalizeLocalActor(actorId) || String(actorId), 'evidence-outbox.jsonl');
+  }
+  return path.join(path.dirname(localStatePaths(cwd).evidenceFile), 'evidence-outbox.jsonl');
+}
+
+function evidenceReceiptId(entry, ticketId) {
+  const crypto = require('crypto');
+  return 'r-' + crypto.createHash('sha256').update(String(ticketId) + '|' + JSON.stringify(entry)).digest('hex').slice(0, 20);
+}
+
+function queueEvidenceReceipt(cwd, entry, context = {}) {
+  try {
+    const ticketId = String((context && context.ticketId) || process.env.REMITS_SUPPORT_TICKET_ID || '').trim();
+    if (!ticketId || !entry) return null;
+    const receipt = {
+      receiptId: evidenceReceiptId(entry, ticketId),
+      ticketId,
+      // Partitioned by platform: a receipt queued against one host is never uploaded to another.
+      host: entry.world && entry.world.host || (context && context.baseUrl) || null,
+      attemptId: process.env.REMITS_WORKER_RUN_ID || null,
+      type: entry.type,
+      claim: entry.claim,
+      outcome: evidenceOutcome(entry),
+      observedAt: entry.ts,
+      world: entry.world,
+      ref: { packetId: entry.ref && entry.ref.packetId, taskId: entry.ref && entry.ref.taskId, callId: entry.ref && entry.ref.callId },
+      queuedAt: new Date().toISOString()
+    };
+    fs.appendFileSync(evidenceOutboxFile(cwd), JSON.stringify(receipt) + '\n');
+    return receipt;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Publish queued receipts. The outbox is RENAMED before it is read, so a concurrent writer appends to a
+ * fresh file and nothing it writes can be lost by this rewrite; whatever is not accepted is appended back.
+ * Returns { sent, duplicate, kept, rejected }.
+ */
+async function drainEvidenceOutbox(cwd, context, actorId) {
+  const file = evidenceOutboxFile(cwd, actorId);
+  const summary = { sent: 0, duplicate: 0, kept: 0, rejected: 0 };
+  // A drain that crashed mid-flight left its renamed file behind; its receipts go back in the queue.
+  try {
+    const dir = path.dirname(file);
+    for (const name of fs.readdirSync(dir)) {
+      const m = /^evidence-outbox\.jsonl\.(\d+)\.draining$/.exec(name);
+      if (m && Number(m[1]) !== process.pid && !processIsAlive(Number(m[1]))) {
+        const orphan = path.join(dir, name);
+        fs.appendFileSync(file, fs.readFileSync(orphan, 'utf8'));
+        fs.unlinkSync(orphan);
+      }
+    }
+  } catch (_) { /* best effort */ }
+  if (!fs.existsSync(file) || !context || !context.session) return summary;
+  const draining = file + '.' + process.pid + '.draining';
+  try { fs.renameSync(file, draining); } catch (_) { return summary; }
+  let receipts = [];
+  try {
+    receipts = fs.readFileSync(draining, 'utf8').split('\n').filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch (_) { return null; } }).filter(Boolean);
+  } catch (_) { /* unreadable: keep nothing */ }
+  const keep = [];
+  const host = String(context.baseUrl || '').replace(/\/$/, '');
+  // Grouped by ticket AND the data lane the receipt was observed in: a ticket lives in one lane, and
+  // addressing it from another (e.g. the draining supervisor's session lane) finds no document there.
+  const byTicket = new Map();
+  for (const r of receipts) {
+    // Another platform's receipts stay queued for that platform.
+    if (r.host && host && String(r.host).replace(/\/$/, '') !== host) { keep.push(r); continue; }
+    const lane = (r.world && r.world.dataMode) || context.dataMode || null;
+    const groupKey = r.ticketId + '|' + (lane || '');
+    if (!byTicket.has(groupKey)) byTicket.set(groupKey, { ticketId: r.ticketId, lane, list: [] });
+    byTicket.get(groupKey).list.push(r);
+  }
+  const api = buildAxios(context.baseUrl, context.session.token, 20000);
+  for (const { ticketId, lane, list } of byTicket.values()) {
+    for (let i = 0; i < list.length; i += 50) {
+      const batch = list.slice(i, i + 50);
+      try {
+        const response = await api.post('/cli/ticket', { action: 'receipt', ticketId, dataMode: lane || undefined, receipts: batch })
+          .then((res) => res.data);
+        if (response && response.success) {
+          summary.sent += response.accepted || 0;
+          summary.duplicate += response.duplicate || 0;
+          summary.rejected += (response.rejected || []).length;
+        } else {
+          keep.push(...batch);
+        }
+      } catch (err) {
+        // Only a request the platform says is malformed or not permitted is dropped (loudly). Everything else —
+        // unreachable, busy (409 also covers a ticket mid-write or a stale revision), throttled, not found yet —
+        // stays queued for the next drain: losing evidence is worse than retrying it.
+        const status = err && err.response && err.response.status;
+        const message = err && err.response && err.response.data && err.response.data.message;
+        if (status === 400 || status === 401 || status === 403 || status === 413 || status === 422) {
+          summary.rejected += batch.length;
+          appendGlobalActivityLog('evidence', 'outbox.rejected', { ticketId, count: batch.length, status, message }, 'error');
+        } else {
+          keep.push(...batch);
+          appendGlobalActivityLog('evidence', 'outbox.kept', { ticketId, count: batch.length, status: status || null,
+            message: message || describeError(err) }, 'warn');
+        }
+      }
+    }
+  }
+  try {
+    if (keep.length) {
+      fs.appendFileSync(file, keep.slice(-EVIDENCE_OUTBOX_MAX_LINES).map((r) => JSON.stringify(r)).join('\n') + '\n');
+    }
+    fs.unlinkSync(draining);
+  } catch (_) { /* the draining file remains and is retried by name below */ }
+  summary.kept = keep.length;
+  return summary;
+}
+
 function evidenceOutcome(row) {
   if (row && (row.pending === true || row.success === null)) return 'pending';
   return row && row.success === false ? 'failed' : 'ok';
@@ -4044,8 +4176,12 @@ function stageTimeoutMs(components, flags = {}) {
   return Math.min(600000, Math.max(60000, Math.round(60000 + (megabytes * 60000))));
 }
 
-function buildAxios(baseUrl, token, timeoutMs = 60000) {
-  const headers = token ? { Authorization: 'Bearer ' + token } : {};
+function cliRequestHeaders(token) {
+  // A supervised worker authenticates with the credential its supervisor minted for THIS attempt
+  // (/cli/agentCredential). The platform then knows which participant is calling from the credential itself,
+  // so omitting or mistyping an identity header cannot turn the worker into a human or another agent.
+  const effectiveToken = process.env.REMITS_AGENT_TOKEN || token;
+  const headers = effectiveToken ? { Authorization: 'Bearer ' + effectiveToken } : {};
   // 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
   // loop hardest are exactly the ones that never do. Without it the platform cannot tell an agent that the
@@ -4055,10 +4191,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 +5133,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 +8222,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 +8234,8 @@ async function commitComponentsCommand(flags) {
       workset: false,
       'replace-lane': false,
       replaceLane: false,
-      'changed-only': true
+      'changed-only': true,
+      intent: 'commit'
     })));
 
     outcome.phase = 'git';
@@ -9115,6 +9265,27 @@ function testRunSummaryLines(status = {}) {
   return lines;
 }
 
+// A full-suite run that took minutes is the most expensive thing an agent's build loop does, and the run itself
+// is the one place to say so. Production 2026-11: agents re-ran whole multi-minute suites after every edit,
+// every case passing. Printed only for an unselected run long enough (90 s of case time) to matter.
+function testRunPacingLines(status = {}, options = {}) {
+  const minMs = 90 * 1000;
+  const result = status.result || {};
+  const tests = Array.isArray(result.tests) ? result.tests.filter((t) => t && t.name) : [];
+  if (options.selected || tests.length < 4) return [];
+  const durationOf = (t) => Number(t.duration) || 0;
+  const totalMs = tests.reduce((sum, t) => sum + durationOf(t), 0);
+  if (totalMs < minMs) return [];
+  const slowest = tests.slice().sort((a, b) => durationOf(b) - durationOf(a)).slice(0, 3)
+    .filter((t) => durationOf(t) > 0);
+  const lines = ['Pacing: ' + tests.length + ' cases, ' + formatDurationMs(totalMs) + ' of case time' +
+    (slowest.length ? '; slowest ' + slowest.map((t) => JSON.stringify(String(t.name)) + ' ' + formatDurationMs(durationOf(t))).join(', ') : '') + '.'];
+  const ref = options.testRef !== undefined ? JSON.stringify(String(options.testRef)) : '<suite>';
+  lines.push('  While iterating, re-run only what you are fixing: remits-cli test run --test ' + ref + ' --failed  (or --names "a|b").');
+  lines.push('  Run the whole suite once before landing.');
+  return lines;
+}
+
 // Per-case comparison of two runs of the same suite: which cases changed outcome, and how cost and duration
 // moved. The answer to "did this revision do better than the last one" without reconstructing either run.
 function compareTestRunResults(baseResult = {}, headResult = {}) {
@@ -9333,6 +9504,13 @@ function testRunLaunchLines(start = {}, runOptions = {}) {
   if (runOptions.label) lines.push('Label: ' + runOptions.label);
   if (runOptions.params) lines.push('Params: ' + Object.keys(runOptions.params).map((k) => k + '=' + JSON.stringify(runOptions.params[k])).join(' '));
   if (runOptions.repeat) lines.push('Repeat: every selected case runs ' + runOptions.repeat + ' times');
+  if (start.rerunOf && Array.isArray(start.rerunOf.failedCases)) {
+    const r = start.rerunOf;
+    lines.push('Re-running ' + r.failedCases.length + ' case(s) that did not pass in run ' + r.taskId +
+      (r.dataMode ? ' (' + r.dataMode + ' lane)' : '') + ':');
+    r.failedCases.slice(0, 20).forEach((name) => lines.push('  - ' + name));
+    if (r.failedCases.length > 20) lines.push('  ... and ' + (r.failedCases.length - 20) + ' more');
+  }
   if (start.runGroupId) {
     lines.push('Parallel: ' + (start.shardTaskIds || []).length + ' shards (' + (start.shardTaskIds || []).join(', ') + '), read as ONE run by ' + start.runGroupId);
   }
@@ -9367,6 +9545,10 @@ async function testCommand(flags) {
     ? []
     : (Array.isArray(flags.names) ? flags.names : [flags.names]);
   const names = parseTestCaseSelectors(rawNames);
+  const rerunFailed = flagEnabled(flags.failed);
+  if (rerunFailed && names.length) {
+    throw new Error('--failed picks the cases itself; drop --names (or drop --failed).');
+  }
   // --label / --param / --repeat / --parallel: what this run varies, and how it is executed.
   const runOptions = testRunOptionsFromFlags(flags);
   const runGroupId = runOptions.parallel > 1 ? 'grp-' + crypto.randomUUID() : undefined;
@@ -9416,6 +9598,11 @@ async function testCommand(flags) {
     dataMode,
     dataModeSource,
     caseConcurrency: flags.parallel !== undefined && runOptions.parallel === 1 ? 1 : undefined,
+    // --candidate <laneContentHash>: refuse (stale_revision) if the lane no longer holds that staged content.
+    expectedLaneContentHash: flags.candidate || undefined,
+    // --failed: the platform re-runs only the cases that did not pass in your last finished run of this suite
+    // on this git branch and staging workspace (and says which run it read).
+    rerunFailed: rerunFailed || undefined,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
     tests: names
@@ -9434,6 +9621,7 @@ async function testCommand(flags) {
         break;
       } catch (err) {
         const data = err && err.response && err.response.data;
+        if (data && data.code === 'no_recorded_run') throw new Error(data.message);
         if (shardStarts.length && shardStartBusy(err) && Date.now() < shardWaitDeadline) {
           console.error('Shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel + ' is waiting for a free suite slot ' +
             '(the platform runs a limited number of suites at once; the shards already running free them).');
@@ -9446,8 +9634,18 @@ async function testCommand(flags) {
         throw err;
       }
     }
+    if (!shardStart.success && shardStart.code === 'nothing_failed' && !shardStarts.length) {
+      // Not an error: the thing --failed exists for is already true. Exit 0 and say what to run next.
+      if (jsonOutput) {
+        console.log(JSON.stringify(shardStart, null, 2));
+      } else {
+        console.log(shardStart.message);
+        console.log('Before landing, run the whole suite once: remits-cli test run --test ' + JSON.stringify(String(testRef)));
+      }
+      return;
+    }
     if (!shardStart.success) {
-      throw new Error('Failed to start test run' + (shardStarts.length ? ' (shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel +
+      throw new Error('Failed to start test run' + (shardStart.message ? ': ' + shardStart.message : '') + (shardStarts.length ? ' (shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel +
         '; the shards already started keep running: ' + shardStarts.map((st) => st.taskId).join(', ') + ')' : ''));
     }
     shardStarts.push(shardStart);
@@ -9548,6 +9746,7 @@ async function testCommand(flags) {
       .forEach((line) => console.log(line));
     testRunSummaryLines(status).forEach((line) => console.log(line));
     testFailureGroupLines(status, { testRef }).forEach((line) => console.log(line));
+    testRunPacingLines(status, { testRef, selected: names.length > 0 || rerunFailed }).forEach((line) => console.log(line));
     printTestRunPivots(status);
     // The whole run object used to be printed here as pretty JSON. One 92-case suite measured 220 KB,
     // most of it identifiers repeated once per case, spent on the turn with the least room left. It is
@@ -13959,7 +14158,7 @@ const AGENT_WORKER_MAX_LOG_BYTES = 8 * 1024 * 1024;
  *
  * `mode` is the autonomy bound, not a preference. `investigate` maps to each CLI's genuine
  * read-only mode so an operator can put a real boundary around a production support agent; `edit`
- * lets it change files but never commits (the brief says so, and nothing here runs git).
+ * lets it change files; whether it may land is the account's landing profile, stated in the brief (nothing here runs git).
  */
 const AGENT_LAUNCHERS = {
   codex: {
@@ -15234,6 +15433,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 {
@@ -15260,6 +15537,22 @@ async function releaseTicketClaim(context, agentId, ticket, options = {}) {
   }
 }
 
+/**
+ * Per-attempt liveness, in memory in the supervisor: when each child last wrote output and its last
+ * summarized progress line. Reported on the supervisor's poll as `attempts`, so the platform can tell a
+ * connected supervisor from a child that is actually producing work. Never persisted; never a heuristic.
+ */
+const WORKER_LIVENESS = new Map();
+
+function noteWorkerLiveness(ticketId, patch) {
+  const key = String(ticketId);
+  WORKER_LIVENESS.set(key, { ...(WORKER_LIVENESS.get(key) || { ticketId: key }), ...patch });
+}
+
+function workerLivenessFor(ticketIds) {
+  return (ticketIds || []).map((id) => WORKER_LIVENESS.get(String(id))).filter(Boolean);
+}
+
 async function postAgentStatus(context, agentId, update) {
   try {
     await buildAxios(context.baseUrl, context.session.token, 10000)
@@ -15276,6 +15569,39 @@ async function postAgentStatus(context, agentId, update) {
  * the same thing. Only the local supervisor can add machine-local repository hints; the worker owns the
  * final grounding step, including creating or choosing a git worktree before it edits.
  */
+/** Mint a credential bound to one worker attempt. Null (legacy identity) when the server cannot. */
+async function mintWorkerCredential(context, binding) {
+  try {
+    const response = await buildAxios(context.baseUrl, context.session.token, 15000)
+      .post('/cli/agentCredential', {
+        mode: 'mint', agentId: binding.agentId, ticketId: binding.ticketId, runId: binding.runId,
+        capabilities: binding.capabilities
+      })
+      .then((r) => r.data);
+    if (response && response.success && response.credential) {
+      appendGlobalActivityLog('agent', 'worker.credential_minted', {
+        agentId: binding.agentId, ticketId: binding.ticketId, expiresAt: response.expiresAt
+      });
+      return { credential: response.credential, expiresAt: response.expiresAt };
+    }
+  } catch (err) {
+    appendGlobalActivityLog('agent', 'worker.credential_unavailable', {
+      agentId: binding.agentId, ticketId: binding.ticketId, error: describeError(err)
+    }, 'warn');
+  }
+  return null;
+}
+
+async function revokeWorkerCredential(context, workerCredential) {
+  if (!workerCredential || !workerCredential.credential) return;
+  try {
+    await buildAxios(context.baseUrl, context.session.token, 15000)
+      .post('/cli/agentCredential', { mode: 'revoke', credential: workerCredential.credential });
+  } catch (_) {
+    // It expires on its own; a failed revoke only shortens nothing.
+  }
+}
+
 async function spawnTicketWorker(context, ctx, ticket) {
   const { spawn } = require('child_process');
   const agentId = ctx.agentId;
@@ -15401,6 +15727,15 @@ async function spawnTicketWorker(context, ctx, ticket) {
   });
 
   const attempt = recordWorkerAttempt(agentId, ticketId);
+  // A credential bound to this attempt (agent + ticket + run). Best effort: an older server without the
+  // endpoint leaves the worker on the legacy header-declared identity, exactly as before.
+  // A session the OPERATOR launched read-only (--mode investigate) gets a credential WITHOUT stage/land, so
+  // the platform refuses source changes from it rather than relying on the brief alone. A worker that is
+  // investigating only because another run holds the lease keeps full reach: it may take the lease later.
+  const workerCredential = await mintWorkerCredential(context, {
+    agentId, ticketId, runId,
+    capabilities: ctx.mode === 'investigate' ? ['read', 'ticket', 'test', 'tool', 'token'] : undefined
+  });
   const child = spawn(launcher.binary, built.args, {
     cwd: workingDirectory || ctx.cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
@@ -15411,6 +15746,7 @@ async function spawnTicketWorker(context, ctx, ticket) {
       REMITS_AGENT_ID: agentId,
       REMITS_SUPPORT_TICKET_ID: ticketId,
       REMITS_WORKER_RUN_ID: runId,
+      ...(workerCredential ? { REMITS_AGENT_TOKEN: workerCredential.credential } : {}),
       // Give the worker its OWN staging lane.
       //
       // The edit LEASE already serializes who may edit a repo, and this does not replace it — a lease
@@ -15472,8 +15808,10 @@ async function spawnTicketWorker(context, ctx, ticket) {
   let lastStatusAtMs = 0;
   let buffered = '';
 
+  noteWorkerLiveness(ticketId, { runId, pid: child.pid, startedAtMs: Date.now() });
   const consume = (chunk) => {
     const text = chunk.toString();
+    noteWorkerLiveness(ticketId, { lastOutputAtMs: Date.now() });
     if (logBytes < AGENT_WORKER_MAX_LOG_BYTES) {
       logBytes += text.length;
       logStream.write(text);
@@ -15489,6 +15827,7 @@ async function spawnTicketWorker(context, ctx, ticket) {
       if (nowMs - lastStatusAtMs < AGENT_WORKER_STATUS_THROTTLE_MS) continue;
       lastStatusAtMs = nowMs;
       recordWorker(agentId, ticketId, { activity: summary, activityAt: new Date().toISOString() });
+      noteWorkerLiveness(ticketId, { lastProgress: String(summary).slice(0, 160), lastProgressAtMs: nowMs });
       postAgentStatus(context, agentId, {
         state: 'working', ticketId, activity: summary, step: 'worker:' + agentType
       });
@@ -15503,12 +15842,23 @@ async function spawnTicketWorker(context, ctx, ticket) {
 
   const done = new Promise((resolve) => {
     child.on('error', (err) => {
+      WORKER_LIVENESS.delete(String(ticketId));
       appendGlobalActivityLog('agent', 'worker.spawn_failed',
         { agentId, ticketId, agentType, error: describeError(err) }, 'error');
       resolve({ ticketId, ok: false, reason: 'spawn_failed', message: describeError(err) });
     });
     child.on('close', async (code, signal) => {
       try { logStream.end(); } catch (_) { /* nothing to do */ }
+      // The attempt is over: its credential must not outlive it (a late or orphaned child cannot keep acting).
+      WORKER_LIVENESS.delete(String(ticketId));
+      // The worker may have exited with receipts still queued in its checkout: a worker exit must not erase
+      // unsent evidence. Drained with the SUPERVISOR's session (the worker credential is about to be revoked).
+      if (workingDirectory) {
+        try {
+          await drainEvidenceOutbox(workingDirectory, { ...context, dataMode: context.dataMode || ctx.dataMode }, agentId);
+        } catch (_) { /* stays queued for the next drain */ }
+      }
+      await revokeWorkerCredential(context, workerCredential);
       const ok = code === 0 && !signal;
       appendGlobalActivityLog('agent', 'worker.finished',
         { agentId, ticketId, agentType, code, signal, attempt, logFile }, ok ? 'info' : 'error');
@@ -15517,6 +15867,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'),
@@ -15662,6 +16014,7 @@ async function agentHeartbeatDaemonCommand(flags) {
           claim: inFlight.size < ctx.maxConcurrent,
           runId: ctx.runId,
           activeTickets,
+          attempts: workerLivenessFor(activeTickets),
           maxConcurrent: ctx.maxConcurrent,
           // Declared so the phase the platform derives already accounts for an operator who asked for a
           // read-only agent. Without it the server would hand out an edit lease this session will never
@@ -15972,6 +16325,8 @@ async function ticketCommand(flags, subcommand) {
 
   const local = ownLocalAgent(flags);
   const context = agentSessionFor(flags, local);
+  // Publish any passive receipts this checkout queued, before the verb that may hand the work to someone else.
+  try { await drainEvidenceOutbox(process.cwd(), context); } catch (_) { /* never blocks the verb */ }
 
   // Routing lives on its own endpoint (the operator surface the dashboard and any Embeddable share),
   // so it is dispatched here rather than folded into the lifecycle switch.
@@ -16015,6 +16370,13 @@ async function ticketCommand(flags, subcommand) {
     route: flags.route === 'false' ? false : undefined,
     details: flags.details,
     nextStep: flags['next-step'],
+    // The structured handoff checkpoint (durable references, never local paths) and the revision a
+    // decision was made from: a stale one is refused with code stale_revision instead of being rebased.
+    artifactRefs: csvFlag(flags['artifact-refs'] || flags.artifactRefs),
+    evidenceRefs: csvFlag(flags['evidence-refs'] || flags.evidenceRefs),
+    waitingOn: csvFlag(flags['waiting-on'] || flags.waitingOn),
+    requiredCapabilities: csvFlag(flags.needs || flags['required-capabilities']),
+    expectedRevision: flags['expected-revision'] !== undefined ? Number(flags['expected-revision']) : undefined,
     category: flags.category,
     // Clearing a planning slot has to be expressible, and `||` could not express it: an empty value is
     // falsy, so it collapsed to undefined, JSON.stringify dropped the key, and the server was never told.
@@ -16063,7 +16425,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 +17159,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.');
@@ -16791,10 +17170,25 @@ function printTicketHelp() {
   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('          [--artifact-refs a,b] [--evidence-refs e1,e2] [--waiting-on X] [--needs capability]');
   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('      The checkpoint (findings, next step, refs, waiting-on, needs) is in the next worker\'s brief.');
+  console.log('  --expected-revision N (handoff, decide, complete): refuse with stale_revision if the ticket moved');
+  console.log('      past revision N since you read it, instead of merging your decision over newer changes.');
   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('  cancel --reason "..." [--expected-revision N]   The outcome is no longer wanted: closed with disposition');
+  console.log('      cancelled; history kept; open requests cancelled; anything already landed or sent is NOT undone.');
+  console.log('  redeliver-events                      OPERATOR: re-dispatch undelivered lifecycle events (deduplicated by eventId).');
+  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');
@@ -16962,6 +17356,113 @@ function usageListFlag(value) {
   return items.length ? items : undefined;
 }
 
+/** `remits-cli capabilities` — the platform's collaboration catalog (features, verbs, refusal codes). */
+async function capabilitiesCommand(flags) {
+  const cwd = process.cwd();
+  let baseUrl = flags['base-url'];
+  if (!baseUrl) {
+    try { baseUrl = resolveSessionContext(cwd, flags).session.baseUrl; } catch (_) { /* no session is fine */ }
+  }
+  baseUrl = baseUrl || DEFAULT_BASE_URL;
+  let response;
+  try {
+    response = await axios.get(baseUrl.replace(/\/$/, '') + '/cli/capabilities', { timeout: 15000, headers: cliRequestHeaders(null) })
+      .then((r) => r.data);
+  } catch (err) {
+    if (err && err.response && err.response.status === 404) {
+      response = { success: false, code: 'unsupported',
+        message: 'This platform predates the capability catalog; it supports none of the negotiated collaboration features.' };
+    } else {
+      throw err;
+    }
+  }
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+  if (!response || response.success !== true) {
+    console.log(response && response.message ? response.message : 'No capability catalog available.');
+    return response;
+  }
+  console.log('Collaboration capabilities — ' + baseUrl + ' (protocol ' + response.protocolVersion + ')');
+  console.log('');
+  console.log('Features:');
+  Object.entries(response.featureDetails || {}).forEach(([name, detail]) => console.log('  ' + name.padEnd(24) + ' ' + detail));
+  console.log('');
+  console.log('Verbs:');
+  (response.verbs || []).forEach((v) => console.log('  ' + String(v.verb).padEnd(30) + ' ' + (v.sideEffect || '') +
+    (v.refusals && v.refusals.length ? '  [refusals: ' + v.refusals.join(', ') + ']' : '')));
+  console.log('');
+  console.log('Refusal codes:');
+  Object.entries(response.codes || {}).forEach(([code, meaning]) => console.log('  ' + code.padEnd(20) + ' ' + meaning));
+  console.log('');
+  console.log(response.note);
+  return response;
+}
+
+/**
+ * `remits-cli policy explain` — what the account's deterministic rules would decide for a proposed action,
+ * and why, WITHOUT applying it. The verb re-evaluates when it actually runs; this is the preview.
+ */
+async function policyExplainCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token, 60000);
+  const components = csvFlag(flags.components || flags.component);
+  const response = await loggedPost(api, cwd, '/cli/policyExplain', {
+    // The checkout's branch and staging workspace: a person explaining their STAGED process draft is answered
+    // from it (the authoring lane shows staged prompts only when the call names its branch).
+    ...runContextPayload(flags),
+    token: session.token,
+    accountId: flags['target-account-id'] ? Number(flags['target-account-id']) : accountId,
+    dataMode: resolveDataMode(flags, session),
+    point: flags.point,
+    workstream: flags.workstream,
+    capabilities: csvFlag(flags.capabilities || flags.capability) || undefined,
+    actorKind: flags.as || flags['actor-kind'],
+    acknowledge: flags.acknowledge,
+    components: components ? components.map((entry) => {
+      const [type, name, category] = String(entry).split(':');
+      return { type, name, category };
+    }) : undefined
+  }).then((r) => r.data).catch((err) => {
+    if (err && err.response && err.response.data) return err.response.data;
+    throw err;
+  });
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+  if (!response || response.success !== true) {
+    throw new Error((response && response.message) || 'Policy explanation failed');
+  }
+  const decision = response.decision || {};
+  console.log('Policy at "' + response.point + '" on account ' + response.accountId +
+    (response.workstream ? ' (workstream ' + response.workstream + ')' : '') + ' — ' + response.dataMode + ' lane');
+  console.log('  as: ' + ((response.actor && response.actor.kind) || '?') +
+    ((response.actor && response.actor.evidence && response.actor.evidence.length) ? ' (' + response.actor.evidence.join(', ') + ')' : ''));
+  console.log('  decision: ' + (decision.allowed ? 'ALLOWED' : 'REFUSED (' + (decision.code || 'policy_denied') + ')'));
+  if (decision.message) console.log('  ' + decision.message);
+  (decision.warnings || []).forEach((w) => console.log('  warn ' + w.ruleId + ': ' + (w.message || '')));
+  const relevant = (response.rules || []).filter((r) => r.appliesAtPoint || r.fires);
+  if (relevant.length) {
+    console.log('  rules that apply at this point:');
+    relevant.forEach((r) => console.log('    ' + (r.fires ? '*' : ' ') + ' [' + r.grade + '] ' + r.id +
+      (r.final ? ' (final)' : '') + '  from ' + (r.source || '?') +
+      (r.distance !== undefined ? ' (distance ' + r.distance + ')' : '')));
+  } else {
+    console.log('  no rule applies at this point.');
+  }
+  const eff = response.effectivePolicy || {};
+  if (eff.unavailable) console.log('  POLICY UNAVAILABLE: mandatory decisions are refused until it can be read.');
+  if (eff.error) console.log('  policy problem: ' + eff.error);
+  console.log('  ' + response.note);
+  return response;
+}
+
 async function usageCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -17419,9 +17920,29 @@ function listWorkstreamIndexes(cwd) {
     .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
 }
 
+function evidenceOutboxPending(cwd) {
+  try {
+    const file = evidenceOutboxFile(cwd);
+    return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).length : 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
 async function evidenceCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
+  if (flags._ && flags._[1] === 'flush') {
+    const context = agentSessionFor(flags, ownLocalAgent(flags));
+    const result = await drainEvidenceOutbox(cwd, context);
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({ success: true, ...result }, null, 2));
+    } else {
+      console.log('Published ' + result.sent + ' receipt(s)' + (result.duplicate ? ', ' + result.duplicate + ' already recorded' : '') +
+        (result.rejected ? ', ' + result.rejected + ' rejected' : '') + (result.kept ? '; ' + result.kept + ' still queued' : '') + '.');
+    }
+    return result;
+  }
   const limit = Math.max(1, Math.min(parseInt(flags.limit || flags.max || '40', 10) || 40, 500));
   const entries = readEvidenceTrail(cwd, limit);
   if (flagEnabled(flags.json)) {
@@ -17430,6 +17951,10 @@ async function evidenceCommand(flags) {
   }
   const paths = localStatePaths(cwd);
   console.log('Evidence trail for actor ' + paths.actor.id + '  (' + paths.evidenceFile + ')');
+  const pending = evidenceOutboxPending(cwd);
+  if (pending) {
+    console.log(pending + ' receipt(s) queued for the work item and not yet published — remits-cli evidence flush');
+  }
   if (!entries.length) {
     console.log('Nothing recorded yet. Every stage, test, token, tool and sync appends one world-stamped line here,');
     console.log('with no envelope and nothing to start.');
@@ -17531,6 +18056,35 @@ async function workstreamCommand(flags, subcommand) {
  * and the one an operator asks when a queue is not moving. Agents, leases and tickets were each readable
  * on their own and never together, so every caller invented its own join and they disagreed.
  */
+/**
+ * One line from the platform's CollaborationActivity projection. Null when an older server sent none.
+ * Live work and stored facts are named separately, and unknown coverage is said, never shown as zero.
+ */
+function describeActivityHeadline(activity) {
+  if (!activity || typeof activity !== 'object') return null;
+  const parts = [];
+  const coverage = activity.coverage || {};
+  if (coverage.registry === 'unavailable') {
+    parts.push('live participants unknown');
+  } else {
+    const running = (activity.attempts && activity.attempts.running) || 0;
+    const online = (activity.participants && activity.participants.online) || 0;
+    parts.push('live: ' + running + ' attempt(s) running, ' + online + ' participant(s) online');
+  }
+  if (coverage.staging === 'unavailable') {
+    parts.push('staging unknown');
+  } else if (activity.staged && activity.staged.laneCount) {
+    const changes = activity.changes || {};
+    parts.push('stored: ' + (changes.componentCount != null ? changes.componentCount + ' last-reported change(s), ' : '') +
+      activity.staged.entryCount + ' staged entr(ies) in ' + activity.staged.laneCount + ' lane(s)' +
+      (changes.asOf ? ' (as of ' + changes.asOf + ')' : ''));
+  }
+  if (Array.isArray(activity.offlineAuthors) && activity.offlineAuthors.length) {
+    parts.push('staged by offline author(s): ' + activity.offlineAuthors.join(', '));
+  }
+  return '  ' + parts.join(' · ');
+}
+
 async function agentWorkMapCommand(flags) {
   const agentId = resolveAgentId(flags, { optional: true });
   const local = agentId ? (listLocalAgents().find((entry) => entry.agentId === agentId) || {}) : {};
@@ -17557,12 +18111,19 @@ async function agentWorkMapCommand(flags) {
     return;
   }
   console.log('Work map — ' + context.baseUrl + ' · ' + response.dataMode + ' lane');
+  // The platform's activity projection (the same one the account console renders): live work is the
+  // running/online counts; last-reported changes and the staged overlay are stored facts with an as-of.
+  const activityLine = describeActivityHeadline(response && response.activity);
+  if (activityLine) console.log(activityLine);
   console.log('');
   for (const repo of repositories) {
     const lease = repo.editLease;
     console.log('  ' + repo.accountName + ' (' + repo.accountId + ')' +
       (repo.accountType ? '  ' + repo.accountType : ''));
-    if (lease) {
+    if (lease && lease.unavailable) {
+      // UNKNOWN is its own state: nobody may edit, and nobody is named as the holder.
+      console.log('    EDIT LEASE  unknown (coordination store unavailable) — investigate read-only');
+    } else if (lease) {
       const who = lease.agentLabel || lease.agentId;
       console.log('    EDIT LEASE  ' + who +
         (lease.ticketId ? '  ticket ' + lease.ticketId : '') +
@@ -18638,7 +19199,7 @@ function printComponentsHelp(subcommand) {
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
   console.log('       remits-cli test status --task-id <taskId> [--base-url URL] [--account-id ID] [--branch stagingScope] [--data-mode test|prod] [--json]');
   console.log('       remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--json]   # durable run history');
   console.log('       remits-cli test compare --base <taskId> --head <taskId> [--json]            # per-case outcome/cost deltas');
@@ -18647,11 +19208,15 @@ function printTestHelp() {
   console.log('Examples:');
   console.log('  remits-cli test run --test 11');
   console.log('  remits-cli test run --test "Merchant Statements" --names "managed account case"');
+  console.log('  remits-cli test run --test "Merchant Statements" --failed');
   console.log('  remits-cli test status --task-id 7a1b...');
   console.log('');
   console.log('Notes:');
   console.log('  --names is delimited by "|" (comma also works when no "|" is present), and may be repeated.');
   console.log('    A selector that matches no case fails the run rather than reporting 0 passed / 0 failed.');
+  console.log('  --failed re-runs only the cases that did not pass in your last finished run of this suite on');
+  console.log('       this git branch and staging workspace. Iterate with --failed / --names; run the whole');
+  console.log('       suite once before landing.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
   console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
   console.log('       to force production/subscription semantics from a variant checkout.');
@@ -18836,6 +19401,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 +19417,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 +19476,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]');
@@ -18924,6 +19492,8 @@ async function main() {
     console.log('  remits-cli activity inspect [--account-id ID] [--scope self|children|related] [--workspace NAME] [--workstream ID] [--user-email E] [--summary|--compact] [--json]');
     console.log('  remits-cli workstream status [--workstream ID|--workspace NAME] [--json]');
     console.log('  remits-cli usage --from DATE [--to DATE] [--by hour|day|month] [--group-by account,sku] [--capabilities ai,document_store] [--json]');
+    console.log('  remits-cli capabilities [--json]                       Collaboration features, verbs and refusal codes this platform supports');
+    console.log('  remits-cli policy explain --point commit [--as agent]  What the account rules would decide, and why (nothing applied)');
     console.log('  remits-cli agent release                                            # stop receiving tickets now');
     console.log('  remits-cli start [--foreground true] [--port 8787]                  # human dashboard in the browser');
     console.log('  remits-cli stop');
@@ -18955,7 +19525,7 @@ async function main() {
     console.log('  remits-cli components branch <name> --subscribe <accountId> [--dry-run] [--confirm-primary-edge]');
     console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
     console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
-    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
+    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
     console.log('  remits-cli test runs [--test <id|name>] [--compare]                 # durable run history; compare latest two');
     console.log('  remits-cli test compare --base <taskId> --head <taskId>');
     console.log('  remits-cli corpus import --manifest corpus-manifest.json             # seed a test corpus: cases + artifacts');
@@ -19186,6 +19756,33 @@ async function main() {
     throw new Error('Unknown activity subcommand: ' + subcommand);
   }
 
+  if (command === 'capabilities') {
+    if (wantsHelp) {
+      console.log('Usage: remits-cli capabilities [--json] [--base-url URL]');
+      console.log('');
+      console.log('What this platform build supports for collaboration: negotiated features, the stable verbs and');
+      console.log('how each settles, and what every refusal code means. Read-only; needs no special access.');
+      return;
+    }
+    await capabilitiesCommand(args);
+    return;
+  }
+
+  if (command === 'policy') {
+    if (wantsHelp || subcommand !== 'explain') {
+      console.log('Usage: remits-cli policy explain --point <commit|land|stage|complete|deliver|...> [--workstream W]');
+      console.log('         [--capabilities a,b] [--as human|agent] [--components type:name[:category],...]');
+      console.log('         [--target-account-id ID] [--json]');
+      console.log('');
+      console.log("What this account's remits-policy rules would decide for that action, which rules apply, where");
+      console.log('they come from (document, account distance, final) — without applying anything. The real verb');
+      console.log('re-checks the policy in force when it runs.');
+      return;
+    }
+    await policyExplainCommand(args);
+    return;
+  }
+
   if (command === 'usage') {
     if (wantsHelp) {
       console.log('Usage: remits-cli usage --from DATE [--to DATE] [--timezone ZONE] [--by hour|day|month]');
@@ -19205,7 +19802,7 @@ async function main() {
 
   if (command === 'evidence') {
     if (wantsHelp) {
-      console.log('Usage: remits-cli evidence [--limit N] [--json]');
+      console.log('Usage: remits-cli evidence [--limit N] [--json]   |   remits-cli evidence flush');
       console.log('');
       console.log('What you have actually run, and in which world. Every stage, test, token, tool and sync');
       console.log('appends one world-stamped line automatically - there is nothing to start and nothing to');
@@ -19213,6 +19810,9 @@ async function main() {
       console.log('');
       console.log('This is per-actor, so agents sharing a checkout never read each other\'s trail.');
       console.log('Use `remits-cli verify` only when someone needs a checkable VERDICT on top of this.');
+      console.log('');
+      console.log('Inside a work attempt (REMITS_SUPPORT_TICKET_ID), each line is also queued and published to the');
+      console.log('work item as a passive receipt, so a successor elsewhere can read it. `flush` publishes now.');
       return;
     }
     await evidenceCommand(args);