@remits/remits-cli 0.1.103 → 0.1.106

package/README.md

@@ -33,7 +33,7 @@ remits-cli components sync
 remits-cli components sync --branch feature_branch --dry-run
 remits-cli components sync --branch feature_branch --dry-run --summary
 remits-cli components sync --branch feature_branch --force-tombstones
-remits-cli token --path page/my-embeddable
+remits-cli token --path page/my-embeddable    # returns tokenKey/embeddableUrl, plus embedTokenKey/embedSnippet for host embeds
 remits-cli token --path page/my-embeddable --variant-branch feature_branch
 remits-cli token inspect --token https://example.test/s/<tokenKey>/page/my-embeddable
 remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'

package/index.js

@@ -74,7 +74,7 @@ const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
 
 // Flags that are legitimately repeatable accumulate into an array instead of last-wins. Every other
 // flag keeps last-wins so existing callers are unaffected.
-const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved']);
+const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved', 'names']);
 
 function parseArgs(argv) {
   const out = { _: [] };
@@ -1386,7 +1386,15 @@ function collectComponents(cwd) {
       const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
 
       if (!byKey.has(key)) {
-        byKey.set(key, { type, id, name });
+        // `metadataAuthoritative` tells the server this payload was assembled from the repo, so the
+        // .meta.yml it carries is the COMPLETE metadata for the component. The server then removes
+        // staged metadata keys the sidecar no longer declares, instead of carrying them forever —
+        // without it, deleting a key from a sidecar and re-staging left the old value staged, so
+        // "restore the file and re-stage" did not restore the staged state.
+        //
+        // A partial stage (mcp_component_edit writing one field) deliberately does NOT set this and
+        // keeps the merge semantics it needs.
+        byKey.set(key, { type, id, name, metadataAuthoritative: true });
       }
       const component = byKey.get(key);
       const filePath = path.join(dir, fileName);
@@ -1564,6 +1572,42 @@ function changedComponentsFromWorkingTree(cwd) {
   });
 }
 
+/**
+ * Components touched by commits between `ref` and HEAD.
+ *
+ * `changedComponentsFromWorkingTree` reads `git status`, i.e. UNCOMMITTED edits only — which is empty
+ * at exactly the moment `--changed-only` is meant to run, because the documented flow is
+ * commit -> push -> sync (sync reads the pushed remote, so it cannot see uncommitted work at all).
+ * The gate was therefore unusable in the flow it exists to guard: it refused every plan with
+ * "plan touches N component(s) this working tree did not edit". `--changed-since <ref>` supplies the
+ * base so the same guard works after the commit.
+ */
+function changedComponentsSinceRef(cwd, ref) {
+  let output = '';
+  try {
+    output = execSync('git diff --name-only ' + JSON.stringify(ref) + '...HEAD -- components', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).toString();
+  } catch (_) {
+    return null;
+  }
+  const byKey = new Map();
+  for (const rawLine of output.split(/\r?\n/)) {
+    const filePath = rawLine.trim();
+    if (!filePath) continue;
+    const info = componentPathInfo(cwd, filePath);
+    if (!info) continue;
+    if (!byKey.has(info.key)) {
+      byKey.set(info.key, { type: info.type, id: info.id, name: info.name, fields: [], paths: [] });
+    }
+    const entry = byKey.get(info.key);
+    if (!entry.fields.includes(info.field)) entry.fields.push(info.field);
+    if (!entry.paths.includes(info.path)) entry.paths.push(info.path);
+  }
+  return Array.from(byKey.values());
+}
+
 function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
@@ -2301,7 +2345,7 @@ async function syncComponentsCommand(flags) {
       throw new Error(previewResponse.message || 'Server sync dry-run failed');
     }
 
-    preflightGate = evaluateSyncGates(previewResponse, flags, changedFromWorkingTree);
+    preflightGate = evaluateSyncGates(previewResponse, flags, changedFromWorkingTree, cwd);
 
     if (namesOnly) {
       printSessionResolutionWarning(sessionContext);
@@ -2324,7 +2368,7 @@ async function syncComponentsCommand(flags) {
   }
 
   const summary = buildSyncSummary(response);
-  const gate = preflightGate || evaluateSyncGates(response, flags, changedFromWorkingTree);
+  const gate = preflightGate || evaluateSyncGates(response, flags, changedFromWorkingTree, cwd);
   summary.gates = gate.checks;
 
   if (flagEnabled(flags.json)) {
@@ -2342,19 +2386,97 @@ async function syncComponentsCommand(flags) {
   }
   if (namesOnly) {
     printSyncNames(response);
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   if (flagEnabled(flags.summary)) {
     console.log('Components sync summary:', JSON.stringify(summary, null, 2));
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   console.log('Components sync:', JSON.stringify(response, null, 2));
+  printPromotionSignals(response);
   failOnSyncGate(gate);
   return response;
 }
 
+// A sync is a step in a longer loop, and the steps after it are the ones that get skipped — so print what
+// the server just observed about this branch's relationship to trunk, not only what it wrote.
+function printPromotionSignals(response) {
+  const sync = (response && response.sync) || {};
+
+  const cmp = sync.branchComparison;
+  if (cmp && cmp.comparable) {
+    console.log('');
+    console.log('Branch vs trunk "' + cmp.trunkBranch + '": ' + cmp.aheadBy + ' ahead, ' + cmp.behindBy +
+      ' behind  [phase ' + cmp.phase + ']');
+    if (cmp.phase === 'diverged') {
+      console.log('  This branch has not merged trunk in. Its overlays assert its OLD copy of everything');
+      console.log('  trunk has changed since, and its subscribers are running that copy right now.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    } else if (cmp.phase === 'awaiting-merge-back') {
+      console.log('  Every commit here is already in trunk and trunk has moved on — a promotion merge-back');
+      console.log('  is outstanding. Until it happens the subscribers stay pinned to the pre-promotion copy.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    }
+    if (cmp.deletionEvidence !== 'complete') {
+      console.log('  NOTE: deletion evidence is ' + cmp.deletionEvidence + ', so removals fall back to the');
+      console.log('  conservative ratio guard rather than git\'s own answer.');
+    }
+  } else if (cmp) {
+    console.log('');
+    console.log('Branch vs trunk: UNAVAILABLE' + (cmp.message ? ' (' + cmp.message + ')' : ''));
+  }
+
+  const promotion = sync.promotion;
+  if (promotion) {
+    (promotion.tags || []).forEach((t) => {
+      console.log('');
+      console.log('Tagged promotion: ' + t.tag + ' -> ' + short(t.sha) + ' (' + t.ref + ')');
+    });
+    // Older servers sent bare branch names; newer ones send {branch, overlayCount}. Normalize, because the
+    // count decides whether this is an alarm or a tidy-up and the difference must not be guessed.
+    const pending = (promotion.pendingMergeBack || []).map((entry) =>
+      (typeof entry === 'string' ? { branch: entry, overlayCount: -1 } : entry));
+    if (pending.length) {
+      const shadowing = pending.filter((p) => p.overlayCount > 0);
+      const unknown = pending.filter((p) => !(p.overlayCount >= 0));
+      console.log('');
+      if (shadowing.length) {
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + shadowing.length +
+          ' variant branch(es) still SHADOW it — their subscribers resolve the PRE-promotion code:');
+      } else if (unknown.length) {
+        // The overlay count could not be read, so say nothing about what is shadowed. "Nothing is
+        // shadowed" would be a claim, and an unverifiable one is the failure this whole change is about.
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + pending.length +
+          ' variant branch(es) are behind it and owe a merge-back:');
+      } else {
+        console.log('Merge-back outstanding on ' + pending.length + ' variant branch(es). Nothing is shadowed' +
+          ' (no overlays stored), but the branch is behind trunk until you merge it back:');
+      }
+      pending.forEach((p) => {
+        const detail = p.overlayCount > 0 ? '  (' + p.overlayCount + ' overlay(s) shadowing trunk)'
+          : p.overlayCount === 0 ? '  (0 overlays — converged, just behind)' : '';
+        console.log('  ' + p.branch + ':' + detail);
+        console.log('    git checkout ' + p.branch + ' && git merge ' + (sync.branchName || 'main') + ' && git push');
+        console.log('    remits-cli components sync --branch ' + p.branch);
+      });
+      console.log('  Verify with: remits-cli components promotion --branch <name>');
+    }
+  }
+
+  (sync.advisories || []).forEach((advisory) => {
+    console.log('');
+    console.log('ADVISORY [' + advisory.code + ']: ' + advisory.message);
+    (advisory.findings || []).slice(0, 15).forEach((f) => {
+      console.log('  ' + f.path + ':' + f.line + '  ' + f.call);
+    });
+    if (advisory.truncated) console.log('  ... (list truncated; re-run with --json for the rest)');
+  });
+}
+
 function syncPreflightRequested(flags) {
   return Boolean(
     flagEnabled(flags['names-only']) ||
@@ -2419,7 +2541,7 @@ function parseExpectedRemoved(flags) {
 }
 
 // Fail-closed gates. Each returns a violation string or null; the command exits non-zero if any fire.
-function evaluateSyncGates(response, flags, changedFromWorkingTree) {
+function evaluateSyncGates(response, flags, changedFromWorkingTree, cwd) {
   const entries = syncPlanEntries(response);
   const results = ((response && response.sync) || {}).syncResults || {};
   const removed = entries.filter((e) => e.bucket === 'removed');
@@ -2450,13 +2572,19 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree) {
   }
 
   if (flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) {
-    if (changedFromWorkingTree === null) {
+    const since = flags['changed-since'] || flags.changedSince;
+    const fromRef = since ? changedComponentsSinceRef(cwd, String(since)) : null;
+    if (since && fromRef === null) {
+      violations.push('--changed-since: could not diff against "' + since + '". Check the ref exists (git fetch first for a remote ref).');
+      checks.changedOnly = false;
+    } else if (changedFromWorkingTree === null && fromRef === null) {
       violations.push('--changed-only: this checkout is not a git working tree, so the changed set cannot be established.');
       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.
-      const allowedIds = new Set(changedFromWorkingTree.filter((c) => c.id != null).map((c) => c.type + ':' + c.id));
-      const allowedNames = new Set(changedFromWorkingTree.filter((c) => c.name).map((c) => c.type + ':' + String(c.name).toLowerCase()));
+      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 unexpected = entries.filter((entry) => {
         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;
@@ -2464,8 +2592,15 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree) {
       });
       checks.changedOnly = unexpected.length === 0;
       if (unexpected.length) {
-        violations.push('--changed-only: plan touches ' + unexpected.length + ' component(s) this working tree did not edit: ' +
-          unexpected.slice(0, 20).map(syncEntryToken).join(', ') + (unexpected.length > 20 ? ', ...' : ''));
+        // Name the most likely cause instead of only the symptom. An empty changed set with a non-empty
+        // plan is the ordinary post-commit state, not evidence that the plan is dangerous.
+        const hint = (!changedSet.length && !since)
+          ? '\n    The changed set is EMPTY: --changed-only reads UNCOMMITTED edits, and the documented flow ' +
+            'commits and pushes before syncing. Pass --changed-since <ref> (e.g. the commit you branched ' +
+            'from, or origin/main) so the gate can see committed work.'
+          : '';
+        violations.push('--changed-only: plan touches ' + unexpected.length + ' component(s) this checkout did not change: ' +
+          unexpected.slice(0, 20).map(syncEntryToken).join(', ') + (unexpected.length > 20 ? ', ...' : '') + hint);
       }
     }
   }
@@ -2482,9 +2617,71 @@ function failOnSyncGate(gate) {
 function buildSyncSummary(response) {
   const sync = (response && response.sync) || {};
   const results = sync.syncResults || {};
-  const removed = Array.isArray(results.removed) ? results.removed : [];
   const errors = Array.isArray(results.errors) ? results.errors : [];
   const skipped = Array.isArray(results.skipped) ? results.skipped : [];
+
+  // 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
+  // `overridden: 0, added: 0, removed: []` — which is what a sync that ran and found nothing to do
+  // prints, so the two were indistinguishable. That matters because the cache can hold a SHA whose
+  // overlays were since removed by another path: an ordinary re-sync then reports zeros forever and
+  // the operator has no reason to suspect the branch was never re-read. Report the skip as itself.
+  // `syncResults` absent is the fallback signal, so this still reads correctly against a server that
+  // predates the explicit `skipped` flag rather than silently falling back to the misleading zeros.
+  const shortCircuited = sync.skipped === true
+    || (sync.syncResults == null && !!sync.message && sync.dryRun !== true);
+  if (shortCircuited) {
+    return {
+      success: response && response.success === true,
+      accountId: response && response.accountId,
+      branchName: sync.branchName || (response && response.branchName),
+      mode: sync.mode || 'variant',
+      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: [
+        // 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.'
+      ]
+    };
+  }
+
+  // A TRUNK sync and a VARIANT sync report in different vocabularies, and this summary only ever spoke
+  // variant. So the single most consequential line of a promotion — "component X was CREATED on trunk as
+  // id N" — printed as `added: 0`, and the runbook's definition of done ("components created, with their
+  // new ids") could not be satisfied from the summary it tells you to read.
+  if ((sync.mode || 'trunk') === 'trunk') {
+    const created = Array.isArray(results.created) ? results.created : [];
+    const updated = Array.isArray(results.updated) ? results.updated : [];
+    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');
+    return {
+      success: response && response.success === true,
+      accountId: response && response.accountId,
+      branchName: sync.branchName || (response && response.branchName),
+      mode: 'trunk',
+      dryRun: false,
+      // 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,
+      deleted: deleted.map((e) => ({ type: e.type, name: e.name, id: e.id })),
+      skipped: skipped.length,
+      errors: errors.length,
+      errorDetails: errors.map((entry) => ({ type: entry.type, id: entry.id, error: entry.error })),
+      warnings: trunkWarnings
+    };
+  }
+
+  const removed = Array.isArray(results.removed) ? results.removed : [];
   const added = Array.isArray(results.added) ? results.added : [];
   const overridden = Array.isArray(results.overridden) ? results.overridden : [];
   const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
@@ -2573,6 +2770,8 @@ async function branchesComponentsCommand(flags) {
     // Optional branch-scoped custom host set on the same edge as the subscription.
     // `--domain none` clears it; omitting the flag leaves any existing host untouched.
     domainName: flags.domain || flags['domain-name'],
+    dryRun: flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun),
+    confirmPrimaryEdge: flagEnabled(flags['confirm-primary-edge']) || flagEnabled(flags.confirmPrimaryEdge),
     force: flagEnabled(flags.force)
   }).then((r) => r.data);
 
@@ -2606,9 +2805,13 @@ function printBranchesSummary(response) {
       console.log('  ' + b.branch +
         '  (overridden ' + b.overridden + ', added ' + b.added + ', removed ' + b.removed +
         ', subscribers ' + b.subscribers + ')' + drift);
+      // Name the commit these counts describe. Without it a three-day-old inventory reads exactly like a
+      // current one, which is how a promotion gets reviewed against the wrong tree.
+      console.log('      computed from ' + short(b.syncedSha) + (b.updated ? ' at ' + b.updated : ''));
     });
     console.log('');
-    console.log('Detail: remits-cli components branch <name>');
+    console.log('Detail:    remits-cli components branch <name>');
+    console.log('Promotion: remits-cli components promotion --branch <name>   # is that commit still the branch HEAD?');
     return;
   }
 
@@ -2666,6 +2869,12 @@ function printBranchesSummary(response) {
 
   if (response.mode === 'subscribe' || response.mode === 'unsubscribe' || response.mode === 'retire') {
     console.log(response.message);
+    if (response.requiresConfirmation) {
+      console.log('Confirmation required: re-run with --confirm-primary-edge if that structural edge should subscribe.');
+    }
+    if (response.edge) {
+      console.log('Edge: ' + response.edge.edgeType + ' -> parent ' + response.edge.parentAccountId);
+    }
     return;
   }
 
@@ -2679,6 +2888,167 @@ function printBranchesSummary(response) {
   });
 }
 
+// The promotion "lay of the land": where this branch sits relative to trunk, whether the platform's
+// stored overlays actually describe the branch's current HEAD, who is affected, and the ordered commands
+// for the next step. Every fact here was already obtainable one command at a time; the point is that a
+// promotion goes wrong by assembling a wrong picture out of individually true answers, so this assembles
+// the picture once, server-side, from the REMOTE (which is what the platform syncs from — not your
+// working tree).
+async function promotionComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolvePromotionSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token);
+
+  const positional = flags._ && flags._[2];
+  const branchName = flags.branch || positional || currentBranch(cwd);
+
+  const response = await loggedPost(api, cwd, '/cli/branches', {
+    token: session.token,
+    accountId,
+    mode: 'promotion',
+    branchName
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Promotion status failed');
+  }
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+  } else {
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    // Say this out loud: the command is named for the operation it reports on, and an agent that reads
+    // "promotion" as "promoted" would skip the git steps this output is telling it to run.
+    console.log('This REPORTS promotion readiness. It performs no git operation and writes nothing.');
+    if (Array.isArray(response.branches)) {
+      response.branches.forEach((entry) => printPromotionStatus(entry, response));
+    } else {
+      printPromotionStatus(response, response);
+    }
+  }
+
+  // Fail closed by default. This command exists to be the gate an agent runs BEFORE touching git, and a
+  // gate that always exits 0 is a suggestion. `--no-fail` is for a human who only wants to look.
+  const blockers = collectPromotionBlockers(response);
+  if (blockers.length && !flagEnabled(flags['no-fail'])) {
+    throw new Error('promotion is blocked (' + blockers.length + '):\n  ' +
+      blockers.map((b) => b.code + ': ' + b.message).join('\n  ') +
+      '\nRe-run with --no-fail to inspect without failing.');
+  }
+  return response;
+}
+
+// A promotion is normally driven from the BRANCH's checkout, and on a single-subscriber branch that
+// checkout's account-info.json describes the SUBSCRIBER — so the CLI resolves the subscriber's account id
+// and demands a session for it, which an owner-side agent has no reason to hold. Every other branch
+// command has the same shape and tells you to pass `--account-id <ownerId>`; this one should not need to
+// be told, because it is READ-ONLY and the server already resolves the branch owner itself.
+//
+// So: if there is no session for the local account, and the checkout names its component owner, retry as
+// the owner. Deliberately scoped to this command — `sync`/`commit` mutate, and there the account the CLI
+// acts as is a decision, not a detail.
+function resolvePromotionSessionContext(cwd, flags) {
+  try {
+    return resolveSessionContext(cwd, flags);
+  } catch (err) {
+    if (flags && flags['account-id']) throw err;
+    let ownerId = null;
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(cwd, 'account-info.json'), 'utf8'));
+      const resolution = (info && info.resolution) || {};
+      const localId = Number(accountIdFromAccountInfo(info));
+      const candidate = Number(resolution.componentOwnerAccountId);
+      if (Number.isFinite(candidate) && candidate > 0 && candidate !== localId) ownerId = candidate;
+    } catch (_) { /* not an account repo, or no owner recorded */ }
+    if (!ownerId) throw err;
+
+    const ownerContext = resolveSessionContext(cwd, Object.assign({}, flags, { 'account-id': ownerId }));
+    console.log('Note: no session for this checkout\'s account; reporting as its component OWNER, account ' +
+      ownerId + '. Branch overlays belong to the owner, so this is the account that can answer.');
+    return ownerContext;
+  }
+}
+
+function collectPromotionBlockers(response) {
+  if (Array.isArray(response.branches)) {
+    return response.branches.reduce((all, entry) => all.concat(entry.blockers || []), []);
+  }
+  return response.blockers || [];
+}
+
+function printPromotionStatus(entry, envelope) {
+  const git = entry.git || {};
+  const platform = entry.platform || {};
+  console.log('');
+  console.log('Branch:      ' + entry.branch + '   (trunk "' + (entry.trunkBranch || envelope.trunk) + '")');
+  console.log('Owner:       account ' + entry.ownerAccountId + (entry.ownerAccountName ? ' (' + entry.ownerAccountName + ')' : '') +
+    '   repo ' + (entry.repository || '?'));
+  console.log('Phase:       ' + String(entry.phase || 'unknown').toUpperCase());
+  if (entry.summary) console.log('             ' + entry.summary);
+
+  console.log('');
+  console.log('  git (remote):');
+  if (git.comparable) {
+    console.log('    ahead of trunk:  ' + git.aheadBy + ' commit(s)   [work not yet promoted]');
+    console.log('    behind trunk:    ' + git.behindBy + ' commit(s)   [trunk this branch has not merged in]');
+    console.log('    merge base:      ' + short(git.mergeBaseSha));
+    console.log('    branch HEAD:     ' + short(git.branchHeadSha));
+    console.log('    trunk HEAD:      ' + short(git.trunkHeadSha));
+    const deletions = git.deliberateDeletions || [];
+    console.log('    deliberate component deletions on this branch: ' + deletions.length +
+      (git.deletionEvidence === 'complete' ? '' : '   (evidence ' + git.deletionEvidence + ')'));
+    deletions.slice(0, 20).forEach((p) => console.log('      D ' + p));
+  } else {
+    console.log('    UNAVAILABLE' + (git.message ? ': ' + git.message : ''));
+  }
+
+  console.log('');
+  console.log('  platform (what subscribers resolve right now):');
+  console.log('    overridden ' + platform.overridden + ', branch-only ' + platform.added +
+    ', tombstoned ' + platform.removed + ', drifted ' + platform.drifted);
+  // Freshness is decided server-side (BranchPromotion.freshnessOf) because sparseness compares BOTH sides
+  // and there are two independent ways to go stale. Re-deriving that here from separate booleans would be
+  // a second copy of one rule.
+  const FRESHNESS_LABELS = {
+    'current': '   [current]',
+    'stale-branch-moved': '   [STALE — does not match the branch HEAD]',
+    'stale-trunk-moved': '   [STALE — matches the branch HEAD, but trunk has moved since]'
+  };
+  console.log('    overlays computed from: ' + short(platform.syncedSha) +
+    (FRESHNESS_LABELS[platform.freshness] || '   [unknown]'));
+  (platform.subscribers || []).forEach((s) => {
+    console.log('    subscriber: account ' + s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '') +
+      (s.domainName ? '  [host ' + s.domainName + ']' : ''));
+  });
+
+  const blockers = entry.blockers || [];
+  if (blockers.length) {
+    console.log('');
+    console.log('  BLOCKERS (' + blockers.length + '):');
+    blockers.forEach((b) => {
+      console.log('    * ' + b.code);
+      console.log('      ' + b.message);
+      console.log('      fix: ' + b.fix);
+    });
+  }
+
+  const steps = entry.nextSteps || [];
+  if (steps.length) {
+    console.log('');
+    console.log('  NEXT, IN ORDER:');
+    steps.forEach((s, i) => console.log('    ' + (i + 1) + '. ' + s));
+  }
+  console.log('');
+}
+
+function short(sha) {
+  return sha ? String(sha).slice(0, 8) : 'unknown';
+}
+
 async function commitComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2862,7 +3232,26 @@ async function testCommand(flags) {
     throw new Error('Missing --test <id-or-name>');
   }
 
-  const names = flags.names ? String(flags.names).split(',').map((s) => s.trim()).filter(Boolean) : [];
+  // Test case names are English prose, so COMMAS occur in them naturally. A comma-delimited selector
+  // therefore split a legitimate name in half, matched nothing, and (before the server learned to
+  // report unmatched selectors) reported a clean run of zero cases. `|` is the delimiter now; the
+  // comma still works when no `|` is present, so existing invocations keep behaving as before.
+  // `--names` may also be repeated, which needs no delimiter at all.
+  const rawNames = flags.names === undefined || flags.names === null
+    ? []
+    : (Array.isArray(flags.names) ? flags.names : [flags.names]);
+  const repeated = rawNames.length > 1;
+  const names = rawNames
+    .flatMap((value) => {
+      const text = String(value);
+      if (text.includes('|')) return text.split('|');
+      // Comma-splitting is the legacy behaviour, kept so existing invocations still work. It is applied
+      // ONLY to a single --names value: repeating the flag is already unambiguous, so splitting there
+      // would take a deliberate literal name back apart.
+      return repeated ? [text] : text.split(',');
+    })
+    .map((s) => s.trim())
+    .filter(Boolean);
 
   const api = buildAxios(baseUrl, session.token);
   // --as-account runs the Test AS a (descendant) subscriber account, so that account's relationship
@@ -2918,6 +3307,23 @@ async function testCommand(flags) {
   }
 
   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.
+  const unmatched = (status.result && status.result.unmatchedTestNames) || [];
+  if (unmatched.length) {
+    console.error('');
+    console.error('No test case matched: ' + unmatched.map((n) => '"' + n + '"').join(', '));
+    const declared = (status.result && status.result.declaredTestNames) || [];
+    if (declared.length) {
+      console.error('Cases declared by this suite:');
+      declared.forEach((n) => console.error('  - ' + n));
+    }
+    console.error('--names is delimited by "|" (a comma still works when no "|" is present), so a case');
+    console.error('name containing a comma must be passed with "|" or by repeating --names.');
+    process.exitCode = 1;
+  }
+
   if (status.status !== 'completed') {
     process.exitCode = 1;
   } else if (status.result && status.result.failed > 0) {
@@ -2945,13 +3351,18 @@ async function tokenCommand(flags) {
   // Embeddable resolves that account's branch variants rather than the owner's trunk.
   // --variant-branch explicitly probes a committed variant branch before any edge subscribes.
   const variantBranch = flags['variant-branch'];
+  // Send the path so the server can also mint the EMBEDDABLE-SCOPED token key. `tokenKey` opens a
+  // tokenized URL in a browser; `embedTokenKey` lets the `<script>` embed loader resolve the component
+  // from persisted token context because the loader request sends no path.
+  const requestedPath = flags.path || flags['embeddable-path'];
   const data = await loggedPost(api, cwd, '/cli/token', {
     token: session.token,
     accountId,
     asAccountId: flags['as-account'] || flags['as-account-id'],
     variantBranch,
     branchName,
-    dataMode
+    dataMode,
+    path: requestedPath
   }).then((r) => r.data);
 
   if (!data.success) {
@@ -2959,7 +3370,7 @@ async function tokenCommand(flags) {
   }
 
   const base = baseUrl.replace(/\/$/, '');
-  const embeddablePath = flags.path || flags['embeddable-path'];
+  const embeddablePath = requestedPath;
   let embeddableUrl = embeddablePath
     ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
     : null;
@@ -2980,6 +3391,26 @@ async function tokenCommand(flags) {
     embeddableUrl
   };
 
+  // What the token will RESOLVE AS. `accountId` says which account it executes as; on a hierarchy the
+  // decisive facts are which component branch applies, whose components those are, and which storage
+  // namespace the page reads — none of which are inferable from the id. Present only when the server
+  // could resolve it.
+  if (data.resolution) {
+    output.resolution = data.resolution;
+  }
+
+  // Present only when the path resolved to an Embeddable. `embedTokenKey` is what a host site pastes
+  // into the loader snippet; the render shape is echoed because it decides what that host receives.
+  if (data.embedTokenKey) {
+    output.embeddableId = data.embeddableId;
+    output.embeddableName = data.embeddableName;
+    output.injectionType = data.injectionType;
+    output.renderMode = data.renderMode;
+    output.headMode = data.headMode;
+    output.embedTokenKey = data.embedTokenKey;
+    output.embedSnippet = data.embedSnippet;
+  }
+
   printSessionResolutionWarning(sessionContext);
   console.log(JSON.stringify(output, null, 2));
 }
@@ -5634,6 +6065,23 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
 }
 
 function printComponentsHelp(subcommand) {
+  if (subcommand === 'promotion' || subcommand === 'promote') {
+    console.log('Usage: remits-cli components promotion [<branch>] [--branch NAME] [--json] [--no-fail]');
+    console.log('');
+    console.log('Reports where a variant branch sits in the promotion loop and what to do next. It performs');
+    console.log('no git operation and writes nothing. Run it from either checkout — it resolves the branch');
+    console.log('OWNER, and it reads the REMOTE, which is what the platform actually syncs from.');
+    console.log('');
+    console.log('Phases:');
+    console.log('  converged            branch == trunk. Nothing to promote.');
+    console.log('  ready                branch is ahead of trunk and current with it -> promote.');
+    console.log('  diverged             branch is behind trunk. Merge trunk IN before reading any plan.');
+    console.log('  awaiting-merge-back  trunk absorbed this branch and moved on. Steps 4-5 are owed, and');
+    console.log('                       until they run the subscribers resolve the PRE-promotion code.');
+    console.log('');
+    console.log('Exits non-zero when there are blockers, so it can gate a runbook. --no-fail just looks.');
+    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('');
@@ -5644,6 +6092,8 @@ function printComponentsHelp(subcommand) {
     console.log('');
     console.log('Agent safety gates (each exits non-zero instead of printing a wall of JSON):');
     console.log('  --changed-only            dry-run first; fail unless every planned write is a component this checkout changed');
+    console.log('  --changed-since <ref>     pair with --changed-only after committing: the changed set becomes');
+    console.log('                            the components touched between <ref> and HEAD, plus uncommitted edits');
     console.log('  --names-only              dry-run first; print only "type id name" lines and write nothing');
     console.log('  --fail-on-removed         dry-run first; fail if the plan removes/tombstones anything');
     console.log('  --fail-on-errors          dry-run first; fail if the server reported any per-component sync error');
@@ -5679,7 +6129,7 @@ function printComponentsHelp(subcommand) {
     console.log('components commit does not support --dry-run.');
     return;
   }
-  console.log('Usage: remits-cli components <stage|status|clear|sync|commit|branches|branch>');
+  console.log('Usage: remits-cli components <stage|status|clear|sync|commit|promotion|branches|branch>');
   console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
   console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-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]');
@@ -5698,13 +6148,13 @@ function printComponentsHelp(subcommand) {
   console.log('  remits-cli components branch <name> [--json]                       # overridden/added/removed + drift');
   console.log('  remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]');
   console.log('  remits-cli components branch <name> --subscribers [--json]');
-  console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]');
+  console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]');
   console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
   console.log('  remits-cli components branch <name> --retire [--force]');
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--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]');
   console.log('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   console.log('Examples:');
@@ -5712,7 +6162,8 @@ function printTestHelp() {
   console.log('  remits-cli test run --test "Merchant Statements" --names "managed account case"');
   console.log('');
   console.log('Notes:');
-  console.log('  --names is comma-delimited, so avoid commas in individual test case names.');
+  console.log('  --names is delimited by "|" (comma also works when no "|" is present), and may be repeated.');
+  console.log('    A selector that matches no case fails the run rather than reporting 0 passed / 0 failed.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
   console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
   console.log('       to force production/subscription semantics from a variant checkout.');
@@ -5742,7 +6193,8 @@ function printTokenHelp() {
   console.log('Usage: 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('');
-  console.log('Mints a branch-aware browser URL for embeddable verification.');
+  console.log('Mints a branch-aware tokenKey and browser URL for embeddable verification.');
+  console.log('When --path resolves to an Embeddable, output also includes embedTokenKey and embedSnippet for host-site embeds.');
   console.log('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
@@ -5806,15 +6258,17 @@ async function main() {
     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 [--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 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>      # make an account resolve this branch');
+    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 name1,name2] [--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]');
     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('');
+    console.log('  token output uses tokenKey for browser URLs and embedTokenKey/embedSnippet for host-site embeds.');
     console.log('  --as-account <ID> verifies AS a descendant subscriber account, so its relationship edge');
     console.log('  selects the component branch and the run resolves exactly what production will.');
     console.log('  --variant-branch <NAME> explicitly probes a committed variant branch (e.g. before any');
@@ -5880,6 +6334,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && (subcommand === 'promotion' || subcommand === 'promote')) {
+    await promotionComponentsCommand(args);
+    return;
+  }
+
   if (command === 'components' && (subcommand === 'branches' || subcommand === 'branch')) {
     await branchesComponentsCommand(args);
     return;

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -168,11 +168,10 @@ For access questions — "who can see this client account?", "why does this user
 
 **Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set by
 the `account(...)` / `user(...)` factories when the execution data lane is `test` (which is how
-`mcp_account_user_admin` creates); prod-data creates leave them false. Two limits worth knowing: a record
-built some other way (`new Account(...).save()` inside a component) is only flagged during an **automated
-Test** in the test lane, so `testAccount:false` on something you created in test mode means it is a real
-account; and updating an existing real account/user in test mode does not convert it into test data,
-though its Firestore extension-field writes still go to the test lane. `Object.testMode` /
+`mcp_account_user_admin` creates); direct inserts such as `new Account(...).save()` are also flagged by the
+domain `beforeInsert` hook in the test lane. Prod-data creates leave them false. Updating an existing real
+account/user in test mode does not convert it into test data, though its Firestore extension-field writes
+still go to the test lane. `Object.testMode` /
 `Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) identify lifecycle
 rows in the test data lane. Agent-facing surfaces expose these fields:
 
@@ -340,6 +339,14 @@ file is catastrophic.
 - Local branch is committed and pushed; sync will read the intended remote commit.
 - Local filenames and live inventory (`mcp_account_view`) **agree on id and name for every component**: no live
   component appears locally under a different id, and no expected component is missing a repo file.
+  > **Do not run this comparison against `account-info.json` alone — it will report false orphans.** That
+  > file omits `auxiliary: true` components by design, so every auxiliary component looks like a repo file
+  > with no DB row, i.e. exactly the "a trunk sync will CREATE a duplicate" signal this check exists to
+  > catch. It also omits README- and AGENT-purpose Prompts, which live at the repo root and as `.md`
+  > sidecars in `components/agents/` rather than in `components/prompts/`, so they look like DB rows with
+  > no repo file — the "will be DELETED" signal. Both are benign. Before treating a flagged component as
+  > drift, confirm against the live row: `mcp_component_view`, or
+  > `mcp_run_action controlAction:"describe"` for an Action. A component that answers is not an orphan.
 - You can state the expected create/update/delete set. **If any delete or renumber is unexpected, stop.**
 
 ### If something looks wrong — stop, don't paper over
@@ -896,7 +903,16 @@ Tests run on the platform against your staged snapshot. They stream results in r
 
 Important test-runner constraints:
 - `remits-cli test run` now defaults to `test` dataMode unless you explicitly pass `--data-mode prod`.
-- Do not put commas in individual `test("...")` names. The CLI `--names` filter is comma-delimited, so comma-bearing test names cannot be targeted cleanly as a single selected case.
+- **`--names` is delimited by `|`, and may be repeated.** A comma still splits a single `--names` value
+  (legacy behaviour), which is why a case name containing a comma used to be cut in half and match
+  nothing. Prefer `|` or repetition whenever a name might contain punctuation:
+  ```bash
+  remits-cli test run --test 13 --names "a case, with a comma|another case"
+  remits-cli test run --test 13 --names "a case, with a comma" --names "another case"
+  ```
+- **A selector that matches no case FAILS the run.** It used to report `0 passed, 0 failed`,
+  `completed`, and exit 0 — indistinguishable from a suite where everything passed. The run now names
+  the unmatched selectors and lists the cases the suite actually declared, and exits non-zero.
 
 If no relevant Test component exists yet, consider creating one. Test components live in `components/tests/` and follow the same component structure. They provide permanent regression protection — every test you write today saves debugging time tomorrow.
 
@@ -930,6 +946,25 @@ playwright-cli eval "() => document.querySelector('.total-amount').textContent"
 
 The `testMode` metadata confirms you're testing against staged changes, not production.
 
+**Two different token keys come back, for two different jobs.** When `--path` resolves to an
+Embeddable, the response carries an `embedTokenKey` and a paste-ready `embedSnippet` alongside the usual
+`tokenKey` / `embeddableUrl`:
+
+| Field | Use it for |
+|---|---|
+| `tokenKey` / `embeddableUrl` | Opening the page in a browser (Playwright, or clicking the link) |
+| `embedTokenKey` / `embedSnippet` | The `<script>` embed loader — verifying the page as a HOST SITE embeds it |
+
+They are not interchangeable. The loader's request carries **no path**, so it resolves the component
+purely from the embeddable-scoped token key's persisted context. The browser `tokenKey` names the account
+preview URL; `embedTokenKey` names the host-loader credential. The response also echoes `injectionType` /
+`renderMode` / `headMode`, which decide what a host actually receives
+(`guides/components/embeddable-components.md`).
+
+**This works for a `new_` component that has never been synced.** The embed token key carries the
+component NAME as well as its id, so a staged, id-less Embeddable is loader-addressable — you do not
+have to sync it, or borrow another component's id, just to verify a host embed.
+
 **Option C — Use investigation tools** (for backend/data changes):
 
 For changes to Readers, Actions, or Rules that process data rather than display UI, verify by examining the data they produce:
@@ -1179,6 +1214,12 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
   branch/user scope. This is the normal edit/test loop.
 - `remits-cli components status` shows which branch/variant world the checkout resolves, plus staged entries,
   staged fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
+- **A full `stage` makes the `.meta.yml` AUTHORITATIVE.** Staging layers a payload over what is already
+  staged, which is what lets `mcp_component_edit` write a single field without blanking the others. But a
+  `remits-cli components stage` sends the whole sidecar, so a key you DELETE from a sidecar is removed from
+  the staged entry rather than lingering — "restore the file and re-stage" restores the staged state, which
+  is the only mental model that is safe to have. Content fields still layer (they come from separate files),
+  so a partial stage is unaffected.
 - `remits-cli components clear` drops staged entries when you intentionally want to fall back to committed DB
   source. An empty staging scope is clean state, not a failure.
 - `remits-cli components sync` syncs the DB from the pushed git remote and then clears staged entries for the
@@ -1352,6 +1393,63 @@ remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> v
 remits-cli token --path embeddable/index/50                    # owner      -> trunk
 ```
 
+Each answer carries a **`resolution`** block for the account the token executes as — `role`,
+`componentBranch` and its owner, `resolvedDatabaseName`, `resolvedDomainName`, `scopeAccountId`, and a
+one-sentence `summary`. Read it before opening the URL: `accountId` alone does not say whether a branch
+overlay applies or which storage namespace the page will read, and those are exactly what
+`--as-account` is being used to change.
+
+Separate branch fields, because these questions answer differently and can disagree:
+
+| Field | Answers |
+|---|---|
+| `componentBranch` | what **this token** will resolve |
+| `componentBranchSource` | `probe` (an explicit `--variant-branch`), `subscription` (the account's edge), or `trunk` |
+| `subscribedComponentBranch` | what the **account graph** says, independent of this token |
+| `componentBranchAnchored` | whether **this resolution actually reached** that subscription |
+
+A single `componentBranch` field would have reported `trunk` under `--variant-branch X`, for a token that
+resolves `X`.
+
+**Subscribing to a branch and resolving through it are different facts.** An account subscribes on an
+edge; a *request* resolves through that edge only when something named the path (`--as-account`, the
+edge's own host, an explicit `--variant-branch`). An account with no `parentId` and several upward links
+resolves trunk by design — the resolver refuses to guess a path. So this is a normal, explainable state:
+
+```
+"componentBranch": null,              // this token resolves TRUNK
+"componentBranchSource": "trunk",
+"subscribedComponentBranch": "forked", // ...but the account does subscribe
+"componentBranchAnchored": false       // ...and nothing anchored this request to it
+```
+
+Reading `componentBranch` alone there tells you the account is on trunk, which is true — and leads you to
+conclude it has no branch, which is false. If several edges carry branches, none is picked for you:
+`subscribedComponentBranch` is `null` and `subscribedComponentBranches` lists them.
+
+Under a probe, `componentOwnerAccountId` is the **nearest account on the token's resolution path that owns
+variant rows for X** — not an edge lookup, which answers `null` for the ordinary case of a variant
+committed before anything subscribes to it. `null` means no account on that path owns rows for X, and what
+that implies depends on the account, so read `summary`:
+
+- **on trunk** — the page resolves what it would without the probe; the branch is not committed yet.
+- **resolving through a subscription** — the probe **suppresses** it. `variantBranch` outranks the
+  subscription before it is consulted, so the page resolves **trunk**, not the overlays that account
+  normally gets. Drop `--variant-branch` to see the subscription.
+- **subscribed but not anchored** — it was already resolving trunk before you probed. Dropping
+  `--variant-branch` will *not* by itself show you the branch; name the path as well.
+
+The page itself then states the same facts. Its hidden `remits-session-info` line — which appears in an
+accessibility snapshot with no script — carries `Account` (what it runs as), `Addressed Account` (what
+the URL/token named), `Data Lane`, `Component Branch`, `Variant Applied`, and `Scope Account`.
+
+**`Component Branch` is the branch SELECTED; `Variant Applied` is what actually overlaid.** They are two
+fields because a branch can be selected and overlay nothing: `--variant-branch missing_branch` reports
+`Component Branch: missing_branch` while the page renders trunk components. So read `Variant Applied` —
+the `ComponentVariant` row id this page's component resolved through, or `none` — when the question is
+"did my variant apply?". That is a far sharper signal than inspecting the rendered markup for a style you
+expected.
+
 If `components status` shows staged entries that you cannot safely clear, isolate verification in an
 unused staging namespace instead of deleting someone else's cache:
 
@@ -1383,10 +1481,41 @@ for you, and merging a branch promotes its **deletions** as hard deletes. Do not
 `remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
 60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
 
+### Where am I in the promotion loop?
+
+```bash
+remits-cli components promotion            # the branch you are standing on
+remits-cli components promotion --branch forked --json
+```
+
+**Run this before every promotion step and after every one.** It reports only — no git, no writes — and it
+reads the remote (which is what the platform syncs from, not your working tree). It works from either
+checkout, because it resolves the branch's owner itself. It exits non-zero while blockers remain, so treat
+that as "do not proceed".
+
+| Phase | Meaning | Next |
+|---|---|---|
+| `converged` | branch == trunk | nothing to do; this is also what a **finished** promotion looks like |
+| `ready` | ahead of trunk, current with it | promote |
+| `diverged` | behind trunk | `git merge <trunk>` into the branch, re-sync, re-read the plan |
+| `awaiting-merge-back` | fully contained in trunk, trunk has moved on | **steps 4–5 are owed** — merge trunk back and re-sync |
+
+Two things it tells you that nothing else does:
+
+- **Which commit the stored counts describe, on BOTH axes.** An overlay is stored only while a file
+  differs from trunk, so the stored set is a statement about a (branch, trunk) pair and either side moving
+  makes it stale: `[STALE — does not match the branch HEAD]` (the branch was pushed since) or
+  `[STALE — matches the branch HEAD, but trunk has moved since]`. The second is the easy one to miss —
+  measured live, a branch at its own synced HEAD reported 2 stored overlays against a real plan of 21.
+- **That a promotion is unfinished.** `awaiting-merge-back` is what a promotion that *looked* successful
+  leaves behind: trunk is correct and its tests pass, while the subscriber silently keeps resolving its
+  pre-promotion overlays — including for any fix made afterwards. **A trunk sync succeeding is step 2 of 5,
+  not completion.**
+
 ### Subscribing, unsubscribing, retiring
 
 ```bash
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]
 remits-cli components branch <name> --unsubscribe <accountId>
 remits-cli components branch <name> --retire [--force]
 ```
@@ -1406,6 +1535,11 @@ Branch administration commands act **as the account you are running from**, whic
   Without it the CLI picks the edge to the owner whose branch you are managing, then falls back to the
   account's primary edge — which may not be the one you intended. `--subscribers` prints
   `via primary|membership edge -> parent N` so you can confirm.
+- **Primary-edge subscriptions are structural.** If the selected edge is the account's `parentId` edge,
+  subscribing it makes that account and descendants resolve the branch by default even though `parentId`
+  still points at the same parent. The server refuses this write unless you pass
+  `--confirm-primary-edge`; run `--dry-run` first and prefer a membership edge for fork/pilot
+  subscriptions.
 - **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
   keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
   pass `--force`.
@@ -1438,7 +1572,13 @@ The analogous hazard is different, and you must still respect it:
 - **Deleting a file means "remove the component", not "stop overriding it."** To withdraw an override,
   make the file identical to trunk again — the sync then removes the variant row.
 - **Keep the branch rebased.** A branch physically carries every file, so anything trunk added *after* the
-  branch was cut looks like a deliberate deletion. A small stale gap tombstones silently.
+  branch was cut is absent from it. The sync now asks git which of those absences are real deletions
+  (comparing against the merge base) and refuses to tombstone the rest, reporting them as
+  `skipped: absent from the branch but never deleted on it`. Treat any such entry as "merge trunk in" —
+  if an older sync already stored one of those absences as a tombstone, a non-dry-run sync prunes it and a
+  dry run reports `wouldPrune: true`. The classification falls back to a conservative ratio guard when
+  GitHub's compare is unavailable or its file list comes back truncated, which the sync output says
+  explicitly.
 - **Use `components sync --dry-run` before risky variant syncs.** It reports `overridden`, `added`,
   `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
   staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
@@ -1494,6 +1634,15 @@ a confirm-gated override when the removal guard refuses. Preview there is the sa
 - A test/tool response reports `testComponentSource` as `staged` | `variant` | `db`, so you can see which
   layer the run resolved without reading logs.
 
+> **A populated staging cache makes a variant look broken.** Anything carrying a CLI `TestMode` — a
+> `remits-cli token` URL, `/s/<tokenKey>/...`, an `X-Auth-Token` request, a script-loader embed — resolves
+> the STAGED layer, which outranks the variant. So with components staged under the same branch/user, a
+> tokenized page reports `Component Branch: <branch>` but `Variant Applied: none` and renders trunk, while
+> an anonymous `?account_id=` request to the same page reports the variant. That is the documented
+> precedence (staged -> variant -> trunk) working correctly, and it reads exactly like "tokens break
+> variant resolution". **Run `remits-cli components clear --all` before verifying variant resolution
+> through any tokenized entry point**, or check `remits-cli components status` first.
+
 ## Production Support Workflow
 
 Switch to prod mode for investigations:
@@ -2681,16 +2830,16 @@ remits-cli data-mode [set test|prod]
 remits-cli components stage [--branch <name>] [--data-mode test|prod] [--json|--verbose]
 remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
-remits-cli components sync [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components sync [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
 remits-cli components commit [--message "msg"] [--data-mode test|prod] [--force-tombstones]
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
 remits-cli components branch <name> --subscribers [--json]
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]   # make an account resolve this branch
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
@@ -2700,7 +2849,8 @@ remits-cli tool status --call-id <callId> [--data-mode test|prod]
 
 For tests specifically:
 - If `--data-mode` is omitted, `remits-cli test run` uses `test`.
-- `--names` is comma-delimited, so keep individual test names comma-free.
+- `--names` is `|`-delimited (a comma still splits a single value) and may be repeated; an unmatched
+  selector fails the run instead of reporting zero cases as success.
 - `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch
   (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
   (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.
@@ -2718,10 +2868,16 @@ For tests specifically:
 - **Fail-closed sync gates.** On non-trunk variant branches these flags now force a server dry-run first,
   evaluate that plan before any overlay row is written, and only then run the mutating sync when the plan
   passes. On trunk, there is no safe dry-run plan, so do not treat these as scoped commit controls:
-  - `--changed-only` — fail unless every planned write is a component **this checkout actually edited**.
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**.
     This is the strongest guard against a sync that quietly rewrites components you never touched. It
     also fails when the checkout is not a git working tree, because "git could not answer" must never
     be read as "nothing changed".
+    > **Pair it with `--changed-since <ref>` after you have committed.** On its own `--changed-only`
+    > reads UNCOMMITTED edits, and the documented flow commits and pushes *before* syncing (sync reads
+    > the pushed remote, so it cannot see uncommitted work at all) — so the changed set is empty at
+    > exactly the moment the gate runs, and it refuses the whole plan. `--changed-since origin/main`
+    > (or the commit you branched from) makes the changed set the components your commits touched.
+    > The refusal message says this when it detects the empty-set case.
   - `--fail-on-removed` — fail if the plan removes or tombstones anything.
   - `--expected-removed <type:id>` — whitelist the removals you intend (repeatable, or comma-delimited,
     e.g. `--expected-removed action:5,reader:9`). It **implies** `--fail-on-removed`, so any removal you
@@ -2779,6 +2935,8 @@ For tests specifically:
 | A component vanished for one account after a variant-branch sync | Its file is missing from that branch, so the sync created a **tombstone** that hides it from subscribers. Restore the file on the branch and re-sync. Trunk is unaffected. |
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |
+| A sync summary reports `skipped: true` with `NO COMPONENTS WERE SYNCED` | The branch head matches the cached sync SHA, so the branch was never re-read — this is NOT an empty plan. It matters when something else changed the overlays at that same SHA: an ordinary re-sync then answers "nothing to do" forever. `--dry-run` always re-reads the branch and shows the real plan; `--force-tombstones` re-reads and applies it. |
+| A branch sync stores overlays for components you never edited on the branch | **Trunk moved.** Sparseness compares the branch against CURRENT trunk, so editing a component on trunk without merging trunk into the branch turns it into a branch overlay on the next branch sync. The branch did not change. Merge trunk in, push, re-sync — the overlays prune. Check `components promotion` for the phase. |
 | After promoting a `new_*` component to trunk, the branch still shows it as `added` | You have not re-synced the branch since the trunk sync. Merge trunk into the branch and `components sync`: the file adopts the promoted id and, if unchanged, removes its own overlay. If the branch carries BOTH `new_Foo.*` and `<id>_Foo.*`, the id file wins and the `new_` one is reported `skipped: superseded` - delete it. |
 | After promoting a standalone Prompt, the branch still shows `OVERRIDDEN prompt:<id>` with only `purpose` changed | The trunk Prompt row does not match repo metadata. Ensure the Prompt sidecar has `description` and `purpose: CUSTOM`, run a platform build that imports Prompt `purpose`, re-sync trunk, merge back, and re-sync the branch. |
 | A branch preview reports a `removed` component nobody deleted | Check whether that component has a file on **trunk**. A DB row with no trunk file is missing from every branch, so it reads as a removal everywhere (and the trunk sync tries to hard-delete it each run). Repair trunk, not the branch. |