@remits/remits-cli 0.1.124 → 0.1.126

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
+- L1234  Account Repos, Guide Sync, And Platform Repo
+- L1892  Component Discovery And HTTP Logging
+- L2382  Skill Delivery And TOC Resolution
+- L2692  Auth And Component Staging
+- L3280  Component Summaries, Status, And Sync Gates
+- L4991  Branches, Promotion, Commit, And Test Runs
+- L5988  Tokens, Tools, Verification, And Config
+- L6889  Service Dashboard And WebSocket Listener
+- L8984  Agent And Ticket Workflows
+- L12042  Help, Auto Update, And Command Dispatch
+*/
+
+/*
+## Runtime Bootstrap And Shared State
+*/
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -84,18 +106,33 @@ const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
 // flag keeps last-wins so existing callers are unaffected.
 const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved', 'names']);
 
+// `-m "msg"` is how git spells a commit message, and agents type it from habit. Before this the parser took a
+// single-dash token as the VALUE of whatever flag preceded it: `--json -m "x"` silently turned JSON mode
+// off, and `--summary -m "x"` committed with the default message. A single-letter `-x` token is now always
+// 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));
+}
+
 function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith('--')) {
+    if (!isFlagToken(arg)) {
       out._.push(arg);
       continue;
     }
-    const key = arg.slice(2);
+    const shortName = arg.startsWith('--') ? null : arg.slice(1);
+    const key = shortName ? (SHORT_FLAG_ALIASES[shortName] || shortName) : arg.slice(2);
     const next = argv[i + 1];
     let value;
-    if (!next || next.startsWith('--')) {
+    if (!next || isFlagToken(next)) {
       value = true;
     } else {
       value = next;
@@ -114,6 +151,25 @@ function flagEnabled(value) {
   return value === true || value === 'true' || value === '1' || value === 'yes';
 }
 
+function withStdoutRoutedToStderr(enabled, fn) {
+  if (!enabled) return fn();
+  const originalLog = console.log;
+  console.log = (...args) => console.error(...args);
+  try {
+    const result = fn();
+    if (result && typeof result.then === 'function') {
+      return result.finally(() => {
+        console.log = originalLog;
+      });
+    }
+    console.log = originalLog;
+    return result;
+  } catch (err) {
+    console.log = originalLog;
+    throw err;
+  }
+}
+
 function ensureSessionDir() {
   if (!fs.existsSync(SESSION_DIR)) {
     fs.mkdirSync(SESSION_DIR, { recursive: true });
@@ -453,11 +509,12 @@ function isLocalBaseUrl(baseUrl) {
  * boundaries by assumption, so the banner is loud, states the account it resolved, and distinguishes
  * live production writes from isolated test-data writes.
  */
-function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false }) {
+function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false, stderr = false }) {
   const normalizedDataMode = String(dataMode || '').toLowerCase();
   const prodData = normalizedDataMode === 'prod';
   const prodHost = baseUrl && !isLocalBaseUrl(baseUrl);
   if (!prodData && !prodHost && !mutating) return;
+  const emit = stderr ? console.error : console.log;
   const bar = '='.repeat(72);
   let headline;
   if (prodData) {
@@ -473,13 +530,13 @@ function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating
       ? 'TEST DATA — DRY RUN (no write will be attempted)'
       : 'TEST DATA WRITE — isolated test data';
   }
-  console.log(bar);
-  console.log('  ' + headline);
-  console.log('  operation: ' + (operation || 'unknown'));
-  if (accountId != null) console.log('  account:   ' + accountId);
-  if (baseUrl) console.log('  host:      ' + normalizeBaseUrl(baseUrl));
-  console.log('  dataMode:  ' + (normalizedDataMode || 'unknown'));
-  console.log(bar);
+  emit(bar);
+  emit('  ' + headline);
+  emit('  operation: ' + (operation || 'unknown'));
+  if (accountId != null) emit('  account:   ' + accountId);
+  if (baseUrl) emit('  host:      ' + normalizeBaseUrl(baseUrl));
+  emit('  dataMode:  ' + (normalizedDataMode || 'unknown'));
+  emit(bar);
 }
 
 // A tool's OWN verdict, which is separate from whether the call was dispatched. Only an explicit
@@ -534,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 });
@@ -1052,7 +1113,11 @@ 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,
+    // `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,
     variantId: resolution.variantId || fallback.variantId,
     sourceLayer: fallback.sourceLayer || (source.testComponentSource === 'staged' ? 'staged' : undefined)
   };
@@ -1165,6 +1230,10 @@ function loadAccountInfo(cwd) {
   }
 }
 
+/*
+## Account Repos, Guide Sync, And Platform Repo
+*/
+
 function readAccountRepoIndex() {
   if (!fs.existsSync(ACCOUNT_REPO_INDEX_FILE)) {
     return {};
@@ -1493,18 +1562,18 @@ function maybePullPlatformRepo(dir, options) {
     const dirty = execSync('git -C ' + shellQuote(dir) + ' status --porcelain', { stdio: ['ignore', 'pipe', 'ignore'] })
       .toString().trim();
     if (dirty) {
-      console.log('[platform] Skipping git pull: ' + dir + ' has uncommitted changes.');
+      console.error('[platform] Skipping git pull: ' + dir + ' has uncommitted changes.');
       return;
     }
     const originUrl = readGitRemoteUrl(dir, 'origin');
     if (originUrl && originUrl !== PLATFORM_REPO_GIT_URL) {
-      console.log('[platform] Found Remits platform repo at ' + dir + ', but its origin remote is ' + originUrl + ' (expected ' + PLATFORM_REPO_GIT_URL + ').');
-      console.log('[platform] Fix it with: git -C ' + dir + ' remote set-url origin ' + PLATFORM_REPO_GIT_URL);
+      console.error('[platform] Found Remits platform repo at ' + dir + ', but its origin remote is ' + originUrl + ' (expected ' + PLATFORM_REPO_GIT_URL + ').');
+      console.error('[platform] Fix it with: git -C ' + dir + ' remote set-url origin ' + PLATFORM_REPO_GIT_URL);
     }
-    console.log('[platform] Updating Remits platform repo (git pull)...');
+    console.error('[platform] Updating Remits platform repo (git pull)...');
     execSync('git -C ' + shellQuote(dir) + ' pull --ff-only', { stdio: 'inherit' });
   } catch (err) {
-    console.log('[platform] git pull did not complete cleanly (leaving the repo as-is): ' + (err && err.message ? err.message : String(err)));
+    console.error('[platform] git pull did not complete cleanly (leaving the repo as-is): ' + (err && err.message ? err.message : String(err)));
   }
 }
 
@@ -1556,21 +1625,21 @@ function ensurePlatformRepoLocal(options = {}) {
 
   const target = defaultPlatformRepoDir();
   if (fs.existsSync(target)) {
-    console.log('[platform] Skipping clone: ' + target + ' already exists but is not the Remits platform repo. Set REMITS_PLATFORM_DIR to its location.');
+    console.error('[platform] Skipping clone: ' + target + ' already exists but is not the Remits platform repo. Set REMITS_PLATFORM_DIR to its location.');
     return null;
   }
   try {
-    console.log('[platform] Cloning Remits platform repo into ' + target + ' (one-time)...');
+    console.error('[platform] Cloning Remits platform repo into ' + target + ' (one-time)...');
     ensureDir(path.dirname(target));
     execSync('git clone ' + shellQuote(PLATFORM_REPO_GIT_URL) + ' ' + shellQuote(target), { stdio: 'inherit' });
   } catch (err) {
-    console.log('[platform] Could not clone the Remits platform repo automatically: ' + (err && err.message ? err.message : String(err)));
-    console.log('[platform] Clone it manually with: git clone ' + PLATFORM_REPO_GIT_URL + ' ' + target);
+    console.error('[platform] Could not clone the Remits platform repo automatically: ' + (err && err.message ? err.message : String(err)));
+    console.error('[platform] Clone it manually with: git clone ' + PLATFORM_REPO_GIT_URL + ' ' + target);
     return null;
   }
   if (looksLikePlatformRepo(target)) {
     setPlatformRepoEntry(target, 'cloned');
-    console.log('[platform] Remits platform repo available at ' + target);
+    console.error('[platform] Remits platform repo available at ' + target);
     return target;
   }
   return null;
@@ -1819,6 +1888,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.
@@ -1936,6 +2009,27 @@ function collectComponents(cwd) {
     components.push(component);
   }
 
+  const rootReadme = path.join(cwd, 'README.md');
+  if (fs.existsSync(rootReadme) && fs.statSync(rootReadme).isFile()) {
+    const component = withFileKey({
+      type: 'prompt',
+      id: null,
+      name: 'README',
+      purpose: 'README',
+      category: 'default',
+      prompt: fs.readFileSync(rootReadme, 'utf8'),
+      metadataAuthoritative: true
+    }, 'prompt:name:readme');
+    const fingerprint = {};
+    Object.keys(component).sort().forEach((key) => {
+      if (key !== 'hash') {
+        fingerprint[key] = component[key] == null ? null : component[key];
+      }
+    });
+    component.hash = sha256(stableStringify(fingerprint));
+    components.push(component);
+  }
+
   return components;
 }
 
@@ -1954,6 +2048,16 @@ function componentPathInfo(cwd, filePath) {
     tests: 'test'
   };
   const relative = String(filePath || '').replace(/\\/g, '/').replace(/^"|"$/g, '');
+  if (relative === 'README.md') {
+    return {
+      key: 'prompt:name:readme',
+      type: 'prompt',
+      id: null,
+      name: 'README',
+      field: 'prompt',
+      path: relative
+    };
+  }
   const parts = relative.split('/');
   if (parts.length < 3 || parts[0] !== 'components') {
     return null;
@@ -2001,7 +2105,7 @@ function changedComponentsFromWorkingTree(cwd) {
     // status field on the FIRST line (` M path` -> `M path`). Any fixed-offset slice then reads the
     // path one character short and silently drops that entry — so a single modified component
     // reported as zero, while an untracked one ("?? path", no leading space) reported fine.
-    porcelain = execSync('git status --porcelain -- components', {
+    porcelain = execSync('git status --porcelain -- components README.md', {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe']
     }).toString();
@@ -2070,7 +2174,7 @@ function changedComponentsFromWorkingTree(cwd) {
 function changedComponentsSinceRef(cwd, ref) {
   let output = '';
   try {
-    output = execSync('git diff --name-only ' + JSON.stringify(ref) + '...HEAD -- components', {
+    output = execSync('git diff --name-only ' + JSON.stringify(ref) + '...HEAD -- components README.md', {
       cwd,
       stdio: ['ignore', 'pipe', 'pipe']
     }).toString();
@@ -2274,6 +2378,10 @@ async function loggedGet(api, cwd, endpoint, params = {}) {
   }
 }
 
+/*
+## Skill Delivery And TOC Resolution
+*/
+
 // ---------------------------------------------------------------------------
 // Skill delivery
 //
@@ -2403,6 +2511,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;
 }
 
@@ -2572,6 +2688,10 @@ async function installSkillsCommand(flags) {
   }
 }
 
+/*
+## Auth And Component Staging
+*/
+
 async function authCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2809,16 +2929,63 @@ async function pushComponentsCommand(flags) {
       // Deliberately NOT an error, and deliberately not a clear. An agent that has not edited anything yet
       // is in an ordinary state; failing its loop teaches it nothing, and reconciling the lane to an empty
       // manifest would delete the overlay its next test run depends on.
-      console.log('Stage mode:', stageMode);
-      console.log('Workset detected from git: 0 component(s) — nothing was staged and the lane was left as it is.');
-      if (worksetReplace) {
-        console.log('  The lane was NOT cleared. Clearing stays explicit: `remits-cli components clear --all`,');
-        console.log('  or re-run with `--empty-workset clear` if an empty lane is what you meant.');
+      const emptyResponse = {
+        success: true,
+        mode,
+        dataMode,
+        accountId,
+        branchName,
+        workspace,
+        stagingLane: workspace ? branchName + ' [ws:' + workspace + ']' : branchName,
+        sharedLane: !workspace,
+        updated: 0,
+        unchanged: 0,
+        skipped: [],
+        changedOnly: true,
+        requestedStageMode: stageMode,
+        stage: {
+          mode: stageMode,
+          manifestScope: 'working-tree',
+          replacedLane: false,
+          submittedCount: 0,
+          worksetCount: 0,
+          worksetKnown: true,
+          retainedCount: null,
+          removedRetainedCount: 0,
+          unrepresentable: unstageable
+        },
+        laneSummary: {
+          stagedCount: null,
+          stageMode: 'unchanged',
+          manifestScope: 'working-tree',
+          submittedCount: 0,
+          retainedCount: null,
+          worksetCount: 0,
+          worksetKnown: true,
+          fullSnapshot: false
+        },
+        staged: false,
+        message: 'Workset detected from git: 0 component(s); nothing was staged and the lane was left as it is.',
+        hint: worksetReplace
+          ? 'The lane was NOT cleared. Clearing stays explicit: remits-cli components clear --all, or re-run with --empty-workset clear if an empty lane is what you meant.'
+          : null,
+        changedFromWorkingTree: [],
+        changedFromWorkingTreeAvailable: true,
+        unrepresentableChanges: unstageable
+      };
+      if (flagEnabled(flags.json)) {
+        console.log(JSON.stringify(emptyResponse, null, 2));
+      } else {
+        console.log('Stage mode:', stageMode);
+        console.log(emptyResponse.message);
+        if (worksetReplace) {
+          console.log('  The lane was NOT cleared. Clearing stays explicit: `remits-cli components clear --all`,');
+          console.log('  or re-run with `--empty-workset clear` if an empty lane is what you meant.');
+        }
+        printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
+        printUnrepresentableChanges(unstageable);
       }
-      printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
-      printUnrepresentableChanges(unstageable);
-      return { success: true, mode, updated: 0, unchanged: 0, skipped: [], changedOnly: true, stageMode,
-               worksetCount: 0, staged: false };
+      return emptyResponse;
     }
   }
 
@@ -2859,6 +3026,9 @@ async function pushComponentsCommand(flags) {
     // The git evidence, per component: which files changed and with what status. It is what lets the
     // console split a lane's "active workset" from the entries a previous full snapshot left behind.
     changedSet: (changedFromWorkingTree || []).concat(unstageable),
+    // The commit this tree is on. Stamped onto every entry as `stageBaseSha`, so `components status` can
+    // tell this lane — and anyone reading it — that somebody has landed since it was staged.
+    baseSha: safeGitValue(cwd, 'git rev-parse HEAD') || undefined,
     // Kept for a platform that predates stageMode. Same meaning it always had.
     replace: !changedOnly,
     components
@@ -3023,6 +3193,25 @@ function unrepresentableChanges(changedFromWorkingTree, collected) {
   return report;
 }
 
+// One list from two sources, de-duplicated on identity + reason.
+function mergeUnrepresentable(local, platform) {
+  const merged = [];
+  const seen = new Set();
+  [].concat(Array.isArray(local) ? local : [], Array.isArray(platform) ? platform : []).forEach((entry) => {
+    if (!entry) return;
+    const key = [
+      String(entry.type || '').toLowerCase(),
+      entry.id != null ? String(entry.id) : '',
+      String(entry.name || '').toLowerCase(),
+      entry.reason || ''
+    ].join('|');
+    if (seen.has(key)) return;
+    seen.add(key);
+    merged.push(entry);
+  });
+  return merged;
+}
+
 function printUnrepresentableChanges(unstageable) {
   if (!unstageable || !unstageable.length) return;
   console.log('');
@@ -3087,6 +3276,10 @@ async function stageOrRefuse(api, cwd, payload) {
   }
 }
 
+/*
+## 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;
@@ -3299,7 +3492,9 @@ function printStageSummary(response, flags) {
     console.log('  Or drop the overlay entirely:        remits-cli components clear --all');
   }
 
-  printUnrepresentableChanges(response.unrepresentableChanges || (stage.unrepresentable || []));
+  // 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 printAccountLanes === 'function') {
     printAccountLanes(response);
   }
@@ -3325,6 +3520,8 @@ function printStatusSummary(response, flags) {
   printBranchContext(response);
   printStagingLane(response.branchName, response.workspace, null);
   printLaneSummary(response);
+  printStagingFreshness(response.freshness);
+  printRepositoryCheck(response.repositoryCheck);
   printComponentTypeCounts(response.entries || []);
 
   // Every lane staged on this branch, not just this one. An agent that believes it is working alone can
@@ -3364,9 +3561,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
@@ -3457,16 +3652,13 @@ function printLaneSummary(response) {
 // lane is still reported authoritatively above.
 function printAccountLanes(response) {
   const lanes = Array.isArray(response.accountLanes) ? response.accountLanes : [];
-  const others = lanes.filter((lane) => !lane.mine);
+  const others = lanes.filter((lane) => !isCurrentStagingLane(lane));
   if (!others.length) return;
 
   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
@@ -3477,12 +3669,33 @@ function printAccountLanes(response) {
       ? ', workset ' + lane.worksetCountAsOf : '';
     const stageMode = lane.stageMode && lane.stageMode !== 'unknown' ? '  [' + lane.stageMode + ']' : '';
     const shared = lane.sharedLane === true ? '  SHARED LANE' : '';
-    console.log('  ' + (lane.mine ? '* ' : '  ') + lane.branchName + ws
+    console.log('  ' + (isCurrentStagingLane(lane) ? '* ' : '  ') + lane.branchName + ws
       + '  (' + world + ')  — overlay ' + (lane.stagedCountAsOf || 0) + workset + stageMode + shared + who + ttl);
   });
   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.');
+}
+
+// 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) {
+  if (!lane) return false;
+  if (typeof lane.currentLane === 'boolean') return lane.currentLane;
+  // Older platforms used `mine` for "this exact command lane". Keep the terminal star compatible.
+  return lane.mine === true;
 }
 
 // Make the working tree's meaning explicit. An agent may be standing in a TRUNK checkout or in a
@@ -3496,11 +3709,29 @@ 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".
+    console.log('  last platform sync of this branch: ' + (ctx.lastSyncedSha ? short(ctx.lastSyncedSha) : 'unknown'));
+  }
+  if (ctx.repository) {
+    console.log('  sync reads repository: ' + ctx.repository +
+      (ctx.commitOwnerAccountId != null ? ' (account ' + ctx.commitOwnerAccountId + ')' : ''));
+  }
+  if (ctx.inheritedSubscription) {
+    console.log('');
+    console.log('  INHERITED BRANCH: ' + (ctx.inheritedSubscriptionMessage ||
+      ('this account resolves the branch through an ancestor owned by account ' + ctx.resolvingOwnerAccountId + '.')));
+  }
 
   if (!ctx.onTrunk) {
     console.log('  variants stored on this branch: ' + (ctx.variantCount || 0));
@@ -3600,6 +3831,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);
@@ -3608,6 +3842,17 @@ async function statusComponentsCommand(flags) {
     throw new Error(response.message || 'Staging status failed');
   }
 
+  // Has anybody landed since this lane was staged? Only this checkout can order commits, so the platform
+  // 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'),
+    lastSyncedSha: response.branchContext && response.branchContext.lastSyncedSha,
+    entries: response.entries,
+    laneSummary: response.laneSummary,
+    isAncestor: (a, b) => gitIsAncestor(cwd, a, b)
+  });
+  response.repositoryCheck = repositoryCheck(cwd, response.branchContext);
+
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
     type: 'component_status',
     success: true,
@@ -3794,7 +4039,8 @@ async function syncComponentsCommand(rawFlags) {
     baseUrl,
     operation: 'components sync (branch ' + branchName + ')',
     mutating: true,
-    dryRun: dryRun || namesOnly
+    dryRun: dryRun || namesOnly,
+    stderr: flagEnabled(flags.json)
   });
 
   const syncPayload = {
@@ -3816,6 +4062,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: []
   };
 
@@ -3835,22 +4084,63 @@ async function syncComponentsCommand(rawFlags) {
     }).then((r) => r.data);
 
     const branchContext = statusResponse && statusResponse.branchContext;
-    if (!branchContext || branchContext.onTrunk) {
+    // --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', branchContext);
+      if (flagEnabled(flags.json)) {
+        const refusal = {
+          success: false,
+          mode: 'sync',
+          dataMode,
+          accountId,
+          branchName,
+          workspace,
+          safe,
+          branchContext,
+          repositoryCheck: preflightRepoCheck,
+          gateViolations: [mismatch],
+          message: mismatch
+        };
+        console.log(JSON.stringify(refusal, null, 2));
+        process.exitCode = 1;
+        return refusal;
+      }
+      throw new Error(mismatch + ' Nothing was synced.');
+    }
+    if (branchContextIsTrunk(branchContext)) {
       // Trunk has no dry-run plan to gate on, and pretending otherwise would be worse than refusing:
       // an agent would read "safe" and get an ungated authoritative reconcile. Say what trunk sync is
       // and make the caller assert it.
       if (!safe) {
         throw new Error('components sync safety preflight requires a non-trunk variant branch because trunk sync has no dry-run plan. Re-run without safety flags only if you intend a full trunk reconcile.');
       }
-      console.log('');
-      console.log('TRUNK SYNC — there is no dry-run plan for trunk, so --safe cannot gate this.');
-      console.log('  This is an AUTHORITATIVE full repo-to-DB reconcile of ' + (branchContext ? branchContext.trunkBranch || branchName : branchName) + ':');
-      console.log('    every component row is rewritten from the pushed repo, and any live component');
-      console.log('    missing from the repo is DELETED.');
-      console.log('  For a gated plan, work on a variant branch instead.');
+      printTrunkSyncWarning(branchContext ? branchContext.trunkBranch || branchName : branchName, {
+        stderr: flagEnabled(flags.json)
+      });
       if (!flagEnabled(flags.yes)) {
-        throw new Error('components sync --safe on trunk requires --yes, because the plan cannot be previewed. ' +
-          'Re-run with --yes to accept the full trunk reconcile, or switch to a variant branch for a gated sync.');
+        const message = trunkSafeRequiresYesMessage('components sync');
+        if (flagEnabled(flags.json)) {
+          const refusal = {
+            success: false,
+            mode: 'sync',
+            dataMode,
+            accountId,
+            branchName,
+            workspace,
+            dryRun,
+            safe: true,
+            branchContext,
+            repositoryCheck: preflightRepoCheck,
+            gates: { safeRequiresYes: false },
+            gateViolations: [message],
+            message
+          };
+          console.log(JSON.stringify(refusal, null, 2));
+          process.exitCode = 1;
+          return refusal;
+        }
+        throw new Error(message);
       }
       // Drop the gates that can only be evaluated against a plan. Leaving them on would fail the command
       // AFTER an authoritative reconcile had already been written, which is the worst of both.
@@ -3870,8 +4160,17 @@ async function syncComponentsCommand(rawFlags) {
       }
 
       preflightGate = evaluateSyncGates(previewResponse, gateFlags, changedFromWorkingTree, cwd);
+      // Decorate the preview ONCE, before any branch below can print or return it, so every preview output
+      // — names-only, a gate refusal, the full or --summary JSON, the commit outcome's nested sync — carries
+      // the same gate results and repository check. Decorating per branch is how one branch was missed.
+      decoratePreview(previewResponse, preflightGate, preflightRepoCheck);
 
       if (namesOnly) {
+        if (flagEnabled(flags.json)) {
+          console.log(JSON.stringify(previewResponse, null, 2));
+          if (preflightGate.violations.length) process.exitCode = 1;
+          return previewResponse;
+        }
         printSessionResolutionWarning(sessionContext);
         printResolvedBaseUrl(baseUrl);
         console.log('Data mode:', previewResponse.dataMode || dataMode);
@@ -3882,6 +4181,12 @@ async function syncComponentsCommand(rawFlags) {
         return previewResponse;
       }
 
+      if (preflightGate.violations.length && flagEnabled(flags.json)) {
+        const previewSummary = previewSummaryFor(previewResponse, preflightGate);
+        console.log(JSON.stringify(flagEnabled(flags.summary) ? previewSummary : previewResponse, null, 2));
+        process.exitCode = 1;
+        return previewResponse;
+      }
       failOnSyncGate(preflightGate);
 
       // The plan passed every gate. Show it before mutating anyway: a gate proves the plan matches the
@@ -3903,9 +4208,17 @@ async function syncComponentsCommand(rawFlags) {
     throw new Error(response.message || 'Server sync failed');
   }
 
-  const summary = buildSyncSummary(response);
   const gate = preflightGate || evaluateSyncGates(response, gateFlags, changedFromWorkingTree, cwd);
+  decorateSyncGate(response, gate);
+  // A plain sync is not gated, but it must still SAY when it reconciled a repository other than this checkout's.
+  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', response.branchContext));
+  }
+  const summary = buildSyncSummary(response);
   summary.gates = gate.checks;
+  summary.gateViolations = gate.violations;
 
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
     type: response.sync && response.sync.dryRun ? 'sync_dry_run' : 'sync_mutation',
@@ -3926,7 +4239,7 @@ async function syncComponentsCommand(rawFlags) {
 
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(flagEnabled(flags.summary) ? summary : response, null, 2));
-    failOnSyncGate(gate);
+    if (gate.violations.length) process.exitCode = 1;
     return response;
   }
 
@@ -4082,7 +4395,8 @@ function resolveChangedSinceFlags(flags, cwd, branchContext, safe) {
       continue;
     }
     if (base) {
-      console.log('--safe: comparing the sync plan against everything this branch added since ' +
+      const emit = flagEnabled(flags.json) ? console.error : console.log;
+      emit('--safe: comparing the sync plan against everything this branch added since ' +
         candidate + ' (' + base.slice(0, 12) + ').');
       return Object.assign({}, flags, { 'changed-since': base });
     }
@@ -4122,7 +4436,8 @@ function syncPlanEntries(response) {
         bucket,
         type: String(entry.type || entry.kind || 'component').toLowerCase(),
         id: entry.id == null ? null : String(entry.id),
-        name: entry.name || null
+        name: entry.name || null,
+        path: entry.path || null
       });
     });
   });
@@ -4201,10 +4516,14 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree, cwd) {
       checks.changedOnly = false;
     } else {
       const changedSet = (changedFromWorkingTree || []).concat(fromRef || []);
-      // A component the checkout edited is identified by type + id, or type + name for `new_` files.
+      // A component the checkout edited is identified by type + id, type + name for `new_` files, or the
+      // repo file it came from. The path is what matches the root README.md: the plan names the README
+      // prompt after its TRUNK row (whatever that row is called), while the checkout only knows the file.
       const allowedIds = new Set(changedSet.filter((c) => c.id != null).map((c) => c.type + ':' + c.id));
       const allowedNames = new Set(changedSet.filter((c) => c.name).map((c) => c.type + ':' + String(c.name).toLowerCase()));
+      const allowedPaths = new Set([].concat(...changedSet.map((c) => (Array.isArray(c.paths) ? c.paths : []))).map(String));
       const unexpected = entries.filter((entry) => {
+        if (entry.path && allowedPaths.has(String(entry.path))) return false;
         if (entry.id != null && allowedIds.has(entry.type + ':' + entry.id)) return false;
         if (entry.name && allowedNames.has(entry.type + ':' + String(entry.name).toLowerCase())) return false;
         return true;
@@ -4242,11 +4561,289 @@ function failOnSyncGate(gate) {
   }
 }
 
+// The ONE decoration of a --safe preview (the server dry-run plan): gate results plus the repository check.
+function decoratePreview(previewResponse, gate, repoCheck) {
+  decorateSyncGate(previewResponse, gate);
+  if (previewResponse) previewResponse.repositoryCheck = repoCheck || null;
+  return previewResponse;
+}
+
+// The --summary shape of a decorated preview. buildSyncSummary reads `repositoryCheck` off the response, so
+// this must be built AFTER decoratePreview.
+function previewSummaryFor(previewResponse, gate) {
+  const summary = buildSyncSummary(previewResponse);
+  summary.gates = gate.checks;
+  summary.gateViolations = gate.violations;
+  return summary;
+}
+
+function decorateSyncGate(response, gate) {
+  if (!response || !gate) return response;
+  response.gates = gate.checks || {};
+  response.gateViolations = gate.violations || [];
+  if (response.sync && typeof response.sync === 'object') {
+    response.sync.gates = gate.checks || {};
+    response.sync.gateViolations = gate.violations || [];
+  }
+  if (gate.violations && gate.violations.length) {
+    response.success = false;
+    response.message = 'components sync safety gate failed';
+  }
+  return response;
+}
+
+function trunkSafeRequiresYesMessage(commandName) {
+  return commandName + ' --safe on trunk requires --yes, because the plan cannot be previewed. ' +
+    'Re-run with --yes to accept the full trunk reconcile, or switch to a variant branch for a gated sync.';
+}
+
+// ONE definition of "does this branch context mean trunk", shared by `components sync --safe` and the
+// pre-git `components commit` refusal. Fail closed: a missing context, or an `onTrunk` that is not
+// explicitly false, is the planless authoritative reconcile — never mistaken for a gated variant sync.
+function branchContextIsTrunk(branchContext) {
+  return !branchContext || branchContext.onTrunk !== false;
+}
+
+// The last path segment of a repository reference — "org/remits-x", "remits-x", or a git URL — lower-cased
+// and without ".git". Null when there is nothing to compare.
+function repositoryBaseName(value) {
+  if (!value) return null;
+  const text = String(value).trim().replace(/\/+$/, '').replace(/\.git$/i, '');
+  const segment = text.split(/[/:]/).pop();
+  return segment ? segment.toLowerCase() : null;
+}
+
+// Does this checkout's origin name the repository the platform syncs for the command's account?
+// true / false, or null when either side is unknown — an unknown is never reported as a match OR a mismatch.
+function repositoryNamesMatch(platformRepository, originUrl) {
+  const platform = repositoryBaseName(platformRepository);
+  const origin = repositoryBaseName(originUrl);
+  if (!platform || !origin) return null;
+  return platform === origin;
+}
+
+// A commit pushes to THIS checkout's origin; the platform then syncs the repository of the account the
+// command resolved (account-info.json, or --account-id). When those are different repositories the push is
+// never synced and the sync reconciles something nobody edited here — the one way a commit lands work
+// somewhere other than where it was made.
+function repositoryCheck(cwd, branchContext) {
+  const platformRepository = branchContext && branchContext.repository ? String(branchContext.repository) : null;
+  const checkoutOrigin = safeGitValue(cwd, 'git remote get-url origin') || null;
+  return { platformRepository, checkoutOrigin, matches: repositoryNamesMatch(platformRepository, checkoutOrigin) };
+}
+
+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. ' + (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) {
+  if (!check || check.matches !== false) return;
+  console.log('');
+  console.log('REPOSITORY MISMATCH: this checkout\'s origin (' + check.checkoutOrigin + ') is not the repository the ' +
+    'platform syncs for this account (' + check.platformRepository + ').');
+  console.log('  `components commit` and `components sync --safe` refuse here; a plain sync would reconcile ' +
+    check.platformRepository + ', not what you edited.');
+}
+
+// Every OTHER worktree that has `branch` checked out, from `git worktree list --porcelain`. Worktrees of one
+// branch SHARE its ref: a pull or a commit in any of them moves HEAD under the others, whose working trees then
+// no longer match it — and `components commit` (`git add -A`) from one of those records its stale tree over
+// work that has already landed. Reproduced in live verification: a sibling's trunk commit was silently reverted.
+// Pure, so it can be tested without a repository.
+function otherWorktreesOnBranch(porcelain, branch, currentTopLevel) {
+  if (!porcelain || !branch) return [];
+  const here = currentTopLevel ? path.resolve(String(currentTopLevel)) : null;
+  return String(porcelain).split(/\n\s*\n/).map((block) => {
+    const lines = block.split('\n');
+    const worktree = (lines.find((l) => l.startsWith('worktree ')) || '').slice('worktree '.length).trim();
+    const ref = (lines.find((l) => l.startsWith('branch ')) || '').slice('branch '.length).trim();
+    return { worktree, ref };
+  }).filter((w) => w.worktree && w.ref === 'refs/heads/' + branch && path.resolve(w.worktree) !== here)
+    .map((w) => w.worktree);
+}
+
+function sharedBranchMessage(branch, others) {
+  return 'components commit: branch "' + branch + '" is also checked out in ' + others.join(', ') + '. Worktrees ' +
+    'of one branch share its ref: a pull or a commit in any of them moves HEAD under the others, and this ' +
+    'commit\'s `git add -A` would record a stale tree over work that has already landed. Give each agent its own ' +
+    'CLONE (git clone <repo> && remits-cli workspace use --auto), or pass --allow-shared-branch once you have ' +
+    'confirmed `git status` shows only your own changes against the current HEAD.';
+}
+
+function trunkCommitRequiresYesMessage() {
+  return 'components commit on trunk requires --yes. It runs `git add -A`, commits, pushes, and then an ' +
+    'AUTHORITATIVE full repo-to-DB reconcile that creates, updates, renames and DELETES live component rows, ' +
+    'and trunk has no dry-run plan to preview. Re-run with --yes to accept that, or use the observable ' +
+    'sequence: git commit, git push, `remits-cli components sync --safe --yes`, git pull --ff-only.';
+}
+
+// Is `ancestor` contained in `descendant`? true / false, or null when git cannot say — typically an object
+// this checkout has never fetched, which is itself a statement that the checkout does not have it.
+function gitIsAncestor(cwd, ancestor, descendant) {
+  if (!ancestor || !descendant) return null;
+  try {
+    execSync('git merge-base --is-ancestor ' + shellQuote(ancestor) + ' ' + shellQuote(descendant), {
+      cwd,
+      stdio: ['ignore', 'ignore', 'ignore']
+    });
+    return true;
+  } catch (err) {
+    return err && err.status === 1 ? false : null;
+  }
+}
+
+/**
+ * Is this lane still describing the world the platform is in?
+ *
+ * After a sibling agent lands on the same branch, the platform clears only THAT agent's lane. Every other
+ * lane keeps shadowing the newly committed rows with content staged from the old base, and nothing used to
+ * say so. The platform reports the last commit it synced (`branchContext.lastSyncedSha`) and each entry's
+ * `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 }) {
+  const rows = Array.isArray(entries) ? entries : [];
+  const staged = rows.filter((entry) => entry && entry.stageBaseSha);
+  const memo = new Map();
+  const ancestorOf = (a, b) => {
+    const key = a + '..' + b;
+    if (!memo.has(key)) memo.set(key, isAncestor(a, b));
+    return memo.get(key);
+  };
+
+  // The platform synced a commit this checkout does not contain: somebody landed after you last pulled.
+  let landedSinceHead = null;
+  if (lastSyncedSha && head) {
+    landedSinceHead = lastSyncedSha === head ? false : ancestorOf(lastSyncedSha, head) !== true;
+  }
+  // Staged from a commit strictly behind the last sync: these shadow rows that landed after they were staged.
+  const behindLastSync = lastSyncedSha
+    ? staged.filter((entry) => entry.stageBaseSha !== lastSyncedSha && ancestorOf(entry.stageBaseSha, lastSyncedSha) === true)
+    : [];
+  const fromOtherCommits = head ? staged.filter((entry) => entry.stageBaseSha !== head) : [];
+  const baseShas = laneSummary && Array.isArray(laneSummary.baseShas)
+    ? laneSummary.baseShas
+    : Array.from(new Set(staged.map((entry) => entry.stageBaseSha)));
+
+  return {
+    head: head || null,
+    lastSyncedSha: lastSyncedSha || null,
+    landedSinceHead,
+    entriesBehindLastSync: behindLastSync.length,
+    entriesFromOtherCommits: fromOtherCommits.length,
+    // Staged by a build that predates the stamp. Unknown, never "fresh".
+    entriesWithUnknownBase: rows.length - staged.length,
+    baseShas,
+    stale: landedSinceHead === true || behindLastSync.length > 0
+  };
+}
+
+function printStagingFreshness(freshness) {
+  if (!freshness) return;
+  const plural = (n) => n + ' staged entr' + (n === 1 ? 'y' : 'ies');
+  if (freshness.landedSinceHead === true) {
+    console.log('');
+    console.log('LANDED SINCE YOUR BASE: the platform last synced ' + short(freshness.lastSyncedSha) +
+      ' on this branch, and this checkout does not contain it.');
+    console.log('  Somebody has landed since you pulled. Their rows are live, your lane still shadows them, and your');
+    console.log('  next commit has to include their work. Run: git fetch origin && git pull --ff-only, then re-stage.');
+  }
+  if (freshness.entriesBehindLastSync > 0) {
+    console.log('');
+    console.log('STALE OVERLAY: ' + plural(freshness.entriesBehindLastSync) + ' came from a commit older than the last sync (' +
+      short(freshness.lastSyncedSha) + ').');
+    console.log('  They shadow committed rows that landed after they were staged. Re-stage from your current tree');
+    console.log('  (remits-cli components stage --workset) or drop them (remits-cli components clear).');
+  } else if (freshness.entriesFromOtherCommits > 0) {
+    console.log('Note: ' + plural(freshness.entriesFromOtherCommits) + ' were staged from a commit other than your HEAD (' +
+      short(freshness.head) + ').');
+  }
+  if (freshness.entriesWithUnknownBase > 0) {
+    console.log('Note: ' + plural(freshness.entriesWithUnknownBase) + ' predate base tracking; their base commit is unknown.');
+  }
+}
+
+function printTrunkSyncWarning(trunkBranch, options) {
+  const emit = options && options.stderr ? console.error : console.log;
+  emit('');
+  emit('TRUNK SYNC — there is no dry-run plan for trunk, so --safe cannot gate this.');
+  emit('  This is an AUTHORITATIVE full repo-to-DB reconcile of ' + (trunkBranch || 'main') + ':');
+  emit('    every component row is rewritten from the pushed repo, and any live component');
+  emit('    missing from the repo is DELETED.');
+  emit('  For a gated plan, work on a variant branch instead.');
+}
+
 function buildSyncSummary(response) {
   const sync = (response && response.sync) || {};
   const results = sync.syncResults || {};
   const errors = Array.isArray(results.errors) ? results.errors : [];
   const skipped = Array.isArray(results.skipped) ? results.skipped : [];
+  // Which repository the platform read, and whether it is this checkout's. Carried on EVERY summary shape —
+  // `--summary`, `--json --summary` and the commit outcome's nested sync all print this object, not the raw
+  // response, so a check attached only to the response is invisible to exactly the callers that ask for less.
+  const repositoryCheck = (response && response.repositoryCheck) || null;
+  const repositoryWarning = repositoryCheck && repositoryCheck.matches === false
+    ? 'REPOSITORY MISMATCH: the platform synced ' + repositoryCheck.platformRepository +
+      ', but this checkout\'s origin is ' + repositoryCheck.checkoutOrigin
+    : null;
 
   // A sync that SHORT-CIRCUITED on the cached branch SHA did no work at all, and the server says so
   // (`skipped: true` plus a message). Rendering it through the normal shape below printed
@@ -4267,14 +4864,18 @@ function buildSyncSummary(response) {
       skipped: true,
       reason: sync.message || 'branch head matches the cached sync SHA; the branch was not re-read',
       branchHeadSha: sync.branchHeadSha || sync.postSyncSha || null,
-      warnings: [
+      repository: sync.repository || null,
+      repositoryCheck,
+      gates: (response && response.gates) || null,
+      gateViolations: (response && response.gateViolations) || null,
+      warnings: (repositoryWarning ? [repositoryWarning] : []).concat([
         // Scoped to COMPONENTS deliberately: the short-circuit still refreshes the delivered guides and
         // account metadata, so "nothing happened" would be its own small untruth.
         'NO COMPONENTS WERE SYNCED. This is the cached-SHA short-circuit, not an empty plan — the ' +
           'branch was never re-read.',
         'Use --dry-run to see the real plan (a dry run always re-reads the branch), or ' +
           '--force-tombstones to re-read and apply it.'
-      ]
+      ])
     };
   }
 
@@ -4285,24 +4886,54 @@ function buildSyncSummary(response) {
   if ((sync.mode || 'trunk') === 'trunk') {
     const created = Array.isArray(results.created) ? results.created : [];
     const updated = Array.isArray(results.updated) ? results.updated : [];
+    const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
     const renamed = Array.isArray(results.renamed) ? results.renamed : [];
     const deleted = Array.isArray(results.deleted) ? results.deleted : [];
     const trunkWarnings = [];
     if (deleted.length) trunkWarnings.push(String(deleted.length) + ' live component(s) DELETED');
     if (errors.length) trunkWarnings.push(String(errors.length) + ' sync error' + (errors.length === 1 ? '' : 's') + ' present');
+    if (repositoryWarning) trunkWarnings.push(repositoryWarning);
     return {
       success: response && response.success === true,
       accountId: response && response.accountId,
       branchName: sync.branchName || (response && response.branchName),
       mode: 'trunk',
       dryRun: false,
+      repository: sync.repository || null,
+      repositoryCheck,
+      gates: (response && response.gates) || null,
+      gateViolations: (response && response.gateViolations) || null,
       // Ids are the part that cannot be recovered later: a promotion mints them once, and anything that
       // recorded the old identity will not line up if they are re-minted.
       created: created.map((e) => ({ type: e.type, name: e.name, id: e.newId != null ? e.newId : e.id })),
-      updated: updated.length,
-      renamed: renamed.length,
+      createdCount: created.length,
+      updated: updated.map((e) => ({
+        type: e.type,
+        name: e.name,
+        id: e.id,
+        changed: Array.isArray(e.changed) ? e.changed : (e.content ? [e.content] : [])
+      })),
+      updatedCount: updated.length,
+      unchanged: unchanged.length,
+      renamed: renamed.map((e) => ({
+        from: e.from || e.oldPath || e.oldName,
+        to: e.to || e.newPath || e.newName,
+        reason: e.reason || (e.message ? String(e.message) : undefined),
+        type: e.type,
+        name: e.name,
+        id: e.id
+      })),
+      renamedCount: renamed.length,
       deleted: deleted.map((e) => ({ type: e.type, name: e.name, id: e.id })),
-      skipped: skipped.length,
+      deletedCount: deleted.length,
+      skipped: skipped.map((e) => ({
+        type: e.type,
+        name: e.name,
+        id: e.id,
+        reason: e.reason || (e.pruned ? 'pruned' : undefined),
+        files: e.files
+      })),
+      skippedCount: skipped.length,
       errors: errors.length,
       errorDetails: errors.map((entry) => ({ type: entry.type, id: entry.id, error: entry.error })),
       warnings: trunkWarnings
@@ -4316,12 +4947,17 @@ function buildSyncSummary(response) {
   const warnings = [];
   if (removed.length) warnings.push(String(removed.length) + ' removed/tombstone entr' + (removed.length === 1 ? 'y' : 'ies') + ' present');
   if (errors.length) warnings.push(String(errors.length) + ' sync error' + (errors.length === 1 ? '' : 's') + ' present');
+  if (repositoryWarning) warnings.push(repositoryWarning);
   return {
     success: response && response.success === true,
     accountId: response && response.accountId,
     branchName: sync.branchName || (response && response.branchName),
     mode: sync.mode || 'trunk',
     dryRun: Boolean(sync.dryRun),
+    repository: sync.repository || null,
+    repositoryCheck,
+    gates: (response && response.gates) || null,
+    gateViolations: (response && response.gateViolations) || null,
     overridden: overridden.length,
     added: added.length,
     removed: removed.map((entry) => ({
@@ -4332,7 +4968,15 @@ function buildSyncSummary(response) {
       variantId: entry.variantId
     })),
     unchanged: unchanged.length,
-    skipped: skipped.length,
+    skipped: skipped.map((entry) => ({
+      type: entry.type,
+      kind: entry.kind,
+      name: entry.name,
+      id: entry.id,
+      variantId: entry.variantId,
+      reason: entry.reason
+    })),
+    skippedCount: skipped.length,
     errors: errors.length,
     errorDetails: errors.map((entry) => ({
       type: entry.type,
@@ -4343,6 +4987,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.
@@ -4420,11 +5068,32 @@ async function branchesComponentsCommand(flags) {
 
 function printBranchesSummary(response) {
   console.log('Trunk branch:', response.trunk || 'main');
+  if (response.branchOwnerAccountId && response.branchOwnerAccountId !== response.accountId) {
+    console.log('Branch owner account:', response.branchOwnerAccountId, '(caller account ' + response.accountId + ')');
+  }
 
   if (response.mode === 'list') {
     const branches = response.branches || [];
+    const subscription = response.subscription;
+    if (subscription && subscription.branchName) {
+      const inherited = subscription.subscriberAccountId != null && String(subscription.subscriberAccountId) !== String(response.accountId)
+        ? ', inherited through account ' + subscription.subscriberAccountId : '';
+      console.log('This account resolves branch "' + subscription.branchName + '" owned by account ' + subscription.ownerAccountId +
+        (subscription.ownerAccountName ? ' (' + subscription.ownerAccountName + ')' : '') + inherited + '.');
+      console.log('  Inspect it: remits-cli components branch ' + subscription.branchName);
+    }
+    // The subscriptions on this account's OWN edges. `subscription` is the resolved-path answer, which is null
+    // for an account with several upward edges and no anchor — a subscriber then listed its own subscription
+    // as nothing. The edges are the fact.
+    const edgeSubscriptions = Array.isArray(response.branchSubscriptions) ? response.branchSubscriptions : [];
+    if (!(subscription && subscription.branchName) && edgeSubscriptions.length) {
+      edgeSubscriptions.forEach((e) => console.log('This account subscribes to branch "' + e.branchName +
+        '" on its edge to account ' + e.parentAccountId + (e.parentAccountName ? ' (' + e.parentAccountName + ')' : '') +
+        (e.primary ? ' [primary edge]' : '') + '.'));
+      console.log('  Inspect it: remits-cli components branch ' + edgeSubscriptions[0].branchName);
+    }
     if (!branches.length) {
-      console.log('No component variant branches for this account.');
+      console.log('No component variant branches OWNED by this account.');
       return;
     }
     console.log('');
@@ -4685,9 +5354,14 @@ async function commitComponentsCommand(flags) {
   const commitMessage = String(flags.message || ('remits-cli commit sync ' + new Date().toISOString()));
   const allowEmpty = flags['allow-empty'] === true || flags['allow-empty'] === 'true';
   const skipGit = flags['skip-git'] === true || flags['skip-git'] === 'true';
+  const jsonOutput = flagEnabled(flags.json);
+  const emit = jsonOutput ? console.error : console.log;
   if (flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun)) {
     throw new Error('components commit does not support --dry-run because it performs local git writes. Use `remits-cli components sync --dry-run`.');
   }
+  if (await refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, skipGit)) {
+    return;
+  }
 
   // Landing is serial and nothing can make it concurrent: `git add -A` sweeps a shared checkout, and the
   // platform pushes a regenerated `account-info.json` back to the branch during sync, so two commits
@@ -4699,14 +5373,33 @@ async function commitComponentsCommand(flags) {
   // The honest limit: this cannot stop a raw `git push` somebody runs themselves. It makes `remits-cli
   // components commit` serial, which is the path everything actually uses.
   const landing = await acquireLandingLease(flags, accountId, branchName);
+  // What this commit has done so far, stated rather than left to be inferred from prose. "Pushed but not
+  // synced" is the state the next agent most needs to know about — the remote and the platform disagree
+  // until a sync succeeds, and the next sync of this branch by ANYONE lands it — and it used to be
+  // recoverable only by reading terminal output. In --json mode this is the ONE document on stdout.
+  const outcome = {
+    success: false,
+    mode: 'commit',
+    accountId,
+    branchName,
+    phase: skipGit ? 'sync' : 'stage',
+    skipGit,
+    gitCommitted: false,
+    pushed: false,
+    pushedSha: null,
+    synced: false,
+    postSyncSha: null,
+    pulled: false,
+    sync: null
+  };
   try {
   if (!skipGit) {
-    console.log('Phase 1/4: staged compile validation');
+    emit('Phase 1/4: staged compile validation');
     // MERGE semantics on purpose (`--changed-only`, never `--workset`). A workset stage RECONCILES the
     // lane — it deletes every entry outside the git changed set — and the lane is frequently shared. A
     // validation pass must not be able to delete another agent's staged work as a side effect of somebody
     // running `components commit`. This adds the changed components to the lane and leaves the rest alone.
-    await pushComponentsCommand(Object.assign({}, flags, {
+    await withStdoutRoutedToStderr(jsonOutput, () => pushComponentsCommand(Object.assign({}, flags, {
       branch: branchName,
       'account-id': accountId,
       mode: 'stage',
@@ -4714,24 +5407,26 @@ async function commitComponentsCommand(flags) {
       'replace-lane': false,
       replaceLane: false,
       'changed-only': true
-    }));
+    })));
 
-    console.log('Phase 2/4: local git commit/push');
+    outcome.phase = 'git';
+    emit('Phase 2/4: local git commit/push');
     const status = runGit(cwd, 'git status --porcelain');
     if (status || allowEmpty) {
       runGit(cwd, 'git add -A');
       const commitCmd = 'git commit ' + (allowEmpty ? '--allow-empty ' : '') + '-m ' + shellQuote(commitMessage);
       try {
         runGit(cwd, commitCmd);
+        outcome.gitCommitted = true;
       } catch (err) {
         if (!allowEmpty && String(err.message || '').toLowerCase().includes('nothing to commit')) {
-          console.log('No staged changes to commit.');
+          emit('No staged changes to commit.');
         } else {
           throw err;
         }
       }
     } else {
-      console.log('No local changes detected; skipping local git commit.');
+      emit('No local changes detected; skipping local git commit.');
     }
 
     try {
@@ -4739,25 +5434,46 @@ async function commitComponentsCommand(flags) {
     } catch (err) {
       runGit(cwd, 'git push --set-upstream origin ' + shellQuote(branchName));
     }
+    outcome.pushed = true;
+    outcome.pushedSha = safeGitValue(cwd, 'git rev-parse HEAD');
   } else {
-    console.log('Skipping local git phase. Prefer `remits-cli components sync` if you only need the server sync step.');
+    emit('Skipping local git phase. Prefer `remits-cli components sync` if you only need the server sync step.');
   }
 
-  console.log('Phase 3/4: server sync');
+  outcome.phase = 'sync';
+  emit('Phase 3/4: server sync');
   if (flagEnabled(flags.safe)) {
-    // Compile validation already ran before the push. The sync safety gates still run after the push
-    // because they need the server's remote-branch plan.
-    console.log('  --safe: compile validation ran before git push; the sync plan gate below runs before');
-    console.log('  the platform writes trunk rows or ComponentVariant overlays.');
+    if (skipGit) {
+      emit('  --safe: running the sync plan gate before the platform writes trunk rows or ComponentVariant overlays.');
+    } else {
+      // Compile validation already ran before the push. The sync safety gates still run after the push
+      // because they need the server's remote-branch plan.
+      emit('  --safe: compile validation ran before git push; the sync plan gate below runs before');
+      emit('  the platform writes trunk rows or ComponentVariant overlays.');
+    }
   }
-  const syncResponse = await syncComponentsCommand({
+  // In --json mode stdout carries ONE document — this command's outcome — so the sync's own document is
+  // routed to stderr rather than printed ahead of it.
+  const syncResponse = await withStdoutRoutedToStderr(jsonOutput, () => syncComponentsCommand({
     ...flags,
     branch: branchName,
     'account-id': accountId
-  });
+  }));
+  outcome.sync = syncResponse && flagEnabled(flags.summary) ? buildSyncSummary(syncResponse) : (syncResponse || null);
+  // Stop here when the sync did not succeed. In --json mode a refused sync gate RETURNS (with a non-zero
+  // exit code) instead of throwing, and this used to fall straight through into the pull phase.
+  if (!syncResponse || syncResponse.success === false) {
+    const reasons = syncResponse && Array.isArray(syncResponse.gateViolations) && syncResponse.gateViolations.length
+      ? ': ' + syncResponse.gateViolations.join('; ')
+      : '';
+    throw new Error(((syncResponse && syncResponse.message) || 'components sync did not succeed') + reasons);
+  }
+  outcome.synced = true;
+  outcome.postSyncSha = (syncResponse.sync && syncResponse.sync.postSyncSha) || null;
 
   if (!skipGit) {
-    console.log('Phase 4/4: local fast-forward pull');
+    outcome.phase = 'pull';
+    emit('Phase 4/4: local fast-forward pull');
     runGit(cwd, 'git fetch origin ' + shellQuote(branchName));
     const expectedSha = syncResponse && syncResponse.sync && syncResponse.sync.postSyncSha;
     if (expectedSha) {
@@ -4767,7 +5483,7 @@ async function commitComponentsCommand(flags) {
           'Remote branch head changed after sync. Expected ' + expectedSha + ' from remits sync, but origin/' + branchName + ' is ' + fetchedSha + '. Stop and investigate before pulling.'
         );
       }
-      console.log('Verified remote branch head:', expectedSha);
+      emit('Verified remote branch head:', expectedSha);
     }
     runGit(cwd, 'git pull --ff-only origin ' + shellQuote(branchName));
     if (expectedSha) {
@@ -4777,9 +5493,23 @@ async function commitComponentsCommand(flags) {
           'Local HEAD does not match remits sync SHA after pull. Expected ' + expectedSha + ', got ' + localSha + '.'
         );
       }
-      console.log('Verified local HEAD matches remits sync SHA:', expectedSha);
+      emit('Verified local HEAD matches remits sync SHA:', expectedSha);
     }
+    outcome.pulled = true;
   }
+  outcome.phase = 'complete';
+  outcome.success = true;
+  if (jsonOutput) console.log(JSON.stringify(outcome, null, 2));
+  return outcome;
+  } catch (err) {
+    outcome.error = err && err.message ? err.message : String(err);
+    outcome.nextStep = commitRecoveryHint(outcome);
+    if (jsonOutput) {
+      console.log(JSON.stringify(outcome, null, 2));
+      process.exitCode = 1;
+      return outcome;
+    }
+    throw new Error(outcome.error + (outcome.nextStep ? '\n' + outcome.nextStep : ''));
   } finally {
     // Give the branch back so the next agent lands in seconds rather than waiting out the TTL. Nothing
     // depends on this happening — the lease expires on its own, which is what covers the run that is
@@ -4788,6 +5518,161 @@ async function commitComponentsCommand(flags) {
   }
 }
 
+// What to do next, given how far a `components commit` got. The phase is the whole answer: a failure
+// before the push leaves the remote and the platform untouched; a failure AT the sync leaves them
+// disagreeing, which is the state the next agent must be told about in so many words.
+function commitRecoveryHint(outcome) {
+  const o = outcome || {};
+  const branch = o.branchName || '<branch>';
+  const abbrev = (sha) => (sha ? String(sha).slice(0, 12) : null);
+  switch (o.phase) {
+    case 'stage':
+      return 'Nothing was committed, pushed or synced. Fix the stage/compile error above and re-run.';
+    case 'git':
+      return o.gitCommitted
+        ? 'A local commit was created but NOT pushed; the remote and the platform are unchanged. Resolve the push ' +
+          '(usually `git pull --rebase origin ' + branch + '`), then re-run.'
+        : 'Nothing was pushed or synced.';
+    case 'sync':
+      return o.pushed
+        ? 'PUSHED BUT NOT SYNCED: ' + (abbrev(o.pushedSha) || 'the push') + ' is on origin/' + branch +
+          ' but the platform has not reconciled it, so the remote and the platform now differ, and the next sync of ' +
+          'this branch by anyone will land it. Fix the cause above, then run `remits-cli components sync` ' +
+          '(with --safe on a variant branch). Do not re-run `components commit`.'
+        : 'Nothing was synced.';
+    case 'pull':
+      return 'The platform synced ' + (abbrev(o.postSyncSha) || 'the branch') + ', but this checkout was not ' +
+        'fast-forwarded. Run `git fetch origin && git pull --ff-only origin ' + branch + '` before any further git work.';
+    default:
+      return null;
+  }
+}
+
+// Every commit on trunk must be acknowledged with --yes, BEFORE any git write. Trunk has no dry-run plan,
+// so neither `--safe` nor anything else can preview what the authoritative reconcile will create, rename or
+// delete; the only honest gate is an explicit acknowledgement. It used to fire only under `--safe`, which
+// left the most dangerous command in the CLI ungated by default. `--skip-git` is included: it is the same
+// planless reconcile without the push.
+async function refuseUnsafeTrunkCommitBeforeGit(flags, accountId, branchName, skipGit) {
+  const cwd = process.cwd();
+  // Before ANY git write: is this branch also checked out in another worktree? See otherWorktreesOnBranch.
+  if (!skipGit && !flagEnabled(flags['allow-shared-branch'])) {
+    const others = otherWorktreesOnBranch(safeGitValue(cwd, 'git worktree list --porcelain'), branchName,
+      safeGitValue(cwd, 'git rev-parse --show-toplevel'));
+    if (others.length) {
+      const shared = sharedBranchMessage(branchName, others);
+      if (flagEnabled(flags.json)) {
+        console.log(JSON.stringify({
+          success: false,
+          mode: 'commit',
+          accountId,
+          branchName,
+          phase: 'pre-git',
+          gitWritten: false,
+          sharedBranchWorktrees: others,
+          gateViolations: [shared],
+          message: shared
+        }, null, 2));
+        process.exitCode = 1;
+        return true;
+      }
+      throw new Error(shared + ' No git commit or push was attempted.');
+    }
+  }
+  const { session } = resolveSessionContext(cwd, flags);
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const dataMode = resolveDataMode(flags, session);
+  const workspace = resolveWorkspace(cwd, flags);
+  const api = buildAxios(baseUrl, session.token, 20000);
+  const statusResponse = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    workspace,
+    dataMode,
+    mode: 'status'
+  }).then((r) => r.data);
+  const branchContext = statusResponse && statusResponse.branchContext;
+  // Before ANY git write: will the push reach the repository the platform syncs? Refused only on a definite
+  // mismatch — no origin, or a platform that does not report its repository, is unknown and not refused.
+  // `--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', branchContext);
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({
+        success: false,
+        mode: 'commit',
+        dataMode,
+        accountId,
+        branchName,
+        workspace,
+        branchContext,
+        repositoryCheck: repoCheck,
+        phase: 'pre-git',
+        gitWritten: false,
+        gateViolations: [mismatch],
+        message: mismatch
+      }, null, 2));
+      process.exitCode = 1;
+      return true;
+    }
+    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)
+    });
+    const message = trunkCommitRequiresYesMessage();
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({
+        success: false,
+        mode: 'commit',
+        dataMode,
+        accountId,
+        branchName,
+        workspace,
+        safe: flagEnabled(flags.safe),
+        skipGit: !!skipGit,
+        branchContext,
+        phase: 'pre-git',
+        gitWritten: false,
+        gates: { safeRequiresYes: false },
+        gateViolations: [message],
+        message
+      }, null, 2));
+      process.exitCode = 1;
+      return true;
+    }
+    throw new Error(message + ' No git commit or push was attempted.');
+  }
+  return false;
+}
+
 /**
  * Take the exclusive right to land this branch, or stop with the sentence saying who has it.
  *
@@ -4812,7 +5697,8 @@ async function acquireLandingLease(flags, accountId, branchName) {
     const response = await buildAxios(baseUrl, session.token, 20000)
       .post('/cli/components', payload).then((r) => r.data);
     if (response && response.success) {
-      console.log('Landing lease: held on ' + branchName + ' (' +
+      const emit = flagEnabled(flags.json) ? console.error : console.log;
+      emit('Landing lease: held on ' + branchName + ' (' +
         (response.ttlMinutes || '?') + 'm, renewed by the sync).');
       return { flags, accountId, branchName, baseUrl, session, held: true };
     }
@@ -4904,7 +5790,8 @@ async function waitForToolStatus(api, cwd, options) {
   }
 }
 
-function watchWebsocket(baseUrl, topicId, taskId) {
+function watchWebsocket(baseUrl, topicId, taskId, options = {}) {
+  const emit = options.stderr ? console.error : console.log;
   const client = new Client({
     brokerURL: webSocketUrl(baseUrl),
     reconnectDelay: 3000,
@@ -4923,7 +5810,7 @@ function watchWebsocket(baseUrl, topicId, taskId) {
             return;
           }
           if (payload.tests || payload.name || payload.total != null) {
-            console.log('[ws][TestSuite]', JSON.stringify(payload));
+            emit('[ws][TestSuite]', JSON.stringify(payload));
           }
         }
       } catch (err) {
@@ -4954,6 +5841,7 @@ async function testCommand(flags) {
     : DEFAULT_DATA_MODE;
   const dataModeSource = dataModeFlagSource(flags);
   const testRef = flags.test || flags['test-id'] || flags.name;
+  const jsonOutput = flagEnabled(flags.json);
 
   if (!testRef) {
     throw new Error('Missing --test <id-or-name>');
@@ -4988,12 +5876,14 @@ async function testCommand(flags) {
   // from the account's subscription edge, which is what production does.
   const variantBranch = flags['variant-branch'];
 
-  printProdDataBanner({
-    dataMode,
-    accountId: asAccountId || accountId,
-    baseUrl,
-    operation: 'test run ' + String(testRef),
-    mutating: true
+  withStdoutRoutedToStderr(jsonOutput, () => {
+    printProdDataBanner({
+      dataMode,
+      accountId: asAccountId || accountId,
+      baseUrl,
+      operation: 'test run ' + String(testRef),
+      mutating: true
+    });
   });
 
   const start = await loggedPost(api, cwd, '/cli/test', {
@@ -5014,20 +5904,22 @@ async function testCommand(flags) {
     throw new Error('Failed to start test run');
   }
 
-  printSessionResolutionWarning(sessionContext);
-  printResolvedBaseUrl(baseUrl);
-  printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
-  if (start.staging && Array.isArray(start.staging.accountLanes)) {
-    printAccountLanes({ accountLanes: start.staging.accountLanes, branchName, workspace });
-  }
-  console.log('Test run started:', start.taskId);
+  withStdoutRoutedToStderr(jsonOutput, () => {
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
+    if (start.staging && Array.isArray(start.staging.accountLanes)) {
+      printAccountLanes({ accountLanes: start.staging.accountLanes, branchName, workspace });
+    }
+    console.log('Test run started:', start.taskId);
+  });
   runtimeState.currentTestTaskId = start.taskId;
 
   let stopWs = null;
   if (flags.watch !== 'false') {
     const topic = session.websocketTopic || start.websocketTopic || (session.user && String(session.user.uuid || '').replace(/-/g, ''));
     if (topic) {
-      stopWs = watchWebsocket(baseUrl, topic, start.taskId);
+      stopWs = watchWebsocket(baseUrl, topic, start.taskId, { stderr: jsonOutput });
     }
   }
 
@@ -5039,7 +5931,11 @@ async function testCommand(flags) {
     runtimeState.currentTestTaskId = null;
   }
 
-  console.log('Final status:', JSON.stringify(status, null, 2));
+  if (jsonOutput) {
+    console.log(JSON.stringify(status, null, 2));
+  } else {
+    console.log('Final status:', JSON.stringify(status, null, 2));
+  }
 
   // A selector that matched no case is a mis-specified run, not a passing one. Say so in the terminal
   // and exit non-zero, or "0 passed, 0 failed" reads exactly like a suite where everything passed.
@@ -5085,9 +5981,13 @@ async function testCommand(flags) {
     limitations: unmatched.length ? ['One or more requested test case selectors matched no case.'] : [],
     rawRefs: { testStatusKey: start.taskId },
     status
-  });
+  }, { quiet: jsonOutput });
 }
 
+/*
+## Tokens, Tools, Verification, And Config
+*/
+
 async function tokenCommand(flags) {
   const subcommand = flags._ && flags._[1];
   if (subcommand === 'inspect' || subcommand === 'details' || subcommand === 'decode') {
@@ -5145,6 +6045,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,
@@ -5364,6 +6267,7 @@ async function toolCommand(flags) {
   const pollIntervalMs = parsePositiveInt(flags['poll-interval-ms'] || flags.pollIntervalMs, 1000);
   const waitTimeoutMs = flags['wait-timeout-ms'] || flags.waitTimeoutMs;
   const api = buildAxios(baseUrl, session.token, timeoutMs);
+  const jsonOutput = flagEnabled(flags.json);
 
   if (statusMode) {
     const requestedCallId = String(flags['call-id'] || flags.callId || '');
@@ -5388,18 +6292,12 @@ async function toolCommand(flags) {
       throw new Error(data.message || 'Tool status lookup failed');
     }
 
-    printSessionResolutionWarning(sessionContext);
-    printResolvedBaseUrl(baseUrl);
-    console.log('Tool call status:', data.status);
-    console.log('Call ID:', requestedCallId);
-    console.log('Data mode:', data.dataMode || dataMode);
-    if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
-    console.log('Session log:', sessionJsonlFile(cwd));
-    console.log('Tool response file:', statusResponse.responseFile);
+    data.responseFile = statusResponse.responseFile;
+    data.sessionLog = sessionJsonlFile(cwd);
     // A completed run can still carry a tool-level refusal — see toolResultFailed.
     const polledFailed = data.toolSuccess === false || toolResultFailed(data.result);
     if (polledFailed) {
-      console.log('Tool error:', data.toolMessage || toolResultMessage(data.result));
+      data.toolMessage = data.toolMessage || toolResultMessage(data.result);
     }
     if (data.status === 'failed' || polledFailed) process.exitCode = 1;
     await appendVerificationPacket(api, cwd, session, accountId, flags, {
@@ -5412,7 +6310,22 @@ async function toolCommand(flags) {
       rawRefs: { toolResponsePath: statusResponse.responseFile, callId: requestedCallId },
       tool: { callId: requestedCallId, status: data.status, name: stored && stored.name },
       result: data
-    });
+    }, { quiet: jsonOutput });
+    if (jsonOutput) {
+      console.log(JSON.stringify(data, null, 2));
+      return;
+    }
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    console.log('Tool call status:', data.status);
+    console.log('Call ID:', requestedCallId);
+    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);
+    if (polledFailed) {
+      console.log('Tool error:', data.toolMessage);
+    }
     return;
   }
 
@@ -5422,7 +6335,8 @@ async function toolCommand(flags) {
     baseUrl,
     operation: toolOperationLabel(toolName, input),
     mutating: isMutatingToolCall(toolName, input),
-    dryRun: looksLikeDryRun(input)
+    dryRun: looksLikeDryRun(input),
+    stderr: jsonOutput
   });
 
   const response = await loggedPost(api, cwd, '/cli/tool', {
@@ -5455,24 +6369,29 @@ async function toolCommand(flags) {
   // result so this still works against an older platform build.
   const toolFailed = data.toolSuccess === false || toolResultFailed(data.result);
   const toolFailureMessage = data.toolMessage || toolResultMessage(data.result);
+  data.responseFile = response.responseFile;
+  data.sessionLog = sessionJsonlFile(cwd);
+  if (toolFailureMessage && !data.toolMessage) data.toolMessage = toolFailureMessage;
 
-  printSessionResolutionWarning(sessionContext);
-  printResolvedBaseUrl(baseUrl);
-  console.log(asyncMode ? 'Tool call started.'
-    : (toolFailed ? 'Tool call FAILED — the tool ran and returned an error.' : 'Tool call succeeded.'));
-  if (toolFailed && toolFailureMessage) console.log('Tool error:', toolFailureMessage);
-  console.log('Call ID:', callId);
-  console.log('Data mode:', data.dataMode || dataMode);
-  if (data.variantBranch || variantBranch) console.log('Variant branch:', data.variantBranch || variantBranch);
-  if (data.status) console.log('Status:', data.status);
-  if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
-  // Make the resolved component version explicit so callers never assume staged vs DB.
-  if (data.componentSource) {
-    const sig = data.componentSignature ? ` (${data.componentSignature})` : '';
-    console.log('Component:', `${data.componentSource}${sig}`);
+  if (!jsonOutput) {
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    console.log(asyncMode ? 'Tool call started.'
+      : (toolFailed ? 'Tool call FAILED — the tool ran and returned an error.' : 'Tool call succeeded.'));
+    if (toolFailed && toolFailureMessage) console.log('Tool error:', toolFailureMessage);
+    console.log('Call ID:', callId);
+    console.log('Data mode:', data.dataMode || dataMode);
+    if (data.variantBranch || variantBranch) console.log('Variant branch:', data.variantBranch || variantBranch);
+    if (data.status) console.log('Status:', data.status);
+    if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
+    // Make the resolved component version explicit so callers never assume staged vs DB.
+    if (data.componentSource) {
+      const sig = data.componentSignature ? ` (${data.componentSignature})` : '';
+      console.log('Component:', `${data.componentSource}${sig}`);
+    }
+    console.log('Session log:', data.sessionLog);
+    console.log('Tool response file:', data.responseFile);
   }
-  console.log('Session log:', sessionJsonlFile(cwd));
-  console.log('Tool response file:', response.responseFile);
 
   // Non-zero exit so scripted/agent callers that check status notice the refusal too.
   if (toolFailed) process.exitCode = 1;
@@ -5489,11 +6408,16 @@ async function toolCommand(flags) {
       waitTimeoutMs
     });
 
-    console.log('Final status:', finalStatus.data.status);
-    console.log('Tool response file:', finalStatus.responseFile);
+    finalStatus.data.responseFile = finalStatus.responseFile;
+    finalStatus.data.sessionLog = sessionJsonlFile(cwd);
+    if (!jsonOutput) {
+      console.log('Final status:', finalStatus.data.status);
+      console.log('Tool response file:', finalStatus.responseFile);
+    }
     if (finalStatus.data.status !== 'completed') {
       process.exitCode = 1;
     }
+    if (jsonOutput) Object.assign(data, { finalStatus: finalStatus.data });
   }
 
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
@@ -5512,7 +6436,10 @@ async function toolCommand(flags) {
     rawRefs: { toolResponsePath: response.responseFile, callId },
     tool: { callId, name: String(toolName), async: asyncMode, status: data.status, toolSuccess: data.toolSuccess },
     result: data
-  });
+  }, { quiet: jsonOutput });
+  if (jsonOutput) {
+    console.log(JSON.stringify(data, null, 2));
+  }
 }
 
 async function verifyCommand(flags, subcommand) {
@@ -5591,9 +6518,10 @@ 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');
+      const verifiedWorld = verificationWorldFromStatus(statusResponse, branchName);
+      source.componentBranch = verifiedWorld.componentBranch;
+      source.sourceLayer = verifiedWorld.sourceLayer;
+      if (verifiedWorld.variantBranchSource) source.variantBranchSource = verifiedWorld.variantBranchSource;
       source.stagedOverlayHash = statusResponse.laneSummary ? sha256(stableStringify(statusResponse.laneSummary)) : null;
     }
 
@@ -5957,6 +6885,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)) {
@@ -8048,6 +8980,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
@@ -11102,6 +12038,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);
@@ -11269,7 +12209,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.');
@@ -11355,7 +12295,7 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'commit') {
-    console.log('Usage: remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+    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.');
@@ -11376,7 +12316,7 @@ function printComponentsHelp(subcommand) {
   console.log('  remits-cli components entries --lane-id ID [--base-url URL] [--account-id ID] [--json|--verbose]');
   console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
   console.log('  remits-cli components sync [--safe] [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
-  console.log('  remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+  console.log('  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('');
   console.log('  --force-tombstones applies only on non-trunk variant syncs, when a missing trunk');
   console.log('  component file is intentionally being recorded as a tombstone override.');
@@ -11396,7 +12336,7 @@ function printComponentsHelp(subcommand) {
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  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('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   console.log('Examples:');
@@ -11411,6 +12351,7 @@ 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('  --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.');
 }
 
@@ -11567,14 +12508,14 @@ async function main() {
     console.log('  remits-cli components entries --lane-id ID [--base-url URL] [--account-id ID] [--json|--verbose]');
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
     console.log('  remits-cli components sync [--safe] [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
-    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+    console.log('  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('  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> --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]');
+    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 token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
     console.log('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     console.log('');