@remits/remits-cli 0.1.90 → 0.1.91

package/README.md

@@ -30,6 +30,7 @@ git commit -m "sync passing changes"
 git push
 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 --variant-branch feature_branch
@@ -60,9 +61,9 @@ remits-cli install --skills --overwrite true
 - Schema `.meta.yml` sidecars can stage/sync the schema flags: `enableTrigger`, `enableFullText`, `enableRAG`, `enableRevisions`, `enableBigQuerySync`, `enableRules`, `anchor`, and `auxiliary`.
 - `components status` shows the branch/user staging entries that can shadow DB components during CLI-scoped test-mode execution.
 - `components clear` clears staged entries. Scope it with `--component-type` and/or `--component-id`. Component ids are type-local, so an id alone clears that one component when the id is staged in only one family; if the same id is staged across multiple families it returns an ambiguity error asking you to add `--component-type`. With no filter it clears every staged entry for the current branch; pass `--all` to force the full-branch wipe explicitly.
-- `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
+- `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response. `components stage` separates local working-tree component deltas from the full materialized staging cache count.
 - `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
-- On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
+- On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. Add `--summary` to dry-run output when you only need counts, removals/tombstones, errors, skipped items, and warnings. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
 - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
 - `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
 - `components push` is deprecated and currently behaves the same as `components stage`.
@@ -79,6 +80,10 @@ remits-cli install --skills --overwrite true
 - Data mode defaults to `test`. For `remits-cli test run`, that default is now enforced even if the most-recent authenticated session for the account is `prod`; a production test run therefore requires an explicit `--data-mode prod` on the command line. Use `remits-cli data-mode set prod` only for production investigation.
 - If the same account is authenticated against more than one host and you omit `--base-url`, the CLI auto-resolves the best matching session and now prints the resolved host. Pass `--base-url` explicitly whenever the target host matters.
 - Avoid commas in individual test names. The `--names` filter is comma-delimited, so a single test case whose name contains commas cannot be targeted cleanly through `remits-cli test run --names ...`.
+- Nested help is available before required-argument validation, including `remits-cli test run --help`, `remits-cli components sync --help`, and `remits-cli tool --help`.
+- `components sync` has fail-closed safety gates for unattended/agent use. Each exits non-zero instead of printing a wall of JSON: `--changed-only` (fail unless every planned write is a component this checkout edited), `--names-only` (print only `BUCKET type:id name` lines), `--fail-on-removed`, `--fail-on-errors`, and `--expected-removed <type:id>` (repeatable or comma-delimited; implies `--fail-on-removed`, so any removal you did not name fails). `--changed-only` also fails closed when the checkout is not a git working tree, because "git could not answer" must never be read as "nothing changed".
+- Any command that can touch production prints a `PROD DATA` banner naming the operation, the resolved account, and the host, and distinguishes a live **write** from a live **read** (and from a dry run). This covers `tool`, `test run`, and `components sync`.
+- When a tool call fails inside the platform runtime rather than inside the tool — Groovy reflective dispatch of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout — the server returns `503` with `failureClass: "transient_infrastructure"` and `retryable: true`, and the CLI prints `TRANSIENT INFRASTRUCTURE FAILURE (retryable)`. A genuine tool error stays a `500` with `failureClass: "tool_error"`. Retry the first; do not retry the second.
 - Test activity is streamed from websocket `TestSuite` events while final status is also polled from `/cli/test`.
 - Tool execution writes the full response to a separate file so large payloads do not bloat the session log.
 - `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.

package/index.js

@@ -72,6 +72,10 @@ const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
   'tmp'
 ]);
 
+// 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']);
+
 function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -82,12 +86,18 @@ function parseArgs(argv) {
     }
     const key = arg.slice(2);
     const next = argv[i + 1];
+    let value;
     if (!next || next.startsWith('--')) {
-      out[key] = true;
+      value = true;
     } else {
-      out[key] = next;
+      value = next;
       i += 1;
     }
+    if (REPEATABLE_FLAGS.has(key) && Object.prototype.hasOwnProperty.call(out, key)) {
+      out[key] = (Array.isArray(out[key]) ? out[key] : [out[key]]).concat(value);
+    } else {
+      out[key] = value;
+    }
   }
   return out;
 }
@@ -268,6 +278,35 @@ function printResolvedBaseUrl(baseUrl) {
   console.log('Base URL:', normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL));
 }
 
+// Tools whose name signals they mutate state rather than only reading it. Used solely to escalate the
+// prod banner from "reading live data" to "WRITING live data" — never to block or permit anything.
+const MUTATING_TOOL_PATTERN = /(^|_)(patch|edit|create|commit|update|delete|remove|write|set|assign|run|execute|send|pause|unpause|interrupt|restore|repair|migrate|sync)(_|$)/i;
+
+function looksLikeDryRun(input) {
+  if (!input || typeof input !== 'object') return false;
+  const value = input.dryRun !== undefined ? input.dryRun : input.dry_run;
+  return value === true || value === 'true';
+}
+
+/**
+ * One consistent banner across every surface that can touch production. Agents have repeatedly run a
+ * prod write believing they were in test mode, so the banner is loud, states the account it resolved,
+ * and distinguishes a live WRITE from a live read.
+ */
+function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false }) {
+  if (String(dataMode || '').toLowerCase() !== 'prod') return;
+  const bar = '='.repeat(72);
+  const headline = dryRun
+    ? 'PROD DATA — DRY RUN (no write will be attempted)'
+    : (mutating ? 'PROD DATA WRITE — this runs against LIVE production data' : 'PROD DATA READ — this reads LIVE production 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(bar);
+}
+
 // A tool's OWN verdict, which is separate from whether the call was dispatched. Only an explicit
 // failure signal counts: tools legitimately return strings, arrays, and maps with no `success` key.
 // Used as a fallback when the platform build predates the envelope's `toolSuccess`.
@@ -1242,6 +1281,124 @@ function collectComponents(cwd) {
   return components;
 }
 
+function componentPathInfo(cwd, filePath) {
+  const mapping = {
+    schemas: 'schema',
+    readers: 'reader',
+    actions: 'action',
+    embeddables: 'embeddable',
+    i18n: 'i18n',
+    rules: 'rule',
+    templates: 'htmltemplate',
+    agents: 'utility',
+    tools: 'tool',
+    prompts: 'prompt',
+    tests: 'test'
+  };
+  const relative = String(filePath || '').replace(/\\/g, '/').replace(/^"|"$/g, '');
+  const parts = relative.split('/');
+  if (parts.length < 3 || parts[0] !== 'components') {
+    return null;
+  }
+  const type = mapping[parts[1]];
+  if (!type) {
+    return null;
+  }
+  const fileName = parts.slice(2).join('/');
+  if (fileName.includes('/')) {
+    return null;
+  }
+  const metaMatch = fileName.match(/^(.+?)_(.+)\.meta\.ya?ml$/i);
+  const match = metaMatch || fileName.match(/^(.+?)_(.+)\.([^.]+)$/);
+  if (!match) {
+    return null;
+  }
+  const prefix = match[1];
+  const rawName = match[2];
+  const ext = metaMatch ? 'meta' : match[3].toLowerCase();
+  const id = /^\d+$/.test(prefix) ? Number(prefix) : null;
+  const name = normalizeName(rawName);
+  const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
+  let field = ext;
+  if (ext === 'meta') field = 'metadata';
+  else if ((type === 'utility' || type === 'prompt') && ext === 'md') field = 'prompt';
+  else if (ext === 'groovy' || ext === 'md') field = 'source';
+  else if (type === 'embeddable' && ext === 'html') field = 'html';
+  else if (type === 'embeddable' && ext === 'js') field = 'javascript';
+  else if (type === 'htmltemplate' && ext === 'html') field = 'html';
+  else if (type === 'htmltemplate' && ext === 'json') field = 'previewData';
+  else if (type === 'tool' && ext === 'json') field = 'inputSchema';
+  else if (type === 'i18n' && ext === 'json') field = 'messages';
+  else if (type === 'schema' && ext === 'json') field = 'schema';
+
+  return { key, type, id, name, field, path: relative };
+}
+
+// Returns null (not []) when git cannot answer — e.g. this checkout is not a git repo. The caller
+// must not render "0 components edited" in that case, because it is a missing answer, not a zero.
+function changedComponentsFromWorkingTree(cwd) {
+  let porcelain = '';
+  try {
+    // NOT runGit(): it trims the whole output, which eats the leading space of porcelain's 2-char
+    // 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', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).toString();
+  } catch (_) {
+    return null;
+  }
+  if (!porcelain.trim()) {
+    return [];
+  }
+  const byKey = new Map();
+  for (const rawLine of porcelain.split(/\r?\n/)) {
+    // Status is exactly 2 columns, then a space, then the path. Match it rather than slicing, so a
+    // status whose first column is a space (unstaged change) parses identically to a staged one.
+    const parsed = /^(..) (.*)$/.exec(rawLine.replace(/\s+$/, ''));
+    if (!parsed) continue;
+    const status = parsed[1].trim() || parsed[1];
+    let filePath = parsed[2].trim();
+    // Renames render as "old -> new"; the new path is the one that exists on disk.
+    if (filePath.includes(' -> ')) {
+      filePath = filePath.split(' -> ').pop().trim();
+    }
+    // Quoted paths (non-ASCII / spaces) come back wrapped in double quotes.
+    if (filePath.startsWith('"') && filePath.endsWith('"')) {
+      filePath = filePath.slice(1, -1);
+    }
+    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: [],
+        statuses: [],
+        paths: []
+      });
+    }
+    const entry = byKey.get(info.key);
+    if (!entry.fields.includes(info.field)) entry.fields.push(info.field);
+    if (!entry.statuses.includes(status)) entry.statuses.push(status);
+    if (!entry.paths.includes(info.path)) entry.paths.push(info.path);
+  }
+  return Array.from(byKey.values()).map((entry) => ({
+    ...entry,
+    fields: entry.fields.sort(),
+    paths: entry.paths.sort()
+  })).sort((a, b) => {
+    const typeCmp = String(a.type).localeCompare(String(b.type));
+    if (typeCmp !== 0) return typeCmp;
+    return String(a.id || a.name || '').localeCompare(String(b.id || b.name || ''));
+  });
+}
+
 function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
@@ -1259,6 +1416,14 @@ function describeError(err) {
   const parts = [];
   if (err.response && err.response.data) {
     const responseData = err.response.data;
+    // The server distinguishes a failure in the RUNTIME (Groovy reflective dispatch, empty connection
+    // pool, Redis reconnect, lock-wait timeout) from a tool that ran and genuinely failed. Surface that
+    // verdict, or the caller cannot tell "retry this" from "this is broken".
+    if (responseData.failureClass === 'transient_infrastructure') {
+      parts.push('TRANSIENT INFRASTRUCTURE FAILURE (retryable)');
+      if (responseData.failureReason) parts.push('signal: ' + responseData.failureReason);
+      if (responseData.hint) parts.push(responseData.hint);
+    }
     if (responseData.message) {
       parts.push(String(responseData.message));
     } else if (typeof responseData === 'string') {
@@ -1679,6 +1844,7 @@ async function pushComponentsCommand(flags) {
   const requestedMode = String(flags.mode || 'stage').toLowerCase();
   const mode = requestedMode === 'push' ? 'stage' : requestedMode;
   const components = collectComponents(cwd);
+  const changedFromWorkingTree = changedComponentsFromWorkingTree(cwd);
 
   if (requestedMode === 'push') {
     console.log('Warning: `components push` is deprecated and currently behaves the same as `components stage`.');
@@ -1694,6 +1860,8 @@ async function pushComponentsCommand(flags) {
     replace: true,
     components
   }).then((r) => r.data);
+  response.changedFromWorkingTree = changedFromWorkingTree || [];
+  response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
 
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(response, null, 2));
@@ -1744,14 +1912,35 @@ function printComponentCommandResponse(label, response, flags) {
 }
 
 function printStageSummary(response, flags) {
-  console.log('Updated:', response.updated || 0);
-  console.log('Unchanged:', response.unchanged || 0);
+  // `stage` always uploads EVERY component in the repo, so the server's Updated/Unchanged counts
+  // describe the whole staging overlay, not what this checkout edited. That is what made "Updated: 75"
+  // read as "I changed 75 components". Lead with the working-tree delta, which is the number an agent
+  // is actually asking about, and label the server counts as the overlay they describe.
+  const changed = Array.isArray(response.changedFromWorkingTree) ? response.changedFromWorkingTree : [];
+  const tracked = response.changedFromWorkingTreeAvailable !== false;
+  if (tracked) {
+    console.log('Components edited in this working tree:', changed.length);
+    changed.slice(0, 20).forEach((entry) => {
+      const label = (entry.type || 'component') + ' ' + (entry.id || entry.name || '(unknown)');
+      const name = entry.name && entry.id ? ' ' + entry.name : '';
+      const fields = Array.isArray(entry.fields) && entry.fields.length ? ': ' + entry.fields.join(', ') : '';
+      console.log('  ' + label + name + fields);
+    });
+    if (changed.length > 20) {
+      console.log('  ...' + (changed.length - 20) + ' more');
+    }
+    if (!changed.length) {
+      console.log('  (no uncommitted component edits — already-committed edits are staged but not listed here)');
+    }
+  }
+  console.log('Staging overlay — newly written:', response.updated || 0);
+  console.log('Staging overlay — already current:', response.unchanged || 0);
   console.log('Skipped:', Array.isArray(response.skipped) ? response.skipped.length : 0);
   if (response.reconcile) {
     console.log('Reconciled stale keys:', response.reconcile.removedCount || 0);
   }
   if (response.staging) {
-    console.log('Remaining staged count:', response.staging.remainingCount || 0);
+    console.log('Total staged entries for this branch/user:', response.staging.remainingCount || 0);
   }
   printComponentCommandResponse('Components stage', response, flags);
 }
@@ -1901,6 +2090,15 @@ async function syncComponentsCommand(flags) {
   const dryRun = flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun);
   const api = buildAxios(baseUrl, session.token);
 
+  printProdDataBanner({
+    dataMode,
+    accountId,
+    baseUrl,
+    operation: 'components sync (branch ' + branchName + ')',
+    mutating: true,
+    dryRun
+  });
+
   const response = await loggedPost(api, cwd, '/cli/components', {
     token: session.token,
     accountId,
@@ -1916,8 +2114,13 @@ async function syncComponentsCommand(flags) {
     throw new Error(response.message || 'Server sync failed');
   }
 
+  const summary = buildSyncSummary(response);
+  const gate = evaluateSyncGates(response, flags, changedComponentsFromWorkingTree(cwd));
+  summary.gates = gate.checks;
+
   if (flagEnabled(flags.json)) {
-    console.log(JSON.stringify(response, null, 2));
+    console.log(JSON.stringify(flagEnabled(flags.summary) ? summary : response, null, 2));
+    failOnSyncGate(gate);
     return response;
   }
 
@@ -1928,10 +2131,169 @@ async function syncComponentsCommand(flags) {
   if (response.sync && response.sync.dryRun) {
     console.log('Dry run: no variants were written and staging was not cleared.');
   }
+  if (flagEnabled(flags['names-only']) || flagEnabled(flags.namesOnly)) {
+    printSyncNames(response);
+    failOnSyncGate(gate);
+    return response;
+  }
+  if (flagEnabled(flags.summary)) {
+    console.log('Components sync summary:', JSON.stringify(summary, null, 2));
+    failOnSyncGate(gate);
+    return response;
+  }
   console.log('Components sync:', JSON.stringify(response, null, 2));
+  failOnSyncGate(gate);
   return response;
 }
 
+// One "type:id" / "type:name" token per planned write, so an agent can eyeball or diff the plan
+// without paging through the full server response.
+function syncPlanEntries(response) {
+  const results = ((response && response.sync) || {}).syncResults || {};
+  const entries = [];
+  ['overridden', 'added', 'removed', 'errors'].forEach((bucket) => {
+    (Array.isArray(results[bucket]) ? results[bucket] : []).forEach((entry) => {
+      entries.push({
+        bucket,
+        type: String(entry.type || entry.kind || 'component').toLowerCase(),
+        id: entry.id == null ? null : String(entry.id),
+        name: entry.name || null
+      });
+    });
+  });
+  return entries;
+}
+
+function syncEntryToken(entry) {
+  return entry.type + ':' + (entry.id != null ? entry.id : (entry.name || '?'));
+}
+
+function printSyncNames(response) {
+  const entries = syncPlanEntries(response);
+  if (!entries.length) {
+    console.log('No planned component writes.');
+    return;
+  }
+  entries.forEach((entry) => {
+    console.log(entry.bucket.toUpperCase().padEnd(10), syncEntryToken(entry), entry.name || '');
+  });
+}
+
+function parseExpectedRemoved(flags) {
+  const raw = flags['expected-removed'] != null ? flags['expected-removed'] : flags.expectedRemoved;
+  if (raw == null) return null;
+  // A bare `--expected-removed` with no value means "I expect none" — fail closed on any removal.
+  const values = raw === true ? [] : (Array.isArray(raw) ? raw : [raw]);
+  const tokens = new Set();
+  values.forEach((value) => {
+    String(value).split(',').forEach((token) => {
+      const trimmed = token.trim().toLowerCase();
+      if (trimmed) tokens.add(trimmed);
+    });
+  });
+  return tokens;
+}
+
+// Fail-closed gates. Each returns a violation string or null; the command exits non-zero if any fire.
+function evaluateSyncGates(response, flags, changedFromWorkingTree) {
+  const entries = syncPlanEntries(response);
+  const results = ((response && response.sync) || {}).syncResults || {};
+  const removed = entries.filter((e) => e.bucket === 'removed');
+  const errors = Array.isArray(results.errors) ? results.errors : [];
+  const expectedRemoved = parseExpectedRemoved(flags);
+  const violations = [];
+  const checks = {};
+
+  if (flagEnabled(flags['fail-on-errors']) || flagEnabled(flags.failOnErrors)) {
+    checks.failOnErrors = errors.length === 0;
+    if (errors.length) {
+      violations.push('--fail-on-errors: server reported ' + errors.length + ' component sync error(s): ' +
+        errors.map((e) => (e.type || 'component') + ':' + (e.id != null ? e.id : e.name)).join(', '));
+    }
+  }
+
+  // --expected-removed implies --fail-on-removed: you named the removals you accept, so any other
+  // removal is by definition unexpected.
+  const failOnRemoved = flagEnabled(flags['fail-on-removed']) || flagEnabled(flags.failOnRemoved) || expectedRemoved !== null;
+  if (failOnRemoved) {
+    const unexpected = removed.filter((entry) => !expectedRemoved || !expectedRemoved.has(syncEntryToken(entry)));
+    checks.failOnRemoved = unexpected.length === 0;
+    if (unexpected.length) {
+      violations.push((expectedRemoved ? '--expected-removed' : '--fail-on-removed') +
+        ': plan removes/tombstones ' + unexpected.length + ' unlisted component(s): ' +
+        unexpected.map(syncEntryToken).join(', '));
+    }
+  }
+
+  if (flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) {
+    if (changedFromWorkingTree === null) {
+      violations.push('--changed-only: this checkout is not a git working tree, so the changed set cannot be established.');
+      checks.changedOnly = false;
+    } else {
+      // 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 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;
+        return true;
+      });
+      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 ? ', ...' : ''));
+      }
+    }
+  }
+
+  return { violations, checks };
+}
+
+function failOnSyncGate(gate) {
+  if (gate && gate.violations && gate.violations.length) {
+    throw new Error('components sync safety gate failed:\n  ' + gate.violations.join('\n  '));
+  }
+}
+
+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 : [];
+  const added = Array.isArray(results.added) ? results.added : [];
+  const overridden = Array.isArray(results.overridden) ? results.overridden : [];
+  const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
+  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');
+  return {
+    success: response && response.success === true,
+    accountId: response && response.accountId,
+    branchName: sync.branchName || (response && response.branchName),
+    mode: sync.mode || 'trunk',
+    dryRun: Boolean(sync.dryRun),
+    overridden: overridden.length,
+    added: added.length,
+    removed: removed.map((entry) => ({
+      type: entry.type,
+      kind: entry.kind,
+      name: entry.name,
+      id: entry.id,
+      variantId: entry.variantId
+    })),
+    unchanged: unchanged.length,
+    skipped: skipped.length,
+    errors: errors.length,
+    errorDetails: errors.map((entry) => ({
+      type: entry.type,
+      id: entry.id,
+      error: entry.error
+    })),
+    warnings
+  };
+}
+
 // 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.
@@ -2285,6 +2647,15 @@ async function testCommand(flags) {
   // --variant-branch explicitly probes a committed variant branch. Normally omitted: variants resolve
   // 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
+  });
+
   const start = await loggedPost(api, cwd, '/cli/test', {
     token: session.token,
     accountId,
@@ -2507,6 +2878,15 @@ async function toolCommand(flags) {
     return;
   }
 
+  printProdDataBanner({
+    dataMode,
+    accountId,
+    baseUrl,
+    operation: 'tool ' + String(toolName),
+    mutating: MUTATING_TOOL_PATTERN.test(String(toolName)),
+    dryRun: looksLikeDryRun(input)
+  });
+
   const response = await loggedPost(api, cwd, '/cli/tool', {
     token: session.token,
     accountId,
@@ -4965,6 +5345,113 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
   }
 }
 
+function printComponentsHelp(subcommand) {
+  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('');
+    console.log('On trunk this reconciles the pushed repository into live component rows.');
+    console.log('On a variant branch this writes ComponentVariant overlays only.');
+    console.log('--dry-run is only supported on variant branches and writes nothing.');
+    console.log('--summary prints compact counts, removals/tombstones, errors, skipped items, and warnings.');
+    console.log('');
+    console.log('Agent safety gates (each exits non-zero instead of printing a wall of JSON):');
+    console.log('  --changed-only            fail unless every planned write is a component this checkout changed');
+    console.log('  --names-only              print only "type id name" lines for the planned writes');
+    console.log('  --fail-on-removed         fail if the plan removes/tombstones anything');
+    console.log('  --fail-on-errors          fail if the server reported any per-component sync error');
+    console.log('  --expected-removed t:id   whitelist an intended removal; repeatable/comma-delimited.');
+    console.log('                            Implies --fail-on-removed, so any OTHER removal fails.');
+    return;
+  }
+  if (subcommand === 'stage' || subcommand === 'push') {
+    console.log('Usage: remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
+    console.log('');
+    console.log('Stages local component files into the Redis staging cache. It never writes the database or git.');
+    console.log('Terminal output separates local working-tree component deltas from the full materialized staging cache count.');
+    return;
+  }
+  if (subcommand === 'status') {
+    console.log('Usage: remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
+    console.log('');
+    console.log('Shows staged entries and whether this checkout resolves/writes trunk or a variant branch.');
+    return;
+  }
+  if (subcommand === 'clear') {
+    console.log('Usage: remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
+    console.log('');
+    console.log('Clears staged Redis entries without touching the database or git.');
+    console.log('Use --component-type with --component-id when the id could exist in multiple component families.');
+    console.log('Use --all for the temporary-experiment cleanup flow.');
+    return;
+  }
+  if (subcommand === 'commit') {
+    console.log('Usage: remits-cli components commit [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+    console.log('');
+    console.log('Runs local git add/commit/push, then server sync. Prefer explicit git + components sync when you need inspectable phases.');
+    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('  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]');
+  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('');
+  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.');
+  console.log('  --dry-run reports the variant override/add/remove plan without writing variants,');
+  console.log('  updating sync SHA cache, or clearing staged CLI entries.');
+  console.log('  --summary, --changed-only, --names-only, --fail-on-removed, --fail-on-errors, and');
+  console.log('  --expected-removed keep sync output small and fail closed. See `components sync --help`.');
+  console.log('');
+  console.log('Committed branch variants (durable overlays subscribing accounts resolve in production):');
+  console.log('  remits-cli components branches [--json]');
+  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> --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] [--names name1,name2] [--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:');
+  console.log('  remits-cli test run --test 11');
+  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('  --as-account changes the execution account so subscriber branch edges apply.');
+  console.log('  --data-mode prod intentionally targets live production data.');
+}
+
+function printToolHelp() {
+  console.log('Usage: remits-cli tool --name <toolName> [--base-url URL] [--account-id ID] [--branch BRANCH] [--input "{...}"|--input-file file.json] [--data-mode test|prod] [--variant-branch NAME|none] [--timeout-ms 60000] [--async true --wait true]');
+  console.log('       remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
+  console.log('');
+  console.log('Examples:');
+  console.log('  remits-cli tool --name mcp_firestore_search --input-file query.json --data-mode prod');
+  console.log('  remits-cli tool --name mcp_run_action --input \'{"accountId":49,"actionId":200,"executionMode":"async"}\' --data-mode prod');
+  console.log('');
+  console.log('For mcp_run_action and mcp_run_agent, prefer the tool\'s own executionMode:"async" and poll with that tool\'s controlAction:"status".');
+}
+
+function printToolsHelp() {
+  console.log('Usage: remits-cli tools [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--variant-branch NAME|none]');
+  console.log('');
+  console.log('Refreshes .remits-cli/tools/tools.json for the current account/branch/data-mode context.');
+}
+
+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('');
+  console.log('Mints a branch-aware browser URL for embeddable verification.');
+}
+
 async function main() {
   migrateSessionIfNeeded();
   const originalArgv = process.argv.slice(2);
@@ -5022,7 +5509,7 @@ async function main() {
     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]');
-    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run]');
+    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 branches [--json]                     # committed branch variants for this account');
     console.log('  remits-cli components branch <name> [--diff <componentId> --component-type <kind>] [--subscribers] [--json]');
@@ -5039,27 +5526,28 @@ async function main() {
     process.exit(0);
   }
 
-  if (command === 'components' && wantsHelp) {
-    console.log('Usage: remits-cli components <stage|status|clear|sync|commit|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]');
-    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run]');
-    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('');
-    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.');
-    console.log('  --dry-run reports the variant override/add/remove plan without writing variants,');
-    console.log('  updating sync SHA cache, or clearing staged CLI entries.');
-    console.log('');
-    console.log('Committed branch variants (durable overlays subscribing accounts resolve in production):');
-    console.log('  remits-cli components branches [--json]');
-    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> --unsubscribe <accountId>');
-    console.log('  remits-cli components branch <name> --retire [--force]');
+  if (wantsHelp && command === 'test') {
+    printTestHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'tool') {
+    printToolHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'tools') {
+    printToolsHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'token') {
+    printTokenHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'components') {
+    printComponentsHelp(subcommand);
     process.exit(0);
   }
 

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -7,121 +7,124 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 
 ## Table of Contents
 
-- Line 127: Account Targeting Model
-- Line 134: Account types
-- Line 149: How accounts connect (and why it changes what runs)
-- Line 179: Users are a separate model — don't reason about them as a tree
-- Line 192: Reading the shape
-- Line 218: Repo selection rules
-- Line 230: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
-- Line 236: How the platform reconciles the repo into the database (the mechanism you must understand)
-- Line 298: The surfaces and their intended behavior
-- Line 322: Intended workflows
-- Line 343: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
-- Line 356: If something looks wrong — stop, don't paper over
-- Line 380: Required Local Index Reads
-- Line 414: Big Picture: How remits-cli State Is Organized
-- Line 444: Support Ticket Mental Model
-- Line 480: Efficiency Rules
-- Line 492: Account Repository Index
-- Line 517: Two Workflows
-- Line 524: Test Mode vs Prod Mode
-- Line 556: Platform Mental Model: Front Stage vs Back Stage
-- Line 563: Documents vs Records
-- Line 573: HTTP Audits
-- Line 627: Record `content` / Context Mental Model
-- Line 647: Provenance Fields
-- Line 665: Why Persisted Context Looks Different From Runtime Context
-- Line 686: Investigation Rule for Record Context
-- Line 701: AI Request Response Records
-- Line 708: AI Session Groupings
-- Line 727: Correlation Keys
-- Line 733: Node Reference Table
-- Line 743: Repository vs External Context
-- Line 750: Getting Started
-- Line 752: Authentication
-- Line 765: Host vs Data Mode
-- Line 784: Tool Execution Lifecycle
-- Line 838: Data Mode
-- Line 848: Development Workflow
-- Line 850: The Golden Rule: Writing Code Is Not Finishing the Job
-- Line 862: Avoid Brittle Front-Stage Intelligence
-- Line 875: The Development Fast Loop
-- Line 879: Step 1: Understand the Request
-- Line 894: Step 2: Make the Change
-- Line 932: Step 3: Stage to Platform
-- Line 947: Step 4: Verify the Change
-- Line 1012: Step 5: Iterate If Needed
-- Line 1022: Step 6: Update Documentation
-- Line 1034: Step 7: Commit and Durable Sync
-- Line 1072: Step 8: Close the Ticket
-- Line 1087: User Confirmation Preferences
-- Line 1097: Component Resolution: Staging Cache vs DB (which "version" actually runs)
-- Line 1103: The three source layers + the compile cache
-- Line 1126: Staging cache key format
-- Line 1141: How the platform picks staged vs DB (the compile signature)
-- Line 1163: When staged overrides apply
-- Line 1187: Diagnosing which version is in play
-- Line 1208: Stage / commit / clear with the MCP tools
-- Line 1232: Stale after sync / commit (the in-memory compile cache)
-- Line 1242: Account Resolution: how a request travels the account graph
-- Line 1335: Branched Component Variants (per-account component overrides)
-- Line 1343: The model (three moving parts)
-- Line 1410: Which world does your working tree resolve? (read this before you run anything)
-- Line 1476: Two levers, two different questions
-- Line 1490: The SDLC is identical on a variant branch
-- Line 1515: Promotion: getting the branch back into trunk
-- Line 1557: Verifying as the subscriber
-- Line 1576: Agents (Utility) on a variant branch
-- Line 1588: Danger profile on a variant branch (different, not absent)
-- Line 1616: Inspecting branches and drift
-- Line 1648: Diagnosing a variant
-- Line 1655: Production Support Workflow
-- Line 1663: Investigation Strategy
-- Line 1693: Presenting Findings
-- Line 1701: Verifying a Production Issue Fix
-- Line 1714: Tool Reference
-- Line 1716: Execute a Tool
-- Line 1745: `mcp_account_view`
-- Line 1777: `mcp_account_user_admin`
-- Line 1812: `mcp_firestore_search`
-- Line 1850: `mcp_object_activity`
-- Line 1859: `mcp_record_listing`
-- Line 1884: `mcp_record_view`
-- Line 1897: `mcp_ai_session_search`
-- Line 1933: `mcp_run_action`
-- Line 1977: `mcp_run_agent`
-- Line 2013: `mcp_system_logs`
-- Line 2036: `mcp_component_view`
-- Line 2059: `mcp_component_grep`
-- Line 2072: `mcp_support_ticket`
-- Line 2121: `mcp_run_test`
-- Line 2130: `mcp_component_edit`
-- Line 2145: `mcp_component_create`
-- Line 2159: `mcp_component_commit`
-- Line 2167: `mcp_component_branches`
-- Line 2186: `mcp_cache`
-- Line 2198: `mcp_sql_query`
-- Line 2233: `mcp_index_search`
-- Line 2253: `mcp_get_guide`
-- Line 2265: `mcp_test_fixture`
-- Line 2278: `mcp_embeddable_test_url`
-- Line 2290: `mcp_playwright_replay`
-- Line 2305: `mcp_jvm_spike_triage`
-- Line 2318: `mcp_support_ticket_queue`
-- Line 2335: Multi-Session Support
-- Line 2355: Persistent Service, Control Center, and Agent Dispatch
-- Line 2364: Starting the Service
-- Line 2390: Control Center
-- Line 2405: Agent Dispatch
-- Line 2426: Configuring the Preferred Agent
-- Line 2437: Local State Files
-- Line 2485: Command Reference
-- Line 2527: Troubleshooting
-- Line 2569: When Something Doesn't Work as Expected
-- Line 2580: Back-Stage Escalation Workflow (platform defect/limitation)
-- Line 2589: Escalation Bundle (tooling/operational issue)
-
+- Line 130: Account Targeting Model
+- Line 137: Account types
+- Line 152: How accounts connect (and why it changes what runs)
+- Line 184: Users are a separate model — don't reason about them as a tree
+- Line 197: Reading the shape
+- Line 223: Repo selection rules
+- Line 235: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
+- Line 241: How the platform reconciles the repo into the database (the mechanism you must understand)
+- Line 303: The surfaces and their intended behavior
+- Line 327: Intended workflows
+- Line 348: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
+- Line 361: If something looks wrong — stop, don't paper over
+- Line 385: Required Local Index Reads
+- Line 419: Big Picture: How remits-cli State Is Organized
+- Line 449: Support Ticket Mental Model
+- Line 485: Efficiency Rules
+- Line 497: Account Repository Index
+- Line 522: Two Workflows
+- Line 529: Test Mode vs Prod Mode
+- Line 561: Platform Mental Model: Front Stage vs Back Stage
+- Line 568: Documents vs Records
+- Line 578: HTTP Audits
+- Line 632: Record `content` / Context Mental Model
+- Line 652: Provenance Fields
+- Line 670: Why Persisted Context Looks Different From Runtime Context
+- Line 691: Investigation Rule for Record Context
+- Line 706: AI Request Response Records
+- Line 713: AI Session Groupings
+- Line 732: Correlation Keys
+- Line 738: Node Reference Table
+- Line 748: Repository vs External Context
+- Line 755: Getting Started
+- Line 757: Authentication
+- Line 770: Host vs Data Mode
+- Line 789: Tool Execution Lifecycle
+- Line 843: Data Mode
+- Line 853: Development Workflow
+- Line 855: The Golden Rule: Writing Code Is Not Finishing the Job
+- Line 867: Avoid Brittle Front-Stage Intelligence
+- Line 880: The Development Fast Loop
+- Line 884: Step 1: Understand the Request
+- Line 899: Step 2: Make the Change
+- Line 938: Step 3: Stage to Platform
+- Line 953: Step 4: Verify the Change
+- Line 1018: Step 5: Iterate If Needed
+- Line 1028: Step 6: Update Documentation
+- Line 1040: Temporary Experiment Workflow
+- Line 1060: Step 7: Commit and Durable Sync
+- Line 1098: Step 8: Close the Ticket
+- Line 1113: User Confirmation Preferences
+- Line 1123: Component Resolution: Staging Cache vs DB (which "version" actually runs)
+- Line 1129: The three source layers + the compile cache
+- Line 1152: Staging cache key format
+- Line 1167: How the platform picks staged vs DB (the compile signature)
+- Line 1189: When staged overrides apply
+- Line 1213: Diagnosing which version is in play
+- Line 1234: Stage / commit / clear with the MCP tools
+- Line 1258: Stale after sync / commit (the in-memory compile cache)
+- Line 1268: Account Resolution: how a request travels the account graph
+- Line 1373: Branched Component Variants (per-account component overrides)
+- Line 1381: The model (three moving parts)
+- Line 1454: Which world does your working tree resolve? (read this before you run anything)
+- Line 1521: Two levers, two different questions
+- Line 1535: The SDLC is identical on a variant branch
+- Line 1560: Promotion: getting the branch back into trunk
+- Line 1602: Verifying as the subscriber
+- Line 1621: Agents (Utility) on a variant branch
+- Line 1633: Danger profile on a variant branch (different, not absent)
+- Line 1661: Inspecting branches and drift
+- Line 1693: Diagnosing a variant
+- Line 1700: Production Support Workflow
+- Line 1708: Investigation Strategy
+- Line 1770: Presenting Findings
+- Line 1778: Verifying a Production Issue Fix
+- Line 1791: Tool Reference
+- Line 1793: Execute a Tool
+- Line 1839: `mcp_account_view`
+- Line 1871: `mcp_account_user_admin`
+- Line 1965: `mcp_firestore_search`
+- Line 2004: `mcp_firestore_patch`
+- Line 2033: `mcp_object_activity`
+- Line 2042: `mcp_record_listing`
+- Line 2067: `mcp_record_view`
+- Line 2080: `mcp_ai_session_search`
+- Line 2116: `mcp_run_action`
+- Line 2169: `mcp_run_agent`
+- Line 2205: `mcp_system_logs`
+- Line 2228: `mcp_performance_trace`
+- Line 2263: `mcp_component_view`
+- Line 2286: `mcp_component_grep`
+- Line 2299: `mcp_support_ticket`
+- Line 2359: `mcp_run_test`
+- Line 2368: `mcp_component_edit`
+- Line 2383: `mcp_component_create`
+- Line 2397: `mcp_component_commit`
+- Line 2405: `mcp_component_branches`
+- Line 2424: `mcp_cache`
+- Line 2436: `mcp_sql_query`
+- Line 2471: `mcp_index_search`
+- Line 2491: `mcp_get_guide`
+- Line 2503: `mcp_test_fixture`
+- Line 2516: `mcp_embeddable_test_url`
+- Line 2528: `mcp_playwright_replay`
+- Line 2543: `mcp_jvm_spike_triage`
+- Line 2556: `mcp_support_ticket_queue`
+- Line 2573: Multi-Session Support
+- Line 2593: Persistent Service, Control Center, and Agent Dispatch
+- Line 2602: Starting the Service
+- Line 2628: Control Center
+- Line 2643: Agent Dispatch
+- Line 2664: Configuring the Preferred Agent
+- Line 2675: Local State Files
+- Line 2723: Command Reference
+- Line 2783: Prod banners and retryable failures
+- Line 2795: Troubleshooting
+- Line 2837: When Something Doesn't Work as Expected
+- Line 2848: Back-Stage Escalation Workflow (platform defect/limitation)
+- Line 2857: Escalation Bundle (tooling/operational issue)
 `remits-cli` is the brainstem for both **development** and **production support**. You might run it inside an account repository (where `account-info.json` and `/components` already exist) or from outside any repo when a user needs help on another account. Your users are business professionals — they think in terms of what they can see in a browser.
 
 ## Account Targeting Model
@@ -173,8 +176,10 @@ Two consequences that generate most "this account is weird" tickets:
    different component version, a different namespace, a different host. Establish which path a failing
    request travelled before comparing behavior. (Full detail in "Account Resolution: how a request travels
    the account graph".)
-2. **An account with no primary parent and several membership edges inherits nothing and runs trunk** until
-   a path is named — the platform refuses to guess between equally valid parents. That is by design.
+2. **An account with no primary parent and SEVERAL membership edges inherits nothing and runs trunk** until
+   a path is named — the platform refuses to guess between equally valid parents. That is by design. With
+   exactly ONE membership edge there is nothing to guess, so it (and everything below it) inherits normally
+   — a missing `parentId` is not itself a problem.
 
 ### Users are a separate model — don't reason about them as a tree
 
@@ -1032,6 +1037,26 @@ Before committing, update metadata so the next session understands what changed:
 describes the owning repo account. On a subscriber-initiated variant sync it describes the subscribing
 account reached through the branch edge, even though the component files still belong to the owner's repo.
 
+#### Temporary Experiment Workflow
+
+Use this when you need to prove a guard or assertion by temporarily making a local component fail. The staged
+Redis cache can affect later test/tool runs, so always clear it after restoring the file:
+
+```bash
+# make temporary local edit
+remits-cli components stage
+remits-cli test run --test <id-or-name> --names "<case name>"
+git restore <file>
+remits-cli components clear --all
+remits-cli components status
+```
+
+For narrower cleanup when only one staged component should be cleared:
+
+```bash
+remits-cli components clear --component-type Action --component-id 25
+```
+
 #### Step 7: Commit and Durable Sync
 
 Once verified and documented, create a normal git commit first:
@@ -1281,19 +1306,31 @@ with a branch.
 
 **The anchor is the branch of the graph you travelled.** At runtime it is `scope_account_id` (stamped
 onto the `Object`/`Event`/`Alert`/`ObjectLog` records a run creates, so async workers re-resolve on the
-same branch). A **null** anchor means "walk the primary `parentId` chain" — today's legacy behavior.
+same branch). A **null** anchor means "walk the structural chain" — see below.
 
-**Default-anchor derivation is deliberately conservative, and this is the #1 gotcha:**
+**How the chain is walked, and the #1 gotcha.** The walk follows `Account.parentId`, and at an account with
+**no** `parentId` it continues through that account's *single* active membership edge. Applied at every hop:
 
-| Account shape | Derived anchor |
+| Account shape at a hop | What the walk does |
 |---|---|
-| has a `parentId` | `null` → primary chain (legacy, unchanged) |
-| no `parentId`, **exactly one** membership edge | that edge's parent |
-| no `parentId`, **multiple** membership edges | `null` — **ambiguous, refuses to guess** |
+| has a `parentId` | follow it (legacy, unchanged) |
+| no `parentId`, **exactly one** membership edge | **continue through that edge** |
+| no `parentId`, **multiple** membership edges | **stop** — ambiguous, refuses to guess |
+| no `parentId`, no edges | stop — a true root |
 
-So a `parentId`-less account with two membership edges resolves **trunk and inherits nothing** until an
-anchor is supplied. That is correct-by-design, not a bug. Entry points that already know the branch
-disambiguate it by branch name; from the CLI you supply it explicitly.
+**Primary-vs-membership does not gate inheritance; only ambiguity does.** A `parentId`-less subscriber shell
+linked to its owner by one membership edge inherits that owner's components and branch — **and so does
+everything beneath it**. You do not need to give it a real `parentId`.
+
+But a `parentId`-less account with **two** membership edges resolves **trunk and inherits nothing** until an
+anchor is supplied. That is correct-by-design (the inheritance path must stay linear, or component
+name-dedupe would pick an arbitrary winner between two sibling products), not a bug. Entry points that
+already know the branch disambiguate it by branch name; from the CLI you supply it explicitly.
+
+> Before 2026-08 the continuation was applied **only to the account a lookup started from**, so a
+> membership-only account truncated the chain for all of its descendants — they inherited nothing and
+> resolved trunk while the subscriber itself looked fine. If you are reading an older investigation that
+> "fixed" this by reparenting a subscriber under its owner, that workaround is no longer needed.
 
 **Same account, two parents, two answers.** An account reached through Product A versus Product B can
 legitimately resolve a different component variant *and* a different data segment. When you investigate
@@ -1466,8 +1503,9 @@ Read the `resolution` block before acting from any checkout — it is the ONE pl
 - `resolution.componentBranch` / `resolution.scopeAccountId` — the branch and the path anchor that made this
   subscriber resolution possible.
 - `resolution.parents` / `resolution.children` / `resolution.relationships` — the account graph, stated once
-  and compactly. The full descendant tree is a lookup (`mcp_account_user_admin`, `mcp_account_view`), not a
-  committed artifact.
+  and compactly. For quick live hierarchy checks, prefer `mcp_account_user_admin` with `action:"account"` or
+  `action:"hierarchy"`; use `mcp_account_view` only when component inventory or detailed configuration is also
+  needed. The full descendant tree is a lookup, not a committed artifact.
 
 **One branch, one `account-info.json`.** There is exactly one git branch, so when a branch has MORE THAN ONE
 subscriber the refresh is skipped (the sync result says so under `accountInfo.skipped`/`reason`) and the file
@@ -1684,8 +1722,9 @@ Before starting an investigation outside the confirmed current repo:
 5. `mcp_record_listing` — search or filter alerts, events, object logs, or objects when you need to find the suspicious record first.
 6. `mcp_record_view` — drill into suspicious entries for full content.
 7. `mcp_ai_session_search` — if the workflow involves AI, inspect session groupings, prompts, tool definitions, and responses in human-readable form.
-8. `mcp_system_logs` — correlate via `threadGroupingId` for execution traces.
-9. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+8. `mcp_performance_trace` — for slow/sluggish reports, start with `action:"slowest"` when you only have a window, or `action:"trace"` when you have a `threadGroupingId`; this is the MCP wrapper for the Diagnostics page request-trace data.
+9. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
+10. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
 
 **Error or Alert Investigation:**
 1. `mcp_record_listing` — search by alert type, content, error text, action, status, `threadGroupingId`, or other exact-match record properties when you do not yet know the record ID.
@@ -1697,6 +1736,40 @@ Before starting an investigation outside the confirmed current repo:
 7. If the context looks missing, redacted, or truncated, consider sanitization rules before concluding data was never present.
 8. If AI behavior is part of the symptom, use `mcp_ai_session_search` and compare the persisted session content against the Agent component implementation and `docs/guides/features/ai-support.md`.
 
+**Stuck / failed / recovered Event:**
+
+Do **not** open the Action source first. The platform records each attempt's delivery envelope (which
+queue delivered it, which delivery attempt this was, which instance owned it, how long it was ever
+allowed to run) and will classify the failure for you. From a Test or any component:
+
+```groovy
+eventDiagnostics(18838)
+```
+
+Read `classification` before anything else:
+
+- `APPLICATION_FAILURE` — **the only one that means the bug is in the component.** Read `errorMessage`
+  and the correlated `alerts`, then investigate the component normally.
+- `ORPHANED_*` / `RECOVERED_*` — the attempt was abandoned. Read `abandonmentCause`:
+  - `REQUEST_TIMEOUT_LIKELY` — used its whole deadline (`timing.deadlineUsed` near `1.0`). The unit of
+    work is too big for one event; the fix is resumable batches, not component logic.
+  - `PROCESS_TERMINATED_LIKELY` — stopped well inside its deadline (`deadlineUsed` near `0`). The worker
+    was killed (memory pressure, restart). Not a logic bug.
+  - `UNKNOWN_NO_DEADLINE_EVIDENCE` — no deadline recorded, so the cause is genuinely unknown. Use
+    `logQuery`; do not assume. Events predating delivery-envelope capture always look like this.
+- `AWAITING_DELIVERY` — never claimed. A queue/delivery problem.
+- `IN_FLIGHT_HEALTHY` — still running with a fresh heartbeat. A long Action is not a stuck one; wait.
+
+`delivery.deliveryAttempt` above `1` means Cloud Tasks had **already** retried this event, so any
+non-idempotent side effect may have run more than once — check for duplicate records before concluding
+the component "ran twice for no reason".
+
+`delivery.threadGroupingId` is the same id everything else uses, so you can pivot straight into
+`mcp_performance_trace` (`action:"trace"`) or `mcp_system_logs` with it. `logQuery` in the response
+carries ready-made Cloud Logging filters, including the container-lifecycle and 504 queries.
+
+Full detail: `docs/guides/features/observability.md` §5b and `events-builder-guide.md`.
+
 ### Presenting Findings
 
 Users are not engineers. When reporting investigation results:
@@ -1867,11 +1940,19 @@ client accounts beneath it:
                            type:'CLIENT'                  # inherits the branch automatically
 ```
 
-> **Put the branch on the account's PRIMARY edge.** Component inheritance follows the *anchored* path, which
-> for an account with a `parentId` is its primary chain. An account that has both a primary edge and a
-> *membership* edge carrying the branch resolves **trunk** by default — the membership edge is never
-> anchored unless a request names it (`--as-account`, `--variant-branch`, or the edge's own host). Descendants
-> then inherit the branch down that primary chain automatically, which is what makes step 4 free.
+> **Put the branch on the edge that is UNAMBIGUOUSLY on the account's path up — primary or membership.**
+> Inheritance walks `parentId` and, at an account that has no `parentId`, continues through its *single*
+> active membership edge. So a subscriber shell with **no `parentId` and one membership edge** to its owner
+> is a fully supported shape: it resolves the branch, **and so do all of its descendants**. You do not need
+> to make the subscriber a structural child of its owner.
+>
+> What is NOT resolved by default is genuine **ambiguity** — an account with *several* upward links, where
+> the platform refuses to guess which product it was reached through. That account (and its descendants)
+> resolve trunk until a request names the path: `--as-account`, `--variant-branch`, or the edge's own host.
+> An account that has a `parentId` **and** a separate membership edge carrying the branch is this case: the
+> `parentId` wins, so put the branch on the link the account actually inherits through.
+>
+> Either way, descendants inherit the branch down the chain automatically, which is what makes step 4 free.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -1899,6 +1980,7 @@ Query Firestore documents.
 | `aggregation` | no | `{sum: [...], avg: [...], min: [...], max: [...], count: true}` |
 | `dateRanges` | no | `[{field, startDate, endDate}]` (yyyy-MM-dd) |
 | `textSearch` | no | `[{field, prefix}]` for prefix matching |
+| `fallbackOnMissingIndex` | no | When `true`, a sorted read that fails on a missing composite index retries without sort and returns `warning`, `missingIndexUrl`, and `sortApplied:false`. Use when an unsorted first page is still useful. |
 
 HTTP audit usage notes:
 
@@ -1922,6 +2004,35 @@ remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collec
   - `response.statusCode`
   - `success`
 
+### `mcp_firestore_patch`
+Guarded exact-document Firestore patch tool for bounded repairs. It defaults to `dryRun:true` and refuses broad
+updates, wildcard collections, delete/remove operations, protected identity fields, and `_lastModified*` audit
+fields.
+
+Use it when the desired repair is mechanical and smaller than rerunning an expensive Action, for example copying
+canonical fields into stale UI mirror fields. Always dry-run first and include preconditions:
+
+```bash
+remits-cli tool --name mcp_firestore_patch --data-mode prod --input '{
+  "accountId":743,
+  "collection":"statements",
+  "documentId":"20958",
+  "dryRun":true,
+  "preconditions":[
+    {"field":"interchangeOptimization.status","equals":"Calculated"},
+    {"field":"interchangeOptimizationChecked","equals":false}
+  ],
+  "patch":{
+    "interchangeOptimizationChecked":true,
+    "feeBreakdown.interchangeOptimization":{"$copyFrom":"interchangeOptimization"},
+    "feeBreakdown.interchange.optimization":{"$copyFrom":"interchangeOptimization"}
+  }
+}'
+```
+
+Response fields include `dataMode`, `accountId`, `collection`, `documentId`, `dryRun`, `patchedFields`, and
+`diff`. Switch to `"dryRun":false` only after the diff and preconditions are exactly what you intended.
+
 ### `mcp_object_activity`
 Object lifecycle timeline — metadata + recent activity.
 
@@ -2009,6 +2120,15 @@ Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summ
 Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
 staged-vs-DB provenance in the result.
 
+Describe the Action first when the input shape is not obvious. This does not execute the Action:
+
+```bash
+remits-cli tool --name mcp_run_action --input '{"controlAction":"describe","accountId":743,"actionId":25,"includeInputSchema":true}' --data-mode prod
+```
+
+The describe response reports `hasInputSchema`, optional `inputSchema`, `inferredInputKeys`, and component
+provenance. If `hasInputSchema:false`, treat `inferredInputKeys` as a best-effort static scan, not a contract.
+
 Use direct mode only for quick Actions:
 
 ```bash
@@ -2108,6 +2228,41 @@ Query Cloud Run service logs.
 {"node": "remitsAdmin-east5", "timeRange": "4h", "severity": "ERROR"}
 ```
 
+### `mcp_performance_trace`
+Read Remits request traces through the same `traces(...)` DSL that powers the admin Diagnostics "Request
+traces" panel. Use this before raw log spelunking for slow or sluggish requests because it returns profiled
+span rollups, component annotations, and retained slow-request summaries directly.
+
+Common flows:
+
+```bash
+# User only knows it was slow this afternoon
+remits-cli tool --name mcp_performance_trace --input '{"action":"slowest","lookbackHours":4,"accountId":52,"minMs":2000,"limit":10}' --data-mode prod
+
+# You have the Diagnostics/request/Object/Event/Alert threadGroupingId
+remits-cli tool --name mcp_performance_trace --input '{"action":"trace","traceId":"msf1y65n-001","lookbackHours":6,"format":"markdown"}' --data-mode prod
+
+# Same local-node data as the Diagnostics table
+remits-cli tool --name mcp_performance_trace --input '{"action":"snapshot","limit":100}' --data-mode prod
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | no | `snapshot`, `slowest`, or `trace`. Default: `snapshot`. |
+| `traceId` / `threadGroupingId` | for `trace` | Request/grouping id to open across local ring and Cloud Logging. |
+| `lookbackHours` | no | Cloud Logging window for `trace`/`slowest`. Defaults are 6 and 4 hours. |
+| `accountId` | no | Account filter for `slowest`. |
+| `kind` | no | Operation kind filter for `slowest`, e.g. `embeddable`, `action`, `reader`. |
+| `minMs` | no | Minimum duration for `slowest`. Default: 1500. |
+| `limit` | no | Result limit. |
+| `format` / `markdown` | no | Set `format:"markdown"` or `markdown:true` for a rendered trace report. |
+
+Reading rule: first use `slowest` to get candidate trace ids, then call `trace` on the suspicious id, then use
+`mcp_system_logs` only if you need surrounding log lines. A trace dominated by `firestore.*`, `http.*`,
+`gorm.save.*`, or component spans points you at the relevant platform seam or front-stage component. Large
+unaccounted wall time is itself a finding: check cold compile, queueing, blocking I/O, or missing
+`measure(...)` instrumentation.
+
 ### `mcp_component_view`
 Read component field content with line numbers.
 
@@ -2582,7 +2737,7 @@ 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]   # 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]   # 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
@@ -2609,6 +2764,36 @@ For tests specifically:
   intentional tombstone overrides. It is rejected on trunk.
 - `--dry-run` is only for `components sync` on non-trunk variant branches. It reports the variant write
   plan without writing rows, caching the sync SHA, or clearing staging.
+- `--summary` on `components sync --dry-run` prints compact counts, removals/tombstones, skipped items, errors,
+  and warnings instead of the full override/add/remove payload.
+- **Fail-closed sync gates.** The row below ("Sync response reports unexpected deletes...") tells you to
+  stop *after* an unexpected sync. These flags make sync refuse it up front instead, each exiting
+  non-zero rather than printing a wall of JSON you have to read carefully:
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually edited**.
+    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".
+  - `--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
+    did not name fails the sync.
+  - `--fail-on-errors` — fail if the server reported any per-component sync error.
+  - `--names-only` — print only `BUCKET type:id name` lines for the planned writes.
+
+  A good default for an unattended promotion is:
+  `remits-cli components sync --dry-run --summary --changed-only --fail-on-errors`
+
+### Prod banners and retryable failures
+
+- Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`
+  banner naming the operation, the resolved account, and the host — and distinguishes a live **WRITE**
+  from a live **READ** and from a **DRY RUN**. If you see a WRITE banner you did not intend, stop.
+- A tool call that fails **in the platform runtime** rather than in the tool (Groovy reflective dispatch
+  of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout)
+  now comes back as HTTP `503` with `failureClass: "transient_infrastructure"` and `retryable: true`,
+  and the CLI prints `TRANSIENT INFRASTRUCTURE FAILURE (retryable)`. Retry that **once**; prefer an
+  idempotent input if the tool has side effects. A genuine tool error stays HTTP `500` with
+  `failureClass: "tool_error"` — do **not** retry it, fix the input or the component.
 
 ## Troubleshooting
 
@@ -2630,7 +2815,7 @@ For tests specifically:
 | Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB (trunk, or the account's subscribed variant). `commit` to make it durable. See "Component Resolution". |
 | Need to know an account's shape (role, type, parents, namespace, branch) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |
 | Need the account tree below an account, or its users | `mcp_account_user_admin` (`action:'hierarchy'` with a `depth`, or `action:'users'`). `account-info.json` deliberately carries only direct children plus counts. |
-| An account has two parents and you don't know which one a run used | `resolution.relationships` lists every link with its own `branchName`/`databaseName`/`domainName`. A membership-only account with several edges resolves **trunk and inherits nothing** until a path is named (`--as-account`, `--variant-branch`, or an edge host) — that is by design, not a bug. |
+| An account has two parents and you don't know which one a run used | `resolution.relationships` lists every link with its own `branchName`/`databaseName`/`domainName`. A membership-only account with SEVERAL edges resolves **trunk and inherits nothing** until a path is named (`--as-account`, `--variant-branch`, or an edge host) — that is by design, not a bug. With exactly ONE membership edge it inherits normally, descendants included. |
 | Documents missing / written to the wrong place | Compare `resolution.databaseName` (the account's own override) with `resolution.resolvedDatabaseName` (what is actually in effect), and check for a `databaseName` on one of the `relationships` edges. Data does not inherit; components do. |
 | A custom hostname resolves to an unexpected account | Compare `resolution.domainName` with `resolvedDomainName` and the edge `domainName`s. An **edge** host wins over the account's own host and additionally supplies the path travelled (which is what makes that edge's branch variants apply). |
 | Need users of an account, or accounts of a user | There is no user MCP tool. Use `mcp_sql_query` on `user` / `user_account` (or `account.users([scope:'children'])` inside a component). Remember user custom fields are stored **per bound account**, so the same person can differ per account. |