@remits/remits-cli 0.1.135 → 0.1.136

package/index.js

@@ -6,16 +6,16 @@
 - L22  Runtime Bootstrap And Shared State
 - L119  Sessions, Account Resolution, And Production Guards
 - L603  Local State, Workspaces, And Verification Evidence
-- L2474  Account Repos, Guide Sync, And Platform Repo
-- L3282  Component Discovery And HTTP Logging
-- L3923  Skill Delivery And TOC Resolution
-- L4233  Auth And Component Staging
-- L4848  Component Summaries, Status, And Sync Gates
-- L6917  Branches, Promotion, Commit, And Test Runs
-- L8600  Tokens, Tools, Verification, And Config
-- L9980  Service Dashboard And WebSocket Listener
-- L12101  Agent And Ticket Workflows
-- L15573  Help, Auto Update, And Command Dispatch
+- L2624  Account Repos, Guide Sync, And Platform Repo
+- L3432  Component Discovery And HTTP Logging
+- L4073  Skill Delivery And TOC Resolution
+- L4383  Auth And Component Staging
+- L4998  Component Summaries, Status, And Sync Gates
+- L7067  Branches, Promotion, Commit, And Test Runs
+- L8750  Tokens, Tools, Verification, And Config
+- L10177  Service Dashboard And WebSocket Listener
+- L12298  Agent And Ticket Workflows
+- L15888  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -626,6 +626,7 @@ function localStatePaths(cwd) {
     toolResponsesDir: path.join(actorDir, 'tool-responses'),
     verificationDir: path.join(actorDir, 'verification'),
     diagnosticsDir: path.join(actorDir, 'diagnostics'),
+    evidenceFile: path.join(actorDir, 'evidence.jsonl'),
     activeVerificationFile: path.join(actorDir, 'verification', 'active'),
     activeVerificationContextsFile: path.join(actorDir, 'verification', 'active-contexts.json'),
     currentSessionFile: path.join(actorDir, 'current-session.txt'),
@@ -1999,9 +2000,145 @@ async function printVerificationRunProbe(api, cwd, session, accountId, envelopeI
   return result;
 }
 
+/**
+ * The always-on evidence trail.
+ *
+ * <p>One world-stamped line per evidence-producing command, written whether or not any verification envelope
+ * exists. This is the answer to "what have I actually run, and in which world?" - the question agents were
+ * opening envelopes to answer, and an envelope is a far heavier instrument than that question needs. It is
+ * per-actor, so two agents in one checkout never read each other's trail, and it is append-only with a bounded
+ * tail so it cannot grow without limit.</p>
+ *
+ * <p>Recording is deliberately decision-free: there is no flag to remember, no state to start, and nothing an
+ * agent can fail to satisfy.</p>
+ */
+const EVIDENCE_TRAIL_MAX_LINES = 2000;
+
+function recordEvidenceEntry(cwd, packet, context = {}) {
+  try {
+    const paths = ensureLocalState(cwd);
+    const world = (packet && packet.world && typeof packet.world === 'object') ? packet.world : {};
+    const hasSuccess = packet && Object.prototype.hasOwnProperty.call(packet, 'success');
+    const entry = {
+      ts: new Date().toISOString(),
+      type: packet && packet.type || 'unknown',
+      claim: packet && packet.claim || null,
+      success: hasSuccess ? packet.success : true,
+      pending: packet && packet.pending === true || (hasSuccess && packet.success === null),
+      world: {
+        repoAccountId: world.repoAccountId != null ? world.repoAccountId : context.accountId || null,
+        executionAccountId: world.executionAccountId != null ? world.executionAccountId : (world.accountId != null ? world.accountId : null),
+        targetAccountId: world.targetAccountId != null ? world.targetAccountId : null,
+        dataMode: world.dataMode || context.dataMode || null,
+        branchName: world.branchName || world.gitBranch || context.branchName || null,
+        componentBranch: world.componentBranch || world.variantBranch || null,
+        workspace: world.workspace !== undefined ? world.workspace : (context.workspace !== undefined ? context.workspace : null),
+        sourceLayer: world.sourceLayer || null,
+        laneContentHash: world.laneContentHash || world.stagedOverlayHash || null,
+        host: world.host || context.baseUrl || null
+      },
+      ref: {
+        packetId: packet && packet.packetId || null,
+        taskId: (packet && packet.test && packet.test.taskId) || (packet && packet.status && packet.status.taskId) || null,
+        callId: (packet && packet.tool && packet.tool.callId) || null,
+        responseFile: (packet && packet.tool && packet.tool.responseFile) || null
+      },
+      // Present when an envelope happened to be active. Never required, and never something to chase.
+      envelopeId: context.envelopeId || null,
+      claims: Array.isArray(packet && packet.claims) ? packet.claims : undefined
+    };
+    fs.appendFileSync(paths.evidenceFile, JSON.stringify(entry) + '\n');
+    trimEvidenceTrail(paths.evidenceFile);
+    return entry;
+  } catch (_) {
+    // A trail write must never fail the command it is describing.
+    return null;
+  }
+}
+
+function evidenceOutcome(row) {
+  if (row && (row.pending === true || row.success === null)) return 'pending';
+  return row && row.success === false ? 'failed' : 'ok';
+}
+
+function evidenceOutcomeLabel(row) {
+  const outcome = evidenceOutcome(row);
+  if (outcome === 'failed') return 'FAILED ';
+  if (outcome === 'pending') return 'PENDING ';
+  return '';
+}
+
+function trimEvidenceTrail(file) {
+  try {
+    const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    if (lines.length <= EVIDENCE_TRAIL_MAX_LINES) return;
+    atomicWriteFile(file, lines.slice(lines.length - EVIDENCE_TRAIL_MAX_LINES).join('\n') + '\n');
+  } catch (_) { /* best effort */ }
+}
+
+function readEvidenceTrail(cwd, limit = 50) {
+  try {
+    const paths = localStatePaths(cwd);
+    if (!fs.existsSync(paths.evidenceFile)) return [];
+    const lines = fs.readFileSync(paths.evidenceFile, 'utf8').split('\n').filter(Boolean);
+    return lines.slice(Math.max(0, lines.length - limit)).map((line) => {
+      try { return JSON.parse(line); } catch (_) { return null; }
+    }).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * WHERE a command ran: accounts, lane, branch, workspace. Deliberately NOT `sourceLayer` or
+ * `laneContentHash` - those legitimately differ between two commands in the same world (a stage is `staged`,
+ * the test that follows resolves `db`), so keying the grouping on them split one world into several and made
+ * two entries from the same context look like two different places. They belong on the entry.
+ */
+function describeEvidenceWorld(world) {
+  const w = world || {};
+  const accounts = w.executionAccountId && String(w.executionAccountId) !== String(w.repoAccountId)
+    ? 'account ' + w.repoAccountId + ' -> runs as ' + w.executionAccountId
+    : 'account ' + (w.repoAccountId == null ? '?' : w.repoAccountId);
+  return [
+    accounts,
+    w.targetAccountId && String(w.targetAccountId) !== String(w.executionAccountId) ? 'targets ' + w.targetAccountId : null,
+    w.dataMode ? w.dataMode + ' lane' : null,
+    w.branchName ? 'branch ' + w.branchName : null,
+    w.componentBranch ? 'components ' + w.componentBranch : null,
+    'ws:' + (w.workspace || 'shared')
+  ].filter(Boolean).join(' · ');
+}
+
+function claimIdsFromFlags(flags) {
+  return []
+    .concat((flags && flags.claim) || [])
+    .concat((flags && flags.claims) || [])
+    .filter(Boolean)
+    .flatMap((value) => String(value).split(','))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function stampPacketClaims(packet, flags) {
+  const claims = claimIdsFromFlags(flags);
+  if (!claims.length) return packet;
+  if (!Array.isArray(packet.evidenceCategories)) packet.evidenceCategories = [];
+  claims.forEach((claim) => {
+    if (!packet.evidenceCategories.includes(claim)) packet.evidenceCategories.push(claim);
+  });
+  packet.claims = claims;
+  return packet;
+}
+
 async function appendVerificationPacket(api, cwd, session, accountId, flags, packet, options = {}) {
   const context = activeVerificationContext(cwd, flags, session, accountId);
   const envelopeId = verificationEnvelopeIdForCommand(cwd, flags, context);
+  // The trail is written FIRST and unconditionally. Evidence recording must not depend on an agent having
+  // remembered to start anything: an envelope is an optional verdict on top of this, never the thing that
+  // makes a command's world durable.
+  stampPacketClaims(packet, flags);
+  recordEvidenceEntry(cwd, packet, Object.assign({}, context, { accountId, envelopeId }));
   if (!envelopeId) return null;
   const finalPacket = Object.assign({
     packetId: crypto.randomUUID(),
@@ -2067,7 +2204,7 @@ function printVerificationSummaryLine(env) {
   const health = env.health ? ' health=' + env.health : '';
   const failures = env.currentFailureCount ? ' currentFailures=' + env.currentFailureCount : (env.failedCount ? ' failed=' + env.failedCount : '');
   const required = ' required=' + (env.satisfiedCount || 0) + '/' + (env.requiredCount || 0);
-  const noManifest = env.noRequiredEvidence ? ' no-manifest' : '';
+  const noManifest = env.noRequiredEvidence ? ' evidence-log' : '';
   const stale = env.staleCount ? ' stale=' + env.staleCount : '';
   const changed = env.requirementsChangedAfterEvidence ? ' requirements-changed' : '';
   const lane = [env.branchName || 'unknown-branch', env.workspace ? 'ws:' + env.workspace : 'shared', env.dataMode || null, env.sourceLayer || null]
@@ -2084,7 +2221,7 @@ function printVerificationEnvelope(envelope, fallbackEnvelopeId) {
   const evaluation = envelope.evaluation || {};
   if (evaluation.health) console.log('Health:', evaluation.health);
   if (evaluation.noRequiredEvidence) {
-    console.log('Required evidence: none declared - evidence packets do not prove a complete acceptance contract.');
+    console.log('Required evidence: none declared - evidence log only; no verdict is outstanding.');
   } else {
     console.log('Required evidence:', (evaluation.satisfiedCount || 0) + '/' + (evaluation.requiredCount || 0));
   }
@@ -2143,7 +2280,7 @@ function compactVerificationEnvelope(envelope, fallbackEnvelopeId) {
   const nextActions = [];
 
   if (evaluation.noRequiredEvidence) {
-    nextActions.push('Attach a manifest or required evidence contract; packets are context, not proof of completion.');
+    nextActions.push('No verdict was requested. Leave this as an evidence log, or add `verify claim <id> --text "..."` only if someone needs a checkable verdict.');
   }
   if (failures.length) {
     nextActions.push('Inspect and replace the current failing evidence packet(s).');
@@ -2227,14 +2364,27 @@ function printEnvelopeWarnings(envelope) {
   console.log('Envelope warnings:');
   warnings.forEach((warning) => {
     console.log('- ' + (warning.message || warning.code || JSON.stringify(warning)));
+    if (warning.command) console.log('  ' + warning.command);
     if (Array.isArray(warning.envelopes) && warning.envelopes.length) {
       warning.envelopes.forEach((env) => {
-        console.log('  ' + (env.envelopeId || '(no id)') + (env.status ? ' ' + env.status : ''));
+        // Say whether the duplicate is in THIS world. A restart in a genuinely different lane or branch is
+        // sometimes exactly right; a second envelope for the same goal in the same world is the loop.
+        const world = env.world && typeof env.world === 'object'
+          ? Object.keys(env.world).map((key) => key + '=' + env.world[key]).join(' ')
+          : '';
+        console.log('  ' + (env.envelopeId || '(no id)') + (env.status ? ' ' + env.status : '') +
+          (env.sameWorld === true ? '  [same world]' : (world ? '  [' + world + ']' : '')));
       });
+      console.log('  Continue one of those with `remits-cli verify use <id>`, or supersede it once this one supersedes its goal.');
     }
   });
 }
 
+function manifestClaims(manifest) {
+  const claims = manifest && manifest.claims;
+  return Array.isArray(claims) ? claims.filter(Boolean) : [];
+}
+
 function manifestRequiredEvidence(manifest = {}) {
   const required = [];
   if (Array.isArray(manifest.requiredEvidence)) required.push(...manifest.requiredEvidence);
@@ -9565,10 +9715,16 @@ async function verifyCommand(flags, subcommand) {
     if (flags.manifest || flags.file) {
       manifest = parseManifestFile(flags.manifest || flags.file);
     }
-    if (dataMode === 'prod' && !manifestRequiredEvidence(manifest).length && !flagEnabled(flags['no-contract'])) {
+    // PROD only, and framed as risk rather than as an unmet obligation. An envelope with no contract is an
+    // evidence log, which is the normal and complete mode; warning about it on every lane taught agents that
+    // their own record-keeping was an exam they were failing, and they responded by starting it over.
+    if (dataMode === 'prod' && !manifestRequiredEvidence(manifest).length && !manifestClaims(manifest).length &&
+        !flagEnabled(flags['no-contract'])) {
       console.error('');
-      console.error('Warning: starting a prod-data verification envelope with no required evidence contract.');
-      console.error('Attach a manifest with requiredEvidence before destructive work, or pass --no-contract when this is intentionally evidence-only.');
+      console.error('Note: this envelope records PRODUCTION-data evidence with no acceptance contract.');
+      console.error('That is fine for investigation. Before destructive or irreversible production work, name what');
+      console.error('must be true so the result is checkable by someone else:');
+      console.error('  remits-cli verify claim <id> --text "what must be true" [--test "<suite>"]');
       console.error('');
     }
     let statusResponse = null;
@@ -9598,12 +9754,17 @@ async function verifyCommand(flags, subcommand) {
       ticketId: flags.ticket,
       account: collectVerificationAccount(cwd, accountId, baseUrl, dataMode),
       source,
-      manifest
+      manifest,
+      noContract: flagEnabled(flags['no-contract']) || undefined
     });
     const envelope = response.envelope;
     writeLocalVerificationEnvelope(cwd, envelope);
     writeActiveVerificationEnvelope(cwd, envelope.envelopeId, activeContext);
     console.log('Verification envelope started:', envelope.envelopeId);
+    if (!manifestRequiredEvidence(manifest).length && !manifestClaims(manifest).length) {
+      console.log('Mode: evidence log (no acceptance contract asked for). Commands attach world-stamped evidence;');
+      console.log('      nothing is outstanding. Add `verify claim <id> --text "..."` only if someone needs a verdict.');
+    }
     printLocalCommandContext(cwd, flags, { accountId, branchName, workspace, dataMode });
     printLocalStateWarnings(cwd, flags);
     console.log('Target:', checkoutWorldLine + ', dataMode=' + dataMode +
@@ -9683,6 +9844,40 @@ async function verifyCommand(flags, subcommand) {
     return envelope;
   }
 
+  if (sub === 'claim' || sub === 'claims') {
+    const claimId = flags.id || (flags._ && flags._[2]);
+    const text = flags.text || flags.claim || flags.summary || flags.note;
+    if (!claimId) {
+      throw new Error('Usage: remits-cli verify claim <id> --text "what must be true" [--test "<suite>"] [--packet-type <type>]');
+    }
+    const claim = { id: String(claimId) };
+    if (text) claim.text = String(text);
+    // A claim may name the shape of evidence that proves it, so one line of contract can bind to a suite
+    // instead of needing a second parallel requiredEvidence list kept in sync by hand.
+    const suite = flags.test || flags.suite;
+    if (suite) {
+      claim.packetType = 'test_run';
+      claim.suite = String(suite);
+      if (flags.case || flags.cases) {
+        claim.cases = [].concat(flags.case || []).concat(flags.cases || [])
+          .flatMap((value) => String(value).split(',')).map((value) => value.trim()).filter(Boolean);
+      }
+    } else if (flags['packet-type'] || flags.packetType) {
+      claim.packetType = String(flags['packet-type'] || flags.packetType);
+    }
+    const response = await postVerificationCommand(api, cwd, session, accountId, 'claim', { envelopeId, claim });
+    writeLocalVerificationEnvelope(cwd, response.envelope);
+    const acceptance = (response.envelope || {}).acceptance || {};
+    console.log('Claim recorded on envelope ' + envelopeId + ': ' + claim.id);
+    console.log('Contract now requires ' + (acceptance.requiredEvidence || []).length + ' item(s).');
+    console.log('Prove it by adding --claim ' + claim.id + ' to the command that demonstrates it, e.g.');
+    console.log('  remits-cli verify test --test "<suite>" --claim ' + claim.id);
+    console.log('  remits-cli verify attach --claim ' + claim.id + ' --note "what you observed"');
+    printAcceptanceWarnings(response.envelope);
+    printEnvelopeWarnings(response.envelope);
+    return response.envelope;
+  }
+
   if (sub === 'attach') {
     const artifacts = [];
     let type = 'manual_observation';
@@ -9719,7 +9914,7 @@ async function verifyCommand(flags, subcommand) {
       artifacts,
       evidenceCategories
     };
-    const response = await appendVerificationPacket(api, cwd, session, accountId, { 'verify-envelope': envelopeId }, packet);
+    const response = await appendVerificationPacket(api, cwd, session, accountId, Object.assign({}, flags, { 'verify-envelope': envelopeId }), packet);
     console.log('Evidence attached:', (response.packet || packet).packetId);
     return response;
   }
@@ -9730,7 +9925,9 @@ async function verifyCommand(flags, subcommand) {
     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,
+      // `--claim` now names a declared acceptance claim id, so the free-text label for a browser step is
+      // `--label`. Reading both from one flag made the id double as prose and the prose double as an id.
+      claim: flags.label || flags.text || action,
       world: buildCommandWorld(null, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl) }),
       browser: {
         action,
@@ -9743,7 +9940,7 @@ async function verifyCommand(flags, subcommand) {
       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);
+    const response = await appendVerificationPacket(api, cwd, session, accountId, Object.assign({}, flags, { 'verify-envelope': envelopeId }), packet);
     console.log('Browser evidence attached:', (response.packet || packet).packetId);
     return response;
   }
@@ -14708,23 +14905,57 @@ function slimActivitySmell(smell) {
     testName: s.testName || null,
     branchName: s.branchName || null,
     workspace: s.workspace || null,
+    packetCount: s.packetCount == null ? null : s.packetCount,
+    requiredCount: s.requiredCount == null ? null : s.requiredCount,
+    openCount: s.openCount == null ? null : s.openCount,
+    command: s.command || null,
     updatedAt: formatTime(s.updatedAtMs || s.updatedAt || s.at || s.createdAt)
   };
 }
 
+/**
+ * The next COMMAND, not the smell restated. This list previously mapped each signal to its own summary
+ * sentence, so "Next actions" contained no action; and it filtered on severity <= 2, which permanently
+ * excluded `no_required_evidence` - the one signal that explains why an envelope never closes.
+ * A signal that knows its own fix is actionable at any severity.
+ */
+function buildActivityNextActions(smells) {
+  const seen = new Set();
+  return (smells || [])
+    .filter((smell) => smell && (smell.command || smellSeverityRank(smell) <= 2))
+    .sort((left, right) => {
+      const command = (right.command ? 1 : 0) - (left.command ? 1 : 0);
+      if (command) return command;
+      return smellSeverityRank(left) - smellSeverityRank(right);
+    })
+    .map((smell) => {
+      const title = smell.title || smell.envelopeSummary || smell.testName ||
+        (Array.isArray(smell.workspaces) ? smell.workspaces.join(', ') : null);
+      return {
+        type: smell.type || 'signal',
+        severity: smell.severity || 'info',
+        why: (title ? title + ' — ' : '') + (smell.summary || 'inspect this signal'),
+        command: smell.command || null
+      };
+    })
+    .filter((action) => {
+      // Dedupe on the COMMAND when there is one: two different signals about one envelope that resolve to
+      // the same next move are one next move.
+      const key = action.command ? 'cmd|' + action.command : action.type + '|' + action.why;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .slice(0, 6);
+}
+
 function compactActivityInspect(response) {
   const counts = response.counts || {};
   const smells = sortedActivitySmells(response.smells);
   const lanes = Array.isArray(response.lanes) ? response.lanes : [];
   const envelopes = Array.isArray(response.envelopes) ? response.envelopes : [];
   const testRuns = Array.isArray(response.testRuns) ? response.testRuns : [];
-  const nextActions = smells
-    .filter((smell) => smellSeverityRank(smell) <= 2)
-    .slice(0, 5)
-    .map((smell) => {
-      const title = smell.title || smell.envelopeSummary || smell.testName;
-      return (smell.type || 'signal') + (title ? ' (' + title + ')' : '') + ': ' + (smell.summary || 'inspect this signal');
-    });
+  const nextActions = buildActivityNextActions(smells);
 
   return {
     success: response.success,
@@ -14809,7 +15040,14 @@ function printActivityInspectSummary(response) {
     (counts.lanes || 0) + ' lane(s), ' +
     (counts.verificationEnvelopes || 0) + ' envelope(s), ' +
     (counts.testRuns || 0) + ' test run(s), ' +
-    (counts.corpusResults || 0) + ' corpus result(s)');
+    (counts.corpusResults || 0) + ' corpus result(s)' +
+    (counts.distinctStagedEntries != null && counts.distinctStagedEntries !== counts.stagedEntries
+      ? ', ' + counts.stagedEntries + ' staged entries across lanes (' + counts.distinctStagedEntries + ' distinct)'
+      : (counts.stagedEntries ? ', ' + counts.stagedEntries + ' staged entries' : '')));
+  if (response.envelopeScope === 'all-data-lanes') {
+    console.log('Note: test runs and corpus results are narrowed to the ' + response.dataMode +
+      ' lane; envelopes are listed across BOTH lanes (stage/sync evidence is lane-independent).');
+  }
 
   const smells = sortedActivitySmells(response.smells);
   console.log('');
@@ -14819,6 +15057,18 @@ function printActivityInspectSummary(response) {
     console.log('Top smells (' + smells.length + '):');
     smells.slice(0, 20).forEach((smell) => {
       console.log('  [' + (smell.severity || 'info') + '] ' + (smell.type || 'signal') + ': ' + smell.summary);
+      // The numbers were in the JSON and not on the line, so twenty signals read as three sentences repeated.
+      const facts = [
+        smell.packetCount != null ? smell.packetCount + ' packet(s)' : null,
+        smell.currentFailureCount != null ? smell.currentFailureCount + ' current failure(s)' : null,
+        smell.requiredCount != null ? smell.requiredCount + ' requirement(s)' : null,
+        smell.openCount != null ? smell.openCount + ' open' : null,
+        smell.recentRuns != null ? smell.recentRuns + ' recent run(s)' : null,
+        smell.failedRuns != null ? smell.failedRuns + ' failed' : null,
+        smell.stagedCount != null ? smell.stagedCount + ' staged' : null,
+        Array.isArray(smell.workspaces) ? smell.workspaces.join(', ') : null
+      ].filter(Boolean);
+      if (facts.length) console.log('       ' + facts.join(' · '));
       const pivots = [
         smell.accountId ? 'account ' + smell.accountId : null,
         smell.laneId ? 'lane ' + smell.laneId : null,
@@ -14831,12 +15081,15 @@ function printActivityInspectSummary(response) {
       if (pivots.length) console.log('       ' + pivots.join(' · '));
     });
     if (smells.length > 20) console.log('  ...' + (smells.length - 20) + ' more; rerun with --json');
-    const actions = compactActivityInspect(response).nextActions;
-    if (actions.length) {
-      console.log('');
-      console.log('Next actions:');
-      actions.forEach((action) => console.log('  - ' + action));
-    }
+  }
+  const actions = buildActivityNextActions(smells);
+  if (actions.length) {
+    console.log('');
+    console.log('Next actions:');
+    actions.forEach((action) => {
+      console.log('  - ' + action.why);
+      if (action.command) console.log('      ' + action.command);
+    });
   }
 
   // "2 agent(s)" with no names is the shape of the question, not the answer: an agent asking who else is in
@@ -14882,8 +15135,14 @@ function printActivityInspectSummary(response) {
     console.log('');
     console.log('Recent verification envelopes:');
     envelopes.slice(0, 8).forEach((env) => {
+      const world = [env.branchName || null, env.workspace ? 'ws:' + env.workspace : null, env.dataMode || null]
+        .filter(Boolean).join('/');
       console.log('  - ' + (env.status || 'unknown') + ' · ' + (env.packetCount || 0) + ' packet(s) · ' +
+        (world ? '[' + world + '] · ' : '') +
         (env.summary || env.envelopeId) + ' · ' + formatTime(env.updatedAtMs || env.lastPacketAtMs || env.createdAt));
+      if (env.noRequiredEvidence) {
+        console.log('      evidence log — no verdict requested; add a claim only if someone needs one: remits-cli verify claim <id> --text "..." --envelope ' + env.envelopeId);
+      }
       if (env.currentFailureCount) console.log('      current failures: ' + env.currentFailureCount);
     });
   }
@@ -14946,6 +15205,62 @@ function listWorkstreamIndexes(cwd) {
     .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
 }
 
+async function evidenceCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const limit = Math.max(1, Math.min(parseInt(flags.limit || flags.max || '40', 10) || 40, 500));
+  const entries = readEvidenceTrail(cwd, limit);
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify({ success: true, actor: resolveLocalActor().id, count: entries.length, entries }, null, 2));
+    return entries;
+  }
+  const paths = localStatePaths(cwd);
+  console.log('Evidence trail for actor ' + paths.actor.id + '  (' + paths.evidenceFile + ')');
+  if (!entries.length) {
+    console.log('Nothing recorded yet. Every stage, test, token, tool and sync appends one world-stamped line here,');
+    console.log('with no envelope and nothing to start.');
+    return entries;
+  }
+  // Grouped by WORLD, because "what have I proven" is only answerable per world. An agent that ran the same
+  // suite in two lanes has two different facts, and a flat list hides exactly that.
+  const groups = new Map();
+  entries.forEach((entry) => {
+    const key = describeEvidenceWorld(entry.world);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(entry);
+  });
+  groups.forEach((rows, world) => {
+    console.log('');
+    console.log(world);
+    const byClaim = new Map();
+    rows.forEach((row) => {
+      const key = (row.type || 'unknown') + '|' + (row.claim || row.type || 'evidence') + '|' + evidenceOutcome(row);
+      if (!byClaim.has(key)) byClaim.set(key, { row, count: 0 });
+      const bucket = byClaim.get(key);
+      bucket.count += 1;
+      bucket.row = row;
+    });
+    Array.from(byClaim.values())
+      .sort((left, right) => right.count - left.count)
+      .slice(0, 15)
+      .forEach((bucket) => {
+        const row = bucket.row;
+        const layer = row.world && row.world.sourceLayer ? '  source ' + row.world.sourceLayer : '';
+        console.log('  ' + (bucket.count > 1 ? bucket.count + ' x ' : '') +
+          evidenceOutcomeLabel(row) + (row.type || 'unknown') + ': ' + (row.claim || '(no claim)') +
+          '   ' + formatTime(row.ts) + layer +
+          (Array.isArray(row.claims) && row.claims.length ? '  [claims ' + row.claims.join(', ') + ']' : '') +
+          (row.envelopeId ? '  [envelope ' + row.envelopeId.slice(0, 8) + ']' : ''));
+      });
+    if (byClaim.size > 15) console.log('  ...' + (byClaim.size - 15) + ' more distinct entries; --json for all');
+  });
+  console.log('');
+  console.log(entries.length + ' entry(s) shown. This is a log, not a verdict: nothing here is outstanding.');
+  console.log('If someone needs a checkable verdict, start an envelope and name what must be true:');
+  console.log('  remits-cli verify start --summary "..." && remits-cli verify claim <id> --text "..."');
+  return entries;
+}
+
 async function workstreamCommand(flags, subcommand) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -16021,6 +16336,9 @@ function printVerifyHelp() {
   console.log('  remits-cli verify use <envelopeId>');
   console.log('  remits-cli verify current');
   console.log('  remits-cli verify clear [--all]');
+  console.log('  remits-cli verify claim <id> --text "what must be true" [--test "<suite>"] [--packet-type TYPE]');
+  console.log('      # declares a contract in ONE command when someone needs a verdict; no-contract envelopes are evidence logs');
+  console.log('      # prove it by adding --claim <id> to any verify test/token/tool/stage/attach command');
   console.log('  remits-cli verify show [--envelope ID] [--summary|--compact] [--json]');
   console.log('  remits-cli verify status [--envelope ID]');
   console.log('  remits-cli verify report [--envelope ID]');
@@ -16142,8 +16460,9 @@ async function main() {
     console.log('  remits-cli tool --name <toolName> [--base-url URL] [--account-id ID] [--as-account ID] [--target-account ID] [--branch BRANCH] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--scope self|children|hierarchy] [--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|list|use|clear|show|status|report|attach|abandon|supersede|test|token|stage|sync|tool]');
+    console.log('  remits-cli evidence [--limit N] [--json]   # what you have run and in which world (always recorded)');
+  console.log('  remits-cli verify start --summary "..." [--manifest file.json]  # OPTIONAL: ask for a checkable verdict');
+    console.log('  remits-cli verify [current|list|use|clear|show|status|report|claim|attach|abandon|supersede|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 lanes [--base-url URL] [--account-id ID] [--json]');
@@ -16383,6 +16702,22 @@ async function main() {
     throw new Error('Unknown activity subcommand: ' + subcommand);
   }
 
+  if (command === 'evidence') {
+    if (wantsHelp) {
+      console.log('Usage: remits-cli evidence [--limit N] [--json]');
+      console.log('');
+      console.log('What you have actually run, and in which world. Every stage, test, token, tool and sync');
+      console.log('appends one world-stamped line automatically - there is nothing to start and nothing to');
+      console.log('satisfy. Grouped by world, because the same suite run in two lanes is two different facts.');
+      console.log('');
+      console.log('This is per-actor, so agents sharing a checkout never read each other\'s trail.');
+      console.log('Use `remits-cli verify` only when someone needs a checkable VERDICT on top of this.');
+      return;
+    }
+    await evidenceCommand(args);
+    return;
+  }
+
   if (command === 'workstream') {
     if (wantsHelp) {
       console.log('Usage: remits-cli workstream status [--workstream ID|--workspace NAME] [--json]');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -162,11 +162,18 @@ 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`)
+- **`remits-cli evidence` answers "what have I actually run, and in which world?"** Every stage, test,
+  token, tool and sync appends one world-stamped line automatically, per actor. Nothing to start,
+  nothing to satisfy. Read it before you re-run something, and quote it when you report what you
+  proved. (`development-loop.md`)
+- **Verification envelopes are OPTIONAL and exist for one job: a verdict someone else will rely on.**
+  Start one when a ticket, a human, or a handoff needs a checkable "these specific things are true" —
+  not as a routine step before editing. `remits-cli verify start --summary "..."` then
+  `remits-cli verify claim <id> --text "..." [--test "<suite>"]` names what must be true; add
+  `--claim <id>` to the command that proves it; `remits-cli verify report` gives the verdict. An
+  envelope with no claims is simply an evidence log, which is a complete state — not something to
+  chase. If you find yourself opening an envelope to answer a question about your own work, use
+  `remits-cli evidence` instead. (`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.
@@ -209,8 +216,9 @@ 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.
+For a workflow-shaped request, rely on the automatic `remits-cli evidence` trail unless someone else needs
+a checkable verdict. Only then start `remits-cli verify start --summary "..."`, declare claims, and 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

@@ -344,10 +344,24 @@ shown is the latest run's, with the distinct worlds listed beneath it.
 
 ### 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:
+**First, the thing you probably want instead.** `remits-cli evidence` prints what you have actually run
+and in which world, grouped by world, with no envelope and nothing to start:
+
+```bash
+remits-cli evidence            # this actor's trail
+remits-cli evidence --json     # structured, for your final report
+```
+
+Every stage, test, token, tool and sync appends to it automatically. Use it for "what have I already
+run?", "did that execute in the prod lane?" and "what do I put in my final message?".
+
+**Verification envelopes are optional, and exist for a verdict someone ELSE will rely on** — a support
+ticket, a human who asked you to prove specific things, a handoff another agent will act on. They are not
+a routine step before editing. An envelope you started for your own benefit is nearly always
+`remits-cli evidence` in disguise, and it costs you turns that prove nothing.
+
+When a verdict is genuinely wanted, start it after you know the target
+account/branch/workspace/data-mode tuple:
 
 ```bash
 remits-cli workspace use --auto
@@ -355,6 +369,35 @@ remits-cli components status
 remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
 ```
 
+**Name what must be true, or there is no verdict to reach.** An envelope with no `claims` and no
+`requiredEvidence` reports `evidence_only` — a world-stamped log. That is a complete, final state, not a
+partial one, and nothing about it is outstanding. When you DO want a verdict, a manifest file is one way to
+declare the contract; `verify claim` is the one-command way, and it works on a live envelope:
+
+```bash
+remits-cli verify claim market-filter --text "US market scoring excludes AU and GB statements"
+remits-cli verify claim pilot-green --text "the pilot suite passes" --test "Acquirer Pilot"
+```
+
+Prove a claim by naming it on the command that already proves it. `--claim <id>` is stamped onto the
+evidence packet every command sends, so it works on `verify test`, `token`, `tool`, `stage`, `sync` and
+`attach` alike, and takes a comma-separated list:
+
+```bash
+remits-cli verify test --test "Acquirer Pilot" --claim pilot-green
+remits-cli verify tool --name mcp_run_action --as-account 36 --claim market-filter
+remits-cli verify attach --claim market-filter --note "AU statements excluded and counted"
+```
+
+A claim with no shape is satisfied by any successful packet tagged with its id. A claim that names a
+`--test` suite (or `--packet-type`) must be proven by that shape. Re-declaring an id replaces it, so
+tightening a claim is also one command.
+
+**When an envelope with a contract will not close, read the report — do not start another one.** Several
+open envelopes for the same goal, or workspaces named `...-r7`/`-r8`/`-r9`, is the loop signature, and
+`activity inspect` reports both as smells. Close what you are not finishing: `verify supersede --envelope
+<old> --superseded-by <new>` or `verify abandon --envelope <old> --reason "false start"`.
+
 An active envelope is stored per command world (`baseUrl + accountId + git branch + workspace`)
 inside the active local actor's mirror; **data mode is deliberately not part of the active pointer key**:
 `./.remits-cli/actors/<local-agent>/verification/active-contexts.json`. The legacy flat
@@ -367,7 +410,7 @@ history:
 
 ```bash
 remits-cli verify stage --workset
-remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery"
+remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery" --claim recovery
 remits-cli verify token --path /page/pricing-config --as-account 21 --data-mode test
 remits-cli verify sync --safe
 remits-cli verify report
@@ -435,10 +478,10 @@ proof noun: `passed` for a Test case, `measured` for corpus comparisons, `synced
 
 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
-action.
+the report lists it under `Verified`. If the report says `evidence_only`, no verdict was requested; if it
+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 action.
 
 Evidence from the wrong world is excluded before it can satisfy a requirement. When the manifest declares
 fields such as `repoAccountId`, `gitBranch`, `componentBranch`, `workspace`, or `dataMode`, the report names

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

@@ -201,9 +201,39 @@ 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.
+**You do not need to start anything to have a record.** Every stage, test, token, tool and sync appends a
+world-stamped line to your actor's evidence trail automatically. Read it with:
+
+```bash
+remits-cli evidence
+```
+
+That is the right tool for "what have I already run?", "did that test actually execute in the prod lane?",
+and "what should I put in my final message?". It is per-actor, so agents sharing a checkout never read each
+other's trail.
+
+**Start a verification envelope only when someone else needs a verdict** — a support ticket, a human who
+asked you to prove specific things, or a handoff another agent will act on. It is not a routine step before
+editing, and an envelope you open for your own benefit is almost always `remits-cli evidence` in disguise.
+
+When you do want a verdict, name what must be true. One command, no manifest file:
+
+```bash
+remits-cli verify start --summary "Hosted upload updates an existing profile"
+remits-cli verify claim fees-balance --text "statement fee totals reconcile to source within five cents"
+remits-cli verify claim pilot-green --text "the pilot suite passes" --test "Acquirer Pilot"
+```
+
+Prove a claim by naming it on the command that already proves it — `--claim <id>` works on `verify
+test`, `token`, `tool`, `stage`, `sync` and `attach` alike:
+
+```bash
+remits-cli verify test --test "Acquirer Pilot" --claim pilot-green
+remits-cli verify attach --claim fees-balance --note "34025 reconciles at 0.02 variance"
+```
+
+An envelope with no claims reports `evidence_only`. That is a complete, final state — a log, not a
+half-finished exam. Nothing about it is outstanding.
 
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.