@remits/remits-cli 0.1.125 → 0.1.127

package/index.js

@@ -1,5 +1,27 @@
 #!/usr/bin/env node
 
+/*
+## Table of Contents
+
+- L22  Runtime Bootstrap And Shared State
+- L116  Sessions, Account Resolution, And Production Guards
+- L595  Local State, Workspaces, And Verification Evidence
+- L1296  Account Repos, Guide Sync, And Platform Repo
+- L1954  Component Discovery And HTTP Logging
+- L2444  Skill Delivery And TOC Resolution
+- L2754  Auth And Component Staging
+- L3352  Component Summaries, Status, And Sync Gates
+- L5107  Branches, Promotion, Commit, And Test Runs
+- L6231  Tokens, Tools, Verification, And Config
+- L7141  Service Dashboard And WebSocket Listener
+- L9236  Agent And Ticket Workflows
+- L12294  Help, Auto Update, And Command Dispatch
+*/
+
+/*
+## Runtime Bootstrap And Shared State
+*/
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -90,6 +112,10 @@ const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved', 'names'
 // a flag, never a value, and these aliases map it to its long name. Values like `-5` or `-abc` are untouched.
 const SHORT_FLAG_ALIASES = { m: 'message', h: 'help' };
 
+/*
+## Sessions, Account Resolution, And Production Guards
+*/
+
 function isFlagToken(token) {
   return typeof token === 'string' && (token.startsWith('--') || /^-[a-zA-Z]$/.test(token));
 }
@@ -565,6 +591,10 @@ function resolveDataMode(flags, session) {
   return DEFAULT_DATA_MODE;
 }
 
+/*
+## Local State, Workspaces, And Verification Evidence
+*/
+
 function ensureDir(dirPath) {
   if (!fs.existsSync(dirPath)) {
     fs.mkdirSync(dirPath, { recursive: true });
@@ -781,6 +811,42 @@ function writeToolResponseFile(cwd, callId, responsePayload) {
   return file;
 }
 
+function fileEvidence(pathname) {
+  if (!pathname || !fs.existsSync(pathname)) return {};
+  const body = fs.readFileSync(pathname);
+  return {
+    responseFile: pathname,
+    bytes: body.length,
+    sha256: sha256(body)
+  };
+}
+
+function boundedToolExcerpt(data = {}) {
+  const result = data.result && typeof data.result === 'object' ? data.result : {};
+  const candidates = [
+    data.message,
+    data.toolMessage,
+    data.error,
+    result.message,
+    result.error,
+    result.reason
+  ].filter(Boolean).map((value) => String(value));
+  const excerpt = candidates.join(' | ').trim();
+  return excerpt ? excerpt.slice(0, 1200) : null;
+}
+
+function toolEvidenceSummary(data = {}, responseFile) {
+  return Object.assign({
+    callId: data.callId,
+    name: data.name,
+    async: data.async,
+    status: data.status,
+    toolSuccess: data.toolSuccess,
+    threadGroupingId: data.threadGroupingId,
+    message: boundedToolExcerpt(data)
+  }, fileEvidence(responseFile));
+}
+
 function readToolResponseFile(cwd, callId) {
   if (!callId) return null;
   const paths = ensureLocalState(cwd);
@@ -1070,12 +1136,28 @@ function printVerificationEnvelope(envelope, fallbackEnvelopeId) {
   }
 }
 
+function printAcceptanceWarnings(envelope) {
+  const warnings = envelope && envelope.acceptance && Array.isArray(envelope.acceptance.warnings)
+    ? envelope.acceptance.warnings
+    : [];
+  if (!warnings.length) return;
+  console.log('Manifest warnings:');
+  warnings.forEach((warning) => {
+    console.log('- ' + (warning.message || warning.code || JSON.stringify(warning)));
+  });
+}
+
 function buildCommandWorld(response, fallback = {}) {
   const source = (response && response.staging) || {};
   const resolution = (response && response.resolution) || {};
+  const result = (response && response.result) || {};
+  const laneHash = laneContentHashFrom(response) || fallback.laneContentHash || fallback.stagedOverlayHash;
+  const executionAccountId = response && (response.executionAccountId || result.accountId || source.executionAccountId || response.accountId) ||
+    resolution.executionAccountId ||
+    fallback.executionAccountId;
   return {
     accountId: response && (response.accountId || response.ownerAccountId) || fallback.accountId,
-    executionAccountId: response && (response.executionAccountId || response.accountId) || resolution.executionAccountId || fallback.executionAccountId,
+    executionAccountId,
     addressedAccountId: resolution.addressedAccountId || fallback.addressedAccountId,
     host: fallback.host,
     dataMode: response && response.dataMode || fallback.dataMode,
@@ -1083,12 +1165,26 @@ function buildCommandWorld(response, fallback = {}) {
     branchName: response && response.branchName || fallback.branchName,
     workspace: response && response.workspace !== undefined ? response.workspace : fallback.workspace,
     stagingLane: response && response.stagingLane || source.stagingLane || fallback.stagingLane,
-    componentBranch: resolution.componentBranch || response && response.variantBranch || fallback.componentBranch,
+    laneContentHash: laneHash,
+    stagedOverlayHash: laneHash,
+    // `variantWorld.componentBranch` is the platform's answer for the run (the variant branch, else the
+    // subscription); a bare `variantBranch` is null whenever the subscription decided.
+    componentBranch: resolution.componentBranch ||
+      response && ((response.variantWorld && response.variantWorld.componentBranch) || response.variantBranch) ||
+      fallback.componentBranch,
+    variantBranchSource: response && (response.variantBranchSource || (response.variantWorld && response.variantWorld.variantBranchSource)) || fallback.variantBranchSource,
     variantId: resolution.variantId || fallback.variantId,
     sourceLayer: fallback.sourceLayer || (source.testComponentSource === 'staged' ? 'staged' : undefined)
   };
 }
 
+function laneContentHashFrom(response) {
+  if (!response) return null;
+  const laneSummary = response.laneSummary || (response.staging && response.staging.laneSummary) ||
+    (response.componentStatus && response.componentStatus.laneSummary);
+  return laneSummary && laneSummary.contentHash ? laneSummary.contentHash : null;
+}
+
 function normalizeName(name) {
   return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
 }
@@ -1196,6 +1292,10 @@ function loadAccountInfo(cwd) {
   }
 }
 
+/*
+## Account Repos, Guide Sync, And Platform Repo
+*/
+
 function readAccountRepoIndex() {
   if (!fs.existsSync(ACCOUNT_REPO_INDEX_FILE)) {
     return {};
@@ -1850,6 +1950,10 @@ function resolveSessionContext(cwd, flags) {
   };
 }
 
+/*
+## Component Discovery And HTTP Logging
+*/
+
 /**
  * Record the FILE identity of a component (type + filename id, or type + filename stem) on an object without
  * sending it anywhere. Non-enumerable, so JSON payloads and the content hash never see it.
@@ -2336,6 +2440,10 @@ async function loggedGet(api, cwd, endpoint, params = {}) {
   }
 }
 
+/*
+## Skill Delivery And TOC Resolution
+*/
+
 // ---------------------------------------------------------------------------
 // Skill delivery
 //
@@ -2465,6 +2573,14 @@ function resolveTocEntry(line, byAnchor, byTitle) {
     return formatTocEntry(legacyEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
   }
 
+  // Prepared form. This makes generated TOCs idempotent: a later package/build pass can re-derive the
+  // current line numbers from the emitted heading text instead of preserving stale numbers.
+  const preparedEntry = /^(\s*)[-*]\s+L\d+\s\s(.+?)\s*$/.exec(line);
+  if (preparedEntry) {
+    const title = preparedEntry[2];
+    return formatTocEntry(preparedEntry[1], byTitle.get(title) || byAnchor.get(headingSlug(title)));
+  }
+
   return null;
 }
 
@@ -2634,6 +2750,10 @@ async function installSkillsCommand(flags) {
   }
 }
 
+/*
+## Auth And Component Staging
+*/
+
 async function authCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2999,6 +3119,7 @@ async function pushComponentsCommand(flags) {
         rawRefs: { command: 'components stage' },
         stage: (err.responseBody || {}).stage,
         compileValidation: (err.responseBody || {}).compileValidation,
+        refusalDetails: stageRefusalDetails(err.responseBody || {}),
         changedFromWorkingTree: changedFromWorkingTree || [],
         unrepresentableChanges: unstageable
       }, { quiet: true });
@@ -3033,6 +3154,7 @@ async function pushComponentsCommand(flags) {
     rawRefs: { command: 'components stage' },
     stage: response.stage,
     laneSummary: response.laneSummary,
+    compileValidation: response.compileValidation || null,
     changedFromWorkingTree: response.changedFromWorkingTree,
     unrepresentableChanges: response.unrepresentableChanges
   }, { quiet: flagEnabled(flags.json) });
@@ -3218,6 +3340,18 @@ async function stageOrRefuse(api, cwd, payload) {
   }
 }
 
+function stageRefusalDetails(body = {}) {
+  const details = {};
+  ['duplicates', 'compileValidation', 'policy', 'editLease', 'skipped', 'reconcile', 'laneHoldsRejectedSource'].forEach((key) => {
+    if (body[key] !== undefined) details[key] = sanitizeForLog(body[key]);
+  });
+  return Object.keys(details).length ? details : undefined;
+}
+
+/*
+## Component Summaries, Status, And Sync Gates
+*/
+
 /** What the account's rules said about this stage or commit — including "they could not be read". */
 function printComponentPolicy(response) {
   const policy = response && response.policy;
@@ -3269,6 +3403,10 @@ function printCompileValidation(validation, options) {
   // A skip is neither a pass nor a failure, and it used to be printed as a pass ("1/1 compiled" over a
   // component whose source was blank). Named, so the reader knows exactly what was NOT looked at.
   const unchecked = Array.isArray(validation.unchecked) ? validation.unchecked : [];
+  const warnings = Array.isArray(validation.warnings) ? validation.warnings : [];
+  warnings.forEach((warning) => {
+    emit('  Warning: ' + (warning.message || JSON.stringify(warning)));
+  });
   if (unchecked.length) {
     emit('  ' + unchecked.length + ' NOT compile-checked: ' + unchecked.map((entry) =>
       (entry.type || 'component') + ' ' + (entry.id || entry.name || '?') + ' (' + (entry.reason || 'unchecked') + ')').join(', '));
@@ -3433,6 +3571,9 @@ function printStageSummary(response, flags) {
   // The CLI's own findings (deleted files) and the platform's (a README withheld on a variant branch) are
   // different sources. Preferring the first whenever it existed — even as an empty list — hid the second.
   printUnrepresentableChanges(mergeUnrepresentable(response.unrepresentableChanges, stage.unrepresentable));
+  if (typeof printOrphanedWorkspaceWarning === 'function') {
+    printOrphanedWorkspaceWarning(response);
+  }
   if (typeof printAccountLanes === 'function') {
     printAccountLanes(response);
   }
@@ -3458,6 +3599,7 @@ function printStatusSummary(response, flags) {
   printBranchContext(response);
   printStagingLane(response.branchName, response.workspace, null);
   printLaneSummary(response);
+  printOrphanedWorkspaceWarning(response);
   printStagingFreshness(response.freshness);
   printRepositoryCheck(response.repositoryCheck);
   printComponentTypeCounts(response.entries || []);
@@ -3499,9 +3641,7 @@ function printLanesSummary(response, flags) {
 }
 
 function printStagingLaneRow(lane) {
-  const world = lane.onTrunk === true ? 'trunk'
-              : lane.onTrunk === false ? 'variant'
-              : 'unknown-world';
+  const world = laneWorldLabel(lane);
   const ws = lane.workspace ? ' [ws:' + lane.workspace + ']' : ' [shared]';
   const workset = lane.worksetKnown && lane.worksetCountAsOf != null
     ? ' workset ' + lane.worksetCountAsOf
@@ -3598,10 +3738,7 @@ function printAccountLanes(response) {
   console.log('');
   console.log('Other staging lanes on this ACCOUNT (as of the last stage/clear in each):');
   lanes.forEach((lane) => {
-    // null onTrunk means the owner could not be resolved. Say "unknown" rather than guessing a world.
-    const world = lane.onTrunk === true ? 'trunk'
-                : lane.onTrunk === false ? 'variant branch'
-                : 'branch world unknown';
+    const world = laneWorldLabel(lane);
     const ws = lane.workspace ? ' [ws:' + lane.workspace + ']' : '';
     const who = lane.userEmail ? '  ' + lane.userEmail : '';
     const ttl = lane.expiresInSeconds != null
@@ -3617,7 +3754,51 @@ function printAccountLanes(response) {
   });
   console.log('  (* = this command\'s lane)');
   console.log('  A variant-branch lane layers over that branch\'s ComponentVariant overlays, and a commit');
-  console.log('  from it writes overlays — never the trunk rows a trunk lane commits to.');
+  console.log('  from it writes overlays — never the trunk rows a trunk lane commits to. A feature-branch lane');
+  console.log('  resolves the account\'s subscription beneath its staged entries and cannot be landed.');
+}
+
+function printOrphanedWorkspaceWarning(response) {
+  const currentCount = Number((response && response.stagedCount) ||
+    (response && response.laneSummary && response.laneSummary.stagedCount) || 0);
+  if (currentCount > 0) return;
+  const lanes = Array.isArray(response && response.accountLanes) ? response.accountLanes : [];
+  const currentBranch = response && response.branchName;
+  const currentWorkspace = response && response.workspace;
+  const orphan = lanes.find((lane) => lane && lane.sameWorkspaceOtherBranch === true);
+  if (!orphan) return;
+  const age = orphan.updatedAtMs ? formatAge(Date.now() - Number(orphan.updatedAtMs)) + ' ago' : 'recently';
+  console.log('');
+  console.log('WARNING: Your workspace "' + (currentWorkspace || orphan.workspace || 'shared') + '" has ' +
+    (orphan.stagedCountAsOf || orphan.stagedCount || 0) + ' staged entr' +
+    ((orphan.stagedCountAsOf || orphan.stagedCount || 0) === 1 ? 'y' : 'ies') +
+    ' on branch "' + orphan.branchName + '" (staged ' + age + '); this checkout is now on "' +
+    (currentBranch || 'unknown') + '". Re-stage here, or switch back.');
+}
+
+function formatAge(ms) {
+  const value = Number(ms);
+  if (!Number.isFinite(value) || value < 0) return 'unknown age';
+  const seconds = Math.round(value / 1000);
+  if (seconds < 90) return seconds + 's';
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 90) return minutes + 'm';
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return hours + 'h';
+  return Math.round(hours / 24) + 'd';
+}
+
+// The world a lane row resolves, from the platform's answer. null onTrunk means the owner could not be
+// resolved, and a non-trunk lane without a reported source (an older platform) is only known to be
+// non-trunk — never guessed to be a variant branch. Pure.
+function laneWorldLabel(lane) {
+  if (!lane || lane.onTrunk == null) return 'branch world unknown';
+  if (lane.onTrunk === true) return 'trunk';
+  if (lane.variantBranchSource === 'subscription-fallback') return 'feature branch';
+  if (lane.variantBranchSource === 'branch-has-variants' || lane.variantBranchSource === 'branch-has-subscribers') {
+    return 'variant branch';
+  }
+  return 'non-trunk branch';
 }
 
 function isCurrentStagingLane(lane) {
@@ -3638,10 +3819,15 @@ function printBranchContext(response) {
   console.log('');
   if (ctx.onTrunk) {
     console.log('Working tree: TRUNK (' + response.branchName + ')');
+  } else if (ctx.variantBranchSource === 'subscription-fallback') {
+    console.log('Working tree: FEATURE BRANCH "' + response.branchName + '"  (not a variant branch; trunk is "' + ctx.trunkBranch + '")');
   } else {
     console.log('Working tree: VARIANT BRANCH "' + response.branchName + '"  (trunk is "' + ctx.trunkBranch + '")');
   }
   console.log('  runs resolve:   ' + ctx.resolves);
+  if (ctx.variantBranchSource) {
+    console.log('  variant world:  ' + (ctx.variantBranch || 'none (subscription)') + '  [' + ctx.variantBranchSource + ']');
+  }
   console.log('  commit writes:  ' + ctx.commitWrites);
   if (Object.prototype.hasOwnProperty.call(ctx, 'lastSyncedSha')) {
     // null is "unknown" (never synced, expired, or the last sync had errors) — never "nothing landed".
@@ -3755,6 +3941,9 @@ async function statusComponentsCommand(flags) {
     workspace,
     dataMode,
     mode: 'status',
+    // So "runs resolve" describes the run these flags would launch, by the same server-side rule.
+    variantBranch: flags['variant-branch'],
+    asAccountId: flags['as-account'] || flags['as-account-id'],
     componentType: flags['component-type'] || flags.type,
     componentId: flags['component-id'] || flags.id
   }).then((r) => r.data);
@@ -3767,6 +3956,7 @@ async function statusComponentsCommand(flags) {
   // supplies the facts (the last SHA it synced, each entry's base) and the comparison happens here.
   response.freshness = stagingFreshness({
     head: safeGitValue(cwd, 'git rev-parse HEAD'),
+    originHead: safeGitValue(cwd, 'git rev-parse ' + shellQuote('origin/' + branchName)),
     lastSyncedSha: response.branchContext && response.branchContext.lastSyncedSha,
     entries: response.entries,
     laneSummary: response.laneSummary,
@@ -3983,6 +4173,9 @@ async function syncComponentsCommand(rawFlags) {
     ...runContextPayload(flags),
     agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
     acknowledge: flags.acknowledge || undefined,
+    // The platform refuses to sync a branch that is not a variant branch (see featureBranchLandingRefusal);
+    // this is the explicit statement that a NEW variant branch is being created on purpose.
+    createVariantBranch: flagEnabled(flags['create-variant-branch']) || undefined,
     components: []
   };
 
@@ -4005,7 +4198,7 @@ async function syncComponentsCommand(rawFlags) {
     // --safe is fail-closed: a sync that would reconcile a repository other than this checkout's is refused.
     const preflightRepoCheck = repositoryCheck(cwd, branchContext);
     if (preflightRepoCheck.matches === false) {
-      const mismatch = repositoryMismatchMessage(preflightRepoCheck, 'components sync');
+      const mismatch = repositoryMismatchMessage(preflightRepoCheck, 'components sync', branchContext);
       if (flagEnabled(flags.json)) {
         const refusal = {
           success: false,
@@ -4132,7 +4325,7 @@ async function syncComponentsCommand(rawFlags) {
   response.repositoryCheck = repositoryCheck(cwd, { repository: response.sync && response.sync.repository });
   if (response.repositoryCheck.matches === false) {
     (flagEnabled(flags.json) ? console.error : console.log)('WARNING: ' +
-      repositoryMismatchMessage(response.repositoryCheck, 'components sync'));
+      repositoryMismatchMessage(response.repositoryCheck, 'components sync', response.branchContext));
   }
   const summary = buildSyncSummary(response);
   summary.gates = gate.checks;
@@ -4550,11 +4743,66 @@ function repositoryCheck(cwd, branchContext) {
   return { platformRepository, checkoutOrigin, matches: repositoryNamesMatch(platformRepository, checkoutOrigin) };
 }
 
-function repositoryMismatchMessage(check, commandName) {
+function repositoryMismatchMessage(check, commandName, branchContext) {
   return commandName + ': this checkout\'s origin is ' + check.checkoutOrigin + ', but the platform syncs repository "' +
     check.platformRepository + '" for this account. A push from here would never be synced, and the sync would ' +
-    'reconcile a repository you are not editing. Run it from that repository\'s checkout, or check which account ' +
-    'this command resolved (account-info.json, --account-id).';
+    'reconcile a repository you are not editing. ' + (featureBranchLandingHint(branchContext) ||
+    ('Run it from that repository\'s checkout, or check which account this command resolved ' +
+    '(account-info.json, --account-id).'));
+}
+
+// A git branch that is not a variant world (no committed variants, no subscribers) resolves the account's
+// SUBSCRIBED branch beneath its staged entries — the platform reports that as
+// `variantBranchSource: 'subscription-fallback'`. Syncing such a branch would write overlays nobody resolves,
+// so the way to land it is through the branch it resolves. Pure; null when the context says nothing of the kind.
+function featureBranchLandingHint(branchContext) {
+  if (!branchContext || branchContext.variantBranchSource !== 'subscription-fallback') return null;
+  const subscribed = branchContext.subscribedComponentBranch;
+  const trunk = branchContext.trunkBranch || 'trunk';
+  // Without a subscription the platform cannot know which branch this was cut from; naming trunk would send a
+  // branch cut from a variant branch into trunk.
+  return 'This git branch is not a variant branch: runs from it resolve ' +
+    (subscribed ? 'the \'' + subscribed + '\' variant branch this account subscribes to' : 'trunk') +
+    ' plus what you staged. To land the work, ' +
+    (subscribed
+      ? 'merge this branch into \'' + subscribed + '\' and commit/sync \'' + subscribed + '\' from that checkout.'
+      : 'merge this branch into the branch you cut it from (trunk \'' + trunk + '\', or the variant branch it came ' +
+        'from) and commit/sync that branch from its checkout.');
+}
+
+// Refuse a commit from a branch the platform reports as NOT a variant branch, unless the caller says it is
+// creating one. Mirrors the server-side refusal so nothing is pushed that cannot be synced. Pure.
+function featureBranchCommitRefusal(branchContext, branchName, flags) {
+  if (!branchContext || branchContext.variantBranchSource !== 'subscription-fallback') return null;
+  if (flags && (flags['create-variant-branch'] === true || flags['create-variant-branch'] === 'true')) return null;
+  return 'components commit refused: \'' + branchName + '\' is not a variant branch (no committed variants, no ' +
+    'subscribers). ' + featureBranchLandingHint(branchContext) + ' Committing here would write overlays for \'' +
+    branchName + '\' that nobody subscribes to, and flip every other lane on that branch to them. If you are ' +
+    'deliberately creating a NEW variant branch, re-run with --create-variant-branch.';
+}
+
+// What a verification envelope records as the world it verified. Taken from the platform's answer
+// (`variantWorld`, the same rule every run uses), never inferred from `onTrunk`: a feature branch cut from a
+// variant branch is not on trunk, yet resolves the SUBSCRIBED branch, and labelling it by its own name recorded
+// a world no run executed in. Pure.
+function verificationWorldFromStatus(statusResponse, branchName) {
+  if (!statusResponse) return {};
+  const ctx = statusResponse.branchContext || {};
+  const world = statusResponse.variantWorld || null;
+  const staged = !!(statusResponse.laneSummary && statusResponse.laneSummary.stagedCount > 0);
+  let componentBranch;
+  if (world) {
+    componentBranch = world.componentBranch || 'trunk';
+  } else {
+    // An older platform that does not report the world: the previous inference, kept for compatibility.
+    componentBranch = ctx.onTrunk ? 'trunk' : branchName;
+  }
+  const sourceLayer = staged ? 'staged' : (componentBranch && componentBranch !== 'trunk' ? 'variant' : 'trunk');
+  return {
+    componentBranch,
+    sourceLayer,
+    variantBranchSource: world ? world.variantBranchSource : undefined
+  };
 }
 
 function printRepositoryCheck(check) {
@@ -4622,7 +4870,7 @@ function gitIsAncestor(cwd, ancestor, descendant) {
  * `stageBaseSha`; only the local checkout can order commits, so the comparison happens here. Pure — git is
  * injected as `isAncestor(a, b)` — so it can be tested without a repository.
  */
-function stagingFreshness({ head, lastSyncedSha, entries, laneSummary, isAncestor }) {
+function stagingFreshness({ head, originHead, lastSyncedSha, entries, laneSummary, isAncestor }) {
   const rows = Array.isArray(entries) ? entries : [];
   const staged = rows.filter((entry) => entry && entry.stageBaseSha);
   const memo = new Map();
@@ -4648,7 +4896,9 @@ function stagingFreshness({ head, lastSyncedSha, entries, laneSummary, isAncesto
 
   return {
     head: head || null,
+    originHead: originHead || null,
     lastSyncedSha: lastSyncedSha || null,
+    freshnessUnknownReason: !originHead ? 'branch has no upstream' : (!lastSyncedSha ? 'platform has no last synced SHA for this branch' : null),
     landedSinceHead,
     entriesBehindLastSync: behindLastSync.length,
     entriesFromOtherCommits: fromOtherCommits.length,
@@ -4662,6 +4912,9 @@ function stagingFreshness({ head, lastSyncedSha, entries, laneSummary, isAncesto
 function printStagingFreshness(freshness) {
   if (!freshness) return;
   const plural = (n) => n + ' staged entr' + (n === 1 ? 'y' : 'ies');
+  if (freshness.freshnessUnknownReason) {
+    console.log('Freshness unknown:', freshness.freshnessUnknownReason + '.');
+  }
   if (freshness.landedSinceHead === true) {
     console.log('');
     console.log('LANDED SINCE YOUR BASE: the platform last synced ' + short(freshness.lastSyncedSha) +
@@ -4850,6 +5103,10 @@ function buildSyncSummary(response) {
   };
 }
 
+/*
+## Branches, Promotion, Commit, And Test Runs
+*/
+
 // Inspect committed branch variants: durable, branch-scoped overlays of this account's components.
 // Unlike `components status` (which shows the ephemeral Redis staging cache), these are what
 // subscribing accounts actually resolve in production.
@@ -5457,7 +5714,7 @@ async function refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, sk
   // `--skip-git` pushes nothing, so there is nothing to mis-deliver.
   const repoCheck = skipGit ? null : repositoryCheck(cwd, branchContext);
   if (repoCheck && repoCheck.matches === false) {
-    const mismatch = repositoryMismatchMessage(repoCheck, 'components commit');
+    const mismatch = repositoryMismatchMessage(repoCheck, 'components commit', branchContext);
     if (flagEnabled(flags.json)) {
       console.log(JSON.stringify({
         success: false,
@@ -5478,6 +5735,30 @@ async function refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, sk
     }
     throw new Error(mismatch + ' No git commit or push was attempted.');
   }
+  // Before ANY git write: is this a feature branch (not a variant branch)? The platform refuses its sync, and
+  // a commit pushed first would leave a pushed-but-unsyncable branch. Same decision, taken before the push.
+  const featureRefusal = featureBranchCommitRefusal(branchContext, branchName, flags);
+  if (featureRefusal) {
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({
+        success: false,
+        mode: 'commit',
+        dataMode,
+        accountId,
+        branchName,
+        workspace,
+        branchContext,
+        refusal: 'feature_branch_landing',
+        phase: 'pre-git',
+        gitWritten: false,
+        gateViolations: [featureRefusal],
+        message: featureRefusal
+      }, null, 2));
+      process.exitCode = 1;
+      return true;
+    }
+    throw new Error(featureRefusal + ' No git commit or push was attempted.');
+  }
   if (!flagEnabled(flags.yes) && branchContextIsTrunk(branchContext)) {
     printTrunkSyncWarning(branchContext ? branchContext.trunkBranch || branchName : branchName, {
       stderr: flagEnabled(flags.json)
@@ -5594,6 +5875,84 @@ async function waitForStatus(api, cwd, accountId, branchName, taskId, token, dat
   }
 }
 
+function testEvidenceCategories(status = {}, selectedNames = []) {
+  const categories = new Set(['test_run']);
+  const test = status.test || {};
+  if (test.name) categories.add('test_run.suite:' + String(test.name));
+  if (test.id !== undefined && test.id !== null) categories.add('test_run.suite_id:' + String(test.id));
+  (Array.isArray(selectedNames) ? selectedNames : []).forEach((name) => {
+    if (name) categories.add('test_run.' + String(name));
+  });
+  const results = status.result && Array.isArray(status.result.tests) ? status.result.tests : [];
+  results.forEach((result) => {
+    if (result && result.passed === true && result.name) {
+      categories.add('test_run.case:' + String(result.name));
+      categories.add('test_run.' + String(result.name));
+    }
+  });
+  return Array.from(categories);
+}
+
+function testComponentProvenance(status = {}) {
+  const direct = status.resolvedComponentProvenance || (status.result && status.result.resolvedComponentProvenance) ||
+    (status.staging && status.staging.resolvedComponentProvenance);
+  if (Array.isArray(direct)) return direct;
+  const staging = status.staging || {};
+  if (staging.testComponentSignature) {
+    return [{
+      type: 'test',
+      id: status.test && status.test.id,
+      name: status.test && status.test.name,
+      signature: staging.testComponentSignature,
+      source: staging.testComponentSource || null
+    }];
+  }
+  return [];
+}
+
+function testCompileSignatures(status = {}) {
+  return testComponentProvenance(status)
+    .map((entry) => entry && entry.signature)
+    .filter(Boolean);
+}
+
+function printTestRunPivots(status = {}) {
+  const tests = status.result && Array.isArray(status.result.tests) ? status.result.tests : [];
+  if (!tests.length) return;
+  const slowest = tests.slice().sort((a, b) => Number(b.duration || 0) - Number(a.duration || 0))[0];
+  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) => {
+    console.log('Pivots for failed case:', test.name || '(unnamed)');
+    if (test.duration != null) console.log('  Duration:', formatDurationMs(test.duration));
+    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));
+    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));
+    }
+    if (Array.isArray(test.resolvedComponentProvenance) && test.resolvedComponentProvenance.length) {
+      console.log('  Components:', test.resolvedComponentProvenance.slice(0, 8).map((entry) =>
+        (entry.type || 'component') + ' ' + (entry.id || entry.name || '?') +
+        (entry.source ? ' [' + entry.source + ']' : '') +
+        (entry.signature ? ' ' + short(entry.signature) : '')).join(', '));
+    }
+    if (Array.isArray(test.liveHttpCalls) && test.liveHttpCalls.length) {
+      console.log('  Live HTTP calls:', test.liveHttpCalls.length);
+    }
+  });
+}
+
+function formatDurationMs(value) {
+  const ms = Number(value);
+  if (!Number.isFinite(ms)) return String(value);
+  if (ms < 1000) return ms + 'ms';
+  return (ms / 1000).toFixed(ms < 10000 ? 1 : 0) + 's';
+}
+
 async function waitForToolStatus(api, cwd, options) {
   const started = Date.now();
   let pollDelayMs = parsePositiveInt(options.pollIntervalMs, 1000);
@@ -5744,6 +6103,7 @@ async function testCommand(flags) {
     printResolvedBaseUrl(baseUrl);
     printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
     if (start.staging && Array.isArray(start.staging.accountLanes)) {
+      printOrphanedWorkspaceWarning(start.staging);
       printAccountLanes({ accountLanes: start.staging.accountLanes, branchName, workspace });
     }
     console.log('Test run started:', start.taskId);
@@ -5770,6 +6130,7 @@ async function testCommand(flags) {
     console.log(JSON.stringify(status, null, 2));
   } else {
     console.log('Final status:', JSON.stringify(status, null, 2));
+    printTestRunPivots(status);
   }
 
   // A selector that matched no case is a mis-specified run, not a passing one. Say so in the terminal
@@ -5800,7 +6161,8 @@ async function testCommand(flags) {
     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(collectVerificationSource(cwd, flags), {
-      compileSignatures: status.staging && status.staging.testComponentSignature ? [status.staging.testComponentSignature] : []
+      compileSignatures: testCompileSignatures(status),
+      componentProvenance: testComponentProvenance(status)
     }),
     test: {
       taskId: start.taskId,
@@ -5809,16 +6171,66 @@ async function testCommand(flags) {
       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: ['test_run'].concat(names.map((name) => 'test_run.' + name)),
+    evidenceCategories: testEvidenceCategories(status, names),
     limitations: unmatched.length ? ['One or more requested test case selectors matched no case.'] : [],
     rawRefs: { testStatusKey: start.taskId },
     status
   }, { quiet: jsonOutput });
 }
 
+async function testStatusCommand(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 branchName = flags.branch || currentBranch(cwd);
+  const dataMode = hasExplicitDataModeFlag(flags)
+    ? resolveDataMode(flags, null)
+    : DEFAULT_DATA_MODE;
+  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>');
+
+  const api = buildAxios(baseUrl, session.token);
+  const status = await loggedPost(api, cwd, '/cli/test', {
+    token: session.token,
+    command: 'status',
+    accountId,
+    branchName,
+    taskId,
+    dataMode
+  }).then((r) => r.data);
+
+  if (jsonOutput) {
+    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);
+  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);
+  }
+  if (status.status === 'failed' || (status.result && status.result.failed > 0)) {
+    process.exitCode = 1;
+  }
+  return status;
+}
+
+/*
+## Tokens, Tools, Verification, And Config
+*/
+
 async function tokenCommand(flags) {
   const subcommand = flags._ && flags._[1];
   if (subcommand === 'inspect' || subcommand === 'details' || subcommand === 'decode') {
@@ -5876,6 +6288,9 @@ async function tokenCommand(flags) {
     accountId: data.accountId,
     branchName: data.branchName,
     variantBranch: data.variantBranch,
+    // Why the variant branch is (or is not) set — the platform's one rule, so a null is explainable.
+    variantBranchSource: data.variantBranchSource,
+    variantWorld: data.variantWorld,
     workspace: data.workspace !== undefined ? data.workspace : workspace,
     stagingLane: data.stagingLane,
     accountLanes: data.accountLanes,
@@ -6136,8 +6551,7 @@ async function toolCommand(flags) {
       revision: collectVerificationSource(cwd, flags),
       evidenceCategories: ['tool_call'],
       rawRefs: { toolResponsePath: statusResponse.responseFile, callId: requestedCallId },
-      tool: { callId: requestedCallId, status: data.status, name: stored && stored.name },
-      result: data
+      tool: Object.assign(toolEvidenceSummary(data, statusResponse.responseFile), { callId: requestedCallId, name: stored && stored.name })
     }, { quiet: jsonOutput });
     if (jsonOutput) {
       console.log(JSON.stringify(data, null, 2));
@@ -6150,7 +6564,8 @@ async function toolCommand(flags) {
     console.log('Data mode:', data.dataMode || dataMode);
     if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
     console.log('Session log:', data.sessionLog);
-    console.log('Tool response file:', data.responseFile);
+    const responseEvidence = fileEvidence(data.responseFile);
+    console.log('Tool response file:', data.responseFile + (responseEvidence.bytes ? ' (' + responseEvidence.bytes + ' bytes, sha256 ' + responseEvidence.sha256.slice(0, 12) + ')' : ''));
     if (polledFailed) {
       console.log('Tool error:', data.toolMessage);
     }
@@ -6201,6 +6616,9 @@ async function toolCommand(flags) {
   data.sessionLog = sessionJsonlFile(cwd);
   if (toolFailureMessage && !data.toolMessage) data.toolMessage = toolFailureMessage;
 
+  let evidenceData = data;
+  let evidenceResponseFile = response.responseFile;
+
   if (!jsonOutput) {
     printSessionResolutionWarning(sessionContext);
     printResolvedBaseUrl(baseUrl);
@@ -6218,7 +6636,8 @@ async function toolCommand(flags) {
       console.log('Component:', `${data.componentSource}${sig}`);
     }
     console.log('Session log:', data.sessionLog);
-    console.log('Tool response file:', data.responseFile);
+    const responseEvidence = fileEvidence(data.responseFile);
+    console.log('Tool response file:', data.responseFile + (responseEvidence.bytes ? ' (' + responseEvidence.bytes + ' bytes, sha256 ' + responseEvidence.sha256.slice(0, 12) + ')' : ''));
   }
 
   // Non-zero exit so scripted/agent callers that check status notice the refusal too.
@@ -6238,9 +6657,12 @@ async function toolCommand(flags) {
 
     finalStatus.data.responseFile = finalStatus.responseFile;
     finalStatus.data.sessionLog = sessionJsonlFile(cwd);
+    evidenceData = finalStatus.data;
+    evidenceResponseFile = finalStatus.responseFile;
     if (!jsonOutput) {
       console.log('Final status:', finalStatus.data.status);
-      console.log('Tool response file:', finalStatus.responseFile);
+      const finalEvidence = fileEvidence(finalStatus.responseFile);
+      console.log('Tool response file:', finalStatus.responseFile + (finalEvidence.bytes ? ' (' + finalEvidence.bytes + ' bytes, sha256 ' + finalEvidence.sha256.slice(0, 12) + ')' : ''));
     }
     if (finalStatus.data.status !== 'completed') {
       process.exitCode = 1;
@@ -6250,20 +6672,19 @@ async function toolCommand(flags) {
 
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
     type: 'tool_call',
-    success: !toolFailed && (!asyncMode || !waitForAsync || process.exitCode !== 1),
+    success: asyncMode && !waitForAsync ? null : (!toolFailed && (!asyncMode || process.exitCode !== 1)),
     claim: 'Tool call ' + String(toolName),
-    world: buildCommandWorld(data, { accountId: data.accountId || accountId, dataMode: data.dataMode || dataMode, branchName: data.branchName || branchName, workspace: resolveWorkspace(cwd, flags), host: normalizeBaseUrl(baseUrl), sourceLayer: data.componentSource }),
+    world: buildCommandWorld(evidenceData, { accountId: evidenceData.accountId || accountId, dataMode: evidenceData.dataMode || dataMode, branchName: evidenceData.branchName || branchName, workspace: resolveWorkspace(cwd, flags), host: normalizeBaseUrl(baseUrl), sourceLayer: evidenceData.componentSource }),
     revision: Object.assign(collectVerificationSource(cwd, flags), {
-      compileSignatures: data.componentSignature ? [data.componentSignature] : []
+      compileSignatures: evidenceData.componentSignature ? [evidenceData.componentSignature] : []
     }),
     evidenceCategories: ['tool_call'],
     dependencies: {
       mocks: [],
-      liveHttpCalls: data.liveHttpCalls || []
+      liveHttpCalls: evidenceData.liveHttpCalls || []
     },
-    rawRefs: { toolResponsePath: response.responseFile, callId },
-    tool: { callId, name: String(toolName), async: asyncMode, status: data.status, toolSuccess: data.toolSuccess },
-    result: data
+    rawRefs: { toolResponsePath: evidenceResponseFile, callId },
+    tool: Object.assign(toolEvidenceSummary(evidenceData, evidenceResponseFile), { callId, name: String(toolName), async: asyncMode })
   }, { quiet: jsonOutput });
   if (jsonOutput) {
     console.log(JSON.stringify(data, null, 2));
@@ -6346,10 +6767,12 @@ async function verifyCommand(flags, subcommand) {
 
     const source = collectVerificationSource(cwd, flags);
     if (statusResponse) {
-      source.componentBranch = statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : branchName;
-      source.sourceLayer = statusResponse.laneSummary && statusResponse.laneSummary.stagedCount > 0
-        ? 'staged' : (statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : 'variant');
-      source.stagedOverlayHash = statusResponse.laneSummary ? sha256(stableStringify(statusResponse.laneSummary)) : null;
+      const verifiedWorld = verificationWorldFromStatus(statusResponse, branchName);
+      source.componentBranch = verifiedWorld.componentBranch;
+      source.sourceLayer = verifiedWorld.sourceLayer;
+      if (verifiedWorld.variantBranchSource) source.variantBranchSource = verifiedWorld.variantBranchSource;
+      source.laneContentHash = laneContentHashFrom(statusResponse);
+      source.stagedOverlayHash = source.laneContentHash;
     }
 
     const response = await postVerificationCommand(api, cwd, session, accountId, 'start', {
@@ -6364,6 +6787,7 @@ async function verifyCommand(flags, subcommand) {
     writeActiveVerificationEnvelope(cwd, envelope.envelopeId, activeContext);
     console.log('Verification envelope started:', envelope.envelopeId);
     console.log('Target:', 'account=' + accountId + ', branch=' + branchName + ', workspace=' + (workspace || 'shared') + ', dataMode=' + dataMode);
+    printAcceptanceWarnings(envelope);
     console.log('Local mirror:', verificationPaths(cwd, envelope.envelopeId).base);
     return envelope;
   }
@@ -6404,6 +6828,7 @@ async function verifyCommand(flags, subcommand) {
     writeLocalVerificationEnvelope(cwd, response.envelope);
     console.log('Manifest attached to envelope:', envelopeId);
     console.log('Required evidence:', (((response.envelope || {}).acceptance || {}).requiredEvidence || []).length);
+    printAcceptanceWarnings(response.envelope);
     return response.envelope;
   }
 
@@ -6712,6 +7137,10 @@ async function sessionsCommand(flags, subcommand) {
   throw new Error('Unknown sessions subcommand: ' + subcommand + '. Use: list, remove');
 }
 
+/*
+## Service Dashboard And WebSocket Listener
+*/
+
 // --- Listener PID management ---
 function isListenerRunning() {
   if (!fs.existsSync(LISTENER_PID_FILE)) {
@@ -8803,6 +9232,10 @@ async function runManagedWebsocketWatchdog() {
 
 // --- Persistent WebSocket listener ---
 // ---------------------------------------------------------------------------------------------
+/*
+## Agent And Ticket Workflows
+*/
+
 // Local agent sessions
 //
 // A "CLI agent" is ONE terminal session — one tab running Claude, Codex, or a person — that has
@@ -11857,6 +12290,10 @@ async function listenStatusCommand(flags = {}) {
   printSessionIdentity(identity);
 }
 
+/*
+## Help, Auto Update, And Command Dispatch
+*/
+
 async function whoamiCommand(flags = {}) {
   const identity = resolveSessionIdentity(process.cwd(), flags);
   printSessionResolutionWarning(identity);
@@ -12024,7 +12461,7 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'sync') {
-    console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--json]');
+    console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--create-variant-branch] [--summary] [--json]');
     console.log('');
     console.log('On trunk this reconciles the pushed repository into live component rows.');
     console.log('On a variant branch this writes ComponentVariant overlays only.');
@@ -12110,7 +12547,7 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'commit') {
-    console.log('Usage: remits-cli components commit [--yes] [--safe] [--message|-m "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]');
+    console.log('Usage: remits-cli components commit [--yes] [--safe] [--create-variant-branch] [--message|-m "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]');
     console.log('');
     console.log('Runs staged compile validation, local git add/commit/push, server sync, then fast-forward pull.');
     console.log('Prefer explicit stage + git + components sync when you need inspectable phases.');
@@ -12152,11 +12589,13 @@ 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] [--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('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   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 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.');
@@ -12543,6 +12982,10 @@ async function main() {
     await testCommand(args);
     return;
   }
+  if (command === 'test' && subcommand === 'status') {
+    await testStatusCommand(args);
+    return;
+  }
 
   if (command === 'token') {
     await tokenCommand(args);