@remits/remits-cli 0.1.115 → 0.1.117

package/index.js

@@ -544,6 +544,8 @@ function localStatePaths(cwd) {
     toolsDir: path.join(base, 'tools'),
     sessionsDir: path.join(base, 'sessions'),
     toolResponsesDir: path.join(base, 'tool-responses'),
+    verificationDir: path.join(base, 'verification'),
+    activeVerificationFile: path.join(base, 'verification', 'active'),
     currentSessionFile: path.join(base, 'current-session.txt'),
     workspaceFile: path.join(base, 'workspace')
   };
@@ -649,6 +651,7 @@ function ensureLocalState(cwd) {
   ensureDir(paths.toolsDir);
   ensureDir(paths.sessionsDir);
   ensureDir(paths.toolResponsesDir);
+  ensureDir(paths.verificationDir);
   return paths;
 }
 
@@ -755,6 +758,196 @@ function readToolResponseFile(cwd, callId) {
   }
 }
 
+function verificationPaths(cwd, envelopeId) {
+  const paths = ensureLocalState(cwd);
+  const base = envelopeId ? path.join(paths.verificationDir, String(envelopeId)) : paths.verificationDir;
+  return {
+    root: paths.verificationDir,
+    activeFile: paths.activeVerificationFile,
+    base,
+    envelopeFile: path.join(base, 'envelope.json'),
+    manifestFile: path.join(base, 'manifest.json'),
+    packetsDir: path.join(base, 'packets')
+  };
+}
+
+function readActiveVerificationEnvelope(cwd) {
+  const file = verificationPaths(cwd).activeFile;
+  try {
+    if (!fs.existsSync(file)) return null;
+    const id = fs.readFileSync(file, 'utf8').trim();
+    return id || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeActiveVerificationEnvelope(cwd, envelopeId) {
+  const paths = verificationPaths(cwd);
+  if (!envelopeId) {
+    try { if (fs.existsSync(paths.activeFile)) fs.unlinkSync(paths.activeFile); } catch (_) { /* best-effort */ }
+    return null;
+  }
+  atomicWriteFile(paths.activeFile, String(envelopeId) + '\n');
+  return String(envelopeId);
+}
+
+function verificationEnvelopeIdForCommand(cwd, flags = {}) {
+  if (flagEnabled(flags['no-verify-envelope']) || flagEnabled(flags.noVerifyEnvelope)) return null;
+  const explicit = flags['verify-envelope'] || flags.verifyEnvelope || flags.envelope;
+  if (explicit !== undefined && explicit !== null && explicit !== true) return String(explicit).trim() || null;
+  return readActiveVerificationEnvelope(cwd);
+}
+
+function writeLocalVerificationEnvelope(cwd, envelope) {
+  if (!envelope || !envelope.envelopeId) return null;
+  const paths = verificationPaths(cwd, envelope.envelopeId);
+  ensureDir(paths.base);
+  ensureDir(paths.packetsDir);
+  atomicWriteFile(paths.envelopeFile, JSON.stringify(envelope, null, 2));
+  if (envelope.acceptance) {
+    atomicWriteFile(paths.manifestFile, JSON.stringify(envelope.acceptance, null, 2));
+  }
+  (envelope.packets || []).forEach((packet) => writeLocalVerificationPacket(cwd, envelope.envelopeId, packet));
+  return paths.envelopeFile;
+}
+
+function readLocalVerificationEnvelope(cwd, envelopeId) {
+  const paths = verificationPaths(cwd, envelopeId);
+  if (!fs.existsSync(paths.envelopeFile)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(paths.envelopeFile, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeLocalVerificationPacket(cwd, envelopeId, packet) {
+  if (!envelopeId || !packet) return null;
+  const paths = verificationPaths(cwd, envelopeId);
+  ensureDir(paths.packetsDir);
+  const packetId = packet.packetId || ('local-' + crypto.randomUUID());
+  const file = path.join(paths.packetsDir, packetId + '.json');
+  atomicWriteFile(file, JSON.stringify(Object.assign({}, packet, { packetId }), null, 2));
+  return file;
+}
+
+function parseManifestFile(file) {
+  const resolved = path.resolve(process.cwd(), String(file));
+  const text = fs.readFileSync(resolved, 'utf8');
+  if (resolved.endsWith('.yml') || resolved.endsWith('.yaml')) {
+    return YAML.parse(text);
+  }
+  return JSON.parse(text);
+}
+
+function sha256File(file) {
+  const resolved = path.resolve(process.cwd(), String(file));
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(resolved));
+  const stat = fs.statSync(resolved);
+  return { path: resolved, sha256: hash.digest('hex'), size: stat.size };
+}
+
+function safeGitValue(cwd, command) {
+  try {
+    return runGit(cwd, command);
+  } catch (_) {
+    return null;
+  }
+}
+
+function collectVerificationSource(cwd, flags = {}) {
+  const branchName = flags.branch || currentBranch(cwd);
+  return {
+    workingDirectory: cwd,
+    gitBranch: branchName,
+    gitHead: safeGitValue(cwd, 'git rev-parse HEAD'),
+    originHead: safeGitValue(cwd, 'git rev-parse ' + shellQuote('origin/' + branchName)),
+    mergeBase: safeGitValue(cwd, 'git merge-base HEAD ' + shellQuote('origin/' + branchName)),
+    workspace: resolveWorkspace(cwd, flags),
+    workspaceSource: workspaceSource(cwd, flags),
+    stagingLane: branchName + ':' + (resolveWorkspace(cwd, flags) || 'shared'),
+    sourceLayer: 'unknown'
+  };
+}
+
+function collectVerificationAccount(cwd, accountId, baseUrl, dataMode) {
+  const info = loadAccountInfo(cwd) || {};
+  const resolution = info.resolution || info.repoContext || {};
+  return {
+    repoAccountId: Number(accountId || accountIdFromAccountInfo(info)) || null,
+    executionAccountId: resolution.executionAccountId || resolution.accountId || accountId || null,
+    addressedAccountId: resolution.addressedAccountId || resolution.accountId || accountId || null,
+    componentOwnerAccountId: resolution.componentOwnerAccountId || resolution.ownerAccountId || null,
+    resolvedDatabaseName: resolution.resolvedDatabaseName || resolution.databaseName || null,
+    host: resolution.resolvedDomainName || resolution.host || normalizeBaseUrl(baseUrl),
+    dataMode,
+    dataModeSource: 'cli',
+    accountRole: resolution.role || null,
+    accountType: resolution.type || null,
+    testAccount: resolution.testAccount === true || info.testAccount === true
+  };
+}
+
+async function postVerificationCommand(api, cwd, session, accountId, command, payload) {
+  const response = await loggedPost(api, cwd, '/cli/verification', Object.assign({
+    token: session.token,
+    accountId,
+    command
+  }, payload || {})).then((r) => r.data);
+  if (!response.success) {
+    throw new Error(response.message || 'Verification command failed');
+  }
+  return response;
+}
+
+async function appendVerificationPacket(api, cwd, session, accountId, flags, packet, options = {}) {
+  const envelopeId = verificationEnvelopeIdForCommand(cwd, flags);
+  if (!envelopeId) return null;
+  const finalPacket = Object.assign({
+    packetId: crypto.randomUUID(),
+    createdAt: new Date().toISOString(),
+    success: true
+  }, packet || {});
+  finalPacket.envelopeId = envelopeId;
+  writeLocalVerificationPacket(cwd, envelopeId, finalPacket);
+  try {
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'packet', {
+      envelopeId,
+      packet: finalPacket
+    });
+    if (response.packet) writeLocalVerificationPacket(cwd, envelopeId, response.packet);
+    if (response.envelope) writeLocalVerificationEnvelope(cwd, response.envelope);
+    if (!options.quiet) console.log('Verification envelope:', envelopeId, '(packet ' + finalPacket.type + ' attached)');
+    return response;
+  } catch (err) {
+    if (!options.quiet) {
+      console.error('Verification evidence captured locally but not attached to the platform envelope:', describeError(err));
+    }
+    return { localOnly: true, envelopeId, packet: finalPacket };
+  }
+}
+
+function buildCommandWorld(response, fallback = {}) {
+  const source = (response && response.staging) || {};
+  const resolution = (response && response.resolution) || {};
+  return {
+    accountId: response && (response.accountId || response.ownerAccountId) || fallback.accountId,
+    executionAccountId: response && (response.executionAccountId || response.accountId) || resolution.executionAccountId || fallback.executionAccountId,
+    addressedAccountId: resolution.addressedAccountId || fallback.addressedAccountId,
+    host: fallback.host,
+    dataMode: response && response.dataMode || fallback.dataMode,
+    dataModeSource: response && response.dataModeSource || fallback.dataModeSource,
+    branchName: response && response.branchName || fallback.branchName,
+    workspace: response && response.workspace !== undefined ? response.workspace : fallback.workspace,
+    stagingLane: response && response.stagingLane || source.stagingLane || fallback.stagingLane,
+    componentBranch: resolution.componentBranch || response && response.variantBranch || fallback.componentBranch,
+    variantId: resolution.variantId || fallback.variantId,
+    sourceLayer: fallback.sourceLayer || (source.testComponentSource === 'staged' ? 'staged' : undefined)
+  };
+}
+
 function normalizeName(name) {
   return name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/\s+/g, ' ').trim();
 }
@@ -2458,12 +2651,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 +2682,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 +2723,45 @@ 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;
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'stage',
+    success: response.success !== false,
+    claim: 'Components staged for verification',
+    world: buildCommandWorld(response, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: 'staged' }),
+    revision: collectVerificationSource(cwd, flags),
+    assertions: [
+      { category: 'stage', stageMode },
+      { category: 'staging_lane', value: response.stagingLane }
+    ],
+    evidenceCategories: ['stage', 'staging_lane'],
+    rawRefs: { command: 'components stage' },
+    stage: response.stage,
+    laneSummary: response.laneSummary,
+    changedFromWorkingTree: response.changedFromWorkingTree,
+    unrepresentableChanges: response.unrepresentableChanges
+  }, { quiet: flagEnabled(flags.json) });
 
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(response, null, 2));
@@ -2520,11 +2772,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 +2896,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 +2957,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)');
+  }
+
+  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);
   }
-  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 (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)');
   }
-  if (response.staging) {
-    console.log('Total staged entries for this branch/user:', response.staging.remainingCount || 0);
+
+  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 +3040,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 +3108,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');
@@ -2820,6 +3245,17 @@ async function statusComponentsCommand(flags) {
     throw new Error(response.message || 'Staging status failed');
   }
 
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'component_status',
+    success: true,
+    claim: 'Component status observed',
+    world: buildCommandWorld(response, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl) }),
+    revision: collectVerificationSource(cwd, flags),
+    evidenceCategories: ['component_status'],
+    rawRefs: { command: 'components status' },
+    componentStatus: response
+  }, { quiet: flagEnabled(flags.json) });
+
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(response, null, 2));
     return response;
@@ -2887,8 +3323,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 +3376,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 +3392,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,9 +3460,26 @@ 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;
 
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: response.sync && response.sync.dryRun ? 'sync_dry_run' : 'sync_mutation',
+    success: response.success !== false,
+    claim: response.sync && response.sync.dryRun ? 'Component sync dry-run observed' : 'Component sync completed',
+    world: buildCommandWorld(response, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: response.sync && response.sync.mode === 'variant' ? 'variant' : 'trunk' }),
+    revision: Object.assign(collectVerificationSource(cwd, flags), {
+      platformSyncedSha: response.sync && (response.sync.postSyncSha || response.sync.branchHeadSha)
+    }),
+    evidenceCategories: [response.sync && response.sync.dryRun ? 'sync_dry_run' : 'sync_mutation'],
+    assertions: [
+      { category: response.sync && response.sync.dryRun ? 'sync_dry_run' : 'sync_mutation', summary }
+    ],
+    rawRefs: { command: 'components sync' },
+    sync: response.sync,
+    summary
+  }, { quiet: flagEnabled(flags.json) });
+
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(flagEnabled(flags.summary) ? summary : response, null, 2));
     failOnSyncGate(gate);
@@ -3093,8 +3587,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 +3773,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 +4285,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,
@@ -4026,6 +4602,30 @@ async function testCommand(flags) {
   } else if (status.result && status.result.failed > 0) {
     process.exitCode = 1;
   }
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'test_run',
+    success: status.status === 'completed' && !(status.result && status.result.failed > 0) && !unmatched.length,
+    claim: 'Test run ' + String(testRef),
+    world: buildCommandWorld(status, { accountId, dataMode: status.dataMode || dataMode, dataModeSource, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: status.staging && status.staging.testComponentSource }),
+    revision: Object.assign(collectVerificationSource(cwd, flags), {
+      compileSignatures: status.staging && status.staging.testComponentSignature ? [status.staging.testComponentSignature] : []
+    }),
+    test: {
+      taskId: start.taskId,
+      testId: status.test && status.test.id,
+      testName: status.test && status.test.name,
+      selectedCases: names,
+      passed: status.result && status.result.passed,
+      failed: status.result && status.result.failed,
+      dataModeSource: status.dataModeSource || dataModeSource,
+      unmatchedTestNames: unmatched
+    },
+    evidenceCategories: ['test_run'].concat(names.map((name) => 'test_run.' + name)),
+    limitations: unmatched.length ? ['One or more requested test case selectors matched no case.'] : [],
+    rawRefs: { testStatusKey: start.taskId },
+    status
+  });
 }
 
 async function tokenCommand(flags) {
@@ -4114,6 +4714,21 @@ async function tokenCommand(flags) {
 
   printSessionResolutionWarning(sessionContext);
   console.log(JSON.stringify(output, null, 2));
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'token_inspect',
+    success: true,
+    claim: 'Verification token minted',
+    world: buildCommandWorld(output, { accountId: output.accountId || accountId, dataMode: output.dataMode || dataMode, branchName, workspace: output.workspace, host: normalizeBaseUrl(baseUrl) }),
+    revision: collectVerificationSource(cwd, flags),
+    browser: {
+      tokenKeyHash: output.tokenKey ? sha256(String(output.tokenKey)) : null,
+      urlHash: output.embeddableUrl ? sha256(String(output.embeddableUrl)) : null,
+      liveUrl: flagEnabled(flags['store-url']) ? output.embeddableUrl : undefined
+    },
+    evidenceCategories: ['token_inspect'],
+    token: Object.assign({}, output, { tokenKey: output.tokenKey ? '[redacted]' : undefined, embedTokenKey: output.embedTokenKey ? '[redacted]' : undefined })
+  });
 }
 
 async function tokenInspectCommand(flags) {
@@ -4143,6 +4758,19 @@ async function tokenInspectCommand(flags) {
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log(JSON.stringify(data, null, 2));
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'token_inspect',
+    success: true,
+    claim: 'Token inspected',
+    world: buildCommandWorld(data.safety || {}, { accountId: data.context && data.context.accountId || accountId, dataMode: data.safety && data.safety.dataMode, host: normalizeBaseUrl(baseUrl) }),
+    revision: collectVerificationSource(cwd, flags),
+    browser: {
+      tokenKeyHash: data.token && data.token.tokenKey ? sha256(String(data.token.tokenKey)) : null
+    },
+    evidenceCategories: ['token_inspect'],
+    tokenInspect: data
+  });
 }
 
 async function toolsCommand(flags) {
@@ -4313,6 +4941,17 @@ async function toolCommand(flags) {
       console.log('Tool error:', data.toolMessage || toolResultMessage(data.result));
     }
     if (data.status === 'failed' || polledFailed) process.exitCode = 1;
+    await appendVerificationPacket(api, cwd, session, accountId, flags, {
+      type: 'tool_call',
+      success: data.status !== 'failed' && !polledFailed,
+      claim: 'Tool status ' + requestedCallId,
+      world: buildCommandWorld(data, { accountId: statusAccountId, dataMode: data.dataMode || dataMode, branchName: flags.branch || (stored && stored.branchName) || branchName, host: normalizeBaseUrl(baseUrl) }),
+      revision: collectVerificationSource(cwd, flags),
+      evidenceCategories: ['tool_call'],
+      rawRefs: { toolResponsePath: statusResponse.responseFile, callId: requestedCallId },
+      tool: { callId: requestedCallId, status: data.status, name: stored && stored.name },
+      result: data
+    });
     return;
   }
 
@@ -4395,6 +5034,274 @@ async function toolCommand(flags) {
       process.exitCode = 1;
     }
   }
+
+  await appendVerificationPacket(api, cwd, session, accountId, flags, {
+    type: 'tool_call',
+    success: !toolFailed && (!asyncMode || !waitForAsync || process.exitCode !== 1),
+    claim: 'Tool call ' + String(toolName),
+    world: buildCommandWorld(data, { accountId: data.accountId || accountId, dataMode: data.dataMode || dataMode, branchName: data.branchName || branchName, workspace: resolveWorkspace(cwd, flags), host: normalizeBaseUrl(baseUrl), sourceLayer: data.componentSource }),
+    revision: Object.assign(collectVerificationSource(cwd, flags), {
+      compileSignatures: data.componentSignature ? [data.componentSignature] : []
+    }),
+    evidenceCategories: ['tool_call'],
+    dependencies: {
+      mocks: [],
+      liveHttpCalls: data.liveHttpCalls || []
+    },
+    rawRefs: { toolResponsePath: response.responseFile, callId },
+    tool: { callId, name: String(toolName), async: asyncMode, status: data.status, toolSuccess: data.toolSuccess },
+    result: data
+  });
+}
+
+async function verifyCommand(flags, subcommand) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sub = String(subcommand || (flags._ && flags._[1]) || 'status').toLowerCase();
+
+  if (sub === 'current') {
+    const active = readActiveVerificationEnvelope(cwd);
+    if (!active) {
+      console.log('No active verification envelope in this checkout.');
+      return;
+    }
+    console.log('Active verification envelope:', active);
+    const local = readLocalVerificationEnvelope(cwd, active);
+    if (local && local.summary) console.log('Summary:', local.summary);
+    return;
+  }
+
+  if (sub === 'use') {
+    const envelopeId = flags._ && flags._[2] || flags.envelope || flags['verify-envelope'];
+    if (!envelopeId) throw new Error('Usage: remits-cli verify use <envelopeId>');
+    writeActiveVerificationEnvelope(cwd, envelopeId);
+    console.log('Active verification envelope:', envelopeId);
+    return;
+  }
+
+  if (sub === 'clear') {
+    writeActiveVerificationEnvelope(cwd, null);
+    console.log('Verification envelope cleared for this checkout.');
+    return;
+  }
+
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const dataMode = resolveDataMode(flags, session);
+  const branchName = flags.branch || currentBranch(cwd);
+  const workspace = resolveWorkspace(cwd, flags);
+  const api = buildAxios(baseUrl, session.token);
+
+  if (sub === 'start') {
+    const summary = flags.summary || flags._ && flags._.slice(2).join(' ');
+    if (!summary) throw new Error('verify start requires --summary "..."');
+    let manifest = {};
+    if (flags.manifest || flags.file) {
+      manifest = parseManifestFile(flags.manifest || flags.file);
+    }
+    let statusResponse = null;
+    try {
+      statusResponse = await loggedPost(api, cwd, '/cli/components', {
+        token: session.token,
+        accountId,
+        branchName,
+        workspace,
+        dataMode,
+        mode: 'status'
+      }).then((r) => r.data);
+    } catch (_) { /* best-effort */ }
+
+    const source = collectVerificationSource(cwd, flags);
+    if (statusResponse) {
+      source.componentBranch = statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : branchName;
+      source.sourceLayer = statusResponse.laneSummary && statusResponse.laneSummary.stagedCount > 0
+        ? 'staged' : (statusResponse.branchContext && statusResponse.branchContext.onTrunk ? 'trunk' : 'variant');
+      source.stagedOverlayHash = statusResponse.laneSummary ? sha256(stableStringify(statusResponse.laneSummary)) : null;
+    }
+
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'start', {
+      summary,
+      ticketId: flags.ticket,
+      account: collectVerificationAccount(cwd, accountId, baseUrl, dataMode),
+      source,
+      manifest
+    });
+    const envelope = response.envelope;
+    writeLocalVerificationEnvelope(cwd, envelope);
+    writeActiveVerificationEnvelope(cwd, envelope.envelopeId);
+    console.log('Verification envelope started:', envelope.envelopeId);
+    console.log('Target:', 'account=' + accountId + ', branch=' + branchName + ', workspace=' + (workspace || 'shared') + ', dataMode=' + dataMode);
+    console.log('Local mirror:', verificationPaths(cwd, envelope.envelopeId).base);
+    return envelope;
+  }
+
+  const envelopeId = flags.envelope || flags['verify-envelope'] || flags.id || readActiveVerificationEnvelope(cwd);
+  if (!envelopeId) {
+    throw new Error('No verification envelope selected. Run `remits-cli verify start --summary "..."` or pass --envelope <id>.');
+  }
+
+  if (sub === 'manifest') {
+    if (flagEnabled(flags.print)) {
+      const local = readLocalVerificationEnvelope(cwd, envelopeId);
+      const response = await postVerificationCommand(api, cwd, session, accountId, 'show', { envelopeId })
+        .catch(() => ({ envelope: local }));
+      const manifest = response.envelope && response.envelope.acceptance;
+      console.log(JSON.stringify(manifest || {}, null, 2));
+      return manifest;
+    }
+    const file = flags.file || flags.manifest;
+    if (!file) throw new Error('verify manifest requires --file <manifest.json> or --print');
+    const manifest = parseManifestFile(file);
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'manifest', { envelopeId, manifest });
+    writeLocalVerificationEnvelope(cwd, response.envelope);
+    console.log('Manifest attached to envelope:', envelopeId);
+    console.log('Required evidence:', (((response.envelope || {}).acceptance || {}).requiredEvidence || []).length);
+    return response.envelope;
+  }
+
+  if (sub === 'show' || sub === 'read' || sub === 'get' || sub === 'packets') {
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'show', { envelopeId });
+    if (response.envelope) writeLocalVerificationEnvelope(cwd, response.envelope);
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify(response.envelope || response, null, 2));
+      return response.envelope || response;
+    }
+    const envelope = response.envelope || {};
+    console.log('Verification envelope:', envelope.envelopeId || envelopeId);
+    if (envelope.summary) console.log('Summary:', envelope.summary);
+    console.log('Status:', envelope.status || 'unknown');
+    const packets = Array.isArray(envelope.packets) ? envelope.packets : [];
+    console.log('Packets:', packets.length);
+    packets.forEach((packet) => {
+      console.log('- ' + (packet.type || 'unknown') + ' ' + (packet.packetId || '') + (packet.success === false ? ' failed' : ''));
+    });
+    return envelope;
+  }
+
+  if (sub === 'attach') {
+    const artifacts = [];
+    let type = 'manual_observation';
+    const label = flags.label || flags.name || 'attached evidence';
+    if (flags.artifact) {
+      type = 'artifact';
+      artifacts.push(Object.assign({ label, kind: 'artifact', source: 'local_path' }, sha256File(flags.artifact)));
+    }
+    if (flags.screenshot) {
+      type = 'artifact';
+      artifacts.push(Object.assign({ label, kind: 'screenshot', source: 'local_path' }, sha256File(flags.screenshot)));
+    }
+    const note = flags.note || flags.message;
+    if (!artifacts.length && !note) {
+      throw new Error('verify attach requires --artifact <path>, --screenshot <path>, or --note "..."');
+    }
+    const packet = {
+      type,
+      success: true,
+      claim: note || label,
+      artifacts,
+      evidenceCategories: artifacts.map((a) => a.kind === 'screenshot' ? 'screenshot' : 'artifact.sha256')
+    };
+    const response = await appendVerificationPacket(api, cwd, session, accountId, { 'verify-envelope': envelopeId }, packet);
+    console.log('Evidence attached:', (response.packet || packet).packetId);
+    return response;
+  }
+
+  if (sub === 'browser-start' || sub === 'browser-step' || sub === 'browser-snapshot') {
+    const url = flags.url || flags.token || flags._ && flags._[2];
+    const action = flags.action || (sub === 'browser-start' ? 'open' : (sub === 'browser-snapshot' ? 'snapshot' : 'observe'));
+    const packet = {
+      type: sub === 'browser-start' ? 'browser_session' : (sub === 'browser-snapshot' ? 'browser_snapshot' : 'browser_step'),
+      success: !flagEnabled(flags.failed),
+      claim: flags.claim || flags.label || action,
+      world: buildCommandWorld(null, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl) }),
+      browser: {
+        action,
+        target: flags.target,
+        value: flags.value,
+        urlHash: url ? sha256(String(url)) : null,
+        liveUrl: flagEnabled(flags['store-url']) ? url : undefined,
+        interactionKind: flags.kind || (['click', 'fill', 'select', 'upload', 'reload'].includes(String(action)) ? 'user_interaction' : 'observation')
+      },
+      evidenceCategories: [sub, action === 'upload' ? 'browser_session.actual_upload' : null, action === 'click' ? 'browser_session.actual_clicks' : null]
+        .filter(Boolean)
+    };
+    const response = await appendVerificationPacket(api, cwd, session, accountId, { 'verify-envelope': envelopeId }, packet);
+    console.log('Browser evidence attached:', (response.packet || packet).packetId);
+    return response;
+  }
+
+  if (sub === 'test') {
+    return await testCommand(Object.assign({}, flags, { 'verify-envelope': envelopeId }));
+  }
+  if (sub === 'token') {
+    return await tokenCommand(Object.assign({}, flags, { 'verify-envelope': envelopeId }));
+  }
+  if (sub === 'stage') {
+    return await pushComponentsCommand(Object.assign({}, flags, { 'verify-envelope': envelopeId }));
+  }
+  if (sub === 'sync') {
+    return await syncComponentsCommand(Object.assign({}, flags, { 'verify-envelope': envelopeId }));
+  }
+  if (sub === 'tool') {
+    return await toolCommand(Object.assign({}, flags, { 'verify-envelope': envelopeId }));
+  }
+
+  if (sub === 'invalidate') {
+    const reason = flags.reason || flags.message || flags._ && flags._.slice(2).join(' ') || 'manually invalidated';
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'invalidate', { envelopeId, reason });
+    writeLocalVerificationEnvelope(cwd, response.envelope);
+    console.log('Envelope marked stale:', envelopeId);
+    return response.envelope;
+  }
+
+  if (sub === 'status' || sub === 'report') {
+    let statusPacket = null;
+    try {
+      const componentStatus = await loggedPost(api, cwd, '/cli/components', {
+        token: session.token,
+        accountId,
+        branchName,
+        workspace,
+        dataMode,
+        mode: 'status'
+      }).then((r) => r.data);
+      statusPacket = {
+        type: 'component_status',
+        success: componentStatus.success !== false,
+        claim: 'Current component status for verification status check',
+        world: buildCommandWorld(componentStatus, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl) }),
+        revision: collectVerificationSource(cwd, flags),
+        assertions: [],
+        rawRefs: { command: 'components status' },
+        componentStatus
+      };
+      await appendVerificationPacket(api, cwd, session, accountId, { 'verify-envelope': envelopeId }, statusPacket, { quiet: true });
+    } catch (err) {
+      if (!flagEnabled(flags.json)) {
+        console.error('Warning: could not attach component_status packet before rendering report:', describeError(err));
+      }
+    }
+    const response = await postVerificationCommand(api, cwd, session, accountId, sub, {
+      envelopeId,
+      currentWorld: buildCommandWorld(statusPacket && statusPacket.componentStatus, {
+        accountId,
+        dataMode,
+        branchName,
+        workspace,
+        host: normalizeBaseUrl(baseUrl)
+      })
+    });
+    if (response.envelope) writeLocalVerificationEnvelope(cwd, response.envelope);
+    if (response.report) {
+      console.log(response.report);
+    } else if (response.evaluation || response.status) {
+      console.log(JSON.stringify(response, null, 2));
+    }
+    return response;
+  }
+
+  throw new Error('Unknown verify subcommand: ' + sub);
 }
 
 async function dataModeCommand(flags, subcommand) {
@@ -9854,6 +10761,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 +10779,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 +10822,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.');
@@ -9979,6 +10913,35 @@ function printTokenHelp() {
   console.log('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
+function printVerifyHelp() {
+  console.log('Usage: remits-cli verify <subcommand>');
+  console.log('');
+  console.log('Envelope lifecycle:');
+  console.log('  remits-cli verify start --summary "..." [--manifest file.json] [--ticket ID]');
+  console.log('  remits-cli verify use <envelopeId>');
+  console.log('  remits-cli verify current');
+  console.log('  remits-cli verify clear');
+  console.log('  remits-cli verify show [--envelope ID] [--json]');
+  console.log('  remits-cli verify status [--envelope ID]');
+  console.log('  remits-cli verify report [--envelope ID]');
+  console.log('');
+  console.log('Manifest and manual evidence:');
+  console.log('  remits-cli verify manifest --file file.json [--envelope ID]');
+  console.log('  remits-cli verify manifest --print [--envelope ID]');
+  console.log('  remits-cli verify attach --artifact path --label "..." [--envelope ID]');
+  console.log('  remits-cli verify attach --screenshot path --label "..." [--envelope ID]');
+  console.log('  remits-cli verify attach --note "..." [--envelope ID]');
+  console.log('');
+  console.log('Wrappers around existing commands:');
+  console.log('  remits-cli verify stage --workset');
+  console.log('  remits-cli verify test --test "..." [--names "case"]');
+  console.log('  remits-cli verify token --path /page');
+  console.log('  remits-cli verify sync --safe');
+  console.log('  remits-cli verify tool --name mcp_tool --input \'{...}\'');
+  console.log('');
+  console.log('Existing commands also accept --verify-envelope <id> and --no-verify-envelope.');
+}
+
 async function main() {
   migrateSessionIfNeeded();
   const originalArgv = process.argv.slice(2);
@@ -10029,7 +10992,7 @@ async function main() {
   // sure the repo has the latest guides — authenticating first if needed — so
   // only platform-authenticated users ever receive them. `auth` syncs its own
   // guides, so it is excluded here.
-  const GUIDE_SYNC_COMMANDS = new Set(['components', 'test', 'token', 'tools', 'tool']);
+  const GUIDE_SYNC_COMMANDS = new Set(['components', 'test', 'token', 'tools', 'tool', 'verify']);
   if (!wantsJson && !isHelpCmd && GUIDE_SYNC_COMMANDS.has(command)) {
     try { await ensureGuidesSynced(process.cwd(), args); } catch (_) { /* best-effort */ }
   }
@@ -10057,10 +11020,12 @@ 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 verify start --summary "..." [--manifest file.json]  # start a verification envelope');
+    console.log('  remits-cli verify [current|use|clear|status|report|attach|test|token|stage|sync|tool]');
+    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');
@@ -10138,6 +11103,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (wantsHelp && command === 'verify') {
+    printVerifyHelp();
+    process.exit(0);
+  }
+
   if (command === 'auth') {
     await authCommand(args);
     return;
@@ -10257,6 +11227,11 @@ async function main() {
     return;
   }
 
+  if (command === 'verify') {
+    await verifyCommand(args, subcommand);
+    return;
+  }
+
   if (command === 'test' && subcommand === 'run') {
     await testCommand(args);
     return;