@remits/remits-cli 0.1.121 → 0.1.124

package/index.js

@@ -19,6 +19,9 @@ const openBrowser = (openModule && typeof openModule === 'function')
 
 //const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'http://localhost:8080';
 const DEFAULT_BASE_URL = process.env.REMITS_BASE_URL || 'https://remits-529558023549.us-east5.run.app';
+
+// How many compile failures print their full message before the rest are listed by identifier only.
+const COMPILE_FAILURES_SHOWN = 5;
 const SESSION_DIR = path.join(os.homedir(), '.remits-cli');
 const SESSIONS_FILE = path.join(SESSION_DIR, 'sessions.json');
 const CONFIG_FILE = path.join(SESSION_DIR, 'config.json');
@@ -1816,6 +1819,19 @@ function resolveSessionContext(cwd, flags) {
   };
 }
 
+/**
+ * Record the FILE identity of a component (type + filename id, or type + filename stem) on an object without
+ * sending it anywhere. Non-enumerable, so JSON payloads and the content hash never see it.
+ *
+ * It exists because a component is named twice: by its files, and by its `.meta.yml` `name:`. For a `new_`
+ * file there is no id, so the two can disagree (`new_PDFStatement` vs `name: PDF Statement`), and the file
+ * identity is the only thing both the payload and the git changed set agree on.
+ */
+function withFileKey(target, key) {
+  Object.defineProperty(target, 'fileKey', { value: key, enumerable: false, configurable: true });
+  return target;
+}
+
 function collectComponents(cwd) {
   const mapping = {
     schemas: 'schema',
@@ -1863,7 +1879,7 @@ function collectComponents(cwd) {
         //
         // A partial stage (mcp_component_edit writing one field) deliberately does NOT set this and
         // keeps the merge semantics it needs.
-        byKey.set(key, { type, id, name, metadataAuthoritative: true });
+        byKey.set(key, withFileKey({ type, id, name, metadataAuthoritative: true }, key));
       }
       const component = byKey.get(key);
       const filePath = path.join(dir, fileName);
@@ -2030,11 +2046,11 @@ function changedComponentsFromWorkingTree(cwd) {
     if (!entry.statuses.includes(status)) entry.statuses.push(status);
     if (!entry.paths.includes(info.path)) entry.paths.push(info.path);
   }
-  return Array.from(byKey.values()).map((entry) => ({
+  return Array.from(byKey.entries()).map(([key, entry]) => withFileKey({
     ...entry,
     fields: entry.fields.sort(),
     paths: entry.paths.sort()
-  })).sort((a, b) => {
+  }, key)).sort((a, b) => {
     const typeCmp = String(a.type).localeCompare(String(b.type));
     if (typeCmp !== 0) return typeCmp;
     return String(a.id || a.name || '').localeCompare(String(b.id || b.name || ''));
@@ -2068,7 +2084,7 @@ function changedComponentsSinceRef(cwd, ref) {
     const info = componentPathInfo(cwd, filePath);
     if (!info) continue;
     if (!byKey.has(info.key)) {
-      byKey.set(info.key, { type: info.type, id: info.id, name: info.name, fields: [], paths: [] });
+      byKey.set(info.key, withFileKey({ type: info.type, id: info.id, name: info.name, fields: [], paths: [] }, info.key));
     }
     const entry = byKey.get(info.key);
     if (!entry.fields.includes(info.field)) entry.fields.push(info.field);
@@ -2756,7 +2772,7 @@ async function pushComponentsCommand(flags) {
   const dataMode = resolveDataMode(flags, session);
   const requestedMode = String(flags.mode || 'stage').toLowerCase();
   const mode = requestedMode === 'push' ? 'stage' : requestedMode;
-  const changedFromWorkingTree = changedComponentsFromWorkingTree(cwd);
+  const changedFromGit = changedComponentsFromWorkingTree(cwd);
 
   // WHAT this stage is. Three shapes, and the difference between them is the difference between a lane
   // that reads as "7 components in flight" and one that reads as "115 staged":
@@ -2776,6 +2792,8 @@ async function pushComponentsCommand(flags) {
   const emptyWorksetPolicy = normalizeEmptyWorksetPolicy(flags);
 
   let components = collectComponents(cwd);
+  // Named the way the payload is named, BEFORE anything compares the two — see alignChangedSetWithComponents.
+  const changedFromWorkingTree = alignChangedSetWithComponents(changedFromGit, components);
   // Changes git reported that a component payload cannot carry — a deleted component file has nothing to
   // stage, and Redis staging has no way to say "hide this during CLI-scoped runs". Removing its staged
   // entry falls back to the committed row, so the component still resolves. Reported out loud rather than
@@ -2785,10 +2803,8 @@ async function pushComponentsCommand(flags) {
     if (changedFromWorkingTree === null) {
       throw new Error('--changed-only needs a git working tree to establish the changed set, and this directory is not one.');
     }
-    const wanted = new Set(changedFromWorkingTree.map((entry) =>
-      entry.type + ':' + (entry.id ? 'id:' + entry.id : 'name:' + String(entry.name || '').toLowerCase())));
-    components = components.filter((component) => wanted.has(
-      component.type + ':' + (component.id ? 'id:' + component.id : 'name:' + String(component.name || '').toLowerCase())));
+    const wanted = new Set(changedFromWorkingTree.map(stageIdentityKey));
+    components = components.filter((component) => wanted.has(stageIdentityKey(component)));
     if (!components.length && !(worksetReplace && emptyWorksetPolicy === 'clear')) {
       // Deliberately NOT an error, and deliberately not a clear. An agent that has not edited anything yet
       // is in an ordinary state; failing its loop teaches it nothing, and reconciling the lane to an empty
@@ -2817,7 +2833,7 @@ async function pushComponentsCommand(flags) {
   // or, worse, conclude staging was broken and go on reading trunk. Scaled by payload size, floored at
   // the old default, and overridable.
   const api = buildAxios(baseUrl, session.token, stageTimeoutMs(components, flags));
-  const response = await stageOrRefuse(api, cwd, {
+  const stagePayload = {
     token: session.token,
     accountId,
     branchName,
@@ -2846,11 +2862,50 @@ async function pushComponentsCommand(flags) {
     // Kept for a platform that predates stageMode. Same meaning it always had.
     replace: !changedOnly,
     components
-  });
+  };
+
+  let response;
+  try {
+    response = await stageOrRefuse(api, cwd, stagePayload);
+  } catch (err) {
+    // A REFUSED stage is evidence too. Recording it only on the success path is how a lane ends up with
+    // an envelope that says nothing happened between two packets, when in fact a stage was attempted and
+    // the platform rejected it. The packet is best-effort: a failing stage must surface the STAGE error,
+    // never an error from writing the record of it.
+    try {
+      await appendVerificationPacket(api, cwd, session, accountId, flags, {
+        type: 'stage',
+        success: false,
+        claim: 'Components refused at staging',
+        world: buildCommandWorld(err.responseBody || {}, { accountId, dataMode, branchName, workspace, host: normalizeBaseUrl(baseUrl), sourceLayer: 'staged' }),
+        revision: collectVerificationSource(cwd, flags),
+        assertions: [
+          { id: 'stage', stageMode },
+          { id: 'stage_refused', value: err.message }
+        ],
+        evidenceCategories: ['stage'],
+        rawRefs: { command: 'components stage' },
+        stage: (err.responseBody || {}).stage,
+        compileValidation: (err.responseBody || {}).compileValidation,
+        changedFromWorkingTree: changedFromWorkingTree || [],
+        unrepresentableChanges: unstageable
+      }, { quiet: true });
+    } catch (packetError) {
+      // Deliberately swallowed and named, not silent.
+      console.error('Could not record the refused-stage verification packet: ' + packetError.message);
+    }
+    throw err;
+  }
   response.changedFromWorkingTree = changedFromWorkingTree || [];
   response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
   response.requestedStageMode = stageMode;
   response.unrepresentableChanges = unstageable;
+  if (response.success === false) {
+    // A 200 that says `success:false`. The 422 path throws out of stageOrRefuse above and never lands
+    // here, so this stays as the belt-and-braces case — print whatever detail came with it first.
+    printCompileValidation(response.compileValidation, { stderr: true });
+    throw new Error(response.message || 'Server stage failed');
+  }
 
   await appendVerificationPacket(api, cwd, session, accountId, flags, {
     type: 'stage',
@@ -2901,16 +2956,71 @@ function normalizeEmptyWorksetPolicy(flags) {
  *
  * Returns [] when git could not answer, because "nothing is unrepresentable" would be a claim.
  */
+/**
+ * The ONE identity a stage compares components by: type + id, or type + name for an id-less `new_` file.
+ * The workset filter and the unrepresentable check used to spell this out separately.
+ */
+function stageIdentityKey(entry) {
+  return entry.type + ':' + (entry.id ? 'id:' + entry.id : 'name:' + String(entry.name || '').toLowerCase());
+}
+
+/**
+ * Name each git-changed component the way its payload is named.
+ *
+ * The changed set is built from FILENAMES; the payload takes `name` from the `.meta.yml`. For a `new_` file
+ * there is no id, so `new_PDFStatement.groovy` + `name: PDF Statement` produced two identities for one
+ * component: `--workset` filtered it out, it was reported as "no-local-files", and the platform (which
+ * matches the changed set against the stored name) never marked it as workset — so a full snapshot staged
+ * it WITHOUT compiling it. Both sides carry the file identity (`fileKey`), so align on that.
+ */
+function alignChangedSetWithComponents(changed, components) {
+  if (!Array.isArray(changed)) return changed;
+  const byFileKey = new Map();
+  (components || []).forEach((component) => {
+    if (component && component.fileKey) byFileKey.set(component.fileKey, component);
+  });
+  return changed.map((entry) => {
+    const component = entry && entry.fileKey ? byFileKey.get(entry.fileKey) : null;
+    if (!component || entry.id || !component.name || component.name === entry.name) return entry;
+    return withFileKey(Object.assign({}, entry, { name: component.name }), entry.fileKey);
+  });
+}
+
+/**
+ * The local components, for identity alignment ONLY on paths that did not already collect them (the sync
+ * gates). Best-effort: a sidecar that does not parse must not stop a sync the server is about to judge.
+ */
+function collectComponentsForIdentity(cwd) {
+  try {
+    return collectComponents(cwd);
+  } catch (_) {
+    return [];
+  }
+}
+
 function unrepresentableChanges(changedFromWorkingTree, collected) {
   if (!Array.isArray(changedFromWorkingTree)) return [];
-  const present = new Set((collected || []).map((component) =>
-    component.type + ':' + (component.id ? 'id:' + component.id : 'name:' + String(component.name || '').toLowerCase())));
-  return changedFromWorkingTree
-    .filter((entry) => !present.has(entry.type + ':' + (entry.id ? 'id:' + entry.id : 'name:' + String(entry.name || '').toLowerCase())))
-    .map((entry) => Object.assign({}, entry, {
-      unrepresentable: true,
-      reason: (entry.statuses || []).some((s) => String(s).includes('D')) ? 'deleted' : 'no-local-files'
-    }));
+  const contentFields = ['source', 'prompt', 'html', 'javascript', 'previewData', 'inputSchema', 'messages', 'schema'];
+  const present = new Map((collected || []).map((component) => [stageIdentityKey(component), component]));
+  const report = [];
+  changedFromWorkingTree.forEach((entry) => {
+    const deleted = (entry.statuses || []).some((s) => String(s).includes('D'));
+    const component = present.get(stageIdentityKey(entry));
+    if (!component) {
+      report.push(Object.assign({}, entry, { unrepresentable: true, reason: deleted ? 'deleted' : 'no-local-files' }));
+      return;
+    }
+    // The component is still present (its other files remain), so it IS staged — but a content file git
+    // reports as deleted has nothing to send, and staged content fields LAYER: the lane keeps whatever it
+    // held before. Reported alongside the component, which stays in the workset.
+    const deletedFields = deleted
+      ? (entry.fields || []).filter((field) => contentFields.includes(field) && component[field] == null)
+      : [];
+    if (deletedFields.length) {
+      report.push(Object.assign({}, entry, { unrepresentable: true, reason: 'content-file-deleted', fields: deletedFields }));
+    }
+  });
+  return report;
 }
 
 function printUnrepresentableChanges(unstageable) {
@@ -2918,12 +3028,23 @@ function printUnrepresentableChanges(unstageable) {
   console.log('');
   console.log('NOT REPRESENTABLE IN REDIS STAGING — ' + unstageable.length + ' change(s):');
   unstageable.slice(0, 20).forEach((entry) => {
+    const fields = Array.isArray(entry.fields) && entry.reason === 'content-file-deleted' ? ': ' + entry.fields.join(', ') : '';
     console.log('  ' + entry.type + ' ' + (entry.id || entry.name || '(unknown)') +
-      '  (' + entry.reason + ')  ' + (entry.paths || []).join(', '));
+      '  (' + entry.reason + fields + ')  ' + (entry.paths || []).join(', '));
   });
   console.log('  A staged entry cannot hide a component. Clearing it falls back to the committed row, so');
   console.log('  the component still resolves in a CLI-scoped run. Prove a deletion through the durable');
   console.log('  plan instead:  remits-cli components sync --dry-run --summary --fail-on-errors');
+  const partial = unstageable.filter((entry) => entry.reason === 'content-file-deleted');
+  if (partial.length) {
+    console.log('  A deleted CONTENT file of a component that is still present is not a staged removal: the');
+    console.log('  lane keeps the content it already held, and compile validation judges THAT. Drop it with:');
+    partial.slice(0, 5).forEach((entry) => {
+      console.log(entry.id
+        ? '    remits-cli components clear --component-type ' + entry.type + ' --component-id ' + entry.id
+        : '    remits-cli components clear --all   (' + entry.type + ' ' + entry.name + ' has no id; this clears only your lane)');
+    });
+  }
 }
 
 /**
@@ -2947,6 +3068,21 @@ async function stageOrRefuse(api, cwd, payload) {
       refusal.refused = true;
       throw refusal;
     }
+    if (body && body.message) {
+      // The server's `message` is ONE line derived from the FIRST failure. The rest of the detail is in
+      // the body, and the caller cannot see the body — an agent handed "compile failed for Reader 41"
+      // over a stage with nine broken components fixes one, re-stages, and pays nine round trips. Render
+      // the whole list HERE, where the body is still in hand, then throw the one-line summary.
+      printCompileValidation(body.compileValidation, { stderr: true });
+      // A refusal can be ABOUT an unrepresentable change: a deleted source file leaves the lane holding the
+      // content it had, and that is what was judged. Without this the refusal names a file that no longer
+      // exists and "fix it and re-stage" cannot work. Read from the payload, which still carries `fields`.
+      printUnrepresentableChanges((payload.changedSet || []).filter((entry) => entry && entry.unrepresentable));
+      const failure = new Error(body.message);
+      failure.responseBody = body;
+      failure.status = status;
+      throw failure;
+    }
     throw err;
   }
 }
@@ -2967,6 +3103,67 @@ function printComponentPolicy(response) {
   (policy.overrides || []).forEach((id) => console.log('Policy override recorded for rule: ' + id));
 }
 
+/**
+ * What the platform compiled, and what it could not.
+ *
+ * Prints on BOTH outcomes, including `attempted: 0`. A silent pass and a pass that validated nothing look
+ * identical otherwise, and they are not the same claim: when git cannot identify the changed set the
+ * server has no workset to validate and says so (`skipped[].reason`). Reporting that as silence would be
+ * the same confident-wrong-number this surface exists to remove.
+ */
+function printCompileValidation(validation, options) {
+  // Failures go to stderr so `--json` stdout stays parseable: a caller that asked for JSON is a program,
+  // and a refusal must not put prose in the middle of its document.
+  const emit = (options && options.stderr) ? console.error : console.log;
+  if (!validation || validation.attempted == null) return;
+  const failures = Array.isArray(validation.failures) ? validation.failures : [];
+  if (validation.attempted === 0) {
+    const reasons = (Array.isArray(validation.skipped) ? validation.skipped : [])
+      .map((entry) => (entry && entry.reason) || '')
+      .filter((reason) => reason && reason !== 'no-compilable-source');
+    if (reasons.length) {
+      emit('Compile validation: NOT RUN — ' + reasons.join(', ') +
+        '. Nothing in this stage was compile-checked.');
+      if (reasons.includes('workset-unknown')) {
+        emit('  git could not identify the changed set, so there was no workset to validate.');
+        emit('  Stage from a git working tree, or re-stage the component explicitly, to get the check.');
+      }
+    }
+    return;
+  }
+  const status = validation.success === true ? 'passed' : 'failed';
+  emit('Compile validation: ' + status + ' — ' + validation.passed + '/' + validation.attempted +
+    ' compiled in ' + validation.durationMs + 'ms' +
+    (validation.concurrency ? ' (' + validation.concurrency + ' parallel)' : ''));
+  // A skip is neither a pass nor a failure, and it used to be printed as a pass ("1/1 compiled" over a
+  // component whose source was blank). Named, so the reader knows exactly what was NOT looked at.
+  const unchecked = Array.isArray(validation.unchecked) ? validation.unchecked : [];
+  if (unchecked.length) {
+    emit('  ' + unchecked.length + ' NOT compile-checked: ' + unchecked.map((entry) =>
+      (entry.type || 'component') + ' ' + (entry.id || entry.name || '?') + ' (' + (entry.reason || 'unchecked') + ')').join(', '));
+  }
+  const shown = failures.slice(0, COMPILE_FAILURES_SHOWN);
+  shown.forEach((failure) => {
+    emit('  ' + (failure.type || 'component') + ' ' + (failure.id || failure.name || '') +
+      ': ' + (failure.message || 'compile failed'));
+  });
+  if (failures.length > shown.length) {
+    // Named, not counted. "3 more failure(s)" sends an agent back for another round trip to learn WHICH
+    // three; the identifiers are already in hand and cost one line.
+    emit('  ' + (failures.length - shown.length) + ' more failed: ' +
+      failures.slice(COMPILE_FAILURES_SHOWN)
+        .map((failure) => (failure.type || 'component') + ' ' + (failure.id || failure.name || '?'))
+        .join(', '));
+    emit('  Re-run with --json for every compile message.');
+  }
+  if (validation.success !== true) {
+    // The lane is written BEFORE it is validated, because the compile has to resolve through the staged
+    // overlay to see the source it is judging. So a refusal does not mean "nothing was staged".
+    emit('  The rejected source IS in the lane: staging writes, then compiles what it wrote.');
+    emit('  A run in this lane will resolve the broken component until you fix it and re-stage.');
+  }
+}
+
 function shouldPrintFullComponentResponse(flags) {
   return flagEnabled(flags.verbose);
 }
@@ -3088,6 +3285,7 @@ function printStageSummary(response, flags) {
   if (overlay != null) {
     console.log('Materialized overlay now held by the lane:', overlay, 'component(s)');
   }
+  printCompileValidation(response.compileValidation);
 
   // The trap `--changed-only` leaves behind: it merges, so a lane inherited from an earlier full snapshot
   // keeps every one of those entries resolving ahead of committed source. Silence here is what made
@@ -3584,7 +3782,9 @@ async function syncComponentsCommand(rawFlags) {
   const forceTombstones = flagEnabled(flags['force-tombstones']) || flagEnabled(flags.forceTombstones);
   const dryRun = flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun);
   const api = buildAxios(baseUrl, session.token);
-  const changedFromWorkingTree = changedComponentsFromWorkingTree(cwd);
+  // Aligned for the same reason a stage is: the server's plan names a `new_` component by its sidecar
+  // `name:`, and the changed set would otherwise name it by its filename and the gate would refuse it.
+  const changedFromWorkingTree = alignChangedSetWithComponents(changedComponentsFromWorkingTree(cwd), collectComponentsForIdentity(cwd));
   const preflightRequested = syncPreflightRequested(flags);
   const namesOnly = flagEnabled(flags['names-only']) || flagEnabled(flags.namesOnly);
 
@@ -3992,7 +4192,7 @@ function evaluateSyncGates(response, flags, changedFromWorkingTree, cwd) {
 
   if (flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) {
     const since = flags['changed-since'] || flags.changedSince;
-    const fromRef = since ? changedComponentsSinceRef(cwd, String(since)) : null;
+    const fromRef = since ? alignChangedSetWithComponents(changedComponentsSinceRef(cwd, String(since)), collectComponentsForIdentity(cwd)) : null;
     if (since && fromRef === null) {
       violations.push('--changed-since: could not diff against "' + since + '". Check the ref exists (git fetch first for a remote ref).');
       checks.changedOnly = false;
@@ -4501,7 +4701,22 @@ async function commitComponentsCommand(flags) {
   const landing = await acquireLandingLease(flags, accountId, branchName);
   try {
   if (!skipGit) {
-    console.log('Phase 1/3: local git commit/push');
+    console.log('Phase 1/4: staged compile validation');
+    // MERGE semantics on purpose (`--changed-only`, never `--workset`). A workset stage RECONCILES the
+    // lane — it deletes every entry outside the git changed set — and the lane is frequently shared. A
+    // validation pass must not be able to delete another agent's staged work as a side effect of somebody
+    // running `components commit`. This adds the changed components to the lane and leaves the rest alone.
+    await pushComponentsCommand(Object.assign({}, flags, {
+      branch: branchName,
+      'account-id': accountId,
+      mode: 'stage',
+      workset: false,
+      'replace-lane': false,
+      replaceLane: false,
+      'changed-only': true
+    }));
+
+    console.log('Phase 2/4: local git commit/push');
     const status = runGit(cwd, 'git status --porcelain');
     if (status || allowEmpty) {
       runGit(cwd, 'git add -A');
@@ -4528,14 +4743,12 @@ async function commitComponentsCommand(flags) {
     console.log('Skipping local git phase. Prefer `remits-cli components sync` if you only need the server sync step.');
   }
 
-  console.log('Phase 2/3: server sync');
+  console.log('Phase 3/4: server sync');
   if (flagEnabled(flags.safe)) {
-    // The honest limit, stated where it applies. `components commit` runs git add/commit/push BEFORE the
-    // server sync, so a --safe gate here cannot stop the push — it stops the PLATFORM from writing bad
-    // overlays. The branch may already be pushed when the gate refuses; that is recoverable, an
-    // unintended ComponentVariant tree is much less so.
-    console.log('  --safe: the branch is already pushed. The gate below stops the platform from WRITING a');
-    console.log('  surprising plan; it cannot un-push. Use `components sync --safe` alone for a pre-push gate.');
+    // Compile validation already ran before the push. The sync safety gates still run after the push
+    // because they need the server's remote-branch plan.
+    console.log('  --safe: compile validation ran before git push; the sync plan gate below runs before');
+    console.log('  the platform writes trunk rows or ComponentVariant overlays.');
   }
   const syncResponse = await syncComponentsCommand({
     ...flags,
@@ -4544,7 +4757,7 @@ async function commitComponentsCommand(flags) {
   });
 
   if (!skipGit) {
-    console.log('Phase 3/3: local fast-forward pull');
+    console.log('Phase 4/4: local fast-forward pull');
     runGit(cwd, 'git fetch origin ' + shellQuote(branchName));
     const expectedSha = syncResponse && syncResponse.sync && syncResponse.sync.postSyncSha;
     if (expectedSha) {
@@ -11144,13 +11357,13 @@ function printComponentsHelp(subcommand) {
   if (subcommand === 'commit') {
     console.log('Usage: remits-cli components commit [--safe] [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
     console.log('');
-    console.log('Runs local git add/commit/push, then server sync. Prefer explicit git + components sync when you need inspectable phases.');
+    console.log('Runs staged compile validation, local git add/commit/push, server sync, then fast-forward pull.');
+    console.log('Prefer explicit stage + git + components sync when you need inspectable phases.');
     console.log('components commit does not support --dry-run.');
     console.log('');
-    console.log('--safe passes the sync gates through to phase 2. The honest limit: git push happens in phase 1,');
-    console.log('so the gate stops the PLATFORM from writing a surprising plan — it cannot un-push the branch.');
-    console.log('For a gate that runs before anything leaves your machine, push yourself and use');
-    console.log('`remits-cli components sync --safe`.');
+    console.log('Phase 1 merge-stages the git-changed components and compile-validates their runtime source.');
+    console.log('It uses --changed-only semantics, so it never reconciles a lane you share with another agent.');
+    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>');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -60,6 +60,12 @@ 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`)
+- **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
+  lane — the compile has to resolve through the staged overlay to see the source it is judging — so fix and
+  re-stage before running anything in that lane. (A policy or edit-lease refusal is the opposite: it
+  returns before any write.) (`development-loop.md`, `component-integrity.md`, `branch-variants.md`)
 - **Stage your WORKSET, not the whole repo: `remits-cli components stage --workset`.** It uploads only
   the components git reports changed and makes the lane hold exactly them. A plain `components stage` is
   a FULL SNAPSHOT — it puts every component in the repo into the lane, so "115 staged" tells a human

package/skills/remits-cli/references/branch-variants.md

@@ -222,6 +222,12 @@ remits-cli components sync --dry-run # inspect overrides/additions/tombstones wi
 remits-cli components sync           # writes ComponentVariant overlays ONLY
 ```
 
+`components stage` validates changed runtime-compiled source through the active branch/workspace lane,
+and `components sync` validates changed/new Groovy source before writing a `ComponentVariant`. This is
+intentional: a branch overlay that cannot compile should fail at staging/sync time, not later when the
+subscriber's workflow first resolves it. `Agent` files in `components/agents/` are the `Utility`
+component kind internally; the CLI and validator normalize both names to the same target.
+
 Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
 for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
 `features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
@@ -330,7 +336,8 @@ The analogous hazard is different, and you must still respect it:
   `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
   staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
   branch has converged back to trunk and the overlay would be removed. It is rejected on trunk, and
-  `components commit --dry-run` is unsupported because `commit` performs local git writes before syncing.
+  `components commit --dry-run` is unsupported because `commit` performs compile validation and local git
+  writes before syncing.
 - **The sync refuses a wholesale removal.** Above roughly a third of a kind — or **100% of a kind at any
   size** — it aborts that kind, reports why, and points at a rebase. Rebasing is almost always the real
   fix. Only when the removals are genuinely deliberate, re-run with `--force-tombstones`.

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

@@ -198,7 +198,7 @@ remits-cli components lanes [--json]                         # every indexed sta
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
-remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # --safe gates phase 2; it cannot un-push phase 1
+remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); --safe gates sync writes
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]

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

@@ -87,21 +87,41 @@ every live component present at its real id, and nothing extra.
 
 | Command | What it touches | Danger |
 |---|---|---|
-| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. | none |
+| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. A plain stage or `--workset` RECONCILES the lane (entries outside the manifest are dropped); `--changed-only` merges. | none for the DB; a lane you share with another agent is reconciled by the first two |
 | `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
 | `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
 | `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
 | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
-| `remits-cli components commit` | **One shot:** `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
+| `remits-cli components commit` | **One shot:** changed-source compile validation (a `--changed-only` MERGE stage, so it never reconciles the lane) + `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
 
 Key implications:
-- **`stage` is always safe** — stage and test as much as you want; it never reconciles or deletes.
-- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it `git add -A`
-  commits and pushes whatever is in the working tree, then immediately syncs. Never run it while the tree
-  contains drift or unexplained changes. Prefer the explicit, observable
-  `git commit → git push → components sync → git pull` sequence so each phase can be inspected.
+- **`stage` never touches the DB or git** — stage and test as much as you want. It is safe *for your
+  components*; it is not inert *for the lane*. A full snapshot and `--workset` both reconcile the lane to
+  their manifest, so on a lane shared with another agent they drop that agent's staged entries. Use
+  `--changed-only` when you mean "add mine, leave theirs".
+- **A COMPILE-VALIDATION refusal still wrote the lane; a policy refusal does not.** Read the status code,
+  because the two refusals leave opposite states behind:
+  - **422 (compile validation)** — the entries are already stored. Validation runs after the write because
+    the compile has to resolve through the staged overlay to see the source it is judging. The response
+    says so with `laneHoldsRejectedSource`. Until you fix the source and re-stage, a run in that lane
+    resolves the broken component.
+  - **409 (account policy, or another agent's edit lease)** — refused before anything was written. The lane
+    is exactly as it was; nothing to undo.
+- **"Compile validation: NOT RUN" is a real answer.** The check keys off the git changed set. If git
+  cannot identify one — you are not in a working tree, or git failed — there is no workset to validate and
+  the CLI says `workset-unknown` rather than implying a pass.
+- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it first
+  merge-stages and compile-validates the changed runtime source, then `git add -A`, commits, pushes, and
+  immediately syncs. Never run it while the tree contains drift or unexplained changes. Prefer the explicit,
+  observable `components stage → git commit → git push → components sync → git pull` sequence so each
+  phase can be inspected.
 - **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
   pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
+- **Runtime-compiled component source is validated before durable writes.** When a trunk sync or variant
+  sync sees changed/new Groovy source for a `Reader`, `Action`, `Embeddable`, `HtmlTemplate`, `Rule`,
+  `Test`, `Agent`/`Utility`, or `Tool`, the platform compiles it before accepting the DB row or
+  `ComponentVariant` overlay. A compile failure lands in `syncResults.errors` and the branch SHA cache is
+  not advanced, so fix the source and retry the same sync.
 - After a successful non-dry-run `components sync` / `components commit`, the server clears the full
   staging scope for that lane (account/user/branch/workspace). This is the expected clean state: old Redis aliases should not keep shadowing
   the newly synced DB rows. `components sync --dry-run` intentionally leaves staging untouched.

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

@@ -218,6 +218,33 @@ remits-cli components stage --workset    # every edit: stage what you changed
 
 This uploads your local component changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
 
+For runtime-compiled components (`Reader`, `Action`, `Embeddable`, `HtmlTemplate`, `Rule`, `Test`,
+`Agent`/`Utility`, and `Tool`), staging also validates the Groovy source that is part of the submitted
+workset. Validation resolves through the same branch/workspace staging lane a later run will use and
+compiles candidates in a small bounded pool, so a syntax/compile error is reported by `components stage`
+instead of waiting for the next workflow to trip over it. A full repository stage does not compile every
+component in the repo; it validates only entries known to be in the current workset, plus explicit partial
+source updates.
+
+Two things to read correctly when it refuses:
+
+- **The lane already holds what it rejected — on a 422.** The compile has to resolve through the staged
+  overlay to see the source it is judging, so the entries are written first and compiled second. `422`
+  means "staged, and rejected", not "nothing happened" — fix the source and re-stage before running
+  anything in that lane. A `409` is the other kind of refusal (account policy, or another agent's edit
+  lease) and writes nothing at all.
+- **Every failure is printed, not just the first.** The one-line error is the first failure; the full list
+  (identified by type and id) follows it. Fix them in one pass rather than one round trip each.
+- **`N NOT compile-checked` is not a pass.** A `new_` component whose source file is empty or blank cannot
+  be judged, so it is listed by name with its reason instead of being counted as compiled. It will not run.
+- **Deleting a component's source file while its sidecar stays is `content-file-deleted`.** The lane keeps
+  the source it already held, and that is what gets compiled and run. Clear that one component with the
+  command the CLI prints (`components clear --component-type <type> --component-id <id>`).
+
+If git cannot identify the changed set — you are not in a working tree, or git failed — there is no
+workset to validate, and the CLI prints `Compile validation: NOT RUN — workset-unknown` rather than
+silently implying a pass.
+
 ##### Stage your workset, not the whole repo
 
 There are three stage modes, and the difference decides what a run in your lane resolves and what a