@remits/remits-cli 0.1.168 → 0.1.170

package/README.md

@@ -2,6 +2,14 @@
 
 Local CLI for rapid Remits component testing without push/sync cycles.
 
+Builder onboarding: `remits-cli builder setup --account-id <owner> --directory <new-checkout>` uses your
+Remits sign-in to clone the account repository with a short-lived Git credential, select a workspace,
+sync guides and install the Remits Builder Claude Code plugin. No GitHub user account is required.
+
+Review staged changes: `remits-cli components propose --title "Describe the change"` creates or updates a
+GitHub PR from your current staging lane. It applies account landing policy and leaves merging and
+synchronization to the reviewer. Use `components propose --help` for scope and verification options.
+
 ## Install
 
 ```bash

package/index.js

@@ -6,16 +6,16 @@
 - L22  Runtime Bootstrap And Shared State
 - L128  Sessions, Account Resolution, And Production Guards
 - L634  Local State, Workspaces, And Verification Evidence
-- L2672  Account Repos, Guide Sync, And Platform Repo
-- L3571  Component Discovery And HTTP Logging
-- L4350  Skill Delivery And TOC Resolution
-- L4665  Auth And Component Staging
-- L5301  Component Summaries, Status, And Sync Gates
-- L7625  Branches, Promotion, Commit, And Test Runs
-- L9889  Tokens, Tools, Verification, And Config
-- L11406  Service Dashboard And WebSocket Listener
-- L13916  Agent And Ticket Workflows
-- L18429  Help, Auto Update, And Command Dispatch
+- L2802  Account Repos, Guide Sync, And Platform Repo
+- L3701  Component Discovery And HTTP Logging
+- L4484  Skill Delivery And TOC Resolution
+- L4849  Auth And Component Staging
+- L5485  Component Summaries, Status, And Sync Gates
+- L7826  Branches, Promotion, Commit, And Test Runs
+- L10139  Tokens, Tools, Verification, And Config
+- L11656  Service Dashboard And WebSocket Listener
+- L14166  Agent And Ticket Workflows
+- L18936  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -2097,6 +2097,7 @@ function recordEvidenceEntry(cwd, packet, context = {}) {
     };
     fs.appendFileSync(paths.evidenceFile, JSON.stringify(entry) + '\n');
     trimEvidenceTrail(paths.evidenceFile);
+    queueEvidenceReceipt(cwd, entry, context);
     return entry;
   } catch (_) {
     // A trail write must never fail the command it is describing.
@@ -2104,6 +2105,135 @@ function recordEvidenceEntry(cwd, packet, context = {}) {
   }
 }
 
+/**
+ * Shared passive evidence: inside a work attempt (a supervised worker, or a command given a ticket), each
+ * trail entry is ALSO written to a durable local outbox and published to the work item as a client-reported
+ * receipt, so a successor on another machine can retrieve it. Write before upload; a stable receiptId makes
+ * a replay after a lost response record nothing twice. Never a verdict and never something to satisfy.
+ */
+const EVIDENCE_OUTBOX_MAX_LINES = 1000;
+
+function evidenceOutboxFile(cwd, actorId) {
+  // A supervisor drains its CHILD's outbox: the child's state lives under its own actor (REMITS_AGENT_ID),
+  // not under the supervisor's, so the actor can be named explicitly.
+  if (actorId) {
+    return path.join(cwd, '.remits-cli', 'actors', normalizeLocalActor(actorId) || String(actorId), 'evidence-outbox.jsonl');
+  }
+  return path.join(path.dirname(localStatePaths(cwd).evidenceFile), 'evidence-outbox.jsonl');
+}
+
+function evidenceReceiptId(entry, ticketId) {
+  const crypto = require('crypto');
+  return 'r-' + crypto.createHash('sha256').update(String(ticketId) + '|' + JSON.stringify(entry)).digest('hex').slice(0, 20);
+}
+
+function queueEvidenceReceipt(cwd, entry, context = {}) {
+  try {
+    const ticketId = String((context && context.ticketId) || process.env.REMITS_SUPPORT_TICKET_ID || '').trim();
+    if (!ticketId || !entry) return null;
+    const receipt = {
+      receiptId: evidenceReceiptId(entry, ticketId),
+      ticketId,
+      // Partitioned by platform: a receipt queued against one host is never uploaded to another.
+      host: entry.world && entry.world.host || (context && context.baseUrl) || null,
+      attemptId: process.env.REMITS_WORKER_RUN_ID || null,
+      type: entry.type,
+      claim: entry.claim,
+      outcome: evidenceOutcome(entry),
+      observedAt: entry.ts,
+      world: entry.world,
+      ref: { packetId: entry.ref && entry.ref.packetId, taskId: entry.ref && entry.ref.taskId, callId: entry.ref && entry.ref.callId },
+      queuedAt: new Date().toISOString()
+    };
+    fs.appendFileSync(evidenceOutboxFile(cwd), JSON.stringify(receipt) + '\n');
+    return receipt;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Publish queued receipts. The outbox is RENAMED before it is read, so a concurrent writer appends to a
+ * fresh file and nothing it writes can be lost by this rewrite; whatever is not accepted is appended back.
+ * Returns { sent, duplicate, kept, rejected }.
+ */
+async function drainEvidenceOutbox(cwd, context, actorId) {
+  const file = evidenceOutboxFile(cwd, actorId);
+  const summary = { sent: 0, duplicate: 0, kept: 0, rejected: 0 };
+  // A drain that crashed mid-flight left its renamed file behind; its receipts go back in the queue.
+  try {
+    const dir = path.dirname(file);
+    for (const name of fs.readdirSync(dir)) {
+      const m = /^evidence-outbox\.jsonl\.(\d+)\.draining$/.exec(name);
+      if (m && Number(m[1]) !== process.pid && !processIsAlive(Number(m[1]))) {
+        const orphan = path.join(dir, name);
+        fs.appendFileSync(file, fs.readFileSync(orphan, 'utf8'));
+        fs.unlinkSync(orphan);
+      }
+    }
+  } catch (_) { /* best effort */ }
+  if (!fs.existsSync(file) || !context || !context.session) return summary;
+  const draining = file + '.' + process.pid + '.draining';
+  try { fs.renameSync(file, draining); } catch (_) { return summary; }
+  let receipts = [];
+  try {
+    receipts = fs.readFileSync(draining, 'utf8').split('\n').filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch (_) { return null; } }).filter(Boolean);
+  } catch (_) { /* unreadable: keep nothing */ }
+  const keep = [];
+  const host = String(context.baseUrl || '').replace(/\/$/, '');
+  // Grouped by ticket AND the data lane the receipt was observed in: a ticket lives in one lane, and
+  // addressing it from another (e.g. the draining supervisor's session lane) finds no document there.
+  const byTicket = new Map();
+  for (const r of receipts) {
+    // Another platform's receipts stay queued for that platform.
+    if (r.host && host && String(r.host).replace(/\/$/, '') !== host) { keep.push(r); continue; }
+    const lane = (r.world && r.world.dataMode) || context.dataMode || null;
+    const groupKey = r.ticketId + '|' + (lane || '');
+    if (!byTicket.has(groupKey)) byTicket.set(groupKey, { ticketId: r.ticketId, lane, list: [] });
+    byTicket.get(groupKey).list.push(r);
+  }
+  const api = buildAxios(context.baseUrl, context.session.token, 20000);
+  for (const { ticketId, lane, list } of byTicket.values()) {
+    for (let i = 0; i < list.length; i += 50) {
+      const batch = list.slice(i, i + 50);
+      try {
+        const response = await api.post('/cli/ticket', { action: 'receipt', ticketId, dataMode: lane || undefined, receipts: batch })
+          .then((res) => res.data);
+        if (response && response.success) {
+          summary.sent += response.accepted || 0;
+          summary.duplicate += response.duplicate || 0;
+          summary.rejected += (response.rejected || []).length;
+        } else {
+          keep.push(...batch);
+        }
+      } catch (err) {
+        // Only a request the platform says is malformed or not permitted is dropped (loudly). Everything else —
+        // unreachable, busy (409 also covers a ticket mid-write or a stale revision), throttled, not found yet —
+        // stays queued for the next drain: losing evidence is worse than retrying it.
+        const status = err && err.response && err.response.status;
+        const message = err && err.response && err.response.data && err.response.data.message;
+        if (status === 400 || status === 401 || status === 403 || status === 413 || status === 422) {
+          summary.rejected += batch.length;
+          appendGlobalActivityLog('evidence', 'outbox.rejected', { ticketId, count: batch.length, status, message }, 'error');
+        } else {
+          keep.push(...batch);
+          appendGlobalActivityLog('evidence', 'outbox.kept', { ticketId, count: batch.length, status: status || null,
+            message: message || describeError(err) }, 'warn');
+        }
+      }
+    }
+  }
+  try {
+    if (keep.length) {
+      fs.appendFileSync(file, keep.slice(-EVIDENCE_OUTBOX_MAX_LINES).map((r) => JSON.stringify(r)).join('\n') + '\n');
+    }
+    fs.unlinkSync(draining);
+  } catch (_) { /* the draining file remains and is retried by name below */ }
+  summary.kept = keep.length;
+  return summary;
+}
+
 function evidenceOutcome(row) {
   if (row && (row.pending === true || row.success === null)) return 'pending';
   return row && row.success === false ? 'failed' : 'ok';
@@ -4047,7 +4177,11 @@ function stageTimeoutMs(components, flags = {}) {
 }
 
 function cliRequestHeaders(token) {
-  const headers = token ? { Authorization: 'Bearer ' + token } : {};
+  // A supervised worker authenticates with the credential its supervisor minted for THIS attempt
+  // (/cli/agentCredential). The platform then knows which participant is calling from the credential itself,
+  // so omitting or mistyping an identity header cannot turn the worker into a human or another agent.
+  const effectiveToken = process.env.REMITS_AGENT_TOKEN || token;
+  const headers = effectiveToken ? { Authorization: 'Bearer ' + effectiveToken } : {};
   // The CLI version on EVERY request, from the one place every request is built. It used to travel only on
   // `agent register`, so the platform knew the version of the sessions that registered - and the agents that
   // loop hardest are exactly the ones that never do. Without it the platform cannot tell an agent that the
@@ -4661,6 +4795,56 @@ async function installSkillsCommand(flags) {
   }
 }
 
+async function builderCommand(flags, subcommand) {
+  const kit = require('./lib/builder-kit');
+  if (flagEnabled(flags.help) || !subcommand) {
+    console.log('remits-cli builder setup --account-id <owner> --directory <new-checkout> [--base-url <host>]');
+    return;
+  }
+  if (!['setup', 'credential'].includes(subcommand)) throw new Error('Expected builder setup.');
+  // Git appends get/store/erase. Never store a token and never emit ordinary CLI output on this door.
+  const operation = flags._ && flags._[2];
+  if (subcommand === 'credential' && operation !== 'get') return;
+  const context = resolveSessionContext(process.cwd(), flags);
+  const { session, accountId } = context;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token);
+  const fields = subcommand === 'credential' ? kit.credentialRequest(fs.readFileSync(0, 'utf8')) : null;
+  if (fields && (fields.protocol !== 'https' || fields.host !== 'github.com' || !fields.path)) return;
+  // Deliberately bypass request evidence logging: this response is a credential, not tool output.
+  let result;
+  try {
+    result = (await api.post('/cli/builderCredential', { token: session.token, accountId })).data;
+  } catch (_) {
+    throw new Error('Builder repository access was refused. Check your Remits sign-in and owner membership.');
+  }
+  if (!result.success || !result.token) throw new Error('No Builder Kit credential was issued.');
+  if (subcommand === 'credential') {
+    if (!kit.matchesRepository(fields, result.repository)) return;
+    process.stdout.write('username=x-access-token\npassword=' + result.token + '\n\n');
+    return;
+  }
+  const directory = path.resolve(flags.directory || result.repository.split('/')[1]);
+  const helper = kit.helperCommand(process.execPath, __filename, accountId, baseUrl);
+  kit.cloneRepository({ cloneUrl: result.cloneUrl, directory, helper });
+  process.chdir(directory);
+  ensureLocalState(directory);
+  await workspaceCommand({ _: ['workspace', 'use'], auto: true });
+  await ensureGuidesSynced(directory, { ...flags, 'account-id': accountId });
+  const plugin = path.join(directory, '.claude', 'skills', 'remits-builder');
+  const refs = path.join(plugin, 'references');
+  ensureDir(path.join(plugin, '.claude-plugin'));
+  atomicWriteFile(path.join(plugin, '.claude-plugin', 'plugin.json'), JSON.stringify({
+    name: 'remits-builder', version: '1.0.0', author: { name: 'Remits' }, license: 'MIT', skills: '.',
+    description: 'Build and verify Remits components in your own workspace.'
+  }, null, 2) + '\n');
+  atomicWriteFile(path.join(plugin, 'SKILL.md'), buildSkillSourceBody(refs));
+  writeSkillReferences(refs);
+  console.log('Builder Kit ready: ' + directory);
+  // Delivered references contain local paths; keep this installation local to this checkout.
+  fs.appendFileSync(path.join(directory, '.git', 'info', 'exclude'), '\n/.claude/skills/remits-builder/\n');
+}
+
 /*
 ## Auth And Component Staging
 */
@@ -6072,6 +6256,23 @@ async function statusComponentsCommand(flags) {
   return response;
 }
 
+async function proposeComponentsCommand(flags) {
+  const cwd = process.cwd();
+  const context = resolveSessionContext(cwd, flags);
+  requireAccountRepoContext(cwd, flags, 'components propose', context);
+  const { session, accountId } = context;
+  const api = buildAxios(flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL, session.token);
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token, accountId, mode: 'propose',
+    branchName: flags.branch || currentBranch(cwd), workspace: resolveWorkspace(cwd, flags),
+    title: flags.title, acknowledge: flags.acknowledge,
+    verificationEnvelopeId: verificationEnvelopeIdForCommand(cwd, flags, context),
+    dataMode: resolveDataMode(flags, session)
+  }).then(r => r.data);
+  if (!response.success) throw new Error(response.message || 'Proposal failed');
+  console.log(flagEnabled(flags.json) ? JSON.stringify(response, null, 2) : response.pullRequest.url);
+}
+
 async function lanesComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -9131,6 +9332,27 @@ function testRunSummaryLines(status = {}) {
   return lines;
 }
 
+// A full-suite run that took minutes is the most expensive thing an agent's build loop does, and the run itself
+// is the one place to say so. Production 2026-11: agents re-ran whole multi-minute suites after every edit,
+// every case passing. Printed only for an unselected run long enough (90 s of case time) to matter.
+function testRunPacingLines(status = {}, options = {}) {
+  const minMs = 90 * 1000;
+  const result = status.result || {};
+  const tests = Array.isArray(result.tests) ? result.tests.filter((t) => t && t.name) : [];
+  if (options.selected || tests.length < 4) return [];
+  const durationOf = (t) => Number(t.duration) || 0;
+  const totalMs = tests.reduce((sum, t) => sum + durationOf(t), 0);
+  if (totalMs < minMs) return [];
+  const slowest = tests.slice().sort((a, b) => durationOf(b) - durationOf(a)).slice(0, 3)
+    .filter((t) => durationOf(t) > 0);
+  const lines = ['Pacing: ' + tests.length + ' cases, ' + formatDurationMs(totalMs) + ' of case time' +
+    (slowest.length ? '; slowest ' + slowest.map((t) => JSON.stringify(String(t.name)) + ' ' + formatDurationMs(durationOf(t))).join(', ') : '') + '.'];
+  const ref = options.testRef !== undefined ? JSON.stringify(String(options.testRef)) : '<suite>';
+  lines.push('  While iterating, re-run only what you are fixing: remits-cli test run --test ' + ref + ' --failed  (or --names "a|b").');
+  lines.push('  Run the whole suite once before landing.');
+  return lines;
+}
+
 // Per-case comparison of two runs of the same suite: which cases changed outcome, and how cost and duration
 // moved. The answer to "did this revision do better than the last one" without reconstructing either run.
 function compareTestRunResults(baseResult = {}, headResult = {}) {
@@ -9349,6 +9571,13 @@ function testRunLaunchLines(start = {}, runOptions = {}) {
   if (runOptions.label) lines.push('Label: ' + runOptions.label);
   if (runOptions.params) lines.push('Params: ' + Object.keys(runOptions.params).map((k) => k + '=' + JSON.stringify(runOptions.params[k])).join(' '));
   if (runOptions.repeat) lines.push('Repeat: every selected case runs ' + runOptions.repeat + ' times');
+  if (start.rerunOf && Array.isArray(start.rerunOf.failedCases)) {
+    const r = start.rerunOf;
+    lines.push('Re-running ' + r.failedCases.length + ' case(s) that did not pass in run ' + r.taskId +
+      (r.dataMode ? ' (' + r.dataMode + ' lane)' : '') + ':');
+    r.failedCases.slice(0, 20).forEach((name) => lines.push('  - ' + name));
+    if (r.failedCases.length > 20) lines.push('  ... and ' + (r.failedCases.length - 20) + ' more');
+  }
   if (start.runGroupId) {
     lines.push('Parallel: ' + (start.shardTaskIds || []).length + ' shards (' + (start.shardTaskIds || []).join(', ') + '), read as ONE run by ' + start.runGroupId);
   }
@@ -9383,6 +9612,10 @@ async function testCommand(flags) {
     ? []
     : (Array.isArray(flags.names) ? flags.names : [flags.names]);
   const names = parseTestCaseSelectors(rawNames);
+  const rerunFailed = flagEnabled(flags.failed);
+  if (rerunFailed && names.length) {
+    throw new Error('--failed picks the cases itself; drop --names (or drop --failed).');
+  }
   // --label / --param / --repeat / --parallel: what this run varies, and how it is executed.
   const runOptions = testRunOptionsFromFlags(flags);
   const runGroupId = runOptions.parallel > 1 ? 'grp-' + crypto.randomUUID() : undefined;
@@ -9432,6 +9665,11 @@ async function testCommand(flags) {
     dataMode,
     dataModeSource,
     caseConcurrency: flags.parallel !== undefined && runOptions.parallel === 1 ? 1 : undefined,
+    // --candidate <laneContentHash>: refuse (stale_revision) if the lane no longer holds that staged content.
+    expectedLaneContentHash: flags.candidate || undefined,
+    // --failed: the platform re-runs only the cases that did not pass in your last finished run of this suite
+    // on this git branch and staging workspace (and says which run it read).
+    rerunFailed: rerunFailed || undefined,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
     tests: names
@@ -9450,6 +9688,7 @@ async function testCommand(flags) {
         break;
       } catch (err) {
         const data = err && err.response && err.response.data;
+        if (data && data.code === 'no_recorded_run') throw new Error(data.message);
         if (shardStarts.length && shardStartBusy(err) && Date.now() < shardWaitDeadline) {
           console.error('Shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel + ' is waiting for a free suite slot ' +
             '(the platform runs a limited number of suites at once; the shards already running free them).');
@@ -9462,8 +9701,18 @@ async function testCommand(flags) {
         throw err;
       }
     }
+    if (!shardStart.success && shardStart.code === 'nothing_failed' && !shardStarts.length) {
+      // Not an error: the thing --failed exists for is already true. Exit 0 and say what to run next.
+      if (jsonOutput) {
+        console.log(JSON.stringify(shardStart, null, 2));
+      } else {
+        console.log(shardStart.message);
+        console.log('Before landing, run the whole suite once: remits-cli test run --test ' + JSON.stringify(String(testRef)));
+      }
+      return;
+    }
     if (!shardStart.success) {
-      throw new Error('Failed to start test run' + (shardStarts.length ? ' (shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel +
+      throw new Error('Failed to start test run' + (shardStart.message ? ': ' + shardStart.message : '') + (shardStarts.length ? ' (shard ' + (shardStarts.length + 1) + ' of ' + runOptions.parallel +
         '; the shards already started keep running: ' + shardStarts.map((st) => st.taskId).join(', ') + ')' : ''));
     }
     shardStarts.push(shardStart);
@@ -9564,6 +9813,7 @@ async function testCommand(flags) {
       .forEach((line) => console.log(line));
     testRunSummaryLines(status).forEach((line) => console.log(line));
     testFailureGroupLines(status, { testRef }).forEach((line) => console.log(line));
+    testRunPacingLines(status, { testRef, selected: names.length > 0 || rerunFailed }).forEach((line) => console.log(line));
     printTestRunPivots(status);
     // The whole run object used to be printed here as pretty JSON. One 92-case suite measured 220 KB,
     // most of it identifiers repeated once per case, spent on the turn with the least room left. It is
@@ -13975,7 +14225,7 @@ const AGENT_WORKER_MAX_LOG_BYTES = 8 * 1024 * 1024;
  *
  * `mode` is the autonomy bound, not a preference. `investigate` maps to each CLI's genuine
  * read-only mode so an operator can put a real boundary around a production support agent; `edit`
- * lets it change files but never commits (the brief says so, and nothing here runs git).
+ * lets it change files; whether it may land is the account's landing profile, stated in the brief (nothing here runs git).
  */
 const AGENT_LAUNCHERS = {
   codex: {
@@ -15354,6 +15604,22 @@ async function releaseTicketClaim(context, agentId, ticket, options = {}) {
   }
 }
 
+/**
+ * Per-attempt liveness, in memory in the supervisor: when each child last wrote output and its last
+ * summarized progress line. Reported on the supervisor's poll as `attempts`, so the platform can tell a
+ * connected supervisor from a child that is actually producing work. Never persisted; never a heuristic.
+ */
+const WORKER_LIVENESS = new Map();
+
+function noteWorkerLiveness(ticketId, patch) {
+  const key = String(ticketId);
+  WORKER_LIVENESS.set(key, { ...(WORKER_LIVENESS.get(key) || { ticketId: key }), ...patch });
+}
+
+function workerLivenessFor(ticketIds) {
+  return (ticketIds || []).map((id) => WORKER_LIVENESS.get(String(id))).filter(Boolean);
+}
+
 async function postAgentStatus(context, agentId, update) {
   try {
     await buildAxios(context.baseUrl, context.session.token, 10000)
@@ -15370,6 +15636,39 @@ async function postAgentStatus(context, agentId, update) {
  * the same thing. Only the local supervisor can add machine-local repository hints; the worker owns the
  * final grounding step, including creating or choosing a git worktree before it edits.
  */
+/** Mint a credential bound to one worker attempt. Null (legacy identity) when the server cannot. */
+async function mintWorkerCredential(context, binding) {
+  try {
+    const response = await buildAxios(context.baseUrl, context.session.token, 15000)
+      .post('/cli/agentCredential', {
+        mode: 'mint', agentId: binding.agentId, ticketId: binding.ticketId, runId: binding.runId,
+        capabilities: binding.capabilities
+      })
+      .then((r) => r.data);
+    if (response && response.success && response.credential) {
+      appendGlobalActivityLog('agent', 'worker.credential_minted', {
+        agentId: binding.agentId, ticketId: binding.ticketId, expiresAt: response.expiresAt
+      });
+      return { credential: response.credential, expiresAt: response.expiresAt };
+    }
+  } catch (err) {
+    appendGlobalActivityLog('agent', 'worker.credential_unavailable', {
+      agentId: binding.agentId, ticketId: binding.ticketId, error: describeError(err)
+    }, 'warn');
+  }
+  return null;
+}
+
+async function revokeWorkerCredential(context, workerCredential) {
+  if (!workerCredential || !workerCredential.credential) return;
+  try {
+    await buildAxios(context.baseUrl, context.session.token, 15000)
+      .post('/cli/agentCredential', { mode: 'revoke', credential: workerCredential.credential });
+  } catch (_) {
+    // It expires on its own; a failed revoke only shortens nothing.
+  }
+}
+
 async function spawnTicketWorker(context, ctx, ticket) {
   const { spawn } = require('child_process');
   const agentId = ctx.agentId;
@@ -15495,6 +15794,15 @@ async function spawnTicketWorker(context, ctx, ticket) {
   });
 
   const attempt = recordWorkerAttempt(agentId, ticketId);
+  // A credential bound to this attempt (agent + ticket + run). Best effort: an older server without the
+  // endpoint leaves the worker on the legacy header-declared identity, exactly as before.
+  // A session the OPERATOR launched read-only (--mode investigate) gets a credential WITHOUT stage/land, so
+  // the platform refuses source changes from it rather than relying on the brief alone. A worker that is
+  // investigating only because another run holds the lease keeps full reach: it may take the lease later.
+  const workerCredential = await mintWorkerCredential(context, {
+    agentId, ticketId, runId,
+    capabilities: ctx.mode === 'investigate' ? ['read', 'ticket', 'test', 'tool', 'token'] : undefined
+  });
   const child = spawn(launcher.binary, built.args, {
     cwd: workingDirectory || ctx.cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
@@ -15505,6 +15813,7 @@ async function spawnTicketWorker(context, ctx, ticket) {
       REMITS_AGENT_ID: agentId,
       REMITS_SUPPORT_TICKET_ID: ticketId,
       REMITS_WORKER_RUN_ID: runId,
+      ...(workerCredential ? { REMITS_AGENT_TOKEN: workerCredential.credential } : {}),
       // Give the worker its OWN staging lane.
       //
       // The edit LEASE already serializes who may edit a repo, and this does not replace it — a lease
@@ -15566,8 +15875,10 @@ async function spawnTicketWorker(context, ctx, ticket) {
   let lastStatusAtMs = 0;
   let buffered = '';
 
+  noteWorkerLiveness(ticketId, { runId, pid: child.pid, startedAtMs: Date.now() });
   const consume = (chunk) => {
     const text = chunk.toString();
+    noteWorkerLiveness(ticketId, { lastOutputAtMs: Date.now() });
     if (logBytes < AGENT_WORKER_MAX_LOG_BYTES) {
       logBytes += text.length;
       logStream.write(text);
@@ -15583,6 +15894,7 @@ async function spawnTicketWorker(context, ctx, ticket) {
       if (nowMs - lastStatusAtMs < AGENT_WORKER_STATUS_THROTTLE_MS) continue;
       lastStatusAtMs = nowMs;
       recordWorker(agentId, ticketId, { activity: summary, activityAt: new Date().toISOString() });
+      noteWorkerLiveness(ticketId, { lastProgress: String(summary).slice(0, 160), lastProgressAtMs: nowMs });
       postAgentStatus(context, agentId, {
         state: 'working', ticketId, activity: summary, step: 'worker:' + agentType
       });
@@ -15597,12 +15909,23 @@ async function spawnTicketWorker(context, ctx, ticket) {
 
   const done = new Promise((resolve) => {
     child.on('error', (err) => {
+      WORKER_LIVENESS.delete(String(ticketId));
       appendGlobalActivityLog('agent', 'worker.spawn_failed',
         { agentId, ticketId, agentType, error: describeError(err) }, 'error');
       resolve({ ticketId, ok: false, reason: 'spawn_failed', message: describeError(err) });
     });
     child.on('close', async (code, signal) => {
       try { logStream.end(); } catch (_) { /* nothing to do */ }
+      // The attempt is over: its credential must not outlive it (a late or orphaned child cannot keep acting).
+      WORKER_LIVENESS.delete(String(ticketId));
+      // The worker may have exited with receipts still queued in its checkout: a worker exit must not erase
+      // unsent evidence. Drained with the SUPERVISOR's session (the worker credential is about to be revoked).
+      if (workingDirectory) {
+        try {
+          await drainEvidenceOutbox(workingDirectory, { ...context, dataMode: context.dataMode || ctx.dataMode }, agentId);
+        } catch (_) { /* stays queued for the next drain */ }
+      }
+      await revokeWorkerCredential(context, workerCredential);
       const ok = code === 0 && !signal;
       appendGlobalActivityLog('agent', 'worker.finished',
         { agentId, ticketId, agentType, code, signal, attempt, logFile }, ok ? 'info' : 'error');
@@ -15758,6 +16081,7 @@ async function agentHeartbeatDaemonCommand(flags) {
           claim: inFlight.size < ctx.maxConcurrent,
           runId: ctx.runId,
           activeTickets,
+          attempts: workerLivenessFor(activeTickets),
           maxConcurrent: ctx.maxConcurrent,
           // Declared so the phase the platform derives already accounts for an operator who asked for a
           // read-only agent. Without it the server would hand out an edit lease this session will never
@@ -16068,6 +16392,8 @@ async function ticketCommand(flags, subcommand) {
 
   const local = ownLocalAgent(flags);
   const context = agentSessionFor(flags, local);
+  // Publish any passive receipts this checkout queued, before the verb that may hand the work to someone else.
+  try { await drainEvidenceOutbox(process.cwd(), context); } catch (_) { /* never blocks the verb */ }
 
   // Routing lives on its own endpoint (the operator surface the dashboard and any Embeddable share),
   // so it is dispatched here rather than folded into the lifecycle switch.
@@ -16111,6 +16437,13 @@ async function ticketCommand(flags, subcommand) {
     route: flags.route === 'false' ? false : undefined,
     details: flags.details,
     nextStep: flags['next-step'],
+    // The structured handoff checkpoint (durable references, never local paths) and the revision a
+    // decision was made from: a stale one is refused with code stale_revision instead of being rebased.
+    artifactRefs: csvFlag(flags['artifact-refs'] || flags.artifactRefs),
+    evidenceRefs: csvFlag(flags['evidence-refs'] || flags.evidenceRefs),
+    waitingOn: csvFlag(flags['waiting-on'] || flags.waitingOn),
+    requiredCapabilities: csvFlag(flags.needs || flags['required-capabilities']),
+    expectedRevision: flags['expected-revision'] !== undefined ? Number(flags['expected-revision']) : undefined,
     category: flags.category,
     // Clearing a planning slot has to be expressible, and `||` could not express it: an empty value is
     // falsy, so it collapsed to undefined, JSON.stringify dropped the key, and the server was never told.
@@ -16904,9 +17237,16 @@ function printTicketHelp() {
   console.log('  cancel-request --request R2 [--reason "..."]');
   console.log('  handoff --summary "what the next worker should do" [--workstream review] [--exclude]');
   console.log('          [--review-action promote --revision R] [--next-step "..."] [--findings "a|b"]');
+  console.log('          [--artifact-refs a,b] [--evidence-refs e1,e2] [--waiting-on X] [--needs capability]');
   console.log('      Hand the next step to another session (queued if nobody is online). --exclude keeps');
   console.log('      YOU off it — use it for independent review. Your exit will not erase this handoff.');
+  console.log('      The checkpoint (findings, next step, refs, waiting-on, needs) is in the next worker\'s brief.');
+  console.log('  --expected-revision N (handoff, decide, complete): refuse with stale_revision if the ticket moved');
+  console.log('      past revision N since you read it, instead of merging your decision over newer changes.');
   console.log('  continue [--reason requested]          Queue the ticket for the automation to work again.');
+  console.log('  cancel --reason "..." [--expected-revision N]   The outcome is no longer wanted: closed with disposition');
+  console.log('      cancelled; history kept; open requests cancelled; anything already landed or sent is NOT undone.');
+  console.log('  redeliver-events                      OPERATOR: re-dispatch undelivered lifecycle events (deduplicated by eventId).');
   console.log('  reset-budget                          OPERATOR: restore a ticket\'s run and spend budget after looking at it.');
   console.log('  wake --in MINUTES | --at ISO-TIME [--reason "..."]   |   wake --cancel');
   console.log('      A durable timer: when it is due the ticket is runnable work again (reason `timer`) and');
@@ -17083,6 +17423,113 @@ function usageListFlag(value) {
   return items.length ? items : undefined;
 }
 
+/** `remits-cli capabilities` — the platform's collaboration catalog (features, verbs, refusal codes). */
+async function capabilitiesCommand(flags) {
+  const cwd = process.cwd();
+  let baseUrl = flags['base-url'];
+  if (!baseUrl) {
+    try { baseUrl = resolveSessionContext(cwd, flags).session.baseUrl; } catch (_) { /* no session is fine */ }
+  }
+  baseUrl = baseUrl || DEFAULT_BASE_URL;
+  let response;
+  try {
+    response = await axios.get(baseUrl.replace(/\/$/, '') + '/cli/capabilities', { timeout: 15000, headers: cliRequestHeaders(null) })
+      .then((r) => r.data);
+  } catch (err) {
+    if (err && err.response && err.response.status === 404) {
+      response = { success: false, code: 'unsupported',
+        message: 'This platform predates the capability catalog; it supports none of the negotiated collaboration features.' };
+    } else {
+      throw err;
+    }
+  }
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+  if (!response || response.success !== true) {
+    console.log(response && response.message ? response.message : 'No capability catalog available.');
+    return response;
+  }
+  console.log('Collaboration capabilities — ' + baseUrl + ' (protocol ' + response.protocolVersion + ')');
+  console.log('');
+  console.log('Features:');
+  Object.entries(response.featureDetails || {}).forEach(([name, detail]) => console.log('  ' + name.padEnd(24) + ' ' + detail));
+  console.log('');
+  console.log('Verbs:');
+  (response.verbs || []).forEach((v) => console.log('  ' + String(v.verb).padEnd(30) + ' ' + (v.sideEffect || '') +
+    (v.refusals && v.refusals.length ? '  [refusals: ' + v.refusals.join(', ') + ']' : '')));
+  console.log('');
+  console.log('Refusal codes:');
+  Object.entries(response.codes || {}).forEach(([code, meaning]) => console.log('  ' + code.padEnd(20) + ' ' + meaning));
+  console.log('');
+  console.log(response.note);
+  return response;
+}
+
+/**
+ * `remits-cli policy explain` — what the account's deterministic rules would decide for a proposed action,
+ * and why, WITHOUT applying it. The verb re-evaluates when it actually runs; this is the preview.
+ */
+async function policyExplainCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token, 60000);
+  const components = csvFlag(flags.components || flags.component);
+  const response = await loggedPost(api, cwd, '/cli/policyExplain', {
+    // The checkout's branch and staging workspace: a person explaining their STAGED process draft is answered
+    // from it (the authoring lane shows staged prompts only when the call names its branch).
+    ...runContextPayload(flags),
+    token: session.token,
+    accountId: flags['target-account-id'] ? Number(flags['target-account-id']) : accountId,
+    dataMode: resolveDataMode(flags, session),
+    point: flags.point,
+    workstream: flags.workstream,
+    capabilities: csvFlag(flags.capabilities || flags.capability) || undefined,
+    actorKind: flags.as || flags['actor-kind'],
+    acknowledge: flags.acknowledge,
+    components: components ? components.map((entry) => {
+      const [type, name, category] = String(entry).split(':');
+      return { type, name, category };
+    }) : undefined
+  }).then((r) => r.data).catch((err) => {
+    if (err && err.response && err.response.data) return err.response.data;
+    throw err;
+  });
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+  if (!response || response.success !== true) {
+    throw new Error((response && response.message) || 'Policy explanation failed');
+  }
+  const decision = response.decision || {};
+  console.log('Policy at "' + response.point + '" on account ' + response.accountId +
+    (response.workstream ? ' (workstream ' + response.workstream + ')' : '') + ' — ' + response.dataMode + ' lane');
+  console.log('  as: ' + ((response.actor && response.actor.kind) || '?') +
+    ((response.actor && response.actor.evidence && response.actor.evidence.length) ? ' (' + response.actor.evidence.join(', ') + ')' : ''));
+  console.log('  decision: ' + (decision.allowed ? 'ALLOWED' : 'REFUSED (' + (decision.code || 'policy_denied') + ')'));
+  if (decision.message) console.log('  ' + decision.message);
+  (decision.warnings || []).forEach((w) => console.log('  warn ' + w.ruleId + ': ' + (w.message || '')));
+  const relevant = (response.rules || []).filter((r) => r.appliesAtPoint || r.fires);
+  if (relevant.length) {
+    console.log('  rules that apply at this point:');
+    relevant.forEach((r) => console.log('    ' + (r.fires ? '*' : ' ') + ' [' + r.grade + '] ' + r.id +
+      (r.final ? ' (final)' : '') + '  from ' + (r.source || '?') +
+      (r.distance !== undefined ? ' (distance ' + r.distance + ')' : '')));
+  } else {
+    console.log('  no rule applies at this point.');
+  }
+  const eff = response.effectivePolicy || {};
+  if (eff.unavailable) console.log('  POLICY UNAVAILABLE: mandatory decisions are refused until it can be read.');
+  if (eff.error) console.log('  policy problem: ' + eff.error);
+  console.log('  ' + response.note);
+  return response;
+}
+
 async function usageCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -17540,9 +17987,29 @@ function listWorkstreamIndexes(cwd) {
     .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
 }
 
+function evidenceOutboxPending(cwd) {
+  try {
+    const file = evidenceOutboxFile(cwd);
+    return fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).length : 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
 async function evidenceCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
+  if (flags._ && flags._[1] === 'flush') {
+    const context = agentSessionFor(flags, ownLocalAgent(flags));
+    const result = await drainEvidenceOutbox(cwd, context);
+    if (flagEnabled(flags.json)) {
+      console.log(JSON.stringify({ success: true, ...result }, null, 2));
+    } else {
+      console.log('Published ' + result.sent + ' receipt(s)' + (result.duplicate ? ', ' + result.duplicate + ' already recorded' : '') +
+        (result.rejected ? ', ' + result.rejected + ' rejected' : '') + (result.kept ? '; ' + result.kept + ' still queued' : '') + '.');
+    }
+    return result;
+  }
   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)) {
@@ -17551,6 +18018,10 @@ async function evidenceCommand(flags) {
   }
   const paths = localStatePaths(cwd);
   console.log('Evidence trail for actor ' + paths.actor.id + '  (' + paths.evidenceFile + ')');
+  const pending = evidenceOutboxPending(cwd);
+  if (pending) {
+    console.log(pending + ' receipt(s) queued for the work item and not yet published — remits-cli evidence flush');
+  }
   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.');
@@ -17652,6 +18123,35 @@ async function workstreamCommand(flags, subcommand) {
  * and the one an operator asks when a queue is not moving. Agents, leases and tickets were each readable
  * on their own and never together, so every caller invented its own join and they disagreed.
  */
+/**
+ * One line from the platform's CollaborationActivity projection. Null when an older server sent none.
+ * Live work and stored facts are named separately, and unknown coverage is said, never shown as zero.
+ */
+function describeActivityHeadline(activity) {
+  if (!activity || typeof activity !== 'object') return null;
+  const parts = [];
+  const coverage = activity.coverage || {};
+  if (coverage.registry === 'unavailable') {
+    parts.push('live participants unknown');
+  } else {
+    const running = (activity.attempts && activity.attempts.running) || 0;
+    const online = (activity.participants && activity.participants.online) || 0;
+    parts.push('live: ' + running + ' attempt(s) running, ' + online + ' participant(s) online');
+  }
+  if (coverage.staging === 'unavailable') {
+    parts.push('staging unknown');
+  } else if (activity.staged && activity.staged.laneCount) {
+    const changes = activity.changes || {};
+    parts.push('stored: ' + (changes.componentCount != null ? changes.componentCount + ' last-reported change(s), ' : '') +
+      activity.staged.entryCount + ' staged entr(ies) in ' + activity.staged.laneCount + ' lane(s)' +
+      (changes.asOf ? ' (as of ' + changes.asOf + ')' : ''));
+  }
+  if (Array.isArray(activity.offlineAuthors) && activity.offlineAuthors.length) {
+    parts.push('staged by offline author(s): ' + activity.offlineAuthors.join(', '));
+  }
+  return '  ' + parts.join(' · ');
+}
+
 async function agentWorkMapCommand(flags) {
   const agentId = resolveAgentId(flags, { optional: true });
   const local = agentId ? (listLocalAgents().find((entry) => entry.agentId === agentId) || {}) : {};
@@ -17678,12 +18178,19 @@ async function agentWorkMapCommand(flags) {
     return;
   }
   console.log('Work map — ' + context.baseUrl + ' · ' + response.dataMode + ' lane');
+  // The platform's activity projection (the same one the account console renders): live work is the
+  // running/online counts; last-reported changes and the staged overlay are stored facts with an as-of.
+  const activityLine = describeActivityHeadline(response && response.activity);
+  if (activityLine) console.log(activityLine);
   console.log('');
   for (const repo of repositories) {
     const lease = repo.editLease;
     console.log('  ' + repo.accountName + ' (' + repo.accountId + ')' +
       (repo.accountType ? '  ' + repo.accountType : ''));
-    if (lease) {
+    if (lease && lease.unavailable) {
+      // UNKNOWN is its own state: nobody may edit, and nobody is named as the holder.
+      console.log('    EDIT LEASE  unknown (coordination store unavailable) — investigate read-only');
+    } else if (lease) {
       const who = lease.agentLabel || lease.agentId;
       console.log('    EDIT LEASE  ' + who +
         (lease.ticketId ? '  ticket ' + lease.ticketId : '') +
@@ -18728,7 +19235,13 @@ function printComponentsHelp(subcommand) {
     console.log('--safe also gates the server sync plan before any trunk rows or ComponentVariant overlays are written.');
     return;
   }
-  console.log('Usage: remits-cli components <stage|status|lanes|entries|clear|sync|commit|promotion|branches|branch>');
+  if (subcommand === 'propose') {
+    console.log('Usage: remits-cli components propose [--account-id ID] [--branch BASE] [--workspace NAME] [--title TITLE] [--verify-envelope ID] [--acknowledge TEXT] [--json]');
+    console.log('Creates or updates a GitHub PR from every staged component in your lane. Account landing policy applies.');
+    console.log('Review the PR before merging; this command does not merge or synchronize components.');
+    return;
+  }
+  console.log('Usage: remits-cli components <stage|status|lanes|entries|clear|sync|commit|propose|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');
@@ -18759,7 +19272,7 @@ function printComponentsHelp(subcommand) {
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
   console.log('       remits-cli test status --task-id <taskId> [--base-url URL] [--account-id ID] [--branch stagingScope] [--data-mode test|prod] [--json]');
   console.log('       remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--json]   # durable run history');
   console.log('       remits-cli test compare --base <taskId> --head <taskId> [--json]            # per-case outcome/cost deltas');
@@ -18768,11 +19281,15 @@ function printTestHelp() {
   console.log('Examples:');
   console.log('  remits-cli test run --test 11');
   console.log('  remits-cli test run --test "Merchant Statements" --names "managed account case"');
+  console.log('  remits-cli test run --test "Merchant Statements" --failed');
   console.log('  remits-cli test status --task-id 7a1b...');
   console.log('');
   console.log('Notes:');
   console.log('  --names is delimited by "|" (comma also works when no "|" is present), and may be repeated.');
   console.log('    A selector that matches no case fails the run rather than reporting 0 passed / 0 failed.');
+  console.log('  --failed re-runs only the cases that did not pass in your last finished run of this suite on');
+  console.log('       this git branch and staging workspace. Iterate with --failed / --names; run the whole');
+  console.log('       suite once before landing.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
   console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
   console.log('       to force production/subscription semantics from a variant checkout.');
@@ -18963,6 +19480,11 @@ async function main() {
   const wantsHelp = args.help === true || subcommand === 'help' || subcommand === '--help' || args._.includes('--help');
   const wantsJson = flagEnabled(args.json);
 
+  if (command === 'builder') {
+    await builderCommand(args, subcommand);
+    return;
+  }
+
   // Inference callbacks must keep one protocol version for the supervisor's lifetime. They do not
   // auto-update, auto-start the support listener, or depend on a component checkout.
   if (command === 'ai') {
@@ -19048,6 +19570,8 @@ async function main() {
     console.log('  remits-cli activity inspect [--account-id ID] [--scope self|children|related] [--workspace NAME] [--workstream ID] [--user-email E] [--summary|--compact] [--json]');
     console.log('  remits-cli workstream status [--workstream ID|--workspace NAME] [--json]');
     console.log('  remits-cli usage --from DATE [--to DATE] [--by hour|day|month] [--group-by account,sku] [--capabilities ai,document_store] [--json]');
+    console.log('  remits-cli capabilities [--json]                       Collaboration features, verbs and refusal codes this platform supports');
+    console.log('  remits-cli policy explain --point commit [--as agent]  What the account rules would decide, and why (nothing applied)');
     console.log('  remits-cli agent release                                            # stop receiving tickets now');
     console.log('  remits-cli start [--foreground true] [--port 8787]                  # human dashboard in the browser');
     console.log('  remits-cli stop');
@@ -19079,7 +19603,7 @@ async function main() {
     console.log('  remits-cli components branch <name> --subscribe <accountId> [--dry-run] [--confirm-primary-edge]');
     console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
     console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
-    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
+    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none] [--label TEXT] [--param name=value ...] [--repeat N] [--parallel N] [--json]');
     console.log('  remits-cli test runs [--test <id|name>] [--compare]                 # durable run history; compare latest two');
     console.log('  remits-cli test compare --base <taskId> --head <taskId>');
     console.log('  remits-cli corpus import --manifest corpus-manifest.json             # seed a test corpus: cases + artifacts');
@@ -19187,6 +19711,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && subcommand === 'propose') {
+    await proposeComponentsCommand(args);
+    return;
+  }
+
   if (command === 'components' && (subcommand === 'lanes' || subcommand === 'lane')) {
     await lanesComponentsCommand(args);
     return;
@@ -19310,6 +19839,33 @@ async function main() {
     throw new Error('Unknown activity subcommand: ' + subcommand);
   }
 
+  if (command === 'capabilities') {
+    if (wantsHelp) {
+      console.log('Usage: remits-cli capabilities [--json] [--base-url URL]');
+      console.log('');
+      console.log('What this platform build supports for collaboration: negotiated features, the stable verbs and');
+      console.log('how each settles, and what every refusal code means. Read-only; needs no special access.');
+      return;
+    }
+    await capabilitiesCommand(args);
+    return;
+  }
+
+  if (command === 'policy') {
+    if (wantsHelp || subcommand !== 'explain') {
+      console.log('Usage: remits-cli policy explain --point <commit|land|stage|complete|deliver|...> [--workstream W]');
+      console.log('         [--capabilities a,b] [--as human|agent] [--components type:name[:category],...]');
+      console.log('         [--target-account-id ID] [--json]');
+      console.log('');
+      console.log("What this account's remits-policy rules would decide for that action, which rules apply, where");
+      console.log('they come from (document, account distance, final) — without applying anything. The real verb');
+      console.log('re-checks the policy in force when it runs.');
+      return;
+    }
+    await policyExplainCommand(args);
+    return;
+  }
+
   if (command === 'usage') {
     if (wantsHelp) {
       console.log('Usage: remits-cli usage --from DATE [--to DATE] [--timezone ZONE] [--by hour|day|month]');
@@ -19329,7 +19885,7 @@ async function main() {
 
   if (command === 'evidence') {
     if (wantsHelp) {
-      console.log('Usage: remits-cli evidence [--limit N] [--json]');
+      console.log('Usage: remits-cli evidence [--limit N] [--json]   |   remits-cli evidence flush');
       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');
@@ -19337,6 +19893,9 @@ async function main() {
       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.');
+      console.log('');
+      console.log('Inside a work attempt (REMITS_SUPPORT_TICKET_ID), each line is also queued and published to the');
+      console.log('work item as a passive receipt, so a successor elsewhere can read it. `flush` publishes now.');
       return;
     }
     await evidenceCommand(args);

package/lib/builder-kit.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function credentialRequest(text) {
+  const fields = {};
+  for (const line of String(text).split(/\r?\n/)) {
+    const split = line.indexOf('=');
+    if (split > 0) fields[line.slice(0, split)] = line.slice(split + 1);
+  }
+  return fields;
+}
+
+function matchesRepository(fields, repository) {
+  return fields.protocol === 'https' && fields.host === 'github.com' &&
+    String(fields.path || '').replace(/\.git$/, '') === repository;
+}
+
+function helperCommand(node, entry, accountId, baseUrl) {
+  const quote = s => "'" + String(s).replace(/'/g, "'\\''") + "'";
+  return '!' + [node, entry, 'builder', 'credential', '--account-id', accountId, '--base-url', baseUrl].map(quote).join(' ');
+}
+
+function cloneRepository({ cloneUrl, directory, helper }) {
+  if (fs.existsSync(directory)) throw new Error('Choose a new directory for Builder Kit setup.');
+  const url = new URL(cloneUrl);
+  if (url.protocol !== 'https:' || url.hostname !== 'github.com' || url.username || url.password) {
+    throw new Error('Invalid Builder Kit repository URL.');
+  }
+  // Disable inherited credential stores for this operation; only our helper sees the issued token.
+  execFileSync('git', ['-c', 'credential.helper=', '-c', 'credential.helper=' + helper,
+    '-c', 'credential.useHttpPath=true', 'clone', '--', cloneUrl, directory],
+  { stdio: 'inherit', env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+  const git = args => execFileSync('git', ['-C', directory, ...args], { stdio: 'pipe' });
+  git(['config', '--local', '--add', 'credential.helper', '']);
+  git(['config', '--local', '--add', 'credential.helper', helper]);
+  git(['config', '--local', 'credential.useHttpPath', 'true']);
+  return path.resolve(directory);
+}
+
+module.exports = { credentialRequest, matchesRepository, helperCommand, cloneRepository };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.168",
+  "version": "0.1.170",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -12,6 +12,7 @@
   "files": [
     "index.js",
     "lib/sync-operation.js",
+    "lib/builder-kit.js",
     "lib/local-ai.js",
     "lib/websocket-retry.js",
     "README.md",

package/skills/remits-cli/SKILL.md

@@ -64,6 +64,9 @@ reference named after it.
 - **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
   moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
   the OLD code. This is the single most common mistake. (`development-loop.md`)
+- **Iterate on the failing cases; run the whole suite once before landing.** Waiting on test runs is most
+  of a slow build loop, not staging. After each edit run `test run --test X --failed` (only what did not
+  pass last time) or `--names "a|b"`, not the full suite. (`development-loop.md`)
 - **Staging and sync fail early on broken runtime-compiled Groovy.** Stage validates changed source in the
   active lane; sync validates changed/new compiled components before writing DB rows or branch variants.
   Agent files are Utility components internally. A stage refused BY COMPILE VALIDATION still wrote the

package/skills/remits-cli/references/agent-sessions.md

@@ -100,9 +100,18 @@ whole point is that it needs no supervision. Following the transcript is the way
 strictly better than a terminal would be: the output is structured, so it can be read as events
 rather than scraped back out of ANSI text.
 
-**No worker ever commits.** The brief forbids `git commit`/`git push` and nothing in the supervisor
-runs git — a worker leaves its changes in the working tree and says so on the ticket, for a human to
-review.
+**Whether a worker lands is the account's choice, not the supervisor's.** Nothing in the supervisor runs
+git. The brief states the account's landing profile: by default a person lands (the worker leaves changes in
+the working tree and says so on the ticket); an account with `supportPolicy.landing: agent` lets the worker
+land with `remits-cli components commit`, which re-checks the account's rules when it runs.
+
+**Each worker gets its own credential.** For every child the supervisor mints a credential bound to that
+attempt (agent + ticket + run) and revokes it when the child exits; the child authenticates with it
+(`REMITS_AGENT_TOKEN`). The platform therefore knows which participant is calling from the credential, so a
+missing or wrong identity header cannot make a worker a human or another agent. Against an older platform
+the worker simply uses the supervisor's session, as before. Each poll also reports, per running child, when
+it last produced output and its last progress line — separate from the supervisor's own heartbeat, so
+`agent map` can tell a connected supervisor from a child that is actually producing work.
 
 ### Resolving which agent a command means
 

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

@@ -8,6 +8,7 @@
 
 ## Table of Contents
 
+- [Builder Kit and review proposals](#builder-kit-and-review-proposals)
 - [Getting Started](#getting-started)
   - [Authentication](#authentication)
   - [Host vs Data Mode](#host-vs-data-mode)
@@ -21,6 +22,22 @@
   - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
 
+## Builder Kit and review proposals
+
+`remits-cli builder setup --account-id <owner> --directory <new-directory>` clones the owning account's
+repository using your Remits builder sign-in. Add `--base-url` to use a local server. It installs a Git
+credential helper, chooses your workspace, syncs guides and installs the Remits Builder Claude Code plugin.
+Git credentials stay in memory, are restricted to that repository and expire within one hour; the next
+issuance checks your current membership. Existing branch protections and account policies still apply.
+
+After staging and testing, `remits-cli components propose --title "Describe the change"` creates or updates
+a GitHub PR containing **every staged entry in your current lane**. `--branch` selects the base;
+`--workspace` selects your lane. It preserves component sidecars, records staged hashes and includes a
+verification envelope when available. `--json` returns the PR URL and branch. Landing policy can refuse it.
+The command does not merge, sync, clear staging or commit your local checkout. Review and merge the PR,
+then use the normal sync flow. Start a new workspace after a proposal is closed. If someone edits the PR
+branch directly, reconcile that work before proposing again.
+
 ## Getting Started
 
 ### Authentication
@@ -218,13 +235,21 @@ remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id I
 remits-cli agent work [--wait SECONDS] [--json]
 remits-cli agent status [--state idle|working|paused] [--ticket ID] [--activity "..."] [--step "..."]
 remits-cli agent list [--account-id ID] [--json]
-remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane
+remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane; first line = live work vs stored (staged/last-reported) facts
+remits-cli capabilities [--json]                        # collaboration features this platform supports, verbs + how they settle, refusal codes
+remits-cli policy explain --point commit|land|stage|complete|deliver|... [--as human|agent] [--workstream W] [--components type:name[:category],...] [--json]   # what the account rules would decide, and why; nothing applied
+remits-cli evidence [--limit N] [--json] | evidence flush   # your world-stamped trail; inside a ticket attempt it is also published to the ticket as receipts
 remits-cli agent inspect [--account-id ID] [--scope self|children] [--user-id ID|--user-email EMAIL] [--limit N] [--json]
 remits-cli activity inspect [--account-id ID] [--scope self|children|related] [--workspace NAME] [--branch NAME] [--workstream ID] [--user-id ID|--user-email EMAIL] [--limit N] [--json]
 remits-cli workstream status [--workstream ID|--workspace NAME] [--json]
 remits-cli agent release
-remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
-remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
+remits-cli ticket read|accept|status|progress|complete|cancel|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--reason "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
+remits-cli ticket cancel --ticket ID --reason "..." [--expected-revision N]  # close with disposition cancelled; history kept; stops worker
+remits-cli ticket reset-budget --ticket ID                                   # OPERATOR: restore run and spend budget after review
+remits-cli ticket redeliver-events --ticket ID                               # OPERATOR: re-dispatch undelivered lifecycle events
+remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only. 503 code=unavailable = holder unknown: investigate, retry
+remits-cli ticket handoff --ticket ID --summary "..." [--next-step "..."] [--findings "a|b"] [--artifact-refs a,b] [--evidence-refs r1,r2] [--waiting-on X] [--needs cap] [--workstream W] [--exclude] [--expected-revision N]
+remits-cli ticket decide|complete ... [--expected-revision N]   # refused with code=stale_revision (nothing written) if the ticket moved past N
 remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
 remits-cli ticket ask --ticket ID --question "..." [--context "..."] [--to WHO]   # park on a human decision
 remits-cli ticket answer --ticket ID --message "..." [--route false]             # answer it (alias: reply); re-routes by default
@@ -265,7 +290,7 @@ remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force]
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--label <text>] [--param name=value ...] [--repeat N] [--parallel N] [--json]
+remits-cli test run --test <id|name> [--candidate <laneContentHash>] [--branch <stagingScope>] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--label <text>] [--param name=value ...] [--repeat N] [--parallel N] [--json]
 remits-cli test status --task-id <taskId|groupId> [--branch <stagingScope>] [--data-mode test|prod] [--json]   # falls back to the DURABLE run record once the live status expires
 remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--all-lanes] [--as-account <ID>] [--json]  # durable run history: pass counts, live AI cost, lane, content hash
 remits-cli test compare --base <taskId> --head <taskId> [--json]                                            # per-case improved / regressed / changed, cost and world deltas
@@ -281,6 +306,10 @@ remits-cli corpus consistency --corpus <name> --case <caseKey> [--json]
 remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restore] [--json]    # drop a case from future runs; past measurements stay readable
 ```
 
+`--candidate <hash>` names the staged content you mean to test (the lane content hash `components status`
+reports); if another process restaged or the lane expired, the run is refused with `stale_revision` instead of
+testing different source. It binds the start of the run, not every later lookup.
+
 `test run` starts a server-side task immediately. By default the CLI process polls until the task is
 terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
 return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
@@ -589,6 +618,10 @@ For tests specifically:
 - `--names` is `|`-delimited and may be repeated. A selector containing commas matches a case with that
   exact name first, else its comma-separated parts; an unmatched selector fails the run instead of
   reporting zero cases as success.
+- `--failed` re-runs only the cases that did not pass in YOUR last finished run of the suite on this git
+  branch and staging workspace (a `--parallel` run is read as its whole group; the launch lane is preferred,
+  else the lane the suite recorded in). The launch prints the run it read and the cases. "Nothing failed"
+  starts nothing and exits 0; no earlier run is refused. Not combinable with `--names`.
 - `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch
   (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
   (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.

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

@@ -421,9 +421,17 @@ This applies to:
 ```bash
 remits-cli test run --test <TEST_ID_OR_NAME>
 remits-cli test run --test "Invoice Tests" --names "specific test case"
+remits-cli test run --test "Invoice Tests" --failed
 remits-cli test status --task-id <TASK_ID>
 ```
 
+**Iterate narrowly, and run the whole suite once before landing.** Waiting on test runs is most of
+an hour-long build loop, not staging. A suite whose cases run one after another re-pays every case's
+fixture work on every rerun. Run the suite once to see what fails. After each edit, run `--failed` (the
+cases that did not pass in your last finished run of this suite, on this git branch and staging
+workspace) or `--names` for the cases your change touches. Then run the full suite once before landing.
+A full rerun after every edit, with every case passing, is the most common way an agent spends an hour.
+
 Tests run on the platform against your staged snapshot. They stream results in real-time. **Read the
 `World:` block printed before the run** — host, execution account, data lane, component world, staging lane
 id + content hash, platform sync vs local HEAD. If it is not the world you meant, stop: the result will be

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

@@ -347,19 +347,26 @@ discouraged.
 - **A refusal is an ANSWER.** The message names the rule and says what to do instead. Act on that
   sentence. Do not retry the identical call, and do not go looking for another door — the rules govern the
   DSL, the MCP tools and this CLI identically.
-- **`[require]` rules mean a human.** You cannot acknowledge one: the platform decides "human" from the
-  absence of an agent run identity, which your commands always carry. Record what you found with
-  `ticket progress` and hand off.
+- **`[require]` rules mean a human.** You cannot acknowledge one. A supervised worker authenticates with a
+  credential bound to its own attempt, so the platform knows it is an agent from the credential itself —
+  omitting identity headers does not change that. Record what you found with `ticket progress` and hand off.
 - **`[warn]` rules let the call through and write a `policy` worklog entry.** Mention it in your handoff.
 - **Rules can name your role** (`"when":{"role":"triage"}`, or `"role":{"not":["release_manager"]}` for
   "only release managers"). Your role is the one your session registered with; you cannot change it from a
   worker, and passing one on a call does nothing. A refusal naming your role means hand off to the role that
   may.
-- **If you see "POLICY NOT ENFORCED"**, the account's rules could not be parsed. Do not read the absence
-  of a refusal as permission — say so on the ticket. It is a defect in the account's `OPERATIONS` prompt.
-
-The same rules govern `components stage` and `components commit`. A `no-commit` rule is why
-`remits-cli components commit` refuses rather than asks.
+- **If you see a policy problem banner**, part of the account's rules could not be parsed. The rules listed
+  under it are still enforced (a broken replacement keeps its last valid version); do not read the absence
+  of a refusal as permission for the rest — say so on the ticket. **`policy_unavailable`** means a published
+  policy could not be read at all: landing, committing, completing and sending are refused until it can be.
+  Retry later; do not look for another door.
+- **Check before you act**: `remits-cli policy explain --point commit --as agent` says what the rules would
+  decide and which rules apply, without applying anything.
+
+The same rules govern `components stage` and `components commit`. Whether you may land at all is the
+account's **landing profile**, stated in your brief: by default a person lands (leave changes in the working
+tree and describe them); an account that sets `supportPolicy.landing: agent` lets you land with
+`remits-cli components commit`, which re-checks the rules when it runs. A `no-commit` rule always wins.
 
 ### Roles and who may launch them
 
@@ -433,6 +440,7 @@ remits-cli ticket accept   --ticket 22454        # claim it before changing anyt
 remits-cli ticket progress --ticket 22454 --summary "Traced it to the posting Action" --category investigation
 remits-cli ticket status   --ticket 22454 --status in_progress
 remits-cli ticket complete --ticket 22454 --resolution "What you found and did"
+remits-cli ticket cancel   --ticket 22454 --reason "Customer withdrew request"  # outcome no longer wanted; stops running worker
 remits-cli ticket ask      --ticket 22454 --question "Re-issue or skip?" --context "412 affected"
 remits-cli ticket answer   --ticket 22454 --message "Skip them."   # alias: reply
 remits-cli ticket message  --ticket 22454 --message "We reproduced it; a fix is staged."
@@ -590,7 +598,12 @@ remits-cli ticket handoff --summary "fix staged in ticket-19463; needs independe
 ```
 
 The handoff is queued even if nobody is online, `--exclude` keeps you off it (independent review needs
-that), and your own exit will not undo it. A reviewer decides with `ticket decide --request R3 --decision
+that), and your own exit will not undo it. It is a checkpoint: `--findings`, `--next-step`,
+`--artifact-refs`, `--evidence-refs`, `--waiting-on` and `--needs` land in the next worker's brief, so give
+durable references (artifact ids, receipt ids), never local paths. Add `--expected-revision N` (the revision
+you read) to `handoff`, `decide` or `complete` and a ticket that moved on is refused with `stale_revision`
+instead of being overwritten. Your evidence trail is published to the ticket as receipts automatically;
+`remits-cli evidence flush` sends anything still queued. A reviewer decides with `ticket decide --request R3 --decision
 approve|changes|reject --revision <rev>`; "changes" sends the work back with the reviewer's note.
 
 An approval or review can need several people: `request-approval ... --min-approvals 2` stays open until two

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

@@ -144,7 +144,8 @@ account).
 **Recurring schedules:** `action_schedules` lists the target account's Action schedules;
 `action_schedule_update` upserts by `targetAccountId` + `actionId` (or an account-scoped `scheduleId`);
 `action_schedule_delete` removes that schedule and its cloud job. Updates accept `cron`, `timeZone`,
-`enabled` and `dryRun`. `enabled:false` pauses; `enabled:true` resumes while preserving omitted settings.
+`enabled` and `dryRun`. Each run executes as the schedule's owner (`ownerUserId` in reads), who defaults to
+whoever first saves it and is rechecked at every run. `enabled:false` pauses; `enabled:true` resumes while preserving omitted settings.
 `regression_schedule` reads the per-account regression settings and latest report;
 `regression_schedule_update` accepts the same scheduling fields plus `resultAction`, `suiteConcurrency`
 (1–16) and explicit `ownerUserId`. Existing owners are preserved. Only admins may assign another owner;