session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/wave-resource-gate.mjs

@@ -123,6 +123,14 @@ async function applyDecisionRules(measurements, opts) {
  * declares a remote host that accepts this wave role, route the wave to that
  * host at its full planned agent count instead of shrinking it.
  *
+ * `offload-first: true` in Session Config (#1465) widens that trigger to a
+ * `proceed` verdict too: an offloadable wave role goes to a ready host even when
+ * the local host has headroom. Host selection, the witness contract and the
+ * HR-004 cap below are identical on both paths. With the switch on, a wave that
+ * stays local anyway (no host declared, none ready) carries a named
+ * `offload-first:` reason, so the switch never fails silently; a role absent
+ * from OFFLOADABLE_WAVE_ROLES stays local without one.
+ *
  * The gate does NOT probe the network — a placement decision must stay a pure
  * function of its inputs. The caller supplies a readiness WITNESS:
  *   - `opts.remoteReady` — `{ [alias]: boolean }`, e.g. built from the
@@ -140,13 +148,24 @@ async function applyDecisionRules(measurements, opts) {
  * @returns {Promise<{decision: string, agents: number, reasons: string[], measurements: object, host?: string}>}
  */
 async function applyOffloadDecision(result, opts) {
-  if (result.decision !== 'reduce' && result.decision !== 'coordinator-direct') return result;
+  const offloadFirst = opts.config?.['offload-first'] === true;
+  if (!offloadFirst && result.decision !== 'reduce' && result.decision !== 'coordinator-direct') {
+    return result;
+  }
 
   const { config, plannedAgents, waveRole, remoteReady, probeFn = null } = opts;
+  const role = String(waveRole ?? '').trim().toLowerCase();
   const hosts = config?.['remote-hosts'];
-  if (!Array.isArray(hosts) || hosts.length === 0) return result;
+  if (!Array.isArray(hosts) || hosts.length === 0) {
+    // Only an offloadable role could have been placed, so only it gets the note.
+    return offloadFirst && OFFLOADABLE_WAVE_ROLES[role] !== undefined
+      ? {
+          ...result,
+          reasons: [...result.reasons, 'offload-first: true but no remote-hosts declared — staying local'],
+        }
+      : result;
+  }
 
-  const role = String(waveRole ?? '').trim().toLowerCase();
   // No isNeverForeignRole() check here (D8 #1204 LOW-1): the invariant is
   // enforced STRUCTURALLY by this mapping table, not by an extra guard.
   // NEVER_FOREIGN_ROLES {impl-core, security-review, migration, release,
@@ -186,9 +205,10 @@ async function applyOffloadDecision(result, opts) {
     }
   }
   if (host === undefined) {
-    return probeFailures.length === 0
-      ? result
-      : { ...result, reasons: [...result.reasons, ...probeFailures] };
+    const notes = offloadFirst
+      ? [...probeFailures, `offload-first: no ready host for '${role}' — staying local`]
+      : probeFailures;
+    return notes.length === 0 ? result : { ...result, reasons: [...result.reasons, ...notes] };
   }
 
   // The wave runs at its planned size again — but never above the HR-004 static
@@ -207,7 +227,9 @@ async function applyOffloadDecision(result, opts) {
     host: host.alias,
     reasons: [
       ...result.reasons,
-      `offload: ${role} routed to host '${host.alias}' instead of reducing to ${result.agents}`,
+      result.decision === 'proceed'
+        ? `offload-first: ${role} routed to host '${host.alias}' (verdict was proceed)`
+        : `offload: ${role} routed to host '${host.alias}' instead of reducing to ${result.agents}`,
     ],
     measurements: result.measurements,
   };
@@ -383,14 +405,18 @@ export async function evaluateWaveResourceGate(opts) {
   }
 
   // Rule 2: probe the system (or use override for tests).
+  // A failed probe yields `proceed`. Under `offload-first: true` (#1465) that
+  // result still goes through placement: routing to a witnessed-ready host needs
+  // no local measurement, so a broken probe must not silently disable the switch.
   const measured = await extractMeasurements(opts);
   if ('probeFailed' in measured) {
-    return {
+    const failed = {
       decision: 'proceed',
       agents: plannedAgents,
       reasons: ['probe failed (ignored)'],
       measurements: {},
     };
+    return config['offload-first'] === true ? applyOffloadDecision(failed, opts) : failed;
   }
 
   // Rules 3-8: apply decision rule sequence.

package/scripts/materialize-wave-scope.mjs

@@ -26,7 +26,7 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { writeJsonAtomicSync } from './lib/io.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
-import { isPeerRecordId } from './lib/scope-gate.mjs';
+import { COORDINATOR_RECORD_ID, isCoordinatorRecordId, isPeerRecordId } from './lib/scope-gate.mjs';
 import { SCOPE_MATERIALIZED_EVENT, scopeDigest } from './lib/scope-echo.mjs';
 import {
   MANIFEST_SESSION_KEYS,
@@ -214,8 +214,8 @@ export function validateScopeRecords(value) {
       throw new InputError(`record #${recordIndex} has duplicate id (case-insensitive): ${record.id}`);
     }
     seenIds.add(idKey);
-    if (idKey === 'coordinator') {
-      if (record.id !== 'coordinator') {
+    if (idKey === COORDINATOR_RECORD_ID) {
+      if (!isCoordinatorRecordId(record.id)) {
         throw new InputError(`record #${recordIndex} id must be exactly coordinator (lowercase)`);
       }
       coordinatorCount++;
@@ -537,7 +537,10 @@ export function transportObservable(pluginRoot = resolve(import.meta.dirname, '.
 async function emitScopeMaterialized({ stateDir, wave, records }) {
   try {
     const repoRoot = dirname(resolve(stateDir));
-    const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+    // Dispatched agents only: a peer's record gets no per-agent file, and the
+    // coordinator's is a declaration no dispatch carries — counted, its empty
+    // `files` (the common case) read as "two agents share one scope" (#1493.2).
+    const agentRecords = records.filter((r) => !isPeerRecordId(r.id) && !isCoordinatorRecordId(r.id));
     const digests = new Set();
     for (const record of agentRecords) {
       if (Array.isArray(record.files) && record.files.length > 0) digests.add(scopeDigest(record.files));

package/scripts/memory-propose.mjs

@@ -35,6 +35,7 @@
  * Related modules:
  *   scripts/lib/memory-proposals/schema.mjs — createProposalRecord, PROPOSAL_TYPES
  *   scripts/lib/memory-proposals/store.mjs  — appendProposal
+ *   scripts/lib/learnings/schema.mjs        — isRepoRelativePathEntry (--file-paths)
  *   scripts/lib/state-md.mjs               — resolveStateMdPath, parseStateMd
  *   scripts/parse-config.mjs               — Session Config subprocess
  */
@@ -42,9 +43,10 @@
 import { parseArgs } from 'node:util';
 import { readFileSync, existsSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { dirname, join, isAbsolute } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { isRepoRelativePathEntry } from './lib/learnings/schema.mjs';
 import { isWaveAgentContext, WAVE_AGENT_ENV_VAR, WAVE_AGENT_ENV_VALUE } from './lib/wave-context.mjs';
 import { readProcessLocalSessionIds, manifestSessionBinding } from './lib/session-identity/own-session.mjs';
 import { readLockDetailed } from './lib/session-lock.mjs';
@@ -197,6 +199,14 @@ if (confidenceRaw !== undefined) {
 // (Step 6) — so a malformed --file-paths value produces the same exit-4
 // argv-error contract as every other required/optional flag, never a
 // downstream schema-validation surprise.
+//
+// The repo-relative rule is `isRepoRelativePathEntry` from learnings/schema.mjs
+// — the predicate strict validateLearning() applies to `file_paths` at write
+// time. A looser rule here (it was `path.isAbsolute`, blind to `~/x`, `C:\x`,
+// UNC and URL entries) queued proposals that the operator approved and
+// appendLearning() then refused, so the learning never landed. The checks below
+// it (newline, glob metacharacters, count, length) are this CLI's own, stricter
+// additions.
 
 const FILE_PATHS_MAX_COUNT = 20;
 const FILE_PATH_MAX_CHARS = 256;
@@ -219,10 +229,13 @@ if (filePaths !== undefined) {
     );
   }
   for (const p of filePaths) {
-    if (isAbsolute(p)) {
-      argErrors.push(`--file-paths must be repo-relative — absolute path rejected: "${p}"`);
-    } else if (p.split(/[\\/]/).includes('..')) {
-      argErrors.push(`--file-paths must not contain ".." path segments: "${p}"`);
+    if (!isRepoRelativePathEntry(p)) {
+      // The `..` probe only picks the message; the predicate decides.
+      argErrors.push(
+        p.split(/[\\/]/).includes('..')
+          ? `--file-paths must not contain ".." path segments: "${p}"`
+          : `--file-paths must be repo-relative — absolute path rejected (leading /, \\ or ~, Windows drive, UNC or URL): "${p}"`,
+      );
     } else if (/[\r\n]/.test(p)) {
       argErrors.push(`--file-paths entries must not contain newline characters: "${p}"`);
     } else if (/[*?[\]{}]/.test(p)) {

package/scripts/release-session-lock.mjs

@@ -43,6 +43,7 @@
  */
 
 import { parseArgs } from 'node:util';
+import path from 'node:path';
 
 import { readLockDetailed, loadOwnerProof, release } from './lib/session-lock.mjs';
 import { LOCK_RELEASED_EVENT } from './lib/session-transition.mjs';
@@ -174,7 +175,7 @@ export async function main({ argv = process.argv.slice(2) } = {}) {
     return 1;
   }
 
-  const repoRoot = values['repo-root'] ?? process.cwd();
+  const repoRoot = path.resolve(values['repo-root'] ?? process.cwd());
 
   const emitResult = async (result) => {
     if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + '\n');

package/scripts/release.mjs

@@ -1303,14 +1303,21 @@ export function evaluatePublishReceipt(result, target) {
  * failure remains visible, but none invalidates the already irreversible npm
  * publish; callers must reconcile rather than retry `--publish`.
  *
+ * `npm view <pkg> version` resolves the `latest` dist-tag (and `npm view` fetches
+ * with `preferOnline`, so no local cache masks the answer): the poll returns
+ * `verified` on the first attempt whose `dist-tags.latest` equals `target`.
+ * Default budget: 12 attempts, 15 s apart = 165 s between the first and last
+ * poll. npm's registry needs ~2 min to serve a fresh `latest` (#1440 C2); the
+ * previous 5 x 3 s = 12 s budget reported `timeout` on every real publish.
+ *
  * @param {string} repoRoot
  * @param {string} target
  * @param {{attempts?: number, delaySeconds?: number, runImpl?: Function, waitImpl?: Function}} [deps]
  * @returns {{ok: boolean, kind: 'verified'|'timeout'|'query-failed'|'wait-failed', attempts: number, detail: string}}
  */
 export function waitForRegistryPropagation(repoRoot, target, deps = {}) {
-  const attempts = deps.attempts ?? 5;
-  const delaySeconds = deps.delaySeconds ?? 3;
+  const attempts = deps.attempts ?? 12;
+  const delaySeconds = deps.delaySeconds ?? 15;
   const runImpl = deps.runImpl ?? run;
   const waitImpl = deps.waitImpl ?? (() => runImpl('sleep', [String(delaySeconds)], { cwd: repoRoot }));
 
@@ -1674,6 +1681,7 @@ export function printPublishOutcome(outcome, target, io = {}) {
   log('\nPost-release checklist (manual):');
   log('  1. Rotate/delete the npm token: https://www.npmjs.com/settings/<user>/tokens');
   log('  2. pi.dev gallery indexes asynchronously — do not block on it.');
+  log('  3. Install the release on this host: npm run update:local -- --skip-pull, then restart the harness.');
   return 0;
 }
 
@@ -1894,7 +1902,7 @@ async function main() {
     console.log(`Rewrote ${changed.length} surface file(s) to ${target}:`);
     for (const f of changed) console.log(`  ${f}`);
     console.log('  package-lock.json (via npm install --package-lock-only)');
-    console.log('  site/index.html cells + site/_census.json re-stamped (scripts/site-numbers.mjs --write) — commit BOTH');
+    console.log('  site/ page cells + site/_census.json + site/sitemap.xml lastmod re-stamped (scripts/site-numbers.mjs --write) — commit ALL of them');
     console.log('\nEditorial TODOs (enforced by --check):');
     console.log(`  1. CHANGELOG.md — write the "## [${target}] - YYYY-MM-DD" entry, fold [Unreleased].`);
     console.log('  2. README.md — rewrite the "Recent highlights" section content.');

package/scripts/repair-invalid-sessions.mjs

@@ -18,7 +18,11 @@
  * over the target (atomic), and the result is then re-verified against BOTH
  * `validateSession` and `checkSessionsIntegrity`. A failed verification restores
  * the backup byte-identically and exits 3 — the ledger is never left in a state
- * worse than the one this CLI found.
+ * worse than the one this CLI found. Records with no defensible repair (a
+ * timestamp that is not ISO-8601 at all, a waves entry that is not an object)
+ * are kept byte-identical and do NOT trigger that rollback (#1442): the repair
+ * of every other line is kept, and the run exits 4 so a caller can tell "clean"
+ * from "clean except N lines nobody can repair".
  *
  * TARGET CONSTRAINT (MED-3): `--file` MUST resolve inside
  * `<repo-root>/.orchestrator/metrics/`. Any target outside it — including a
@@ -32,6 +36,10 @@
  *   1 — user/input error (bad flag, unknown argument)
  *   2 — system error (unreadable/unwritable ledger, I/O failure)
  *   3 — post-verification failed; the backup was restored and nothing was kept
+ *   4 — completed, but N unrepairable lines remain (apply: every repairable
+ *       line was fixed and verified, the N were kept byte-identical; dry-run:
+ *       the N lines that WOULD remain are listed). Checked after 3: a
+ *       rolled-back run is always 3, never 4.
  */
 
 import fs from 'node:fs';
@@ -53,7 +61,9 @@ const USAGE =
   ');\n' +
   '                must resolve inside <repo-root>/.orchestrator/metrics/\n' +
   '  --repo-root   project root (default: resolved project dir)\n' +
-  'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n';
+  'Exit codes: 0 completed, 1 arg error, 2 system error, 3 post-verification failed\n' +
+  '            (backup restored), 4 unrepairable remain (N lines kept byte-identical;\n' +
+  '            every repairable line fixed — dry-run: would remain)\n';
 
 /**
  * Resolve `--file` and REFUSE any target outside
@@ -127,7 +137,10 @@ export function renderHuman(s) {
   }
   if (s.backup_path) lines.push(`  backup:          ${s.backup_path}`);
   if (s.errors.length > 0) {
-    lines.push(`  errors:          ${s.errors.length} (original line kept)`);
+    // #1442: name every line that stays invalid — in dry-run BEFORE anything is
+    // written, so the operator knows the remainder --apply will leave behind.
+    const verb = s.mode === 'apply' ? 'remain' : 'would remain';
+    lines.push(`  unrepairable:    ${s.errors.length} (${verb} invalid; original line kept byte-identical)`);
     for (const e of s.errors) lines.push(`    line ${e.line} ${e.session_id ?? '<no session_id>'}: ${e.error}`);
   }
   if (s.post_verify && s.post_verify.integrity !== 'clean' && s.post_verify.integrity !== 'skipped-not-canonical-path') {
@@ -135,10 +148,30 @@ export function renderHuman(s) {
   }
   if (s.ok === false) {
     lines.push('  POST-VERIFICATION FAILED — backup restored, ledger unchanged.');
+  } else if (s.errors.length > 0) {
+    lines.push(
+      s.mode === 'apply'
+        ? `  Repairable lines fixed and verified; ${s.errors.length} unrepairable line(s) left as they were (exit 4).`
+        : `  --apply would fix every repairable line and leave ${s.errors.length} unrepairable line(s) as they are (exit 4).`
+    );
   }
   return lines.join('\n') + '\n';
 }
 
+/**
+ * Map a `repairLedger` summary to the exit-code contract in the header.
+ * Rollback (3) wins over an unrepairable remainder (4): a restored ledger kept
+ * nothing, so "N remain" would describe a write that did not happen.
+ *
+ * @param {object} summary
+ * @returns {0|3|4}
+ */
+export function exitCodeFor(summary) {
+  if (summary.ok === false) return 3;
+  if (summary.unrepairable > 0) return 4;
+  return 0;
+}
+
 async function main() {
   let parsed;
   try {
@@ -197,7 +230,7 @@ async function main() {
   } else {
     process.stdout.write(renderHuman(summary));
   }
-  process.exit(summary.ok === false ? 3 : 0);
+  process.exit(exitCodeFor(summary));
 }
 
 const isDirectRun =isMainModule(import.meta.url);

package/scripts/run-migrate-v2-cross-repo.mjs

@@ -3,7 +3,12 @@
  * run-migrate-v2-cross-repo.mjs — cross-repo Migrate-CLI v2 runner.
  *
  * Walks a list of repos, applies the v2 migration to each repo's learnings.jsonl,
- * and reports pre/post invalid-rate per repo.
+ * and reports pre/post invalid-rate per repo — plus, per repo and in the
+ * aggregate, the count of invalid records per validation error class before and
+ * after migration (`errorClassesPre` / `errorClassesPost`, GitHub #69 / GitLab
+ * #1446). An error class is the validateLearning message up to `, got:`
+ * (e.g. `scope must be one of local|private|public`), so a dry run shows which
+ * failure kinds the migration fixes and which remain.
  *
  * Usage:
  *   node scripts/run-migrate-v2-cross-repo.mjs [--repos <comma-list>] [--apply] [--json] [--out <path>]
@@ -11,15 +16,20 @@
  * Flags:
  *   --repos <comma-list>  Comma-separated repo paths (absolute or ~-prefixed).
  *                         When omitted, uses the hardcoded ROLLOUT_REPOS list.
- *   --apply               Write migrated records back to each file (atomic).
- *                         DEFAULT is dry-run (no writes).
+ *   --apply               Write migrated records back to each file (atomic),
+ *                         under that store's lock (`withLearningsLock`, the
+ *                         `<store>.lock` every learnings writer takes), so a
+ *                         live session appending in that repo is never lost.
+ *                         DEFAULT is dry-run (no writes, no lock).
  *   --json                Output machine-readable JSON instead of Markdown table.
  *   --out <path>          Write output to file instead of stdout.
  *
  * Exit codes:
  *   0  Success (including repos with no learnings.jsonl — gracefully skipped)
  *   1  Input/argument error
- *   2  I/O error
+ *   2  I/O error — incl. a store lock not acquired under --apply: that repo
+ *      is left unwritten and reported `status: 'error'`, the run continues
+ *      with the next repo, and exits 2 at the end
  */
 
 import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
@@ -30,6 +40,7 @@ import {
   migrateLegacyLearning,
   validateLearning,
 } from './lib/learnings.mjs';
+import { LearningsLockError, withLearningsLock } from './lib/learnings/io.mjs';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 
@@ -135,47 +146,102 @@ if (reposArg) {
  * @property {number} invalidPost - invalid records after migration
  * @property {number} fixedByV2  - records that became valid after migration
  * @property {number} malformed  - JSON-parse failures (preserved, not counted in invalid)
+ * @property {Record<string, number>} errorClassesPre  - invalid-pre count per error class
+ * @property {Record<string, number>} errorClassesPost - invalid-post count per error class
  * @property {string|null} error  - error message if status=error
  */
 
+/**
+ * Reduce a validateLearning error message to its class: the text before the
+ * record-specific `, got: <value>` tail. Messages without that tail (e.g.
+ * `learning missing required field: subject`) are their own class.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errorClassOf(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const idx = message.indexOf(', got:');
+  return idx === -1 ? message : message.slice(0, idx);
+}
+
+/**
+ * @param {Record<string, number>} counts
+ * @param {string} cls
+ */
+function bump(counts, cls) {
+  counts[cls] = (counts[cls] ?? 0) + 1;
+}
+
+/**
+ * A RepoResult that counted nothing.
+ *
+ * @param {string} repoPath
+ * @param {string} status
+ * @param {string|null} error
+ * @returns {RepoResult}
+ */
+function emptyResult(repoPath, status, error) {
+  return {
+    repo: repoPath,
+    status,
+    total: 0,
+    invalidPre: 0,
+    invalidPost: 0,
+    fixedByV2: 0,
+    malformed: 0,
+    errorClassesPre: {},
+    errorClassesPost: {},
+    error,
+  };
+}
+
+/** Repos whose store lock was not acquired under --apply (nothing written there). */
+const lockFailedRepos = [];
+
 /**
  * Process a single repo. Returns a RepoResult.
  *
+ * Under --apply the WHOLE read → backup → rename runs inside the store lock:
+ * these are other repos, where a live session may append between this read
+ * and the rename — outside the lock that record would be silently replaced.
+ * A dry run writes nothing and takes no lock.
+ *
  * @param {string} repoPath - resolved absolute path to the repo
  * @param {boolean} apply   - whether to write changes back
- * @returns {RepoResult}
+ * @returns {Promise<RepoResult>}
  */
-function processRepo(repoPath, apply) {
+async function processRepo(repoPath, apply) {
   const learningsPath = join(repoPath, LEARNINGS_REL);
 
-  if (!existsSync(learningsPath)) {
-    return {
-      repo: repoPath,
-      status: 'skipped',
-      total: 0,
-      invalidPre: 0,
-      invalidPost: 0,
-      fixedByV2: 0,
-      malformed: 0,
-      error: null,
-    };
+  if (!existsSync(learningsPath)) return emptyResult(repoPath, 'skipped', null);
+  if (!apply) return migrateStore(repoPath, learningsPath, false);
+
+  try {
+    return await withLearningsLock(learningsPath, () => migrateStore(repoPath, learningsPath, true));
+  } catch (err) {
+    if (!(err instanceof LearningsLockError)) throw err;
+    lockFailedRepos.push(repoPath);
+    return emptyResult(repoPath, 'error', err.message);
   }
+}
 
+/**
+ * Read, migrate and (when `apply`) atomically rewrite one store. Under --apply
+ * the caller holds the store lock.
+ *
+ * @param {string} repoPath
+ * @param {string} learningsPath
+ * @param {boolean} apply
+ * @returns {RepoResult}
+ */
+function migrateStore(repoPath, learningsPath, apply) {
   // Read
   let raw;
   try {
     raw = readFileSync(learningsPath, 'utf8');
   } catch (err) {
-    return {
-      repo: repoPath,
-      status: 'error',
-      total: 0,
-      invalidPre: 0,
-      invalidPost: 0,
-      fixedByV2: 0,
-      malformed: 0,
-      error: `read failed: ${err.message}`,
-    };
+    return emptyResult(repoPath, 'error', `read failed: ${err.message}`);
   }
 
   const lines = raw.split('\n').filter((l) => l.trim().length > 0);
@@ -184,6 +250,10 @@ function processRepo(repoPath, apply) {
   let invalidPre = 0;
   let invalidPost = 0;
   let fixedByV2 = 0;
+  /** @type {Record<string, number>} */
+  const errorClassesPre = {};
+  /** @type {Record<string, number>} */
+  const errorClassesPost = {};
   const outputLines = [];
 
   for (const line of lines) {
@@ -201,9 +271,10 @@ function processRepo(repoPath, apply) {
     let wasValidPre = true;
     try {
       validateLearning({ ...parsed, schema_version: parsed.schema_version ?? 1 });
-    } catch {
+    } catch (err) {
       wasValidPre = false;
       invalidPre++;
+      bump(errorClassesPre, errorClassOf(err));
     }
 
     // Migrate
@@ -217,9 +288,10 @@ function processRepo(repoPath, apply) {
         ...migrated,
         schema_version: migrated.schema_version ?? 1,
       });
-    } catch {
+    } catch (err) {
       isValidPost = false;
       invalidPost++;
+      bump(errorClassesPost, errorClassOf(err));
     }
 
     if (!wasValidPre && isValidPost) {
@@ -259,6 +331,8 @@ function processRepo(repoPath, apply) {
         invalidPost,
         fixedByV2,
         malformed,
+        errorClassesPre,
+        errorClassesPost,
         error: `write failed: ${err.message}`,
       };
     }
@@ -272,6 +346,8 @@ function processRepo(repoPath, apply) {
     invalidPost,
     fixedByV2,
     malformed,
+    errorClassesPre,
+    errorClassesPost,
     error: null,
   };
 }
@@ -280,7 +356,10 @@ function processRepo(repoPath, apply) {
 // Run across all repos
 // ---------------------------------------------------------------------------
 
-const results = repos.map((r) => processRepo(r, applyFlag));
+// Sequential: one store lock at a time, and a lock failure in one repo never
+// stops the next.
+const results = [];
+for (const r of repos) results.push(await processRepo(r, applyFlag));
 
 // ---------------------------------------------------------------------------
 // Aggregate
@@ -294,6 +373,12 @@ const aggregate = results.reduce(
     acc.totalMalformed += r.malformed;
     acc.totalReposProcessed += r.status !== 'skipped' ? 1 : 0;
     acc.totalReposSkipped += r.status === 'skipped' ? 1 : 0;
+    for (const [cls, n] of Object.entries(r.errorClassesPre)) {
+      acc.errorClassesPre[cls] = (acc.errorClassesPre[cls] ?? 0) + n;
+    }
+    for (const [cls, n] of Object.entries(r.errorClassesPost)) {
+      acc.errorClassesPost[cls] = (acc.errorClassesPost[cls] ?? 0) + n;
+    }
     return acc;
   },
   {
@@ -303,6 +388,10 @@ const aggregate = results.reduce(
     totalMalformed: 0,
     totalReposProcessed: 0,
     totalReposSkipped: 0,
+    /** @type {Record<string, number>} */
+    errorClassesPre: {},
+    /** @type {Record<string, number>} */
+    errorClassesPost: {},
   }
 );
 
@@ -319,6 +408,26 @@ function fmtPct(count, total) {
   return `${count} (${((count / total) * 100).toFixed(1)}%)`;
 }
 
+/**
+ * Markdown table of invalid-record counts per error class, pre vs post
+ * migration. Classes are the union of both sides, sorted by pre count desc.
+ *
+ * @param {Record<string, number>} pre
+ * @param {Record<string, number>} post
+ * @returns {string[]}
+ */
+function errorClassTable(pre, post) {
+  const classes = [...new Set([...Object.keys(pre), ...Object.keys(post)])].sort(
+    (a, b) => (pre[b] ?? 0) - (pre[a] ?? 0) || a.localeCompare(b)
+  );
+  if (classes.length === 0) return ['_No validation errors._'];
+  const rows = ['| Error class | Invalid pre | Invalid post |', '|-------------|-------------|--------------|'];
+  for (const cls of classes) {
+    rows.push(`| ${cls.replaceAll('|', '\\|')} | ${pre[cls] ?? 0} | ${post[cls] ?? 0} |`);
+  }
+  return rows;
+}
+
 function buildMarkdown(results, aggregate, mode) {
   const lines = [];
   lines.push(`# Cross-Repo Migrate-CLI v2 — ${mode} report`);
@@ -345,6 +454,17 @@ function buildMarkdown(results, aggregate, mode) {
   lines.push(`- Repos processed: **${aggregate.totalReposProcessed}**`);
   lines.push(`- Repos skipped (no learnings.jsonl): **${aggregate.totalReposSkipped}**`);
   lines.push('');
+  lines.push('## Error classes (all repos)');
+  lines.push('');
+  lines.push(...errorClassTable(aggregate.errorClassesPre, aggregate.errorClassesPost));
+  lines.push('');
+  for (const r of results) {
+    if (r.status === 'skipped') continue;
+    lines.push(`### ${repoName(r.repo)}`);
+    lines.push('');
+    lines.push(...errorClassTable(r.errorClassesPre, r.errorClassesPost));
+    lines.push('');
+  }
   return lines.join('\n');
 }
 
@@ -382,4 +502,24 @@ process.stderr.write(
     `${aggregate.totalStillInvalidPost} still-invalid\n`
 );
 
-process.exit(0);
+let exitCode = 0;
+if (lockFailedRepos.length > 0) {
+  process.stderr.write(
+    `run-migrate-v2: ERROR learnings store lock not acquired, nothing written in ${lockFailedRepos.length} repo(s): ` +
+      `${lockFailedRepos.join(', ')}\n`
+  );
+  exitCode = 2;
+}
+
+// #1487.15: every other `status: 'error'` (read failed / write failed) is an
+// I/O error too — exit 2 as the header and --help document, never 0.
+const ioFailed = results.filter((r) => r.status === 'error' && !lockFailedRepos.includes(r.repo));
+if (ioFailed.length > 0) {
+  process.stderr.write(
+    `run-migrate-v2: ERROR I/O error in ${ioFailed.length} repo(s): ` +
+      `${ioFailed.map((r) => `${r.repo} (${r.error})`).join(', ')}\n`
+  );
+  exitCode = 2;
+}
+
+process.exit(exitCode);