session-orchestrator 5.2.0 → 5.4.0

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/resolve-session-invocation.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/** Stdin-only boundary for commands/session.md; never executes task context. */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { resolveSessionInvocation } from './lib/session-invocation.mjs';
+
+const HELP = `Usage: node scripts/resolve-session-invocation.mjs [--json] < arguments.txt
+
+Read the complete /session argument text from UTF-8 stdin.
+Resolve the leading housekeeping, feature, deep or ultradeep token; preserve
+the rest as task context. Empty input defaults to deep. An invalid mode emits
+a warning and resolves to deep, as the session command has always specified.
+
+  --json     Emit one JSON object instead of a human-readable summary
+  --help     Show this help
+  --version  Show the plugin version
+
+Example: node scripts/resolve-session-invocation.mjs --json < arguments.txt
+Write arguments.txt with a file tool; do not interpolate user text into a shell.
+Exit codes: 0 resolved (including fallback), 1 bad CLI arguments, 2 stdin I/O error
+`;
+
+let options;
+try {
+  options = parseArgs({
+    options: { json: { type: 'boolean' }, help: { type: 'boolean' }, version: { type: 'boolean' } },
+    allowPositionals: false,
+  }).values;
+} catch (error) {
+  process.stderr.write(`session-invocation: ${error.message}\n`);
+  process.exit(1);
+}
+
+if (options.help) {
+  process.stdout.write(HELP);
+} else if (options.version) {
+  process.stdout.write(
+    `${JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}\n`,
+  );
+} else {
+  let input;
+  try {
+    input = readFileSync(0, 'utf8');
+  } catch {
+    process.stderr.write('session-invocation: could not read UTF-8 stdin\n');
+    process.exit(2);
+  }
+  const resolved = resolveSessionInvocation(input);
+  if (resolved.invalidMode !== undefined) {
+    process.stderr.write(
+      `Invalid session type '${resolved.invalidMode}'. Valid types: housekeeping, feature, deep (alias: ultradeep). Falling back to deep.\n`,
+    );
+  }
+  process.stdout.write(
+    options.json
+      ? `${JSON.stringify(resolved)}\n`
+      : `Session type: ${resolved.sessionType}${resolved.profile ? ` (profile: ${resolved.profile})` : ''}\nTask context: ${resolved.context}\n`,
+  );
+}

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,12 @@ process.stderr.write(
     `${aggregate.totalStillInvalidPost} still-invalid\n`
 );
 
+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`
+  );
+  process.exit(2);
+}
+
 process.exit(0);