@remits/remits-cli 0.1.116 → 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();
 }
@@ -2552,6 +2745,24 @@ async function pushComponentsCommand(flags) {
   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));
     return response;
@@ -3034,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;
@@ -3241,6 +3463,23 @@ async function syncComponentsCommand(rawFlags) {
   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);
@@ -4363,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) {
@@ -4451,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) {
@@ -4480,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) {
@@ -4650,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;
   }
 
@@ -4732,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) {
@@ -10343,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);
@@ -10393,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 */ }
   }
@@ -10421,6 +11020,8 @@ 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 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]');
@@ -10502,6 +11103,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (wantsHelp && command === 'verify') {
+    printVerifyHelp();
+    process.exit(0);
+  }
+
   if (command === 'auth') {
     await authCommand(args);
     return;
@@ -10621,6 +11227,11 @@ async function main() {
     return;
   }
 
+  if (command === 'verify') {
+    await verifyCommand(args, subcommand);
+    return;
+  }
+
   if (command === 'test' && subcommand === 'run') {
     await testCommand(args);
     return;

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -121,6 +121,11 @@ reference named after it.
   component (preferred, because it becomes regression protection) or a browser flow through
   `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
   cannot verify, say what you would need and ask. (`development-loop.md`)
+- **For concrete user workflows, start a verification envelope before you edit.** `remits-cli verify
+  start --summary "..."` records the account/source/lane tuple and a manifest when you have one.
+  Stage, test, token, tool, and sync commands attach evidence automatically while the envelope is
+  active; finish from `remits-cli verify report`, which separates verified claims from missing or stale
+  evidence. (`development-loop.md`, `component-resolution.md`)
 - **Read the component's `.meta.yml` before changing behavior.** Sidecar descriptions can be dated
   decision records. Before changing a displayed value, helper, calculation, schema field, or prompt
   contract, check the sidecar and either preserve its decision or explicitly supersede it.
@@ -162,6 +167,8 @@ remits-cli tools                  # which tools this account actually has (tools
 ```
 
 plus the repo's `account-info.json` → `resolution` block for the account's shape.
+For a workflow-shaped request, also run `remits-cli verify start --summary "..."` once the target tuple
+is understood, then keep that envelope active through stage/test/token/sync.
 
 If any command returns 401, run `remits-cli auth` (with the same `--base-url` if you were targeting a
 non-default host).

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)
+  - [Verification envelopes](#verification-envelopes)
   - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
 
@@ -209,8 +210,86 @@ remits-cli token inspect --token <token|tokenKey|URL>                  # inspect
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
 remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--variant-branch <name|none>] [--timeout-ms 60000] [--async true --wait true]
 remits-cli tool status --call-id <callId> [--data-mode test|prod]
+remits-cli verify start --summary "..." [--manifest file.json] [--ticket ID]
+remits-cli verify use <envelopeId>
+remits-cli verify current
+remits-cli verify clear
+remits-cli verify show [--envelope ID] [--json]
+remits-cli verify manifest --file file.json [--envelope ID]
+remits-cli verify manifest --print [--envelope ID]
+remits-cli verify attach --artifact path --label "..." [--envelope ID]
+remits-cli verify attach --screenshot path --label "..." [--envelope ID]
+remits-cli verify attach --note "..." [--envelope ID]
+remits-cli verify browser-start --url URL [--label "..."]
+remits-cli verify browser-step [--action click|fill|upload|reload|observe|...] [--target "..."] [--value "..."] [--url URL] [--label "..."]
+remits-cli verify browser-snapshot [--url URL] [--label "..."]
+remits-cli verify stage --workset
+remits-cli verify test --test <id|name> [--names "case"]
+remits-cli verify token --path <embeddablePathOrId>
+remits-cli verify sync --safe
+remits-cli verify tool --name <toolName> [--input "{...}"]
+remits-cli verify status [--envelope ID]
+remits-cli verify report [--envelope ID]
 ```
 
+### Verification envelopes
+
+Use a verification envelope for workflow-shaped work: concrete user journeys, browser-facing changes,
+branch variants, subscriber/forked accounts, production-vs-test lane questions, support tickets, and
+multi-agent work. Start it after you know the target account/branch/workspace/data-mode tuple and before
+the first edit:
+
+```bash
+remits-cli workspace use --auto
+remits-cli components status
+remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
+```
+
+An active envelope is stored in `./.remits-cli/verification/active`. Stage/test/token/tool/sync commands
+attach evidence automatically while an envelope is active. The explicit wrappers do the same thing and
+make the intent visible in terminal history:
+
+```bash
+remits-cli verify stage --workset
+remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery"
+remits-cli verify token --path /page/pricing-config --as-account 21 --data-mode test
+remits-cli verify sync --safe
+remits-cli verify report
+```
+
+Existing commands also accept `--verify-envelope <id>` to attach to a specific envelope and
+`--no-verify-envelope` to suppress automatic attachment for one command.
+
+The manifest is the proof contract. It should name the world being exercised: repo account, host,
+git/component branch, workspace, data mode, source layer, user journeys, artifacts and hashes, and the
+evidence categories required before the final response may claim the work is done. If the manifest
+cannot be written because the workflow is ambiguous, ask before implementation. For machine-gated report
+requirements, prefer structured entries like `{"id":"actual_upload","packetType":"browser_step",
+"category":"browser_session.actual_upload"}`. Plain strings work when they match a packet type or an
+evidence category, but structured entries are clearer when several agents collect packets for one
+envelope.
+
+Common packet meanings:
+
+| Packet | It proves | It does not prove by itself |
+|---|---|---|
+| `stage` | Which components were uploaded to the staging lane, including workset vs overlay | The requested behavior works |
+| `component_status` | Which source world and lane are currently staged or clean | Any behavior was exercised |
+| `test_run` | A Test component passed in the recorded account/branch/workspace/data lane | A hosted browser journey unless that Test actually drove it |
+| `token_inspect` | A token was minted/inspected for a specific account, source layer, and lane | A user clicked through the page |
+| `browser_session` / `browser_step` / `browser_snapshot` | The browser journey was opened or observed with named actions | Server-side persistence unless paired with assertions or follow-up state checks |
+| `tool_call` | A platform tool ran in the recorded world and returned the recorded result | User-visible behavior unless the tool is the requested entry point |
+| `sync_dry_run` | The planned durable writes and safety gates | Anything was written |
+| `sync_mutation` | Durable source moved to trunk or variant and returned a sync SHA | The committed source behaves after staging is cleared |
+| `artifact` | A file/screenshot/note exists with path, size, and sha256 | The workflow consumed it |
+
+Final claims should come from `remits-cli verify report`. Treat `Verified` as the acceptance boundary.
+`Additional evidence` is useful handoff context, but it does not satisfy a missing required packet unless
+the report lists it under `Verified`. If the report says `partially_verified`, stale, or missing evidence,
+say that plainly instead of widening the claim. In particular, staged proof is not committed variant/trunk
+proof, a token is not browser proof, and a direct DOM or Alpine state mutation is not the same as a user
+click/upload/reload flow.
+
 For tests specifically:
 - If `--data-mode` is omitted, `remits-cli test run` uses `test` and sends `dataModeSource:"cliDefault"`.
   An explicit `--data-mode prod` sends `dataModeSource:"explicitFlag"` so production test runs are

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

@@ -10,6 +10,7 @@
 
 - [Component Resolution: Staging Cache vs DB (which "version" actually runs)](#component-resolution-staging-cache-vs-db-which-version-actually-runs)
   - [The three source layers + the compile cache](#the-three-source-layers--the-compile-cache)
+  - [Verification envelopes record the source layer](#verification-envelopes-record-the-source-layer)
   - [Staging cache key format](#staging-cache-key-format)
   - [How the platform picks staged vs DB (the compile signature)](#how-the-platform-picks-staged-vs-db-the-compile-signature)
   - [When staged overrides apply](#when-staged-overrides-apply)
@@ -48,6 +49,18 @@ Plus the compile cache:
   cache of the parsed closure, keyed by `(componentId, type, compileSignature)`. This is why a change that
   is correctly in the DB can still execute stale on a running instance — see "Stale after sync" below.
 
+### Verification envelopes record the source layer
+
+When a verification envelope is active, `components stage`, `components status`, `test run`, `token`,
+`tool`, and `components sync` attach evidence packets with the branch/workspace/staging lane and the best
+source-layer facts the command observed. A staged test packet is proof of the staged layer; a sync packet
+is proof of a source transition; a token packet is proof of the browser token's resolution tuple. Those
+are not interchangeable.
+
+Use `remits-cli verify report` before summarizing the work. It will naturally say when the evidence only
+covered staged source, when committed variant/trunk proof is missing, or when evidence became stale after
+the git head, overlay, or platform sync moved.
+
 ### Staging cache key format
 
 ```

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

@@ -10,6 +10,7 @@
 
 - [Two Workflows](#two-workflows)
   - [Test Mode vs Prod Mode](#test-mode-vs-prod-mode)
+- [Verification Envelopes](#verification-envelopes)
 - [Development Workflow](#development-workflow)
   - [The Golden Rule: Writing Code Is Not Finishing the Job](#the-golden-rule-writing-code-is-not-finishing-the-job)
   - [The Development Fast Loop](#the-development-fast-loop)
@@ -66,6 +67,36 @@ The right model is:
 
 Never treat "it looks right in prod data inspection" as sufficient proof that a code change is verified.
 
+## Verification Envelopes
+
+For a concrete user workflow, browser-facing change, branch-variant release, support ticket, or any loop
+where earlier manual testing found a gap, start a verification envelope before editing:
+
+```bash
+remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
+```
+
+The envelope records the account, host, data lane, branch, workspace, git heads, staging lane, and the
+acceptance manifest. It is mirrored locally under `.remits-cli/verification/<envelopeId>/` and becomes
+active for this checkout. While active, `components stage`, `components status`, `test run`, `token`,
+`token inspect`, `tool`, and `components sync` attach evidence packets automatically; pass
+`--verify-envelope <id>` to name one explicitly or `--no-verify-envelope` when a command should not be
+attached.
+
+Use the wrappers when you want the intent to be unmistakable:
+
+```bash
+remits-cli verify stage --workset
+remits-cli verify test --test "Suite" --names "case name"
+remits-cli verify token --path /page/example
+remits-cli verify sync --safe
+remits-cli verify attach --artifact sample.zip --label "user supplied ZIP"
+remits-cli verify report
+```
+
+The report is the final-response source. It separates verified claims, missing evidence, stale packets,
+and the source/account/lane tuple, so do not replace it with a generic "verified" sentence.
+
 ## Development Workflow
 
 ### The Golden Rule: Writing Code Is Not Finishing the Job
@@ -124,6 +155,10 @@ runs resolve and what a sync writes. If `account-info.json` carries a `component
 variants of these components exist: editing an origin component will drift them, so check
 `remits-cli components branches` before changing shared code. See `branch-variants.md`.
 
+If the request names a journey or acceptance behavior, start the envelope here, after the target tuple is
+understood and before editing. A manifest can be lightweight JSON; the point is that the required
+evidence is durable before the proof is collected.
+
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
 

package/skills/remits-cli/references/support-tickets.md

@@ -17,6 +17,7 @@
   - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
   - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
   - [Some of that process is enforced, not requested](#some-of-that-process-is-enforced-not-requested)
+  - [Verification envelopes on tickets](#verification-envelopes-on-tickets)
   - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
   - [Agent components are workers too](#agent-components-are-workers-too)
   - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
@@ -191,6 +192,26 @@ start.
 `--data-mode test` registers a fixture agent instead, which will never be routed a production ticket —
 use it only when you are deliberately testing the routing itself.
 
+### Verification envelopes on tickets
+
+For ticket work that changes component behavior, especially browser workflows, branch variants, release
+gates, or a previously failed manual loop, start an envelope tied to the ticket:
+
+```bash
+remits-cli verify start --ticket 22454 --summary "Fix hosted upload recovery"
+```
+
+Keep it active while you stage, run Tests, mint browser tokens, call tools, and sync. Those commands
+attach evidence packets to the platform envelope and mirror them locally under `.remits-cli/verification/`.
+Before completing or handing off the ticket, run:
+
+```bash
+remits-cli verify report
+```
+
+Use that output in the ticket update. It names what was verified, what is still missing, and whether the
+proof covered staged source or committed source.
+
 ### If you are the worker
 
 You know you are one when `REMITS_SUPPORT_TICKET_ID` is set in your environment. Your whole job is