@remits/remits-cli 0.1.115 → 0.1.116

package/README.md

@@ -22,7 +22,9 @@ remits-cli install --skills
 remits-cli tools
 remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
 remits-cli tool --name mcp_firestore_search --input '{"collection":"statements","documentId":"1234"}' --scope children
-remits-cli components stage
+remits-cli workspace use --auto               # once per checkout: your own staging lane
+remits-cli components stage --workset         # normal iteration: stage exactly what you changed
+remits-cli components stage                   # FULL SNAPSHOT of the repo into the lane
 remits-cli components status
 remits-cli components clear
 remits-cli test run --test 45
@@ -30,6 +32,7 @@ remits-cli test run --test "My New Test" --names "test case 1,test case 2"
 git add -A
 git commit -m "sync passing changes"
 git push
+remits-cli components sync --safe             # variant branch: gated, dry-runs first, refuses surprises
 remits-cli components sync
 remits-cli components sync --branch feature_branch --dry-run
 remits-cli components sync --branch feature_branch --dry-run --summary
@@ -61,11 +64,17 @@ remits-cli install --skills --overwrite true
 
 ## How It Works
 
-- `components stage` uploads the current working tree into the staging cache used by test-mode execution. It replaces the branch/user staging scope with the current manifest, so stale aliases from prior stages are removed.
+- `components stage` has three modes, and the difference decides what a run in the lane resolves:
+  - **default (full snapshot)** — uploads the whole repository manifest and reconciles the lane to it, so stale aliases from prior stages are removed. Correct as a complete snapshot and as a "what is stale here?" reset; a poor progress signal, because the lane then holds every component in the repo.
+  - **`--workset`** — uploads only the components git reports changed and reconciles the lane to exactly those. The normal iteration mode. `--changed-only --replace-lane` is the explicit spelling.
+  - **`--changed-only`** — uploads only the changed components and MERGES, leaving every other staged entry in place. It therefore cannot shrink a lane inherited from an earlier full snapshot; the command warns when it retains entries that way.
+- An **empty workset never clears a lane**: `--workset` on a clean working tree stages nothing and leaves the lane as it is. Pass `--empty-workset clear` to opt in, or use `components clear --all`.
+- A **deleted component file cannot be represented in Redis staging** — clearing a staged entry falls back to the committed row, so the component still resolves. Those changes are reported as NOT REPRESENTABLE. On a non-trunk variant branch, prove a deletion through `components sync --dry-run --summary --fail-on-errors`; on trunk there is no dry-run plan, so use the full pre-sync safety check before any mutating reconcile.
 - 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` separates local working-tree component deltas from the full materialized staging cache count.
+- `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
+- `components stage` and `components status` report three separate numbers, and they answer three different questions: the **workset** (components git reports this working tree changed), what was **submitted**, and the materialized **overlay** the lane now holds — which is what a run resolves. A number that could not be established prints as `unknown`, never as `0`.
 - `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`, `account-hierarchy.json`, and `account-configurations.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`.
@@ -86,6 +95,7 @@ remits-cli install --skills --overwrite true
 - 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 --safe` is the recommended agent path on a variant branch. It expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves `--changed-since` from the branch's merge base with trunk when you did not name one (local refs only; it never runs an implicit `git fetch`), and prints the planned writes before mutating unless `--yes` is passed. On trunk there is no plan to gate, so it states what a trunk reconcile does and requires `--yes`.
 - `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.
@@ -197,7 +207,7 @@ tail -n 200 ~/.remits-cli/tmux-activity.log
 - `tmux` must be installed for agent dispatch to work. Without it, websocket dispatch is received but agent panes cannot be created.
 - In sandboxed local agent environments, `remits-cli` network calls may fail with `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar errors even when dispatch worked correctly. That means the command needs escalated permissions or must be run outside the sandbox.
 - If the platform returns a 500 or other unexpected server-side failure, stop normal task execution and escalate to a Remits system admin. Agents should not invent workarounds for platform faults.
-- Recommended durable update flow for agents: `components stage` for testing, then `git add/commit/push`, then `remits-cli components sync`, then `git pull --ff-only` to confirm platform-generated files like `account-info.json`.
+- Recommended durable update flow for agents: `components stage --workset` for testing, then `git add/commit/push`, then `remits-cli components sync --safe`, then `git pull --ff-only` to confirm platform-generated files like `account-info.json`. To verify the COMMITTED variant rather than your staging, run `components clear --all` first — staged entries still win for CLI-scoped runs.
 - In sandboxed agent environments, local git writes may require a single approval step. If you want to minimize approval churn, `remits-cli components commit` consolidates the local git and sync phases into one CLI command.
 - If account repo discovery fails for a websocket message, dispatch is skipped because the listener does not know which local directory to open for that account.
 - If you authenticate a new account while the listener is already running, the listener now refreshes its websocket clients automatically instead of requiring a manual restart.

package/index.js

@@ -2458,12 +2458,29 @@ async function pushComponentsCommand(flags) {
   const mode = requestedMode === 'push' ? 'stage' : requestedMode;
   const changedFromWorkingTree = changedComponentsFromWorkingTree(cwd);
 
-  // --changed-only stages just the components this working tree edited, instead of re-uploading all of
-  // them. Two reasons it matters here: it is what makes an iteration loop cheap on a large repo, and it
-  // deliberately does NOT send `replace`, so the server's reconcile pass cannot delete the entries for
-  // components this partial stage did not mention.
-  const changedOnly = flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly);
+  // WHAT this stage is. Three shapes, and the difference between them is the difference between a lane
+  // that reads as "7 components in flight" and one that reads as "115 staged":
+  //
+  //   full snapshot   the whole repo manifest, lane reconciled to it       `components stage`
+  //   workset replace only the git-changed components, lane reconciled     `components stage --workset`
+  //   workset merge   only the git-changed components, merged into the lane `components stage --changed-only`
+  //
+  // `--changed-only` keeps its old merge semantics deliberately — changing what an existing flag does
+  // silently is how a safe command becomes a destructive one for somebody's script. The exact-lane
+  // behavior is the new flag.
+  const worksetReplace = flagEnabled(flags.workset) ||
+    ((flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) &&
+     (flagEnabled(flags['replace-lane']) || flagEnabled(flags.replaceLane)));
+  const changedOnly = worksetReplace || flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly);
+  const stageMode = worksetReplace ? 'workset-replace' : (changedOnly ? 'workset-merge' : 'full-snapshot');
+  const emptyWorksetPolicy = normalizeEmptyWorksetPolicy(flags);
+
   let components = collectComponents(cwd);
+  // Changes git reported that a component payload cannot carry — a deleted component file has nothing to
+  // stage, and Redis staging has no way to say "hide this during CLI-scoped runs". Removing its staged
+  // entry falls back to the committed row, so the component still resolves. Reported out loud rather than
+  // dropped, because "my delete did not take effect" otherwise looks like a platform bug.
+  const unstageable = unrepresentableChanges(changedFromWorkingTree, components);
   if (changedOnly) {
     if (changedFromWorkingTree === null) {
       throw new Error('--changed-only needs a git working tree to establish the changed set, and this directory is not one.');
@@ -2472,10 +2489,20 @@ async function pushComponentsCommand(flags) {
       entry.type + ':' + (entry.id ? 'id:' + entry.id : 'name:' + String(entry.name || '').toLowerCase())));
     components = components.filter((component) => wanted.has(
       component.type + ':' + (component.id ? 'id:' + component.id : 'name:' + String(component.name || '').toLowerCase())));
-    if (!components.length) {
-      console.log('--changed-only: this working tree has no uncommitted component edits; nothing to stage.');
+    if (!components.length && !(worksetReplace && emptyWorksetPolicy === 'clear')) {
+      // Deliberately NOT an error, and deliberately not a clear. An agent that has not edited anything yet
+      // is in an ordinary state; failing its loop teaches it nothing, and reconciling the lane to an empty
+      // manifest would delete the overlay its next test run depends on.
+      console.log('Stage mode:', stageMode);
+      console.log('Workset detected from git: 0 component(s) — nothing was staged and the lane was left as it is.');
+      if (worksetReplace) {
+        console.log('  The lane was NOT cleared. Clearing stays explicit: `remits-cli components clear --all`,');
+        console.log('  or re-run with `--empty-workset clear` if an empty lane is what you meant.');
+      }
       printStagingLane(branchName, workspace, workspaceSource(cwd, flags));
-      return { success: true, mode, updated: 0, unchanged: 0, skipped: [], changedOnly: true };
+      printUnrepresentableChanges(unstageable);
+      return { success: true, mode, updated: 0, unchanged: 0, skipped: [], changedOnly: true, stageMode,
+               worksetCount: 0, staged: false };
     }
   }
 
@@ -2503,13 +2530,27 @@ async function pushComponentsCommand(flags) {
     ...runContextPayload(flags),
     agentId: flags['agent-id'] || process.env.REMITS_AGENT_ID || undefined,
     acknowledge: flags.acknowledge || undefined,
-    // A partial (--changed-only) stage must not trigger the server's reconcile pass: reconcile deletes
-    // every staged entry absent from the manifest, which for a partial manifest is nearly all of them.
+    // What this stage IS, stated rather than implied. The server derives the lane behavior from the mode
+    // (CliComponentStaging.stageRequest) instead of from `replace`, which was overloaded: a partial
+    // manifest with `replace: true` would make the reconcile pass delete nearly the whole lane, so
+    // `--changed-only` had to send `replace: false` and could therefore never shrink a lane it inherited.
+    stageMode,
+    manifestScope: changedOnly ? 'working-tree' : 'repo',
+    emptyWorksetPolicy,
+    // Whether git could answer at all. A zero rendered for an unavailable answer is exactly the kind of
+    // confident wrong number this whole surface exists to remove.
+    worksetKnown: changedFromWorkingTree !== null,
+    // The git evidence, per component: which files changed and with what status. It is what lets the
+    // console split a lane's "active workset" from the entries a previous full snapshot left behind.
+    changedSet: (changedFromWorkingTree || []).concat(unstageable),
+    // Kept for a platform that predates stageMode. Same meaning it always had.
     replace: !changedOnly,
     components
   });
   response.changedFromWorkingTree = changedFromWorkingTree || [];
   response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
+  response.requestedStageMode = stageMode;
+  response.unrepresentableChanges = unstageable;
 
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(response, null, 2));
@@ -2520,11 +2561,53 @@ async function pushComponentsCommand(flags) {
   printResolvedBaseUrl(baseUrl);
   printStagingLane(response.branchName || branchName, response.workspace || workspace, workspaceSource(cwd, flags));
   console.log('Data mode:', response.dataMode || dataMode);
-  console.log('Mode:', response.mode || mode + (changedOnly ? ' (--changed-only)' : ''));
   printComponentPolicy(response);
   printStageSummary(response, flags);
 }
 
+/** `--empty-workset refuse|clear`. Refusing is the default, and the only safe one. */
+function normalizeEmptyWorksetPolicy(flags) {
+  const raw = flags['empty-workset'] != null ? flags['empty-workset'] : flags.emptyWorkset;
+  const value = raw === true ? '' : String(raw == null ? '' : raw).trim().toLowerCase();
+  if (value === 'clear' || value === 'clears-lane') return 'clear';
+  return 'refuse';
+}
+
+/**
+ * Git-reported component changes that a stage payload cannot carry.
+ *
+ * A deleted component file has no content to send, and Redis staging has no way to express "hide this
+ * during CLI-scoped runs" — clearing its staged entry falls back to the committed row, so the component
+ * still resolves. An agent that deletes a file, stages, and sees the component still running would read
+ * that as a platform defect. Durable deletion lives in variant sync (tombstones), not here.
+ *
+ * Returns [] when git could not answer, because "nothing is unrepresentable" would be a claim.
+ */
+function unrepresentableChanges(changedFromWorkingTree, collected) {
+  if (!Array.isArray(changedFromWorkingTree)) return [];
+  const present = new Set((collected || []).map((component) =>
+    component.type + ':' + (component.id ? 'id:' + component.id : 'name:' + String(component.name || '').toLowerCase())));
+  return changedFromWorkingTree
+    .filter((entry) => !present.has(entry.type + ':' + (entry.id ? 'id:' + entry.id : 'name:' + String(entry.name || '').toLowerCase())))
+    .map((entry) => Object.assign({}, entry, {
+      unrepresentable: true,
+      reason: (entry.statuses || []).some((s) => String(s).includes('D')) ? 'deleted' : 'no-local-files'
+    }));
+}
+
+function printUnrepresentableChanges(unstageable) {
+  if (!unstageable || !unstageable.length) return;
+  console.log('');
+  console.log('NOT REPRESENTABLE IN REDIS STAGING — ' + unstageable.length + ' change(s):');
+  unstageable.slice(0, 20).forEach((entry) => {
+    console.log('  ' + entry.type + ' ' + (entry.id || entry.name || '(unknown)') +
+      '  (' + entry.reason + ')  ' + (entry.paths || []).join(', '));
+  });
+  console.log('  A staged entry cannot hide a component. Clearing it falls back to the committed row, so');
+  console.log('  the component still resolves in a CLI-scoped run. Prove a deletion through the durable');
+  console.log('  plan instead:  remits-cli components sync --dry-run --summary --fail-on-errors');
+}
+
 /**
  * A policy refusal is an ANSWER, not a transport failure.
  *
@@ -2602,15 +2685,55 @@ function printComponentCommandResponse(label, response, flags) {
   printFullResponseHint();
 }
 
+/**
+ * What this stage did, in the terms a human is actually asking about.
+ *
+ * Three numbers, and they are three different questions:
+ *
+ *   WORKSET   how many components this working tree changed, per git
+ *   SUBMITTED how many this command uploaded
+ *   OVERLAY   how many staged entries the lane now holds, which is what a run resolves
+ *
+ * They used to be reported as one number — the overlay — so an agent that edited 5 components in a repo
+ * of 115 produced "Updated: 115" and a console badge reading "STAGED 115". Nobody could tell 115 edits
+ * from one full snapshot, and those want opposite actions.
+ */
 function printStageSummary(response, flags) {
-  // `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;
+  const stage = response.stage || {};
+  const lane = response.laneSummary || {};
+  // What we ASKED for, and what the platform says it did. Kept apart deliberately: comparing the server's
+  // answer against a value that already fell back to it can never disagree, so the mismatch note below
+  // could never fire.
+  const requestedMode = response.requestedStageMode || null;
+  const stageMode = stage.mode || requestedMode || 'full-snapshot';
+
+  console.log('Stage mode:', describeStageMode(stageMode));
+
+  // A platform that predates stage modes ignores `stageMode` and reads `replace`, which a workset stage
+  // sends as false — so it MERGES where the caller asked for a lane replacement, and returns no `stage`
+  // block to say so. Silence there is the worst outcome available: the agent believes the lane holds
+  // exactly its workset while the platform left an inherited overlay in place. Detect it by what came
+  // back rather than by a version number.
+  if (stage.mode == null && response.staging) {
+    console.log('NOTE: this platform predates stage modes. It read the legacy `replace` flag, so a');
+    console.log('  --workset stage MERGED into the lane instead of reconciling it, and the workset/');
+    console.log('  overlay split below is not available. Use `components clear --all` first if you need');
+    console.log('  the lane to hold exactly your workset.');
+  } else if (stage.mode && requestedMode && stage.mode !== requestedMode) {
+    console.log('NOTE: asked the platform for `' + requestedMode + '`; it applied `' + stage.mode + '`.');
+  }
+
+  if (response.sharedLane === true) {
+    console.log('Lane: SHARED (no workspace) — a full stage REPLACES it rather than merging, so a second');
+    console.log('      agent staging here overwrites what you are testing. `remits-cli workspace use --auto`.');
+  }
+
+  // "git could not answer" and "git says nothing changed" are different facts, and only one of them is a
+  // number. Never render the missing answer as zero.
   if (tracked) {
-    console.log('Components edited in this working tree:', changed.length);
+    console.log('Workset detected from git:', changed.length, 'component(s)');
     changed.slice(0, 20).forEach((entry) => {
       const label = (entry.type || 'component') + ' ' + (entry.id || entry.name || '(unknown)');
       const name = entry.name && entry.id ? ' ' + entry.name : '';
@@ -2623,23 +2746,66 @@ function printStageSummary(response, flags) {
     if (!changed.length) {
       console.log('  (no uncommitted component edits — already-committed edits are staged but not listed here)');
     }
+  } else {
+    console.log('Workset detected from git: UNKNOWN (this is not a git working tree)');
   }
-  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);
+
+  const submitted = stage.submittedCount != null
+    ? stage.submittedCount
+    : ((response.updated || 0) + (response.unchanged || 0));
+  console.log('Submitted to the platform:', submitted, 'component(s)  (' +
+    (response.updated || 0) + ' newly written, ' + (response.unchanged || 0) + ' already current)');
+  if (Array.isArray(response.skipped) && response.skipped.length) {
+    console.log('Skipped (no type/hash/identity):', response.skipped.length);
   }
-  if (response.staging) {
-    console.log('Total staged entries for this branch/user:', response.staging.remainingCount || 0);
+  if (stage.removedRetainedCount) {
+    console.log('Removed from the lane by this stage:', stage.removedRetainedCount, 'staged entry(ies)');
+  } else if (response.reconcile) {
+    console.log('Removed from the lane by this stage:', response.reconcile.removedCount || 0, 'staged entry(ies)');
   }
+
+  const overlay = lane.stagedCount != null
+    ? lane.stagedCount
+    : (response.staging ? response.staging.remainingCount : null);
+  if (overlay != null) {
+    console.log('Materialized overlay now held by the lane:', overlay, 'component(s)');
+  }
+
+  // The trap `--changed-only` leaves behind: it merges, so a lane inherited from an earlier full snapshot
+  // keeps every one of those entries resolving ahead of committed source. Silence here is what made
+  // "I staged 7 components" and "this lane holds 115" look like the same statement.
+  const retained = lane.retainedCount;
+  if (retained > 0) {
+    console.log('');
+    console.log('WARNING: ' + retained + ' staged component(s) in this lane were NOT submitted by this stage.');
+    console.log('  They came from an earlier stage and still shadow committed source for every run in this lane.');
+    console.log('  Make the lane exactly your workset:  remits-cli components stage --workset');
+    console.log('  Or drop the overlay entirely:        remits-cli components clear --all');
+  }
+
+  printUnrepresentableChanges(response.unrepresentableChanges || (stage.unrepresentable || []));
   printComponentCommandResponse('Components stage', response, flags);
 }
 
+function describeStageMode(mode) {
+  switch (mode) {
+    case 'full-snapshot':
+      return 'full snapshot (whole repo manifest; the lane is reconciled to it)';
+    case 'workset-replace':
+      return 'workset replace (only the components git reports changed; the lane is reconciled to exactly them)';
+    case 'workset-merge':
+      return 'workset merge (only the components git reports changed, MERGED into whatever the lane already held)';
+    case 'partial':
+      return 'partial (single-component field edit)';
+    default:
+      return mode || 'unknown';
+  }
+}
+
 function printStatusSummary(response, flags) {
   printBranchContext(response);
   printStagingLane(response.branchName, response.workspace, null);
-  console.log('Staged count:', response.stagedCount || 0);
+  printLaneSummary(response);
   printComponentTypeCounts(response.entries || []);
 
   // Every lane staged on this branch, not just this one. An agent that believes it is working alone can
@@ -2663,6 +2829,48 @@ function printStatusSummary(response, flags) {
   printComponentCommandResponse('Components staging', response, flags);
 }
 
+/**
+ * What THIS lane holds, separated into the work in flight and the overlay carried along with it.
+ *
+ * Read authoritatively from the staging keys (not the lane index), so the numbers here are the ones a run
+ * in this lane will actually resolve.
+ */
+function printLaneSummary(response) {
+  const lane = response.laneSummary || {};
+  const overlay = lane.stagedCount != null ? lane.stagedCount : (response.stagedCount || 0);
+
+  console.log('Materialized overlay (what a run in this lane resolves):', overlay, 'component(s)');
+  // An EMPTY lane has no last stage, so "Last stage: unknown" would invite a reader to go looking for a
+  // stage that never happened. Nothing staged is clean state, not a missing answer.
+  if (!overlay) {
+    console.log('Nothing is staged in this lane; runs here resolve committed source.');
+  } else if (lane.stageMode && lane.stageMode !== 'unknown') {
+    console.log('Last stage:', describeStageMode(lane.stageMode));
+    if (lane.submittedCount != null) {
+      console.log('  submitted by that stage:', lane.submittedCount, 'component(s)');
+    }
+    // null is "not established", never zero. A lane staged by a build that predates stage provenance has
+    // an unknown workset, and printing 0 would assert that nobody is working in it.
+    if (lane.worksetKnown && lane.worksetCount != null) {
+      console.log('  of which git reported as edited:', lane.worksetCount, 'component(s)');
+    } else {
+      console.log('  of which git reported as edited: unknown (that stage reported no git evidence — an');
+      console.log('    older CLI, a non-git checkout, or a single-field MCP edit)');
+    }
+    if (lane.retainedCount > 0) {
+      console.log('  retained from EARLIER stages:', lane.retainedCount, 'component(s) — these still shadow');
+      console.log('    committed source. `components stage --workset` makes the lane exactly your workset.');
+    }
+  } else {
+    console.log('Last stage: unknown (staged before stage modes existed, or by another door)');
+  }
+
+  if (response.sharedLane === true) {
+    console.log('Lane isolation: SHARED — no workspace. A full stage here REPLACES the lane rather than');
+    console.log('  merging, so a second agent overwrites what you are testing. `remits-cli workspace use --auto`.');
+  }
+}
+
 // Every staging lane on the ACCOUNT, across branches.
 //
 // The block above only ever covered lanes on the SAME git branch, because that is all its key pattern
@@ -2689,8 +2897,14 @@ function printAccountLanes(response) {
     const who = lane.userEmail ? '  ' + lane.userEmail : '';
     const ttl = lane.expiresInSeconds != null
       ? '  expires in ~' + Math.round(lane.expiresInSeconds / 60) + 'm' : '';
+    // Overlay first (it is what a run resolves), then the work the last stage actually submitted. A lane
+    // showing "115 overlay / 7 workset" is one agent iterating on 7 components, not 115 edits in flight.
+    const workset = (lane.worksetKnown && lane.worksetCountAsOf != null)
+      ? ', workset ' + lane.worksetCountAsOf : '';
+    const stageMode = lane.stageMode && lane.stageMode !== 'unknown' ? '  [' + lane.stageMode + ']' : '';
+    const shared = lane.sharedLane === true ? '  SHARED LANE' : '';
     console.log('  ' + (lane.mine ? '* ' : '  ') + lane.branchName + ws
-      + '  (' + world + ')  — ' + (lane.stagedCountAsOf || 0) + ' component(s)' + who + ttl);
+      + '  (' + world + ')  — overlay ' + (lane.stagedCountAsOf || 0) + workset + stageMode + shared + who + ttl);
   });
   console.log('  (* = this command\'s lane)');
   console.log('  A variant-branch lane layers over that branch\'s ComponentVariant overlays, and a commit');
@@ -2887,8 +3101,13 @@ async function clearComponentsCommand(flags) {
   return response;
 }
 
-async function syncComponentsCommand(flags) {
+async function syncComponentsCommand(rawFlags) {
   const cwd = process.cwd();
+  // `--safe` is a NAME for the gate combination that should be the default agent path, not a new gate.
+  // Spelling out --summary --changed-only --fail-on-errors --fail-on-removed correctly every time is the
+  // step agents skip, and skipping it is how a stale branch writes 34 unrelated ComponentVariant rows.
+  const safe = flagEnabled(rawFlags.safe);
+  const flags = safe ? expandSafeSyncFlags(rawFlags) : rawFlags;
   ensureLocalState(cwd);
   const sessionContext = resolveSessionContext(cwd, flags);
   const { session, accountId } = sessionContext;
@@ -2935,6 +3154,10 @@ async function syncComponentsCommand(flags) {
   };
 
   let preflightGate = null;
+  // The flags the gates are actually evaluated with. `--safe` may resolve `--changed-since` for the
+  // caller, and it must be the SAME value the preflight and the post-sync evaluation use, or the two
+  // could disagree about the same plan.
+  let gateFlags = flags;
   if (preflightRequested && !dryRun) {
     const statusResponse = await loggedPost(api, cwd, '/cli/components', {
       token: session.token,
@@ -2947,31 +3170,63 @@ async function syncComponentsCommand(flags) {
 
     const branchContext = statusResponse && statusResponse.branchContext;
     if (!branchContext || branchContext.onTrunk) {
-      throw new Error('components sync safety preflight requires a non-trunk variant branch because trunk sync has no dry-run plan. Re-run without safety flags only if you intend a full trunk reconcile.');
-    }
+      // Trunk has no dry-run plan to gate on, and pretending otherwise would be worse than refusing:
+      // an agent would read "safe" and get an ungated authoritative reconcile. Say what trunk sync is
+      // and make the caller assert it.
+      if (!safe) {
+        throw new Error('components sync safety preflight requires a non-trunk variant branch because trunk sync has no dry-run plan. Re-run without safety flags only if you intend a full trunk reconcile.');
+      }
+      console.log('');
+      console.log('TRUNK SYNC — there is no dry-run plan for trunk, so --safe cannot gate this.');
+      console.log('  This is an AUTHORITATIVE full repo-to-DB reconcile of ' + (branchContext ? branchContext.trunkBranch || branchName : branchName) + ':');
+      console.log('    every component row is rewritten from the pushed repo, and any live component');
+      console.log('    missing from the repo is DELETED.');
+      console.log('  For a gated plan, work on a variant branch instead.');
+      if (!flagEnabled(flags.yes)) {
+        throw new Error('components sync --safe on trunk requires --yes, because the plan cannot be previewed. ' +
+          'Re-run with --yes to accept the full trunk reconcile, or switch to a variant branch for a gated sync.');
+      }
+      // Drop the gates that can only be evaluated against a plan. Leaving them on would fail the command
+      // AFTER an authoritative reconcile had already been written, which is the worst of both.
+      gateFlags = Object.assign({}, flags, {
+        'changed-only': false, changedOnly: false,
+        'fail-on-removed': false, failOnRemoved: false
+      });
+    } else {
+      gateFlags = resolveChangedSinceFlags(flags, cwd, branchContext, safe);
 
-    const previewResponse = await loggedPost(api, cwd, '/cli/components', Object.assign({}, syncPayload, {
-      dryRun: true
-    })).then((r) => r.data);
+      const previewResponse = await loggedPost(api, cwd, '/cli/components', Object.assign({}, syncPayload, {
+        dryRun: true
+      })).then((r) => r.data);
 
-    if (!previewResponse.success) {
-      throw new Error(previewResponse.message || 'Server sync dry-run failed');
-    }
+      if (!previewResponse.success) {
+        throw new Error(previewResponse.message || 'Server sync dry-run failed');
+      }
 
-    preflightGate = evaluateSyncGates(previewResponse, flags, changedFromWorkingTree, cwd);
+      preflightGate = evaluateSyncGates(previewResponse, gateFlags, changedFromWorkingTree, cwd);
+
+      if (namesOnly) {
+        printSessionResolutionWarning(sessionContext);
+        printResolvedBaseUrl(baseUrl);
+        console.log('Data mode:', previewResponse.dataMode || dataMode);
+        console.log('Mode:', 'sync dry-run');
+        console.log('Dry run: no variants were written and staging was not cleared.');
+        printSyncNames(previewResponse);
+        failOnSyncGate(preflightGate);
+        return previewResponse;
+      }
 
-    if (namesOnly) {
-      printSessionResolutionWarning(sessionContext);
-      printResolvedBaseUrl(baseUrl);
-      console.log('Data mode:', previewResponse.dataMode || dataMode);
-      console.log('Mode:', 'sync dry-run');
-      console.log('Dry run: no variants were written and staging was not cleared.');
-      printSyncNames(previewResponse);
       failOnSyncGate(preflightGate);
-      return previewResponse;
-    }
 
-    failOnSyncGate(preflightGate);
+      // The plan passed every gate. Show it before mutating anyway: a gate proves the plan matches the
+      // changed set, not that the changed set is what the author meant.
+      if (safe && !flagEnabled(flags.yes)) {
+        console.log('');
+        console.log('Planned durable writes (gates passed):');
+        printSyncNames(previewResponse);
+        console.log('');
+      }
+    }
   }
 
   // Through the same refusal-aware door as `stage`: the landing lease and the account's commit rules both
@@ -2983,7 +3238,7 @@ async function syncComponentsCommand(flags) {
   }
 
   const summary = buildSyncSummary(response);
-  const gate = preflightGate || evaluateSyncGates(response, flags, changedFromWorkingTree, cwd);
+  const gate = preflightGate || evaluateSyncGates(response, gateFlags, changedFromWorkingTree, cwd);
   summary.gates = gate.checks;
 
   if (flagEnabled(flags.json)) {
@@ -3093,8 +3348,73 @@ function printPromotionSignals(response) {
   });
 }
 
+/**
+ * `--safe`: the gate combination that should be the normal agent path for a variant-branch sync.
+ *
+ * Named rather than remembered. The individual flags have existed for a while and the failure they exist
+ * to stop — a stale branch whose old copies of untouched files become unrelated ComponentVariant
+ * overrides — happens precisely when somebody forgets one of them.
+ *
+ * `--expected-removed` already implies fail-on-removed and NAMES the removals the caller accepts, so
+ * --safe must not layer a blanket --fail-on-removed on top of it and contradict the narrower answer.
+ */
+function expandSafeSyncFlags(flags) {
+  const expectedRemoved = flags['expected-removed'] != null ? flags['expected-removed'] : flags.expectedRemoved;
+  return Object.assign({}, flags, {
+    summary: true,
+    'fail-on-errors': true,
+    'changed-only': true,
+    'fail-on-removed': expectedRemoved != null ? flags['fail-on-removed'] : true
+  });
+}
+
+/**
+ * The base ref the `--changed-only` gate compares the server plan against.
+ *
+ * `--changed-only` alone reads UNCOMMITTED edits, and the documented flow commits and pushes BEFORE the
+ * sync (the server syncs by pulling the remote, so it cannot see uncommitted work at all). So at the
+ * moment the gate runs, the working tree is usually clean and the changed set is empty — which used to
+ * make the gate refuse every plan.
+ *
+ * Under --safe the ref is derived from the branch's own merge base with trunk when the caller did not
+ * name one. Local refs only: no implicit `git fetch`, because a status/gate command that quietly reaches
+ * the network is a command whose cost and failure modes the caller did not agree to. When nothing local
+ * can answer, this refuses with the command to run rather than gating against an empty set.
+ */
+function resolveChangedSinceFlags(flags, cwd, branchContext, safe) {
+  const explicit = flags['changed-since'] || flags.changedSince;
+  if (explicit || !safe) {
+    return flags;
+  }
+  const trunk = (branchContext && branchContext.trunkBranch) || 'main';
+  const candidates = ['origin/' + trunk, trunk];
+  for (const candidate of candidates) {
+    let base = null;
+    try {
+      base = execSync('git merge-base HEAD ' + JSON.stringify(candidate), {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe']
+      }).toString().trim();
+    } catch (_) {
+      continue;
+    }
+    if (base) {
+      console.log('--safe: comparing the sync plan against everything this branch added since ' +
+        candidate + ' (' + base.slice(0, 12) + ').');
+      return Object.assign({}, flags, { 'changed-since': base });
+    }
+  }
+  throw new Error(
+    'components sync --safe needs a base ref to compare the plan against, and neither origin/' + trunk +
+    ' nor ' + trunk + ' could be resolved locally.\n' +
+    '  Run `git fetch origin ' + trunk + '` and retry, or pass it yourself:\n' +
+    '    remits-cli components sync --safe --changed-since origin/' + trunk
+  );
+}
+
 function syncPreflightRequested(flags) {
   return Boolean(
+    flagEnabled(flags.safe) ||
     flagEnabled(flags['names-only']) ||
     flagEnabled(flags.namesOnly) ||
     flagEnabled(flags['changed-only']) ||
@@ -3214,7 +3534,16 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree, cwd) {
           ? '\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.'
-          : '';
+          // A plan that reaches well beyond a real changed set is almost always a STALE BRANCH: it still
+          // physically carries old copies of files nobody on it touched, and a variant sync turns each of
+          // those into an unrelated override. Naming the cause is the difference between a gate that
+          // stops the damage and a gate that also tells you how to clear it.
+          : (changedSet.length && unexpected.length > changedSet.length)
+            ? '\n    Most likely cause: this branch is BEHIND trunk and still carries old copies of files ' +
+              'it never changed. A variant sync turns each of those into an unrelated override.' +
+              '\n    Next step: merge trunk into this branch, push, then re-run the same command:' +
+              '\n      git merge <trunk> && git push origin <branch>'
+            : '';
         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);
       }
@@ -3717,6 +4046,14 @@ async function commitComponentsCommand(flags) {
   }
 
   console.log('Phase 2/3: server sync');
+  if (flagEnabled(flags.safe)) {
+    // The honest limit, stated where it applies. `components commit` runs git add/commit/push BEFORE the
+    // server sync, so a --safe gate here cannot stop the push — it stops the PLATFORM from writing bad
+    // overlays. The branch may already be pushed when the gate refuses; that is recoverable, an
+    // unintended ComponentVariant tree is much less so.
+    console.log('  --safe: the branch is already pushed. The gate below stops the platform from WRITING a');
+    console.log('  surprising plan; it cannot un-push. Use `components sync --safe` alone for a pre-push gate.');
+  }
   const syncResponse = await syncComponentsCommand({
     ...flags,
     branch: branchName,
@@ -9854,6 +10191,13 @@ function printComponentsHelp(subcommand) {
     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('  --safe                    THE RECOMMENDED PATH on a variant branch. Expands to');
+    console.log('                            --summary --changed-only --fail-on-errors --fail-on-removed,');
+    console.log('                            resolves --changed-since from the merge base with trunk when you');
+    console.log('                            did not name one (local refs only, no implicit fetch), and prints');
+    console.log('                            the planned writes before mutating unless --yes is passed.');
+    console.log('                            On TRUNK there is no plan to gate, so it explains what a trunk');
+    console.log('                            reconcile does and requires --yes.');
     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');
@@ -9865,14 +10209,29 @@ function printComponentsHelp(subcommand) {
     return;
   }
   if (subcommand === 'stage' || subcommand === 'push') {
-    console.log('Usage: remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--changed-only] [--data-mode test|prod] [--json|--verbose]');
+    console.log('Usage: remits-cli components stage [--workset | --changed-only] [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--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.');
+    console.log('');
+    console.log('Three stage modes, and the difference decides what a run in this lane resolves:');
+    console.log('  (default)          FULL SNAPSHOT — uploads the whole repo manifest and reconciles the lane');
+    console.log('                     to it. Correct as a complete snapshot and as a "what is stale?" reset;');
+    console.log('                     a poor progress signal, because the lane then holds every component.');
+    console.log('  --workset          WORKSET REPLACE — uploads only the components git reports changed and');
+    console.log('                     reconciles the lane to exactly them. THE NORMAL ITERATION MODE: the');
+    console.log('                     lane holds your work and nothing else, so the console shows what you');
+    console.log('                     are actually doing. An empty workset is refused, never a silent clear.');
+    console.log('  --changed-only     WORKSET MERGE — uploads only the changed components and leaves every');
+    console.log('                     other staged entry in place. Keeps its long-standing semantics, so it');
+    console.log('                     cannot shrink a lane inherited from an earlier full snapshot; the');
+    console.log('                     command warns when entries are retained that way.');
     console.log('');
     console.log('  --workspace NAME   stage into an isolated lane on this branch (see `remits-cli workspace`).');
-    console.log('  --changed-only     stage only the components this working tree edited, and do NOT reconcile');
-    console.log('                     (entries for untouched components are left alone rather than deleted).');
+    console.log('  --empty-workset clear   with --workset, let an empty workset clear the lane (default: refuse).');
+    console.log('  --replace-lane     with --changed-only, the explicit spelling of --workset.');
+    console.log('');
+    console.log('Output separates three different numbers: the WORKSET git reports, what was SUBMITTED, and');
+    console.log('the materialized OVERLAY the lane now holds — which is the one a run resolves.');
     return;
   }
   if (subcommand === 'status') {
@@ -9893,21 +10252,26 @@ function printComponentsHelp(subcommand) {
     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('Usage: remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
     console.log('');
     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.');
+    console.log('');
+    console.log('--safe passes the sync gates through to phase 2. The honest limit: git push happens in phase 1,');
+    console.log('so the gate stops the PLATFORM from writing a surprising plan — it cannot un-push the branch.');
+    console.log('For a gate that runs before anything leaves your machine, push yourself and use');
+    console.log('`remits-cli components sync --safe`.');
     return;
   }
   console.log('Usage: remits-cli components <stage|status|clear|sync|commit|promotion|branches|branch>');
   console.log('');
   console.log('All staging subcommands accept --workspace NAME to isolate a lane on the same branch,');
   console.log('so several agents can iterate at once. See: remits-cli workspace --help');
-  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 stage [--workset|--changed-only] [--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('  remits-cli components sync [--safe] [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
+  console.log('  remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
   console.log('');
   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.');
@@ -10057,10 +10421,10 @@ async function main() {
     console.log('  remits-cli tool --name <toolName> [--base-url URL] [--branch BRANCH] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--scope self|children|hierarchy] [--target-account-id ID] [--account-ids 1,2,3] [--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('  remits-cli workspace [show|use <name>|use --auto|clear]        # isolate staging when several agents share a repo');
-    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--changed-only] [--data-mode test|prod] [--json|--verbose]');
+    console.log('  remits-cli components stage [--workset|--changed-only] [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--data-mode test|prod] [--json|--verbose]');
     console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--component-type TYPE --component-id ID] [--json|--verbose]');
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--workspace NAME] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
-    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
+    console.log('  remits-cli components sync [--safe] [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
     console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
     console.log('  remits-cli components promotion [<branch>] [--json] [--no-fail]  # promotion readiness + ordered next steps');
     console.log('  remits-cli components branches [--json]                     # committed branch variants for this account');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -60,6 +60,19 @@ reference named after it.
 - **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
   moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
   the OLD code. This is the single most common mistake. (`development-loop.md`)
+- **Stage your WORKSET, not the whole repo: `remits-cli components stage --workset`.** It uploads only
+  the components git reports changed and makes the lane hold exactly them. A plain `components stage` is
+  a FULL SNAPSHOT — it puts every component in the repo into the lane, so "115 staged" tells a human
+  nothing about what you are working on, and every one of those entries shadows committed source until
+  it expires. Keep the full stage for a deliberate complete snapshot or a "what is stale here?" reset.
+  (`development-loop.md`)
+- **Give each agent its own lane: `remits-cli workspace use --auto`.** Without a workspace you are in
+  the SHARED lane, where a full stage replaces what another agent is testing rather than merging with
+  it. (`component-resolution.md`)
+- **On a variant branch, sync with `remits-cli components sync --safe`.** It dry-runs first and refuses
+  a plan that would write components this checkout did not change — which is what a branch that is
+  behind trunk produces, because it still physically carries old copies of files nobody touched.
+  (`component-integrity.md`, `branch-variants.md`)
 - **`stage` is always safe. `components commit` on trunk is the most dangerous command in the CLI.**
   It is not a convenience wrapper: it `git add -A`, commits, pushes, and then reconciles the whole
   pushed repo into the live component database — creating, updating, renaming, and **hard-deleting**
@@ -84,6 +97,10 @@ reference named after it.
 - **Resolution order is staged → variant → trunk, and each layers over the one beneath.** A populated
   staging cache makes a committed variant look broken through any tokenized entry point; clear it before
   verifying variant resolution. (`component-resolution.md`)
+- **A lane's staged count is the OVERLAY, not your workset.** The overlay is every staged entry the lane
+  holds — what a run resolves. The workset is what git says you changed. A full stage makes them differ
+  by the size of the repo, and `--changed-only` merges, so it can never shrink an overlay it inherited.
+  `components status` prints all three numbers; so does the console. (`component-resolution.md`)
 - **Host and data mode are two independent decisions.** `--base-url` picks the Remits host,
   `--data-mode` picks the data segment on it. Neither implies the other. (`command-reference.md`)
 - **`test run` ignores the stored session data lane.** It defaults to `test` even when `whoami` shows
@@ -139,7 +156,8 @@ reference named after it.
 
 ```bash
 remits-cli whoami                 # account, user, branch, data mode, host for the NEXT tool call
-remits-cli components status      # trunk or variant checkout, staging lane, what is staged
+remits-cli workspace use --auto   # your own staging lane, named after this checkout
+remits-cli components status      # trunk or variant checkout, staging lane, workset vs overlay, who else is staging
 remits-cli tools                  # which tools this account actually has (tools are per-account)
 ```
 

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

@@ -15,6 +15,7 @@
   - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
   - [Data Mode](#data-mode)
 - [Command Reference](#command-reference)
+  - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
 
 ## Getting Started
@@ -189,12 +190,12 @@ remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--
 remits-cli whoami [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
 remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
-remits-cli components stage [--branch <name>] [--workspace <name>] [--changed-only] [--data-mode test|prod] [--json|--verbose]
+remits-cli components stage [--workset | --changed-only] [--branch <name>] [--workspace <name>] [--empty-workset clear] [--data-mode test|prod] [--json|--verbose]   # default = FULL SNAPSHOT of the repo; --workset = only what git says changed, lane reconciled to it
 remits-cli workspace [show | use <name> | use --auto | clear]
 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] [--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 sync [--safe [--yes]] [--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 [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # --safe gates phase 2; it cannot un-push phase 1
 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]
@@ -251,8 +252,50 @@ For tests specifically:
   - `--names-only` — dry-run and print only `BUCKET type:id name` lines for the planned writes, then stop
     without writing overlays.
 
+  - `--safe` — the NAME for that combination, and the recommended agent path on a variant branch. It
+    expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves `--changed-since`
+    from this branch's merge base with trunk when you did not name one (local refs only — it never runs
+    an implicit `git fetch`, and refuses with the fetch command when nothing local can answer), and
+    prints the planned writes before mutating unless `--yes` is passed. On TRUNK there is no plan to
+    gate, so it states what a trunk reconcile does (every row rewritten from the repo; any live component
+    missing from the repo DELETED) and requires `--yes`. It does not override a narrower
+    `--expected-removed`.
+
   A good default for an unattended promotion is:
-  `remits-cli components sync --summary --changed-only --fail-on-errors`
+  `remits-cli components sync --safe`
+
+  When `--changed-only` refuses a plan far larger than your changed set, the usual cause is a branch that
+  is BEHIND trunk: it still physically carries old copies of files nobody on it touched, and a variant
+  sync turns each of those into an unrelated override. The refusal says so. Merge trunk in, push, re-run.
+
+### Staging modes: workset vs full snapshot
+
+`components stage` reports three numbers, and they answer three different questions:
+
+| Number | Question |
+|---|---|
+| **workset** | how many components git reports this working tree changed |
+| **submitted** | how many this command uploaded |
+| **overlay** | how many staged entries the lane now holds — **what a run resolves** |
+
+| Mode | Uploads | Lane afterwards |
+|---|---|---|
+| `components stage` (default) | the whole repository manifest | reconciled to the whole repo — a FULL SNAPSHOT |
+| `components stage --workset` | only the git-changed components | reconciled to exactly those |
+| `components stage --changed-only` | only the git-changed components | merged; earlier entries are left in place |
+
+`--workset` is the iteration mode. `--changed-only` keeps its long-standing merge semantics, so it cannot
+shrink a lane inherited from an earlier full stage; the command warns when it retains entries that way.
+`--changed-only --replace-lane` is the explicit spelling of `--workset`.
+
+An empty workset never clears a lane: `--workset` on a clean tree stages nothing and leaves the lane as
+it is. `--empty-workset clear` opts into the clear; `components clear --all` is the direct way.
+
+A deleted component file cannot be represented in Redis staging — clearing a staged entry falls back to
+the committed row, so the component still resolves. The command reports those changes as NOT
+REPRESENTABLE. On a non-trunk variant branch, prove a deletion through
+`components sync --dry-run --summary --fail-on-errors`; on trunk there is no dry-run plan, so use the
+full pre-sync safety check before any mutating reconcile.
 
 ### Prod banners and retryable failures
 

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

@@ -15,6 +15,7 @@
   - [When staged overrides apply](#when-staged-overrides-apply)
   - [Diagnosing which version is in play](#diagnosing-which-version-is-in-play)
   - [Working alongside other agents: the staging WORKSPACE](#working-alongside-other-agents-the-staging-workspace)
+  - [A lane holds an OVERLAY; your workset is a different number](#a-lane-holds-an-overlay-your-workset-is-a-different-number)
   - [Stage / sync / clear with remits-cli](#stage--sync--clear-with-remits-cli)
   - [Stale after sync / commit (the in-memory compile cache)](#stale-after-sync--commit-the-in-memory-compile-cache)
 
@@ -184,19 +185,60 @@ commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 - Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
   effect, check that line FIRST. A mismatched lane resolves committed source, which looks identical to
   "the stage did not work".
-- `remits-cli components status` lists every lane staged on the branch, so you can see whether another
-  agent is working alongside you.
+- `remits-cli components status` lists every lane staged on the branch AND every lane on the account, so
+  you can see whether another agent is working alongside you. Each row names its world (trunk or variant
+  branch), its overlay, its workset where known, and whether it is the SHARED lane.
 - `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
 
+### A lane holds an OVERLAY; your workset is a different number
+
+This is the distinction that decides whether a lane is legible to anyone but you.
+
+- The **overlay** is every staged entry the lane currently holds. It is what a CLI-scoped run resolves,
+  and it is the number the console shows as "staged".
+- The **workset** is what git reports this working tree changed. It is the work in flight.
+
+A plain `components stage` is a FULL SNAPSHOT: it uploads the whole repository manifest and reconciles
+the lane to it, so on a 115-component repo the overlay is 115 whether you edited five components or all
+of them. That is safe — it is a complete, known state — but it is a poor signal. Everyone reading the
+console sees a lane that looks like 115 edits in flight, and all 115 entries shadow committed source for
+every run in that lane until they expire.
+
+`components stage --workset` uploads only the changed components and reconciles the lane to exactly
+them, so the overlay IS the workset. That is the mode to iterate in.
+
+`components stage --changed-only` uploads the same narrow set but MERGES: it deliberately leaves every
+other staged entry alone. So it can never shrink a lane inherited from an earlier full snapshot — the
+overlay stays at 115 while you work on seven. The command warns when entries are retained that way.
+
+Every count is `unknown` rather than `0` when it cannot be established. "git could not answer" and "git
+says nothing changed" are different facts and only one of them is a number.
+
+**Deletion is not expressible here.** There is no staged removal: clearing a staged entry falls back to
+the committed row, so the component still resolves. `stage --workset` reports a deleted component file as
+NOT REPRESENTABLE rather than quietly omitting it. On a non-trunk variant branch, prove a deletion
+through the durable variant plan — `remits-cli components sync --dry-run --summary --fail-on-errors` —
+and read the removed/tombstone bucket. On trunk there is no dry-run plan; a deletion is only proven by
+the full pre-sync safety check before a mutating reconcile.
+
+**An empty workset never clears the lane.** `--workset` on a clean tree stages nothing and leaves the
+lane as it is; reconciling to an empty manifest would delete the overlay the next run depends on.
+Clearing stays explicit (`components clear --all`), or `--empty-workset clear` if that really is what you
+meant.
+
 ### Stage / sync / clear with remits-cli
 
-- `remits-cli components stage` writes local file changes into the Redis staging cache for the current
-  branch/user/workspace scope. This is the normal edit/test loop.
-- `remits-cli components stage --changed-only` stages just the components this working tree edited. It
-  does NOT reconcile, so entries for components it did not mention are left alone rather than deleted.
-  Useful on a large repo; a full stage is still the default and the safest.
-- `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.
+- `remits-cli components stage --workset` stages exactly what git says this working tree changed and
+  reconciles the lane to it. **The normal iteration mode.**
+- `remits-cli components stage` stages the whole repository manifest (a full snapshot). Use it for a
+  deliberate complete snapshot, when a `.meta.yml` key you deleted must be reconciled against the whole
+  repo, or as a "what is stale in here?" reset — then clear when you are done.
+- `remits-cli components stage --changed-only` stages just the changed components and does NOT reconcile,
+  so entries it did not mention are left alone rather than deleted. Kept as-is for compatibility;
+  `--workset` is the same narrow upload with the lane reconciled.
+- `remits-cli components status` shows which branch/variant world the checkout resolves, whether the lane
+  is shared, the overlay/workset/retained split with the last stage's mode, 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

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

@@ -16,11 +16,14 @@
     - [Step 1: Understand the Request](#step-1-understand-the-request)
     - [Step 2: Make the Change](#step-2-make-the-change)
     - [Step 3: Stage to Platform](#step-3-stage-to-platform)
+      - [Stage your workset, not the whole repo](#stage-your-workset-not-the-whole-repo)
+      - [Three numbers, three questions](#three-numbers-three-questions)
     - [Step 4: Verify the Change](#step-4-verify-the-change)
     - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
     - [Step 6: Update Documentation](#step-6-update-documentation)
     - [Temporary Experiment Workflow](#temporary-experiment-workflow)
     - [Step 7: Commit and Durable Sync](#step-7-commit-and-durable-sync)
+      - [Verifying the COMMITTED variant, not your staging](#verifying-the-committed-variant-not-your-staging)
     - [Step 8: Close the Ticket](#step-8-close-the-ticket)
   - [User Confirmation Preferences](#user-confirmation-preferences)
 
@@ -174,10 +177,63 @@ overlay instead of pruning cleanly.
 #### Step 3: Stage to Platform
 
 ```bash
-remits-cli components stage
+remits-cli workspace use --auto          # once per checkout: your own lane
+remits-cli components stage --workset    # every edit: stage what you changed
 ```
 
-This uploads your local file changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+This uploads your local component changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+
+##### Stage your workset, not the whole repo
+
+There are three stage modes, and the difference decides what a run in your lane resolves and what a
+human watching the console sees:
+
+| Command | What it uploads | What the lane holds afterwards |
+|---|---|---|
+| `components stage --workset` | only the components git reports changed | **exactly those** — the lane is reconciled to your workset |
+| `components stage` | the whole repository manifest | **every component in the repo** (a full snapshot) |
+| `components stage --changed-only` | only the changed components | the changed ones **merged into whatever was already there** |
+
+**Use `--workset` for normal iteration.** A full stage is correct and safe, but on a real repository it
+puts a hundred-plus components into your lane, and every one of them then shadows committed source for
+any run in that lane until it expires. A human looking at `/admin/platforms` sees "115 staged" and cannot
+tell whether you edited 115 components or five.
+
+`--changed-only` MERGES. It cannot shrink a lane it inherited from an earlier full stage, so a lane can
+sit at 115 overlay entries while you are working on seven. The command warns when that happens; the fix
+is `--workset` (or `components clear --all` once, then keep using `--workset`).
+
+**When a full stage is the right answer:**
+
+- you deliberately want a complete snapshot of the repo in the lane;
+- you changed a `.meta.yml` sidecar and want removed keys reconciled against the whole repo;
+- you cannot tell what is stale in the lane and want a clean, known state (then `components clear --all`
+  when you are done).
+
+**An empty workset never clears your lane.** `--workset` on a clean working tree stages nothing and
+leaves the lane alone — reconciling to an empty manifest would delete the overlay your next test run
+depends on. Clearing stays explicit: `components clear --all`.
+
+**Deleting a component file cannot be verified by staging.** There is no staged "removal": clearing a
+staged entry falls back to the committed row, so the component still resolves. `stage --workset` reports
+those changes as NOT REPRESENTABLE.
+
+On a non-trunk variant branch, prove the removal through the durable variant plan:
+`remits-cli components sync --dry-run --summary --fail-on-errors` and read the removed/tombstone bucket.
+On trunk there is no dry-run plan; treat deletion as a high-risk durable reconcile and pass the full
+pre-sync safety check before running any mutating sync.
+
+##### Three numbers, three questions
+
+`components stage` and `components status` report all three, and so does the admin console. They are not
+interchangeable:
+
+- **workset** — components git reports this working tree changed. The work in flight.
+- **submitted** — what this command uploaded.
+- **overlay** — every staged entry the lane now holds. **This is what a run resolves.**
+
+A missing answer is printed as `unknown`, never as `0`: "git could not answer" and "git says nothing
+changed" are different facts and only one of them is a number.
 
 **THE STAGE-BEFORE-RUN RULE:** You MUST run `remits-cli components stage` after EVERY file edit and BEFORE any test run or verification. The platform executes whatever version is in the staging cache at the moment the test starts. If you edit a file and run a test without staging first, the test runs the OLD code — not your changes. This is the single most common mistake. Never skip staging. The sequence is always: **edit → stage → run**.
 
@@ -310,13 +366,16 @@ Redis cache can affect later test/tool runs, so always clear it after restoring
 
 ```bash
 # make temporary local edit
-remits-cli components stage
+remits-cli components stage --workset
 remits-cli test run --test <id-or-name> --names "<case name>"
 git restore <file>
 remits-cli components clear --all
 remits-cli components status
 ```
 
+With `--workset` the restore-and-clear is belt and braces rather than the only thing standing between
+the experiment and a later run: the lane only ever held the component you were experimenting on.
+
 For narrower cleanup when only one staged component should be cleared:
 
 ```bash
@@ -352,10 +411,41 @@ IDs or when unexpected deletes/renumbers are present.
 Only after those checks pass, and only when the user intends to promote the repo to the platform database:
 
 ```bash
+# On a VARIANT branch — the recommended path. Dry-runs first and refuses a surprising plan.
+remits-cli components sync --safe
+git pull --ff-only origin <branch>
+
+# On TRUNK — there is no plan to gate, so --safe explains what a trunk reconcile does and needs --yes.
 remits-cli components sync
 git pull --ff-only origin <branch>
 ```
 
+`--safe` expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves the
+comparison base from this branch's merge base with trunk when you did not pass `--changed-since`, and
+prints the planned writes before mutating unless you pass `--yes`. It refuses when the plan would write
+components this checkout did not change — which is exactly what a branch that is BEHIND trunk produces,
+because it still physically carries old copies of files nobody on it touched, and a variant sync turns
+each of those into an unrelated override. When it refuses that way, merge trunk into your branch, push,
+and re-run the same command.
+
+When a removal is intended, name it rather than disabling the gate:
+
+```bash
+remits-cli components sync --safe --expected-removed action:50
+```
+
+`--force-tombstones` stays explicit and human-owned. Never pass it to get past a refusal.
+
+##### Verifying the COMMITTED variant, not your staging
+
+After a sync, staged entries still win for CLI-scoped runs, so a test that passes may be testing your
+staging rather than what you just committed. Clear the lane first:
+
+```bash
+remits-cli components clear --all
+remits-cli test run --test <id-or-name> --as-account <subscriber-id>
+```
+
 `remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations,
 and it is capable of reconciling creates/deletes/renames from the remote repository into the database. Treat it
 as a gated promote/reconciliation command, not as an exploratory command or fallback.