@remits/remits-cli 0.1.136 → 0.1.137

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- L119  Sessions, Account Resolution, And Production Guards
-- L603  Local State, Workspaces, And Verification Evidence
-- L2624  Account Repos, Guide Sync, And Platform Repo
-- L3432  Component Discovery And HTTP Logging
-- L4073  Skill Delivery And TOC Resolution
-- L4383  Auth And Component Staging
-- L4998  Component Summaries, Status, And Sync Gates
-- L7067  Branches, Promotion, Commit, And Test Runs
-- L8750  Tokens, Tools, Verification, And Config
-- L10177  Service Dashboard And WebSocket Listener
-- L12298  Agent And Ticket Workflows
-- L15888  Help, Auto Update, And Command Dispatch
+- L123  Sessions, Account Resolution, And Production Guards
+- L615  Local State, Workspaces, And Verification Evidence
+- L2652  Account Repos, Guide Sync, And Platform Repo
+- L3460  Component Discovery And HTTP Logging
+- L4107  Skill Delivery And TOC Resolution
+- L4417  Auth And Component Staging
+- L5032  Component Summaries, Status, And Sync Gates
+- L7104  Branches, Promotion, Commit, And Test Runs
+- L9193  Tokens, Tools, Verification, And Config
+- L10620  Service Dashboard And WebSocket Listener
+- L12742  Agent And Ticket Workflows
+- L16337  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -58,6 +58,10 @@ const SERVICE_STATE_FILE = path.join(SESSION_DIR, 'service-state.json');
 const ISSUES_DIR = path.join(SESSION_DIR, 'issues');
 const WEBSOCKET_STATE_FILE = path.join(SESSION_DIR, 'websocket-state.json');
 const AUTO_UPDATE_LOCK_DIR = path.join(SESSION_DIR, 'auto-update.lock');
+const AUTO_UPDATE_STAMP_FILE = path.join(SESSION_DIR, 'auto-update-check.json');
+// `npm view` is a network round trip. It used to run on EVERY command, which is a per-command latency tax
+// on the agents that issue the most commands.
+const AUTO_UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 const AUTO_UPDATE_DISABLED_VALUES = new Set(['0', 'false', 'no', 'off']);
 const REMITS_CLI_PACKAGE_NAME = '@remits/remits-cli';
 const DEFAULT_DATA_MODE = 'test';
@@ -154,6 +158,14 @@ function flagEnabled(value) {
   return value === true || value === 'true' || value === '1' || value === 'yes';
 }
 
+function flagDisabled(value) {
+  return value === false || value === 'false' || value === '0' || value === 'no';
+}
+
+function waitForTestCompletion(flags = {}) {
+  return !(flagDisabled(flags.wait) || flagEnabled(flags['no-wait']) || flagEnabled(flags.noWait));
+}
+
 function withStdoutRoutedToStderr(enabled, fn) {
   if (!enabled) return fn();
   const originalLog = console.log;
@@ -898,6 +910,22 @@ function printLocalStateWarnings(cwd, flags = {}) {
   warnings.forEach((warning) => console.log('  - ' + warning));
 }
 
+/**
+ * "Your remits-cli is older than this platform's" - printed once per process, from ONE place.
+ *
+ * The platform attaches `cliAdvisory` to the two responses every working loop passes through (stage and
+ * test-run start) and returns nothing at all when the caller is current, so this renders only when there
+ * is something to act on. stderr, because a `--json` caller's stdout is a document.
+ */
+let cliAdvisoryPrinted = false;
+function printCliAdvisory(response) {
+  const advisory = response && response.cliAdvisory;
+  if (!advisory || cliAdvisoryPrinted) return;
+  cliAdvisoryPrinted = true;
+  console.error('');
+  console.error('[remits-cli ' + (advisory.current || '?') + ' -> ' + (advisory.expected || '?') + '] ' + advisory.message);
+}
+
 function printLocalCommandContext(cwd, flags = {}, context = {}) {
   const paths = localStatePaths(cwd);
   const branchName = context.branchName || flags.branch || safeGitValue(cwd, 'git rev-parse --abbrev-ref HEAD') || 'unknown';
@@ -3834,6 +3862,12 @@ function stageTimeoutMs(components, flags = {}) {
 
 function buildAxios(baseUrl, token, timeoutMs = 60000) {
   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
+  // loop hardest are exactly the ones that never do. Without it the platform cannot tell an agent that the
+  // diagnostics it is missing exist, and every output improvement lands invisibly.
+  const cliVersion = readCliVersion();
+  if (cliVersion) headers['X-Remits-Cli-Version'] = cliVersion;
   return axios.create({ baseURL: baseUrl, timeout: parsePositiveInt(timeoutMs, 60000), headers });
 }
 
@@ -5232,6 +5266,9 @@ function printStageSummary(response, flags) {
   if (typeof printAccountLanes === 'function') {
     printAccountLanes(response);
   }
+  if (typeof printCliAdvisory === 'function') {
+    printCliAdvisory(response);
+  }
   printComponentCommandResponse('Components stage', response, flags);
 }
 
@@ -7083,6 +7120,10 @@ async function branchesComponentsCommand(flags) {
   // after the subcommand is the branch name when present.
   const positional = flags._ && flags._[2];
   const branchName = flags.branch || positional;
+  const copyToBranch = flags['copy-to'] || flags.copyTo;
+  if ((flags['copy-to'] !== undefined || flags.copyTo !== undefined) && !branchName) {
+    throw new Error('components branch <source> --copy-to <target> requires a source branch name');
+  }
 
   // Without a branch there is nothing to detail, so always list. With one, the mutating flags
   // (--subscribe/--unsubscribe/--retire) win, then the narrower read views, and the default is the
@@ -7092,10 +7133,14 @@ async function branchesComponentsCommand(flags) {
     if (flags.subscribe !== undefined) mode = 'subscribe';
     else if (flags.unsubscribe !== undefined) mode = 'unsubscribe';
     else if (flagEnabled(flags.retire)) mode = 'retire';
+    else if (flags['copy-to'] !== undefined || flags.copyTo !== undefined) mode = 'copy';
     else if (flags.diff !== undefined) mode = 'diff';
     else if (flagEnabled(flags.subscribers)) mode = 'subscribers';
     else mode = 'status';
   }
+  if (mode === 'copy' && (copyToBranch === true || !String(copyToBranch || '').trim())) {
+    throw new Error('components branch <source> --copy-to <target> requires a target branch name');
+  }
 
   // `--diff 42` carries the component id inline; a bare `--diff` falls back to --component-id/--name.
   const componentId = mode === 'diff'
@@ -7118,6 +7163,7 @@ async function branchesComponentsCommand(flags) {
     componentType: flags['component-type'] || flags.type,
     componentId,
     componentName: flags['component-name'] || flags.name,
+    targetBranchName: copyToBranch,
     subscribeAccountId,
     parentAccountId: flags['parent-account'],
     // Optional branch-scoped custom host set on the same edge as the subscription.
@@ -7241,6 +7287,33 @@ function printBranchesSummary(response) {
     return;
   }
 
+  if (response.mode === 'copy') {
+    console.log(response.message || ('Copied branch overlays to ' + response.targetBranch));
+    console.log('Source branch:', response.branch);
+    console.log('Target branch:', response.targetBranch);
+    // A dry run writes nothing, so `copied` is 0 by contract — printing it as "Copied overlays: 0"
+    // under a "Would copy 2" message reads as a failed copy. Name the plan instead.
+    if (response.dryRun) {
+      console.log('Plan only (dry run) — overlays that would be copied:', response.plannedCopies || 0);
+      if (response.existingCount) console.log('Existing overlays that would be replaced:', response.existingCount);
+    } else {
+      console.log('Copied overlays:', response.copied || 0);
+      if (response.overwritten) console.log('Replaced existing overlays:', response.overwritten);
+    }
+    // A source overlay that is identical to trunk in both content and metadata is sparse and is never
+    // stored, so it is named rather than silently missing from the count.
+    const skippedSparse = response.skippedIdenticalToTrunk || [];
+    if (skippedSparse.length) {
+      console.log('Skipped as identical to trunk:', skippedSparse.join(', '));
+    }
+    // The number an operator needs BEFORE deciding to pass --force: a target branch with live
+    // subscribers is code those accounts are running right now.
+    if (response.targetSubscriberCount) {
+      console.log('Live subscribers on the target branch:', response.targetSubscriberCount);
+    }
+    return;
+  }
+
   if (response.mode === 'subscribe' || response.mode === 'unsubscribe' || response.mode === 'retire') {
     console.log(response.message);
     if (response.requiresConfirmation) {
@@ -7852,7 +7925,7 @@ async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dat
       dataMode
     }).then((r) => r.data);
 
-    if (status.status === 'completed' || status.status === 'failed') {
+    if (testStatusIsTerminal(status)) {
       return status;
     }
     await new Promise((r) => setTimeout(r, pollDelayMs));
@@ -7860,6 +7933,10 @@ async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dat
   }
 }
 
+function testStatusIsTerminal(status = {}) {
+  return ['completed', 'failed', 'interrupted'].includes(String(status.status || '').toLowerCase());
+}
+
 function testEvidenceCategories(status = {}, selectedNames = []) {
   const categories = new Set(['test_run']);
   const test = status.test || {};
@@ -7989,6 +8066,108 @@ function detectNondeterministicTestRun(priorPackets, currentStatus, currentProve
   return null;
 }
 
+async function appendTerminalTestRunEvidence(options = {}) {
+  const {
+    api,
+    cwd,
+    session,
+    accountId,
+    flags,
+    status,
+    testRef,
+    selectedNames = [],
+    dataMode,
+    dataModeSource,
+    branchName,
+    workspace,
+    baseUrl,
+    activeEnvelopeId,
+    quiet
+  } = options;
+  const unmatched = (status.result && status.result.unmatchedTestNames) || [];
+  const componentProvenance = testComponentProvenance(status);
+  const sourceRevision = collectVerificationSource(cwd, flags);
+  const priorPackets = await readVerificationPacketsForDiagnostics(api, cwd, session, accountId, activeEnvelopeId, {
+    packetType: 'test_run',
+    suite: status.test && status.test.name,
+    max: 50
+  });
+  const nondeterminism = detectNondeterministicTestRun(priorPackets, status, componentProvenance, {
+    laneContentHash: status.staging && status.staging.laneSummary && status.staging.laneSummary.contentHash,
+    gitHead: sourceRevision.gitHead
+  });
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'test_run',
+    success: status.status === 'completed' && !(status.result && status.result.failed > 0) && !unmatched.length,
+    claim: 'Test run ' + String(testRef || (status.test && (status.test.name || status.test.id)) || status.taskId || 'unknown'),
+    world: buildCommandWorld(status, {
+      accountId,
+      dataMode: status.dataMode || dataMode,
+      dataModeSource,
+      branchName,
+      workspace,
+      host: normalizeBaseUrl(baseUrl),
+      sourceLayer: status.staging && status.staging.testComponentSource
+    }),
+    revision: Object.assign(sourceRevision, {
+      compileSignatures: testCompileSignatures(status),
+      componentProvenance
+    }),
+    nondeterministic: nondeterminism ? true : undefined,
+    nondeterminism: nondeterminism || undefined,
+    test: {
+      taskId: status.taskId || (status.result && status.result.taskId),
+      testId: status.test && status.test.id,
+      testName: status.test && status.test.name,
+      selectedCases: selectedNames,
+      passed: status.result && status.result.passed,
+      failed: status.result && status.result.failed,
+      tests: status.result && status.result.tests,
+      dataModeSource: status.dataModeSource || dataModeSource,
+      unmatchedTestNames: unmatched
+    },
+    evidenceCategories: testEvidenceCategories(status, selectedNames),
+    // What the run spent and whether that live AI was declared (withAiBudget), so an envelope can tell a
+    // measurement run from a suite with missing mocks without re-reading every case.
+    dependencies: testRunDependencies(status),
+    summary: status.result && status.result.summary,
+    limitations: []
+      .concat(unmatched.length ? ['One or more requested test case selectors matched no case.'] : [])
+      .concat(nondeterminism ? [nondeterminism.message] : []),
+    rawRefs: { testStatusKey: status.taskId, durableTestRun: status.result && status.result.durableRecord ? status.taskId : undefined },
+    status
+  }, { quiet });
+
+  return { unmatched, nondeterminism };
+}
+
+/**
+ * One failed case per distinct failure root, largest root first, capped.
+ *
+ * A pivot block per failed case is one problem stated N times: the thirty-three failures of a real suite
+ * are twenty-one roots, and the twelve repeats carry the same trace shape, the same components and the
+ * same error. The grouped roll-up above already names every case; this picks the ones worth a full block.
+ */
+/** Truncate, and SAY that it was truncated — a silent cut reads as the whole message. */
+function truncateForPivot(text, max) {
+  if (text.length <= max) return text;
+  return text.slice(0, max) + '… (truncated; --json for the full text)';
+}
+
+function selectPivotCases(tests, limit = 6) {
+  const failed = (tests || []).filter((test) => test && test.passed === false);
+  const seen = new Set();
+  const representatives = [];
+  failed.forEach((test) => {
+    const root = testFailureRoot(test);
+    if (seen.has(root)) return;
+    seen.add(root);
+    representatives.push(test);
+  });
+  return { shown: representatives.slice(0, limit), failedCount: failed.length, rootCount: representatives.length };
+}
+
 function printTestRunPivots(status = {}) {
   const tests = status.result && Array.isArray(status.result.tests) ? status.result.tests : [];
   if (!tests.length) return;
@@ -7996,7 +8175,8 @@ function printTestRunPivots(status = {}) {
   if (slowest && slowest.duration != null) {
     console.log('Slowest case:', (slowest.name || '(unnamed)') + ' in ' + formatDurationMs(slowest.duration));
   }
-  tests.filter((test) => test && test.passed === false).forEach((test) => {
+  const selection = selectPivotCases(tests);
+  selection.shown.forEach((test) => {
     console.log('Pivots for failed case:', test.name || '(unnamed)');
     if (test.outcome) console.log('  Outcome:', test.outcome + (test.outcomeReason && test.outcomeReason !== test.error ? ' - ' + String(test.outcomeReason).slice(0, 300) : ''));
     if (test.duration != null) console.log('  Duration:', formatDurationMs(test.duration));
@@ -8007,7 +8187,9 @@ function printTestRunPivots(status = {}) {
     if (test.threadGroupingId || test.threadGroupId || test.traceId) {
       console.log('  Trace:', test.traceId || test.threadGroupingId || test.threadGroupId);
     }
-    if (test.error) console.log('  Error:', String(test.error).slice(0, 500));
+    // 500 chars cut the replay diagnosis mid-sentence, losing the half that says what to DO. A pivot is the
+    // block a reader acts on; truncating its one actionable sentence to save four lines is a bad trade.
+    if (test.error) console.log('  Error:', truncateForPivot(String(test.error), 1200));
     const diagnostics = test.diagnostics && typeof test.diagnostics === 'object' ? test.diagnostics : null;
     if (diagnostics && Object.keys(diagnostics).length) {
       console.log('  Diagnostics:', JSON.stringify(diagnostics).slice(0, 1200));
@@ -8023,6 +8205,12 @@ function printTestRunPivots(status = {}) {
       console.log('  Live HTTP calls:', test.liveHttpCalls.length + (intentional ? ' (' + intentional + ' intentional, inside withAiBudget)' : ''));
     }
   });
+  // Named, not silently dropped: a reader must be able to tell "this is everything" from "this is a sample".
+  if (selection.rootCount > selection.shown.length) {
+    console.log('Pivots shown for ' + selection.shown.length + ' of ' + selection.rootCount +
+      ' failure root(s) (' + selection.failedCount + ' failed case(s)). Every root is listed above; ' +
+      'use --names "<case>" for one, or --json for all.');
+  }
 }
 
 function formatDurationMs(value) {
@@ -8236,6 +8424,114 @@ function stagedMaskedByVariantLines(masked, accountId) {
   return lines;
 }
 
+/**
+ * The assertion ROOT of one failed case: what broke, with the particulars of this case removed.
+ *
+ * Deliberately built only from properties of the JVM/Groovy failure format - a power-assert's
+ * `Expression:`/`Values:` decoration, an `assert <expr>` head, an exception class prefix - and never from
+ * any vocabulary a suite happens to use. Identifiers and numbers are replaced because two cases failing
+ * the same way differ exactly in those.
+ */
+function testFailureRoot(test = {}) {
+  let text = String(test.error || test.outcomeReason || test.outcome || 'failed').trim();
+  // Groovy's power assert appends the rendered expression and every intermediate value.
+  text = text.split(/\.\s+(?:Expression|Values):/)[0];
+  const assertion = text.match(/assert\s+(.+)$/);
+  if (assertion) text = 'assert ' + assertion[1];
+  text = text
+    .replace(/['"][0-9a-fA-F]{8}-[0-9a-fA-F-]{4,}['"]/g, "'<id>'")
+    .replace(/\b[0-9a-fA-F]{8}-[0-9a-fA-F-]{27,}\b/g, '<id>')
+    .replace(/\b\d[\d.,]*\b/g, '<n>')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= FAILURE_ROOT_LABEL_CHARS) return text;
+  // Cut on a word boundary: "found no usable stored provid" reads as a different error than the one it is.
+  const cut = text.slice(0, FAILURE_ROOT_LABEL_CHARS);
+  const lastSpace = cut.lastIndexOf(' ');
+  return (lastSpace > FAILURE_ROOT_LABEL_CHARS * 0.6 ? cut.slice(0, lastSpace) : cut) + '\u2026';
+}
+
+/** Long enough to tell two failures apart, short enough that a root list stays a list. */
+const FAILURE_ROOT_LABEL_CHARS = 120;
+
+/**
+ * Failed cases grouped by that root, largest first.
+ *
+ * Thirty-three failures printed in run order read as thirty-three problems; the same run grouped is four.
+ * This is the line that decides whether the next move is a narrow root-cause pass or another broad rerun,
+ * so it is computed from the run itself rather than left to the reader.
+ */
+function testFailureGroups(status = {}) {
+  const tests = status.result && Array.isArray(status.result.tests) ? status.result.tests : [];
+  const groups = new Map();
+  tests.filter((test) => test && test.passed === false && !test.interrupted).forEach((test) => {
+    const root = testFailureRoot(test);
+    if (!groups.has(root)) groups.set(root, { root, count: 0, cases: [] });
+    const group = groups.get(root);
+    group.count += 1;
+    group.cases.push(test.name || '(unnamed)');
+  });
+  return Array.from(groups.values()).sort((left, right) => right.count - left.count || left.root.localeCompare(right.root));
+}
+
+const FAILURE_GROUPS_SHOWN = 8;
+
+function testFailureGroupLines(status = {}, options = {}) {
+  const groups = testFailureGroups(status);
+  if (!groups.length) return [];
+  const failed = groups.reduce((sum, group) => sum + group.count, 0);
+  const lines = [''];
+  lines.push('Failure roots (' + failed + ' failed case(s), ' + groups.length + ' distinct root(s)):');
+  groups.slice(0, FAILURE_GROUPS_SHOWN).forEach((group) => {
+    lines.push('  ' + String(group.count) + 'x  ' + group.root);
+    // The representative case is what `--names` takes, so the next command is a copy of this line.
+    lines.push('        e.g. ' + group.cases[0] + (group.count > 1 ? '  (+' + (group.count - 1) + ' more)' : ''));
+  });
+  if (groups.length > FAILURE_GROUPS_SHOWN) {
+    lines.push('  ...' + (groups.length - FAILURE_GROUPS_SHOWN) + ' more root(s); --json for all');
+  }
+  const testRef = options.testRef || (status.test && (status.test.id || status.test.name)) ||
+    (status.result && (status.result.testId || status.result.testName));
+  if (groups[0] && groups[0].count > 1 && testRef) {
+    lines.push('Largest root first: remits-cli test run --test ' + JSON.stringify(String(testRef)) +
+      ' --names ' + JSON.stringify(groups[0].cases[0]));
+  }
+  return lines;
+}
+
+/**
+ * The verdict of a run in four lines, shared by `test run` and `test status`.
+ *
+ * `test run` used to print the whole run object as pretty JSON before its human summary. Measured on one
+ * 92-case suite that is 220 KB - most of it per-case ids repeated once per case - spent by the command an
+ * agent runs most often, on the turn where it has the least room left to reason. Every byte is still one
+ * `--json` away.
+ */
+function testRunHeadlineLines(status = {}, options = {}) {
+  const result = status.result || {};
+  const lines = [];
+  lines.push('Test run status: ' + (status.status || 'unknown'));
+  if (options.taskId || status.taskId) lines.push('Task ID: ' + (options.taskId || status.taskId));
+  if (options.source) lines.push('Source: ' + options.source);
+  const actualDataMode = status.dataMode || result.dataMode || options.dataMode;
+  let dataModeLine = 'Data mode: ' + (actualDataMode || 'unknown');
+  // A durable run answers about the lane it RAN in, which need not be the lane this command asked for.
+  // Reporting only the run's own lane is correct and reads as if the request had been honoured.
+  if (options.requestedDataMode && actualDataMode && options.requestedDataMode !== actualDataMode) {
+    dataModeLine += '   (you asked for ' + options.requestedDataMode + '; this run was recorded in the ' +
+      actualDataMode + ' lane, and that is what it proves)';
+  }
+  lines.push(dataModeLine);
+  if (result.total != null || result.passed != null) {
+    lines.push('Cases: ' + (result.passed || 0) + ' passed, ' + (result.failed || 0) + ' failed, ' +
+      (result.total || 0) + ' total');
+  }
+  if (status.error || status.message || result.error) {
+    lines.push('Message: ' + (status.error || status.message || result.error));
+  }
+  return lines;
+}
+
 // The corpus-style roll-up printed after a run: outcome counts, case duration percentiles, AI usage split
 // live/mocked, and the durable record. Built only from the result the platform returned.
 function testRunSummaryLines(status = {}) {
@@ -8491,6 +8787,7 @@ async function testCommand(flags) {
     printLocalStateWarnings(cwd, flags);
     printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
     printStagingLaneOwnerNotice(start.staging || {});
+    printCliAdvisory(start);
     if (start.staging && Array.isArray(start.staging.accountLanes)) {
       printOrphanedWorkspaceWarning(start.staging);
       printAccountLanes({ accountLanes: start.staging.accountLanes, branchName, workspace });
@@ -8506,6 +8803,48 @@ async function testCommand(flags) {
   });
   runtimeState.currentTestTaskId = start.taskId;
 
+  const waitForCompletion = waitForTestCompletion(flags);
+  if (!waitForCompletion) {
+    recordEvidenceEntry(cwd, {
+      type: 'test_run',
+      success: null,
+      pending: true,
+      claim: 'Test run ' + String(testRef),
+      world: buildCommandWorld(start, {
+        accountId,
+        dataMode,
+        dataModeSource,
+        branchName,
+        workspace,
+        host: normalizeBaseUrl(baseUrl),
+        sourceLayer: start.staging && start.staging.testComponentSource
+      }),
+      test: {
+        taskId: start.taskId,
+        testId: start.test && start.test.id,
+        testName: start.test && start.test.name,
+        selectedCases: names,
+        dataModeSource
+      },
+      evidenceCategories: testEvidenceCategories(start, names),
+      rawRefs: { testStatusKey: start.taskId },
+      status: start
+    }, { accountId, dataMode, branchName, workspace, baseUrl: normalizeBaseUrl(baseUrl), envelopeId: activeEnvelopeId });
+    runtimeState.currentTestTaskId = null;
+    if (jsonOutput) {
+      console.log(JSON.stringify(Object.assign({}, start, {
+        pending: true,
+        wait: false,
+        statusCommand: 'remits-cli test status --task-id ' + start.taskId
+      }), null, 2));
+    } else {
+      console.log('Not waiting (--wait false).');
+      console.log('Poll this run: remits-cli test status --task-id ' + start.taskId);
+      console.log('Terminal evidence attaches when `test status` reads a completed, failed or interrupted run.');
+    }
+    return;
+  }
+
   let stopWs = null;
   if (flags.watch !== 'false') {
     const topic = session.websocketTopic || start.websocketTopic || (session.user && String(session.user.uuid || '').replace(/-/g, ''));
@@ -8526,10 +8865,16 @@ async function testCommand(flags) {
   if (jsonOutput) {
     console.log(JSON.stringify(status, null, 2));
   } else {
-    console.log('Final status:', JSON.stringify(status, null, 2));
     printStagingLaneOwnerNotice(status.staging || {});
+    testRunHeadlineLines(status, { taskId: start.taskId, dataMode, requestedDataMode: dataMode })
+      .forEach((line) => console.log(line));
     testRunSummaryLines(status).forEach((line) => console.log(line));
+    testFailureGroupLines(status, { testRef }).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
+    // still one flag away, and the durable record keeps it after the live status expires.
+    console.log('Full run payload: remits-cli test status --task-id ' + start.taskId + ' --json');
   }
 
   // A selector that matched no case is a mis-specified run, not a passing one. Say so in the terminal
@@ -8554,17 +8899,24 @@ async function testCommand(flags) {
     process.exitCode = 1;
   }
 
-  const componentProvenance = testComponentProvenance(status);
-  const sourceRevision = collectVerificationSource(cwd, flags);
-  const priorPackets = await readVerificationPacketsForDiagnostics(api, cwd, session, accountId, activeEnvelopeId, {
-    packetType: 'test_run',
-    suite: status.test && status.test.name,
-    max: 50
-  });
-  const nondeterminism = detectNondeterministicTestRun(priorPackets, status, componentProvenance, {
-    laneContentHash: status.staging && status.staging.laneSummary && status.staging.laneSummary.contentHash,
-    gitHead: sourceRevision.gitHead
+  const evidence = await appendTerminalTestRunEvidence({
+    api,
+    cwd,
+    session,
+    accountId,
+    flags: verification.evidenceFlags,
+    status,
+    testRef,
+    selectedNames: names,
+    dataMode,
+    dataModeSource,
+    branchName,
+    workspace,
+    baseUrl,
+    activeEnvelopeId,
+    quiet: jsonOutput
   });
+  const nondeterminism = evidence.nondeterminism;
   if (nondeterminism && !jsonOutput) {
     console.log('Nondeterministic signal:', nondeterminism.message);
     nondeterminism.flips.slice(0, 6).forEach((flip) => {
@@ -8572,40 +8924,6 @@ async function testCommand(flags) {
         ' (previous packet ' + (flip.previousPacketId || 'unknown') + ')');
     });
   }
-
-  await appendVerificationPacket(api, cwd, session, accountId, verification.evidenceFlags, {
-    type: 'test_run',
-    success: status.status === 'completed' && !(status.result && status.result.failed > 0) && !unmatched.length,
-    claim: 'Test run ' + String(testRef),
-    world: buildCommandWorld(status, { accountId, dataMode: status.dataMode || dataMode, dataModeSource, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: status.staging && status.staging.testComponentSource }),
-    revision: Object.assign(sourceRevision, {
-      compileSignatures: testCompileSignatures(status),
-      componentProvenance
-    }),
-    nondeterministic: nondeterminism ? true : undefined,
-    nondeterminism: nondeterminism || undefined,
-    test: {
-      taskId: start.taskId,
-      testId: status.test && status.test.id,
-      testName: status.test && status.test.name,
-      selectedCases: names,
-      passed: status.result && status.result.passed,
-      failed: status.result && status.result.failed,
-      tests: status.result && status.result.tests,
-      dataModeSource: status.dataModeSource || dataModeSource,
-      unmatchedTestNames: unmatched
-    },
-    evidenceCategories: testEvidenceCategories(status, names),
-    // What the run spent and whether that live AI was declared (withAiBudget), so an envelope can tell a
-    // measurement run from a suite with missing mocks without re-reading every case.
-    dependencies: testRunDependencies(status),
-    summary: status.result && status.result.summary,
-    limitations: []
-      .concat(unmatched.length ? ['One or more requested test case selectors matched no case.'] : [])
-      .concat(nondeterminism ? [nondeterminism.message] : []),
-    rawRefs: { testStatusKey: start.taskId, durableTestRun: status.result && status.result.durableRecord ? start.taskId : undefined },
-    status
-  }, { quiet: jsonOutput });
 }
 
 async function testStatusCommand(flags) {
@@ -8615,9 +8933,11 @@ async function testStatusCommand(flags) {
   const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
+  const workspace = resolveWorkspace(cwd, flags);
   const dataMode = hasExplicitDataModeFlag(flags)
     ? resolveDataMode(flags, null)
     : DEFAULT_DATA_MODE;
+  const dataModeSource = dataModeFlagSource(flags);
   const taskId = flags['task-id'] || flags.taskId || flags.id || (flags._ && flags._[2]);
   const jsonOutput = flagEnabled(flags.json);
   if (!taskId) throw new Error('Missing --task-id <taskId>');
@@ -8631,31 +8951,94 @@ async function testStatusCommand(flags) {
     taskId,
     dataMode
   }).then((r) => r.data);
+  if (!status.taskId) status.taskId = taskId;
+
+  let statusVerification = { envelopeId: null, evidenceFlags: flags };
+  if (testStatusIsTerminal(status)) {
+    statusVerification = await verificationPreflight(api, cwd, session, accountId, flags, {
+      packetType: 'test_run',
+      world: buildCommandWorld(status, {
+        accountId,
+        dataMode: status.dataMode || dataMode,
+        dataModeSource,
+        branchName,
+        workspace,
+        host: normalizeBaseUrl(baseUrl),
+        sourceLayer: status.staging && status.staging.testComponentSource
+      }),
+      test: status.test && status.test.id !== undefined && status.test.id !== null
+        ? { testId: status.test.id, testName: status.test.name }
+        : { testName: status.test && status.test.name }
+    }, { command: 'test status', neverRefuse: true, quiet: jsonOutput });
+  }
 
   if (jsonOutput) {
+    if (testStatusIsTerminal(status)) {
+      await appendTerminalTestRunEvidence({
+        api,
+        cwd,
+        session,
+        accountId,
+        flags: statusVerification.evidenceFlags,
+        status,
+        testRef: status.test && (status.test.name || status.test.id) || taskId,
+        selectedNames: status.result && Array.isArray(status.result.tests) ? status.result.tests.map((t) => t && t.name).filter(Boolean) : [],
+        dataMode,
+        dataModeSource,
+        branchName,
+        workspace,
+        baseUrl,
+        activeEnvelopeId: statusVerification.envelopeId,
+        quiet: true
+      });
+    }
     console.log(JSON.stringify(status, null, 2));
     return status;
   }
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
-  console.log('Test run status:', status.status || 'unknown');
-  console.log('Task ID:', taskId);
   // Say where this answer came from. A durable record is a finished snapshot rebuilt from the database after the
   // live status was gone; without this line a reconstructed run is indistinguishable from one still being watched.
-  console.log('Source:', status.durable
-    ? 'durable run record (the live status has expired; this run is final)'
-    : 'live run status');
-  console.log('Data mode:', status.dataMode || dataMode);
-  if (status.result) {
-    console.log('Cases:', (status.result.passed || 0) + ' passed, ' + (status.result.failed || 0) + ' failed, ' + (status.result.total || 0) + ' total');
-  }
-  if (status.error || status.message) {
-    console.log('Message:', status.error || status.message);
-  }
+  testRunHeadlineLines(status, {
+    taskId,
+    source: status.durable
+      ? 'durable run record (the live status has expired; this run is final)'
+      : 'live run status',
+    dataMode,
+    // A durable run reports the lane it RAN in. When that differs from the lane this command asked for,
+    // say so: auditing prod activity and being handed a test-lane run is correct and reads as if it were not.
+    requestedDataMode: hasExplicitDataModeFlag(flags) ? dataMode : null
+  }).forEach((line) => console.log(line));
   if (status.world) runWorldLines(status.world, { host: normalizeBaseUrl(baseUrl) }).forEach((line) => console.log(line));
   testRunSummaryLines(status).forEach((line) => console.log(line));
+  testFailureGroupLines(status).forEach((line) => console.log(line));
   printTestRunPivots(status);
-  if (status.status === 'failed' || (status.result && status.result.failed > 0)) {
+  if (testStatusIsTerminal(status)) {
+    const evidence = await appendTerminalTestRunEvidence({
+      api,
+      cwd,
+      session,
+      accountId,
+      flags: statusVerification.evidenceFlags,
+      status,
+      testRef: status.test && (status.test.name || status.test.id) || taskId,
+      selectedNames: status.result && Array.isArray(status.result.tests) ? status.result.tests.map((t) => t && t.name).filter(Boolean) : [],
+      dataMode,
+      dataModeSource,
+      branchName,
+      workspace,
+      baseUrl,
+      activeEnvelopeId: statusVerification.envelopeId
+    });
+    if (evidence.nondeterminism) {
+      console.log('Nondeterministic signal:', evidence.nondeterminism.message);
+      evidence.nondeterminism.flips.slice(0, 6).forEach((flip) => {
+        console.log('  - ' + flip.caseName + ': ' + (flip.previousPassed ? 'passed' : 'failed') + ' -> ' + (flip.currentPassed ? 'passed' : 'failed') +
+          ' (previous packet ' + (flip.previousPacketId || 'unknown') + ')');
+      });
+    }
+  }
+  if (status.status === 'failed' || status.status === 'interrupted' || (status.result && status.result.failed > 0)) {
     process.exitCode = 1;
   }
   return status;
@@ -8671,10 +9054,13 @@ async function testRunsCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const api = buildAxios(baseUrl, session.token);
   const testRef = flags.test || flags['test-id'] || flags.name;
+  const allDataLanes = flagEnabled(flags['all-lanes']) || flagEnabled(flags['all-data-lanes']);
   const data = await loggedPost(api, cwd, '/cli/testRuns', {
     token: session.token,
     accountId,
     asAccountId: flags['as-account'] || flags['as-account-id'],
+    dataMode: resolveDataMode(flags, session),
+    allDataLanes: allDataLanes || undefined,
     testId: testRef && /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: testRef && !/^\d+$/.test(String(testRef)) ? String(testRef) : undefined,
     max: flags.limit || flags.max || 20
@@ -8682,9 +9068,17 @@ async function testRunsCommand(flags) {
   if (!data.success) throw new Error(data.message || 'Could not list test runs');
 
   if (flagEnabled(flags.compare)) {
-    const runs = data.runs || [];
-    if (runs.length < 2) throw new Error('--compare needs at least two recorded runs' + (testRef ? ' of ' + testRef : '') + '; found ' + runs.length);
-    return testCompareCommand(Object.assign({}, flags, { base: runs[1].taskId, head: runs[0].taskId }));
+    const pair = selectComparableRuns(data.runs || []);
+    if (!pair) {
+      throw new Error('--compare needs two COMPARABLE recorded runs' + (testRef ? ' of ' + testRef : '') +
+        ' — same data lane, branch, workspace and case count. Found ' + (data.runs || []).length +
+        ' run(s); pick two explicitly with: remits-cli test compare --base <taskId> --head <taskId>');
+    }
+    if (pair.skipped) {
+      console.error('Comparing the latest two comparable runs (' + describeRunShape(pair.head) + '); ' +
+        pair.skipped + ' newer run(s) differ in lane, branch, workspace or case count and were skipped.');
+    }
+    return testCompareCommand(Object.assign({}, flags, { base: pair.base.taskId, head: pair.head.taskId }));
   }
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(data, null, 2));
@@ -8693,6 +9087,9 @@ async function testRunsCommand(flags) {
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log('Recorded test runs' + (testRef ? ' for ' + testRef : '') + ' (account ' + data.accountId + '), newest first:');
+  // Which lane this list is, said once. Pass counts from two lanes are two different facts.
+  console.log('Data lane: ' + (data.dataLaneScope || 'all-data-lanes') +
+    (data.otherLaneCount ? '   (' + data.otherLaneCount + ' more run(s) in the other lane; --all-lanes to include)' : ''));
   (data.runs || []).forEach((run) => {
     console.log('- ' + run.taskId + '  ' + (run.status || 'unknown') + '  ' + (run.passed || 0) + '/' + (run.total || 0) + ' passed' +
       '  ' + corpusAiLabel(run) +
@@ -8705,6 +9102,40 @@ async function testRunsCommand(flags) {
   return data;
 }
 
+/** The world fields that decide whether two runs are the same experiment repeated. */
+function runShapeKey(run = {}) {
+  return [run.dataMode || '?', run.branchName || '?', run.workspace || 'shared',
+    run.variantBranch || 'none', run.total == null ? '?' : run.total].join('|');
+}
+
+function describeRunShape(run = {}) {
+  return [(run.dataMode || '?') + ' lane', run.branchName || '?',
+    run.workspace ? 'ws:' + run.workspace : 'shared lane',
+    (run.total == null ? '?' : run.total) + ' case(s)'].join(' · ');
+}
+
+/**
+ * The newest two runs that are actually comparable, and how many newer ones were passed over.
+ *
+ * `--compare` used to take runs[0] and runs[1] unconditionally. On a real history that pairs a 92-case
+ * suite with a 1-case `--names` probe, or a prod-lane run with a test-lane one, and reports the difference
+ * as regressions. A comparison across worlds is not a comparison.
+ */
+function selectComparableRuns(runs) {
+  const list = Array.isArray(runs) ? runs.filter(Boolean) : [];
+  for (let head = 0; head < list.length; head += 1) {
+    const key = runShapeKey(list[head]);
+    for (let base = head + 1; base < list.length; base += 1) {
+      if (runShapeKey(list[base]) === key) {
+        // Every run passed over, including the ones BETWEEN head and base — a 1-case probe sitting between
+        // two full suites is exactly the run whose absence from the comparison needs saying.
+        return { head: list[head], base: list[base], skipped: base - 1 };
+      }
+    }
+  }
+  return null;
+}
+
 // `test compare --base <taskId> --head <taskId>`: per-case outcome, cost and duration deltas between two runs,
 // read from the durable records.
 async function testCompareCommand(flags) {
@@ -8735,6 +9166,18 @@ async function testCompareCommand(flags) {
     .filter((key) => comparison.baseWorld && comparison.headWorld && String(comparison.baseWorld[key] || '') !== String(comparison.headWorld[key] || ''))
     .map((key) => key + ' ' + short(String(comparison.baseWorld[key] || 'none')) + ' -> ' + short(String(comparison.headWorld[key] || 'none')));
   if (worldDiff.length) console.log('World changed: ' + worldDiff.join('; '));
+  // A lane or case-count difference is not a delta to interpret, it is two different experiments. Say so
+  // rather than letting "regressed (33)" stand for "these runs never measured the same thing".
+  const baseLane = comparison.baseWorld && comparison.baseWorld.dataMode;
+  const headLane = comparison.headWorld && comparison.headWorld.dataMode;
+  if (baseLane && headLane && baseLane !== headLane) {
+    console.log('NOT COMPARABLE: these runs are in different DATA LANES (' + baseLane + ' vs ' + headLane +
+      '). A record\'s dataMode is the lane it was written in; the pass counts below are two different facts.');
+  }
+  if (comparison.base.total && comparison.head.total && comparison.base.total !== comparison.head.total) {
+    console.log('NOT COMPARABLE like-for-like: ' + comparison.base.total + ' case(s) vs ' + comparison.head.total +
+      '. One of these is a narrowed --names run; "absent" below means the case did not run, not that it broke.');
+  }
   if (comparison.improved.length) console.log('Improved (' + comparison.improved.length + '): ' + comparison.improved.join(', '));
   if (comparison.regressed.length) console.log('Regressed (' + comparison.regressed.length + '): ' + comparison.regressed.join(', '));
   comparison.changed.filter((c) => c.direction === 'changed').forEach((c) => console.log('Changed: ' + c.name + ' ' + c.base + ' -> ' + c.head));
@@ -10898,6 +11341,7 @@ function buildRepoSnapshot(entry) {
   const repoFiles = [
     { label: 'account-info.json', path: entry.accountInfoPath || path.join(directory, 'account-info.json'), mode: 'json' },
     { label: 'account-hierarchy.json', path: path.join(directory, 'account-hierarchy.json'), mode: 'json' },
+    { label: 'account-analytics.json', path: path.join(directory, 'account-analytics.json'), mode: 'json' },
     { label: '.remits-cli/active-actor/current-session.txt', path: localPaths.currentSessionFile, mode: 'text' },
     { label: '.remits-cli/shared/tools/tools.json', path: path.join(localPaths.toolsDir, 'tools.json'), mode: 'json' },
     { label: '.remits-cli/active-actor/session log (tail)', path: currentSessionLog, mode: 'tail' },
@@ -15143,7 +15587,12 @@ function printActivityInspectSummary(response) {
       if (env.noRequiredEvidence) {
         console.log('      evidence log — no verdict requested; add a claim only if someone needs one: remits-cli verify claim <id> --text "..." --envelope ' + env.envelopeId);
       }
-      if (env.currentFailureCount) console.log('      current failures: ' + env.currentFailureCount);
+      // A failure recorded in an envelope that promised nothing is HISTORY, not an outstanding task — the
+      // same rule the smells already apply (`promises` in activitySmells). Printing it as "current failures"
+      // re-created, one line lower, exactly the unfinishable-looking work the evidence/verdict split removed.
+      if (env.currentFailureCount) {
+        console.log('      ' + (env.noRequiredEvidence ? 'failed evidence recorded: ' : 'current failures: ') + env.currentFailureCount);
+      }
     });
   }
 
@@ -15968,10 +16417,18 @@ function releaseAutoUpdateLock() {
   } catch (_) {}
 }
 
+/**
+ * May this invocation check for, and install, a newer CLI?
+ *
+ * `--json` used to disable it outright, to keep update chatter out of a document a program is parsing.
+ * The effect was that the callers who pass `--json` on every command - which is every AI agent - never
+ * upgraded at all, so each release of better diagnostics reached the population that needed it least.
+ * The chatter now goes to stderr (see `autoUpdateIfNeeded`), which is where a program's stdout contract
+ * says it belongs, and the check stays on.
+ */
 function shouldAutoUpdate(command, flags) {
   if (!command || command === 'help' || command === '--help') return false;
   if (flags && flags['no-auto-update']) return false;
-  if (flags && flagEnabled(flags.json)) return false;
   if (process.env.REMITS_CLI_AUTO_UPDATE && AUTO_UPDATE_DISABLED_VALUES.has(String(process.env.REMITS_CLI_AUTO_UPDATE).toLowerCase())) {
     return false;
   }
@@ -15979,10 +16436,31 @@ function shouldAutoUpdate(command, flags) {
   return true;
 }
 
+/** True when the last registry check is recent enough that another one would only cost latency. */
+function autoUpdateCheckedRecently() {
+  try {
+    const stamp = JSON.parse(fs.readFileSync(AUTO_UPDATE_STAMP_FILE, 'utf8'));
+    return Number(stamp.checkedAtMs) > Date.now() - AUTO_UPDATE_CHECK_INTERVAL_MS;
+  } catch (_) {
+    return false;
+  }
+}
+
+function recordAutoUpdateCheck(latest) {
+  try {
+    ensureSessionDir();
+    fs.writeFileSync(AUTO_UPDATE_STAMP_FILE,
+      JSON.stringify({ checkedAtMs: Date.now(), latest: latest || null }, null, 2));
+  } catch (_) {}
+}
+
 function autoUpdateIfNeeded(originalArgv, options = {}) {
   const requireSuccess = Boolean(options.requireSuccess);
+  // Update chatter is diagnostics, never part of a `--json` document. stderr keeps both promises at once.
+  const note = (line) => console.error(line);
   let lockAcquired = false;
   try {
+    if (!requireSuccess && autoUpdateCheckedRecently()) return false;
     lockAcquired = acquireAutoUpdateLock();
     if (!lockAcquired) {
       if (requireSuccess) {
@@ -15996,20 +16474,22 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore']
     }).trim();
+    recordAutoUpdateCheck(latest);
     if (latest && compareSemver(latest, currentVersion) > 0) {
-      console.log('[update] New version available: ' + currentVersion + ' -> ' + latest + '. Installing...');
+      note('[update] New version available: ' + currentVersion + ' -> ' + latest + '. Installing...');
+      // npm's own progress output goes to stderr too: a `--json` caller's stdout must stay one document.
       const install = spawnSync(npmCommand(), ['install', '-g', REMITS_CLI_PACKAGE_NAME + '@latest'], {
-        stdio: 'inherit',
+        stdio: ['ignore', process.stderr, process.stderr],
         env: process.env
       });
       if (install.error || install.status !== 0) {
         if (requireSuccess) {
           throw new Error('Auto-update failed; remits-cli start requires the latest published version before continuing.');
         }
-        console.log('[update] Update failed; continuing with version ' + currentVersion + '.');
+        note('[update] Update failed; continuing with version ' + currentVersion + '.');
         return false;
       }
-      console.log('[update] Updated to ' + latest + '. Re-running command...');
+      note('[update] Updated to ' + latest + '. Re-running command...');
       const rerun = spawnSync(remitsCliCommand(), originalArgv, {
         stdio: 'inherit',
         env: Object.assign({}, process.env, { REMITS_CLI_AUTO_UPDATED: '1' })
@@ -16018,7 +16498,7 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
         if (requireSuccess) {
           throw new Error('Auto-update succeeded but re-running the updated remits-cli command failed.');
         }
-        console.log('[update] Re-run failed; continuing with version ' + currentVersion + '.');
+        note('[update] Re-run failed; continuing with version ' + currentVersion + '.');
         return false;
       }
       process.exitCode = rerun.status === null ? 1 : rerun.status;
@@ -16177,13 +16657,14 @@ function printComponentsHelp(subcommand) {
   console.log('  remits-cli components branch <name> [--json]                       # overridden/added/removed + drift');
   console.log('  remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]');
   console.log('  remits-cli components branch <name> --subscribers [--json]');
+  console.log('  remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force] [--json]');
   console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]');
   console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
   console.log('  remits-cli components branch <name> --retire [--force]');
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--json]');
+  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] [--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');
@@ -16202,6 +16683,8 @@ function printTestHelp() {
   console.log('       to force production/subscription semantics from a variant checkout.');
   console.log('  --branch changes only the CLI staging namespace for test execution. Pair an unused');
   console.log('       value with --variant-branch none when existing staged entries would shadow DB rows.');
+  console.log('  --watch false disables websocket progress streaming; the CLI still waits for final status.');
+  console.log('  --wait false returns after launch with a task id; test status attaches terminal evidence.');
   console.log('  --json prints only the final status JSON to stdout; banners and progress go to stderr.');
   console.log('  --data-mode prod intentionally targets live production data.');
   console.log('  Every finished run is recorded durably: test status keeps working after the live status');
@@ -16473,10 +16956,11 @@ async function main() {
     console.log('  remits-cli components promotion [<branch>] [--json] [--no-fail]  # promotion readiness + ordered next steps');
     console.log('  remits-cli components branches [--json]                     # committed branch variants for this account');
     console.log('  remits-cli components branch <name> [--diff <componentId> --component-type <kind>] [--subscribers] [--json]');
+    console.log('  remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force] [--json]');
     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] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--json]');
+    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] [--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');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -48,6 +48,7 @@ reference below, load it before you act, not after something surprises you.
 | register this session as an agent, or ask why a routed ticket never started | `agent-sessions.md` | `serve` vs `register`, what registration does, worker spawning per agent kind, routing order, the control center, multi-session auth |
 | investigate live behavior | `investigation.md` | which tool reads which record, correlation keys, reading a record's `content`, HTTP audits, AI activity, node/`localMode`, the production support flows |
 | call any `mcp_*` tool | `tool-reference.md` | every tool's parameters, semantics, and traps — read the tool's entry before building its input |
+| run, describe, poll, or interrupt an Action from the CLI | `tool-reference.md` → `mcp_run_action` | Action execution through `remits-cli tool --name mcp_run_action`; there is no separate top-level `remits-cli action` / `run action` wrapper |
 | reason about repo discovery, auth state, or what a command actually sent | `cli-state.md` | the global `~/.remits-cli/` control plane vs per-repo `./.remits-cli/`, and which file answers which question |
 | need an exact flag, or the auth / host / async surface | `command-reference.md` | authentication, host vs data mode, the two async mechanisms, hierarchy-scoped reads, the full command list, prod banners |
 | give up on something that misbehaved | `troubleshooting.md` | the symptom→fix table, the two kinds of escalation, and the escalation bundle |

package/skills/remits-cli/references/branch-variants.md

@@ -408,6 +408,31 @@ from that checkout). Its first real sync (or commit) needs `--create-variant-bra
 variants or a subscriber the platform treats it as a feature branch and refuses to land it, so creating a
 new variant branch is always a stated decision, never a side effect of a feature branch's name.
 
+For a nested branch cut from an existing variant branch, seed the platform overlays explicitly after the git
+branch is created and pushed:
+
+```bash
+remits-cli components branch forked --copy-to sandbox --dry-run
+remits-cli components branch forked --copy-to sandbox
+remits-cli components sync --safe --branch sandbox
+```
+
+The copy is a DB overlay bootstrap, not a git write. It makes inherited overlays from `forked` already
+`storedCurrent` on the first `sandbox` sync, so the safe diff gate only has to account for the new branch's
+real file changes.
+
+**Copy before you subscribe, or the copy needs `--force`.** The copy refuses a target that already has
+stored overlays *or* live subscribers, and that second guard fires even when the target has no overlays at
+all — a branch somebody is already resolving is code those accounts are running right now, and replacing it
+has to be a stated decision. Seeding first and subscribing after keeps the plain form working. The copy is
+also all-or-nothing: the delete of any replaced overlays and every inserted row share one transaction, so a
+failure leaves the target exactly as it was rather than half-populated.
+
+Run it as `--dry-run` first. The plan reports `plannedCopies` — the number the real run will write — which
+is not always the source branch's row count: a source overlay that has become identical to trunk in both
+content and metadata is sparse, is not stored, and is listed as skipped instead of being silently dropped
+from the total.
+
 **Trunk moving also invalidates a branch.** Variant sparseness compares branch content against *current*
 trunk, so a trunk change can make an overlay obsolete without the branch changing at all. A trunk sync
 drops the affected branches' cached sync verdicts, so the next `components sync` on the branch really

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

@@ -15,6 +15,8 @@
   - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
   - [Data Mode](#data-mode)
 - [Command Reference](#command-reference)
+  - [Reading a failing run](#reading-a-failing-run)
+  - [A pass count only means something within one data lane](#a-pass-count-only-means-something-within-one-data-lane)
   - [Verification envelopes](#verification-envelopes)
   - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
@@ -236,12 +238,13 @@ remits-cli components branches [--json]                                # branche
 remits-cli components branch <name> [--json]                           # one branch: owner account, overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
 remits-cli components branch <name> --subscribers [--json]
+remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force] [--json] # seed a new variant branch with this branch's stored overlays; force if target has overlays/subscribers
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
 remits-cli test status --task-id <taskId> [--branch <stagingScope>] [--data-mode test|prod] [--json]   # falls back to the DURABLE run record once the live status expires
-remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--as-account <ID>] [--json]              # durable run history: pass counts, live AI cost, lane, content hash
+remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--all-lanes] [--as-account <ID>] [--json]  # durable run history: pass counts, live AI cost, lane, content hash
 remits-cli test compare --base <taskId> --head <taskId> [--json]                                            # per-case improved / regressed / changed, cost and world deltas
 remits-cli corpus import --manifest corpus-manifest.json [--corpus <name>] [--as-account <ID>] [--data-mode test|prod --confirm-prod] [--json]   # seed an evaluation corpus: cases + immutable artifacts; idempotent by caseKey
 remits-cli corpus cases --corpus <name> [--split S] [--tag T|--tags T,U] [--key K|--keys K,L] [--include-values] [--include-retired] [--limit N] [--json]
@@ -252,6 +255,54 @@ remits-cli corpus consistency --corpus <name> --case <caseKey> [--json]
 remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restore] [--json]    # drop a case from future runs; past measurements stay readable
 ```
 
+`test run` starts a server-side task immediately. By default the CLI process polls until the task is
+terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
+return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
+and those cases execute sequentially in declaration order. To overlap independent slow cases, launch
+separate `remits-cli test run --names "<case>" --wait false` commands from the same staged lane and keep the
+printed task ids; complete each proof with `test status --task-id <id>`. Avoid parallel runs for cases that
+share mutable fixtures, suite-level side effects, or undeclared live AI/provider calls.
+
+### Reading a failing run
+
+`test run` and `test status` print a **verdict**, not the run. The whole run object used to be dumped as
+pretty JSON in human mode - 220 KB for one 92-case suite, most of it identifiers repeated once per case - so
+the command an agent runs most often was the one that spent its remaining room to think. Every byte is still
+there behind `--json`, and behind `test status --task-id <id> --json` once the live status expires.
+
+What you get instead, and what to do with it:
+
+```text
+Cases: 59 passed, 33 failed, 92 total
+
+Failure roots (33 failed case(s), 21 distinct root(s)):
+  10x  assert statement.data.processingStatus == 'Analyzed'
+        e.g. bundled UK statements  (+9 more)
+   2x  assert statement.data.feeBreakdownChecked == true
+        e.g. 7851 Flat Rate  (+1 more)
+Largest root first: remits-cli test run --test "Statement Reader Calculations" --names "bundled UK statements"
+```
+
+**Thirty-three failures are not thirty-three problems.** Cases are grouped by their assertion root - the
+failure with the particulars (ids, numbers, Groovy's `Expression:`/`Values:` decoration) removed - largest
+group first, and one pivot block is printed per root rather than per case. Fix the largest root against one
+named case, then re-run the whole suite. Re-running the suite before you have a root is how a session spends
+an afternoon at the same pass count.
+
+### A pass count only means something within one data lane
+
+`test runs` is scoped to the data lane of the command by default, and says so:
+
+```text
+Data lane: test   (6 more run(s) in the other lane; --all-lanes to include)
+```
+
+A run's `dataMode` **is** the lane it was written in, so `64/92` in the prod lane and `59/92` in the test lane
+are two different facts, not a regression. `--compare` (and `test runs --compare`) picks the newest two runs
+of the same **shape** - same data lane, branch, workspace and case count - and says how many newer runs it
+skipped; it refuses rather than comparing across worlds. `test status --data-mode prod` on a run recorded in
+the test lane returns the run's real lane and now says that is what happened.
+
 A run labelled **`AI MOCKED`** replayed every AI turn from `aiMock`: it produces the same outcomes, scores and
 metrics a measured run would, so read that label before treating green as evidence. `compare` warns when base and
 head used different AI modes; `consistency` warns before calling a case unstable when its runs mixed modes.

package/skills/remits-cli/references/component-resolution.md

@@ -16,6 +16,7 @@
   - [When staged overrides apply](#when-staged-overrides-apply)
   - [Diagnosing which version is in play](#diagnosing-which-version-is-in-play)
   - [Working alongside other agents: the staging WORKSPACE](#working-alongside-other-agents-the-staging-workspace)
+  - [Keeping your remits-cli current](#keeping-your-remits-cli-current)
   - [A lane holds an OVERLAY; your workset is a different number](#a-lane-holds-an-overlay-your-workset-is-a-different-number)
   - [Stage / sync / clear with remits-cli](#stage--sync--clear-with-remits-cli)
   - [Stale after sync / commit (the in-memory compile cache)](#stale-after-sync--commit-the-in-memory-compile-cache)
@@ -250,6 +251,18 @@ index with `remits-cli workstream status`.
     `null` means unknown — a lane staged by an older CLI, or a branch whose last sync is not recorded —
     never "fresh".
 
+### Keeping your remits-cli current
+
+The diagnostics in these references only exist in the CLI that prints them. An older install does not print a
+worse version of them — it prints nothing, with no error, so nothing tells you what you are not being shown.
+`components stage` and `test run` warn when yours is behind:
+
+```text
+[remits-cli 0.1.120 -> 0.1.136] ... npm install -g @remits/remits-cli@latest
+```
+
+Upgrade when you see it. Auto-update handles it for you on most commands, including `--json` ones.
+
 ### A lane holds an OVERLAY; your workset is a different number
 
 This is the distinction that decides whether a lane is legible to anyone but you.

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

@@ -20,6 +20,7 @@
       - [Stage your workset, not the whole repo](#stage-your-workset-not-the-whole-repo)
       - [Three numbers, three questions](#three-numbers-three-questions)
     - [Step 4: Verify the Change](#step-4-verify-the-change)
+      - [Many failures are usually few causes](#many-failures-are-usually-few-causes)
     - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
     - [Step 6: Update Documentation](#step-6-update-documentation)
     - [Temporary Experiment Workflow](#temporary-experiment-workflow)
@@ -411,14 +412,54 @@ Tests run on the platform against your staged snapshot. They stream results in r
 id + content hash, platform sync vs local HEAD. If it is not the world you meant, stop: the result will be
 about a different world.
 
+The platform launch is asynchronous. By default `remits-cli test run` waits for its task to finish, and any
+cases selected by `--names "a|b"` execute sequentially inside that suite task. If several slow cases are
+independent, stage once, then start separate `test run --names "<case>" --wait false` commands from the same
+lane and keep the task ids they print. Complete each proof with
+`remits-cli test status --task-id <id>`; that terminal status read records and attaches the final `test_run`
+evidence. Do not parallelize cases that mutate the same fixture, rely on shared suite setup state, or make
+undeclared live AI/provider calls.
+
 If cases fail, read the printed summary and pivots first: each case has an `outcome`
 (`failed`, `error`, `budget_exceeded`, `provider_unavailable`, …) with its reason, timing, trace id, AI usage
 (live vs mocked, cost), bounded `report(...)` diagnostics, live HTTP signals, and resolved component
 provenance. Fix the code, re-stage, and re-run only after those pivots explain the failure.
 
+##### Many failures are usually few causes
+
+When several cases fail, the run leads with **failure roots** — the failures grouped by their assertion with
+the particulars (ids, numbers, Groovy's `Expression:`/`Values:` decoration) stripped out, largest group first,
+one pivot block per root rather than per case:
+
+```text
+Failure roots (33 failed case(s), 21 distinct root(s)):
+  10x  assert statement.data.processingStatus == 'Analyzed'
+        e.g. bundled UK statements  (+9 more)
+Largest root first: remits-cli test run --test "Statement Reader Calculations" --names "bundled UK statements"
+```
+
+**Work the largest root against ONE named case, then re-run the suite.** A full re-run after every edit is the
+most expensive way to learn nothing: a real account spent two days and twenty-five runs holding a suite at
+56–59 of 92 while ten of its thirty-three failures were one cause. The narrow run is seconds, tells you
+whether the cause moved, and leaves your context for the actual reasoning.
+
+Two failure roots mean "stop and look elsewhere", not "iterate harder":
+
+- **`aiMock ctx.replay(...) found no usable stored provider response`** — the message says which of three
+  things happened. *No rows at all* for that sessionId means the stored session this fixture borrows is not
+  on this platform and will not come back; the case cannot pass until the mock builds its own response with
+  `ctx.toolCall(...)` / `ctx.content(...)`. Do not re-run it. (Replaying a session that IS there renews it,
+  so a suite that runs regularly keeps its fixtures.)
+- **`Method too large` / `Class too large` / a synthetic `_closureNN`** — a JVM limit on one method body, not
+  a bug in the line it names. Staging now warns *before* the refusal and names the closure's source line span.
+  Split that body; see `development-guide.md` → *Keep Component Bodies Split*.
+
 Every finished run is recorded durably: `remits-cli test status --task-id <id>` answers after the live status
-expires, `remits-cli test runs --test <name> --compare` compares the latest run with the previous one, and
-`remits-cli test compare --base <id> --head <id>` compares any two. For evaluation suites (a `corpus(name)` of
+expires, `remits-cli test runs --test <name> --compare` compares the latest run with the newest **comparable**
+one, and `remits-cli test compare --base <id> --head <id>` compares any two. Comparable means the same data
+lane, branch, workspace and case count: a run's `dataMode` is the lane it was written in, so `64/92` in prod
+and `59/92` in test are two facts and not a trend. `test runs` lists one lane at a time and names it
+(`--all-lanes` to see both). For evaluation suites (a `corpus(name)` of
 cases seeded with `remits-cli corpus import`, one case per corpus case, intentional live AI inside
 `withAiBudget(...)`, measurements compared with `remits-cli corpus compare` / `corpus consistency`), read
 `guides/test-components.md` → *Evaluation Suites And Corpora*.

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

@@ -76,6 +76,9 @@ remits-cli tool --account-id 21 --as-account 37 --target-account 37 --name mcp_r
 # poll by run id:  --account-id 21 --as-account 37 --target-account 37 --input '{"controlAction":"status","actionRunId":"my-stable-run-id"}'
 ```
 
+That is the CLI Action-run surface. The command is still `remits-cli tool`; this CLI does not have a
+separate top-level `remits-cli action`, `remits-cli actions`, or `remits-cli run action` wrapper.
+
 For long tools that lack their own async mode, use the CLI transport async (`--async true`), optionally with
 `--wait true` to poll locally, and `remits-cli tool status --call-id <callId>`. Do not stack both mechanisms
 (see `command-reference.md` → *Tool Execution Lifecycle*). Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is
@@ -403,12 +406,18 @@ Front-stage references:
 | `page` | no | 1-based page number. Default: `1` |
 | `pageSize` | no | Results per page. Default: `25`, max: `100` |
 | `summaryOnly` | no | Detail mode: return the MAP (record index + stats + timeline) with no payloads. Same as `parts:["index"]` |
-| `parts` | no | Detail parts: `index`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
+| `compact` | no | Detail mode: after reading the MAP, open selected records without repeating the `records` index and `timeline`; keeps `groupingSummary`, `representativeSession`, `stats`, selected ids, and requested payload sections |
+| `payloadOnly` | no | Alias for `compact` |
+| `parts` | no | Detail parts: `index`, `map`, `records`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
 | `sections` | no | Alias for `parts` |
 | `recordIds` | no | Detail mode: open only these request/response record IDs |
 | `toolCallIds` | no | Detail mode: return the FULL exact input/result from `ai_tool_call` for these tool-call ids (what the tool PRODUCED — see the lens caveat) |
 | `consolidateContext` | no | When `true`, collapses repeated XML-like prompt context into a consolidated section |
 
+Detail responses expose both lenses: `groupingSummary` is the authoritative grouping-wide summary
+(counts, lanes, cost, status), while `representativeSession` names the concrete session used for
+owner/runtime metadata. `session` remains only as a compatibility alias for older callers.
+
 Spend: each search row carries `liveRequestCount`, `mockedRequestCount`, `lanes`, `testTaskId` and
 `estimatedCost`/`estimatedCostUsd` = **live spend only** (a mocked turn is never priced, even when it replays a
 recording with a cost). `pageTotals` sums the page. Turns recorded before the platform stored the mock flag are
@@ -416,12 +425,16 @@ recording with a cost). `pageTotals` sums the page. Turns recorded before the pl
 is refused rather than silently widened; the applied bounds are echoed as `filters.rangeStart`/`rangeEnd`.
 To audit one Test run: `{"action":"search","testTaskId":"<taskId>","pageSize":100}`.
 
-Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
+Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need, usually with `compact:true` once the map has chosen the row. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
 
 ### `mcp_run_action`
 Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
 staged-vs-DB provenance in the result.
 
+Invoke it with `remits-cli tool --name mcp_run_action`. Despite the natural shorthand "run an Action", there
+is no separate top-level `remits-cli action` / `actions` command and no `remits-cli run action` wrapper in
+this CLI build.
+
 Describe the Action first when the input shape is not obvious. This does not execute the Action:
 
 ```bash
@@ -832,6 +845,10 @@ Common uses:
 - `remits-cli components branch <name> --diff <id> --component-type <kind>` — compare one variant against
   current trunk.
 - `remits-cli components branch <name> --subscribers` — list accounts resolving that branch.
+- `remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force]` — seed a new variant
+  branch with the source branch's stored overlays before the first safe sync of the new branch. Dry-run
+  reports the copy plan without writes; force is required when the target already has overlays or live
+  subscribers.
 
 ### `mcp_cache`
 Bounded read-only investigation of the platform Redis keyspace — the way to see exactly what a staged