session-orchestrator 3.16.0

package/scripts/lib/evolve/autopilot-effectiveness.mjs

@@ -0,0 +1,293 @@
+/**
+ * autopilot-effectiveness.mjs — /evolve type 8 analyzer (issue #298).
+ *
+ * Type 8: autopilot-effectiveness — compares manual vs autopilot effectiveness
+ * per session mode (housekeeping / feature / deep). Surfaces a learning per
+ * mode once enough paired runs accumulate to make the comparison statistically
+ * useful.
+ *
+ * DATA-GATING (intentional): the analyzer returns [] until at least
+ * `minPairedRuns` (default 20) sessions of EACH variant (manual + autopilot)
+ * exist for a given mode. This keeps the skeleton inert through the early
+ * autopilot rollout while wiring lives end-to-end. Once data accumulates the
+ * function activates without any further code change.
+ *
+ * Manual vs. autopilot is determined by the presence of an `autopilot_run_id`
+ * field on the session record (written by `scripts/autopilot.mjs` for every
+ * session it spawns). Sessions without that field are treated as manual.
+ *
+ * Existing analyzer types (1-7) for reference: fragile-file, effective-sizing,
+ * recurring-issue, scope-guidance, deviation-pattern, stagnation-class-frequency,
+ * hardware-pattern. This module adds type 8 to the family.
+ *
+ * Contract: pure, no-throw, ES module, zero external deps. Mirrors the style of
+ * `scripts/lib/hardware-pattern-detector.mjs` (issue #171 / C2).
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default data-gating threshold per mode (manual AND autopilot side). */
+export const DEFAULT_MIN_PAIRED_RUNS = 20;
+
+/** Modes recognised by mode-selector / autopilot. */
+export const KNOWN_MODES = Object.freeze(['housekeeping', 'feature', 'deep']);
+
+/** Initial confidence — lifecycle (decay/boost) handled by evolve infrastructure. */
+const INITIAL_CONFIDENCE = 0.5;
+
+/** Learning lifetime: 90 days from emit. */
+const EXPIRY_DAYS = 90;
+
+// ---------------------------------------------------------------------------
+// Defensive helpers
+// ---------------------------------------------------------------------------
+
+/** Safe number coercion. Returns null for non-finite inputs. */
+function num(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null;
+  return v;
+}
+
+/** Round to 3 decimals for stable evidence shape (no float noise). */
+function round3(v) {
+  if (v === null || v === undefined) return null;
+  return Math.round(v * 1000) / 1000;
+}
+
+/** ISO-8601 string for `now + N days`. */
+function isoPlusDays(nowIso, days) {
+  try {
+    const t = new Date(nowIso).getTime();
+    if (!Number.isFinite(t)) return new Date(Date.now() + days * 86400e3).toISOString();
+    return new Date(t + days * 86400e3).toISOString();
+  } catch {
+    return new Date(Date.now() + days * 86400e3).toISOString();
+  }
+}
+
+/**
+ * Extract a completion ratio from a session record. Sessions encode this in a
+ * few historically-evolved shapes; we tolerate all of them and fall back to
+ * `null` (excluded from the average) when nothing usable is present.
+ *
+ * @param {object} s
+ * @returns {number|null} ratio in [0, 1], or null when unknown
+ */
+function completionOf(s) {
+  if (!s || typeof s !== 'object') return null;
+  // Direct ratio fields
+  const direct = num(s.completion_rate ?? s.completion_ratio);
+  if (direct !== null && direct >= 0 && direct <= 1) return direct;
+  // Planned vs completed counts
+  const planned = num(s.planned_count ?? s.tasks_planned);
+  const completed = num(s.completed_count ?? s.tasks_completed);
+  if (planned !== null && completed !== null && planned > 0) {
+    return Math.max(0, Math.min(1, completed / planned));
+  }
+  return null;
+}
+
+/**
+ * Extract a carryover ratio from a session record. Carryover = work not closed
+ * within the session that flowed to a follow-up. Same tolerance pattern as
+ * `completionOf`.
+ *
+ * @param {object} s
+ * @returns {number|null} ratio in [0, 1], or null when unknown
+ */
+function carryoverOf(s) {
+  if (!s || typeof s !== 'object') return null;
+  const direct = num(s.carryover_ratio ?? s.carryover_rate);
+  if (direct !== null && direct >= 0 && direct <= 1) return direct;
+  const planned = num(s.planned_count ?? s.tasks_planned);
+  const carried = num(s.carryover_count ?? s.tasks_carried_over);
+  if (planned !== null && carried !== null && planned > 0) {
+    return Math.max(0, Math.min(1, carried / planned));
+  }
+  return null;
+}
+
+/** Mean of an array of numbers, ignoring null/undefined. Returns null when empty. */
+function mean(values) {
+  const xs = values.filter((v) => typeof v === 'number' && Number.isFinite(v));
+  if (xs.length === 0) return null;
+  return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+
+// ---------------------------------------------------------------------------
+// Grouping
+// ---------------------------------------------------------------------------
+
+/**
+ * Group sessions by mode and split into manual vs. autopilot variants.
+ * A session is "autopilot" when it carries an `autopilot_run_id` field (added
+ * by scripts/autopilot.mjs for every spawned wave), "manual" otherwise.
+ *
+ * The `autopilotRuns` array is accepted for symmetry with the public `analyze`
+ * signature and to allow future per-run filtering (e.g., only count sessions
+ * whose autopilot_run_id matches a known run). For the skeleton it is used
+ * only as a non-emptiness signal.
+ *
+ * @param {Array} autopilotRuns
+ * @param {Array} sessions
+ * @returns {Map<string, {n_manual:number, n_autopilot:number,
+ *   completion_rate_manual:number|null, completion_rate_autopilot:number|null,
+ *   carryover_ratio_manual:number|null, carryover_ratio_autopilot:number|null}>}
+ */
+export function groupByMode(autopilotRuns, sessions) {
+  const out = new Map();
+  if (!Array.isArray(sessions) || sessions.length === 0) return out;
+
+  // Optional: known autopilot_run_id set for stricter pairing. Empty set means
+  // accept any session with a non-empty autopilot_run_id field.
+  const knownRunIds = new Set();
+  if (Array.isArray(autopilotRuns)) {
+    for (const r of autopilotRuns) {
+      if (r && typeof r === 'object') {
+        const id = r.autopilot_run_id ?? r.run_id ?? r.id;
+        if (typeof id === 'string' && id.length > 0) knownRunIds.add(id);
+      }
+    }
+  }
+
+  // Bucket: mode → {manual: [], autopilot: []}
+  const buckets = new Map();
+  for (const s of sessions) {
+    if (!s || typeof s !== 'object') continue;
+    const mode = typeof s.mode === 'string' ? s.mode : null;
+    if (!mode) continue;
+    const apId = typeof s.autopilot_run_id === 'string' ? s.autopilot_run_id : null;
+    const isAutopilot =
+      apId !== null && apId.length > 0 && (knownRunIds.size === 0 || knownRunIds.has(apId));
+    const variant = isAutopilot ? 'autopilot' : 'manual';
+    if (!buckets.has(mode)) buckets.set(mode, { manual: [], autopilot: [] });
+    buckets.get(mode)[variant].push(s);
+  }
+
+  for (const [mode, { manual, autopilot }] of buckets) {
+    out.set(mode, {
+      n_manual: manual.length,
+      n_autopilot: autopilot.length,
+      completion_rate_manual: round3(mean(manual.map(completionOf))),
+      completion_rate_autopilot: round3(mean(autopilot.map(completionOf))),
+      carryover_ratio_manual: round3(mean(manual.map(carryoverOf))),
+      carryover_ratio_autopilot: round3(mean(autopilot.map(carryoverOf))),
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Learning record builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a canonical schema_version:1 learning record for a single mode.
+ * Subject form: `<mode>-manual-vs-autopilot`. Insight is human-readable.
+ *
+ * @param {string} mode
+ * @param {object} stats — output of `groupByMode().get(mode)`
+ * @param {string} nowIso
+ * @returns {object} learning record
+ */
+export function buildLearning(mode, stats, nowIso) {
+  const cm = stats.completion_rate_manual;
+  const ca = stats.completion_rate_autopilot;
+  const km = stats.carryover_ratio_manual;
+  const ka = stats.carryover_ratio_autopilot;
+
+  const completionDelta = cm !== null && ca !== null ? round3(ca - cm) : null;
+  const carryoverDelta = km !== null && ka !== null ? round3(ka - km) : null;
+
+  const parts = [];
+  if (completionDelta !== null) {
+    const dir = completionDelta > 0 ? 'higher' : completionDelta < 0 ? 'lower' : 'matched';
+    parts.push(`autopilot completion ${dir} by ${Math.abs(completionDelta)} (${ca} vs ${cm})`);
+  }
+  if (carryoverDelta !== null) {
+    const dir = carryoverDelta > 0 ? 'more' : carryoverDelta < 0 ? 'less' : 'equal';
+    parts.push(`carryover ${dir} (${ka} vs ${km})`);
+  }
+  const insight =
+    parts.length > 0
+      ? `Mode '${mode}': ${parts.join('; ')} across ${stats.n_manual} manual + ${stats.n_autopilot} autopilot runs.`
+      : `Mode '${mode}': insufficient effectiveness data despite ${stats.n_manual}+${stats.n_autopilot} paired runs.`;
+
+  const sourceSession = `evolve-${nowIso.slice(0, 10)}`;
+
+  return {
+    schema_version: 1,
+    id: randomUUID(),
+    type: 'autopilot-effectiveness',
+    subject: `${mode}-manual-vs-autopilot`,
+    insight,
+    evidence: {
+      mode,
+      n_manual: stats.n_manual,
+      n_autopilot: stats.n_autopilot,
+      completion_rate_manual: cm,
+      completion_rate_autopilot: ca,
+      carryover_ratio_manual: km,
+      carryover_ratio_autopilot: ka,
+      completion_delta: completionDelta,
+      carryover_delta: carryoverDelta,
+    },
+    confidence: INITIAL_CONFIDENCE,
+    source_session: sourceSession,
+    created_at: nowIso,
+    expires_at: isoPlusDays(nowIso, EXPIRY_DAYS),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze paired manual + autopilot runs and emit `autopilot-effectiveness`
+ * learnings — one per qualifying mode. Returns `[]` until the data-gating
+ * threshold is met (default: 20 paired runs per mode).
+ *
+ * Never throws. Defensive against malformed entries.
+ *
+ * @param {Array} autopilotRuns — entries from .orchestrator/metrics/autopilot.jsonl
+ * @param {Array} sessions      — entries from .orchestrator/metrics/sessions.jsonl
+ * @param {object} [opts]
+ * @param {number} [opts.minPairedRuns=20] — min(n_manual, n_autopilot) per mode
+ * @param {string} [opts.now] — ISO 8601 timestamp for created_at (testable)
+ * @returns {Array<object>} learning records (empty until threshold met)
+ */
+export function analyze(autopilotRuns, sessions, opts = {}) {
+  const minPairedRuns = Number.isFinite(opts.minPairedRuns)
+    ? opts.minPairedRuns
+    : DEFAULT_MIN_PAIRED_RUNS;
+  const now = typeof opts.now === 'string' && opts.now.length > 0
+    ? opts.now
+    : new Date().toISOString();
+
+  if (!Array.isArray(autopilotRuns) || autopilotRuns.length === 0) return [];
+  if (!Array.isArray(sessions) || sessions.length === 0) return [];
+
+  let grouped;
+  try {
+    grouped = groupByMode(autopilotRuns, sessions);
+  } catch {
+    return [];
+  }
+  if (!grouped || grouped.size === 0) return [];
+
+  const learnings = [];
+  for (const [mode, stats] of grouped) {
+    if (Math.min(stats.n_manual, stats.n_autopilot) < minPairedRuns) continue;
+    try {
+      learnings.push(buildLearning(mode, stats, now));
+    } catch {
+      // Skip a single failed mode rather than collapsing the whole analysis.
+    }
+  }
+  return learnings;
+}

package/scripts/lib/exclusivity-matrix.mjs

@@ -0,0 +1,68 @@
+/**
+ * exclusivity-matrix.mjs — Classify orchestrator skill modes into exclusivity classes.
+ *
+ * Pure ESM, no imports required. Stateless pure functions only.
+ *
+ * Exclusivity classes control whether a session mode may run concurrently with
+ * other active sessions in the same working directory:
+ *  - "exclusive"   — must hold the session lock alone (e.g., housekeeping)
+ *  - "parallel-ok" — may coexist with other parallel-ok sessions
+ *  - "always-ok"   — lightweight; always allowed regardless of active sessions
+ *
+ * Used by:
+ *  - parallel-aware-preamble (W3-P3, #574) — inject concurrency guardrail text
+ *  - acquire() integration (P1.2, #570) — enforce lock semantics at session-start
+ *
+ * Stable contract: the list of modes per class is documented in
+ * `skills/_shared/state-ownership.md` (PRD §3.A line 195).
+ * Do NOT add or move modes without coordinating with that document.
+ */
+
+// ---------------------------------------------------------------------------
+// EXCLUSIVITY_MATRIX
+// ---------------------------------------------------------------------------
+
+/**
+ * Static, frozen mapping from exclusivity class → mode names.
+ *
+ * All inner arrays are also frozen to prevent mutation. Any attempt to push,
+ * splice, or reassign will throw a TypeError in strict mode (and silently fail
+ * in sloppy mode after Object.freeze — prefer strict mode callers).
+ *
+ * @type {{ exclusive: readonly string[], "parallel-ok": readonly string[], "always-ok": readonly string[] }}
+ */
+export const EXCLUSIVITY_MATRIX = Object.freeze({
+  exclusive: Object.freeze(['bootstrap', 'housekeeping', 'memory-cleanup']),
+  'parallel-ok': Object.freeze(['deep', 'feature']),
+  'always-ok': Object.freeze(['discovery', 'evolve', 'plan', 'repo-audit', 'portfolio']),
+});
+
+// ---------------------------------------------------------------------------
+// classifyMode
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a skill mode name into its exclusivity class.
+ *
+ * Lookup is case-sensitive; all documented modes are lowercase. Whitespace is
+ * trimmed defensively before the lookup so callers do not need to pre-strip.
+ *
+ * @param {string} modeName - The skill mode name to classify (e.g. "deep").
+ * @returns {"exclusive" | "parallel-ok" | "always-ok"} The exclusivity class.
+ * @throws {Error} If `modeName` (after trimming) is not a recognised mode.
+ *
+ * @example
+ * classifyMode('deep')          // → "parallel-ok"
+ * classifyMode('housekeeping')  // → "exclusive"
+ * classifyMode('discovery')     // → "always-ok"
+ */
+export function classifyMode(modeName) {
+  const name = String(modeName).trim();
+
+  for (const [cls, modes] of Object.entries(EXCLUSIVITY_MATRIX)) {
+    if (modes.includes(name)) return cls;
+  }
+
+  const known = Object.values(EXCLUSIVITY_MATRIX).flat().join(', ');
+  throw new Error(`classifyMode: unknown mode "${name}". Known modes: ${known}`);
+}

package/scripts/lib/fetch-baseline.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+/**
+ * scripts/lib/fetch-baseline.mjs
+ *
+ * Fetch a file from a GitLab project's repository raw endpoint.
+ * Node.js port of scripts/lib/fetch-baseline.sh (issue #218).
+ *
+ * Used by the bootstrap skill to pull canonical baseline files (rules, agents,
+ * CLAUDE.md / AGENTS.md snippets) on demand instead of relying on local copies
+ * that drift.
+ *
+ * Required env vars:
+ *   GITLAB_TOKEN  — personal access token with read_api or read_repository scope
+ *
+ * Optional env vars:
+ *   GITLAB_HOST         — GitLab host (required; no private domain fallback)
+ *   BASELINE_REF        — default: main
+ *   FETCH_TIMEOUT_MS    — default: 10000 (ms; maps to FETCH_TIMEOUT seconds in .sh)
+ *   BASELINE_CACHE_DIR  — override cache directory
+ *
+ * Named export (module usage):
+ *   import { fetchBaselineFile } from './fetch-baseline.mjs';
+ *   const result = await fetchBaselineFile({ baselineRef, filePath, token, projectId });
+ *
+ * CLI usage:
+ *   node scripts/lib/fetch-baseline.mjs <project_id> <file_path> [ref]
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Configuration defaults (mirrors the .sh defaults)
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BASELINE_REF = 'main';
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the cache directory.
+ * Honours BASELINE_CACHE_DIR env override, then falls back to
+ * <repo-root>/.claude/.baseline-cache (same logic as .sh).
+ *
+ * @returns {string}
+ */
+function _cacheDir() {
+  if (process.env.BASELINE_CACHE_DIR) {
+    return process.env.BASELINE_CACHE_DIR;
+  }
+  let root;
+  try {
+    root = execSync('git rev-parse --show-toplevel', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    root = process.cwd();
+  }
+  return path.join(root, '.claude', '.baseline-cache');
+}
+
+/**
+ * URL-encode a file path for the GitLab API.
+ * Encodes slashes as %2F and other special characters via encodeURIComponent.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function _urlEncodePath(filePath) {
+  // encodeURIComponent handles all characters except A-Z a-z 0-9 - _ . ! ~ * ' ( )
+  // GitLab expects slashes encoded as %2F in the path segment (already the default output).
+  return encodeURIComponent(filePath);
+}
+
+/**
+ * Derive a filesystem-safe cache key from (projectId, ref, filePath).
+ * Mirrors the __cache_key() function in the .sh original.
+ *
+ * @param {string} projectId
+ * @param {string} ref
+ * @param {string} filePath
+ * @returns {string}
+ */
+function _cacheKey(projectId, ref, filePath) {
+  const raw = `${projectId}-${ref}-${filePath}`;
+  return raw.replace(/[/.]/g, '_');
+}
+
+// ---------------------------------------------------------------------------
+// Public named export
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a single file from a GitLab project's repository.
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath     - repo-relative path (e.g. ".claude/rules/security.md")
+ * @param {string} [opts.baselineRef]  - git ref (default: BASELINE_REF env or "main")
+ * @param {string} [opts.token]      - GitLab personal access token (default: GITLAB_TOKEN env)
+ * @param {string|number} [opts.projectId] - GitLab project ID (default: 52)
+ * @param {string} [opts.host]       - GitLab host (required; falls back to GITLAB_HOST env; no default private host)
+ * @param {number} [opts.timeoutMs]  - fetch timeout in ms (default: FETCH_TIMEOUT_MS env or 10000)
+ *
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   body?: string,
+ *   status?: number,
+ *   error?: string,
+ *   fromCache?: boolean
+ * }>}
+ *
+ * Exit-code semantics (mirrored as result shapes):
+ *   ok:true                  — success (network or cache fallback)
+ *   ok:false, status:401/403 — auth failure — fatal
+ *   ok:false, status:404     — file not found + no cache
+ *   ok:false, status:0       — network/transport failure + no cache (status 0 = transport)
+ */
+export async function fetchBaselineFile({
+  filePath,
+  baselineRef,
+  token,
+  projectId = 52,
+  host,
+  timeoutMs,
+} = {}) {
+  const resolvedToken = token ?? process.env.GITLAB_TOKEN;
+  const resolvedRef = baselineRef ?? process.env.BASELINE_REF ?? DEFAULT_BASELINE_REF;
+  const resolvedHost = host ?? process.env.GITLAB_HOST;
+  const resolvedTimeout = timeoutMs ?? Number(process.env.FETCH_TIMEOUT_MS ?? DEFAULT_FETCH_TIMEOUT_MS);
+
+  if (!resolvedHost) {
+    const errMsg = 'GITLAB_HOST not configured — set GITLAB_HOST env or pass opts.host';
+    process.stderr.write(`ERROR: ${errMsg}\n`);
+    return {
+      ok: false,
+      status: 0,
+      error: errMsg,
+    };
+  }
+
+  if (!resolvedToken) {
+    const errMsg = 'GITLAB_TOKEN not set — cannot fetch from baseline.';
+    process.stderr.write(`ERROR: ${errMsg}\n`);
+    return {
+      ok: false,
+      status: 401,
+      error: errMsg,
+    };
+  }
+
+  if (!filePath) {
+    return {
+      ok: false,
+      status: 0,
+      error: 'filePath is required.',
+    };
+  }
+
+  const cacheDirectory = _cacheDir();
+  const cacheKey = _cacheKey(String(projectId), resolvedRef, filePath);
+  const cacheFile = path.join(cacheDirectory, cacheKey);
+
+  const encodedPath = _urlEncodePath(filePath);
+  const url = `https://${resolvedHost}/api/v4/projects/${projectId}/repository/files/${encodedPath}/raw?ref=${resolvedRef}`;
+
+  // ---------------------------------------------------------------------------
+  // Attempt network fetch
+  // ---------------------------------------------------------------------------
+  let response;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), resolvedTimeout);
+    try {
+      response = await fetch(url, {
+        headers: { 'PRIVATE-TOKEN': resolvedToken },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    // Transport/network failure (DNS, timeout, connection refused, etc.)
+    const errMsg = err instanceof Error ? err.message : String(err);
+
+    // Try cache fallback
+    try {
+      const cached = await fs.readFile(cacheFile, 'utf8');
+      process.stderr.write(`WARNING: fetch failed (network error: ${errMsg}); using cache for ${filePath}\n`);
+      return { ok: true, body: cached, fromCache: true };
+    } catch {
+      process.stderr.write(
+        `ERROR: fetch failed and no cache for ${filePath} (project ${projectId}, ref ${resolvedRef}): ${errMsg}\n`,
+      );
+      return { ok: false, status: 0, error: errMsg };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Handle HTTP status codes (mirrors the case statement in .sh)
+  // ---------------------------------------------------------------------------
+
+  if (response.status === 200) {
+    const body = await response.text();
+    // Write to cache (best-effort — don't fail the caller if cache write fails)
+    try {
+      await fs.mkdir(cacheDirectory, { recursive: true });
+      await fs.writeFile(cacheFile, body, 'utf8');
+    } catch {
+      // ignore cache write errors
+    }
+    return { ok: true, body, status: 200 };
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    // Auth failure — fatal, no cache fallback (matches .sh behaviour)
+    const errMsg = `auth failed (${response.status}) fetching ${filePath} — check GITLAB_TOKEN scope`;
+    process.stderr.write(`ERROR: ${errMsg}\n`);
+    return { ok: false, status: response.status, error: errMsg };
+  }
+
+  if (response.status === 404) {
+    // Try cache fallback
+    try {
+      const cached = await fs.readFile(cacheFile, 'utf8');
+      process.stderr.write(
+        `WARNING: 404 for ${filePath}; using cache (file may have been removed from baseline)\n`,
+      );
+      return { ok: true, body: cached, status: 404, fromCache: true };
+    } catch {
+      const errMsg = `file not found (${filePath} on ${resolvedRef}) and no cache`;
+      process.stderr.write(`ERROR: ${errMsg}\n`);
+      return { ok: false, status: 404, error: errMsg };
+    }
+  }
+
+  // Any other non-2xx status — try cache fallback
+  try {
+    const cached = await fs.readFile(cacheFile, 'utf8');
+    process.stderr.write(`WARNING: HTTP ${response.status} for ${filePath}; using cache\n`);
+    return { ok: true, body: cached, status: response.status, fromCache: true };
+  } catch {
+    const errMsg = `HTTP ${response.status} fetching ${filePath} — no cache`;
+    process.stderr.write(`ERROR: ${errMsg}\n`);
+    return { ok: false, status: response.status, error: errMsg };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI mode
+// ---------------------------------------------------------------------------
+
+/**
+ * When invoked directly: node scripts/lib/fetch-baseline.mjs <project_id> <file_path> [ref]
+ *
+ * Fetches the file and prints the body to stdout.
+ * Exit codes mirror the .sh original:
+ *   0 — success
+ *   1 — auth failure (401/403) or missing GITLAB_TOKEN
+ *   2 — file not found (404, no cache)
+ *   3 — network/transport failure, no cache; or unexpected HTTP status
+ */
+async function _cliMain() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) {
+    process.stderr.write(
+      `Usage: node ${path.basename(process.argv[1])} <project_id> <file_path> [ref]\n`,
+    );
+    process.exit(1);
+  }
+
+  const [projectId, filePath, ref] = args;
+
+  const result = await fetchBaselineFile({
+    projectId,
+    filePath,
+    baselineRef: ref, // undefined when not supplied → uses env/default
+  });
+
+  if (result.ok) {
+    process.stdout.write(result.body ?? '');
+    process.exit(0);
+  }
+
+  // Map error to exit code matching .sh
+  const status = result.status ?? 0;
+  if (status === 401 || status === 403) {
+    process.exit(1);
+  }
+  if (status === 404) {
+    process.exit(2);
+  }
+  // network failure or unexpected HTTP status
+  process.exit(3);
+}
+
+// Detect CLI invocation: import.meta.url matches the argv[1] path
+const isMain = process.argv[1] && (
+  process.argv[1] === new URL(import.meta.url).pathname ||
+  // Handle invocation without file:// prefix
+  process.argv[1].endsWith('fetch-baseline.mjs')
+);
+
+if (isMain) {
+  _cliMain().catch((err) => {
+    process.stderr.write(`FATAL: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(3);
+  });
+}